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

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

[DJ Delorie]

diff --git a/man/man8/ldconfig.8 b/man/man8/ldconfig.8
index ee024b8f6..8574eae24 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,11 @@ .SH DESCRIPTION
 .P
 Failure to follow this pattern may result in compatibility issues
 after an upgrade.
+.P
+If the file
+.IR /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.
 .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
@@ -177,9 +190,85 @@ .SH OPTIONS
 .B \-N
 is also specified,
 the cache is still rebuilt.
+.SH INCLUDES
+The files
+.IR /etc/ld.so.conf
+and
+.IR /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
+[
+.I filter
+:
+.I pattern
+]
+.RE
+.P
+.TP
+.B proc
+The
+.I proc
+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
+Example config file:
+.P
+.RS
+.nf
+glibc.malloc.arenas_max=5
+onlysecure glibc.malloc.arenas_max=1
+-glibc.pthread.rseq=1
+[proc:/bin/bad.program]
+-glibc.pthread.rseq=0
+.fi
+.RE
+.P
 .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

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

[Alejandro Colomar]

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

Hi DJ,

On 2026-07-09T14:53:09-0400, DJ Delorie wrote:
> 
> diff --git a/man/man8/ldconfig.8 b/man/man8/ldconfig.8

I see some diagnostics after applying this patch:

	$ make lint-man build-catman -R -k
	make: warning: undefined variable 'GNUMAKEFLAGS'
	MANDOC		.tmp/man/man8/ldconfig.8.lint-man.mandoc.touch
	mandoc: .tmp/man/man8/ldconfig.8:212:85: STYLE: input text line longer than 80 bytes: Allow the tunable to...
	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
	make: *** [/srv/alx/src/linux/man-pages/man-pages/contrib/share/mk/lint/man/mandoc.mk:30: .tmp/man/man8/ldconfig.8.lint-man.mandoc.touch] Error 1
	PCRE2GREP	.tmp/man/man8/ldconfig.8.lint-man.poems.touch
	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
	make: *** [/srv/alx/src/linux/man-pages/man-pages/contrib/share/mk/lint/man/poems.mk:30: .tmp/man/man8/ldconfig.8.lint-man.poems.touch] Error 1
	make: Target 'lint-man' not remade because of errors.
	TROFF		.tmp/man/man8/ldconfig.8.cat.set
	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
	make: *** [/srv/alx/src/linux/man-pages/man-pages/contrib/share/mk/build/catman/troff.mk:33: .tmp/man/man8/ldconfig.8.cat.set] Error 1
	make: *** Deleting file '.tmp/man/man8/ldconfig.8.cat.set'
	make: Target 'build-catman' not remade because of errors.

> index ee024b8f6..8574eae24 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,11 @@ .SH DESCRIPTION
>  .P
>  Failure to follow this pattern may result in compatibility issues
>  after an upgrade.
> +.P
> +If the file
> +.IR /etc/tunables.conf

	s/IR/I/

> +exists, it contains one tunable per line.  These tunables are stored

Please use semantic newlines.  See man-pages(7):

$ MANWIDTH=72 man man-pages | awk '/Use semantic newlines/,/^$/'
   Use semantic newlines
     In the source of a manual page, new sentences should be started on
     new lines, long sentences should be split  into  lines  at  clause
     breaks  (commas,  semicolons, colons, and so on), and long clauses
     should be split at phrase boundaries.  This convention,  sometimes
     known as "semantic newlines", makes it easier to see the effect of
     patches, which often operate at the level of individual sentences,
     clauses, or phrases.

> +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
> @@ -177,9 +190,85 @@ .SH OPTIONS
>  .B \-N
>  is also specified,
>  the cache is still rebuilt.
> +.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.

> +The files
> +.IR /etc/ld.so.conf

	s/IR/I/

> +and
> +.IR /etc/tunables.conf

	s/IR/I/

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

Please use semantic newlines.

> +.SH TUNABLES

Same here; I think this belongs in tunables.conf(5).


Have a lovely day!
Alex

> +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
> +[
> +.I filter
> +:
> +.I pattern
> +]
> +.RE
> +.P
> +.TP
> +.B proc
> +The
> +.I proc
> +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
> +Example config file:
> +.P
> +.RS
> +.nf
> +glibc.malloc.arenas_max=5
> +onlysecure glibc.malloc.arenas_max=1
> +-glibc.pthread.rseq=1
> +[proc:/bin/bad.program]
> +-glibc.pthread.rseq=0
> +.fi
> +.RE
> +.P
>  .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 --]

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

[DJ Delorie]

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.

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

>> +The files
>> +.IR /etc/ld.so.conf
>
> 	s/IR/I/

Really, really, want a better language for this... ;-)

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
@@ -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
+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
@@ -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
+[
+.I filter
+:
+.I pattern
+]
+.RE
+.TP
+.B proc
+The
+.I proc
+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
+Example config file:
+.P
+.RS
+.nf
+glibc.malloc.arenas_max=5
+onlysecure glibc.malloc.arenas_max=1
+-glibc.pthread.rseq=1
+[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

Why we're stuck with man(7) (was: man/man8/ldconfig.8: document system-wide tunables)

[G. Branden Robinson]

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

Hi DJ,

At 2026-07-10T14:12:10-0400, DJ Delorie wrote:
> Alejandro Colomar <alx@kernel.org> writes:
> > 	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 ;-)

21 years ago I figured we'd get one that would conquer the world.  We
haven't.  Too bad.  I could have started working on groff back then.

Here's a summary of how we got here.

* man(7) (Bell Labs CSRC, 1979) was "good enough" ("worse is better").
  At least one generation of Unix people came up venerating the
  documents written using it.
* Many, many programmers don't want to _write_ documentation at all.
* Many programmers' managers regard documentation as an unwelcome
  friction slowing down the launch of a Minimum Viable Product.
* Many of the programmers who _do_ want to write documentation don't
  want to compose it in anything more complex than Markdown.
* Markdown can't do semantics.
∴ Goodbye, "semantic Web".

* People who did want a semantic Web ran into problems.
* XML overpromised and underdelivered.
* DocBook-XML was lexically overcomplicated--meaning hard to learn--with
  something like 400 elements.  A part-time practitioner, such as a
  person writing in a "real" programming language, could not retain the
  markup language in their head between periods of exile to
  Documentation Land.  Further, its toolchain, involving stuff like jade
  and opensp, was heavyweight and difficult to work with.  And also
  written in Java because Java was going to be the One Language to Rule
  them All, with C and C++ forgotten, by 2005 or so.
∴ "Semantics" got a bad rap because everyone with a fat wallet who
  backed it bet on a losing horse for the delivery of said semantics.
  They spent 10+ years telling the world that XML was the _only way to
  do semantics_.  And because venture capitalists and tech bros are
  infallible geniuses in black turtlenecks, everybody believed them.

* There's mdoc(7), which one might uncharitably say brought you the
  worst of all worlds.  Semantics?  Yes!  But many element types.  (Only
  about 1/4th as bloated as DocBook, though.  And Ingo Schwarze insists
  you can get by with much less than that.  Until you guess wrong and he
  reviews your document.  ;-) )  And if you don't like *roff as a macro
  system, wait until you discover mdoc!  It implements a macro processor
  on top of your macro processor!  And mdoc(7) was only created in the
  first place because AT&T were such jerks about the licensing of troff
  (and Unix generally).  So the Berkeley CSRG's mandate, I infer, was to
  spec out a macro system that could eventually be ripped free of troff
  and set down on top of something else.
* That decision, taken in maybe 1987 or 1988, predated by only one year
  the advent of James Clark's "groff", which BSD promptly shipped in
  Net/2 and later 4.4BSD.  (Later, its descendants ripped it out
  again, because GPL and C++ bad.  BAD!)
* That "other" macro system didn't arrive until about 2010, in the shape
  of mdocml(1)--now known as mandoc(1)--which, because man(7) documents
  had not had the decency to shrink below 90-95% of man pages on all
  systems, ended up reimplementing huge chunks of...troff.
∴ Almost the only people writing mdoc(7) are strident BSD partisans.
  You can write your man page in mdoc(7), but sooner or later you'll be
  asked why you aren't running *BSD, and you'll get treated like an
  idiot if you don't.  You will then understand how *BSD is a refuge
  from the evangelicalism of GNU people.[1]  ;-)

* In my estimation, TeX could have conquered this space too.  It was
  pristinely engineered (if idiosyncratically implemented), had tons of
  momentum, oodles of capable practitioners, and a benign, deific,
  universally esteemed figure behind it.
* TeX's holy mission is beautiful typography, and it's good at it.
* People read man pages on terminals 90%+ of the time.
* You can't do beautiful typography on terminals.
* Terminals can **** off.
∴ TeX ceded this ground without ever contesting it.

I've ventured my own proposal for the addition of a flexible semantic
system to man(7) with backwards compatibility, at the cost of only two
additional macro names.[2]  Literally no one has expressed interest.

So it goes.

Regards,
Branden

[1] mdoc(7) is fine.  It has some nice features, and insofar as I have
    a command of it, I'm happy to help people draft or improve their man
    pages that use it.  What it is not, is easier than man(7).

[2] https://lists.gnu.org/archive/html/groff/2022-12/msg00075.html

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

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

[Alejandro Colomar]

[-- 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 --]

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

[Alejandro Colomar]

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

Hi DJ,

On 2026-07-10T22:07:00+0200, Alejandro Colomar wrote:
> > 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.

I have added a small ld.so.conf(5) manual page (already pushed to
master).  This will allow you to add stuff there.  If you want to add
a tunables.conf(5) manual page, you can have a look at the ld.so.conf(5)
page.


Cheers,
Alex


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

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

Re: Why we're stuck with man(7) (was: man/man8/ldconfig.8: document system-wide tunables)

[DJ Delorie]

"G. Branden Robinson" <g.branden.robinson@gmail.com> writes:
> * Markdown can't do semantics.

