#unix #socket #abstract #seqpacket #fdpassing

uds

A unix domain socket crate that supports abstract addresses, fd-passing and seqpacket sockets

9 releases

0.2.6 Apr 2, 2021
0.2.5 Apr 1, 2021
0.2.4 Mar 24, 2021
0.2.2 Jan 31, 2021
0.0.0 Nov 23, 2019

#18 in Unix APIs

Download history 17/week @ 2020-12-24 68/week @ 2020-12-31 98/week @ 2021-01-07 132/week @ 2021-01-14 150/week @ 2021-01-21 201/week @ 2021-01-28 182/week @ 2021-02-04 175/week @ 2021-02-11 193/week @ 2021-02-18 1185/week @ 2021-02-25 1337/week @ 2021-03-04 778/week @ 2021-03-11 907/week @ 2021-03-18 1638/week @ 2021-03-25 1116/week @ 2021-04-01 1497/week @ 2021-04-08

2,466 downloads per month

Apache-2.0 / MIT

180KB
2.5K SLoC

uds

A unix domain sockets Rust library that supports abstract addresses, fd-passing, SOCK_SEQPACKET sockets and more.

crates.io page License: Apache v2 / MIT Documentation cirrus-ci build status sourcehut build status

When possible, features are implemented via extension traits for std::os::unix::net types (and optionally mio-uds types) instead of exposing new structs. The only new socket structs this crate exposes are those for seqpacket sockets.

Ancillary credentials and timestamps are not yet supported.

Example

(only runs sucessfully on Linux)

extern crate uds;

let addr = uds::UnixSocketAddr::from_abstract(b"not a file!")
    .expect("create abstract socket address");
let listener = uds::UnixSeqpacketListener::bind_unix_addr(&addr)
    .expect("create seqpacket listener");

let client = uds::UnixSeqpacketConn::connect_unix_addr(&addr)
    .expect("connect to listener");
client.send_fds(b"Here I come", &[0, 1, 2])
    .expect("send stdin, stdout and stderr");

let (server_side, _) = listener.accept_unix_addr()
    .expect("accept connection");
let creds: uds::ConnCredentials = server_side.initial_peer_credentials()
    .expect("get peer credentials");
if creds.euid() == 0 {
    let mut fd_buf = [-1; 3];
    let (_, _, fds) = server_side.recv_fds(&mut[0u8; 1], &mut fd_buf
        ).expect("receive with fd capacity");
    if fds == 3 {
        /* do something with the file descriptors */
    }
    /* remember to close the file descripts */
} else {
    server_side.send(b"go away!\n").expect("send response");
}

Portability

macOS doesn't support SOCK_SEQPACKET sockets, and abstract socket addresses is Linux-only, so if you don't want to bother with supporting non-portable features you are probably better off only using what std or mio-uds provides. If you're writing a datagram server though, using std or mio-uds means you can't respond to abstract adresses, forcing clients to use path addresses and deal with cleaning up the socket file after themselves.

Even when all operating systems you care about supports something, they might behave differently:
On Linux file descriptors are cloned when they are sent, but macOS and the BSDs first clones them when they are received. This means that if a FD is closed before the peer receives it you have a problem.
Also, some OSes might return the original file descriptor without cloning it if it's received within the same process as it was sent from. (DragonFly BSD, possibly macOS and maybe FreeBSD).

Linux macOS FreeBSD OpenBSD DragonFly BSD NetBSD Illumos
Seqpacket Yes N/A Yes Yes Yes Yes N/A
fd-passing Yes Yes Yes Yes Yes Yes No
abstract addresses Yes N/A N/A N/A N/A N/A N/A
mio (0.6 & 0.7 & uds) Yes Yes Yes Yes Yes Yes Yes
tokio Yes Yes Yes Yes Yes Yes Yes
Tested? Locally + CI CI CI + Manually CI Manually Manually Manually

Other OSes

  • Android: I haven't tested on it, but I assume there are no differences from regular Linux.
  • Windows 10: While it added some unix socket features, Windows support is not a priority. (PRs are welcome though).
  • Solaris: Treated identically as Illumos.

mio integration

The non-blocking seqpacket types can optionally be used with mio (version 0.6):

To enable it, add this to Cargo.toml:

[dependencies]
uds = {version="0.2.6", features=["mio"]}

The extension traits can also be implement for mio-uds types:

To enable them, add this to Cargo.toml:

[dependencies]
uds = {version="0.2.6", features=["mio-uds"]}

Mio 0.7 is also supported:

[dependencies]
uds = {version="0.2.6", features=["mio_07"]}

tokio integration

Futures-aware seqpacket types can optionally be used with tokio (version 0.2):

To enable it, add this to Cargo.toml:

[dependencies]
uds = {version="0.2.6", features=["tokio"]}

Minimum Rust version

The minimum Rust version is 1.39.

unsafe usage

This crate calls many C functions, which are all unsafe (even ones as simple as socket()). The public interface is safe (except for FromRawFd), so if you find something unsound (even internal functions that aren't marked unsafe) please open an issue.

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Dependencies

~0–410KB