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