Add pkttyagent(1) helper

This came up while working on

 https://bugzilla.redhat.com/show_bug.cgi?id=804088

and is useful for example if it's not suitable or appropriate to link
against the polkit libraries.

Signed-off-by: David Zeuthen <davidz@redhat.com>

8 files changed, 182 insertions, 0 deletions

diff --git a/docs/man/Makefile.am b/docs/man/Makefile.am
index 076608b..b71c1d2 100644
--- a/docs/man/Makefile.am
+++ b/docs/man/Makefile.am
@@ -10,6 +10,7 @@ man_MANS = 				\
 	pkexec.1			\
 	pkcheck.1			\
 	pkaction.1			\
+	pkttyagent.1			\
 	$(NULL)
 
 %.8 %.1 : %.xml
@@ -24,6 +25,7 @@ EXTRA_DIST = 				\
 	pkexec.xml			\
 	pkcheck.xml			\
 	pkaction.xml			\
+	pkttyagent.xml			\
 	$(NULL)
 
 clean-local:
diff --git a/docs/man/pkaction.xml b/docs/man/pkaction.xml
index ba91e9a..24c156f 100644
--- a/docs/man/pkaction.xml
+++ b/docs/man/pkaction.xml
@@ -100,6 +100,9 @@
       </citerefentry>,
       <citerefentry>
         <refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>pkttyagent</refentrytitle><manvolnum>1</manvolnum>
       </citerefentry>
     </para>
   </refsect1>
diff --git a/docs/man/pkcheck.xml b/docs/man/pkcheck.xml
index bb5866d..6b8a874 100644
--- a/docs/man/pkcheck.xml
+++ b/docs/man/pkcheck.xml
@@ -213,6 +213,9 @@ KEY3=VALUE3
       </citerefentry>,
       <citerefentry>
         <refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>pkttyagent</refentrytitle><manvolnum>1</manvolnum>
       </citerefentry>
     </para>
   </refsect1>
diff --git a/docs/man/pkexec.xml b/docs/man/pkexec.xml
index 8196511..1734033 100644
--- a/docs/man/pkexec.xml
+++ b/docs/man/pkexec.xml
@@ -283,6 +283,9 @@
       </citerefentry>,
       <citerefentry>
         <refentrytitle>pkcheck</refentrytitle><manvolnum>1</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>pkttyagent</refentrytitle><manvolnum>1</manvolnum>
       </citerefentry>
     </para>
   </refsect1>
