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](http://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.40.0 or newer. 91 92To use `nix`, add this to your `Cargo.toml`: 93 94```toml 95[dependencies] 96nix = "0.20.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}