Crate linux_unsafe

source ·
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

Thin wrappers around the CPU instructions for making system calls on riscv64.
Types representing results from system call wrapper functions.

Structs

A type used with crate::readv and crate::writev.
A file descriptor request object for use with [crate::poll].

Constants

Functions

Close a file.
exit
Immediately terminate the current thread, without giving Rust or libc any opportunity to run destructors or other cleanup code.
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.
Get the process id (PID) of the current process.
Reposition the read/write offset for a file.
read
Read from a file descriptor.
Read from a file descriptor into multiple buffers.
sync
Commit all filesystem caches to disk.
Commit filesystem caches to disk for the filesystem containing a particular file.
Write to a file descriptor.
Write to a file descriptor from multiple buffers.

Type Definitions

The type used for characters on the current platform.
The primary signed integer type for the current platform.
The type used to represent larger file sizes and offsets into files on the current platform.
The signed long integer type for the current platform.
The type used to represent file modes on the current platform.
The type used to represent file sizes and offsets into files on the current platform.
The type used for process identifiers (PIDs) on the current platform.
The short signed integer type for the current platform.
The unsigned size type for the current platform.
The signed size type (or “pointer difference” type) for the current platform.
The primary unsigned integer type for the current platform.
The unsigned long integer type for the current platform.
The short unsigned integer type for the current platform.
The type used for void pointers on the current platform.