diff options
Diffstat (limited to 'static/freebsd/man5/a.out.5 3.html')
| -rw-r--r-- | static/freebsd/man5/a.out.5 3.html | 354 |
1 files changed, 354 insertions, 0 deletions
diff --git a/static/freebsd/man5/a.out.5 3.html b/static/freebsd/man5/a.out.5 3.html new file mode 100644 index 00000000..f4fb643b --- /dev/null +++ b/static/freebsd/man5/a.out.5 3.html @@ -0,0 +1,354 @@ +<table class="head"> + <tr> + <td class="head-ltitle">A.OUT(5)</td> + <td class="head-vol">File Formats Manual</td> + <td class="head-rtitle">A.OUT(5)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<p class="Pp"><code class="Nm">a.out</code> — <span class="Nd">format of + executable binary files</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><code class="In">#include + <<a class="In">a.out.h</a>></code></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The include file + <code class="In"><<a class="In">a.out.h</a>></code> declares three + structures and several macros. The structures describe the format of + executable machine code files (‘binaries’) on the system.</p> +<p class="Pp">A binary file consists of up to 7 sections. In order, these + sections are:</p> +<dl class="Bl-tag"> + <dt>exec header</dt> + <dd>Contains parameters used by the kernel to load a binary file into memory + and execute it, and by the link editor <a class="Xr">ld(1)</a> to combine + a binary file with other binary files. This section is the only mandatory + one.</dd> + <dt>text segment</dt> + <dd>Contains machine code and related data that are loaded into memory when a + program executes. May be loaded read-only.</dd> + <dt>data segment</dt> + <dd>Contains initialized data; always loaded into writable memory.</dd> + <dt>text relocations</dt> + <dd>Contains records used by the link editor to update pointers in the text + segment when combining binary files.</dd> + <dt>data relocations</dt> + <dd>Like the text relocation section, but for data segment pointers.</dd> + <dt>symbol table</dt> + <dd>Contains records used by the link editor to cross reference the addresses + of named variables and functions (‘symbols’) between binary + files.</dd> + <dt>string table</dt> + <dd>Contains the character strings corresponding to the symbol names.</dd> +</dl> +<p class="Pp">Every binary file begins with an <var class="Fa">exec</var> + structure:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>struct exec { + unsigned long a_midmag; + unsigned long a_text; + unsigned long a_data; + unsigned long a_bss; + unsigned long a_syms; + unsigned long a_entry; + unsigned long a_trsize; + unsigned long a_drsize; +};</pre> +</div> +<p class="Pp">The fields have the following functions:</p> +<dl class="Bl-tag"> + <dt id="N_GETFLAG"><var class="Fa">a_midmag</var></dt> + <dd>This field is stored in host byte-order. It has a number of sub-components + accessed by the macros + <a class="permalink" href="#N_GETFLAG"><code class="Fn">N_GETFLAG</code></a>(), + <code class="Fn">N_GETMID</code>(), and + <code class="Fn">N_GETMAGIC</code>(), and set by the macro + <a class="permalink" href="#N_SETMAGIC"><code class="Fn" id="N_SETMAGIC">N_SETMAGIC</code></a>(). + <p class="Pp" id="N_GETFLAG~2">The macro + <a class="permalink" href="#N_GETFLAG~2"><code class="Fn">N_GETFLAG</code></a>() + returns a few flags:</p> + <dl class="Bl-tag"> + <dt id="EX_DYNAMIC"><a class="permalink" href="#EX_DYNAMIC"><code class="Dv">EX_DYNAMIC</code></a></dt> + <dd>indicates that the executable requires the services of the run-time + link editor.</dd> + <dt id="EX_PIC"><a class="permalink" href="#EX_PIC"><code class="Dv">EX_PIC</code></a></dt> + <dd>indicates that the object contains position independent code. This + flag is set by <a class="Xr">as(1)</a> when given the + ‘-k’ flag and is preserved by <a class="Xr">ld(1)</a> if + necessary.</dd> + </dl> + <p class="Pp">If both EX_DYNAMIC and EX_PIC are set, the object file is a + position independent executable image (e.g. a shared library), which is + to be loaded into the process address space by the run-time link + editor.</p> + <p class="Pp" id="N_GETMID">The macro + <a class="permalink" href="#N_GETMID"><code class="Fn">N_GETMID</code></a>() + returns the machine-id. This indicates which machine(s) the binary is + intended to run on.</p> + <p class="Pp" id="N_GETMAGIC"><a class="permalink" href="#N_GETMAGIC"><code class="Fn">N_GETMAGIC</code></a>() + specifies the magic number, which uniquely identifies binary files and + distinguishes different loading conventions. The field must contain one + of the following values:</p> + <dl class="Bl-tag"> + <dt id="OMAGIC"><a class="permalink" href="#OMAGIC"><code class="Dv">OMAGIC</code></a></dt> + <dd>The text and data segments immediately follow the header and are + contiguous. The kernel loads both text and data segments into writable + memory.</dd> + <dt id="NMAGIC"><a class="permalink" href="#NMAGIC"><code class="Dv">NMAGIC</code></a></dt> + <dd>As with <code class="Dv">OMAGIC</code>, text and data segments + immediately follow the header and are contiguous. However, the kernel + loads the text into read-only memory and loads the data into writable + memory at the next page boundary after the text.</dd> + <dt id="ZMAGIC"><a class="permalink" href="#ZMAGIC"><code class="Dv">ZMAGIC</code></a></dt> + <dd>The kernel loads individual pages on demand from the binary. The + header, text segment and data segment are all padded by the link + editor to a multiple of the page size. Pages that the kernel loads + from the text segment are read-only, while pages from the data segment + are writable.</dd> + </dl> + </dd> + <dt><var class="Fa">a_text</var></dt> + <dd>Contains the size of the text segment in bytes.</dd> + <dt><var class="Fa">a_data</var></dt> + <dd>Contains the size of the data segment in bytes.</dd> + <dt id="bss"><var class="Fa">a_bss</var></dt> + <dd>Contains the number of bytes in the ‘bss segment’ and is + used by the kernel to set the initial break (<a class="Xr">brk(2)</a>) + after the data segment. The kernel loads the program so that this amount + of writable memory appears to follow the data segment and initially reads + as zeroes. (<a class="permalink" href="#bss"><i class="Em">bss</i></a> = + block started by symbol)</dd> + <dt><var class="Fa">a_syms</var></dt> + <dd>Contains the size in bytes of the symbol table section.</dd> + <dt><var class="Fa">a_entry</var></dt> + <dd>Contains the address in memory of the entry point of the program after the + kernel has loaded it; the kernel starts the execution of the program from + the machine instruction at this address.</dd> + <dt><var class="Fa">a_trsize</var></dt> + <dd>Contains the size in bytes of the text relocation table.</dd> + <dt><var class="Fa">a_drsize</var></dt> + <dd>Contains the size in bytes of the data relocation table.</dd> +</dl> +<p class="Pp">The <code class="In"><<a class="In">a.out.h</a>></code> + include file defines several macros which use an <var class="Fa">exec</var> + structure to test consistency or to locate section offsets in the binary + file.</p> +<dl class="Bl-tag"> + <dt id="N_BADMAG"><a class="permalink" href="#N_BADMAG"><code class="Fn">N_BADMAG</code></a>(<var class="Fa">exec</var>)</dt> + <dd>Nonzero if the <var class="Fa">a_magic</var> field does not contain a + recognized value.</dd> + <dt id="N_TXTOFF"><a class="permalink" href="#N_TXTOFF"><code class="Fn">N_TXTOFF</code></a>(<var class="Fa">exec</var>)</dt> + <dd>The byte offset in the binary file of the beginning of the text + segment.</dd> + <dt id="N_SYMOFF"><a class="permalink" href="#N_SYMOFF"><code class="Fn">N_SYMOFF</code></a>(<var class="Fa">exec</var>)</dt> + <dd>The byte offset of the beginning of the symbol table.</dd> + <dt id="N_STROFF"><a class="permalink" href="#N_STROFF"><code class="Fn">N_STROFF</code></a>(<var class="Fa">exec</var>)</dt> + <dd>The byte offset of the beginning of the string table.</dd> +</dl> +<p class="Pp">Relocation records have a standard format which is described by + the <var class="Fa">relocation_info</var> structure:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>struct relocation_info { + int r_address; + unsigned int r_symbolnum : 24, + r_pcrel : 1, + r_length : 2, + r_extern : 1, + r_baserel : 1, + r_jmptable : 1, + r_relative : 1, + r_copy : 1; +};</pre> +</div> +<p class="Pp">The <var class="Fa">relocation_info</var> fields are used as + follows:</p> +<dl class="Bl-tag"> + <dt><var class="Fa">r_address</var></dt> + <dd>Contains the byte offset of a pointer that needs to be link-edited. Text + relocation offsets are reckoned from the start of the text segment, and + data relocation offsets from the start of the data segment. The link + editor adds the value that is already stored at this offset into the new + value that it computes using this relocation record.</dd> + <dt id="not"><var class="Fa">r_symbolnum</var></dt> + <dd>Contains the ordinal number of a symbol structure in the symbol table (it + is <a class="permalink" href="#not"><i class="Em">not</i></a> a byte + offset). After the link editor resolves the absolute address for this + symbol, it adds that address to the pointer that is undergoing relocation. + (If the <var class="Fa">r_extern</var> bit is clear, the situation is + different; see below.)</dd> + <dt><var class="Fa">r_pcrel</var></dt> + <dd>If this is set, the link editor assumes that it is updating a pointer that + is part of a machine code instruction using pc-relative addressing. The + address of the relocated pointer is implicitly added to its value when the + running program uses it.</dd> + <dt><var class="Fa">r_length</var></dt> + <dd>Contains the log base 2 of the length of the pointer in bytes; 0 for + 1-byte displacements, 1 for 2-byte displacements, 2 for 4-byte + displacements.</dd> + <dt><var class="Fa">r_extern</var></dt> + <dd>Set if this relocation requires an external reference; the link editor + must use a symbol address to update the pointer. When the + <var class="Fa">r_extern</var> bit is clear, the relocation is + ‘local’; the link editor updates the pointer to reflect + changes in the load addresses of the various segments, rather than changes + in the value of a symbol (except when <var class="Fa">r_baserel</var> is + also set (see below). In this case, the content of the + <var class="Fa">r_symbolnum</var> field is an <var class="Fa">n_type</var> + value (see below); this type field tells the link editor what segment the + relocated pointer points into.</dd> + <dt><var class="Fa">r_baserel</var></dt> + <dd>If set, the symbol, as identified by the <var class="Fa">r_symbolnum</var> + field, is to be relocated to an offset into the Global Offset Table. At + run-time, the entry in the Global Offset Table at this offset is set to be + the address of the symbol.</dd> + <dt><var class="Fa">r_jmptable</var></dt> + <dd>If set, the symbol, as identified by the <var class="Fa">r_symbolnum</var> + field, is to be relocated to an offset into the Procedure Linkage + Table.</dd> + <dt><var class="Fa">r_relative</var></dt> + <dd>If set, this relocation is relative to the (run-time) load address of the + image this object file is going to be a part of. This type of relocation + only occurs in shared objects.</dd> + <dt><var class="Fa">r_copy</var></dt> + <dd>If set, this relocation record identifies a symbol whose contents should + be copied to the location given in <var class="Fa">r_address</var>. The + copying is done by the run-time link-editor from a suitable data item in a + shared object.</dd> +</dl> +<p class="Pp">Symbols map names to addresses (or more generally, strings to + values). Since the link-editor adjusts addresses, a symbol's name must be + used to stand for its address until an absolute value has been assigned. + Symbols consist of a fixed-length record in the symbol table and a + variable-length name in the string table. The symbol table is an array of + <var class="Fa">nlist</var> structures:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>struct nlist { + union { + const char *n_name; + long n_strx; + } n_un; + unsigned char n_type; + char n_other; + short n_desc; + unsigned long n_value; +};</pre> +</div> +<p class="Pp">The fields are used as follows:</p> +<dl class="Bl-tag"> + <dt><var class="Fa">n_un.n_strx</var></dt> + <dd>Contains a byte offset into the string table for the name of this symbol. + When a program accesses a symbol table with the <a class="Xr">nlist(3)</a> + function, this field is replaced with the + <var class="Fa">n_un.n_name</var> field, which is a pointer to the string + in memory.</dd> + <dt><var class="Fa">n_type</var></dt> + <dd>Used by the link editor to determine how to update the symbol's value. The + <var class="Fa">n_type</var> field is broken down into three sub-fields + using bitmasks. The link editor treats symbols with the + <code class="Dv">N_EXT</code> type bit set as ‘external’ + symbols and permits references to them from other binary files. The + <code class="Dv">N_TYPE</code> mask selects bits of interest to the link + editor: + <dl class="Bl-tag"> + <dt id="N_UNDF"><a class="permalink" href="#N_UNDF"><code class="Dv">N_UNDF</code></a></dt> + <dd>An undefined symbol. The link editor must locate an external symbol + with the same name in another binary file to determine the absolute + value of this symbol. As a special case, if the + <var class="Fa">n_value</var> field is nonzero and no binary file in + the link-edit defines this symbol, the link-editor will resolve this + symbol to an address in the bss segment, reserving an amount of bytes + equal to <var class="Fa">n_value</var>. If this symbol is undefined in + more than one binary file and the binary files do not agree on the + size, the link editor chooses the greatest size found across all + binaries.</dd> + <dt id="N_ABS"><a class="permalink" href="#N_ABS"><code class="Dv">N_ABS</code></a></dt> + <dd>An absolute symbol. The link editor does not update an absolute + symbol.</dd> + <dt id="N_TEXT"><a class="permalink" href="#N_TEXT"><code class="Dv">N_TEXT</code></a></dt> + <dd>A text symbol. This symbol's value is a text address and the link + editor will update it when it merges binary files.</dd> + <dt id="N_DATA"><a class="permalink" href="#N_DATA"><code class="Dv">N_DATA</code></a></dt> + <dd>A data symbol; similar to <code class="Dv">N_TEXT</code> but for data + addresses. The values for text and data symbols are not file offsets + but addresses; to recover the file offsets, it is necessary to + identify the loaded address of the beginning of the corresponding + section and subtract it, then add the offset of the section.</dd> + <dt id="N_BSS"><a class="permalink" href="#N_BSS"><code class="Dv">N_BSS</code></a></dt> + <dd>A bss symbol; like text or data symbols but has no corresponding + offset in the binary file.</dd> + <dt id="N_FN"><a class="permalink" href="#N_FN"><code class="Dv">N_FN</code></a></dt> + <dd>A filename symbol. The link editor inserts this symbol before the + other symbols from a binary file when merging binary files. The name + of the symbol is the filename given to the link editor, and its value + is the first text address from that binary file. Filename symbols are + not needed for link-editing or loading, but are useful for + debuggers.</dd> + </dl> + <p class="Pp">The <code class="Dv">N_STAB</code> mask selects bits of + interest to symbolic debuggers such as <a class="Xr">gdb(1)</a> + (<span class="Pa">ports/devel/gdb</span>); the values are described in + <a class="Xr">stab(5)</a>.</p> + </dd> + <dt><var class="Fa">n_other</var></dt> + <dd>This field provides information on the nature of the symbol independent of + the symbol's location in terms of segments as determined by the + <var class="Fa">n_type</var> field. Currently, the lower 4 bits of the + <var class="Fa">n_other</var> field hold one of two values: + <code class="Dv">AUX_FUNC</code> and <code class="Dv">AUX_OBJECT</code> + (see <code class="In"><<a class="In">link.h</a>></code> for their + definitions). <code class="Dv">AUX_FUNC</code> associates the symbol with + a callable function, while <code class="Dv">AUX_OBJECT</code> associates + the symbol with data, irrespective of their locations in either the text + or the data segment. This field is intended to be used by + <a class="Xr">ld(1)</a> for the construction of dynamic executables.</dd> + <dt><var class="Fa">n_desc</var></dt> + <dd>Reserved for use by debuggers; passed untouched by the link editor. + Different debuggers use this field for different purposes.</dd> + <dt><var class="Fa">n_value</var></dt> + <dd>Contains the value of the symbol. For text, data and bss symbols, this is + an address; for other symbols (such as debugger symbols), the value may be + arbitrary.</dd> +</dl> +<p class="Pp" id="unsigned">The string table consists of an + <a class="permalink" href="#unsigned"><i class="Em">unsigned long</i></a> + length followed by null-terminated symbol strings. The length represents the + size of the entire table in bytes, so its minimum value (or the offset of + the first string) is always 4 on 32-bit machines.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<p class="Pp"><a class="Xr">as(1)</a>, <a class="Xr">gdb(1)</a> + (<span class="Pa">ports/devel/gdb</span>), <a class="Xr">ld(1)</a>, + <a class="Xr">brk(2)</a>, <a class="Xr">execve(2)</a>, + <a class="Xr">nlist(3)</a>, <a class="Xr">core(5)</a>, + <a class="Xr">elf(5)</a>, <a class="Xr">link(5)</a>, + <a class="Xr">stab(5)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="In"><<a class="In">a.out.h</a>></code> + include file appeared in <span class="Ux">Version 7 AT&T + UNIX</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> +<p class="Pp">Since not all of the supported architectures use the + <var class="Fa">a_midmag</var> field, it can be difficult to determine what + architecture a binary will execute on without examining its actual machine + code. Even with a machine identifier, the byte order of the + <var class="Fa">exec</var> header is machine-dependent.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">June 10, 2010</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |