pub struct Writer<'a> { /* private fields */ }
Expand description
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§
source§impl<'a> Writer<'a>
impl<'a> Writer<'a>
sourcepub fn new(buffer: &'a mut dyn WritableBuffer) -> Self
pub fn new(buffer: &'a mut dyn WritableBuffer) -> Self
Create a new Writer
.
sourcepub fn reserved_len(&self) -> usize
pub fn reserved_len(&self) -> usize
Return the current file length that has been reserved.
sourcepub fn reserve(&mut self, len: usize, align_start: usize) -> u32
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.
sourcepub fn write_align(&mut self, align_start: usize)
pub fn write_align(&mut self, align_start: usize)
Write alignment padding bytes.
sourcepub fn reserve_until(&mut self, offset: usize)
pub fn reserve_until(&mut self, offset: usize)
Reserve the file range up to the given file offset.
sourcepub fn reserve_file_header(&mut self)
pub fn reserve_file_header(&mut self)
Reserve the range for the file header.
This must be at the start of the file.
sourcepub fn write_file_header(&mut self, header: FileHeader) -> Result<()>
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.
sourcepub fn reserve_section_headers(&mut self, section_num: u16)
pub fn reserve_section_headers(&mut self, section_num: u16)
Reserve the range for the section headers.
sourcepub fn write_section_header(&mut self, section: SectionHeader)
pub fn write_section_header(&mut self, section: SectionHeader)
Write a section header.
sourcepub fn reserve_section(&mut self, len: usize) -> u32
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.
sourcepub fn write_section_align(&mut self)
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.
sourcepub fn write_section(&mut self, data: &[u8])
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.
sourcepub fn write_section_zeroes(&mut self, len: usize)
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.
sourcepub fn reserve_relocations(&mut self, count: usize) -> u32
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.
sourcepub fn write_relocations_count(&mut self, count: usize)
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.
sourcepub fn write_relocation(&mut self, reloc: Relocation)
pub fn write_relocation(&mut self, reloc: Relocation)
Write a relocation.
sourcepub fn reserve_symbol_index(&mut self) -> u32
pub fn reserve_symbol_index(&mut self) -> u32
Reserve a symbol table entry.
This must be called before Self::reserve_symtab_strtab
.
sourcepub fn reserve_symbol_indices(&mut self, count: u32)
pub fn reserve_symbol_indices(&mut self, count: u32)
Reserve a number of symbol table entries.
sourcepub fn write_symbol(&mut self, symbol: Symbol)
pub fn write_symbol(&mut self, symbol: Symbol)
Write a symbol table entry.
sourcepub fn reserve_aux_file_name(&mut self, name: &[u8]) -> u8
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
.
sourcepub fn write_aux_file_name(&mut self, name: &[u8], aux_count: u8)
pub fn write_aux_file_name(&mut self, name: &[u8], aux_count: u8)
Write auxiliary symbols for a file name.
sourcepub fn reserve_aux_section(&mut self) -> u8
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
.
sourcepub fn write_aux_section(&mut self, section: AuxSymbolSection)
pub fn write_aux_section(&mut self, section: AuxSymbolSection)
Write an auxiliary symbol for a section.
sourcepub fn symbol_count(&self) -> u32
pub fn symbol_count(&self) -> u32
Return the number of reserved symbol table entries.
sourcepub fn add_string(&mut self, name: &'a [u8]) -> StringId
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
.
sourcepub fn add_name(&mut self, name: &'a [u8]) -> Name
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
.
sourcepub fn reserve_symtab_strtab(&mut self)
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.
sourcepub fn write_strtab(&mut self)
pub fn write_strtab(&mut self)
Write the string table.