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

[DJ Delorie <dj@redhat.com>]

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