1.\" $OpenBSD: ldconfig.8,v 1.27 2013/07/10 06:43:38 jmc Exp $ 2.\" 3.\" Copyright (c) 1993,1995 Paul Kranenburg 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by Paul Kranenburg. 17.\" 3. The name of the author may not be used to endorse or promote products 18.\" derived from this software without specific prior written permission 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 21.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 22.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 23.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 24.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 25.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 29.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30.\" 31.\" 32.Dd $Mdocdate: July 10 2013 $ 33.Dt LDCONFIG 8 34.Os 35.Sh NAME 36.Nm ldconfig 37.Nd configure the shared library cache 38.Sh SYNOPSIS 39.Nm ldconfig 40.Op Fl DmPRrSsUv 41.Op Ar path ... 42.Sh DESCRIPTION 43.Nm 44is used to prepare a set of 45.Dq hints 46for use by the run-time linker 47.Xr ld.so 1 48to facilitate quick lookup of shared libraries available in multiple 49directories. 50It scans a set of built-in system directories and any 51.Ar directories 52specified on the command line (in the given order) looking for shared 53libraries and stores the results in the file 54.Pa /var/run/ld.so.hints 55to forestall the overhead that would otherwise result from the 56directory search operations 57.Xr ld.so 1 58would have to perform to load the required shared libraries. 59.Pp 60The shared libraries so found will be automatically available for loading 61if needed by the program being prepared for execution. 62This obviates the need for storing search paths within the executable. 63.Pp 64The 65.Ev LD_LIBRARY_PATH 66environment variable can be used to override the use of 67directories (or the order thereof) from the cache or to specify additional 68directories where shared libraries might be found. 69.Ev LD_LIBRARY_PATH 70is a 71.Sq \&: 72separated list of directory paths which are searched by 73.Xr ld.so 1 74when it needs to load a shared library. 75It can be viewed as the run-time equivalent of the 76.Fl L 77switch of 78.Xr ld 1 . 79.Pp 80.Nm 81is typically run as part of the boot sequence. 82In addition to the built-in system directories, 83directories containing shared libraries may be specified via the 84.Ev shlib_dirs 85variable in 86.Pa /etc/rc.conf.local . 87See 88.Xr rc.conf 8 89for further information. 90.Pp 91The following options are recognized by 92.Nm ldconfig : 93.Bl -tag -width indent 94.It Fl D 95Remove any prebind information in the specified binary or shared library. 96.It Fl m 97Merge the result of the scan of the directories given as arguments into 98the existing hints file. 99The default action is to build the hints file afresh. 100This option cannot be used with 101.Fl U . 102.It Fl P 103Create and append prebind information to all executables found in 104the specified directories, and also all shared libraries which are 105required by those executables. 106.It Fl R 107Rescan the previously configured directories. 108This opens the hints file and fetches the directory list from the header. 109Any additional pathnames on the command line are also processed. 110.It Fl r 111List the current contents of 112.Pa ld.so.hints 113on the standard output. 114The hints file will not be modified. 115.It Fl S 116Perform prelinking operations in a safe mode; always copies the binaries 117when prelinking data is added to a file. 118Use this to eliminate the possibility that 119.Dv ETXTBUSY 120will occur when attempting to run a binary while prelinking 121is running. 122.It Fl s 123Do not scan the built-in system directory 124.Pq Dq /usr/lib 125for shared libraries. 126.It Fl U 127Unconfigure directories specified on the command line or remove inaccessible 128directories from search path if no directories specified. 129This option cannot be used with 130.Fl m . 131.It Fl v 132Switch on verbose mode. 133.El 134.Sh PREBINDING 135Prebinding is loosely based on an earlier concept called Prelinking, which 136also accelerated 137.Xr ld.so 1 138performance but simultaneously impaired address space randomization. 139When prebinding information is added to libraries and programs using 140.Fl P , 141program startup can be significantly improved because 142.Xr ld.so 1 143can initialize the shared library environment much faster. 144Prebinding information adds a small amount of data to the end of each 145specified program and associated shared libraries. 146.Sh SECURITY 147Special care must be taken when loading shared libraries into the address 148space of 149.Ev set-user-Id 150programs. 151Whenever such a program is run, 152.Xr ld.so 1 153will only load shared libraries from the 154.Pa ld.so.hints 155file. 156In particular, the 157.Ev LD_LIBRARY_PATH 158is not used to search for libraries. 159Thus, the role of 160.Nm 161is dual. 162In addition to building a set of hints for quick lookup, it also serves to 163specify the trusted collection of directories from which shared objects can 164be safely loaded. 165It is presumed that the set of directories specified to 166.Nm 167are under control of the system's administrator. 168.Xr ld.so 1 169further assists set-user-Id programs by erasing the 170.Ev LD_LIBRARY_PATH 171from the environment. 172.Sh ENVIRONMENT 173.Bl -tag -width Ds 174.It Ev LD_LIBRARY_PATH 175Additional directories containing shared libraries, 176settable in the user's environment. 177.It Ev shlib_dirs 178Additional directories containing shared libraries, 179settable in 180.Pa /etc/rc.conf.local . 181.El 182.Sh FILES 183.Bl -tag -width Ds -compact 184.It Pa /etc/rc.conf 185.It Pa /etc/rc.conf.local 186.It Pa /var/run/ld.so.hints 187.El 188.Sh SEE ALSO 189.Xr ld 1 , 190.Xr elf 5 , 191.Xr rc.conf 8 192.Sh HISTORY 193An 194.Nm 195utility first appeared in SunOS 4.0. 196It appeared in its current form in 197.Nx 0.9a . 198