Commit | Line | Data |
---|---|---|
ad787160 C |
1 | .\" This source code is a product of Sun Microsystems, Inc. and is provided |
2 | .\" for unrestricted use provided that this legend is included on all tape | |
3 | .\" media and as a part of the software program in whole or part. Users | |
4 | .\" may copy or modify this source code without charge, but are not authorized | |
5 | .\" to license or distribute it to anyone else except as part of a product or | |
6 | .\" program developed by the user. | |
7 | .\" | |
8 | .\" THIS PROGRAM CONTAINS SOURCE CODE COPYRIGHTED BY SUN MICROSYSTEMS, INC. | |
9 | .\" SUN MICROSYSTEMS, INC., MAKES NO REPRESENTATIONS ABOUT THE SUITABLITY | |
10 | .\" OF SUCH SOURCE CODE FOR ANY PURPOSE. IT IS PROVIDED "AS IS" WITHOUT | |
11 | .\" EXPRESS OR IMPLIED WARRANTY OF ANY KIND. SUN MICROSYSTEMS, INC. DISCLAIMS | |
12 | .\" ALL WARRANTIES WITH REGARD TO SUCH SOURCE CODE, INCLUDING ALL IMPLIED | |
13 | .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN | |
14 | .\" NO EVENT SHALL SUN MICROSYSTEMS, INC. BE LIABLE FOR ANY SPECIAL, INDIRECT, | |
15 | .\" INCIDENTAL, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING | |
16 | .\" FROM USE OF SUCH SOURCE CODE, REGARDLESS OF THE THEORY OF LIABILITY. | |
17 | .\" | |
18 | .\" This source code is provided with no support and without any obligation on | |
19 | .\" the part of Sun Microsystems, Inc. to assist in its use, correction, | |
20 | .\" modification or enhancement. | |
21 | .\" | |
22 | .\" SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE | |
23 | .\" INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY THIS | |
24 | .\" SOURCE CODE OR ANY PART THEREOF. | |
25 | .\" | |
26 | .\" Sun Microsystems, Inc. | |
27 | .\" 2550 Garcia Avenue | |
28 | .\" Mountain View, California 94043 | |
29 | .\" | |
30 | .\" Copyright (c) 1991 Sun Microsystems, Inc. | |
31 | .\" | |
32 | .\" @(#)ld.1 1.48 90/02/02 SMI; | |
33 | .TH LD 1 "21 January 1990" | |
34 | .SH NAME | |
35 | ld, ld.so \- link editor, dynamic link editor | |
36 | .SH SYNOPSIS | |
37 | .B ld | |
38 | [ | |
39 | .BI \-align " datum" | |
40 | ] [ | |
41 | .BI \-assert " assertion-keyword" | |
42 | ] | |
43 | .if n .ti +0.5i | |
44 | [ | |
45 | .BI \-A " name" | |
46 | ] [ | |
47 | .BI \-B "binding-keyword" | |
48 | ] [ | |
49 | .B \-d | |
50 | ] | |
51 | .if t .ti +0.5i | |
52 | [ | |
53 | .B \-dc | |
54 | ] | |
55 | .if n .ti +0.5i | |
56 | [ | |
57 | .B \-dp | |
58 | ] [ | |
59 | .BI \-D " hex" | |
60 | ] [ | |
61 | .BI \-e " entry" | |
62 | ] [ | |
63 | .BI \-l x | |
64 | ] [ | |
65 | .BI \-L dir | |
66 | ] | |
67 | .if n .ti +0.5i | |
68 | [ | |
69 | .B \-M | |
70 | ] [ | |
71 | .B \-n | |
72 | ] [ | |
73 | .B \-N | |
74 | ] [ | |
75 | .BI \-o " name" | |
76 | ] [ | |
77 | .B \-p | |
78 | ] | |
79 | .if t .ti +0.5i | |
80 | [ | |
81 | .B \-r | |
82 | ] [ | |
83 | .B \-s | |
84 | ] [ | |
85 | .B \-S | |
86 | ] | |
87 | .if n .ti +0.5i | |
88 | [ | |
89 | .B \-t | |
90 | ] [ | |
91 | .BR \-T \|[\| text \|] | |
92 | .I hex | |
93 | ] [ | |
94 | .BI \-Tdata " hex" | |
95 | ] [ | |
96 | .BI \-u " name" | |
97 | ] | |
98 | .if n .ti +0.5i | |
99 | [ | |
100 | .B \-x | |
101 | ] [ | |
102 | .B \-X | |
103 | ] [ | |
104 | .BI \-y sym | |
105 | ] | |
106 | .if t .ti +0.5i | |
107 | [ | |
108 | .B \-z | |
109 | ] | |
110 | .I filename | |
111 | \&.\|.\|. | |
112 | .SH DESCRIPTION | |
113 | .IX "ld command" "" "\fLld\fP \(em link editor" | |
114 | .IX "programming tools" "ld command" "" "\fLld\fP \(em link editor" | |
115 | .IX "link editor" "" "link editor \(em \fLld\fP" | |
116 | .LP | |
117 | .B ld | |
118 | combines object programs to create an | |
119 | .I executable | |
120 | file or another object program suitable for further | |
121 | .B ld | |
122 | processing | |
123 | (with the | |
124 | .B \-r | |
125 | option). The object modules on which | |
126 | .B ld | |
127 | operates are specified on the command line, and can be: | |
128 | .RS | |
129 | .TP 3 | |
130 | \(bu | |
131 | simple object files, which typically end in the | |
132 | .BR .o | |
133 | suffix, and are referred to as \*(lqdot-oh\*(rq files | |
134 | .TP 3 | |
135 | \(bu | |
136 | .BR ar (1V) | |
137 | library archives | |
138 | .RB ( .a ), | |
139 | or \*(lqlibraries\*(rq | |
140 | .TP 3 | |
141 | \(bu | |
142 | dynamically-bound, sharable object files | |
143 | .RB ( .so ), | |
144 | are also referred to as \*(lqshared libraries,\*(rq | |
145 | which are created from previous | |
146 | .B ld | |
147 | executions. | |
148 | .RE | |
149 | .LP | |
150 | Unless an output file is specified, | |
151 | .B ld | |
152 | produces a file named | |
153 | .BR a.out . | |
154 | This file contains the object files given as input, | |
155 | appropriately combined to form an executable file. | |
156 | .SH OPTIONS | |
157 | When linking debugging or profiling objects, include the | |
158 | .B \-g | |
159 | or | |
160 | .B \-pg | |
161 | option (see | |
162 | .BR cc (1V)), | |
163 | as appropriate, in the | |
164 | .B ld | |
165 | command. | |
166 | .LP | |
167 | Options should appear before | |
168 | filenames, except for abbreviated library | |
169 | names specified with | |
170 | .B \-l | |
171 | options, and some binding control options specified by | |
172 | .BR \-B | |
173 | (which can appear anywhere in the line). | |
174 | .TP | |
175 | .BI \-align " datum" | |
176 | Force the global uninitialized data symbol | |
177 | .I datum | |
178 | (usually a | |
179 | .SM FORTRAN | |
180 | common block) to be page-aligned. Increase its size to a whole number of | |
181 | pages, and place its first byte at the start of a page. | |
182 | .TP | |
183 | .BI \-assert " assertion-keyword" | |
184 | Check an assertion about the link editing being performed. The assertion | |
185 | desired is specified by the | |
186 | .I assertion-keyword | |
187 | string. | |
188 | .B ld | |
189 | is silent if the assertion holds, else it yields a diagnostic and aborts. | |
190 | Valid | |
191 | .IR assertion-keyword 's | |
192 | and their interpretations are: | |
193 | .RS | |
194 | .RS | |
195 | .TP 15 | |
196 | .B definitions | |
197 | If the resulting program were run now, there would be no run-time undefined | |
198 | symbol diagnostics. This assertion is set by default. | |
199 | .TP | |
200 | .B nodefinitions | |
201 | Permit the successful linking of a program with | |
202 | unresolved references. | |
203 | .TP | |
204 | .B nosymbolic | |
205 | There are no symbolic relocation items remaining to be resolved. | |
206 | .TP | |
207 | .B pure-text | |
208 | The resulting load has no relocation items remaining in its text. | |
209 | .RE | |
210 | .RE | |
211 | .TP | |
212 | .BI \-A " name" | |
213 | Incremental loading: linking is to be done in a manner so that the | |
214 | resulting object may be read into an already executing program. | |
215 | .I name | |
216 | is the name of a file whose symbol table is taken as a basis | |
217 | on which to define additional symbols. | |
218 | Only newly linked material is | |
219 | entered into the text and data portions of | |
220 | .BR a.out , | |
221 | but the new symbol table will reflect all symbols defined before and after | |
222 | the incremental load. | |
223 | This argument must appear before any other object | |
224 | file in the argument list. | |
225 | One or both of the | |
226 | .B \-T | |
227 | options may be used as well, and will be taken to mean that the newly linked | |
228 | segment will commence at the corresponding addresses (which must be a multiple | |
229 | of the page size). | |
230 | The default value is the old value of | |
231 | .BR _end . | |
232 | .br | |
233 | .ne 10 | |
234 | .TP | |
235 | .BI \-B binding-keyword | |
236 | Specify allowed binding times for the items which follow. Allowed values of | |
237 | .I binding-keyword | |
238 | are: | |
239 | .RS | |
240 | .TP 15 | |
241 | .B dynamic | |
242 | Allow dynamic binding: do not resolve symbolic references, allow creation of | |
243 | run-time symbol and relocation environment. | |
244 | .B -Bdynamic | |
245 | is the default. | |
246 | When | |
247 | .B \-Bdynamic | |
248 | is in effect, all sharable objects encountered until a | |
249 | succeeding | |
250 | .B \-Bstatic | |
251 | may be added dynamically to the object being | |
252 | linked. Non-sharable objects are bound statically. | |
253 | .TP | |
254 | .B nosymbolic | |
255 | Do not perform symbolic relocation, even if other options imply it. | |
256 | .TP | |
257 | .B static | |
258 | Bind statically. Opposite of | |
259 | .BR \-Bdynamic . | |
260 | Implied when either | |
261 | .B \-n | |
262 | or | |
263 | .B \-N | |
264 | is specified. Influences handling of all objects | |
265 | following its specification on a command line until the next | |
266 | .BR \-Bdynamic . | |
267 | .TP | |
268 | .B symbolic | |
269 | Force symbolic relocation. Normally implied if an entry point has been | |
270 | specified with | |
271 | .BR \-e , | |
272 | or if dynamic loading is in effect. | |
273 | .RE | |
274 | .TP | |
275 | .B \-d | |
276 | Force common storage for uninitialized variables and other | |
277 | common symbols to be allocated in the current | |
278 | .B ld | |
279 | run, even when the | |
280 | .B \-r | |
281 | flag is present (which would otherwise postpone this binding | |
282 | until the final linking phase). | |
283 | .TP | |
284 | .B \-dc | |
285 | Do | |
286 | .BR \-d , | |
287 | but also copy initialized data referenced by this program | |
288 | from shared objects. | |
289 | .TP | |
290 | .B \-dp | |
291 | Force an alias definition of undefined procedure entry points. | |
292 | Used with dynamic binding to improve sharing and the locality | |
293 | of run-time relocations. | |
294 | .TP | |
295 | .BI \-D " hex" | |
296 | Pad the data segment with zero-valued bytes to make it | |
297 | .I hex | |
298 | bytes long. | |
299 | .TP | |
300 | .BI \-e " entry" | |
301 | Define the entry point: the | |
302 | .I entry | |
303 | argument is made the | |
304 | name of the entry point of the loaded program. Implies | |
305 | .BR \-Bsymbolic . | |
306 | .TP | |
307 | .BI \-l x\|\fR[ . v\|\fR] | |
308 | This option is an abbreviation for the library name | |
309 | .BI lib x .a\fR, | |
310 | where | |
311 | .I x | |
312 | is a string. | |
313 | .B ld | |
314 | searches for libraries first in any directories specified with | |
315 | .B \-L | |
316 | options, then in the standard directories | |
317 | .BR /lib , | |
318 | .BR /usr/lib , | |
319 | and | |
320 | .BR /usr/local/lib . | |
321 | A library is searched when its name is encountered, | |
322 | so the placement of a | |
323 | .B \-l | |
324 | is significant. If a dynamically loadable object is found, and | |
325 | .B \-Bdynamic | |
326 | is in effect at that point on the command line, then | |
327 | .B ld | |
328 | prepares to access the object for relocation at run-time. In such a | |
329 | case, the optional | |
330 | .BI . v | |
331 | suffix can be used to indicate a specific library version. | |
332 | .br | |
333 | .ne 5 | |
334 | .TP | |
335 | .BI \-L dir | |
336 | Add | |
337 | .I dir | |
338 | to the list of directories in which to search for libraries. | |
339 | Directories specified with | |
340 | .B \-L | |
341 | are searched before the standard directories, | |
342 | .BR /lib , | |
343 | .BR /usr/lib , | |
344 | and | |
345 | .BR /usr/local/lib . | |
346 | When building a program in which one or more objects are loaded when | |
347 | .B -Bdynamic | |
348 | is in effect, those directories specified by | |
349 | .B \-L | |
350 | options will be \*(lqremembered\*(rq for use at execution time. This permits | |
351 | the construction of software that uses shared objects as libraries not | |
352 | residing | |
353 | in the standard locations and avoids requiring the specification of | |
354 | the | |
355 | .SB LD_LIBRARY_PATH | |
356 | environment variable | |
357 | in order to execute such software. Note that such directories are | |
358 | retained in | |
359 | .I exactly | |
360 | the form specified in the option, which means that relative directory | |
361 | specifications (i.e., not beginning with \*(lq/\*(rq) will be evaluated | |
362 | relative to the current directory when the program is | |
363 | .IR run , | |
364 | not just during the operation of | |
365 | .BR ld . | |
366 | .TP | |
367 | .B \-M | |
368 | Produce a primitive load map, listing the names of the files | |
369 | which will be loaded. | |
370 | .TP | |
371 | .B \-n | |
372 | Arrange (by giving the output file a 0410 \*(lqmagic number\*(rq) | |
373 | that when the output | |
374 | file is executed, the text portion will be read-only with the data areas | |
375 | placed at the beginning of the next address boundary following the end of | |
376 | the text. Implies | |
377 | .BR \-Bstatic . | |
378 | .TP | |
379 | .B \-N | |
380 | Do not make the text portion read-only. (Use \*(lqmagic number\*(rq 0407.) | |
381 | Implies | |
382 | .BR \-Bstatic . | |
383 | .TP | |
384 | .BI \-o " name" | |
385 | .I name | |
386 | is made the name of the | |
387 | .B ld | |
388 | output file, instead of | |
389 | .BR a.out . | |
390 | .br | |
391 | .ne 3 | |
392 | .TP | |
393 | .B \-p | |
394 | Arrange for the data segment to begin on a page boundary, even if the text is | |
395 | not shared (with the | |
396 | .B \-N | |
397 | option). | |
398 | .TP | |
399 | .B \-r | |
400 | Generate relocation bits in the output file | |
401 | so that it can be the subject of another | |
402 | .B ld | |
403 | run. This flag also prevents final definitions from being given to common | |
404 | symbols, and suppresses the \*(lqundefined symbol\*(rq diagnostics. | |
405 | .TP | |
406 | .B \-s | |
407 | Strip the output, that is, remove the symbol table and relocation bits to save | |
408 | space (but impair the usefulness of the debuggers). This information can also | |
409 | be removed by | |
410 | .BR strip (1). | |
411 | .TP | |
412 | .B \-S | |
413 | Strip the output by removing all symbols except locals and globals. | |
414 | .TP | |
415 | .B \-t | |
416 | Trace: display the name of each file as it is processed. | |
417 | .br | |
418 | .ne 5 | |
419 | .TP | |
420 | .BR \-T \|[\| text \|]\| \fIhex\fR | |
421 | Start the text segment at location | |
422 | .IR hex . | |
423 | Specifying | |
424 | .B \-T | |
425 | is the same as using the | |
426 | .B \-Ttext | |
427 | option. | |
428 | .TP | |
429 | .BI \-Tdata " hex" | |
430 | Start the data segment at location | |
431 | .IR hex . | |
432 | This option is only of use | |
433 | to programmers wishing to write code for | |
434 | .SM PROM\s0s, | |
435 | since the resulting code cannot be executed by the system. | |
436 | .TP | |
437 | .BI \-u " name" | |
438 | Enter | |
439 | .I name | |
440 | as an undefined symbol. | |
441 | This is useful for loading | |
442 | wholly from a library, since initially the symbol table is empty and an | |
443 | unresolved reference is needed to force the loading of the first routine. | |
444 | .TP | |
445 | .B \-x | |
446 | Preserve only global (non-\fB.globl\fP) symbols in the output symbol | |
447 | table; only enter external symbols. | |
448 | This option saves some space in the output file. | |
449 | .TP | |
450 | .B \-X | |
451 | Record local symbols, except for those whose names begin with | |
452 | .BR L . | |
453 | This option is used by | |
454 | .B cc | |
455 | to discard internally generated labels while | |
456 | retaining symbols local to routines. | |
457 | .TP | |
458 | .BI \-y sym | |
459 | Display each file in which | |
460 | .I sym | |
461 | appears, its type and whether the file defines or references it. | |
462 | Many such options may be given to trace many symbols. | |
463 | It is usually necessary to begin | |
464 | .I sym | |
465 | with an | |
466 | .RB ` _ ', | |
467 | as external C, | |
468 | .SM FORTRAN | |
469 | and Pascal variables begin | |
470 | with underscores. | |
471 | .TP | |
472 | .B \-z | |
473 | Arrange for the process demand paged from the resulting executable | |
474 | file (0413 \*(lqmagic number\*(rq). This is the default. | |
475 | Results in a (32-byte) header on the output file followed by | |
476 | text and data segments, each of which has a multiple of page-size | |
477 | bytes (being padded out with | |
478 | null | |
479 | characters in the file if necessary). | |
480 | With this format the first few | |
481 | .SM BSS | |
482 | segment symbols may actually end up | |
483 | in the data segment; | |
484 | this is to avoid wasting the space resulting from rounding the data | |
485 | segment size. Implies | |
486 | .BR \-Bdynamic . | |
487 | .SH USAGE | |
488 | .SS Command Line Processing | |
489 | .LP | |
490 | In general, options should appear ahead of the list of files to | |
491 | process. Unless otherwise specified, the | |
492 | effect of an option covers all of | |
493 | .B ld | |
494 | operations, independent | |
495 | of that option's placement on the command line. Exceptions to this | |
496 | rule include some of the binding control options specified by | |
497 | .RB ` \-B ' | |
498 | and the abbreviated library-names specified by | |
499 | .RB ` \-l '. | |
500 | These may appear | |
501 | anywhere, and their influence is dependent upon their location. | |
502 | Some options may be obtained from | |
503 | environment variables, such options are interpreted before any | |
504 | on the command line (see | |
505 | .SM ENVIRONMENT\s0, | |
506 | below). | |
507 | .SS Object File Processing | |
508 | .LP | |
509 | The files specified on the command line are processed in | |
510 | the order listed. Information is extracted from each file, | |
511 | and concatenated to form the output. The specific | |
512 | processing performed on a given file depends upon whether it is | |
513 | a simple object file, a library archive, or a shared library. | |
514 | .LP | |
515 | Simple object | |
516 | .RB ( .o ) | |
517 | files are concatenated to the output as they are encountered. | |
518 | .LP | |
519 | Library archive | |
520 | .RB ( .a ) | |
521 | files are searched exactly once each, as each is encountered; | |
522 | only those archive entries matching an unresolved external reference | |
523 | are extracted and concatenated to the output. If a member of an | |
524 | archive references a symbol defined by another member of that same | |
525 | archive, the member making the reference must appear before the | |
526 | member containing the definition. | |
527 | .LP | |
528 | On Sun386i, a library contains a dictionary of symbols, On | |
529 | other Sun systems, processing library archives through | |
530 | .BR ranlib (1) | |
531 | provides this dictionary. In addition, you can use | |
532 | .BR lorder (1), | |
533 | in combination with | |
534 | .BR tsort (1) | |
535 | to place library members in calling order (see | |
536 | .BR lorder (1) | |
537 | for details), or both (for fastest symbol lookup). | |
538 | The first member of an archived processed by | |
539 | .B ranlib | |
540 | has the reserved name of | |
541 | .BR _\^_.\s-1SYMDEF\s0 , | |
542 | which | |
543 | .B ld | |
544 | takes to be the dictionary of all symbols defined by | |
545 | members of the archive. | |
546 | .LP | |
547 | Sharable objects | |
548 | .RB ( .so ) | |
549 | are scanned for symbol definitions and references, | |
550 | but are not normally included in the output from | |
551 | .BR ld , | |
552 | except in cases where a shared library exports initialized data | |
553 | structures and the | |
554 | .B \-dc | |
555 | option is in effect. However, the | |
556 | occurrence of each sharable object file in the | |
557 | .BR ld | |
558 | command line is noted in the resulting executable file; this | |
559 | notation is utilized by an execution-time variant of | |
560 | .BR ld , | |
561 | .BR ld.so , | |
562 | for | |
563 | .I deferred | |
564 | and | |
565 | .I dynamic | |
566 | loading and binding during execution. | |
567 | See | |
568 | .BR "Execution-Time Loading" , | |
569 | below, for details. | |
570 | .LP | |
571 | The | |
572 | .B \-l | |
573 | option specifies a short name for an object | |
574 | file or archive used as a library. | |
575 | The full name of the object file is | |
576 | derived by adding the prefix | |
577 | .B lib | |
578 | and a suffix of either | |
579 | .B .a | |
580 | or | |
581 | .BR .so [ .\c | |
582 | .IR v ] | |
583 | to indicate an | |
584 | .BR ar (1V) | |
585 | archive or a shared library, respectively. | |
586 | The specific suffix used is determined through rules discussed in | |
587 | .BR "Binding and Relocation Semantics" , | |
588 | below. | |
589 | .LP | |
590 | .B ld | |
591 | searches for the desired object file through a list of | |
592 | directories specified by | |
593 | .B \-L | |
594 | options, the environment variable | |
595 | .BR \s-1LD_LIBRARY_PATH\s0 , | |
596 | and finally, the built-in list of standard library directories: | |
597 | .BR /lib , | |
598 | .BR /usr/lib , | |
599 | and | |
600 | .BR /usr/local/lib . | |
601 | . | |
602 | .SS Binding and Relocation Semantics | |
603 | .LP | |
604 | The manner in which | |
605 | .B ld | |
606 | processes a given object file is | |
607 | dependent in part upon the \*(lqbinding mode\*(rq in which it is operating | |
608 | at the time the file is encountered. | |
609 | This binding mode is specified by the | |
610 | .B \-B | |
611 | flag, which takes the keyword arguments: | |
612 | .RS | |
613 | .TP 10 | |
614 | .B dynamic | |
615 | Allow dynamic binding, do not resolve symbolic references, and allow | |
616 | creation of execution-time symbol and relocation information. | |
617 | This is the default setting. | |
618 | .TP | |
619 | .B static | |
620 | Force static binding, implied by options that generate non-sharable | |
621 | executable formats. | |
622 | .RE | |
623 | .LP | |
624 | .B \-Bdynamic | |
625 | and | |
626 | .B \-Bstatic | |
627 | may be specified several times, and may be used to toggle each other | |
628 | on and off. | |
629 | Like | |
630 | .BR \-l , | |
631 | the influence of each depends upon its location within the | |
632 | command line. | |
633 | When | |
634 | .B \-Bdynamic | |
635 | is in effect, | |
636 | .B \-l | |
637 | searches may be satisfied by the first occurrence of either form of | |
638 | library | |
639 | .RB ( .so | |
640 | or | |
641 | .BR .a ), | |
642 | but if both are encountered, the | |
643 | .B .so | |
644 | form is preferred. When | |
645 | .B \-Bstatic | |
646 | is in effect, | |
647 | .B ld | |
648 | refuses to use any | |
649 | .B .so | |
650 | libraries it encounters; it continue searching | |
651 | for the | |
652 | .B .a | |
653 | form. Furthermore, an explicit request to load a | |
654 | .B .so | |
655 | file is treated as an error. | |
656 | .LP | |
657 | After | |
658 | .B ld | |
659 | has processed all input files and command line options, the form of | |
660 | the output it produces is based on the information provided in | |
661 | both. | |
662 | .B ld | |
663 | first tries to reduce all symbolic references to | |
664 | relative numerical offsets within the executable it is building. To | |
665 | perform this \*(lqsymbolic reduction,\*(rq | |
666 | .B ld | |
667 | must be able to determine that: | |
668 | .RS | |
669 | .TP 3 | |
670 | \(bu | |
671 | all information relating to the program has been provided, in | |
672 | particular, no | |
673 | .B .so | |
674 | is to be added at execution time; and/or | |
675 | .TP | |
676 | \(bu | |
677 | the program has an entry point, and symbolic reduction can | |
678 | be performed for all symbols having definitions existing in the | |
679 | material provided. | |
680 | .RE | |
681 | .LP | |
682 | It should be noted that uninitialized \*(lqcommon\*(rq areas | |
683 | (for example, uninitialized C globals) are allocated by the | |
684 | link editor | |
685 | .I after | |
686 | it has collected all references. | |
687 | In particular, this allocation can not occur in a program that still | |
688 | requires the addition of information contained in a | |
689 | .B \&.so | |
690 | file, as the missing information may affect the allocation process. | |
691 | Initialized \*(lqcommons\*(rq however, are allocated within the executable | |
692 | in which their definition appears. | |
693 | .LP | |
694 | After | |
695 | .B ld | |
696 | has performed all the symbolic reductions it can, it | |
697 | attempts to transform all relative references to absolute addresses. | |
698 | .B ld | |
699 | is able to perform this \*(lqrelative reduction\*(rq | |
700 | only if it has been provided | |
701 | .I some | |
702 | absolute address, either implicitly through the specification of an | |
703 | entry point, or explicitly through | |
704 | .B ld | |
705 | command-line options. | |
706 | If, after performing all the reductions it can, | |
707 | there are no further relocations or definitions to perform, then | |
708 | .B ld | |
709 | has produced a completely linked executable. | |
710 | .SS Execution-Time Loading | |
711 | .LP | |
712 | In the event that one or more reductions can not be completed, | |
713 | the executable will require further link editing at execution | |
714 | time in order to be usable. Such executables contain an | |
715 | data structure identified with the symbol | |
716 | .BR _\^_\s-1DYNAMIC\s0 . | |
717 | An incompletely linked \*(lqmain\*(rq program should be | |
718 | linked with a \*(lqbootstrap\*(rq routine that invokes | |
719 | .BR ld.so , | |
720 | which uses the information | |
721 | contained in the main program's | |
722 | .SB _\^_DYNAMIC | |
723 | to assemble the rest | |
724 | of the executables constituting the entire program. A standard | |
725 | Sun compilation driver (such as | |
726 | .BR cc (1V)) | |
727 | automatically includes such a module in each \*(lqmain\*(rq executable. | |
728 | .LP | |
729 | When | |
730 | .B ld.so | |
731 | is given control on program startup, it finds all | |
732 | .B .so | |
733 | files specified when the program was constructed (and | |
734 | all | |
735 | .BR .so 's | |
736 | on which they depend), and loads | |
737 | them into the address space. The algorithm by which such files are found | |
738 | mimics that used when | |
739 | .B ld | |
740 | is run, and like | |
741 | .BR ld , | |
742 | can be influenced by the setting of | |
743 | .SB LD_LIBRARY_PATH | |
744 | and any | |
745 | .B \-L | |
746 | options specified to | |
747 | .B ld | |
748 | when the program was built. | |
749 | .B ld.so | |
750 | then completes all | |
751 | remaining relocations, with the exception of procedure call | |
752 | relocations; failure to resolve a given non-procedural relocation | |
753 | results in termination of the program with an appropriate diagnostic. | |
754 | .LP | |
755 | Procedure relocations are resolved when the referencing instruction | |
756 | is first executed. It should be noted that it is possible for | |
757 | \*(lqundefined symbol\*(rq diagnostics to be produced during program | |
758 | execution if a given target is not defined when referenced. | |
759 | .LP | |
760 | Although it is possible for binding errors to occur at execution-time, | |
761 | such an occurrence generally indicates something wrong in the | |
762 | maintenance of shared objects. | |
763 | .BR ld 's | |
764 | .B "\-assert nodefinitions" | |
765 | function (on by default) checks at | |
766 | .BR ld -time | |
767 | whether or not an execution-time binding error would occur. | |
768 | .SS Version Handling for Shared Libraries | |
769 | .LP | |
770 | To allow the independent evolution of | |
771 | .BR .so 's | |
772 | used as libraries and the programs which use them, | |
773 | .BR ld 's | |
774 | handling of | |
775 | .B .so | |
776 | files found through | |
777 | .B \-l | |
778 | options involves the retention and | |
779 | management of version control information. The | |
780 | .B .so | |
781 | files used as such \*(lqshared libraries\*(rq are post-fixed with a | |
782 | Dewey-decimal format string describing the version of the \*(lqlibrary\*(rq | |
783 | contained in the file. | |
784 | .LP | |
785 | The first decimal component is called the library's | |
786 | \*(lqmajor version\*(rq number, | |
787 | and the second component its \*(lqminor version\*(rq number. When | |
788 | .B ld | |
789 | records a | |
790 | .B .so | |
791 | used as a library, it also records these two | |
792 | numbers in the database used by | |
793 | .B ld.so | |
794 | at execution time. In turn, | |
795 | .B ld.so | |
796 | uses these numbers to | |
797 | decide which of multiple versions of a given library is \*(lqbest\*(rq or | |
798 | whether | |
799 | .I any | |
800 | of the available versions are acceptable. The | |
801 | rules are: | |
802 | .RS | |
803 | .TP 3 | |
804 | \(bu | |
805 | Major Versions Identical: the major version used at | |
806 | execution time must exactly match the version found at | |
807 | .BR ld -time. | |
808 | Failure to find an instance of the library with a matching major | |
809 | version causes a diagnostic to be issued and the program's | |
810 | execution to be terminated. | |
811 | .TP | |
812 | \(bu | |
813 | Highest Minor Version: in the presence of multiple instances of | |
814 | libraries that match the desired major version, | |
815 | .B ld.so | |
816 | uses the highest minor version it finds. However, if the highest minor | |
817 | version found at execution time is less than the version found at | |
818 | .BR ld -time, | |
819 | a warning diagnostic is issued; program execution continues. | |
820 | .RE | |
821 | .LP | |
822 | The semantics of version numbers are such that major version numbers | |
823 | should be changed whenever interfaces are changed. Minor versions | |
824 | should be changed to reflect compatible updates to libraries, and | |
825 | programs will silently favor the highest compatible version they can | |
826 | obtain. | |
827 | .SS Special Symbols | |
828 | .LP | |
829 | A number of symbols have special meanings to | |
830 | .B ld | |
831 | and programs should not define these symbols. The symbols described | |
832 | below are those actually seen by | |
833 | .BR ld . | |
834 | Note: C and several | |
835 | other languages prepend symbols they use with | |
836 | .RB ` _ '. | |
837 | .TP | |
838 | .BR _etext | |
839 | The first location after the text of the program. | |
840 | .TP | |
841 | .BR _edata | |
842 | The first location after initialized data. | |
843 | .TP | |
844 | .B _end | |
845 | The first location after all data. | |
846 | .br | |
847 | .ne 5 | |
848 | .TP | |
849 | .SB _\^_DYNAMIC | |
850 | Identifies an | |
851 | .BR ld -produced | |
852 | data structure. It is defined with a non-zero value in | |
853 | executables which require execution-time link editing. | |
854 | By convention, if defined, it is the | |
855 | first symbol in the symbol table associated with an | |
856 | .B a.out | |
857 | file. | |
858 | .br | |
859 | .ne 8 | |
860 | .TP | |
861 | .SB _\^_GLOBAL_OFFSET_TABLE_ | |
862 | A position-independent reference to an | |
863 | .BR ld -constructed | |
864 | table of addresses. This table is constructed from | |
865 | \*(lqposition-independent\*(rq data references occurring in objects | |
866 | that have been assembled with the assembler's | |
867 | .B \-k | |
868 | flag (invoked on behalf of C compilations | |
869 | performed with the | |
870 | .B \-pic | |
871 | flag). A related table (for which no | |
872 | symbol is currently defined) contains a series of transfer | |
873 | instructions and is created from \*(lqposition-independent\*(rq procedure | |
874 | calls or, if | |
875 | .B \-dp | |
876 | is specified to | |
877 | .BR ld , | |
878 | a list of undefined symbols. | |
879 | .LP | |
880 | Symbols in object files beginning with the letter | |
881 | .B L | |
882 | are taken to be | |
883 | local symbols and unless otherwise specified are purged from | |
884 | .B ld | |
885 | output files. | |
886 | .br | |
887 | .ne 6 | |
888 | .SH ENVIRONMENT | |
889 | .TP | |
890 | .SB LD_LIBRARY_PATH | |
891 | A colon-separated list of directories in which to search for | |
892 | libraries specified with the | |
893 | .B \-l | |
894 | option. Similar to the | |
895 | .SB PATH | |
896 | environment variable. | |
897 | .SB LD_LIBRARY_PATH | |
898 | also affects library searching during execution-time loading, causing | |
899 | the search to use first those directories found in | |
900 | the environment variable, then any directories specified by | |
901 | .B \-L | |
902 | options, and finally the standard directories | |
903 | .B /usr/lib | |
904 | and | |
905 | .BR /usr/local/lib . | |
906 | .SB NOTE: | |
907 | when running a set-user- or set-group-ID program, | |
908 | .BR ld.so | |
909 | will only search for libraries in directories it \*(lqtrusts\*(rq, which | |
910 | are | |
911 | .BR /usr/lib , | |
912 | .BR /usr/5lib , | |
913 | .BR /usr/local/lib , | |
914 | and any directories specified within the executable as a result of | |
915 | .B \-L | |
916 | options given when the executable was constructed. | |
917 | .br | |
918 | .ne 5 | |
919 | .TP | |
920 | .SB LD_OPTIONS | |
921 | A default set of options to | |
922 | .BR ld . | |
923 | .SB LD_OPTIONS | |
924 | is interpreted by | |
925 | .B ld | |
926 | just as though its value had been placed on the command line, | |
927 | immediately following the name used to invoke | |
928 | .BR ld , | |
929 | as in: | |
930 | .IP | |
931 | .ft B | |
932 | example% ld $LD_OPTIONS \fR.\|.\|. \fIother-arguments \fR.\|.\|. | |
933 | .LP | |
934 | Note: Environment variable-names beginning with the characters | |
935 | .RB ` LD_ ' | |
936 | are reserved for possible future enhancements to | |
937 | .BR ld . | |
938 | .SH FILES | |
939 | .PD 0 | |
940 | .TP 20 | |
941 | .B /usr/lib/lib*.a | |
942 | libraries | |
943 | .TP | |
944 | .B lib*.so.v | |
945 | shared libraries | |
946 | .TP | |
947 | .B lib*.sa.v | |
948 | exported, initialized shared library data | |
949 | .TP | |
950 | .B /usr/lib/ld.so | |
951 | execution-time | |
952 | .B ld | |
953 | .TP | |
954 | .B /usr/lib/*crt*.o | |
955 | default program bootstraps | |
956 | .TP | |
957 | .B a.out | |
958 | output file | |
959 | .TP | |
960 | .B /usr/local/lib | |
961 | .PD | |
962 | .SH SEE ALSO | |
963 | .BR ar (1V), | |
964 | .BR as (1), | |
965 | .BR cc (1V), | |
966 | .BR lorder (1), | |
967 | .BR ranlib (1), | |
968 | .BR strip (1), | |
969 | .BR tsort (1), | |
970 | .BR ldconfig (8) | |
971 | .br | |
972 | .ne 8 | |
973 | .SH BUGS | |
974 | .LP | |
975 | Options are being overloaded and are an inappropriate vehicle for describing | |
976 | to | |
977 | .B ld | |
978 | the wide variety of things it can do. | |
979 | There needs to be | |
980 | a link-editing language which can be used in the more complex situations. | |
981 | .LP | |
982 | The | |
983 | .B \-r | |
984 | option does not properly handle programs assembled with | |
985 | the | |
986 | .B \-k | |
987 | (position-independent) flag, invoked from | |
988 | .B cc | |
989 | with | |
990 | .B \-pic | |
991 | or | |
992 | .BR \-\s-1PIC\s0 . |