1.\" $NetBSD: link.5,v 1.25 2022/12/29 22:41:36 gutteridge 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 39The include file 40.In link.h 41declares several structures that are present in dynamically linked 42programs and libraries. 43The structures define the interface between several components of the 44link-editor and loader mechanism. 45The layout of a number of these structures within the binaries resembles the 46.Xr a.out 5 47format in many places as it serves such similar functions as symbol 48definitions (including the accompanying string table) and relocation records 49needed to resolve references to external entities. 50.Pp 51It also records a number of data structures 52unique to the dynamic loading and linking process. 53These include references to other objects that are required to 54complete 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 58The 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 61the dynamically linked program or shared object image as the existing 62.Xr a.out 5 63format offers no room for it elsewhere. 64.Pp 65Several utilities cooperate to ensure that the task of getting a program 66ready to run can complete successfully in a way that optimizes the use 67of system resources. 68The compiler emits PIC code from which shared libraries can be built by 69.Xr ld 1 . 70The compiler also includes size information of any initialized data items 71through the .size assembler directive. 72.Pp 73PIC code differs from conventional code in that it accesses data 74variables through an indirection table, the Global Offset Table, 75by convention accessible by the reserved name 76.Em _GLOBAL_OFFSET_TABLE_ . 77The exact mechanism used for this is machine dependent, usually a machine 78register is reserved for the purpose. 79The rationale behind this construct is to generate code that is 80independent of the actual load address. 81Only the values contained in the Global Offset Table may need 82updating at run-time depending on the load addresses of the various 83shared objects in the address space. 84.Pp 85Likewise, procedure calls to globally defined functions are redirected 86through the Procedure Linkage Table (PLT) residing in the data 87segment of the core image. 88Again, this is done to avoid run-time modifications to the text segment. 89.Pp 90The linker-editor allocates the Global Offset Table and Procedure 91Linkage Table when combining PIC object files into an image suitable 92for mapping into the process address space. 93It also collects all symbols that may be needed by the run-time 94link-editor and stores these along with the image's text and data bits. 95Another reserved symbol, 96.Em _DYNAMIC 97is used to indicate the presence of the run-time linker structures. 98Whenever 99.Em _DYNAMIC 100is relocated to 0, there is no need to invoke the run-time link-editor. 101If this symbol is non-zero, it points at a data structure from 102which the location of the necessary relocation and symbol information 103can be derived. 104This is most notably used by the start-up module, 105.Em crt0 . 106The _DYNAMIC structure is conventionally located at the start of the data 107segment of the image to which it pertains. 108.Sh DATA STRUCTURES 109The data structures supporting dynamic linking and run-time relocation 110reside both in the text and data segments of the image they apply to. 111The text segments contain read-only data such as symbols descriptions and 112names, while the data segments contain the tables that need to be modified by 113during the relocation process. 114.Pp 115The _DYNAMIC symbol references a 116.Fa _dynamic 117structure: 118.Bd -literal -offset indent 119struct _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 130This field provides for different versions of the dynamic linking 131implementation. 132The current version numbers understood by ld and ld.so are 133.Em LD_VERSION_SUN (3) , 134which is used by the 135.Tn "SunOS 4.x" 136releases, and 137.Em LD_VERSION_BSD (8) , 138which is currently in use by 139.Nx . 140.It Fa d_un 141Refers to a 142.Em d_version 143dependent data structure. 144.It Fa d_debug 145this field provides debuggers with a hook to access symbol tables of shared 146objects loaded as a result of the actions of the run-time link-editor. 147.It Fa d_entry 148this field is obsoleted by CRT interface version CRT_VERSION_BSD4, and is 149replaced by the crt_ldentry in 150.Fa crt_ldso . 151.El 152.Pp 153The 154.Fa section_dispatch_table 155structure is the main 156.Dq dispatcher 157table, containing offsets into the image's segments where various symbol 158and relocation information is located. 159.Bd -literal -offset indent 160struct 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 180A pointer to the first link map loaded (see below). 181This field is set by 182.Xr ld.so 1 183for the benefit of debuggers that may use it to load a shared object's 184symbol table. 185.It Fa sdt_sods 186The start of a (linked) list of shared object descriptors needed by 187.Em this 188object. 189.It Fa sdt_paths 190Library search rules. 191A colon separated list of directories corresponding to the 192.Fl R 193option of 194.Xr ld 1 . 195.It Fa sdt_got 196The location of the Global Offset Table within this image. 197.It Fa sdt_plt 198The location of the Procedure Linkage Table within this image. 199.It Fa sdt_rel 200The location of an array of 201.Fa relocation_info 202structures 203.Po 204see 205.Xr a.out 5 206.Pc 207specifying run-time relocations. 208.It Fa sdt_hash 209The location of the hash table for fast symbol lookup in this object's 210symbol table. 211.It Fa sdt_nzlist 212The location of the symbol table. 213.It Fa sdt_filler2 214Currently unused. 215.It Fa sdt_buckets 216The number of buckets in 217.Fa sdt_hash 218.It Fa sdt_strings 219The location of the symbol string table that goes with 220.Fa sdt_nzlist . 221.It Fa sdt_str_sz 222The size of the string table. 223.It Fa sdt_text_sz 224The size of the object's text segment. 225.It Fa sdt_plt_sz 226The size of the Procedure Linkage Table. 227.El 228.Pp 229A 230.Fa sod 231structure describes a shared object that is needed 232to complete the link edit process of the object containing it. 233A list of such objects 234.Po 235chained through 236.Fa sod_next 237.Pc 238is pointed at 239by the 240.Fa sdt_sods 241in the section_dispatch_table structure. 242.Bd -literal -offset indent 243struct 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 255The offset in the text segment of a string describing this link object. 256.It Fa sod_library 257If set, 258.Fa sod_name 259specifies a library that is to be searched for by ld.so. 260The path name is obtained by searching a set of directories 261.Po 262see also 263.Xr ldconfig 8 264.Pc 265for a shared object matching 266.Em lib\&<sod_name>\&.so.n.m . 267If not set, 268.Fa sod_name 269should point at a full path name for the desired shared object. 270.It Fa sod_major 271Specifies the major version number of the shared object to load. 272.It Fa sod_minor 273Specifies the preferred minor version number of the shared object to load. 274.El 275.Pp 276The run-time link-editor maintains a list of structures called 277.Em link maps 278to keep track of all shared objects loaded into a process' address space. 279These structures are only used at run-time and do not occur within 280the text or data segment of an executable or shared library. 281.Bd -literal -offset indent 282struct 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 295The address at which the shared object associated with this link map has 296been loaded. 297.It Fa som_path 298The full path name of the loaded object. 299.It Fa som_next 300Pointer to the next link map. 301.It Fa som_sod 302The 303.Fa sod 304structure that was responsible for loading this shared object. 305.It Fa som_sodbase 306Tossed in later versions the run-time linker. 307.It Fa som_write 308Set if (some portion of) this object's text segment is currently writable. 309.It Fa som_dynamic 310Pointer to this object's 311.Fa _dynamic 312structure. 313.It Fa som_spd 314Hook for attaching private data maintained by the run-time link-editor. 315.El 316.Pp 317Symbol description with size. 318This is simply an 319.Fa nlist 320structure with one field 321.Pq Fa nz_size 322added. 323Used to convey size information on items in the data segment of 324shared objects. 325An array of these lives in the shared object's text segment and is 326addressed by the 327.Fa sdt_nzlist 328field of 329.Fa section_dispatch_table . 330.Bd -literal -offset indent 331struct 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 346see 347.Xr nlist 3 348.Pc . 349.It Fa nz_size 350The size of the data represented by this symbol. 351.El 352.Pp 353A hash table is included within the text segment of shared object 354to facilitate quick lookup of symbols during run-time link-editing. 355The 356.Fa sdt_hash 357field of the 358.Fa section_dispatch_table 359structure points at an array of 360.Fa rrs_hash 361structures: 362.Bd -literal -offset indent 363struct 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 371The index of the symbol in the shared object's symbol table (as given by the 372.Fa ld_symbols 373field). 374.It Fa rh_next 375In case of collisions, this field is the offset of the next entry in this 376hash table bucket. 377It is zero for the last bucket element. 378.El 379The 380.Fa rt_symbol 381structure is used to keep track of run-time allocated commons 382and data items copied from shared objects. 383These items are kept in a linked list which is exported through the 384.Fa dd_cc 385field in the 386.Fa so_debug 387structure (see below) for use by debuggers. 388.Bd -literal -offset indent 389struct 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 400The symbol description. 401.It Fa rt_next 402Virtual address of next rt_symbol. 403.It Fa rt_link 404Next in hash bucket. 405Used by internally by ld.so. 406.It Fa rt_srcaddr 407Location of the source of initialized data within a shared object. 408.It Fa rt_smp 409The shared object which is the original source of the data that this 410run-time symbol describes. 411.El 412.Pp 413The 414.Fa so_debug 415structure is used by debuggers to gain knowledge of any shared objects 416that have been loaded in the process's address space as a result of run-time 417link-editing. 418Since the run-time link-editor runs as a part of process initialization, 419a debugger that wishes to access symbols from shared objects can 420only do so after the link-editor has been called from crt0. 421A dynamically linked binary contains a 422.Fa so_debug 423structure which can be located by means of the 424.Fa d_debug 425field in 426.Fa _dynamic . 427.Bd -literal -offset indent 428struct 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 440Version number of this interface. 441.It Fa dd_in_debugger 442Set by the debugger to indicate to the run-time linker that the program is 443run under control of a debugger. 444.It Fa dd_sym_loaded 445Set by the run-time linker whenever it adds symbols by loading shared objects. 446.It Fa dd_bpt_addr 447The address were a breakpoint will be set by the run-time linker to 448divert control to the debugger. 449This address is determined by the start-up module, 450.Em crt0.o , 451to be some convenient place before the call to _main. 452.It Fa dd_bpt_shadow 453Contains the original instruction that was at 454.Fa dd_bpt_addr . 455The debugger is expected to put this instruction back before continuing the 456program. 457.It Fa dd_cc 458A pointer to the linked list of run-time allocated symbols that the debugger 459may be interested in. 460.El 461.Pp 462The 463.Em ld_entry 464structure defines a set of service routines within ld.so. 465See 466.Xr dlfcn 3 467for more information. 468.Bd -literal -offset indent 469struct 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 478The 479.Fa crt_ldso 480structure defines the interface between ld.so and the start-up code in crt0. 481.Bd -literal -offset indent 482struct 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 500The virtual address at which ld.so was loaded by crt0. 501.It Fa crt_dzfd 502On 503.Tn SunOS 504systems, this field contains an open file descriptor to 505.Dq /dev/zero 506used to get demand paged zeroed pages. 507On 508.Nx 509systems it contains -1. 510.It Fa crt_ldfd 511Contains an open file descriptor that was used by crt0 to load ld.so. 512.It Fa crt_dp 513A pointer to main's 514.Fa _dynamic 515structure. 516.It Fa crt_ep 517A pointer to the environment strings. 518.It Fa crt_bp 519The address at which a breakpoint will be placed by the run-time linker 520if the main program is run by a debugger. 521See 522.Fa so_debug 523.It Fa crt_prog 524The name of the main program as determined by crt0 (CRT_VERSION_BSD3 only). 525.It Fa crt_ldso 526The path of the run-time linker as mapped by crt0 (CRT_VERSION_BSD4 only). 527.It Fa crt_ldentry 528The 529.Xr dlfcn 3 530entry points provided by the run-time linker (CRT_VERSION_BSD4 only). 531.El 532.Pp 533The 534.Fa hints_header 535and 536.Fa hints_bucket 537structures define the layout of the library hints, normally found in 538.Dq /var/run/ld.so.hints , 539which is used by ld.so to quickly locate the shared object images in the 540file system. 541The organization of the hints file is not unlike that of an 542.Xr a.out 5 543object file, in that it contains a header determining the offset and size 544of a table of fixed sized hash buckets and a common string pool. 545.Bd -literal -offset indent 546struct 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 562Hints file magic number. 563.It Fa hh_version 564Interface version number. 565.It Fa hh_hashtab 566Offset of hash table. 567.It Fa hh_strtab 568Offset of string table. 569.It Fa hh_strtab_sz 570Size of strings. 571.It Fa hh_ehints 572Maximum usable offset in hints file. 573.It Fa hh_dirlist 574Offset in string table of a colon-separated list of directories that was 575used in constructing the hints file. 576See also 577.Xr ldconfig 8 . 578This field is only available with interface version number 579.Dv LD_HINTS_VERSION_2 580and higher. 581.El 582.Pp 583.Bd -literal -offset indent 584/* 585 * Hash table element in hints file. 586 */ 587struct 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 599Index of the string identifying the library. 600.It Fa hi_pathx 601Index of the string representing the full path name of the library. 602.It Fa hi_dewey 603The version numbers of the shared library. 604.It Fa hi_ndewey 605The number of valid entries in 606.Fa hi_dewey . 607.It Fa hi_next 608Next bucket in case of hashing collisions. 609.El 610