# Struct std::os::unix::net::UnixListener

1.10.0 · source ·

    pub struct UnixListener(/* private fields */);

Available on Unix only.
Expand description

A structure representing a Unix domain socket server.

## Examples

    use std::thread;
    use std::os::unix::net::{UnixStream, UnixListener};

    fn handle_client(stream: UnixStream) {
        // ...
    }

    fn main() -> std::io::Result<()> {
        let listener = UnixListener::bind("/path/to/the/socket")?;

        // accept connections and process them, spawning a new thread for each one
        for stream in listener.incoming() {
            match stream {
                Ok(stream) => {
                    /* connection succeeded */
                    thread::spawn(|| handle_client(stream));
                }
                Err(err) => {
                    /* connection failed */
                    break;
                }
            }
        }
        Ok(())
    }

Run

## Implementations§

source§

### impl UnixListener

source

#### pub fn bind<P: AsRef<Path>>(path: P) -> Result<UnixListener>

Creates a new `UnixListener` bound to the specified socket.

##### Examples

    use std::os::unix::net::UnixListener;

    let listener = match UnixListener::bind("/path/to/the/socket") {
        Ok(sock) => sock,
        Err(e) => {
            println!("Couldn't connect: {e:?}");
            return
        }
    };

Run
1.70.0 · source

#### pub fn bind_addr(socket_addr: &SocketAddr) -> Result<UnixListener>

Creates a new `UnixListener` bound to the specified `socket address`.

##### Examples

    use std::os::unix::net::{UnixListener};

    fn main() -> std::io::Result<()> {
        let listener1 = UnixListener::bind("path/to/socket")?;
        let addr = listener1.local_addr()?;

        let listener2 = match UnixListener::bind_addr(&addr) {
            Ok(sock) => sock,
            Err(err) => {
                println!("Couldn't bind: {err:?}");
                return Err(err);
            }
        };
        Ok(())
    }

Run
source

#### pub fn accept(&self) -> Result<(UnixStream, SocketAddr)>

Accepts a new incoming connection to this listener.

This function will block the calling thread until a new Unix connection is established. When established, the corresponding `UnixStream` and the remote peer’s address will be returned.

##### Examples

    use std::os::unix::net::UnixListener;

    fn main() -> std::io::Result<()> {
        let listener = UnixListener::bind("/path/to/the/socket")?;

        match listener.accept() {
            Ok((socket, addr)) => println!("Got a client: {addr:?}"),
            Err(e) => println!("accept function failed: {e:?}"),
        }
        Ok(())
    }

Run
source

#### pub fn try_clone(&self) -> Result<UnixListener>

Creates a new independently owned handle to the underlying socket.

The returned `UnixListener` is a reference to the same socket that this object references. Both handles can be used to accept incoming connections and options set on one listener will affect the other.

##### Examples

    use std::os::unix::net::UnixListener;

    fn main() -> std::io::Result<()> {
        let listener = UnixListener::bind("/path/to/the/socket")?;
        let listener_copy = listener.try_clone().expect("try_clone failed");
        Ok(())
    }

Run
source

#### pub fn local_addr(&self) -> Result<SocketAddr>

Returns the local socket address of this listener.

##### Examples

    use std::os::unix::net::UnixListener;

    fn main() -> std::io::Result<()> {
        let listener = UnixListener::bind("/path/to/the/socket")?;
        let addr = listener.local_addr().expect("Couldn't get local address");
        Ok(())
    }

Run
source

#### pub fn set_nonblocking(&self, nonblocking: bool) -> Result<()>

Moves the socket into or out of nonblocking mode.

This will result in the `accept` operation becoming nonblocking, i.e., immediately returning from their calls. If the IO operation is successful, `Ok` is returned and no further action is required. If the IO operation could not be completed and needs to be retried, an error with kind `io::ErrorKind::WouldBlock` is returned.

