Description

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

polkit_auth_obtain ()

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 ()

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()).

polkit_dbus_error_parse_from_strings ()

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.