README.md
1# Rust bindings to *nix APIs
2
3[](https://cirrus-ci.com/github/nix-rust/nix)
4[](https://crates.io/crates/nix)
5
6[Documentation (Releases)](https://docs.rs/nix/)
7
8Nix seeks to provide friendly bindings to various *nix platform APIs (Linux, Darwin,
9...). The goal is to not provide a 100% unified interface, but to unify
10what can be while still providing platform specific APIs.
11
12For many system APIs, Nix provides a safe alternative to the unsafe APIs
13exposed by the [libc crate](https://github.com/rust-lang/libc). This is done by
14wrapping the libc functionality with types/abstractions that enforce legal/safe
15usage.
16
17
18As an example of what Nix provides, examine the differences between what is
19exposed by libc and nix for the
20[gethostname](https://man7.org/linux/man-pages/man2/gethostname.2.html) system
21call:
22
23```rust,ignore
24// libc api (unsafe, requires handling return code/errno)
25pub unsafe extern fn gethostname(name: *mut c_char, len: size_t) -> c_int;
26
27// nix api (returns a nix::Result<CStr>)
28pub fn gethostname<'a>(buffer: &'a mut [u8]) -> Result<&'a CStr>;
29```
30
31## Supported Platforms
32
33nix target support consists of two tiers. While nix attempts to support all
34platforms supported by [libc](https://github.com/rust-lang/libc), only some
35platforms are actively supported due to either technical or manpower
36limitations. Support for platforms is split into three tiers:
37
38 * Tier 1 - Builds and tests for this target are run in CI. Failures of either
39 block the inclusion of new code.
40 * Tier 2 - Builds for this target are run in CI. Failures during the build
41 blocks the inclusion of new code. Tests may be run, but failures
42 in tests don't block the inclusion of new code.
43 * Tier 3 - Builds for this target are run in CI. Failures during the build
44 *do not* block the inclusion of new code. Testing may be run, but
45 failures in tests don't block the inclusion of new code.
46
47The following targets are supported by `nix`:
48
49Tier 1:
50 * aarch64-unknown-linux-gnu
51 * arm-unknown-linux-gnueabi
52 * armv7-unknown-linux-gnueabihf
53 * i686-unknown-freebsd
54 * i686-unknown-linux-gnu
55 * i686-unknown-linux-musl
56 * mips-unknown-linux-gnu
57 * mips64-unknown-linux-gnuabi64
58 * mips64el-unknown-linux-gnuabi64
59 * mipsel-unknown-linux-gnu
60 * powerpc64le-unknown-linux-gnu
61 * x86_64-apple-darwin
62 * x86_64-unknown-freebsd
63 * x86_64-unknown-linux-gnu
64 * x86_64-unknown-linux-musl
65
66Tier 2:
67 * aarch64-apple-ios
68 * aarch64-linux-android
69 * arm-linux-androideabi
70 * arm-unknown-linux-musleabi
71 * armv7-linux-androideabi
72 * i686-linux-android
73 * powerpc-unknown-linux-gnu
74 * s390x-unknown-linux-gnu
75 * x86_64-apple-ios
76 * x86_64-linux-android
77 * x86_64-unknown-illumos
78 * x86_64-unknown-netbsd
79
80Tier 3:
81 * x86_64-fuchsia
82 * x86_64-unknown-dragonfly
83 * x86_64-unknown-linux-gnux32
84 * x86_64-unknown-openbsd
85 * x86_64-unknown-redox
86
87## Minimum Supported Rust Version (MSRV)
88
89nix is supported on Rust 1.46.0 and higher. It's MSRV will not be
90changed in the future without bumping the major or minor version.
91
92## Contributing
93
94Contributions are very welcome. Please See [CONTRIBUTING](CONTRIBUTING.md) for
95additional details.
96
97Feel free to join us in [the nix-rust/nix](https://gitter.im/nix-rust/nix) channel on Gitter to
98discuss `nix` development.
99
100## License
101
102Nix is licensed under the MIT license. See [LICENSE](LICENSE) for more details.
103
){kind=link}
){kind=link}