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. 52It scans a set of built-in system directories and any 53.Ar directories 54specified on the command line (in the given order) looking for 55shared libraries and stores the results in a system file to forestall 56the overhead that would otherwise result from the directory search 57operations the dynamic linker would have to perform to load the 58required shared libraries. 59.Pp 60Files named on the command line are expected to contain directories 61to scan for shared libraries. 62Each directory's pathname must start on a new 63line. 64Blank lines and lines starting with the comment character 65.Ql \&# 66are ignored. 67Filenames must conform to the 68.Pa lib*.so.[0-9] 69pattern in order to be added to the hints file. 70.Pp 71For security reasons, directories which are world or group-writable or which 72are not owned by root produce warning messages and are skipped, unless 73the 74.Fl i 75option is present. 76.Pp 77The shared libraries which are found will be automatically available for loading 78if needed by the program being prepared for execution. 79This obviates the need 80for storing search paths within the executable. 81.Pp 82The 83.Ev LD_LIBRARY_PATH 84environment variable can be used to override the use of 85directories (or the order thereof) from the cache or to specify additional 86directories where shared libraries might be found. 87.Ev LD_LIBRARY_PATH 88is a 89.Sq \&: 90separated list of directory paths which are searched by 91the dynamic linker 92when it needs to load a shared library. 93It can be viewed as the run-time 94equivalent of the 95.Fl L 96switch of 97.Xr ld 1 . 98.Pp 99The 100.Nm 101utility is typically run as part of the boot sequence. 102.Pp 103The following options are recognized by 104.Nm : 105.Bl -tag -width indent 106.It Fl aout 107Generate the hints for a.out format shared libraries. 108.It Fl elf 109Generate the hints for ELF format shared libraries. 110.It Fl R 111Rescan the previously configured directories. 112This opens the previous hints 113file and fetches the directory list from the header. 114Any additional pathnames 115on the command line are also processed. 116This is the default action when no parameters are given. 117.It Fl f Ar hints_file 118Read and/or update the specified hints file, instead of the standard file. 119This option is provided primarily for testing. 120.It Fl i 121Run in insecure mode. 122The security checks will not be performed. 123.It Fl m 124Instead of replacing the contents of the hints file 125with those found in the directories specified, 126.Dq merge 127in new entries. 128Directories recorded in the hints file by previous runs of 129.Nm 130are also rescanned for new shared libraries. 131.It Fl r 132List the current contents of the hints file 133on the standard output. 134The hints file is not modified. 135The list of 136directories stored in the hints file is included. 137.It Fl s 138Do not scan the built-in system directory 139.Pq Dq /usr/lib 140for shared libraries. 141.It Fl v 142Switch on verbose mode. 143.El 144.Sh SECURITY 145Special care must be taken when loading shared libraries into the address 146space of 147.Ev set-user-Id 148programs. 149Whenever such a program is run by any user except the owner of the program, 150the dynamic linker 151will only load shared libraries from the hints 152file. 153In particular, the 154.Ev LD_LIBRARY_PATH 155is not used to search for libraries. 156Thus, the role of ldconfig is dual. 157In 158addition to building a set of hints for quick lookup, it also serves to 159specify the trusted collection of directories from which shared objects can 160be safely loaded. 161.Sh ENVIRONMENT 162.Bl -tag -width OBJFORMATxxx -compact 163.It Ev OBJFORMAT 164Overrides 165.Pa /etc/objformat 166(see below) to determine whether 167.Fl aout 168or 169.Fl elf 170is the default. 171If set, its value should be either 172.Ql aout 173or 174.Ql elf . 175.El 176.Sh FILES 177.Bl -tag -width /var/run/ld-elf.so.hintsxxx -compact 178.It Pa /var/run/ld.so.hints 179Standard hints file for the a.out dynamic linker. 180.It Pa /var/run/ld-elf.so.hints 181Standard hints file for the ELF dynamic linker. 182.It Pa /etc/ld.so.conf 183Conventional configuration file containing directory names for 184invocations with 185.Fl aout . 186.It Pa /etc/ld-elf.so.conf 187Conventional configuration file containing directory names for 188invocations with 189.Fl elf . 190.It Pa /etc/objformat 191Determines whether 192.Fl aout 193or 194.Fl elf 195is the default. 196If present, it must consist of a single line 197containing either 198.Ql OBJFORMAT=aout 199or 200.Ql OBJFORMAT=elf . 201.El 202.Sh SEE ALSO 203.Xr ld 1 , 204.Xr link 5 205.Sh HISTORY 206A 207.Nm 208utility first appeared in SunOS 4.0, it appeared in its current form 209in 210.Fx 1.1 . 211.Sh BUGS 212Some security checks (for example, verifying root ownership of 213added directories) are not performed when 214.Fl aout 215is specified. 216