Debian Codegraph @

upstream/debian-unstable/man3/sd_bus_creds_new_from_pid.3

raw
1 '\" t
2 .TH "SD_BUS_CREDS_NEW_FROM_PID" "3" "" "systemd 261~rc3" "sd_bus_creds_new_from_pid"
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_bus_creds_new_from_pid, sd_bus_creds_new_from_pidfd, sd_bus_creds_get_mask, sd_bus_creds_get_augmented_mask, sd_bus_creds_ref, sd_bus_creds_unref, sd_bus_creds_unrefp \- Retrieve credentials object for the specified PID
24 .SH "SYNOPSIS"
25 .sp
26 .ft B
27 .nf
28 #include <systemd/sd\-bus\&.h>
29 .fi
30 .ft
31 .HP \w'int\ sd_bus_creds_new_from_pid('u
32 .BI "int sd_bus_creds_new_from_pid(pid_t\ " "pid" ", uint64_t\ " "creds_mask" ", sd_bus_creds\ **" "ret" ");"
33 .HP \w'int\ sd_bus_creds_new_from_pidfd('u
34 .BI "int sd_bus_creds_new_from_pidfd(int\ " "pidfd" ", uint64_t\ " "creds_mask" ", sd_bus_creds\ **" "ret" ");"
35 .HP \w'uint64_t\ sd_bus_creds_get_mask('u
36 .BI "uint64_t sd_bus_creds_get_mask(sd_bus_creds\ *" "c" ");"
37 .HP \w'uint64_t\ sd_bus_creds_get_augmented_mask('u
38 .BI "uint64_t sd_bus_creds_get_augmented_mask(sd_bus_creds\ *" "c" ");"
39 .HP \w'sd_bus_creds\ *sd_bus_creds_ref('u
40 .BI "sd_bus_creds *sd_bus_creds_ref(sd_bus_creds\ *" "c" ");"
41 .HP \w'sd_bus_creds\ *sd_bus_creds_unref('u
42 .BI "sd_bus_creds *sd_bus_creds_unref(sd_bus_creds\ *" "c" ");"
43 .HP \w'void\ sd_bus_creds_unrefp('u
44 .BI "void sd_bus_creds_unrefp(sd_bus_creds\ **" "c" ");"
45 .PP
46 \fBSD_BUS_CREDS_PID\fR,
47 \fBSD_BUS_CREDS_PPID\fR,
48 \fBSD_BUS_CREDS_TID\fR,
49 \fBSD_BUS_CREDS_UID\fR,
50 \fBSD_BUS_CREDS_EUID\fR,
51 \fBSD_BUS_CREDS_SUID\fR,
52 \fBSD_BUS_CREDS_FSUID\fR,
53 \fBSD_BUS_CREDS_GID\fR,
54 \fBSD_BUS_CREDS_EGID\fR,
55 \fBSD_BUS_CREDS_SGID\fR,
56 \fBSD_BUS_CREDS_FSGID\fR,
57 \fBSD_BUS_CREDS_SUPPLEMENTARY_GIDS\fR,
58 \fBSD_BUS_CREDS_COMM\fR,
59 \fBSD_BUS_CREDS_TID_COMM\fR,
60 \fBSD_BUS_CREDS_EXE\fR,
61 \fBSD_BUS_CREDS_CMDLINE\fR,
62 \fBSD_BUS_CREDS_CGROUP\fR,
63 \fBSD_BUS_CREDS_UNIT\fR,
64 \fBSD_BUS_CREDS_SLICE\fR,
65 \fBSD_BUS_CREDS_USER_UNIT\fR,
66 \fBSD_BUS_CREDS_USER_SLICE\fR,
67 \fBSD_BUS_CREDS_SESSION\fR,
68 \fBSD_BUS_CREDS_OWNER_UID\fR,
69 \fBSD_BUS_CREDS_EFFECTIVE_CAPS\fR,
70 \fBSD_BUS_CREDS_PERMITTED_CAPS\fR,
71 \fBSD_BUS_CREDS_INHERITABLE_CAPS\fR,
72 \fBSD_BUS_CREDS_BOUNDING_CAPS\fR,
73 \fBSD_BUS_CREDS_SELINUX_CONTEXT\fR,
74 \fBSD_BUS_CREDS_AUDIT_SESSION_ID\fR,
75 \fBSD_BUS_CREDS_AUDIT_LOGIN_UID\fR,
76 \fBSD_BUS_CREDS_TTY\fR,
77 \fBSD_BUS_CREDS_UNIQUE_NAME\fR,
78 \fBSD_BUS_CREDS_WELL_KNOWN_NAMES\fR,
79 \fBSD_BUS_CREDS_DESCRIPTION\fR,
80 \fBSD_BUS_CREDS_PIDFD\fR,
81 \fBSD_BUS_CREDS_AUGMENT\fR,
82 \fB_SD_BUS_CREDS_ALL\fR
83 .SH "DESCRIPTION"
84 .PP
85 \fBsd_bus_creds_new_from_pid()\fR
86 creates a new credentials object and fills it with information about the process
87 \fIpid\fR\&. The pointer to this object will be stored in the
88 \fIret\fR
89 pointer\&. Note that credential objects may also be created and retrieved via
90 \fBsd_bus_get_name_creds\fR(3),
91 \fBsd_bus_get_owner_creds\fR(3)
92 and
93 \fBsd_bus_message_get_creds\fR(3)\&.
94 .PP
95 \fBsd_bus_creds_new_from_pidfd()\fR
96 is identical to
97 \fBsd_bus_creds_new_from_pid()\fR, but takes a PID file descriptor rather than a numeric PID as reference to the process\&. See
98 \fBpidfd_open\fR(2)\&.
99 .PP
100 The information that will be stored is determined by
101 \fIcreds_mask\fR\&. It may contain a subset of ORed constants
102 \fBSD_BUS_CREDS_PID\fR,
103 \fBSD_BUS_CREDS_PPID\fR,
104 \fBSD_BUS_CREDS_TID\fR,
105 \fBSD_BUS_CREDS_UID\fR,
106 \fBSD_BUS_CREDS_EUID\fR,
107 \fBSD_BUS_CREDS_SUID\fR,
108 \fBSD_BUS_CREDS_FSUID\fR,
109 \fBSD_BUS_CREDS_GID\fR,
110 \fBSD_BUS_CREDS_EGID\fR,
111 \fBSD_BUS_CREDS_SGID\fR,
112 \fBSD_BUS_CREDS_FSGID\fR,
113 \fBSD_BUS_CREDS_SUPPLEMENTARY_GIDS\fR,
114 \fBSD_BUS_CREDS_COMM\fR,
115 \fBSD_BUS_CREDS_TID_COMM\fR,
116 \fBSD_BUS_CREDS_EXE\fR,
117 \fBSD_BUS_CREDS_CMDLINE\fR,
118 \fBSD_BUS_CREDS_CGROUP\fR,
119 \fBSD_BUS_CREDS_UNIT\fR,
120 \fBSD_BUS_CREDS_SLICE\fR,
121 \fBSD_BUS_CREDS_USER_UNIT\fR,
122 \fBSD_BUS_CREDS_USER_SLICE\fR,
123 \fBSD_BUS_CREDS_SESSION\fR,
124 \fBSD_BUS_CREDS_OWNER_UID\fR,
125 \fBSD_BUS_CREDS_EFFECTIVE_CAPS\fR,
126 \fBSD_BUS_CREDS_PERMITTED_CAPS\fR,
127 \fBSD_BUS_CREDS_INHERITABLE_CAPS\fR,
128 \fBSD_BUS_CREDS_BOUNDING_CAPS\fR,
129 \fBSD_BUS_CREDS_SELINUX_CONTEXT\fR,
130 \fBSD_BUS_CREDS_AUDIT_SESSION_ID\fR,
131 \fBSD_BUS_CREDS_AUDIT_LOGIN_UID\fR,
132 \fBSD_BUS_CREDS_TTY\fR,
133 \fBSD_BUS_CREDS_UNIQUE_NAME\fR,
134 \fBSD_BUS_CREDS_WELL_KNOWN_NAMES\fR,
135 \fBSD_BUS_CREDS_DESCRIPTION\fR, and
136 \fBSD_BUS_CREDS_PIDFD\fR\&. Use the special value
137 \fB_SD_BUS_CREDS_ALL\fR
138 to request all supported fields\&. The
139 \fBSD_BUS_CREDS_AUGMENT\fR
140 constant may not be ORed into the mask for invocations of
141 \fBsd_bus_creds_new_from_pid()\fR
142 or
143 \fBsd_bus_creds_new_from_pidfd()\fR\&.
144 .PP
145 Fields can be retrieved from the credentials object using
146 \fBsd_bus_creds_get_pid\fR(3)
147 and other functions which correspond directly to the constants listed above\&.
148 .PP
149 A mask of fields which were actually successfully retrieved can be retrieved with
150 \fBsd_bus_creds_get_mask()\fR\&. If the credentials object was created with
151 \fBsd_bus_creds_new_from_pid()\fR
152 or
153 \fBsd_bus_creds_new_from_pidfd()\fR, this will be a subset of fields requested in
154 \fIcreds_mask\fR\&.
155 .PP
156 Similar to
157 \fBsd_bus_creds_get_mask()\fR, the function
158 \fBsd_bus_creds_get_augmented_mask()\fR
159 returns a bitmask of field constants\&. The mask indicates which credential fields have been retrieved in a non\-atomic fashion\&. For credential objects created via
160 \fBsd_bus_creds_new_from_pid()\fR
161 or
162 \fBsd_bus_creds_new_from_pidfd()\fR, this mask will be identical to the mask returned by
163 \fBsd_bus_creds_get_mask()\fR\&. However, for credential objects retrieved via
164 \fBsd_bus_get_name_creds()\fR, this mask will be set for the credential fields that could not be determined atomically at peer connection time, and which were later added by reading augmenting credential data from
165 /proc/\&. Similarly, for credential objects retrieved via
166 \fBsd_bus_get_owner_creds()\fR, the mask is set for the fields that could not be determined atomically at bus creation time, but have been augmented\&. Similarly, for credential objects retrieved via
167 \fBsd_bus_message_get_creds()\fR, the mask is set for the fields that could not be determined atomically at message sending time, but have been augmented\&. The mask returned by
168 \fBsd_bus_creds_get_augmented_mask()\fR
169 is always a subset of (or identical to) the mask returned by
170 \fBsd_bus_creds_get_mask()\fR
171 for the same object\&. The latter call hence returns all credential fields available in the credential object, the former then marks the subset of those that have been augmented\&. Note that augmented fields are unsuitable for authorization decisions, as they may be retrieved at different times, thus being subject to races\&. Hence, augmented fields should be used exclusively for informational purposes\&.
172 .PP
173 \fBsd_bus_creds_ref()\fR
174 creates a new reference to the credentials object
175 \fIc\fR\&. This object will not be destroyed until
176 \fBsd_bus_creds_unref()\fR
177 has been called as many times plus once more\&. Once the reference count has dropped to zero,
178 \fIc\fR
179 cannot be used anymore, so further calls to
180 \fBsd_bus_creds_ref(c)\fR
181 or
182 \fBsd_bus_creds_unref(c)\fR
183 are illegal\&.
184 .PP
185 \fBsd_bus_creds_unref()\fR
186 destroys a reference to
187 \fIc\fR\&.
188 .PP
189 \fBsd_bus_creds_unrefp()\fR
190 is similar to
191 \fBsd_bus_creds_unref()\fR
192 but takes a pointer to a pointer to an
193 \fBsd_bus_creds\fR
194 object\&. This call is useful in conjunction with GCC\*(Aqs and LLVM\*(Aqs
195 \m[blue]\fBClean\-up Variable Attribute\fR\m[]\&\s-2\u[1]\d\s+2\&. Note that this function is defined as inline function\&.
196 .PP
197 \fBsd_bus_creds_ref()\fR,
198 \fBsd_bus_creds_unref()\fR
199 and
200 \fBsd_bus_creds_unrefp()\fR
201 execute no operation if the passed in bus credentials object is
202 \fBNULL\fR\&.
203 .SH "RETURN VALUE"
204 .PP
205 On success,
206 \fBsd_bus_creds_new_from_pid()\fR
207 and
208 \fBsd_bus_creds_new_from_pidfd()\fR
209 return 0 or a positive integer\&. On failure, they return a negative errno\-style error code\&.
210 .PP
211 \fBsd_bus_creds_get_mask()\fR
212 returns the mask of successfully acquired fields\&.
213 .PP
214 \fBsd_bus_creds_get_augmented_mask()\fR
215 returns the mask of fields that have been augmented from data in
216 /proc/, and are thus not suitable for authorization decisions\&.
217 .PP
218 \fBsd_bus_creds_ref()\fR
219 always returns the argument\&.
220 .PP
221 \fBsd_bus_creds_unref()\fR
222 always returns
223 \fBNULL\fR\&.
224 .SH "REFERENCE OWNERSHIP"
225 .PP
226 The functions
227 \fBsd_bus_creds_new_from_pid()\fR
228 and
229 \fBsd_bus_creds_new_from_pidfd()\fR
230 create a new object and the caller owns the sole reference\&. When not needed anymore, this reference should be destroyed with
231 \fBsd_bus_creds_unref\fR(3)\&.
232 .SS "Errors"
233 .PP
234 Returned errors may indicate the following problems:
235 .PP
236 \fB\-ESRCH\fR
237 .RS 4
238 Specified
239 \fIpid\fR
240 could not be found\&.
241 .RE
242 .PP
243 \fB\-EINVAL\fR
244 .RS 4
245 Specified parameter is invalid (\fBNULL\fR
246 in case of output parameters)\&.
247 .RE
248 .PP
249 \fB\-ENOMEM\fR
250 .RS 4
251 Memory allocation failed\&.
252 .RE
253 .PP
254 \fB\-EOPNOTSUPP\fR
255 .RS 4
256 One of the requested fields is unknown to the local system\&.
257 .RE
258 .SH "NOTES"
259 .PP
260 Functions described here are available as a shared library, which can be compiled against and linked to with the
261 \fBlibsystemd\fR\ \&\fBpkg-config\fR(1)
262 file\&.
263 .PP
264 The code described here uses
265 \fBgetenv\fR(3), which is declared to be not multi\-thread\-safe\&. This means that the code calling the functions described here must not call
266 \fBsetenv\fR(3)
267 from a parallel thread\&. It is recommended to only do calls to
268 \fBsetenv()\fR
269 from an early phase of the program when no other threads have been started\&.
270 .SH "HISTORY"
271 .PP
272 \fBsd_bus_creds_new_from_pid()\fR,
273 \fBsd_bus_creds_get_mask()\fR,
274 \fBsd_bus_creds_ref()\fR,
275 \fBsd_bus_creds_unref()\fR, and
276 \fBsd_bus_creds_get_augmented_mask()\fR
277 were added in version 221\&.
278 .PP
279 \fBsd_bus_creds_unrefp()\fR
280 was added in version 229\&.
281 .PP
282 \fBsd_bus_creds_new_from_pidfd()\fR
283 was added in version 256\&.
284 .SH "SEE ALSO"
285 .PP
286 \fBsystemd\fR(1), \fBsd-bus\fR(3), \fBsd_bus_creds_get_pid\fR(3), \fBsd_bus_get_name_creds\fR(3), \fBsd_bus_get_owner_creds\fR(3), \fBsd_bus_message_get_creds\fR(3)
287 .SH "NOTES"
288 .IP " 1." 4
289 Clean-up Variable Attribute
290 .RS 4
291 \%https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html
292 .RE