xref: /freebsd/sbin/ldconfig/ldconfig.8 (revision 71fe318b852b8dfb3e799cb12ef184750f7f8eac)
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.\" $FreeBSD$
31.\"
32.Dd October 3, 1993
33.Dt LDCONFIG 8
34.Os
35.Sh NAME
36.Nm ldconfig
37.Nd configure the shared library cache
38.Sh SYNOPSIS
39.Nm
40.Op Fl aout | Fl elf
41.Op Fl Rimrsv
42.Op Fl f Ar hints_file
43.Op Ar directory | Ar
44.Sh DESCRIPTION
45The
46.Nm
47utility is used to prepare a set of
48.Dq hints
49for use by the dynamic linker
50to facilitate quick lookup of shared libraries available in multiple
51directories.  It scans a set of built-in system directories and any
52.Ar directories
53specified on the command line (in the given order) looking for
54shared libraries and stores the results in a system file to forestall
55the overhead that would otherwise result from the directory search
56operations the dynamic linker would have to perform to load the
57required shared libraries.
58.Pp
59Files named on the command line are expected to contain directories
60to scan for shared libraries.  Each directory's pathname must start on a new
61line.  Blank lines and lines starting with the comment character
62.Ql \&#
63are ignored.
64.Pp
65For security reasons, directories which are world or group-writable or which
66are not owned by root produce warning messages and are skipped, unless
67the
68.Fl i
69option is present.
70.Pp
71The shared libraries which are found will be automatically available for loading
72if needed by the program being prepared for execution.
73This obviates the need
74for storing search paths within the executable.
75.Pp
76The
77.Ev LD_LIBRARY_PATH
78environment variable can be used to override the use of
79directories (or the order thereof) from the cache or to specify additional
80directories where shared libraries might be found.
81.Ev LD_LIBRARY_PATH
82is a
83.Sq \&:
84separated list of directory paths which are searched by
85the dynamic linker
86when it needs to load a shared library.
87It can be viewed as the run-time
88equivalent of the
89.Fl L
90switch of
91.Xr ld 1 .
92.Pp
93The
94.Nm
95utility is typically run as part of the boot sequence.
96.Pp
97The following options are recognized by
98.Nm :
99.Bl -tag -width indent
100.It Fl aout
101Generate the hints for a.out format shared libraries.
102.It Fl elf
103Generate the hints for ELF format shared libraries.
104.It Fl R
105Rescan the previously configured directories.  This opens the previous hints
106file and fetches the directory list from the header.  Any additional pathnames
107on the command line are also processed.
108This is the default action when no parameters are given.
109.It Fl f Ar hints_file
110Read and/or update the specified hints file, instead of the standard file.
111This option is provided primarily for testing.
112.It Fl i
113Run in insecure mode. The security checks will not be performed.
114.It Fl m
115Instead of replacing the contents of the hints file
116with those found in the directories specified,
117.Dq merge
118in new entries.
119Directories recorded in the hints file by previous runs of
120.Nm
121are also rescanned for new shared libraries.
122.It Fl r
123List the current contents of the hints file
124on the standard output.
125The hints file is not modified.  The list of
126directories stored in the hints file is included.
127.It Fl s
128Do not scan the built-in system directory
129.Pq Dq /usr/lib
130for shared libraries.
131.It Fl v
132Switch on verbose mode.
133.El
134.Sh SECURITY
135Special care must be taken when loading shared libraries into the address
136space of
137.Ev set-user-Id
138programs.
139Whenever such a program is run by any user except the owner of the program,
140the dynamic linker
141will only load shared libraries from the hints
142file.
143In particular, the
144.Ev LD_LIBRARY_PATH
145is not used to search for libraries.
146Thus, the role of ldconfig is dual.
147In
148addition to building a set of hints for quick lookup, it also serves to
149specify the trusted collection of directories from which shared objects can
150be safely loaded.
151.Sh ENVIRONMENT
152.Bl -tag -width OBJFORMATxxx -compact
153.It Ev OBJFORMAT
154Overrides
155.Pa /etc/objformat
156(see below) to determine whether
157.Fl aout
158or
159.Fl elf
160is the default.  If set, its value should be either
161.Ql aout
162or
163.Ql elf .
164.El
165.Sh FILES
166.Bl -tag -width /var/run/ld-elf.so.hintsxxx -compact
167.It Pa /var/run/ld.so.hints
168Standard hints file for the a.out dynamic linker.
169.It Pa /var/run/ld-elf.so.hints
170Standard hints file for the ELF dynamic linker.
171.It Pa /etc/ld.so.conf
172Conventional configuration file containing directory names for
173invocations with
174.Fl aout .
175.It Pa /etc/ld-elf.so.conf
176Conventional configuration file containing directory names for
177invocations with
178.Fl elf .
179.It Pa /etc/objformat
180Determines whether
181.Fl aout
182or
183.Fl elf
184is the default.  If present, it must consist of a single line
185containing either
186.Ql OBJFORMAT=aout
187or
188.Ql OBJFORMAT=elf .
189.El
190.Sh SEE ALSO
191.Xr ld 1 ,
192.Xr link 5
193.Sh HISTORY
194A
195.Nm
196utility first appeared in SunOS 4.0, it appeared in its current form
197in
198.Fx 1.1 .
199.Sh BUGS
200Some security checks (for example, verifying root ownership of
201added directories) are not performed when
202.Fl aout
203is specified.
204