share/man/man5/a.out.5

   1 .\" Copyright (c) 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This manual page is derived from documentation contributed to Berkeley by
   5 .\" Donn Seeley at UUNET Technologies, Inc.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. Neither the name of the University nor the names of its contributors
  16 .\"    may be used to endorse or promote products derived from this software
  17 .\"    without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .Dd June 10, 2010
  32 .Dt A.OUT 5
  33 .Os
  34 .Sh NAME
  35 .Nm a.out
  36 .Nd format of executable binary files
  37 .Sh SYNOPSIS
  38 .In a.out.h
  39 .Sh DESCRIPTION
  40 The include file
  41 .In a.out.h
  42 declares three structures and several macros.
  43 The structures describe the format of
  44 executable machine code files
  45 .Pq Sq binaries
  46 on the system.
  47 .Pp
  48 A binary file consists of up to 7 sections.
  49 In order, these sections are:
  50 .Bl -tag -width "text relocations"
  51 .It exec header
  52 Contains parameters used by the kernel
  53 to load a binary file into memory and execute it,
  54 and by the link editor
  55 .Xr ld 1
  56 to combine a binary file with other binary files.
  57 This section is the only mandatory one.
  58 .It text segment
  59 Contains machine code and related data
  60 that are loaded into memory when a program executes.
  61 May be loaded read-only.
  62 .It data segment
  63 Contains initialized data; always loaded into writable memory.
  64 .It text relocations
  65 Contains records used by the link editor
  66 to update pointers in the text segment when combining binary files.
  67 .It data relocations
  68 Like the text relocation section, but for data segment pointers.
  69 .It symbol table
  70 Contains records used by the link editor
  71 to cross reference the addresses of named variables and functions
  72 .Pq Sq symbols
  73 between binary files.
  74 .It string table
  75 Contains the character strings corresponding to the symbol names.
  76 .El
  77 .Pp
  78 Every binary file begins with an
  79 .Fa exec
  80 structure:
  81 .Bd -literal -offset indent
  82 struct exec {
  83         unsigned long   a_midmag;
  84         unsigned long   a_text;
  85         unsigned long   a_data;
  86         unsigned long   a_bss;
  87         unsigned long   a_syms;
  88         unsigned long   a_entry;
  89         unsigned long   a_trsize;
  90         unsigned long   a_drsize;
  91 };
  92 .Ed
  93 .Pp
  94 The fields have the following functions:
  95 .Bl -tag -width a_trsize
  96 .It Fa a_midmag
  97 This field is stored in host byte-order.
  98 It has a number of sub-components accessed by the macros
  99 .Fn N_GETFLAG ,
 100 .Fn N_GETMID ,
 101 and
 102 .Fn N_GETMAGIC ,
 103 and set by the macro
 104 .Fn N_SETMAGIC .
 105 .Pp
 106 The macro
 107 .Fn N_GETFLAG
 108 returns a few flags:
 109 .Bl -tag -width EX_DYNAMIC
 110 .It Dv EX_DYNAMIC
 111 indicates that the executable requires the services of the run-time link editor.
 112 .It Dv EX_PIC
 113 indicates that the object contains position independent code.
 114 This flag is
 115 set by
 116 .Xr as 1
 117 when given the
 118 .Sq -k
 119 flag and is preserved by
 120 .Xr ld 1
 121 if necessary.
 122 .El
 123 .Pp
 124 If both EX_DYNAMIC and EX_PIC are set, the object file is a position independent
 125 executable image (e.g.\& a shared library), which is to be loaded into the
 126 process address space by the run-time link editor.
 127 .Pp
 128 The macro
 129 .Fn N_GETMID
 130 returns the machine-id.
 131 This indicates which machine(s) the binary is intended to run on.
 132 .Pp
 133 .Fn N_GETMAGIC
 134 specifies the magic number, which uniquely identifies binary files
 135 and distinguishes different loading conventions.
 136 The field must contain one of the following values:
 137 .Bl -tag -width ZMAGIC
 138 .It Dv OMAGIC
 139 The text and data segments immediately follow the header
 140 and are contiguous.
 141 The kernel loads both text and data segments into writable memory.
 142 .It Dv NMAGIC
 143 As with
 144 .Dv OMAGIC ,
 145 text and data segments immediately follow the header and are contiguous.
 146 However, the kernel loads the text into read-only memory
 147 and loads the data into writable memory at the next
 148 page boundary after the text.
 149 .It Dv ZMAGIC
 150 The kernel loads individual pages on demand from the binary.
 151 The header, text segment and data segment are all
 152 padded by the link editor to a multiple of the page size.
 153 Pages that the kernel loads from the text segment are read-only,
 154 while pages from the data segment are writable.
 155 .El
 156 .It Fa a_text
 157 Contains the size of the text segment in bytes.
 158 .It Fa a_data
 159 Contains the size of the data segment in bytes.
 160 .It Fa a_bss
 161 Contains the number of bytes in the
 162 .Sq bss segment
 163 and is used by the kernel to set the initial break
 164 .Pq Xr brk 2
 165 after the data segment.
 166 The kernel loads the program so that this amount of writable memory
 167 appears to follow the data segment and initially reads as zeroes.
 168 .Em ( bss
 169 = block started by symbol)
 170 .It Fa a_syms
 171 Contains the size in bytes of the symbol table section.
 172 .It Fa a_entry
 173 Contains the address in memory of the entry point
 174 of the program after the kernel has loaded it;
 175 the kernel starts the execution of the program
 176 from the machine instruction at this address.
 177 .It Fa a_trsize
 178 Contains the size in bytes of the text relocation table.
 179 .It Fa a_drsize
 180 Contains the size in bytes of the data relocation table.
 181 .El
 182 .Pp
 183 The
 184 .In a.out.h
 185 include file defines several macros which use an
 186 .Fa exec
 187 structure to test consistency or to locate section offsets in the binary file.
 188 .Bl -tag -width N_BADMAG(exec)
 189 .It Fn N_BADMAG exec
 190 Nonzero if the
 191 .Fa a_magic
 192 field does not contain a recognized value.
 193 .It Fn N_TXTOFF exec
 194 The byte offset in the binary file of the beginning of the text segment.
 195 .It Fn N_SYMOFF exec
 196 The byte offset of the beginning of the symbol table.
 197 .It Fn N_STROFF exec
 198 The byte offset of the beginning of the string table.
 199 .El
 200 .Pp
 201 Relocation records have a standard format which
 202 is described by the
 203 .Fa relocation_info
 204 structure:
 205 .Bd -literal -offset indent
 206 struct relocation_info {
 207         int             r_address;
 208         unsigned int    r_symbolnum : 24,
 209                         r_pcrel : 1,
 210                         r_length : 2,
 211                         r_extern : 1,
 212                         r_baserel : 1,
 213                         r_jmptable : 1,
 214                         r_relative : 1,
 215                         r_copy : 1;
 216 };
 217 .Ed
 218 .Pp
 219 The
 220 .Fa relocation_info
 221 fields are used as follows:
 222 .Bl -tag -width r_symbolnum
 223 .It Fa r_address
 224 Contains the byte offset of a pointer that needs to be link-edited.
 225 Text relocation offsets are reckoned from the start of the text segment,
 226 and data relocation offsets from the start of the data segment.
 227 The link editor adds the value that is already stored at this offset
 228 into the new value that it computes using this relocation record.
 229 .It Fa r_symbolnum
 230 Contains the ordinal number of a symbol structure
 231 in the symbol table (it is
 232 .Em not
 233 a byte offset).
 234 After the link editor resolves the absolute address for this symbol,
 235 it adds that address to the pointer that is undergoing relocation.
 236 (If the
 237 .Fa r_extern
 238 bit is clear, the situation is different; see below.)
 239 .It Fa r_pcrel
 240 If this is set,
 241 the link editor assumes that it is updating a pointer
 242 that is part of a machine code instruction using pc-relative addressing.
 243 The address of the relocated pointer is implicitly added
 244 to its value when the running program uses it.
 245 .It Fa r_length
 246 Contains the log base 2 of the length of the pointer in bytes;
 247 0 for 1-byte displacements, 1 for 2-byte displacements,
 248 2 for 4-byte displacements.
 249 .It Fa r_extern
 250 Set if this relocation requires an external reference;
 251 the link editor must use a symbol address to update the pointer.
 252 When the
 253 .Fa r_extern
 254 bit is clear, the relocation is
 255 .Sq local ;
 256 the link editor updates the pointer to reflect
 257 changes in the load addresses of the various segments,
 258 rather than changes in the value of a symbol (except when
 259 .Fa r_baserel
 260 is also set (see below).
 261 In this case, the content of the
 262 .Fa r_symbolnum
 263 field is an
 264 .Fa n_type
 265 value (see below);
 266 this type field tells the link editor
 267 what segment the relocated pointer points into.
 268 .It Fa r_baserel
 269 If set, the symbol, as identified by the
 270 .Fa r_symbolnum
 271 field, is to be relocated to an offset into the Global Offset Table.
 272 At run-time, the entry in the Global Offset Table at this offset is set to
 273 be the address of the symbol.
 274 .It Fa r_jmptable
 275 If set, the symbol, as identified by the
 276 .Fa r_symbolnum
 277 field, is to be relocated to an offset into the Procedure Linkage Table.
 278 .It Fa r_relative
 279 If set, this relocation is relative to the (run-time) load address of the
 280 image this object file is going to be a part of.
 281 This type of relocation
 282 only occurs in shared objects.
 283 .It Fa r_copy
 284 If set, this relocation record identifies a symbol whose contents should
 285 be copied to the location given in
 286 .Fa r_address .
 287 The copying is done by the run-time link-editor from a suitable data
 288 item in a shared object.
 289 .El
 290 .Pp
 291 Symbols map names to addresses (or more generally, strings to values).
 292 Since the link-editor adjusts addresses,
 293 a symbol's name must be used to stand for its address
 294 until an absolute value has been assigned.
 295 Symbols consist of a fixed-length record in the symbol table
 296 and a variable-length name in the string table.
 297 The symbol table is an array of
 298 .Fa nlist
 299 structures:
 300 .Bd -literal -offset indent
 301 struct nlist {
 302         union {
 303                 const char      *n_name;
 304                 long            n_strx;
 305         } n_un;
 306         unsigned char           n_type;
 307         char                    n_other;
 308         short                   n_desc;
 309         unsigned long           n_value;
 310 };
 311 .Ed
 312 .Pp
 313 The fields are used as follows:
 314 .Bl -tag -width n_un.n_strx
 315 .It Fa n_un.n_strx
 316 Contains a byte offset into the string table
 317 for the name of this symbol.
 318 When a program accesses a symbol table with the
 319 .Xr nlist 3
 320 function,
 321 this field is replaced with the
 322 .Fa n_un.n_name
 323 field, which is a pointer to the string in memory.
 324 .It Fa n_type
 325 Used by the link editor to determine
 326 how to update the symbol's value.
 327 The
 328 .Fa n_type
 329 field is broken down into three sub-fields using bitmasks.
 330 The link editor treats symbols with the
 331 .Dv N_EXT
 332 type bit set as
 333 .Sq external
 334 symbols and permits references to them from other binary files.
 335 The
 336 .Dv N_TYPE
 337 mask selects bits of interest to the link editor:
 338 .Bl -tag -width N_TEXT
 339 .It Dv N_UNDF
 340 An undefined symbol.
 341 The link editor must locate an external symbol with the same name
 342 in another binary file to determine the absolute value of this symbol.
 343 As a special case, if the
 344 .Fa n_value
 345 field is nonzero and no binary file in the link-edit defines this symbol,
 346 the link-editor will resolve this symbol to an address
 347 in the bss segment,
 348 reserving an amount of bytes equal to
 349 .Fa n_value .
 350 If this symbol is undefined in more than one binary file
 351 and the binary files do not agree on the size,
 352 the link editor chooses the greatest size found across all binaries.
 353 .It Dv N_ABS
 354 An absolute symbol.
 355 The link editor does not update an absolute symbol.
 356 .It Dv N_TEXT
 357 A text symbol.
 358 This symbol's value is a text address and
 359 the link editor will update it when it merges binary files.
 360 .It Dv N_DATA
 361 A data symbol; similar to
 362 .Dv N_TEXT
 363 but for data addresses.
 364 The values for text and data symbols are not file offsets but
 365 addresses; to recover the file offsets, it is necessary
 366 to identify the loaded address of the beginning of the corresponding
 367 section and subtract it, then add the offset of the section.
 368 .It Dv N_BSS
 369 A bss symbol; like text or data symbols but
 370 has no corresponding offset in the binary file.
 371 .It Dv N_FN
 372 A filename symbol.
 373 The link editor inserts this symbol before
 374 the other symbols from a binary file when
 375 merging binary files.
 376 The name of the symbol is the filename given to the link editor,
 377 and its value is the first text address from that binary file.
 378 Filename symbols are not needed for link-editing or loading,
 379 but are useful for debuggers.
 380 .El
 381 .Pp
 382 The
 383 .Dv N_STAB
 384 mask selects bits of interest to symbolic debuggers
 385 such as
 386 .Xr gdb 1 Pq Pa ports/devel/gdb ;
 387 the values are described in
 388 .Xr stab 5 .
 389 .It Fa n_other
 390 This field provides information on the nature of the symbol independent of
 391 the symbol's location in terms of segments as determined by the
 392 .Fa n_type
 393 field.
 394 Currently, the lower 4 bits of the
 395 .Fa n_other
 396 field hold one of two values:
 397 .Dv AUX_FUNC
 398 and
 399 .Dv AUX_OBJECT
 400 (see
 401 .In link.h
 402 for their definitions).
 403 .Dv AUX_FUNC
 404 associates the symbol with a callable function, while
 405 .Dv AUX_OBJECT
 406 associates the symbol with data, irrespective of their locations in
 407 either the text or the data segment.
 408 This field is intended to be used by
 409 .Xr ld 1
 410 for the construction of dynamic executables.
 411 .It Fa n_desc
 412 Reserved for use by debuggers; passed untouched by the link editor.
 413 Different debuggers use this field for different purposes.
 414 .It Fa n_value
 415 Contains the value of the symbol.
 416 For text, data and bss symbols, this is an address;
 417 for other symbols (such as debugger symbols),
 418 the value may be arbitrary.
 419 .El
 420 .Pp
 421 The string table consists of an
 422 .Em unsigned long
 423 length followed by null-terminated symbol strings.
 424 The length represents the size of the entire table in bytes,
 425 so its minimum value (or the offset of the first string)
 426 is always 4 on 32-bit machines.
 427 .Sh SEE ALSO
 428 .Xr as 1 ,
 429 .Xr gdb 1 Pq Pa ports/devel/gdb ,
 430 .Xr ld 1 ,
 431 .Xr brk 2 ,
 432 .Xr execve 2 ,
 433 .Xr nlist 3 ,
 434 .Xr core 5 ,
 435 .Xr elf 5 ,
 436 .Xr link 5 ,
 437 .Xr stab 5
 438 .Sh HISTORY
 439 The
 440 .In a.out.h
 441 include file appeared in
 442 .At v7 .
 443 .Sh BUGS
 444 Since not all of the supported architectures use the
 445 .Fa a_midmag
 446 field,
 447 it can be difficult to determine what
 448 architecture a binary will execute on
 449 without examining its actual machine code.
 450 Even with a machine identifier,
 451 the byte order of the
 452 .Fa exec
 453 header is machine-dependent.