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