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