Struct object::write::coff::Writer

pub struct Writer<'a> { /* private fields */ }

A helper for writing COFF files.

Writing uses a two phase approach. The first phase builds up all of the information that may need to be known ahead of time:

• build string table
• reserve section indices
• reserve symbol indices
• reserve file ranges for headers and sections

Some of the information has ordering requirements. For example, strings must be added to the string table before reserving the file range for the string table. There are debug asserts to check some of these requirements.

The second phase writes everything out in order. Thus the caller must ensure writing is in the same order that file ranges were reserved. There are debug asserts to assist with checking this.

Implementations

impl<'a> Writer<'a>

pub fn new(buffer: &'a mut dyn WritableBuffer) -> Self

Create a new Writer.

pub fn reserved_len(&self) -> usize

Return the current file length that has been reserved.

pub fn len(&self) -> usize

Return the current file length that has been written.

pub fn reserve(&mut self, len: usize, align_start: usize) -> u32

Reserve a file range with the given size and starting alignment.

Returns the aligned offset of the start of the range.

align_start must be a power of two.

pub fn write_align(&mut self, align_start: usize)

Write alignment padding bytes.

pub fn write(&mut self, data: &[u8])

Write data.

pub fn reserve_until(&mut self, offset: usize)

Reserve the file range up to the given file offset.

pub fn pad_until(&mut self, offset: usize)

Write padding up to the given file offset.

pub fn reserve_file_header(&mut self)

Reserve the range for the file header.

This must be at the start of the file.

pub fn write_file_header(&mut self, header: FileHeader) -> Result<()>

Write the file header.

This must be at the start of the file.

Fields that can be derived from known information are automatically set by this function.

pub fn reserve_section_headers(&mut self, section_num: u16)

Reserve the range for the section headers.

pub fn write_section_header(&mut self, section: SectionHeader)

Write a section header.

pub fn reserve_section(&mut self, len: usize) -> u32

Reserve the range for the section data.

Returns the aligned offset of the start of the range. Does nothing and returns 0 if the length is zero.

pub fn write_section_align(&mut self)

Write the alignment bytes prior to section data.

This is unneeded if you are using write_section or write_section_zeroes for the data.

pub fn write_section(&mut self, data: &[u8])

Write the section data.

Writes alignment bytes prior to the data. Does nothing if the data is empty.

pub fn write_section_zeroes(&mut self, len: usize)

Write the section data using zero bytes.

Writes alignment bytes prior to the data. Does nothing if the length is zero.

pub fn reserve_relocations(&mut self, count: usize) -> u32

Reserve a file range for the given number of relocations.

This will automatically reserve an extra relocation if there are more than 0xffff.

Returns the offset of the range. Does nothing and returns 0 if the count is zero.

pub fn write_relocations_count(&mut self, count: usize)

Write a relocation containing the count if required.

This should be called before writing the first relocation for a section.

pub fn write_relocation(&mut self, reloc: Relocation)

Write a relocation.

pub fn reserve_symbol_index(&mut self) -> u32

Reserve a symbol table entry.

This must be called before Self::reserve_symtab_strtab.

pub fn reserve_symbol_indices(&mut self, count: u32)

Reserve a number of symbol table entries.

pub fn write_symbol(&mut self, symbol: Symbol)

Write a symbol table entry.

pub fn reserve_aux_file_name(&mut self, name: &[u8]) -> u8

Reserve auxiliary symbols for a file name.

Returns the number of auxiliary symbols required.

This must be called before Self::reserve_symtab_strtab.

pub fn write_aux_file_name(&mut self, name: &[u8], aux_count: u8)

Write auxiliary symbols for a file name.

pub fn reserve_aux_section(&mut self) -> u8

Reserve an auxiliary symbol for a section.

Returns the number of auxiliary symbols required.

This must be called before Self::reserve_symtab_strtab.

pub fn write_aux_section(&mut self, section: AuxSymbolSection)

Write an auxiliary symbol for a section.

pub fn symbol_count(&self) -> u32

Return the number of reserved symbol table entries.

pub fn add_string(&mut self, name: &'a [u8]) -> StringId

Add a string to the string table.

This must be called before Self::reserve_symtab_strtab.

pub fn add_name(&mut self, name: &'a [u8]) -> Name

Add a section or symbol name to the string table if required.

This must be called before Self::reserve_symtab_strtab.

pub fn reserve_symtab_strtab(&mut self)

Reserve the range for the symbol table and string table.

This must be called after functions that reserve symbol indices or add strings.

pub fn write_strtab(&mut self)

Write the string table.