Class PEFile

Namespace

AsmResolver.PE.File

Assembly

AsmResolver.PE.File.dll

Models a file using the portable executable (PE) file format. It provides access to various PE headers, as well as the raw contents of each section present in the file.

public class PEFile : ISegmentReferenceFactory, IOffsetConverter

Inheritance

object

PEFile

Implements

ISegmentReferenceFactory

IOffsetConverter

Derived

SerializedPEFile

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

PEFile()

Creates a new empty portable executable file.

public PEFile()

PEFile(DosHeader, FileHeader, OptionalHeader)

Creates a new portable executable file.

public PEFile(DosHeader dosHeader, FileHeader fileHeader, OptionalHeader optionalHeader)

Parameters

dosHeader DosHeader

The DOS header to add.

fileHeader FileHeader

The COFF header to add.

optionalHeader OptionalHeader

The optional header to add.

Fields

ValidPESignature

Indicates a valid NT header signature.

public const uint ValidPESignature = 17744

Field Value

uint

Properties

DosHeader

Gets or sets the DOS header of the PE file.

public DosHeader DosHeader { get; set; }

Property Value

DosHeader

EofData

Gets or sets the data appended to the end of the file (EoF), if available.

public ISegment? EofData { get; set; }

Property Value

ISegment

ExtraSectionData

Gets or sets the padding data in between the last section header and the first section.

public ISegment? ExtraSectionData { get; set; }

Property Value

ISegment

FileHeader

Gets or sets the COFF file header of the portable executable (PE) file.

public FileHeader FileHeader { get; set; }

Property Value

FileHeader

FilePath

When this PE file was read from the disk, gets the file path to the PE file.

public string? FilePath { get; protected set; }

Property Value

string

MappingMode

Gets a value indicating the mapping mode of the PE file. If the PE file is in its mapped form, then every offset of all segments in the PE file will be equal to the physical memory address. If the file is in its unmapped form, the offsets will be equal to the file offset.

public PEMappingMode MappingMode { get; protected set; }

Property Value

PEMappingMode

OptionalHeader

Gets or sets the optional header of the portable executable (PE) file.

public OptionalHeader OptionalHeader { get; set; }

Property Value

OptionalHeader

Sections

Gets a collection of sections present in the portable executable (PE) file.

public IList<PESection> Sections { get; }

Property Value

IList<PESection>

Methods

AlignDataDirectoryEntries(IList<SectionHeader>)

Aligns all data directories' virtual address according to the section header's ones.

public void AlignDataDirectoryEntries(IList<SectionHeader> oldHeaders)

Parameters

oldHeaders IList<SectionHeader>

AlignSections()

Aligns all sections according to the file and section alignment properties in the optional header.

public void AlignSections()

CreateDataDirectoryReader(DataDirectory)

Obtains a reader that spans the provided data directory.

public BinaryStreamReader CreateDataDirectoryReader(DataDirectory dataDirectory)

Parameters

dataDirectory DataDirectory

The data directory to read.

Returns

BinaryStreamReader

The reader.

CreateReaderAtFileOffset(uint)

Creates a new reader at the provided file offset.

public BinaryStreamReader CreateReaderAtFileOffset(uint fileOffset)

Parameters

fileOffset uint

The file offset to start reading at.

Returns

BinaryStreamReader

The reader.

CreateReaderAtFileOffset(uint, uint)

Creates a new reader of a chunk of data at the provided file offset.

public BinaryStreamReader CreateReaderAtFileOffset(uint fileOffset, uint size)

Parameters

fileOffset uint

The file offset to start reading at.

size uint

The number of bytes in the chunk.

Returns

BinaryStreamReader

The reader.

CreateReaderAtRva(uint)

Creates a new reader at the provided virtual address.

public BinaryStreamReader CreateReaderAtRva(uint rva)

Parameters

rva uint

The virtual address to start reading at.

Returns

BinaryStreamReader

The reader.

CreateReaderAtRva(uint, uint)

Creates a new reader of a chunk of data at the provided virtual address.

public BinaryStreamReader CreateReaderAtRva(uint rva, uint size)

Parameters

rva uint

The virtual address to start reading at.

size uint

The number of bytes in the chunk.

Returns

BinaryStreamReader

The reader.

FileOffsetToRva(ulong)

Converts a file offset to the virtual address when it is loaded into memory.

public uint FileOffsetToRva(ulong fileOffset)

