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