howto/Unicode.xml

   1 <chapter id="unicode">
   2 <chapterinfo>
   3         &author.jelmer;
   4         &author.jht;
   5         <author>
   6                 <firstname>TAKAHASHI</firstname><surname>Motonobu</surname>
   7                 <affiliation>
   8                 <address><email>monyo@home.monyo.com</email></address>
   9                 </affiliation>
  10                 <contrib>Japanese character support</contrib>
  11         </author>
  12         <pubdate>25 March 2003</pubdate>
  13 </chapterinfo>
  14
  15 <title>Unicode/Charsets</title>
  16
  17 <sect1>
  18 <title>Features and Benefits</title>
  19
  20 <para>
  21 Every industry eventually matures. One of the great areas of maturation is in
  22 the focus that has been given over the past decade to make it possible for anyone
  23 anywhere to use a computer. It has not always been that way, in fact, not so long
  24 ago it was common for software to be written for exclusive use in the country of
  25 origin.
  26 </para>
  27
  28 <para>
  29 Of all the effort that has been brought to bear on providing native
  30 language support for all computer users, the efforts of the
  31 <ulink url="http://www.openi18n.org/">Openi18n organization</ulink>
  32 is deserving of special mention.
  33 </para>
  34
  35 <para>
  36 Samba-2.x supported a single locale through a mechanism called
  37 <emphasis>codepages</emphasis>. Samba-3 is destined to become a truly trans-global
  38 file and printer-sharing platform.
  39 </para>
  40
  41 </sect1>
  42
  43 <sect1>
  44 <title>What Are Charsets and Unicode?</title>
  45
  46 <para>
  47 Computers communicate in numbers. In texts, each number will be
  48 translated to a corresponding letter. The meaning that will be assigned
  49 to a certain number depends on the <emphasis>character set (charset)
  50 </emphasis> that is used.
  51 </para>
  52
  53 <para>
  54 A charset can be seen as a table that is used to translate numbers to
  55 letters. Not all computers use the same charset (there are charsets
  56 with German umlauts, Japanese characters, and so on). The American Standard Code
  57 for Information Interchange (ASCII) encoding system has been the normative character
  58 encoding scheme used by computers to date. This employs a charset that contains
  59 256 characters. Using this mode of encoding each character takes exactly one byte.
  60 </para>
  61
  62 <para>
  63 There are also charsets that support extended characters, but those need at least
  64 twice as much storage space as does ASCII encoding. Such charsets can contain
  65 <command>256 * 256 = 65536</command> characters, which is more than all possible
  66 characters one could think of. They are called multi-byte charsets because they use
  67 more then one byte to store one character.
  68 </para>
  69
  70 <para>
  71 One standardized multi-byte charset encoding scheme is known as
  72 <ulink url="http://www.unicode.org/">unicode</ulink>.  A big advantage of using a
  73 multi-byte charset is that you only need one. There is no need to make sure two
  74 computers use the same charset when they are communicating.
  75 </para>
  76
  77 <para>Old Windows clients use single-byte charsets, named
  78 <parameter>codepages</parameter>, by Microsoft. However, there is no support for
  79 negotiating the charset to be used in the SMB/CIFS protocol. Thus, you
  80 have to make sure you are using the same charset when talking to an older client.
  81 Newer clients (Windows NT, 200x, XP) talk unicode over the wire.
  82 </para>
  83 </sect1>
  84
  85 <sect1>
  86 <title>Samba and Charsets</title>
  87
  88 <para>
  89 As of Samba-3, Samba can (and will) talk unicode over the wire. Internally,
  90 Samba knows of three kinds of character sets:
  91 </para>
  92
  93 <variablelist>
  94         <varlistentry>
  95                 <term><smbconfoption><name>unix charset</name></smbconfoption></term>
  96                 <listitem><para>
  97                 This is the charset used internally by your operating system.
  98                 The default is <constant>UTF-8</constant>, which is fine for most
  99                 systems, which covers all characters in all languages. The default
 100                 in previous Samba releases was <constant>ASCII</constant>.
 101                 </para></listitem>
 102         </varlistentry>
 103
 104         <varlistentry>
 105                 <term><smbconfoption><name>display charset</name></smbconfoption></term>
 106                 <listitem><para>This is the charset Samba will use to print messages
 107                 on your screen. It should generally be the same as the <parameter>unix charset</parameter>.
 108                 </para></listitem>
 109         </varlistentry>
 110
 111         <varlistentry>
 112                 <term><smbconfoption><name>dos charset</name></smbconfoption></term>
 113                 <listitem><para>This is the charset Samba uses when communicating with
 114                 DOS and Windows 9x/Me clients. It will talk unicode to all newer clients.
 115                 The default depends on the charsets you have installed on your system.
 116                 Run <command>testparm -v | grep <quote>dos charset</quote></command> to see
 117                 what the default is on your system.
 118                 </para></listitem>
 119         </varlistentry>
 120 </variablelist>
 121
 122 </sect1>
 123
 124 <sect1>
 125 <title>Conversion from Old Names</title>
 126
 127 <para>Because previous Samba versions did not do any charset conversion,
 128 characters in filenames are usually not correct in the UNIX charset but only
 129 for the local charset used by the DOS/Windows clients.</para>
 130
 131 <para>Bjoern Jacke has written a utility named <ulink url="http://j3e.de/linux/convmv/">convmv</ulink>
 132 that can convert whole directory structures to different charsets with one single command.
 133 </para>
 134
 135 </sect1>
 136
 137 <sect1>
 138 <title>Japanese Charsets</title>
 139
 140 <para>
 141 Setting up Japanese charsets is quite difficult. This is mainly because:
 142 </para>
 143
 144 <itemizedlist>
 145         <listitem><para>The Windows character set is extended from the original legacy Japanese
 146                 standard (JIS X 0208) and is not standardized. This means that the strictly
 147                 standardized implementation cannot support the full Windows character set.
 148         </para></listitem>
 149
 150         <listitem><para> Mainly for historical reasons, there are several encoding methods in
 151                 Japanese, which are not fully compatible with each other. There are
 152                 two major encoding methods. One is the Shift_JIS series, it is used in Windows
 153                 and some UNIX's. The other is the EUC-JP series, used in most UNIX's
 154                 and Linux. Moreover, Samba previously also offered several unique encoding
 155                 methods, named CAP and HEX, to keep interoperability with CAP/NetAtalk and
 156                 UNIX's which can't use Japanese filenames.  Some implementations of the
 157                 EUC-JP series can't support the full Windows character set.
 158         </para></listitem>
 159
 160         <listitem><para>There are some code conversion tables between Unicode and legacy
 161                 Japanese character sets. One is compatible with Windows, another one
 162                 is based on the reference of the Unicode consortium and others are
 163                 a mixed implementation. The Unicode consortium does not officially
 164                 define any conversion tables between Unicode and legacy character
 165                 sets so there cannot be standard one.
 166         </para></listitem>
 167
 168         <listitem><para>The character set and conversion tables available in iconv() depends
 169                 on the iconv library that is available. Next to that, the Japanese locale
 170                 names may be different on different systems.  This means that the value of
 171                 the charset parameters depends on the implementation of iconv() you are using.
 172                 </para>
 173
 174                 <para>Though 2 byte fixed UCS-2 encoding is used in Windows internally,
 175                 Shift_JIS series encoding is usually used in Japanese environments
 176                 as ASCII encoding is in English environments.
 177         </para></listitem>
 178 </itemizedlist>
 179
 180 <sect2><title>Basic Parameter Setting</title>
 181
 182         <para>
 183         <smbconfoption><name>dos charset</name></smbconfoption> and
 184         <smbconfoption><name>display charset</name></smbconfoption>
 185         should be set to the locale compatible with the character set
 186         and encoding method used on Windows. This is usually CP932
 187         but sometimes has a different name.
 188         </para>
 189
 190         <para>
 191         <smbconfoption><name>unix charset</name></smbconfoption> can be either Shift_JIS series,
 192         EUC-JP series and UTF-8. UTF-8 is always available but the availability of other locales
 193         and its name itself depends on the system.
 194         </para>
 195
 196         <para>
 197         Additionally, you can consider to use the Shift_JIS series as the
 198         value of the <smbconfoption><name>unix charset</name></smbconfoption>
 199         parameter by using the vfs_cap module, which does the same thing as
 200         setting <quote>coding system = CAP</quote> in the Samba 2.2 series.
 201         </para>
 202
 203         <para>
 204         Where to set <smbconfoption><name>unix charset</name></smbconfoption>
 205         to is a difficult question. Here is a list of details, advantages and
 206         disadvantages of using a certain value.
 207         </para>
 208
 209         <variablelist>
 210                 <varlistentry><term>Shift_JIS series</term>
 211                         <listitem><para>
 212                         Shift_JIS series means a locale which is equivalent to <constant>Shift_JIS</constant>,
 213                         used as a standard on Japanese Windows. In the case of <constant>Shift_JIS</constant>,
 214                         for example if a Japanese file name consist of 0x8ba4 and 0x974c
 215                         (a 4 bytes Japanese character string meaning <quote>share</quote>) and <quote>.txt</quote>
 216                         is written from Windows on Samba, the file name on UNIX becomes
 217                         0x8ba4, 0x974c, <quote>.txt</quote> (a 8 bytes BINARY string), same as Windows.
 218                         </para>
 219
 220                         <para>Since Shift_JIS series is usually used on some commercial based
 221                         UNIX's; hp-ux and AIX as Japanese locale (however, it is also possible
 222                         to use the EUC-JP series), To use Shift_JIS series on these platforms,
 223                         Japanese file names created from Windows can be referred to also on
 224                         UNIX.</para>
 225
 226                         <para>
 227                         If your UNIX is already working with Shift_JIS and there is a user
 228                         who needs to use Japanese file names written from Windows, the
 229                         Shift_JIS series is the best choice.  However, broken file names
 230                         may be displayed and some commands which cannot handle non-ASCII
 231                         filenames may be aborted during parsing filenames. especially there
 232                         may be <quote>\ (0x5c)</quote> in file names, which need to be handled carefully.
 233                         So you had better not touch file names written from Windows on UNIX.
 234                         </para>
 235
 236                         <para>
 237                         Note that most Japanized free software actually works with EUC-JP
 238                         only. You had better verify if the Japanized free software can work
 239                         with Shift_JIS.
 240                         </para>
 241                         </listitem>
 242                 </varlistentry>
 243
 244                 <varlistentry><term>EUC-JP series</term>
 245                         <listitem><para>
 246                         EUC-JP series means a locale which is equivalent to the industry
 247                         standard called EUC-JP, widely used in Japanese UNIX (although EUC
 248                         contains specifications for languages other than Japanese, such as
 249                         EUC-KR). In the case of EUC-JP series, for example if a Japanese
 250                         file name consist of 0x8ba4 and 0x974c and <quote>.txt</quote> is written from
 251                         Windows on Samba, the file name on UNIX becomes 0xb6a6, 0xcdad,
 252                         <quote>.txt</quote> (a 8 bytes BINARY string).
 253                         </para>
 254
 255                         <para>
 256                         Since EUC-JP is usually used on Open source UNIX, Linux and FreeBSD,
 257                         and on commercial based UNIX, Solaris, IRIX and Tru64 UNIX as
 258                         Japanese locale (however, it is also possible on Solaris to use
 259                         Shift_JIS and UTF-8, on Tru64 UNIX to use Shift_JIS). To use EUC-JP
 260                         series, most Japanese file names created from Windows can be
 261                         referred to also on UNIX. Also, most Japanized free software work
 262                         mainly with EUC-JP only.
 263                         </para>
 264
 265                         <para>
 266                         It is recommended to choose EUC-JP series when using Japanese file
 267                         names on these UNIX.
 268                         </para>
 269
 270                         <para>
 271                         Although there is no character which needs to be carefully treated
 272                         like <quote>\ (0x5c)</quote>, broken file names may be displayed and some
 273                         commands which cannot handle non-ASCII filenames may be aborted
 274                         during parsing filenames.
 275                         </para>
 276
 277                         <para>
 278                         Moreover, if you built Samba using differently installed libiconv,
 279                         eucJP-ms locale included in libiconv and EUC-JP series locale
 280                         included in OS may not be compatible. In this case, you may need to
 281                         avoid using incompatible characters for file names.
 282                         </para>
 283                         </listitem>
 284                 </varlistentry>
 285
 286                 <varlistentry><term>UTF-8</term>
 287                         <listitem><para>
 288                         UTF-8 means a locale which is equivalent to UTF-8, the international
 289                         standard defined by Unicode consortium. In UTF-8, a <parameter>character</parameter> is
 290                         expressed using 1-3 bytes. In case of Japanese, most characters
 291                         are expressed using 3 bytes. Since on Windows Shift_JIS, where a
 292                         character is expressed with 1 or 2 bytes, is used to express
 293                         Japanese, basically a byte length of a UTF-8 string grows 1.5 times
 294                         the length of a original Shift_JIS string. In the case of UTF-8,
 295                         for example if a Japanese file name consist of 0x8ba4 and 0x974c and
 296                         <quote>.txt</quote> is written from Windows on Samba, the file name on UNIX
 297                         becomes 0xe585, 0xb1e6, 0x9c89, <quote>.txt</quote> (a 10 bytes BINARY string).
 298                         </para>
 299
 300                         <para>
 301                         For systems where iconv() is not available or where iconv()'s locales
 302                         are not compatible with Windows, UTF-8 is the only locale available.
 303                         </para>
 304
 305                         <para>
 306                         There are no systems that use UTF-8 as default locale for Japanese.
 307                         </para>
 308
 309                         <para>
 310                         Some broken file names may be displayed and some commands which
 311                         cannot handle non-ASCII filenames may be aborted during parsing
 312                         filenames. especially there may be <quote>\ (0x5c)</quote> in file names, which
 313                         need to be handled carefully. So you had better not touch file names
 314                         written from Windows on UNIX.
 315                         </para>
 316
 317                         <para>
 318                         In addition, although it is not directly concerned with Samba, since
 319                         there is a delicate difference between iconv() function, which is
 320                         generally used on UNIX and the functions used on other platforms,
 321                         such as Windows and Java about the conversion table between
 322                         Shift_JIS and Unicode, you should be carefully to handle UTF-8.
 323                         </para>
 324
 325                         <para>
 326                         Although Mac OS X uses UTF-8 as its encoding method for filenames,
 327                         it uses an extended UTF-8 specification that Samba cannot handle so
 328                         UTF-8 locale is not available for Mac OS X.
 329                         </para>
 330                         </listitem>
 331                 </varlistentry>
 332
 333                 <varlistentry><term>Shift_JIS series + vfs_cap (CAP encoding)</term>
 334                         <listitem><para>
 335                         CAP encoding means a specification using in CAP and NetAtalk, file
 336                         server software for Macintosh. In the case of CAP encoding, for
 337                         example if a Japanese file name consist of 0x8ba4 and 0x974c and
 338                         <quote>.txt</quote> is written from Windows on Samba, the file name on UNIX
 339                         becomes <quote>:8b:a4:97L.txt</quote> (a 14 bytes ASCII string).
 340                         </para>
 341
 342                         <para>
 343                         For CAP encoding a byte which cannot be expressed as an ASCII
 344                         character (0x80 or above) is encoded as <quote>:xx</quote> form. You need to take
 345                         care of containing a <quote>\(0x5c)</quote> in a filename but filenames are not
 346                         broken in a system which cannot handle non-ASCII filenames.
 347                         </para>
 348
 349                         <para>
 350                         The greatest merit of CAP encoding is the compatibility of encoding
 351                         filenames with CAP or NetAtalk, file server software of Macintosh.
 352                         Since they usually write a file name on UNIX with CAP encoding, if a
 353                         directory is shared with both Samba and NetAtalk, you need to use
 354                         CAP encoding to avoid non-ASCII filenames are broken.
 355                         </para>
 356
 357                         <para>
 358                         However, recently there are some systems where NetAtalk has been
 359                         patched to write filenames with EUC-JP (i.e. Japanese original Vine Linux).
 360                         Here you need to choose EUC-JP series instead of CAP encoding.
 361                         </para>
 362
 363                         <para>
 364                         vfs_cap itself is available for non Shift_JIS series locales for
 365                         systems which cannot handle non-ASCII characters or systems which
 366                         shares files with NetAtalk.
 367                         </para>
 368
 369                         <para>
 370                         To use CAP encoding on Samba-3, you should use the unix charset parameter and VFS
 371                         as follows:
 372                         </para>
 373
 374 <smbconfexample><title>VFS CAP</title>
 375 <smbconfsection>[global]</smbconfsection>
 376 <smbconfoption><name>dos charset</name><value>CP932<footnote><para>the locale name "CP932" may be different name</para></footnote></value></smbconfoption>
 377 <smbconfoption><name>unix charset</name><value>CP932</value></smbconfoption>
 378
 379 <member><para>...</para></member>
 380
 381 <smbconfsection>[cap-share]</smbconfsection>
 382 <smbconfoption><name>vfs option</name><value>cap</value></smbconfoption>
 383 </smbconfexample>
 384
 385                         <para>
 386                         You should set CP932 if using GNU libiconv for unix charset. Setting this,
 387                         filenames in the <quote>cap-share</quote> share are written with CAP encoding.
 388                         </para>
 389                         </listitem>
 390                 </varlistentry>
 391         </variablelist>
 392
 393 </sect2>
 394
 395 <sect2><title>Individual Implementations</title>
 396
 397 <para>
 398 Here is some additional information regarding individual implementations:
 399 </para>
 400
 401         <variablelist>
 402                 <varlistentry><term>GNU libiconv</term>
 403                         <listitem><para>
 404                         To handle Japanese correctly, you should apply the patch
 405                         <ulink url="http://www2d.biglobe.ne.jp/~msyk/software/libiconv-patch.html">libiconv-1.8-cp932-patch.diff.gz</ulink>
 406                         to libiconv-1.8.
 407                         </para>
 408
 409                         <para>
 410                         Using the patched libiconv-1.8, these settings are available:
 411                         </para>
 412
 413
 414 <!-- FIXME: Convert to diagram ? -->
 415 <programlisting>
 416 dos charset = CP932
 417 unix charset = CP932 / eucJP-ms / UTF-8
 418                 |       |
 419                 |       +-- EUC-JP series
 420                 +-- Shift_JIS series
 421 display charset = CP932
 422 </programlisting>
 423
 424                         <para>
 425                         Other Japanese locales (for example Shift_JIS and EUC-JP) should not
 426                         be used for the lack of the compatibility with Windows.
 427                         </para>
 428                         </listitem>
 429                 </varlistentry>
 430
 431                 <varlistentry><term>GNU glibc</term>
 432                         <listitem><para>
 433                         To handle Japanese correctly, you should apply a <ulink url="http://www2d.biglobe.ne.jp/~msyk/software/glibc/">patch</ulink>
 434                         to glibc-2.2.5/2.3.1/2.3.2 or should use the patch-merged versions, glibc-2.3.3 or later.
 435                         </para>
 436
 437                         <para>
 438                         Using the above glibc, these setting are available:
 439                         </para>
 440
 441 <smbconfblock>
 442 <smbconfoption><name>dos charset</name><value>CP932</value></smbconfoption>
 443 <smbconfoption><name>unix charset</name><value>CP932 / eucJP-ms / UTF-8</value></smbconfoption>
 444 <smbconfoption><name>display charset</name><value>CP932</value></smbconfoption>
 445 </smbconfblock>
 446
 447                         <para>
 448                         Other Japanese locales (for example Shift_JIS and EUC-JP) should not
 449                         be used for the lack of the compatibility with Windows.
 450                         </para>
 451                         </listitem>
 452                 </varlistentry>
 453         </variablelist>
 454
 455 </sect2>
 456
 457 <sect2>
 458         <title>Migration from Samba-2.2 Series</title>
 459
 460 <para>
 461 Prior to Samba-2.2 series <quote>coding system</quote> parameter is used as
 462 <smbconfoption><name>unix charset</name></smbconfoption> parameter of the Samba-3 series.
 463 <link linkend="japancharsets">Next table</link> shows the mapping table when migrating from the Samba-2.2 series to Samba-3.
 464 </para>
 465
 466         <table frame="all" id="japancharsets">
 467                 <title>Japanese Character Sets in Samba-2.2 and Samba-3</title>
 468
 469                 <tgroup cols="2" align="center">
 470                         <colspec align="center"/>
 471                         <colspec align="center"/>
 472                         <thead>
 473                                 <row><entry>Samba-2.2 Coding System</entry><entry>Samba-3 unix charset</entry></row>
 474                         </thead>
 475                         <tbody>
 476                                 <row><entry>SJIS</entry><entry>Shift_JIS series</entry></row>
 477                                 <row><entry>EUC</entry><entry>EUC-JP series</entry></row>
 478                                 <row><entry>EUC3<footnote><para>Only exists in Japanese Samba version</para></footnote></entry><entry>EUC-JP series</entry></row>
 479                                 <row><entry>CAP</entry><entry>Shift_JIS series + VFS</entry></row>
 480                                 <row><entry>HEX</entry><entry>currently none</entry></row>
 481                                 <row><entry>UTF8</entry><entry>UTF-8</entry></row>
 482                                 <row><entry>UTF8-Mac<footnote><para>Only exists in Japanese Samba version</para></footnote></entry><entry>currently none</entry></row>
 483                                 <row><entry>others</entry><entry>none</entry></row>
 484                         </tbody>
 485                 </tgroup>
 486         </table>
 487
 488 </sect2>
 489
 490 </sect1>
 491
 492 <sect1>
 493         <title>Common Errors</title>
 494
 495         <sect2>
 496                 <title>CP850.so Can't Be Found</title>
 497
 498                 <para><quote>Samba is complaining about a missing <filename>CP850.so</filename> file.</quote></para>
 499
 500                 <para><emphasis>Answer:</emphasis> CP850 is the default <smbconfoption><name>dos charset</name></smbconfoption>.
 501                 The <smbconfoption><name>dos charset</name></smbconfoption> is used to convert data to the codepage used by your dos clients.
 502                 If you do not have any dos clients, you can safely ignore this message. </para>
 503
 504                 <para>CP850 should be supported by your local iconv implementation. Make sure you have all the required packages installed.
 505                 If you compiled Samba from source, make sure to configure found iconv.</para>
 506         </sect2>
 507 </sect1>
 508
 509 </chapter>