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