sd_bus_creds_new_from_pid

Index · Directives · Python · libudev · gudev systemd 215

## Name

sd_bus_creds_new_from_pid, sd_bus_creds_get_mask, sd_bus_creds_ref, sd_bus_creds_unref — Retrieve credentials object for the specified PID

## Synopsis

    #include <systemd/sd-bus.h>

`int sd_bus_creds_new_from_pid(` | pid_t pid,
| uint64_t creds_mask,
| sd_bus_creds **ret`)`;

`uint64_t sd_bus_creds_get_mask(` | const sd_bus_creds *c`)`;

`sd_bus_creds *sd_bus_creds_ref(` | sd_bus_creds *c`)`;

`sd_bus_creds *sd_bus_creds_unref(` | sd_bus_creds *c`)`;

`SD_BUS_CREDS_PID`, `SD_BUS_CREDS_PID_STARTTIME`, `SD_BUS_CREDS_TID`, `SD_BUS_CREDS_UID`, `SD_BUS_CREDS_GID`, `SD_BUS_CREDS_COMM`, `SD_BUS_CREDS_TID_COMM`, `SD_BUS_CREDS_EXE`, `SD_BUS_CREDS_CMDLINE`, `SD_BUS_CREDS_CGROUP`, `SD_BUS_CREDS_UNIT`, `SD_BUS_CREDS_USER_UNIT`, `SD_BUS_CREDS_SLICE`, `SD_BUS_CREDS_SESSION`, `SD_BUS_CREDS_OWNER_UID`, `SD_BUS_CREDS_EFFECTIVE_CAPS`, `SD_BUS_CREDS_PERMITTED_CAPS`, `SD_BUS_CREDS_INHERITABLE_CAPS`, `SD_BUS_CREDS_BOUNDING_CAPS`, `SD_BUS_CREDS_SELINUX_CONTEXT`, `SD_BUS_CREDS_AUDIT_SESSION_ID`, `SD_BUS_CREDS_AUDIT_LOGIN_UID`, `SD_BUS_CREDS_UNIQUE_NAME`, `SD_BUS_CREDS_WELL_KNOWN_NAMES`, `_SD_BUS_CREDS_ALL`

## Description

`sd_bus_creds_new_from_pid()` creates a new credentials object and fills it with information about the process `pid`. This pointer to this object will be stored in `ret` pointer.

The information that will be stored is determined by `creds_mask`. It may contain a subset of ORed constants `SD_BUS_CREDS_PID`, `SD_BUS_CREDS_PID_STARTTIME`, `SD_BUS_CREDS_TID`, `SD_BUS_CREDS_UID`, `SD_BUS_CREDS_GID`, `SD_BUS_CREDS_COMM`, `SD_BUS_CREDS_TID_COMM`, `SD_BUS_CREDS_EXE`, `SD_BUS_CREDS_CMDLINE`, `SD_BUS_CREDS_CGROUP`, `SD_BUS_CREDS_UNIT`, `SD_BUS_CREDS_USER_UNIT`, `SD_BUS_CREDS_SLICE`, `SD_BUS_CREDS_SESSION`, `SD_BUS_CREDS_OWNER_UID`, `SD_BUS_CREDS_EFFECTIVE_CAPS`, `SD_BUS_CREDS_PERMITTED_CAPS`, `SD_BUS_CREDS_INHERITABLE_CAPS`, `SD_BUS_CREDS_BOUNDING_CAPS`, `SD_BUS_CREDS_SELINUX_CONTEXT`, `SD_BUS_CREDS_AUDIT_SESSION_ID`, `SD_BUS_CREDS_AUDIT_LOGIN_UID`, `SD_BUS_CREDS_UNIQUE_NAME`, `SD_BUS_CREDS_WELL_KNOWN_NAMES`, or `_SD_BUS_CREDS_ALL` to indicate all known fields.

Fields can be retrieved from the credentials object using sd_bus_creds_get_pid(3) and other functions which correspond directly to the constants listed above.

A mask of fields which were actually sucessfully set (acquired from `/proc`, etc.) can be retrieved with `sd_bus_creds_get_mask()`. If the credentials object was created with `sd_bus_creds_new_from_pid()`, this will be a subset of fields requested in `creds_mask`.

`sd_bus_creds_ref` creates a new reference to the credentials object `c`. This object will not be destroyed until `sd_bus_creds_unref` has been called as many times plus once more. Once the reference count has dropped to zero, `c` cannot be used anymore, so futher calls to `sd_bus_creds_ref(c)` or `sd_bus_creds_unref(c)` are illegal.

`sd_bus_creds_unref` destroys a reference to `c`.

## Return Value

On success, `sd_bus_creds_new_from_pid()` returns 0 or a positive integer. On failure, it returns a negative errno-style error code.

`sd_bus_creds_get_mask()` returns the mask of successfully acquired fields.

`sd_bus_creds_ref` always returns the argument.

`sd_bus_creds_unref` always returns `NULL`.

## Reference ownership

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

## Errors

Returned errors may indicate the following problems:

`-ESRCH`

  Specified `pid` could not be found.

`-EINVAL`

  Specified parameter is invalid (`NULL` in case of output parameters).

`-ENOMEM`

  Memory allocation failed.

## Notes

`sd_bus_creds_new_from_pid()` is available as a shared library, which can be compiled and linked to with the `libsystemd` pkg-config(1) file.

## See Also

systemd(1), sd-bus(3), sd_bus_creds_ref(3), sd_bus_creds_unref(3), sd_bus_creds_get_pid(3), sd_bus_creds_get_pid_starttime(3), sd_bus_creds_get_tid(3), sd_bus_creds_get_uid(3), sd_bus_creds_get_gid(3), sd_bus_creds_get_comm(3), sd_bus_creds_get_tid_comm(3), sd_bus_creds_get_exe(3), sd_bus_creds_get_cmdline(3), sd_bus_creds_get_cgroup(3), sd_bus_creds_get_unit(3), sd_bus_creds_get_user_unit(3), sd_bus_creds_get_slice(3), sd_bus_creds_get_session(3), sd_bus_creds_get_owner_uid(3), sd_bus_creds_has_effective_cap(3), sd_bus_creds_has_permitted_cap(3), sd_bus_creds_has_inheritable_cap(3), sd_bus_creds_has_bounding_cap(3), sd_bus_creds_get_selinux_context(3), sd_bus_creds_get_audit_session_id(3), sd_bus_creds_get_audit_login_uid(3), sd_bus_creds_get_unique_name(3), sd_bus_creds_get_well_known_names(3)