Core API Reference - Simple Convenience Interface

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:

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.

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.

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.

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.

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.

Since 0.8