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
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 all supported by nix on Rust 1.24.1 or newer (unless
48otherwise noted):
49
50Tier 1:
51 * aarch64-unknown-linux-gnu
52 * arm-unknown-linux-gnueabi
53 * armv7-unknown-linux-gnueabihf
54 * i686-apple-darwin
55 * i686-unknown-freebsd
56 * i686-unknown-linux-gnu
57 * i686-unknown-linux-musl
58 * mips-unknown-linux-gnu
59 * mips64-unknown-linux-gnuabi64
60 * mips64el-unknown-linux-gnuabi64
61 * mipsel-unknown-linux-gnu
62 * powerpc64-unknown-linux-gnu
63 * powerpc64le-unknown-linux-gnu
64 * x86_64-apple-darwin
65 * x86_64-unknown-freebsd
66 * x86_64-unknown-linux-gnu
67 * x86_64-unknown-linux-musl
68
69Tier 2:
70 * aarch64-apple-ios
71 * aarch64-linux-android
72 * arm-linux-androideabi
73 * arm-unknown-linux-musleabi
74 * armv7-apple-ios
75 * armv7-linux-androideabi
76 * armv7s-apple-ios
77 * i386-apple-ios
78 * i686-linux-android
79 * powerpc-unknown-linux-gnu
80 * s390x-unknown-linux-gnu
81 * x86_64-apple-ios
82 * x86_64-linux-android
83 * x86_64-unknown-netbsd
84
85## Usage
86
87To use `nix`, first add this to your `Cargo.toml`:
88
89```toml
90[dependencies]
91nix = "0.14.1"
92```
93
94Then, add this to your crate root:
95
96```rust,ignore
97extern crate nix;
98```
99
100## Contributing
101
102Contributions are very welcome. Please See [CONTRIBUTING](CONTRIBUTING.md) for
103additional details.
104
105Feel free to join us in [the nix-rust/nix](https://gitter.im/nix-rust/nix) channel on Gitter to
106discuss `nix` development.
107
108## License
109
110Nix is licensed under the MIT license. See [LICENSE](LICENSE) for more details.
111
){kind=link}