sd_bus_creds_new_from_pid(3)

1SD_BUS_CREDS_NEW_FROM_PID(3)sd_bus_creds_new_from_piSdD_BUS_CREDS_NEW_FROM_PID(3)
2
3
4

NAME

6       sd_bus_creds_new_from_pid, sd_bus_creds_get_mask,
7       sd_bus_creds_get_augmented_mask, sd_bus_creds_ref, sd_bus_creds_unref,
8       sd_bus_creds_unrefp - Retrieve credentials object for the specified PID
9

SYNOPSIS

11       #include <systemd/sd-bus.h>
12
13       int sd_bus_creds_new_from_pid(pid_t pid, uint64_t creds_mask,
14                                     sd_bus_creds **ret);
15
16       uint64_t sd_bus_creds_get_mask(sd_bus_creds *c);
17
18       uint64_t sd_bus_creds_get_augmented_mask(sd_bus_creds *c);
19
20       sd_bus_creds *sd_bus_creds_ref(sd_bus_creds *c);
21
22       sd_bus_creds *sd_bus_creds_unref(sd_bus_creds *c);
23
24       void sd_bus_creds_unrefp(sd_bus_creds **c);
25
26       SD_BUS_CREDS_PID, SD_BUS_CREDS_PPID, SD_BUS_CREDS_TID,
27       SD_BUS_CREDS_UID, SD_BUS_CREDS_EUID, SD_BUS_CREDS_SUID,
28       SD_BUS_CREDS_FSUID, SD_BUS_CREDS_GID, SD_BUS_CREDS_EGID,
29       SD_BUS_CREDS_SGID, SD_BUS_CREDS_FSGID, SD_BUS_CREDS_SUPPLEMENTARY_GIDS,
30       SD_BUS_CREDS_COMM, SD_BUS_CREDS_TID_COMM, SD_BUS_CREDS_EXE,
31       SD_BUS_CREDS_CMDLINE, SD_BUS_CREDS_CGROUP, SD_BUS_CREDS_UNIT,
32       SD_BUS_CREDS_SLICE, SD_BUS_CREDS_USER_UNIT, SD_BUS_CREDS_USER_SLICE,
33       SD_BUS_CREDS_SESSION, SD_BUS_CREDS_OWNER_UID,
34       SD_BUS_CREDS_EFFECTIVE_CAPS, SD_BUS_CREDS_PERMITTED_CAPS,
35       SD_BUS_CREDS_INHERITABLE_CAPS, SD_BUS_CREDS_BOUNDING_CAPS,
36       SD_BUS_CREDS_SELINUX_CONTEXT, SD_BUS_CREDS_AUDIT_SESSION_ID,
37       SD_BUS_CREDS_AUDIT_LOGIN_UID, SD_BUS_CREDS_TTY,
38       SD_BUS_CREDS_UNIQUE_NAME, SD_BUS_CREDS_WELL_KNOWN_NAMES,
39       SD_BUS_CREDS_DESCRIPTION, SD_BUS_CREDS_AUGMENT, _SD_BUS_CREDS_ALL
40

DESCRIPTION

