mirror of
https://github.com/systemd/systemd.git
synced 2026-06-24 08:47:49 +00:00
man: add sd-dlopen(3) and SD_ELF_NOTE_DLOPEN(3) man pages
Document the new public sd-dlopen.h header and SD_ELF_NOTE_DLOPEN() macro with associated constants. Includes usage examples for single and multiple soname annotations. Signed-off-by: Christian Brauner <brauner@kernel.org>
This commit is contained in:
Christian Brauner
committed by
Luca Boccassi
Luca Boccassi
parent
8b12350b75
commit
f90ee22bcf
143
man/SD_ELF_NOTE_DLOPEN.xml
Normal file
143
man/SD_ELF_NOTE_DLOPEN.xml
Normal file
@@ -0,0 +1,143 @@
|
||||
<?xml version='1.0'?>
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
|
||||
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
|
||||
|
||||
<refentry id="SD_ELF_NOTE_DLOPEN" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||||
|
||||
<refentryinfo>
|
||||
<title>SD_ELF_NOTE_DLOPEN</title>
|
||||
<productname>systemd</productname>
|
||||
</refentryinfo>
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>SD_ELF_NOTE_DLOPEN</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>SD_ELF_NOTE_DLOPEN</refname>
|
||||
<refname>SD_ELF_NOTE_DLOPEN_VENDOR</refname>
|
||||
<refname>SD_ELF_NOTE_DLOPEN_TYPE</refname>
|
||||
<refname>SD_ELF_NOTE_DLOPEN_PRIORITY_REQUIRED</refname>
|
||||
<refname>SD_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED</refname>
|
||||
<refname>SD_ELF_NOTE_DLOPEN_PRIORITY_SUGGESTED</refname>
|
||||
|
||||
<refpurpose>Embed ELF .note.dlopen metadata for shared library dependencies</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>#include <systemd/sd-dlopen.h></funcsynopsisinfo>
|
||||
|
||||
<funcsynopsisinfo><function>SD_ELF_NOTE_DLOPEN(<replaceable>feature</replaceable>, <replaceable>description</replaceable>, <replaceable>priority</replaceable>, <replaceable>soname...</replaceable>)</function></funcsynopsisinfo>
|
||||
|
||||
<funcsynopsisinfo>#define SD_ELF_NOTE_DLOPEN_VENDOR "FDO"</funcsynopsisinfo>
|
||||
<funcsynopsisinfo>#define SD_ELF_NOTE_DLOPEN_TYPE UINT32_C(0x407c0c0a)</funcsynopsisinfo>
|
||||
<funcsynopsisinfo>#define SD_ELF_NOTE_DLOPEN_PRIORITY_REQUIRED "required"</funcsynopsisinfo>
|
||||
<funcsynopsisinfo>#define SD_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED "recommended"</funcsynopsisinfo>
|
||||
<funcsynopsisinfo>#define SD_ELF_NOTE_DLOPEN_PRIORITY_SUGGESTED "suggested"</funcsynopsisinfo>
|
||||
|
||||
</funcsynopsis>
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para><function>SD_ELF_NOTE_DLOPEN()</function> is a macro that embeds a
|
||||
<filename>.note.dlopen</filename> ELF note section in the compiled binary, declaring a weak dependency
|
||||
on a shared library loaded via <function>dlopen()</function>. This implements the
|
||||
<ulink url="https://uapi-group.org/specifications/specs/elf_dlopen_metadata/">ELF dlopen
|
||||
metadata</ulink> specification, allowing package managers and build systems to discover runtime
|
||||
dependencies that are not visible through regular ELF <constant>DT_NEEDED</constant> entries.</para>
|
||||
|
||||
<para>The macro takes the following parameters:</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><parameter>feature</parameter></term>
|
||||
<listitem><para>A short string identifying the feature this library provides (e.g.
|
||||
<literal>XKB</literal>, <literal>PCRE2</literal>).</para>
|
||||
<xi:include href="version-info.xml" xpointer="v261"/></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><parameter>description</parameter></term>
|
||||
<listitem><para>A human-readable description of what the library is used for.</para>
|
||||
<xi:include href="version-info.xml" xpointer="v261"/></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><parameter>priority</parameter></term>
|
||||
<listitem><para>One of <constant>SD_ELF_NOTE_DLOPEN_PRIORITY_REQUIRED</constant>,
|
||||
<constant>SD_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED</constant>, or
|
||||
<constant>SD_ELF_NOTE_DLOPEN_PRIORITY_SUGGESTED</constant>, indicating how important the
|
||||
dependency is.</para>
|
||||
<xi:include href="version-info.xml" xpointer="v261"/></listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><parameter>soname...</parameter></term>
|
||||
<listitem><para>One or more shared object names (sonames) for the library, e.g.
|
||||
<literal>libfoo.so.1</literal>. Multiple sonames may be specified as separate arguments (up to 5)
|
||||
for libraries that have changed soname across versions.</para>
|
||||
<xi:include href="version-info.xml" xpointer="v261"/></listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<para>The embedded metadata can be read from a compiled ELF binary using:</para>
|
||||
<programlisting>systemd-analyze dlopen-metadata <replaceable>binary</replaceable></programlisting>
|
||||
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Examples</title>
|
||||
|
||||
<example>
|
||||
<title>Single soname</title>
|
||||
<programlisting>#include <systemd/sd-dlopen.h>
|
||||
|
||||
SD_ELF_NOTE_DLOPEN("XKB", "Keyboard layout support",
|
||||
SD_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED,
|
||||
"libxkbcommon.so.0");</programlisting>
|
||||
</example>
|
||||
|
||||
<example>
|
||||
<title>Multiple sonames for different library versions</title>
|
||||
<programlisting>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");</programlisting>
|
||||
</example>
|
||||
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Notes</title>
|
||||
|
||||
<para>The macros described here are header-only and do not require runtime linkage against
|
||||
<citerefentry><refentrytitle>libsystemd</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
||||
Only the installed header and include path (as provided by
|
||||
<command>pkg-config --cflags libsystemd</command>) are needed.</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>History</title>
|
||||
<para><function>SD_ELF_NOTE_DLOPEN()</function>,
|
||||
<function>SD_ELF_NOTE_DLOPEN_VENDOR</function>,
|
||||
<function>SD_ELF_NOTE_DLOPEN_TYPE</function>,
|
||||
<function>SD_ELF_NOTE_DLOPEN_PRIORITY_REQUIRED</function>,
|
||||
<function>SD_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED</function>, and
|
||||
<function>SD_ELF_NOTE_DLOPEN_PRIORITY_SUGGESTED</function> were added in version 261.</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>See Also</title>
|
||||
|
||||
<para><simplelist type="inline">
|
||||
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
|
||||
<member><citerefentry><refentrytitle>sd-dlopen</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
|
||||
<member><citerefentry project='man-pages'><refentrytitle>dlopen</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
|
||||
</simplelist></para>
|
||||
</refsect1>
|
||||
|
||||
</refentry>
|
||||
@@ -127,6 +127,7 @@ manpages = [
|
||||
'SD_WARNING'],
|
||||
''],
|
||||
['sd-device', '3', [], ''],
|
||||
['sd-dlopen', '3', [], ''],
|
||||
['sd-event', '3', [], ''],
|
||||
['sd-hwdb', '3', [], ''],
|
||||
['sd-id128',
|
||||
@@ -154,6 +155,14 @@ manpages = [
|
||||
['sd-login', '3', [], 'HAVE_PAM'],
|
||||
['sd-path', '3', [], ''],
|
||||
['sd-varlink', '3', [], ''],
|
||||
['SD_ELF_NOTE_DLOPEN',
|
||||
'3',
|
||||
['SD_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED',
|
||||
'SD_ELF_NOTE_DLOPEN_PRIORITY_REQUIRED',
|
||||
'SD_ELF_NOTE_DLOPEN_PRIORITY_SUGGESTED',
|
||||
'SD_ELF_NOTE_DLOPEN_TYPE',
|
||||
'SD_ELF_NOTE_DLOPEN_VENDOR'],
|
||||
''],
|
||||
['sd_booted', '3', [], ''],
|
||||
['sd_bus_add_match',
|
||||
'3',
|
||||
|
||||
80
man/sd-dlopen.xml
Normal file
80
man/sd-dlopen.xml
Normal file
@@ -0,0 +1,80 @@
|
||||
<?xml version='1.0'?>
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
|
||||
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
|
||||
|
||||
<refentry id="sd-dlopen" xmlns:xi="http://www.w3.org/2001/XInclude">
|
||||
|
||||
<refentryinfo>
|
||||
<title>sd-dlopen</title>
|
||||
<productname>systemd</productname>
|
||||
</refentryinfo>
|
||||
|
||||
<refmeta>
|
||||
<refentrytitle>sd-dlopen</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>sd-dlopen</refname>
|
||||
<refpurpose>ELF dlopen metadata annotation macros</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsynopsisdiv>
|
||||
<funcsynopsis>
|
||||
<funcsynopsisinfo>#include <systemd/sd-dlopen.h></funcsynopsisinfo>
|
||||
</funcsynopsis>
|
||||
|
||||
<cmdsynopsis>
|
||||
<command>pkg-config --cflags libsystemd</command>
|
||||
</cmdsynopsis>
|
||||
|
||||
</refsynopsisdiv>
|
||||
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
|
||||
<para><filename>sd-dlopen.h</filename> provides macros for embedding
|
||||
<filename>.note.dlopen</filename> metadata in ELF binaries, implementing the
|
||||
<ulink url="https://uapi-group.org/specifications/specs/elf_dlopen_metadata/">ELF dlopen
|
||||
metadata</ulink> specification for declaring optional shared library dependencies that are loaded via
|
||||
<citerefentry project='man-pages'><refentrytitle>dlopen</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||
at runtime.</para>
|
||||
|
||||
<para>The header is self-contained and does not require runtime linkage against
|
||||
<citerefentry><refentrytitle>libsystemd</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
||||
Projects only need the installed header to use the macros.</para>
|
||||
|
||||
<para>Package managers and build systems can read the embedded ELF notes to discover runtime
|
||||
dependencies that are not visible in ELF <constant>DT_NEEDED</constant> entries.</para>
|
||||
|
||||
<para>See
|
||||
<citerefentry><refentrytitle>SD_ELF_NOTE_DLOPEN</refentrytitle><manvolnum>3</manvolnum></citerefentry>
|
||||
for details on the available macros and constants.</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Notes</title>
|
||||
|
||||
<para>The macros described here are header-only and do not require runtime linkage against
|
||||
<citerefentry><refentrytitle>libsystemd</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
||||
Only the installed header and include path (as provided by
|
||||
<command>pkg-config --cflags libsystemd</command>) are needed.</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>History</title>
|
||||
<para><function>SD_ELF_NOTE_DLOPEN()</function> and associated macros and constants were added in
|
||||
version 261.</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>See Also</title>
|
||||
<para><simplelist type="inline">
|
||||
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
|
||||
<member><citerefentry><refentrytitle>SD_ELF_NOTE_DLOPEN</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
|
||||
<member><citerefentry project='man-pages'><refentrytitle>dlopen</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
|
||||
</simplelist></para>
|
||||
</refsect1>
|
||||
|
||||
</refentry>
|
||||
Reference in New Issue
Block a user