Crate linux_unsafe

A low-level, unsafe Rust interface to Linux system calls.

The raw module provides functions wrapping platform-specific assembly language stubs for making arbitrary system calls by providing a system call number and arbitrary number of arguments.

This crate currently supports the following architectures:

• x86_64
• x86 (32-bit)
• arm
• riscv64

For this initial release, x86_64 has seen some limited testing and the other platforms have been barely tested at all. Over time I intend to support all architectures that Linux supports that are also supported by Rust inline assembly, but we’ll see how it goes.

The functions in the root of the crate then wrap those stubs with thin wrappers that just lightly convert their arguments to what the kernel expects for a particular system call and then delegate to one of the system call stubs in raw.

This crate also includes a number of types and type aliases representing the memory layout of objects the kernel will interpret. For those which are aliases, calling code must always use the aliases rather than their underlying types because their exact definitions may vary on different platforms and in future versions of this crate.

Where possible the wrapping functions and types are portable across architectures, as long as callers use the argument types and type aliases defined in this crate. The raw system call interface has considerable overlap between platforms but is ultimately architecture-specific and this crate does not attempt to hide differences at that layer.

Be careful mixing with std

The Rust std crate has lots of functionality that wraps the target’s libc functions. On Linux systems libc is a wrapper around the same system call interface this crate is exposing, but also adds other state and abstractions such as buffers and error codes. Making direct system calls may violate the assumptions being made by libc.

To avoid strange problems, avoid interacting with the same system resources through both the standard library and though direct system calls.

Modules

• args
  Supporting traits for preparing values to be system call arguments.
• raw
  Thin wrappers around the CPU instructions for making system calls on ARM.
• result
  Types representing results from system call wrapper functions.

Structs

• epoll_event
  A type used with crate::epoll_ctl.
• flock
  A type used with some crate::fcntl commands.
• io_cqring_offsets
  Used with io_uring_params.
• io_sqring_offsets
  Used with io_uring_params.
• io_uring_params
  Used for crate::io_uring_setup.
• iovec
  A type used with crate::readv and crate::writev.
• linux_dirent
  Used for crate::getdents.
• linux_dirent64
  Used for crate::getdents64.
• pollfd
  A file descriptor request object for use with crate::poll.
• sigset_t
  A set of signals for use with signal blocking functions.
• sockaddr
  The type used for representing socket addresses in the raw system calls.
• sockaddr_storage
  Represents the upper limit for the size of any sockaddr value, across all address families.
• timespec
  Representation of time as separate seconds and nanoseconds.
• timeval
  Representation of time as separate seconds and microseconds.

Enums

• sock_type
  The type for representing socket communication model types.

Constants

• O_ACCMODE
• O_APPEND
• O_CLOEXEC
• O_CREAT
• O_DIRECT
• O_DIRECTORY
• O_DSYNC
• O_EXCL
• O_LARGEFILE
• O_NDELAY
• O_NOATIME
• O_NOCTTY
• O_NOFOLLOW
• O_NONBLOCK
• O_PATH
• O_RDONLY
• O_RDWR
• O_SYNC
• O_TMPFILE
• O_TMPFILE_MASK
• O_TRUNC
• O_WRONLY
• POLLERR
• POLLHUP
• POLLIN
• POLLNVAL
• POLLOUT
• POLLPRI
• SEEK_CUR
  Seek relative to the current file position.
• SEEK_DATA
  Seek to the next data.
• SEEK_END
  Seek relative to the end of the file.
• SEEK_HOLE
  Seek to the next hole.
• SEEK_SET
  Seek relative to the beginning of the file.

Functions

• _llseek^⚠
  A special variant of lseek for 32-bit platforms that need the 64-bit offset split into two arguments.
• accept^⚠
  Accept a connection on a socket.
• accept4^⚠
  Accept a connection on a socket with additional flags.
• access^⚠
  Check user’s permissions for a file.
• acct^⚠
  Switch process accounting on or off.
• bind^⚠
  Bind a name to a socket.
• brk^⚠
  Set the program break.
• chdir^⚠
  Change working directory.
• chmod^⚠
  Change permissions of a file.
• chown^⚠
  Change ownership of a file.
• chroot^⚠
  Change the root directory.
• close^⚠
  Close a file.
• close_range^⚠
  Close all file descriptors in a given range.
• connect^⚠
  Initiate a connection on a socket.
• creat^⚠
  Create a file.
• dup^⚠
  Duplicate a file descriptor.
• dup2^⚠
  Duplicate a file descriptor.
• dup3^⚠
  Duplicate a file descriptor.
• epoll_create^⚠
  Open an epoll file descriptor.
• epoll_create1^⚠
  Open an epoll file descriptor.
• epoll_ctl^⚠
  Control interface for an epoll file descriptor.
• epoll_wait^⚠
  Wait for an I/O event on an epoll file descriptor.
• eventfd^⚠
  Create a file descriptor for event notification.
• eventfd2^⚠
  Create a file descriptor for event notification.
• exit^⚠
  Immediately terminate the current thread, without giving Rust or libc any opportunity to run destructors or other cleanup code.
• exit_group^⚠
  Immediately terminate all threads in the current process’s thread group, without giving Rust or libc any opportunity to run destructors or other cleanup code.
• faccessat^⚠
  Check user’s permissions for a file.
• faccessat2^⚠
  Check user’s permissions for a file.
• fchdir^⚠
  Change working directory.
• fchmod^⚠
  Change permissions of a file.
• fchmodat^⚠
  Change permissions of a file.
• fchown^⚠
  Change ownership of a file.
• fchownat^⚠
  Change ownership of a file.
• fcntl^⚠
  Manipulate characteristics of a file descriptor.
