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

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

[DJ Delorie]

Signed-off-by: DJ Delorie <dj@redhat.com>

---
 man/man5/tunables.conf.5 | 132 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 132 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..44b32d40c
--- /dev/null
+++ b/man/man5/tunables.conf.5
@@ -0,0 +1,132 @@
+.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
+ld.so \-\-list\-tunables
+.EE
+.P
+The file is parsed by
+.BR \%ldconfig (8)
+and the results stored in
+.IR /etc/ld.so.cache .
+The resulting data is read when a new process is created by
+.IR ld.so .
+.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
+.BR \%glob (7)
+pattern.
+Files matching that pattern will be processed
+as if their contents were included at that point.
+.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)
-- 
2.47.3

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

[Alejandro Colomar]

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

Hi DJ,

> Date: 2026-08-03 15:21:31-0400
> From: DJ Delorie <dj@redhat.com>
>
> 
> Signed-off-by: DJ Delorie <dj@redhat.com>

A few minor comments below.

> 
> ---
>  man/man5/tunables.conf.5 | 132 +++++++++++++++++++++++++++++++++++++++
>  1 file changed, 132 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..44b32d40c
> --- /dev/null
> +++ b/man/man5/tunables.conf.5
> @@ -0,0 +1,132 @@
[...]
> +.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)

I'd append within the parentheses:
	, whichever comes first

> +or a line with only
> +.B []
> +on it.

So, this is like an end-all-filters directive, right?

I wonder something: Does a filter end previous filters, or do they
compound until a [] ends them all?

> +The syntax is:
> +.P
> +.in +4n
> +.EX
> +.RI [ filter : pattern ]

Since '[', ':', and ']' are literal, let's put them in bold.  Thus, BI.


Have a lovely day!
Alex

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

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

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

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

[DJ Delorie]

Alejandro Colomar <alx@kernel.org> writes:
> A few minor comments below.

I'll defer a v5 until we finish discussing...

>> +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)
>
> I'd append within the parentheses:
> 	, whichever comes first

"first"?  Or "next"?

>> +or a line with only
>> +.B []
>> +on it.
>
> So, this is like an end-all-filters directive, right?
>
> I wonder something: Does a filter end previous filters, or do they
> compound until a [] ends them all?

There is only ever one filter active at a time.  It stops being the
active filter when another filter is encountered, or the current file
ends, or an include directive.  An empty filter spec (i.e. "[]") is a "no
filters" filter.  It acts as a "new filter" for the purpose of ending
the previous filter, but does not specify a new filter, so no new filter
is active after that.

If you can get that into five words or less, you win ;-)

>> +The syntax is:
>> +.P
>> +.in +4n
>> +.EX
>> +.RI [ filter : pattern ]
>
> Since '[', ':', and ']' are literal, let's put them in bold.  Thus, BI.

Done.

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

[Alejandro Colomar]

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

Hi DJ,

> Date: 2026-08-06 11:33:47-0400
> From: DJ Delorie <dj@redhat.com>
>
> Alejandro Colomar <alx@kernel.org> writes:
> > A few minor comments below.
> 
> I'll defer a v5 until we finish discussing...

Good.  :)

> >> +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)
> >
> > I'd append within the parentheses:
> > 	, whichever comes first
> 
> "first"?  Or "next"?
> 
> >> +or a line with only
> >> +.B []
> >> +on it.
> >
> > So, this is like an end-all-filters directive, right?
> >
> > I wonder something: Does a filter end previous filters, or do they
> > compound until a [] ends them all?
> 
> There is only ever one filter active at a time.  It stops being the
> active filter when another filter is encountered, or the current file
> ends, or an include directive.  An empty filter spec (i.e. "[]") is a "no
> filters" filter.  It acts as a "new filter" for the purpose of ending
> the previous filter, but does not specify a new filter, so no new filter
> is active after that.
> 
> If you can get that into five words or less, you win ;-)

