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 May 15, 2021 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 Rimrv 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 R 109Appends pathnames on the command line to the directory list from 110the hints file. 111.Pp 112This is the default action when no options are given. 113.It Fl f Ar hints_file 114Read and/or update the specified hints file, instead of the standard file. 115This option is provided primarily for testing. 116.It Fl i 117Run in insecure mode. 118The security checks will not be performed. 119.It Fl m 120Instead of replacing the list of the directories to search with the 121directories specified on the command line, merge existing list 122with the specified directories, and write the result to the hints file. 123.It Fl r 124List the current list of the directories from the hints file 125on the standard output. 126The hints file is not modified. 127.Pp 128Scan and print all libraries found on the directories list. 129.It Fl v 130Switch on verbose mode. 131.El 132.Sh SECURITY 133Special care must be taken when loading shared libraries into the address 134space of 135.Ev set-user-Id 136programs. 137Whenever such a program is run by any user except the owner of the program, 138the dynamic linker will only load shared libraries from paths found in 139the hints file. 140In particular, the 141.Ev LD_LIBRARY_PATH 142is not used to search for libraries. 143Thus, 144.Nm 145serves to specify the trusted collection of directories from which 146shared objects can be safely loaded. 147.Sh FILES 148.Bl -tag -width /var/run/ld-elf.so.hintsxxx -compact 149.It Pa /var/run/ld-elf.so.hints 150Standard hints file for the ELF dynamic linker. 151.It Pa /etc/ld-elf.so.conf 152Conventional configuration file containing directory names for 153invocations with 154.Fl elf . 155.It Pa /var/run/ld-elf32.so.hints 156Conventional configuration files containing directory names for 157invocations with 158.Fl 32 . 159.El 160.Sh SEE ALSO 161.Xr ld 1 , 162.Xr ld-elf.so.1 , 163.Xr link 5 164.Sh HISTORY 165A 166.Nm 167utility first appeared in SunOS 4.0, it appeared in its current form 168in 169.Fx 1.1 . 170.Pp 171The name 'hints file' is historic from the times when the file also contained 172hints to the dynamic linker. 173This functionality is not provided for ELF. 174