42       sd_bus_creds_new_from_pid() creates a new credentials object and fills
43       it with information about the process pid. The pointer to this object
44       will be stored in the ret pointer. Note that credential objects may
45       also be created and retrieved via sd_bus_get_name_creds(3),
46       sd_bus_get_owner_creds(3) and sd_bus_message_get_creds(3).
47
48       The information that will be stored is determined by creds_mask. It may
49       contain a subset of ORed constants SD_BUS_CREDS_PID, SD_BUS_CREDS_PPID,
50       SD_BUS_CREDS_TID, SD_BUS_CREDS_UID, SD_BUS_CREDS_EUID,
51       SD_BUS_CREDS_SUID, SD_BUS_CREDS_FSUID, SD_BUS_CREDS_GID,
52       SD_BUS_CREDS_EGID, SD_BUS_CREDS_SGID, SD_BUS_CREDS_FSGID,
53       SD_BUS_CREDS_SUPPLEMENTARY_GIDS, SD_BUS_CREDS_COMM,
54       SD_BUS_CREDS_TID_COMM, SD_BUS_CREDS_EXE, SD_BUS_CREDS_CMDLINE,
55       SD_BUS_CREDS_CGROUP, SD_BUS_CREDS_UNIT, SD_BUS_CREDS_SLICE,
56       SD_BUS_CREDS_USER_UNIT, SD_BUS_CREDS_USER_SLICE, SD_BUS_CREDS_SESSION,
57       SD_BUS_CREDS_OWNER_UID, SD_BUS_CREDS_EFFECTIVE_CAPS,
58       SD_BUS_CREDS_PERMITTED_CAPS, SD_BUS_CREDS_INHERITABLE_CAPS,
59       SD_BUS_CREDS_BOUNDING_CAPS, SD_BUS_CREDS_SELINUX_CONTEXT,
60       SD_BUS_CREDS_AUDIT_SESSION_ID, SD_BUS_CREDS_AUDIT_LOGIN_UID,
61       SD_BUS_CREDS_TTY, SD_BUS_CREDS_UNIQUE_NAME,
62       SD_BUS_CREDS_WELL_KNOWN_NAMES, and SD_BUS_CREDS_DESCRIPTION. Use the
63       special value _SD_BUS_CREDS_ALL to request all supported fields. The
64       SD_BUS_CREDS_AUGMENT constant may not be ORed into the mask for
65       invocations of sd_bus_creds_new_from_pid().
66
67       Fields can be retrieved from the credentials object using
68       sd_bus_creds_get_pid(3) and other functions which correspond directly
69       to the constants listed above.
70
71       A mask of fields which were actually successfully retrieved can be
72       retrieved with sd_bus_creds_get_mask(). If the credentials object was
73       created with sd_bus_creds_new_from_pid(), this will be a subset of
74       fields requested in creds_mask.
75
76       Similar to sd_bus_creds_get_mask(), the function
77       sd_bus_creds_get_augmented_mask() returns a bitmask of field constants.
78       The mask indicates which credential fields have been retrieved in a
79       non-atomic fashion. For credential objects created via
80       sd_bus_creds_new_from_pid(), this mask will be identical to the mask
81       returned by sd_bus_creds_get_mask(). However, for credential objects
82       retrieved via sd_bus_get_name_creds(), this mask will be set for the
83       credential fields that could not be determined atomically at peer
84       connection time, and which were later added by reading augmenting
85       credential data from /proc. Similarly, for credential objects retrieved
86       via sd_bus_get_owner_creds(), the mask is set for the fields that could
87       not be determined atomically at bus creation time, but have been
88       augmented. Similarly, for credential objects retrieved via
89       sd_bus_message_get_creds(), the mask is set for the fields that could
90       not be determined atomically at message sending time, but have been
91       augmented. The mask returned by sd_bus_creds_get_augmented_mask() is
92       always a subset of (or identical to) the mask returned by
93       sd_bus_creds_get_mask() for the same object. The latter call hence
94       returns all credential fields available in the credential object, the
95       former then marks the subset of those that have been augmented. Note
96       that augmented fields are unsuitable for authorization decisions, as
97       they may be retrieved at different times, thus being subject to races.
98       Hence, augmented fields should be used exclusively for informational
99       purposes.
100
101       sd_bus_creds_ref() creates a new reference to the credentials object c.
102       This object will not be destroyed until sd_bus_creds_unref() has been
103       called as many times plus once more. Once the reference count has
104       dropped to zero, c cannot be used anymore, so further calls to
105       sd_bus_creds_ref(c) or sd_bus_creds_unref(c) are illegal.
106
107       sd_bus_creds_unref() destroys a reference to c.
108
109       sd_bus_creds_unrefp() is similar to sd_bus_creds_unref() but takes a
110       pointer to a pointer to an sd_bus_creds object. This call is useful in
111       conjunction with GCC's and LLVM's Clean-up Variable Attribute[1]. Note
112       that this function is defined as inline function.
113
114       sd_bus_creds_ref(), sd_bus_creds_unref() and sd_bus_creds_unrefp()
115       execute no operation if the passed in bus credentials object is NULL.
116

RETURN VALUE

118       On success, sd_bus_creds_new_from_pid() returns 0 or a positive
119       integer. On failure, it returns a negative errno-style error code.
120
121       sd_bus_creds_get_mask() returns the mask of successfully acquired
122       fields.
123
124       sd_bus_creds_get_augmented_mask() returns the mask of fields that have
125       been augmented from data in /proc, and are thus not suitable for
126       authorization decisions.
127
128       sd_bus_creds_ref() always returns the argument.
129
130       sd_bus_creds_unref() always returns NULL.
131

REFERENCE OWNERSHIP

133       Function sd_bus_creds_new_from_pid() creates a new object and the
134       caller owns the sole reference. When not needed anymore, this reference
135       should be destroyed with sd_bus_creds_unref(3).
136

ERRORS

138       Returned errors may indicate the following problems:
139
140       -ESRCH
141           Specified pid could not be found.
142
143       -EINVAL
144           Specified parameter is invalid (NULL in case of output parameters).
145
146       -ENOMEM
147           Memory allocation failed.
148
149       -EOPNOTSUPP
150           One of the requested fields is unknown to the local system.
151

NOTES

153       These APIs are implemented as a shared library, which can be compiled
154       and linked to with the libsystemd pkg-config(1) file.
155

NOTES

162        1. Clean-up Variable Attribute
163           https://gcc.gnu.org/onlinedocs/gcc/Common-Variable-Attributes.html
164
165
166
167systemd 239                                       SD_BUS_CREDS_NEW_FROM_PID(3)