And roff has .IR ;-)

These days, most of the docs I write are in texinfo or HTML (raw html,
not markup).  I think I've experienced most of the formats on your list.
I think I've written converters between many things on your list.

Is there a canonical reference to the flavor of roff that we write to,
for modern systems' man page formatters?

Re: Why we're stuck with man(7) (was: man/man8/ldconfig.8: document system-wide tunables)

[DJ Delorie]

> Is there a canonical reference to the flavor of roff that we write to,
> for modern systems' man page formatters?

Nevermind, found it...

Re: Why we're stuck with man(7) (was: man/man8/ldconfig.8: document system-wide tunables)

[Alejandro Colomar]

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

Hi DJ,

On 2026-07-10T18:11:09-0400, DJ Delorie wrote:
> 
> "G. Branden Robinson" <g.branden.robinson@gmail.com> writes:
> > * Markdown can't do semantics.
> 
> And roff has .IR ;-)
> 
> These days, most of the docs I write are in texinfo or HTML (raw html,
> not markup).  I think I've experienced most of the formats on your list.
> I think I've written converters between many things on your list.
> 
> Is there a canonical reference to the flavor of roff that we write to,
> for modern systems' man page formatters?

groff_man(7) and groff_man_style(7) are what you're looking for,
I believe.


Cheers,
Alex

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

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

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

[DJ Delorie]

How about this?

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.
+The file allows lines to start with the word
+.I include
+followed by a path wildcard,
+and will include any files matching that wildcard.
+The file is parsed by
+.B \%ldconfig
+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
+.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.
+For a list of valid tunables,
+please consult the glibc manual.
+The file allows lines to start with the word
+.I include
+followed by a path wildcard,
+and will include any files matching that wildcard.
+The file is parsed by
+.B \%ldconfig
+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).
+.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
+(such as 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:
+.IP
+.EX
+.RI [ filter : pattern ]
+.EE
+.TP
+.B proc
+The
+.I proc
+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
+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
+.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),

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

[Alejandro Colomar]

[-- 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 --]

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

[DJ Delorie]

Alejandro Colomar <alx@kernel.org> writes:
> Please split into separate patches with commit messages,

How do you want them split?  Per man page, or one for breaking out
ld.so.conf and one for adding tunables.conf?

Also, I've been using the output of "git show" for these patches.

> Let's start a new paragraph:
>
> 	.P

We still need a better language ;-) ("why doesn't it know to start a
paragraph after a heading?" ;)

>> +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)?

.P
The syntax allows lines to start with the word
.I include
followed by a path wildcard,
and will include any files matching that wildcard.
The wildcard is a path specification in the
.BR \%glob (7)
format.
Files matching that wildcard will be processed
as if their contents were included in the main config file.

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

Fixed.

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

Fixed.

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

Fixed, but that's a lot of one-sentence paragraphs.

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

Fixed.

> Should we document an ENVIRONMENT section in ldconfig(8)?

No, the environment variable is read at runtime, not by ldconfig.

>> +(such as setuid, or elevated capabilities)
>
> Do you mean the system call setuid(2)?  Or a setuid program?

a set-user-ID program.  Fixed.

>> +.IP
>> +.EX
>> +.RI [ filter : pattern ]
>> +.EE
>
> You should indent this compared to the surrounding text:
>
> 	.IP
> 	.in +4n

Isn't that what the .IP does ?

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

It actually means exactly what it says, but I admit it can be confusing.
When the dynamic linker creates a process, and uses the image in file
/file/ as the template, that new process is affected.

i.e.  If you type "/usr/bin/ls" and the filter is "/usr/bin/ls", that
new copy of /usr/bin/ls is affected.

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

No, for security and logical reasons, it cannot be a relative path.  So
you end up with "one specific version of XYZ" or "any version of XYZ".
No wildcards either.  It's intended for rare exceptions.

commit a9b49369175e67e07b556ec28cd2d9d5538c0fe6
Author: DJ Delorie <dj@redhat.com>
Date:   Mon Jul 13 17:30:56 2026 -0400

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

diff --git a/man/man5/ld.so.conf.5 b/man/man5/ld.so.conf.5
index 481cf9152..9954c74bc 100644
--- a/man/man5/ld.so.conf.5
+++ b/man/man5/ld.so.conf.5
@@ -6,9 +6,36 @@ .SH SYNOPSIS
 .B /etc/ld.so.conf
 .fi
 .SH DESCRIPTION
+.P
 This file contains a list of directories,
 one per line,
 in which to search for libraries.
