Changeset View
Standalone View
sbin/ldconfig/ldconfig.8
.\" | .\" | ||||
.\" Copyright (c) 1993 Paul Kranenburg | .\" Copyright (c) 1993 Paul Kranenburg | ||||
.\" All rights reserved. | .\" All rights reserved. | ||||
.\" Copyright (c) 2021 The FreeBSD Foundation, Inc. | |||||
.\" | .\" | ||||
.\" Portions of this documentation were written by | |||||
emaste: `Portions of this documentation were written by` | |||||
.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship | |||||
.\" from the FreeBSD Foundation. | |||||
.\" | |||||
.\" Redistribution and use in source and binary forms, with or without | .\" Redistribution and use in source and binary forms, with or without | ||||
.\" modification, are permitted provided that the following conditions | .\" modification, are permitted provided that the following conditions | ||||
.\" are met: | .\" are met: | ||||
.\" 1. Redistributions of source code must retain the above copyright | .\" 1. Redistributions of source code must retain the above copyright | ||||
.\" notice, this list of conditions and the following disclaimer. | .\" notice, this list of conditions and the following disclaimer. | ||||
.\" 2. Redistributions in binary form must reproduce the above copyright | .\" 2. Redistributions in binary form must reproduce the above copyright | ||||
.\" notice, this list of conditions and the following disclaimer in the | .\" notice, this list of conditions and the following disclaimer in the | ||||
.\" documentation and/or other materials provided with the distribution. | .\" documentation and/or other materials provided with the distribution. | ||||
Show All 11 Lines | |||||
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | ||||
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY | .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY | ||||
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | ||||
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF | .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF | ||||
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | ||||
.\" | .\" | ||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd December 31, 2020 | .Dd May 15, 2021 | ||||
.Dt LDCONFIG 8 | .Dt LDCONFIG 8 | ||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm ldconfig | .Nm ldconfig | ||||
.Nd configure the shared library cache | .Nd configure the dynamic linker search path for shared libraries | ||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||
.Nm | .Nm | ||||
.Op Fl 32 | .Op Fl 32 | ||||
.Op Fl elf | |||||
.Op Fl Rimrsv | .Op Fl Rimrsv | ||||
.Op Fl f Ar hints_file | .Op Fl f Ar hints_file | ||||
.Op Ar directory | Ar | .Op Ar directory | Ar | ||||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||||
The | |||||
.Nm | .Nm | ||||
utility is used to prepare a set of | utility is used to configure the set of paths used by the dynamic linker | ||||
.Dq hints | .Xr ld-elf.so.1 1 | ||||
for use by the dynamic linker | when searching for shared libraries. | ||||
to facilitate quick lookup of shared libraries available in multiple | The dynamic linker looks for libraries in a set of built-in system directories | ||||
directories. | and any directories specified in the hints file. | ||||
It scans a set of built-in system directories and any | This obviates the need for storing search paths within the executable, | ||||
see the | |||||
.Fl rpath | |||||
option for the static linker | |||||
emasteUnsubmitted Done Inline ActionsIMO we don't really need this either - for someone unfamiliar with the history of a.out this seems like we're telling them that they don't need to do something that they wouldn't anyway. But not a big deal. emaste: IMO we don't really need this either - for someone unfamiliar with the history of a.out this… | |||||
kibAuthorUnsubmitted Done Inline ActionsMmm, no, this does not have anything to do with a.out. It is about -rpath (actually ELF feature, I do not remember anything similar in Sun 4.x/FreeBSD a.out so). kib: Mmm, no, this does not have anything to do with a.out. It is about -rpath (actually ELF… | |||||
.Xr ld 1 . | |||||
.Pp | |||||
The hints file is maintained by | |||||
.Nm . | |||||
The | |||||
Done Inline Actionss/configure set/configure a set/ bcr: s/configure set/configure a set/ | |||||
.Ar directories | .Ar directories | ||||
Done Inline Actionsmaybe .Nm emaste: maybe
.Nm
utility is used to configure the set of paths used by the dynamic linker
.Xr ld-elf. | |||||
specified on the command line (in the given order) looking for | list to be stored in the hints file is supplied on the command line. | ||||
shared libraries and stores the results in a system file to forestall | |||||
the overhead that would otherwise result from the directory search | |||||
operations the dynamic linker would have to perform to load the | |||||
required shared libraries. | |||||
.Pp | .Pp | ||||
Alternatively, | Alternatively to the | ||||
.Ar directories | |||||
list on the command line, | |||||
.Ar files | .Ar files | ||||
may be specified; these are expected to contain directories | may be specified; these are expected to contain directories | ||||
to scan for shared libraries. | to scan for shared libraries. | ||||
Each directory's pathname must start on a new | Each directory's pathname must start on a new | ||||
line. | line. | ||||
Blank lines and lines starting with the comment character | Blank lines and lines starting with the comment character | ||||
.Ql \&# | .Ql \&# | ||||
are ignored. | are ignored. | ||||
Filenames must conform to the | |||||
.Pa lib*.so.[0-9] | |||||
pattern in order to be added to the hints file. | |||||
.Pp | .Pp | ||||
For security reasons, directories which are world or group-writable or which | For security reasons, directories which are world or group-writable or which | ||||
are not owned by root produce warning messages and are skipped, unless | are not owned by root produce warning messages and are skipped, unless | ||||
the | the | ||||
.Fl i | .Fl i | ||||
option is present. | option is present. | ||||
.Pp | .Pp | ||||
The shared libraries which are found will be automatically available for loading | |||||
if needed by the program being prepared for execution. | |||||
This obviates the need | |||||
for storing search paths within the executable. | |||||
.Pp | |||||
The | The | ||||
Done Inline ActionsI'm not sure we need to keep this text at all - "the shared libraries which are found" implies we are building a list at ldconfig time? emaste: I'm not sure we need to keep this text at all - "the shared libraries which are found" implies… | |||||
.Ev LD_LIBRARY_PATH | .Ev LD_LIBRARY_PATH | ||||
environment variable can be used to override the use of | environment variable can be used to specify additional | ||||
directories (or the order thereof) from the cache or to specify additional | shared library search directories. | ||||
Done Inline Actionsadditional shared library search directories. emaste: additional shared library search directories.
| |||||
directories where shared libraries might be found. | |||||
.Ev LD_LIBRARY_PATH | .Ev LD_LIBRARY_PATH | ||||
is a | is a | ||||
.Sq \&: | .Sq \&: | ||||
separated list of directory paths which are searched by | separated list of directory paths which are searched by | ||||
the dynamic linker | the dynamic linker | ||||
when it needs to load a shared library. | when it needs to load a shared library. | ||||
It can be viewed as the run-time | It can be viewed as the run-time | ||||
equivalent of the | equivalent of the | ||||
.Fl L | .Fl L | ||||
switch of | switch of | ||||
.Xr ld 1 . | .Xr ld 1 . | ||||
.Pp | .Pp | ||||
The | |||||
.Nm | |||||
utility is typically run as part of the boot sequence. | |||||
.Pp | |||||
The following options are recognized by | The following options are recognized by | ||||
.Nm : | .Nm : | ||||
.Bl -tag -width indent | .Bl -tag -width indent | ||||
.It Fl 32 | .It Fl 32 | ||||
Generate the hints for 32-bit ABI shared libraries | Generate the hints for 32-bit ABI shared libraries | ||||
on 64-bit systems that support running 32-bit binaries. | on 64-bit systems that support running 32-bit binaries. | ||||
.It Fl elf | .It Fl elf | ||||
Ignored for backwards compatibility. | Ignored for backwards compatibility. | ||||
.It Fl R | .It Fl R | ||||
Rescan the previously configured directories. | Appends pathnames on the command line to the directory list from | ||||
This opens the previous hints | the hints file. | ||||
file and fetches the directory list from the header. | .Pp | ||||
Done Inline ActionsAre they printed? emaste: Are they printed? | |||||
Any additional pathnames | This is the default action when no options are given. | ||||
on the command line are also processed. | |||||
This is the default action when no parameters are given. | |||||
.It Fl f Ar hints_file | .It Fl f Ar hints_file | ||||
Read and/or update the specified hints file, instead of the standard file. | Read and/or update the specified hints file, instead of the standard file. | ||||
This option is provided primarily for testing. | This option is provided primarily for testing. | ||||
.It Fl i | .It Fl i | ||||
Run in insecure mode. | Run in insecure mode. | ||||
The security checks will not be performed. | The security checks will not be performed. | ||||
.It Fl m | .It Fl m | ||||
Instead of replacing the contents of the hints file | Instead of replacing the list of the directories to search with the | ||||
with those found in the directories specified, | directories specified on the command line, merge existing list | ||||
.Dq merge | with the specified directories, and write the result to the hints file. | ||||
in new entries. | |||||
Directories recorded in the hints file by previous runs of | |||||
.Nm | |||||
are also rescanned for new shared libraries. | |||||
.It Fl r | .It Fl r | ||||
List the current contents of the hints file | List the current list of the directories from the hints file | ||||
Done Inline Actionss/directoriesf/directories/ bcr: s/directoriesf/directories/ | |||||
Done Inline Actions-r also performs a search and prints the libraries found? emaste: -r also performs a search and prints the libraries found? | |||||
on the standard output. | on the standard output. | ||||
The hints file is not modified. | The hints file is not modified. | ||||
The list of | .Pp | ||||
directories stored in the hints file is included. | Scan and print all libraries found on the directories list. | ||||
.It Fl s | .It Fl s | ||||
Do not scan the built-in system directory | Do not scan the built-in system directory | ||||
.Pq Dq /usr/lib | .Pq Dq /usr/lib | ||||
for shared libraries. | for shared libraries. | ||||
.It Fl v | .It Fl v | ||||
Switch on verbose mode. | Switch on verbose mode. | ||||
.El | .El | ||||
.Sh SECURITY | .Sh SECURITY | ||||
Special care must be taken when loading shared libraries into the address | Special care must be taken when loading shared libraries into the address | ||||
space of | space of | ||||
.Ev set-user-Id | .Ev set-user-Id | ||||
programs. | programs. | ||||
Whenever such a program is run by any user except the owner of the program, | Whenever such a program is run by any user except the owner of the program, | ||||
the dynamic linker | the dynamic linker will only load shared libraries from paths found in | ||||
will only load shared libraries from the hints | the hints file. | ||||
Done Inline Actionsshould this perhaps be "only load shared libraries from paths found in the hints file"? emaste: should this perhaps be "only load shared libraries from paths found in the hints file"? | |||||
file. | |||||
In particular, the | In particular, the | ||||
.Ev LD_LIBRARY_PATH | .Ev LD_LIBRARY_PATH | ||||
is not used to search for libraries. | is not used to search for libraries. | ||||
Thus, the role of | Thus, | ||||
.Nm | .Nm | ||||
is dual. | serves to specify the trusted collection of directories from which | ||||
In addition to building a set of hints for quick lookup, it also serves to | shared objects can be safely loaded. | ||||
specify the trusted collection of directories from which shared objects can | |||||
be safely loaded. | |||||
.Sh FILES | .Sh FILES | ||||
.Bl -tag -width /var/run/ld-elf.so.hintsxxx -compact | .Bl -tag -width /var/run/ld-elf.so.hintsxxx -compact | ||||
.It Pa /var/run/ld.so.hints | |||||
Standard hints file for the a.out dynamic linker. | |||||
.It Pa /var/run/ld-elf.so.hints | .It Pa /var/run/ld-elf.so.hints | ||||
Standard hints file for the ELF dynamic linker. | Standard hints file for the ELF dynamic linker. | ||||
.It Pa /etc/ld.so.conf | |||||
Conventional configuration file containing directory names for | |||||
invocations with | |||||
.Fl aout . | |||||
.It Pa /etc/ld-elf.so.conf | .It Pa /etc/ld-elf.so.conf | ||||
Conventional configuration file containing directory names for | Conventional configuration file containing directory names for | ||||
invocations with | invocations with | ||||
.Fl elf . | .Fl elf . | ||||
.It Pa /var/run/ld-elf32.so.hints | .It Pa /var/run/ld-elf32.so.hints | ||||
.It Pa /var/run/ld32.so.hints | |||||
Conventional configuration files containing directory names for | Conventional configuration files containing directory names for | ||||
invocations with | invocations with | ||||
.Fl 32 . | .Fl 32 . | ||||
.El | .El | ||||
.Sh SEE ALSO | .Sh SEE ALSO | ||||
.Xr ld 1 , | .Xr ld 1 , | ||||
.Xr ld-elf.so.1 , | |||||
.Xr link 5 | .Xr link 5 | ||||
.Sh HISTORY | .Sh HISTORY | ||||
A | A | ||||
.Nm | .Nm | ||||
utility first appeared in SunOS 4.0, it appeared in its current form | utility first appeared in SunOS 4.0, it appeared in its current form | ||||
in | in | ||||
.Fx 1.1 . | .Fx 1.1 . | ||||
.Sh BUGS | .Pp | ||||
Some security checks (for example, verifying root ownership of | The name 'hints file' is historic from the times when the file also contained | ||||
added directories) are not performed when | hints to the dynamic linker. | ||||
.Fl aout | This functionality is not provided for ELF. | ||||
is specified. |
Portions of this documentation were written by