| 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 |