+.P
+The file
+(and any other files included by it)
+is parsed by
+.B \%ldconfig
+and the results stored in
+.IR /etc/ld.so.cache .
+.P
+The syntax allows lines to start with the word
+.I include
+followed by a path wildcard,
+and will include any files matching that wildcard.
+The wildcard is a path specification in the
+.BR \%glob (7)
+format.
+Files matching that wildcard will be processed
+as if their contents were included in the main config file.
+.P
+Example config file:
+.IP
+.EX
+/lib
+/usr/lib
+/usr/local/lib
+include /etc/ld.so.conf.d/*.conf
+.EE
 .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..b983a2bfe
--- /dev/null
+++ b/man/man5/tunables.conf.5
@@ -0,0 +1,112 @@
+.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
+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 syntax allows lines to start with the word
+.I include
+followed by a path wildcard,
+and will include any files matching that wildcard.
+The wildcard is a path specification in the
+.BR \%glob (7)
+format.
+Files matching that wildcard will be processed
+as if their contents were included in the main config file.
+.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 starts.
+.P
+Each line may include zero or more words or symbols at the beginning,
+which affect how each tunable affects each processes:
+.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 only applies to
+.B AT_SECURE
+processes,
+such as a set-user-ID process,
+or one with elevated capabilities.
+.TP
+.B nonsecure
+.TQ
+.B $
+The tunable only applies to
+.RB non- AT_SECURE
+processes (this is the default).
+.TP
+.B anysecure
+.TQ
+.B *
+The tunable only 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:
+.IP
+.EX
+.RI [ filter : pattern ]
+.EE
+.TP
+.B proc
+The
+.I 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.
+.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
+[proc:some.program]
+\-glibc.malloc.mmap_threshold=65536
+.EE
+.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),

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

[G. Branden Robinson]

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

At 2026-07-13T17:33:05-0400, DJ Delorie wrote:
> Alejandro Colomar <alx@kernel.org> writes:
> > Please split into separate patches with commit messages,
> 
> How do you want them split?  Per man page, or one for breaking out
> ld.so.conf and one for adding tunables.conf?
> 
> Also, I've been using the output of "git show" for these patches.
> 
> > Let's start a new paragraph:
> >
> > 	.P
> 
> We still need a better language ;-) ("why doesn't it know to start a
> paragraph after a heading?" ;)

It does.

groff_man(7):

     .SH [heading‐text]
            Set heading‐text as a section heading.  Given no argument,
            SH plants a one‐line input trap; text on the next line
            becomes heading‐text.  The heading text is set in bold (or
            the font specified by the string HF), and, on typesetters,
            slightly larger than the base type size.  If the heading
            font \*[HF] is bold, use of an italic style in heading‐text
            is mapped to the bold‐italic style if available in the font
            family.  The inset level is reset to 1; see subsection
            “Horizontal and vertical spacing” below.  Text lines after
                                                      ^^^^^^^^^^^^^^^^
            the call are set as an ordinary paragraph (P).
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

> > You should indent this compared to the surrounding text:
> >
> > 	.IP
> > 	.in +4n
> 
> Isn't that what the .IP does ?

There were difficulties, some imposed by the previous Linux man-pages
maintainer, Michael Kerrisk.

https://lore.kernel.org/linux-man/a79fc055-c7ab-1793-04eb-eb4f678e5035@gmail.com/

The better language that doesn't yet exist would, of course, solve all
of everyone's problems at once, even the problems that are mutually
exclude each other's solutions.

Regards,
Branden

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

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

[Alejandro Colomar]

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

Hi DJ,

On 2026-07-13T17:33:05-0400, DJ Delorie wrote:
> Alejandro Colomar <alx@kernel.org> writes:
> > Please split into separate patches with commit messages,
> 
> How do you want them split?  Per man page, or one for breaking out
> ld.so.conf and one for adding tunables.conf?

One per logical change.

The documentation of tunables is one logical change, even if it covers
several pages.

The documentation of an include directive in ld.so.conf(5) is a separate
logical change.

I think the -t flag of ldconfig(8) could be considered a separate change
too.

> 
> Also, I've been using the output of "git show" for these patches.

I suggest using git-format-patch(1).  It's very similar to git-show(1),
except that it can then be applied on my side with git-am(1).

git-format-patch(1) is best paired with git-send-email(1), but if that's
too inconvenient for you, you can paste it as if it were the output of
git-show(1).  For that, you may want to use the --stdout flag of
git-format-patch(1).

> > Let's start a new paragraph:
> >
> > 	.P
> 
> We still need a better language ;-)

I actually like it for its simplicity.  Once you learn the few macros,
there's not much more that you need to learn.

> ("why doesn't it know to start a
> paragraph after a heading?" ;)

There's no heading (what do you consider a heading?).  It was just a
new line after period.

Actually, after a heading (a section heading is .SH) it knows to start
a new paragraph:

	.SH DESCRIPTION
	First paragraph.
	No need for '.P' before this.
	.P
	Second paragraph.

But that text was:

	@@ -9,6 +9,14 @@ .SH DESCRIPTION
	 This file contains a list of directories,
	 one per line,
	 in which to search for libraries.
	+The file allows lines to start with the word
	+.I include
	+followed by a path wildcard,
	+and will include any files matching that wildcard.

So we need a .P because there's just text there (no headings).

> >> +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)?
> 
> .P
> The syntax allows lines to start with the word
> .I include
> followed by a path wildcard,
> and will include any files matching that wildcard.
> The wildcard is a path specification in the
> .BR \%glob (7)
> format.

'wildcard' is a technical term referring to a specific pattern (a string
containing '?', '*', or '[') in glob(7).  I suggest using 'glob(7)
pattern' instead.  How about this?:

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

> Files matching that wildcard will be processed

And then
	Files matching that pattern will be processed

> as if their contents were included in the main config file.
> 
> >> +and will include any files matching that wildcard.
> >> +The file is parsed by
> >> +.B \%ldconfig
> >
> > .BR \%ldconfig (8)
> 
> Fixed.
> 
> > 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.
> 
> Fixed.
> 
> >> +.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
> 
> Fixed, but that's a lot of one-sentence paragraphs.

Given they are about different topics, that's fine.  Especially, since
the page is small.  Eyes will be able to find the information they want
easily, skipping paragraphs that are not interesting.  Otherwise, the
brain must parse the entire paragraph, looking for the sentence that is
interesting.

> >> +.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?
> 
> Fixed.
> 
> > Should we document an ENVIRONMENT section in ldconfig(8)?
> 
> No, the environment variable is read at runtime, not by ldconfig.

Then maybe document this environment vairable in ld.so(8) (which already
has an ENVIRONMENT section)?

> >> +(such as setuid, or elevated capabilities)
> >
> > Do you mean the system call setuid(2)?  Or a setuid program?
> 
> a set-user-ID program.  Fixed.
> 
> >> +.IP
> >> +.EX
> >> +.RI [ filter : pattern ]
> >> +.EE
> >
> > You should indent this compared to the surrounding text:
> >
> > 	.IP
> > 	.in +4n
> 
> Isn't that what the .IP does ?

Oh, sorry, I misread the context.  So, you're already outside of the
tagged paragraph, and back in the non-indented text.  Then, we want:

	.P
	.in +4n
	...
	.in

The reason we use .in instead of .IP is to have a consistent indentation
level that can be applied independent of whether we're in a P or IP
paragraph (sometimes we want P, and sometimes IP; whatever the context
uses).

> >> +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?
> 
> It actually means exactly what it says, but I admit it can be confusing.
> When the dynamic linker creates a process, and uses the image in file
> /file/ as the template, that new process is affected.
> 
> i.e.  If you type "/usr/bin/ls" and the filter is "/usr/bin/ls", that

"type" isn't very specific.  The shell first forks, which I guess isn't
important, and then that file is exec(3)'d, which (I guess) is what
triggers all this?

> new copy of /usr/bin/ls is affected.

Hmm.

> >> +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?
> 
> No, for security and logical reasons, it cannot be a relative path.  So
> you end up with "one specific version of XYZ" or "any version of XYZ".
> No wildcards either.  It's intended for rare exceptions.

Ok.  Then basename or absolute pathname, I think.

> 
> commit a9b49369175e67e07b556ec28cd2d9d5538c0fe6
> Author: DJ Delorie <dj@redhat.com>
> Date:   Mon Jul 13 17:30:56 2026 -0400
> 
>     man/man8/ldconfig.8: document system-wide tunables
> 
> diff --git a/man/man5/ld.so.conf.5 b/man/man5/ld.so.conf.5
> index 481cf9152..9954c74bc 100644
> --- a/man/man5/ld.so.conf.5
> +++ b/man/man5/ld.so.conf.5
> @@ -6,9 +6,36 @@ .SH SYNOPSIS
>  .B /etc/ld.so.conf
>  .fi
>  .SH DESCRIPTION
> +.P
>  This file contains a list of directories,
>  one per line,
>  in which to search for libraries.
> +.P
> +The file
> +(and any other files included by it)
> +is parsed by
> +.B \%ldconfig
> +and the results stored in
> +.IR /etc/ld.so.cache .
> +.P
> +The syntax allows lines to start with the word
> +.I include
> +followed by a path wildcard,
> +and will include any files matching that wildcard.
> +The wildcard is a path specification in the
> +.BR \%glob (7)
> +format.
> +Files matching that wildcard will be processed
> +as if their contents were included in the main config file.
> +.P
> +Example config file:

I think the example should go in an EXAMPLES section after FILES and
before SEE ALSO.  (See man-pages(7) for the order of sections.)

> +.IP
> +.EX
> +/lib
> +/usr/lib
> +/usr/local/lib
> +include /etc/ld.so.conf.d/*.conf
> +.EE
>  .SH FILES
>  .I /etc/ld.so.conf

	.SH
	Example configuration file:
	.P
	.in +4n
	.EX
	/lib
	/usr/lib
	/usr/local/lib
	include /etc/ld.so.conf.d/*.conf
	.EE
	.in

>  .SH SEE ALSO
> diff --git a/man/man5/tunables.conf.5 b/man/man5/tunables.conf.5
> new file mode 100644
> index 000000000..b983a2bfe
> --- /dev/null
> +++ b/man/man5/tunables.conf.5
> @@ -0,0 +1,112 @@
> +.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
> +Each line in the file
> +.I /etc/tunables.conf
> +specifies a tunable,

Maybe we can say it more visually:

	which is a string of the form
	.IB name = value \f[R].\f[]

> +which is a name and value separated by an equals sign.
> +.P
> +For a list of valid tunables,
> +please consult the glibc manual.

Any specific link?

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

	followed by a path glob(7) pattern,

> +and will include any files matching that wildcard.

The line above seems redundant with the sentence 'Files matching ...'.
I'd remove this line, as the other seems more specific.

> +The wildcard is a path specification in the
> +.BR \%glob (7)
> +format.

And then remove the sentence above.

> +Files matching that wildcard will be processed
> +as if their contents were included in the main config file.

s/wildcard/pattern/

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

Is this accurate?  New processes start with fork(1), but it's when they
exec(1) that the actual file that they run is loaded.

> +.P
> +Each line may include zero or more words or symbols at the beginning,

s/include/be preceded by/?

Also, maybe s/words/keywords/?

Also, is white space important after a symbol?  Is it optional,
mandatory, or forbidden?

> +which affect how each tunable affects each processes:
> +.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.

	the
	.B GLIBC_TUNABLES
	environment variable.

> +.TP
> +.B onlysecure
> +.TQ
> +.B @
> +The tunable only applies to

s/only applies/applies only/

> +.B AT_SECURE
> +processes,

Is it really processes or programs?  

> +such as a set-user-ID process,

Same here.  Set-user-ID is a property of a program, not of a process,
I believe.  In fact, no ocurrences of set-user-ID in the manual pages
are followed by 'process', and 10 are followed by 'program':

	$ grep -ro set-user-ID.pro.... 
	man3/getlogin.3:set-user-ID program
	man3/realpath.3:set-user-ID program
	man7/pthreads.7:set-user-ID program
	man7/user_namespaces.7:set-user-ID program
	man7/credentials.7:set-user-ID program
	man7/capabilities.7:set-user-ID program
	man7/keyrings.7:set-user-ID program
	man2/access.2:set-user-ID program
	man2/access.2:set-user-ID program
	man2/execve.2:set-user-ID program

> +or one with elevated capabilities.
> +.TP
> +.B nonsecure
> +.TQ
> +.B $
> +The tunable only applies to
> +.RB non- AT_SECURE
> +processes (this is the default).
> +.TP
> +.B anysecure
> +.TQ
> +.B *
> +The tunable only 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:
> +.IP

	.P
	.in +4n

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

	.in

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

Since it's a literal value:

	.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.
> +.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
> +[proc:some.program]
> +\-glibc.malloc.mmap_threshold=65536
> +.EE

The example should go to EXAMPLES after FILES.

> +.SH FILES
> +.I /etc/ld.so.conf

	.SH EXAMPLES
	Example configuration file:
	.P
	.in +4n
	.EX
	...
	.EE


Have a lovely night!
Alex

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

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

[G. Branden Robinson]

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

[self-follow-up]

At 2026-07-13T17:22:37-0500, G. Branden Robinson wrote:
> At 2026-07-13T17:33:05-0400, DJ Delorie wrote:
> > Alejandro Colomar <alx@kernel.org> writes:
> > > You should indent this compared to the surrounding text:
> > >
> > > 	.IP
> > > 	.in +4n
> > 
> > Isn't that what the .IP does ?
> 
> There were difficulties, some imposed by the previous Linux man-pages
> maintainer, Michael Kerrisk.

I worded that sentence like crap, and threw shade on Michael when I
didn't mean to.  There was a very pretty _constraint problem_ that
Michael posed to me--one I was unable to solve.  Sorry, Michael!

I sympathize with the problem, and don't often endorse "punching through
the floor" to employ "raw" *roff requests in a man(7) document, but this
was an exception.  The Linux man-pages corpus is huge; Michael then and
Alex now have a large management challenge, so it's reasonable to
facilitate shuffling EX/EE examples from place to place in that corpus
with simple copy-and-paste operations.

> https://lore.kernel.org/linux-man/a79fc055-c7ab-1793-04eb-eb4f678e5035@gmail.com/

That link remains a good précis of the problem.  One could show up my
man(7) composition abilities and earn my gratitude by solving that
constraint problem using only macros from the package.  :)

Alternatively, if I think of a backward-compatible extension I can add
to groff man(7) that would eliminate the need for these `in` requests,
I'd likely implement it.  I welcome design suggestions!

I should not send mails after a 12-hour session preparing a release
candidate...

Regards,
Branden

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

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

[DJ Delorie]

"G. Branden Robinson" <g.branden.robinson@gmail.com> writes:
> That link remains a good précis of the problem.  One could show up my
> man(7) composition abilities and earn my gratitude by solving that
> constraint problem using only macros from the package.  :)

We already process all the raw files to fill in the date and version.
Add the .in macros around .EX there?

There are 1528 .EX's in the tree, but a short perl script should be able
to fix them all up.  Note: there are 336 .EX's that do not have the .in,
and two .EX's that do not have a closing .EE.

Turns out Gemini is good at perl.

Anyway, doing this as a postprocessor would let us purge the hacks and
make .EX/.EE properly semantic again, while retaining our desired
appearance.  It's also one more bit of folklore new authors won't need
to learn ;-)

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

[Alejandro Colomar]

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

Hi DJ,

On 2026-07-14T22:34:15-0400, DJ Delorie wrote:
> "G. Branden Robinson" <g.branden.robinson@gmail.com> writes:
> > That link remains a good précis of the problem.  One could show up my
> > man(7) composition abilities and earn my gratitude by solving that
> > constraint problem using only macros from the package.  :)
> 
> We already process all the raw files to fill in the date and version.

The TH line is already special, so filling the date and version is
relatively easy.  It's in the file "share/mk/build/man/nonso.mk":

$(_NONSO): $(_MANDIR)/%: $(MANDIR)/% $(MK) | $$(@D)/
	$(info	$(INFO_)SED		$@)
	<$< \
	$(SED) "/^\.TH /s/(date)/$$($(MANPAGEDATECMD))/" \
	| $(SED) '/^\.TH /s/(unreleased)/$(DISTVERSION)/' \
	| $(SED) '/^\.Dd /s/$$Mdocdate$$'"/$$($(MANPAGEDATECMD))/" \
	| $(SED) '/^\.Os /s/(unreleased)/$(DISTVERSION)/' \
	>$@

> Add the .in macros around .EX there?

But we'd need to know where to add them.  There are cases of EX/EE that
don't need to be surrounded by '.in' (otfen, those that take an entire
section, but also those in SYNOPSIS).  Maybe we could have a full list
of exceptions and write a stripy for that, but...

Also, the manual pages should be readable in the form they exist in the
repository (and match as much as possible how it will render when
installed).  That makes it easy to see if a change works, by running
man(1) on the source code.  If we had to build the pages before being
able to read them, it would add some friction to contributors reading
what they write.

> There are 1528 .EX's in the tree, but a short perl script should be able
> to fix them all up.  Note: there are 336 .EX's that do not have the .in,

I guess those are all (or most) in EXAMPLES and SYNOPSIS.

> and two .EX's that do not have a closing .EE.

Hmmm, indeed:

	$ diff -u \
		<(find man/ -type f \
			| sort \
			| xargs grep '^\.EX$' \
			| sed 's/\.EX/.EE/') \
		<(find man/ -type f \
			| sort \
			| xargs grep '^\.EE$');
	--- /dev/fd/63	2026-07-15 13:39:48.230169833 +0200
	+++ /dev/fd/62	2026-07-15 13:39:48.230169833 +0200
	@@ -140,7 +140,6 @@
	 man/man2/io_submit.2:.EE
	 man/man2/io_submit.2:.EE
	 man/man2/ioctl_eventpoll.2:.EE
	-man/man2/ioctl_eventpoll.2:.EE
	 man/man2/ioctl_fsmap.2:.EE
	 man/man2/ioctl_kd.2:.EE
	 man/man2/ioctl_kd.2:.EE
	@@ -1460,7 +1459,6 @@
	 man/man7/string_copying.7:.EE
	 man/man7/string_copying.7:.EE
	 man/man7/string_copying.7:.EE
	-man/man7/string_copying.7:.EE
	 man/man7/string_copying.7:.EE
	 man/man7/string_copying.7:.EE
	 man/man7/string_copying.7:.EE

Hmmm, this sounds like a good linter that I should add to the build
system.  I can make it general for all macros that must always come in
pairs.

BTW, Branden, I expect this would have been diagnosed by either groff(1)
or mandoc(1).  Why isn't it?

I've pushed a fix for EX/EE pairs.

	commit 4d872e2747885ee2ae6139b9bc78cc3123392b72
	Author: Alejandro Colomar <alx@kernel.org>
	Date:   2026-07-15 13:42:14 +0200

	    man/: srcfix
	    
	    Add missing closing EE for EX.
	    
	    Reported-by: DJ Delorie <dj@redhat.com>
	    Signed-off-by: Alejandro Colomar <alx@kernel.org>

I've checked that no other pairs of man(7) macros are not balanced.

	$ find man -type f | xargs src/bin/lintman-pairs 
	--- /dev/fd/63	2026-07-15 14:42:44.957949101 +0200
	+++ /dev/fd/62	2026-07-15 14:42:44.957949101 +0200
	@@ -668,7 +668,6 @@
	 man/man7/string_copying.7:.EE
	 man/man7/string_copying.7:.EE
	 man/man7/string_copying.7:.EE
	-man/man7/string_copying.7:.EE
	 man/man7/user_namespaces.7:.EE
	 man/man7/user_namespaces.7:.EE
	 man/man7/user_namespaces.7:.EE
	@@ -1313,7 +1312,6 @@
	 man/man2/epoll_wait.2:.EE
	 man/man2/epoll_wait.2:.EE
	 man/man2/ioctl_eventpoll.2:.EE
	-man/man2/ioctl_eventpoll.2:.EE
	 man/man2/landlock_restrict_self.2:.EE
	 man/man2/sendmmsg.2:.EE
	 man/man2/sendmmsg.2:.EE

Where the script is:

	$ cat src/bin/lintman-pairs 
	#!/bin/bash
	#
	# Copyright, the authors of the Linux man-pages project
	# SPDX-License-Identifier: GPL-3.0-or-later

	set -Eefuo pipefail;


	err()
	{
		>&2 printf '%s\n' "$(basename "$0"): error: $*";
		exit 2;
	}


	if test $# -lt 1; then
		err "Missing files.";
	fi;
	files="$@";


	check_pair()
	{
		diff -u \
			<(grep "^\.$1\>" /dev/null $files | sed "/\.$1\>/s/:.*/:.$2/") \
			<(grep "^\.$2\>" /dev/null $files | sed "/\.$2\>/s/:.*/:.$2/");
	}


	check_pair 'EX' 'EE';
	check_pair 'MT' 'ME';
	check_pair 'RS' 'RE';
	check_pair 'SY' 'YS';
	check_pair 'UR' 'UE';


