Revision control
Copy as Markdown
Other Tools
<!-- Copyright 2022 The Fuchsia Authors
Licensed under a BSD-style license <LICENSE-BSD>, Apache License, Version 2.0
This file may not be copied, modified, or distributed except according to
those terms.
WARNING: DO NOT EDIT THIS FILE. It is generated automatically. Edits should be
made in the doc comment on `src/lib.rs` or in `generate-readme.sh`.
-->
# zerocopy
*<span style="font-size: 100%; color:grey;">Want to help improve zerocopy?
Fill out our [user survey][user-survey]!</span>*
***<span style="font-size: 140%">Fast, safe, <span
style="color:red;">compile error</span>. Pick two.</span>***
Zerocopy makes zero-cost memory manipulation effortless. We write `unsafe`
so you don't have to.
## Overview
Zerocopy provides four core marker traits, each of which can be derived
(e.g., `#[derive(FromZeroes)]`):
- `FromZeroes` indicates that a sequence of zero bytes represents a valid
instance of a type
- `FromBytes` indicates that a type may safely be converted from an
arbitrary byte sequence
- `AsBytes` indicates that a type may safely be converted *to* a byte
sequence
- `Unaligned` indicates that a type's alignment requirement is 1
Types which implement a subset of these traits can then be converted to/from
byte sequences with little to no runtime overhead.
Zerocopy also provides byte-order aware integer types that support these
conversions; see the `byteorder` module. These types are especially useful
for network parsing.
[user-survey]: https://docs.google.com/forms/d/e/1FAIpQLSdzBNTN9tzwsmtyZxRFNL02K36IWCdHWW2ZBckyQS2xiO3i8Q/viewform?usp=published_options
## Cargo Features
- **`alloc`**
By default, `zerocopy` is `no_std`. When the `alloc` feature is enabled,
the `alloc` crate is added as a dependency, and some allocation-related
functionality is added.
- **`byteorder`** (enabled by default)
Adds the `byteorder` module and a dependency on the `byteorder` crate.
The `byteorder` module provides byte order-aware equivalents of the
multi-byte primitive numerical types. Unlike their primitive equivalents,
the types in this module have no alignment requirement and support byte
order conversions. This can be useful in handling file formats, network
packet layouts, etc which don't provide alignment guarantees and which may
use a byte order different from that of the execution platform.
- **`derive`**
Provides derives for the core marker traits via the `zerocopy-derive`
crate. These derives are re-exported from `zerocopy`, so it is not
necessary to depend on `zerocopy-derive` directly.
However, you may experience better compile times if you instead directly
depend on both `zerocopy` and `zerocopy-derive` in your `Cargo.toml`,
since doing so will allow Rust to compile these crates in parallel. To do
so, do *not* enable the `derive` feature, and list both dependencies in
your `Cargo.toml` with the same leading non-zero version number; e.g:
```toml
[dependencies]
zerocopy = "0.X"
zerocopy-derive = "0.X"
```
- **`simd`**
When the `simd` feature is enabled, `FromZeroes`, `FromBytes`, and
`AsBytes` impls are emitted for all stable SIMD types which exist on the
target platform. Note that the layout of SIMD types is not yet stabilized,
so these impls may be removed in the future if layout changes make them
invalid. For more information, see the Unsafe Code Guidelines Reference
page on the [layout of packed SIMD vectors][simd-layout].
- **`simd-nightly`**
Enables the `simd` feature and adds support for SIMD types which are only
available on nightly. Since these types are unstable, support for any type
may be removed at any point in the future.
## Security Ethos
Zerocopy is expressly designed for use in security-critical contexts. We
strive to ensure that that zerocopy code is sound under Rust's current
memory model, and *any future memory model*. We ensure this by:
- **...not 'guessing' about Rust's semantics.**
We annotate `unsafe` code with a precise rationale for its soundness that
cites a relevant section of Rust's official documentation. When Rust's
documented semantics are unclear, we work with the Rust Operational
Semantics Team to clarify Rust's documentation.
- **...rigorously testing our implementation.**
We run tests using [Miri], ensuring that zerocopy is sound across a wide
array of supported target platforms of varying endianness and pointer
width, and across both current and experimental memory models of Rust.
- **...formally proving the correctness of our implementation.**
We apply formal verification tools like [Kani][kani] to prove zerocopy's
correctness.
For more information, see our full [soundness policy].
## Relationship to Project Safe Transmute
[Project Safe Transmute] is an official initiative of the Rust Project to
develop language-level support for safer transmutation. The Project consults
with crates like zerocopy to identify aspects of safer transmutation that
would benefit from compiler support, and has developed an [experimental,
compiler-supported analysis][mcp-transmutability] which determines whether,
for a given type, any value of that type may be soundly transmuted into
another type. Once this functionality is sufficiently mature, zerocopy
intends to replace its internal transmutability analysis (implemented by our
custom derives) with the compiler-supported one. This change will likely be
an implementation detail that is invisible to zerocopy's users.
Project Safe Transmute will not replace the need for most of zerocopy's
higher-level abstractions. The experimental compiler analysis is a tool for
checking the soundness of `unsafe` code, not a tool to avoid writing
`unsafe` code altogether. For the foreseeable future, crates like zerocopy
will still be required in order to provide higher-level abstractions on top
of the building block provided by Project Safe Transmute.
## MSRV
See our [MSRV policy].
## Changelog
Zerocopy uses [GitHub Releases].
## Disclaimer
Disclaimer: Zerocopy is not an officially supported Google product.