[unix-history] / gnu / usr.bin / ld / ldconfig / ldconfig.8

.Dd October 3, 1993
.Dt LDCONFIG 8
.Os FreeBSD 1.1
.Sh NAME
.Nm ldconfig
.Nd configure the shared library cache
.Sh SYNOPSIS
.Nm ldconfig
.Op Fl rsv
.Op Ar directory Ar ...
.Sh DESCRIPTION
.Nm
is used to prepare a set of
.Dq hints
for use by the run-time linker
.Xr ld.so
to facilitate quick lookup of shared libraries available in multiple
directories.  It scans a set of built-in system directories and any
.Ar directories
specified on the command line (in the given order) looking for shared
libraries and stores the results in the file
.Xr /var/run/ld.so.hints
to forstall the overhead that would otherwise result from the
directory search operations
.Xr ld.so
would have to perform to load the required shared libraries.
.Pp
The shared libraries so 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
.Ev LD_LIBRARY_PATH
environment variable can be used to override the use of
directories (or the order thereof) from the cache or to specify additional
directories where shared libraries might be found.
.Ev LD_LIBRARY_PATH
is a
.Sq \:
separated list of directory paths which are searched by
.Xr ld.so
when it needs to load a shared library. It can be viewed as the run-time
equivalent of the
.Fl L
switch of
.Xr ld.
.Pp
.Nm Ldconfig
is typically run as part of the boot sequence.
.Pp
The following options recognized by
.Nm ldconfig:
.Bl -tag -width indent
.It Fl r
Lists the current contents of
.Xr ld.so.hints
on the standard output. The hints file will not be modified.
.It Fl s
Do not scan
.Nm ldconfig
's builtin system directories
.Sq /usr/lib
and
.Sq /usr/local/lib
for shared libraries.
.It Fl v
Switch on verbose mode.
.Sh Security
Special care must be taken when loading shared libraries into the address
space of
.Ev set-user-Id
programs. Whenever such a program is run,
.Xr ld.so
will only load shared libraries from the
.Ev ld.so.hints
file. In particular, the
.Ev LD_LIBRARY_PATH
is not used to search for libraries. Thus, the role of ldconfig is dual. In
addition to building a set of hints for quick lookup, it also serves to
specify the trusted collection of directories from which shared objects can
be safely loaded. It is presumed that the set of directories specified to
.Nm ldconfig
are under control of the system's administrator.
.Xr ld.so
further assists set-user-Id programs by erasing the
.Ev LD_LIBRARY_PATH
from the environment.

.Sh FILES
.Xr /var/run/ld.so.hints
.Sh SEE ALSO
.Xr ld 1 ,
.Xr link 5
.Sh HISTORY
A
.Nm
utility first appeared in SunOS 4.0, it appeared in its current form
in FreeBSD 1.1.
Commit	Line	Data
1136f72d PR	1	.Dd October 3, 1993
1136f72d PR	2	.Dt LDCONFIG 8
6a61ea88	3	.Os FreeBSD 1.1
1136f72d PR	4	.Sh NAME
	5	.Nm ldconfig
	6	.Nd configure the shared library cache
	7	.Sh SYNOPSIS
	8	.Nm ldconfig
	9	.Op Fl rsv
	10	.Op Ar directory Ar ...
	11	.Sh DESCRIPTION
	12	.Nm
	13	is used to prepare a set of
	14	.Dq hints
	15	for use by the run-time linker
	16	.Xr ld.so
	17	to facilitate quick lookup of shared libraries available in multiple
	18	directories. It scans a set of built-in system directories and any
	19	.Ar directories
	20	specified on the command line (in the given order) looking for shared
	21	libraries and stores the results in the file
	22	.Xr /var/run/ld.so.hints
	23	to forstall the overhead that would otherwise result from the
	24	directory search operations
	25	.Xr ld.so
	26	would have to perform to load the required shared libraries.
	27	.Pp
	28	The shared libraries so found will be automatically available for loading
	29	if needed by the program being prepared for execution. This obviates the need
	30	for storing search paths within the executable.
	31	.Pp
	32	The
	33	.Ev LD_LIBRARY_PATH
	34	environment variable can be used to override the use of
	35	directories (or the order thereof) from the cache or to specify additional
	36	directories where shared libraries might be found.
	37	.Ev LD_LIBRARY_PATH
	38	is a
	39	.Sq \:
	40	separated list of directory paths which are searched by
	41	.Xr ld.so
	42	when it needs to load a shared library. It can be viewed as the run-time
	43	equivalent of the
	44	.Fl L
	45	switch of
	46	.Xr ld.
	47	.Pp
	48	.Nm Ldconfig
	49	is typically run as part of the boot sequence.
	50	.Pp
	51	The following options recognized by
	52	.Nm ldconfig:
	53	.Bl -tag -width indent
	54	.It Fl r
	55	Lists the current contents of
	56	.Xr ld.so.hints
	57	on the standard output. The hints file will not be modified.
	58	.It Fl s
	59	Do not scan
	60	.Nm ldconfig
	61	's builtin system directories
	62	.Sq /usr/lib
	63	and
	64	.Sq /usr/local/lib
	65	for shared libraries.
	66	.It Fl v
	67	Switch on verbose mode.
68	.Sh Security
69	Special care must be taken when loading shared libraries into the address
70	space of
71	.Ev set-user-Id
72	programs. Whenever such a program is run,
73	.Xr ld.so
74	will only load shared libraries from the
75	.Ev ld.so.hints
76	file. In particular, the
77	.Ev LD_LIBRARY_PATH
78	is not used to search for libraries. Thus, the role of ldconfig is dual. In
79	addition to building a set of hints for quick lookup, it also serves to
80	specify the trusted collection of directories from which shared objects can
81	be safely loaded. It is presumed that the set of directories specified to
82	.Nm ldconfig
83	are under control of the system's administrator.
84	.Xr ld.so
85	further assists set-user-Id programs by erasing the
86	.Ev LD_LIBRARY_PATH
87	from the environment.
88
89	.Sh FILES
90	.Xr /var/run/ld.so.hints
91	.Sh SEE ALSO
92	.Xr ld 1 ,
93	.Xr link 5
94	.Sh HISTORY
95	A
96	.Nm
97	utility first appeared in SunOS 4.0, it appeared in its current form
548edb9e	98	in FreeBSD 1.1.