Debian Codegraph @

docs/man/pkcheck.xml

raw
1 <?xml version="1.0"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
4 <!ENTITY version SYSTEM "../version.xml">
5 ]>
6 <refentry id="pkcheck.1" xmlns:xi="http://www.w3.org/2003/XInclude">
7 <refentryinfo>
8 <title>pkcheck</title>
9 <date>May 2009</date>
10 <productname>polkit</productname>
11 </refentryinfo>
12
13 <refmeta>
14 <refentrytitle>pkcheck</refentrytitle>
15 <manvolnum>1</manvolnum>
16 <refmiscinfo class="version"></refmiscinfo>
17 </refmeta>
18
19 <refnamediv>
20 <refname>pkcheck</refname>
21 <refpurpose>Check whether a process is authorized</refpurpose>
22 </refnamediv>
23
24 <refsynopsisdiv>
25 <cmdsynopsis>
26 <command>pkcheck</command>
27 <arg><option>--version</option></arg>
28 <arg><option>--help|-h</option></arg>
29 </cmdsynopsis>
30
31 <cmdsynopsis>
32 <command>pkcheck</command>
33 <arg><option>--list-temp</option></arg>
34 </cmdsynopsis>
35
36 <cmdsynopsis>
37 <command>pkcheck</command>
38 <arg><option>--revoke-temp</option></arg>
39 </cmdsynopsis>
40
41 <cmdsynopsis>
42 <command>pkcheck</command>
43 <arg choice="plain">
44 <option>--action-id|-a</option>
45 <replaceable>action</replaceable>
46 </arg>
47
48 <group choice="req">
49 <arg choice="plain">
50 <option>--process|-p</option>
51 <group choice="req">
52 <arg choice="plain">
53 <replaceable>pid</replaceable>
54 </arg>
55 <arg choice="plain">
56 <replaceable>pid,pid-start-time</replaceable>
57 </arg>
58 <arg choice="plain">
59 <replaceable>pid,pid-start-time,uid</replaceable>
60 </arg>
61 </group>
62 </arg>
63 <arg choice="plain">
64 <option>--system-bus-name|-s</option>
65 <replaceable>busname</replaceable>
66 </arg>
67 </group>
68
69 <group>
70 <arg choice="plain">
71 <option>--allow-user-interaction|-u</option>
72 </arg>
73 </group>
74
75 <group>
76 <arg choice="plain">
77 <option>--enable-internal-agent</option>
78 </arg>
79 </group>
80
81 <group rep="repeat">
82 <arg choice="plain">
83 <option>--detail|-d</option>
84 <replaceable>key</replaceable>
85 <replaceable>value</replaceable>
86 </arg>
87 </group>
88 </cmdsynopsis>
89
90 </refsynopsisdiv>
91
92 <refsect1 id="pkcheck-descsription">
93 <title>DESCRIPTION</title>
94 <para>
95 <command>pkcheck</command> is used to check whether a process, specified by
96 either <option>--process</option> (see below) or <option>--system-bus-name</option>,
97 is authorized for <replaceable>action</replaceable>. The <option>--detail</option>
98 option can be used zero or more times to pass details about <replaceable>action</replaceable>.
99 If <option>--allow-user-interaction</option> is passed, <command>pkcheck</command> blocks
100 while waiting for authentication.
101 </para>
102 <para>
103 The invocation <command>pkcheck --list-temp</command> will list
104 all temporary authorizations for the current session and
105 <command>pkcheck --revoke-temp</command> will revoke all
106 temporary authorizations for the current session.
107 </para>
108 <para>
109 This command is a simple wrapper around the polkit D-Bus interface; see the
110 D-Bus interface documentation for details.
111 </para>
112 </refsect1>
113
114 <refsect1 id="pkcheck-return-value">
115 <title>RETURN VALUE</title>
116 <para>
117 If the specified process is
118 authorized, <command>pkcheck</command> exits with a return value
119 of 0. If the authorization result contains any details, these
120 are printed on standard output as key/value pairs using
121 environment style reporting, e.g. first the key followed by a an equal sign, then the
122 value followed by a newline.
123 <programlisting>
124 KEY1=VALUE1
125 KEY2=VALUE2
126 KEY3=VALUE3
127 ...</programlisting>
128 Octets that are not in [a-zA-Z0-9_] are escaped using octal codes prefixed
129 with <emphasis>\</emphasis>.
130 For example, the UTF-8 string <emphasis>føl,你好</emphasis> will be printed
131 as <emphasis>f\303\270l\54\344\275\240\345\245\275</emphasis>.
132 </para>
133 <para>
134 If the specified process is not
135 authorized, <command>pkcheck</command> exits with a return value
136 of 1 and a diagnostic message is printed on standard error. Details
137 are printed on standard output.
138 </para>
139 <para>
140 If the specified process is not
141 authorized because no suitable authentication agent is available or if the
142 <option>--allow-user-interaction</option> wasn't passed, <command>pkcheck</command>
143 exits with a return value of 2 and a diagnostic message is printed on standard error.
144 Details are printed on standard output.
145 </para>
146 <para>
147 If the specified process is not authorized because the
148 authentication dialog / request was dismissed by the user,
149 <command>pkcheck</command> exits with a return value of 3 and a
150 diagnostic message is printed on standard error. Details are
151 printed on standard output.
152 </para>
153 <para>
154 If an error occurred while checking for authorization, <command>pkcheck</command> exits
155 with a return value of 127 with a diagnostic message printed on standard error.
156 </para>
157 <para>
158 If one or more of the options passed are malformed, <command>pkcheck</command> exits
159 with a return value of 126. If stdin is a tty, then this manual page is also shown.
160 </para>
161 </refsect1>
162
163 <refsect1 id="pkcheck-notes">
164 <title>NOTES</title>
165 <para>
166 Do not use either the bare <replaceable>pid</replaceable> or
167 <replaceable>pid,start-time</replaceable> syntax forms for
168 <option>--process</option>. There are race conditions in both.
169 New code should always use
170 <replaceable>pid,pid-start-time,uid</replaceable>. The value of
171 <replaceable>start-time</replaceable> can be determined by
172 consulting e.g. the
173 <citerefentry><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>
174 file system depending on the operating system. If fewer than 3
175 arguments are passed, <command>pkcheck</command> will attempt to
176 look up them up internally, but note that this may be racy.
177 </para>
178 <para>
179 If your program is a daemon with e.g. a custom Unix domain
180 socket, you should determine the <replaceable>uid</replaceable>
181 parameter via operating system mechanisms such as
182 <literal>PEERCRED</literal>.
183 </para>
184 </refsect1>
185
186 <refsect1 id="pkcheck-auth-agent"><title>AUTHENTICATION AGENT</title>
187 <para>
188 <command>pkcheck</command>, like any other polkit
189 application, will use the authentication agent registered for
190 the process in question. However, if no authentication agent is
191 available, then <command>pkcheck</command> can register its own
192 textual authentication agent if the option
193 <option>--enable-internal-agent</option> is passed.
194 </para>
195 </refsect1>
196
197 <refsect1 id="pkcheck-author"><title>AUTHOR</title>
198 <para>
199 Written by David Zeuthen <email>[email protected]</email> with
200 a lot of help from many others.
201 </para>
202 </refsect1>
203
204 <refsect1 id="pkcheck-bugs">
205 <title>BUGS</title>
206 <para>
207 Please send bug reports to either the distribution or the
208 polkit-devel mailing list,
209 see <ulink url="https://github.com/polkit-org/polkit#bugs-and-development"/>.
210 </para>
211 </refsect1>
212
213 <refsect1 id="pkcheck-see-also">
214 <title>SEE ALSO</title>
215 <para>
216 <link linkend="polkit.8"><citerefentry><refentrytitle>polkit</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>,
217 <link linkend="polkitd.8"><citerefentry><refentrytitle>polkitd</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>,
218 <link linkend="pkaction.1"><citerefentry><refentrytitle>pkaction</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>,
219 <link linkend="pkexec.1"><citerefentry><refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>,
220 <link linkend="pkttyagent.1"><citerefentry><refentrytitle>pkttyagent</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>
221 </para>
222 </refsect1>
223 </refentry>