doc/rgcmd.xml

   1
   2 <!--
   3 $Id$
   4 -->
   5         <section id="kdbdesc"><title>Description</title>
   6                 <para>The <command>kdb</command> command provide ways to manipulate the Elektra keys database.</para>
   7                 <para>The subcommands implemented are very similar to regular UNIX commands like <command>ls</command>, and <command>rm</command>, specially in their output and options.</para>
   8         </section>
   9
  10         <section id="kdbsubc"><title>Subcommands</title>
  11                 <variablelist>
  12                         <varlistentry><term><command>get</command></term>
  13                                 <listitem><para>Get the value from the specified key. Accepts options: <option>-d</option>, <option>-l</option>, <option>-f</option>, <option>-s</option></para></listitem>
  14                         </varlistentry>
  15
  16                         <varlistentry><term><command>set</command></term>
  17                                 <listitem><para>Set the value to the specified key. Accepts options: <option>-c</option>, <option>-t</option>, <option>-d</option>, <option>-m</option>, <option>-b</option></para></listitem>
  18                         </varlistentry>
  19
  20                         <varlistentry><term><command>ls</command></term>
  21                                 <listitem><para>As the <citerefentry><refentrytitle>ls</refentrytitle><manvolnum>1</manvolnum></citerefentry> command, list key names for the specified key, or children keys, if specified a folder key. The <option>-v</option> argument will make it show also the values of each key. The <option>-d</option> (descriptive) will make it show the comment, key name and its value, as you are watching a plain text file. Accepts options: <option>-x</option>, <option>-d</option>, <option>-l</option>, <option>-f</option>, <option>-v</option>, <option>-R</option>, <option>-s</option></para></listitem>
  22                         </varlistentry>
  23
  24                         <varlistentry><term><command>ln</command></term>
  25                                 <listitem><para>Creates a key that is a symbolic links to another key.</para></listitem>
  26                         </varlistentry>
  27
  28                         <varlistentry><term><command>mv</command></term>
  29                                 <listitem><para>Move, or renames a key. Currently it can't move keys across different filesystems.</para></listitem>
  30                         </varlistentry>
  31
  32                         <varlistentry><term><command>rm</command></term>
  33                                 <listitem><para>As the <citerefentry><refentrytitle>rm</refentrytitle><manvolnum>1</manvolnum></citerefentry> command, removes the key specified.</para></listitem>
  34                         </varlistentry>
  35
  36                         <varlistentry><term><command>edit</command></term>
  37                                 <listitem><para>A very powerfull subcommand that lets you edit an XML representation of the keys. The parameters it accepts is usually a parent key, so its child keys will be gathered. Can be used with the <option>-R</option> flag to work recursively. The editor used is the one set in the <envar>$EDITOR</envar> environment variable, or <command>vi</command>. After editing the keys, <command>kdb edit</command> will analyze them and commit only the changed keys, remove the keys removed, and add the keys added. This command is only available when <filename>/usr/lib/libelektratools.so</filename> is available.</para></listitem>
  38                         </varlistentry>
  39
  40                         <varlistentry><term><command>export</command></term><term><command>save</command></term>
  41                                 <listitem><para>Export a subtree of keys to XML. If no subtree is defined right after the <command>export</command> command, <filename>system</filename> and current <filename>user</filename> trees will be exported. Output is written to standard output. The output encoding will allways be UTF-8, regardeless of your system encoding. UTF-8 is the most universal charset you can get when exchanging data between multiple systems. Accepts <option>-f</option>.</para></listitem>
  42                         </varlistentry>
  43
  44                         <varlistentry><term><command>import</command></term><term><command>load</command></term>
  45                                 <listitem><para>Import an XML representation of keys and save it to the keys database. If no filename is passed right after the <command>import</command> command, standard input is used. This command is only available when <filename>/usr/lib/libelektratools.so</filename> is available.</para></listitem>
  46                         </varlistentry>
  47
  48                         <varlistentry><term><command>monitor</command></term><term><command>mon</command></term>
  49                                 <listitem><para>Monitor a key for some value change. It will block your command line until a change in the key value is detected, then return its new value.</para></listitem>
  50                         </varlistentry>
  51                 </variablelist>
  52         </section>
  53
  54         <section id="kdbopt"><title>Options</title>
  55                 <variablelist>
  56                         <varlistentry><term><option>-R</option></term>
  57                                 <listitem><para>Causes to work recursively. In <command>ls</command>, will list recursively.</para></listitem>
  58                         </varlistentry>
  59
  60                         <varlistentry><term><option>-x</option></term>
  61                                 <listitem><para>Makes <command>ls</command> output an XML representation of the keys, instead of an <command>ls</command>-compatible output.</para></listitem>
  62                         </varlistentry>
  63
  64                         <varlistentry><term><option>-l</option></term>
  65                                 <listitem><para>Causes to display long results. With <command>ls</command>, will generate lists similar to <command>ls -l</command>. With <command>get</command>, will show also the key name.</para></listitem>
  66                         </varlistentry>
  67
  68                         <varlistentry><term><option>-a</option></term>
  69                                 <listitem><para>Causes <command>ls</command> to display also inactive keys. Generate lists similar to <command>ls -a</command>. Inactive keys are keys which basename begins with a '.' (dot). An example of inactive key: <filename>system/sw/XFree/current/Monitor/.Monitor1</filename></para></listitem>
  70                         </varlistentry>
  71
  72                         <varlistentry><term><option>-f</option></term>
  73                                 <listitem><para>Causes to work with full key names. A full key name makes sense only on <filename>user/*</filename> keys, and differentiate from the regular key names in specifying the owner user. If the current user is <filename>someuser</filename>, the <filename>user/some/key</filename> full name is <filename>user:someuser/some/key</filename>. Makes effect in <command>ls</command>, <command>export</command> and <command>get</command> subcommands.</para></listitem>
  74                         </varlistentry>
  75
  76                         <varlistentry><term><option>-d</option></term>
  77                                 <listitem><para>Causes <command>get</command> to work descriptivelly. When requesting a key it will show the comment, key name and its value in a fancy format.</para></listitem>
  78                                 <listitem><para>Causes <command>set</command> to mark the key as a directory key.</para></listitem>
  79                         </varlistentry>
  80
  81                         <varlistentry><term><option>-s</option></term>
  82                                 <listitem><para>Causes <command>get</command> and <command>ls</command> to be more friendly to Shell scripts. For example, when requesting <filename>user/env/env2/PATH</filename>, the output will be PATH="the value", that is, only the basename of the key will be showed and the value will be surrounded by ' " '.</para></listitem>
  83                         </varlistentry>
  84
  85                         <varlistentry><term><option>-t type</option></term>
  86                                 <listitem><para>When <command>set</command>ting a key's value, you can specify the type with this switch. Currently accepted types are <type>string</type> for plain text, <type>bin</type> for binary as-is values, <type>dir</type> to create folder keys and <type>link</type> to create symbolic links between keys. Plain text are always stored as <citerefentry><refentrytitle>UTF-8</refentrytitle><manvolnum>7</manvolnum></citerefentry> in Elektra, regardeless of your current encoding (<envar>$LANG</envar>). If you want to force a value to be stored without the <citerefentry><refentrytitle>UTF-8</refentrytitle><manvolnum>7</manvolnum></citerefentry> encoding (a bad idea), you can set it as binary. Binary values should be avoided, because they are black boxes for system administrators.</para></listitem>
  87                         </varlistentry>
  88
  89                         <varlistentry><term><option>-b filename</option></term>
  90                                 <listitem><para>Set the key value as the content of file <filename>filename</filename>. This option is more usefull when setting binary keys.</para></listitem>
  91                         </varlistentry>
  92
  93                         <varlistentry><term><option>-m mode</option></term>
  94                                 <listitem><para>For the <command>set</command> command. Will set the key access permission to <option>mode</option>, which must be an octal number as for <citerefentry><refentrytitle><command>chmod</command></refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para></listitem>
  95                         </varlistentry>
  96
  97                         <varlistentry><term><option>-u uid</option></term>
  98                                 <listitem><para>Create the key with <option>uid</option> user ID. It can be a user name or a uid number.</para></listitem>
  99                         </varlistentry>
 100
 101                         <varlistentry><term><option>-g gid</option></term>
 102                                 <listitem><para>Create the key with <option>gid</option> group ID. It can be a group name or a gid number</para></listitem>
 103                         </varlistentry>
 104
 105                         <varlistentry><term><option>-c comment</option></term>
 106                                 <listitem><para>When <command>set</command>ting keys, you can use this argument to set a descriptive comment for it. This comment is exactly as a comment in a plain text configuration file. The comment is stored as <citerefentry><refentrytitle>UTF-8</refentrytitle><manvolnum>7</manvolnum></citerefentry> regardeless of your current encoding (<envar>$LANG</envar>).</para></listitem>
 107                         </varlistentry>
 108
 109                         <varlistentry><term><option>-v</option></term>
 110                                 <listitem><para>With the <command>ls</command> subcommand, will make it show also the value stored in the key.</para></listitem>
 111                         </varlistentry>
 112
 113                         <varlistentry><term><option>--</option></term>
 114                                 <listitem><para>With the <command>set</command> subcommand, everything after it will be considered the value, even text with dashes (-).</para></listitem>
 115                         </varlistentry>
 116                 </variablelist>
 117         </section>