.
[kopensolaris-gnu/glibc.git] / manual / charset.texi
1 @node Character Set Handling, Locales, String and Array Utilities, Top
2 @c %MENU% Support for extended character sets
3 @chapter Character Set Handling
4
5 @ifnottex
6 @macro cal{text}
7 \text\
8 @end macro
9 @end ifnottex
10
11 Character sets used in the early days of computing had only six, seven,
12 or eight bits for each character: there was never a case where more than
13 eight bits (one byte) were used to represent a single character.  The
14 limitations of this approach became more apparent as more people
15 grappled with non-Roman character sets, where not all the characters
16 that make up a language's character set can be represented by @math{2^8}
17 choices.  This chapter shows the functionality that was added to the C
18 library to support multiple character sets.
19
20 @menu
21 * Extended Char Intro::              Introduction to Extended Characters.
22 * Charset Function Overview::        Overview about Character Handling
23                                       Functions.
24 * Restartable multibyte conversion:: Restartable multibyte conversion
25                                       Functions.
26 * Non-reentrant Conversion::         Non-reentrant Conversion Function.
27 * Generic Charset Conversion::       Generic Charset Conversion.
28 @end menu
29
30
31 @node Extended Char Intro
32 @section Introduction to Extended Characters
33
34 A variety of solutions is available to overcome the differences between
35 character sets with a 1:1 relation between bytes and characters and
36 character sets with ratios of 2:1 or 4:1.  The remainder of this
37 section gives a few examples to help understand the design decisions
38 made while developing the functionality of the @w{C library}.
39
40 @cindex internal representation
41 A distinction we have to make right away is between internal and
42 external representation.  @dfn{Internal representation} means the
43 representation used by a program while keeping the text in memory.
44 External representations are used when text is stored or transmitted
45 through some communication channel.  Examples of external
46 representations include files waiting in a directory to be
47 read and parsed.
48
49 Traditionally there has been no difference between the two representations.
50 It was equally comfortable and useful to use the same single-byte
51 representation internally and externally.  This comfort level decreases
52 with more and larger character sets.
53
54 One of the problems to overcome with the internal representation is
55 handling text that is externally encoded using different character
56 sets.  Assume a program that reads two texts and compares them using
57 some metric.  The comparison can be usefully done only if the texts are
58 internally kept in a common format.
59
60 @cindex wide character
61 For such a common format (@math{=} character set) eight bits are certainly
62 no longer enough.  So the smallest entity will have to grow: @dfn{wide
63 characters} will now be used.  Instead of one byte per character, two or
64 four will be used instead.  (Three are not good to address in memory and
65 more than four bytes seem not to be necessary).
66
67 @cindex Unicode
68 @cindex ISO 10646
69 As shown in some other part of this manual,
70 @c !!! Ahem, wide char string functions are not yet covered -- drepper
71 a completely new family has been created of functions that can handle wide
72 character texts in memory.  The most commonly used character sets for such
73 internal wide character representations are Unicode and @w{ISO 10646}
74 (also known as UCS for Universal Character Set).  Unicode was originally
75 planned as a 16-bit character set; whereas, @w{ISO 10646} was designed to
76 be a 31-bit large code space.  The two standards are practically identical.
77 They have the same character repertoire and code table, but Unicode specifies
78 added semantics.  At the moment, only characters in the first @code{0x10000}
79 code positions (the so-called Basic Multilingual Plane, BMP) have been
80 assigned, but the assignment of more specialized characters outside this
81 16-bit space is already in progress.  A number of encodings have been
82 defined for Unicode and @w{ISO 10646} characters:
83 @cindex UCS-2
84 @cindex UCS-4
85 @cindex UTF-8
86 @cindex UTF-16
87 UCS-2 is a 16-bit word that can only represent characters
88 from the BMP, UCS-4 is a 32-bit word than can represent any Unicode
89 and @w{ISO 10646} character, UTF-8 is an ASCII compatible encoding where
90 ASCII characters are represented by ASCII bytes and non-ASCII characters
91 by sequences of 2-6 non-ASCII bytes, and finally UTF-16 is an extension
92 of UCS-2 in which pairs of certain UCS-2 words can be used to encode
93 non-BMP characters up to @code{0x10ffff}.
94
95 To represent wide characters the @code{char} type is not suitable.  For
96 this reason the @w{ISO C} standard introduces a new type that is
97 designed to keep one character of a wide character string.  To maintain
98 the similarity there is also a type corresponding to @code{int} for
99 those functions that take a single wide character.
100
101 @comment stddef.h
102 @comment ISO
103 @deftp {Data type} wchar_t
104 This data type is used as the base type for wide character strings.
105 In other words, arrays of objects of this type are the equivalent of
106 @code{char[]} for multibyte character strings.  The type is defined in
107 @file{stddef.h}.
108
109 The @w{ISO C90} standard, where @code{wchar_t} was introduced, does not
110 say anything specific about the representation.  It only requires that
111 this type is capable of storing all elements of the basic character set.
112 Therefore it would be legitimate to define @code{wchar_t} as @code{char},
113 which might make sense for embedded systems.
114
115 But for GNU systems @code{wchar_t} is always 32 bits wide and, therefore,
116 capable of representing all UCS-4 values and, therefore, covering all of
117 @w{ISO 10646}.  Some Unix systems define @code{wchar_t} as a 16-bit type
118 and thereby follow Unicode very strictly.  This definition is perfectly
119 fine with the standard, but it also means that to represent all
120 characters from Unicode and @w{ISO 10646} one has to use UTF-16 surrogate
121 characters, which is in fact a multi-wide-character encoding.  But
122 resorting to multi-wide-character encoding contradicts the purpose of the
123 @code{wchar_t} type.
124 @end deftp
125
126 @comment wchar.h
127 @comment ISO
128 @deftp {Data type} wint_t
129 @code{wint_t} is a data type used for parameters and variables that
130 contain a single wide character.  As the name suggests this type is the
131 equivalent of @code{int} when using the normal @code{char} strings.  The
132 types @code{wchar_t} and @code{wint_t} often have the same
133 representation if their size is 32 bits wide but if @code{wchar_t} is
134 defined as @code{char} the type @code{wint_t} must be defined as
135 @code{int} due to the parameter promotion.
136
137 @pindex wchar.h
138 This type is defined in @file{wchar.h} and was introduced in
139 @w{Amendment 1} to @w{ISO C90}.
140 @end deftp
141
142 As there are for the @code{char} data type macros are available for
143 specifying the minimum and maximum value representable in an object of
144 type @code{wchar_t}.
145
146 @comment wchar.h
147 @comment ISO
148 @deftypevr Macro wint_t WCHAR_MIN
149 The macro @code{WCHAR_MIN} evaluates to the minimum value representable
150 by an object of type @code{wint_t}.
151
152 This macro was introduced in @w{Amendment 1} to @w{ISO C90}.
153 @end deftypevr
154
155 @comment wchar.h
156 @comment ISO
157 @deftypevr Macro wint_t WCHAR_MAX
158 The macro @code{WCHAR_MAX} evaluates to the maximum value representable
159 by an object of type @code{wint_t}.
160
161 This macro was introduced in @w{Amendment 1} to @w{ISO C90}.
162 @end deftypevr
163
164 Another special wide character value is the equivalent to @code{EOF}.
165
166 @comment wchar.h
167 @comment ISO
168 @deftypevr Macro wint_t WEOF
169 The macro @code{WEOF} evaluates to a constant expression of type
170 @code{wint_t} whose value is different from any member of the extended
171 character set.
172
173 @code{WEOF} need not be the same value as @code{EOF} and unlike
174 @code{EOF} it also need @emph{not} be negative.  In other words, sloppy
175 code like
176
177 @smallexample
178 @{
179   int c;
180   @dots{}
181   while ((c = getc (fp)) < 0)
182     @dots{}
183 @}
184 @end smallexample
185
186 @noindent
187 has to be rewritten to use @code{WEOF} explicitly when wide characters
188 are used:
189
190 @smallexample
191 @{
192   wint_t c;
193   @dots{}
194   while ((c = wgetc (fp)) != WEOF)
195     @dots{}
196 @}
197 @end smallexample
198
199 @pindex wchar.h
200 This macro was introduced in @w{Amendment 1} to @w{ISO C90} and is
201 defined in @file{wchar.h}.
202 @end deftypevr
203
204
205 These internal representations present problems when it comes to storing
206 and transmittal.  Because each single wide character consists of more
207 than one byte, they are effected by byte-ordering.  Thus, machines with
208 different endianesses would see different values when accessing the same
209 data.  This byte ordering concern also applies for communication protocols
210 that are all byte-based and therefore require that the sender has to
211 decide about splitting the wide character in bytes.  A last (but not least
212 important) point is that wide characters often require more storage space
213 than a customized byte-oriented character set.
214
215 @cindex multibyte character
216 @cindex EBCDIC
217 For all the above reasons, an external encoding that is different from
218 the internal encoding is often used if the latter is UCS-2 or UCS-4.
219 The external encoding is byte-based and can be chosen appropriately for
220 the environment and for the texts to be handled.  A variety of different
221 character sets can be used for this external encoding (information that
222 will not be exhaustively presented here--instead, a description of the
223 major groups will suffice).  All of the ASCII-based character sets
224 fulfill one requirement: they are "filesystem safe."  This means that
225 the character @code{'/'} is used in the encoding @emph{only} to
226 represent itself.  Things are a bit different for character sets like
227 EBCDIC (Extended Binary Coded Decimal Interchange Code, a character set
228 family used by IBM), but if the operation system does not understand
229 EBCDIC directly the parameters-to-system calls have to be converted
230 first anyhow.
231
232 @itemize @bullet
233 @item
234 The simplest character sets are single-byte character sets.  There can
235 be only up to 256 characters (for @w{8 bit} character sets), which is
236 not sufficient to cover all languages but might be sufficient to handle
237 a specific text.  Handling of a @w{8 bit} character sets is simple.  This
238 is not true for other kinds presented later, and therefore, the
239 application one uses might require the use of @w{8 bit} character sets.
240
241 @cindex ISO 2022
242 @item
243 The @w{ISO 2022} standard defines a mechanism for extended character
244 sets where one character @emph{can} be represented by more than one
245 byte.  This is achieved by associating a state with the text.
246 Characters that can be used to change the state can be embedded in the
247 text.  Each byte in the text might have a different interpretation in each
248 state.  The state might even influence whether a given byte stands for a
249 character on its own or whether it has to be combined with some more
250 bytes.
251
252 @cindex EUC
253 @cindex Shift_JIS
254 @cindex SJIS
255 In most uses of @w{ISO 2022} the defined character sets do not allow
256 state changes that cover more than the next character.  This has the
257 big advantage that whenever one can identify the beginning of the byte
258 sequence of a character one can interpret a text correctly.  Examples of
259 character sets using this policy are the various EUC character sets
260 (used by Sun's operations systems, EUC-JP, EUC-KR, EUC-TW, and EUC-CN)
261 or Shift_JIS (SJIS, a Japanese encoding).
262
263 But there are also character sets using a state that is valid for more
264 than one character and has to be changed by another byte sequence.
265 Examples for this are ISO-2022-JP, ISO-2022-KR, and ISO-2022-CN.
266
267 @item
268 @cindex ISO 6937
269 Early attempts to fix 8 bit character sets for other languages using the
270 Roman alphabet lead to character sets like @w{ISO 6937}.  Here bytes
271 representing characters like the acute accent do not produce output
272 themselves: one has to combine them with other characters to get the
273 desired result.  For example, the byte sequence @code{0xc2 0x61}
274 (non-spacing acute accent, followed by lower-case `a') to get the ``small
275 a with  acute'' character.  To get the acute accent character on its own,
276 one has to write @code{0xc2 0x20} (the non-spacing acute followed by a
277 space).
278
279 Character sets like @w{ISO 6937} are used in some embedded systems such
280 as teletex.
281
282 @item
283 @cindex UTF-8
284 Instead of converting the Unicode or @w{ISO 10646} text used internally,
285 it is often also sufficient to simply use an encoding different than
286 UCS-2/UCS-4.  The Unicode and @w{ISO 10646} standards even specify such an
287 encoding: UTF-8.  This encoding is able to represent all of @w{ISO
288 10646} 31 bits in a byte string of length one to six.
289
290 @cindex UTF-7
291 There were a few other attempts to encode @w{ISO 10646} such as UTF-7,
292 but UTF-8 is today the only encoding that should be used.  In fact, with
293 any luck UTF-8 will soon be the only external encoding that has to be
294 supported.  It proves to be universally usable and its only disadvantage
295 is that it favors Roman languages by making the byte string
296 representation of other scripts (Cyrillic, Greek, Asian scripts) longer
297 than necessary if using a specific character set for these scripts.
298 Methods like the Unicode compression scheme can alleviate these
299 problems.
300 @end itemize
301
302 The question remaining is: how to select the character set or encoding
303 to use.  The answer: you cannot decide about it yourself, it is decided
304 by the developers of the system or the majority of the users.  Since the
305 goal is interoperability one has to use whatever the other people one
306 works with use.  If there are no constraints, the selection is based on
307 the requirements the expected circle of users will have.  In other words,
308 if a project is expected to be used in only, say, Russia it is fine to use
309 KOI8-R or a similar character set.  But if at the same time people from,
310 say, Greece are participating one should use a character set that allows
311 all people to collaborate.
312
313 The most widely useful solution seems to be: go with the most general
314 character set, namely @w{ISO 10646}.  Use UTF-8 as the external encoding
315 and problems about users not being able to use their own language
316 adequately are a thing of the past.
317
318 One final comment about the choice of the wide character representation
319 is necessary at this point.  We have said above that the natural choice
320 is using Unicode or @w{ISO 10646}.  This is not required, but at least
321 encouraged, by the @w{ISO C} standard.  The standard defines at least a
322 macro @code{__STDC_ISO_10646__} that is only defined on systems where
323 the @code{wchar_t} type encodes @w{ISO 10646} characters.  If this
324 symbol is not defined one should avoid making assumptions about the wide
325 character representation.  If the programmer uses only the functions
326 provided by the C library to handle wide character strings there should
327 be no compatibility problems with other systems.
328
329 @node Charset Function Overview
330 @section Overview about Character Handling Functions
331
332 A Unix @w{C library} contains three different sets of functions in two
333 families to handle character set conversion.  One of the function families
334 (the most commonly used) is specified in the @w{ISO C90} standard and,
335 therefore, is portable even beyond the Unix world.  Unfortunately this
336 family is the least useful one.  These functions should be avoided
337 whenever possible, especially when developing libraries (as opposed to
338 applications).
339
340 The second family of functions got introduced in the early Unix standards
341 (XPG2) and is still part of the latest and greatest Unix standard:
342 @w{Unix 98}.  It is also the most powerful and useful set of functions.
343 But we will start with the functions defined in @w{Amendment 1} to
344 @w{ISO C90}.
345
346 @node Restartable multibyte conversion
347 @section Restartable Multibyte Conversion Functions
348
349 The @w{ISO C} standard defines functions to convert strings from a
350 multibyte representation to wide character strings.  There are a number
351 of peculiarities:
352
353 @itemize @bullet
354 @item
355 The character set assumed for the multibyte encoding is not specified
356 as an argument to the functions.  Instead the character set specified by
357 the @code{LC_CTYPE} category of the current locale is used; see
358 @ref{Locale Categories}.
359
360 @item
361 The functions handling more than one character at a time require NUL
362 terminated strings as the argument (i.e., converting blocks of text
363 does not work unless one can add a NUL byte at an appropriate place).
364 The GNU C library contains some extensions to the standard that allow
365 specifying a size, but basically they also expect terminated strings.
366 @end itemize
367
368 Despite these limitations the @w{ISO C} functions can be used in many
369 contexts.  In graphical user interfaces, for instance, it is not
370 uncommon to have functions that require text to be displayed in a wide
371 character string if the text is not simple ASCII.  The text itself might
372 come from a file with translations and the user should decide about the
373 current locale, which determines the translation and therefore also the
374 external encoding used.  In such a situation (and many others) the
375 functions described here are perfect.  If more freedom while performing
376 the conversion is necessary take a look at the @code{iconv} functions
377 (@pxref{Generic Charset Conversion}).
378
379 @menu
380 * Selecting the Conversion::     Selecting the conversion and its properties.
381 * Keeping the state::            Representing the state of the conversion.
382 * Converting a Character::       Converting Single Characters.
383 * Converting Strings::           Converting Multibyte and Wide Character
384                                   Strings.
385 * Multibyte Conversion Example:: A Complete Multibyte Conversion Example.
386 @end menu
387
388 @node Selecting the Conversion
389 @subsection Selecting the conversion and its properties
390
391 We already said above that the currently selected locale for the
392 @code{LC_CTYPE} category decides about the conversion that is performed
393 by the functions we are about to describe.  Each locale uses its own
394 character set (given as an argument to @code{localedef}) and this is the
395 one assumed as the external multibyte encoding.  The wide character
396 character set always is UCS-4, at least on GNU systems.
397
398 A characteristic of each multibyte character set is the maximum number
399 of bytes that can be necessary to represent one character.  This
400 information is quite important when writing code that uses the
401 conversion functions (as shown in the examples below).
402 The @w{ISO C} standard defines two macros that provide this information.
403
404
405 @comment limits.h
406 @comment ISO
407 @deftypevr Macro int MB_LEN_MAX
408 @code{MB_LEN_MAX} specifies the maximum number of bytes in the multibyte
409 sequence for a single character in any of the supported locales.  It is
410 a compile-time constant and is defined in @file{limits.h}.
411 @pindex limits.h
412 @end deftypevr
413
414 @comment stdlib.h
415 @comment ISO
416 @deftypevr Macro int MB_CUR_MAX
417 @code{MB_CUR_MAX} expands into a positive integer expression that is the
418 maximum number of bytes in a multibyte character in the current locale.
419 The value is never greater than @code{MB_LEN_MAX}.  Unlike
420 @code{MB_LEN_MAX} this macro need not be a compile-time constant, and in
421 the GNU C library it is not.
422
423 @pindex stdlib.h
424 @code{MB_CUR_MAX} is defined in @file{stdlib.h}.
425 @end deftypevr
426
427 Two different macros are necessary since strictly @w{ISO C90} compilers
428 do not allow variable length array definitions, but still it is desirable
429 to avoid dynamic allocation.  This incomplete piece of code shows the
430 problem:
431
432 @smallexample
433 @{
434   char buf[MB_LEN_MAX];
435   ssize_t len = 0;
436
437   while (! feof (fp))
438     @{
439       fread (&buf[len], 1, MB_CUR_MAX - len, fp);
440       /* @r{@dots{} process} buf */
441       len -= used;
442     @}
443 @}
444 @end smallexample
445
446 The code in the inner loop is expected to have always enough bytes in
447 the array @var{buf} to convert one multibyte character.  The array
448 @var{buf} has to be sized statically since many compilers do not allow a
449 variable size.  The @code{fread} call makes sure that @code{MB_CUR_MAX}
450 bytes are always available in @var{buf}.  Note that it isn't
451 a problem if @code{MB_CUR_MAX} is not a compile-time constant.
452
453
454 @node Keeping the state
455 @subsection Representing the state of the conversion
456
457 @cindex stateful
458 In the introduction of this chapter it was said that certain character
459 sets use a @dfn{stateful} encoding.  That is, the encoded values depend
460 in some way on the previous bytes in the text.
461
462 Since the conversion functions allow converting a text in more than one
463 step we must have a way to pass this information from one call of the
464 functions to another.
465
466 @comment wchar.h
467 @comment ISO
468 @deftp {Data type} mbstate_t
469 @cindex shift state
470 A variable of type @code{mbstate_t} can contain all the information
471 about the @dfn{shift state} needed from one call to a conversion
472 function to another.
473
474 @pindex wchar.h
475 @code{mbstate_t} is defined in @file{wchar.h}.  It was introduced in
476 @w{Amendment 1} to @w{ISO C90}.
477 @end deftp
478
479 To use objects of type @code{mbstate_t} the programmer has to define such
480 objects (normally as local variables on the stack) and pass a pointer to
481 the object to the conversion functions.  This way the conversion function
482 can update the object if the current multibyte character set is stateful.
483
484 There is no specific function or initializer to put the state object in
485 any specific state.  The rules are that the object should always
486 represent the initial state before the first use, and this is achieved by
487 clearing the whole variable with code such as follows:
488
489 @smallexample
490 @{
491   mbstate_t state;
492   memset (&state, '\0', sizeof (state));
493   /* @r{from now on @var{state} can be used.}  */
494   @dots{}
495 @}
496 @end smallexample
497
498 When using the conversion functions to generate output it is often
499 necessary to test whether the current state corresponds to the initial
500 state.  This is necessary, for example, to decide whether to emit
501 escape sequences to set the state to the initial state at certain
502 sequence points.  Communication protocols often require this.
503
504 @comment wchar.h
505 @comment ISO
506 @deftypefun int mbsinit (const mbstate_t *@var{ps})
507 The @code{mbsinit} function determines whether the state object pointed
508 to by @var{ps} is in the initial state.  If @var{ps} is a null pointer or
509 the object is in the initial state the return value is nonzero.  Otherwise
510 it is zero.
511
512 @pindex wchar.h
513 @code{mbsinit} was introduced in @w{Amendment 1} to @w{ISO C90} and is
514 declared in @file{wchar.h}.
515 @end deftypefun
516
517 Code using @code{mbsinit} often looks similar to this:
518
519 @c Fix the example to explicitly say how to generate the escape sequence
520 @c to restore the initial state.
521 @smallexample
522 @{
523   mbstate_t state;
524   memset (&state, '\0', sizeof (state));
525   /* @r{Use @var{state}.}  */
526   @dots{}
527   if (! mbsinit (&state))
528     @{
529       /* @r{Emit code to return to initial state.}  */
530       const wchar_t empty[] = L"";
531       const wchar_t *srcp = empty;
532       wcsrtombs (outbuf, &srcp, outbuflen, &state);
533     @}
534   @dots{}
535 @}
536 @end smallexample
537
538 The code to emit the escape sequence to get back to the initial state is
539 interesting.  The @code{wcsrtombs} function can be used to determine the
540 necessary output code (@pxref{Converting Strings}).  Please note that on
541 GNU systems it is not necessary to perform this extra action for the
542 conversion from multibyte text to wide character text since the wide
543 character encoding is not stateful.  But there is nothing mentioned in
544 any standard that prohibits making @code{wchar_t} using a stateful
545 encoding.
546
547 @node Converting a Character
548 @subsection Converting Single Characters
549
550 The most fundamental of the conversion functions are those dealing with
551 single characters.  Please note that this does not always mean single
552 bytes.  But since there is very often a subset of the multibyte
553 character set that consists of single byte sequences, there are
554 functions to help with converting bytes.  Frequently, ASCII is a subpart
555 of the multibyte character set.  In such a scenario, each ASCII character
556 stands for itself, and all other characters have at least a first byte
557 that is beyond the range @math{0} to @math{127}.
558
559 @comment wchar.h
560 @comment ISO
561 @deftypefun wint_t btowc (int @var{c})
562 The @code{btowc} function (``byte to wide character'') converts a valid
563 single byte character @var{c} in the initial shift state into the wide
564 character equivalent using the conversion rules from the currently
565 selected locale of the @code{LC_CTYPE} category.
566
567 If @code{(unsigned char) @var{c}} is no valid single byte multibyte
568 character or if @var{c} is @code{EOF}, the function returns @code{WEOF}.
569
570 Please note the restriction of @var{c} being tested for validity only in
571 the initial shift state.  No @code{mbstate_t} object is used from
572 which the state information is taken, and the function also does not use
573 any static state.
574
575 @pindex wchar.h
576 The @code{btowc} function was introduced in @w{Amendment 1} to @w{ISO C90}
577 and is declared in @file{wchar.h}.
578 @end deftypefun
579
580 Despite the limitation that the single byte value always is interpreted
581 in the initial state this function is actually useful most of the time.
582 Most characters are either entirely single-byte character sets or they
583 are extension to ASCII.  But then it is possible to write code like this
584 (not that this specific example is very useful):
585
586 @smallexample
587 wchar_t *
588 itow (unsigned long int val)
589 @{
590   static wchar_t buf[30];
591   wchar_t *wcp = &buf[29];
592   *wcp = L'\0';
593   while (val != 0)
594     @{
595       *--wcp = btowc ('0' + val % 10);
596       val /= 10;
597     @}
598   if (wcp == &buf[29])
599     *--wcp = L'0';
600   return wcp;
601 @}
602 @end smallexample
603
604 Why is it necessary to use such a complicated implementation and not
605 simply cast @code{'0' + val % 10} to a wide character?  The answer is
606 that there is no guarantee that one can perform this kind of arithmetic
607 on the character of the character set used for @code{wchar_t}
608 representation.  In other situations the bytes are not constant at
609 compile time and so the compiler cannot do the work.  In situations like
610 this it is necessary @code{btowc}.
611
612 @noindent
613 There also is a function for the conversion in the other direction.
614
615 @comment wchar.h
616 @comment ISO
617 @deftypefun int wctob (wint_t @var{c})
618 The @code{wctob} function (``wide character to byte'') takes as the
619 parameter a valid wide character.  If the multibyte representation for
620 this character in the initial state is exactly one byte long, the return
621 value of this function is this character.  Otherwise the return value is
622 @code{EOF}.
623
624 @pindex wchar.h
625 @code{wctob} was introduced in @w{Amendment 1} to @w{ISO C90} and
626 is declared in @file{wchar.h}.
627 @end deftypefun
628
629 There are more general functions to convert single character from
630 multibyte representation to wide characters and vice versa.  These
631 functions pose no limit on the length of the multibyte representation
632 and they also do not require it to be in the initial state.
633
634 @comment wchar.h
635 @comment ISO
636 @deftypefun size_t mbrtowc (wchar_t *restrict @var{pwc}, const char *restrict @var{s}, size_t @var{n}, mbstate_t *restrict @var{ps})
637 @cindex stateful
638 The @code{mbrtowc} function (``multibyte restartable to wide
639 character'') converts the next multibyte character in the string pointed
640 to by @var{s} into a wide character and stores it in the wide character
641 string pointed to by @var{pwc}.  The conversion is performed according
642 to the locale currently selected for the @code{LC_CTYPE} category.  If
643 the conversion for the character set used in the locale requires a state,
644 the multibyte string is interpreted in the state represented by the
645 object pointed to by @var{ps}.  If @var{ps} is a null pointer, a static,
646 internal state variable used only by the @code{mbrtowc} function is
647 used.
648
649 If the next multibyte character corresponds to the NUL wide character,
650 the return value of the function is @math{0} and the state object is
651 afterwards in the initial state.  If the next @var{n} or fewer bytes
652 form a correct multibyte character, the return value is the number of
653 bytes starting from @var{s} that form the multibyte character.  The
654 conversion state is updated according to the bytes consumed in the
655 conversion.  In both cases the wide character (either the @code{L'\0'}
656 or the one found in the conversion) is stored in the string pointed to
657 by @var{pwc} if @var{pwc} is not null.
658
659 If the first @var{n} bytes of the multibyte string possibly form a valid
660 multibyte character but there are more than @var{n} bytes needed to
661 complete it, the return value of the function is @code{(size_t) -2} and
662 no value is stored.  Please note that this can happen even if @var{n}
663 has a value greater than or equal to @code{MB_CUR_MAX} since the input
664 might contain redundant shift sequences.
665
666 If the first @code{n} bytes of the multibyte string cannot possibly form
667 a valid multibyte character, no value is stored, the global variable
668 @code{errno} is set to the value @code{EILSEQ}, and the function returns
669 @code{(size_t) -1}.  The conversion state is afterwards undefined.
670
671 @pindex wchar.h
672 @code{mbrtowc} was introduced in @w{Amendment 1} to @w{ISO C90} and
673 is declared in @file{wchar.h}.
674 @end deftypefun
675
676 Use of @code{mbrtowc} is straightforward.  A function that copies a
677 multibyte string into a wide character string while at the same time
678 converting all lowercase characters into uppercase could look like this
679 (this is not the final version, just an example; it has no error
680 checking, and sometimes leaks memory):
681
682 @smallexample
683 wchar_t *
684 mbstouwcs (const char *s)
685 @{
686   size_t len = strlen (s);
687   wchar_t *result = malloc ((len + 1) * sizeof (wchar_t));
688   wchar_t *wcp = result;
689   wchar_t tmp[1];
690   mbstate_t state;
691   size_t nbytes;
692
693   memset (&state, '\0', sizeof (state));
694   while ((nbytes = mbrtowc (tmp, s, len, &state)) > 0)
695     @{
696       if (nbytes >= (size_t) -2)
697         /* Invalid input string.  */
698         return NULL;
699       *wcp++ = towupper (tmp[0]);
700       len -= nbytes;
701       s += nbytes;
702     @}
703   return result;
704 @}
705 @end smallexample
706
707 The use of @code{mbrtowc} should be clear.  A single wide character is
708 stored in @code{@var{tmp}[0]}, and the number of consumed bytes is stored
709 in the variable @var{nbytes}.  If the conversion is successful, the
710 uppercase variant of the wide character is stored in the @var{result}
711 array and the pointer to the input string and the number of available
712 bytes is adjusted.
713
714 The only non-obvious thing about @code{mbrtowc} might be the way memory
715 is allocated for the result.  The above code uses the fact that there
716 can never be more wide characters in the converted results than there are
717 bytes in the multibyte input string.  This method yields a pessimistic
718 guess about the size of the result, and if many wide character strings
719 have to be constructed this way or if the strings are long, the extra
720 memory required to be allocated because the input string contains
721 multibyte characters might be significant.  The allocated memory block can
722 be resized to the correct size before returning it, but a better solution
723 might be to allocate just the right amount of space for the result right
724 away.  Unfortunately there is no function to compute the length of the wide
725 character string directly from the multibyte string.  There is, however, a
726 function that does part of the work.
727
728 @comment wchar.h
729 @comment ISO
730 @deftypefun size_t mbrlen (const char *restrict @var{s}, size_t @var{n}, mbstate_t *@var{ps})
731 The @code{mbrlen} function (``multibyte restartable length'') computes
732 the number of at most @var{n} bytes starting at @var{s}, which form the
733 next valid and complete multibyte character.
734
735 If the next multibyte character corresponds to the NUL wide character,
736 the return value is @math{0}.  If the next @var{n} bytes form a valid
737 multibyte character, the number of bytes belonging to this multibyte
738 character byte sequence is returned.
739
740 If the first @var{n} bytes possibly form a valid multibyte
741 character but the character is incomplete, the return value is
742 @code{(size_t) -2}.  Otherwise the multibyte character sequence is invalid
743 and the return value is @code{(size_t) -1}.
744
745 The multibyte sequence is interpreted in the state represented by the
746 object pointed to by @var{ps}.  If @var{ps} is a null pointer, a state
747 object local to @code{mbrlen} is used.
748
749 @pindex wchar.h
750 @code{mbrlen} was introduced in @w{Amendment 1} to @w{ISO C90} and
751 is declared in @file{wchar.h}.
752 @end deftypefun
753
754 The attentive reader now will note that @code{mbrlen} can be implemented
755 as
756
757 @smallexample
758 mbrtowc (NULL, s, n, ps != NULL ? ps : &internal)
759 @end smallexample
760
761 This is true and in fact is mentioned in the official specification.
762 How can this function be used to determine the length of the wide
763 character string created from a multibyte character string?  It is not
764 directly usable, but we can define a function @code{mbslen} using it:
765
766 @smallexample
767 size_t
768 mbslen (const char *s)
769 @{
770   mbstate_t state;
771   size_t result = 0;
772   size_t nbytes;
773   memset (&state, '\0', sizeof (state));
774   while ((nbytes = mbrlen (s, MB_LEN_MAX, &state)) > 0)
775     @{
776       if (nbytes >= (size_t) -2)
777         /* @r{Something is wrong.}  */
778         return (size_t) -1;
779       s += nbytes;
780       ++result;
781     @}
782   return result;
783 @}
784 @end smallexample
785
786 This function simply calls @code{mbrlen} for each multibyte character
787 in the string and counts the number of function calls.  Please note that
788 we here use @code{MB_LEN_MAX} as the size argument in the @code{mbrlen}
789 call.  This is acceptable since a) this value is larger then the length of
790 the longest multibyte character sequence and b) we know that the string
791 @var{s} ends with a NUL byte, which cannot be part of any other multibyte
792 character sequence but the one representing the NUL wide character.
793 Therefore, the @code{mbrlen} function will never read invalid memory.
794
795 Now that this function is available (just to make this clear, this
796 function is @emph{not} part of the GNU C library) we can compute the
797 number of wide character required to store the converted multibyte
798 character string @var{s} using
799
800 @smallexample
801 wcs_bytes = (mbslen (s) + 1) * sizeof (wchar_t);
802 @end smallexample
803
804 Please note that the @code{mbslen} function is quite inefficient.  The
805 implementation of @code{mbstouwcs} with @code{mbslen} would have to
806 perform the conversion of the multibyte character input string twice, and
807 this conversion might be quite expensive.  So it is necessary to think
808 about the consequences of using the easier but imprecise method before
809 doing the work twice.
810
811 @comment wchar.h
812 @comment ISO
813 @deftypefun size_t wcrtomb (char *restrict @var{s}, wchar_t @var{wc}, mbstate_t *restrict @var{ps})
814 The @code{wcrtomb} function (``wide character restartable to
815 multibyte'') converts a single wide character into a multibyte string
816 corresponding to that wide character.
817
818 If @var{s} is a null pointer, the function resets the state stored in
819 the objects pointed to by @var{ps} (or the internal @code{mbstate_t}
820 object) to the initial state.  This can also be achieved by a call like
821 this:
822
823 @smallexample
824 wcrtombs (temp_buf, L'\0', ps)
825 @end smallexample
826
827 @noindent
828 since, if @var{s} is a null pointer, @code{wcrtomb} performs as if it
829 writes into an internal buffer, which is guaranteed to be large enough.
830
831 If @var{wc} is the NUL wide character, @code{wcrtomb} emits, if
832 necessary, a shift sequence to get the state @var{ps} into the initial
833 state followed by a single NUL byte, which is stored in the string
834 @var{s}.
835
836 Otherwise a byte sequence (possibly including shift sequences) is written
837 into the string @var{s}.  This only happens if @var{wc} is a valid wide
838 character (i.e., it has a multibyte representation in the character set
839 selected by locale of the @code{LC_CTYPE} category).  If @var{wc} is no
840 valid wide character, nothing is stored in the strings @var{s},
841 @code{errno} is set to @code{EILSEQ}, the conversion state in @var{ps}
842 is undefined and the return value is @code{(size_t) -1}.
843
844 If no error occurred the function returns the number of bytes stored in
845 the string @var{s}.  This includes all bytes representing shift
846 sequences.
847
848 One word about the interface of the function: there is no parameter
849 specifying the length of the array @var{s}.  Instead the function
850 assumes that there are at least @code{MB_CUR_MAX} bytes available since
851 this is the maximum length of any byte sequence representing a single
852 character.  So the caller has to make sure that there is enough space
853 available, otherwise buffer overruns can occur.
854
855 @pindex wchar.h
856 @code{wcrtomb} was introduced in @w{Amendment 1} to @w{ISO C90} and is
857 declared in @file{wchar.h}.
858 @end deftypefun
859
860 Using @code{wcrtomb} is as easy as using @code{mbrtowc}.  The following
861 example appends a wide character string to a multibyte character string.
862 Again, the code is not really useful (or correct), it is simply here to
863 demonstrate the use and some problems.
864
865 @smallexample
866 char *
867 mbscatwcs (char *s, size_t len, const wchar_t *ws)
868 @{
869   mbstate_t state;
870   /* @r{Find the end of the existing string.}  */
871   char *wp = strchr (s, '\0');
872   len -= wp - s;
873   memset (&state, '\0', sizeof (state));
874   do
875     @{
876       size_t nbytes;
877       if (len < MB_CUR_LEN)
878         @{
879           /* @r{We cannot guarantee that the next}
880              @r{character fits into the buffer, so}
881              @r{return an error.}  */
882           errno = E2BIG;
883           return NULL;
884         @}
885       nbytes = wcrtomb (wp, *ws, &state);
886       if (nbytes == (size_t) -1)
887         /* @r{Error in the conversion.}  */
888         return NULL;
889       len -= nbytes;
890       wp += nbytes;
891     @}
892   while (*ws++ != L'\0');
893   return s;
894 @}
895 @end smallexample
896
897 First the function has to find the end of the string currently in the
898 array @var{s}.  The @code{strchr} call does this very efficiently since a
899 requirement for multibyte character representations is that the NUL byte
900 is never used except to represent itself (and in this context, the end
901 of the string).
902
903 After initializing the state object the loop is entered where the first
904 task is to make sure there is enough room in the array @var{s}.  We
905 abort if there are not at least @code{MB_CUR_LEN} bytes available.  This
906 is not always optimal but we have no other choice.  We might have less
907 than @code{MB_CUR_LEN} bytes available but the next multibyte character
908 might also be only one byte long.  At the time the @code{wcrtomb} call
909 returns it is too late to decide whether the buffer was large enough.  If
910 this solution is unsuitable, there is a very slow but more accurate
911 solution.
912
913 @smallexample
914   @dots{}
915   if (len < MB_CUR_LEN)
916     @{
917       mbstate_t temp_state;
918       memcpy (&temp_state, &state, sizeof (state));
919       if (wcrtomb (NULL, *ws, &temp_state) > len)
920         @{
921           /* @r{We cannot guarantee that the next}
922              @r{character fits into the buffer, so}
923              @r{return an error.}  */
924           errno = E2BIG;
925           return NULL;
926         @}
927     @}
928   @dots{}
929 @end smallexample
930
931 Here we perform the conversion that might overflow the buffer so that
932 we are afterwards in the position to make an exact decision about the
933 buffer size.  Please note the @code{NULL} argument for the destination
934 buffer in the new @code{wcrtomb} call; since we are not interested in the
935 converted text at this point, this is a nice way to express this.  The
936 most unusual thing about this piece of code certainly is the duplication
937 of the conversion state object, but if a change of the state is necessary
938 to emit the next multibyte character, we want to have the same shift state
939 change performed in the real conversion.  Therefore, we have to preserve
940 the initial shift state information.
941
942 There are certainly many more and even better solutions to this problem.
943 This example is only provided for educational purposes.
944
945 @node Converting Strings
946 @subsection Converting Multibyte and Wide Character Strings
947
948 The functions described in the previous section only convert a single
949 character at a time.  Most operations to be performed in real-world
950 programs include strings and therefore the @w{ISO C} standard also
951 defines conversions on entire strings.  However, the defined set of
952 functions is quite limited; therefore, the GNU C library contains a few
953 extensions that can help in some important situations.
954
955 @comment wchar.h
956 @comment ISO
957 @deftypefun size_t mbsrtowcs (wchar_t *restrict @var{dst}, const char **restrict @var{src}, size_t @var{len}, mbstate_t *restrict @var{ps})
958 The @code{mbsrtowcs} function (``multibyte string restartable to wide
959 character string'') converts an NUL-terminated multibyte character
960 string at @code{*@var{src}} into an equivalent wide character string,
961 including the NUL wide character at the end.  The conversion is started
962 using the state information from the object pointed to by @var{ps} or
963 from an internal object of @code{mbsrtowcs} if @var{ps} is a null
964 pointer.  Before returning, the state object is updated to match the state
965 after the last converted character.  The state is the initial state if the
966 terminating NUL byte is reached and converted.
967
968 If @var{dst} is not a null pointer, the result is stored in the array
969 pointed to by @var{dst}; otherwise, the conversion result is not
970 available since it is stored in an internal buffer.
971
972 If @var{len} wide characters are stored in the array @var{dst} before
973 reaching the end of the input string, the conversion stops and @var{len}
974 is returned.  If @var{dst} is a null pointer, @var{len} is never checked.
975
976 Another reason for a premature return from the function call is if the
977 input string contains an invalid multibyte sequence.  In this case the
978 global variable @code{errno} is set to @code{EILSEQ} and the function
979 returns @code{(size_t) -1}.
980
981 @c XXX The ISO C9x draft seems to have a problem here.  It says that PS
982 @c is not updated if DST is NULL.  This is not said straightforward and
983 @c none of the other functions is described like this.  It would make sense
984 @c to define the function this way but I don't think it is meant like this.
985
986 In all other cases the function returns the number of wide characters
987 converted during this call.  If @var{dst} is not null, @code{mbsrtowcs}
988 stores in the pointer pointed to by @var{src} either a null pointer (if
989 the NUL byte in the input string was reached) or the address of the byte
990 following the last converted multibyte character.
991
992 @pindex wchar.h
993 @code{mbsrtowcs} was introduced in @w{Amendment 1} to @w{ISO C90} and is
994 declared in @file{wchar.h}.
995 @end deftypefun
996
997 The definition of the @code{mbsrtowcs} function has one important
998 limitation.  The requirement that @var{dst} has to be a NUL-terminated
999 string provides problems if one wants to convert buffers with text.  A
1000 buffer is normally no collection of NUL-terminated strings but instead a
1001 continuous collection of lines, separated by newline characters.  Now
1002 assume that a function to convert one line from a buffer is needed.  Since
1003 the line is not NUL-terminated, the source pointer cannot directly point
1004 into the unmodified text buffer.  This means, either one inserts the NUL
1005 byte at the appropriate place for the time of the @code{mbsrtowcs}
1006 function call (which is not doable for a read-only buffer or in a
1007 multi-threaded application) or one copies the line in an extra buffer
1008 where it can be terminated by a NUL byte.  Note that it is not in general
1009 possible to limit the number of characters to convert by setting the
1010 parameter @var{len} to any specific value.  Since it is not known how
1011 many bytes each multibyte character sequence is in length, one can only
1012 guess.
1013
1014 @cindex stateful
1015 There is still a problem with the method of NUL-terminating a line right
1016 after the newline character, which could lead to very strange results.
1017 As said in the description of the @code{mbsrtowcs} function above the
1018 conversion state is guaranteed to be in the initial shift state after
1019 processing the NUL byte at the end of the input string.  But this NUL
1020 byte is not really part of the text (i.e., the conversion state after
1021 the newline in the original text could be something different than the
1022 initial shift state and therefore the first character of the next line
1023 is encoded using this state).  But the state in question is never
1024 accessible to the user since the conversion stops after the NUL byte
1025 (which resets the state).  Most stateful character sets in use today
1026 require that the shift state after a newline be the initial state--but
1027 this is not a strict guarantee.  Therefore, simply NUL-terminating a
1028 piece of a running text is not always an adequate solution and,
1029 therefore, should never be used in generally used code.
1030
1031 The generic conversion interface (@pxref{Generic Charset Conversion})
1032 does not have this limitation (it simply works on buffers, not
1033 strings), and the GNU C library contains a set of functions that take
1034 additional parameters specifying the maximal number of bytes that are
1035 consumed from the input string.  This way the problem of
1036 @code{mbsrtowcs}'s example above could be solved by determining the line
1037 length and passing this length to the function.
1038
1039 @comment wchar.h
1040 @comment ISO
1041 @deftypefun size_t wcsrtombs (char *restrict @var{dst}, const wchar_t **restrict @var{src}, size_t @var{len}, mbstate_t *restrict @var{ps})
1042 The @code{wcsrtombs} function (``wide character string restartable to
1043 multibyte string'') converts the NUL-terminated wide character string at
1044 @code{*@var{src}} into an equivalent multibyte character string and
1045 stores the result in the array pointed to by @var{dst}.  The NUL wide
1046 character is also converted.  The conversion starts in the state
1047 described in the object pointed to by @var{ps} or by a state object
1048 locally to @code{wcsrtombs} in case @var{ps} is a null pointer.  If
1049 @var{dst} is a null pointer, the conversion is performed as usual but the
1050 result is not available.  If all characters of the input string were
1051 successfully converted and if @var{dst} is not a null pointer, the
1052 pointer pointed to by @var{src} gets assigned a null pointer.
1053
1054 If one of the wide characters in the input string has no valid multibyte
1055 character equivalent, the conversion stops early, sets the global
1056 variable @code{errno} to @code{EILSEQ}, and returns @code{(size_t) -1}.
1057
1058 Another reason for a premature stop is if @var{dst} is not a null
1059 pointer and the next converted character would require more than
1060 @var{len} bytes in total to the array @var{dst}.  In this case (and if
1061 @var{dest} is not a null pointer) the pointer pointed to by @var{src} is
1062 assigned a value pointing to the wide character right after the last one
1063 successfully converted.
1064
1065 Except in the case of an encoding error the return value of the
1066 @code{wcsrtombs} function is the number of bytes in all the multibyte
1067 character sequences stored in @var{dst}.  Before returning the state in
1068 the object pointed to by @var{ps} (or the internal object in case
1069 @var{ps} is a null pointer) is updated to reflect the state after the
1070 last conversion.  The state is the initial shift state in case the
1071 terminating NUL wide character was converted.
1072
1073 @pindex wchar.h
1074 The @code{wcsrtombs} function was introduced in @w{Amendment 1} to
1075 @w{ISO C90} and is declared in @file{wchar.h}.
1076 @end deftypefun
1077
1078 The restriction mentioned above for the @code{mbsrtowcs} function applies
1079 here also.  There is no possibility of directly controlling the number of
1080 input characters.  One has to place the NUL wide character at the correct
1081 place or control the consumed input indirectly via the available output
1082 array size (the @var{len} parameter).
1083
1084 @comment wchar.h
1085 @comment GNU
1086 @deftypefun size_t mbsnrtowcs (wchar_t *restrict @var{dst}, const char **restrict @var{src}, size_t @var{nmc}, size_t @var{len}, mbstate_t *restrict @var{ps})
1087 The @code{mbsnrtowcs} function is very similar to the @code{mbsrtowcs}
1088 function.  All the parameters are the same except for @var{nmc}, which is
1089 new.  The return value is the same as for @code{mbsrtowcs}.
1090
1091 This new parameter specifies how many bytes at most can be used from the
1092 multibyte character string.  In other words, the multibyte character
1093 string @code{*@var{src}} need not be NUL-terminated.  But if a NUL byte
1094 is found within the @var{nmc} first bytes of the string, the conversion
1095 stops here.
1096
1097 This function is a GNU extension.  It is meant to work around the
1098 problems mentioned above.  Now it is possible to convert a buffer with
1099 multibyte character text piece for piece without having to care about
1100 inserting NUL bytes and the effect of NUL bytes on the conversion state.
1101 @end deftypefun
1102
1103 A function to convert a multibyte string into a wide character string
1104 and display it could be written like this (this is not a really useful
1105 example):
1106
1107 @smallexample
1108 void
1109 showmbs (const char *src, FILE *fp)
1110 @{
1111   mbstate_t state;
1112   int cnt = 0;
1113   memset (&state, '\0', sizeof (state));
1114   while (1)
1115     @{
1116       wchar_t linebuf[100];
1117       const char *endp = strchr (src, '\n');
1118       size_t n;
1119
1120       /* @r{Exit if there is no more line.}  */
1121       if (endp == NULL)
1122         break;
1123
1124       n = mbsnrtowcs (linebuf, &src, endp - src, 99, &state);
1125       linebuf[n] = L'\0';
1126       fprintf (fp, "line %d: \"%S\"\n", linebuf);
1127     @}
1128 @}
1129 @end smallexample
1130
1131 There is no problem with the state after a call to @code{mbsnrtowcs}.
1132 Since we don't insert characters in the strings that were not in there
1133 right from the beginning and we use @var{state} only for the conversion
1134 of the given buffer, there is no problem with altering the state.
1135
1136 @comment wchar.h
1137 @comment GNU
1138 @deftypefun size_t wcsnrtombs (char *restrict @var{dst}, const wchar_t **restrict @var{src}, size_t @var{nwc}, size_t @var{len}, mbstate_t *restrict @var{ps})
1139 The @code{wcsnrtombs} function implements the conversion from wide
1140 character strings to multibyte character strings.  It is similar to
1141 @code{wcsrtombs} but, just like @code{mbsnrtowcs}, it takes an extra
1142 parameter, which specifies the length of the input string.
1143
1144 No more than @var{nwc} wide characters from the input string
1145 @code{*@var{src}} are converted.  If the input string contains a NUL
1146 wide character in the first @var{nwc} characters, the conversion stops at
1147 this place.
1148
1149 The @code{wcsnrtombs} function is a GNU extension and just like
1150 @code{mbsnrtowcs} helps in situations where no NUL-terminated input
1151 strings are available.
1152 @end deftypefun
1153
1154
1155 @node Multibyte Conversion Example
1156 @subsection A Complete Multibyte Conversion Example
1157
1158 The example programs given in the last sections are only brief and do
1159 not contain all the error checking, etc.  Presented here is a complete
1160 and documented example.  It features the @code{mbrtowc} function but it
1161 should be easy to derive versions using the other functions.
1162
1163 @smallexample
1164 int
1165 file_mbsrtowcs (int input, int output)
1166 @{
1167   /* @r{Note the use of @code{MB_LEN_MAX}.}
1168      @r{@code{MB_CUR_MAX} cannot portably be used here.}  */
1169   char buffer[BUFSIZ + MB_LEN_MAX];
1170   mbstate_t state;
1171   int filled = 0;
1172   int eof = 0;
1173
1174   /* @r{Initialize the state.}  */
1175   memset (&state, '\0', sizeof (state));
1176
1177   while (!eof)
1178     @{
1179       ssize_t nread;
1180       ssize_t nwrite;
1181       char *inp = buffer;
1182       wchar_t outbuf[BUFSIZ];
1183       wchar_t *outp = outbuf;
1184
1185       /* @r{Fill up the buffer from the input file.}  */
1186       nread = read (input, buffer + filled, BUFSIZ);
1187       if (nread < 0)
1188         @{
1189           perror ("read");
1190           return 0;
1191         @}
1192       /* @r{If we reach end of file, make a note to read no more.} */
1193       if (nread == 0)
1194         eof = 1;
1195
1196       /* @r{@code{filled} is now the number of bytes in @code{buffer}.} */
1197       filled += nread;
1198
1199       /* @r{Convert those bytes to wide characters--as many as we can.} */
1200       while (1)
1201         @{
1202           size_t thislen = mbrtowc (outp, inp, filled, &state);
1203           /* @r{Stop converting at invalid character;}
1204              @r{this can mean we have read just the first part}
1205              @r{of a valid character.}  */
1206           if (thislen == (size_t) -1)
1207             break;
1208           /* @r{We want to handle embedded NUL bytes}
1209              @r{but the return value is 0.  Correct this.}  */
1210           if (thislen == 0)
1211             thislen = 1;
1212           /* @r{Advance past this character.} */
1213           inp += thislen;
1214           filled -= thislen;
1215           ++outp;
1216         @}
1217
1218       /* @r{Write the wide characters we just made.}  */
1219       nwrite = write (output, outbuf,
1220                       (outp - outbuf) * sizeof (wchar_t));
1221       if (nwrite < 0)
1222         @{
1223           perror ("write");
1224           return 0;
1225         @}
1226
1227       /* @r{See if we have a @emph{real} invalid character.} */
1228       if ((eof && filled > 0) || filled >= MB_CUR_MAX)
1229         @{
1230           error (0, 0, "invalid multibyte character");
1231           return 0;
1232         @}
1233
1234       /* @r{If any characters must be carried forward,}
1235          @r{put them at the beginning of @code{buffer}.} */
1236       if (filled > 0)
1237         memmove (inp, buffer, filled);
1238     @}
1239
1240   return 1;
1241 @}
1242 @end smallexample
1243
1244
1245 @node Non-reentrant Conversion
1246 @section Non-reentrant Conversion Function
1247
1248 The functions described in the previous chapter are defined in
1249 @w{Amendment 1} to @w{ISO C90}, but the original @w{ISO C90} standard
1250 also contained functions for character set conversion.  The reason that
1251 these original functions are not described first is that they are almost
1252 entirely useless.
1253
1254 The problem is that all the conversion functions described in the
1255 original @w{ISO C90} use a local state.  Using a local state implies that
1256 multiple conversions at the same time (not only when using threads)
1257 cannot be done, and that you cannot first convert single characters and
1258 then strings since you cannot tell the conversion functions which state
1259 to use.
1260
1261 These original functions are therefore usable only in a very limited set
1262 of situations.  One must complete converting the entire string before
1263 starting a new one, and each string/text must be converted with the same
1264 function (there is no problem with the library itself; it is guaranteed
1265 that no library function changes the state of any of these functions).
1266 @strong{For the above reasons it is highly requested that the functions
1267 described in the previous section be used in place of non-reentrant
1268 conversion functions.}
1269
1270 @menu
1271 * Non-reentrant Character Conversion::  Non-reentrant Conversion of Single
1272                                          Characters.
1273 * Non-reentrant String Conversion::     Non-reentrant Conversion of Strings.
1274 * Shift State::                         States in Non-reentrant Functions.
1275 @end menu
1276
1277 @node Non-reentrant Character Conversion
1278 @subsection Non-reentrant Conversion of Single Characters
1279
1280 @comment stdlib.h
1281 @comment ISO
1282 @deftypefun int mbtowc (wchar_t *restrict @var{result}, const char *restrict @var{string}, size_t @var{size})
1283 The @code{mbtowc} (``multibyte to wide character'') function when called
1284 with non-null @var{string} converts the first multibyte character
1285 beginning at @var{string} to its corresponding wide character code.  It
1286 stores the result in @code{*@var{result}}.
1287
1288 @code{mbtowc} never examines more than @var{size} bytes.  (The idea is
1289 to supply for @var{size} the number of bytes of data you have in hand.)
1290
1291 @code{mbtowc} with non-null @var{string} distinguishes three
1292 possibilities: the first @var{size} bytes at @var{string} start with
1293 valid multibyte characters, they start with an invalid byte sequence or
1294 just part of a character, or @var{string} points to an empty string (a
1295 null character).
1296
1297 For a valid multibyte character, @code{mbtowc} converts it to a wide
1298 character and stores that in @code{*@var{result}}, and returns the
1299 number of bytes in that character (always at least @math{1} and never
1300 more than @var{size}).
1301
1302 For an invalid byte sequence, @code{mbtowc} returns @math{-1}.  For an
1303 empty string, it returns @math{0}, also storing @code{'\0'} in
1304 @code{*@var{result}}.
1305
1306 If the multibyte character code uses shift characters, then
1307 @code{mbtowc} maintains and updates a shift state as it scans.  If you
1308 call @code{mbtowc} with a null pointer for @var{string}, that
1309 initializes the shift state to its standard initial value.  It also
1310 returns nonzero if the multibyte character code in use actually has a
1311 shift state.  @xref{Shift State}.
1312 @end deftypefun
1313
1314 @comment stdlib.h
1315 @comment ISO
1316 @deftypefun int wctomb (char *@var{string}, wchar_t @var{wchar})
1317 The @code{wctomb} (``wide character to multibyte'') function converts
1318 the wide character code @var{wchar} to its corresponding multibyte
1319 character sequence, and stores the result in bytes starting at
1320 @var{string}.  At most @code{MB_CUR_MAX} characters are stored.
1321
1322 @code{wctomb} with non-null @var{string} distinguishes three
1323 possibilities for @var{wchar}: a valid wide character code (one that can
1324 be translated to a multibyte character), an invalid code, and
1325 @code{L'\0'}.
1326
1327 Given a valid code, @code{wctomb} converts it to a multibyte character,
1328 storing the bytes starting at @var{string}.  Then it returns the number
1329 of bytes in that character (always at least @math{1} and never more
1330 than @code{MB_CUR_MAX}).
1331
1332 If @var{wchar} is an invalid wide character code, @code{wctomb} returns
1333 @math{-1}.  If @var{wchar} is @code{L'\0'}, it returns @code{0}, also
1334 storing @code{'\0'} in @code{*@var{string}}.
1335
1336 If the multibyte character code uses shift characters, then
1337 @code{wctomb} maintains and updates a shift state as it scans.  If you
1338 call @code{wctomb} with a null pointer for @var{string}, that
1339 initializes the shift state to its standard initial value.  It also
1340 returns nonzero if the multibyte character code in use actually has a
1341 shift state.  @xref{Shift State}.
1342
1343 Calling this function with a @var{wchar} argument of zero when
1344 @var{string} is not null has the side-effect of reinitializing the
1345 stored shift state @emph{as well as} storing the multibyte character
1346 @code{'\0'} and returning @math{0}.
1347 @end deftypefun
1348
1349 Similar to @code{mbrlen} there is also a non-reentrant function that
1350 computes the length of a multibyte character.  It can be defined in
1351 terms of @code{mbtowc}.
1352
1353 @comment stdlib.h
1354 @comment ISO
1355 @deftypefun int mblen (const char *@var{string}, size_t @var{size})
1356 The @code{mblen} function with a non-null @var{string} argument returns
1357 the number of bytes that make up the multibyte character beginning at
1358 @var{string}, never examining more than @var{size} bytes.  (The idea is
1359 to supply for @var{size} the number of bytes of data you have in hand.)
1360
1361 The return value of @code{mblen} distinguishes three possibilities: the
1362 first @var{size} bytes at @var{string} start with valid multibyte
1363 characters, they start with an invalid byte sequence or just part of a
1364 character, or @var{string} points to an empty string (a null character).
1365
1366 For a valid multibyte character, @code{mblen} returns the number of
1367 bytes in that character (always at least @code{1} and never more than
1368 @var{size}).  For an invalid byte sequence, @code{mblen} returns
1369 @math{-1}.  For an empty string, it returns @math{0}.
1370
1371 If the multibyte character code uses shift characters, then @code{mblen}
1372 maintains and updates a shift state as it scans.  If you call
1373 @code{mblen} with a null pointer for @var{string}, that initializes the
1374 shift state to its standard initial value.  It also returns a nonzero
1375 value if the multibyte character code in use actually has a shift state.
1376 @xref{Shift State}.
1377
1378 @pindex stdlib.h
1379 The function @code{mblen} is declared in @file{stdlib.h}.
1380 @end deftypefun
1381
1382
1383 @node Non-reentrant String Conversion
1384 @subsection Non-reentrant Conversion of Strings
1385
1386 For convenience the @w{ISO C90} standard also defines functions to
1387 convert entire strings instead of single characters.  These functions
1388 suffer from the same problems as their reentrant counterparts from
1389 @w{Amendment 1} to @w{ISO C90}; see @ref{Converting Strings}.
1390
1391 @comment stdlib.h
1392 @comment ISO
1393 @deftypefun size_t mbstowcs (wchar_t *@var{wstring}, const char *@var{string}, size_t @var{size})
1394 The @code{mbstowcs} (``multibyte string to wide character string'')
1395 function converts the null-terminated string of multibyte characters
1396 @var{string} to an array of wide character codes, storing not more than
1397 @var{size} wide characters into the array beginning at @var{wstring}.
1398 The terminating null character counts towards the size, so if @var{size}
1399 is less than the actual number of wide characters resulting from
1400 @var{string}, no terminating null character is stored.
1401
1402 The conversion of characters from @var{string} begins in the initial
1403 shift state.
1404
1405 If an invalid multibyte character sequence is found, the @code{mbstowcs}
1406 function returns a value of @math{-1}.  Otherwise, it returns the number
1407 of wide characters stored in the array @var{wstring}.  This number does
1408 not include the terminating null character, which is present if the
1409 number is less than @var{size}.
1410
1411 Here is an example showing how to convert a string of multibyte
1412 characters, allocating enough space for the result.
1413
1414 @smallexample
1415 wchar_t *
1416 mbstowcs_alloc (const char *string)
1417 @{
1418   size_t size = strlen (string) + 1;
1419   wchar_t *buf = xmalloc (size * sizeof (wchar_t));
1420
1421   size = mbstowcs (buf, string, size);
1422   if (size == (size_t) -1)
1423     return NULL;
1424   buf = xrealloc (buf, (size + 1) * sizeof (wchar_t));
1425   return buf;
1426 @}
1427 @end smallexample
1428
1429 @end deftypefun
1430
1431 @comment stdlib.h
1432 @comment ISO
1433 @deftypefun size_t wcstombs (char *@var{string}, const wchar_t *@var{wstring}, size_t @var{size})
1434 The @code{wcstombs} (``wide character string to multibyte string'')
1435 function converts the null-terminated wide character array @var{wstring}
1436 into a string containing multibyte characters, storing not more than
1437 @var{size} bytes starting at @var{string}, followed by a terminating
1438 null character if there is room.  The conversion of characters begins in
1439 the initial shift state.
1440
1441 The terminating null character counts towards the size, so if @var{size}
1442 is less than or equal to the number of bytes needed in @var{wstring}, no
1443 terminating null character is stored.
1444
1445 If a code that does not correspond to a valid multibyte character is
1446 found, the @code{wcstombs} function returns a value of @math{-1}.
1447 Otherwise, the return value is the number of bytes stored in the array
1448 @var{string}.  This number does not include the terminating null character,
1449 which is present if the number is less than @var{size}.
1450 @end deftypefun
1451
1452 @node Shift State
1453 @subsection States in Non-reentrant Functions
1454
1455 In some multibyte character codes, the @emph{meaning} of any particular
1456 byte sequence is not fixed; it depends on what other sequences have come
1457 earlier in the same string.  Typically there are just a few sequences that
1458 can change the meaning of other sequences; these few are called
1459 @dfn{shift sequences} and we say that they set the @dfn{shift state} for
1460 other sequences that follow.
1461
1462 To illustrate shift state and shift sequences, suppose we decide that
1463 the sequence @code{0200} (just one byte) enters Japanese mode, in which
1464 pairs of bytes in the range from @code{0240} to @code{0377} are single
1465 characters, while @code{0201} enters Latin-1 mode, in which single bytes
1466 in the range from @code{0240} to @code{0377} are characters, and
1467 interpreted according to the ISO Latin-1 character set.  This is a
1468 multibyte code that has two alternative shift states (``Japanese mode''
1469 and ``Latin-1 mode''), and two shift sequences that specify particular
1470 shift states.
1471
1472 When the multibyte character code in use has shift states, then
1473 @code{mblen}, @code{mbtowc}, and @code{wctomb} must maintain and update
1474 the current shift state as they scan the string.  To make this work
1475 properly, you must follow these rules:
1476
1477 @itemize @bullet
1478 @item
1479 Before starting to scan a string, call the function with a null pointer
1480 for the multibyte character address---for example, @code{mblen (NULL,
1481 0)}.  This initializes the shift state to its standard initial value.
1482
1483 @item
1484 Scan the string one character at a time, in order.  Do not ``back up''
1485 and rescan characters already scanned, and do not intersperse the
1486 processing of different strings.
1487 @end itemize
1488
1489 Here is an example of using @code{mblen} following these rules:
1490
1491 @smallexample
1492 void
1493 scan_string (char *s)
1494 @{
1495   int length = strlen (s);
1496
1497   /* @r{Initialize shift state.}  */
1498   mblen (NULL, 0);
1499
1500   while (1)
1501     @{
1502       int thischar = mblen (s, length);
1503       /* @r{Deal with end of string and invalid characters.}  */
1504       if (thischar == 0)
1505         break;
1506       if (thischar == -1)
1507         @{
1508           error ("invalid multibyte character");
1509           break;
1510         @}
1511       /* @r{Advance past this character.}  */
1512       s += thischar;
1513       length -= thischar;
1514     @}
1515 @}
1516 @end smallexample
1517
1518 The functions @code{mblen}, @code{mbtowc} and @code{wctomb} are not
1519 reentrant when using a multibyte code that uses a shift state.  However,
1520 no other library functions call these functions, so you don't have to
1521 worry that the shift state will be changed mysteriously.
1522
1523
1524 @node Generic Charset Conversion
1525 @section Generic Charset Conversion
1526
1527 The conversion functions mentioned so far in this chapter all had in
1528 common that they operate on character sets that are not directly
1529 specified by the functions.  The multibyte encoding used is specified by
1530 the currently selected locale for the @code{LC_CTYPE} category.  The
1531 wide character set is fixed by the implementation (in the case of GNU C
1532 library it is always UCS-4 encoded @w{ISO 10646}.
1533
1534 This has of course several problems when it comes to general character
1535 conversion:
1536
1537 @itemize @bullet
1538 @item
1539 For every conversion where neither the source nor the destination
1540 character set is the character set of the locale for the @code{LC_CTYPE}
1541 category, one has to change the @code{LC_CTYPE} locale using
1542 @code{setlocale}.
1543
1544 Changing the @code{LC_TYPE} locale introduces major problems for the rest
1545 of the programs since several more functions (e.g., the character
1546 classification functions, @pxref{Classification of Characters}) use the
1547 @code{LC_CTYPE} category.
1548
1549 @item
1550 Parallel conversions to and from different character sets are not
1551 possible since the @code{LC_CTYPE} selection is global and shared by all
1552 threads.
1553
1554 @item
1555 If neither the source nor the destination character set is the character
1556 set used for @code{wchar_t} representation, there is at least a two-step
1557 process necessary to convert a text using the functions above.  One would
1558 have to select the source character set as the multibyte encoding,
1559 convert the text into a @code{wchar_t} text, select the destination
1560 character set as the multibyte encoding, and convert the wide character
1561 text to the multibyte (@math{=} destination) character set.
1562
1563 Even if this is possible (which is not guaranteed) it is a very tiring
1564 work.  Plus it suffers from the other two raised points even more due to
1565 the steady changing of the locale.
1566 @end itemize
1567
1568 The XPG2 standard defines a completely new set of functions, which has
1569 none of these limitations.  They are not at all coupled to the selected
1570 locales, and they have no constraints on the character sets selected for
1571 source and destination.  Only the set of available conversions limits
1572 them.  The standard does not specify that any conversion at all must be
1573 available.  Such availability is a measure of the quality of the
1574 implementation.
1575
1576 In the following text first the interface to @code{iconv} and then the
1577 conversion function, will be described.  Comparisons with other
1578 implementations will show what obstacles stand in the way of portable
1579 applications.  Finally, the implementation is described in so far as might
1580 interest the advanced user who wants to extend conversion capabilities.
1581
1582 @menu
1583 * Generic Conversion Interface::    Generic Character Set Conversion Interface.
1584 * iconv Examples::                  A complete @code{iconv} example.
1585 * Other iconv Implementations::     Some Details about other @code{iconv}
1586                                      Implementations.
1587 * glibc iconv Implementation::      The @code{iconv} Implementation in the GNU C
1588                                      library.
1589 @end menu
1590
1591 @node Generic Conversion Interface
1592 @subsection Generic Character Set Conversion Interface
1593
1594 This set of functions follows the traditional cycle of using a resource:
1595 open--use--close.  The interface consists of three functions, each of
1596 which implements one step.
1597
1598 Before the interfaces are described it is necessary to introduce a
1599 data type.  Just like other open--use--close interfaces the functions
1600 introduced here work using handles and the @file{iconv.h} header
1601 defines a special type for the handles used.
1602
1603 @comment iconv.h
1604 @comment XPG2
1605 @deftp {Data Type} iconv_t
1606 This data type is an abstract type defined in @file{iconv.h}.  The user
1607 must not assume anything about the definition of this type; it must be
1608 completely opaque.
1609
1610 Objects of this type can get assigned handles for the conversions using
1611 the @code{iconv} functions.  The objects themselves need not be freed, but
1612 the conversions for which the handles stand for have to.
1613 @end deftp
1614
1615 @noindent
1616 The first step is the function to create a handle.
1617
1618 @comment iconv.h
1619 @comment XPG2
1620 @deftypefun iconv_t iconv_open (const char *@var{tocode}, const char *@var{fromcode})
1621 The @code{iconv_open} function has to be used before starting a
1622 conversion.  The two parameters this function takes determine the
1623 source and destination character set for the conversion, and if the
1624 implementation has the possibility to perform such a conversion, the
1625 function returns a handle.
1626
1627 If the wanted conversion is not available, the @code{iconv_open} function
1628 returns @code{(iconv_t) -1}. In this case the global variable
1629 @code{errno} can have the following values:
1630
1631 @table @code
1632 @item EMFILE
1633 The process already has @code{OPEN_MAX} file descriptors open.
1634 @item ENFILE
1635 The system limit of open file is reached.
1636 @item ENOMEM
1637 Not enough memory to carry out the operation.
1638 @item EINVAL
1639 The conversion from @var{fromcode} to @var{tocode} is not supported.
1640 @end table
1641
1642 It is not possible to use the same descriptor in different threads to
1643 perform independent conversions.  The data structures associated
1644 with the descriptor include information about the conversion state.
1645 This must not be messed up by using it in different conversions.
1646
1647 An @code{iconv} descriptor is like a file descriptor as for every use a
1648 new descriptor must be created.  The descriptor does not stand for all
1649 of the conversions from @var{fromset} to @var{toset}.
1650
1651 The GNU C library implementation of @code{iconv_open} has one
1652 significant extension to other implementations.  To ease the extension
1653 of the set of available conversions, the implementation allows storing
1654 the necessary files with data and code in an arbitrary number of
1655 directories.  How this extension must be written will be explained below
1656 (@pxref{glibc iconv Implementation}).  Here it is only important to say
1657 that all directories mentioned in the @code{GCONV_PATH} environment
1658 variable are considered only if they contain a file @file{gconv-modules}.
1659 These directories need not necessarily be created by the system
1660 administrator.  In fact, this extension is introduced to help users
1661 writing and using their own, new conversions.  Of course, this does not
1662 work for security reasons in SUID binaries; in this case only the system
1663 directory is considered and this normally is
1664 @file{@var{prefix}/lib/gconv}.  The @code{GCONV_PATH} environment
1665 variable is examined exactly once at the first call of the
1666 @code{iconv_open} function.  Later modifications of the variable have no
1667 effect.
1668
1669 @pindex iconv.h
1670 The @code{iconv_open} function was introduced early in the X/Open
1671 Portability Guide, @w{version 2}.  It is supported by all commercial
1672 Unices as it is required for the Unix branding.  However, the quality and
1673 completeness of the implementation varies widely.  The @code{iconv_open}
1674 function is declared in @file{iconv.h}.
1675 @end deftypefun
1676
1677 The @code{iconv} implementation can associate large data structure with
1678 the handle returned by @code{iconv_open}.  Therefore, it is crucial to
1679 free all the resources once all conversions are carried out and the
1680 conversion is not needed anymore.
1681
1682 @comment iconv.h
1683 @comment XPG2
1684 @deftypefun int iconv_close (iconv_t @var{cd})
1685 The @code{iconv_close} function frees all resources associated with the
1686 handle @var{cd}, which must have been returned by a successful call to
1687 the @code{iconv_open} function.
1688
1689 If the function call was successful the return value is @math{0}.
1690 Otherwise it is @math{-1} and @code{errno} is set appropriately.
1691 Defined error are:
1692
1693 @table @code
1694 @item EBADF
1695 The conversion descriptor is invalid.
1696 @end table
1697
1698 @pindex iconv.h
1699 The @code{iconv_close} function was introduced together with the rest
1700 of the @code{iconv} functions in XPG2 and is declared in @file{iconv.h}.
1701 @end deftypefun
1702
1703 The standard defines only one actual conversion function.  This has,
1704 therefore, the most general interface: it allows conversion from one
1705 buffer to another.  Conversion from a file to a buffer, vice versa, or
1706 even file to file can be implemented on top of it.
1707
1708 @comment iconv.h
1709 @comment XPG2
1710 @deftypefun size_t iconv (iconv_t @var{cd}, char **@var{inbuf}, size_t *@var{inbytesleft}, char **@var{outbuf}, size_t *@var{outbytesleft})
1711 @cindex stateful
1712 The @code{iconv} function converts the text in the input buffer
1713 according to the rules associated with the descriptor @var{cd} and
1714 stores the result in the output buffer.  It is possible to call the
1715 function for the same text several times in a row since for stateful
1716 character sets the necessary state information is kept in the data
1717 structures associated with the descriptor.
1718
1719 The input buffer is specified by @code{*@var{inbuf}} and it contains
1720 @code{*@var{inbytesleft}} bytes.  The extra indirection is necessary for
1721 communicating the used input back to the caller (see below).  It is
1722 important to note that the buffer pointer is of type @code{char} and the
1723 length is measured in bytes even if the input text is encoded in wide
1724 characters.
1725
1726 The output buffer is specified in a similar way.  @code{*@var{outbuf}}
1727 points to the beginning of the buffer with at least
1728 @code{*@var{outbytesleft}} bytes room for the result.  The buffer
1729 pointer again is of type @code{char} and the length is measured in
1730 bytes.  If @var{outbuf} or @code{*@var{outbuf}} is a null pointer, the
1731 conversion is performed but no output is available.
1732
1733 If @var{inbuf} is a null pointer, the @code{iconv} function performs the
1734 necessary action to put the state of the conversion into the initial
1735 state.  This is obviously a no-op for non-stateful encodings, but if the
1736 encoding has a state, such a function call might put some byte sequences
1737 in the output buffer, which perform the necessary state changes.  The
1738 next call with @var{inbuf} not being a null pointer then simply goes on
1739 from the initial state.  It is important that the programmer never makes
1740 any assumption as to whether the conversion has to deal with states.
1741 Even if the input and output character sets are not stateful, the
1742 implementation might still have to keep states.  This is due to the
1743 implementation chosen for the GNU C library as it is described below.
1744 Therefore an @code{iconv} call to reset the state should always be
1745 performed if some protocol requires this for the output text.
1746
1747 The conversion stops for one of three reasons. The first is that all
1748 characters from the input buffer are converted.  This actually can mean
1749 two things: either all bytes from the input buffer are consumed or
1750 there are some bytes at the end of the buffer that possibly can form a
1751 complete character but the input is incomplete.  The second reason for a
1752 stop is that the output buffer is full.  And the third reason is that
1753 the input contains invalid characters.
1754
1755 In all of these cases the buffer pointers after the last successful
1756 conversion, for input and output buffer, are stored in @var{inbuf} and
1757 @var{outbuf}, and the available room in each buffer is stored in
1758 @var{inbytesleft} and @var{outbytesleft}.
1759
1760 Since the character sets selected in the @code{iconv_open} call can be
1761 almost arbitrary, there can be situations where the input buffer contains
1762 valid characters, which have no identical representation in the output
1763 character set.  The behavior in this situation is undefined.  The
1764 @emph{current} behavior of the GNU C library in this situation is to
1765 return with an error immediately.  This certainly is not the most
1766 desirable solution; therefore, future versions will provide better ones,
1767 but they are not yet finished.
1768
1769 If all input from the input buffer is successfully converted and stored
1770 in the output buffer, the function returns the number of non-reversible
1771 conversions performed.  In all other cases the return value is
1772 @code{(size_t) -1} and @code{errno} is set appropriately.  In such cases
1773 the value pointed to by @var{inbytesleft} is nonzero.
1774
1775 @table @code
1776 @item EILSEQ
1777 The conversion stopped because of an invalid byte sequence in the input.
1778 After the call, @code{*@var{inbuf}} points at the first byte of the
1779 invalid byte sequence.
1780
1781 @item E2BIG
1782 The conversion stopped because it ran out of space in the output buffer.
1783
1784 @item EINVAL
1785 The conversion stopped because of an incomplete byte sequence at the end
1786 of the input buffer.
1787
1788 @item EBADF
1789 The @var{cd} argument is invalid.
1790 @end table
1791
1792 @pindex iconv.h
1793 The @code{iconv} function was introduced in the XPG2 standard and is
1794 declared in the @file{iconv.h} header.
1795 @end deftypefun
1796
1797 The definition of the @code{iconv} function is quite good overall.  It
1798 provides quite flexible functionality.  The only problems lie in the
1799 boundary cases, which are incomplete byte sequences at the end of the
1800 input buffer and invalid input.  A third problem, which is not really
1801 a design problem, is the way conversions are selected.  The standard
1802 does not say anything about the legitimate names, a minimal set of
1803 available conversions.  We will see how this negatively impacts other
1804 implementations, as demonstrated below.
1805
1806 @node iconv Examples
1807 @subsection A complete @code{iconv} example
1808
1809 The example below features a solution for a common problem.  Given that
1810 one knows the internal encoding used by the system for @code{wchar_t}
1811 strings, one often is in the position to read text from a file and store
1812 it in wide character buffers.  One can do this using @code{mbsrtowcs},
1813 but then we run into the problems discussed above.
1814
1815 @smallexample
1816 int
1817 file2wcs (int fd, const char *charset, wchar_t *outbuf, size_t avail)
1818 @{
1819   char inbuf[BUFSIZ];
1820   size_t insize = 0;
1821   char *wrptr = (char *) outbuf;
1822   int result = 0;
1823   iconv_t cd;
1824
1825   cd = iconv_open ("WCHAR_T", charset);
1826   if (cd == (iconv_t) -1)
1827     @{
1828       /* @r{Something went wrong.}  */
1829       if (errno == EINVAL)
1830         error (0, 0, "conversion from '%s' to wchar_t not available",
1831                charset);
1832       else
1833         perror ("iconv_open");
1834
1835       /* @r{Terminate the output string.}  */
1836       *outbuf = L'\0';
1837
1838       return -1;
1839     @}
1840
1841   while (avail > 0)
1842     @{
1843       size_t nread;
1844       size_t nconv;
1845       char *inptr = inbuf;
1846
1847       /* @r{Read more input.}  */
1848       nread = read (fd, inbuf + insize, sizeof (inbuf) - insize);
1849       if (nread == 0)
1850         @{
1851           /* @r{When we come here the file is completely read.}
1852              @r{This still could mean there are some unused}
1853              @r{characters in the @code{inbuf}.  Put them back.}  */
1854           if (lseek (fd, -insize, SEEK_CUR) == -1)
1855             result = -1;
1856
1857           /* @r{Now write out the byte sequence to get into the}
1858              @r{initial state if this is necessary.}  */
1859           iconv (cd, NULL, NULL, &wrptr, &avail);
1860
1861           break;
1862         @}
1863       insize += nread;
1864
1865       /* @r{Do the conversion.}  */
1866       nconv = iconv (cd, &inptr, &insize, &wrptr, &avail);
1867       if (nconv == (size_t) -1)
1868         @{
1869           /* @r{Not everything went right.  It might only be}
1870              @r{an unfinished byte sequence at the end of the}
1871              @r{buffer.  Or it is a real problem.}  */
1872           if (errno == EINVAL)
1873             /* @r{This is harmless.  Simply move the unused}
1874                @r{bytes to the beginning of the buffer so that}
1875                @r{they can be used in the next round.}  */
1876             memmove (inbuf, inptr, insize);
1877           else
1878             @{
1879               /* @r{It is a real problem.  Maybe we ran out of}
1880                  @r{space in the output buffer or we have invalid}
1881                  @r{input.  In any case back the file pointer to}
1882                  @r{the position of the last processed byte.}  */
1883               lseek (fd, -insize, SEEK_CUR);
1884               result = -1;
1885               break;
1886             @}
1887         @}
1888     @}
1889
1890   /* @r{Terminate the output string.}  */
1891   if (avail >= sizeof (wchar_t))
1892     *((wchar_t *) wrptr) = L'\0';
1893
1894   if (iconv_close (cd) != 0)
1895     perror ("iconv_close");
1896
1897   return (wchar_t *) wrptr - outbuf;
1898 @}
1899 @end smallexample
1900
1901 @cindex stateful
1902 This example shows the most important aspects of using the @code{iconv}
1903 functions.  It shows how successive calls to @code{iconv} can be used to
1904 convert large amounts of text.  The user does not have to care about
1905 stateful encodings as the functions take care of everything.
1906
1907 An interesting point is the case where @code{iconv} returns an error and
1908 @code{errno} is set to @code{EINVAL}.  This is not really an error in the
1909 transformation.  It can happen whenever the input character set contains
1910 byte sequences of more than one byte for some character and texts are not
1911 processed in one piece.  In this case there is a chance that a multibyte
1912 sequence is cut.  The caller can then simply read the remainder of the
1913 takes and feed the offending bytes together with new character from the
1914 input to @code{iconv} and continue the work.  The internal state kept in
1915 the descriptor is @emph{not} unspecified after such an event as is the
1916 case with the conversion functions from the @w{ISO C} standard.
1917
1918 The example also shows the problem of using wide character strings with
1919 @code{iconv}.  As explained in the description of the @code{iconv}
1920 function above, the function always takes a pointer to a @code{char}
1921 array and the available space is measured in bytes.  In the example, the
1922 output buffer is a wide character buffer; therefore, we use a local
1923 variable @var{wrptr} of type @code{char *}, which is used in the
1924 @code{iconv} calls.
1925
1926 This looks rather innocent but can lead to problems on platforms that
1927 have tight restriction on alignment.  Therefore the caller of @code{iconv}
1928 has to make sure that the pointers passed are suitable for access of
1929 characters from the appropriate character set.  Since, in the
1930 above case, the input parameter to the function is a @code{wchar_t}
1931 pointer, this is the case (unless the user violates alignment when
1932 computing the parameter).  But in other situations, especially when
1933 writing generic functions where one does not know what type of character
1934 set one uses and, therefore, treats text as a sequence of bytes, it might
1935 become tricky.
1936
1937 @node Other iconv Implementations
1938 @subsection Some Details about other @code{iconv} Implementations
1939
1940 This is not really the place to discuss the @code{iconv} implementation
1941 of other systems but it is necessary to know a bit about them to write
1942 portable programs.  The above mentioned problems with the specification
1943 of the @code{iconv} functions can lead to portability issues.
1944
1945 The first thing to notice is that, due to the large number of character
1946 sets in use, it is certainly not practical to encode the conversions
1947 directly in the C library.  Therefore, the conversion information must
1948 come from files outside the C library.  This is usually done in one or
1949 both of the following ways:
1950
1951 @itemize @bullet
1952 @item
1953 The C library contains a set of generic conversion functions that can
1954 read the needed conversion tables and other information from data files.
1955 These files get loaded when necessary.
1956
1957 This solution is problematic as it requires a great deal of effort to
1958 apply to all character sets (potentially an infinite set).  The
1959 differences in the structure of the different character sets is so large
1960 that many different variants of the table-processing functions must be
1961 developed.  In addition, the generic nature of these functions make them
1962 slower than specifically implemented functions.
1963
1964 @item
1965 The C library only contains a framework that can dynamically load
1966 object files and execute the conversion functions contained therein.
1967
1968 This solution provides much more flexibility.  The C library itself
1969 contains only very little code and therefore reduces the general memory
1970 footprint.  Also, with a documented interface between the C library and
1971 the loadable modules it is possible for third parties to extend the set
1972 of available conversion modules.  A drawback of this solution is that
1973 dynamic loading must be available.
1974 @end itemize
1975
1976 Some implementations in commercial Unices implement a mixture of these
1977 possibilities; the majority implement only the second solution.  Using
1978 loadable modules moves the code out of the library itself and keeps
1979 the door open for extensions and improvements, but this design is also
1980 limiting on some platforms since not many platforms support dynamic
1981 loading in statically linked programs.  On platforms without this
1982 capability it is therefore not possible to use this interface in
1983 statically linked programs.  The GNU C library has, on ELF platforms, no
1984 problems with dynamic loading in these situations; therefore, this
1985 point is moot.  The danger is that one gets acquainted with this
1986 situation and forgets about the restrictions on other systems.
1987
1988 A second thing to know about other @code{iconv} implementations is that
1989 the number of available conversions is often very limited.  Some
1990 implementations provide, in the standard release (not special
1991 international or developer releases), at most 100 to 200 conversion
1992 possibilities.  This does not mean 200 different character sets are
1993 supported; for example, conversions from one character set to a set of 10
1994 others might count as 10 conversions.  Together with the other direction
1995 this makes 20 conversion possibilities used up by one character set.  One
1996 can imagine the thin coverage these platform provide.  Some Unix vendors
1997 even provide only a handful of conversions, which renders them useless for
1998 almost all uses.
1999
2000 This directly leads to a third and probably the most problematic point.
2001 The way the @code{iconv} conversion functions are implemented on all
2002 known Unix systems and the availability of the conversion functions from
2003 character set @math{@cal{A}} to @math{@cal{B}} and the conversion from
2004 @math{@cal{B}} to @math{@cal{C}} does @emph{not} imply that the
2005 conversion from @math{@cal{A}} to @math{@cal{C}} is available.
2006
2007 This might not seem unreasonable and problematic at first, but it is a
2008 quite big problem as one will notice shortly after hitting it.  To show
2009 the problem we assume to write a program that has to convert from
2010 @math{@cal{A}} to @math{@cal{C}}.  A call like
2011
2012 @smallexample
2013 cd = iconv_open ("@math{@cal{C}}", "@math{@cal{A}}");
2014 @end smallexample
2015
2016 @noindent
2017 fails according to the assumption above.  But what does the program
2018 do now?  The conversion is necessary; therefore, simply giving up is not
2019 an option.
2020
2021 This is a nuisance.  The @code{iconv} function should take care of this.
2022 But how should the program proceed from here on?  If it tries to convert
2023 to character set @math{@cal{B}}, first the two @code{iconv_open}
2024 calls
2025
2026 @smallexample
2027 cd1 = iconv_open ("@math{@cal{B}}", "@math{@cal{A}}");
2028 @end smallexample
2029
2030 @noindent
2031 and
2032
2033 @smallexample
2034 cd2 = iconv_open ("@math{@cal{C}}", "@math{@cal{B}}");
2035 @end smallexample
2036
2037 @noindent
2038 will succeed, but how to find @math{@cal{B}}?
2039
2040 Unfortunately, the answer is: there is no general solution.  On some
2041 systems guessing might help.  On those systems most character sets can
2042 convert to and from UTF-8 encoded @w{ISO 10646} or Unicode text. Beside
2043 this only some very system-specific methods can help.  Since the
2044 conversion functions come from loadable modules and these modules must
2045 be stored somewhere in the filesystem, one @emph{could} try to find them
2046 and determine from the available file which conversions are available
2047 and whether there is an indirect route from @math{@cal{A}} to
2048 @math{@cal{C}}.
2049
2050 This example shows one of the design errors of @code{iconv} mentioned
2051 above.  It should at least be possible to determine the list of available
2052 conversion programmatically so that if @code{iconv_open} says there is no
2053 such conversion, one could make sure this also is true for indirect
2054 routes.
2055
2056 @node glibc iconv Implementation
2057 @subsection The @code{iconv} Implementation in the GNU C library
2058
2059 After reading about the problems of @code{iconv} implementations in the
2060 last section it is certainly good to note that the implementation in
2061 the GNU C library has none of the problems mentioned above.  What
2062 follows is a step-by-step analysis of the points raised above.  The
2063 evaluation is based on the current state of the development (as of
2064 January 1999).  The development of the @code{iconv} functions is not
2065 complete, but basic functionality has solidified.
2066
2067 The GNU C library's @code{iconv} implementation uses shared loadable
2068 modules to implement the conversions.  A very small number of
2069 conversions are built into the library itself but these are only rather
2070 trivial conversions.
2071
2072 All the benefits of loadable modules are available in the GNU C library
2073 implementation.  This is especially appealing since the interface is
2074 well documented (see below), and it, therefore, is easy to write new
2075 conversion modules.  The drawback of using loadable objects is not a
2076 problem in the GNU C library, at least on ELF systems.  Since the
2077 library is able to load shared objects even in statically linked
2078 binaries, static linking need not be forbidden in case one wants to use
2079 @code{iconv}.
2080
2081 The second mentioned problem is the number of supported conversions.
2082 Currently, the GNU C library supports more than 150 character sets.  The
2083 way the implementation is designed the number of supported conversions
2084 is greater than 22350 (@math{150} times @math{149}).  If any conversion
2085 from or to a character set is missing, it can be added easily.
2086
2087 Particularly impressive as it may be, this high number is due to the
2088 fact that the GNU C library implementation of @code{iconv} does not have
2089 the third problem mentioned above (i.e., whenever there is a conversion
2090 from a character set @math{@cal{A}} to @math{@cal{B}} and from
2091 @math{@cal{B}} to @math{@cal{C}} it is always possible to convert from
2092 @math{@cal{A}} to @math{@cal{C}} directly).  If the @code{iconv_open}
2093 returns an error and sets @code{errno} to @code{EINVAL}, there is no
2094 known way, directly or indirectly, to perform the wanted conversion.
2095
2096 @cindex triangulation
2097 Triangulation is achieved by providing for each character set a
2098 conversion from and to UCS-4 encoded @w{ISO 10646}.  Using @w{ISO 10646}
2099 as an intermediate representation it is possible to @dfn{triangulate}
2100 (i.e., convert with an intermediate representation).
2101
2102 There is no inherent requirement to provide a conversion to @w{ISO
2103 10646} for a new character set, and it is also possible to provide other
2104 conversions where neither source nor destination character set is @w{ISO
2105 10646}.  The existing set of conversions is simply meant to cover all
2106 conversions that might be of interest.
2107
2108 @cindex ISO-2022-JP
2109 @cindex EUC-JP
2110 All currently available conversions use the triangulation method above,
2111 making conversion run unnecessarily slow.  If, for example, somebody
2112 often needs the conversion from ISO-2022-JP to EUC-JP, a quicker solution
2113 would involve direct conversion between the two character sets, skipping
2114 the input to @w{ISO 10646} first.  The two character sets of interest
2115 are much more similar to each other than to @w{ISO 10646}.
2116
2117 In such a situation one easily can write a new conversion and provide it
2118 as a better alternative.  The GNU C library @code{iconv} implementation
2119 would automatically use the module implementing the conversion if it is
2120 specified to be more efficient.
2121
2122 @subsubsection Format of @file{gconv-modules} files
2123
2124 All information about the available conversions comes from a file named
2125 @file{gconv-modules}, which can be found in any of the directories along
2126 the @code{GCONV_PATH}.  The @file{gconv-modules} files are line-oriented
2127 text files, where each of the lines has one of the following formats:
2128
2129 @itemize @bullet
2130 @item
2131 If the first non-whitespace character is a @kbd{#} the line contains only
2132 comments and is ignored.
2133
2134 @item
2135 Lines starting with @code{alias} define an alias name for a character
2136 set.  Two more words are expected on the line.  The first word
2137 defines the alias name, and the second defines the original name of the
2138 character set.  The effect is that it is possible to use the alias name
2139 in the @var{fromset} or @var{toset} parameters of @code{iconv_open} and
2140 achieve the same result as when using the real character set name.
2141
2142 This is quite important as a character set has often many different
2143 names.  There is normally an official name but this need not correspond to
2144 the most popular name.  Beside this many character sets have special
2145 names that are somehow constructed.  For example, all character sets
2146 specified by the ISO have an alias of the form @code{ISO-IR-@var{nnn}}
2147 where @var{nnn} is the registration number.  This allows programs that
2148 know about the registration number to construct character set names and
2149 use them in @code{iconv_open} calls.  More on the available names and
2150 aliases follows below.
2151
2152 @item
2153 Lines starting with @code{module} introduce an available conversion
2154 module.  These lines must contain three or four more words.
2155
2156 The first word specifies the source character set, the second word the
2157 destination character set of conversion implemented in this module, and
2158 the third word is the name of the loadable module.  The filename is
2159 constructed by appending the usual shared object suffix (normally
2160 @file{.so}) and this file is then supposed to be found in the same
2161 directory the @file{gconv-modules} file is in.  The last word on the line,
2162 which is optional, is a numeric value representing the cost of the
2163 conversion.  If this word is missing, a cost of @math{1} is assumed.  The
2164 numeric value itself does not matter that much; what counts are the
2165 relative values of the sums of costs for all possible conversion paths.
2166 Below is a more precise description of the use of the cost value.
2167 @end itemize
2168
2169 Returning to the example above where one has written a module to directly
2170 convert from ISO-2022-JP to EUC-JP and back.  All that has to be done is
2171 to put the new module, let its name be ISO2022JP-EUCJP.so, in a directory
2172 and add a file @file{gconv-modules} with the following content in the
2173 same directory:
2174
2175 @smallexample
2176 module  ISO-2022-JP//   EUC-JP//        ISO2022JP-EUCJP    1
2177 module  EUC-JP//        ISO-2022-JP//   ISO2022JP-EUCJP    1
2178 @end smallexample
2179
2180 To see why this is sufficient, it is necessary to understand how the
2181 conversion used by @code{iconv} (and described in the descriptor) is
2182 selected.  The approach to this problem is quite simple.
2183
2184 At the first call of the @code{iconv_open} function the program reads
2185 all available @file{gconv-modules} files and builds up two tables: one
2186 containing all the known aliases and another that contains the
2187 information about the conversions and which shared object implements
2188 them.
2189
2190 @subsubsection Finding the conversion path in @code{iconv}
2191
2192 The set of available conversions form a directed graph with weighted
2193 edges.  The weights on the edges are the costs specified in the
2194 @file{gconv-modules} files.  The @code{iconv_open} function uses an
2195 algorithm suitable for search for the best path in such a graph and so
2196 constructs a list of conversions that must be performed in succession
2197 to get the transformation from the source to the destination character
2198 set.
2199
2200 Explaining why the above @file{gconv-modules} files allows the
2201 @code{iconv} implementation to resolve the specific ISO-2022-JP to
2202 EUC-JP conversion module instead of the conversion coming with the
2203 library itself is straightforward.  Since the latter conversion takes two
2204 steps (from ISO-2022-JP to @w{ISO 10646} and then from @w{ISO 10646} to
2205 EUC-JP), the cost is @math{1+1 = 2}.  The above @file{gconv-modules}
2206 file, however, specifies that the new conversion modules can perform this
2207 conversion with only the cost of @math{1}.
2208
2209 A mysterious item about the @file{gconv-modules} file above (and also
2210 the file coming with the GNU C library) are the names of the character
2211 sets specified in the @code{module} lines.  Why do almost all the names
2212 end in @code{//}?  And this is not all: the names can actually be
2213 regular expressions.  At this point in time this mystery should not be
2214 revealed, unless you have the relevant spell-casting materials: ashes
2215 from an original @w{DOS 6.2} boot disk burnt in effigy, a crucifix
2216 blessed by St.@: Emacs, assorted herbal roots from Central America, sand
2217 from Cebu, etc.  Sorry!  @strong{The part of the implementation where
2218 this is used is not yet finished.  For now please simply follow the
2219 existing examples.  It'll become clearer once it is. --drepper}
2220
2221 A last remark about the @file{gconv-modules} is about the names not
2222 ending with @code{//}.  A character set named @code{INTERNAL} is often
2223 mentioned.  From the discussion above and the chosen name it should have
2224 become clear that this is the name for the representation used in the
2225 intermediate step of the triangulation.  We have said that this is UCS-4
2226 but actually that is not quite right.  The UCS-4 specification also
2227 includes the specification of the byte ordering used.  Since a UCS-4 value
2228 consists of four bytes, a stored value is effected by byte ordering.  The
2229 internal representation is @emph{not} the same as UCS-4 in case the byte
2230 ordering of the processor (or at least the running process) is not the
2231 same as the one required for UCS-4.  This is done for performance reasons
2232 as one does not want to perform unnecessary byte-swapping operations if
2233 one is not interested in actually seeing the result in UCS-4.  To avoid
2234 trouble with endianness, the internal representation consistently is named
2235 @code{INTERNAL} even on big-endian systems where the representations are
2236 identical.
2237
2238 @subsubsection @code{iconv} module data structures
2239
2240 So far this section has described how modules are located and considered
2241 to be used.  What remains to be described is the interface of the modules
2242 so that one can write new ones. This section describes the interface as
2243 it is in use in January 1999.  The interface will change a bit in the
2244 future but, with luck, only in an upwardly compatible way.
2245
2246 The definitions necessary to write new modules are publicly available
2247 in the non-standard header @file{gconv.h}.  The following text,
2248 therefore, describes the definitions from this header file.  First,
2249 however, it is necessary to get an overview.
2250
2251 From the perspective of the user of @code{iconv} the interface is quite
2252 simple: the @code{iconv_open} function returns a handle that can be used
2253 in calls to @code{iconv}, and finally the handle is freed with a call to
2254 @code{iconv_close}.  The problem is that the handle has to be able to
2255 represent the possibly long sequences of conversion steps and also the
2256 state of each conversion since the handle is all that is passed to the
2257 @code{iconv} function.  Therefore, the data structures are really the
2258 elements necessary to understanding the implementation.
2259
2260 We need two different kinds of data structures.  The first describes the
2261 conversion and the second describes the state etc.  There are really two
2262 type definitions like this in @file{gconv.h}.
2263 @pindex gconv.h
2264
2265 @comment gconv.h
2266 @comment GNU
2267 @deftp {Data type} {struct __gconv_step}
2268 This data structure describes one conversion a module can perform.  For
2269 each function in a loaded module with conversion functions there is
2270 exactly one object of this type.  This object is shared by all users of
2271 the conversion (i.e., this object does not contain any information
2272 corresponding to an actual conversion; it only describes the conversion
2273 itself).
2274
2275 @table @code
2276 @item struct __gconv_loaded_object *__shlib_handle
2277 @itemx const char *__modname
2278 @itemx int __counter
2279 All these elements of the structure are used internally in the C library
2280 to coordinate loading and unloading the shared.  One must not expect any
2281 of the other elements to be available or initialized.
2282
2283 @item const char *__from_name
2284 @itemx const char *__to_name
2285 @code{__from_name} and @code{__to_name} contain the names of the source and
2286 destination character sets.  They can be used to identify the actual
2287 conversion to be carried out since one module might implement conversions
2288 for more than one character set and/or direction.
2289
2290 @item gconv_fct __fct
2291 @itemx gconv_init_fct __init_fct
2292 @itemx gconv_end_fct __end_fct
2293 These elements contain pointers to the functions in the loadable module.
2294 The interface will be explained below.
2295
2296 @item int __min_needed_from
2297 @itemx int __max_needed_from
2298 @itemx int __min_needed_to
2299 @itemx int __max_needed_to;
2300 These values have to be supplied in the init function of the module.  The
2301 @code{__min_needed_from} value specifies how many bytes a character of
2302 the source character set at least needs.  The @code{__max_needed_from}
2303 specifies the maximum value that also includes possible shift sequences.
2304
2305 The @code{__min_needed_to} and @code{__max_needed_to} values serve the
2306 same purpose as @code{__min_needed_from} and @code{__max_needed_from} but
2307 this time for the destination character set.
2308
2309 It is crucial that these values be accurate since otherwise the
2310 conversion functions will have problems or not work at all.
2311
2312 @item int __stateful
2313 This element must also be initialized by the init function.
2314 @code{int __stateful} is nonzero if the source character set is stateful.
2315 Otherwise it is zero.
2316
2317 @item void *__data
2318 This element can be used freely by the conversion functions in the
2319 module.  @code{void *__data} can be used to communicate extra information
2320 from one call to another.  @code{void *__data} need not be initialized if
2321 not needed at all.  If @code{void *__data} element is assigned a pointer
2322 to dynamically allocated memory (presumably in the init function) it has
2323 to be made sure that the end function deallocates the memory.  Otherwise
2324 the application will leak memory.
2325
2326 It is important to be aware that this data structure is shared by all
2327 users of this specification conversion and therefore the @code{__data}
2328 element must not contain data specific to one specific use of the
2329 conversion function.
2330 @end table
2331 @end deftp
2332
2333 @comment gconv.h
2334 @comment GNU
2335 @deftp {Data type} {struct __gconv_step_data}
2336 This is the data structure that contains the information specific to
2337 each use of the conversion functions.
2338
2339
2340 @table @code
2341 @item char *__outbuf
2342 @itemx char *__outbufend
2343 These elements specify the output buffer for the conversion step.  The
2344 @code{__outbuf} element points to the beginning of the buffer, and
2345 @code{__outbufend} points to the byte following the last byte in the
2346 buffer.  The conversion function must not assume anything about the size
2347 of the buffer but it can be safely assumed the there is room for at
2348 least one complete character in the output buffer.
2349
2350 Once the conversion is finished, if the conversion is the last step, the
2351 @code{__outbuf} element must be modified to point after the last byte
2352 written into the buffer to signal how much output is available.  If this
2353 conversion step is not the last one, the element must not be modified.
2354 The @code{__outbufend} element must not be modified.
2355
2356 @item int __is_last
2357 This element is nonzero if this conversion step is the last one.  This
2358 information is necessary for the recursion.  See the description of the
2359 conversion function internals below.  This element must never be
2360 modified.
2361
2362 @item int __invocation_counter
2363 The conversion function can use this element to see how many calls of
2364 the conversion function already happened.  Some character sets require a
2365 certain prolog when generating output, and by comparing this value with
2366 zero, one can find out whether it is the first call and whether,
2367 therefore, the prolog should be emitted.  This element must never be
2368 modified.
2369
2370 @item int __internal_use
2371 This element is another one rarely used but needed in certain
2372 situations.  It is assigned a nonzero value in case the conversion
2373 functions are used to implement @code{mbsrtowcs} et.al.@: (i.e., the
2374 function is not used directly through the @code{iconv} interface).
2375
2376 This sometimes makes a difference as it is expected that the
2377 @code{iconv} functions are used to translate entire texts while the
2378 @code{mbsrtowcs} functions are normally used only to convert single
2379 strings and might be used multiple times to convert entire texts.
2380
2381 But in this situation we would have problem complying with some rules of
2382 the character set specification.  Some character sets require a prolog,
2383 which must appear exactly once for an entire text.  If a number of
2384 @code{mbsrtowcs} calls are used to convert the text, only the first call
2385 must add the prolog.  However, because there is no communication between the
2386 different calls of @code{mbsrtowcs}, the conversion functions have no
2387 possibility to find this out.  The situation is different for sequences
2388 of @code{iconv} calls since the handle allows access to the needed
2389 information.
2390
2391 The @code{int __internal_use} element is mostly used together with
2392 @code{__invocation_counter} as follows:
2393
2394 @smallexample
2395 if (!data->__internal_use
2396      && data->__invocation_counter == 0)
2397   /* @r{Emit prolog.}  */
2398   @dots{}
2399 @end smallexample
2400
2401 This element must never be modified.
2402
2403 @item mbstate_t *__statep
2404 The @code{__statep} element points to an object of type @code{mbstate_t}
2405 (@pxref{Keeping the state}).  The conversion of a stateful character
2406 set must use the object pointed to by @code{__statep} to store
2407 information about the conversion state.  The @code{__statep} element
2408 itself must never be modified.
2409
2410 @item mbstate_t __state
2411 This element must @emph{never} be used directly.  It is only part of
2412 this structure to have the needed space allocated.
2413 @end table
2414 @end deftp
2415
2416 @subsubsection @code{iconv} module interfaces
2417
2418 With the knowledge about the data structures we now can describe the
2419 conversion function itself.  To understand the interface a bit of
2420 knowledge is necessary about the functionality in the C library that
2421 loads the objects with the conversions.
2422
2423 It is often the case that one conversion is used more than once (i.e.,
2424 there are several @code{iconv_open} calls for the same set of character
2425 sets during one program run).  The @code{mbsrtowcs} et.al.@: functions in
2426 the GNU C library also use the @code{iconv} functionality, which
2427 increases the number of uses of the same functions even more.
2428
2429 Because of this multiple use of conversions, the modules do not get
2430 loaded exclusively for one conversion.  Instead a module once loaded can
2431 be used by an arbitrary number of @code{iconv} or @code{mbsrtowcs} calls
2432 at the same time.  The splitting of the information between conversion-
2433 function-specific information and conversion data makes this possible.
2434 The last section showed the two data structures used to do this.
2435
2436 This is of course also reflected in the interface and semantics of the
2437 functions that the modules must provide.  There are three functions that
2438 must have the following names:
2439
2440 @table @code
2441 @item gconv_init
2442 The @code{gconv_init} function initializes the conversion function
2443 specific data structure.  This very same object is shared by all
2444 conversions that use this conversion and, therefore, no state information
2445 about the conversion itself must be stored in here.  If a module
2446 implements more than one conversion, the @code{gconv_init} function will
2447 be called multiple times.
2448
2449 @item gconv_end
2450 The @code{gconv_end} function is responsible for freeing all resources
2451 allocated by the @code{gconv_init} function.  If there is nothing to do,
2452 this function can be missing.  Special care must be taken if the module
2453 implements more than one conversion and the @code{gconv_init} function
2454 does not allocate the same resources for all conversions.
2455
2456 @item gconv
2457 This is the actual conversion function.  It is called to convert one
2458 block of text.  It gets passed the conversion step information
2459 initialized by @code{gconv_init} and the conversion data, specific to
2460 this use of the conversion functions.
2461 @end table
2462
2463 There are three data types defined for the three module interface
2464 functions and these define the interface.
2465
2466 @comment gconv.h
2467 @comment GNU
2468 @deftypevr {Data type} int {(*__gconv_init_fct)} (struct __gconv_step *)
2469 This specifies the interface of the initialization function of the
2470 module.  It is called exactly once for each conversion the module
2471 implements.
2472
2473 As explained in the description of the @code{struct __gconv_step} data
2474 structure above the initialization function has to initialize parts of
2475 it.
2476
2477 @table @code
2478 @item __min_needed_from
2479 @itemx __max_needed_from
2480 @itemx __min_needed_to
2481 @itemx __max_needed_to
2482 These elements must be initialized to the exact numbers of the minimum
2483 and maximum number of bytes used by one character in the source and
2484 destination character sets, respectively.  If the characters all have the
2485 same size, the minimum and maximum values are the same.
2486
2487 @item __stateful
2488 This element must be initialized to an nonzero value if the source
2489 character set is stateful.  Otherwise it must be zero.
2490 @end table
2491
2492 If the initialization function needs to communicate some information
2493 to the conversion function, this communication can happen using the
2494 @code{__data} element of the @code{__gconv_step} structure.  But since
2495 this data is shared by all the conversions, it must not be modified by
2496 the conversion function.  The example below shows how this can be used.
2497
2498 @smallexample
2499 #define MIN_NEEDED_FROM         1
2500 #define MAX_NEEDED_FROM         4
2501 #define MIN_NEEDED_TO           4
2502 #define MAX_NEEDED_TO           4
2503
2504 int
2505 gconv_init (struct __gconv_step *step)
2506 @{
2507   /* @r{Determine which direction.}  */
2508   struct iso2022jp_data *new_data;
2509   enum direction dir = illegal_dir;
2510   enum variant var = illegal_var;
2511   int result;
2512
2513   if (__strcasecmp (step->__from_name, "ISO-2022-JP//") == 0)
2514     @{
2515       dir = from_iso2022jp;
2516       var = iso2022jp;
2517     @}
2518   else if (__strcasecmp (step->__to_name, "ISO-2022-JP//") == 0)
2519     @{
2520       dir = to_iso2022jp;
2521       var = iso2022jp;
2522     @}
2523   else if (__strcasecmp (step->__from_name, "ISO-2022-JP-2//") == 0)
2524     @{
2525       dir = from_iso2022jp;
2526       var = iso2022jp2;
2527     @}
2528   else if (__strcasecmp (step->__to_name, "ISO-2022-JP-2//") == 0)
2529     @{
2530       dir = to_iso2022jp;
2531       var = iso2022jp2;
2532     @}
2533
2534   result = __GCONV_NOCONV;
2535   if (dir != illegal_dir)
2536     @{
2537       new_data = (struct iso2022jp_data *)
2538         malloc (sizeof (struct iso2022jp_data));
2539
2540       result = __GCONV_NOMEM;
2541       if (new_data != NULL)
2542         @{
2543           new_data->dir = dir;
2544           new_data->var = var;
2545           step->__data = new_data;
2546
2547           if (dir == from_iso2022jp)
2548             @{
2549               step->__min_needed_from = MIN_NEEDED_FROM;
2550               step->__max_needed_from = MAX_NEEDED_FROM;
2551               step->__min_needed_to = MIN_NEEDED_TO;
2552               step->__max_needed_to = MAX_NEEDED_TO;
2553             @}
2554           else
2555             @{
2556               step->__min_needed_from = MIN_NEEDED_TO;
2557               step->__max_needed_from = MAX_NEEDED_TO;
2558               step->__min_needed_to = MIN_NEEDED_FROM;
2559               step->__max_needed_to = MAX_NEEDED_FROM + 2;
2560             @}
2561
2562           /* @r{Yes, this is a stateful encoding.}  */
2563           step->__stateful = 1;
2564
2565           result = __GCONV_OK;
2566         @}
2567     @}
2568
2569   return result;
2570 @}
2571 @end smallexample
2572
2573 The function first checks which conversion is wanted.  The module from
2574 which this function is taken implements four different conversions;
2575 which one is selected can be determined by comparing the names.  The
2576 comparison should always be done without paying attention to the case.
2577
2578 Next, a data structure, which contains the necessary information about
2579 which conversion is selected, is allocated.  The data structure
2580 @code{struct iso2022jp_data} is locally defined since, outside the
2581 module, this data is not used at all.  Please note that if all four
2582 conversions this modules supports are requested there are four data
2583 blocks.
2584
2585 One interesting thing is the initialization of the @code{__min_} and
2586 @code{__max_} elements of the step data object.  A single ISO-2022-JP
2587 character can consist of one to four bytes.  Therefore the
2588 @code{MIN_NEEDED_FROM} and @code{MAX_NEEDED_FROM} macros are defined
2589 this way.  The output is always the @code{INTERNAL} character set (aka
2590 UCS-4) and therefore each character consists of exactly four bytes.  For
2591 the conversion from @code{INTERNAL} to ISO-2022-JP we have to take into
2592 account that escape sequences might be necessary to switch the character
2593 sets.  Therefore the @code{__max_needed_to} element for this direction
2594 gets assigned @code{MAX_NEEDED_FROM + 2}.  This takes into account the
2595 two bytes needed for the escape sequences to single the switching.  The
2596 asymmetry in the maximum values for the two directions can be explained
2597 easily: when reading ISO-2022-JP text, escape sequences can be handled
2598 alone (i.e., it is not necessary to process a real character since the
2599 effect of the escape sequence can be recorded in the state information).
2600 The situation is different for the other direction.  Since it is in
2601 general not known which character comes next, one cannot emit escape
2602 sequences to change the state in advance.  This means the escape
2603 sequences that have to be emitted together with the next character.
2604 Therefore one needs more room than only for the character itself.
2605
2606 The possible return values of the initialization function are:
2607
2608 @table @code
2609 @item __GCONV_OK
2610 The initialization succeeded
2611 @item __GCONV_NOCONV
2612 The requested conversion is not supported in the module.  This can
2613 happen if the @file{gconv-modules} file has errors.
2614 @item __GCONV_NOMEM
2615 Memory required to store additional information could not be allocated.
2616 @end table
2617 @end deftypevr
2618
2619 The function called before the module is unloaded is significantly
2620 easier.  It often has nothing at all to do; in which case it can be left
2621 out completely.
2622
2623 @comment gconv.h
2624 @comment GNU
2625 @deftypevr {Data type} void {(*__gconv_end_fct)} (struct gconv_step *)
2626 The task of this function is to free all resources allocated in the
2627 initialization function.  Therefore only the @code{__data} element of
2628 the object pointed to by the argument is of interest.  Continuing the
2629 example from the initialization function, the finalization function
2630 looks like this:
2631
2632 @smallexample
2633 void
2634 gconv_end (struct __gconv_step *data)
2635 @{
2636   free (data->__data);
2637 @}
2638 @end smallexample
2639 @end deftypevr
2640
2641 The most important function is the conversion function itself, which can
2642 get quite complicated for complex character sets.  But since this is not
2643 of interest here, we will only describe a possible skeleton for the
2644 conversion function.
2645
2646 @comment gconv.h
2647 @comment GNU
2648 @deftypevr {Data type} int {(*__gconv_fct)} (struct __gconv_step *, struct __gconv_step_data *, const char **, const char *, size_t *, int)
2649 The conversion function can be called for two basic reason: to convert
2650 text or to reset the state.  From the description of the @code{iconv}
2651 function it can be seen why the flushing mode is necessary.  What mode
2652 is selected is determined by the sixth argument, an integer.  This
2653 argument being nonzero means that flushing is selected.
2654
2655 Common to both modes is where the output buffer can be found.  The
2656 information about this buffer is stored in the conversion step data.  A
2657 pointer to this information is passed as the second argument to this
2658 function.  The description of the @code{struct __gconv_step_data}
2659 structure has more information on the conversion step data.
2660
2661 @cindex stateful
2662 What has to be done for flushing depends on the source character set.
2663 If the source character set is not stateful, nothing has to be done.
2664 Otherwise the function has to emit a byte sequence to bring the state
2665 object into the initial state.  Once this all happened the other
2666 conversion modules in the chain of conversions have to get the same
2667 chance.  Whether another step follows can be determined from the
2668 @code{__is_last} element of the step data structure to which the first
2669 parameter points.
2670
2671 The more interesting mode is when actual text has to be converted.  The
2672 first step in this case is to convert as much text as possible from the
2673 input buffer and store the result in the output buffer.  The start of the
2674 input buffer is determined by the third argument, which is a pointer to a
2675 pointer variable referencing the beginning of the buffer.  The fourth
2676 argument is a pointer to the byte right after the last byte in the buffer.
2677
2678 The conversion has to be performed according to the current state if the
2679 character set is stateful.  The state is stored in an object pointed to
2680 by the @code{__statep} element of the step data (second argument).  Once
2681 either the input buffer is empty or the output buffer is full the
2682 conversion stops.  At this point, the pointer variable referenced by the
2683 third parameter must point to the byte following the last processed
2684 byte (i.e., if all of the input is consumed, this pointer and the fourth
2685 parameter have the same value).
2686
2687 What now happens depends on whether this step is the last one.  If it is
2688 the last step, the only thing that has to be done is to update the
2689 @code{__outbuf} element of the step data structure to point after the
2690 last written byte.  This update gives the caller the information on how
2691 much text is available in the output buffer.  In addition, the variable
2692 pointed to by the fifth parameter, which is of type @code{size_t}, must
2693 be incremented by the number of characters (@emph{not bytes}) that were
2694 converted in a non-reversible way.  Then, the function can return.
2695
2696 In case the step is not the last one, the later conversion functions have
2697 to get a chance to do their work.  Therefore, the appropriate conversion
2698 function has to be called.  The information about the functions is
2699 stored in the conversion data structures, passed as the first parameter.
2700 This information and the step data are stored in arrays, so the next
2701 element in both cases can be found by simple pointer arithmetic:
2702
2703 @smallexample
2704 int
2705 gconv (struct __gconv_step *step, struct __gconv_step_data *data,
2706        const char **inbuf, const char *inbufend, size_t *written,
2707        int do_flush)
2708 @{
2709   struct __gconv_step *next_step = step + 1;
2710   struct __gconv_step_data *next_data = data + 1;
2711   @dots{}
2712 @end smallexample
2713
2714 The @code{next_step} pointer references the next step information and
2715 @code{next_data} the next data record.  The call of the next function
2716 therefore will look similar to this:
2717
2718 @smallexample
2719   next_step->__fct (next_step, next_data, &outerr, outbuf,
2720                     written, 0)
2721 @end smallexample
2722
2723 But this is not yet all.  Once the function call returns the conversion
2724 function might have some more to do.  If the return value of the function
2725 is @code{__GCONV_EMPTY_INPUT}, more room is available in the output
2726 buffer.  Unless the input buffer is empty the conversion, functions start
2727 all over again and process the rest of the input buffer.  If the return
2728 value is not @code{__GCONV_EMPTY_INPUT}, something went wrong and we have
2729 to recover from this.
2730
2731 A requirement for the conversion function is that the input buffer
2732 pointer (the third argument) always point to the last character that
2733 was put in converted form into the output buffer.  This is trivially
2734 true after the conversion performed in the current step, but if the
2735 conversion functions deeper downstream stop prematurely, not all
2736 characters from the output buffer are consumed and, therefore, the input
2737 buffer pointers must be backed off to the right position.
2738
2739 Correcting the input buffers is easy to do if the input and output
2740 character sets have a fixed width for all characters.  In this situation
2741 we can compute how many characters are left in the output buffer and,
2742 therefore, can correct the input buffer pointer appropriately with a
2743 similar computation.  Things are getting tricky if either character set
2744 has characters represented with variable length byte sequences, and it
2745 gets even more complicated if the conversion has to take care of the
2746 state.  In these cases the conversion has to be performed once again, from
2747 the known state before the initial conversion (i.e., if necessary the
2748 state of the conversion has to be reset and the conversion loop has to be
2749 executed again).  The difference now is that it is known how much input
2750 must be created, and the conversion can stop before converting the first
2751 unused character.  Once this is done the input buffer pointers must be
2752 updated again and the function can return.
2753
2754 One final thing should be mentioned.  If it is necessary for the
2755 conversion to know whether it is the first invocation (in case a prolog
2756 has to be emitted), the conversion function should increment the
2757 @code{__invocation_counter} element of the step data structure just
2758 before returning to the caller.  See the description of the @code{struct
2759 __gconv_step_data} structure above for more information on how this can
2760 be used.
2761
2762 The return value must be one of the following values:
2763
2764 @table @code
2765 @item __GCONV_EMPTY_INPUT
2766 All input was consumed and there is room left in the output buffer.
2767 @item __GCONV_FULL_OUTPUT
2768 No more room in the output buffer.  In case this is not the last step
2769 this value is propagated down from the call of the next conversion
2770 function in the chain.
2771 @item __GCONV_INCOMPLETE_INPUT
2772 The input buffer is not entirely empty since it contains an incomplete
2773 character sequence.
2774 @end table
2775
2776 The following example provides a framework for a conversion function.
2777 In case a new conversion has to be written the holes in this
2778 implementation have to be filled and that is it.
2779
2780 @smallexample
2781 int
2782 gconv (struct __gconv_step *step, struct __gconv_step_data *data,
2783        const char **inbuf, const char *inbufend, size_t *written,
2784        int do_flush)
2785 @{
2786   struct __gconv_step *next_step = step + 1;
2787   struct __gconv_step_data *next_data = data + 1;
2788   gconv_fct fct = next_step->__fct;
2789   int status;
2790
2791   /* @r{If the function is called with no input this means we have}
2792      @r{to reset to the initial state.  The possibly partly}
2793      @r{converted input is dropped.}  */
2794   if (do_flush)
2795     @{
2796       status = __GCONV_OK;
2797
2798       /* @r{Possible emit a byte sequence which put the state object}
2799          @r{into the initial state.}  */
2800
2801       /* @r{Call the steps down the chain if there are any but only}
2802          @r{if we successfully emitted the escape sequence.}  */
2803       if (status == __GCONV_OK && ! data->__is_last)
2804         status = fct (next_step, next_data, NULL, NULL,
2805                       written, 1);
2806     @}
2807   else
2808     @{
2809       /* @r{We preserve the initial values of the pointer variables.}  */
2810       const char *inptr = *inbuf;
2811       char *outbuf = data->__outbuf;
2812       char *outend = data->__outbufend;
2813       char *outptr;
2814
2815       do
2816         @{
2817           /* @r{Remember the start value for this round.}  */
2818           inptr = *inbuf;
2819           /* @r{The outbuf buffer is empty.}  */
2820           outptr = outbuf;
2821
2822           /* @r{For stateful encodings the state must be safe here.}  */
2823
2824           /* @r{Run the conversion loop.  @code{status} is set}
2825              @r{appropriately afterwards.}  */
2826
2827           /* @r{If this is the last step, leave the loop. There is}
2828              @r{nothing we can do.}  */
2829           if (data->__is_last)
2830             @{
2831               /* @r{Store information about how many bytes are}
2832                  @r{available.}  */
2833               data->__outbuf = outbuf;
2834
2835              /* @r{If any non-reversible conversions were performed,}
2836                 @r{add the number to @code{*written}.}  */
2837
2838              break;
2839            @}
2840
2841           /* @r{Write out all output that was produced.}  */
2842           if (outbuf > outptr)
2843             @{
2844               const char *outerr = data->__outbuf;
2845               int result;
2846
2847               result = fct (next_step, next_data, &outerr,
2848                             outbuf, written, 0);
2849
2850               if (result != __GCONV_EMPTY_INPUT)
2851                 @{
2852                   if (outerr != outbuf)
2853                     @{
2854                       /* @r{Reset the input buffer pointer.  We}
2855                          @r{document here the complex case.}  */
2856                       size_t nstatus;
2857
2858                       /* @r{Reload the pointers.}  */
2859                       *inbuf = inptr;
2860                       outbuf = outptr;
2861
2862                       /* @r{Possibly reset the state.}  */
2863
2864                       /* @r{Redo the conversion, but this time}
2865                          @r{the end of the output buffer is at}
2866                          @r{@code{outerr}.}  */
2867                     @}
2868
2869                   /* @r{Change the status.}  */
2870                   status = result;
2871                 @}
2872               else
2873                 /* @r{All the output is consumed, we can make}
2874                    @r{ another run if everything was ok.}  */
2875                 if (status == __GCONV_FULL_OUTPUT)
2876                   status = __GCONV_OK;
2877            @}
2878         @}
2879       while (status == __GCONV_OK);
2880
2881       /* @r{We finished one use of this step.}  */
2882       ++data->__invocation_counter;
2883     @}
2884
2885   return status;
2886 @}
2887 @end smallexample
2888 @end deftypevr
2889
2890 This information should be sufficient to write new modules.  Anybody
2891 doing so should also take a look at the available source code in the GNU
2892 C library sources.  It contains many examples of working and optimized
2893 modules.
2894
2895 @c File charset.texi edited October 2001 by Dennis Grace, IBM Corporation