1.\" $NetBSD: link.5,v 1.10 1999/03/24 06:14:18 mycroft 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 <link.h> 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 refered 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 accessable 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.Pp 116.Sh DATA STRUCTURES 117The data structures supporting dynamic linking and run-time relocation 118reside both in the text and data segments of the image they apply to. 119The text segments contain read-only data such as symbols descriptions and 120names, while the data segments contain the tables that need to be modified by 121during the relocation process. 122.Pp 123The _DYNAMIC symbol references a 124.Fa _dynamic 125structure: 126.Bd -literal -offset indent 127struct _dynamic { 128 int d_version; 129 struct so_debug *d_debug; 130 union { 131 struct section_dispatch_table *d_sdt; 132 } d_un; 133 struct ld_entry *d_entry; 134}; 135.Ed 136.Bl -tag -width d_version 137.It Fa d_version 138This field provides for different versions of the dynamic linking 139implementation. 140The current version numbers understood by ld and ld.so are 141.Em LD_VERSION_SUN (3), 142which is used by the 143.Tn "SunOS 4.x" 144releases, and 145.Em LD_VERSION_BSD (8), 146which is currently in use by 147.Nx . 148.It Fa d_un 149Refers to a 150.Em d_version 151dependent data structure. 152.It Fa d_debug 153this field provides debuggers with a hook to access symbol tables of shared 154objects loaded as a result of the actions of the run-time link-editor. 155.It Fa d_entry 156this field is obsoleted by CRT interface version CRT_VERSION_BSD4, and is 157replaced by the crt_ldentry in 158.Fa crt_ldso . 159.El 160.Pp 161The 162.Fa section_dispatch_table 163structure is the main 164.Dq dispatcher 165table, containing offsets into the image's segments where various symbol 166and relocation information is located. 167.Bd -literal -offset indent 168struct section_dispatch_table { 169 struct so_map *sdt_loaded; 170 long sdt_sods; 171 long sdt_paths; 172 long sdt_got; 173 long sdt_plt; 174 long sdt_rel; 175 long sdt_hash; 176 long sdt_nzlist; 177 long sdt_filler2; 178 long sdt_buckets; 179 long sdt_strings; 180 long sdt_str_sz; 181 long sdt_text_sz; 182 long sdt_plt_sz; 183}; 184.Ed 185.Pp 186.Bl -tag -width sdt_loaded 187.It Fa sdt_loaded 188A pointer to the first link map loaded (see below). 189This field is set by 190.Xr ld.so 1 191for the benefit of debuggers that may use it to load a shared object's 192symbol table. 193.It Fa sdt_sods 194The start of a (linked) list of shared object descriptors needed by 195.Em this 196object. 197.It Fa sdt_paths 198Library search rules. 199A colon separated list of directories corresponding to the 200.Fl R 201option of 202.Xr ld 1 . 203.It Fa sdt_got 204The location of the Global Offset Table within this image. 205.It Fa sdt_plt 206The location of the Procedure Linkage Table within this image. 207.It Fa sdt_rel 208The location of an array of 209.Fa relocation_info 210structures 211.Po 212see 213.Xr a.out 5 214.Pc 215specifying run-time relocations. 216.It Fa sdt_hash 217The location of the hash table for fast symbol lookup in this object's 218symbol table. 219.It Fa sdt_nzlist 220The location of the symbol table. 221.It Fa sdt_filler2 222Currently unused. 223.It Fa sdt_buckets 224The number of buckets in 225.Fa sdt_hash 226.It Fa sdt_strings 227The location of the symbol string table that goes with 228.Fa sdt_nzlist . 229.It Fa sdt_str_sz 230The size of the string table. 231.It Fa sdt_text_sz 232The size of the object's text segment. 233.It Fa sdt_plt_sz 234The size of the Procedure Linkage Table. 235.El 236.Pp 237A 238.Fa sod 239structure descibes a shared object that is needed 240to complete the link edit process of the object containing it. 241A list of such objects 242.Po 243chained through 244.Fa sod_next 245.Pc 246is pointed at 247by the 248.Fa sdt_sods 249in the section_dispatch_table structure. 250.Bd -literal -offset indent 251struct sod { 252 long sod_name; 253 u_int sod_library : 1, 254 sod_unused : 31; 255 short sod_major; 256 short sod_minor; 257 long sod_next; 258}; 259.Ed 260.Pp 261.Bl -tag -width sod_library 262.It Fa sod_name 263The offset in the text segment of a string describing this link object. 264.It Fa sod_library 265If set, 266.Fa sod_name 267specifies a library that is to be searched for by ld.so. 268The path name is obtained by searching a set of directories 269.Po 270see also 271.Xr ldconfig 8 272.Pc 273for a shared object matching 274.Em lib\&<sod_name>\&.so.n.m . 275If not set, 276.Fa sod_name 277should point at a full path name for the desired shared object. 278.It Fa sod_major 279Specifies the major version number of the shared object to load. 280.It Fa sod_minor 281Specifies the prefered minor version number of the shared object to load. 282.El 283.Pp 284The run-time link-editor maintains a list of structures called 285.Em link maps 286to keep track of all shared objects loaded into a process' address space. 287These structures are only used at run-time and do not occur within 288the text or data segment of an executable or shared library. 289.Bd -literal -offset indent 290struct so_map { 291 caddr_t som_addr; 292 char *som_path; 293 struct so_map *som_next; 294 struct sod *som_sod; 295 caddr_t som_sodbase; 296 u_int som_write : 1; 297 struct _dynamic *som_dynamic; 298 caddr_t som_spd; 299}; 300.Ed 301.Bl -tag -width som_dynamic 302.It Fa som_addr 303The address at which the shared object associated with this link map has 304been loaded. 305.It Fa som_path 306The full path name of the loaded object. 307.It Fa som_next 308Pointer to the next link map. 309.It Fa som_sod 310The 311.Fa sod 312structure that was responsible for loading this shared object. 313.It Fa som_sodbase 314Tossed in later versions the run-time linker. 315.It Fa som_write 316Set if (some portion of) this object's text segment is currently writable. 317.It Fa som_dynamic 318Pointer to this object's 319.Fa _dynamic 320structure. 321.It Fa som_spd 322Hook for attaching private data maintained by the run-time link-editor. 323.El 324.Pp 325Symbol description with size. 326This is simply an 327.Fa nlist 328structure with one field 329.Pq Fa nz_size 330added. 331Used to convey size information on items in the data segment of 332shared objects. 333An array of these lives in the shared object's text segment and is 334addressed by the 335.Fa sdt_nzlist 336field of 337.Fa section_dispatch_table . 338.Bd -literal -offset indent 339struct nzlist { 340 struct nlist nlist; 341 u_long nz_size; 342#define nz_un nlist.n_un 343#define nz_strx nlist.n_un.n_strx 344#define nz_name nlist.n_un.n_name 345#define nz_type nlist.n_type 346#define nz_value nlist.n_value 347#define nz_desc nlist.n_desc 348#define nz_other nlist.n_other 349}; 350.Ed 351.Bl -tag -width nz_size 352.It Fa nlist 353.Po 354see 355.Xr nlist 3 356.Pc . 357.It Fa nz_size 358The size of the data represented by this symbol. 359.El 360.Pp 361A hash table is included within the text segment of shared object to 362to facilitate quick lookup of symbols during run-time link-editing. 363The 364.Fa sdt_hash 365field of the 366.Fa section_dispatch_table 367structure points at an array of 368.Fa rrs_hash 369structures: 370.Bd -literal -offset indent 371struct rrs_hash { 372 int rh_symbolnum; /* symbol number */ 373 int rh_next; /* next hash entry */ 374}; 375.Ed 376.Pp 377.Bl -tag -width rh_symbolnum 378.It Fa rh_symbolnum 379The index of the symbol in the shared object's symbol table (as given by the 380.Fa ld_symbols 381field). 382.It Fa rh_next 383In case of collisions, this field is the offset of the next entry in this 384hash table bucket. 385It is zero for the last bucket element. 386.El 387The 388.Fa rt_symbol 389structure is used to keep track of run-time allocated commons 390and data items copied from shared objects. 391These items are kept on linked list and is exported through the 392.Fa dd_cc 393field in the 394.Fa so_debug 395structure (see below) for use by debuggers. 396.Bd -literal -offset indent 397struct rt_symbol { 398 struct nzlist *rt_sp; 399 struct rt_symbol *rt_next; 400 struct rt_symbol *rt_link; 401 caddr_t rt_srcaddr; 402 struct so_map *rt_smp; 403}; 404.Ed 405.Pp 406.Bl -tag -width rt_scraddr 407.It Fa rt_sp 408The symbol description. 409.It Fa rt_next 410Virtual address of next rt_symbol. 411.It Fa rt_link 412Next in hash bucket. 413Used by internally by ld.so. 414.It Fa rt_srcaddr 415Location of the source of initialized data within a shared object. 416.It Fa rt_smp 417The shared object which is the original source of the data that this 418run-time symbol describes. 419.El 420.Pp 421The 422.Fa so_debug 423structure is used by debuggers to gain knowledge of any shared objects 424that have been loaded in the process's address space as a result of run-time 425link-editing. 426Since the run-time link-editor runs as a part of process initialization, 427a debugger that wishes to access symbols from shared objects can 428only do so after the link-editor has been called from crt0. 429A dynamically linked binary contains a 430.Fa so_debug 431structure which can be located by means of the 432.Fa d_debug 433field in 434.Fa _dynamic . 435.Bd -literal -offset indent 436struct so_debug { 437 int dd_version; 438 int dd_in_debugger; 439 int dd_sym_loaded; 440 char *dd_bpt_addr; 441 int dd_bpt_shadow; 442 struct rt_symbol *dd_cc; 443}; 444.Ed 445.Pp 446.Bl -tag -width dd_in_debugger 447.It Fa dd_version 448Version number of this interface. 449.It Fa dd_in_debugger 450Set by the debugger to indicate to the run-time linker that the program is 451run under control of a debugger. 452.It Fa dd_sym_loaded 453Set by the run-time linker whenever it adds symbols by loading shared objects. 454.It Fa dd_bpt_addr 455The address were a breakpoint will be set by the run-time linker to 456divert control to the debugger. 457This address is determined by the start-up module, 458.Em crt0.o, 459to be some convenient place before the call to _main. 460.It Fa dd_bpt_shadow 461Contains the original instruction that was at 462.Fa dd_bpt_addr . 463The debugger is expected to put this instruction back before continuing the 464program. 465.It Fa dd_cc 466A pointer to the linked list of run-time allocated symbols that the debugger 467may be interested in. 468.El 469.Pp 470The 471.Em ld_entry 472structure defines a set of service routines within ld.so. 473See 474.Xr dlfcn 3 475for more information. 476.Bd -literal -offset indent 477struct ld_entry { 478 void *(*dlopen)(char *, int); 479 int (*dlclose)(void *); 480 void *(*dlsym)(void *, char *); 481 int (*dlctl)(void *, int, void *); 482 void (*dlexit) __P((void)); 483}; 484.Ed 485 486The 487.Fa crt_ldso 488structure defines the interface between ld.so and the start-up code in crt0. 489.Bd -literal -offset indent 490struct crt_ldso { 491 int crt_ba; 492 int crt_dzfd; 493 int crt_ldfd; 494 struct _dynamic *crt_dp; 495 char **crt_ep; 496 caddr_t crt_bp; 497 char *crt_prog; 498 char *crt_ldso; 499 char *crt_ldentry; 500}; 501#define CRT_VERSION_SUN 1 502#define CRT_VERSION_BSD2 2 503#define CRT_VERSION_BSD3 3 504#define CRT_VERSION_BSD4 4 505.Ed 506.Bl -tag -width crt_dzfd 507.It Fa crt_ba 508The virtual address at which ld.so was loaded by crt0. 509.It Fa crt_dzfd 510On 511.Tn SunOS 512systems, this field contains an open file descriptor to 513.Dq /dev/zero 514used to get demand paged zeroed pages. 515On 516.Nx 517systems it contains -1. 518.It Fa crt_ldfd 519Contains an open file descriptor that was used by crt0 to load ld.so. 520.It Fa crt_dp 521A pointer to main's 522.Fa _dynamic 523structure. 524.It Fa crt_ep 525A pointer to the environment strings. 526.It Fa crt_bp 527The address at which a breakpoint will be placed by the run-time linker 528if the main program is run by a debugger. 529See 530.Fa so_debug 531.It Fa crt_prog 532The name of the main program as determined by crt0 (CRT_VERSION_BSD3 only). 533.It Fa crt_ldso 534The path of the run-time linker as mapped by crt0 (CRT_VERSION_BSD4 only). 535.It Fa crt_ldentry 536The 537.Xr dlfcn 3 538entry points provided by the run-time linker (CRT_VERSION_BSD4 only). 539.El 540.Pp 541The 542.Fa hints_header 543and 544.Fa hints_bucket 545structures define the layout of the library hints, normally found in 546.Dq /var/run/ld.so.hints, 547which is used by ld.so to quickly locate the shared object images in the 548filesystem. 549The organization of the hints file is not unlike that of an 550.Xr a.out 5 551object file, in that it contains a header determining the offset and size 552of a table of fixed sized hash buckets and a common string pool. 553.Bd -literal -offset indent 554struct hints_header { 555 long hh_magic; 556#define HH_MAGIC 011421044151 557 long hh_version; 558#define LD_HINTS_VERSION_1 1 559#define LD_HINTS_VERSION_2 2 560 long hh_hashtab; 561 long hh_nbucket; 562 long hh_strtab; 563 long hh_strtab_sz; 564 long hh_ehints; 565 long hh_dirlist; 566}; 567.Ed 568.Bl -tag -width hh_strtab_sz 569.It Fa hh_magic 570Hints file magic number. 571.It Fa hh_version 572Interface version number. 573.It Fa hh_hashtab 574Offset of hash table. 575.It Fa hh_strtab 576Offset of string table. 577.It Fa hh_strtab_sz 578Size of strings. 579.It Fa hh_ehints 580Maximum usable offset in hints file. 581.It Fa hh_dirlist 582Offset in string table of a colon-separated list of directories that was 583used in constructing the hints file. 584See also 585.Xr ldconfig 8 . 586This field is only available with interface version number 587.Dv LD_HINTS_VERSION_2 588and higher. 589.El 590.Pp 591.Bd -literal -offset indent 592/* 593 * Hash table element in hints file. 594 */ 595struct hints_bucket { 596 int hi_namex; 597 int hi_pathx; 598 int hi_dewey[MAXDEWEY]; 599 int hi_ndewey; 600#define hi_major hi_dewey[0] 601#define hi_minor hi_dewey[1] 602 int hi_next; 603}; 604.Ed 605.Bl -tag -width hi_ndewey 606.It Fa hi_namex 607Index of the string identifying the library. 608.It Fa hi_pathx 609Index of the string representing the full path name of the library. 610.It Fa hi_dewey 611The version numbers of the shared library. 612.It Fa hi_ndewey 613The number of valid entries in 614.Fa hi_dewey . 615.It Fa hi_next 616Next bucket in case of hashing collisions. 617.El 618.Sh CAVEATS 619Only the (GNU) C compiler currently supports the creation of shared libraries. 620Other programming languages can not be used. 621