1.\" $OpenBSD: ldconfig.8,v 1.30 2020/05/08 11:04:50 jca 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: May 8 2020 $ 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 mRrsUv 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 m 95Merge the result of the scan of the directories given as arguments into 96the existing hints file. 97The default action is to build the hints file afresh. 98This option cannot be used with 99.Fl U . 100.It Fl R 101Rescan the previously configured directories. 102This opens the hints file and fetches the directory list from the header. 103Any additional pathnames on the command line are also processed. 104.It Fl r 105List the current contents of 106.Pa ld.so.hints 107on the standard output. 108The hints file will not be modified. 109.It Fl s 110Do not scan the built-in system directory 111.Pq Dq /usr/lib 112for shared libraries. 113.It Fl U 114Unconfigure directories specified on the command line or remove inaccessible 115directories from search path if no directories specified. 116This option cannot be used with 117.Fl m . 118.It Fl v 119Switch on verbose mode. 120.El 121.Sh SECURITY 122Special care must be taken when loading shared libraries into the address 123space of set-user-ID and set-group-ID programs. 124Whenever such a program is run, 125.Xr ld.so 1 126will only load shared libraries from the 127.Pa ld.so.hints 128file. 129In particular, the 130.Ev LD_LIBRARY_PATH 131is not used to search for libraries. 132Thus, the role of 133.Nm 134is dual. 135In addition to building a set of hints for quick lookup, it also serves to 136specify the trusted collection of directories from which shared objects can 137be safely loaded. 138It is presumed that the set of directories specified to 139.Nm 140are under control of the system's administrator. 141.Xr ld.so 1 142further assists set-user-ID and set-group-ID programs by erasing the 143.Ev LD_LIBRARY_PATH 144from the environment. 145.Sh ENVIRONMENT 146.Bl -tag -width Ds 147.It Ev LD_LIBRARY_PATH 148Additional directories containing shared libraries, 149settable in the user's environment. 150.It Ev shlib_dirs 151Additional directories containing shared libraries, 152settable in 153.Pa /etc/rc.conf.local . 154.El 155.Sh FILES 156.Bl -tag -width Ds -compact 157.It Pa /etc/rc.conf 158.It Pa /etc/rc.conf.local 159.It Pa /var/run/ld.so.hints 160.El 161.Sh SEE ALSO 162.Xr ld 1 , 163.Xr elf 5 , 164.Xr rc.conf 8 165.Sh HISTORY 166An 167.Nm 168utility first appeared in SunOS 4.0. 169It appeared in its current form in 170.Nx 0.9a . 171