##### Examples

    use std::os::unix::net::UnixListener;

    fn main() -> std::io::Result<()> {
        let listener = UnixListener::bind("/path/to/the/socket")?;
        listener.set_nonblocking(true).expect("Couldn't set non blocking");
        Ok(())
    }

Run
source

#### pub fn take_error(&self) -> Result<Option<Error>>

Returns the value of the `SO_ERROR` option.

##### Examples

    use std::os::unix::net::UnixListener;

    fn main() -> std::io::Result<()> {
        let listener = UnixListener::bind("/tmp/sock")?;

        if let Ok(Some(err)) = listener.take_error() {
            println!("Got error: {err:?}");
        }
        Ok(())
    }

Run

##### Platform specific

On Redox this always returns `None`.

source

#### pub fn incoming(&self) -> Incoming<'_> ⓘ

Returns an iterator over incoming connections.

The iterator will never return `None` and will also not yield the peer’s `SocketAddr` structure.

##### Examples

    use std::thread;
    use std::os::unix::net::{UnixStream, UnixListener};

    fn handle_client(stream: UnixStream) {
        // ...
    }

    fn main() -> std::io::Result<()> {
        let listener = UnixListener::bind("/path/to/the/socket")?;

        for stream in listener.incoming() {
            match stream {
                Ok(stream) => {
                    thread::spawn(|| handle_client(stream));
                }
                Err(err) => {
                    break;
                }
            }
        }
        Ok(())
    }

Run

## Trait Implementations§

1.63.0 · source§

### impl AsFd for UnixListener

source§

#### fn as_fd(&self) -> BorrowedFd<'_>

Borrows the file descriptor. Read more
source§

### impl AsRawFd for UnixListener

source§

#### fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor. Read more
source§

### impl Debug for UnixListener

source§

#### fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
1.63.0 · source§

### impl From<OwnedFd> for UnixListener

source§

#### fn from(fd: OwnedFd) -> UnixListener

Converts to this type from the input type.
1.63.0 · source§

### impl From<UnixListener> for OwnedFd

source§

#### fn from(listener: UnixListener) -> OwnedFd

Converts to this type from the input type.
source§

### impl FromRawFd for UnixListener

source§

#### unsafe fn from_raw_fd(fd: RawFd) -> UnixListener

Constructs a new instance of `Self` from the given raw file descriptor. Read more
source§

### impl<'a> IntoIterator for &'a UnixListener

§

#### type Item = Result<UnixStream, Error>

The type of the elements being iterated over.
§

#### type IntoIter = Incoming<'a>

Which kind of iterator are we turning this into?
source§

#### fn into_iter(self) -> Incoming<'a> ⓘ

Creates an iterator from a value. Read more
source§

### impl IntoRawFd for UnixListener

source§

#### fn into_raw_fd(self) -> RawFd

Consumes this object, returning the raw underlying file descriptor. Read more

## Auto Trait Implementations§

§

### impl RefUnwindSafe for UnixListener

§

### impl Send for UnixListener

§

### impl Sync for UnixListener

§

### impl Unpin for UnixListener

§

### impl UnwindSafe for UnixListener

## Blanket Implementations§

source§

### impl<T> Any for Twhere T: 'static + ?Sized,

source§

#### fn type_id(&self) -> TypeId

Gets the `TypeId` of `self`. Read more
source§

### impl<T> Borrow<T> for Twhere T: ?Sized,

source§

#### fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

### impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

#### fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

### impl<T> From<T> for T

source§

#### fn from(t: T) -> T

Returns the argument unchanged.

source§

### impl<T, U> Into<U> for Twhere U: From<T>,

source§

#### fn into(self) -> U

Calls `U::from(self)`.

That is, this conversion is whatever the implementation of `From<T> for U` chooses to do.

source§

### impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

#### type Error = Infallible

The type returned in the event of a conversion error.
source§

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

### impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

#### type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.