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