aboutsummaryrefslogtreecommitdiff
path: root/libc/README.md
diff options
context:
space:
mode:
authorDaniel Mueller <deso@posteo.net>2019-05-24 18:07:22 -0700
committerDaniel Mueller <deso@posteo.net>2019-05-24 18:07:22 -0700
commit82cf43dd887801b8b22b8aae8c02854d921915d5 (patch)
treeb1bf3710bd07fe83e396a5db8563f3e6c5e85689 /libc/README.md
parent06722702ea35434189d7de2b13a00209b2ebbd6d (diff)
downloadnitrocli-82cf43dd887801b8b22b8aae8c02854d921915d5.tar.gz
nitrocli-82cf43dd887801b8b22b8aae8c02854d921915d5.tar.bz2
Update libc crate to 0.2.55
This change updates the libc crate to version 0.2.55. Import subrepo libc/:libc at caf17a0641d29dc624621177f5756804dd180c13
Diffstat (limited to 'libc/README.md')
-rw-r--r--libc/README.md226
1 files changed, 78 insertions, 148 deletions
diff --git a/libc/README.md b/libc/README.md
index 636f10e..a974ccd 100644
--- a/libc/README.md
+++ b/libc/README.md
@@ -1,173 +1,103 @@
-libc
+[![Travis-CI Status]][Travis-CI] [![Appveyor Status]][Appveyor] [![Cirrus-CI Status]][Cirrus-CI] [![Latest Version]][crates.io] [![Documentation]][docs.rs] ![License]
+
+libc - Raw FFI bindings to platforms' system libraries
====
-Raw FFI bindings to platform libraries like `libc`.
+`libc` provides all of the definitions necessary to easily interoperate with C
+code (or "C-like" code) on each of the platforms that Rust supports. This
+includes type definitions (e.g. `c_int`), constants (e.g. `EINVAL`) as well as
+function headers (e.g. `malloc`).
+
+This crate exports all underlying platform types, functions, and constants under
+the crate root, so all items are accessible as `libc::foo`. The types and values
+of all the exported APIs match the platform that libc is compiled for.
-[![Build Status](https://travis-ci.org/rust-lang/libc.svg?branch=master)](https://travis-ci.org/rust-lang/libc)
-[![Build status](https://ci.appveyor.com/api/projects/status/github/rust-lang/libc?svg=true)](https://ci.appveyor.com/project/rust-lang-libs/libc)
-[![Build Status](https://api.cirrus-ci.com/github/rust-lang/libc.svg)](https://cirrus-ci.com/github/rust-lang/libc)
-[![Latest version](https://img.shields.io/crates/v/libc.svg)](https://crates.io/crates/libc)
-[![Documentation](https://docs.rs/libc/badge.svg)](https://docs.rs/libc)
-![License](https://img.shields.io/crates/l/libc.svg)
+More detailed information about the design of this library can be found in its
+[associated RFC][rfc].
+
+[rfc]: https://github.com/rust-lang/rfcs/blob/master/text/1291-promote-libc.md
## Usage
-First, add the following to your `Cargo.toml`:
+Add the following to your `Cargo.toml`:
```toml
[dependencies]
libc = "0.2"
```
-Next, add this to your crate root:
+## Features
-```rust
-extern crate libc;
-```
+* `use_std`: by default `libc` links to the standard library. Disable this
+ feature remove this dependency and be able to use `libc` in `#![no_std]`
+ crates.
-Currently libc by default links to the standard library, but if you would
-instead like to use libc in a `#![no_std]` situation or crate you can request
-this via:
+* `extra_traits`: all `struct`s implemented in `libc` are `Copy` and `Clone`.
+ This feature derives `Debug`, `Eq`, `Hash`, and `PartialEq`.
-```toml
-[dependencies]
-libc = { version = "0.2", default-features = false }
-```
+## Rust version support
-By default libc uses private fields in structs in order to enforce a certain
-memory alignment on them. These structs can be hard to instantiate outside of
-libc. To make libc use `#[repr(align(x))]`, instead of the private fields,
-activate the *align* feature. This requires Rust 1.25 or newer:
+The minimum supported Rust toolchain version is **Rust 1.13.0** . APIs requiring
+newer Rust features are only available on newer Rust toolchains:
-```toml
-[dependencies]
-libc = { version = "0.2", features = ["align"] }
-```
+| Feature | Version |
+|----------------------|---------|
+| `union` | 1.19.0 |
+| `const mem::size_of` | 1.24.0 |
+| `repr(align)` | 1.25.0 |
+| `extra_traits` | 1.25.0 |
+| `core::ffi::c_void` | 1.30.0 |
+| `repr(packed(N))` | 1.33.0 |
-## What is libc?
+## Platform support
-The primary purpose of this crate is to provide all of the definitions necessary
-to easily interoperate with C code (or "C-like" code) on each of the platforms
-that Rust supports. This includes type definitions (e.g. `c_int`), constants
-(e.g. `EINVAL`) as well as function headers (e.g. `malloc`).
+[Platform-specific documentation (master branch)][docs.master].
-This crate does not strive to have any form of compatibility across platforms,
-but rather it is simply a straight binding to the system libraries on the
-platform in question.
+See
+[`ci/build.sh`](https://github.com/rust-lang/libc/blob/master/libc-test/build.rs)
+for the platforms on which `libc` is guaranteed to build for each Rust
+toolchain. The test-matrix at [Travis-CI], [Appveyor], and [Cirrus-CI] show the
+platforms in which `libc` tests are run.
-## Public API
+<div class="platform_docs"></div>
-This crate exports all underlying platform types, functions, and constants under
-the crate root, so all items are accessible as `libc::foo`. The types and values
-of all the exported APIs match the platform that libc is compiled for.
+## License
-More detailed information about the design of this library can be found in its
-[associated RFC][rfc].
+This project is licensed under either of
-[rfc]: https://github.com/rust-lang/rfcs/blob/master/text/1291-promote-libc.md
+* [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
+ ([LICENSE-APACHE](LICENSE-APACHE))
+
+* [MIT License](http://opensource.org/licenses/MIT)
+ ([LICENSE-MIT](LICENSE-MIT))
+
+at your option.
+
+## Contributing
+
+We welcome all people who want to contribute. Please see the [contributing
+instructions] for more information.
+
+[contributing instructions]: CONTRIBUTING.md
+
+Contributions in any form (issues, pull requests, etc.) to this project
+must adhere to Rust's [Code of Conduct].
+
+[Code of Conduct]: https://www.rust-lang.org/en-US/conduct.html
+
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in `libc` by you, as defined in the Apache-2.0 license, shall be
+dual licensed as above, without any additional terms or conditions.
-## Adding an API
-
-Want to use an API which currently isn't bound in `libc`? It's quite easy to add
-one!
-
-The internal structure of this crate is designed to minimize the number of
-`#[cfg]` attributes in order to easily be able to add new items which apply
-to all platforms in the future. As a result, the crate is organized
-hierarchically based on platform. Each module has a number of `#[cfg]`'d
-children, but only one is ever actually compiled. Each module then reexports all
-the contents of its children.
-
-This means that for each platform that libc supports, the path from a
-leaf module to the root will contain all bindings for the platform in question.
-Consequently, this indicates where an API should be added! Adding an API at a
-particular level in the hierarchy means that it is supported on all the child
-platforms of that level. For example, when adding a Unix API it should be added
-to `src/unix/mod.rs`, but when adding a Linux-only API it should be added to
-`src/unix/notbsd/linux/mod.rs`.
-
-If you're not 100% sure at what level of the hierarchy an API should be added
-at, fear not! This crate has CI support which tests any binding against all
-platforms supported, so you'll see failures if an API is added at the wrong
-level or has different signatures across platforms.
-
-With that in mind, the steps for adding a new API are:
-
-1. Determine where in the module hierarchy your API should be added.
-2. Add the API.
-3. Send a PR to this repo.
-4. Wait for CI to pass, fixing errors.
-5. Wait for a merge!
-
-### Test before you commit
-
-We have two automated tests running on [Travis](https://travis-ci.org/rust-lang/libc):
-
-1. [`libc-test`](https://github.com/alexcrichton/ctest)
- - `cd libc-test && cargo test`
- - Use the `skip_*()` functions in `build.rs` if you really need a workaround.
-2. Style checker
- - `rustc ci/style.rs && ./style src`
-
-### Releasing your change to crates.io
-
-Now that you've done the amazing job of landing your new API or your new
-platform in this crate, the next step is to get that sweet, sweet usage from
-crates.io! The only next step is to bump the version of libc and then publish
-it. If you'd like to get a release out ASAP you can follow these steps:
-
-1. Update the version number in `Cargo.toml`, you'll just be bumping the patch
- version number.
-2. Run `cargo update` to regenerate the lockfile to encode your version bump in
- the lock file. You may pull in some other updated dependencies, that's ok.
-3. Send a PR to this repository. It should [look like this][example], but it'd
- also be nice to fill out the description with a small rationale for the
- release (any rationale is ok though!)
-4. Once merged the release will be tagged and published by one of the libc crate
- maintainers.
-
-[example]: https://github.com/rust-lang/libc/pull/583
-
-## Platforms and Documentation
-
-The following platforms are currently tested and have documentation available:
-
-Tested:
- * [`i686-pc-windows-msvc`](https://rust-lang.github.io/libc/i686-pc-windows-msvc/libc/)
- * [`x86_64-pc-windows-msvc`](https://rust-lang.github.io/libc/x86_64-pc-windows-msvc/libc/)
- (Windows)
- * [`i686-pc-windows-gnu`](https://rust-lang.github.io/libc/i686-pc-windows-gnu/libc/)
- * [`x86_64-pc-windows-gnu`](https://rust-lang.github.io/libc/x86_64-pc-windows-gnu/libc/)
- * [`i686-apple-darwin`](https://rust-lang.github.io/libc/i686-apple-darwin/libc/)
- * [`x86_64-apple-darwin`](https://rust-lang.github.io/libc/x86_64-apple-darwin/libc/)
- (OSX)
- * `i386-apple-ios`
- * `x86_64-apple-ios`
- * [`i686-unknown-linux-gnu`](https://rust-lang.github.io/libc/i686-unknown-linux-gnu/libc/)
- * [`x86_64-unknown-linux-gnu`](https://rust-lang.github.io/libc/x86_64-unknown-linux-gnu/libc/)
- (Linux)
- * [`x86_64-unknown-linux-musl`](https://rust-lang.github.io/libc/x86_64-unknown-linux-musl/libc/)
- (Linux MUSL)
- * [`aarch64-unknown-linux-gnu`](https://rust-lang.github.io/libc/aarch64-unknown-linux-gnu/libc/)
- (Linux)
- * `aarch64-unknown-linux-musl`
- (Linux MUSL)
- * [`sparc64-unknown-linux-gnu`](https://rust-lang.github.io/libc/sparc64-unknown-linux-gnu/libc/)
- (Linux)
- * [`mips-unknown-linux-gnu`](https://rust-lang.github.io/libc/mips-unknown-linux-gnu/libc/)
- * [`arm-unknown-linux-gnueabihf`](https://rust-lang.github.io/libc/arm-unknown-linux-gnueabihf/libc/)
- * [`arm-linux-androideabi`](https://rust-lang.github.io/libc/arm-linux-androideabi/libc/)
- (Android)
- * [`x86_64-unknown-freebsd`](https://rust-lang.github.io/libc/x86_64-unknown-freebsd/libc/)
- * [`x86_64-unknown-openbsd`](https://rust-lang.github.io/libc/x86_64-unknown-openbsd/libc/)
- * [`x86_64-rumprun-netbsd`](https://rust-lang.github.io/libc/x86_64-unknown-netbsd/libc/)
-
-The following may be supported, but are not guaranteed to always work:
-
- * `i686-unknown-freebsd`
- * [`x86_64-unknown-bitrig`](https://rust-lang.github.io/libc/x86_64-unknown-bitrig/libc/)
- * [`x86_64-unknown-dragonfly`](https://rust-lang.github.io/libc/x86_64-unknown-dragonfly/libc/)
- * `i686-unknown-haiku`
- * `x86_64-unknown-haiku`
- * [`x86_64-unknown-netbsd`](https://rust-lang.github.io/libc/x86_64-unknown-netbsd/libc/)
- * [`x86_64-sun-solaris`](https://rust-lang.github.io/libc/x86_64-sun-solaris/libc/)
+[Travis-CI]: https://travis-ci.com/rust-lang/libc
+[Travis-CI Status]: https://travis-ci.com/rust-lang/libc.svg?branch=master
+[Appveyor]: https://ci.appveyor.com/project/rust-lang-libs/libc
+[Appveyor Status]: https://ci.appveyor.com/api/projects/status/github/rust-lang/libc?svg=true
+[Cirrus-CI]: https://cirrus-ci.com/github/rust-lang/libc
+[Cirrus-CI Status]: https://api.cirrus-ci.com/github/rust-lang/libc.svg
+[crates.io]: https://crates.io/crates/libc
+[Latest Version]: https://img.shields.io/crates/v/libc.svg
+[Documentation]: https://docs.rs/libc/badge.svg
+[docs.rs]: https://docs.rs/libc
+[License]: https://img.shields.io/crates/l/libc.svg
+[docs.master]: https://rust-lang.github.io/libc/#platform-specific-documentation