<?xml version="1.0" encoding="UTF-8"?>
<refentry id="uniconv.1">

  <refmeta>
    <refentrytitle>uniconv</refentrytitle>

    <manvolnum>1</manvolnum>

    <refmiscinfo class="date">19 Jan 2013</refmiscinfo>

    <refmiscinfo class="source">@NETATALK_VERSION@</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>uniconv</refname>

    <refpurpose>convert Netatalk volume encoding</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>uniconv</command>

      <arg choice="opt">-ndv</arg>

      <arg choice="plain">-c <replaceable>cnidbackend</replaceable></arg>

      <arg choice="plain">-f <replaceable>fromcode</replaceable></arg>

      <arg choice="plain">-t <replaceable>tocode</replaceable></arg>

      <arg>-m <replaceable>maccode</replaceable></arg>

      <arg choice="plain"><replaceable>volumepath</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para><command>uniconv</command> converts the volume encoding of
    <replaceable>volumepath</replaceable> from the <replaceable>fromcode</replaceable>
    to the <replaceable>tocode</replaceable> encoding.</para>
  </refsect1>

  <refsect1>
    <title>Options</title>

    <variablelist>
      <varlistentry>
        <term>-c</term>

        <listitem>
          <para>CNID backend used on this volume, usually cdb or dbd. Should
          match the backend selected with afpd for this volume. If not
          specified, the default CNID backend "@DEFAULT_CNID_SCHEME@" is
          used</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-d</term>

        <listitem>
          <para>don't HEX encode leading dots (:2e), equivalent to
          <option>use dots = yes</option> in <citerefentry><refentrytitle>afp.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-f</term>

        <listitem>
          <para>encoding to convert from, use ASCII for HEX encoded volumes</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-h</term>

        <listitem>
          <para>display help</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-m</term>

        <listitem>
          <para>Macintosh client codepage, required for HEX encoded volumes.
          Defaults to "MAC_ROMAN"</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-n</term>

        <listitem>
          <para>"dry run", don't do any real changes</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-t</term>

        <listitem>
          <para>volume encoding to convert to, e.g. UTF8</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-v</term>

        <listitem>
          <para>verbose output, use twice for maximum logging.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>-V</term>

        <listitem>
          <para>print version and exit</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para></para>
  </refsect1>

  <refsect1>
    <title>WARNING</title>

    <para>Setting the wrong options might render your data unusable!!! Make
    sure you know what you are doing. Always backup your data first.</para>

    <para>It is <emphasis role="bold">*strongly*</emphasis> recommended to do
    a "dry run" first and to check the output for conversion errors.</para>

    <para><citerefentry><refentrytitle>afpd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
    should <emphasis>not</emphasis> be running while you change the volume
    encoding. Remember to change <option>unix charset</option> or
    <option>vol charset</option> in
    <citerefentry><refentrytitle>afp.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
    to the new codepage, before restarting afpd.</para>

    <para>In case of <emphasis role="bold">MacChineseTraditional</emphasis>,
    <emphasis role="bold">MacJapanese</emphasis> or
    <emphasis role="bold">MacKorean</emphasis>,
    uniconv cannot be used.</para>

    <para><emphasis role="bold">USE AT YOUR OWN RISK!!!</emphasis></para>
  </refsect1>

  <refsect1>
    <title>Selectable charsets</title>

    <para>Netatalk provides internal support for UTF-8 (pre- and decomposed)
    and HEX. If you want to use other charsets, they must be provided by
    <citerefentry><refentrytitle>iconv</refentrytitle><manvolnum>1</manvolnum></citerefentry></para>

    <para><command>uniconv</command> also knows iso-8859.adapted, an old style
    1.x NLS widely used. This is only intended for upgrading old volumes,
    <citerefentry><refentrytitle>afpd</refentrytitle><manvolnum>8</manvolnum></citerefentry>
    cannot handle iso-8859.adapted anymore.</para>
  </refsect1>

  <refsect1>
    <title>CNID background</title>

    <para>The CNID backends maintains name to ID mappings. If you change a
    filename outside afpd(8) (shell, samba), the CNID db, i.e. the DIDNAME
    index, gets inconsistent. Netatalk tries to recover from such
    inconsistencies as gracefully as possible. The mechanisms to resolve such
    inconsistencies may fail sometimes, though, as this is not an easy task to
    accomplish. I.e. if several names in the path to the file or directory
    have changed, things may go wrong.</para>

    <para>If you change a lot of filenames at once, chances are higher that
    the afpds fallback mechanisms fail, i.e. files will be assigned new IDs,
    even though the file hasn't changed. <command>uniconv</command>
    therefore updates the CNID entry for each file/directory directly after it
    changes the name to avoid inconsistencies. The two supported backends for
    volumes, dbd and cdb, use the same CNID db format. Therefore, you
    <emphasis>could</emphasis> use <command>uniconv</command> with cdb and
    <command>afpd</command> with dbd later.</para>

    <para><emphasis role="bold">Warning</emphasis>: There must not be two
    processes opening the CNID database using different backends at once! If a
    volume is still opened with dbd (cnid_metad/cnid_dbd) and you start
    <command>uniconv</command> with cdb, the result will be a corrupted CNID
    database, as the two backends use different locking schemes. You might run
    into additional problems, e.g. if dbd is compiled with transactions, cdb
    will not update the transaction logs.</para>

    <para>In general, it is recommended to use the same backend for
    <command>uniconv</command> you are using with
    <citerefentry><refentrytitle>afpd</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
  </refsect1>

  <refsect1>
    <title>Examples</title>

    <para>convert 1.x CAP encoded volume to UTF-8, clients used MacRoman
    codepage, cnidscheme is dbd:</para>

    <screen><prompt>example%</prompt><userinput> uniconv -c dbd -f ASCII -t UTF8 -m MAC_ROMAN /path/to/share</userinput></screen>

    <para>convert iso8859-1 volume to UTF-8, cnidscheme is cdb:</para>

    <screen><prompt>example%</prompt><userinput> uniconv -c cdb -f ISO-8859-1 -t UTF8 -m MAC_ROMAN /path/to/share</userinput></screen>

    <para>convert 1.x volume using iso8859-1 adapted NLS to HEX encoding:</para>

    <screen><prompt>example%</prompt><userinput> uniconv -f ISO-8859-ADAPTED -t ASCII -m MAC_ROMAN/path/to/share</userinput></screen>

    <para>convert UTF-8 volume to HEX, for MacCyrillic clients:</para>

    <screen><prompt>example%</prompt><userinput> uniconv -f UTF8 -t ASCII -m MAC_CYRILLIC /path/to/share</userinput></screen>
  </refsect1>

  <refsect1>
    <title>See also</title>

    <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>
  </refsect1>
</refentry>