> Turns out Gemini is good at perl.

Please don't use LLMs for contributing to this project.  The file
"CONTRIBUTING.d/ai" contains our guidelines for their use, which
essentially says it's not allowed.

> Anyway, doing this as a postprocessor would let us purge the hacks and
> make .EX/.EE properly semantic again, while retaining our desired
> appearance.  It's also one more bit of folklore new authors won't need
> to learn ;-)


Have a lovely day!
Alex

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

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

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

[DJ Delorie]

Alejandro Colomar <alx@kernel.org> writes:
>> Add the .in macros around .EX there?
>
> But we'd need to know where to add them.  There are cases of EX/EE that
> don't need to be surrounded by '.in'

Ok, now you have a new rule that's even easier to not know about :-P

> Also, the manual pages should be readable in the form they exist in the
> repository

Not a problem here, a different indentation doesn't affect readability.

> (and match as much as possible how it will render when
> installed).

Er, close?  ;-)

Is ".in +4n" the default for .EX, unless the user changed it?  I wonder
how often that case comes up.  I wonder because I would need to review
an example of the problem to figure out how to search for it ;-)

Now I wonder if the problem case is predictable enough to have the
preprocessor *know* when .EX needs the .in +4n, and when it doesn't...

> That makes it easy to see if a change works, by running man(1) on the
> source code.

Yup, I have my own lman script that acts like man(1) but takes a
filename instead of a man page reference, finds it in the tree, and
formats it with underscores, italics, bold, *and* color!

Perhaps such a helper could be included in the git repo, just for
authors?

>> and two .EX's that do not have a closing .EE.
>> Turns out Gemini is good at perl.
>
> Please don't use LLMs for contributing to this project.

None of the patches I've sent include anything AI-generated, nor would I
attempt such a thing without disclosure, because I understand and agree
with the legal and quality issues of AI-generated output.  However, I
won't not use AI to help me understand the problems I'm trying to solve,
or optimize any diagnosing I need to do.  My time is too precious to be
stupid on purpose.

What I did was tell Gemini what I was looking for, and it wrote a perl
script faster than I could open my editor.  Cut, paste, run, throw it
away.  That was just for the statistics, of course.  If we added a
preprocessor script to the build itself, then (1) I wouldn't use AI, and
(2) it would be sed instead of perl anyway, to avoid another dependency.

Ok, now I looked for it, and we *already* use a perl script to
preprocess the files, in scripts/mk/build/pdf/book/prepare.pl.  (this
just means perl is not a new dependency, so we *could* use perl instead
of sed)

> The file "CONTRIBUTING.d/ai" contains our guidelines for their use,
> which essentially says it's not allowed.

glibc is the same way, I'm used to that.

However, glibc decided that it has no place dictating how the user uses
AI *outside* of creating the patch itself.  Yes, that includes linters,
analyzers, and perl scripts that generate statistics so I can understand
what I'm working on.

I refuse to follow any policy that tells me what my morals should be in
the privacy of my own home.

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

[G. Branden Robinson]

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

Hi DJ,

At 2026-07-15T10:33:58-0400, DJ Delorie wrote:
> Alejandro Colomar <alx@kernel.org> writes:
> >> Add the .in macros around .EX there?
> >
> > But we'd need to know where to add them.  There are cases of EX/EE
> > that don't need to be surrounded by '.in'
> 
> Ok, now you have a new rule that's even easier to not know about :-P

The man(7) package doesn't impose a rigid stylesheet on its output.
Many decisions about presentation and layout have to be made at the
project level.  Historically, there have been, for example, many
differences of opinion over whether items like file names, environment
variable names, function names, data types, parameters to functions, and
names of other man pages should be set in roman, bold, or italic.

One solution to this problem is to come up with an element name for
every distinguishable syntactical item of interest.  That's how
DocBook-XML ended up with something like 400 tags.  Granted, its scope
was intended to be an entire camera-ready technical book, like one in
the O'Reilly Nutshell series.  *roff macro packages for man pages have a
narrower scope.  Thus, the "semantic" mdoc(7) package has a mere ~100
macro names, including gems like the following.

