third_party/rust/libc/README.md

   1 # libc - Raw FFI bindings to platforms' system libraries
   2
   3 [![GHA Status]][GitHub Actions] [![Cirrus CI Status]][Cirrus CI] [![Latest Version]][crates.io] [![Documentation]][docs.rs] ![License]
   4
   5 `libc` provides all of the definitions necessary to easily interoperate with C
   6 code (or "C-like" code) on each of the platforms that Rust supports. This
   7 includes type definitions (e.g. `c_int`), constants (e.g. `EINVAL`) as well as
   8 function headers (e.g. `malloc`).
   9
  10 This crate exports all underlying platform types, functions, and constants under
  11 the crate root, so all items are accessible as `libc::foo`. The types and values
  12 of all the exported APIs match the platform that libc is compiled for.
  13
  14 More detailed information about the design of this library can be found in its
  15 [associated RFC][rfc].
  16
  17 [rfc]: https://github.com/rust-lang/rfcs/blob/HEAD/text/1291-promote-libc.md
  18
  19 ## v0.3 Roadmap
  20
  21 The main branch is now for v0.3 which has some breaking changes.
  22
  23 For v0.2, please submit PRs to the `libc-0.2` branch instead.
  24 We will stop making new v0.2 releases once we release v0.3 on crates.io.
  25
  26 See the [tracking issue](https://github.com/rust-lang/libc/issues/3248) for details.
  27
  28 ## Usage
  29
  30 Add the following to your `Cargo.toml`:
  31
  32 ```toml
  33 [dependencies]
  34 libc = "0.2"
  35 ```
  36
  37 ## Features
  38
  39 * `std`: by default `libc` links to the standard library. Disable this
  40   feature to remove this dependency and be able to use `libc` in `#![no_std]`
  41   crates.
  42
  43 * `extra_traits`: all `struct`s implemented in `libc` are `Copy` and `Clone`.
  44   This feature derives `Debug`, `Eq`, `Hash`, and `PartialEq`.
  45
  46 * `const-extern-fn`: Changes some `extern fn`s into `const extern fn`s.
  47   If you use Rust >= 1.62, this feature is implicitly enabled.
  48   Otherwise it requires a nightly rustc.
  49
  50 * **deprecated**: `use_std` is deprecated, and is equivalent to `std`.
  51
  52 ## Rust version support
  53
  54 The minimum supported Rust toolchain version is currently **Rust 1.13.0**.
  55 (libc does not currently have any policy regarding changes to the minimum
  56 supported Rust version; such policy is a work in progress.) APIs requiring
  57 newer Rust features are only available on newer Rust toolchains:
  58
  59 | Feature              | Version |
  60 |----------------------|---------|
  61 | `union`              |  1.19.0 |
  62 | `const mem::size_of` |  1.24.0 |
  63 | `repr(align)`        |  1.25.0 |
  64 | `extra_traits`       |  1.25.0 |
  65 | `core::ffi::c_void`  |  1.30.0 |
  66 | `repr(packed(N))`    |  1.33.0 |
  67 | `cfg(target_vendor)` |  1.33.0 |
  68 | `const-extern-fn`    |  1.62.0 |
  69
  70 ## Platform support
  71
  72 You can see the platform(target)-specific docs on [docs.rs], select a platform you want to see.
  73
  74 See
  75 [`ci/build.sh`](https://github.com/rust-lang/libc/blob/HEAD/ci/build.sh)
  76 for the platforms on which `libc` is guaranteed to build for each Rust
  77 toolchain. The test-matrix at [GitHub Actions] and [Cirrus CI] show the
  78 platforms in which `libc` tests are run.
  79
  80 <div class="platform_docs"></div>
  81
  82 ## License
  83
  84 This project is licensed under either of
  85
  86 * [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0)
  87   ([LICENSE-APACHE](https://github.com/rust-lang/libc/blob/HEAD/LICENSE-APACHE))
  88
  89 * [MIT License](https://opensource.org/licenses/MIT)
  90   ([LICENSE-MIT](https://github.com/rust-lang/libc/blob/HEAD/LICENSE-MIT))
  91
  92 at your option.
  93
  94 ## Contributing
  95
  96 We welcome all people who want to contribute. Please see the [contributing
  97 instructions] for more information.
  98
  99 [contributing instructions]: https://github.com/rust-lang/libc/blob/HEAD/CONTRIBUTING.md
 100
 101 Contributions in any form (issues, pull requests, etc.) to this project
 102 must adhere to Rust's [Code of Conduct].
 103
 104 [Code of Conduct]: https://www.rust-lang.org/policies/code-of-conduct
 105
 106 Unless you explicitly state otherwise, any contribution intentionally submitted
 107 for inclusion in `libc` by you, as defined in the Apache-2.0 license, shall be
 108 dual licensed as above, without any additional terms or conditions.
 109
 110 [GitHub Actions]: https://github.com/rust-lang/libc/actions
 111 [GHA Status]: https://github.com/rust-lang/libc/workflows/CI/badge.svg
 112 [Cirrus CI]: https://cirrus-ci.com/github/rust-lang/libc
 113 [Cirrus CI Status]: https://api.cirrus-ci.com/github/rust-lang/libc.svg
 114 [crates.io]: https://crates.io/crates/libc
 115 [Latest Version]: https://img.shields.io/crates/v/libc.svg
 116 [Documentation]: https://docs.rs/libc/badge.svg
 117 [docs.rs]: https://docs.rs/libc
 118 [License]: https://img.shields.io/crates/l/libc.svg