man/man1/uniconv.1.tmpl

   1 '\" t
   2 .\"     Title: uniconv
   3 .\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
   4 .\" Generator: DocBook XSL Stylesheets v1.74.3 <http://docbook.sf.net/>
   5 .\"      Date: 24 Jun 2004
   6 .\"    Manual: Netatalk 2.0.4
   7 .\"    Source: Netatalk 2.0.4
   8 .\"  Language: English
   9 .\"
  10 .TH "UNICONV" "1" "24 Jun 2004" "Netatalk 2\&.0\&.4" "Netatalk 2.0.4"
  11 .\" -----------------------------------------------------------------
  12 .\" * set default formatting
  13 .\" -----------------------------------------------------------------
  14 .\" disable hyphenation
  15 .nh
  16 .\" disable justification (adjust text to left margin only)
  17 .ad l
  18 .\" -----------------------------------------------------------------
  19 .\" * MAIN CONTENT STARTS HERE *
  20 .\" -----------------------------------------------------------------
  21 .SH "NAME"
  22 uniconv \- convert Netatalk volume encoding
  23 .SH "SYNOPSIS"
  24 .HP \w'\fBuniconv\fR\fB\fR\ 'u
  25 \fBuniconv\fR\fB\fR [\-ndv] \-c\ \fIcnidbackend\fR \-f\ \fIfromcode\fR \-t\ \fItocode\fR [\-m\ \fImaccode\fR] \fIvolumepath\fR
  26 .SH "DESCRIPTION"
  27 .PP
  28 \fBuniconv\fR
  29 converts the volume encoding of
  30 \fIvolumepath\fR
  31 from the
  32 \fIfromcode\fR
  33 to the
  34 \fItocode\fR
  35 encoding\&.
  36 .SH "OPTIONS"
  37 .PP
  38 \-c
  39 .RS 4
  40 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
  41 .RE
  42 .PP
  43 \-d
  44 .RS 4
  45 don\'t CAP encode leading dots (:2e), equivalent to
  46 \fBusedots\fR
  47 in
  48 \fBAppleVolumes.default\fR(5)
  49 .RE
  50 .PP
  51 \-f
  52 .RS 4
  53 encoding to convert from, use ASCII for CAP encoded volumes
  54 .RE
  55 .PP
  56 \-h
  57 .RS 4
  58 display help
  59 .RE
  60 .PP
  61 \-m
  62 .RS 4
  63 Macintosh client codepage, required for CAP encoded volumes\&. Defaults to `MAC_ROMAN\'
  64 .RE
  65 .PP
  66 \-n
  67 .RS 4
  68 `dry run\', don\'t do any real changes
  69 .RE
  70 .PP
  71 \-t
  72 .RS 4
  73 volume encoding to convert to, e\&.g\&. UTF8
  74 .RE
  75 .PP
  76 \-v
  77 .RS 4
  78 verbose output, use twice for maximum logging\&.
  79 .RE
  80 .PP
  81 \-V
  82 .RS 4
  83 print version and exit
  84 .RE
  85 .PP
  86 .SH "WARNING"
  87 .PP
  88 Setting the wrong options might render your data unusable!!! Make sure you know what you are doing\&. Always backup your data first\&.
  89 .PP
  90 It is
  91 \fB*strongly*\fR
  92 recommended to do a `dry run\' first and to check the output for conversion errors\&.
  93 .PP
  94 \fBafpd\fR(8)
  95 should
  96 \fInot\fR
  97 be running while you change the volume encoding\&. Remember to change
  98 \fBvolcodepage\fR
  99 in
 100 \fBAppleVolumes.default\fR(5)
 101 to the new codepage, before restarting afpd\&.
 102 .PP
 103 \fBUSE AT YOUR OWN RISK!!!\fR
 104 .SH "SELECTABLE CHARSETS"
 105 .PP
 106 Netatalk provides internal support for UTF\-8 (pre\- and decomposed) and CAP\&. If you want to use other charsets, they must be provided by
 107 \fBiconv\fR(1)
 108 .PP
 109 \fBuniconv\fR
 110 also knows iso\-8859\&.adapted, an old style 1\&.x NLS widely used\&. This is only intended for upgrading old volumes,
 111 \fBafpd\fR(8)
 112 cannot handle iso\-8859\&.adapted anymore\&.
 113 .SH "CNID BACKGROUND"
 114 .PP
 115 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\&.
 116 .PP
 117 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\&.
 118 \fBuniconv\fR
 119 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
 120 \fIcould\fR
 121 use
 122 \fBuniconv\fR
 123 with cdb and
 124 \fBafpd\fR
 125 with dbd later\&.
 126 .PP
 127 \fBWarning\fR: 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
 128 \fBuniconv\fR
 129 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\&.
 130 .PP
 131 In general, it is recommended to use the same backend for
 132 \fBuniconv\fR
 133 you are using with
 134 \fBafpd\fR(8)\&.
 135 .SH "EXAMPLES"
 136 .PP
 137 convert 1\&.x CAP encoded volume to UTF\-8, clients used MacRoman codepage, cnidscheme is dbd:
 138 .sp
 139 .if n \{\
 140 .RS 4
 141 .\}
 142 .nf
 143 example%\fB uniconv \-c dbd \-f ASCII \-t UTF8 \-m MAC_ROMAN /path/to/share\fR
 144 .fi
 145 .if n \{\
 146 .RE
 147 .\}
 148 .PP
 149 convert iso8859\-1 volume to UTF\-8, cnidscheme is cdb:
 150 .sp
 151 .if n \{\
 152 .RS 4
 153 .\}
 154 .nf
 155 example%\fB uniconv \-c cdb \-f ISO\-8859\-1 \-t UTF8 \-m MAC_ROMAN /path/to/share\fR
 156 .fi
 157 .if n \{\
 158 .RE
 159 .\}
 160 .PP
 161 convert 1\&.x volume using iso8859\-1 adapted NLS to CAP encoding:
 162 .sp
 163 .if n \{\
 164 .RS 4
 165 .\}
 166 .nf
 167 example%\fB uniconv \-f ISO\-8859\-ADAPTED \-t ASCII \-m MAC_ROMAN/path/to/share\fR
 168 .fi
 169 .if n \{\
 170 .RE
 171 .\}
 172 .PP
 173 convert UTF\-8 volume to CAP, for MacCyrillic clients:
 174 .sp
 175 .if n \{\
 176 .RS 4
 177 .\}
 178 .nf
 179 example%\fB uniconv \-f UTF8 \-t ASCII \-m MAC_CYRILLIC /path/to/share\fR
 180 .fi
 181 .if n \{\
 182 .RE
 183 .\}
 184 .SH "SEE ALSO"
 185 .PP
 186 \fBAppleVolumes.default\fR(5),\fBafpd\fR(8),\fBiconv\fR(1),\fBcnid_metad\fR(8),\fBcnid_dbd\fR(8)