(Tips for Installtion): New section.

[glibc.git] / manual / mbyte.texi

@node Extended Characters, Locales, String and Array Utilities, Top
@chapter Extended Characters

A number of languages use character sets that are larger than the range
of values of type @code{char}.  Japanese and Chinese are probably the
most familiar examples.

The GNU C library includes support for two mechanisms for dealing with
extended character sets: multibyte characters and wide characters.  This
chapter describes how to use these mechanisms, and the functions for
converting between them.
@cindex extended character sets

The behavior of the functions in this chapter is affected by the current
locale for character classification---the @code{LC_CTYPE} category; see
@ref{Locale Categories}.  This choice of locale selects which multibyte
code is used, and also controls the meanings and characteristics of wide
character codes.

@menu
* Extended Char Intro::         Multibyte codes versus wide characters.
* Locales and Extended Chars::  The locale selects the character codes.
* Multibyte Char Intro::        How multibyte codes are represented.
* Wide Char Intro::             How wide characters are represented.
* Wide String Conversion::      Converting wide strings to multibyte code
                                 and vice versa.
* Length of Char::              how many bytes make up one multibyte char.
* Converting One Char::         Converting a string character by character.
* Example of Conversion::       Example showing why converting
                                 one character at a time may be useful.
* Shift State::                 Multibyte codes with "shift characters".
@end menu

@node Extended Char Intro, Locales and Extended Chars,  , Extended Characters
@section Introduction to Extended Characters

You can represent extended characters in either of two ways:

@itemize @bullet
@item
As @dfn{multibyte characters} which can be embedded in an ordinary
string, an array of @code{char} objects.  Their advantage is that many
programs and operating systems can handle occasional multibyte
characters scattered among ordinary ASCII characters, without any
change.

@item
@cindex wide characters
As @dfn{wide characters}, which are like ordinary characters except that
they occupy more bits.  The wide character data type, @code{wchar_t},
has a range large enough to hold extended character codes as well as
old-fashioned ASCII codes.

An advantage of wide characters is that each character is a single data
object, just like ordinary ASCII characters.  There are a few
disadvantages:

@itemize @bullet
@item
Each existing program must be modified and recompiled to make it use
wide characters.

@item
Files of wide characters cannot be read by programs that expect ordinary
characters.
@end itemize
@end itemize

Typically, you use the multibyte character representation as part of the
external program interface, such as reading or writing text to files.
However, it's usually easier to perform internal manipulations on
strings containing extended characters on arrays of @code{wchar_t}
objects, since the uniform representation makes most editing operations
easier.  If you do use multibyte characters for files and wide
characters for internal operations, you need to convert between them
when you read and write data.

If your system supports extended characters, then it supports them both
as multibyte characters and as wide characters.  The library includes
functions you can use to convert between the two representations.
These functions are described in this chapter.

@node Locales and Extended Chars, Multibyte Char Intro, Extended Char Intro, Extended Characters
@section Locales and Extended Characters

A computer system can support more than one multibyte character code,
and more than one wide character code.  The user controls the choice of
codes through the current locale for character classification
(@pxref{Locales}).  Each locale specifies a particular multibyte
character code and a particular wide character code.  The choice of locale
influences the behavior of the conversion functions in the library.

Some locales support neither wide characters nor nontrivial multibyte
characters.  In these locales, the library conversion functions still
work, even though what they do is basically trivial.

If you select a new locale for character classification, the internal
shift state maintained by these functions can become confused, so it's
not a good idea to change the locale while you are in the middle of
processing a string.

@node Multibyte Char Intro, Wide Char Intro, Locales and Extended Chars, Extended Characters
@section Multibyte Characters
@cindex multibyte characters

In the ordinary ASCII code, a sequence of characters is a sequence of
bytes, and each character is one byte.  This is very simple, but
allows for only 256 distinct characters.

In a @dfn{multibyte character code}, a sequence of characters is a
sequence of bytes, but each character may occupy one or more consecutive
bytes of the sequence.

