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