#fd #serial #terminal #sockets #file-descriptors

nightly file-descriptors

Wrapper around the common kinds of (mostly Linux) file descriptors, including sockets, pipes, FIFOs, terminals, serial ports, character devices, epoll, POSIX message queues, timerfd, eventfd, signalfd fanotify and inotify

28 releases

Uses old Rust 2015

0.9.1 Mar 21, 2020
0.8.7 Jan 31, 2019

#175 in Unix APIs

Download history 9/week @ 2022-01-27 6/week @ 2022-02-03 3/week @ 2022-02-10 38/week @ 2022-02-17 10/week @ 2022-02-24 8/week @ 2022-03-03 63/week @ 2022-03-10 147/week @ 2022-03-17 8/week @ 2022-03-24 7/week @ 2022-03-31 12/week @ 2022-04-07 7/week @ 2022-04-14 9/week @ 2022-04-21 177/week @ 2022-04-28 127/week @ 2022-05-05 459/week @ 2022-05-12

773 downloads per month
Used in 2 crates (via magic-ring-buffer)

MIT license

11K SLoC


file-descriptors is a Rust crate wrapping the various kinds of file descriptors with safe abstractions, including IPv4 / IPv6 sockets, Unix domain sockets, epoll, timerfd, signalfd, eventfd, POSIX message queues, pipes, FIFOs, terminals (and serial ports), character devices, inotify, fanotify and Files.

There is a particularly extensive and safe wrapper for signals and terminals.

Fully functional on Android and Linux.

Somewhat functional on Fuschia, Illumos (a Solaris fork), uclibc and emscripten.

Support for the BSDs is desired.

Supported File Descriptors

  • character devices.
  • epoll.
  • eventfd.
  • fanotify.
  • inotify.
  • POSIX message queues (<(https://linux.die.net/man/7/mq_overview>).
  • pipes and FIFOs (anonymous and named FIFOs), including support for splice, vmsplice and tee.
  • sockets (TCP, UDP and the equivalent over Unix Domain Sockets; sendfile supported).
  • terminals (serial ports and modems).
  • timerfd.

Additionally, extensions (SendFile, SpliceRecipient and SpliceSender) are implemented for Rust's File.

Unix Domain Sockets

When using file paths

  • Every effort is made to create the socket file path cleanly;
  • To make sure all parent folders exist;
  • To make sure parent folder permissions are correctly set;
  • To remove any stale files;
  • To remove socket file paths on drop (close).

The above features may not work correctly after the use of seccomp to lock down system calls (particularly the attempt to delete a socket file path on close).


  • The use of splice(), vmsplice() and tee() are supported for all file descriptors where possible (including Rust's ::std::fs::File).
  • To be able to use epoll with standard in (stdin), use pipes_and_fifos::ReceivePipeFileDescriptor::standard_in().
  • To be able to use epoll with standard out (stdout), use pipes_and_fifos::SendPipeFileDescriptor::standard_out().
  • To be able to use epoll with standard error (stderr), use pipes_and_fifos::SendPipeFileDescriptor::standard_error().

Unsupported for now

  • Linux zero copy send (MSG_ZEROCOPY) and receive (SO_ZEROCOPY), mostly because they have a horrible, hacky API.
  • Unix Domain Sockets using autobind; setting of the SO_PASSCRED socket option.
  • Receiving credentials over Unix Domain Sockets using recvmsg().
  • mkfifo().
  • mknod().
  • infiniband sockets.
  • canbus (SocketCAN sockets and can4linux http://can-wiki.info/can4linux/man/can4linux_8h_source.html character device drivers).


The license for this project is MIT.