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 6code (or "C-like" code) on each of the platforms that Rust supports. This 7includes type definitions (e.g. `c_int`), constants (e.g. `EINVAL`) as well as 8function headers (e.g. `malloc`). 9 10This crate exports all underlying platform types, functions, and constants under 11the crate root, so all items are accessible as `libc::foo`. The types and values 12of all the exported APIs match the platform that libc is compiled for. 13 14More 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 21The main branch is now for v0.3 which has some breaking changes. 22 23For v0.2, please submit PRs to the `libc-0.2` branch instead. 24We will stop making new v0.2 releases once we release v0.3 on crates.io. 25 26See the [tracking issue](https://github.com/rust-lang/libc/issues/3248) for details. 27 28## Usage 29 30Add the following to your `Cargo.toml`: 31 32```toml 33[dependencies] 34libc = "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 54The minimum supported Rust toolchain version is currently **Rust 1.13.0**. 55(libc does not currently have any policy regarding changes to the minimum 56supported Rust version; such policy is a work in progress.) APIs requiring 57newer 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 72You can see the platform(target)-specific docs on [docs.rs], select a platform you want to see. 73 74See 75[`ci/build.sh`](https://github.com/rust-lang/libc/blob/HEAD/ci/build.sh) 76for the platforms on which `libc` is guaranteed to build for each Rust 77toolchain. The test-matrix at [GitHub Actions] and [Cirrus CI] show the 78platforms in which `libc` tests are run. 79 80<div class="platform_docs"></div> 81 82## License 83 84This 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 92at your option. 93 94## Contributing 95 96We welcome all people who want to contribute. Please see the [contributing 97instructions] for more information. 98 99[contributing instructions]: https://github.com/rust-lang/libc/blob/HEAD/CONTRIBUTING.md 100 101Contributions in any form (issues, pull requests, etc.) to this project 102must adhere to Rust's [Code of Conduct]. 103 104[Code of Conduct]: https://www.rust-lang.org/policies/code-of-conduct 105 106Unless you explicitly state otherwise, any contribution intentionally submitted 107for inclusion in `libc` by you, as defined in the Apache-2.0 license, shall be 108dual 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 119