groff_mdoc(7):
     .Ot  Usage unknown.  The mdoc sources describe it as “old function
          type (fortran)”.

     .Fr  is an obsolete means of specifying a function return value.

                Usage: .Fr return‐value ...

          ‘Fr’ allows a break right before the return value (usually a
          single digit) which is bad typographical behaviour.  Instead,
          set the return value with the rest of the code, using ‘\~’ to
          tie the return value to the previous word.

          Its default width is 12n.

     .Me  Usage unknown.  The mdoc sources describe it as a macro for
          “menu entries”.

          Its default width is 6n.

The only alternative I know of to not exhaustively cataloging every type
of "thing" one might use to compose a man page is to write down rules
governing the usage of a smaller lexicon, which itself is necessarily
semantically "loose", and thus frequently derided as "presentational".

There is, potentially, a _third_ option, which I mentioned in my earlier
email.  As I said, literally no one expressed interest.

https://lore.kernel.org/linux-man/xno6ge8p38.fsf@greed.delorie.com/T/#m9fda91ba28ca257c67d4595f81d38b32c5c9c937

> Is ".in +4n" the default for .EX, unless the user changed it?

No, meddling with indentation is not part of `EX`'s job at all.

groff_man(7):
     .EX
     .EE    Begin and end example.  After EX, filling is disabled (and,
            on typesetters, a monospaced font family is selected).
            Calling EE enables filling (and restores the previous
            family).

            Ninth Edition Unix introduced the EX and EE extensions.
            Documenter’s Workbench (DWB), Heirloom Doctools, and Plan 9
            troffs, and mandoc (since 1.12.2) support them.  Solaris
            troff does not.

> I wonder how often that case comes up.  I wonder because I would need
> to review an example of the problem to figure out how to search for it
> ;-)

It wouldn't be hard to snapshot a text dump of all the man-pages
project's documents, as with "nroff -t -mandoc", do a "sed -i '/^\.in/d'
man/man*" over the tree, snapshot another dump, and study the diff.

It's the sort of thing I'd try out were I on a mission to eradicate `in`
request usage from the man-pages project's documents, but I have no such
mission.

> Now I wonder if the problem case is predictable enough to have the
> preprocessor *know* when .EX needs the .in +4n, and when it doesn't...

What preprocessor?

> Ok, now I looked for it, and we *already* use a perl script to
> preprocess the files, in scripts/mk/build/pdf/book/prepare.pl.  (this
> just means perl is not a new dependency, so we *could* use perl
> instead of sed)

That script is used just to generate a PDF of one or two man page
corpora.  Deri James and Brian Inglis participate in groff development.
(Deri is the author of gropdf(1).)  The script is there to get older
versions of groff "over the hump" while we implemented PDF and
hyperlinking support directly within groff itself.  (That work was
substantially delivered in the groff 1.23 release in July 2023; note the
script's date of December 2022.)  I see that it also has some features
to stylistically massage Research Tenth Edition Unix man pages.

"prepare.pl" is not a general-purpose preprocessor that can or should be
run over a given document in the Linux man-pages.  As I understand it,
one of Alex's objectives, as was Michael's before, is to keep the files
in the man/man* directories directly renderable with "man -l".

Regards,
Branden

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

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

[Alejandro Colomar]

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

Hi DJ,

On 2026-07-15T10:33:58-0400, DJ Delorie wrote:
> Alejandro Colomar <alx@kernel.org> writes:
> >> Add the .in macros around .EX there?
> >
> > But we'd need to know where to add them.  There are cases of EX/EE that
> > don't need to be surrounded by '.in'
> 
> Ok, now you have a new rule that's even easier to not know about :-P

It's not that they don't need to be surrounded, but rather that they
must be not surrounded, actually.

An example is the SNOPSIS of timeval(3type):

	$ man -w timeval | xargs mansect SYNOPSIS;
	.lf 1 /usr/local/man/man3type/timeval.3type
	.TH timeval 3type 2026-02-08 "Linux man-pages 6.18-154-g618fb5732fc4"
	.SH SYNOPSIS
	.EX
	.B #include <sys/time.h>
	.P
	.B struct timeval {
	.BR "    time_t       tv_sec;" "   /* Seconds */"
	.BR "    suseconds_t  tv_usec;" "  /* Microseconds */"
	.B };
	.EE

We certainly don't want to indent that, but we want it to be monospaced,
so that the fields are aligned (in PDF, PS, and HTML).

	$ man -w timeval | MANWIDTH=64 xargs mansectf SYNOPSIS | cat;
	timeval(3type)                                   timeval(3type)

	SYNOPSIS
	     #include <sys/time.h>

	     struct timeval {
		 time_t       tv_sec;   /* Seconds */
		 suseconds_t  tv_usec;  /* Microseconds */
	     };

	Linux man‐pages 6.18‐15... 2026‐02‐08            timeval(3type)

EX/EE should not try to indent stuff, since indentation is not always
appropriate (even if we try to minimize differences/inconsistencies).

> > Also, the manual pages should be readable in the form they exist in the
> > repository
> 
> Not a problem here, a different indentation doesn't affect readability.

More than readable; I think it's a feature that the page is exactly the
same as what users will read in their computers.  That allows
contributors to look at what they've written, and know if it makes sense
or not.  If they had to build it to see slight differences, I expect
many would complain.

> > (and match as much as possible how it will render when
> > installed).
> 
> Er, close?  ;-)
> 
> Is ".in +4n" the default for .EX, unless the user changed it?  I wonder
> how often that case comes up.  I wonder because I would need to review
> an example of the problem to figure out how to search for it ;-)

When inserted in the middle of running text, we indent the examples.
The main reason is that because terminals use monospaced fonts
everywhere, it's difficult to differentiate examples from the rest of
the page.  The 4-n indentation makes them stand out.
In PDF or HTML, because running text uses proportional fonts, the
examples stand out on their own by being monospaced.

However, when not inserted in the middle of running text, that
indentation is not useful, and is even ugly.  Thus, we don't indent in
those cases.  Most often, this happens in SYNOPSIS and EXAMPLES.

> Now I wonder if the problem case is predictable enough to have the
> preprocessor *know* when .EX needs the .in +4n, and when it doesn't...

I expect I would be able to write a script that differentiates them.
However, as I said, I believe it's better to have the source match
excatly what is installed (ignoring details in the title heading (TH)).

> > That makes it easy to see if a change works, by running man(1) on the
> > source code.
> 
> Yup, I have my own lman script that acts like man(1) but takes a
> filename instead of a man page reference,

man(1) also accepts a path.

	$ MANWIDTH=64 man man/man5/proc_driver.5 | cat
	proc_driver(5)        File Formats Manual        proc_driver(5)

	NAME
	     /proc/driver/ - empty dir

	DESCRIPTION
	     /proc/driver/
		    Empty subdirectory.

	SEE ALSO
	     proc(5)

	Linux man‐pages (unreleased) (date)              proc_driver(5)

> finds it in the tree, and
> formats it with underscores, italics, bold, *and* color!
> 
> Perhaps such a helper could be included in the git repo, just for
> authors?

I'd be interested in at least having a look at it!  It might have
something useful.

BTW, what's the etymology of 'lman', out of curiosity?

> >> and two .EX's that do not have a closing .EE.
> >> Turns out Gemini is good at perl.
> >
> > Please don't use LLMs for contributing to this project.
> 
> None of the patches I've sent include anything AI-generated, nor would I
> attempt such a thing without disclosure, because I understand and agree
> with the legal and quality issues of AI-generated output.

Thanks!

> However, I
> won't not use AI to help me understand the problems I'm trying to solve,
> or optimize any diagnosing I need to do.  My time is too precious to be
> stupid on purpose.

(I'll paste this below to reply.)

> 
> What I did was tell Gemini what I was looking for, and it wrote a perl
> script faster than I could open my editor.  Cut, paste, run, throw it
> away.  That was just for the statistics, of course.

As long as it's for statistics, I won't complain (I mentally might,
because the ethical concerns remain, but not publicly, because it's not
my business), as statistics are not a contribution (at least in this
case).  I might actually doubt the statistics, though, so a disclaimer
of use would be appropriate even for statistics, but as long as it isn't
something that influences in a decision (for example, in merging or
rejecting a patch), it's _relatively_ okay.

>  If we added a
> preprocessor script to the build itself, then (1) I wouldn't use AI, and
> (2) it would be sed instead of perl anyway, to avoid another dependency.
> 
> Ok, now I looked for it, and we *already* use a perl script to
> preprocess the files, in scripts/mk/build/pdf/book/prepare.pl.  (this
> just means perl is not a new dependency, so we *could* use perl instead
> of sed)

I would like to avoid another perl script.  That one exists because its
author wrote it in perl, and I don't understand perl enough to translate
it to something I'd understand and be able to maintain.

If anyone understands perl enough to translate that into a shell script,
I'd appreciate it very much.  :)

I don't mind having perl as a dependency, but I worry about being able
to maintain all the code in the repository, and that existing perl
script is the one little thing I'm unable to maintain.  (Every time a
problem shows up, I need to contact the author.)

> > The file "CONTRIBUTING.d/ai" contains our guidelines for their use,
> > which essentially says it's not allowed.
> 
> glibc is the same way, I'm used to that.

Nice to hear that glibc doesn't allow AI!

> However, glibc decided that it has no place dictating how the user uses
> AI *outside* of creating the patch itself.  Yes, that includes linters,
> analyzers, and perl scripts that generate statistics so I can understand
> what I'm working on.

I'll go with a real case here, although I won't be specific in details,
because I don't remember all of them, and also because it has happened
several times in several projects, so this is generic enough.  In some
other project, a co-maintainer saw a bug report from an AI tool, and
immediately wrote a fix for it.  The bug report was bogus, and prompted
the programmer to write a patch that indeed made the code worse.  I'm
very worried about this kind of problems when using AI for linting code.

Linters directly or indirectly influence the patch, even if they don't
generate the patch verbatim.

