Skip to main content

UnixListener

Struct UnixListener 

Source
pub struct UnixListener { /* private fields */ }
Available on Unix and crate feature local only.
Expand description

A Unix domain socket listener. Dropping it removes its socket file, but only while the path still names the file this listener created.

let listener = net_io::UnixListener::bind("/run/myapp/control.sock")?;
let (mut conn, info) = listener.accept()?;
println!("uid {:?}", info.peer_credentials.and_then(|c| c.uid));
conn.send_all(b"ready\n")?;

Implementations§

Source§

impl UnixListener

Source

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

Binds path with LocalOptions::new: mode 0600, a stale socket file removed.

§Errors

PathTooLong, StaleSocketInUse, PermissionDenied, NotFound (no such directory), InvalidConfig { field: "path" } (a NUL byte, a path that ends in /, ., or .., or reason: InsecureDirectory, see UnixListener::bind_with), Os.

Source

pub fn bind_with<P: AsRef<Path>>( path: P, options: LocalOptions, ) -> Result<UnixListener, NetError>

Binds path with options: the socket is bound, given its mode and owner, and only then listens, so no connection is accepted under the umask’s permissions.

The mode and owner are never set through a path another user can change. The socket’s directory is opened once and checked:

  • writable by every user without the sticky bit: refused with InvalidConfig { field: "path", reason: InsecureDirectory }, as anyone could swap the socket file for a link to another file;
  • owned by this user or root, and writable by nobody else (or sticky, as /tmp): the socket is bound at path and its mode and owner are set by name relative to the open directory;
  • otherwise (writable by its group, or owned by another user): the socket is bound in a new private directory next to path (.nio and 8 hex digits, mode 0700), given its mode and owner there, and linked to path once it listens; the private directory is then removed. The directory’s path plus 15 bytes must then also fit the platform limit, or the bind fails with PathTooLong.

In the last case the name the OS reports for the socket (getsockname, and so for a listener adopted from it) is the private one, as with UnixListener::bind_atomic; UnixListener::path and ListenerInfo::local are always path.

§Errors

As UnixListener::bind.

Source

pub fn bind_atomic<P: AsRef<Path>>( path: P, options: LocalOptions, ) -> Result<UnixListener, NetError>

As UnixListener::bind_with, but bound under a temporary name in the same directory and renamed into place once it listens with its final mode: the path never names a socket that refuses or is not ready, and a stale socket at it is replaced in one step. The directory is checked as for bind_with; where others can change it, the temporary name is the socket in the private directory, and the rename moves it from there.

§Errors

As UnixListener::bind.

Source

pub fn accept(&self) -> Result<(UnixConnection, ConnectionInfo), NetError>

Blocks until a connection arrives. Peer credentials are read once and stored in ConnectionInfo; with require_uid, other users’ connections are closed before any read and accepting continues.

§Errors

Limit { which: Descriptors } when exhaustion persists past one backoff step; Os.

Source

pub fn accept_timeout( &self, timeout: Duration, ) -> Result<Option<(UnixConnection, ConnectionInfo)>, NetError>

As UnixListener::accept, but Ok(None) when nothing arrived within timeout.

§Errors

As UnixListener::accept.

Source

pub fn info(&self) -> &ListenerInfo

Facts about this listener.

Source

pub fn path(&self) -> Option<&Path>

The path this listener was bound to (recorded at bind, not read back: decision D-058); for an adopted socket, the path the OS reports.

Trait Implementations§

Source§

impl AsFd for UnixListener

Source§

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

Borrows the file descriptor. Read more
Source§

impl Debug for UnixListener

Source§

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

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

impl Drop for UnixListener

Source§

fn drop(&mut self)

Removes the socket file only if the path still names the file this listener created, never a replacement someone else bound.

Source§

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)
Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned. 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>,

Source§

type Error = !

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

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

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.