Re: [PATCH v3 2/4] man/man5/tunables.conf: Document system-wide tunables config

[Alejandro Colomar <alx@kernel.org>]

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

Hi DJ,

> Date: 2026-07-31 14:22:24-0400
> From: DJ Delorie <dj@redhat.com>
>
> ---
>  man/man5/tunables.conf.5 | 134 +++++++++++++++++++++++++++++++++++++++
>  1 file changed, 134 insertions(+)
>  create mode 100644 man/man5/tunables.conf.5
> 
> diff --git a/man/man5/tunables.conf.5 b/man/man5/tunables.conf.5
> new file mode 100644
> index 000000000..f96355bed
> --- /dev/null
> +++ b/man/man5/tunables.conf.5
> @@ -0,0 +1,134 @@
> +.TH tunables.conf 5 (date) "Linux man-pages (unreleased)"
> +.SH NAME
> +tunables.conf \- tunables configuration file
> +.SH SYNOPSIS
> +.nf
> +.B /etc/tunables.conf
> +.fi
> +.SH DESCRIPTION
> +Tunables are a feature in the GNU C Library
> +that allows application authors and distribution maintainers
> +to alter the runtime library behavior to match their workload.
> +For a list of supported tunables,
> +please consult the glibc manual
> +that corresponds to your installed version of glibc,
> +or run the following command:
> +.P
> +.in +4n
> +.EX
> +.B ld.so --list-tunables

'-' should be escaped: '\-'

Also, these examples don't need bold.  We use bold to differentiate from
program output, when we have examples that show both a command and its
output.  In this case, being just a simple command, it's fine in roman.

	ld.so \-\-list\-tunables

> +.EE
> +.P
> +Each line in the file
> +.I /etc/tunables.conf
> +specifies a tunable,
> +which is specified with a string of the form
> +.IB name = value \f[R].\f[]
> +.P
> +The syntax allows lines to start with the keyword
> +.I include
> +followed by a path wildcard.
> +The wildcard is a path specification in the
> +.BR \%glob (7)
> +format.

For consistency with patch 1/4, this should use the same wording:

	The syntax allows lines to start with the keyword
	.B include
	followed by a
	.BR glob (7)
	pattern.

It's also much simpler.

> +Matching files will be processed
> +as if their contents were included
> +at that point in the config file.

Same here, for consistency with patch 1/4:

	Files matching that pattern will be processed
	as if their contents were included at that point.

> +.P
> +The file is parsed by
> +.BR \%ldconfig (8)
> +and the results stored in
> +.IR /etc/ld.so.cache .

In patch 1/4 (ld.so.conf(5)), this paragraph is specified above the
specification of 'include'.  We should be consistent.  Do you prefer it
above in both, or below in both?

(I haven't pushed patch 1 yet, so if you want to modify it, I can amend
 it.)

> +The resulting data is read when a new process is created by
> +.IR ld.so .
> +.P
> +Each line may include zero or more keywords or symbols at the beginning,
> +which affect how each tunable affects each processes.
> +The keywords must be separated by whitespace,
> +but the symbols need not be.
> +.TP
> +.B overridable
> +.TQ
> +.B +
> +Allow the tunable to be overridden by the
> +.B GLIBC_TUNABLES
> +environment variable when the process runs
> +(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 applies only to
> +.B AT_SECURE
> +processes,
> +such as one started from a set-user-ID program,
> +or one with elevated capabilities.
> +.TP
> +.B nonsecure
> +.TQ
> +.B $
> +The tunable applies only to
> +.RB non- AT_SECURE
> +processes (this is the default).
> +.TP
> +.B anysecure
> +.TQ
> +.B *
> +The tunable applies to both
> +.B AT_SECURE
> +and
> +.RB non- AT_SECURE
> +processes.
> +.P
> +The file may also contain
> +.IR 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:
> +.P
> +.in +4n
> +.EX
> +.RI [ filter : pattern ]
> +.EE
> +.in
> +.TP
> +.B proc
> +The
> +.B proc
> +filter limits the following tunables to processes
> +whose name matches the pattern.
> +The pattern may be an absolute path
> +or just the base name.
> +.SH FILES
> +.TP
> +.I /etc/tunables.conf
> +.TP
> +.I /etc/ld.so.cache
> +cached copy of tunables
> +.SH EXAMPLES
> +Example configuration file:
> +.P
> +.in +4n
> +.EX
> +glibc.malloc.arenas_max=5
> +onlysecure glibc.malloc.arenas_max=1
> +\-glibc.pthread.rseq=1
> +[proc:/bin/bad.program]
> +\-glibc.pthread.rseq=0
> +[proc:some.program]
> +\-glibc.malloc.mmap_threshold=65536
> +.EE
> +.in
> +.SH SEE ALSO
> +.BR ld.so (8),
> +.BR ldconfig (8)

Except for those consistency issues, it looks quite good to me.  Send
a revision and let me know what to do with patch 1/4, please.


Cheers,
Alex

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

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