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.

Modules

character_device	Character device file descriptors.
epoll	EPoll file descriptors.
eventfd	Event file descriptors.
fanotify	fanotify file descriptors.
file_descriptor_information	File descriptor information obtained from /proc.
inotify	inotify file descriptors.
pipes_and_fifos	Anonymous and named, connected unidirectional pipes_and_fifos (act like TCP connected sockets).
posix_message_queues	POSIX message queue file descriptors.
sendfile	Additional support for using sendfile() with Rust's File and our sockets.
signalfd	Signal file descriptors.
socket	Socket file descriptors.
terminal	Terminal (serial port and modem) file descriptors.
timerfd	Timer file descriptors.

Enums

CreationError	An error that can occur during creation of a file descriptor instance.
InvalidPathReason	Reason given for why a path is an invalid for a FIFO.
SpecialFileOpenError	An error that can occur when opening one end of a FIFO (a named pipe) or a character device.
StructReadError	An error that can occur during read.
StructWriteError	An error that can occur during read of a timer instance.

Traits

AsRawFdExt	Extensions for a file descriptor.
RawFdExt	Common raw file descriptor extensions.
VectoredRead	Implementors support vectored reads.
VectoredWrite	Implementors support vectored writes.