SD_ELF_NOTE_DLOPEN(3)

SD_ELF_NOTE_DLOPEN

.SH "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

.SH "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"

.SH "DESCRIPTION"

.PP 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.

.PP The macro takes the following parameters:

.PP feature

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

Added in version 261.

.RE

.PP description

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

Added in version 261.

.RE

.PP 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.

.RE

.PP 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.

.RE

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

systemd-analyze dlopen-metadata binary

.SH "EXAMPLES"

.PP 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");

.PP 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");

.SH "NOTES"

.PP 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.

.SH "HISTORY"

.PP 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.

.SH "SEE ALSO"

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

NOTES

1.: ELF dlopen metadata

https://uapi-group.org/specifications/specs/elf_dlopen_metadata/

systemd 262.2