1.Dd October 23, 1993 2.Dt LINK 5 3.Os 4.Sh NAME 5.Nm link 6.Nd dynamic loader and link editor interface 7.Sh SYNOPSIS 8.Fd #include <link.h> 9.Sh DESCRIPTION 10The include file 11.Aq Pa link.h 12declares several structures that are present in dynamically linked 13programs and libraries. 14The structures define the interface between several components of the 15link-editor and loader mechanism. The layout of a number of these 16structures within the binaries resembles the a.out format in many places 17as it serves such similar functions as symbol definitions (including the 18accompanying string table) and relocation records needed to resolve 19references to external entities. It also records a number of data structures 20unique to the dynamic loading and linking process. These include references 21to other objects that are required to complete the link-editing process and 22indirection tables to facilitate 23.Ev Position Independent Code (PIC for short) 24to improve sharing of code pages among different processes. 25The collection of data structures described here will be refered to as the 26.Ev Run-time Relocation Section (RRS) 27and is embedded in the standard text and data segments of the dynamically 28linked program or shared object image as the existing 29.Xr a.out 30format offers no room for it elsewhere. 31.Pp 32Several utilities cooperate to ensure that the task of getting a program 33ready to run can complete successfully in a way that optimizes the use 34of system resources. The compiler emits PIC code from which shared libraries 35can be build by 36.Ev ld. 37The compiler also includes size information of any initialized data items 38through the .size assembler directive. PIC code differs from conventional code 39in that it accesses data variables through an indirection table, the 40Global Offset Table, by convention accessable by the reserved name 41.Ev _GLOBAL_OFFSET_TABLE_. 42The exact mechanism used for this is machine dependent, usually a machine 43register is reserved for the purpose. The rational behind this construct 44is to generate code that is independent of the actual load address. Only 45the values contained in the Global Offset Table may need updating at run-time 46depending on the load addresses of the various shared objects in the address 47space. 48.Pp 49Likewise, procedure calls to globally defined functions are redirected through 50the Procedure Linkage Table (PLT) residing in the data segment of the core 51image. Again, this is done to avoid run-time modifications to the text segment. 52.Pp 53The linker-editor allocates the Global Offset Table and Procedure Linkage Table 54when combining PIC object files into an image suitable for mapping into the 55process address space. It also collects all symbols that may be needed by the 56run-time link-editor and stores these along with the image's text and data bits. 57Another reserved symbol, 58.Ev _DYNAMIC 59is used to indicate the presence of the run-time linker structures. Whenever 60_DYNAMIC is relocated to 0, there is no need to invoke the run-time 61link-editor. If this symbol is non-zero, it points at a data structure from 62which the location of the necessary relocation- and symbol information can 63be derived. This is most notably used by the start-up module, 64.Ev crt0. 65The _DYNAMIC structure is conventionally located at the start of the data 66segment of the image to which it pertains. 67.Pp 68.Sh DATA STRUCTURES 69The data structures supporting dynamic linking and run-time relocation 70reside both in the text and data segments of the image they apply to. 71The text segments contain read-only data such as symbols descriptions and 72names, while the data segments contain the tables that need to be modified by 73during the relocation process. 74.Pp 75The _DYNAMIC symbol references a 76.Fa link_dynamic 77structure: 78.Bd -literal -offset indent 79struct link_dynamic { 80 int ld_version; 81 struct ld_debug *ldd; 82 union { 83 struct link_dynamic_2 *ld_2; 84 } ld_un; 85 struct ld_entry *ld_entry; 86}; 87.Ed 88.Bl -tag -width ld_version 89.It Fa ld_version 90This field provides for different versions of the dynamic linking 91implementation. The current version numbers understood by ld and ld.so are 92.Ev LD_VERSION_SUN (3), 93which is used by the SunOS 4.x releases, and 94.Ev LD_VERSION_BSD (8), 95which is currently in use by NetBSD release 0.9a. 96.It Fa ld_un 97Refers to a 98.Ev ld_version 99dependent data structure. 100.It Fa ldd_debug 101this field provides debuggers with a hook to access symbol tables of shared 102objects loaded as a result of the actions of the run-time link-editor. 103.El 104.Pp 105The 106.Fa link_dynamic_2 107structure is the main 108.Dq dispatcher 109table, containing offsets into the image's segments where various symbol 110and relocation information is located. 111.Bd -literal -offset indent 112struct link_dynamic_2 { 113 struct link_map *ld_loaded; 114 long ld_need; 115 long ld_rules; 116 long ld_got; 117 long ld_plt; 118 long ld_rel; 119 long ld_hash; 120 long ld_symbols; 121 long (*ld_stab_hash)(); 122 long ld_buckets; 123 long ld_strings; 124 long ld_str_sz; 125 long ld_text_sz; 126 long ld_plt_sz; 127}; 128.Ed 129.Pp 130.Bl -tag -width ld_stab_hash 131.It Fa ld_loaded 132A pointer to the first link map loaded (see below). This field is set by 133.Xr ld.so. 134.It Fa ld_need 135The start of a (linked) list of shared objects needed by 136.Ev this 137object. 138.It Fa ld_rules 139Depricated (used by SunOS to specify library search rules). 140.It Fa ld_got 141The location of the Global Offset Table within this image. 142.It Fa ld_plt 143The location of the Procedure Linkage Table within this image. 144.It Fa ld_rel 145The location of an array of 146.Fa relocation_info 147structures (see 148.Xr a.out 5) 149specifying run-time relocations. 150.It Fa ld_hash 151The location of the hash table for fast symbol lookup in this object's 152symbol table. 153.It Fa ld_symbols 154The location of the symbol table. 155.It Fa ld_stab_hash 156Currently unused. 157.It Fa ld_buckets 158The number of buckets in 159.Fa ld_hash 160.It Fa ld_strings 161The location of the symbol string table that goes with 162.Fa ld_symbols. 163.It Fa ld_str_sz 164The size of the string table. 165.It Fa ld_text_sz 166The size of the object's text segment. 167.It Fa ld_plt_sz 168The size of the Procedure Linkage Table. 169.El 170.Pp 171A 172.Fa link_object 173structure descibes a shared object that is needed 174to complete the link edit process of the object containing it. 175A list of such objects (chained through 176.Fa lo_next) 177is pointed at 178by the 179.Fa ld_need 180in the link_dynamic_2 structure. 181.Bd -literal -offset indent 182struct link_object { 183 long lo_name; 184 u_int lo_library : 1, 185 lo_unused : 31; 186 short lo_major; 187 short lo_minor; 188 long lo_next; 189}; 190.Ed 191.Pp 192.Bl -tag -width lo_library 193.It Fa lo_name 194The offset in the text segment of a string describing this link object. 195.It Fa lo_library 196If set, 197.Fa lo_name 198specifies a library that is to be searched for by ld.so. The path name 199is obtained by searching a set of directories (see 200.Xr ldconfig) 201for a shared object matching 202.Ev lib\&<lo_name>\&.so.n.m. 203If not set, 204.Fa lo_name 205should point at a full path name for the desired shared object. 206.It Fa lo_major 207Specifies the major version number of the shared object to load. 208.It Fa lo_minor 209Specifies the prefered minor version number of the shared object to load. 210.El 211.Pp 212The run-time link-editor maintains a list of link maps to keep 213track of all shared objects loaded into a process' address space. 214These structures are only used at run-time and do not occur within 215the text or data segment of an executable or shared library. 216.Bd -literal -offset indent 217struct link_map { 218 caddr_t lm_addr; 219 char *lm_name; 220 struct link_map *lm_next; 221 struct link_object *lm_lop; 222 caddr_t lm_lob; 223 u_int lm_rwt : 1; 224 struct link_dynamic *lm_ld; 225 caddr_t lm_lpd; 226}; 227.Bl -tag -width ld_addr 228.It Fa lm_addr 229The address at which the shared object associated with this link map has 230been loaded. 231.It Fa lm_name 232The full path name of the loaded object. 233.It Fa lm_next 234Pointer to the next link map. 235.It Fa lm_lop 236The 237.Fa link_object 238structure that was responsible for this shared object to get loaded. 239.It Fa lm_lob 240Depricated. 241.It Fa lm_rwt 242Set if this object's text segment is currently writable. 243.It Fa lm_ld 244Pointer to this object 245.Fa link_dynamic 246structure. 247.It Fa lm_lpd 248Hook for attaching private data maintained by the run-time link-editor. 249.El 250.Ed 251.Pp 252Symbol description with size. This is simply an 253.Fa nlist 254structure with one field ( 255.Fa nz_size 256) added. Used to convey size information on items in the data segment 257of shared objects. An array of these lives in the shared object's 258text segment and is addressed by the 259.Fa ld_symbols 260field of 261.Fa link_dynamic_2. 262.Bd -literal -offset indent 263struct nzlist { 264 struct nlist nlist; 265 u_long nz_size; 266#define nz_un nlist.n_un 267#define nz_strx nlist.n_un.n_strx 268#define nz_name nlist.n_un.n_name 269#define nz_type nlist.n_type 270#define nz_value nlist.n_value 271#define nz_desc nlist.n_desc 272#define nz_other nlist.n_other 273}; 274.Ed 275.Bl -tag -width nz_size 276.It Fa nlist 277(see 278.Xr nlist 5 279). 280.It Fa nz_size 281The size of the data represented by this symbol. 282.El 283.Pp 284A hash table is included within the text segment of shared object to 285to facilitate quick lookup of symbols during run-time link-editing. 286The 287.Fa ld_hash 288field of the 289.Fa link_dynamic_2 290structure points at an array of 291.Fa rrs_hash 292structures: 293.Bd -literal -offset indent 294struct rrs_hash { 295 int rh_symbolnum; /* symbol number */ 296 int rh_next; /* next hash entry */ 297}; 298.Ed 299.Pp 300.Bl -tag -width rh_symbolnum 301.It Fa rh_symbolnum 302The index of the symbol in the shared object's symbol table (as given by the 303.Fa ld_symbols 304field). 305.It Fa rh_next 306In case of collisions, this field is the offset of the next entry in this 307hash table bucket. It is zero for the last bucket element. 308.El 309The 310.Fa rt_symbol 311structure is used to keep track of run-time allocated commons 312and data items copied from shared objects. These items are kept on linked list 313and is exported through the 314.Fa ldd_cp 315field in the 316.Fa ld_debug 317structure (see below) for use by debuggers. 318.Bd -literal -offset indent 319struct rt_symbol { 320 struct nzlist *rt_sp; 321 struct rt_symbol *rt_next; 322 struct rt_symbol *rt_link; 323 caddr_t rt_srcaddr; 324}; 325.Ed 326.Pp 327.Bl -tag -width rt_scraddr 328.It Fa rt_sp 329The symbol description. 330.It Fa rt_next 331Virtual address of next rt_symbol. 332.It Fa rt_link 333Next in hash bucket. Used by internally by ld.so. 334.It Fa rt_srcaddr 335Location of the source of initialized data within a shared object. 336.El 337.Pp 338The 339.Fa ld_debug 340structure is used by debuggers to gain knowledge of any shared objects 341that have been loaded in the process's address space as a result of run-time 342link-editing. Since the run-time link-editor runs as a part of process 343initialization, a debugger that wishes to access symbols from shared objects 344can only do so after the link-editor has been called from crt0. 345A dynamically linked binary contains a 346.Fa ld_debug 347structure which can be located by means of the 348.Fa ldd 349field in 350.Fa link_dynamic. 351.Bd -literal -offset indent 352struct ld_debug { 353 int ldd_version; 354 int ldd_in_debugger; 355 int ldd_sym_loaded; 356 char *ldd_bp_addr; 357 int ldd_bp_inst; 358 struct rt_symbol *ldd_cp; 359}; 360.Ed 361.Pp 362.Bl -tag -width ldd_in_debugger 363.It Fa ldd_version 364Version number of this interface. 365.It Fa ldd_in_debugger 366Set by the debugger to indicate to ld.so that the program is run under 367control of a debugger. 368.It Fa ldd_sym_loaded 369Set by ld.so whenever it adds symbols by loading shared objects. 370.It Fa ldd_bp_addr 371The address were a breakpoint will be set by the ld.so to divert control to 372the debugger. This address is determined by the start-up module, 373.Ev crt0.o, 374to be some convenient place before the call to _main. 375.It Fa ldd_bp_inst 376Contains the original instruction that was at 377.Fa ldd_bp_addr. 378The debugger is expected to put this instruction back before continuing the 379program. 380.It Fa ldd_cp 381A pointer to the linked list of run-time allocated symbols that the debugger 382may interested in. 383.El 384.Pp 385.Bd -literal -offset indent 386The 387.Fa ld_entry 388structure defines a set of service routines within ld.so. See 389.Ev libdl.a 390for more information. 391struct ld_entry { 392 int (*dlopen)(); 393 int (*dlclose)(); 394 int (*dlsym)(); 395}; 396.Ed 397 398.Bd -literal -offset indent 399The 400.Fa crt_ldso 401structure defines the interface between the start-up code in crt0 and ld.so. 402struct crt_ldso { 403 int crt_ba; 404 int crt_dzfd; 405 int crt_ldfd; 406 struct link_dynamic *crt_dp; 407 char **crt_ep; 408 caddr_t crt_bp; 409}; 410#define CRT_VERSION_SUN 1 411#define CRT_VERSION_BSD 2 412.Ed 413.Bl -tag -width crt_dzfd 414.It Fa crt_ba 415The virtual address at which ld.so was loaded by crt0. 416.It Fa crt_dzfd 417On SunOS systems, this field contains an open file descriptor to 418.Dq /dev/zero 419used to get demand paged zeroed pages. On NetBSD systems it contains -1. 420.It Fa crt_ldfd 421Contains an open file descriptor that was used by crt0 to load ld.so. 422.It Fa crt_dp 423A pointer to main's 424.Fa link_dynamic 425structure. 426.It Fa crt_ep 427A pointer to the environment strings. 428.It Fa crt_bp 429The address at which a breakpoint will be placed by ld.so if run by a debugger. 430See 431.Fa ld_debug 432.El 433.Pp 434The 435.Fa hints_header 436and 437.Fa hints_bucket 438structures define the layout of the library hints, normally found in 439.Dq /var/run/ld.so.hints, 440which is used by ld.so to quickly locate the shared object images in the 441filesystem. 442The organization of the hints file is not unlike that of an 443.Dq a.out 444object file, in that it contains a header determining the offset and size 445of a table of fixed sized hash buckets and a common string pool. 446.Bd -literal -offset indent 447struct hints_header { 448 long hh_magic; 449#define HH_MAGIC 011421044151 450 long hh_version; 451#define LD_HINTS_VERSION_1 1 452 long hh_hashtab; 453 long hh_nbucket; 454 long hh_strtab; 455 long hh_strtab_sz; 456 long hh_ehints; 457}; 458.Ed 459.Bl -tag -width hh_strtab_sz 460.It Fa hh_magic 461Hints file magic number. 462.It Fa hh_version 463Interface version number. 464.It Fa hh_hashtab 465Offset of hash table. 466.It Fa hh_strtab 467Offset of string table. 468.It Fa hh_strtab_sz 469Size of strings. 470.It Fa hh_ehints 471Maximum usable offset in hints file. 472.El 473.Pp 474.Bd -literal -offset indent 475/* 476 * Hash table element in hints file. 477 */ 478struct hints_bucket { 479 int hi_namex; 480 int hi_pathx; 481 int hi_dewey[MAXDEWEY]; 482 int hi_ndewey; 483#define hi_major hi_dewey[0] 484#define hi_minor hi_dewey[1] 485 int hi_next; 486}; 487.Ed 488.Bl -tag -width hi_ndewey 489.It Fa hi_namex 490Index of the string identifying the library. 491.It Fa hi_pathx 492Index of the string representing the full path name of the library. 493.It Fa hi_dewey 494The version numbers of the shared library. 495.It Fa hi_ndewey 496The number of valid entries in 497.Fa hi_dewey. 498.It Fa hi_next 499Next bucket in case of hashing collisions. 500.El 501 502.Sh CAVEATS 503Only the GNU C compiler currently supports the creation of shared libraries. 504Other programming languages can not be used. 505 506