Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/sunfishcode/rustix-testing

Extra testing for rustix
https://github.com/sunfishcode/rustix-testing
Last synced: 5 days ago
JSON representation
Extra testing for rustix
Host: GitHub
URL: https://github.com/sunfishcode/rustix-testing
Owner: sunfishcode
License: other
Created: 2021-06-30T03:04:46.000Z (over 3 years ago)
Default Branch: main
Last Pushed: 2023-10-12T11:06:12.000Z (about 1 year ago)
Last Synced: 2024-10-25T00:39:29.963Z (20 days ago)
Language: Rust
Homepage:
Size: 3.7 MB
Stars: 2
Watchers: 3
Forks: 1
Open Issues: 0
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE-APACHE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project

README

        


  rustix


  


    Safe Rust bindings to POSIX/Unix/Linux/Winsock2 syscalls

  


  A Bytecode Alliance project

  


    

    

    

    

  



`rustix` provides efficient memory-safe and [I/O-safe] wrappers to POSIX-like,

Unix-like, Linux, and Winsock2 syscall-like APIs, with configurable backends.

It uses Rust references, slices, and return values instead of raw pointers, and

[I/O safety types] instead of raw file descriptors, providing memory safety,

[I/O safety], and [provenance]. It uses `Result`s for reporting errors,

[`bitflags`] instead of bare integer flags, an [`Arg`] trait with optimizations

to efficiently accept any Rust string type, and several other efficient

conveniences.

`rustix` is low-level and, and while the `net` API supports Winsock2 on

Windows, the rest of the APIs do not support Windows; for higher-level and more

portable APIs built on this functionality, see the [`cap-std`], [`memfd`],

[`timerfd`], and [`io-streams`] crates, for example.

`rustix` currently has two backends available:

 * linux_raw, which uses raw Linux system calls and vDSO calls, and is

   supported on Linux on x86-64, x86, aarch64, riscv64gc, powerpc64le,

   arm (v5 onwards), mipsel, and mips64el, with stable, nightly, and 1.63 Rust.

    - By being implemented entirely in Rust, avoiding `libc`, `errno`, and pthread

      cancellation, and employing some specialized optimizations, most functions

      compile down to very efficient code, which can often be fully inlined into

      user code.

    - Most functions in `linux_raw` preserve memory, I/O safety, and pointer

      provenance all the way down to the syscalls.

 * libc, which uses the [`libc`] crate which provides bindings to native `libc`

   libraries on Unix-family platforms, and [`windows-sys`] for Winsock2 on

   Windows, and is portable to many OS's.

The linux_raw backend is enabled by default on platforms which support it. To

enable the libc backend instead, either enable the "use-libc" cargo feature,

or set the `RUSTFLAGS` environment variable to `--cfg=rustix_use_libc` when

building.

## Cargo features

The modules [`rustix::io`], [`rustix::fd`], and [`rustix::ffi`] are enabled

by default. The rest of the API is conditional with cargo feature flags:

| Name       | Description

| ---------- | ---------------------

| `event`    | [`rustix::event`]—Polling and event operations.

| `fs`       | [`rustix::fs`] and [`rustix::path`]—Filesystem operations.

| `io_uring` | [`rustix::io_uring`]—Linux io_uring.

| `mm`       | [`rustix::mm`]—Memory map operations.

| `net`      | [`rustix::net`] and [`rustix::path`]—Network-related operations.

| `param`    | [`rustix::param`]—Process parameters.

| `pipe`     | [`rustix::pipe`]—Pipe operations.

| `process`  | [`rustix::process`]—Process-associated operations.

| `procfs`   | [`rustix::procfs`]—Utilities for reading `/proc` on Linux.

| `pty`      | [`rustix::pty`]—Pseudoterminal operations.

| `rand`     | [`rustix::rand`]—Random-related operations.

| `stdio`    | [`rustix::stdio`]—Stdio-related operations.

| `system`   | [`rustix::system`]—System-related operations.

| `termios`  | [`rustix::termios`]—Terminal I/O stream operations.

| `thread`   | [`rustix::thread`]—Thread-associated operations.

| `time`     | [`rustix::time`]—Time-related operations.

|            |

| `use-libc` | Enable the libc backend.

[`rustix::event`]: https://docs.rs/rustix/*/rustix/fs/index.html

[`rustix::fs`]: https://docs.rs/rustix/*/rustix/fs/index.html

[`rustix::io_uring`]: https://docs.rs/rustix/*/rustix/io_uring/index.html

[`rustix::mm`]: https://docs.rs/rustix/*/rustix/mm/index.html

[`rustix::net`]: https://docs.rs/rustix/*/rustix/net/index.html

[`rustix::param`]: https://docs.rs/rustix/*/rustix/param/index.html

[`rustix::pipe`]: https://docs.rs/rustix/*/rustix/pipe/index.html

[`rustix::process`]: https://docs.rs/rustix/*/rustix/process/index.html

[`rustix::procfs`]: https://docs.rs/rustix/*/rustix/procfs/index.html

[`rustix::pty`]: https://docs.rs/rustix/*/rustix/pty/index.html

[`rustix::rand`]: https://docs.rs/rustix/*/rustix/rand/index.html

[`rustix::stdio`]: https://docs.rs/rustix/*/rustix/stdio/index.html

[`rustix::system`]: https://docs.rs/rustix/*/rustix/system/index.html

