[−][src]Crate file_descriptors

#file-descriptors

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.

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.
  • signalfd.
  • 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).

Pipes

  • 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.
  • SO_BUSY_POLL and SO_INCOMING_CPU.
  • Unix Domain Sockets using autobind; setting of the SO_PASSCRED socket option.
  • Receiving credentials over Unix Domain Sockets using recvmsg().
  • mkfifo().
  • mknod().
  • copy_file_range().
  • infiniband sockets.
  • canbus (SocketCAN sockets and can4linux http://can-wiki.info/can4linux/man/can4linux_8h_source.html character device drivers).

Licensing

The license for this project is MIT.

Traits

RawFdExt

Common raw file descriptor extensions.