Commit | Line | Data |
---|---|---|
b126b715 KM |
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 | .\" | |
69428b9e | 5 | .\" @(#)ld.1 6.2 (Berkeley) %G% |
b126b715 | 6 | .\" |
98c29de5 | 7 | .TH LD 1 "" |
b126b715 KM |
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. | |
98c29de5 KM |
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 | |
69428b9e | 116 | are searched before the standard directories. |
b126b715 KM |
117 | .TP |
118 | .BI \-l x | |
119 | This | |
120 | option is an abbreviation for the library name | |
98c29de5 | 121 | .RI `lib x .a', |
b126b715 KM |
122 | where |
123 | .I x | |
124 | is a string. | |
98c29de5 KM |
125 | .I Ld |
126 | searches for libraries first in any directories | |
127 | specified with | |
128 | .B \-L | |
69428b9e JL |
129 | options, then in the standard directories `/lib', `/usr/lib', and |
130 | `/usr/local/lib'. | |
b126b715 KM |
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 | |
3d685d18 | 229 | .IR size (1)) |
b126b715 KM |
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. | |
3d685d18 KM |
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. |