Because the world has survived without AI for so many years, I think
it's safer to err on the side of not using it enough, compared to using
it too much.

[pasted again:]
> However, I
> won't not use AI to help me understand the problems I'm trying to solve,
> or optimize any diagnosing I need to do.  My time is too precious to be
> stupid on purpose.

I'm worried that I must insist on the policy in this regard.  If the LLM
makes you misunderstand something, and causes a false sense of
understanding, your contribution might end up having lower quality than
it would.

I offer my help explaining any doubts you may have, if that helps you
reduce any time consumption.

> I refuse to follow any policy that tells me what my morals should be in
> the privacy of my own home.

I don't care about your morals in the privacy of your home.
But I care about the difference between the quality of a patch, and the
quality perceived by the author, and my expectations of the contributor.


Cheers,
Alex

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

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

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

[DJ Delorie]

"G. Branden Robinson" <g.branden.robinson@gmail.com> writes:
> The man(7) package doesn't impose a rigid stylesheet on its output.

Perhaps, but the fact that I now know about the rule, and the exception,
means that it's not entirely flexible either ;-)

> The only alternative I know of to not exhaustively cataloging every type
> of "thing" one might use to compose a man page is to write down rules
> governing the usage of a smaller lexicon, which itself is necessarily
> semantically "loose", and thus frequently derided as "presentational".

In this case, it does sound like the man pages need a different thing
for "example code" (.EX) and "preformatted text" (html's <PRE>).  Or we
need some magic for known types of .SH like SYNOPSIS which are almost
always rendered differently than other sections.

> There is, potentially, a _third_ option, which I mentioned in my earlier
> email.  As I said, literally no one expressed interest.
>
> https://lore.kernel.org/linux-man/xno6ge8p38.fsf@greed.delorie.com/T/#m9fda91ba28ca257c67d4595f81d38b32c5c9c937

glibc uses texinfo, which is TeX but terminals don't have **** off ;-)

I think of texinfo as a "TeX compiler".  I don't write programs in
assembly either (well, usually ;).

I've always advocated for "whatever system means the docs are stored and
edited with the code, that I can turn into whatever I need."  Roff,
html, texinfo, markup, whatever.  I know how to write converters.  DJGPP
had a rule about "every .c must have a .txh" where the .txh was a
texinfo snippet, and these had meta-info in them so the tools knew where
to put them in the manual.  gEDA's pcb had a "comments in code become
manual" system that used a short perl script to merge everything.  Etc.

Yes, I know why the man pages are separate.  I've advocated for the
glibc project to maintain its man pages along with the sources that
affect them, but it's easier to just have glibc developers be man page
contributors too.  I wrote the tunables docs a long time ago, but had to
hold back the patch until I knew which release would have the code
changes, so they would stay in sync.

> It's the sort of thing I'd try out were I on a mission to eradicate `in`
> request usage from the man-pages project's documents, but I have no such
> mission.

Nor do I, but I wondered if there was a programmatic way to automate
this so that the authors don't need to worry about it.  My general rule
is "the third time you repeat something, automate it."  I still don't
have a robot lawn mower, though ;-)

>> Now I wonder if the problem case is predictable enough to have the
>> preprocessor *know* when .EX needs the .in +4n, and when it doesn't...
>
> What preprocessor?

Whatever "sed" scripts we run in the Makefiles, that's all.  Currently
they just fill in the .TH data.

> As I understand it, one of Alex's objectives, as was Michael's before,
> is to keep the files in the man/man* directories directly renderable
> with "man -l".

I agree with that!

I just think we could relax the "and must be formatted exactly as a
release" a bit, in exchange for making it easier to contribute by
removing one or two rules the contributors need to know.

But that assumes that it's (1) purely cosmetic, and (2) automatable.  I
note that "man" formats according to the window's width, so even the
official tools don't honor the "and formatted exactly as" rule.

(wait, when did "man -l" happen?  Have I been missing that all along?
Is my script really that old?)

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

[DJ Delorie]

Alejandro Colomar <alx@kernel.org> writes:
>> Perhaps such a helper could be included in the git repo, just for
>> authors?
>
> I'd be interested in at least having a look at it!  It might have
> something useful.

I'll append it here for posterity.  It's not much.

> BTW, what's the etymology of 'lman', out of curiosity?

"local man page" vs installed man page.

>> What I did was tell Gemini what I was looking for, and it wrote a perl
>> script faster than I could open my editor.  Cut, paste, run, throw it
>> away.  That was just for the statistics, of course.

> I might actually doubt the statistics, though, so a disclaimer of use
> would be appropriate even for statistics,

I did too, and modified the script to show me the uncommon lines so I
could verify it was doing what it was supposed to be doing.

> I would like to avoid another perl script.

Heh ;-)

> That one exists because its author wrote it in perl, and I don't
> understand perl enough to translate it to something I'd understand and
> be able to maintain.

I do, and perl looks like the right choice for that one.  Perhaps in the
future, if it needed maintaining, I could go through and add copious
comments.  For now I'm inclined to just leave it ;-)

> If anyone understands perl enough to translate that into a shell script,
> I'd appreciate it very much.  :)

Perl is just a shell script, for AWK, right?  And AWK is just a shell
script for SED?  <ducks>

>> glibc is the same way, I'm used to that.
>
> Nice to hear that glibc doesn't allow AI!

Well, for legal and technical reasons, not for moral reasons.  The FSF's
stand is similar at the moment - the legal landscape is still too risky
to allow direct contributions derived from AI output.  There is no moral
problem with AI itself, just the way that companies have implemented it
so far.  If you had an AI based on FLOSS sources, run on local hardware,
trained on known copyright-safe inputs, there would be no moral issue
with it.  Home assistant's Piper/Kaldi/HassIL modules are examples of
"moral AI".

> In some other project, a co-maintainer saw a bug report from an AI
> tool,

I hate those, especially when the submitter hasn't bothered to check the
AI's work.  However, AI *has* found some serious bugs (and sometimes
with correct patches) for us.  It needs to mature, but I think it is
already showing it's worth.

> Linters directly or indirectly influence the patch, even if they don't
> generate the patch verbatim.

Yes, but there's no technical solution for stupid.  A contributor who is
inexperienced enough to misuse AI is no different than a contributor who
is inexperienced enough to misuse emacs.  It's our job to help them
become better contributors.

> Because the world has survived without AI for so many years, I think
> it's safer to err on the side of not using it enough, compared to using
> it too much.

The same could be said of any technology, all the way back to the
invention of farming ("hunting and gathering is good enough for
everyone!")

I think the key today is to find out what it *is* good for, and what it
isn't, and try to help the community find AI's place in things.  In my
case, I find it very useful as an "idea generator".  I give it the
basics of a problem and see which rabbit holes it goes down that I
haven't considered yet.  It's also a much better search engine than the
search engines (I used it to find out about the groff_man man page).
However, I treat it like "a recent college grad with a degree in
Everything."  Knowledge but not wisdom, needs oversight.

In our specific case, I wouldn't want AI to write mission-critical
software, but it's a waste of my time to write yet another single-use
20-line perl script to look for patterns in man pages.  Plus, I didn't
ask the AI to give me the statistics, I asked it for the perl script.
It's short enough I can look at it and say "yup, that's what I would
have written", and then *I* run it to get the statistics.

(as an amusing aside, our company encourages us to use AI to automate
boring repetitive tasks.  So I had it do my quarterly self-review.  I
think it did a better job than I would have at making me look good...)

>> However, I won't not use AI to help me understand the problems I'm
>> trying to solve, or optimize any diagnosing I need to do.  My time is
>> too precious to be stupid on purpose.
>
> If the LLM makes you misunderstand something, and causes a false
> sense of understanding, your contribution might end up having lower
> quality than it would.

This is not an LLM problem.  EVERYTHING we use to help us solve problems
could lead to misunderstanding.  I *know* AI can be wrong, and I double
check it all the time.  Please give me some credit for my many decades
of not trusting technology ;-)

> But I care about the difference between the quality of a patch, and the
> quality perceived by the author, and my expectations of the contributor.

Then judge the patch, help the author/contributor improve, and not worry
about the hidden details.  You don't make the author use a specific
editor, or a particular brand of keyboard.  AI is just another tool.
Yes, we should not accept *unmoderated* AI contributions, but how a
human chooses to use the tools available to them is up to them, not us.

--------------------------------------------------
#!/usr/bin/perl
# -*- perl -*-

$MANPATH=$ENV{"MANPATH"};
$MANPATH=".:/usr/local/man";

if ($#ARGVV == 1) {
    $pattern = "^$ARGV[1]\\.$ARGV[0]" . "\\D*";
} else {
    $pattern = "^$ARGV[0]" . "\\.(\\d\\D*|[a-zA-Z]\$)";
}

# print "pattern is $pattern\n";

if ( -f $ARGV[0] ) {
    $page = $ARGV[0];
} else {
    # Find it, including one level of subdirectory.
  DIR:
    for $dir (split(':', $MANPATH)) {
	opendir(D, $dir);
	for $f (sort readdir(D)) {
	    next if $f =~ /^\./;
	    #print "try $dir/$f\n";
	    if ($f =~ m@$pattern@io) {
		$page = "$dir/$f";
		last DIR;
	    }
	    if ( -d "$dir/$f") {
		opendir(SD, "$dir/$f");
		for $sf (sort readdir(SD)) {
		    next if $sf =~ /^\./;
		    #print "try $dir/$f/$sf\n";
		    if ($sf =~ m@$pattern@io) {
			$page = "$dir/$f/$sf";
			last DIR;
		    }
		}
		closedir(SD);
	    }
	}
	closedir(D);
    }
}

unless ($page) {
    print "Not found!\n";
    exit 0;
}
# print "Found $page\n";
# exit 0;

# Get the terminal's width
$stty = `stty size 2>/dev/null`; 
($height, $width) = ($stty =~ m@(\d+)\s+(\d+)@);
$width = $width unless $width > 10;
$width -= 2;

