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