sd_bus_creds_new_from_pid

systemd
A monkey with a typewriter Zbigniew Jędrzejewski-Szmek zbyszek@in.waw.pl
sd_bus_creds_new_from_pid 3
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

    #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