[`rustix::termios`]: https://docs.rs/rustix/*/rustix/termios/index.html

[`rustix::thread`]: https://docs.rs/rustix/*/rustix/thread/index.html

[`rustix::time`]: https://docs.rs/rustix/*/rustix/time/index.html

[`rustix::io`]: https://docs.rs/rustix/*/rustix/io/index.html

[`rustix::fd`]: https://docs.rs/rustix/*/rustix/fd/index.html

[`rustix::ffi`]: https://docs.rs/rustix/*/rustix/ffi/index.html

[`rustix::path`]: https://docs.rs/rustix/*/rustix/path/index.html

## 64-bit Large File Support (LFS) and Year 2038 (y2038) support

`rustix` automatically uses 64-bit APIs when available, and avoids exposing

32-bit APIs that would have the year-2038 problem or fail to support large

files. For instance, `rustix::fstatvfs` calls `fstatvfs64`, and returns a

struct that's 64-bit even on 32-bit platforms.

## Similar crates

`rustix` is similar to [`nix`], [`simple_libc`], [`unix`], [`nc`], and

[`uapi`]. `rustix` is architected for [I/O safety] with most APIs using

[`OwnedFd`] and [`AsFd`] to manipulate file descriptors rather than `File` or

even `c_int`, and supporting multiple backends so that it can use direct

syscalls while still being usable on all platforms `libc` supports. Like `nix`,

`rustix` has an optimized and flexible filename argument mechanism that allows

users to use a variety of string types, including non-UTF-8 string types.

[`relibc`] is a similar project which aims to be a full "libc", including

C-compatible interfaces and higher-level C/POSIX standard-library

functionality; `rustix` just aims to provide safe and idiomatic Rust interfaces

to low-level syscalls. `relibc` also doesn't tend to support features not

supported on Redox, such as `*at` functions like `openat`, which are important

features for `rustix`.

`rustix` has its own code for making direct syscalls, similar to the

[`syscall`], [`sc`], and [`scall`] crates, though `rustix` can use either the

Rust `asm!` macro or out-of-line `.s` files so it supports Rust versions from

1.63 through Nightly and architectures where Rust's inline asm is not yet

stable. `rustix` can also use Linux's vDSO mechanism to optimize Linux

`clock_gettime` on all architectures, and all Linux system calls on x86. And

`rustix`'s syscalls report errors using an optimized `Errno` type.

`rustix`'s `*at` functions are similar to the [`openat`] crate, but `rustix`

provides them as free functions rather than associated functions of a `Dir`

type. `rustix`'s `CWD` constant exposes the special `AT_FDCWD` value in a safe

way, so users don't need to open `.` to get a current-directory handle.

`rustix`'s `openat2` function is similar to the [`openat2`] crate, but uses I/O

safety types rather than `RawFd`. `rustix` does not provide dynamic feature

detection, so users must handle the [`NOSYS`] error themselves.

`rustix`'s `termios` module is similar to the [`termios`] crate, but uses I/O

safety types rather than `RawFd`, and the flags parameters to functions such as

`tcsetattr` are `enum`s rather than bare integers. And, rustix calls its

`tcgetattr` function `tcgetattr`, rather than `Termios::from_fd`.

## Minimum Supported Rust Version (MSRV)

This crate currently works on the version of [Rust on Debian stable], which is

currently Rust 1.63. This policy may change in the future, in minor version

releases, so users using a fixed version of Rust should pin to a specific

version of this crate.

[Rust on Debian stable]: https://packages.debian.org/stable/rust/rustc

[`nix`]: https://crates.io/crates/nix

[`unix`]: https://crates.io/crates/unix

[`nc`]: https://crates.io/crates/nc

[`simple_libc`]: https://crates.io/crates/simple_libc

[`uapi`]: https://crates.io/crates/uapi

[`relibc`]: https://github.com/redox-os/relibc

[`syscall`]: https://crates.io/crates/syscall

[`sc`]: https://crates.io/crates/sc

[`scall`]: https://crates.io/crates/scall

[`openat`]: https://crates.io/crates/openat

[`openat2`]: https://crates.io/crates/openat2

[I/O safety types]: https://doc.rust-lang.org/stable/std/os/fd/index.html#structs

[`termios`]: https://crates.io/crates/termios

[`libc`]: https://crates.io/crates/libc

[`windows-sys`]: https://crates.io/crates/windows-sys

[`cap-std`]: https://crates.io/crates/cap-std

[`memfd`]: https://crates.io/crates/memfd

[`timerfd`]: https://crates.io/crates/timerfd

[`io-streams`]: https://crates.io/crates/io-streams

[`bitflags`]: https://crates.io/crates/bitflags

[`Arg`]: https://docs.rs/rustix/*/rustix/path/trait.Arg.html

[I/O-safe]: https://github.com/rust-lang/rfcs/blob/master/text/3128-io-safety.md

[I/O safety]: https://github.com/rust-lang/rfcs/blob/master/text/3128-io-safety.md

[provenance]: https://github.com/rust-lang/rust/issues/95228

[`OwnedFd`]: https://doc.rust-lang.org/stable/std/os/fd/struct.OwnedFd.html

[`AsFd`]: https://doc.rust-lang.org/stable/std/os/fd/trait.AsFd.html

[`NOSYS`]: https://docs.rs/rustix/*/rustix/io/struct.Errno.html#associatedconstant.NOSYS