binlayout
Calculate the size, alignment, field offsets, and padding of binary structures without reading or writing their data. Intended for binary format and protocol implementations, compiler tooling, and guest data models in emulators and VMs.
Host layout and target layout are independent. All byte sizes, offsets,
alignments, and array counts use u64, including on a 32-bit host. There are no
dependencies and no unsafe code. Rust 1.85 or newer is required.
Installation
[]
= "0.1"
The API reference is available with cargo doc --open.
Basic layouts
Layout describes byte geometry. Construction validates alignment, which must
be a nonzero power of two. Size can be zero or an unpadded intermediate size.
use Layout;
let a = new?;
let b = new?;
let = a.extend?;
assert_eq!;
assert_eq!;
assert_eq!;
# Ok::
extend inserts padding before the next field. pad_to_align adds trailing
padding when a record is finished. repeat(count) returns an array layout and
element stride, including trailing padding for every element.
Calculations that exceed u64 return LayoutError::Overflow.
Named structures
use ;
let header = builder
.field
.field
.field
.build?;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
# Ok::
| Byte range | Contents |
|---|---|
| 0 | tag |
| 1–3 | padding |
| 4–7 | length |
| 8–9 | flags |
| 10–11 | tail padding |
Fields retain declaration order. Duplicate names are errors; unknown names
return None. header.layout() can be nested in another structure or repeated
as an array.
For byte-packed wire formats, use .packed(1) on the builder: this header then
has offsets 0, 1, 5, size 7, and alignment 1. A larger power-of-two packing
value caps field alignment at that value. .align(n) imposes a minimum aggregate
alignment. Packing does not alter padding already inside a nested layout.
FieldLayout::layout() preserves the original layout while FieldLayout::align()
reports the effective placement alignment.
Types and targets
Type describes fixed-width unsigned/signed integers, floats, pointers, arrays,
ordered structures, and unions. A target supplies scalar and pointer alignment rules.
use ;
let foo = Struct;
let wasm32 = wasm32;
let x86_64 = x86_64;
let a = wasm32.layout_of?;
let b = x86_64.layout_of?;
assert_eq!;
assert_eq!;
// Use named types when you also need field offsets.
let named = x86_64.struct_layout?;
assert_eq!;
let records = array;
assert_eq!;
assert_eq!;
# Ok::
Custom targets require explicit pointer size and alignment. Scalar alignments default to their byte sizes, and can be overridden individually:
use ;
let target = builder
.pointer_size
.pointer_align
.scalar_alignment
.scalar_alignment
.scalar_alignment
.build?;
let record = Struct;
assert_eq!;
# Ok::
Scalar and pointer sizes must be nonzero multiples of alignment. Signed and
unsigned scalar overrides are independent. For a packed target-specific record,
pass target.layout_of(&ty)? into StructLayout::builder().field(...).
The wasm32 and x86-64 presets cover scalar, pointer, and aggregate layouts; they do not implement complete calling conventions or bit-field rules.
Unions
Unions place every member at offset zero and round the largest member size up to the union alignment. They do not add a tag or discriminant.
use ;
let payload = builder
.field
.field
.build?;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
# Ok::
UnionLayout supports the same .packed(n) and .align(n) builder options as
structures. Type::Union(vec![...]) and target.union_layout([("name", ty), ...])
provide target-dependent union calculations. tail_padding() counts bytes past
the largest member, not unused bytes after a smaller alternative.
Format examples
cargo run --example header: padding and 32/64-bit pointer layouts.cargo run --example elf: ELF32 and ELF64 headers, with every field offset.cargo run --example protocol: a byte-packed tagged union.
no_std
Disable the default std feature:
[]
= { = "0.1", = false }
alloc is still required for names and type/field collections. Basic Layout
arithmetic does not allocate.
License
This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. See LICENSE or https://mozilla.org/MPL/2.0/.