Differential D30272 Diff 89618 sbin/ldconfig/ldconfig.8

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
				emasteUnsubmitted Done Inline Actions `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 Actions IMO 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 Actions Mmm, 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
				bcrUnsubmitted Done Inline Actions s/configure set/configure a set/ bcr: s/configure set/configure a set/
	.Ar directories			.Ar directories
				emasteUnsubmitted Done Inline Actions maybe .Nm utility is used to configure the set of paths used by the dynamic linker .Xr ld-elf.so.1 1 when searching for shared libraries. 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
				emasteUnsubmitted Done Inline Actions I'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.
				emasteUnsubmitted Done Inline Actions additional 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
				emasteUnsubmitted Done Inline Actions Are 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
				bcrUnsubmitted Done Inline Actions s/directoriesf/directories/ bcr: s/directoriesf/directories/
				emasteUnsubmitted 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.
				emasteUnsubmitted Done Inline Actions should 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.