Re: [PATCH v4 02/10] ldconfig.8: Revise and update for glibc 2.32

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 8771 bytes --]

Hi Branden,

On 1/7/23 10:54, G. Branden Robinson wrote:
> * Recast summary description to identify relevance of libraries.
> * Drop `-V` option from synopsis; it doesn't make any sense combined
>    with the operation mode shown, and no other "get out quick" option,
>    including its synonym `--version`, is documented in the synopsis.
> * Clarify that the "links" manipulated by the program are symbolic.
> * Discuss caching feature separately from symbolic link management.
> * Clarify how ldconfig can be run by unprivileged users (probably for
>    troubleshooting).
> * Recast example of shared library linkage chain and motivate the
>    existence for each link or file.  Define term "soname" and present it
>    in lowercase like other Linux man-pages, instead of full caps.
> * Document auxiliary cache file, which apparently has been described
>    nowhere but a source comment in the original commit 15 years ago.
> * Document that `-C` implies `-i`.  See elf/ldconfig.c:162.
> * Clarify how `-l` option works (a little).
> * Drop mention of "quiet mode", which does not seem to exist.
> * Be explicit that `-p`/`--print-cache` option exits early; i.e., it
>    doesn't undertake ldconfig's primary function.
> * Document `--usage` and `-?`/`--help` options.
> * Clarify what `-v`/`--verbose` does.
> * Clarify that `-V`/`--version` exits early.
> * Expand description of "ld.so.conf" file to discuss "include" and
>    "hwcap" features.  Describe these as "directives" (though the latter
>    died upstream in glibc 2.32 before we got around to documenting it).
>    Document ld.so.conf's comment syntax.

I think ld.so.conf(4) might be a good manual page on its own, and ldconfig(1) 
refer to it.

And maybe also for ld.so.cache(4).

Cheers,

Alex

