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.75.2 <http://docbook.sf.net/>
   5 .\"      Date: 24 Jun 2004
   6 .\"    Manual: Netatalk 2.2
   7 .\"    Source: Netatalk 2.2
   8 .\"  Language: English
   9 .\"
  10 .TH "UNICONV" "1" "24 Jun 2004" "Netatalk 2.2" "Netatalk 2.2"
  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 In case of
 104 \fBMacChineseTraditional\fR,
 105 \fBMacJapanese\fR
 106 or
 107 \fBMacKorean\fR, uniconv cannot be used\&.
 108 .PP
 109 \fBUSE AT YOUR OWN RISK!!!\fR
 110 .SH "SELECTABLE CHARSETS"
 111 .PP
 112 Netatalk provides internal support for UTF\-8 (pre\- and decomposed) and CAP\&. If you want to use other charsets, they must be provided by
 113 \fBiconv\fR(1)
 114 .PP
 115 \fBuniconv\fR
 116 also knows iso\-8859\&.adapted, an old style 1\&.x NLS widely used\&. This is only intended for upgrading old volumes,
 117 \fBafpd\fR(8)
 118 cannot handle iso\-8859\&.adapted anymore\&.
 119 .SH "CNID BACKGROUND"
 120 .PP
 121 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\&.
 122 .PP
 123 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\&.
 124 \fBuniconv\fR
 125 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
 126 \fIcould\fR
 127 use
 128 \fBuniconv\fR
 129 with cdb and
 130 \fBafpd\fR
 131 with dbd later\&.
 132 .PP
 133 \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
 134 \fBuniconv\fR
 135 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\&.
 136 .PP
 137 In general, it is recommended to use the same backend for
 138 \fBuniconv\fR
 139 you are using with
 140 \fBafpd\fR(8)\&.
 141 .SH "EXAMPLES"
 142 .PP
 143 convert 1\&.x CAP encoded volume to UTF\-8, clients used MacRoman codepage, cnidscheme is dbd:
 144 .sp
 145 .if n \{\
 146 .RS 4
 147 .\}
 148 .nf
 149 example%\fB uniconv \-c dbd \-f ASCII \-t UTF8 \-m MAC_ROMAN /path/to/share\fR
 150 .fi
 151 .if n \{\
 152 .RE
 153 .\}
 154 .PP
 155 convert iso8859\-1 volume to UTF\-8, cnidscheme is cdb:
 156 .sp
 157 .if n \{\
 158 .RS 4
 159 .\}
 160 .nf
 161 example%\fB uniconv \-c cdb \-f ISO\-8859\-1 \-t UTF8 \-m MAC_ROMAN /path/to/share\fR
 162 .fi
 163 .if n \{\
 164 .RE
 165 .\}
 166 .PP
 167 convert 1\&.x volume using iso8859\-1 adapted NLS to CAP encoding:
 168 .sp
 169 .if n \{\
 170 .RS 4
 171 .\}
 172 .nf
 173 example%\fB uniconv \-f ISO\-8859\-ADAPTED \-t ASCII \-m MAC_ROMAN/path/to/share\fR
 174 .fi
 175 .if n \{\
 176 .RE
 177 .\}
 178 .PP
 179 convert UTF\-8 volume to CAP, for MacCyrillic clients:
 180 .sp
 181 .if n \{\
 182 .RS 4
 183 .\}
 184 .nf
 185 example%\fB uniconv \-f UTF8 \-t ASCII \-m MAC_CYRILLIC /path/to/share\fR
 186 .fi
 187 .if n \{\
 188 .RE
 189 .\}
 190 .SH "SEE ALSO"
 191 .PP
 192 \fBAppleVolumes.default\fR(5),\fBafpd\fR(8),\fBiconv\fR(1),\fBcnid_metad\fR(8),\fBcnid_dbd\fR(8)