Expand description
A utility library for more easily writing out structured data in arbitrary binary file formats.
This library is particularly suited for formats that include offsets to other parts of the file contents, or need to specify the size of sub-sections before producing those subsections. It includes a mechaism for labelling particular offsets and then including placeholders for values derived from those offsets which can be updated later once their results are known.
§Example: Write to a vector with little-endian ordering
let mut buf = Vec::<u8>::new();
binbin::write_vec_le(&mut buf, |w| {
let header_start = w.position()? as u32;
let header_len = w.deferred(0 as u32);
w.write(&b"\x7fELF"[..])?;
w.write(1 as u8)?; // 32-bit ELF
w.write(1 as u8)?; // Little-endian ELF
w.write(1 as u8)?; // ELF header version
w.write(0 as u8)?; // ABI
w.skip(8)?;
w.write(1 as u16)?; // Relocatable
w.write(0x28 as u16)?; // ARM instruction set
w.write(1 as u32)?; // ELF version
w.write(0 as u32)?; // no entry point
w.write(0 as u32)?; // no program header table
let section_header_pos = w.write_deferred(0 as u32)?;
w.write(0 as u32)?; // flags
w.write_placeholder(header_len)?;
w.write(0 as u32)?; // size of program header entry (none)
w.write(0 as u32)?; // number of program header entries (none)
let section_header_size = w.write_deferred(0 as u32)?;
let section_header_count = w.write_deferred(0 as u32)?;
let header_end = w.position()? as u32;
w.resolve(header_len, header_end - header_start);
w.write(0 as u32)?; // no string table
w.align(4)?;
let pos = w.position()? as u32;
w.resolve(section_header_pos, pos)?;
// (...and then the rest of an ELF writer...)
Ok(())
})?;
assert_eq!(buf, vec![
0x7f, b'E', b'L', b'F', // magic number
1, 1, 1, 0, // initial header fields
0, 0, 0, 0, 0, 0, 0, 0, // padding
0x01, 0x00, // relocatable
0x28, 0x00, // ARM instruction set
0x01, 0x00, 0x00, 0x00, // ELF version
0x00, 0x00, 0x00, 0x00, // entry point
0x00, 0x00, 0x00, 0x00, // program header table offset
// Section header position was deferred and resolved later
0x40, 0x00, 0x00, 0x00, // section header position
0x00, 0x00, 0x00, 0x00, // flags
// Header length was deferred and resolved later
0x3c, 0x00, 0x00, 0x00, // header length
0x00, 0x00, 0x00, 0x00, // size of program header entry
0x00, 0x00, 0x00, 0x00, // number of program header entries
// Section header entries were deferred but never resolved,
// so they retain their placeholder values.
0x00, 0x00, 0x00, 0x00, // size of section header entry
0x00, 0x00, 0x00, 0x00, // number of section header entries
0x00, 0x00, 0x00, 0x00, // no string table
]);
Modules§
- deferred
- Representation of values to be determined later.
- derive
- Types used with
Writer::derive
. - endian
- Types for representing endianness.
- pack
- Traits for serializing data for
Writer::write
.
Structs§
- Writer
- Wraps a seekable writer with extra functions to conveniently write data in various common binary formats and keep track of labelled offsets to help calculate section sizes and object positions.
Functions§
- write
- Generic equivalent of
write_le
andwrite_be
, with endianness selected by a type parameter. - write_
be - Writes arbitrary binary data to the given writer
w
using the given functionf
, where writes will be big-endian by default. - write_
le - Writes arbitrary binary data to the given writer
w
using the given functionf
, where writes will be little-endian by default. - write_
vec - Generic equivalent of
write_vec_le
andwrite_vec_be
, with endianness selected by a type parameter. - write_
vec_ be - Writes arbitrary binary data into a byte vector using the given
function
f
, writing big-endian by default. - write_
vec_ le - Writes arbitrary binary data into a byte vector using the given
function
f
, writing little-endian by default.