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