Hmmmm, let's see.  I couldn't do it in five words, but how about this
schematic approach?

	The file may also contain
	.IR filters ,
	which limit the tunables following it,
	The effects of a filter are terminated by
	any of the following:
	.IP \[bu] 3
	The end of the file.
	.IP \[bu]
	The end of an included file.
	.IP \[bu]
	An
	.B include
	directive.
	.IP \[bu]
	A new (possibly empty) filter.

> 
> >> +The syntax is:
> >> +.P
> >> +.in +4n
> >> +.EX
> >> +.RI [ filter : pattern ]
> >
> > Since '[', ':', and ']' are literal, let's put them in bold.  Thus, BI.
> 
> Done.

Since a filter can be empty, we should document that.  If we document
that 'filter:pattern' is optional, it'd be [[filter:pattern]] (with the
appropriate formatting differences: the inner '[' wouldn't be bold).
However, that's likely to be confusing, so let's document that
separately:

	A filter can also be empty:
	.BR [] .
	Such a filter has no effects.


Have a lovely day!
Alex

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

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

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

[DJ Delorie]

Alejandro Colomar <alx@kernel.org> writes:

> Hmmmm, let's see.  I couldn't do it in five words, but how about this
> schematic approach?
>
> 	The file may also contain
> 	.IR filters ,
> 	which limit the tunables following it,
> 	The effects of a filter are terminated by
> 	any of the following:
> 	.IP \[bu] 3
> 	The end of the file.
> 	.IP \[bu]
> 	The end of an included file.
> 	.IP \[bu]
> 	An
> 	.B include
> 	directive.
> 	.IP \[bu]
> 	A new (possibly empty) filter.

I like it as-is, other than "why are there blank lines" but I don't care
about that ;-)

> Since a filter can be empty, we should document that.  If we document
> that 'filter:pattern' is optional, it'd be [[filter:pattern]] (with the
> appropriate formatting differences: the inner '[' wouldn't be bold).
> However, that's likely to be confusing, so let's document that
> separately:
>
> 	A filter can also be empty:
> 	.BR [] .
> 	Such a filter has no effects.

Done.  I put it after the filter list, so the "also" made sense.

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

[Alejandro Colomar]

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

Hi DJ,

> Date: 2026-08-06 16:17:36-0400
> From: DJ Delorie <dj@redhat.com>
>
> Alejandro Colomar <alx@kernel.org> writes:
> 
> > Hmmmm, let's see.  I couldn't do it in five words, but how about this
> > schematic approach?
> >
> > 	The file may also contain
> > 	.IR filters ,
> > 	which limit the tunables following it,
> > 	The effects of a filter are terminated by
> > 	any of the following:
> > 	.IP \[bu] 3
> > 	The end of the file.
> > 	.IP \[bu]
> > 	The end of an included file.
> > 	.IP \[bu]
> > 	An
> > 	.B include
> > 	directive.
> > 	.IP \[bu]
> > 	A new (possibly empty) filter.
> 
> I like it as-is, other than "why are there blank lines" but I don't care
> about that ;-)

We can compact them.  ;-)

	The file may also contain
	.IR filters ,
	which limit the tunables following it,
	The effects of a filter are terminated by
	any of the following:
	.PD 0
	.IP \[bu] 3
	The end of the file.
	.IP \[bu]
	The end of an included file.
	.IP \[bu]
	An
	.B include
	directive.
	.IP \[bu]
	A new (possibly empty) filter.
	.PD

(I haven't tested; I've written it in the mail editor directly)

> > Since a filter can be empty, we should document that.  If we document
> > that 'filter:pattern' is optional, it'd be [[filter:pattern]] (with the
> > appropriate formatting differences: the inner '[' wouldn't be bold).
> > However, that's likely to be confusing, so let's document that
> > separately:
> >
> > 	A filter can also be empty:
> > 	.BR [] .
> > 	Such a filter has no effects.
> 
> Done.  I put it after the filter list, so the "also" made sense.