Parameters

fileOffset ulong

The file offset to convert.

Returns

uint

The virtual address, relative to the image base.

Exceptions

ArgumentOutOfRangeException

Occurs when the file offset falls outside of the range of the convertible file offsets.

FromBytes(byte[])

Reads an unmapped PE file from memory.

public static PEFile FromBytes(byte[] raw)

Parameters

raw byte[]

The raw bytes representing the contents of the PE file to read.

Returns

PEFile

The PE file that was read.

Exceptions

BadImageFormatException

Occurs when the file does not follow the PE file format.

FromDataSource(IDataSource, PEMappingMode)

Reads a PE file from the provided data source.

public static PEFile FromDataSource(IDataSource dataSource, PEMappingMode mode = PEMappingMode.Unmapped)

Parameters

dataSource IDataSource

The data source to read from.

mode PEMappingMode

Indicates how the input PE file is mapped.

Returns

PEFile

The PE file that was read.

Exceptions

BadImageFormatException

Occurs when the file does not follow the PE file format.

FromFile(IInputFile)

Reads an unmapped PE file.

public static PEFile FromFile(IInputFile file)

Parameters

file IInputFile

The file representing the PE.

Returns

PEFile

The PE file that was read.

Exceptions

BadImageFormatException

Occurs when the file does not follow the PE file format.

FromFile(string)

Reads an unmapped PE file from the disk.

public static PEFile FromFile(string path)

Parameters

path string

The file path to the PE file.

Returns

PEFile

The PE file that was read.

Exceptions

BadImageFormatException

Occurs when the file does not follow the PE file format.

FromModuleBaseAddress(nint)

Reads a mapped PE file starting at the provided module base address (HINSTANCE).

public static PEFile FromModuleBaseAddress(nint hInstance)

Parameters

hInstance nint

The HINSTANCE or base address of the module.

Returns

PEFile

The PE file that was read.

Exceptions

BadImageFormatException

Occurs when the file does not follow the PE file format.

FromModuleBaseAddress(nint, PEMappingMode)

Reads a PE file starting at the provided module base address (HINSTANCE).

public static PEFile FromModuleBaseAddress(nint hInstance, PEMappingMode mode)

Parameters

hInstance nint

The HINSTANCE or base address of the module.

mode PEMappingMode

Indicates how the input PE file is mapped.

Returns

PEFile

The PE file that was read.

Exceptions

BadImageFormatException

Occurs when the file does not follow the PE file format.

FromReader(in BinaryStreamReader, PEMappingMode)

Reads a PE file from the provided input stream.

public static PEFile FromReader(in BinaryStreamReader reader, PEMappingMode mode = PEMappingMode.Unmapped)

Parameters

reader BinaryStreamReader

The input stream to read from.

mode PEMappingMode

Indicates how the input PE file is mapped.

Returns

PEFile

The PE file that was read.

Exceptions

BadImageFormatException

Occurs when the file does not follow the PE file format.

FromStream(Stream)

Reads an unmapped PE file from memory.

public static PEFile FromStream(Stream raw)

Parameters

raw Stream

The raw stream representing the contents of the PE file to read.

Returns

PEFile

The PE file that was read.

Exceptions

BadImageFormatException

Occurs when the file does not follow the PE file format.

GetEofData()

Obtains any data appended to the end of the file (EoF).

protected virtual ISegment? GetEofData()

Returns

ISegment

The extra data.

Remarks

This method is called upon the initialization of the EofData property.

GetExtraSectionData()

Obtains the padding data in between the last section header and the first section.

protected virtual ISegment? GetExtraSectionData()

Returns

ISegment

The extra padding data.

Remarks

This method is called upon the initialization of the ExtraSectionData property.

GetReferenceToRva(uint)

Resolves the provided virtual address to a segment reference.

public ISegmentReference GetReferenceToRva(uint rva)

Parameters

rva uint

The virtual address of the segment.

Returns

ISegmentReference

The reference to the segment.

GetSectionContainingOffset(ulong)

Finds the section containing the provided file offset.

public PESection GetSectionContainingOffset(ulong fileOffset)

Parameters

fileOffset ulong

The file offset.

Returns

PESection

The section containing the file offset.

Exceptions

ArgumentOutOfRangeException

Occurs when the file offset does not fall within any of the sections.

GetSectionContainingRva(uint)

Finds the section containing the provided virtual address.

public PESection GetSectionContainingRva(uint rva)

