'\" t
.\"     Title: pkcheck
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: May 2009
.\"    Manual: pkcheck
.\"    Source: polkit
.\"  Language: English
.\"
.TH "PKCHECK" "1" "May 2009" "polkit" "pkcheck"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
pkcheck \- Check whether a process is authorized
.SH "SYNOPSIS"
.HP \w'\fBpkcheck\fR\ 'u
\fBpkcheck\fR [\fB\-\-version\fR] [\fB\-\-help\fR]
.HP \w'\fBpkcheck\fR\ 'u
\fBpkcheck\fR [\fB\-\-list\-temp\fR]
.HP \w'\fBpkcheck\fR\ 'u
\fBpkcheck\fR [\fB\-\-revoke\-temp\fR]
.HP \w'\fBpkcheck\fR\ 'u
\fBpkcheck\fR \fB\-\-action\-id\fR\ \fIaction\fR {\fB\-\-process\fR\ {\ \fIpid\fR\ |\ \fIpid,pid\-start\-time\fR\ |\ \fIpid,pid\-start\-time,uid\fR\ } | \fB\-\-system\-bus\-name\fR\ \fIbusname\fR} [\fB\-\-allow\-user\-interaction\fR] [\fB\-\-enable\-internal\-agent\fR] [\fB\-\-detail\fR\ \fIkey\fR\ \fIvalue\fR...]
.SH "DESCRIPTION"
.PP
\fBpkcheck\fR
is used to check whether a process, specified by either
\fB\-\-process\fR
(see below) or
\fB\-\-system\-bus\-name\fR, is authorized for
\fIaction\fR\&. The
\fB\-\-detail\fR
option can be used zero or more times to pass details about
\fIaction\fR\&. If
\fB\-\-allow\-user\-interaction\fR
is passed,
\fBpkcheck\fR
blocks while waiting for authentication\&.
.PP
The invocation
\fBpkcheck \-\-list\-temp\fR
will list all temporary authorizations for the current session and
\fBpkcheck \-\-revoke\-temp\fR
will revoke all temporary authorizations for the current session\&.
.PP
This command is a simple wrapper around the PolicyKit D\-Bus interface; see the D\-Bus interface documentation for details\&.
.SH "RETURN VALUE"
.PP
If the specified process is authorized,
\fBpkcheck\fR
exits with a return value of 0\&. If the authorization result contains any details, these are printed on standard output as key/value pairs using environment style reporting, e\&.g\&. first the key followed by a an equal sign, then the value followed by a newline\&.
.sp
.if n \{\
.RS 4
.\}
.nf
KEY1=VALUE1
KEY2=VALUE2
KEY3=VALUE3
\&.\&.\&.
.fi
.if n \{\
.RE
.\}
.sp
Octects that are not in [a\-zA\-Z0\-9_] are escaped using octal codes prefixed with
\fI\e\fR\&. For example, the UTF\-8 string
\fIføl,你好\fR
will be printed as
\fIf\e303\e270l\e54\e344\e275\e240\e345\e245\e275\fR\&.
.PP
If the specificied process is not authorized,
\fBpkcheck\fR
exits with a return value of 1 and a diagnostic message is printed on standard error\&. Details are printed on standard output\&.
.PP
If the specificied process is not authorized because no suitable authentication agent is available or if the
\fB\-\-allow\-user\-interaction\fR
wasn\*(Aqt passed,
\fBpkcheck\fR
exits with a return value of 2 and a diagnostic message is printed on standard error\&. Details are printed on standard output\&.
.PP
If the specificied process is not authorized because the authentication dialog / request was dismissed by the user,
\fBpkcheck\fR
exits with a return value of 3 and a diagnostic message is printed on standard error\&. Details are printed on standard output\&.
.PP
If an error occured while checking for authorization,
\fBpkcheck\fR
exits with a return value of 127 with a diagnostic message printed on standard error\&.
.PP
If one or more of the options passed are malformed,
\fBpkcheck\fR
exits with a return value of 126\&. If stdin is a tty, then this manual page is also shown\&.
.SH "NOTES"
.PP
Do not use either the bare
\fIpid\fR
or
\fIpid,start\-time\fR
syntax forms for
\fB\-\-process\fR\&. There are race conditions in both\&. New code should always use
\fIpid,pid\-start\-time,uid\fR\&. The value of
\fIstart\-time\fR
can be determined by consulting e\&.g\&. the
\fBproc\fR(5)
file system depending on the operating system\&. If fewer than 3 arguments are passed,
\fBpkcheck\fR
will attempt to look up them up internally, but note that this may be racy\&.
.PP
If your program is a daemon with e\&.g\&. a custom Unix domain socket, you should determine the
\fIuid\fR
parameter via operating system mechanisms such as
PEERCRED\&.
.SH "AUTHENTICATION AGENT"
.PP
\fBpkcheck\fR, like any other PolicyKit application, will use the authentication agent registered for the process in question\&. However, if no authentication agent is available, then
\fBpkcheck\fR
can register its own textual authentication agent if the option
\fB\-\-enable\-internal\-agent\fR
is passed\&.
.SH "AUTHOR"
.PP
Written by David Zeuthen
<davidz@redhat\&.com>
with a lot of help from many others\&.
.SH "BUGS"
.PP
Please send bug reports to either the distribution or the polkit\-devel mailing list, see the link
\m[blue]\fB\%http://lists.freedesktop.org/mailman/listinfo/polkit-devel\fR\m[]
on how to subscribe\&.
.SH "SEE ALSO"
.PP
\fBpolkit\fR(8),
\fBpkaction\fR(1),
\fBpkexec\fR(1),
\fBpkttyagent\fR(1)