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