Re: man/man8/ldconfig.8: document system-wide tunables

[Alejandro Colomar <alx@kernel.org>]

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

Hi DJ,

On 2026-07-10T14:12:10-0400, DJ Delorie wrote:
> Alejandro Colomar <alx@kernel.org> writes:
> > 	mandoc: .tmp/man/man8/ldconfig.8:212:85: STYLE: input text line longer than 80 bytes: Allow the tunable to...
> 
> Fixed.
> 
> > 	mandoc: .tmp/man/man8/ldconfig.8:250:2: WARNING: skipping paragraph macro: PP empty
> > 	mandoc: .tmp/man/man8/ldconfig.8:270:2: WARNING: skipping paragraph macro: PP empty
> 
> Fixed.  I think.  We need a better language for this ;-)
> 
> > 	lint-man-poems: .tmp/man/man8/ldconfig.8: Use semantic newlines (see man-pages(7)):
> > 	    222:	The tunable only applies to AT_SECURE (i.e. setuid, or elevated
> 
> Maybe fixed?  Better at least.  The linter still complains despite me
> splitting it up:
> 
> .B @
> The tunable only applies to AT_SECURE
> (i.e. setuid, or elevated capabilities)
> processes.

You need to use a dummy character to tell this linter that you really
meant a dot followed by one space which doesn't terminate the sentence.

	(i.e.\& setuid, or elevated capabilities)

Other than that, it's better.

Also, man-pages(7) recommends using 'that is,' instead of 'i.e.,'.

$ MANWIDTH=72 man man-pages | awk '/Use of e.g.,/,/^$/'
   Use of e.g., i.e., etc., a.k.a., and similar
     In  general,  the  use  of  abbreviations  such as "e.g.", "i.e.",
     "etc.", "cf.", and "a.k.a." should be avoided, in favor  of  suit‐
     able  full  wordings ("for example", "that is", "and so on", "com‐
     pare to", "also known as").

> > 	an.tmac:.tmp/man/man8/ldconfig.8:92: style: .IR expects at least 2 arguments, got 1
> > 	an.tmac:.tmp/man/man8/ldconfig.8:195: style: .IR expects at least 2 arguments, got 1
> > 	an.tmac:.tmp/man/man8/ldconfig.8:197: style: .IR expects at least 2 arguments, got 1
> 
> Fixed.
> 
> >> +.SH INCLUDES
> >
> > I think this section belongs in new manual pages, ld.so.conf(5) and
> > tuinables.conf(5), which would describe the formats of those files.
> >> +.SH TUNABLES
> >
> > Same here; I think this belongs in tunables.conf(5).
> 
> I looked for ld.so.conf.5 but didn't see one (which kinda surprised me,
> but a lot of ldconfig isn't documented either in the man pages or in the
> glibc manual) so went with "what was there".  I have a slight preference
> for "get this change in quickly" as glibc is releasing with the new
> funcionality soon(ish) but if you want me to split these two out, I can
> do that too.  Or do it later.

I would very much prefer to split these out.

An incomplete ld.so.conf.5 page would be fine; we don't need to make it
perfect.  But the separate manual page would help keep this
documentation reasonably organized.

I can help to get this quickly in.

> >> +The files
> >> +.IR /etc/ld.so.conf
> >
> > 	s/IR/I/
> 
> Really, really, want a better language for this... ;-)

For remembering these, IR is for alternating italics and roman, and I
is for fully italics.

> 
> diff --git a/man/man8/ldconfig.8 b/man/man8/ldconfig.8
> index ee024b8f6..19f1ddf43 100644
> --- a/man/man8/ldconfig.8
> +++ b/man/man8/ldconfig.8
> @@ -17,6 +17,8 @@ .SH SYNOPSIS
>  .IR conf ]
>  .RB [ \-r\~\c
>  .IR root ]
> +.RB [ \-t\~\c
> +.IR tunconf ]
>  .IR directory \~.\|.\|.
>  .YS
>  .SY /sbin/ldconfig

LGTM.

> @@ -85,6 +87,11 @@ .SH DESCRIPTION
>  .P
>  Failure to follow this pattern may result in compatibility issues
>  after an upgrade.
> +.P
> +If the file
> +.I /etc/tunables.conf
> +exists, it contains one tunable per line.  These tunables are stored

After period, always start a new line.  After the comma, it's more a
matter of taste, but in general encouraged.  (semantic newlines)

	.P
	If the file
	.I /etc/tunables.conf
	exists,
	it contains one tunable per line.
	These tunables are stored in the cache
	and applied to every process at its startup.

> +in the cache and applied to every process at its startup.
>  .SH OPTIONS
>  .TP
>  .BI \-\-format= fmt
> @@ -157,6 +164,12 @@ .SH OPTIONS
>  .I root
>  as the root directory.
>  .TP
> +.BI \-t\~ tunconf
> +Use
> +.I tunconf
> +instead of
> +.IR /etc/tunables.conf .
> +.TP
>  .B \-\-verbose
>  .TQ
>  .B \-v

LGTM.

