Annotation of src/libexec/ld.aout_so/ld.aout_so.1, Revision 1.7.30.1
1.7.30.1! yamt 1: .\" $NetBSD: ld.aout_so.1,v 1.7 2003/06/26 18:09:39 wiz Exp $
1.1 wiz 2: .\"
3: .\" Copyright (c) 1998 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: .\"
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 March 24, 2000
31: .Dt LD.AOUT_SO 1
32: .Os
33: .Sh NAME
34: .Nm ld.so
35: .Nd run-time link-editor
36: .Sh DESCRIPTION
37: .Nm
1.4 wiz 38: is a self-contained, position independent program image
39: providing run-time support for loading and link-editing
40: shared objects into a process' address space.
41: It uses the data structures
1.1 wiz 42: .Po
43: see
44: .Xr link 5
45: .Pc
46: contained within dynamically linked programs to determine which shared
47: libraries are needed and loads them at a convenient virtual address
48: using the
49: .Xr mmap 2
50: system call.
51: .Pp
52: After all shared libraries have been successfully loaded,
53: .Nm
54: proceeds to resolve external references from both the main program and
1.4 wiz 55: all objects loaded.
1.5 perry 56: A mechanism is provided for initialization routines to be called,
1.4 wiz 57: on a per-object basis, giving a shared object an opportunity
1.1 wiz 58: to perform any extra set-up, before execution of the program proper begins.
59: .Nm
60: looks for a symbol named
61: .Em .init
1.4 wiz 62: in each object's symbol table.
63: If present, this symbol is assumed to represent a C-function declared as
1.1 wiz 64: .Ft void
65: .Fn .init "void" ,
1.4 wiz 66: which is then called.
67: Similarly, a
1.1 wiz 68: .Ft void
69: .Fn .fini "void"
70: function is called just before an object is unloaded from the process
71: address space as a result of calling
72: .Xr dlclose 3 .
73: Note that while an object's
74: .Em .init
75: is always called, whether the object is loaded automatically at program
1.5 perry 76: startup or programmatically by using
1.1 wiz 77: .Xr dlopen 3 ,
78: the
79: .Em .fini
80: function is called only on
81: .Sq last Xr dlclose 3 .
82: .Pp
83: This mechanism is exploited by the system-supplied C++ constructor
84: initialization code located in
85: .Pa /usr/lib/c++rt.o .
86: This file should be included in the list of object-code files passed to
87: .Xr ld 1
88: when building a shared C++ library.
89: .Pp
90: .Nm
91: is itself a shared object that is initially loaded by the startup module
92: .Em crt0 .
93: Since
94: .Xr a.out 5
95: formats do not provide easy access to the file header from within a running
96: process,
97: .Em crt0
98: uses the special symbol
99: .Va _DYNAMIC
1.4 wiz 100: to determine whether a program is in fact dynamically linked or not.
101: Whenever the linker
1.1 wiz 102: .Xr ld 1
103: has relocated this symbol to a location other than 0,
104: .Em crt0
105: assumes the services of
106: .Nm
107: are needed
108: .Po
109: see
110: .Xr link 5
111: for details
1.6 wiz 112: .Pc .
1.1 wiz 113: .Em crt0
114: passes control to
115: .Nm rtld Ns 's
116: entry point before the program's
117: .Fn main
1.4 wiz 118: routine is called.
119: Thus,
1.1 wiz 120: .Nm
121: can complete the link-editing process before the dynamic program calls upon
122: services of any dynamic library.
123: .Pp
124: To quickly locate the required shared objects in the filesystem,
125: .Nm
126: may use a
127: .Dq hints
128: file, prepared by the
129: .Xr ldconfig 8
130: utility, in which the full path specification of the shared objects can be
131: looked up by hashing on the 3-tuple
132: .Ao
133: library-name, major-version-number, minor-version-number
134: .Ac Ns \&.
135: .Pp
136: .Nm
1.5 perry 137: recognizes a number of environment variables that can be used to modify
138: its behavior as follows:
1.1 wiz 139: .Pp
1.3 ross 140: .Bl -tag -width LD_TRACE_LOADED_OBJECTS \" intentionally not the longest
1.1 wiz 141: .It Ev LD_LIBRARY_PATH
142: A colon separated list of directories, overriding the default search path
143: for shared libraries.
144: .It Ev LD_PRELOAD
145: A colon separated list of shared object filenames to be loaded
146: .Em after
147: the main program but
148: .Em before
149: its shared object dependencies.
150: .It Ev LD_WARN_NON_PURE_CODE
151: When set, issue a warning whenever a link-editing operation requires
1.4 wiz 152: modification of the text segment of some loaded object.
153: This is usually indicative of an incorrectly built library.
1.1 wiz 154: .It Ev LD_SUPPRESS_WARNINGS
1.4 wiz 155: When set, no warning messages of any kind are issued.
156: Normally, a warning is given if satisfactorily versioned
157: library could not be found.
1.1 wiz 158: .It Ev LD_TRACE_LOADED_OBJECTS
159: When set, causes
160: .Nm
161: to exit after loading the shared objects and printing a summary which includes
162: the absolute pathnames of all objects, to standard output.
163: .It Ev LD_TRACE_LOADED_OBJECTS_FMT1
164: .It Ev LD_TRACE_LOADED_OBJECTS_FMT2
165: When set, these variables are interpreted as format strings a la
166: .Xr printf 3
167: to customize the trace output and are used by
1.7 wiz 168: .Xr ldd 1 Ns 's
1.1 wiz 169: .Fl f
170: option and allows
171: .Xr ldd 1
172: to be operated as a filter more conveniently.
173: The following conversions can be used:
1.3 ross 174: .Bl -tag -width xxxx
1.1 wiz 175: .It \&%a
176: The main program's name
177: .Po also known as
178: .Dq __progname
179: .Pc .
180: .It \&%A
181: The value of the environment variable
182: .Ev LD_TRACE_LOADED_OBJECTS_PROGNAME
183: .It \&%o
184: The library name.
185: .It \&%m
186: The library's major version number.
187: .It \&%n
188: The library's minor version number.
189: .It \&%p
190: The full pathname as determined by
191: .Nm rtld Ns 's
192: library search rules.
193: .It \&%x
194: The library's load address.
195: .El
196: .Pp
197: Additionally,
198: .Sy \en
199: and
200: .Sy \et
1.5 perry 201: are recognized and have their usual meaning.
1.1 wiz 202: .It Ev LD_NO_INTERN_SEARCH
203: When set,
204: .Nm
205: does not process any internal search paths that were recorded in the
206: executable.
207: .It Ev LD_NOSTD_PATH
208: When set, do not include a set of built-in standard directory paths for
1.4 wiz 209: searching.
210: This might be useful when running on a system with a completely
1.1 wiz 211: non-standard filesystem layout.
212: .El
213: .Sh FILES
214: .Bl -tag -width /var/run/ld.so.hintsXXX -compact
215: .It Pa /var/run/ld.so.hints
216: library location hints built by
217: .Xr ldconfig 8
218: .El
219: .Sh SEE ALSO
220: .Xr ld 1 ,
221: .Xr ld.elf_so 1 ,
222: .Xr ld.so 1 ,
223: .Xr link 5 ,
224: .Xr ldconfig 8
225: .Sh HISTORY
226: The shared library model employed first appeared in SunOS 4.0.
227: .Sh SECURITY CONSIDERATIONS
228: The environment variables
229: .Ev LD_LIBRARY_PATH
230: and
231: .Ev LD_PRELOAD
232: are not honored when executing in a set-user-ID or set-group-ID environment.
233: This action is taken to prevent malicious substitution of shared object
234: dependencies or interposition of symbols.
CVSweb <webmaster@jp.NetBSD.org>