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
impl UnixSocket
Sourcepub fn new_datagram() -> Result<UnixSocket>
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.
Sourcepub fn new_stream() -> Result<UnixSocket>
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.
Sourcepub fn bind(&self, path: impl AsRef<Path>) -> Result<()>
pub fn bind(&self, path: impl AsRef<Path>) -> Result<()>
Binds the socket to the given address.
This calls the bind(2)
operating-system function.
Sourcepub fn listen(self, backlog: u32) -> Result<UnixListener>
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.
Sourcepub async fn connect(self, path: impl AsRef<Path>) -> Result<UnixStream>
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.
Sourcepub fn datagram(self) -> Result<UnixDatagram>
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
impl AsFd for UnixSocket
Source§fn as_fd(&self) -> BorrowedFd<'_>
fn as_fd(&self) -> BorrowedFd<'_>
Source§impl AsRawFd for UnixSocket
impl AsRawFd for UnixSocket
Source§impl Debug for UnixSocket
impl Debug for UnixSocket
Source§impl FromRawFd for UnixSocket
impl FromRawFd for UnixSocket
Source§unsafe fn from_raw_fd(fd: RawFd) -> UnixSocket
unsafe fn from_raw_fd(fd: RawFd) -> UnixSocket
Self
from the given raw file
descriptor. Read more