Debian Codegraph @

docs/man/pkttyagent.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="pkttyagent.1" xmlns:xi="http://www.w3.org/2003/XInclude">
7 <refentryinfo>
8 <title>pkttyagent</title>
9 <date>May 2009</date>
10 <productname>polkit</productname>
11 </refentryinfo>
12
13 <refmeta>
14 <refentrytitle>pkttyagent</refentrytitle>
15 <manvolnum>1</manvolnum>
16 <refmiscinfo class="version"></refmiscinfo>
17 </refmeta>
18
19 <refnamediv>
20 <refname>pkttyagent</refname>
21 <refpurpose>Textual authentication helper</refpurpose>
22 </refnamediv>
23
24 <refsynopsisdiv>
25 <cmdsynopsis>
26 <command>pkttyagent</command>
27 <arg><option>--version</option></arg>
28 <arg><option>--help</option></arg>
29 </cmdsynopsis>
30
31 <cmdsynopsis>
32 <command>pkttyagent</command>
33
34 <group>
35 <arg choice="plain">
36 <option>--process</option>
37 <group choice="req">
38 <arg choice="plain">
39 <replaceable>pid</replaceable>
40 </arg>
41 <arg choice="plain">
42 <replaceable>pid,pid-start-time</replaceable>
43 </arg>
44 </group>
45 </arg>
46 <arg choice="plain">
47 <option>--system-bus-name</option>
48 <replaceable>busname</replaceable>
49 </arg>
50 </group>
51
52 <group>
53 <arg choice="plain">
54 <option>--notify-fd</option>
55 <replaceable>fd</replaceable>
56 </arg>
57 </group>
58
59 <group>
60 <arg choice="plain">
61 <option>--fallback</option>
62 </arg>
63 </group>
64
65 </cmdsynopsis>
66
67 </refsynopsisdiv>
68
69 <refsect1 id="pkttyagent-descsription">
70 <title>DESCRIPTION</title>
71 <para>
72 <command>pkttyagent</command> is used to start a textual
73 authentication agent for the subject specified by either
74 <option>--process</option> or
75 <option>--system-bus-name</option>. If neither of these options
76 are given, the parent process is used.
77 </para>
78 <para>
79 To get notified when the authentication agent has been
80 registered either listen to the <link
81 linkend="eggdbus-signal-org.freedesktop.PolicyKit1.Authority::Changed">Changed</link>
82 D-Bus signal or use <option>--notify-fd</option> to pass the
83 number of a file descriptor that has been passed to the
84 program. This file descriptor will then be closed when the
85 authentication agent has been successfully registered.
86 </para>
87 <para>
88 If <option>--fallback</option> is used, the textual
89 authentication agent will not replace an existing authentication
90 agent.
91 </para>
92 </refsect1>
93
94 <refsect1 id="pkttyagent-return-value">
95 <title>RETURN VALUE</title>
96 <para>
97 If the authentication agent could not be registered,
98 <command>pkttyagent</command> exits with an exit code of
99 127. Diagnostic messages are printed on standard error.
100 </para>
101 <para>
102 If one or more of the options passed are malformed,
103 <command>pkttyagent</command> exits with an exit code of 126. If
104 stdin is a tty, then this manual page is also shown.
105 </para>
106 <para>
107 If the authentication agent was successfully registered,
108 <command>pkttyagent</command> will keep running, interacting
109 with the user as needed. When its services are no longer needed,
110 the process can be killed.
111 </para>
112 </refsect1>
113
114 <refsect1 id="pkttyagent-notes">
115 <title>NOTES</title>
116 <para>
117 Since process identifiers can be recycled, the caller should
118 always use <replaceable>pid,pid-start-time</replaceable> when
119 using the <option>--process</option> option. The value of
120 <replaceable>pid-start-time</replaceable> can be determined by
121 consulting e.g. the
122 <citerefentry><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>
123 file system depending on the operating system. If only <replaceable>pid</replaceable>
124 is passed to the <option>--process</option> option, then <command>pkttyagent</command>
125 will look up the start time itself but note that this may be racy.
126 </para>
127 </refsect1>
128
129 <refsect1 id="pkttyagent-author"><title>AUTHOR</title>
130 <para>
131 Written by David Zeuthen <email>[email protected]</email> with
132 a lot of help from many others.
133 </para>
134 </refsect1>
135
136 <refsect1 id="pkttyagent-bugs">
137 <title>BUGS</title>
138 <para>
139 Please send bug reports to either the distribution or the
140 polkit-devel mailing list,
141 see <ulink url="https://github.com/polkit-org/polkit#bugs-and-development"/>.
142 </para>
143 </refsect1>
144
145 <refsect1 id="pkttyagent-see-also">
146 <title>SEE ALSO</title>
147 <para>
148 <link linkend="polkit.8"><citerefentry><refentrytitle>polkit</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>,
149 <link linkend="polkitd.8"><citerefentry><refentrytitle>polkitd</refentrytitle><manvolnum>8</manvolnum></citerefentry></link>,
150 <link linkend="pkaction.1"><citerefentry><refentrytitle>pkaction</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>,
151 <link linkend="pkcheck.1"><citerefentry><refentrytitle>pkcheck</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>,
152 <link linkend="pkexec.1"><citerefentry><refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum></citerefentry></link>
153 </para>
154 </refsect1>
155 </refentry>