@cindex basic byte sequence
There are many different ways of designing a multibyte character code;
different systems use different codes.  To specify a particular code
means designating the @dfn{basic} byte sequences---those which represent
a single character---and what characters they stand for.  A code that a
computer can actually use must have a finite number of these basic
sequences, and typically none of them is more than a few characters
long.

These sequences need not all have the same length.  In fact, many of
them are just one byte long.  Because the basic ASCII characters in the
range from @code{0} to @code{0177} are so important, they stand for
themselves in all multibyte character codes.  That is to say, a byte
whose value is @code{0} through @code{0177} is always a character in
itself.  The characters which are more than one byte must always start
with a byte in the range from @code{0200} through @code{0377}.

The byte value @code{0} can be used to terminate a string, just as it is
often used in a string of ASCII characters.

Specifying the basic byte sequences that represent single characters
automatically gives meanings to many longer byte sequences, as more than
one character.  For example, if the two byte sequence @code{0205 049}
stands for the Greek letter alpha, then @code{0205 049 065} must stand
for an alpha followed by an @samp{A} (ASCII code 065), and @code{0205 049
0205 049} must stand for two alphas in a row.

If any byte sequence can have more than one meaning as a sequence of
characters, then the multibyte code is ambiguous---and no good.  The
codes that systems actually use are all unambiguous.

In most codes, there are certain sequences of bytes that have no meaning
as a character or characters.  These are called @dfn{invalid}.

The simplest possible multibyte code is a trivial one:

@quotation
The basic sequences consist of single bytes.
@end quotation

This particular code is equivalent to not using multibyte characters at
all.  It has no invalid sequences.  But it can handle only 256 different
characters.

Here is another possible code which can handle 9376 different
characters:

@quotation
The basic sequences consist of

@itemize @bullet
@item
single bytes with values in the range @code{0} through @code{0237}.

@item
two-byte sequences, in which both of the bytes have values in the range
from @code{0240} through @code{0377}.
@end itemize
@end quotation

@noindent
This code or a similar one is used on some systems to represent Japanese
characters.  The invalid sequences are those which consist of an odd
number of consecutive bytes in the range from @code{0240} through
@code{0377}.

Here is another multibyte code which can handle more distinct extended
characters---in fact, almost thirty million:

@quotation
The basic sequences consist of

@itemize @bullet
@item
single bytes with values in the range @code{0} through @code{0177}.

@item
sequences of up to four bytes in which the first byte is in the range
from @code{0200} through @code{0237}, and the remaining bytes are in the
range from @code{0240} through @code{0377}.
@end itemize
@end quotation

@noindent
In this code, any sequence that starts with a byte in the range
from @code{0240} through @code{0377} is invalid.

And here is another variant which has the advantage that removing the
last byte or bytes from a valid character can never produce another
valid character.  (This property is convenient when you want to search
strings for particular characters.)

@quotation
The basic sequences consist of

@itemize @bullet
@item
single bytes with values in the range @code{0} through @code{0177}.

@item
two-byte sequences in which the first byte is in the range from
@code{0200} through @code{0207}, and the second byte is in the range
from @code{0240} through @code{0377}.

@item
three-byte sequences in which the first byte is in the range from
@code{0210} through @code{0217}, and the other bytes are in the range
from @code{0240} through @code{0377}.

@item
four-byte sequences in which the first byte is in the range from
@code{0220} through @code{0227}, and the other bytes are in the range
from @code{0240} through @code{0377}.
@end itemize
@end quotation

@noindent
The list of invalid sequences for this code is long and not worth
stating in full; examples of invalid sequences include @code{0240} and
@code{0220 0300 065}.

The number of @emph{possible} multibyte codes is astronomical.  But a
given computer system will support at most a few different codes.  (One
of these codes may allow for thousands of different characters.)
Another computer system may support a completely different code.  The
library facilities described in this chapter are helpful because they
package up the knowledge of the details of a particular computer
system's multibyte code, so your programs need not know them.

