1.\" $NetBSD: ldconfig.8,v 1.14 2002/10/01 13:40:34 wiz Exp $ 2.\" 3.\" Copyright (c) 1998 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Paul Kranenburg. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd October 8, 2000 38.Dt LDCONFIG 8 39.Os 40.Sh NAME 41.Nm ldconfig 42.Nd configure the a.out shared library cache 43.Sh SYNOPSIS 44.Nm ldconfig 45.Op Fl cmrsSv 46.Op Ar directory Ar ... 47.Sh DESCRIPTION 48.Nm 49is used to prepare a set of 50.Dq hints 51for use by the a.out run-time linker 52.Nm ld.so 53to facilitate quick lookup of shared libraries available in multiple 54directories. 55.Nm 56is only available on systems that use the 57.Dq a.out 58format for executables and libraries \(en on ELF systems, all the work 59is done by 60.Nm ld.elf_so . 61.Pp 62By default, it scans a set of built-in system directories, 63directories listed in 64.Pa /etc/ld.so.conf , 65and any 66.Ar directories 67specified on the command line (in the given order) looking for shared 68libraries and stores the results in the file 69.Pa /var/run/ld.so.hints 70to forestall the overhead that would otherwise result from the 71directory search operations 72.Nm ld.so 73would have to perform to load required shared libraries. 74.Pp 75The shared libraries so found will be automatically available for loading 76if needed by the program being prepared for execution. 77This obviates the need for storing search paths within the executable. 78.Pp 79The 80.Ev LD_LIBRARY_PATH 81environment variable can be used to override the use of 82directories (or the order thereof) from the cache or to specify additional 83directories where shared libraries might be found. 84.Ev LD_LIBRARY_PATH 85is a 86.Sq \&: 87separated list of directory paths that are searched by 88.Nm ld.so 89when it needs to load a shared library. 90It can be viewed as the run-time equivalent of the 91.Fl L 92switch of 93.Nm ld . 94.Pp 95.Nm 96is typically run as part of the boot sequence. 97.Pp 98The following options are recognized by 99.Nm ldconfig : 100.Bl -tag -width indent 101.It Fl c 102Do not scan directories listed in 103.Pa /etc/ld.so.conf 104for shared libraries. 105.It Fl m 106Merge the result of the scan of the directories given as arguments into 107the existing hints file. 108The default action is to build the hints file afresh. 109.It Fl r 110Lists the current contents of 111.Pa ld.so.hints 112on the standard output. 113The hints file will not be modified. 114.It Fl s 115Do not scan the built-in system directory 116.Pq Pa /usr/lib , 117nor any directories listed in 118.Pa /etc/ld.so.conf 119for shared libraries. 120.It Fl S 121Do not scan the built-in system directory 122.Pq Pa /usr/lib , 123for shared libraries. 124(Directories listed in 125.Pa /etc/ld.so.conf 126are still scanned.) 127.It Fl v 128Switch on verbose mode. 129.El 130.Sh FILES 131.Pa /var/run/ld.so.hints , 132.Pa /etc/ld.so.conf 133.Sh SEE ALSO 134.Xr ld 1 , 135.Xr ld.so 1 , 136.Xr ld.so.conf 5 , 137.Xr link 5 138.Sh HISTORY 139A 140.Nm 141utility first appeared in SunOS 4.0, it appeared in its current form 142in 143.Nx 0.9a . 144.Sh SECURITY CONSIDERATIONS 145Special care must be taken when loading shared libraries into the address 146space of 147.Em set-user-ID 148programs. 149Whenever such a program is run, 150.Nm ld.so 151will only load shared libraries from the 152.Pa ld.so.hints 153file. 154In particular, the 155.Ev LD_LIBRARY_PATH 156and 157.Ev LD_PRELOAD 158is not used to search for libraries. 159Thus, the role of ldconfig is dual. 160In addition to building a set of hints for quick lookup, it also serves to 161specify the trusted collection of directories from which shared objects can 162be safely loaded. 163It is presumed that the set of directories specified to 164.Nm 165is under control of the system's administrator. 166.Nm ld.so 167further assists set-user-ID programs by erasing the 168.Ev LD_LIBRARY_PATH 169and 170.Ev LD_PRELOAD 171from the environment. 172