Crate sys_util

Small system utility modules for usage by other modules.

Re-exports

pub use guest_memory::Error as GuestMemoryError;

pub use guest_memory::*;

pub use ioctl::*;

pub use signal::*;

Modules

guest_memory

Track memory regions that are mapped to the guest VM.

handle_eintr

Macro and helper trait for handling interrupted routines.

ioctl

Macros and wrapper functions for dealing with ioctls.

net

signal

syslog

Facilities for sending log message to syslog.

Macros

debug

A macro for logging debug information.

error

A macro for logging an error.

handle_eintr

Macro that retries the given expression every time its result indicates it was interrupted (i.e. returned EINTR). This is useful for operations that are prone to being interrupted by signals, such as blocking syscalls.

handle_eintr_errno

Macro that retries the given expression every time its result indicates it was interrupted. It is intended to use with system functions that signal error by returning -1 and setting errno to appropriate error code (EINTR, EINVAL, etc.) Most of standard non-reentrant libc functions use this way of signalling errors.

handle_eintr_rc

Macro that retries the given expression every time its result indicates it was interrupted. It is intended to use with system functions that return EINTR and other error codes directly as their result. Most of reentrant functions use this way of signalling errors.

info

A macro for logging info.

ioctl_expr

Raw macro to declare the expression that calculates an ioctl number

ioctl_io_nr

Declare an ioctl that transfers no data.

ioctl_ioc_nr

Raw macro to declare a function that returns an ioctl number.

ioctl_ior_nr

Declare an ioctl that reads data.

ioctl_iow_nr

Declare an ioctl that writes data.

ioctl_iowr_nr

Declare an ioctl that reads and writes data.

log

A macro for logging at an arbitrary priority level.

warn

A macro for logging a warning.

Structs

Clock

EpollContext

EpollContext wraps linux epoll. It provides similar interface to PollContext. It is thread safe while PollContext is not. It requires user to pass in a reference of EpollEvents while PollContext does not. Always use PollContext if you don’t need to access the same epoll from different threads.

EpollEvents

EpollEvents wraps raw epoll_events, it should only be used with EpollContext.

Error

An error number, retrieved from errno (man 3 errno), set by a libc function that returned an error.

EventFd

A safe wrapper around a Linux eventfd (man 2 eventfd).

FakeClock

A fake clock that can be used in tests to give exact control over the time. For a code example, see the tests in sys_util/src/timerfd.rs.

FakeTimerFd

FakeTimerFd: For use in tests.

Fd

GuestAddress

Represents an Address in the guest’s memory.

MemfdSeals

A set of memfd seals.

MemoryMapping

Wraps an anonymous shared memory mapping in the current process.

PollContext

Used to poll multiple objects that have file descriptors.

PollEvent

An event returned by PollContext::wait.

PollEventIter

An iterator over some (sub)set of events returned by PollContext::wait.

PollEvents

The list of event returned by PollContext::wait.

PollEventsOwned

A deep copy of the event records from PollEvents.

SharedMemory

A shared memory file descriptor and its size.

SignalFd

A safe wrapper around a Linux signalfd (man 2 signalfd).

TempDir

Create and remove a temporary directory. The directory will be maintained for the lifetime of the TempDir object.

TimerFd

A safe wrapper around a Linux timerfd (man 2 timerfd_create).

UnlinkUnixDatagram

Used to attempt to clean up a named pipe after it is no longer used.

WatchingEvents

Watching events taken by PollContext.

Enums

CloneError

CloneNamespace

Controls what namespace clone_process will have. See NAMESPACES(7).

Error

Error

FallocateMode

The operation to perform with fallocate.

FileFlags

FlockOperation

The operation to perform with flock.

MmapError

SignalFdError

Traits

FileSetLen

A trait for setting the size of a file. This is equivalent to File’s set_len method, but wrapped in a trait so that it can be implemented for other types.

FileSync

A trait for flushing the contents of a file to disk. This is equivalent to File’s sync_all method, but wrapped in a trait so that it can be implemented for other types.

IntoIovec

Trait for types that can be converted into an iovec that can be referenced by a syscall for the lifetime of this object.

PollToken

Trait for a token that can be associated with an fd in a PollContext.

PunchHole

A trait for deallocating space in a file.

ScmSocket

Trait for file descriptors can send and receive socket control messages via sendmsg and recvmsg.

SeekHole

A trait for seeking to the next hole or non-hole position in a file.

Terminal

Trait for file descriptors that are TTYs, according to isatty(3).

WriteZeroes

A trait for writing zeroes to a stream.

Functions

chown

Safe wrapper for chown(2).

clone_process

Clones this process and calls a closure in the new process.

fallocate

Safe wrapper for fallocate().

flock

Safe wrapper for flock(2) with the operation op and optionally nonblocking. The lock will be dropped automatically when file is dropped.

get_group_id

Safe wrapper for getting a gid from a group name with getgrnam_r(3).

get_user_id

Safe wrapper for getting a uid from a user name with getpwnam_r(3).

getegid

Safe wrapper for getegid(2).

geteuid

Safe wrapper for geteuid(2).

getpid

This bypasses libc’s caching getpid(2) wrapper which can be invalid if a raw clone was used elsewhere.

kernel_has_memfd

Checks if the kernel we are running on has memfd_create. It was introduced in 3.17. Only to be used from tests to prevent running on ancient kernels that won’t support the functionality anyways.

kill_process_group

Kill all processes in the current process group.

pagesize

Safe wrapper for sysconf(_SC_PAGESIZE).

pipe

Spawns a pipe pair where the first pipe is the read end and the second pipe is the write end.

read_struct^⚠

Reads a struct from an input buffer. This is unsafe because the struct is initialized to unverified data read from the input. read_struct should only be called to fill plain old data structs. It is not endian safe.

read_struct_slice^⚠

Reads an array of structs from an input buffer. Returns a Vec of structs initialized with data from the specified input. This is unsafe because the structs are initialized to unverified data read from the input. read_struct_slice should only be called for plain old data structs. It is not endian safe.

reap_child

Reaps a child process that has terminated.

round_up_to_page_size

Uses the system’s page size in bytes to round the given value up to the nearest page boundary.

set_rt_prio_limit

Enables real time thread priorities in the current thread up to limit.

set_rt_round_robin

Sets the current thread to be scheduled using the round robin real time class with priority.

validate_raw_fd

Verifies that |raw_fd| is actually owned by this process and duplicates it to ensure that we have a unique handle to it.

Type Aliases

Result

Derive Macros

PollToken

Implements the PollToken trait for a given enum.