Struct `UnixSocket`

struct UnixSocket { ... }

A Unix socket that has not yet been converted to a UnixStream, UnixDatagram, or UnixListener.

UnixSocket wraps an operating system socket and enables the caller to configure the socket before establishing a connection or accepting inbound connections. The caller is able to set socket option and explicitly bind the socket with a socket address.

The underlying socket is closed when the UnixSocket value is dropped.

UnixSocket should only be used directly if the default configuration used by UnixStream::connect, UnixDatagram::bind, and UnixListener::bind does not meet the required use case.

Calling UnixStream::connect(path) effectively performs the same function as:

use tokio::net::UnixSocket;
use std::error::Error;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let dir = tempfile::tempdir().unwrap();
    let path = dir.path().join("bind_path");
    let socket = UnixSocket::new_stream()?;

    let stream = socket.connect(path).await?;

    Ok(())
}

Calling UnixDatagram::bind(path) effectively performs the same function as:

use tokio::net::UnixSocket;
use std::error::Error;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let dir = tempfile::tempdir().unwrap();
    let path = dir.path().join("bind_path");
    let socket = UnixSocket::new_datagram()?;
    socket.bind(path)?;

    let datagram = socket.datagram()?;

    Ok(())
}

Calling UnixListener::bind(path) effectively performs the same function as:

use tokio::net::UnixSocket;
use std::error::Error;

#[tokio::main]
async fn main() -> Result<(), Box<dyn Error>> {
    let dir = tempfile::tempdir().unwrap();
    let path = dir.path().join("bind_path");
    let socket = UnixSocket::new_stream()?;
    socket.bind(path)?;

    let listener = socket.listen(1024)?;

    Ok(())
}

Setting socket options not explicitly provided by UnixSocket may be done by accessing the RawFd/RawSocket using AsRawFd/AsRawSocket and setting the option with a crate like socket2.

Implementations

`impl UnixSocket`

fn new_datagram() -> Result<UnixSocket>

Creates a new Unix datagram socket.

Calls socket(2) with AF_UNIX and SOCK_DGRAM.

Returns

On success, the newly created UnixSocket is returned. If an error is encountered, it is returned instead.

fn new_stream() -> Result<UnixSocket>

Creates a new Unix stream socket.

Calls socket(2) with AF_UNIX and SOCK_STREAM.

Returns

On success, the newly created UnixSocket is returned. If an error is encountered, it is returned instead.

fn bind<impl AsRef<Path>: AsRef<Path>>(self: &Self, path: impl AsRef<Path>) -> Result<()>

Binds the socket to the given address.

This calls the bind(2) operating-system function.

fn listen(self: Self, backlog: u32) -> Result<UnixListener>

Converts the socket into a UnixListener.

backlog defines the maximum number of pending connections are queued by the operating system at any given time. Connection are removed from the queue with UnixListener::accept. When the queue is full, the operating-system will start rejecting connections.

Calling this function on a socket created by new_datagram will return an error.

This calls the listen(2) operating-system function, marking the socket as a passive socket.

async fn connect<impl AsRef<Path>: AsRef<Path>>(self: Self, path: impl AsRef<Path>) -> Result<UnixStream>

Establishes a Unix connection with a peer at the specified socket address.

The UnixSocket is consumed. Once the connection is established, a connected UnixStream is returned. If the connection fails, the encountered error is returned.

Calling this function on a socket created by new_datagram will return an error.

This calls the connect(2) operating-system function.

fn datagram(self: Self) -> Result<UnixDatagram>

Converts the socket into a UnixDatagram.

Calling this function on a socket created by new_stream will return an error.

`impl AsFd for UnixSocket`

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

`impl AsRawFd for UnixSocket`

fn as_raw_fd(self: &Self) -> RawFd

`impl Debug for UnixSocket`

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

`impl Freeze for UnixSocket`

`impl FromRawFd for UnixSocket`

unsafe fn from_raw_fd(fd: RawFd) -> UnixSocket

`impl IntoRawFd for UnixSocket`

fn into_raw_fd(self: Self) -> RawFd

`impl RefUnwindSafe for UnixSocket`

`impl Send for UnixSocket`

`impl Sync for UnixSocket`

`impl Unpin for UnixSocket`

`impl UnsafeUnpin for UnixSocket`

`impl UnwindSafe for UnixSocket`

`impl<T> Any for UnixSocket`

fn type_id(self: &Self) -> TypeId

`impl<T> Borrow for UnixSocket`

fn borrow(self: &Self) -> &T

`impl<T> BorrowMut for UnixSocket`

fn borrow_mut(self: &mut Self) -> &mut T

`impl<T> From for UnixSocket`

fn from(t: T) -> T: Returns the argument unchanged.

`impl<T, U> Into for UnixSocket`

fn into(self: Self) -> U

Calls U::from(self).

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

`impl<T, U> TryFrom for UnixSocket`

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

`impl<T, U> TryInto for UnixSocket`

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