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