Debian Codegraph @

upstream/debian-unstable/man3/SD_ELF_NOTE_DLOPEN.3

raw
1 '\" t
2 .TH "SD_ELF_NOTE_DLOPEN" "3" "" "systemd 261~rc3" "SD_ELF_NOTE_DLOPEN"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 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
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-dlopen\&.h>
29 .fi
30 .ft
31 .sp
32 .ft B
33 .nf
34 SD_ELF_NOTE_DLOPEN(\fIfeature\fR, \fIdescription\fR, \fIpriority\fR, \fIsoname\&.\&.\&.\fR)
35 .fi
36 .ft
37 .sp
38 .ft B
39 .nf
40 #define SD_ELF_NOTE_DLOPEN_VENDOR "FDO"
41 .fi
42 .ft
43 .sp
44 .ft B
45 .nf
46 #define SD_ELF_NOTE_DLOPEN_TYPE UINT32_C(0x407c0c0a)
47 .fi
48 .ft
49 .sp
50 .ft B
51 .nf
52 #define SD_ELF_NOTE_DLOPEN_PRIORITY_REQUIRED "required"
53 .fi
54 .ft
55 .sp
56 .ft B
57 .nf
58 #define SD_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED "recommended"
59 .fi
60 .ft
61 .sp
62 .ft B
63 .nf
64 #define SD_ELF_NOTE_DLOPEN_PRIORITY_SUGGESTED "suggested"
65 .fi
66 .ft
67 .SH "DESCRIPTION"
68 .PP
69 \fBSD_ELF_NOTE_DLOPEN()\fR
70 is a macro that embeds a
71 \&.note\&.dlopen
72 ELF note section in the compiled binary, declaring a weak dependency on a shared library loaded via
73 \fBdlopen()\fR\&. This implements the
74 \m[blue]\fBELF dlopen metadata\fR\m[]\&\s-2\u[1]\d\s+2
75 specification, allowing package managers and build systems to discover runtime dependencies that are not visible through regular ELF
76 \fBDT_NEEDED\fR
77 entries\&.
78 .PP
79 The macro takes the following parameters:
80 .PP
81 \fIfeature\fR
82 .RS 4
83 A short string identifying the feature this library provides (e\&.g\&.
84 "XKB",
85 "PCRE2")\&.
86 .sp
87 Added in version 261\&.
88 .RE
89 .PP
90 \fIdescription\fR
91 .RS 4
92 A human\-readable description of what the library is used for\&.
93 .sp
94 Added in version 261\&.
95 .RE
96 .PP
97 \fIpriority\fR
98 .RS 4
99 One of
100 \fBSD_ELF_NOTE_DLOPEN_PRIORITY_REQUIRED\fR,
101 \fBSD_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED\fR, or
102 \fBSD_ELF_NOTE_DLOPEN_PRIORITY_SUGGESTED\fR, indicating how important the dependency is\&.
103 .sp
104 Added in version 261\&.
105 .RE
106 .PP
107 \fIsoname\&.\&.\&.\fR
108 .RS 4
109 One or more shared object names (sonames) for the library, e\&.g\&.
110 "libfoo\&.so\&.1"\&. Multiple sonames may be specified as separate arguments (up to 5) for libraries that have changed soname across versions\&.
111 .sp
112 Added in version 261\&.
113 .RE
114 .PP
115 The embedded metadata can be read from a compiled ELF binary using:
116 .sp
117 .if n \{\
118 .RS 4
119 .\}
120 .nf
121 systemd\-analyze dlopen\-metadata \fIbinary\fR
122 .fi
123 .if n \{\
124 .RE
125 .\}
126 .SH "EXAMPLES"
127 .PP
128 \fBExample\ \&1.\ \&Single soname\fR
129 .sp
130 .if n \{\
131 .RS 4
132 .\}
133 .nf
134 #include <systemd/sd\-dlopen\&.h>
135
136 SD_ELF_NOTE_DLOPEN("XKB", "Keyboard layout support",
137 SD_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED,
138 "libxkbcommon\&.so\&.0");
139 .fi
140 .if n \{\
141 .RE
142 .\}
143 .PP
144 \fBExample\ \&2.\ \&Multiple sonames for different library versions\fR
145 .sp
146 .if n \{\
147 .RS 4
148 .\}
149 .nf
150 SD_ELF_NOTE_DLOPEN("crypt", "Support for hashing passwords",
151 SD_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED,
152 "libcrypt\&.so\&.2", "libcrypt\&.so\&.1", "libcrypt\&.so\&.1\&.1");
153 .fi
154 .if n \{\
155 .RE
156 .\}
157 .SH "NOTES"
158 .PP
159 The macros described here are header\-only and do not require runtime linkage against
160 \fBlibsystemd\fR(3)\&. Only the installed header and include path (as provided by
161 \fBpkg\-config \-\-cflags libsystemd\fR) are needed\&.
162 .SH "HISTORY"
163 .PP
164 \fBSD_ELF_NOTE_DLOPEN()\fR,
165 \fBSD_ELF_NOTE_DLOPEN_VENDOR\fR,
166 \fBSD_ELF_NOTE_DLOPEN_TYPE\fR,
167 \fBSD_ELF_NOTE_DLOPEN_PRIORITY_REQUIRED\fR,
168 \fBSD_ELF_NOTE_DLOPEN_PRIORITY_RECOMMENDED\fR, and
169 \fBSD_ELF_NOTE_DLOPEN_PRIORITY_SUGGESTED\fR
170 were added in version 261\&.
171 .SH "SEE ALSO"
172 .PP
173 \fBsystemd\fR(1), \fBsd-dlopen\fR(3), \fBdlopen\fR(3)
174 .SH "NOTES"
175 .IP " 1." 4
176 ELF dlopen metadata
177 .RS 4
178 \%https://uapi-group.org/specifications/specs/elf_dlopen_metadata/
179 .RE