'\" t
.\"     Title: pkcheck
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <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\ } | \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
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
Since process identifiers can be recycled, the caller should always use
\fIpid,pid\-start\-time\fR
to specify the process to check for authorization when using the
\fB\-\-process\fR
option\&. The value of
\fIpid\-start\-time\fR
can be determined by consulting e\&.g\&. the
\fBproc\fR(5)
file system depending on the operating system\&. If only
\fIpid\fR
is passed to the
\fB\-\-process\fR
option, then
\fBpkcheck\fR
will look up the start time itself but note that this may be racy\&.
.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)