[PATCH v4 1/1] rtld: add glibc.rtld.optional_static_tls_alignment

Adhemerval Zanella Netto adhemerval.zanella@linaro.org
Tue Nov 3 17:00:39 GMT 2026



On 29/10/26 13:43, DJ Delorie wrote:
> Add an alignment tunable to go along with glibc.rtld.optional_static_tls
> to optimize loading audit modules with higher-than-default alignment

I think it is not really optimizing, but rather allowing a program that
requires larger init-exec alignment requirement to run in the presence
of audit modules.

For instance, a program whose DT_NEEDED library has a 4 KiB aligned
initial-exec TLS block runs fine on its own, but fails at startup with
an auditor that only defines la_version:

  tst-tlsalign-tunable-dep: TLS allocation error:
  tst-tlsalign-tunable-depmod.so: cannot allocate memory in static TLS
  block: var: requested 00000000000006c0, available 0000000000001000

The same check applies to a dlopen of an initial-exec module, with or
without auditing:

cat > lib.c <<'EOF'
__thread int var[4] __attribute__ ((tls_model ("initial-exec"), aligned (4096)));
int *get_var (void) { return var; }
EOF
cat > main.c <<'EOF'
int *get_var (void);
int main (void) { return get_var () == 0; }
EOF
cat > dl.c <<'EOF'
#include <dlfcn.h>
#include <stdio.h>
int main (void) { if (dlopen ("./libtlsa.so", RTLD_NOW) == NULL) puts (dlerror ()); }
EOF
echo 'unsigned int la_version (unsigned int v) { return v; }' > audit.c
gcc -shared -fPIC -o libtlsa.so lib.c
gcc -shared -fPIC -o audit.so audit.c
gcc -o main main.c -L. -ltlsa -Wl,-rpath,'$ORIGIN'
gcc -o dl dl.c

$ ./main; echo $?
0
$ LD_AUDIT=./audit.so ./main
./main: TLS allocation error: libtlsa.so: cannot allocate memory in
static TLS block: var: requested 0000000000000740, available
0000000000001080
$ ./dl
./libtlsa.so: cannot allocate memory in static TLS block: var:
requested 0000000000000680, available 0000000000000fc0

With this patch and optional_static_tls_alignment=4096, both work.
I think it is worth to describe this on commit message and on the
manual.

> requirements.  Unlike the extra size, this is only used when creating
> the TLS area so need not be stored in GLRO().

A new tunable should have a NEW entry as well, something like:

* A new tunable, glibc.rtld.optional_static_tls_alignment, sets a minimum
  alignment for the static TLS block of each thread.  It allows objects
  that need static TLS with a large alignment to be loaded after program
  startup, such as audit modules, objects loaded at startup when auditing
  is enabled, and objects using the initial-exec TLS model that are loaded
  with dlopen.

> ---
> changes in v4:
>   - rebased
> changes in v3:
>   - renamed test
>   - random style cleanups
>   - comment optional_static_tls_alignment variable
>   - ignore invalid alignments
>   - make tdata1 volatile
>   - tweak documentation
>   - fix list-tunables test
> changes in v2:
>   - add the other tls case type for adding extra alignment
> 
>  elf/Makefile                        |  7 ++++
>  elf/dl-tls.c                        | 15 +++++++++
>  elf/dl-tunables.list                |  5 +++
>  elf/tst-rtld-list-tunables.exp      |  1 +
>  elf/tst-tlsalign-tunable-auditmod.c | 52 +++++++++++++++++++++++++++++
>  elf/tst-tlsalign-tunable.c          | 39 ++++++++++++++++++++++
>  manual/tunables.texi                |  7 ++++
>  7 files changed, 126 insertions(+)
>  create mode 100644 elf/tst-tlsalign-tunable-auditmod.c
>  create mode 100644 elf/tst-tlsalign-tunable.c
> 
> diff --git a/elf/Makefile b/elf/Makefile
> index 2c74e11946..280f64b2dc 100644
> --- a/elf/Makefile
> +++ b/elf/Makefile
> @@ -312,6 +312,7 @@ tests-container := \
>    tst-dl-cache-old-format \
>    tst-ldconfig-bad-aux-cache \
>    tst-ldconfig-ld_so_conf-update \
> +  tst-tlsalign-tunable \