diff --git a/docs/man/pkttyagent.xml b/docs/man/pkttyagent.xml
new file mode 100644
index 0000000..f0f328e
--- /dev/null
+++ b/docs/man/pkttyagent.xml
@@ -0,0 +1,154 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY version SYSTEM "../version.xml">
+]>
+<refentry id="pkttyagent.1" xmlns:xi="http://www.w3.org/2003/XInclude">
+  <refentryinfo>
+    <title>pkttyagent</title>
+    <date>May 2009</date>
+    <productname>polkit</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>pkttyagent</refentrytitle>
+    <manvolnum>1</manvolnum>
+    <refmiscinfo class="version"></refmiscinfo>
+  </refmeta>
+
+  <refnamediv>
+    <refname>pkttyagent</refname>
+    <refpurpose>Textual authentication helper</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>pkttyagent</command>
+      <arg><option>--version</option></arg>
+      <arg><option>--help</option></arg>
+    </cmdsynopsis>
+
+    <cmdsynopsis>
+      <command>pkttyagent</command>
+
+      <group>
+        <arg choice="plain">
+          <option>--process</option>
+          <group choice="req">
+            <arg choice="plain">
+              <replaceable>pid</replaceable>
+            </arg>
+            <arg choice="plain">
+              <replaceable>pid,pid-start-time</replaceable>
+            </arg>
+          </group>
+        </arg>
+        <arg choice="plain">
+          <option>--system-bus-name</option>
+          <replaceable>busname</replaceable>
+        </arg>
+      </group>
+
+      <group>
+        <arg choice="plain">
+          <option>--notify-fd</option>
+          <replaceable>fd</replaceable>
+        </arg>
+      </group>
+
+    </cmdsynopsis>
+
+  </refsynopsisdiv>
+
+  <refsect1 id="pkttyagent-descsription">
+    <title>DESCRIPTION</title>
+    <para>
+      <command>pkttyagent</command> is used to start a textual
+      authentication agent for the subject specified by either
+      <option>--process</option> or
+      <option>--system-bus-name</option>. If neither of these options
+      are given, the parent process is used.
+    </para>
+    <para>
+      To get notified when the authentication agent has been
+      registered either listen to the <link
+      linkend="eggdbus-signal-org.freedesktop.PolicyKit1.Authority::Changed">Changed</link>
+      D-Bus signal or use <option>--notify-fd</option> to pass the
+      number of a file descriptor that has been passed to the
+      program. This file descriptor will then be closed when the
+      authentication agent has been successfully registered.
+    </para>
+  </refsect1>
+
+  <refsect1 id="pkttyagent-return-value">
+    <title>RETURN VALUE</title>
+    <para>
+      If the authentication agent could not be registered,
+      <command>pkttyagent</command> exits with an exit code of
+      127. Diagnostic messages are printed on standard error.
+    </para>
+    <para>
+      If one or more of the options passed are malformed,
+      <command>pkttyagent</command> exits with an exit code of 126. If
+      stdin is a tty, then this manual page is also shown.
+    </para>
+    <para>
+      If the authentication agent was successfully registered,
+      <command>pkttyagent</command> will keep running, interacting
+      with the user as needed. When its services are no longer needed,
+      the process can be killed.
+    </para>
+  </refsect1>
+
+  <refsect1 id="pkttyagent-notes">
+    <title>NOTES</title>
+    <para>
+      Since process identifiers can be recycled, the caller should
+      always use <replaceable>pid,pid-start-time</replaceable> when
+      using the <option>--process</option> option.  The value of
+      <replaceable>pid-start-time</replaceable> can be determined by
+      consulting e.g. the
+      <citerefentry>
+        <refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum>
+      </citerefentry>
+      file system depending on the operating system. If only <replaceable>pid</replaceable>
+      is passed to the <option>--process</option> option, then <command>pkttyagent</command>
+      will look up the start time itself but note that this may be racy.
+    </para>
+  </refsect1>
+
+  <refsect1 id="pkttyagent-author"><title>AUTHOR</title>
+    <para>
+      Written by David Zeuthen <email>davidz@redhat.com</email> with
+      a lot of help from many others.
+    </para>
+  </refsect1>
+
+  <refsect1 id="pkttyagent-bugs">
+    <title>BUGS</title>
+    <para>
+      Please send bug reports to either the distribution or the
+      polkit-devel mailing list,
+      see the link <ulink url="http://lists.freedesktop.org/mailman/listinfo/polkit-devel"/>
+      on how to subscribe.
+    </para>
+  </refsect1>
+
+  <refsect1 id="pkttyagent-see-also">
+    <title>SEE ALSO</title>
+    <para>
+      <citerefentry>
+        <refentrytitle>polkit</refentrytitle><manvolnum>8</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>pkaction</refentrytitle><manvolnum>1</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>pkcheck</refentrytitle><manvolnum>1</manvolnum>
+      </citerefentry>,
+      <citerefentry>
+        <refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum>
+      </citerefentry>
+    </para>
+  </refsect1>
+</refentry>
diff --git a/docs/man/polkit.xml b/docs/man/polkit.xml
index ae67f7c..188c514 100644
--- a/docs/man/polkit.xml
+++ b/docs/man/polkit.xml
@@ -223,6 +223,18 @@ System Context         |                        |
       implemention for systems without a <literal>root</literal>
       account.
     </para>
+
+    <para>
+      Applications that do not run under a desktop environment (for
+      example, if launched from a
+      <citerefentry><refentrytitle>ssh</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+      login) may not have have an authentication agent associated with
+      them. Such applications may use the <link
+      linkend="PolkitAgentTextListener-struct">PolkitAgentTextListener</link>
+      type or the
+      <citerefentry><refentrytitle>pkttyagent</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+      helper so the user can authenticate using a textual interface.
+    </para>
   </refsect1>
 
   <refsect1 id="polkit-declaring-actions"><title>DECLARING ACTIONS</title>
@@ -469,6 +481,9 @@ System Context         |                        |
       <citerefentry>
         <refentrytitle>pkexec</refentrytitle><manvolnum>1</manvolnum>
       </citerefentry>,
+      <citerefentry>
+        <refentrytitle>pkttyagent</refentrytitle><manvolnum>1</manvolnum>
+      </citerefentry>
     </para>
   </refsect1>
 </refentry>
diff --git a/docs/polkit/Makefile.am b/docs/polkit/Makefile.am
index 370fb56..fd7123f 100644
--- a/docs/polkit/Makefile.am
+++ b/docs/polkit/Makefile.am
@@ -65,6 +65,7 @@ content_files =  			    								\
 	../man/pkcheck.xml										\
 	../man/pkaction.xml										\
 	../man/pkexec.xml										\
+	../man/pkttyagent.xml										\
 	$(NULL)
 
 # Images to copy into HTML directory
diff --git a/docs/polkit/polkit-1-docs.xml b/docs/polkit/polkit-1-docs.xml
index 38a69a4..4fc8a99 100644
--- a/docs/polkit/polkit-1-docs.xml
+++ b/docs/polkit/polkit-1-docs.xml
@@ -112,6 +112,7 @@
     <xi:include href="../man/pkaction.xml"/>
     <xi:include href="../man/pkexec.xml"/>
     <xi:include href="../man/pklocalauthority.xml"/>
+    <xi:include href="../man/pkttyagent.xml"/>
   </part>
 
   <chapter id="polkit-hierarchy">