doc/manpages/man1/uniconv.1.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <refentry id="uniconv.1">
   3
   4   <refmeta>
   5     <refentrytitle>uniconv</refentrytitle>
   6
   7     <manvolnum>1</manvolnum>
   8
   9     <refmiscinfo class="date">19 Jan 2013</refmiscinfo>
  10
  11     <refmiscinfo class="source">@NETATALK_VERSION@</refmiscinfo>
  12   </refmeta>
  13
  14   <refnamediv>
  15     <refname>uniconv</refname>
  16
  17     <refpurpose>convert Netatalk volume encoding</refpurpose>
  18   </refnamediv>
  19
  20   <refsynopsisdiv>
  21     <cmdsynopsis>
  22       <command>uniconv<indexterm><primary>uniconv</primary></indexterm></command>
  23
  24       <arg choice="opt">-ndv</arg>
  25
  26       <arg choice="plain">-c <replaceable>cnidbackend</replaceable></arg>
  27
  28       <arg choice="plain">-f <replaceable>fromcode</replaceable></arg>
  29
  30       <arg choice="plain">-t <replaceable>tocode</replaceable></arg>
  31
  32       <arg>-m <replaceable>maccode</replaceable></arg>
  33
  34       <arg choice="plain"><replaceable>volumepath</replaceable></arg>
  35     </cmdsynopsis>
  36   </refsynopsisdiv>
  37
  38   <refsect1>
  39     <title>Description</title>
  40
  41     <para><command>uniconv</command> converts the volume encoding of
  42     <replaceable>volumepath</replaceable> from the <replaceable>fromcode</replaceable>
  43     to the <replaceable>tocode</replaceable> encoding.</para>
  44   </refsect1>
  45
  46   <refsect1>
  47     <title>Options</title>
  48
  49     <variablelist>
  50       <varlistentry>
  51         <term>-c</term>
  52
  53         <listitem>
  54           <para>CNID backend used on this volume, usually cdb or dbd. Should
  55           match the backend selected with afpd for this volume. If not
  56           specified, the default CNID backend "@DEFAULT_CNID_SCHEME@" is
  57           used</para>
  58         </listitem>
  59       </varlistentry>
  60
  61       <varlistentry>
  62         <term>-d</term>
  63
  64         <listitem>
  65           <para>don't HEX encode leading dots (:2e), equivalent to
  66           <option>use dots = yes</option> in <citerefentry><refentrytitle>afp.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></para>
  67         </listitem>
  68       </varlistentry>
  69
  70       <varlistentry>
  71         <term>-f</term>
  72
  73         <listitem>
  74           <para>encoding to convert from, use ASCII for HEX encoded volumes</para>
  75         </listitem>
  76       </varlistentry>
  77
  78       <varlistentry>
  79         <term>-h</term>
  80
  81         <listitem>
  82           <para>display help</para>
  83         </listitem>
  84       </varlistentry>
  85
  86       <varlistentry>
  87         <term>-m</term>
  88
  89         <listitem>
  90           <para>Macintosh client codepage, required for HEX encoded volumes.
  91           Defaults to "MAC_ROMAN"</para>
  92         </listitem>
  93       </varlistentry>
  94
  95       <varlistentry>
  96         <term>-n</term>
  97
  98         <listitem>
  99           <para>"dry run", don't do any real changes</para>
 100         </listitem>
 101       </varlistentry>
 102
 103       <varlistentry>
 104         <term>-t</term>
 105
 106         <listitem>
 107           <para>volume encoding to convert to, e.g. UTF8</para>
 108         </listitem>
 109       </varlistentry>
 110
 111       <varlistentry>
 112         <term>-v</term>
 113
 114         <listitem>
 115           <para>verbose output, use twice for maximum logging.</para>
 116         </listitem>
 117       </varlistentry>
 118
 119       <varlistentry>
 120         <term>-V</term>
 121
 122         <listitem>
 123           <para>print version and exit</para>
 124         </listitem>
 125       </varlistentry>
 126     </variablelist>
 127
 128     <para></para>
 129   </refsect1>
 130
 131   <refsect1>
 132     <title>WARNING</title>
 133
 134     <para>Setting the wrong options might render your data unusable!!! Make
 135     sure you know what you are doing. Always backup your data first.</para>
 136
 137     <para>It is <emphasis role="bold">*strongly*</emphasis> recommended to do
 138     a "dry run" first and to check the output for conversion errors.</para>
 139
 140     <para><citerefentry><refentrytitle>afpd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 141     should <emphasis>not</emphasis> be running while you change the volume
 142     encoding. Remember to change <option>unix charset</option> or
 143     <option>vol charset</option> in
 144     <citerefentry><refentrytitle>afp.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 145     to the new codepage, before restarting afpd.</para>
 146
 147     <para>In case of <emphasis role="bold">MacChineseTraditional</emphasis>,
 148     <emphasis role="bold">MacJapanese</emphasis> or
 149     <emphasis role="bold">MacKorean</emphasis>,
 150     uniconv cannot be used.</para>
 151
 152     <para><emphasis role="bold">USE AT YOUR OWN RISK!!!</emphasis></para>
 153   </refsect1>
 154
 155   <refsect1>
 156     <title>Selectable charsets</title>
 157
 158     <para>Netatalk provides internal support for UTF-8 (pre- and decomposed)
 159     and HEX. If you want to use other charsets, they must be provided by
 160     <citerefentry><refentrytitle>iconv</refentrytitle><manvolnum>1</manvolnum></citerefentry></para>
 161
 162     <para><command>uniconv</command> also knows iso-8859.adapted, an old style
 163     1.x NLS widely used. This is only intended for upgrading old volumes,
 164     <citerefentry><refentrytitle>afpd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 165     cannot handle iso-8859.adapted anymore.</para>
 166   </refsect1>
 167
 168   <refsect1>
 169     <title>CNID background</title>
 170
 171     <para>The CNID backends maintains name to ID mappings. If you change a
 172     filename outside afpd(8) (shell, samba), the CNID db, i.e. the DIDNAME
 173     index, gets inconsistent. Netatalk tries to recover from such
 174     inconsistencies as gracefully as possible. The mechanisms to resolve such
 175     inconsistencies may fail sometimes, though, as this is not an easy task to
 176     accomplish. I.e. if several names in the path to the file or directory
 177     have changed, things may go wrong.</para>
 178
 179     <para>If you change a lot of filenames at once, chances are higher that
 180     the afpds fallback mechanisms fail, i.e. files will be assigned new IDs,
 181     even though the file hasn't changed. <command>uniconv</command>
 182     therefore updates the CNID entry for each file/directory directly after it
 183     changes the name to avoid inconsistencies. The two supported backends for
 184     volumes, dbd and cdb, use the same CNID db format. Therefore, you
 185     <emphasis>could</emphasis> use <command>uniconv</command> with cdb and
 186     <command>afpd</command> with dbd later.</para>
 187
 188     <para><emphasis role="bold">Warning</emphasis>: There must not be two
 189     processes opening the CNID database using different backends at once! If a
 190     volume is still opened with dbd (cnid_metad/cnid_dbd) and you start
 191     <command>uniconv</command> with cdb, the result will be a corrupted CNID
 192     database, as the two backends use different locking schemes. You might run
 193     into additional problems, e.g. if dbd is compiled with transactions, cdb
 194     will not update the transaction logs.</para>
 195
 196     <para>In general, it is recommended to use the same backend for
 197     <command>uniconv</command> you are using with
 198     <citerefentry><refentrytitle>afpd</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 199   </refsect1>
 200
 201   <refsect1>
 202     <title>Examples</title>
 203
 204     <para>convert 1.x CAP encoded volume to UTF-8, clients used MacRoman
 205     codepage, cnidscheme is dbd:</para>
 206
 207     <screen><prompt>example%</prompt><userinput> uniconv -c dbd -f ASCII -t UTF8 -m MAC_ROMAN /path/to/share</userinput></screen>
 208
 209     <para>convert iso8859-1 volume to UTF-8, cnidscheme is cdb:</para>
 210
 211     <screen><prompt>example%</prompt><userinput> uniconv -c cdb -f ISO-8859-1 -t UTF8 -m MAC_ROMAN /path/to/share</userinput></screen>
 212
 213     <para>convert 1.x volume using iso8859-1 adapted NLS to HEX encoding:</para>
 214
 215     <screen><prompt>example%</prompt><userinput> uniconv -f ISO-8859-ADAPTED -t ASCII -m MAC_ROMAN/path/to/share</userinput></screen>
 216
 217     <para>convert UTF-8 volume to HEX, for MacCyrillic clients:</para>
 218
 219     <screen><prompt>example%</prompt><userinput> uniconv -f UTF8 -t ASCII -m MAC_CYRILLIC /path/to/share</userinput></screen>
 220   </refsect1>
 221
 222   <refsect1>
 223     <title>See also</title>
 224
 225     <para><citerefentry><refentrytitle>afp.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,<citerefentry><refentrytitle>afpd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,<citerefentry><refentrytitle>iconv</refentrytitle><manvolnum>1</manvolnum></citerefentry>,<citerefentry><refentrytitle>cnid_metad</refentrytitle><manvolnum>8</manvolnum></citerefentry>,<citerefentry><refentrytitle>cnid_dbd</refentrytitle><manvolnum>8</manvolnum></citerefentry></para>
 226   </refsect1>
 227 </refentry>