Re: [PATCH 2/4] ldconfig.8: Revise and update.

[Alejandro Colomar <alx.manpages@xxxxxxxxx>]

Hi Branden!

On 1/2/23 15:23, G. Branden Robinson wrote:
> Content:
> * 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.
> * Clarify how ldconfig can be run by unprivileged users (probably for
>    troubleshooting).
> * Discuss caching feature separately.
> * Comment out multiple paragraphs discussing libc4 and libc5 shared
>    library support.  It was removed upstream in July.
> * 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.
>
> Style:
> * Set `TH` page title in lowercase, since the migration is underway.

More than underway.  I already "finished" it; or at least I thought I had.  I 
already found a few cases where it didn't work (open.2).  My sed expressions 
didn't have enough mana...

> * In synopses, set ellipses as separate "operands" to better suggest
>    argument separation by white space.
> * Sort option flags in English lexicographic order.
> * Typeset ellipses more attractively on troff devices.
> * De-parenthesize content that seems important.
> * Perform a Kemper notectomy.  That is, stop saying "note that"
>    followed by some declarative statement.  This trope is all over Unix
>    documentation and I even see it in ISO standards.  The latter doesn't
>    serve to recommend it; as Dave Kemper has pointed out, everything we
>    put in technical documentation should be worthy of note unless placed
>    in a footnote, marked as "unnecessary on a first reading", or similar.
>    It is the exception, not the rule.  If you feel the need to say "note
>    that", consider what adjacent material you shouldn't be saying at all.
> * Say "symbolic link" instead of "symlink".  (Should we add this to the
>    man-pages(7) usage table?)

Probably.

> * When one sentence explains the previous, use a semicolon.

Oh, another lover of semicolons here :)

