## Simple convenience interface Simple convenience interface — Simple convenience interface |

## Synopsis

    polkit_uint64_t     polkit_check_auth                   (pid_t pid,
                                                             ...);
    polkit_uint64_t     polkit_check_authv                  (pid_t pid,
                                                             const char **action_ids);
    polkit_bool_t       polkit_auth_obtain                  (const char *action_id,
                                                             polkit_uint32_t xid,
                                                             pid_t pid,
                                                             DBusError *error);
    polkit_bool_t       polkit_dbus_error_generate          (PolKitAction *action,
                                                             PolKitResult result,
                                                             DBusError *error);
    polkit_bool_t       polkit_dbus_error_parse             (DBusError *error,
                                                             PolKitAction **action,
                                                             PolKitResult *result);
    polkit_bool_t       polkit_dbus_error_parse_from_strings
                                                            (const char *error_name,
                                                             const char *error_message,
                                                             PolKitAction **action,
                                                             PolKitResult *result);

## Description

Simple convenience interface

## Details

### polkit_check_auth ()

    polkit_uint64_t     polkit_check_auth                   (pid_t pid,
                                                             ...);

A simple convenience function to check whether a given process is authorized for a number of actions.

This is useful for programs that just wants to check whether they should carry out some action. Note that the user identity used for the purpose of checking authorizations is the Real one compared to the e.g. Effective one (e.g. `getuid()`, `getgid()` is used instead of e.g. `geteuid()`, `getegid()`). This is typically what one wants in a setuid root program if the setuid root program is designed to do work on behalf of the unprivileged user who invoked it (for example, the PulseAudio sound server is setuid root only so it can become a real time process; after that it drops all privileges).

It varies whether one wants to pass `getpid()` or `getppid()` as the process id to this function. For example, in the PulseAudio case it is the right thing to pass `getpid()`. However, in a setup where the process is a privileged helper, one wants to pass the process id of the parent. Beware though, if the parent dies, `getppid()` will return 1 (the process id of `/sbin/init`) which is almost certainly guaranteed to be privileged as it is running as uid 0.

Note that this function will open a connection to the system message bus and query ConsoleKit for details. In addition, it will load PolicyKit specific files and spawn privileged helpers if necessary. As such, there is a bit of IPC, context switching, syscall overhead and I/O involved in using this function. If you are planning on calling this function multiple times (e.g. from a daemon) on a frequent basis and/or need more detail you should use the PolKitContext and PolKitTracker classes instead as these are designed to aggresively cache information.

The return value is a bit mask indicating whether the given process is authorized for the given actions. Bit 0 represents the first action; bit 1 represents the 2nd action and so forth. A bit is set to 1 if, and only if, the caller is authorized for the given action. If the given action is unknown zero will be returned as well.

If the function succeeds, errno will be set to 0. If an error occurs 0 is returned and errno will be set:

- `ENOMEM`: Out of memory.
- `ENOENT`: Failed to connect to either the system message bus or ConsoleKit.

`pid` : | process to check for; typically you want to pass the result of `getpid()` here
`...` : | `NULL` terminated list of action identifiers to check for
Returns : | See above

Since 0.7

### polkit_check_authv ()

    polkit_uint64_t     polkit_check_authv                  (pid_t pid,
                                                             const char **action_ids);

This function is similar to `polkit_check_auth()` but takes an `NULL` terminated array instead of being a varadic function.

`pid` : | See docs for `polkit_check_auth()`
`action_ids` : | `NULL` terminated array of action id's
Returns : | See docs for `polkit_check_auth()`

Since 0.7

### polkit_auth_obtain ()

    polkit_bool_t       polkit_auth_obtain                  (const char *action_id,
                                                             polkit_uint32_t xid,
                                                             pid_t pid,
                                                             DBusError *error);

Convenience function to prompt the user to authenticate to gain an authorization for the given action. First, an attempt to reach an Authentication Agent on the session message bus is made. If that doesn't work and stdout/stdin are both tty's, polkit-auth(1) is invoked.

This is a blocking call. If you're using GTK+ see `polkit_gnome_auth_obtain()` for a non-blocking version.

`action_id` : | The action_id for the PolKitAction to make the user authenticate for
`xid` : | X11 window ID for the window that the dialog will be transient for. If there is no window, pass 0.
`pid` : | Process ID of process to grant authorization to. Normally one wants to pass result of `getpid()`.
`error` : | return location for error; cannot be `NULL`
Returns : | `TRUE` if, and only if, the user successfully authenticated. `FALSE` if the user failed to authenticate or if error is set

Since 0.7

### polkit_dbus_error_generate ()

    polkit_bool_t       polkit_dbus_error_generate          (PolKitAction *action,
                                                             PolKitResult result,
                                                             DBusError *error);

Convenience function to generate a DBusError that encapsulates information that the caller is not authorized. This includes information such as `action` that describes what action the caller lacks an authorization for, as well as `result` that describes if the caller can obtain an authorization through authentication.

Typically a privileged mechanism uses this function to generate errors. At the other end of the wire, the caller can use `polkit_dbus_error_parse()` to extract `action` and `result`.

The form of the DBusError is as follows. The name is set to `org.freedesktop.PolicyKit.Error.NotAuthorized` and the message consists of two strings separated by a single space: the string representation of the action (cf. `polkit_action_to_string_representation()`) and the string representation of the result (cf. `polkit_result_to_string_representation()`).

This function is in `libpolkit-dbus`.

`action` : | the action that the caller needs an authorization for
`result` : | the result from e.g. `polkit_context_is_caller_authorized()`
`error` : | the DBusError to set
Returns : | TRUE if `error` was set. FALSE on error or OOM.

Since 0.8

### polkit_dbus_error_parse ()

    polkit_bool_t       polkit_dbus_error_parse             (DBusError *error,
                                                             PolKitAction **action,
                                                             PolKitResult *result);

Parse an error received over D-Bus, typically generated by `polkit_dbus_error_generate()`, into what action an authorization is missing for and whether that authorization can be obtained.

This function is in `libpolkit-dbus`.

`error` : | error to parse; must be set
`action` : | return location for PolKitAction object
`result` : | return location for PolKitResult variable
Returns : | TRUE only if `error` was successfully parsed and `action` and `result` is set (and caller must free `action` using `polkit_action_unref()`).

Since 0.8

### polkit_dbus_error_parse_from_strings ()

    polkit_bool_t       polkit_dbus_error_parse_from_strings
                                                            (const char *error_name,
                                                             const char *error_message,
                                                             PolKitAction **action,
                                                             PolKitResult *result);

Like `polkit_dbus_error_parse()`, only it takes the name and message instead of a DBusError. This is useful when usings D-Bus bindings (such as dbus-glib) that don't expose the DBusError object directly.

This function is in `libpolkit-dbus`.

`error_name` : | name of D-Bus error
`error_message` : | message of D-Bus error
`action` : | return location for PolKitAction object
`result` : | return location for PolKitResult variable
Returns : | See `polkit_dbus_error_parse()`.

Since 0.8