man/man1/uniconv.1.in

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