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.

iovec

A type used with crate::readv and crate::writev.

pollfd

A file descriptor request object for use with crate::poll.

Enums

sock_type

The type for representing socket communication model types.

Constants

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

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.

getcpu^⚠

Determine CPU and NUMA node on which the calling thread is running.

getcwd^⚠

Get current working directory.

getpid^⚠

Get the process id (PID) of the current process.

getsockopt^⚠

Get a socket option.

ioctl^⚠

Arbitrary requests for file descriptors representing devices.

listen^⚠

Listen for connections on a socket.

lseek^⚠

Reposition the read/write offset for a file.

mmap^⚠

Map a file or device into memory.

munmap^⚠

Remove a mapping previously created with mmap.

open^⚠

Open a file.

pipe^⚠

Create pipe.

pipe2^⚠

Create pipe.

poll^⚠

Wait for events on one or more file descriptors.

read^⚠

Read from a file descriptor.

readv^⚠

Read from a file descriptor into multiple buffers.

setsockopt^⚠

Set a socket option.

socket^⚠

Create a socket endpoint for communication.

sync^⚠

Commit all filesystem caches to disk.

syncfs^⚠

Commit filesystem caches to disk for the filesystem containing a particular file.

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.

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.

mode_t

The type used to represent file modes on the current platform.

nfds_t

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.

sockaddr

The type used for representing the length of a socket address.

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.

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.

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.