| blob | 8f9782e752d84183673374062b307166e94761c3 |
1 .\" $NetBSD: ld.elf_so.1,v 1.11 2008/04/30 13:10:52 martin Exp $
2 .\"
3 .\" Copyright (c) 2001 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Nick Hudson.
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 May 18, 2007
31 .Dt LD.ELF_SO 1
32 .Os
33 .Sh NAME
34 .Nm ld.elf_so
35 .Nd run-time link-editor (linker)
36 .Sh DESCRIPTION
37 .Nm
38 is a self-contained, position independent program
39 image providing run-time support for loading and
40 link-editing shared objects into a process' address space.
41 It uses information stored in data structures within the binary (see
42 .Xr elf 5 )
43 and environment variables to determine which shared objects are needed.
44 These shared objects are loaded at a convenient virtual address using the
45 .Xr mmap 2
46 system call.
47 After all shared objects have been successfully loaded,
48 .Nm
49 proceeds to resolve external references from both
50 the main program and all objects loaded.
51 Once all required references are resolved control is
52 passed to the program via its entry point.
53 .Ss Startup
54 On the execution of a dynamically linked binary the kernel will load
55 the program and its run-time linker as specified in the PT_INTERP
56 section in the program header.
57 At this point, instead of passing control directly to the program,
58 the kernel passes control to the specified linker.
59 An auxiliary vector of information is passed that includes
60 the address of the program header, the size of each entry in the header,
61 and the number of entries.
62 The entry point of the program and the base address of where
63 .Nm
64 is loaded is also supplied.
65 .Pp
66 Careful use of code allows
67 .Nm
68 to relocate itself before proceeding.
69 Specifically the use of global variables and
70 large switch statements is not allowed.
71 The later can cause the output of a jump table that
72 can use the equivalent of a global variable.
73 .Ss Finding objects
74 Each
75 .Xr elf 5
76 object file may contain information in its dynamic (PT_DYNAMIC) section
77 about which shared objects it requires (often referred to as dependencies).
78 These dependencies are specified in the optional DT_NEEDED entry within
79 the dynamic section.
80 Each DT_NEEDED entry refers to a filename string of
81 the shared object that is to be searched for.
82 .Pp
83 The linker will search for libraries in three lists of paths:
84 .Bl -enum
85 .It
86 A user defined list of paths as specified in LD_LIBRARY_PATH and
87 .Xr ld.so.conf 5 .
88 .Pp
89 The use of ld.so.conf should be avoided as the setting of a global search
90 path can present a security risk.
91 .It
92 A list of paths specified within a shared object using a DT_RPATH entry in
93 the dynamic section.
94 This is defined at shared object link time.
95 .It
96 The list of default paths which is set to
97 .Pa /usr/lib .
98 .El
99 .Pp
100 .Nm
101 will expand the following variables if present in the paths:
102 .Bl -tag -width $PLATFORM
103 .It $HWCAP
104 Processor hardware capabilities, for example FPU, MMX, SSE.
105 Currently unimplemented.
106 .It $ISALIST
107 List of instructions sets this processor can execute.
108 Currently unimplemented.
109 .It $ORIGIN
110 The directory of the main object.
111 .It $OSNAME
112 The value of the
113 .Dv kern.ostype
114 .Xr sysctl 3 .
115 .It $OSREL
116 The value of the
117 .Dv kern.osrelease
118 .Xr sysctl 3 .
119 .It $PLATFORM
120 The value of the
121 .Dv hw.machine_arch
122 .Xr sysctl 3 .
123 .El
124 .Pp
125 Both
126 .Dv ${VARIABLE}
127 and
128 .Dv $VARIABLE
129 are recognized.
130 .Pp
131 The filename string can be considered free form, however, it will almost
132 always take the form lib\*[Lt]name\*[Gt].so.\*[Lt]number\*[Gt],
133 where name specifies the
134 .Sq library
135 name and number is conceptually the library's major version number.
136 .Pp
137 This name and another of the form lib\*[Lt]name\*[Gt].so are normally
138 symbolic links to the real shared object which has a filename of the form
139 lib\*[Lt]name\*[Gt].so.\*[Lt]major\*[Gt].\*[Lt]minor\*[Gt][.\*[Lt]teeny\*[Gt]].
140 This naming convention allows a versioning scheme similar to
141 .Xr a.out 5 .
142 .Ss Relocation
143 .Nm
144 will perform all necessary relocations immediately except for relocations
145 relating to the Procedure Linkage Table (PLT).
146 The PLT is used as a indirection method for procedure
147 calls to globally defined functions.
148 It allows, through the use of intermediate code, the delayed binding of
149 a call to a globally defined function to be performed at procedure call time.
150 This
151 .Sq lazy
152 method is the default (see LD_BIND_NOW).
153 .Ss Initialization
154 A mechanism is provided for initialization and termination routines
155 to be called, on a per-object basis before execution of the program proper
156 begins or after the program has completed.
157 This gives a shared object an opportunity to perform
158 any extra set-up or completion work.
159 .Pp
160 The DT_INIT and DT_FINI entries in the dynamic section specify the addresses
161 of the initialization and termination functions, respectively, for
162 the shared object.
163 .Nm
164 arranges for each initialization function to be called before control is passed
165 to the program and for the termination functions to be called by using
166 .Xr atexit 3 .
167 .Pp
168 This mechanism is exploited by the system-supplied constructor
169 initialization and destructor code located in
170 .Pa /usr/lib/crtbeginS.o
171 and
172 .Pa /usr/lib/crtendS.o .
173 These files are automatically included by
174 .Xr cc 1
175 and
176 .Xr c++ 1
177 in the list of object-code files passed to
178 .Xr ld 1
179 when building a shared C or C++ object.
180 .Sh ENVIRONMENT
181 If the following environment variables exist they will be used by
182 .Nm .
183 .Bl -tag -width "LD_LIBRARY_PATH"
184 .It Ev LD_LIBRARY_PATH
185 A colon separated list of directories, overriding the default search path
186 for shared libraries.
187 .It Ev LD_PRELOAD
188 A colon or space separated list of shared object filenames to be loaded
189 .Em after
190 the main program but
191 .Em before
192 its shared object dependencies.
193 Space is allowed as a separator for backwards compatibility only.
194 Support may be removed in a future release and should not be relied upon.
195 .It Ev LD_BIND_NOW
196 If defined immediate binding of Procedure Link Table (PLT) entries is
197 performed instead of the default lazy method.
198 .It Ev LD_DEBUG
199 If defined a variety of debug information will be written to the standard
200 error of an dynamically linked executed when it is run.
201 This variable is only recognized if
202 .Nm
203 was compiled with debugging support
204 .Sy ( -DDEBUG ) .
205 .El
206 .Sh FILES
207 .Bl -tag -width /etc/ld.so.conf -compact
208 .It Pa /etc/ld.so.conf
209 library location hints supplied by the system administrator.
210 .El
211 .Sh SEE ALSO
212 .Xr ld 1 ,
213 .Xr ld.aout_so 1 ,
214 .Xr dlfcn 3 ,
215 .Xr elf 5
216 .Sh HISTORY
217 The ELF shared library model employed first appeared in Sys V R4.
218 .Pp
219 The path expansion variables first appeared in Solaris 10, and
220 in
221 .Nx 5.0 .
222 .Sh SECURITY CONSIDERATIONS
223 The environment variables
224 .Ev LD_LIBRARY_PATH
225 and
226 .Ev LD_PRELOAD
227 are not honored when executing in a set-user-ID or set-group-ID environment.
228 This action is taken to prevent malicious substitution of shared object
229 dependencies or interposition of symbols.