• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Rust bindings to *nix APIs
2
3[![Cirrus Build Status](https://api.cirrus-ci.com/github/nix-rust/nix.svg)](https://cirrus-ci.com/github/nix-rust/nix)
4[![crates.io](https://img.shields.io/crates/v/nix.svg)](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<OsString>)
28pub fn gethostname() -> Result<OsString>;
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-apple-darwin
51  * aarch64-unknown-linux-gnu
52  * arm-unknown-linux-gnueabi
53  * armv7-unknown-linux-gnueabihf
54  * i686-unknown-freebsd
55  * i686-unknown-linux-gnu
56  * i686-unknown-linux-musl
57  * mips-unknown-linux-gnu
58  * mips64-unknown-linux-gnuabi64
59  * mips64el-unknown-linux-gnuabi64
60  * mipsel-unknown-linux-gnu
61  * powerpc64le-unknown-linux-gnu
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-apple-darwin
78  * x86_64-unknown-illumos
79  * x86_64-unknown-netbsd
80
81Tier 3:
82  * armv7-unknown-linux-uclibceabihf
83  * x86_64-fuchsia
84  * x86_64-unknown-dragonfly
85  * x86_64-unknown-haiku
86  * x86_64-unknown-linux-gnux32
87  * x86_64-unknown-openbsd
88  * x86_64-unknown-redox
89
90## Minimum Supported Rust Version (MSRV)
91
92nix is supported on Rust 1.56.1 and higher.  Its MSRV will not be
93changed in the future without bumping the major or minor version.
94
95## Contributing
96
97Contributions are very welcome.  Please See [CONTRIBUTING](CONTRIBUTING.md) for
98additional details.
99
100Feel free to join us in [the nix-rust/nix](https://gitter.im/nix-rust/nix) channel on Gitter to
101discuss `nix` development.
102
103## License
104
105Nix is licensed under the MIT license.  See [LICENSE](LICENSE) for more details.
106