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