Commit | Line | Data |
---|---|---|
d9d7a9f0 | 1 | .\" Copyright (c) 1980, 1990 The Regents of the University of California. |
b126b715 KM |
2 | .\" All rights reserved. The Berkeley software License Agreement |
3 | .\" specifies the terms and conditions for redistribution. | |
4 | .\" | |
d9d7a9f0 | 5 | .\" @(#)ld.1 6.3 (Berkeley) %G% |
b126b715 | 6 | .\" |
d9d7a9f0 CL |
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 | |
b126b715 KM |
20 | combines several |
21 | object programs into one, resolves external | |
22 | references, and searches libraries. | |
23 | In the simplest case several object | |
d9d7a9f0 | 24 | .Ar files |
b126b715 | 25 | are given, and |
d9d7a9f0 | 26 | .Nm ld |
b126b715 KM |
27 | combines them, producing |
28 | an object module which can be either executed or | |
29 | become the input for a further | |
d9d7a9f0 | 30 | .Nm ld |
b126b715 KM |
31 | run. |
32 | (In the latter case, the | |
d9d7a9f0 | 33 | .Fl r |
b126b715 | 34 | option must be given |
d9d7a9f0 | 35 | to preserve the relocation bits.)\ |
b126b715 | 36 | The output of |
d9d7a9f0 | 37 | .Nm ld |
b126b715 | 38 | is left on |
d9d7a9f0 | 39 | .Pa a.out . |
b126b715 KM |
40 | This file is made executable |
41 | only if no errors occurred during the load. | |
d9d7a9f0 | 42 | .Pp |
b126b715 KM |
43 | The argument routines are concatenated in the order |
44 | specified. The entry point of the output is the | |
d9d7a9f0 CL |
45 | beginning of the first routine (unless the |
46 | .Fl e | |
47 | option is specified). | |
48 | .Pp | |
b126b715 KM |
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 | |
d9d7a9f0 | 56 | .Xr ranlib 1 , |
b126b715 KM |
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 | |
d9d7a9f0 | 64 | .Xr ranlib 1 ; |
b126b715 KM |
65 | the dictionary is searched iteratively to satisfy as many references as |
66 | possible. | |
d9d7a9f0 | 67 | .Pp |
b126b715 KM |
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. | |
d9d7a9f0 CL |
75 | .Pp |
76 | .Nm Ld | |
b126b715 KM |
77 | understands several options. |
78 | Except for | |
d9d7a9f0 | 79 | .Fl l , |
b126b715 | 80 | they should appear before the file names. |
d9d7a9f0 CL |
81 | .Tw Ds |
82 | .Tp Fl A | |
b126b715 KM |
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 | |
d9d7a9f0 CL |
89 | data portions of |
90 | .Xr a.out , | |
b126b715 KM |
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 | |
d9d7a9f0 | 95 | .Fl T |
b126b715 KM |
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. | |
d9d7a9f0 | 100 | .Tp Fl D |
b126b715 KM |
101 | Take the next argument as a hexadecimal number and pad the data segment |
102 | with zero bytes to the indicated length. | |
d9d7a9f0 | 103 | .Tp Fl d |
b126b715 KM |
104 | Force definition of common storage |
105 | even if the | |
d9d7a9f0 | 106 | .Fl r |
b126b715 | 107 | flag is present. |
d9d7a9f0 | 108 | .Tp Fl e |
b126b715 KM |
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. | |
d9d7a9f0 CL |
112 | .Tc Fl L |
113 | .Ar dir | |
114 | .Cx | |
98c29de5 | 115 | Add |
d9d7a9f0 | 116 | .Ar dir |
98c29de5 | 117 | to the list of directories in which libraries are searched for. |
d9d7a9f0 CL |
118 | Directories specified with |
119 | .Fl L | |
69428b9e | 120 | are searched before the standard directories. |
d9d7a9f0 CL |
121 | .Tc Fl l |
122 | .Ar x | |
123 | .Cx | |
b126b715 KM |
124 | This |
125 | option is an abbreviation for the library name | |
d9d7a9f0 | 126 | .Sq Pa libx.a, |
b126b715 | 127 | where |
d9d7a9f0 | 128 | .Ar x |
b126b715 | 129 | is a string. |
d9d7a9f0 | 130 | .Nm Ld |
98c29de5 KM |
131 | searches for libraries first in any directories |
132 | specified with | |
d9d7a9f0 | 133 | .Fl L |
69428b9e JL |
134 | options, then in the standard directories `/lib', `/usr/lib', and |
135 | `/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. |
d9d7a9f0 | 140 | .Tp Fl M |
b126b715 KM |
141 | produce a primitive load map, listing the names of the files |
142 | which will be loaded. | |
d9d7a9f0 | 143 | .Tp Fl N |
b126b715 | 144 | Do not make the text portion read only or sharable. (Use "magic number" 0407.) |
d9d7a9f0 | 145 | .Tp 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. | |
d9d7a9f0 | 153 | .Tp 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 CL |
161 | .Pa a.out . |
162 | .Tp 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. | |
d9d7a9f0 | 170 | .Tp Fl S |
b126b715 | 171 | `Strip' the output by removing all symbols except locals and globals. |
d9d7a9f0 | 172 | .Tp 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 CL |
177 | .Xr strip 1 . |
178 | .Tp Fl T | |
b126b715 KM |
179 | The next argument is a hexadecimal number which sets the text segment origin. |
180 | The default origin is 0. | |
d9d7a9f0 | 181 | .Tp Fl t |
b126b715 | 182 | ("trace") Print the name of each file as it is processed. |
d9d7a9f0 | 183 | .Tp 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. | |
d9d7a9f0 | 189 | .Tp 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. | |
d9d7a9f0 | 196 | .Tp 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. | |
d9d7a9f0 CL |
201 | .Tc Fl y |
202 | .Ar sym | |
203 | .Cx | |
b126b715 | 204 | Indicate each file in which |
d9d7a9f0 | 205 | .Ar sym |
b126b715 KM |
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 | |
d9d7a9f0 | 209 | .Ar sym |
b126b715 KM |
210 | with an `_', as external C, FORTRAN and Pascal variables begin |
211 | with underscores.) | |
d9d7a9f0 | 212 | .Tp 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). | |
220 | With this format the first few BSS segment symbols may actually appear | |
221 | (from the output of | |
d9d7a9f0 | 222 | .Xr size 1 ) |
b126b715 KM |
223 | to live in the data segment; |
224 | this to avoid wasting the space resulting from data segment size roundup. | |
d9d7a9f0 CL |
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 | |
b126b715 | 245 | There is no way to force data to be page aligned. |
d9d7a9f0 | 246 | .Nm Ld |
3d685d18 KM |
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. |