SD_ELF_NOTE_DLOPEN(3)

NAME
SD_ELF_NOTE_DLOPEN, SD_ELF_NOTE_DLOPEN_VENDOR, SD_ELF_NOTE_DLOPEN_TYPE, SD_ELF_NOTE_DLOPEN_PRIORITY_REQUIRED, SD_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED, SD_ELF_NOTE_DLOPEN_PRIORITY_SUGGESTED - Embed ELF .note.dlopen metadata for shared library dependencies

SYNOPSIS

#include <systemd/sd-dlopen.h>

SD_ELF_NOTE_DLOPEN(feature, description, priority, soname...)

#define SD_ELF_NOTE_DLOPEN_VENDOR "FDO"

#define SD_ELF_NOTE_DLOPEN_TYPE UINT32_C(0x407c0c0a)

#define SD_ELF_NOTE_DLOPEN_PRIORITY_REQUIRED    "required"

#define SD_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED "recommended"

#define SD_ELF_NOTE_DLOPEN_PRIORITY_SUGGESTED   "suggested"

DESCRIPTION

SD_ELF_NOTE_DLOPEN() is a macro that embeds a .note.dlopen ELF note section in the compiled binary, declaring a weak dependency on a shared library loaded via dlopen(). This implements the ELF dlopen metadata[1] specification, allowing package managers and build systems to discover runtime dependencies that are not visible through regular ELF DT_NEEDED entries.

The macro takes the following parameters:

feature
    A short string identifying the feature this library provides (e.g. "XKB", "PCRE2").

    Added in version 261.

description
    A human-readable description of what the library is used for.

    Added in version 261.

priority
    One of SD_ELF_NOTE_DLOPEN_PRIORITY_REQUIRED, SD_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED, or SD_ELF_NOTE_DLOPEN_PRIORITY_SUGGESTED, indicating how important the dependency is.

    Added in version 261.

soname...
    One or more shared object names (sonames) for the library, e.g. "libfoo.so.1". Multiple sonames may be specified as separate arguments (up to 5) for libraries that have changed soname across versions.

    Added in version 261.

The embedded metadata can be read from a compiled ELF binary using:

    systemd-analyze dlopen-metadata binary

EXAMPLES

Example 1. Single soname

    #include <systemd/sd-dlopen.h>
    SD_ELF_NOTE_DLOPEN("XKB", "Keyboard layout support",
                        SD_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED,
                        "libxkbcommon.so.0");

Example 2. Multiple sonames for different library versions

    SD_ELF_NOTE_DLOPEN("crypt", "Support for hashing passwords",
                        SD_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED,
                        "libcrypt.so.2", "libcrypt.so.1", "libcrypt.so.1.1");

NOTES

The macros described here are header-only and do not require runtime linkage against libsystemd(3). Only the installed header and include path (as provided by pkg-config --cflags libsystemd) are needed.

HISTORY

SD_ELF_NOTE_DLOPEN(), SD_ELF_NOTE_DLOPEN_VENDOR, SD_ELF_NOTE_DLOPEN_TYPE, SD_ELF_NOTE_DLOPEN_PRIORITY_REQUIRED, SD_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED, and SD_ELF_NOTE_DLOPEN_PRIORITY_SUGGESTED were added in version 261.

SEE ALSO

systemd(1), sd-dlopen(3), dlopen(3)

NOTES

1.  ELF dlopen metadata
    https://uapi-group.org/specifications/specs/elf_dlopen_metadata/