docs/dconf-tool.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <refentry id="dconf-tool">
   6   <refentryinfo>
   7     <title>dconf</title>
   8     <productname>dconf</productname>
   9
  10     <authorgroup>
  11       <author>
  12         <contrib>Developer</contrib>
  13         <firstname>Ryan</firstname>
  14         <surname>Lortie</surname>
  15         <email>desrt@desrt.ca</email>
  16       </author>
  17     </authorgroup>
  18
  19   </refentryinfo>
  20
  21   <refmeta>
  22     <refentrytitle>dconf</refentrytitle>
  23     <manvolnum>1</manvolnum>
  24     <refmiscinfo class="manual">User Commands</refmiscinfo>
  25   </refmeta>
  26
  27   <refnamediv>
  28     <refname>dconf</refname>
  29     <refpurpose>Simple tool for manipulating a dconf database</refpurpose>
  30   </refnamediv>
  31
  32   <refsynopsisdiv>
  33     <cmdsynopsis>
  34       <command>dconf</command>
  35       <arg choice="plain">read</arg>
  36       <arg choice="plain"><replaceable>KEY</replaceable></arg>
  37     </cmdsynopsis>
  38     <cmdsynopsis>
  39       <command>dconf</command>
  40       <arg choice="plain">list</arg>
  41       <arg choice="plain"><replaceable>DIR</replaceable></arg>
  42     </cmdsynopsis>
  43     <cmdsynopsis>
  44       <command>dconf</command>
  45       <arg choice="plain">write</arg>
  46       <arg choice="plain"><replaceable>KEY</replaceable></arg>
  47       <arg choice="plain"><replaceable>VALUE</replaceable></arg>
  48     </cmdsynopsis>
  49     <cmdsynopsis>
  50       <command>dconf</command>
  51       <arg choice="plain">reset</arg>
  52       <arg choice="opt">-f</arg>
  53       <arg choice="plain"><replaceable>PATH</replaceable></arg>
  54     </cmdsynopsis>
  55     <cmdsynopsis>
  56       <command>dconf</command>
  57       <arg choice="plain">compile</arg>
  58       <arg choice="plain"><replaceable>OUTPUT</replaceable></arg>
  59       <arg choice="plain"><replaceable>KEYFILEDIR</replaceable></arg>
  60     </cmdsynopsis>
  61     <cmdsynopsis>
  62       <command>dconf</command>
  63       <arg choice="plain">update</arg>
  64     </cmdsynopsis>
  65     <cmdsynopsis>
  66       <command>dconf</command>
  67       <arg choice="plain">watch</arg>
  68       <arg choice="plain"><replaceable>PATH</replaceable></arg>
  69     </cmdsynopsis>
  70     <cmdsynopsis>
  71       <command>dconf</command>
  72       <arg choice="plain">dump</arg>
  73       <arg choice="plain"><replaceable>DIR</replaceable></arg>
  74     </cmdsynopsis>
  75     <cmdsynopsis>
  76       <command>dconf</command>
  77       <arg choice="plain">load</arg>
  78       <arg choice="plain"><replaceable>DIR</replaceable></arg>
  79     </cmdsynopsis>
  80     <cmdsynopsis>
  81       <command>dconf</command>
  82       <arg choice="plain">help</arg>
  83       <arg choice="opt"><replaceable>COMMAND</replaceable></arg>
  84     </cmdsynopsis>
  85   </refsynopsisdiv>
  86
  87   <refsect1>
  88     <title>Description</title>
  89
  90     <para>
  91       The <command>dconf</command> program can perform various operations on a dconf database, such as reading
  92       or writing individual values or entire directories. This tool operates on dconf directly, without using
  93       gsettings schema information. Therefore, it cannot perform type and consistency checks on values.  The
  94       <citerefentry><refentrytitle>gsettings</refentrytitle><manvolnum>1</manvolnum></citerefentry> utility is
  95       an alternative if such checks are needed.
  96     </para>
  97
  98     <para>
  99       The <replaceable>DIR</replaceable> arguments must be directory paths (starting and ending with '/'), the
 100       <replaceable>KEY</replaceable> arguments must be key paths (starting, but not ending with '/') and the
 101       <replaceable>PATH</replaceable> arguments can be either directory or key paths.
 102     </para>
 103
 104     <para>
 105       The <replaceable>OUTPUT</replaceable> argument must the location to write a (binary) dconf database to and the
 106       <replaceable>KEYFILEDIR</replaceable> argument must be a .d directory containing keyfiles.
 107     </para>
 108
 109     <para>
 110       <replaceable>VALUE</replaceable> arguments must be in GVariant format, so e.g. a string must include
 111       explicit quotes: "'foo'". This format is also used when printing out values.
 112     </para>
 113
 114     <para>
 115       Note that dconf needs a D-Bus session bus connection to write changes to the dconf database.
 116     </para>
 117   </refsect1>
 118
 119   <refsect1>
 120     <title>Commands</title>
 121
 122     <variablelist>
 123
 124       <varlistentry>
 125         <term><option>read</option></term>
 126
 127         <listitem><para>Read the value of a key.</para></listitem>
 128       </varlistentry>
 129
 130       <varlistentry>
 131         <term><option>list</option></term>
 132
 133         <listitem><para>List the sub-keys and sub-directories of a directory.</para></listitem>
 134       </varlistentry>
 135
 136       <varlistentry>
 137         <term><option>write</option></term>
 138
 139         <listitem><para>Write a new value to a key.</para></listitem>
 140       </varlistentry>
 141
 142       <varlistentry>
 143         <term><option>reset</option></term>
 144
 145         <listitem><para>Reset a key or an entire directory. For directories, <option>-f</option> must be specified.</para></listitem>
 146       </varlistentry>
 147
 148       <varlistentry>
 149         <term><option>compile</option></term>
 150
 151         <listitem>
 152           <para>Compile a binary database from keyfiles.</para>
 153           <para>
 154             The result is always in little-endian byte order, so it can be safely installed in 'share'.  If it
 155             is used on a big endian machine, dconf will automatically byteswap the contents on read.
 156           </para>
 157         </listitem>
 158       </varlistentry>
 159
 160       <varlistentry>
 161         <term><option>update</option></term>
 162
 163         <listitem><para>Update the system dconf databases.</para></listitem>
 164       </varlistentry>
 165
 166       <varlistentry>
 167         <term><option>watch</option></term>
 168
 169         <listitem><para>Watch a key or directory for changes.</para></listitem>
 170       </varlistentry>
 171
 172       <varlistentry>
 173         <term><option>dump</option></term>
 174
 175         <listitem><para>Dump an entire subpath to stdout. The output is in a keyfile-like format, with values in GVariant syntax.</para></listitem>
 176       </varlistentry>
 177
 178       <varlistentry>
 179         <term><option>load</option></term>
 180
 181         <listitem><para>Populate a subpath from stdin. The expected format is the same as produced by <option>dump</option>.</para></listitem>
 182       </varlistentry>
 183
 184       <varlistentry>
 185         <term><option>help</option></term>
 186
 187         <listitem><para>Display help and exit.  If <replaceable>COMMAND</replaceable> is given, display help for this command.</para></listitem>
 188       </varlistentry>
 189
 190     </variablelist>
 191   </refsect1>
 192
 193   <refsect1>
 194     <title>Environment</title>
 195
 196     <variablelist>
 197       <varlistentry>
 198         <term><envar>DCONF_PROFILE</envar></term>
 199         <listitem><para>
 200           This environment variable determines which dconf <firstterm>profile</firstterm> to use. See
 201           <citerefentry><refentrytitle>dconf</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 202         </para></listitem>
 203       </varlistentry>
 204     </variablelist>
 205   </refsect1>
 206
 207   <refsect1>
 208     <title>See Also</title>
 209     <para>
 210       <citerefentry><refentrytitle>dconf</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 211       <citerefentry><refentrytitle>gsettings</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 212       <citerefentry><refentrytitle>dconf-editor</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 213     </para>
 214   </refsect1>
 215 </refentry>