xref: /freebsd/sbin/ldconfig/ldconfig.8 (revision ef5d438ed4bc17ad7ece3e40fe4d1f9baf3aadf7)
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.\"	$Id: ldconfig.8,v 1.6 1994/12/23 22:31:21 nate Exp $
31.\"
32.Dd October 3, 1993
33.Dt LDCONFIG 8
34.Os FreeBSD
35.Sh NAME
36.Nm ldconfig
37.Nd configure the shared library cache
38.Sh SYNOPSIS
39.Nm ldconfig
40.Op Fl mrsv
41.Op Ar directory Ar ...
42.Sh DESCRIPTION
43.Nm
44is used to prepare a set of
45.Dq hints
46for use by the run-time linker
47.Xr ld.so
48to facilitate quick lookup of shared libraries available in multiple
49directories.  It scans a set of built-in system directories and any
50.Ar directories
51specified on the command line (in the given order) looking for shared
52libraries and stores the results in the file
53.Xr /var/run/ld.so.hints
54to forestall the overhead that would otherwise result from the
55directory search operations
56.Xr ld.so
57would have to perform to load the required shared libraries.
58.Pp
59The shared libraries so found will be automatically available for loading
60if needed by the program being prepared for execution. This obviates the need
61for storing search paths within the executable.
62.Pp
63The
64.Ev LD_LIBRARY_PATH
65environment variable can be used to override the use of
66directories (or the order thereof) from the cache or to specify additional
67directories where shared libraries might be found.
68.Ev LD_LIBRARY_PATH
69is a
70.Sq \:
71separated list of directory paths which are searched by
72.Xr ld.so
73when it needs to load a shared library. It can be viewed as the run-time
74equivalent of the
75.Fl L
76switch of
77.Xr ld.
78.Pp
79.Nm Ldconfig
80is typically run as part of the boot sequence.
81.Pp
82The following options recognized by
83.Nm ldconfig:
84.Bl -tag -width indent
85.It Fl m
86Instead of replacing the contents of
87.Xr ld.so.hints
88with those found in the directories specified,
89.Dq merge
90in new entries.
91.It Fl r
92Lists the current contents of
93.Xr ld.so.hints
94on the standard output. The hints file will not be modified.
95.It Fl s
96Do not scan the built-in system directory
97.Pq Dq /usr/lib
98for shared libraries.
99.It Fl v
100Switch on verbose mode.
101.Sh Security
102Special care must be taken when loading shared libraries into the address
103space of
104.Ev set-user-Id
105programs. Whenever such a program is run,
106.Xr ld.so
107will only load shared libraries from the
108.Ev ld.so.hints
109file. In particular, the
110.Ev LD_LIBRARY_PATH
111is not used to search for libraries. Thus, the role of ldconfig is dual. In
112addition to building a set of hints for quick lookup, it also serves to
113specify the trusted collection of directories from which shared objects can
114be safely loaded. It is presumed that the set of directories specified to
115.Nm ldconfig
116are under control of the system's administrator.
117.Xr ld.so
118further assists set-user-Id programs by erasing the
119.Ev LD_LIBRARY_PATH
120from the environment.
121
122.Sh FILES
123.Xr /var/run/ld.so.hints
124.Sh SEE ALSO
125.Xr ld 1 ,
126.Xr link 5
127.Sh HISTORY
128A
129.Nm
130utility first appeared in SunOS 4.0, it appeared in its current form
131in FreeBSD 1.1.
132