[PATCH v3 1/4] man/man5/ld.so.conf.5: document include syntax

[PATCH v3 1/4] man/man5/ld.so.conf.5: document include syntax

[DJ Delorie]

---
 man/man5/ld.so.conf.5 | 24 ++++++++++++++++++++++++
 man/man8/ldconfig.8   |  2 --
 2 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/man/man5/ld.so.conf.5 b/man/man5/ld.so.conf.5
index 481cf9152..d9fae3c1f 100644
--- a/man/man5/ld.so.conf.5
+++ b/man/man5/ld.so.conf.5
@@ -9,8 +9,32 @@ .SH DESCRIPTION
 This file contains a list of directories,
 one per line,
 in which to search for libraries.
+.P
+The file is parsed by
+.BR \%ldconfig (8)
+and the results stored in
+.IR /etc/ld.so.cache .
+.P
+The syntax allows lines to start with the keyword
+.B include
+followed by a
+.BR glob (7)
+pattern.
+Files matching that pattern will be processed
+as if their contents were included at that point.
 .SH FILES
 .I /etc/ld.so.conf
+.SH EXAMPLES
+Example config file:
+.P
+.in +4n
+.EX
+/lib
+/usr/lib
+/usr/local/lib
+include /etc/ld.so.conf.d/*.conf
+.EE
+.in
 .SH SEE ALSO
 .BR ld.so (8),
 .BR ldconfig (8)
diff --git a/man/man8/ldconfig.8 b/man/man8/ldconfig.8
index 9ac146b44..cb7d62ccc 100644
--- a/man/man8/ldconfig.8
+++ b/man/man8/ldconfig.8
@@ -178,8 +178,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
-- 
2.47.3

[PATCH v3 0/4] Tunables-related updates

[DJ Delorie]

DJ Delorie (4):
  man/man5/ld.so.conf.5: document include syntax
  man/man5/tunables.conf: Document system-wide tunables config
  man/man8/ld.so.8: Note that ld.so.cache includes tunables
  man/man8/ldconfig.8: Add tunables options

 man/man5/ld.so.conf.5    |  24 +++++++
 man/man5/tunables.conf.5 | 134 +++++++++++++++++++++++++++++++++++++++
 man/man8/ld.so.8         |   3 +-
 man/man8/ldconfig.8      |  25 +++++++-
 4 files changed, 182 insertions(+), 4 deletions(-)
 create mode 100644 man/man5/tunables.conf.5

-- 
2.47.3

[PATCH v3 4/4] man/man8/ldconfig.8: Add tunables options

[DJ Delorie]

---
 man/man8/ldconfig.8 | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/man/man8/ldconfig.8 b/man/man8/ldconfig.8
index cb7d62ccc..e575fdec6 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
@@ -188,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 tunables listed in
+.IR /etc/tunables.conf .
 .PD
 .SH SEE ALSO
 .BR ldd (1),
-- 
2.47.3

[PATCH v3 3/4] man/man8/ld.so.8: Note that ld.so.cache includes tunables

[DJ Delorie]

---
 man/man8/ld.so.8 | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/man/man8/ld.so.8 b/man/man8/ld.so.8
index d1d60cefd..36c8db275 100644
--- a/man/man8/ld.so.8
+++ b/man/man8/ld.so.8
@@ -793,7 +793,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 tunables to be applied.
 See
 .BR ldconfig (8).
 .TP
-- 
2.47.3

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

[DJ Delorie]

---
 man/man5/tunables.conf.5 | 134 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 134 insertions(+)
 create mode 100644 man/man5/tunables.conf.5

diff --git a/man/man5/tunables.conf.5 b/man/man5/tunables.conf.5
new file mode 100644
index 000000000..f96355bed
--- /dev/null
+++ b/man/man5/tunables.conf.5
@@ -0,0 +1,134 @@
+.TH tunables.conf 5 (date) "Linux man-pages (unreleased)"
+.SH NAME
+tunables.conf \- tunables configuration file
+.SH SYNOPSIS
+.nf
+.B /etc/tunables.conf
+.fi
+.SH DESCRIPTION
+Tunables are a feature in the GNU C Library
+that allows application authors and distribution maintainers
+to alter the runtime library behavior to match their workload.
+For a list of supported tunables,
+please consult the glibc manual
+that corresponds to your installed version of glibc,
+or run the following command:
+.P
+.in +4n
+.EX
+.B ld.so --list-tunables
+.EE
+.P
+Each line in the file
+.I /etc/tunables.conf
+specifies a tunable,
+which is specified with a string of the form
+.IB name = value \f[R].\f[]
+.P
+The syntax allows lines to start with the keyword
+.I include
+followed by a path wildcard.
+The wildcard is a path specification in the
+.BR \%glob (7)
+format.
+Matching files will be processed
+as if their contents were included
+at that point in the 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 is created by
+.IR ld.so .
+.P
+Each line may include zero or more keywords or symbols at the beginning,
+which affect how each tunable affects each processes.
+The keywords must be separated by whitespace,
+but the symbols need not be.
+.TP
+.B overridable
+.TQ
+.B +
+Allow the tunable to be overridden by the
+.B GLIBC_TUNABLES
+environment variable when the process runs
+(this is the default).
+.TP
+.B nonoverridable
+.TQ
+.B \-
+Do not allow the tunable to be overridden by the environment variable.
+.TP
+.B onlysecure
+.TQ
+.B @
+The tunable applies only to
+.B AT_SECURE
+processes,
+such as one started from a set-user-ID program,
+or one with elevated capabilities.
+.TP
+.B nonsecure
+.TQ
+.B $
+The tunable applies only to
+.RB non- AT_SECURE
+processes (this is the default).
+.TP
+.B anysecure
+.TQ
+.B *
+The tunable applies to both
+.B AT_SECURE
+and
+.RB non- AT_SECURE
+processes.
+.P
+The file may also contain
+.IR filters ,
+which limit the tunables following it,
+up to the end of the file
+(or end of the included file,
+or start of a new included file)
+or a line with only
+.B []
+on it.
+The syntax is:
+.P
+.in +4n
+.EX
+.RI [ filter : pattern ]
+.EE
+.in
+.TP
+.B proc
+The
+.B proc
+filter limits the following tunables to processes
+whose name matches the pattern.
+The pattern may be an absolute path
+or just the base name.
+.SH FILES
+.TP
+.I /etc/tunables.conf
+.TP
+.I /etc/ld.so.cache
+cached copy of tunables
+.SH EXAMPLES
+Example configuration file:
+.P
+.in +4n
+.EX
+glibc.malloc.arenas_max=5
+onlysecure glibc.malloc.arenas_max=1
+\-glibc.pthread.rseq=1
+[proc:/bin/bad.program]
+\-glibc.pthread.rseq=0
+[proc:some.program]
+\-glibc.malloc.mmap_threshold=65536
+.EE
+.in
+.SH SEE ALSO
+.BR ld.so (8),
+.BR ldconfig (8)
-- 
2.47.3

Re: [PATCH v3 1/4] man/man5/ld.so.conf.5: document include syntax

[Alejandro Colomar]

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

Hi DJ,

> Date: 2026-07-31 14:22:24-0400
> From: DJ Delorie <dj@redhat.com>
>
> ---

Thanks!  I've applied the patch.


Have a lovely night!
Alex

>  man/man5/ld.so.conf.5 | 24 ++++++++++++++++++++++++
>  man/man8/ldconfig.8   |  2 --
>  2 files changed, 24 insertions(+), 2 deletions(-)
> 
> diff --git a/man/man5/ld.so.conf.5 b/man/man5/ld.so.conf.5
> index 481cf9152..d9fae3c1f 100644
> --- a/man/man5/ld.so.conf.5
> +++ b/man/man5/ld.so.conf.5
> @@ -9,8 +9,32 @@ .SH DESCRIPTION
>  This file contains a list of directories,
>  one per line,
>  in which to search for libraries.
> +.P
> +The file is parsed by
> +.BR \%ldconfig (8)
> +and the results stored in
> +.IR /etc/ld.so.cache .
> +.P
> +The syntax allows lines to start with the keyword
> +.B include
> +followed by a
> +.BR glob (7)
> +pattern.
> +Files matching that pattern will be processed
> +as if their contents were included at that point.
>  .SH FILES
>  .I /etc/ld.so.conf
> +.SH EXAMPLES
> +Example config file:
> +.P
> +.in +4n
> +.EX
> +/lib
> +/usr/lib
> +/usr/local/lib
> +include /etc/ld.so.conf.d/*.conf
> +.EE
> +.in
>  .SH SEE ALSO
>  .BR ld.so (8),
>  .BR ldconfig (8)
> diff --git a/man/man8/ldconfig.8 b/man/man8/ldconfig.8
> index 9ac146b44..cb7d62ccc 100644
> --- a/man/man8/ldconfig.8
> +++ b/man/man8/ldconfig.8
> @@ -178,8 +178,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
> -- 
> 2.47.3
> 
> 

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

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

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

[Alejandro Colomar]

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

Hi DJ,

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

'-' should be escaped: '\-'

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

	ld.so \-\-list\-tunables

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

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

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

It's also much simpler.

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

Same here, for consistency with patch 1/4:

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

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

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

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

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

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


Cheers,
Alex

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

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

Re: [PATCH v3 3/4] man/man8/ld.so.8: Note that ld.so.cache includes tunables

[Alejandro Colomar]

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

Hi DJ,

> Date: 2026-07-31 14:22:24-0400
> From: DJ Delorie <dj@redhat.com>
>
> ---

Patch applied; thanks!  BTW, please sign your patches (Signed-off-by);
I just noticed now.


Cheers,
Alex

>  man/man8/ld.so.8 | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/man/man8/ld.so.8 b/man/man8/ld.so.8
> index d1d60cefd..36c8db275 100644
> --- a/man/man8/ld.so.8
> +++ b/man/man8/ld.so.8
> @@ -793,7 +793,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 tunables to be applied.
>  See
>  .BR ldconfig (8).
>  .TP
> -- 
> 2.47.3
> 

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

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

Re: [PATCH v3 4/4] man/man8/ldconfig.8: Add tunables options

[Alejandro Colomar]

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

Hi DJ,

> Date: 2026-07-31 14:22:24-0400
> From: DJ Delorie <dj@redhat.com>
>
> ---

Thanks!  I've applied the patch, with a minor amendment:

	diff --git i/man/man8/ldconfig.8 w/man/man8/ldconfig.8
	index e575fdec65a2..c2347049b800 100644
	--- i/man/man8/ldconfig.8
	+++ w/man/man8/ldconfig.8
	@@ -92,8 +92,9 @@ .SH DESCRIPTION
	 .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.
	+These tunables
	+are stored in the cache
	+and applied to every process at its startup.
	 .SH OPTIONS
	 .TP
	 .BI \-\-format= fmt


Cheers,
Alex

>  man/man8/ldconfig.8 | 23 ++++++++++++++++++++++-
>  1 file changed, 22 insertions(+), 1 deletion(-)
> 
> diff --git a/man/man8/ldconfig.8 b/man/man8/ldconfig.8
> index cb7d62ccc..e575fdec6 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
> @@ -188,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 tunables listed in
> +.IR /etc/tunables.conf .
>  .PD
>  .SH SEE ALSO
>  .BR ldd (1),
> -- 
> 2.47.3
> 

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

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