UNIX/Linux a.out binary file format. More...

#include <aout.h>

Inheritance diagram for AOut::AOutFormat:

Classes
class	AOutOptionCollector

class	Symbol

Public Types
enum	system_type { UNSPECIFIED , LINUX , FREEBSD , NETBSD , DJGPP1 , PDOS386 , EMX }
	The target operating system type for parsing or generating binaries. More...

enum	magic_type { OMAGIC = 0x0107 , NMAGIC = 0x0108 , ZMAGIC = 0x010B , QMAGIC = 0x00CC }
	The low 16 bits of the midmag field, it determines how sections should be loaded into memory, in a system dependent way. More...

enum	word_size_t { WordSize16 = 2 , WordSize32 = 4 }

enum	cpu_type { UNKNOWN , M68K , SPARC , SPARC64 , I386 , AMD64 , ARM , AARCH64 , MIPS , PARISC , PDP11 , NS32K , VAX , ALPHA , SUPERH , SUPERH64 , PPC , PPC64 , M88K , IA64 , OR1K , RISCV }

Public Member Functions
constexpr uint32_t	GetHeaderSize () const
	Retrieves the size of the header for the current settings.

::EndianType	GetEndianType () const
	Returns the default endian type for the currently set CPU.

word_size_t	GetWordSize () const
	Returns the expected word size for the currently set CPU.

uint32_t	GetPageSize () const

uint32_t	GetTextOffset () const

uint32_t	GetTextAddress () const

uint32_t	GetDataOffsetAlign () const

uint32_t	GetDataAddressAlign () const

void	ReadHeader (Linker::Reader &rd)

void	ReadFile (Linker::Reader &rd) override
	Loads file into memory.

offset_t	ImageSize () const override
	Retrieves size of stored data.

void	WriteHeader (Linker::Writer &wr) const

offset_t	WriteFile (Linker::Writer &wr) const override
	Stores data in memory to file.

void	Dump (Dumper::Dumper &dump) const override
	Display file contents in a nice manner.

void	GenerateModule (Linker::Module &module) const override
	Loads the information into a module object, a convenience method when there is a single module generated.

std::vector< Linker::OptionDescription< void > * >	GetLinkerScriptParameterNames () override
	Returns a list of the parameters used in the linker scripts, used for documentation.

std::shared_ptr< Linker::OptionCollector >	GetOptions () override
	Returns object containing a sequence of option fields provided with the -S command line flag.

void	SetOptions (std::map< std::string, std::string > &options) override
	Passes command line parameters as settings over to format object.

void	OnNewSegment (std::shared_ptr< Linker::Segment > segment) override
	Callback function when allocating a new segment When the linker script runs, it creates segments consecutively. Overriding this method permits the output format to handle the allocated segment.

void	CreateDefaultSegments ()

std::unique_ptr< Script::List >	GetScript (Linker::Module &module)

void	Link (Linker::Module &module)

std::shared_ptr< Linker::Segment >	GetCodeSegment ()

std::shared_ptr< Linker::Segment >	GetDataSegment ()

std::shared_ptr< Linker::Segment >	GetBssSegment ()

void	ProcessModule (Linker::Module &module) override
	Processes the module object and initializes format fields.

void	CalculateValues () override
	Intermediate step between processing module and generating output file to set up headers and management sections It is expected that after a module is processed, additional steps are required to evaluate the final values of the fields.

void	GenerateFile (std::string filename, Linker::Module &module) override
	The main function that handles processing, calculating and generating the final image.

std::string	GetDefaultExtension (Linker::Module &module, std::string filename) const override
	Appends a default extension to the filename.

std::string	GetDefaultExtension (Linker::Module &module) const override
	Provides a default filename for the output file.

Public Member Functions inherited from Linker::InputFormat
virtual void	SetupOptions (std::shared_ptr< OutputFormat > format)
	Initializes the reader for linking purposes.

