[PATCH] manual: Document indirect functions (IFUNC)

[Yury Khrustalev]

On Wed, Jun 10, 2026 at 03:24:06PM -0300, Adhemerval Zanella wrote:
> Add a new section to the Dynamic Linker chapter describing the
> STT_GNU_IFUNC mechanism: the resolver calling convention for each
> supported architecture, when resolvers run, and the functionality
> supported in resolvers (TLS access, stack protector, cross-object
> references) along with the remaining restrictions, reflecting the
> recent ordering fixes (BZ 20680, BZ 23240, BZ 28817, BZ 34164,
> BZ 34170).  Also cross-reference it from the hardening section.

Thanks, this is very helpful addition to the Glibc manual! Some
comments below.

> ---
>  manual/dynlink.texi | 287 +++++++++++++++++++++++++++++++++++++++++++-
>  1 file changed, 284 insertions(+), 3 deletions(-)
> 
> diff --git a/manual/dynlink.texi b/manual/dynlink.texi
> index 5c1579ff098..66c313657b5 100644
>
> ...
> 
> +Indirect functions are usually defined using the @code{ifunc} function
> +attribute provided by GCC and compatible compilers:
> +
> +@smallexample
> +static int
> +my_func_generic (int a)
> +@{
> +  /* @r{@dots{}} */
> +@}
> +
> +static int
> +my_func_vectorized (int a)
> +@{
> +  /* @r{@dots{}} */
> +@}
> +
> +/* @r{The resolver returns the address of the selected
> +   implementation.}  */
> +static int (*my_func_resolver (void)) (int)

Perhaps, static int (*my_func_resolver (int)) (void)?

>
> ...
>
> +The architecture-specific conventions are:
> +
> +@table @asis
> +@item AArch64
> +@smallexample
> +#include <sys/ifunc.h>
> +
> +void *resolver (uint64_t hwcap, const __ifunc_arg_t *arg);

On AArch64 the preferred way is (see [1]):

  void *resolver (uint64_t, const uint64_t *)

While using __ifunc_arg_t is acceptable, it is somewhat confusing
in light of recent extension of this argument to hwcap3,4.

[1]: https://github.com/ARM-software/abi-aa/blob/main/sysvabi64/sysvabi64.rst#gnu-c-library-ifunc-interface

Perhaps, just reference [1] in this section for the details to avoid
repetition that might diverge in the future?

That said, the section in [1] that tries to describe Glibc handling of
ifunc resolvers should probably be updated or removed (with a reference
to the updated Glibc manual), so that AArch64-specific things are
described in [1] while Glibc-specific things are described here.

>
> ...
>
> +@subsection When IFUNC Resolvers Run
> +
> +Resolver functions run early, before the process or the newly loaded
> +objects are fully initialized.  The exact point at which a resolver
> +runs depends on how the indirect function is referenced and how the
> +program is linked:
> +
> +@itemize @bullet
> +@item
> +In dynamically linked programs, resolvers for non-lazy references run
> +during relocation processing at program startup, before ELF
> +constructors and before @code{main}.

Should we also say, perhaps in another section aimed at Glibc contributors,
when resolvers run with respect to the process start-up stages (e.g. after
tunables processing etc)?

> Non-lazy references include data
> +relocations against the function address (for example, initialized
> +function pointer variables), and all references if lazy binding is
> +disabled (for example, with the @option{-z now}

s/link-time option/static link-time option/
(I know it's almost obvious, but I think it would be more precise.)

>
> ...
>
> +@subsection Supported Functionality in IFUNC Resolvers
> +
> +Because resolvers run during relocation processing, only a restricted
> +execution environment is available to them.  @Theglibc{} guarantees
> +the following:
> +
> +@itemize @bullet
> +@item
> +The thread control block (TCB) of the initial thread is set up before
> +any resolver runs.

Does this apply to Glibc's own resolvers? I think it's worth to
point this out.

>
> ...
>
> +The guarantees described in this section are provided by @theglibc{}
> +version 2.44 and later.

I think we should mention this above before we list guarantees.
Perhaps add a "since X version" in each guarantee in case we add more
in the future versions.

> ...

Thanks,
Yury