Parameters

rva uint

The virtual address.

Returns

PESection

The section containing the virtual address.

Exceptions

ArgumentOutOfRangeException

Occurs when the virtual address does not fall within any of the sections.

GetSections()

Obtains the sections in the portable executable file.

protected virtual IList<PESection> GetSections()

Returns

IList<PESection>

The section.

Remarks

This method is called upon the initialization of the Sections property.

RvaToFileOffset(uint)

Converts a virtual address to the physical file offset.

public ulong RvaToFileOffset(uint rva)

Parameters

rva uint

The virtual address, relative to the image base, to convert.

Returns

ulong

The file offset.

Exceptions

ArgumentOutOfRangeException

Occurs when the virtual address falls outside of the range of the convertible addresses.

TryCreateDataDirectoryReader(DataDirectory, out BinaryStreamReader)

Attempts to create a reader that spans the provided data directory.

public bool TryCreateDataDirectoryReader(DataDirectory dataDirectory, out BinaryStreamReader reader)

Parameters

dataDirectory DataDirectory

The data directory to read.

reader BinaryStreamReader

The reader that was created.

Returns

bool

true if the reader was created successfully, false otherwise.

TryCreateReaderAtFileOffset(uint, out BinaryStreamReader)

Attempts to create a new reader at the provided file offset.

public bool TryCreateReaderAtFileOffset(uint fileOffset, out BinaryStreamReader reader)

Parameters

fileOffset uint

The file offset to start reading at.

reader BinaryStreamReader

The reader that was created.

Returns

bool

true if the reader was created successfully, false otherwise.

TryCreateReaderAtFileOffset(uint, uint, out BinaryStreamReader)

Attempts to create a new reader of a chunk of data at the provided file offset.

public bool TryCreateReaderAtFileOffset(uint fileOffset, uint size, out BinaryStreamReader reader)

Parameters

fileOffset uint

The file offset to start reading at.

size uint

The number of bytes in the chunk.

reader BinaryStreamReader

The reader that was created.

Returns

bool

true if the reader was created successfully, false otherwise.

TryCreateReaderAtRva(uint, out BinaryStreamReader)

Attempts to create a new reader at the provided virtual address.

public bool TryCreateReaderAtRva(uint rva, out BinaryStreamReader reader)

Parameters

rva uint

The virtual address to start reading at.

reader BinaryStreamReader

The reader that was created.

Returns

bool

true if the reader was created successfully, false otherwise.

TryCreateReaderAtRva(uint, uint, out BinaryStreamReader)

Attempts to create a new reader of a chunk of data at the provided virtual address.

public bool TryCreateReaderAtRva(uint rva, uint size, out BinaryStreamReader reader)

Parameters

rva uint

The virtual address to start reading at.

size uint

The number of bytes in the chunk.

reader BinaryStreamReader

The reader that was created.

Returns

bool

true if the reader was created successfully, false otherwise.

TryGetSectionContainingOffset(ulong, out PESection?)

Attempts to find the section containing the provided file offset.

public bool TryGetSectionContainingOffset(ulong fileOffset, out PESection? section)

Parameters

fileOffset ulong

The file offset.

section PESection

The section that was found.

Returns

bool

true if the section was found, false otherwise.

TryGetSectionContainingRva(uint, out PESection?)

Attempts to find the section containing the provided virtual address.

public bool TryGetSectionContainingRva(uint rva, out PESection? section)

Parameters

rva uint

The virtual address.

section PESection

The section that was found.

Returns

bool

true if the section was found, false otherwise.

UpdateHeaders()

Recomputes file offsets and sizes in the file, optional and section headers.

public void UpdateHeaders()

Remarks

Affected fields in the file header include:

• SizeOfOptionalHeader

Affected fields in the optional header include:

• SizeOfHeadersSizeOfImageData directories

Affected fields in the section header include:

• VirtualAddressVirtualSizePointerToRawDataSizeOfRawData

Write(BinaryStreamWriter)

Writes the PE file to the provided output stream.

public void Write(BinaryStreamWriter writer)

Parameters

writer BinaryStreamWriter

The output stream to write to.

Write(Stream)

Writes the PE file to the provided output stream.

public void Write(Stream stream)

Parameters

stream Stream

The output stream to write to.

Write(string)

Writes the PE file to a file on the disk.

public void Write(string filePath)

Parameters

filePath string

The path of the file.