cherry pick 39a07ec8f2c612a5af234c7713571362f7ca90b4

[apt.git] / doc / apt-config.8.xml

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [

<!ENTITY % aptent SYSTEM "apt.ent">
%aptent;

<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent">
%aptverbatiment;

]>

<refentry>

 <refentryinfo>
   &apt-author.jgunthorpe;
   &apt-author.team;
   &apt-email;
   &apt-product;
   <!-- The last update date -->
   <date>2012-06-09T00:00:00Z</date>
 </refentryinfo>
 
 <refmeta>
   <refentrytitle>apt-config</refentrytitle>
   <manvolnum>8</manvolnum>
   <refmiscinfo class="manual">APT</refmiscinfo>
 </refmeta>
 
 <!-- Man page title -->
 <refnamediv>
    <refname>apt-config</refname>
    <refpurpose>APT Configuration Query program</refpurpose>
 </refnamediv>

 &synopsis-command-apt-config;

 <refsect1><title>Description</title>
   <para><command>apt-config</command> is an internal program used by various
   portions of the APT suite to provide consistent configurability. It accesses
   the main configuration file <filename>/etc/apt/apt.conf</filename> in a
   manner that is easy to use for scripted applications.</para>

   <para>Unless the <option>-h</option>, or <option>--help</option> option is
   given, one of the commands below must be present.
   </para>
   
   <variablelist>
     <varlistentry><term><option>shell</option></term>
     <listitem><para>
     shell is used to access the configuration information from a shell
     script. It is given pairs of arguments, the first being a shell
     variable and the second the configuration value to query. As output
     it lists shell assignment commands for each value present.
     In a shell script it should be used as follows:
     </para>
     
<informalexample><programlisting>
OPTS="-f"
RES=`apt-config shell OPTS MyApp::options`
eval $RES
</programlisting></informalexample>

     <para>This will set the shell environment variable $OPTS to the value of
     MyApp::options with a default of <option>-f</option>.</para>

     
     <para>The configuration item may be postfixed with a /[fdbi]. f returns
     file names, d returns directories, b returns true or false and i returns
     an integer. Each of the returns is normalized and verified
     internally.</para>
     </listitem>
     </varlistentry>

     <varlistentry><term><option>dump</option></term>
     <listitem><para>
     Just show the contents of the configuration space.</para>
     </listitem>
     </varlistentry>

   </variablelist>
 </refsect1>

 <refsect1><title>options</title>
   &apt-cmdblurb;
   
   <variablelist>
     <varlistentry>
      <term><option>--empty</option></term>
      <listitem><para>Include options which have an empty value. This is the default, so
		      use --no-empty to remove them from the output.</para></listitem>
     </varlistentry>

     <varlistentry>
      <term><option>--format '<replaceable>&percnt;f &#x0022;&percnt;v&#x0022;;&percnt;n</replaceable>'</option></term>
      <listitem><para>Defines the output of each config option. &percnt;t will be replaced with its individual name,
		      &percnt;f with its full hierarchical name and &percnt;v with its value.
		      Use uppercase letters and special characters in the value will be encoded to ensure that
		      it can e.g. be safely used in a quoted-string as defined by RFC822. Additionally
		      &percnt;n will be replaced by a newline, and &percnt;N by a tab. A &percnt; can be
		      printed by using &percnt;&percnt;.</para></listitem>
     </varlistentry>

     &apt-commonoptions;
     
   </variablelist>
 </refsect1>

 <refsect1><title>See Also</title>
   <para>&apt-conf;
   </para>
 </refsect1>

 <refsect1><title>Diagnostics</title>
   <para><command>apt-config</command> returns zero on normal operation, decimal 100 on error.
   </para>
 </refsect1>

 &manbugs;
 
</refentry>