You can use special standard macros to find out the maximum possible
number of bytes in a character in the currently selected multibyte
code with @code{MB_CUR_MAX}, and the maximum for @emph{any} multibyte
code supported on your computer with @code{MB_LEN_MAX}.

@comment limits.h
@comment ISO
@deftypevr Macro int MB_LEN_MAX
This is the maximum length of a multibyte character for any supported
locale.  It is defined in @file{limits.h}.
@pindex limits.h
@end deftypevr

@comment stdlib.h
@comment ISO
@deftypevr Macro int MB_CUR_MAX
This macro expands into a (possibly non-constant) positive integer
expression that is the maximum number of bytes in a multibyte character
in the current locale.  The value is never greater than @code{MB_LEN_MAX}.

@pindex stdlib.h
@code{MB_CUR_MAX} is defined in @file{stdlib.h}.
@end deftypevr

Normally, each basic sequence in a particular character code stands for
one character, the same character regardless of context.  Some multibyte
character codes have a concept of @dfn{shift state}; certain codes,
called @dfn{shift sequences}, change to a different shift state, and the
meaning of some or all basic sequences varies according to the current
shift state.  In fact, the set of basic sequences might even be
different depending on the current shift state.  @xref{Shift State}, for
more information on handling this sort of code.

What happens if you try to pass a string containing multibyte characters
to a function that doesn't know about them?  Normally, such a function
treats a string as a sequence of bytes, and interprets certain byte
values specially; all other byte values are ``ordinary''.  As long as a
multibyte character doesn't contain any of the special byte values, the
function should pass it through as if it were several ordinary
characters.

For example, let's figure out what happens if you use multibyte
characters in a file name.  The functions such as @code{open} and
@code{unlink} that operate on file names treat the name as a sequence of
byte values, with @samp{/} as the only special value.  Any other byte
values are copied, or compared, in sequence, and all byte values are
treated alike.  Thus, you may think of the file name as a sequence of
bytes or as a string containing multibyte characters; the same behavior
makes sense equally either way, provided no multibyte character contains
a @samp{/}.

@node Wide Char Intro, Wide String Conversion, Multibyte Char Intro, Extended Characters
@section Wide Character Introduction

@dfn{Wide characters} are much simpler than multibyte characters.  They
are simply characters with more than eight bits, so that they have room
for more than 256 distinct codes.  The wide character data type,
@code{wchar_t}, has a range large enough to hold extended character
codes as well as old-fashioned ASCII codes.

An advantage of wide characters is that each character is a single data
object, just like ordinary ASCII characters.  Wide characters also have
some disadvantages:

@itemize @bullet
@item
A program must be modified and recompiled in order to use wide
characters at all.

@item
Files of wide characters cannot be read by programs that expect ordinary
characters.
@end itemize

Wide character values @code{0} through @code{0177} are always identical
in meaning to the ASCII character codes.  The wide character value zero
is often used to terminate a string of wide characters, just as a single
byte with value zero often terminates a string of ordinary characters.

@comment stddef.h
@comment ISO
@deftp {Data Type} wchar_t
This is the ``wide character'' type, an integer type whose range is
large enough to represent all distinct values in any extended character
set in the supported locales.  @xref{Locales}, for more information
about locales.  This type is defined in the header file @file{stddef.h}.
@pindex stddef.h
@end deftp

If your system supports extended characters, then each extended
character has both a wide character code and a corresponding multibyte
basic sequence.

@cindex code, character
@cindex character code
In this chapter, the term @dfn{code} is used to refer to a single
extended character object to emphasize the distinction from the
@code{char} data type.

@node Wide String Conversion, Length of Char, Wide Char Intro, Extended Characters
@section Conversion of Extended Strings
@cindex extended strings, converting representations
@cindex converting extended strings

@pindex stdlib.h
The @code{mbstowcs} function converts a string of multibyte characters
to a wide character array.  The @code{wcstombs} function does the
reverse.  These functions are declared in the header file
@file{stdlib.h}.

