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