sbin/ldconfig/ldconfig.8

   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 .\"
  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
  42 is used to prepare a set of
  43 .Dq hints
  44 for use by the a.out run-time linker
  45 .Nm ld.so
  46 to facilitate quick lookup of shared libraries available in multiple
  47 directories.
  48 .Nm
  49 is only available on systems that use the
  50 .Dq a.out
  51 format for executables and libraries \(en on ELF systems, all the work
  52 is done by
  53 .Nm ld.elf_so .
  54 .Pp
  55 By default, it scans a set of built-in system directories,
  56 directories listed in
  57 .Pa /etc/ld.so.conf ,
  58 and any
  59 .Ar directories
  60 specified on the command line (in the given order) looking for shared
  61 libraries and stores the results in the file
  62 .Pa /var/run/ld.so.hints
  63 to forestall the overhead that would otherwise result from the
  64 directory search operations
  65 .Nm ld.so
  66 would have to perform to load required shared libraries.
  67 .Pp
  68 The shared libraries so found will be automatically available for loading
  69 if needed by the program being prepared for execution.
  70 This obviates the need for storing search paths within the executable.
  71 .Pp
  72 The
  73 .Ev LD_LIBRARY_PATH
  74 environment variable can be used to override the use of
  75 directories (or the order thereof) from the cache or to specify additional
  76 directories where shared libraries might be found.
  77 .Ev LD_LIBRARY_PATH
  78 is a
  79 .Sq \&:
  80 separated list of directory paths that are searched by
  81 .Nm ld.so
  82 when it needs to load a shared library.
  83 It can be viewed as the run-time equivalent of the
  84 .Fl L
  85 switch of
  86 .Nm ld .
  87 .Pp
  88 .Nm
  89 is typically run as part of the boot sequence.
  90 .Pp
  91 The following options are recognized by
  92 .Nm ldconfig :
  93 .Bl -tag -width indent
  94 .It Fl c
  95 Do not scan directories listed in
  96 .Pa /etc/ld.so.conf
  97 for shared libraries.
  98 .It Fl m
  99 Merge the result of the scan of the directories given as arguments into
 100 the existing hints file.
 101 The default action is to build the hints file afresh.
 102 .It Fl r
 103 Lists the current contents of
 104 .Pa ld.so.hints
 105 on the standard output.
 106 The hints file will not be modified.
 107 .It Fl s
 108 Do not scan the built-in system directory
 109 .Pq Pa /usr/lib ,
 110 nor any directories listed in
 111 .Pa /etc/ld.so.conf
 112 for shared libraries.
 113 .It Fl S
 114 Do not scan the built-in system directory
 115 .Pq Pa /usr/lib ,
 116 for shared libraries.
 117 (Directories listed in
 118 .Pa /etc/ld.so.conf
 119 are still scanned.)
 120 .It Fl v
 121 Switch 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
 132 A
 133 .Nm
 134 utility first appeared in SunOS 4.0, it appeared in its current form
 135 in
 136 .Nx 0.9a .
 137 .Sh SECURITY CONSIDERATIONS
 138 Special care must be taken when loading shared libraries into the address
 139 space of
 140 .Em set-user-ID
 141 programs.
 142 Whenever such a program is run,
 143 .Nm ld.so
 144 will only load shared libraries from the
 145 .Pa ld.so.hints
 146 file.
 147 In particular, the
 148 .Ev LD_LIBRARY_PATH
 149 and
 150 .Ev LD_PRELOAD
 151 is not used to search for libraries.
 152 Thus, the role of ldconfig is dual.
 153 In addition to building a set of hints for quick lookup, it also serves to
 154 specify the trusted collection of directories from which shared objects can
 155 be safely loaded.
 156 It is presumed that the set of directories specified to
 157 .Nm
 158 is under control of the system's administrator.
 159 .Nm ld.so
 160 further assists set-user-ID programs by erasing the
 161 .Ev LD_LIBRARY_PATH
 162 and
 163 .Ev LD_PRELOAD
 164 from the environment.