In most programs, these functions are the only ones you need for
conversion between wide strings and multibyte character strings.  But
they have limitations.  If your data is not null-terminated or is not
all in core at once, you probably need to use the low-level conversion
functions to convert one character at a time.  @xref{Converting One
Char}.

@comment stdlib.h
@comment ISO
@deftypefun size_t mbstowcs (wchar_t *@var{wstring}, const char *@var{string}, size_t @var{size})
The @code{mbstowcs} (``multibyte string to wide character string'')
function converts the null-terminated string of multibyte characters
@var{string} to an array of wide character codes, storing not more than
@var{size} wide characters into the array beginning at @var{wstring}.
The terminating null character counts towards the size, so if @var{size}
is less than the actual number of wide characters resulting from
@var{string}, no terminating null character is stored.

The conversion of characters from @var{string} begins in the initial
shift state.

If an invalid multibyte character sequence is found, this function
returns a value of @code{-1}.  Otherwise, it returns the number of wide
characters stored in the array @var{wstring}.  This number does not
include the terminating null character, which is present if the number
is less than @var{size}.

Here is an example showing how to convert a string of multibyte
characters, allocating enough space for the result.

@smallexample
wchar_t *
mbstowcs_alloc (const char *string)
@{
  size_t size = strlen (string) + 1;
  wchar_t *buf = xmalloc (size * sizeof (wchar_t));

  size = mbstowcs (buf, string, size);
  if (size == (size_t) -1)
    return NULL;
  buf = xrealloc (buf, (size + 1) * sizeof (wchar_t));
  return buf;
@}
@end smallexample

@end deftypefun

@comment stdlib.h
@comment ISO
@deftypefun size_t wcstombs (char *@var{string}, const wchar_t *@var{wstring}, size_t @var{size})
The @code{wcstombs} (``wide character string to multibyte string'')
function converts the null-terminated wide character array @var{wstring}
into a string containing multibyte characters, storing not more than
@var{size} bytes starting at @var{string}, followed by a terminating
null character if there is room.  The conversion of characters begins in
the initial shift state.

The terminating null character counts towards the size, so if @var{size}
is less than or equal to the number of bytes needed in @var{wstring}, no
terminating null character is stored.

If a code that does not correspond to a valid multibyte character is
found, this function returns a value of @code{-1}.  Otherwise, the
return value is the number of bytes stored in the array @var{string}.
This number does not include the terminating null character, which is
present if the number is less than @var{size}.
@end deftypefun

@node Length of Char, Converting One Char, Wide String Conversion, Extended Characters
@section Multibyte Character Length
@cindex multibyte character, length of
@cindex length of multibyte character

This section describes how to scan a string containing multibyte
characters, one character at a time.  The difficulty in doing this
is to know how many bytes each character contains.  Your program
can use @code{mblen} to find this out.

@comment stdlib.h
@comment ISO
@deftypefun int mblen (const char *@var{string}, size_t @var{size})
The @code{mblen} function with a non-null @var{string} argument returns
the number of bytes that make up the multibyte character beginning at
@var{string}, never examining more than @var{size} bytes.  (The idea is
to supply for @var{size} the number of bytes of data you have in hand.)

The return value of @code{mblen} distinguishes three possibilities: the
first @var{size} bytes at @var{string} start with valid multibyte
character, they start with an invalid byte sequence or just part of a
character, or @var{string} points to an empty string (a null character).

For a valid multibyte character, @code{mblen} returns the number of
bytes in that character (always at least @code{1}, and never more than
@var{size}).  For an invalid byte sequence, @code{mblen} returns
@code{-1}.  For an empty string, it returns @code{0}.

If the multibyte character code uses shift characters, then @code{mblen}
maintains and updates a shift state as it scans.  If you call
@code{mblen} with a null pointer for @var{string}, that initializes the
shift state to its standard initial value.  It also returns nonzero if
the multibyte character code in use actually has a shift state.
@xref{Shift State}.

@pindex stdlib.h
The function @code{mblen} is declared in @file{stdlib.h}.
@end deftypefun