> * Document handling of leading spaces and empty lines in ld.so.conf.
> * Document location of auxiliary cache file.
> 
> Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com>
> ---
>   man8/ldconfig.8 | 121 +++++++++++++++++++++++++++++++++++++-----------
>   1 file changed, 95 insertions(+), 26 deletions(-)
> 
> diff --git a/man8/ldconfig.8 b/man8/ldconfig.8
> index 36b891dab..5b671f0a1 100644
> --- a/man8/ldconfig.8
> +++ b/man8/ldconfig.8
> @@ -7,12 +7,12 @@
>   .\"   Change listed order of /usr/lib and /lib
>   .TH ldconfig 8 (date) "Linux man-pages (unreleased)"
>   .SH NAME
> -ldconfig \- configure dynamic linker run-time bindings
> +ldconfig \- configure library bindings used by run-time dynamic linker
>   .SH SYNOPSIS
>   .SY /sbin/ldconfig
>   .\" TODO?: -c, --format, -i, --ignore-aux-cache, --print-cache,
>   .\" --verbose, -V, --version, -?, --help, --usage
> -.RB [ \-nNvVX ]
> +.RB [ \-nNvX ]
>   .RB [ \-C\~\c
>   .IR cache ]
>   .RB [ \-f\~\c
> @@ -31,8 +31,10 @@ ldconfig \- configure dynamic linker run-time bindings
>   .YS
>   .SH DESCRIPTION
>   .B \%ldconfig
> -creates the necessary links and cache to the most recent shared
> -libraries found in the directories specified on the command line,
> +creates the necessary symbolic links
> +to the most recent versions of the shared libraries
> +found in the directories
> +specified on the command line,
>   in the file
>   .IR /etc/ld.so.conf ,
>   and in the trusted directories,
> @@ -50,7 +52,8 @@ and
>   .I /usr/lib64
>   are used for 64-bit libraries.
>   .PP
> -The cache is used by the run-time linker,
> +It also maintains a cache
> +used by the run-time linker,
>   .I ld.so
>   or
>   .IR ld\-linux.so .
> @@ -61,8 +64,11 @@ determining which versions should have their links updated.
>   .\" 8ee878592c4a642937152c8308b8faef86bcfc40 (2022-07-14) as "obsolete
>   .\" for over twenty years".
>   .B \%ldconfig
> -should normally be run by the superuser as it may require write
> -permission on some root owned directories and files.
> +is normally run by the superuser
> +since it may require write permission
> +on some root-owned directories and files.
> +.RI \%\(lq ldconfig\~\-p \(rq
> +can be run without such privileges.
>   .PP
>   .B \%ldconfig
>   will look only at files that are named
> @@ -74,10 +80,7 @@ Other files will be ignored.
>   Also,
>   .B \%ldconfig
>   expects a certain pattern to how the symbolic links are set up,
> -like this example,
> -where the middle file
> -.RB ( libfoo.so.1
> -here) is the SONAME for the library:
> +as in the following.
>   .PP
>   .in +4n
>   .EX
> @@ -85,8 +88,26 @@ libfoo.so \-> libfoo.so.1 \-> libfoo.so.1.12
>   .EE
>   .in
>   .PP
> -Failure to follow this pattern may result in compatibility issues
> -after an upgrade.
> +The name
> +.B libfoo.so
> +is used when preparing object code that uses shared libraries.
> +.B libfoo.so.1
> +is the
> +.I soname
> +(shared object name)
> +used at run time,
> +by which object code locates its shared library dependencies.
> +.B libfoo.so.1.12
> +is the shared library.
> +This practice enables upward-compatible upgrades of shared libraries;
> +a change in the version number after the soname indicates that no
> +\(lqbreak\(rq in the ABI
> +(application binary interface)
> +has occurred.
> +.PP
> +.B ldconfig
> +maintains an auxiliary cache file that helps it to avoid re-reading
> +libraries that have not changed since the last time it was run.
>   .SH OPTIONS
>   .TP
>   .BI \-c\~ fmt
> @@ -102,9 +123,9 @@ which is one of
>   or
>   .BR \%compat .
>   Since glibc 2.32,
> +.\" commit cad64f778aced84efdaa04ae64f8737b86f063ab
>   the default is
>   .BR new .
> -.\" commit cad64f778aced84efdaa04ae64f8737b86f063ab
>   Before that,
>   it was
>   .BR \%compat .
> @@ -114,6 +135,8 @@ Use
>   .I cache
>   instead of
>   .IR /etc/ld.so.cache .
> +Implies
> +.BR \-i .
>   .TP
>   .BI \-f\~ conf
>   Use
> @@ -151,27 +174,29 @@ links are still updated.
>   .B \-p
>   .TQ
>   .B \-\-print\-cache
> -Print the lists of directories and candidate libraries stored in
> -the current cache.
> +Report the libraries stored in the cache and exit.
>   .TP
>   .BI \-r\~ root
>   Change to and use
>   .I root
>   as the root directory.
>   .TP
> +.B \-\-usage
> +Report a terse usage message and exit.
> +.TP
>   .B \-v
>   .TQ
>   .B \-\-verbose
> -Verbose mode.
> -Print current version number,
> +Operate verbosely;
> +for each library,
> +report the current version number,
>   the name of each directory as it is scanned,
>   and any links that are created.
> -Overrides quiet mode.
>   .TP
>   .B \-V
>   .TQ
>   .B \-\-version
> -Print program version.
> +Report program version information and exit.
>   .TP
>   .B \-X
>   Don't update links.
> @@ -179,26 +204,70 @@ Unless
>   .B \-N
>   is also specified,
>   the cache is still rebuilt.
> +.TP
> +.B \-?
> +.TQ
> +.B \-\-help
> +Report a usage message and exit.
>   .SH FILES
> -.\" FIXME Since glibc-2.3.4, "include" directives are supported in ld.so.conf
> -.\"
> -.\" FIXME Since glibc-2.4, "hwcap" directives are supported in ld.so.conf
> -.PD 0
>   .TP
>   .I /lib/ld.so
>   is the run-time linker/loader.
>   .TP
>   .I /etc/ld.so.conf
> +.RS
>   contains a list of directories,
>   one per line,
> -in which to search for libraries.
> +in which to search for libraries;
> +or a multi-word
> +.I directive
> +further configuring the run-time linker/loader.
> +A number sign
> +.RB ( # )
> +introduces a comment that extends to the end of the line;
> +this character is thus not supported in directives or directory names.
> +Leading spaces are removed.
> +Empty lines are ignored.
> +.PP
> +Since glibc\~2.3.4,
> +.\" commit 8e115d80b07f17a11690c108918f847846a752da
> +a directive in the form
> +.RS
> +.EX
> +include\~\c
> +.I filename\~\c
> +\&.\|.\|.
> +.EE
> +.RE
> +is supported;
> +each
> +.I filename
> +is recursively opened and read.
> +.\" XXX: ...with no detection of cycles!
> +.I filename
> +can be a
> +.BR glob (3)
> +pattern.
> +This feature enables libraries or packages to manage shared library
> +placement in a modular way.
> +.PP
> +In glibc\~2.4,
> +.\" commit ab1d521db39bf4371c7db96e8a0fcd4857ee70ed
> +a
> +.B \%hwcap
> +directive was introduced,
> +but it is no longer supported as of glibc\~2.32.
> +.\" commit 31563b68410ff8e9490c5aafca31ec71b38f87a5
> +.RE
>   .TP
>   .I /etc/ld.so.cache
>   contains an ordered list of libraries found in the directories
>   specified in
>   .IR /etc/ld.so.conf ,
>   as well as those found in the trusted directories.
> -.PD
> +.TP
> +.I /var/cache/ldconfig/aux\-cache
> +is the auxiliary cache.
>   .SH SEE ALSO
>   .BR ldd (1),
>   .BR ld.so (8)

-- 
<http://www.alejandro-colomar.es/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]