scripts/desc/xdg-su.xml

<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl"
   href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
]>
<refentry id="xdg-su">
  <refentryinfo>
    <title>xdg-su Manual</title>
    <copyright>
      <year>2006</year>
    </copyright>
    <author>
      <firstname>Kevin</firstname>
      <surname>Krammer</surname>
    </author>
    <address><email>kevin.krammer@gmx.at</email></address>
    <author>
      <firstname>Jeremy</firstname>
      <surname>White</surname>
    </author>
    <address><email>jwhite@codeweavers.com</email></address>
    <releaseinfo>This is release 0.5 of the xdg-su Manual.</releaseinfo>
  </refentryinfo>

  <refmeta>
    <refentrytitle>xdg-su</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>xdg-su</refname>
    <refpurpose>run a GUI program as root after prompting for the root password</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>xdg-su</command>
      <arg><option>-u <replaceable>user</replaceable></option></arg>
      <arg choice="plain"><option>-c <replaceable>command</replaceable></option></arg>
    </cmdsynopsis>
    <cmdsynopsis>
      <command>xdg-su</command>
      <group choice="req">
        <arg choice="plain"><option>--help</option></arg>
        <arg choice="plain"><option>--manual</option></arg>
        <arg choice="plain"><option>--version</option></arg>
      </group>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1 id="description">
    <title>Description</title>
    <para>
      xdg-su provides a graphical dialog that prompts the user for a password
      to run <replaceable>command</replaceable> as <replaceable>user</replaceable>
      or as root if no user was specified.
    </para>
    <para>
      xdg-su is for use inside a desktop session only.
    </para>
    <para>
      xdg-su discards any stdout and stderr output from
      <replaceable>command</replaceable>.
    </para>
  </refsect1>
  <refsect1 id="options">
    <title>Options</title>
    <variablelist>
      <varlistentry>
	<term><option>-u <replaceable>user</replaceable></option></term>
	<listitem>
	  <simpara>
	    run <replaceable>command</replaceable> as
            <replaceable>user</replaceable>. The default is to run as root.
	  </simpara>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>--help</option></term>
	<listitem>
	  <simpara>
	    Show command synopsis.
	  </simpara>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><option>--manual</option></term>
	<listitem>
	  <simpara>
	    Show this manualpage.
	  </simpara>
	</listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--version</option></term>
        <listitem>
          <simpara>
            Show the xdg-utils version information.
          </simpara>
        </listitem>
      </varlistentry>

    </variablelist>
  </refsect1>
  <refsect1 id="exitcodes">
    <title>Exit Codes</title>
    <para>
      An exit code of 0 indicates success while a non-zero exit code
      indicates failure. The following failure codes can be returned:
    </para>
    <variablelist>
      <varlistentry>
	<term><option>1</option></term>
	<listitem>
	  <simpara>
	    Error in command line syntax.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>2</option></term>
	<listitem>
	  <simpara>
	    One of the files passed on the command line did not exist.
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>3</option></term>
	<listitem>
	  <simpara>
	    A required tool could not be found. 
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>4</option></term>
	<listitem>
	  <simpara>
	    The action failed. 
	  </simpara>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1 id="seealso">
    <title>See Also</title>
    <para><citerefentry><refentrytitle>su</refentrytitle>
        <manvolnum>1</manvolnum>
      </citerefentry>
    </para>
  </refsect1>
  <refsect1 id="examples">
    <title>Examples</title>
    <para>
<programlisting>
xdg-su -u root -c "/opt/shinythings/bin/install-GUI --install fast"
</programlisting>
       Runs the /opt/shinythings/bin/install-GUI command with root permissions.
    </para>
  </refsect1>
</refentry>