@node Converting One Char, Example of Conversion, Length of Char, Extended Characters
@section Conversion of Extended Characters One by One
@cindex extended characters, converting
@cindex converting extended characters

@pindex stdlib.h
You can convert multibyte characters one at a time to wide characters
with the @code{mbtowc} function.  The @code{wctomb} function does the
reverse.  These functions are declared in @file{stdlib.h}.

@comment stdlib.h
@comment ISO
@deftypefun int mbtowc (wchar_t *@var{result}, const char *@var{string}, size_t @var{size})
The @code{mbtowc} (``multibyte to wide character'') function when called
with non-null @var{string} converts the first multibyte character
beginning at @var{string} to its corresponding wide character code.  It
stores the result in @code{*@var{result}}.

@code{mbtowc} never examines more than @var{size} bytes.  (The idea is
to supply for @var{size} the number of bytes of data you have in hand.)

@code{mbtowc} with non-null @var{string} distinguishes three
possibilities: the first @var{size} bytes at @var{string} start with
valid multibyte character, they start with an invalid byte sequence or
just part of a character, or @var{string} points to an empty string (a
null character).

For a valid multibyte character, @code{mbtowc} converts it to a wide
character and stores that in @code{*@var{result}}, and returns the
number of bytes in that character (always at least @code{1}, and never
more than @var{size}).

For an invalid byte sequence, @code{mbtowc} returns @code{-1}.  For an
empty string, it returns @code{0}, also storing @code{0} in
@code{*@var{result}}.

If the multibyte character code uses shift characters, then
@code{mbtowc} maintains and updates a shift state as it scans.  If you
call @code{mbtowc} with a null pointer for @var{string}, that
initializes the shift state to its standard initial value.  It also
returns nonzero if the multibyte character code in use actually has a
shift state.  @xref{Shift State}.
@end deftypefun

@comment stdlib.h
@comment ISO
@deftypefun int wctomb (char *@var{string}, wchar_t @var{wchar})
The @code{wctomb} (``wide character to multibyte'') function converts
the wide character code @var{wchar} to its corresponding multibyte
character sequence, and stores the result in bytes starting at
@var{string}.  At most @code{MB_CUR_MAX} characters are stored.

@code{wctomb} with non-null @var{string} distinguishes three
possibilities for @var{wchar}: a valid wide character code (one that can
be translated to a multibyte character), an invalid code, and @code{0}.

Given a valid code, @code{wctomb} converts it to a multibyte character,
storing the bytes starting at @var{string}.  Then it returns the number
of bytes in that character (always at least @code{1}, and never more
than @code{MB_CUR_MAX}).

If @var{wchar} is an invalid wide character code, @code{wctomb} returns
@code{-1}.  If @var{wchar} is @code{0}, it returns @code{0}, also
storing @code{0} in @code{*@var{string}}.

If the multibyte character code uses shift characters, then
@code{wctomb} maintains and updates a shift state as it scans.  If you
call @code{wctomb} with a null pointer for @var{string}, that
initializes the shift state to its standard initial value.  It also
returns nonzero if the multibyte character code in use actually has a
shift state.  @xref{Shift State}.

Calling this function with a @var{wchar} argument of zero when
@var{string} is not null has the side-effect of reinitializing the
stored shift state @emph{as well as} storing the multibyte character
@code{0} and returning @code{0}.
@end deftypefun

@node Example of Conversion, Shift State, Converting One Char, Extended Characters
@section Character-by-Character Conversion Example

Here is an example that reads multibyte character text from descriptor
@code{input} and writes the corresponding wide characters to descriptor
@code{output}.  We need to convert characters one by one for this
example because @code{mbstowcs} is unable to continue past a null
character, and cannot cope with an apparently invalid partial character
by reading more input.

