Struct tokio::net::UnixSocket

source ·
pub struct UnixSocket { /* private fields */ }
Expand description

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§

source§

impl UnixSocket

source

pub 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.

source

pub 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.

source

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

Binds the socket to the given address.

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

source

pub fn listen(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.

source

pub async fn connect(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.

source

pub fn datagram(self) -> Result<UnixDatagram>

Converts the socket into a UnixDatagram.

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

Trait Implementations§

source§

impl AsFd for UnixSocket

source§

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

Borrows the file descriptor. Read more
source§

impl AsRawFd for UnixSocket

source§

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor. Read more
source§

impl Debug for UnixSocket

source§

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

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

impl FromRawFd for UnixSocket

source§

unsafe fn from_raw_fd(fd: RawFd) -> UnixSocket

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

impl IntoRawFd for UnixSocket

source§

fn into_raw_fd(self) -> RawFd

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

Auto Trait Implementations§

Blanket Implementations§

source§

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

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where 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 T
where 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 T
where 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 T
where 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.