Crate linux_unsafe

Expand description

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 x86_64.
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.
statx
statx_timestamp
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§

AT_EACCESS
AT_EMPTY_PATH
AT_FDCWD
AT_HANDLE_FID
AT_NO_AUTOMOUNT
AT_RECURSIVE
AT_REMOVEDIR
AT_STATX_DONT_SYNC
AT_STATX_FORCE_SYNC
AT_STATX_SYNC_AS_STAT
AT_STATX_SYNC_TYPE
AT_SYMLINK_FOLLOW
AT_SYMLINK_NOFOLLOW
DT_BLK
DT_CHR
DT_DIR
DT_FIFO
DT_LNK
DT_REG
DT_SOCK
DT_UNKNOWN
DT_WHT
FUTEX_CLOCK_REALTIME
FUTEX_CMP_REQUEUE
FUTEX_FD
FUTEX_LOCK_PI
FUTEX_PRIVATE
FUTEX_REQUEUE
FUTEX_TRYLOCK_PI
FUTEX_UNLOCK_PI
FUTEX_WAIT
FUTEX_WAIT_BITSET
FUTEX_WAKE
FUTEX_WAKE_OP
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.
STATX_ALL
STATX_ATIME
STATX_ATTR_APPEND
STATX_ATTR_AUTOMOUNT
STATX_ATTR_COMPRESSED
STATX_ATTR_DAX
STATX_ATTR_ENCRYPTED
STATX_ATTR_IMMUTABLE
STATX_ATTR_MOUNT_ROOT
STATX_ATTR_NODUMP
STATX_ATTR_VERITY
STATX_BASIC_STATS
STATX_BLOCKS
STATX_BTIME
STATX_CTIME
STATX_GID
STATX_INO
STATX_MODE
STATX_MTIME
STATX_NLINK
STATX_SIZE
STATX_TYPE
STATX_UID

Functions§

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.
alarm^⚠: Set an alarm clock for delivery of a signal.
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.
futex^⚠: Interact with the kernel’s “fast userspace locking” mechanism.
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 GID, the effective GID, and the saved set-group-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.
openat^⚠: 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.
readlink^⚠: Read value of a symbolic link.
readlinkat^⚠: Read value of a symbolic link relative to a directory file descriptor.
readv^⚠: Read from a file descriptor into multiple buffers.
sendfile^⚠: 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.
statx^⚠: Get file status, extended.
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 Aliases§

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.

Crate linux_unsafeCopy item path

§Be careful mixing with std