| aio.rs |
POSIX Asynchronous I/O
The POSIX AIO interface is used for asynchronous I/O on files and disk-like
devices. It supports [`read`](struct.AioRead.html#method.new),
[`write`](struct.AioWrite.html#method.new),
[`fsync`](struct.AioFsync.html#method.new),
[`readv`](struct.AioReadv.html#method.new), and
[`writev`](struct.AioWritev.html#method.new), operations, subject to
platform support. Completion
notifications can optionally be delivered via
[signals](../signal/enum.SigevNotify.html#variant.SigevSignal), via the
[`aio_suspend`](fn.aio_suspend.html) function, or via polling. Some
platforms support other completion
notifications, such as
[kevent](../signal/enum.SigevNotify.html#variant.SigevKevent).
Multiple operations may be submitted in a batch with
[`lio_listio`](fn.lio_listio.html), though the standard does not guarantee
that they will be executed atomically.
Outstanding operations may be cancelled with
[`cancel`](trait.Aio.html#method.cancel) or
[`aio_cancel_all`](fn.aio_cancel_all.html), though the operating system may
not support this for all filesystems and devices. |
39148 |
| epoll.rs |
|
7463 |
| event.rs |
Kernel event notification mechanism
# See Also
[kqueue(2)](https://www.freebsd.org/cgi/man.cgi?query=kqueue) |
14322 |
| eventfd.rs |
|
2929 |
| fanotify.rs |
Monitoring API for filesystem events.
Fanotify is a Linux-only API to monitor filesystems events.
Additional capabilities compared to the `inotify` API include the ability to
monitor all of the objects in a mounted filesystem, the ability to make
access permission decisions, and the possibility to read or modify files
before access by other applications.
For more documentation, please read
[fanotify(7)](https://man7.org/linux/man-pages/man7/fanotify.7.html). |
13786 |
| inotify.rs |
Monitoring API for filesystem events.
Inotify is a Linux-only API to monitor filesystems events.
For more documentation, please read [inotify(7)](https://man7.org/linux/man-pages/man7/inotify.7.html).
# Examples
Monitor all events happening in directory "test":
```no_run
# use nix::sys::inotify::{AddWatchFlags,InitFlags,Inotify};
#
// We create a new inotify instance.
let instance = Inotify::init(InitFlags::empty()).unwrap();
// We add a new watch on directory "test" for all events.
let wd = instance.add_watch("test", AddWatchFlags::IN_ALL_EVENTS).unwrap();
loop {
// We read from our inotify instance for events.
let events = instance.read_events().unwrap();
println!("Events: {:?}", events);
}
``` |
8289 |
| ioctl |
|
|
| memfd.rs |
Interfaces for managing memory-backed files. |
4217 |
| mman.rs |
Memory management declarations. |
21699 |
| mod.rs |
Mostly platform-specific functionality |
3133 |
| personality.rs |
Process execution domains |
3480 |
| prctl.rs |
prctl is a Linux-only API for performing operations on a process or thread.
Note that careless use of some prctl() operations can confuse the user-space run-time
environment, so these operations should be used with care.
For more documentation, please read [prctl(2)](https://man7.org/linux/man-pages/man2/prctl.2.html). |
6754 |
| pthread.rs |
Low level threading primitives |
1306 |
| ptrace |
|
|
| quota.rs |
Set and configure disk quotas for users, groups, or projects.
# Examples
Enabling and setting a quota:
```rust,no_run
# use nix::sys::quota::{Dqblk, quotactl_on, quotactl_set, QuotaFmt, QuotaType, QuotaValidFlags};
quotactl_on(QuotaType::USRQUOTA, "/dev/sda1", QuotaFmt::QFMT_VFS_V1, "aquota.user").unwrap();
let mut dqblk: Dqblk = Default::default();
dqblk.set_blocks_hard_limit(10000);
dqblk.set_blocks_soft_limit(8000);
quotactl_set(QuotaType::USRQUOTA, "/dev/sda1", 50, &dqblk, QuotaValidFlags::QIF_BLIMITS).unwrap();
``` |
9331 |
| reboot.rs |
Reboot/shutdown
On Linux, This can also be used to enable/disable Ctrl-Alt-Delete. |
6346 |
| resource.rs |
Configure the process resource limits. |
13076 |
| select.rs |
Portably monitor a group of file descriptors for readiness. |
10309 |
| sendfile.rs |
Send data from a file to a socket, bypassing userland. |
15194 |
| signal.rs |
Operating system signals. |
52106 |
| signalfd.rs |
Interface for the `signalfd` syscall.
# Signal discarding
When a signal can't be delivered to a process (or thread), it will become a pending signal.
Failure to deliver could happen if the signal is blocked by every thread in the process or if
the signal handler is still handling a previous signal.
If a signal is sent to a process (or thread) that already has a pending signal of the same
type, it will be discarded. This means that if signals of the same type are received faster than
they are processed, some of those signals will be dropped. Because of this limitation,
`signalfd` in itself cannot be used for reliable communication between processes or threads.
Once the signal is unblocked, or the signal handler is finished, and a signal is still pending
(ie. not consumed from a signalfd) it will be delivered to the signal handler.
Please note that signal discarding is not specific to `signalfd`, but also happens with regular
signal handlers. |
5215 |
| socket |
|
|
| stat.rs |
|
13457 |
| statfs.rs |
Get filesystem statistics, non-portably
See [`statvfs`](crate::sys::statvfs) for a portable alternative. |
20747 |
| statvfs.rs |
Get filesystem statistics
See [the man pages](https://pubs.opengroup.org/onlinepubs/9699919799/functions/fstatvfs.html)
for more details. |
4466 |
| sysinfo.rs |
|
2742 |
| termios.rs |
An interface for controlling asynchronous communication ports
This interface provides a safe wrapper around the termios subsystem defined by POSIX. The
underlying types are all implemented in libc for most platforms and either wrapped in safer
types here or exported directly.
If you are unfamiliar with the `termios` API, you should first read the
[API documentation](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/termios.h.html) and
then come back to understand how `nix` safely wraps it.
It should be noted that this API incurs some runtime overhead above the base `libc` definitions.
As this interface is not used with high-bandwidth information, this should be fine in most
cases. The primary cost when using this API is that the `Termios` datatype here duplicates the
standard fields of the underlying `termios` struct and uses safe type wrappers for those fields.
This means that when crossing the FFI interface to the underlying C library, data is first
copied into the underlying `termios` struct, then the operation is done, and the data is copied
back (with additional sanity checking) into the safe wrapper types. The `termios` struct is
relatively small across all platforms (on the order of 32-64 bytes).
The following examples highlight some of the API use cases such that users coming from using C
or reading the standard documentation will understand how to use the safe API exposed here.
Example disabling processing of the end-of-file control character:
```
# use self::nix::sys::termios::SpecialCharacterIndices::VEOF;
# use self::nix::sys::termios::{_POSIX_VDISABLE, Termios};
# let mut termios: Termios = unsafe { std::mem::zeroed() };
termios.control_chars[VEOF as usize] = _POSIX_VDISABLE;
```
The flags within `Termios` are defined as bitfields using the `bitflags` crate. This provides
an interface for working with bitfields that is similar to working with the raw unsigned
integer types but offers type safety because of the internal checking that values will always
be a valid combination of the defined flags.
An example showing some of the basic operations for interacting with the control flags:
```
# use self::nix::sys::termios::{ControlFlags, Termios};
# let mut termios: Termios = unsafe { std::mem::zeroed() };
termios.control_flags & ControlFlags::CSIZE == ControlFlags::CS5;
termios.control_flags |= ControlFlags::CS5;
```
# Baud rates
This API is not consistent across platforms when it comes to `BaudRate`: Android and Linux both
only support the rates specified by the `BaudRate` enum through their termios API while the BSDs
support arbitrary baud rates as the values of the `BaudRate` enum constants are the same integer
value of the constant (`B9600` == `9600`). Therefore the `nix::termios` API uses the following
conventions:
* `cfgetispeed()` - Returns `u32` on BSDs, `BaudRate` on Android/Linux
* `cfgetospeed()` - Returns `u32` on BSDs, `BaudRate` on Android/Linux
* `cfsetispeed()` - Takes `u32` or `BaudRate` on BSDs, `BaudRate` on Android/Linux
* `cfsetospeed()` - Takes `u32` or `BaudRate` on BSDs, `BaudRate` on Android/Linux
* `cfsetspeed()` - Takes `u32` or `BaudRate` on BSDs, `BaudRate` on Android/Linux
The most common use case of specifying a baud rate using the enum will work the same across
platforms:
```rust
# use nix::sys::termios::{BaudRate, cfsetispeed, cfsetospeed, cfsetspeed, Termios};
# fn main() {
# let mut t: Termios = unsafe { std::mem::zeroed() };
cfsetispeed(&mut t, BaudRate::B9600).unwrap();
cfsetospeed(&mut t, BaudRate::B9600).unwrap();
cfsetspeed(&mut t, BaudRate::B9600).unwrap();
# }
```
Additionally round-tripping baud rates is consistent across platforms:
```rust
# use nix::sys::termios::{BaudRate, cfgetispeed, cfgetospeed, cfsetispeed, cfsetspeed, Termios};
# fn main() {
# let mut t: Termios = unsafe { std::mem::zeroed() };
# cfsetspeed(&mut t, BaudRate::B9600).unwrap();
let speed = cfgetispeed(&t);
assert_eq!(speed, cfgetospeed(&t));
cfsetispeed(&mut t, speed).unwrap();
# }
```
On non-BSDs, `cfgetispeed()` and `cfgetospeed()` both return a `BaudRate`:
|
33686 |
| time.rs |
|
20694 |
| timer.rs |
Timer API via signals.
Timer is a POSIX API to create timers and get expiration notifications
through queued Unix signals, for the current process. This is similar to
Linux's timerfd mechanism, except that API is specific to Linux and makes
use of file polling.
For more documentation, please read [timer_create](https://pubs.opengroup.org/onlinepubs/9699919799/functions/timer_create.html).
# Examples
Create an interval timer that signals SIGALARM every 250 milliseconds.
```no_run
use nix::sys::signal::{self, SigEvent, SigHandler, SigevNotify, Signal};
use nix::sys::timer::{Expiration, Timer, TimerSetTimeFlags};
use nix::time::ClockId;
use std::convert::TryFrom;
use std::sync::atomic::{AtomicU64, Ordering};
use std::thread::yield_now;
use std::time::Duration;
const SIG: Signal = Signal::SIGALRM;
static ALARMS: AtomicU64 = AtomicU64::new(0);
extern "C" fn handle_alarm(signal: libc::c_int) {
let signal = Signal::try_from(signal).unwrap();
if signal == SIG {
ALARMS.fetch_add(1, Ordering::Relaxed);
}
}
fn main() {
let clockid = ClockId::CLOCK_MONOTONIC;
let sigevent = SigEvent::new(SigevNotify::SigevSignal {
signal: SIG,
si_value: 0,
});
let mut timer = Timer::new(clockid, sigevent).unwrap();
let expiration = Expiration::Interval(Duration::from_millis(250).into());
let flags = TimerSetTimeFlags::empty();
timer.set(expiration, flags).expect("could not set timer");
let handler = SigHandler::Handler(handle_alarm);
unsafe { signal::signal(SIG, handler) }.unwrap();
loop {
let alarms = ALARMS.load(Ordering::Relaxed);
if alarms >= 10 {
println!("total alarms handled: {}", alarms);
break;
}
yield_now()
}
}
``` |
6757 |
| timerfd.rs |
Timer API via file descriptors.
Timer FD is a Linux-only API to create timers and get expiration
notifications through file descriptors.
For more documentation, please read [timerfd_create(2)](https://man7.org/linux/man-pages/man2/timerfd_create.2.html).
# Examples
Create a new one-shot timer that expires after 1 second.
```
# use std::os::unix::io::AsRawFd;
# use nix::sys::timerfd::{TimerFd, ClockId, TimerFlags, TimerSetTimeFlags,
# Expiration};
# use nix::sys::time::{TimeSpec, TimeValLike};
# use nix::unistd::read;
#
// We create a new monotonic timer.
let timer = TimerFd::new(ClockId::CLOCK_MONOTONIC, TimerFlags::empty())
.unwrap();
// We set a new one-shot timer in 1 seconds.
timer.set(
Expiration::OneShot(TimeSpec::seconds(1)),
TimerSetTimeFlags::empty()
).unwrap();
// We wait for the timer to expire.
timer.wait().unwrap();
``` |
7670 |
| uio.rs |
Vectored I/O |
8206 |
| utsname.rs |
Get system identification |
1651 |
| wait.rs |
Wait for a process to change status |
13534 |