library_6.html

Glibc的中文手册

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.
<P>
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</CODE>, and the maximum for <EM>any</EM> multibyte
code supported on your computer with <CODE>MB_LEN_MAX</CODE>.
<P>
<A NAME="IDX334"></A>
<U>Macro:</U> int <B>MB_LEN_MAX</B><P>
This is the maximum length of a multibyte character for any supported
locale.  It is defined in <TT>`limits.h'</TT>.
<A NAME="IDX335"></A>
<P>
<A NAME="IDX336"></A>
<U>Macro:</U> int <B>MB_CUR_MAX</B><P>
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</CODE>.
<A NAME="IDX337"></A>
<P>
<CODE>MB_CUR_MAX</CODE> is defined in <TT>`stdlib.h'</TT>.
<P>
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</DFN>; certain codes,
called <DFN>shift sequences</DFN>, 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.  See section <A HREF="library_6.html#SEC75" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_6.html#SEC75">Multibyte Codes Using Shift Sequences</A>, for
more information on handling this sort of code.
<P>
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.
<P>
For example, let's figure out what happens if you use multibyte
characters in a file name.  The functions such as <CODE>open</CODE> and
<CODE>unlink</CODE> that operate on file names treat the name as a sequence of
byte values, with <SAMP>`/'</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>`/'</SAMP>.
<P>
<H2><A NAME="SEC70" HREF="library_toc.html#SEC70" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC70">Wide Character Introduction</A></H2>
<P>
<DFN>Wide characters</DFN> 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</CODE>, has a range large enough to hold extended character
codes as well as old-fashioned ASCII codes.
<P>
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:
<P>
<UL>
<LI>
A program must be modified and recompiled in order to use wide
characters at all.
<P>
<LI>
Files of wide characters cannot be read by programs that expect ordinary
characters.
</UL>
<P>
Wide character values <CODE>0</CODE> through <CODE>0177</CODE> 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.
<P>
<A NAME="IDX338"></A>
<U>Data Type:</U> <B>wchar_t</B><P>
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.  See section <A HREF="library_7.html#SEC76" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_7.html#SEC76">Locales and Internationalization</A>, for more information
about locales.  This type is defined in the header file <TT>`stddef.h'</TT>.
<A NAME="IDX339"></A>
<P>
If your system supports extended characters, then each extended
character has both a wide character code and a corresponding multibyte
basic sequence.
<A NAME="IDX340"></A>
<A NAME="IDX341"></A>
<P>
In this chapter, the term <DFN>code</DFN> is used to refer to a single
extended character object to emphasize the distinction from the
<CODE>char</CODE> data type.
<P>
<A NAME="IDX342"></A>
<A NAME="IDX343"></A>
<H2><A NAME="SEC71" HREF="library_toc.html#SEC71" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC71">Conversion of Extended Strings</A></H2>
<A NAME="IDX344"></A>
<P>
The <CODE>mbstowcs</CODE> function converts a string of multibyte characters
to a wide character array.  The <CODE>wcstombs</CODE> function does the
reverse.  These functions are declared in the header file
<TT>`stdlib.h'</TT>.
<P>
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.  See section <A HREF="library_6.html#SEC73" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_6.html#SEC73">Conversion of Extended Characters One by One</A>.
<P>
<A NAME="IDX345"></A>
<U>Function:</U> size_t <B>mbstowcs</B> <I>(wchar_t *<VAR>wstring</VAR>, const char *<VAR>string</VAR>, size_t <VAR>size</VAR>)</I><P>
The <CODE>mbstowcs</CODE> ("multibyte string to wide character string")
function converts the null-terminated string of multibyte characters
<VAR>string</VAR> to an array of wide character codes, storing not more than
<VAR>size</VAR> wide characters into the array beginning at <VAR>wstring</VAR>.
The terminating null character counts towards the size, so if <VAR>size</VAR>
is less than the actual number of wide characters resulting from
<VAR>string</VAR>, no terminating null character is stored.
<P>
The conversion of characters from <VAR>string</VAR> begins in the initial
shift state.
<P>
If an invalid multibyte character sequence is found, this function
returns a value of <CODE>-1</CODE>.  Otherwise, it returns the number of wide
characters stored in the array <VAR>wstring</VAR>.  This number does not
include the terminating null character, which is present if the number
is less than <VAR>size</VAR>.
<P>
Here is an example showing how to convert a string of multibyte
characters, allocating enough space for the result.
<P>
<PRE>
wchar_t *
mbstowcs_alloc (char *string)
{
  int size = strlen (string) + 1;
  wchar_t *buffer = (wchar_t) xmalloc (size * sizeof (wchar_t));

  size = mbstowcs (buffer, string, size);
  if (size &#60; 0)
    return NULL;
  return (wchar_t) xrealloc (buffer, (size + 1) * sizeof (wchar_t));
}
</PRE>
<P>
<A NAME="IDX346"></A>
<U>Function:</U> size_t <B>wcstombs</B> <I>(char *<VAR>string</VAR>, const wchar_t <VAR>wstring</VAR>, size_t <VAR>size</VAR>)</I><P>
The <CODE>wcstombs</CODE> ("wide character string to multibyte string")
function converts the null-terminated wide character array <VAR>wstring</VAR>
into a string containing multibyte characters, storing not more than
<VAR>size</VAR> bytes starting at <VAR>string</VAR>, followed by a terminating
null character if there is room.  The conversion of characters begins in
the initial shift state.
<P>
The terminating null character counts towards the size, so if <VAR>size</VAR>
is less than or equal to the number of bytes needed in <VAR>wstring</VAR>, no
terminating null character is stored.
<P>
If a code that does not correspond to a valid multibyte character is
found, this function returns a value of <CODE>-1</CODE>.  Otherwise, the
return value is the number of bytes stored in the array <VAR>string</VAR>.
This number does not include the terminating null character, which is
present if the number is less than <VAR>size</VAR>.
<P>
<A NAME="IDX347"></A>
<A NAME="IDX348"></A>
<H2><A NAME="SEC72" HREF="library_toc.html#SEC72" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC72">Multibyte Character Length</A></H2>
<P>
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</CODE> to find this out.
<P>
<A NAME="IDX349"></A>
<U>Function:</U> int <B>mblen</B> <I>(const char *<VAR>string</VAR>, size_t <VAR>size</VAR>)</I><P>
The <CODE>mblen</CODE> function with non-null <VAR>string</VAR> returns the number
of bytes that make up the multibyte character beginning at <VAR>string</VAR>,
never examining more than <VAR>size</VAR> bytes.  (The idea is to supply
for <VAR>size</VAR> the number of bytes of data you have in hand.)
<P>
The return value of <CODE>mblen</CODE> distinguishes three possibilities: the
first <VAR>size</VAR> bytes at <VAR>string</VAR> start with valid multibyte
character, they start with an invalid byte sequence or just part of a
character, or <VAR>string</VAR> points to an empty string (a null character).
<P>
For a valid multibyte character, <CODE>mblen</CODE> returns the number of
bytes in that character (always at least <CODE>1</CODE>, and never more than
<VAR>size</VAR>).  For an invalid byte sequence, <CODE>mblen</CODE> returns
<CODE>-1</CODE>.  For an empty string, it returns <CODE>0</CODE>.
<P>
If the multibyte character code uses shift characters, then <CODE>mblen</CODE>
maintains and updates a shift state as it scans.  If you call
<CODE>mblen</CODE> with a null pointer for <VAR>string</VAR>, 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.
See section <A HREF="library_6.html#SEC75" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_6.html#SEC75">Multibyte Codes Using Shift Sequences</A>.
<A NAME="IDX350"></A>
<P>
The function <CODE>mblen</CODE> is declared in <TT>`stdlib.h'</TT>.
<P>
<A NAME="IDX351"></A>
<A NAME="IDX352"></A>
<H2><A NAME="SEC73" HREF="library_toc.html#SEC73" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC73">Conversion of Extended Characters One by One</A></H2>
<A NAME="IDX353"></A>
<P>
You can convert multibyte characters one at a time to wide characters
with the <CODE>mbtowc</CODE> function.  The <CODE>wctomb</CODE> function does the
reverse.  These functions are declared in <TT>`stdlib.h'</TT>.
<P>
<A NAME="IDX354"></A>
<U>Function:</U> int <B>mbtowc</B> <I>(wchar_t *<VAR>result</VAR>, const char *<VAR>string</VAR>, size_t <VAR>size</VAR>)</I><P>
The <CODE>mbtowc</CODE> ("multibyte to wide character") function when called
with non-null <VAR>string</VAR> converts the first multibyte character