xref: /freebsd/sbin/ldconfig/ldconfig.8 (revision 5b56413d04e608379c9a306373554a8e4d321bc0)
1.\"
2.\" Copyright (c) 1993 Paul Kranenburg
3.\" All rights reserved.
4.\" Copyright (c) 2021 The FreeBSD Foundation, Inc.
5.\"
6.\" Portions of this documentation were written by
7.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship
8.\" from the FreeBSD Foundation.
9.\"
10.\" Redistribution and use in source and binary forms, with or without
11.\" modification, are permitted provided that the following conditions
12.\" are met:
13.\" 1. Redistributions of source code must retain the above copyright
14.\"    notice, this list of conditions and the following disclaimer.
15.\" 2. Redistributions in binary form must reproduce the above copyright
16.\"    notice, this list of conditions and the following disclaimer in the
17.\"    documentation and/or other materials provided with the distribution.
18.\" 3. All advertising materials mentioning features or use of this software
19.\"    must display the following acknowledgement:
20.\"      This product includes software developed by Paul Kranenburg.
21.\" 3. The name of the author may not be used to endorse or promote products
22.\"    derived from this software without specific prior written permission
23.\"
24.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
25.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
26.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
27.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
28.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
29.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
30.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
31.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
32.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
33.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
34.\"
35.Dd April 20, 2024
36.Dt LDCONFIG 8
37.Os
38.Sh NAME
39.Nm ldconfig
40.Nd configure the dynamic linker search path for shared libraries
41.Sh SYNOPSIS
42.Nm
43.Op Fl 32
44.Op Fl BRimr
45.Op Fl f Ar hints_file
46.Op Ar directory | Ar
47.Sh DESCRIPTION
48.Nm
49utility is used to configure the set of paths used by the dynamic linker
50.Xr ld-elf.so.1 1
51when searching for shared libraries.
52The dynamic linker looks for libraries in a set of built-in system directories
53and any directories specified in the hints file.
54This obviates the need for storing search paths within the executable,
55see the
56.Fl rpath
57option for the static linker
58.Xr ld 1 .
59.Pp
60The hints file is maintained by
61.Nm .
62The
63.Ar directories
64list to be stored in the hints file is supplied on the command line.
65.Pp
66Alternatively to the
67.Ar directories
68list on the command line,
69.Ar files
70may be specified; these are expected to contain directories
71to scan for shared libraries.
72Each directory's pathname must start on a new
73line.
74Blank lines and lines starting with the comment character
75.Ql \&#
76are ignored.
77.Pp
78For security reasons, directories which are world or group-writable or which
79are not owned by root produce warning messages and are skipped, unless
80the
81.Fl i
82option is present.
83.Pp
84The
85.Ev LD_LIBRARY_PATH
86environment variable can be used to specify additional
87shared library search directories.
88.Ev LD_LIBRARY_PATH
89is a
90.Sq \&:
91separated list of directory paths which are searched by
92the dynamic linker
93when it needs to load a shared library.
94It can be viewed as the run-time
95equivalent of the
96.Fl L
97switch of
98.Xr ld 1 .
99.Pp
100The following options are recognized by
101.Nm :
102.Bl -tag -width indent
103.It Fl 32
104Generate the hints for 32-bit ABI shared libraries
105on 64-bit systems that support running 32-bit binaries.
106.It Fl elf
107Ignored for backwards compatibility.
108.It Fl B
109Force writing big-endian binary data to the hints file.
110The default is to create hints files in little-endian byte-order on all
111architectures.
112Reading of and merging into hints files preserves the endianness of the
113existing hints file.
114.It Fl R
115Appends pathnames on the command line to the directory list from
116the hints file.
117.Pp
118This is the default action when no options are given.
119.It Fl f Ar hints_file
120Read and/or update the specified hints file, instead of the standard file.
121This option is provided primarily for testing.
122.It Fl i
123Run in insecure mode.
124The security checks will not be performed.
125.It Fl m
126Instead of replacing the list of the directories to search with the
127directories specified on the command line, merge existing list
128with the specified directories, and write the result to the hints file.
129.It Fl r
130List the current list of the directories from the hints file
131on the standard output.
132The hints file is not modified.
133.Pp
134Scan and print all libraries found on the directories list.
135.El
136.Pp
137The historic options
138.Fl elf ,
139.Fl s ,
140and
141.Fl v
142are accepted but ignored.
143.Sh SECURITY
144Special care must be taken when loading shared libraries into the address
145space of
146.Ev set-user-Id
147programs.
148Whenever such a program is run by any user except the owner of the program,
149the dynamic linker will only load shared libraries from paths found in
150the hints file.
151In particular, the
152.Ev LD_LIBRARY_PATH
153is not used to search for libraries.
154Thus,
155.Nm
156serves to specify the trusted collection of directories from which
157shared objects can be safely loaded.
158.Sh FILES
159.Bl -tag -width /usr/local/libdata/ldconfig/* -compact
160.It Pa /var/run/ld-elf.so.hints
161Standard hints file for the ELF dynamic linker.
162.It Pa /var/run/ld-elf32.so.hints
163Hints file for 32 bit libraries on 64 bit architectures, processed by
164ldconfig when invoked with
165.Fl 32 .
166.It Pa /etc/ld-elf.so.conf
167Optional file with names of directories to be included in the standard
168hints file when booting to multi-user mode.
169.It Pa /usr/local/libdata/ldconfig/*
170Additional files with names of directories provided by optional ports
171or packages.
172.El
173.Sh SEE ALSO
174.Xr ld 1 ,
175.Xr ld-elf.so.1 1 ,
176.Xr link 5
177.Sh HISTORY
178A
179.Nm
180utility first appeared in SunOS 4.0, it appeared in its current form
181in
182.Fx 1.1 .
183.Pp
184The name 'hints file' is historic from the times when the file also contained
185hints to the dynamic linker.
186This functionality is not provided for ELF.
187