virtual void	ProduceModule (ModuleCollector &linker, Reader &rd, std::string file_name)
	Reads a file and loads the information into a module object.

virtual void	ProduceModule (Module &module, Reader &rd)
	Reads a file and loads the information into a module object, a convenience method when there is a single module generated.

virtual void	GenerateModule (ModuleCollector &linker, std::string file_name, bool is_library=false) const
	Loads the information into a module object.

virtual bool	FormatProvidesSegmentation () const
	Whether the format enables multiple x86 segments.

virtual bool	FormatRequiresDataStreamFix () const
	Whether the generated file might contain bugs that require fixing.

virtual bool	FormatProvidesResources () const
	Whether the format supports resources.

virtual bool	FormatProvidesLibraries () const
	Whether the format enables importing/exporting libraries.

Public Member Functions inherited from Linker::Format
	Format (offset_t file_offset=0)

virtual void	Clear ()
	Resets all fields to their default values, deallocate memory.

offset_t	ImageSize () const override
	Retrieves size of stored data.

offset_t	WriteFile (Writer &wr, offset_t count, offset_t offset=0) const override
	Writes data of non-zero filled sections.

Public Member Functions inherited from Linker::Image
virtual std::shared_ptr< const ActualImage >	AsImage () const
	Retrieves a randomly accessible image.

std::shared_ptr< ActualImage >	AsImage ()
	Retrieves a randomly accessible image.

Public Member Functions inherited from Linker::SegmentManager
void	ClearSegmentManager ()

void	SetLinkScript (std::string script_file, std::map< std::string, std::string > &options) override
	Sets up the linker script and linker parameters.

std::unique_ptr< Script::List >	GetScript (Module &module)
	Compiles the linker script into an internal format.

offset_t	GetCurrentAddress () const
	Retrieves current address pointer.

void	SetCurrentAddress (offset_t address)
	Moves the current address pointer further, and if the current segment already contains data, fill it up to the point.

void	AlignCurrentAddress (offset_t align)
	Aligns current address to alignment, using SetCurrentAddress.

void	SetLatestBase (offset_t address)
	Sets the base of the current section (the value from which offsets are counted from)

void	FinishCurrentSegment ()
	Closes the current segment, sets current_segment to null.

std::shared_ptr< Segment >	AppendSegment (std::string name)
	Terminates the current segment (if there is one), creates a new segment and attaches it to the image.

std::shared_ptr< Segment >	FetchSegment (std::string name)
	Attempts to fetch a segment, returns null if not found.

void	AppendSection (std::shared_ptr< Section > section)
	Adds a new section to the current segment, sets the base to the same as the segment.

void	ProcessScript (std::unique_ptr< Script::List > &directives, Module &module)
	Executes a parsed linker script on a module and collects segments The function OnNewSegment can be defined to handle each newly allocated segment.

void	ProcessAction (std::unique_ptr< Script::Node > &action, Module &module)

void	PostProcessAction (std::unique_ptr< Script::Node > &action, Module &module)

void	ProcessCommand (std::unique_ptr< Script::Node > &command, Module &module)

bool	CheckPredicate (std::unique_ptr< Script::Node > &predicate, std::shared_ptr< Section > section, Module &module)

offset_t	EvaluateExpression (std::unique_ptr< Script::Node > &expression, Module &module)

Public Member Functions inherited from Linker::OutputFormat
virtual bool	AddSupplementaryOutputFormat (std::string subformat)
	If the output format actually drives multiple output formats (resource file, apple double, etc.), specify multiple types, return false if unknown.

virtual std::vector< OptionDescription< void > >	GetMemoryModelNames ()
	Returns a list of the supported memory models, used for documentation.

virtual std::vector< OptionDescription< void > >	GetSpecialSymbolNames ()
	Returns a list of special symbol names recognized by the format, used for documentation.

std::optional< std::string >	FetchOption (std::map< std::string, std::string > &options, std::string name)
	Convenience method to look up option by name.

