Repository files navigation

Need more out of zerocopy?Submit acustomer request issue!

Fast, safe,compile error. Pick two.

Zerocopy makes zero-cost memory manipulation effortless. We writeunsafeso you don't have to.

Thanks for using zerocopy 0.8! For an overview of what changes from 0.7,check out ourrelease notes, which include a step-by-stepguide for upgrading from 0.7.

Have questions? Need help? Ask the maintainers onGitHub oronDiscord!

Zerocopy provides four derivable traits for zero-cost conversions:

• TryFromBytes indicates that a type may safely be converted fromcertain byte sequences (conditional on runtime checks)
• FromZeros indicates that a sequence of zero bytes represents a validinstance of a type
• FromBytes indicates that a type may safely be converted from anarbitrary byte sequence
• IntoBytes indicates that a type may safely be convertedto a bytesequence

These traits support sized types, slices, andslice DSTs.

Zerocopy provides three derivable marker traits that do not provide anyfunctionality themselves, but are required to call certain methods providedby the conversion traits:

• KnownLayout indicates that zerocopy can reason about certain layoutqualities of a type
• Immutable indicates that a type is free from interior mutability,except by ownership or an exclusive (&mut) borrow
• Unaligned indicates that a type's alignment requirement is 1

You should generally derive these marker traits whenever possible.

Zerocopy provides six macros for safe casting between types:

• (try_[try_transmute])transmute (conditionally) converts a value ofone type to a value of another type of the same size
• (try_[try_transmute_mut])transmute_mut (conditionally) converts amutable reference of one type to a mutable reference of another type ofthe same size
• (try_[try_transmute_ref])transmute_ref (conditionally) converts amutable or immutable reference of one type to an immutable reference ofanother type of the same size

These macros performcompile-time size and alignment checks, meaning thatunconditional casts have zero cost at runtime. Conditional casts do not needto validate size or alignment runtime, but do need to validate contents.

These macros cannot be used in generic contexts. For generic conversions,use the methods defined by theconversion traits.

Zerocopy provides byte-order aware integer types that support theseconversions; see thebyteorder module. These types are especially usefulfor network parsing.

• allocBy default,zerocopy isno_std. When thealloc feature is enabled,thealloc crate is added as a dependency, and some allocation-relatedfunctionality is added.

• stdBy default,zerocopy isno_std. When thestd feature is enabled, thestd crate is added as a dependency (ie,no_std is disabled), andsupport for somestd types is added.std impliesalloc.

• deriveProvides derives for the core marker traits via thezerocopy-derivecrate. These derives are re-exported fromzerocopy, so it is notnecessary to depend onzerocopy-derive directly.

  However, you may experience better compile times if you instead directlydepend on bothzerocopy andzerocopy-derive in yourCargo.toml,since doing so will allow Rust to compile these crates in parallel. To doso, donot enable thederive feature, and list both dependencies inyourCargo.toml with the same leading non-zero version number; e.g:

  [dependencies]zerocopy ="0.X"zerocopy-derive ="0.X"

  To avoid the risk ofduplicate import errors ifone of your dependencies enables zerocopy'sderive feature, importderives asuse zerocopy_derive::* rather than by name (e.g.,use zerocopy_derive::FromBytes).

• simdWhen thesimd feature is enabled,FromZeros,FromBytes, andIntoBytes impls are emitted for all stable SIMD types which exist on thetarget 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 theminvalid. For more information, see the Unsafe Code Guidelines Referencepage on thelayout of packed SIMD vectors.

• simd-nightlyEnables thesimd feature and adds support for SIMD types which are onlyavailable on nightly. Since these types are unstable, support for any typemay be removed at any point in the future.

• float-nightlyAdds support for the unstablef16 andf128 types. These types arenot yet fully implemented and may not be supported on all platforms.

Zerocopy is expressly designed for use in security-critical contexts. Westrive to ensure that that zerocopy code is sound under Rust's currentmemory model, andany future memory model. We ensure this by:

• ...not 'guessing' about Rust's semantics.We annotateunsafe code with a precise rationale for its soundness thatcites a relevant section of Rust's official documentation. When Rust'sdocumented semantics are unclear, we work with the Rust OperationalSemantics Team to clarify Rust's documentation.
• ...rigorously testing our implementation.We run tests usingMiri, ensuring that zerocopy is sound across a widearray of supported target platforms of varying endianness and pointerwidth, and across both current and experimental memory models of Rust.
• ...formally proving the correctness of our implementation.We apply formal verification tools likeKani to prove zerocopy'scorrectness.

For more information, see our fullsoundness policy.

Project Safe Transmute is an official initiative of the Rust Project todevelop language-level support for safer transmutation. The Project consultswith crates like zerocopy to identify aspects of safer transmutation thatwould benefit from compiler support, and has developed anexperimental,compiler-supported analysis which determines whether,for a given type, any value of that type may be soundly transmuted intoanother type. Once this functionality is sufficiently mature, zerocopyintends to replace its internal transmutability analysis (implemented by ourcustom derives) with the compiler-supported one. This change will likely bean implementation detail that is invisible to zerocopy's users.

Project Safe Transmute will not replace the need for most of zerocopy'shigher-level abstractions. The experimental compiler analysis is a tool forchecking the soundness ofunsafe code, not a tool to avoid writingunsafe code altogether. For the foreseeable future, crates like zerocopywill still be required in order to provide higher-level abstractions on topof the building block provided by Project Safe Transmute.

See ourMSRV policy.

Zerocopy usesGitHub Releases.

Zerocopy is maintained by engineers at Google and Amazon with help frommany wonderful contributors. Thank you to everyone who haslent a hand in making Rust a little more secure!

Disclaimer: Zerocopy is not an officially supported Google product.