I think this does not need to be a test-container.

>    # tests-container
>  
>  ifeq (no,$(build-hardcoded-path-in-tests))
> @@ -1097,6 +1098,7 @@ modules-names += \
>    tst-tls22-mod2-gnu2 \
>    tst-tls23-mod \
>    tst-tlsalign-lib \
> +  tst-tlsalign-tunable-auditmod \
>    tst-tlsgap-mod0 \
>    tst-tlsgap-mod1 \
>    tst-tlsgap-mod2 \
> @@ -1852,6 +1854,11 @@ $(objpfx)tst-nodelete-opened.out: $(objpfx)tst-nodelete-opened-lib.so
>  $(objpfx)tst-tlsalign-extern: $(objpfx)tst-tlsalign-vars.o
>  $(objpfx)tst-tlsalign-extern-static: $(objpfx)tst-tlsalign-vars.o
>  
> +tst-tlsalign-tunable-TUNABLES = glibc.rtld.optional_static_tls_alignment=0x1000
> +tst-tlsalign-tunable-TUNABLES += glibc.rtld.optional_static_tls=0x3000
> +tst-tlsalign-tunable-ENV = LD_AUDIT=$(objpfx)tst-tlsalign-tunable-auditmod.so
> +$(objpfx)tst-tlsalign-tunable.out: $(objpfx)tst-tlsalign-tunable-auditmod.so
> +
>  # The resolver translation unit must always be compiled with
>  # -fstack-protector-all so the canary code is emitted regardless of the
>  # default.
> diff --git a/elf/dl-tls.c b/elf/dl-tls.c
> index f2a99e8edb..31b26fe8d3 100644
> --- a/elf/dl-tls.c
> +++ b/elf/dl-tls.c
> @@ -126,6 +126,11 @@ tls_static_surplus (int nns, int opt_tls)
>     backwards compatibility.  */
>  #define LEGACY_TLS (1664 - tls_static_surplus (DEFAULT_NNS, OPTIONAL_TLS))
>  
> +/* This value is set from the glibc.rtld.optional_static_tls_alignment
> +   tunable, and sets an additional minimum alignment on the TLS
> +   data.  */
> +static size_t optional_static_tls_alignment = 0;
> +

[...]

>  /* Calculate the size of the static TLS surplus, when the given
>     number of audit modules are loaded.  Must be called after the
>     number of audit modules is known and before static TLS allocation.  */
> @@ -136,6 +141,10 @@ _dl_tls_static_surplus_init (size_t naudit)
>  
>    nns = TUNABLE_GET (nns, size_t, NULL);
>    opt_tls = TUNABLE_GET (optional_static_tls, size_t, NULL);
> +  optional_static_tls_alignment = TUNABLE_GET (optional_static_tls_alignment, size_t, NULL);
> +  /* Ignore invalid requests.  */
> +  if (! powerof2 (optional_static_tls_alignment))
> +    optional_static_tls_alignment = 0;
>    if (nns > DL_NNS)
>      nns = DL_NNS;
>    if (DL_NNS - nns < naudit)
> @@ -346,6 +355,9 @@ _dl_determine_tlsoffset (void)
>    size_t extra_tls_size = _dl_extra_tls_get_size ();
>    size_t extra_tls_align = _dl_extra_tls_get_align ();
>  
> +  /* Apply any user-specified alignment, if larger.  */
> +  extra_tls_align = MAX (extra_tls_align, optional_static_tls_alignment);
> +

Only max_align needs to change, and the extra_tls_align also places the extra
TLS block (rseq on Linux), so this moves rseq to the next alignment boundary
and leaves a gap before it that is never used.

And it also does not follow the comment above, which says the block size is a
multiple of extra_tls_align. 

