NAME

ld − link editor

SYNOPSIS

ld [ option ] ... file ... 

DESCRIPTION

Ld combines several Mach-O (Mach object) files into one by combining like sections in like segments from all the object files, resolves external references, and searches libraries.  In the simplest case several object files are given, and ld combines them, producing an object file which can be either executed or become the input for a further ld run.  (In the latter case, the −r option must be given to preserve the relocation bits.)  The output of ld is left on a.out.  This file is made executable only if no errors occurred during the load. 

The object files are concatenated in the order specified.  The segments and the sections in those segments are loaded in the order they are encountered in the object files loaded with zero fill sections appearing after non-zero fill sections in their segments.  The entry point of the output is the beginning of the first section in the first segment. (unless the −e option is specified). 

If any argument is a library, it is searched exactly once at the point it is encountered in the argument list.  Only those routines defining an unresolved external reference are loaded.  If a routine from a library references another routine in the library, and the library has not been processed by ranlib(1), the referenced routine must appear after the referencing routine in the library. Thus the order of programs within libraries may be important.  If the library has been processed by ranlib(1), the first member of a library will be a file named ‘__.SYMDEF’, which is understood to be a dictionary for the library. The dictionary is searched iteratively to satisfy as many references as possible.

The symbols ‘__etext’, ‘__edata’, ‘__end’, ‘__mh_execute_header’, and ‘__shared_library_initialization’ (‘_etext’, ‘_edata’ etc. in C) are reserved.  These loader defined symbols if referred to, are set to their values as described in end(3). It is erroneous to define these symbols.

Ld understands several options.  Except for −l, they should appear before the file names. 

−A This option specifies incremental loading, i.e.  linking is to be done in a manner so that the resulting object may be read into an already executing program.  The next argument is the name of a file whose symbol table will be taken as a basis on which to define additional symbols.  Only newly linked material will be entered into the a.out file, but the new symbol table will reflect every symbol defined before and after the incremental load.  This option must appear before any other object file in the argument list.  The −T option may be used as well, and will be taken to mean that the newly linked object file will commence at the corresponding address (which must be a correct multiple for the resulting object type).  The default address value for the newly linked object file is the old value of __end symbol rounded to the next page boundary (8192 bytes). The default object file type is a Mach-O executable file type (MH_EXECUTE).

−aoriginal:alias
Change the undefined symbol name original to the symbol name alias.  The symbol name alias maybe defined or undefined but the symbol original must be undefined. 

−D Take the next argument as a hexadecimal number and pad the __DATA segment with zero bytes to the indicated length.  The padded area appears after the last zero fill section in the __DATA segment.

−d Force definition of common storage even if the −r flag is present.  This also forces loader defined symbols to be defined. 

−e The following argument is taken to be the symbol name of the entry point of the resulting file; the address of the first section in the first segment is the default. 

−ident string
Create an ident command in the resulting object file and add the string, string, to that command.  More than one such option can be specified but only one ident command will be created.  The strings from ident commands of the loaded object files are always discarded. 

−Ldir Add dir to the list of directories in which libraries are searched for.  Directories specified with −L are searched before the standard directories. 

−lx This option is an abbreviation for the library name ‘libx.a’, where x is a string.  Ld searches for libraries first in any directories specified with −L options, then in the standard directories ‘/lib’, ‘/usr/lib’, and ‘/usr/local/lib’.  A library is searched when its name is encountered, so the placement of a −l is significant.  The string x can be of the form x.o and then that file is searched for in the same places but does not have a lib or a .a added before and after the string. 

−M produce a primitive load map, listing the names of the files which will be loaded. 

−Mach
Produce a Mach-O demand paged executable format file.  The headers are placed in the first segment and all segments are padded to page size multiples. This has a file type of MH_EXECUTE.  This is the default.

−o The name argument after −o is used as the name of the ld output file, instead of a.out. 

−p Produce a Mach-O preloaded executable format file.  The headers are not placed in any segment and the segments are not padded to page size multiples.  This has a file type of MH_PRELOAD. 

−r Generate relocation bits in the output file so that it can be the subject of another ld run.  The resulting file type is a Mach-O relocatable file (MH_OBJECT).  The sections are loaded starting at address 0, with no padding between them, and all in one unnamed segment.  This file is not executable (it does not have a thread command and therefore no entry point).  This flag also prevents final definitions from being given to common symbols, and suppresses the ‘undefined symbol’ diagnostics. 

−S ‘Strip’ the output by removing all symbols except locals and globals. 

−s ‘Strip’ the output, that is, remove the symbol table and relocation bits to save space (but impair the usefulness of the debuggers).  This information can also be removed by strip(1).

−segcreate seg sect file
Create a section, sect, in the segment, seg, that contains the contents of file.  The resulting section size is rounded to a multiple of 4 bytes and the resulting segment is rounded to a multiple of the page size (8192 bytes).  More than one section can be created in the same segment. 

−seglinkedit
Create a segment named “__LINKEDIT” that contains all the link edit information in object file produced.  This allows programs to have access to their symbol table and all parts of their object file at runtime.  The headers (which are also mapped in) must be used to find the specific information needed.

−T or −Ttext
The next argument is a hexadecimal number (without the leading 0x) which sets the __TEXT segment origin.  The default origin is a page size (0x2000).

−Tdata
The next argument is a hexadecimal number (without the leading 0x) which sets the __DATA segment origin.  The default origin is the last address of the __TEXT segment a rounded to the next multiple of page size (0x2000).

−t ("trace")  Print the name of each file as it is processed. 

−U Take the following argument as a symbol that is allowed to be undefined even without −r.  And produce an executable file if only such symbols are undefined. 

−u Take the following argument as a symbol and enter it as undefined in the symbol table.  This is useful for loading wholly from a library, since initially the symbol table is empty and an unresolved reference is needed to force the loading of the first object file. 

−v This is option is accepted but ignored. 

−X Save local symbols except for those whose names begin with ‘L’.  This option is used by cc(1) to discard internally-generated labels while retaining symbols local to routines.

−x Do not preserve local (non-.globl) symbols in the output symbol table; only enter external symbols.  This option saves some space in the output file. 

−ysym
Indicate each file in which sym appears, its type and whether the file defines or references it.  Many such options may be given to trace many symbols.  (It is usually necessary to begin sym with an ‘_’, as external C, FORTRAN and Pascal variables begin with underscores.) 

−Z Do not search the default directories when searching for libraries. 

FILES

/lib/lib∗.alibraries
/usr/lib/lib∗.amore libraries
/usr/local/lib/lib∗.astill more libraries
a.outoutput file

SEE ALSO

as(1), ar(1), cc(1), ranlib(1), end(3), atom(1), otool(1), Mach-O(5)

4th Berkeley Distribution  —  June 14, 1989