std::string	FetchOption (std::map< std::string, std::string > &options, std::string name, std::string default_value)
	Convenience method to look up option by name, returning default value if name is missing.

std::optional< offset_t >	FetchIntegerOption (std::map< std::string, std::string > &options, std::string name)
	Convenience method to look up option by name and convert it to integer.

virtual void	SetModel (std::string model)
	Sets the way memory is organized, typically modifying a built-in script.

virtual bool	FormatSupportsSegmentation () const
	Whether the format supports multiple segments.

virtual bool	FormatIs16bit () const
	Whether the format is 16-bit or not.

virtual bool	FormatIsProtectedMode () const
	Whether the format is in protected mode or not (x86 only)

virtual bool	FormatIsLinear () const
	Whether the address space is linear or segmented.

virtual bool	FormatSupportsResources () const
	Whether the format supports resources.

virtual bool	FormatSupportsLibraries () const
	Whether the format supports libraries.

virtual unsigned	FormatAdditionalSectionFlags (std::string section_name) const

Static Public Member Functions
static constexpr magic_type	GetDefaultMagic (system_type system)
	Default magic number associated with the system.

static std::shared_ptr< AOutFormat >	CreateReader (word_size_t word_size, ::EndianType endiantype, system_type system=UNSPECIFIED)

static std::shared_ptr< AOutFormat >	CreateWriter (system_type system, magic_type magic)

static std::shared_ptr< AOutFormat >	CreateWriter (system_type system)

Public Attributes
::EndianType	endiantype = ::UndefinedEndian

system_type	system
	The target operating system, it influences section offset and address choices.

magic_type	magic
	The low 16 bits of the midmag field.

::EndianType	midmag_endiantype
	All fields in the header must appear in native byte order, except for FreeBSD and NetBSD where:

uint16_t	mid_value = 0

uint8_t	flags = 0

word_size_t	word_size = word_size_t(0)
	Number of bytes in a machine word (2 or 4), typically also determines the size of the header (16 or 32 bytes)

cpu_type	cpu = UNKNOWN

uint32_t	code_size = 0

uint32_t	data_size = 0

uint32_t	bss_size = 0

uint32_t	symbol_table_size = 0

uint32_t	entry_address = 0

uint32_t	code_relocation_size = 0

uint32_t	data_relocation_size = 0

std::map< uint32_t, uint32_t >	code_relocations

std::map< uint32_t, uint32_t >	data_relocations

std::shared_ptr< Linker::Image >	code

std::shared_ptr< Linker::Image >	data

std::shared_ptr< Linker::Image >	bss

std::vector< Symbol >	symbols

uint32_t	page_size = 0

Microsoft::MZSimpleStubWriter	stub

Public Attributes inherited from Linker::Format
offset_t	file_offset

Public Attributes inherited from Linker::SegmentManager
offset_t	current_base = 0
	The base address of the current section.

std::vector< std::shared_ptr< Segment > >	segment_vector
	Ordered sequence of segments.

std::map< std::string, std::shared_ptr< Segment > >	segment_map
	Map of segments from their names.

std::shared_ptr< Segment >	current_segment
	Currently processed segment.

std::map< std::string, Location >	linker_parameters
	Parameters that permit customizing the linker script.

std::string	linker_script
	Contents of the linker script.

Static Public Attributes
static constexpr uint16_t	MID_UNKNOWN = 0x000

static constexpr uint16_t	MID_68010 = 0x001

static constexpr uint16_t	MID_68020 = 0x002

static constexpr uint16_t	MID_PC386 = 0x064

static constexpr uint16_t	MID_I386 = 0x086

static constexpr uint16_t	MID_ARM6 = 0x08F

static constexpr uint16_t	MID_MIPS1 = 0x097

static constexpr uint16_t	MID_MIPS2 = 0x098

static constexpr uint16_t	MID_HP200 = 0x0C8

