| blob | 08f309398ab5f097595a4499901cfa7b0296e4c9 |
1 .\" $NetBSD: link.5,v 1.21 2007/03/07 00:41:17 dogcow Exp $
2 .\"
3 .\" Copyright (c) 1996 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Paul Kranenburg.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28 .\" POSSIBILITY OF SUCH DAMAGE.
29 .\"
30 .Dd October 23, 1993
31 .Dt LINK 5
32 .Os
33 .Sh NAME
34 .Nm link
35 .Nd dynamic loader and link editor interface
36 .Sh SYNOPSIS
37 .In link.h
38 .Sh DESCRIPTION
39 The include file
40 .Aq Pa link.h
41 declares several structures that are present in dynamically linked
42 programs and libraries.
43 The structures define the interface between several components of the
44 link-editor and loader mechanism.
45 The layout of a number of these structures within the binaries resembles the
46 .Xr a.out 5
47 format in many places as it serves such similar functions as symbol
48 definitions (including the accompanying string table) and relocation records
49 needed to resolve references to external entities.
50 .Pp
51 It also records a number of data structures
52 unique to the dynamic loading and linking process.
53 These include references to other objects that are required to
54 complete the link-editing process and indirection tables to facilitate
55 .Em Position Independent Code
56 (PIC) to improve sharing of code pages among different processes.
57 .Pp
58 The collection of data structures described here will be referred to as the
59 .Em Run-time Relocation Section
60 (RRS) and is embedded in the standard text and data segments of
61 the dynamically linked program or shared object image as the existing
62 .Xr a.out 5
63 format offers no room for it elsewhere.
64 .Pp
65 Several utilities cooperate to ensure that the task of getting a program
66 ready to run can complete successfully in a way that optimizes the use
67 of system resources.
68 The compiler emits PIC code from which shared libraries can be built by
69 .Xr ld 1 .
70 The compiler also includes size information of any initialized data items
71 through the .size assembler directive.
72 .Pp
73 PIC code differs from conventional code in that it accesses data
74 variables through an indirection table, the Global Offset Table,
75 by convention accessible by the reserved name
76 .Em _GLOBAL_OFFSET_TABLE_ .
77 The exact mechanism used for this is machine dependent, usually a machine
78 register is reserved for the purpose.
79 The rational behind this construct is to generate code that is
80 independent of the actual load address.
81 Only the values contained in the Global Offset Table may need
82 updating at run-time depending on the load addresses of the various
83 shared objects in the address space.
84 .Pp
85 Likewise, procedure calls to globally defined functions are redirected
86 through the Procedure Linkage Table (PLT) residing in the data
87 segment of the core image.
88 Again, this is done to avoid run-time modifications to the text segment.
89 .Pp
90 The linker-editor allocates the Global Offset Table and Procedure
91 Linkage Table when combining PIC object files into an image suitable
92 for mapping into the process address space.
93 It also collects all symbols that may be needed by the run-time
94 link-editor and stores these along with the image's text and data bits.
95 Another reserved symbol,
96 .Em _DYNAMIC
97 is used to indicate the presence of the run-time linker structures.
98 Whenever
99 .Em _DYNAMIC
100 is relocated to 0, there is no need to invoke the run-time link-editor.
101 If this symbol is non-zero, it points at a data structure from
102 which the location of the necessary relocation- and symbol information
103 can be derived.
104 This is most notably used by the start-up module,
105 .Em crt0 .
106 The _DYNAMIC structure is conventionally located at the start of the data
107 segment of the image to which it pertains.
108 .Sh DATA STRUCTURES
109 The data structures supporting dynamic linking and run-time relocation
110 reside both in the text and data segments of the image they apply to.
111 The text segments contain read-only data such as symbols descriptions and
112 names, while the data segments contain the tables that need to be modified by
113 during the relocation process.
114 .Pp
115 The _DYNAMIC symbol references a
116 .Fa _dynamic
117 structure:
118 .Bd -literal -offset indent
119 struct _dynamic {
120 int d_version;
121 struct so_debug *d_debug;
122 union {
123 struct section_dispatch_table *d_sdt;
124 } d_un;
125 struct ld_entry *d_entry;
126 };
127 .Ed
128 .Bl -tag -width d_version
129 .It Fa d_version
130 This field provides for different versions of the dynamic linking
131 implementation.
132 The current version numbers understood by ld and ld.so are
133 .Em LD_VERSION_SUN (3) ,
134 which is used by the
135 .Tn "SunOS 4.x"
136 releases, and
137 .Em LD_VERSION_BSD (8) ,
138 which is currently in use by
139 .Nx .
140 .It Fa d_un
141 Refers to a
142 .Em d_version
143 dependent data structure.
144 .It Fa d_debug
145 this field provides debuggers with a hook to access symbol tables of shared
146 objects loaded as a result of the actions of the run-time link-editor.
147 .It Fa d_entry
148 this field is obsoleted by CRT interface version CRT_VERSION_BSD4, and is
149 replaced by the crt_ldentry in
150 .Fa crt_ldso .
151 .El
152 .Pp
153 The
154 .Fa section_dispatch_table
155 structure is the main
156 .Dq dispatcher
157 table, containing offsets into the image's segments where various symbol
158 and relocation information is located.
159 .Bd -literal -offset indent
160 struct section_dispatch_table {
161 struct so_map *sdt_loaded;
162 long sdt_sods;
163 long sdt_paths;
164 long sdt_got;
165 long sdt_plt;
166 long sdt_rel;
167 long sdt_hash;
168 long sdt_nzlist;
169 long sdt_filler2;
170 long sdt_buckets;
171 long sdt_strings;
172 long sdt_str_sz;
173 long sdt_text_sz;
174 long sdt_plt_sz;
175 };
176 .Ed
177 .Pp
178 .Bl -tag -width sdt_loaded
179 .It Fa sdt_loaded
180 A pointer to the first link map loaded (see below).
181 This field is set by
182 .Xr ld.so 1
183 for the benefit of debuggers that may use it to load a shared object's
184 symbol table.
185 .It Fa sdt_sods
186 The start of a (linked) list of shared object descriptors needed by
187 .Em this
188 object.
189 .It Fa sdt_paths
190 Library search rules.
191 A colon separated list of directories corresponding to the
192 .Fl R
193 option of
194 .Xr ld 1 .
195 .It Fa sdt_got
196 The location of the Global Offset Table within this image.
197 .It Fa sdt_plt
198 The location of the Procedure Linkage Table within this image.
199 .It Fa sdt_rel
200 The location of an array of
201 .Fa relocation_info
202 structures
203 .Po
204 see
205 .Xr a.out 5
206 .Pc
207 specifying run-time relocations.
208 .It Fa sdt_hash
209 The location of the hash table for fast symbol lookup in this object's
210 symbol table.
211 .It Fa sdt_nzlist
212 The location of the symbol table.
213 .It Fa sdt_filler2
214 Currently unused.
215 .It Fa sdt_buckets
216 The number of buckets in
217 .Fa sdt_hash
218 .It Fa sdt_strings
219 The location of the symbol string table that goes with
220 .Fa sdt_nzlist .
221 .It Fa sdt_str_sz
222 The size of the string table.
223 .It Fa sdt_text_sz
224 The size of the object's text segment.
225 .It Fa sdt_plt_sz
226 The size of the Procedure Linkage Table.
227 .El
228 .Pp
229 A
230 .Fa sod
231 structure describes a shared object that is needed
232 to complete the link edit process of the object containing it.
233 A list of such objects
234 .Po
235 chained through
236 .Fa sod_next
237 .Pc
238 is pointed at
239 by the
240 .Fa sdt_sods
241 in the section_dispatch_table structure.
242 .Bd -literal -offset indent
243 struct sod {
244 long sod_name;
245 u_int sod_library : 1,
246 sod_unused : 31;
247 short sod_major;
248 short sod_minor;
249 long sod_next;
250 };
251 .Ed
252 .Pp
253 .Bl -tag -width sod_library
254 .It Fa sod_name
255 The offset in the text segment of a string describing this link object.
256 .It Fa sod_library
257 If set,
258 .Fa sod_name
259 specifies a library that is to be searched for by ld.so.
260 The path name is obtained by searching a set of directories
261 .Po
262 see also
263 .Xr ldconfig 8
264 .Pc
265 for a shared object matching
266 .Em lib\&\*[Lt]sod_name\*[Gt]\&.so.n.m .
267 If not set,
268 .Fa sod_name
269 should point at a full path name for the desired shared object.
270 .It Fa sod_major
271 Specifies the major version number of the shared object to load.
272 .It Fa sod_minor
273 Specifies the preferred minor version number of the shared object to load.
274 .El
275 .Pp
276 The run-time link-editor maintains a list of structures called
277 .Em link maps
278 to keep track of all shared objects loaded into a process' address space.
279 These structures are only used at run-time and do not occur within
280 the text or data segment of an executable or shared library.
281 .Bd -literal -offset indent
282 struct so_map {
283 void *som_addr;
284 char *som_path;
285 struct so_map *som_next;
286 struct sod *som_sod;
287 void *som_sodbase;
288 u_int som_write : 1;
289 struct _dynamic *som_dynamic;
290 void *som_spd;
291 };
292 .Ed
293 .Bl -tag -width som_dynamic
294 .It Fa som_addr
295 The address at which the shared object associated with this link map has
296 been loaded.
297 .It Fa som_path
298 The full path name of the loaded object.
299 .It Fa som_next
300 Pointer to the next link map.
301 .It Fa som_sod
302 The
303 .Fa sod
304 structure that was responsible for loading this shared object.
305 .It Fa som_sodbase
306 Tossed in later versions the run-time linker.
307 .It Fa som_write
308 Set if (some portion of) this object's text segment is currently writable.
309 .It Fa som_dynamic
310 Pointer to this object's
311 .Fa _dynamic
312 structure.
313 .It Fa som_spd
314 Hook for attaching private data maintained by the run-time link-editor.
315 .El
316 .Pp
317 Symbol description with size.
318 This is simply an
319 .Fa nlist
320 structure with one field
321 .Pq Fa nz_size
322 added.
323 Used to convey size information on items in the data segment of
324 shared objects.
325 An array of these lives in the shared object's text segment and is
326 addressed by the
327 .Fa sdt_nzlist
328 field of
329 .Fa section_dispatch_table .
330 .Bd -literal -offset indent
331 struct nzlist {
332 struct nlist nlist;
333 u_long nz_size;
334 #define nz_un nlist.n_un
335 #define nz_strx nlist.n_un.n_strx
336 #define nz_name nlist.n_un.n_name
337 #define nz_type nlist.n_type
338 #define nz_value nlist.n_value
339 #define nz_desc nlist.n_desc
340 #define nz_other nlist.n_other
341 };
342 .Ed
343 .Bl -tag -width nz_size
344 .It Fa nlist
345 .Po
346 see
347 .Xr nlist 3
348 .Pc .
349 .It Fa nz_size
350 The size of the data represented by this symbol.
351 .El
352 .Pp
353 A hash table is included within the text segment of shared object
354 to facilitate quick lookup of symbols during run-time link-editing.
355 The
356 .Fa sdt_hash
357 field of the
358 .Fa section_dispatch_table
359 structure points at an array of
360 .Fa rrs_hash
361 structures:
362 .Bd -literal -offset indent
363 struct rrs_hash {
364 int rh_symbolnum; /* symbol number */
365 int rh_next; /* next hash entry */
366 };
367 .Ed
368 .Pp
369 .Bl -tag -width rh_symbolnum
370 .It Fa rh_symbolnum
371 The index of the symbol in the shared object's symbol table (as given by the
372 .Fa ld_symbols
373 field).
374 .It Fa rh_next
375 In case of collisions, this field is the offset of the next entry in this
376 hash table bucket.
377 It is zero for the last bucket element.
378 .El
379 The
380 .Fa rt_symbol
381 structure is used to keep track of run-time allocated commons
382 and data items copied from shared objects.
383 These items are kept on linked list and is exported through the
384 .Fa dd_cc
385 field in the
386 .Fa so_debug
387 structure (see below) for use by debuggers.
388 .Bd -literal -offset indent
389 struct rt_symbol {
390 struct nzlist *rt_sp;
391 struct rt_symbol *rt_next;
392 struct rt_symbol *rt_link;
393 void *rt_srcaddr;
394 struct so_map *rt_smp;
395 };
396 .Ed
397 .Pp
398 .Bl -tag -width rt_scraddr
399 .It Fa rt_sp
400 The symbol description.
401 .It Fa rt_next
402 Virtual address of next rt_symbol.
403 .It Fa rt_link
404 Next in hash bucket.
405 Used by internally by ld.so.
406 .It Fa rt_srcaddr
407 Location of the source of initialized data within a shared object.
408 .It Fa rt_smp
409 The shared object which is the original source of the data that this
410 run-time symbol describes.
411 .El
412 .Pp
413 The
414 .Fa so_debug
415 structure is used by debuggers to gain knowledge of any shared objects
416 that have been loaded in the process's address space as a result of run-time
417 link-editing.
418 Since the run-time link-editor runs as a part of process initialization,
419 a debugger that wishes to access symbols from shared objects can
420 only do so after the link-editor has been called from crt0.
421 A dynamically linked binary contains a
422 .Fa so_debug
423 structure which can be located by means of the
424 .Fa d_debug
425 field in
426 .Fa _dynamic .
427 .Bd -literal -offset indent
428 struct so_debug {
429 int dd_version;
430 int dd_in_debugger;
431 int dd_sym_loaded;
432 char *dd_bpt_addr;
433 int dd_bpt_shadow;
434 struct rt_symbol *dd_cc;
435 };
436 .Ed
437 .Pp
438 .Bl -tag -width dd_in_debugger
439 .It Fa dd_version
440 Version number of this interface.
441 .It Fa dd_in_debugger
442 Set by the debugger to indicate to the run-time linker that the program is
443 run under control of a debugger.
444 .It Fa dd_sym_loaded
445 Set by the run-time linker whenever it adds symbols by loading shared objects.
446 .It Fa dd_bpt_addr
447 The address were a breakpoint will be set by the run-time linker to
448 divert control to the debugger.
449 This address is determined by the start-up module,
450 .Em crt0.o ,
451 to be some convenient place before the call to _main.
452 .It Fa dd_bpt_shadow
453 Contains the original instruction that was at
454 .Fa dd_bpt_addr .
455 The debugger is expected to put this instruction back before continuing the
456 program.
457 .It Fa dd_cc
458 A pointer to the linked list of run-time allocated symbols that the debugger
459 may be interested in.
460 .El
461 .Pp
462 The
463 .Em ld_entry
464 structure defines a set of service routines within ld.so.
465 See
466 .Xr dlfcn 3
467 for more information.
468 .Bd -literal -offset indent
469 struct ld_entry {
470 void *(*dlopen)(char *, int);
471 int (*dlclose)(void *);
472 void *(*dlsym)(void *, char *);
473 int (*dlctl)(void *, int, void *);
474 void (*dlexit)(void);
475 };
476 .Ed
477 .Pp
478 The
479 .Fa crt_ldso
480 structure defines the interface between ld.so and the start-up code in crt0.
481 .Bd -literal -offset indent
482 struct crt_ldso {
483 int crt_ba;
484 int crt_dzfd;
485 int crt_ldfd;
486 struct _dynamic *crt_dp;
487 char **crt_ep;
488 void *crt_bp;
489 char *crt_prog;
490 char *crt_ldso;
491 char *crt_ldentry;
492 };
493 #define CRT_VERSION_SUN 1
494 #define CRT_VERSION_BSD2 2
495 #define CRT_VERSION_BSD3 3
496 #define CRT_VERSION_BSD4 4
497 .Ed
498 .Bl -tag -width crt_dzfd
499 .It Fa crt_ba
500 The virtual address at which ld.so was loaded by crt0.
501 .It Fa crt_dzfd
502 On
503 .Tn SunOS
504 systems, this field contains an open file descriptor to
505 .Dq /dev/zero
506 used to get demand paged zeroed pages.
507 On
508 .Nx
509 systems it contains -1.
510 .It Fa crt_ldfd
511 Contains an open file descriptor that was used by crt0 to load ld.so.
512 .It Fa crt_dp
513 A pointer to main's
514 .Fa _dynamic
515 structure.
516 .It Fa crt_ep
517 A pointer to the environment strings.
518 .It Fa crt_bp
519 The address at which a breakpoint will be placed by the run-time linker
520 if the main program is run by a debugger.
521 See
522 .Fa so_debug
523 .It Fa crt_prog
524 The name of the main program as determined by crt0 (CRT_VERSION_BSD3 only).
525 .It Fa crt_ldso
526 The path of the run-time linker as mapped by crt0 (CRT_VERSION_BSD4 only).
527 .It Fa crt_ldentry
528 The
529 .Xr dlfcn 3
530 entry points provided by the run-time linker (CRT_VERSION_BSD4 only).
531 .El
532 .Pp
533 The
534 .Fa hints_header
535 and
536 .Fa hints_bucket
537 structures define the layout of the library hints, normally found in
538 .Dq /var/run/ld.so.hints ,
539 which is used by ld.so to quickly locate the shared object images in the
540 file system.
541 The organization of the hints file is not unlike that of an
542 .Xr a.out 5
543 object file, in that it contains a header determining the offset and size
544 of a table of fixed sized hash buckets and a common string pool.
545 .Bd -literal -offset indent
546 struct hints_header {
547 long hh_magic;
548 #define HH_MAGIC 011421044151
549 long hh_version;
550 #define LD_HINTS_VERSION_1 1
551 #define LD_HINTS_VERSION_2 2
552 long hh_hashtab;
553 long hh_nbucket;
554 long hh_strtab;
555 long hh_strtab_sz;
556 long hh_ehints;
557 long hh_dirlist;
558 };
559 .Ed
560 .Bl -tag -width hh_strtab_sz
561 .It Fa hh_magic
562 Hints file magic number.
563 .It Fa hh_version
564 Interface version number.
565 .It Fa hh_hashtab
566 Offset of hash table.
567 .It Fa hh_strtab
568 Offset of string table.
569 .It Fa hh_strtab_sz
570 Size of strings.
571 .It Fa hh_ehints
572 Maximum usable offset in hints file.
573 .It Fa hh_dirlist
574 Offset in string table of a colon-separated list of directories that was
575 used in constructing the hints file.
576 See also
577 .Xr ldconfig 8 .
578 This field is only available with interface version number
579 .Dv LD_HINTS_VERSION_2
580 and higher.
581 .El
582 .Pp
583 .Bd -literal -offset indent
584 /*
585 * Hash table element in hints file.
586 */
587 struct hints_bucket {
588 int hi_namex;
589 int hi_pathx;
590 int hi_dewey[MAXDEWEY];
591 int hi_ndewey;
592 #define hi_major hi_dewey[0]
593 #define hi_minor hi_dewey[1]
594 int hi_next;
595 };
596 .Ed
597 .Bl -tag -width hi_ndewey
598 .It Fa hi_namex
599 Index of the string identifying the library.
600 .It Fa hi_pathx
601 Index of the string representing the full path name of the library.
602 .It Fa hi_dewey
603 The version numbers of the shared library.
604 .It Fa hi_ndewey
605 The number of valid entries in
606 .Fa hi_dewey .
607 .It Fa hi_next
608 Next bucket in case of hashing collisions.
609 .El