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

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

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 7895 bytes --]

* 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.
* 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)
-- 
2.30.2


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

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

[Alejandro Colomar]

[-- 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 --]

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

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 1004 bytes --]

Hi Alex,

At 2023-01-07T14:10:12+0100, Alejandro Colomar wrote:
> > * 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.

s/1/8;s/4/5

That seems reasonable.  Can I tackle that _after_ the current batch is
off my plate?  :-O

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

(assuming s/4/5)

Here I don't agree.  The format of the cache file is an internal
implementation detail; the user can select a format (possibly for
file-sharing purposes[1]), but beyond the name of each format ("old",
"compat", "new"), these are opaque.

In my opinion a file format need be documented in section 5 only if it
is (deliberately) exposed to manipulation by other tools.

Regards,
Branden

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

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

[Alejandro Colomar]

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

Hi Branden,

On 1/7/23 17:53, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-01-07T14:10:12+0100, Alejandro Colomar wrote:
>>> * 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.
> 
> s/1/8;s/4/5

D'oh!

> 
> That seems reasonable.  Can I tackle that _after_ the current batch is
> off my plate?  :-O

You mean apply this patch, then prepare a new page?  If so, yes, that makes sense.

> 
>> And maybe also for ld.so.cache(4).
> 
> (assuming s/4/5)

*.*

> 
> Here I don't agree.  The format of the cache file is an internal
> implementation detail; the user can select a format (possibly for
> file-sharing purposes[1]), but beyond the name of each format ("old",
> "compat", "new"), these are opaque.
> 
> In my opinion a file format need be documented in section 5 only if it
> is (deliberately) exposed to manipulation by other tools.

Makes sense.

> 
> Regards,
> Branden

Cheers,

Alex

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

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

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

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 519 bytes --]

Hi Alex,

At 2023-01-07T20:39:01+0100, Alejandro Colomar wrote:
> On 1/7/23 17:53, G. Branden Robinson wrote:
> > > I think ld.so.conf(4) might be a good manual page on its own, and
> > > ldconfig(1) refer to it.
> > That seems reasonable.  Can I tackle that _after_ the current batch
> > is off my plate?  :-O
> 
> You mean apply this patch, then prepare a new page?  If so, yes, that
> makes sense.

Great, thanks.  Will do.  I'm piling up quite a few miscellaneous fixes
to pages.

Regards,
Branden

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