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

[Alejandro Colomar <alx@kernel.org>]

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

Hi DJ,

On 2026-07-13T12:24:19-0400, DJ Delorie wrote:
> 
> How about this?

Please split into separate patches with commit messages, and send one
email per patch (the usual git-format-patch(1) + git-send-email(1) would
work).

> diff --git a/man/man5/ld.so.conf.5 b/man/man5/ld.so.conf.5
> index 481cf9152..aa27b73f6 100644
> --- a/man/man5/ld.so.conf.5
> +++ b/man/man5/ld.so.conf.5
> @@ -9,6 +9,14 @@ .SH DESCRIPTION
>  This file contains a list of directories,
>  one per line,
>  in which to search for libraries.

Let's start a new paragraph:

	.P

> +The file allows lines to start with the word
> +.I include
> +followed by a path wildcard,

What is a path wildcard?  We should specify it, since different programs
treat wildcards differently.  Is it a glob(7)?

> +and will include any files matching that wildcard.
> +The file is parsed by
> +.B \%ldconfig

.BR \%ldconfig (8)

> +and the results stored in
> +.IR /etc/ld.so.cache .
>  .SH FILES
>  .I /etc/ld.so.conf
>  .SH SEE ALSO
> diff --git a/man/man5/tunables.conf.5 b/man/man5/tunables.conf.5
> new file mode 100644
> index 000000000..d24eb0fa5
> --- /dev/null
> +++ b/man/man5/tunables.conf.5
> @@ -0,0 +1,86 @@
> +.TH tunables.conf 5 (date) "Linux man-pages (unreleased)"
> +.SH NAME
> +tunables.conf \- System-wide tunables configuration file

s/System/system/.  See man-pages(7):

     NAME   The name of this manual page.

            See man(7) for important details of the line(s) that should
            follow the .SH NAME command.  All words in this  line  (in‐
            cluding  the word immediately following the "\-") should be
            in lowercase, except where English or technical terminolog‐
            ical convention dictates otherwise.

However, I think 'system-wide' is unnecessary here: 'tunables
configuration file' should be enough.  By being in /etc/, it is known to
be system-wide.

> +.SH SYNOPSIS
> +.nf
> +.B /etc/tunables.conf
> +.fi
> +.SH DESCRIPTION
> +Each line in the file
> +.I /etc/tunables.conf
> +specifies a tunable,
> +which is a name and value separated by an equals sign.

	.P

> +For a list of valid tunables,
> +please consult the glibc manual.

	.P

> +The file allows lines to start with the word
> +.I include
> +followed by a path wildcard,
> +and will include any files matching that wildcard.

Again, a glob(7)?

And:
	.P

> +The file is parsed by
> +.B \%ldconfig

	.BR \%ldconfig (8)

> +and the results stored in
> +.IR /etc/ld.so.cache .
> +.P
> +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).

Which environment variable?
Should we document an ENVIRONMENT section in ldconfig(8)?

> +.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

	.B AT_SECURE

> +(such as setuid, or elevated capabilities)

Do you mean the system call setuid(2)?  Or a setuid program?

> +processes.
> +.TP
> +.B nonsecure
> +.TQ
> +.B $
> +The tunable only applies to non-AT_SECURE processes (this is the default).

	.RB non- AT_SECURE

> +.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 ,

	.IR filters ,

> +which limit the tunables following it, up to the end of the file

Please break the line after the comma.

> +(or end of the included file, or start of a new included file)
> +or a line with only
> +.B []
> +on it.  The syntax is:

New sentence, new line.

> +.IP
> +.EX
> +.RI [ filter : pattern ]
> +.EE

You should indent this compared to the surrounding text:

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

> +.TP
> +.B proc
> +The
> +.I proc
> +filter limits the following tunables to processes starting from the
> +file matching the pattern.

What do you mean by processes starting from the file?  Processes that
exec(3) the file and its children?

> +The file may be fully qualified or just the basename.

'fully qualified' isn't something we say of paths.  We should say an
absolute pathname.  Is it only absolute pathnames and basenames?  How
about relative pathnames?

> +.P
> +Example config file:
> +.IP
> +.EX
> +glibc.malloc.arenas_max=5
> +onlysecure glibc.malloc.arenas_max=1
> +-glibc.pthread.rseq=1

	\-

> +[proc:/bin/bad.program]
> +-glibc.pthread.rseq=0

	\-

> +.EE

Have a lovely night!
Alex

> +.SH FILES
> +.I /etc/ld.so.conf
> +.SH SEE ALSO
> +.BR ld.so (8),
> +.BR ldconfig (8)
> diff --git a/man/man8/ld.so.8 b/man/man8/ld.so.8
> index 5f3c22ef2..40f129b71 100644
> --- a/man/man8/ld.so.8
> +++ b/man/man8/ld.so.8
> @@ -792,7 +792,8 @@ .SH FILES
>  .TP
>  .I /etc/ld.so.cache
>  File containing a compiled list of directories in which to search for
> -shared objects and an ordered list of candidate shared objects.
> +shared objects and an ordered list of candidate shared objects,
> +and any system-wide tunables to be applied.
>  See
>  .BR ldconfig (8).
>  .TP
> diff --git a/man/man8/ldconfig.8 b/man/man8/ldconfig.8
> index 9ac146b44..234169504 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
> @@ -85,6 +87,13 @@ .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 tunables to be applied to all processes.
> +These tunables are stored
> +in the cache and applied to every process at its startup.
>  .SH OPTIONS
>  .TP
>  .BI \-\-format= fmt
> @@ -157,6 +166,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
> @@ -178,8 +193,6 @@ .SH OPTIONS
>  is also specified,
>  the cache is still rebuilt.
>  .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
> @@ -190,11 +203,17 @@ .SH FILES
>  See
>  .BR ld.so.conf (5).
>  .TP
> +.I /etc/tunables.conf
> +See
> +.BR tunables.conf (5).
> +.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.
> +as well as those found in the trusted directories,
> +and any system-wide tunables listed in
> +.IR /etc/tunables.conf .
>  .PD
>  .SH SEE ALSO
>  .BR ldd (1),
> 
> 

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

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