static constexpr uint16_t	MID_HP300 = 0x12C

static constexpr uint16_t	MID_HPUX800 = 0x20B

static constexpr uint16_t	MID_HPUX = 0x20C

static constexpr uint16_t	MID_LINUX_OLDSUN2 = 0x000

static constexpr uint16_t	MID_LINUX_SPARC = 0x003

static constexpr uint16_t	MID_FREEBSD_SPARC = 0x08C

static constexpr uint16_t	MID_NETBSD_M68K = 0x087

static constexpr uint16_t	MID_NETBSD_M68K4K = 0x088

static constexpr uint16_t	MID_NETBSD_NS32532K = 0x089

static constexpr uint16_t	MID_NETBSD_SPARC = 0x08A

static constexpr uint16_t	MID_NETBSD_PMAX = 0x08B

static constexpr uint16_t	MID_NETBSD_VAX1K = 0x08C

static constexpr uint16_t	MID_NETBSD_ALPHA = 0x08D

static constexpr uint16_t	MID_NETBSD_MIPS = 0x08E

static constexpr uint16_t	MID_NETBSD_M680002K = 0x090

static constexpr uint16_t	MID_NETBSD_SH3 = 0x091

static constexpr uint16_t	MID_NETBSD_POWERPC64 = 0x094

static constexpr uint16_t	MID_NETBSD_POWERPC = 0x095

static constexpr uint16_t	MID_NETBSD_VAX = 0x096

static constexpr uint16_t	MID_NETBSD_M88K = 0x099

static constexpr uint16_t	MID_NETBSD_HPPA = 0x09A

static constexpr uint16_t	MID_NETBSD_SH5_64 = 0x09B

static constexpr uint16_t	MID_NETBSD_SPARC64 = 0x09C

static constexpr uint16_t	MID_NETBSD_X86_64 = 0x09D

static constexpr uint16_t	MID_NETBSD_SH5_32 = 0x09E

static constexpr uint16_t	MID_NETBSD_IA64 = 0x09F

static constexpr uint16_t	MID_NETBSD_AARCH64 = 0x0B7

static constexpr uint16_t	MID_NETBSD_OR1K = 0x0B8

static constexpr uint16_t	MID_NETBSD_RISCV = 0x0B9

static constexpr uint16_t	MID_BFD_ARM = 0x067

static std::vector< Linker::OptionDescription< void > * >	ParameterNames

Protected Member Functions
	AOutFormat (system_type system, magic_type magic)

Additional Inherited Members
Protected Attributes inherited from Linker::SegmentManager
offset_t	current_address = 0
	Holds the current address value when there is no current_segment.

bool	current_is_template = false

bool	current_is_template_head = false

offset_t	template_counter = 0

std::string	current_template_name

Detailed Description

UNIX/Linux a.out binary file format.

Introduced in the earliest versions of UNIX, it underwent several incompatible updates, including being extended to 32 bits. At the time of writing, almost all current UNIX platforms use the COFF or ELF format.

Versions:

PDP-7 version (unimplemented)
UNIX v1 version (unimplemented)
16-bit UNIX version (unimplemented)
32-bit UNIX version (first introduced on the VAX)

Variants:

OMAGIC (old magic), the code segment is writable
NMAGIC (new magic), the code segment is pure and can be shared (read-only)
ZMAGIC, demand paged
QMAGIC (TODO)

Platforms:

