Put a @table around @include summary.out.
[kopensolaris-gnu/glibc.git] / manual / mbyte.texi
1 @node Extended Characters
2 @chapter Extended Characters
3
4 A number of languages use character sets that are larger than the range
5 of values of type @code{char}.  Japanese and Chinese are probably the
6 most familiar examples.
7
8 The GNU C library includes support for two mechanisms for dealing with
9 extended character sets: multibyte characters and wide characters.  This
10 chapter describes how to use these mechanisms, and the functions for
11 converting between them.
12 @cindex extended character sets
13
14 The behavior of the functions in this chapter is affected by the
15 current locale for character classification (@pxref{Locales}).
16 This choice of locale selects which multibyte code is used, and also
17 controls the meanings and characteristics of wide character codes.
18
19 @menu
20 * Extended Char Intro::          Multibyte codes versus wide characters.
21 * Locales and Extended Chars::   The locale selects the character codes.
22 * Multibyte Char Intro::         How multibyte codes are represented.
23 * Wide Char Intro::              How wide characters are represented.
24 * Wide String Conversion::       Converting wide strings to multibyte code
25                                    and vice versa.
26 * Length of Char::               how many bytes make up one multibyte char.
27 * Converting One Char::          Converting a string character by character.
28 * Example of Conversion::        Example showing why converting 
29                                    one character at a time may be useful.
30 * Shift State::                  Multibyte codes with "shift characters".
31 @end menu
32
33 @node Extended Char Intro
34 @section Introduction to Extended Characters
35
36 You can represent extended characters in either of two ways:
37
38 @itemize @bullet
39 @item
40 As @dfn{Multibyte characters} which can be embedded in an ordinary
41 string, an array of @code{char} objects.  Their advantage is that many
42 programs and operating systems can handle occasional multibyte
43 characters scattered among ordinary ASCII characters, without any
44 change.
45
46 @item
47 @cindex wide characters
48 As @dfn{wide characters}, which are like ordinary characters except that
49 they occupy more bits.  The wide character data type, @code{wchar_t},
50 has a range large enough to hold extended character codes as well as
51 old-fashioned ASCII codes.
52
53 An advantage of wide characters is that each character is a single data
54 object, just like ordinary ASCII characters.  There are a few
55 disadvantages:
56
57 @itemize -
58 @item
59 Each program that uses wide characters must be modified and
60 recompiled.
61
62 @item
63 Files of wide characters cannot be read by programs that expect ordinary
64 characters.
65 @end itemize
66 @end itemize
67
68 Typically, you use the multibyte character representation as part of the
69 external program interface, such as reading or writing text to files.
70 However, it's usually easier to perform internal manipulations on
71 strings containing extended characters on arrays of @code{wchar_t}
72 objects, since the uniform representation makes most editing operations
73 easier.  If you do use multibyte characters for files and wide
74 characters for internal operations, you need to convert between them
75 when you read and write data.
76
77 If your system supports extended characters, then it supports them both
78 as multibyte characters and as wide characters.  The library includes
79 functions you can use to convert between the two representations,
80 functions described in this chapter.
81
82 @node Locales and Extended Chars
83 @section Locales and Extended Characters
84
85 A computer system can support more than one multibyte character code,
86 and more than one wide character code.  The user controls the choice of
87 codes through the current locale for character classification
88 (@pxref{Locales}).  Each locale specifies a particular multibyte
89 character code and a particular wide character code.  The choice of locale
90 influences the behavior of the conversion functions in the library.
91
92 Some locales support neither wide characters nor nontrivial multibyte
93 characters.  In these locales, the library conversion functions still
94 work, even though what they do is basically trivial.
95
96 If you select a new locale for character classification, the internal
97 shift state maintained by these functions can become confused, so it's
98 not a good idea to change the locale while you are in the middle of
99 processing a string.
100
101 @node Multibyte Char Intro
102 @section Multibyte Characters
103 @cindex multibyte characters
104
105 In the ordinary ASCII code, a sequence of characters is a sequence of
106 bytes, and each character is one byte.  This is very simple, but
107 allows for only 256 distinct characters.
108
109 In a @dfn{multibyte character code}, a sequence of characters is a
110 sequence of bytes, but each character may occupy one or more consecutive
111 bytes of the sequence.
112
113 @cindex basic byte sequence
114 There are many different ways of designing a multibyte character code;
115 different systems use different codes.  To specify a particular code
116 means designating the @dfn{basic} byte sequences---those which represent
117 a single character---and what characters they stand for.  A code that a
118 computer can actually use must have a finite number of these basic
119 sequences, and typically none of them is more than a few characters
120 long.
121
122 These sequences need not all have the same length.  In fact, many of
123 them are just one byte long.  Because the basic ASCII characters in the
124 range from @code{0} to @code{0177} are so important, they stand for
125 themselves in all multibyte character codes.  That is to say, a byte
126 whose value is @code{0} through @code{0177} is always a character in
127 itself.  The characters which are more than one byte must always start
128 with a byte in the range from @code{0200} through @code{0377}.
129
130 The byte value @code{0} can be used to terminated a string, just as it
131 is often used in a string of ASCII characters.
132
133 Specifying the basic byte sequences that represent single characters
134 automatically gives meanings to many longer byte sequences, as more than
135 one character.  For example, if the two byte sequence @code{0205 049}
136 stands for the Greek letter alpha, then @code{0205 049 065} must stand
137 for an alpha followed by an @samp{A} (ASCII code 065), and @code{0205 049
138 0205 049} must stand for two alphas in a row.
139
140 If any byte sequence can have more than one meaning as a sequence of
141 characters, then the multibyte code is ambiguous---and no good.  The
142 codes that systems actually use are all unambiguous.
143
144 In most codes, there are certain sequences of bytes that have no meaning
145 as a character or characters.  These are called @dfn{invalid}.
146
147 The simplest possible multibyte code is a trivial one:
148
149 @quotation
150 The basic sequences consist of single bytes.
151 @end quotation
152
153 This particular code is equivalent to not using multibyte characters at
154 all.  It has no invalid sequences.  But it can handle only 256 different
155 characters.
156
157 Here is another possible code which can handle 9376 different
158 characters:
159
160 @quotation
161 The basic sequences consist of
162
163 @itemize @bullet
164 @item
165 single bytes with values in the range @code{0} through @code{0237}.
166
167 @item
168 two-byte sequences, in which both of the bytes have values in the range
169 from @code{0240} through @code{0377}.
170 @end itemize
171 @end quotation
172
173 @noindent
174 This code or a similar one is used on some systems to represent Japanese
175 characters.  The invalid sequences are those which consist of an odd
176 number of consecutive bytes in the range from @code{0240} through
177 @code{0377}.
178
179 Here is another multibyte code which can handle more distinct extended
180 characters---in fact, almost thirty million:
181
182 @quotation
183 The basic sequences consist of
184
185 @itemize @bullet
186 @item
187 single bytes with values in the range @code{0} through @code{0177}.
188
189 @item
190 sequences of up to four bytes in which the first byte is in the range
191 from @code{0200} through @code{0237}, and the remaining bytes are in the
192 range from @code{0240} through @code{0377}.
193 @end itemize
194 @end quotation
195
196 @noindent
197 In this code, any sequence that starts with a byte in the range
198 from @code{0240} through @code{0377} is invalid.
199
200 And here is another variant which has the advantage that removing the
201 last byte or bytes from a valid character can never produce another
202 valid character.  (This property is convenient when you want to search
203 strings for particular characters.)
204
205 @quotation
206 The basic sequences consist of
207
208 @itemize @bullet
209 @item
210 single bytes with values in the range @code{0} through @code{0177}.
211
212 @item
213 two-byte sequences in which the first byte is in the range from
214 @code{0200} through @code{0207}, and the second byte is in the range
215 from @code{0240} through @code{0377}.
216
217 @item
218 three-byte sequences in which the first byte is in the range from
219 @code{0210} through @code{0217}, and the other bytes are in the range
220 from @code{0240} through @code{0377}.
221
222 @item
223 four-byte sequences in which the first byte is in the range from
224 @code{0220} through @code{0227}, and the other bytes are in the range
225 from @code{0240} through @code{0377}.
226 @end itemize
227 @end quotation
228
229 @noindent
230 The list of invalid sequences for this code is long and not worth
231 stating in full; examples of invalid sequences include @code{0240} and
232 @code{0220 0300 065}.
233
234 The number of @emph{possible} multibyte codes is astronomical.  But a
235 given computer system will support at most a few different codes.  (One
236 of these codes may allow for thousands of different characters.)
237 Another computer system may support a completely different code.  The
238 library facilities described in this chapter are helpful because they
239 package up the knowledge of the details of a particular computer
240 system's multibyte code, so your programs need not know them.
241
242 You can use special standard macros to find out the maximum possible
243 number of bytes in a character in the currently selected multibyte
244 code with @code{MB_CUR_MAX}, and the maximum for @emph{any} multibyte
245 code supported on your computer with @code{MB_LEN_MAX}.
246
247 @comment limits.h
248 @comment ANSI
249 @deftypevr Macro int MB_LEN_MAX
250 This is the maximum length of a multibyte character for any supported
251 locale.  It is defined in @file{limits.h}.
252 @pindex limits.h
253 @end deftypevr
254
255 @comment stdlib.h
256 @comment ANSI
257 @deftypevr Macro int MB_CUR_MAX
258 This macro expands into a (possibly non-constant) positive integer
259 expression that is the maximum number of bytes in a multibyte character
260 in the current locale.  The value is never greater than @code{MB_LEN_MAX}.
261
262 @pindex stdlib.h
263 @code{MB_CUR_MAX} is defined in @file{stdlib.h}.
264 @end deftypevr
265
266 Normally, each basic sequence in a particular character code stands for
267 one character, the same character regardless of context.  Some multibyte
268 character codes have a concept of @dfn{shift state}; certain codes,
269 called @dfn{shift sequences}, change to a different shift state, and the
270 meaning of some or all basic sequences varies according to the current
271 shift state.  In fact, the set of basic sequences might even be
272 different depending on the current shift state.  @xref{Shift State}, for
273 more information on handling this sort of code.
274
275 @strong{Incomplete:}  There should be a statement here about what 
276 functions that operate on strings deal with multibyte strings correctly.
277 For example, @code{printf} and friends do, but what about multibyte
278 strings as file names, etc?
279
280 @node Wide Char Intro
281 @section Wide Character Introduction
282
283 @dfn{Wide characters} are much simpler than multibyte characters.  They
284 are simply characters with more than eight bits, so that they have room
285 for more than 256 distinct codes.  The wide character data type,
286 @code{wchar_t}, has a range large enough to hold extended character
287 codes as well as old-fashioned ASCII codes.
288
289 An advantage of wide characters is that each character is a single data
290 object, just like ordinary ASCII characters.  Wide characters also have
291 some disadvantages:
292
293 @itemize @bullet
294 @item
295 A program must be modified and recompiled in order to use wide
296 characters at all.
297
298 @item
299 Files of wide characters cannot be read by programs that expect ordinary
300 characters.
301 @end itemize
302
303 Wide character values @code{0} through @code{0177} are always identical
304 in meaning to the ASCII character codes.  The wide character value zero
305 is often used to terminate a string of wide characters, just as a single
306 byte with value zero often terminates a string of ordinary characters.
307
308 @comment stddef.h
309 @comment ANSI
310 @deftp {Data Type} wchar_t
311 This is the ``wide character'' type, an integer type whose range is
312 large enough to represent all distinct values in any extended character
313 set in the supported locales.  @xref{Locales}, for more information
314 about locales.  This type is defined in the header file @file{stddef.h}.
315 @pindex stddef.h
316 @end deftp
317
318 If your system supports extended characters, then each extended
319 character has both a wide character code and a corresponding multibyte
320 basic sequence.
321
322 @cindex code, character
323 @cindex character code
324 In this chapter, the term @dfn{code} is used to refer to a single
325 extended character object to emphasize the distinction from the
326 @code{char} data type.
327
328 @node Wide String Conversion
329 @section Conversion of Extended Strings
330 @cindex extended strings, converting representations
331 @cindex converting extended strings
332
333 @pindex stdlib.h
334 The @code{mbstowcs} function converts a string of multibyte characters
335 to a wide character array.  The @code{wcstombs} function does the
336 reverse.  These functions are declared in the header file
337 @file{stdlib.h}.
338
339 In most programs, these functions are the only ones you need for
340 conversion between wide strings and multibyte character strings.  But
341 they have limitations.  If your data is not null-terminated or is not
342 all in core at once, you probably need to use the low-level conversion
343 functions to convert one character at a time.  @xref{Converting One
344 Char}.
345
346 @comment stdlib.h
347 @comment ANSI
348 @deftypefun size_t mbstowcs (wchar_t *@var{wstring}, const char *@var{string}, size_t @var{size})
349 The @code{mbstowcs} (``multibyte string to wide character string'')
350 function converts the null-terminated string of multibyte characters
351 @var{string} to an array of wide character codes, storing not more than
352 @var{size} wide characters into the array beginning at @var{wstring}.
353 The terminating null character counts towards the size, so if @var{size}
354 is less than the actual number of wide characters resulting from
355 @var{string}, no terminating null character is stored.
356
357 The conversion of characters from @var{string} begins in the initial
358 shift state.
359
360 If an invalid multibyte character sequence is found, this function
361 returns a value of @code{-1}.  Otherwise, it returns the number of wide
362 characters stored in the array @var{wstring}.  This number does not
363 include the terminating null character, which is present if the number
364 is less than @var{size}.
365
366 Here is an example showing how to convert a string of multibyte
367 characters, allocating enough space for the result.
368
369 @example
370 wchar_t *
371 mbstowcs_alloc (char *string)
372 @{
373   int size = strlen (string) + 1;
374   wchar_t *buffer = (wchar_t) xmalloc (size * sizeof (wchar_t));
375
376   size = mbstowcs (buffer, string, size);
377   if (size < 0)
378     return NULL;
379   return (wchar_t) xrealloc (buffer, (size + 1) * sizeof (wchar_t));
380 @}
381 @end example
382
383 @end deftypefun
384
385 @comment stdlib.h
386 @comment ANSI
387 @deftypefun size_t wcstombs (char *@var{string}, const wchar_t @var{wstring}, size_t @var{size})
388 The @code{wcstombs} (``wide character string to multibyte string'')
389 function converts the null-terminated wide character array @var{wstring}
390 into a string containing multibyte characters, storing not more than
391 @var{size} bytes starting at @var{string}, followed by a terminating
392 null character if there is room.  The conversion of characters begins in
393 the initial shift state.
394
395 The terminating null character counts towards the size, so if @var{size}
396 is less than or equal to the number of bytes needed in @var{wstring}, no
397 terminating null character is stored.
398
399 If a code that does not correspond to a valid multibyte character is
400 found, this function returns a value of @code{-1}.  Otherwise, the
401 return value is the number of bytes stored in the array @var{string}.
402 This number does not include the terminating null character, which is
403 present if the number is less than @var{size}.
404 @end deftypefun
405
406 @node Length of Char
407 @section Multibyte Character Length
408 @cindex multibyte character, length of
409 @cindex length of multibyte character
410
411 This section describes how to scan a string containing multibyte
412 characters, one character at a time.  The difficulty in doing this
413 is to know how many bytes each character contains.  Your program 
414 can use @code{mblen} to find this out.
415
416 @comment stdlib.h
417 @comment ANSI
418 @deftypefun int mblen (const char *@var{string}, size_t @var{size})
419 The @code{mblen} function with non-null @var{string} returns the number
420 of bytes that make up the multibyte character beginning at @var{string},
421 never examining more than @var{size} bytes.  (The idea is to supply
422 for @var{size} the number of bytes of data you have in hand.)
423
424 The return value of @code{mblen} distinguishes three possibilities: the
425 first @var{size} bytes at @var{string} start with valid multibyte
426 character, they start with an invalid byte sequence or just part of a
427 character, or @var{string} points to an empty string (a null character).
428
429 For a valid multibyte character, @code{mblen} returns the number of
430 bytes in that character (always at least @code{1}, and never more than
431 @var{size}).  For an invalid byte sequence, @code{mblen} returns
432 @code{-1}.  For an empty string, it returns @code{0}.
433
434 If the multibyte character code uses shift characters, then @code{mblen}
435 maintains and updates a shift state as it scans.  If you call
436 @code{mblen} with a null pointer for @var{string}, that initializes the
437 shift state to its standard initial value.  It also returns nonzero if
438 the multibyte character code in use actually has a shift state.
439 @xref{Shift State}.
440
441 @pindex stdlib.h
442 The function @code{mblen} is declared in @file{stdlib.h}.
443 @end deftypefun
444
445 @node Converting One Char
446 @section Conversion of Extended Characters One by One
447 @cindex extended characters, converting
448 @cindex converting extended characters
449
450 @pindex stdlib.h
451 You can convert multibyte characters one at a time to wide characters
452 with the @code{mbtowc} function.  The @code{wctomb} function does the
453 reverse.  These functions are declared in @file{stdlib.h}.
454
455 @comment stdlib.h
456 @comment ANSI
457 @deftypefun int mbtowc (wchar_t *@var{result}, const char *@var{string}, size_t @var{size})
458 The @code{mbtowc} (``multibyte to wide character'') function when called
459 with non-null @var{string} converts the first multibyte character
460 beginning at @var{string} to its corresponding wide character code.  It
461 stores the result in @code{*@var{result}}.
462
463 @code{mbtowc} never examines more than @var{size} bytes.  (The idea is
464 to supply for @var{size} the number of bytes of data you have in hand.)
465
466 @code{mbtowc} with non-null @var{string} distinguishes three
467 possibilities: the first @var{size} bytes at @var{string} start with
468 valid multibyte character, they start with an invalid byte sequence or
469 just part of a character, or @var{string} points to an empty string (a
470 null character).
471
472 For a valid multibyte character, @code{mbtowc} converts it to a wide
473 character and stores that in @code{*@var{result}}, and returns the
474 number of bytes in that character (always at least @code{1}, and never
475 more than @var{size}).
476
477 For an invalid byte sequence, @code{mbtowc} returns @code{-1}.  For an
478 empty string, it returns @code{0}, also storing @code{0} in
479 @code{*@var{result}}.
480
481 If the multibyte character code uses shift characters, then
482 @code{mbtowc} maintains and updates a shift state as it scans.  If you
483 call @code{mbtowc} with a null pointer for @var{string}, that
484 initializes the shift state to its standard initial value.  It also
485 returns nonzero if the multibyte character code in use actually has a
486 shift state.  @xref{Shift State}.
487 @end deftypefun
488
489 @comment stdlib.h
490 @comment ANSI
491 @deftypefun int wctomb (char *@var{string}, wchar_t @var{wchar})
492 The @code{wctomb} (``wide character to multibyte'') function converts
493 the wide character code @var{wchar} to its corresponding multibyte
494 character sequence, and stores the result in bytes starting at
495 @var{string}.  At most @code{MB_CUR_MAX} characters are stored.
496
497 @code{wctomb} with non-null @var{string} distinguishes three
498 possibilities for @var{wchar}: a valid wide character code (one that can
499 be translated to a multibyte character), an invalid code, and @code{0}.
500
501 Given a valid code, @code{wctomb} converts it to a multibyte character,
502 storing the bytes starting at @var{string}.  Then it returns the number
503 of bytes in that character (always at least @code{1}, and never more
504 than @code{MB_CUR_MAX}).
505
506 If @var{wchar} is an invalid wide character code, @code{wctomb} returns
507 @code{-1}.  If @var{wchar} is @code{0}, it returns @code{0}, also
508 storing @code{0} in @code{*@var{string}}.
509
510 If the multibyte character code uses shift characters, then
511 @code{wctomb} maintains and updates a shift state as it scans.  If you
512 call @code{wctomb} with a null pointer for @var{string}, that
513 initializes the shift state to its standard initial value.  It also
514 returns nonzero if the multibyte character code in use actually has a
515 shift state.  @xref{Shift State}.
516
517 Calling this function with a @var{wchar} argument of zero when
518 @var{string} is not null has the side-effect of reinitializing the
519 stored shift state @emph{as well as} storing the multibyte character
520 @code{0} and returning @code{0}.
521 @end deftypefun
522
523 @node Example of Conversion
524 @section Example of Character-by-Character Conversion
525
526 Here is an example that reads multibyte character text from descriptor
527 @code{input} and writes the corresponding wide characters to descriptor
528 @code{output}.  We need to convert characters one by one for this
529 example because @code{mbstowcs} is unable to continue past a null
530 character, and cannot cope with an apparently invalid partial character
531 by reading more input.
532
533 @example
534 int
535 file_mbstowcs (int input, int output)
536 @{
537   char buffer[BUFSIZ + MB_LEN_MAX];
538   int filled = 0;
539   int eof = 0;
540
541   while (!eof) @{
542     int nread;
543     int nwrite;
544     char *inp = buffer;
545     wchar_t outbuf[BUFSIZ];
546     wchar_t *outp = outbuf;
547
548     /* @r{Fill up the buffer from the input file.} */
549     nread = read (input, buffer + filled, BUFSIZ);
550     if (nread < 0) @{
551       perror ("read");
552       return 0;
553     @}
554     /* @r{If we reach end of file, make a note to read no more.} */
555     if (nread == 0)
556       eof = 1;
557
558     /* @r{@code{filled} is now the number of bytes in @code{buffer}.} */
559     filled += nread;
560
561     /* @r{Convert those bytes to wide characters--as many as we can.} */
562     while (1) @{
563       int thislen = mbtowc (outp, inp, filled);
564       /* Stop converting at invalid character;
565          this can mean we have read just the first part
566          of a valid character.  */
567       if (thislen == -1)
568         break;
569       /* @r{Treat null character like any other,}
570          @r{but also reset shift state.} */
571       if (thislen == 0) @{
572         thislen = 1;
573         mbtowc (NULL, NULL, 0);
574       @}
575       /* @r{Advance past this character.} */
576       inp += thislen;
577       filled -= thislen;
578       outp++;
579     @}
580
581     /* @r{Write the wide characters we just made.} */
582     nwrite = write (output, outbuf,
583                     (outp - outbuf) * sizeof (wchar_t));
584     if (nwrite < 0) @{
585       perror ("write");
586       return 0;
587     @}
588
589     /* @r{See if we have a @emph{real} invalid character.} */
590     if ((eof && filled > 0) || filled >= MB_CUR_MAX) @{
591       error ("invalid multibyte character");
592       return 0;
593     @}
594
595     /* @r{If any characters must be carried forward,
596        put them at the beginning of @code{buffer}.} */
597     if (filled > 0)
598       memcpy (inp, buffer, filled);
599     @}
600   @}
601
602   return 1;
603 @}
604 @end example
605
606 @node Shift State
607 @section Multibyte Codes Using Shift Sequences
608
609 In some multibyte character codes, the @emph{meaning} of any particular
610 byte sequence is not fixed; it depends on what other sequences have come
611 earlier in the same string.  Typically there are just a few sequences
612 that can change the meaning of other sequences; these few are called
613 @dfn{shift sequences} and we say that they set the @dfn{shift state} for
614 other sequences that follow.
615
616 To illustrate shift state and shift sequences, suppose we decide that
617 the sequence @code{0200} (just one byte) enters Japanese mode, in which
618 pairs of bytes in the range from @code{0240} to @code{0377} are single
619 characters, while @code{0201} enters Latin-1 mode, in which single bytes
620 in the range from @code{0240} to @code{0377} are characters, and
621 interpreted according to the ISO Latin-1 character set.  This is a
622 multibyte code which has two alternative shift states (``Japanese mode''
623 and ``Latin-1 mode''), and two shift sequences that specify particular
624 shift states.
625
626 When the multibyte character code in use has shift states, then
627 @code{mblen}, @code{mbtowc} and @code{wctomb} must maintain and update
628 the current shift state as it scans the string.  To make this work
629 properly, you must follow these rules:
630
631 @itemize @bullet
632 @item
633 Before starting to scan a string, call the function with a null pointer
634 for the multibyte character address---for example, @code{mblen (NULL,
635 0)}.  This initializes the shift state to its standard initial value.
636
637 @item
638 Scan the string one character at a time, in order.  Do not ``back up''
639 and rescan characters already scanned, and do not intersperse the
640 processing of different strings.
641 @end itemize
642
643 Here is an example of using @code{mblen} following these rules:
644
645 @example
646 void
647 scan_string (char *s)
648 @{
649   int length = strlen (s);
650
651   /* @r{Initialize shift state.} */
652   mblen (NULL, 0);
653
654   while (1) @{
655     int thischar = mblen (s, length);
656     /* @r{Deal with end of string and invalid characters.} */
657     if (thischar == 0)
658       break;
659     if (thischar == -1) @{
660       error ("invalid multibyte character");
661       break;
662     @}
663     /* @r{Advance past this character.} */
664     s += thischar;
665     length -= thischar;
666   @}
667 @}
668 @end example
669
670 The functions @code{mblen}, @code{mbtowc} and @code{wctomb} are not
671 reentrant when using a multibyte code that uses a shift state.  However,
672 no other library functions call these functions, so you don't have to
673 worry that the shift state will be changed mysteriously.