@smallexample
int
file_mbstowcs (int input, int output)
@{
  char buffer[BUFSIZ + MB_LEN_MAX];
  int filled = 0;
  int eof = 0;

  while (!eof)
    @{
      int nread;
      int nwrite;
      char *inp = buffer;
      wchar_t outbuf[BUFSIZ];
      wchar_t *outp = outbuf;

      /* @r{Fill up the buffer from the input file.}  */
      nread = read (input, buffer + filled, BUFSIZ);
      if (nread < 0)
        @{
          perror ("read");
          return 0;
        @}
      /* @r{If we reach end of file, make a note to read no more.} */
      if (nread == 0)
        eof = 1;

      /* @r{@code{filled} is now the number of bytes in @code{buffer}.} */
      filled += nread;

      /* @r{Convert those bytes to wide characters--as many as we can.} */
      while (1)
        @{
          int thislen = mbtowc (outp, inp, filled);
          /* Stop converting at invalid character;
             this can mean we have read just the first part
             of a valid character.  */
          if (thislen == -1)
            break;
          /* @r{Treat null character like any other,}
             @r{but also reset shift state.} */
          if (thislen == 0) @{
            thislen = 1;
            mbtowc (NULL, NULL, 0);
          @}
          /* @r{Advance past this character.} */
          inp += thislen;
          filled -= thislen;
          outp++;
        @}

      /* @r{Write the wide characters we just made.}  */
      nwrite = write (output, outbuf,
                      (outp - outbuf) * sizeof (wchar_t));
      if (nwrite < 0)
        @{
          perror ("write");
          return 0;
        @}

      /* @r{See if we have a @emph{real} invalid character.} */
      if ((eof && filled > 0) || filled >= MB_CUR_MAX)
        @{
          error ("invalid multibyte character");
          return 0;
        @}

      /* @r{If any characters must be carried forward,}
         @r{put them at the beginning of @code{buffer}.} */
      if (filled > 0)
        memcpy (inp, buffer, filled);
      @}
    @}

  return 1;
@}
@end smallexample

@node Shift State,  , Example of Conversion, Extended Characters
@section Multibyte Codes Using Shift Sequences

In some multibyte character codes, the @emph{meaning} of any particular
byte sequence is not fixed; it depends on what other sequences have come
earlier in the same string.  Typically there are just a few sequences
that can change the meaning of other sequences; these few are called
@dfn{shift sequences} and we say that they set the @dfn{shift state} for
other sequences that follow.

To illustrate shift state and shift sequences, suppose we decide that
the sequence @code{0200} (just one byte) enters Japanese mode, in which
pairs of bytes in the range from @code{0240} to @code{0377} are single
characters, while @code{0201} enters Latin-1 mode, in which single bytes
in the range from @code{0240} to @code{0377} are characters, and
interpreted according to the ISO Latin-1 character set.  This is a
multibyte code which has two alternative shift states (``Japanese mode''
and ``Latin-1 mode''), and two shift sequences that specify particular
shift states.

When the multibyte character code in use has shift states, then
@code{mblen}, @code{mbtowc} and @code{wctomb} must maintain and update
the current shift state as they scan the string.  To make this work
properly, you must follow these rules:

@itemize @bullet
@item
Before starting to scan a string, call the function with a null pointer
for the multibyte character address---for example, @code{mblen (NULL,
0)}.  This initializes the shift state to its standard initial value.

@item
Scan the string one character at a time, in order.  Do not ``back up''
and rescan characters already scanned, and do not intersperse the
processing of different strings.
@end itemize

Here is an example of using @code{mblen} following these rules:

@smallexample
void
scan_string (char *s)
@{
  int length = strlen (s);

  /* @r{Initialize shift state.} */
  mblen (NULL, 0);

  while (1)
    @{
      int thischar = mblen (s, length);
      /* @r{Deal with end of string and invalid characters.} */
      if (thischar == 0)
        break;
      if (thischar == -1)
        @{
          error ("invalid multibyte character");
          break;
        @}
      /* @r{Advance past this character.} */
      s += thischar;
      length -= thischar;
    @}
@}
@end smallexample

The functions @code{mblen}, @code{mbtowc} and @code{wctomb} are not
reentrant when using a multibyte code that uses a shift state.  However,
no other library functions call these functions, so you don't have to
worry that the shift state will be changed mysteriously.