Thanks!


Have a lovely night!
Alex

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

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

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

[DJ Delorie]

Alejandro Colomar <alx@kernel.org> writes:
> (I haven't tested; I've written it in the mail editor directly)

The placement of the .PD's is important ;-)

I'll send a v5 with these, you can decide if you like them or not.

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

[G. Branden Robinson]

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

At 2026-08-06T16:42:35-0400, DJ Delorie wrote:
> Alejandro Colomar <alx@kernel.org> writes:
> > (I haven't tested; I've written it in the mail editor directly)
> 
> The placement of the .PD's is important ;-)
> 
> I'll send a v5 with these, you can decide if you like them or not.

Managing `PD` placement to achieve "compact lists" is indeed tedious.

If you like, you guys can pilot groff 1.25.0's new `LS` and `LE` macros
for man(7).  I expect to release 1.25.0 in the next week and a half.

Unlike the `MR` macro introduction/reform, `LS` and `LE` can be adopted
early and without any negative consequence except a GNU troff(1) warning
in category `mac`, which is not enabled by default, but which some
people enable for linting purposes.

If even that is unacceptable, you can add the following anywhere after
the `TH` macro call and before your use of `LS`.

.\" Avoid `mac` warnings from groff < 1.25.
.as LS \" empty
.as LE \" empty

Use the `as` request instead of `ds`, lest you clobber groff 1.25's
macro definitions.

So how do `LS` and `LE` help?  Here's groff's "NEWS" file:

*  The an (man) package offers new macros to ease the formatting of
   lists.  Enclose paragraphing macros between `LS` and `LE` to identify
   them as list items.  Doing so can mark them as "compact", ease
   management of their indentation, and supply hints to the output
   driver to improve their rendering (as with HTML).  Lists can be
   nested.  (Sub)sectioning macro calls, and the end of the document,
   close all open lists.  See groff_man(7) for details, and
   groff_man_style(7) for an example.  Thanks to Alex Colomar, Chet
   Ramey, Pádraig Brady, and Stephen Gildea for consultation and
   encouragement, and to Alex for selecting these macros' names.

   Because these macros format no text, documents employing them risk no
   damage to their content if the formatter does not support them.  A
   man(7) document author can choose either to transition to these
   macros, to manage list "compactness" and item indentation with
   existing man(7) package facilities, or to employ both approaches.

...and here's groff_man(7).

   List enclosure macros
...
     .LS type [compactness [indentation]]
            (since groff 1.25) Start (or open) a list.  type is one of
            “definition”, “enumerated”, or “itemized”.  compactness is a
            Boolean value directing suppression of inter‐paragraph
            spacing between list items.  indentation specifies an
            indentation amount for the body of each list item; it is
            then unnecessary to specify this argument to the list item
            macros.  Use IP with a mark argument to represent an
            itemized or enumerated list item, and TP for a definition
            list item.  Use IP without arguments to associate successive
            paragraphs with an existing list item; to these, inter‐
            paragraph spacing applies even in compact lists.

     .LE    (since groff 1.25) End (or close) the most recent open list.

For groff 1.26, I hope to use the "type" property to select appropriate
HTML elements to bracket paragraphs within list enclosures.

See:

https://savannah.gnu.org/bugs/?68335
https://savannah.gnu.org/bugs/?68424

Regards,
Branden

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

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

[DJ Delorie]

The problem I had with .PD placement was not the compactness of the list
itself, but the inter-line spacing between the list and
previous/following paragraphs.  You just have to know to put the .PDs
before the paragraphs that come after the space you want to affect:

.P
normal paragraph
.P
* list item
.PD 0
.P
* list item
.P
* list item
.P
* list item
.PD
.P
normal paragraph

My HTML background had me put the first .PD before the first list item,
which bunched the list up against the previous paragraph.

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

[G. Branden Robinson]

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

