<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 27. Unicode/Charsets</title><link rel="stylesheet" href="samba.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.61.2"><link rel="home" href="index.html" title="Samba HOWTO Collection"><link rel="up" href="optional.html" title="Part III. Advanced Configuration"><link rel="previous" href="integrate-ms-networks.html" title="Chapter 26. Integrating MS Windows Networks with Samba"><link rel="next" href="Backup.html" title="Chapter 28. Samba Backup Techniques"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 27. Unicode/Charsets</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="integrate-ms-networks.html">Prev</a> </td><th width="60%" align="center">Part III. Advanced Configuration</th><td width="20%" align="right"> <a accesskey="n" href="Backup.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="unicode"></a>Chapter 27. Unicode/Charsets</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Jelmer</span> <span class="othername">R.</span> <span class="surname">Vernooij</span></h3><div class="affiliation"><span class="orgname">The Samba Team<br></span><div class="address"><p><tt class="email"><<a href="mailto:jelmer@samba.org">jelmer@samba.org</a>></tt></p></div></div></div></div><div><div class="author"><h3 class="author"><span class="firstname">John</span> <span class="othername">H.</span> <span class="surname">Terpstra</span></h3><div class="affiliation"><span class="orgname">Samba Team<br></span><div class="address"><p><tt class="email"><<a href="mailto:jht@samba.org">jht@samba.org</a>></tt></p></div></div></div></div><div><div class="author"><h3 class="author"><span class="firstname">TAKAHASHI</span> <span class="surname">Motonobu</span></h3><span class="contrib">Japanese character support</span><div class="affiliation"><div class="address"><p><tt class="email"><<a href="mailto:monyo@home.monyo.com">monyo@home.monyo.com</a>></tt></p></div></div></div></div><div><p class="pubdate">25 March 2003</p></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="unicode.html#id2967369">Features and Benefits</a></dt><dt><a href="unicode.html#id2967413">What Are Charsets and Unicode?</a></dt><dt><a href="unicode.html#id2967502">Samba and Charsets</a></dt><dt><a href="unicode.html#id2967622">Conversion from Old Names</a></dt><dt><a href="unicode.html#id2967652">Japanese Charsets</a></dt><dd><dl><dt><a href="unicode.html#id2967727">Basic Parameter Setting</a></dt><dt><a href="unicode.html#id2968252">Individual Implementations</a></dt><dt><a href="unicode.html#id2968418">Migration from Samba-2.2 Series</a></dt></dl></dd><dt><a href="unicode.html#id2968590">Common Errors</a></dt><dd><dl><dt><a href="unicode.html#id2968598">CP850.so Can't Be Found</a></dt></dl></dd></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2967369"></a>Features and Benefits</h2></div></div><div></div></div><p> Every industry eventually matures. One of the great areas of maturation is in the focus that has been given over the past decade to make it possible for anyone anywhere to use a computer. It has not always been that way, in fact, not so long ago it was common for software to be written for exclusive use in the country of origin. </p><p> Of all the effort that has been brought to bear on providing native language support for all computer users, the efforts of the <a href="http://www.openi18n.org/" target="_top">Openi18n organization</a> is deserving of special mention. </p><p> Samba-2.x supported a single locale through a mechanism called <span class="emphasis"><em>codepages</em></span>. Samba-3 is destined to become a truly trans-global file and printer-sharing platform. </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2967413"></a>What Are Charsets and Unicode?</h2></div></div><div></div></div><p> Computers communicate in numbers. In texts, each number will be translated to a corresponding letter. The meaning that will be assigned to a certain number depends on the <span class="emphasis"><em>character set (charset) </em></span> that is used. </p><p> A charset can be seen as a table that is used to translate numbers to letters. Not all computers use the same charset (there are charsets with German umlauts, Japanese characters, and so on). The American Standard Code for Information Interchange (ASCII) encoding system has been the normative character encoding scheme used by computers to date. This employs a charset that contains 256 characters. Using this mode of encoding each character takes exactly one byte. </p><p> There are also charsets that support extended characters, but those need at least twice as much storage space as does ASCII encoding. Such charsets can contain <b class="command">256 * 256 = 65536</b> characters, which is more than all possible characters one could think of. They are called multi-byte charsets because they use more then one byte to store one character. </p><p> One standardized multi-byte charset encoding scheme is known as <a href="http://www.unicode.org/" target="_top">unicode</a>. A big advantage of using a multi-byte charset is that you only need one. There is no need to make sure two computers use the same charset when they are communicating. </p><p>Old Windows clients use single-byte charsets, named <i class="parameter"><tt>codepages</tt></i>, by Microsoft. However, there is no support for negotiating the charset to be used in the SMB/CIFS protocol. Thus, you have to make sure you are using the same charset when talking to an older client. Newer clients (Windows NT, 200x, XP) talk unicode over the wire. </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2967502"></a>Samba and Charsets</h2></div></div><div></div></div><p> As of Samba-3, Samba can (and will) talk unicode over the wire. Internally, Samba knows of three kinds of character sets: </p><div class="variablelist"><dl><dt><span class="term"><a class="indexterm" name="id2967524"></a>unix charset</span></dt><dd><p> This is the charset used internally by your operating system. The default is <tt class="constant">UTF-8</tt>, which is fine for most systems, which covers all characters in all languages. The default in previous Samba releases was <tt class="constant">ASCII</tt>. </p></dd><dt><span class="term"><a class="indexterm" name="id2967558"></a>display charset</span></dt><dd><p>This is the charset Samba will use to print messages on your screen. It should generally be the same as the <i class="parameter"><tt>unix charset</tt></i>. </p></dd><dt><span class="term"><a class="indexterm" name="id2967588"></a>dos charset</span></dt><dd><p>This is the charset Samba uses when communicating with DOS and Windows 9x/Me clients. It will talk unicode to all newer clients. The default depends on the charsets you have installed on your system. Run <b class="command">testparm -v | grep “<span class="quote"><span class="emphasis"><em>dos charset</em></span></span>”</b> to see what the default is on your system. </p></dd></dl></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2967622"></a>Conversion from Old Names</h2></div></div><div></div></div><p>Because previous Samba versions did not do any charset conversion, characters in filenames are usually not correct in the UNIX charset but only for the local charset used by the DOS/Windows clients.</p><p>Bjoern Jacke has written a utility named <a href="http://j3e.de/linux/convmv/" target="_top">convmv</a> that can convert whole directory structures to different charsets with one single command. </p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2967652"></a>Japanese Charsets</h2></div></div><div></div></div><p> Setting up Japanese charsets is quite difficult. This is mainly because: </p><div class="itemizedlist"><ul type="disc"><li><p>The Windows character set is extended from the original legacy Japanese standard (JIS X 0208) and is not standardized. This means that the strictly standardized implementation cannot support the full Windows character set. </p></li><li><p> Mainly for historical reasons, there are several encoding methods in Japanese, which are not fully compatible with each other. There are two major encoding methods. One is the Shift_JIS series, it is used in Windows and some UNIX's. The other is the EUC-JP series, used in most UNIX's and Linux. Moreover, Samba previously also offered several unique encoding methods, named CAP and HEX, to keep interoperability with CAP/NetAtalk and UNIX's which can't use Japanese filenames. Some implementations of the EUC-JP series can't support the full Windows character set. </p></li><li><p>There are some code conversion tables between Unicode and legacy Japanese character sets. One is compatible with Windows, another one is based on the reference of the Unicode consortium and others are a mixed implementation. The Unicode consortium does not officially define any conversion tables between Unicode and legacy character sets so there cannot be standard one. </p></li><li><p>The character set and conversion tables available in iconv() depends on the iconv library that is available. Next to that, the Japanese locale names may be different on different systems. This means that the value of the charset parameters depends on the implementation of iconv() you are using. </p><p>Though 2 byte fixed UCS-2 encoding is used in Windows internally, Shift_JIS series encoding is usually used in Japanese environments as ASCII encoding is in English environments. </p></li></ul></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2967727"></a>Basic Parameter Setting</h3></div></div><div></div></div><p> <a class="indexterm" name="id2967736"></a>dos charset and <a class="indexterm" name="id2967745"></a>display charset should be set to the locale compatible with the character set and encoding method used on Windows. This is usually CP932 but sometimes has a different name. </p><p> <a class="indexterm" name="id2967760"></a>unix charset can be either Shift_JIS series, EUC-JP series and UTF-8. UTF-8 is always available but the availability of other locales and its name itself depends on the system. </p><p> Additionally, you can consider to use the Shift_JIS series as the value of the <a class="indexterm" name="id2967778"></a>unix charset parameter by using the vfs_cap module, which does the same thing as setting “<span class="quote"><span class="emphasis"><em>coding system = CAP</em></span></span>” in the Samba 2.2 series. </p><p> Where to set <a class="indexterm" name="id2967798"></a>unix charset to is a difficult question. Here is a list of details, advantages and disadvantages of using a certain value. </p><div class="variablelist"><dl><dt><span class="term">Shift_JIS series</span></dt><dd><p> Shift_JIS series means a locale which is equivalent to <tt class="constant">Shift_JIS</tt>, used as a standard on Japanese Windows. In the case of <tt class="constant">Shift_JIS</tt>, for example if a Japanese file name consist of 0x8ba4 and 0x974c (a 4 bytes Japanese character string meaning “<span class="quote"><span class="emphasis"><em>share</em></span></span>”) and “<span class="quote"><span class="emphasis"><em>.txt</em></span></span>” is written from Windows on Samba, the file name on UNIX becomes 0x8ba4, 0x974c, “<span class="quote"><span class="emphasis"><em>.txt</em></span></span>” (a 8 bytes BINARY string), same as Windows. </p><p>Since Shift_JIS series is usually used on some commercial based UNIX's; hp-ux and AIX as Japanese locale (however, it is also possible to use the EUC-JP series), To use Shift_JIS series on these platforms, Japanese file names created from Windows can be referred to also on UNIX.</p><p> If your UNIX is already working with Shift_JIS and there is a user who needs to use Japanese file names written from Windows, the Shift_JIS series is the best choice. However, broken file names may be displayed and some commands which cannot handle non-ASCII filenames may be aborted during parsing filenames. especially there may be “<span class="quote"><span class="emphasis"><em>\ (0x5c)</em></span></span>” in file names, which need to be handled carefully. So you had better not touch file names written from Windows on UNIX. </p><p> Note that most Japanized free software actually works with EUC-JP only. You had better verify if the Japanized free software can work with Shift_JIS. </p></dd><dt><span class="term">EUC-JP series</span></dt><dd><p> EUC-JP series means a locale which is equivalent to the industry standard called EUC-JP, widely used in Japanese UNIX (although EUC contains specifications for languages other than Japanese, such as EUC-KR). In the case of EUC-JP series, for example if a Japanese file name consist of 0x8ba4 and 0x974c and “<span class="quote"><span class="emphasis"><em>.txt</em></span></span>” is written from Windows on Samba, the file name on UNIX becomes 0xb6a6, 0xcdad, “<span class="quote"><span class="emphasis"><em>.txt</em></span></span>” (a 8 bytes BINARY string). </p><p> Since EUC-JP is usually used on Open source UNIX, Linux and FreeBSD, and on commercial based UNIX, Solaris, IRIX and Tru64 UNIX as Japanese locale (however, it is also possible on Solaris to use Shift_JIS and UTF-8, on Tru64 UNIX to use Shift_JIS). To use EUC-JP series, most Japanese file names created from Windows can be referred to also on UNIX. Also, most Japanized free software work mainly with EUC-JP only. </p><p> It is recommended to choose EUC-JP series when using Japanese file names on these UNIX. </p><p> Although there is no character which needs to be carefully treated like “<span class="quote"><span class="emphasis"><em>\ (0x5c)</em></span></span>”, broken file names may be displayed and some commands which cannot handle non-ASCII filenames may be aborted during parsing filenames. </p><p> Moreover, if you built Samba using differently installed libiconv, eucJP-ms locale included in libiconv and EUC-JP series locale included in OS may not be compatible. In this case, you may need to avoid using incompatible characters for file names. </p></dd><dt><span class="term">UTF-8</span></dt><dd><p> UTF-8 means a locale which is equivalent to UTF-8, the international standard defined by Unicode consortium. In UTF-8, a <i class="parameter"><tt>character</tt></i> is expressed using 1-3 bytes. In case of Japanese, most characters are expressed using 3 bytes. Since on Windows Shift_JIS, where a character is expressed with 1 or 2 bytes, is used to express Japanese, basically a byte length of a UTF-8 string grows 1.5 times the length of a original Shift_JIS string. In the case of UTF-8, for example if a Japanese file name consist of 0x8ba4 and 0x974c and “<span class="quote"><span class="emphasis"><em>.txt</em></span></span>” is written from Windows on Samba, the file name on UNIX becomes 0xe585, 0xb1e6, 0x9c89, “<span class="quote"><span class="emphasis"><em>.txt</em></span></span>” (a 10 bytes BINARY string). </p><p> For systems where iconv() is not available or where iconv()'s locales are not compatible with Windows, UTF-8 is the only locale available. </p><p> There are no systems that use UTF-8 as default locale for Japanese. </p><p> Some broken file names may be displayed and some commands which cannot handle non-ASCII filenames may be aborted during parsing filenames. especially there may be “<span class="quote"><span class="emphasis"><em>\ (0x5c)</em></span></span>” in file names, which need to be handled carefully. So you had better not touch file names written from Windows on UNIX. </p><p> In addition, although it is not directly concerned with Samba, since there is a delicate difference between iconv() function, which is generally used on UNIX and the functions used on other platforms, such as Windows and Java about the conversion table between Shift_JIS and Unicode, you should be carefully to handle UTF-8. </p><p> Although Mac OS X uses UTF-8 as its encoding method for filenames, it uses an extended UTF-8 specification that Samba cannot handle so UTF-8 locale is not available for Mac OS X. </p></dd><dt><span class="term">Shift_JIS series + vfs_cap (CAP encoding)</span></dt><dd><p> CAP encoding means a specification using in CAP and NetAtalk, file server software for Macintosh. In the case of CAP encoding, for example if a Japanese file name consist of 0x8ba4 and 0x974c and “<span class="quote"><span class="emphasis"><em>.txt</em></span></span>” is written from Windows on Samba, the file name on UNIX becomes “<span class="quote"><span class="emphasis"><em>:8b:a4:97L.txt</em></span></span>” (a 14 bytes ASCII string). </p><p> For CAP encoding a byte which cannot be expressed as an ASCII character (0x80 or above) is encoded as “<span class="quote"><span class="emphasis"><em>:xx</em></span></span>” form. You need to take care of containing a “<span class="quote"><span class="emphasis"><em>\(0x5c)</em></span></span>” in a filename but filenames are not broken in a system which cannot handle non-ASCII filenames. </p><p> The greatest merit of CAP encoding is the compatibility of encoding filenames with CAP or NetAtalk, file server software of Macintosh. Since they usually write a file name on UNIX with CAP encoding, if a directory is shared with both Samba and NetAtalk, you need to use CAP encoding to avoid non-ASCII filenames are broken. </p><p> However, recently there are some systems where NetAtalk has been patched to write filenames with EUC-JP (i.e. Japanese original Vine Linux). Here you need to choose EUC-JP series instead of CAP encoding. </p><p> vfs_cap itself is available for non Shift_JIS series locales for systems which cannot handle non-ASCII characters or systems which shares files with NetAtalk. </p><p> To use CAP encoding on Samba-3, you should use the unix charset parameter and VFS as follows: </p><div class="example"><a name="id2968141"></a><p class="title"><b>Example 27.1. VFS CAP</b></p><table class="simplelist" border="0" summary="Simple list"><tr><td> </td></tr><tr><td><i class="parameter"><tt>[global]</tt></i></td></tr><tr><td><i class="parameter"><tt> dos charset = CP932the locale name "CP932" may be different name</tt></i></td></tr><tr><td><i class="parameter"><tt> unix charset = CP932</tt></i></td></tr><tr><td><p>...</p></td></tr><tr><td> </td></tr><tr><td><i class="parameter"><tt>[cap-share]</tt></i></td></tr><tr><td><i class="parameter"><tt> vfs option = cap</tt></i></td></tr></table></div><p> You should set CP932 if using GNU libiconv for unix charset. Setting this, filenames in the “<span class="quote"><span class="emphasis"><em>cap-share</em></span></span>” share are written with CAP encoding. </p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2968252"></a>Individual Implementations</h3></div></div><div></div></div><p> Here is some additional information regarding individual implementations: </p><div class="variablelist"><dl><dt><span class="term">GNU libiconv</span></dt><dd><p> To handle Japanese correctly, you should apply the patch <a href="http://www2d.biglobe.ne.jp/~msyk/software/libiconv-patch.html" target="_top">libiconv-1.8-cp932-patch.diff.gz</a> to libiconv-1.8. </p><p> Using the patched libiconv-1.8, these settings are available: </p><pre class="programlisting"> dos charset = CP932 unix charset = CP932 / eucJP-ms / UTF-8 | | | +-- EUC-JP series +-- Shift_JIS series display charset = CP932 </pre><p> Other Japanese locales (for example Shift_JIS and EUC-JP) should not be used for the lack of the compatibility with Windows. </p></dd><dt><span class="term">GNU glibc</span></dt><dd><p> To handle Japanese correctly, you should apply a <a href="http://www2d.biglobe.ne.jp/~msyk/software/glibc/" target="_top">patch</a> to glibc-2.2.5/2.3.1/2.3.2 or should use the patch-merged versions, glibc-2.3.3 or later. </p><p> Using the above glibc, these setting are available: </p><table class="simplelist" border="0" summary="Simple list"><tr><td><i class="parameter"><tt> dos charset = CP932</tt></i></td></tr><tr><td><i class="parameter"><tt> unix charset = CP932 / eucJP-ms / UTF-8</tt></i></td></tr><tr><td><i class="parameter"><tt> display charset = CP932</tt></i></td></tr></table><p> Other Japanese locales (for example Shift_JIS and EUC-JP) should not be used for the lack of the compatibility with Windows. </p></dd></dl></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2968418"></a>Migration from Samba-2.2 Series</h3></div></div><div></div></div><p> Prior to Samba-2.2 series “<span class="quote"><span class="emphasis"><em>coding system</em></span></span>” parameter is used as <a class="indexterm" name="id2968436"></a>unix charset parameter of the Samba-3 series. <a href="unicode.html#japancharsets" title="Table 27.1. Japanese Character Sets in Samba-2.2 and Samba-3">Next table</a> shows the mapping table when migrating from the Samba-2.2 series to Samba-3. </p><div class="table"><a name="japancharsets"></a><p class="title"><b>Table 27.1. Japanese Character Sets in Samba-2.2 and Samba-3</b></p><table summary="Japanese Character Sets in Samba-2.2 and Samba-3" border="1"><colgroup><col align="center"><col align="center"></colgroup><thead><tr><th align="center">Samba-2.2 Coding System</th><th align="center">Samba-3 unix charset</th></tr></thead><tbody><tr><td align="center">SJIS</td><td align="center">Shift_JIS series</td></tr><tr><td align="center">EUC</td><td align="center">EUC-JP series</td></tr><tr><td align="center">EUC3<sup>[<a name="id2968529" href="#ftn.id2968529">a</a>]</sup></td><td align="center">EUC-JP series</td></tr><tr><td align="center">CAP</td><td align="center">Shift_JIS series + VFS</td></tr><tr><td align="center">HEX</td><td align="center">currently none</td></tr><tr><td align="center">UTF8</td><td align="center">UTF-8</td></tr><tr><td align="center">UTF8-Mac<sup>[<a name="id2968568" href="#ftn.id2968568">b</a>]</sup></td><td align="center">currently none</td></tr><tr><td align="center">others</td><td align="center">none</td></tr></tbody><tbody class="footnotes"><tr><td colspan="2"><div class="footnote"><p><sup>[<a name="ftn.id2968529" href="#id2968529">a</a>] </sup>Only exists in Japanese Samba version</p></div><div class="footnote"><p><sup>[<a name="ftn.id2968568" href="#id2968568">b</a>] </sup>Only exists in Japanese Samba version</p></div></td></tr></tbody></table></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2968590"></a>Common Errors</h2></div></div><div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2968598"></a>CP850.so Can't Be Found</h3></div></div><div></div></div><p>“<span class="quote"><span class="emphasis"><em>Samba is complaining about a missing <tt class="filename">CP850.so</tt> file.</em></span></span>”</p><p><span class="emphasis"><em>Answer:</em></span> CP850 is the default <a class="indexterm" name="id2968626"></a>dos charset. The <a class="indexterm" name="id2968634"></a>dos charset is used to convert data to the codepage used by your dos clients. If you do not have any dos clients, you can safely ignore this message. </p><p>CP850 should be supported by your local iconv implementation. Make sure you have all the required packages installed. If you compiled Samba from source, make sure to configure found iconv.</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="integrate-ms-networks.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="optional.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="Backup.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 26. Integrating MS Windows Networks with Samba </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 28. Samba Backup Techniques</td></tr></table></div></body></html>