1.\" 2.\" Copyright (c) 1993 Paul Kranenburg 3.\" All rights reserved. 4.\" Copyright (c) 2021 The FreeBSD Foundation 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