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-apple-ios
72 * armv7-linux-androideabi
73 * armv7s-apple-ios
74 * i386-apple-ios
75 * i686-apple-darwin
76 * i686-linux-android
77 * powerpc-unknown-linux-gnu
78 * s390x-unknown-linux-gnu
79 * x86_64-apple-ios
80 * x86_64-linux-android
81 * x86_64-unknown-netbsd
82
83Tier 3:
84 * x86_64-fuchsia
85 * x86_64-unknown-redox
86 * x86_64-unknown-linux-gnux32
87
88## Usage
89
90`nix` requires Rust 1.41.0 or newer.
91
92To use `nix`, add this to your `Cargo.toml`:
93
94```toml
95[dependencies]
96nix = "0.22.0"
97```
98
99## Contributing
100
101Contributions are very welcome. Please See [CONTRIBUTING](CONTRIBUTING.md) for
102additional details.
103
104Feel free to join us in [the nix-rust/nix](https://gitter.im/nix-rust/nix) channel on Gitter to
105discuss `nix` development.
106
107## License
108
109Nix is licensed under the MIT license. See [LICENSE](LICENSE) for more details.
110
){kind=link}