--- /dev/null
+<?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<indexterm><primary>uniconv</primary></indexterm></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>
projects / netatalk.git / blobdiff