So I think it should be just:

  size_t max_align = TUNABLE_GET (optional_static_tls_alignment, size_t, NULL);
  if (!powerof2 (max_align) || max_align < TCB_ALIGNMENT)
    max_align = TCB_ALIGNMENT;

>    /* Increase the maximum alignment with the extra TLS alignment requirements
>       if necessary.  */
>    max_align = MAX (max_align, extra_tls_align);
> @@ -426,6 +438,9 @@ _dl_determine_tlsoffset (void)
>    size_t extra_tls_size = _dl_extra_tls_get_size ();
>    size_t extra_tls_align = _dl_extra_tls_get_align ();
>  
> +  /* Apply any user-specified alignment, if larger.  */
> +  extra_tls_align = MAX (extra_tls_align, optional_static_tls_alignment);
> +
>    /* Increase the maximum alignment with the extra TLS alignment requirements
>       if necessary.  */
>    max_align = MAX (max_align, extra_tls_align);
> diff --git a/elf/dl-tunables.list b/elf/dl-tunables.list
> index 111649f145..4c78444542 100644
> --- a/elf/dl-tunables.list
> +++ b/elf/dl-tunables.list
> @@ -101,6 +101,11 @@ glibc {
>        minval: 0
>        default: 512
>      }
> +    optional_static_tls_alignment {
> +      type: SIZE_T
> +      minval: 0
> +      default: 0
> +    }

Should we add a maximum upper bound? There is no upper bound, and the TLS size
computations can wrap for very large sizes.

glibc.rtld.optional_static_tls has another issues, where 'tls_static_surplus'
takes the value as an int.  For example, optional_static_tls=0xfffffa80 is
-1408 as an int, which makes the surplus negative.  

