1.\" Copyright (c) 1980, 1990 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.proprietary.man% 5.\" 6.\" @(#)ld.1 6.7 (Berkeley) 08/09/91 7.\" 8.Dd 9.Dt LD 1 10.Os BSD 4 11.Sh NAME 12.Nm ld 13.Nd link editor 14.Sh SYNOPSIS 15.Nm ld 16.Op option 17.Ar ... 18.Ar file ... 19.Sh DESCRIPTION 20.Nm Ld 21combines several 22object programs into one, resolves external 23references, and searches libraries. 24In the simplest case several object 25.Ar files 26are given, and 27.Nm ld 28combines them, producing 29an object module which can be either executed or 30become the input for a further 31.Nm ld 32run. 33(In the latter case, the 34.Fl r 35option must be given 36to preserve the relocation bits.) 37The output of 38.Nm ld 39is left on 40.Pa a.out . 41This file is made executable 42only if no errors occurred during the load. 43.Pp 44The argument routines are concatenated in the order 45specified. The entry point of the output is the 46beginning of the first routine (unless the 47.Fl e 48option is specified). 49.Pp 50If any argument is a library, it is searched exactly once 51at the point it is encountered in the argument list. 52Only those routines defining an unresolved external 53reference are loaded. 54If a routine from a library 55references another routine in the library, 56and the library has not been processed by 57.Xr ranlib 1 , 58the referenced routine must appear after the 59referencing routine in the library. 60Thus the order of programs within libraries 61may be important. 62The first member of a library 63should be a file named `\_\^\_.SYMDEF', 64which is understood to be a dictionary for the library as produced by 65.Xr ranlib 1 ; 66the dictionary is searched iteratively to satisfy as many references as 67possible. 68.Pp 69The symbols `\_etext', `\_edata' and `\_end' 70(`etext', `edata' and `end' in C) 71are reserved, and if referred to, 72are set to the first location above the program, 73the first location above initialized data, 74and the first location above all data respectively. 75It is erroneous to define these symbols. 76.Pp 77.Nm Ld 78understands several options. 79Except for 80.Fl l , 81they should appear before the file names. 82.Bl -tag -width flagx 83.It Fl A 84This option specifies incremental loading, i.e. 85linking is to be done in a manner so that the resulting object 86may be read into an already executing program. 87The next argument is the name of a file whose symbol table will be 88taken as a basis on which to define additional symbols. 89Only newly linked material will be entered into the text and 90data portions of 91.Xr a.out , 92but the new symbol table will reflect 93every symbol defined before and after the incremental load. 94This argument must appear before any other object file in the argument list. 95The 96.Fl T 97option may be used as well, and will be taken to mean that the 98newly linked segment will commence at the corresponding address 99(which must be a multiple of 1024). 100The default value is the old value of _end. 101.It Fl D 102Take the next argument as a hexadecimal number and pad the data segment 103with zero bytes to the indicated length. 104.It Fl d 105Force definition of common storage 106even if the 107.Fl r 108flag is present. 109.It Fl e 110The following argument is taken to be the 111name of the entry point of the loaded 112program; location 0 is the default. 113.It Fl L Ns Ar dir 114Add 115.Ar dir 116to the list of directories in which libraries are searched for. 117Directories specified with 118.Fl L 119are searched before the standard directories. 120.It Fl l Ns Ar x 121This 122option is an abbreviation for the library name 123.Sq Pa libx.a, 124where 125.Ar x 126is a string. 127.Nm Ld 128searches for libraries first in any directories 129specified with 130.Fl L 131options, then in the standard directories 132.Pa /lib , 133.Pa /usr/lib , 134and 135.Pa /usr/local/lib . 136A library is searched when its name is encountered, 137so the placement of a 138.Fl l 139is significant. 140.It Fl M 141produce a primitive load map, listing the names of the files 142which will be loaded. 143.It Fl N 144Do not make the text portion read only or sharable. (Use "magic number" 0407.) 145.It Fl n 146Arrange (by giving the output file a 0410 "magic number") that 147when the output file is executed, 148the text portion will be read-only and shared 149among all users executing the file. 150This involves moving the data areas up to the first 151possible 1024 byte boundary following the 152end of the text. 153.It Fl o 154The 155.Ar name 156argument after 157.Fl o 158is used as the name of the 159.Nm ld 160output file, instead of 161.Pa a.out . 162.It Fl r 163Generate relocation bits in the output file 164so that it can be the subject of another 165.Nm ld 166run. 167This flag also prevents final definitions from being 168given to common symbols, 169and suppresses the `undefined symbol' diagnostics. 170.It Fl S 171`Strip' the output by removing all symbols except locals and globals. 172.It Fl s 173`Strip' the output, that is, remove the symbol table 174and relocation bits to save space (but impair the 175usefulness of the debuggers). 176This information can also be removed by 177.Xr strip 1 . 178.It Fl T 179The next argument is a hexadecimal number which sets the text segment origin. 180The default origin is 0. 181.It Fl t 182("trace") Print the name of each file as it is processed. 183.It Fl u 184Take the following argument as a symbol and enter 185it as undefined in the symbol table. This is useful 186for loading wholly from a library, since initially the symbol 187table is empty and an unresolved reference is needed 188to force the loading of the first routine. 189.It Fl X 190Save local symbols 191except for those whose names begin with `L'. 192This option is used by 193.Xr cc 1 194to discard internally-generated labels while 195retaining symbols local to routines. 196.It Fl x 197Do not preserve local 198(non-.globl) symbols in the output symbol table; only enter 199external symbols. 200This option saves some space in the output file. 201.It Fl y Ns Ar sym 202Indicate each file in which 203.Ar sym 204appears, its type and whether the file defines or references it. 205Many such options may be given to trace many symbols. 206(It is usually necessary to begin 207.Ar sym 208with an `_', as external C, 209.Tn FORTRAN 210and Pascal variables begin 211with underscores.) 212.It Fl z 213Arrange for the process to be loaded on 214demand from the resulting executable file (413 format) 215rather than preloaded. 216This is the default. 217Results in a 1024 byte header on the output file followed by 218a text and data segment each of which have size a multiple of 1024 bytes 219(being padded out with nulls in the file if necessary). 220With this format the first few 221.Tn BSS 222segment symbols may actually appear 223(from the output of 224.Xr size 1 ) 225to live in the data segment; 226this to avoid wasting the space resulting from data segment size roundup. 227.El 228.Sh FILES 229.Bl -tag -width /usr/local/lib/lib*.a -compact 230.It Pa /usr/lib/lib*.a 231Libraries. 232.It Pa /usr/local/lib/lib*.a 233More libraries. 234.It Pa a.out 235Output file. 236.El 237.Sh SEE ALSO 238.Xr as 1 , 239.Xr ar 1 , 240.Xr cc 1 , 241.Xr ranlib 1 242.Sh HISTORY 243The 244.Nm ld 245command appeared in 246.At v6 . 247.Sh BUGS 248There is no way to force data to be page aligned. 249.Nm Ld 250pads images which are to be demand loaded from 251the file system to the next 252page boundary to avoid a bug in the system. 253