early Linux (unimplemented) (obsolete)
early DJGPP before version 1.11
early PDOS/386 and PD-Windows (http://pdos.sourceforge.net/) (obsolete)

Member Enumeration Documentation

◆ magic_type

enum AOut::AOutFormat::magic_type

The low 16 bits of the midmag field, it determines how sections should be loaded into memory, in a system dependent way.

Enumerator
OMAGIC	Object file or impure executable: The text, data and bss sections are loaded contiguously.
NMAGIC	Pure executable: The data section starts on a page boundary, making it possible to have a write protected text section.
ZMAGIC	Demand paged executable: Like NMAGIC, the data section starts on a page boundary, but the text section also starts on a page boundary.
QMAGIC	The header is included in the text segment, but the first page is unmapped.

◆ system_type

enum AOut::AOutFormat::system_type

The target operating system type for parsing or generating binaries.

Enumerator
UNSPECIFIED	Treat it as undetermined, intended for object files and early UNIX binaries.
LINUX	Treat it as a Linux a.out binary, used before kernel 5.19 (Linux switched to ELF in 1.2) Linux supported OMAGIC, NMAGIC, ZMAGIC, QMAGIC binaries, the midmag field is in the native byte order and the machine type is stored in bits 16 to 23 of midmag
FREEBSD	Treat it as a FreeBSD a.out binary, used before 3.0. FreeBSD supported OMAGIC, NMAGIC, ZMAGIC, QMAGIC binaries, the midmag field is preferred to be in the little endian byte order and the machine type is stored in bits 16 to 25 of midmag
NETBSD	Treat it as a NetBSD a.out binary, used before 1.5. FreeBSD supported OMAGIC, NMAGIC, ZMAGIC, QMAGIC binaries, the midmag field is preferred to be in the big endian byte order and the machine type is stored in bits 16 to 25 of midmag
DJGPP1	Treat it as a DJGPP a.out binary, used before DJGPP 1.11. Similar to Linux
PDOS386	Treat it as a Public Domain OS a.out, a 32-bit DOS-like operating system (http://pdos.sourceforge.net/) PDOS only supports OMAGIC binaries
EMX	Treat it as an EMX a.out binary, should only be used with EMXAOutFormat.

Member Function Documentation

◆ CalculateValues()

void AOutFormat::CalculateValues ( )

overridevirtual

Intermediate step between processing module and generating output file to set up headers and management sections It is expected that after a module is processed, additional steps are required to evaluate the final values of the fields.

Reimplemented from Linker::OutputFormat.

Reimplemented in EMX::EMXAOutFormat.

◆ Dump()

void AOutFormat::Dump ( Dumper::Dumper & dump ) const

overridevirtual

Display file contents in a nice manner.

Reimplemented from Linker::Format.

Reimplemented in EMX::EMXAOutFormat.

◆ GenerateFile()

void AOutFormat::GenerateFile	(	std::string	filename,
		Linker::Module &	module )

overridevirtual

The main function that handles processing, calculating and generating the final image.

Reimplemented from Linker::OutputFormat.

Reimplemented in EMX::EMXAOutFormat.

◆ GenerateModule()

void AOutFormat::GenerateModule ( Linker::Module & module ) const

overridevirtual

Loads the information into a module object, a convenience method when there is a single module generated.

Reimplemented from Linker::InputFormat.

Reimplemented in EMX::EMXAOutFormat.

◆ GetDefaultExtension() [1/2]

std::string AOutFormat::GetDefaultExtension ( Linker::Module & module ) const

overridevirtual

Provides a default filename for the output file.

Typically a.out or some other extension, such as a.exe.

Reimplemented from Linker::OutputFormat.

Reimplemented in EMX::EMXAOutFormat.

◆ GetDefaultExtension() [2/2]

std::string AOutFormat::GetDefaultExtension	(	Linker::Module &	module,
		std::string	filename ) const

overridevirtual

Appends a default extension to the filename.

A typical behavior would be to append .exe at the end of the filename. The default action is to leave it intact.

Reimplemented from Linker::OutputFormat.

Reimplemented in EMX::EMXAOutFormat.

◆ GetDefaultMagic()

static constexpr magic_type AOut::AOutFormat::GetDefaultMagic ( system_type system )

inlinestaticconstexpr

Default magic number associated with the system.

This information is based on studying the executables included with that software. PDOS/386 uses OMAGIC, whereas DJGPP uses ZMAGIC.

◆ GetLinkerScriptParameterNames()

std::vector< Linker::OptionDescription< void > * > AOutFormat::GetLinkerScriptParameterNames ( )

overridevirtual

Returns a list of the parameters used in the linker scripts, used for documentation.

Reimplemented from Linker::OutputFormat.

Reimplemented in EMX::EMXAOutFormat.

◆ GetOptions()

std::shared_ptr< Linker::OptionCollector > AOutFormat::GetOptions ( )

overridevirtual

Returns object containing a sequence of option fields provided with the -S command line flag.

Reimplemented from Linker::OutputFormat.

Reimplemented in EMX::EMXAOutFormat.

◆ ImageSize()

offset_t AOutFormat::ImageSize ( ) const

overridevirtual

Retrieves size of stored data.

Implements Linker::Image.

Reimplemented in EMX::EMXAOutFormat.

◆ OnNewSegment()

void AOutFormat::OnNewSegment ( std::shared_ptr< Linker::Segment > segment )

overridevirtual

Callback function when allocating a new segment When the linker script runs, it creates segments consecutively. Overriding this method permits the output format to handle the allocated segment.

Reimplemented from Linker::SegmentManager.

Reimplemented in EMX::EMXAOutFormat.

◆ ProcessModule()

void AOutFormat::ProcessModule ( Linker::Module & object )

overridevirtual

Processes the module object and initializes format fields.

Reimplemented from Linker::OutputFormat.

Reimplemented in EMX::EMXAOutFormat.

◆ ReadFile()

void AOutFormat::ReadFile ( Linker::Reader & rd )

overridevirtual

Loads file into memory.

Implements Linker::Format.

Reimplemented in EMX::EMXAOutFormat.

◆ SetOptions()

void AOutFormat::SetOptions ( std::map< std::string, std::string > & options )

overridevirtual

Passes command line parameters as settings over to format object.

Reimplemented from Linker::OutputFormat.

Reimplemented in EMX::EMXAOutFormat.

◆ WriteFile()

offset_t AOutFormat::WriteFile ( Linker::Writer & wr ) const

overridevirtual

Stores data in memory to file.

Implements Linker::Format.

Reimplemented in EMX::EMXAOutFormat.

Member Data Documentation

◆ flags

uint8_t AOut::AOutFormat::flags = 0

Represents the high 8 bits of the midmag field, typically 6 to 8 bits wide

◆ mid_value

uint16_t AOut::AOutFormat::mid_value = 0

Represents a CPU/Machine type field, typically 8 to 10 bits wide

◆ midmag_endiantype

::EndianType AOut::AOutFormat::midmag_endiantype

All fields in the header must appear in native byte order, except for FreeBSD and NetBSD where:

Under FreeBSD, the midmag field is expected to be in little endian byte order, but it recognizes NetBSD headers with a big endian midmag field
Under NetBSD, the midmag field is expected to be in big endian byte order, but if the CPU field is missing, it can be read in little endian byte order

◆ ParameterNames

std::vector< Linker::OptionDescription< void > * > AOutFormat::ParameterNames

static

Initial value:

=
{
    &p_code_base_address,
    &p_data_align,
    &p_code_end_align,
    &p_data_end_align,
    &p_bss_end_align,
}

The documentation for this class was generated from the following files:

src/format/aout.h
src/format/aout.cc

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ magic_type

◆ system_type

Member Function Documentation

◆ CalculateValues()

◆ Dump()

◆ GenerateFile()

◆ GenerateModule()

◆ GetDefaultExtension() [1/2]

◆ GetDefaultExtension() [2/2]

◆ GetDefaultMagic()

◆ GetLinkerScriptParameterNames()

◆ GetOptions()

◆ ImageSize()

◆ OnNewSegment()

◆ ProcessModule()

◆ ReadFile()

◆ SetOptions()

◆ WriteFile()

Member Data Documentation

◆ flags

◆ mid_value

◆ midmag_endiantype

◆ ParameterNames