>      enable_secure {
>        type: INT_32
>        minval: 0
> diff --git a/elf/tst-rtld-list-tunables.exp b/elf/tst-rtld-list-tunables.exp
> index 9590021f3a..17520d6b31 100644
> --- a/elf/tst-rtld-list-tunables.exp
> +++ b/elf/tst-rtld-list-tunables.exp
> @@ -15,3 +15,4 @@ glibc.rtld.enable_secure: 0 (min: 0, max: 1)
>  glibc.rtld.execstack: 1 (min: 0, max: 2)
>  glibc.rtld.nns: 0x4 (min: 0x1, max: 0x10)
>  glibc.rtld.optional_static_tls: 0x200 (min: 0x0, max: 0x[f]+)
> +glibc.rtld.optional_static_tls_alignment: 0x0 (min: 0x0, max: 0x[f]+)
> diff --git a/elf/tst-tlsalign-tunable-auditmod.c b/elf/tst-tlsalign-tunable-auditmod.c
> new file mode 100644
> index 0000000000..e6f6c23652
> --- /dev/null
> +++ b/elf/tst-tlsalign-tunable-auditmod.c
> @@ -0,0 +1,52 @@
> +/* Test for large alignment in TLS blocks, BZ#1838, audit module.
> +   Copyright (C) 2020-2026 Free Software Foundation, Inc.

s/2020-2026/2026

> +   This file is part of the GNU C Library.
> +
> +   The GNU C Library is free software; you can redistribute it and/or
> +   modify it under the terms of the GNU Lesser General Public
> +   License as published by the Free Software Foundation; either
> +   version 2.1 of the License, or (at your option) any later version.
> +
> +   The GNU C Library is distributed in the hope that it will be useful,
> +   but WITHOUT ANY WARRANTY; without even the implied warranty of
> +   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
> +   Lesser General Public License for more details.
> +
> +   You should have received a copy of the GNU Lesser General Public
> +   License along with the GNU C Library; if not, see
> +   <https://www.gnu.org/licenses/>.  */
> +
> +#include <unistd.h>
> +
> +__thread int x;
> +__thread int b[4]
> +  __attribute__ ((tls_model("initial-exec")))
> +  __attribute__ ((aligned(0x1000)));
> +
> +/* These exist just to make the above variables "used".  */
> +int *
> +func_x (void)
> +{
> +  return &x;
> +}
> +
> +int *
> +func_b (void)
> +{
> +  return b;
> +}
> +
> +void __attribute__ ((constructor))
> +la_ctor (void)
> +{
> +  write (1, "AUDITctor\n", 10);
> +  /* We only care if the auditor got loaded.  It doesn't need to
> +     run.  */
> +  _exit (0);
> +}

This only checks that the module was loaded, I think it would be worth
to check that b is aligned before exiting.

The test also never creates a thread, and since the process exits from
the auditor's constructor, the program never runs with the larger
alignment.  A second test for the dependency case above should covers
both: a trivial auditor, a DT_NEEDED library with 4 KiB aligned initial-exec
TLS, and a main that checks the alignment in the main thread and in a
new thread.

> +
> +unsigned int
> +la_version (unsigned int version)
> +{
> +  return version;
> +}
> diff --git a/elf/tst-tlsalign-tunable.c b/elf/tst-tlsalign-tunable.c
> new file mode 100644
> index 0000000000..eb98e6e912
> --- /dev/null
> +++ b/elf/tst-tlsalign-tunable.c
> @@ -0,0 +1,39 @@
> +/* Test for large alignment in TLS blocks, BZ#18383.
> +   Copyright (C) 2015-2026 Free Software Foundation, Inc.
> +   This file is part of the GNU C Library.
> +
> +   The GNU C Library is free software; you can redistribute it and/or
> +   modify it under the terms of the GNU Lesser General Public
> +   License as published by the Free Software Foundation; either
> +   version 2.1 of the License, or (at your option) any later version.
> +
> +   The GNU C Library is distributed in the hope that it will be useful,
> +   but WITHOUT ANY WARRANTY; without even the implied warranty of
> +   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
> +   Lesser General Public License for more details.
> +
> +   You should have received a copy of the GNU Lesser General Public
> +   License along with the GNU C Library; if not, see
> +   <https://www.gnu.org/licenses/>.  */
> +
> +/* This specifically tests that the
> +   glibc.rtld.optional_static_tls_alignment tunable works, by loading
> +   an audit module that can't load without alignment help.  */
> +
> +#include <stdint.h>
> +#include <stdio.h>
> +#include <stdlib.h>
> +
> +static volatile __thread int tdata1 = 1;

This is not strictly required, because init_tls lays out the static TLS block
whether or not the executable has TLS.

> +
> +static int
> +do_test (void)
> +{
> +  printf("tst-tlsalign-tunable!\n");
> +  /* If the test passes, the auditor itself will call exit with a
> +     value of 0.  If we get here, we've failed.  "Use" tdata1 here
> +     too.  */
> +  return tdata1 ? EXIT_FAILURE : 43;
> +}
> +
> +#include <support/test-driver.c>
> diff --git a/manual/tunables.texi b/manual/tunables.texi
> index bbff2f5fdd..2cb516b1dc 100644
> --- a/manual/tunables.texi
> +++ b/manual/tunables.texi
> @@ -422,6 +422,13 @@ changed once allocated at process startup.  The default allocation of
>  optional static TLS is 512 bytes and is allocated in every thread.
>  @end deftp
>  
> +@deftp Tunable glibc.rtld.optional_static_tls_alignment
> +Sets a minimum alignment for the static TLS.  The loader normally uses
> +the alignment requirements of shared objects, but this might be needed
> +for (for example) audit modules that have a higher-than-default
> +alignment requirement.
> +@end deftp
> +

I think it would be worth to add:

- the value is in bytes and must be a power of two (other values are
  silently ignored);
- which kind of objects need it (like the initial example I gave it);
- glibc.rtld.optional_static_tls might also need to grow to hold the
  padding;
- it increases the memory used by every thread.

>  @deftp Tunable glibc.rtld.dynamic_sort
>  Sets the algorithm to use for DSO sorting, valid values are @samp{1} and
>  @samp{2}.  For value of @samp{1}, an older O(n^3) algorithm is used, which is



More information about the Libc-alpha mailing list