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