> * Place the modifier "only" more carefully.
> * Recast option descriptions to be in the imperative mood.
> * Recast file descriptions to use the paragraph tag as the subject of
>    the first sentence.
>
> Markup:
> * Add glibc Git repository commit IDs for several features (and one
>    feature withdrawal).  Drop FIXME comments that apparently desired
>    this.
> * Annotate potential DoS attack on ldconfig(8).  (But you'd have to have
>    write access to /etc/ld.so.conf or something it reads anyway.)
> * Set literals used as arguments to `-c` option in bold, not italics.
> * Rewrite synopses to use man(7) font macros instead of *roff font
>    selection escape sequences.
> * Drop redundant `PD` macro calls.
> * Use `P` macro instead of `PP` (my preference; it's shorter).

This one I would either do it for all pages at once, or not do it.  I don't have 
any preference, so if you send a script (a patch would be several MB long, I 
guess), I can apply it.  I guess I can't stop in on the grounds of churn, 
considering that I've had my fair amount of it.

> * Use AT&T troff-compatible right-arrow special characters.

These things, I'd also like if the fix was applied globally.

> * Rewrite option list to use man(7) font macros instead of *roff font
>    selection escape sequences.
> * Use `TQ` macro to include multiple tags for options with long synonyms
>    instead of comma notation.
> * Break input lines after commas.
> * Set multi-word parentheticals on their own input lines.
> * Break input lines at phrase boundaries more often.
> * Protect literals from automatic hyphenation with `\%` escape sequence.

Heh!

Let's see where I can start with this bone.  How about breaking it into 3: one 
for markup, one for style, and one for contents, in that order.  If you find 
some of the changes inside one of those, feel free to break them further; 
anyway, I expect that I'll ask you to do so after you send v2 ;)

Cheers,

Alex

> ---
>   man8/ldconfig.8 | 292 ++++++++++++++++++++++++++++++++----------------
>   1 file changed, 193 insertions(+), 99 deletions(-)
>
> diff --git a/man8/ldconfig.8 b/man8/ldconfig.8
> index d608aaf56..6f6e51008 100644
> --- a/man8/ldconfig.8
> +++ b/man8/ldconfig.8
> @@ -5,146 +5,184 @@
>   .\"
>   .\" Modified, 6 May 2002, Michael Kerrisk, <mtk.manpages@xxxxxxxxx>
>   .\"   Change listed order of /usr/lib and /lib
> -.TH LDCONFIG 8 (date) "Linux man-pages (unreleased)"
> +.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
> -.BR /sbin/ldconfig " [" \-nNvXV "] [" \-f " \fIconf\fP] [" \-C " \fIcache\fP] [" \-r " \fIroot\fP]"
> -.IR directory \...
>   .PD 0
> -.PP
> -.PD
> +.\" TODO?: -c, --format, -i, --ignore-aux-cache, ,--print-cache,
> +.\" --verbose, -V, --version, -?, --help, --usage
> +.BR /sbin/ldconfig " [" \-nNvX "]
> +.RB [ \-C
> +.IR cache ]
> +.RB [ \-f
> +.IR conf ]
> +.RB [ \-r
> +.IR root ]
> +.IR directory \~.\|.\|.
> +.P
>   .B /sbin/ldconfig
>   .B \-l
>   .RB [ \-v ]
> -.IR library \...
> -.PD 0
> -.PP
> -.PD
> +.IR library \~.\|.\|.
> +.P
>   .B /sbin/ldconfig
>   .B \-p
> +.PD
>   .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,
> +.B \%ldconfig
> +creates the necessary symbolic links
> +to the most recent shared libraries found in the directories
> +specified on the command line,
>   in the file
>   .IR /etc/ld.so.conf ,
>   and in the trusted directories,
>   .I /lib
>   and
> -.I /usr/lib
> -(on some 64-bit architectures such as x86-64,
> +.IR /usr/lib .
> +On some 64-bit architectures such as x86-64,
>   .I /lib
>   and
>   .I /usr/lib
> -are the trusted directories for 32-bit libraries, while
> +are the trusted directories for 32-bit libraries,
> +while
>   .I /lib64
>   and
>   .I /usr/lib64
> -are used for 64-bit libraries).
> -.PP
> -The cache is used by the run-time linker,
> +are used for 64-bit libraries.
> +.P
> +It also maintains a cache
> +used by the run-time linker,
>   .I ld.so
>   or
>   .IR ld\-linux.so .
> -.B ldconfig
> +.B \%ldconfig
>   checks the header and filenames of the libraries it encounters when
>   determining which versions should have their links updated.
> -.PP
> -.B ldconfig
> -will attempt to deduce the type of ELF libraries (i.e., libc5 or libc6/glibc)
> -based on what C libraries, if any, the library was linked against.
> -.\" The following sentence looks suspect
> -.\" (perhaps historical cruft) -- MTK, Jul 2005
> -.\" Therefore, when making dynamic libraries,
> -.\" it is wise to explicitly link against libc (use \-lc).
> -.PP
> -Some existing libraries do not contain enough information
> -to allow the deduction of their type.
> -Therefore, the
> -.I /etc/ld.so.conf
> -file format allows the specification of an expected type.
> -This is used
> -.I only
> -for those ELF libraries which we can not work out.
> -The format
> -is "dirname=TYPE", where TYPE can be libc4, libc5, or libc6.
> -(This syntax also works on the command line.)
> -Spaces are
> -.I not
> -allowed.
> -Also see the
> -.B \-p
> -option.
> -.B ldconfig
> -should normally be run by the superuser as it may require write
> -permission on some root owned directories and files.
> -.PP
> -Note that
> -.B ldconfig
> -will only look at files that are named
> +.\" Support for libc4 and libc5 dropped in
> +.\" 8ee878592c4a642937152c8308b8faef86bcfc40 (2022-07-14) as "obsolete
> +.\" for over twenty years".
> +.\".P
> +.\".B \%ldconfig
> +.\"will attempt to deduce the type of ELF libraries (i.e., libc5 or libc6/glibc)
> +.\"based on what C libraries, if any, the library was linked against.
> +.\".\" The following sentence looks suspect
> +.\".\" (perhaps historical cruft) -- MTK, Jul 2005
> +.\".\" Therefore, when making dynamic libraries,
> +.\".\" it is wise to explicitly link against libc (use \-lc).
> +.\".P
> +.\"Some existing libraries do not contain enough information
> +.\"to allow the deduction of their type.
> +.\"Therefore, the
> +.\".I /etc/ld.so.conf
> +.\"file format allows the specification of an expected type.
> +.\"This is used
> +.\".I only
> +.\"for those ELF libraries which we can not work out.
> +.\"The format
> +.\"is "dirname=TYPE", where TYPE can be libc4, libc5, or libc6.
> +.\"(This syntax also works on the command line.)
> +.\"Spaces are
> +.\".I not
> +.\"allowed.
> +.\"Also see the
> +.\".B \-p
> +.\"option.
> +.B \%ldconfig
> +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.
> +.P
> +.B \%ldconfig
> +will look only at files that are named
>   .I lib*.so*
>   (for regular shared objects) or
>   .I ld\-*.so*
>   (for the dynamic loader itself).
>   Other files will be ignored.
>   Also,
> -.B ldconfig
> -expects a certain pattern to how the symlinks are set up, like this
> -example, where the middle file
> -.RB ( libfoo.so.1
> -here) is the SONAME for the library:
> -.PP
> +.B \%ldconfig
> +expects a certain pattern to how the symbolic links are set up,
> +as in the following.
> +.P
>   .in +4n
>   .EX
> -libfoo.so \-> libfoo.so.1 \-> libfoo.so.1.12
> +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.
> +.P
> +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.
> +.P
> +.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
> -.BR \-c " \fIfmt\fP, " \-\-format=\fIfmt\fP
> +.BI \-c\~ fmt
> +.TQ
> +.BI \-\-format= fmt
>   (Since glibc 2.2)
> +.\" 45eca4d141c047950db48c69c8941163d0a61fcd
>   Cache format to use:
> -.IR old ,
> -.IR new ,
> +.BR old ,
> +.BR new ,
>   or
> -.IR compat .
> -Since glibc 2.32, the default is
> -.IR new .
> +.BR \%compat .
> +Since glibc 2.32,
>   .\" commit cad64f778aced84efdaa04ae64f8737b86f063ab
> -Before that, it was
> -.IR compat .
> +the default is
> +.BR new .
> +Before that,
> +it was
> +.BR \%compat .
>   .TP
>   .BI "\-C " cache
>   Use
>   .I cache
>   instead of
>   .IR /etc/ld.so.cache .
> +Implies
> +.BR \-i .
>   .TP
>   .BI "\-f " conf
>   Use
>   .I conf
>   instead of
>   .IR /etc/ld.so.conf .
> -.\" FIXME glibc 2.7 added -i
>   .TP
> -.BR \-i ", " \-\-ignore\-aux\-cache
> +.B \-i
> +.TQ
> +.B \-\-ignore\-aux\-cache
>   (Since glibc 2.7)
> -.\"             commit 27d9ffda17df4d2388687afd12897774fde39bcc
> +.\" commit 27d9ffda17df4d2388687afd12897774fde39bcc
>   Ignore auxiliary cache file.
>   .TP
>   .B \-l
>   (Since glibc 2.2)
>   Library mode.
> -Manually link individual libraries.
> -Intended for use by experts only.
> +Interprets each operand as a libary name and configures its links.
> +Intended for use only by experts.
>   .TP
>   .B \-n
> -Process only the directories specified on the command line.
> -Don't process the trusted directories,
> +Process only the directories specified on the command line;
> +don't process the trusted directories,
>   nor those specified in
>   .IR /etc/ld.so.conf .
>   Implies
> @@ -154,50 +192,106 @@ Implies
>   Don't rebuild the cache.
>   Unless
>   .B \-X
> -is also specified, links are still updated.
> +is also specified,
> +links are still updated.
>   .TP
> -.BR \-p ", " \-\-print\-cache
> -Print the lists of directories and candidate libraries stored in
> -the current cache.
> +.B \-p
> +.TQ
> +.B \-\-print\-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
> -.BR \-v ", " \-\-verbose
> -Verbose mode.
> -Print current version number, the name of each directory as it
> -is scanned, and any links that are created.
> -Overrides quiet mode.
> +.B \-\-usage
> +Report a terse usage message and exit.
> +.TP
> +.B \-v
> +.TQ
> +.B \-\-verbose
> +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.
>   .TP
> -.BR \-V ", " \-\-version
> -Print program version.
> +.B \-V
> +.TQ
> +.B \-\-version
> +Report program version information and exit.
>   .TP
>   .B \-X
>   Don't update links.
>   Unless
>   .B \-N
> -is also specified, the cache is still rebuilt.
> +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
> -Run-time linker/loader.
> +is the run-time linker/loader.
>   .TP
>   .I /etc/ld.so.conf
> -File containing a list of directories, one per line,
> -in which to search for libraries.
> +.RS
> +contains containing a list of directories,
> +one per line,
> +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.
> +.P
> +.\" commit 8e115d80b07f17a11690c108918f847846a752da
> +Since glibc\~2.3.4,
> +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.
> +.P
> +.\" commit ab1d521db39bf4371c7db96e8a0fcd4857ee70ed
> +In glibc\~2.4,
> +a
> +.B \%hwcap
> +directive was introduced,
> +.\" commit 31563b68410ff8e9490c5aafca31ec71b38f87a5
> +but it is no longer supported as of glibc\~2.32.
> +.RE
>   .TP
>   .I /etc/ld.so.cache
> -File containing an ordered list of libraries found in the directories
> +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: OpenPGP_signature
Description: OpenPGP digital signature