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