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[![maintenance-status](https://img.shields.io/badge/maintenance-looking--for--maintainer-orange.svg)](https://github.com/nix-rust/nix/issues/2132)
6
7[Documentation (Releases)](https://docs.rs/nix/)
8
9Nix seeks to provide friendly bindings to various *nix platform APIs (Linux, Darwin,
10...). The goal is to not provide a 100% unified interface, but to unify
11what can be while still providing platform specific APIs.
12
13For many system APIs, Nix provides a safe alternative to the unsafe APIs
14exposed by the [libc crate](https://github.com/rust-lang/libc).  This is done by
15wrapping the libc functionality with types/abstractions that enforce legal/safe
16usage.
17
18
19As an example of what Nix provides, examine the differences between what is
20exposed by libc and nix for the
21[gethostname](https://man7.org/linux/man-pages/man2/gethostname.2.html) system
22call:
23
24```rust,ignore
25// libc api (unsafe, requires handling return code/errno)
26pub unsafe extern fn gethostname(name: *mut c_char, len: size_t) -> c_int;
27
28// nix api (returns a nix::Result<OsString>)
29pub fn gethostname() -> Result<OsString>;
30```
31
32## Supported Platforms
33
34nix target support consists of three tiers. While nix attempts to support all
35platforms supported by [libc](https://github.com/rust-lang/libc), only some
36platforms are actively supported due to either technical or manpower
37limitations. Support for platforms is split into three tiers:
38
39  * Tier 1 - Builds and tests for this target are run in CI. Failures of either
40             block the inclusion of new code.
41  * Tier 2 - Builds for this target are run in CI. Failures during the build
42             blocks the inclusion of new code. Tests may be run, but failures
43             in tests don't block the inclusion of new code.
44  * Tier 3 - Builds for this target are run in CI. Failures during the build
45             *do not* necessarily block the inclusion of new code.  That is, at
46             our discretion a Tier 3 target may be dropped at any time, if it
47             would otherwise block development.
48
49Platforms not listed are supported on a best-effort basis, relying on our users
50to report any problems.
51
52The following targets are supported by `nix`:
53
54<table>
55 <tr>
56  <th>Tier 1</th>
57  <th>Tier 2</th>
58  <th>Tier 3</th>
59 </tr>
60 <tr>
61  <td>
62   <ul>
63    <li>aarch64-apple-darwin</li>
64    <li>aarch64-unknown-linux-gnu</li>
65    <li>arm-unknown-linux-gnueabi</li>
66    <li>armv7-unknown-linux-gnueabihf</li>
67    <li>i686-unknown-freebsd</li>
68    <li>i686-unknown-linux-gnu</li>
69    <li>i686-unknown-linux-musl</li>
70    <li>mips-unknown-linux-gnu</li>
71    <li>mips64-unknown-linux-gnuabi64</li>
72    <li>mips64el-unknown-linux-gnuabi64</li>
73    <li>mipsel-unknown-linux-gnu</li>
74    <li>powerpc64le-unknown-linux-gnu</li>
75    <li>x86_64-unknown-freebsd</li>
76    <li>x86_64-unknown-linux-gnu</li>
77    <li>x86_64-unknown-linux-musl</li>
78   </ul>
79  </td>
80  <td>
81   <ul>
82    <li>aarch64-apple-ios</li>
83    <li>aarch64-linux-android</li>
84    <li>arm-linux-androideabi</li>
85    <li>arm-unknown-linux-musleabi</li>
86    <li>armv7-linux-androideabi</li>
87    <li>i686-linux-android</li>
88    <li>s390x-unknown-linux-gnu</li>
89    <li>x86_64-linux-android</li>
90    <li>x86_64-unknown-illumos</li>
91    <li>x86_64-unknown-netbsd</li>
92   </td>
93   <td>
94    <li>armv7-unknown-linux-uclibceabihf</li>
95    <li>powerpc64-unknown-linux-gnu</li>
96    <li>x86_64-fuchsia</li>
97    <li>x86_64-unknown-dragonfly</li>
98    <li>x86_64-unknown-haiku</li>
99    <li>x86_64-unknown-linux-gnux32</li>
100    <li>x86_64-unknown-openbsd</li>
101    <li>x86_64-unknown-redox</li>
102    <li>i686-unknown-hurd-gnu</li>
103   </td>
104  </tr>
105</table>
106
107## Minimum Supported Rust Version (MSRV)
108
109nix is supported on Rust 1.69 and higher.  Its MSRV will not be
110changed in the future without bumping the major or minor version.
111
112## Contributing
113
114Contributions are very welcome.  Please See [CONTRIBUTING](CONTRIBUTING.md) for
115additional details.
116
117Feel free to join us in [the nix-rust/nix](https://gitter.im/nix-rust/nix) channel on Gitter to
118discuss `nix` development.
119
120## License
121
122Nix is licensed under the MIT license.  See [LICENSE](LICENSE) for more details.
123