vendor/nix/README.md

   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
   6 [Documentation (Releases)](https://docs.rs/nix/)
   7
   8 Nix 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
  10 what can be while still providing platform specific APIs.
  11
  12 For many system APIs, Nix provides a safe alternative to the unsafe APIs
  13 exposed by the [libc crate](https://github.com/rust-lang/libc).  This is done by
  14 wrapping the libc functionality with types/abstractions that enforce legal/safe
  15 usage.
  16
  17
  18 As an example of what Nix provides, examine the differences between what is
  19 exposed by libc and nix for the
  20 [gethostname](https://man7.org/linux/man-pages/man2/gethostname.2.html) system
  21 call:
  22
  23 ```rust,ignore
  24 // libc api (unsafe, requires handling return code/errno)
  25 pub unsafe extern fn gethostname(name: *mut c_char, len: size_t) -> c_int;
  26
  27 // nix api (returns a nix::Result<OsString>)
  28 pub fn gethostname() -> Result<OsString>;
  29 ```
  30
  31 ## Supported Platforms
  32
  33 nix target support consists of two tiers. While nix attempts to support all
  34 platforms supported by [libc](https://github.com/rust-lang/libc), only some
  35 platforms are actively supported due to either technical or manpower
  36 limitations. 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
  47 The following targets are supported by `nix`:
  48
  49 Tier 1:
  50   * aarch64-apple-darwin
  51   * aarch64-unknown-linux-gnu
  52   * arm-unknown-linux-gnueabi
  53   * armv7-unknown-linux-gnueabihf
  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   * powerpc64le-unknown-linux-gnu
  62   * x86_64-unknown-freebsd
  63   * x86_64-unknown-linux-gnu
  64   * x86_64-unknown-linux-musl
  65
  66 Tier 2:
  67   * aarch64-apple-ios
  68   * aarch64-linux-android
  69   * arm-linux-androideabi
  70   * arm-unknown-linux-musleabi
  71   * armv7-linux-androideabi
  72   * i686-linux-android
  73   * powerpc-unknown-linux-gnu
  74   * s390x-unknown-linux-gnu
  75   * x86_64-apple-ios
  76   * x86_64-linux-android
  77   * x86_64-apple-darwin
  78   * x86_64-unknown-illumos
  79   * x86_64-unknown-netbsd
  80
  81 Tier 3:
  82   * armv7-unknown-linux-uclibceabihf
  83   * x86_64-fuchsia
  84   * x86_64-unknown-dragonfly
  85   * x86_64-unknown-haiku
  86   * x86_64-unknown-linux-gnux32
  87   * x86_64-unknown-openbsd
  88   * x86_64-unknown-redox
  89
  90 ## Minimum Supported Rust Version (MSRV)
  91
  92 nix is supported on Rust 1.56.1 and higher.  Its MSRV will not be
  93 changed in the future without bumping the major or minor version.
  94
  95 ## Contributing
  96
  97 Contributions are very welcome.  Please See [CONTRIBUTING](CONTRIBUTING.md) for
  98 additional details.
  99
 100 Feel free to join us in [the nix-rust/nix](https://gitter.im/nix-rust/nix) channel on Gitter to
 101 discuss `nix` development.
 102
 103 ## License
 104
 105 Nix is licensed under the MIT license.  See [LICENSE](LICENSE) for more details.