> @@ -177,9 +190,85 @@ .SH OPTIONS
>  .B \-N
>  is also specified,
>  the cache is still rebuilt.
> +.SH INCLUDES
> +The files
> +.I /etc/ld.so.conf
> +and
> +.I /etc/tunables.conf
> +allow lines to start with the word
> +.I include
> +followed by a path wildcard,
> +and will include any files matching that wildcard.
> +.SH TUNABLES
> +Each line in the file
> +.I /etc/tunables.conf
> +specifies a tunable,
> +which is a name and value separated by an equals sign.
> +Each line may include zero or more words or symbols at the beginning:
> +.TP
> +.B overridable
> +.TQ
> +.B +
> +Allow the tunable to be overridden by the environment variable
> +(this is the default).
> +.TP
> +.B nonoverridable
> +.TQ
> +.B \-
> +Do not allow the tunable to be overridden by the environment variable.
> +.TP
> +.B onlysecure
> +.TQ
> +.B @
> +The tunable only applies to AT_SECURE
> +(i.e. setuid, or elevated capabilities)
> +processes.
> +.TP
> +.B nonsecure
> +.TQ
> +.B $
> +The tunable only applies to non-AT_SECURE processes (this is the default).
> +.TP
> +.B anysecure
> +.TQ
> +.B *
> +The tunable only applies to both AT_SECURE and non-AT_SECURE processes.
> +.P
> +The file may also contain
> +.I filters ,
> +which limit the tunables following it, up to the end of the file
> +(or end of the included file, or start of a new included file)
> +or a line with only
> +.B []
> +on it.  The syntax is:
> +.RS
> +.P

You probably mean .IP, which means indented paragraph.

> +[
> +.I filter
> +:
> +.I pattern
> +]
> +.RE

For examples, we use .EX/.EE sections.  These ensure a monospaced font
in PDF or HTML.  See man-pages(7):

$ MANWIDTH=72 man man-pages | sed -n '/Indentation/,+18p'
   Indentation of structure definitions, shell session logs, and so on
     When  structure definitions, shell session logs, and so on are in‐
     cluded in running text, indent them by 4 spaces (i.e., a block en‐
     closed by .in +4n and .in), format them  using  the  .EX  and  .EE
     macros,  and surround them with suitable paragraph markers (either
     .P or .IP).  For example:

         .P
         .in +4n
         .EX
         int
         main(int argc, char *argv[])
         {
             return 0;
         }
         .EE
         .in
         .P

Is the white space intended?  I'd write one of these, depending on what
you actually mean (if I understood your intention correctly):

	.IP
	.in +4n
	.EX
	.RI [ filter : pattern ]
	.EE
	.in
or
	.IP
	.in +4n
	.EX
	.RI [\~ filter \~:\~ pattern \~]
	.EE
	.in

> +.TP
> +.B proc
> +The
> +.I proc

proc should consistently be in italics or bold, I think.  If it's a
literal value that users should type as is, it should be bold.

> +filter limits the following tunables to processes starting from the
> +file matching the pattern.
> +The file may be fully qualified or just the basename.
> +.P

For continuing the indentation of TP, you probably want IP.

BTW, you can check the effects of your patch as a diff with the
diffman-git(1) script.  It's already provided in some distros, and you
can also find in the repository of this project if your distro hasn't
packaged it yet.  It is a simple shell script, which you can find in
src/bin/diffman-git.  Its documentation is as usual under man/man1/.

Here's how it works:

	$ diffman-git HEAD^^
	--- HEAD^^^:man/man4/console_codes.4
	+++ HEAD^^:man/man4/console_codes.4
	@@ -439,7 +439,7 @@ DESCRIPTION
				       to txt.
	      ESC ] 1 ; txt ST         Set icon name to txt.
	      ESC ] 2 ; txt ST         Set window title to txt.
	-     ESC ] 4 ; num ; txt ST   Set ANSI color num to txt.
	+     ESC ] 4 ; num ; txt ST   Set color num (0‐255) to txt.
	      ESC ] 10 ; txt ST        Set dynamic text color to txt.
	      ESC ] 46 ; name ST       Change log file to name (nor‐
				       mally disabled by a compile‐

If you don't specify a commit, it shows the diff of the changes not
staged.

> +Example config file:
> +.P
> +.RS
> +.nf

You probably want monospace, and not just no-fill.  .EX/.EE sections
achieve this (EXample, Example End).

> +glibc.malloc.arenas_max=5
> +onlysecure glibc.malloc.arenas_max=1
> +-glibc.pthread.rseq=1

Hyphen-minus must be escaped as \-, otherwise, they're interpreted as
hyphens (not the thing you want).


Have a lovely night!
Alex

> +[proc:/bin/bad.program]
> +-glibc.pthread.rseq=0
> +.fi
> +.RE
>  .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
> @@ -191,6 +280,11 @@ .SH FILES
>  one per line,
>  in which to search for libraries.
>  .TP
> +.I /etc/tunables.conf
> +contains a list of tunables,
> +one per line,
> +to apply to all newly created processes.
> +.TP
>  .I /etc/ld.so.cache
>  contains an ordered list of libraries found in the directories
>  specified in
> 

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

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