Core API Reference - Simple Convenience Interface
Desktop Apps Training - Policy Kit

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