• fdatasync^⚠
  Synchronize a file’s in-core state with storage device.
• fsync^⚠
  Synchronize a file’s in-core state with storage device.
• ftruncate^⚠
  Truncate a file to a specified length.
• getcpu^⚠
  Determine CPU and NUMA node on which the calling thread is running.
• getcwd^⚠
  Get current working directory.
• getdents^⚠
  Get directory entries.
• getdents64^⚠
  Get directory entries using the new 64-bit structure type.
• getegid^⚠
  Get the effective group ID of the current process.
• geteuid^⚠
  Get the effective user ID of the current process.
• getgid^⚠
  Get the real group ID of the current process.
• getgroups^⚠
  Get the supplementary group IDs of the current process.
• getpeername^⚠
  Get the address of the peer connected to a socket.
• getpid^⚠
  Get the process id (PID) of the current process.
• getppid^⚠
  Get the process id (PID) of the parent of the current process.
• getrandom^⚠
  Get random bytes from the kernel.
• getresgid^⚠
  Get the real UID, the effective UID, and the saved set-user-ID of the current process.
• getresuid^⚠
  Get the real UID, the effective UID, and the saved set-user-ID of the current process.
• getsid^⚠
  Get the session ID of a process, or of the current process if pid is zero.
• getsockname^⚠
  Get the address that a socket is bound to.
• getsockopt^⚠
  Get a socket option.
• gettid^⚠
  Get the thread id (TID) of the current process.
• getuid^⚠
  Get the real user ID of the current process.
• inotify_add_watch^⚠
  Adds a new watch, or modifies an existing watch, to an inotify event queue.
• inotify_init^⚠
  Initializes a new inotify instance and returns a file descriptor associated with a new inotify event queue.
• inotify_init1^⚠
  Initializes a new inotify instance and returns a file descriptor associated with a new inotify event queue.
• inotify_rm_watch^⚠
  Removes an existing watch from an inotify event queue.
• io_uring_enter^⚠
  Initiate and complete I/O using the shared submission and completion queues for an io_uring instance.
• io_uring_register^⚠
  Registers resources for use with an io_uring instance.
• io_uring_setup^⚠
  Sets up an io_uring instance.
• ioctl^⚠
  Arbitrary requests for file descriptors representing devices.
• kill^⚠
  Send a signal to a process.
• lchown^⚠
  Change ownership of a file without dereferencing symbolic links.
• link^⚠
  Create a new link (a “hard link”) for an existing file.
• linkat^⚠
  Create a new link (a “hard link”) for an existing file relative to directory file descriptors.
• listen^⚠
  Listen for connections on a socket.
• lseek^⚠
  Reposition the read/write offset for a file.
• mmap^⚠
  Map a file or device into memory.
• mremap^⚠
  Change a memory mapping previously created with mmap.
• munmap^⚠
  Remove a mapping previously created with mmap.
• open^⚠
  Open a file.
• pause^⚠
  Pause the current process until a signal is delivered.
• pidfd_open^⚠
  Create a file descriptor representing a process.
• pipe^⚠
  Create pipe.
• pipe2^⚠
  Create pipe.
• pivot_root^⚠
  Changes the root mount in the mount namespace of the calling process.
• poll^⚠
  Wait for events on one or more file descriptors.
• ppoll^⚠
  Wait for events on one or more file descriptors while also awaiting signals.
• prctl^⚠
  Manipulates various aspects of the behavior of the calling thread or process.
• read^⚠
  Read from a file descriptor.
• readv^⚠
  Read from a file descriptor into multiple buffers.
• sendfile^⚠
  Copies data between one file descriptor and another.
• sendfile64^⚠
  Copies data between one file descriptor and another.
• setsockopt^⚠
  Set a socket option.
• socket^⚠
  Create a socket endpoint for communication.
• socketpair^⚠
  Create an unnamed pair of connected sockets.
• splice^⚠
  Moves data between two file descriptors without copying between kernel address space and user address space.
• sync^⚠
  Commit all filesystem caches to disk.
• syncfs^⚠
  Commit filesystem caches to disk for the filesystem containing a particular file.
• tee^⚠
  Duplicates data between file descriptors without consuming the data at the source.
• truncate^⚠
  Truncate a file to a specified length.
• write^⚠
  Write to a file descriptor.
• writev^⚠
  Write to a file descriptor from multiple buffers.

Type Definitions

• char
  The type used for characters on the current platform.
• gid_t
  The type used to represent group ids.
• ino64_t
• int
  The primary signed integer type for the current platform.
• loff_t
  The type used to represent larger file sizes and offsets into files on the current platform.
• long
  The signed long integer type for the current platform.
• longlong
  The signed long long integer type for the current platform.
• mode_t
  The type used to represent file modes on the current platform.
• nfds_t
• off64_t
  64-bit offset.
• off_t
  The type used to represent file sizes and offsets into files on the current platform.
• pid_t
  The type used for process identifiers (PIDs) on the current platform.
• sa_family_t
  The type for representing socket address families.
• short
  The short signed integer type for the current platform.
• size_t
  The unsigned size type for the current platform.
• socklen_t
  The type used for representing the length of a socket address.
• ssize_t
  The signed size type (or “pointer difference” type) for the current platform.
• suseconds_t
  Used for time in microseconds.
• time_t
  Used for time in seconds.
• uchar
  The type used for unsigned characters on the current platform.
• uid_t
  The type used to represent user ids.
• uint
  The primary unsigned integer type for the current platform.
• ulong
  The unsigned long integer type for the current platform.
• ulonglong
  The unsigned long long integer type for the current platform.
• ushort
  The short unsigned integer type for the current platform.
• void
  The type used for void pointers on the current platform.

Unions

• epoll_data
  A type used with crate::epoll_ctl.