At 2026-08-06T23:29:43-0400, DJ Delorie wrote:
> The problem I had with .PD placement was not the compactness of the
> list itself, but the inter-line spacing between the list and
> previous/following paragraphs.  You just have to know to put the .PDs
> before the paragraphs that come after the space you want to affect:

Right.  But having to know that is one of those fiddly details that
deters people from using man(7), no?

https://lore.kernel.org/linux-man/xnse5q90jp.fsf@greed.delorie.com/

> .P
> normal paragraph
> .P
> * list item
> .PD 0
> .P
> * list item
> .P
> * list item
> .P
> * list item
> .PD
> .P
> normal paragraph
> 
> My HTML background had me put the first .PD before the first list
> item, which bunched the list up against the previous paragraph.

Control of this sort of detail of formatting is, I submit, more
straightforward with the new `LS`/`LE` macros forthcoming in groff 1.25.
If you want a (compact) list bunched up against the preceding paragraph,
don't put a `P`[1] between the paragraph text and the list.  If you
don't want it bunched, _do_ put a `P` there.

Here's an illustration of your example above using each method.

$ cat ATTIC/dj-delorie-demo-PD.man
.TH foo 1 2026-08-06 "groff test suite"
.SH Name
foo \- frobnicate a bar
.SH Description
Baz qux.
.P
normal paragraph
.P
* list item 1
.PD 0
.P
* list item 2
.P
* list item 3
.P
* list item 4
.PD
.P
normal paragraph
$ cat ATTIC/dj-delorie-demo-LS-LE.man
.TH foo 1 2026-08-06 "groff test suite"
.SH Name
foo \- frobnicate a bar
.SH Description
Baz qux.
.P
normal paragraph
.P
.LS itemized 1 2n
.IP *
list item 1
.IP *
list item 2
.IP *
list item 3
.IP *
list item 4
.LE
.P
normal paragraph

These render the same.  Here, I'll prove it:

$ nroff -man ATTIC/dj-delorie-demo-PD.man >| dj-PD.txt
$ nroff -man ATTIC/dj-delorie-demo-LS-LE.man >| dj-LS-LE.txt
$ cksum dj-*
3663585518 394 dj-LS-LE.txt
3663585518 394 dj-PD.txt

Since groff 1.25.0 isn't released yet, let me add full disclosure.

$ nroff --version | head -n 1
GNU nroff (groff) version 1.25.0.rc2.16-0e05a

The result?

$ cat dj-LS-LE.txt
foo(1)                       General Commands Manual                      foo(1)

Name
     foo - frobnicate a bar

Description
     Baz qux.

     normal paragraph

     * list item 1
     * list item 2
     * list item 3
     * list item 4

     normal paragraph

groff test suite                   2026‐08‐06                             foo(1)

Regards,
Branden

[1] or its synonyms `PP` or `LP`

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

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

[DJ Delorie]

"G. Branden Robinson" <g.branden.robinson@gmail.com> writes:
> Right.  But having to know that is one of those fiddly details that
> deters people from using man(7), no?

Sure.  I vastly prefer semantic syntax like <ul> in HTML to the
presentation syntax in roff.  My complaint was just that I didn't know
how .PD worked and had to figure out where to put them, because
placement mattered and didn't do what I initially expected.

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

[G. Branden Robinson]

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

At 2026-08-07T00:01:44-0400, DJ Delorie wrote:
> "G. Branden Robinson" <g.branden.robinson@gmail.com> writes:
> > Right.  But having to know that is one of those fiddly details that
> > deters people from using man(7), no?
> 
> Sure.  I vastly prefer semantic syntax like <ul> in HTML to the
> presentation syntax in roff.  My complaint was just that I didn't know
> how .PD worked and had to figure out where to put them, because
> placement mattered and didn't do what I initially expected.

Yes; I believe that's a fair criticism of `PD`, and is one reason I
think the new `LS`/`LE` macros can be helpful to man(7) page authors.

Regards,
Branden

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