# I prefer no hyphenation when I'm reviewing my changes
$hypenate = "";
#$hyphenate = "-rHY=0";

open(N, "groff -mandoc -Tutf8 -rLL=${width}n $hyphenate -rCR=1 -P-i $page |");
#open(M, "| less -R");
#select M;
while (<N>) {
    # Colorize certain formatting
    s/\033\[1m/\033\[1;32m/g;		# bold -> green
    s/\033\[3m/\033\[3;34m/g;		# italics -> blue
    s/^\033\[1;32m/\033\[1;31m/g;	# section headers are red

    s/\033\[21m/\033\[21;39m/g;		# ending style ends color too
    s/\033\[22m/\033\[22;39m/g;
    s/\033\[23m/\033\[23;39m/g;
    print;
}
close(N);
#close(M);

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

[G. Branden Robinson]

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

Hi DJ,

At 2026-07-15T14:19:49-0400, DJ Delorie wrote:
> "G. Branden Robinson" <g.branden.robinson@gmail.com> writes:
> > The man(7) package doesn't impose a rigid stylesheet on its output.
> 
> Perhaps, but the fact that I now know about the rule, and the
> exception, means that it's not entirely flexible either ;-)

The man(7) macro language is not highly flexible, no, but it didn't need
and wasn't meant to be.  If you punch through the floor to raw *roff,
you can acquire some pretty impressive flexibility, but then draw the
ire of the people who write non-*roff interpreters of man(7).  At some
point in the 1990s, a bunch of Linux people got the notion that man(7)
was a markup language like HTML, and started writing a variety of
translators for it, all called "man2html".[0]

Some had little success, others a bit more, but all eventually dashed
themselves on the rocks of a man page that is more ambitious than they
had planned for.

In groff_man_style(7), I urge authors to limit themselves to only the
(non-deprecated) macros of the man(7) package and a small subset of
*roff escape sequences in an effort to keep the peace among those using
*roff formatters, mandoc(1), and man2html and other scrapers and ad-hoc
translators.  That effort in turn serves the goal of making man page
text accessible to as many readers as possible, because it's hard enough
getting programmers to write that documentation, in _any_ language, in
the first place.

We have other objectives for man(7) too, like being able to also render
a publication-quality PDF with a useful navigation pane and hyperlink
support, both internally and externally.

> In this case, it does sound like the man pages need a different thing
> for "example code" (.EX) and "preformatted text" (html's <PRE>).

A common error is to assume that `EX` implies `<PRE>`.  It doesn't.

groff_man_style(7):
            ... An example region is not a “literal mode” of any sort:
            special character escape sequences must still be used to
            produce correct glyphs for ', -, \, ^, `, and ~ (see
            subsection “Portability” below).  Sentence endings are still
            detected and supplemental inter‐sentence space applied.  If
            the amount of supplemental inter‐sentence spacing is
            altered, the rendering of, for instance, regular expressions
            using . or ? followed by multiple spaces can change.  Use
            the dummy character escape sequence \& before the spaces.

> Or we need some magic for known types of .SH like SYNOPSIS which are
> almost always rendered differently than other sections.

We _can_ render them differently.  _We have the technology._

   Synopsis macros
     Use SY and YS to summarize syntax using familiar Unix conventions.
     Heirloom Doctools troff (since Git snapshot 151218) and mandoc
     (since 1.14.5) support these GNU extensions; DWB, Plan 9, and
     Solaris troffs do not.

     .SY keyword [suffix]
            Begin synopsis.  Adjustment and automatic hyphenation are
            disabled.  If SY has already been called without a
            corresponding YS, a break is performed.  keyword and any
            suffix are set in bold.  When suffix is present, the package
            sets the next word after it without intervening space.  If a
            break is required in subsequent text (up to a paragraphing,
            sectioning, or YS macro call), lines after the first are
            indented.  Unless the previous synopsis’s indentation is
            reused (see YS below), output lines after the first indent
            by the width of the pending output line up to the end of
            keyword plus a space, if keyword is the only argument, and
            up to the end of suffix otherwise.

     .YS [reuse‐indentation]
            End synopsis, breaking the line and restoring indentation,
            adjustment, and hyphenation to their previous states.  If an
            argument is given, the indentation corresponding to the
            previous SY call is reused by the next SY call instead of
            being computed.

But, for those who don't want to employ these extensions, in groff
1.24.0 I undeprecated the `HP` macro (a decision made by Eric Raymond in
about 2008, I think).

     .HP [indentation]
            Set a paragraph with a hanging indentation.  Text on output
            lines after the first is indented by indentation, if
            specified, and by the amount of the IN register otherwise.

            Caution: A hanging indentation cannot be expressed naturally
            in (pure) HTML, a hanging paragraph is not distinguishable
            from an ordinary one if it formats on only one output line,
            and non‐roff‐based man page interpreters may treat HP as an
            ordinary paragraph anyway.  Thus, information or
            distinctions you mean to express with indentation may be
            lost.

At long last I've started working on the CSS stylesheet groff
produces,[1] and I expect to finagle up a provision for paragraphs with
hanging indents, since several macro packages, not just man(7), support
them.  It's simply not an urgent matter.  I'd like to get groff 1.25.0
out soon.

> > There is, potentially, a _third_ option, which I mentioned in my
> > earlier email.  As I said, literally no one expressed interest.
> >
> > https://lore.kernel.org/linux-man/xno6ge8p38.fsf@greed.delorie.com/T/#m9fda91ba28ca257c67d4595f81d38b32c5c9c937
> 
> glibc uses texinfo, which is TeX but terminals don't have **** off ;-)

Yes.  And info(1) sometimes produces...intriguing results.

1.6 Output Devices
==================

GNU 'troff''s output is in a device-independent page description
language.

...

   Delimiter syntax is flexible (and laborious to describe) primarily
for historical reasons; the foregoing restrictions need be kept in mind
mainly when using GNU 'troff' in AT&T compatibility mode.  Normally, GNU
'troff' keeps track of the nesting depth of escape sequence
interpolations, so the only characters you need to avoid using as
delimiters are those that appear in the arguments you input, not those
that result from interpolation.  Typically, ''' works fine.(4)  (*note
Delimiters-Footnote-4::)

Is the neutral apostrophe of syntactical import in the language you're
documenting with Texinfo?  Tough.

I guess there is a Law of Conservation of ****ing Off.

> I think of texinfo as a "TeX compiler".

That's an excellent way to think of it.  TeX and troff are both
Turing-complete languages.

> I don't write programs in assembly either (well, usually ;).

No indeed.  The real "assembly language" of troff is its
"device-independent output", which for short I call "trout" if it's
Kernighan's original spec from CSTR #97 in 1982, or "grout" if it
features groff's extensions.

Here's an example from a test script I have, in shell, for grotty(1).

input='#
x T ascii
x res 240 24 40
x init
p 1
x font 1 R
f 1
s 10
V 40
H 0
m d
D F d
t 1234567890123456
n 40 0
V 80
H 0
t abcdef
w
h 48
t ijklmnop
n 40 0
V 120
H 0
t abcdefg
w
h 24
t ijklmnop
n 40 0
x trailer
V 120
x stop
#'

> I've always advocated for "whatever system means the docs are stored
> and edited with the code, that I can turn into whatever I need."
> Roff, html, texinfo, markup, whatever.  I know how to write
> converters.

That's a good idea.  And Pandoc can help where knowledge is lacking.

I've soured completely on the notion of a uniform documentation format
for all domains.  We've seen world conquerors come and go across
multiple generations.  They either give up, or proclaim that the
limitations of their selected champion are not really limitations at
all, and that everyone else is stupid to complain.

Again, _that people write useful documentation at all_ is my primary
concern.  I decided that I could be of aid in keeping groff and man(7)
fit for purpose, when one's already decided those are the tools they're
going to use, or the project they work with has decided for them.

> DJGPP had a rule about "every .c must have a .txh" where the .txh was
> a texinfo snippet, and these had meta-info in them so the tools knew
> where to put them in the manual.  gEDA's pcb had a "comments in code
> become manual" system that used a short perl script to merge
> everything.  Etc.

Yup.  Done well, literate programming is wonderful!

> Yes, I know why the man pages are separate.  I've advocated for the
> glibc project to maintain its man pages along with the sources that
> affect them, but it's easier to just have glibc developers be man page
> contributors too.

At one time, Texinfo was one of those world conquerors.  Like groff, it
had a stretch where it went nearly completely moribund.  (Actually,
groff had more like two of those.)

> > It's the sort of thing I'd try out were I on a mission to eradicate
> > `in` request usage from the man-pages project's documents, but I
> > have no such mission.
> 
> Nor do I, but I wondered if there was a programmatic way to automate
> this so that the authors don't need to worry about it.  My general
> rule is "the third time you repeat something, automate it."

You have more patience than I do, then.  The _second_ time I find myself
doing something manually, I start writing a script, and spend much more
time refining it than I would have just doing the tedious thing again.
But I have more fun, and if I have to undertake the noxious task a third
time, I'm ready.  :)

> I still don't have a robot lawn mower, though ;-)

Chaotic environments mess up our automatons.  Trash blows into the yard
(or is discarded there by neighbors).  Wildlife learns to screw with the
machine.[2]  Or a contributor brings you a present.[3]

> >> Now I wonder if the problem case is predictable enough to have the
> >> preprocessor *know* when .EX needs the .in +4n, and when it
> >> doesn't...
> >
> > What preprocessor?
> 
> Whatever "sed" scripts we run in the Makefiles, that's all.  Currently
> they just fill in the .TH data.

Indentation revision, and wholesale request (or macro call) insertion,
seems like a job of slightly greater magnitude.

> > As I understand it, one of Alex's objectives, as was Michael's
> > before, is to keep the files in the man/man* directories directly
> > renderable with "man -l".
> 
> I agree with that!
> 
> I just think we could relax the "and must be formatted exactly as a
> release" a bit, in exchange for making it easier to contribute by
> removing one or two rules the contributors need to know.
> 
> But that assumes that it's (1) purely cosmetic, and (2) automatable.
> I note that "man" formats according to the window's width, so even the
> official tools don't honor the "and formatted exactly as" rule.

Yes, but people get _really wedded_ to the specifics of rendering even
after setting aside the huge issue of terminal width.  The podlators
maintainer, for example, has exacting expectations about the widths of
paragraph indentations, a parameter that has been tunable at rendering
time _since 1980_.

groff_man(7):

Options
...
     -rIN=standard‐indentation
              Set the default indentation amount used by IP, TP, and HP,
              and the inset amount used by RS.  The default is 7n on
              terminals and 7.2n on typesetters.  Use only integer
              multiples of unit “n” on terminals for consistent
              indentation.
...
   History
...
     UC appeared in 3BSD (1980).  Unix System III (1980) introduced P
     and exposed the registers IN and LL, which had been internal to
     Seventh Edition Unix man.  ...

> (wait, when did "man -l" happen?  Have I been missing that all along?
> Is my script really that old?)

In the man-db implementation of man(1), it seems to date back to _at
least_ 2002, as I see a Git commit for it (imported from CVS or
Subversion or something) mentioning it as an already existing feature.

commit 5ca206194b7bda56d1d4cbfb0a9ee401c5ea9a7b
Author: Colin Watson <cjwatson@debian.org>
Date:   Sun Sep 14 15:58:58 2003 +0000

    * src/encodings.c (get_source_encoding): Assume ISO-8859-1 source
    encoding if it's unknown (e.g. 'man -l').
    (get_default_device): source_encoding can no longer be NULL.
    * src/man.c (make_roff_command): Likewise.

If you are/were using Red Hat/RPM-based systems, you may have been using
Brouwer/Lucifredi man(1), which as far as I know never implemented this
`-l` option.  After that implementation lay moribund for many years,
Fedora threw in the NIH towel in, apparently, 2010.[4]

Regards,
Branden

[0] https://invisible-island.net/scripts/man2html.html#same-name
[1] https://lists.gnu.org/archive/html/groff-commit/2026-07/msg00096.html
    https://lists.gnu.org/archive/html/groff-commit/2026-07/msg00098.html
[2] https://www.reddit.com/r/Unexpected/comments/9hek1m/like_a_boss/
[3] https://gitlab.com/procps-ng/procps/blob/7ac9a0e1f5606696dc799b773d5ec70183ca91a3/ps/ps.1
[4] https://pagure.io/fork/evana/fedora-comps/c/fb4ab73d9eff9f06330bc8cb6fdaba9a0b418bcc?branch=0231a510e78ca62533cdd473914bba725050c85a

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

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

[DJ Delorie]

"G. Branden Robinson" <g.branden.robinson@gmail.com> writes:
>> > The man(7) package doesn't impose a rigid stylesheet on its output.
>> 
>> Perhaps, but the fact that I now know about the rule, and the
>> exception, means that it's not entirely flexible either ;-)
>
> The man(7) macro language is not highly flexible, no,

Sorry, I meant the man-pages style guide rules, not roff itself.

>> In this case, it does sound like the man pages need a different thing
>> for "example code" (.EX) and "preformatted text" (html's <PRE>).
>
> A common error is to assume that `EX` implies `<PRE>`.  It doesn't.

I just meant for semantic context, like "this is a code snippet" vs "I
want this to be formatted the way I typed it."  Might be helpful when
outputting HTML/CSS, like the examples would be in boxes and shaded with
the usual "copy to paste buffer" button, but <pre> would just be
monospaced and unformatted.  But thus is the slippery slope that led to
XML, and we don't want that again.

>> glibc uses texinfo, which is TeX but terminals don't have **** off ;-)
>
> Yes.  And info(1) sometimes produces...intriguing results.

My preference here is PDF, as we make sure all the cross refs and TOC
work correctly, and it formats very nicely (duh, TeX).  Info is useful
in emacs only because my fingers are already on the keyboard.

>> I don't write programs in assembly either (well, usually ;).
>
> No indeed.  The real "assembly language" of troff is its
> "device-independent output", which for short I call "trout" if it's
> Kernighan's original spec from CSTR #97 in 1982, or "grout" if it
> features groff's extensions.

I've been accused of abusing my own namespace here.  I would have called
my version "djrout".

> Yes, but people get _really wedded_ to the specifics of rendering even
> after setting aside the huge issue of terminal width.

I once worked for a guy who, at one point, wrote a typesetter that went
between satellites and the New York Times.  The typesetting had to be
perfect, every time, and run at line speed.  I learned a lot from him,
and he's the reason I have my own copy of the Chicago Manual of Style
and know what Reverse Boustrophedon is.

Also, Team Oxford Comma!

>> (wait, when did "man -l" happen?  Have I been missing that all along?
>> Is my script really that old?)
>
> In the man-db implementation of man(1), it seems to date back to _at
> least_ 2002, as I see a Git commit for it (imported from CVS or

I might predate even that.

> If you are/were using Red Hat/RPM-based systems, you may have been using
> Brouwer/Lucifredi man(1), which as far as I know never implemented this
> `-l` option.  After that implementation lay moribund for many years,

RHEL 9 has "man -l" via man.man-db at least, but that's today.

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

[Alejandro Colomar]

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

Hi DJ,

On 2026-07-15T14:19:49-0400, DJ Delorie wrote:
[...]
> > There is, potentially, a _third_ option, which I mentioned in my earlier
> > email.  As I said, literally no one expressed interest.
> >
> > https://lore.kernel.org/linux-man/xno6ge8p38.fsf@greed.delorie.com/T/#m9fda91ba28ca257c67d4595f81d38b32c5c9c937
> 
> glibc uses texinfo, which is TeX but terminals don't have **** off ;-)
> 
> I think of texinfo as a "TeX compiler".  I don't write programs in
> assembly either (well, usually ;).

I find it easier to write documentation in man(7) than in any other
languages.  It's simple enough that I don't need to remember much.
Also, not needing to compile the documentation makes it also easier to
deal with.  I don't write assembly, but sh(1) scripts are nice for
writing something quick.  :)

> I've always advocated for "whatever system means the docs are stored and
> edited with the code, that I can turn into whatever I need."

If you mean store them in a separate file (such as a .3 file next to the
.c file), I can agree.

If you mean source code comments (that is, in the same file),
I disagree.  I find code without comments to be more readable (assuming
the author of the code doesn't golf, or worse).

[...]
> I wrote the tunables docs a long time ago, but had to
> hold back the patch until I knew which release would have the code
> changes, so they would stay in sync.

You're welcome to send the patches well before they're merged in glibc.
We can review them with enough time.  You can just tell me the feature
is not merged in glibc, and thus I can't merge.

[...]
> > As I understand it, one of Alex's objectives, as was Michael's before,
> > is to keep the files in the man/man* directories directly renderable
> > with "man -l".
> 
> I agree with that!
> 
> I just think we could relax the "and must be formatted exactly as a
> release" a bit, in exchange for making it easier to contribute by
> removing one or two rules the contributors need to know.
> 
> But that assumes that it's (1) purely cosmetic, and (2) automatable.  I
> note that "man" formats according to the window's width, so even the
> official tools don't honor the "and formatted exactly as" rule.

For the tests in the build system, I use MANWIDTH=80,
precisely to maintain a consistent width that is the most common one.

	$ grepc -xmk MANWIDTH share/mk/
	share/mk/configure/build-depends/man/man.mk:MANWIDTH ?= 80

> (wait, when did "man -l" happen?  Have I been missing that all along?
> Is my script really that old?)

It seems to be there already in the first commit of the man-db.git
repository.

	190b315e1cae (2001-04-26; "Initial revision")

The ChangeLog has some older traces from it:

	Wed Nov 16 20:34:54 GMT 1994  Wilf.  (G.Wilford@ee.surrey.ac.uk)

		* Version: 2.2a7

		* src/man.c (format_and_display_file): Fix bug which caused 
		`man -l -' to fail. Produce sensible error message when -l file
		is inaccessable. Allow compressed manual pages to be specified when
		using -l (must have correct extension)

		* soelim/soelim.l (main): ensure (progname) is the basename of
		argv[0] .

		* src/manpath.c (main): remove local declaration of (quiet).
		add `--global' option.

So, it's at least as old as 1994.  :)


Have a lovely night!
Alex

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

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

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

[DJ Delorie]

Alejandro Colomar <alx@kernel.org> writes:
> I find it easier to write documentation in man(7) than in any other
> languages.  It's simple enough that I don't need to remember much.

I can say the same for HTML, because I'm used to it and I stick to
simple constructs.  It's good that there are people who find man(7)
easy, and it's good that those people have found a way to contribute
using their expertese.  I.e. Thank You :-)

>> I've always advocated for "whatever system means the docs are stored and
>> edited with the code, that I can turn into whatever I need."
>
> If you mean store them in a separate file (such as a .3 file next to the
> .c file), I can agree.

I don't mean that.

> If you mean source code comments (that is, in the same file),
> I disagree.

I don't mean that either.

I mean "anything that means one commit has code change and doc change".
I don't care about the mechanism.  Do it either way as long as you do
something.

> You're welcome to send the patches well before they're merged in glibc.

Er, I've been working on tunables for about 3-4 years now.  I doubt
you'd want to hold on to a patch set that long.

In this case, the timing was poor - it finished up just before a release
cycle, so whether the man pages needed to be done now or in six months
was not known until the last minute.  The time from glibc freeze to
glibc release is plenty long enough for a man page review cycle, though.

> For the tests in the build system, I use MANWIDTH=80,
> precisely to maintain a consistent width that is the most common one.

I don't think I've had a default with of 80 for a couple decades now.  I
wish we'd standardized on the 132-column terminals instead.

> So, it's at least as old as 1994.  :)

Um, my career predates that too.  I don't think I was doing man pages
back then, though.