   This file documents the GNU C library.

   This is Edition 0.07 DRAFT, last updated 4 Oct 1996, of `The GNU C
Library Reference Manual', for Version 2.00 Beta.

   Copyright (C) 1993, '94, '95, '96, '97 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU Library General Public License" is
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the text of the translation of the section
entitled "GNU Library General Public License" must be approved for
accuracy by the Foundation.

Multibyte Characters
====================

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

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

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

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

   The byte value `0' can be used to terminate a string, just as it is
often used in a string of ASCII characters.

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

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

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

   The simplest possible multibyte code is a trivial one:

     The basic sequences consist of single bytes.

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

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

     The basic sequences consist of

        * single bytes with values in the range `0' through `0237'.

        * two-byte sequences, in which both of the bytes have values in
          the range from `0240' through `0377'.

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

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

     The basic sequences consist of

        * single bytes with values in the range `0' through `0177'.

        * sequences of up to four bytes in which the first byte is in
          the range from `0200' through `0237', and the remaining bytes
          are in the range from `0240' through `0377'.

In this code, any sequence that starts with a byte in the range from
`0240' through `0377' is invalid.

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

     The basic sequences consist of

        * single bytes with values in the range `0' through `0177'.

        * two-byte sequences in which the first byte is in the range
          from `0200' through `0207', and the second byte is in the
          range from `0240' through `0377'.

        * three-byte sequences in which the first byte is in the range
          from `0210' through `0217', and the other bytes are in the
          range from `0240' through `0377'.

        * four-byte sequences in which the first byte is in the range
          from `0220' through `0227', and the other bytes are in the
          range from `0240' through `0377'.

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

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

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

 - Macro: int MB_LEN_MAX
     This is the maximum length of a multibyte character for any
     supported locale.  It is defined in `limits.h'.

 - Macro: int MB_CUR_MAX
     This macro expands into a (possibly non-constant) positive integer
     expression that is the maximum number of bytes in a multibyte
     character in the current locale.  The value is never greater than
     `MB_LEN_MAX'.

     `MB_CUR_MAX' is defined in `stdlib.h'.

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

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

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

Wide Character Introduction
===========================

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

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

   * A program must be modified and recompiled in order to use wide
     characters at all.

   * Files of wide characters cannot be read by programs that expect
     ordinary characters.

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

 - Data Type: wchar_t
     This is the "wide character" type, an integer type whose range is
     large enough to represent all distinct values in any extended
     character set in the supported locales.  See Locales, for more
     information about locales.  This type is defined in the header
     file `stddef.h'.

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

   In this chapter, the term "code" is used to refer to a single
extended character object to emphasize the distinction from the `char'
data type.

Conversion of Extended Strings
==============================

   The `mbstowcs' function converts a string of multibyte characters to
a wide character array.  The `wcstombs' function does the reverse.
These functions are declared in the header file `stdlib.h'.

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

 - Function: size_t mbstowcs (wchar_t *WSTRING, const char *STRING,
          size_t SIZE)
     The `mbstowcs' ("multibyte string to wide character string")
     function converts the null-terminated string of multibyte
     characters STRING to an array of wide character codes, storing not
     more than SIZE wide characters into the array beginning at WSTRING.
     The terminating null character counts towards the size, so if SIZE
     is less than the actual number of wide characters resulting from
     STRING, no terminating null character is stored.

     The conversion of characters from STRING begins in the initial
     shift state.

     If an invalid multibyte character sequence is found, this function
     returns a value of `-1'.  Otherwise, it returns the number of wide
     characters stored in the array WSTRING.  This number does not
     include the terminating null character, which is present if the
     number is less than SIZE.

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

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

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

 - Function: size_t wcstombs (char *STRING, const wchar_t WSTRING,
          size_t SIZE)
     The `wcstombs' ("wide character string to multibyte string")
     function converts the null-terminated wide character array WSTRING
     into a string containing multibyte characters, storing not more
     than SIZE bytes starting at STRING, followed by a terminating null
     character if there is room.  The conversion of characters begins in
     the initial shift state.

     The terminating null character counts towards the size, so if SIZE
     is less than or equal to the number of bytes needed in WSTRING, no
     terminating null character is stored.

     If a code that does not correspond to a valid multibyte character
     is found, this function returns a value of `-1'.  Otherwise, the
     return value is the number of bytes stored in the array STRING.
     This number does not include the terminating null character, which
     is present if the number is less than SIZE.

Multibyte Character Length
==========================

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

 - Function: int mblen (const char *STRING, size_t SIZE)
     The `mblen' function with a non-null STRING argument returns the
     number of bytes that make up the multibyte character beginning at
     STRING, never examining more than SIZE bytes.  (The idea is to
     supply for SIZE the number of bytes of data you have in hand.)

     The return value of `mblen' distinguishes three possibilities: the
     first SIZE bytes at STRING start with valid multibyte character,
     they start with an invalid byte sequence or just part of a
     character, or STRING points to an empty string (a null character).

     For a valid multibyte character, `mblen' returns the number of
     bytes in that character (always at least `1', and never more than
     SIZE).  For an invalid byte sequence, `mblen' returns `-1'.  For
     an empty string, it returns `0'.

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

     The function `mblen' is declared in `stdlib.h'.

Conversion of Extended Characters One by One
============================================

   You can convert multibyte characters one at a time to wide characters
with the `mbtowc' function.  The `wctomb' function does the reverse.
These functions are declared in `stdlib.h'.

 - Function: int mbtowc (wchar_t *RESULT, const char *STRING, size_t
          SIZE)
     The `mbtowc' ("multibyte to wide character") function when called
     with non-null STRING converts the first multibyte character
     beginning at STRING to its corresponding wide character code.  It
     stores the result in `*RESULT'.

     `mbtowc' never examines more than SIZE bytes.  (The idea is to
     supply for SIZE the number of bytes of data you have in hand.)

     `mbtowc' with non-null STRING distinguishes three possibilities:
     the first SIZE bytes at STRING start with valid multibyte
     character, they start with an invalid byte sequence or just part
     of a character, or STRING points to an empty string (a null
     character).

     For a valid multibyte character, `mbtowc' converts it to a wide
     character and stores that in `*RESULT', and returns the number of
     bytes in that character (always at least `1', and never more than
     SIZE).

     For an invalid byte sequence, `mbtowc' returns `-1'.  For an empty
     string, it returns `0', also storing `0' in `*RESULT'.

     If the multibyte character code uses shift characters, then
     `mbtowc' maintains and updates a shift state as it scans.  If you
     call `mbtowc' with a null pointer for STRING, that initializes the
     shift state to its standard initial value.  It also returns
     nonzero if the multibyte character code in use actually has a
     shift state.  See Shift State.

 - Function: int wctomb (char *STRING, wchar_t WCHAR)
     The `wctomb' ("wide character to multibyte") function converts the
     wide character code WCHAR to its corresponding multibyte character
     sequence, and stores the result in bytes starting at STRING.  At
     most `MB_CUR_MAX' characters are stored.

     `wctomb' with non-null STRING distinguishes three possibilities
     for WCHAR: a valid wide character code (one that can be translated
     to a multibyte character), an invalid code, and `0'.

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

     If WCHAR is an invalid wide character code, `wctomb' returns `-1'.
     If WCHAR is `0', it returns `0', also storing `0' in `*STRING'.

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

     Calling this function with a WCHAR argument of zero when STRING is
     not null has the side-effect of reinitializing the stored shift
     state *as well as* storing the multibyte character `0' and
     returning `0'.

Character-by-Character Conversion Example
=========================================

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

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

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

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

           /* `filled' is now the number of bytes in `buffer'. */
           filled += nread;

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

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

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

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

       return 1;
     }

Multibyte Codes Using Shift Sequences
=====================================

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

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

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

   * Before starting to scan a string, call the function with a null
     pointer for the multibyte character address--for example, `mblen
     (NULL, 0)'.  This initializes the shift state to its standard
     initial value.

   * Scan the string one character at a time, in order.  Do not "back
     up" and rescan characters already scanned, and do not intersperse
     the processing of different strings.

   Here is an example of using `mblen' following these rules:

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

       /* Initialize shift state. */
       mblen (NULL, 0);

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

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

Locales and Internationalization
********************************

   Different countries and cultures have varying conventions for how to
communicate.  These conventions range from very simple ones, such as the
format for representing dates and times, to very complex ones, such as
the language spoken.

   "Internationalization" of software means programming it to be able
to adapt to the user's favorite conventions.  In ISO C,
internationalization works by means of "locales".  Each locale
specifies a collection of conventions, one convention for each purpose.
The user chooses a set of conventions by specifying a locale (via
environment variables).

   All programs inherit the chosen locale as part of their environment.
Provided the programs are written to obey the choice of locale, they
will follow the conventions preferred by the user.

What Effects a Locale Has
=========================

   Each locale specifies conventions for several purposes, including the
following:

   * What multibyte character sequences are valid, and how they are
     interpreted (see Extended Characters.).

   * Classification of which characters in the local character set are
     considered alphabetic, and upper- and lower-case conversion
     conventions (see Character Handling.).

   * The collating sequence for the local language and character set
     (see Collation Functions.).

   * Formatting of numbers and currency amounts (see Numeric Formatting.).

   * Formatting of dates and times (see Formatting Date and Time.).

   * What language to use for output, including error messages.  (The C
     library doesn't yet help you implement this.)

   * What language to use for user answers to yes-or-no questions.

   * What language to use for more complex user input.  (The C library
     doesn't yet help you implement this.)

   Some aspects of adapting to the specified locale are handled
automatically by the library subroutines.  For example, all your program
needs to do in order to use the collating sequence of the chosen locale
is to use `strcoll' or `strxfrm' to compare strings.

   Other aspects of locales are beyond the comprehension of the library.
For example, the library can't automatically translate your program's
output messages into other languages.  The only way you can support
output in the user's favorite language is to program this more or less
by hand.  (Eventually, we hope to provide facilities to make this
easier.)

   This chapter discusses the mechanism by which you can modify the
current locale.  The effects of the current locale on specific library
functions are discussed in more detail in the descriptions of those
functions.

Choosing a Locale
=================

   The simplest way for the user to choose a locale is to set the
environment variable `LANG'.  This specifies a single locale to use for
all purposes.  For example, a user could specify a hypothetical locale
named `espana-castellano' to use the standard conventions of most of
Spain.

   The set of locales supported depends on the operating system you are
using, and so do their names.  We can't make any promises about what
locales will exist, except for one standard locale called `C' or
`POSIX'.

   A user also has the option of specifying different locales for
different purposes--in effect, choosing a mixture of multiple locales.

   For example, the user might specify the locale `espana-castellano'
for most purposes, but specify the locale `usa-english' for currency
formatting.  This might make sense if the user is a Spanish-speaking
American, working in Spanish, but representing monetary amounts in US
dollars.

   Note that both locales `espana-castellano' and `usa-english', like
all locales, would include conventions for all of the purposes to which
locales apply.  However, the user can choose to use each locale for a
particular subset of those purposes.

Categories of Activities that Locales Affect
============================================

   The purposes that locales serve are grouped into "categories", so
that a user or a program can choose the locale for each category
independently.  Here is a table of categories; each name is both an
environment variable that a user can set, and a macro name that you can
use as an argument to `setlocale'.

`LC_COLLATE'
     This category applies to collation of strings (functions `strcoll'
     and `strxfrm'); see Collation Functions.

`LC_CTYPE'
     This category applies to classification and conversion of
     characters, and to multibyte and wide characters; see
     Character Handling and Extended Characters.

`LC_MONETARY'
     This category applies to formatting monetary values; see
     Numeric Formatting.

`LC_NUMERIC'
     This category applies to formatting numeric values that are not
     monetary; see Numeric Formatting.

`LC_TIME'
     This category applies to formatting date and time values; see
     Formatting Date and Time.

`LC_MESSAGES'
     This category applies to selecting the language used in the user
     interface for message translation.

`LC_ALL'
     This is not an environment variable; it is only a macro that you
     can use with `setlocale' to set a single locale for all purposes.

`LANG'
     If this environment variable is defined, its value specifies the
     locale to use for all purposes except as overridden by the
     variables above.

How Programs Set the Locale
===========================

   A C program inherits its locale environment variables when it starts
up.  This happens automatically.  However, these variables do not
automatically control the locale used by the library functions, because
ISO C says that all programs start by default in the standard `C'
locale.  To use the locales specified by the environment, you must call
`setlocale'.  Call it as follows:

     setlocale (LC_ALL, "");

to select a locale based on the appropriate environment variables.

   You can also use `setlocale' to specify a particular locale, for
general use or for a specific category.

   The symbols in this section are defined in the header file
`locale.h'.

 - Function: char * setlocale (int CATEGORY, const char *LOCALE)
     The function `setlocale' sets the current locale for category
     CATEGORY to LOCALE.

     If CATEGORY is `LC_ALL', this specifies the locale for all
     purposes.  The other possible values of CATEGORY specify an
     individual purpose (see Locale Categories.).

     You can also use this function to find out the current locale by
     passing a null pointer as the LOCALE argument.  In this case,
     `setlocale' returns a string that is the name of the locale
     currently selected for category CATEGORY.

     The string returned by `setlocale' can be overwritten by subsequent
     calls, so you should make a copy of the string (see Copying and Concatenation.)
     if you want to save it past any further calls to
     `setlocale'.  (The standard library is guaranteed never to call
     `setlocale' itself.)

     You should not modify the string returned by `setlocale'.  It
     might be the same string that was passed as an argument in a
     previous call to `setlocale'.

     When you read the current locale for category `LC_ALL', the value
     encodes the entire combination of selected locales for all
     categories.  In this case, the value is not just a single locale
     name.  In fact, we don't make any promises about what it looks
     like.  But if you specify the same "locale name" with `LC_ALL' in
     a subsequent call to `setlocale', it restores the same combination
     of locale selections.

     When the LOCALE argument is not a null pointer, the string returned
     by `setlocale' reflects the newly modified locale.

     If you specify an empty string for LOCALE, this means to read the
     appropriate environment variable and use its value to select the
     locale for CATEGORY.

     If you specify an invalid locale name, `setlocale' returns a null
     pointer and leaves the current locale unchanged.

   Here is an example showing how you might use `setlocale' to
temporarily switch to a new locale.

     #include <stddef.h>
     #include <locale.h>
     #include <stdlib.h>
     #include <string.h>

     void
     with_other_locale (char *new_locale,
                        void (*subroutine) (int),
                        int argument)
     {
       char *old_locale, *saved_locale;

       /* Get the name of the current locale.  */
       old_locale = setlocale (LC_ALL, NULL);

       /* Copy the name so it won't be clobbered by `setlocale'. */
       saved_locale = strdup (old_locale);
       if (old_locale == NULL)
         fatal ("Out of memory");

       /* Now change the locale and do some stuff with it. */
       setlocale (LC_ALL, new_locale);
       (*subroutine) (argument);

       /* Restore the original locale. */
       setlocale (LC_ALL, saved_locale);
       free (saved_locale);
     }

   *Portability Note:* Some ISO C systems may define additional locale
categories.  For portability, assume that any symbol beginning with
`LC_' might be defined in `locale.h'.

Standard Locales
================

   The only locale names you can count on finding on all operating
systems are these three standard ones:

`"C"'
     This is the standard C locale.  The attributes and behavior it
     provides are specified in the ISO C standard.  When your program
     starts up, it initially uses this locale by default.

`"POSIX"'
     This is the standard POSIX locale.  Currently, it is an alias for
     the standard C locale.

`""'
     The empty name says to select a locale based on environment
     variables.  See Locale Categories.

   Defining and installing named locales is normally a responsibility of
the system administrator at your site (or the person who installed the
GNU C library).  Some systems may allow users to create locales, but we
don't discuss that here.

   If your program needs to use something other than the `C' locale, it
will be more portable if you use whatever locale the user specifies
with the environment, rather than trying to specify some non-standard
locale explicitly by name.  Remember, different machines might have
different sets of locales installed.

Numeric Formatting
==================

   When you want to format a number or a currency amount using the
conventions of the current locale, you can use the function
`localeconv' to get the data on how to do it.  The function
`localeconv' is declared in the header file `locale.h'.

 - Function: struct lconv * localeconv (void)
     The `localeconv' function returns a pointer to a structure whose
     components contain information about how numeric and monetary
     values should be formatted in the current locale.

     You shouldn't modify the structure or its contents.  The structure
     might be overwritten by subsequent calls to `localeconv', or by
     calls to `setlocale', but no other function in the library
     overwrites this value.

 - Data Type: struct lconv
     This is the data type of the value returned by `localeconv'.

   If a member of the structure `struct lconv' has type `char', and the
value is `CHAR_MAX', it means that the current locale has no value for
that parameter.

Generic Numeric Formatting Parameters
-------------------------------------

   These are the standard members of `struct lconv'; there may be
others.

`char *decimal_point'
`char *mon_decimal_point'
     These are the decimal-point separators used in formatting
     non-monetary and monetary quantities, respectively.  In the `C'
     locale, the value of `decimal_point' is `"."', and the value of
     `mon_decimal_point' is `""'.

`char *thousands_sep'
`char *mon_thousands_sep'
     These are the separators used to delimit groups of digits to the
     left of the decimal point in formatting non-monetary and monetary
     quantities, respectively.  In the `C' locale, both members have a
     value of `""' (the empty string).

`char *grouping'
`char *mon_grouping'
     These are strings that specify how to group the digits to the left
     of the decimal point.  `grouping' applies to non-monetary
     quantities and `mon_grouping' applies to monetary quantities.  Use
     either `thousands_sep' or `mon_thousands_sep' to separate the digit
     groups.

     Each string is made up of decimal numbers separated by semicolons.
     Successive numbers (from left to right) give the sizes of
     successive groups (from right to left, starting at the decimal
     point).  The last number in the string is used over and over for
     all the remaining groups.

     If the last integer is `-1', it means that there is no more
     grouping--or, put another way, any remaining digits form one large
     group without separators.

     For example, if `grouping' is `"4;3;2"', the correct grouping for
     the number `123456787654321' is `12', `34', `56', `78', `765',
     `4321'.  This uses a group of 4 digits at the end, preceded by a
     group of 3 digits, preceded by groups of 2 digits (as many as
     needed).  With a separator of `,', the number would be printed as
     `12,34,56,78,765,4321'.

     A value of `"3"' indicates repeated groups of three digits, as
     normally used in the U.S.

     In the standard `C' locale, both `grouping' and `mon_grouping'
     have a value of `""'.  This value specifies no grouping at all.

`char int_frac_digits'
`char frac_digits'
     These are small integers indicating how many fractional digits (to
     the right of the decimal point) should be displayed in a monetary
     value in international and local formats, respectively.  (Most
     often, both members have the same value.)

     In the standard `C' locale, both of these members have the value
     `CHAR_MAX', meaning "unspecified".  The ISO standard doesn't say
     what to do when you find this the value; we recommend printing no
     fractional digits.  (This locale also specifies the empty string
     for `mon_decimal_point', so printing any fractional digits would be
     confusing!)

Printing the Currency Symbol
----------------------------

   These members of the `struct lconv' structure specify how to print
the symbol to identify a monetary value--the international analog of
`$' for US dollars.

   Each country has two standard currency symbols.  The "local currency
symbol" is used commonly within the country, while the "international
currency symbol" is used internationally to refer to that country's
currency when it is necessary to indicate the country unambiguously.

   For example, many countries use the dollar as their monetary unit,
and when dealing with international currencies it's important to specify
that one is dealing with (say) Canadian dollars instead of U.S. dollars
or Australian dollars.  But when the context is known to be Canada,
there is no need to make this explicit--dollar amounts are implicitly
assumed to be in Canadian dollars.

`char *currency_symbol'
     The local currency symbol for the selected locale.

     In the standard `C' locale, this member has a value of `""' (the
     empty string), meaning "unspecified".  The ISO standard doesn't
     say what to do when you find this value; we recommend you simply
     print the empty string as you would print any other string found
     in the appropriate member.

`char *int_curr_symbol'
     The international currency symbol for the selected locale.

     The value of `int_curr_symbol' should normally consist of a
     three-letter abbreviation determined by the international standard
     `ISO 4217 Codes for the Representation of Currency and Funds',
     followed by a one-character separator (often a space).

     In the standard `C' locale, this member has a value of `""' (the
     empty string), meaning "unspecified".  We recommend you simply
     print the empty string as you would print any other string found
     in the appropriate member.

`char p_cs_precedes'
`char n_cs_precedes'
     These members are `1' if the `currency_symbol' string should
     precede the value of a monetary amount, or `0' if the string should
     follow the value.  The `p_cs_precedes' member applies to positive
     amounts (or zero), and the `n_cs_precedes' member applies to
     negative amounts.

     In the standard `C' locale, both of these members have a value of
     `CHAR_MAX', meaning "unspecified".  The ISO standard doesn't say
     what to do when you find this value, but we recommend printing the
     currency symbol before the amount.  That's right for most
     countries.  In other words, treat all nonzero values alike in
     these members.

     The POSIX standard says that these two members apply to the
     `int_curr_symbol' as well as the `currency_symbol'.  The ISO C
     standard seems to imply that they should apply only to the
     `currency_symbol'--so the `int_curr_symbol' should always precede
     the amount.

     We can only guess which of these (if either) matches the usual
     conventions for printing international currency symbols.  Our
     guess is that they should always precede the amount.  If we find
     out a reliable answer, we will put it here.

`char p_sep_by_space'
`char n_sep_by_space'
     These members are `1' if a space should appear between the
     `currency_symbol' string and the amount, or `0' if no space should
     appear.  The `p_sep_by_space' member applies to positive amounts
     (or zero), and the `n_sep_by_space' member applies to negative
     amounts.

     In the standard `C' locale, both of these members have a value of
     `CHAR_MAX', meaning "unspecified".  The ISO standard doesn't say
     what you should do when you find this value; we suggest you treat
     it as one (print a space).  In other words, treat all nonzero
     values alike in these members.

     These members apply only to `currency_symbol'.  When you use
     `int_curr_symbol', you never print an additional space, because
     `int_curr_symbol' itself contains the appropriate separator.

     The POSIX standard says that these two members apply to the
     `int_curr_symbol' as well as the `currency_symbol'.  But an
     example in the ISO C standard clearly implies that they should
     apply only to the `currency_symbol'--that the `int_curr_symbol'
     contains any appropriate separator, so you should never print an
     additional space.

     Based on what we know now, we recommend you ignore these members
     when printing international currency symbols, and print no extra
     space.

Printing the Sign of an Amount of Money
---------------------------------------

   These members of the `struct lconv' structure specify how to print
the sign (if any) in a monetary value.

`char *positive_sign'
`char *negative_sign'
     These are strings used to indicate positive (or zero) and negative
     (respectively) monetary quantities.

     In the standard `C' locale, both of these members have a value of
     `""' (the empty string), meaning "unspecified".

     The ISO standard doesn't say what to do when you find this value;
     we recommend printing `positive_sign' as you find it, even if it is
     empty.  For a negative value, print `negative_sign' as you find it
     unless both it and `positive_sign' are empty, in which case print
     `-' instead.  (Failing to indicate the sign at all seems rather
     unreasonable.)

`char p_sign_posn'
`char n_sign_posn'
     These members have values that are small integers indicating how to
     position the sign for nonnegative and negative monetary quantities,
     respectively.  (The string used by the sign is what was specified
     with `positive_sign' or `negative_sign'.)  The possible values are
     as follows:

    `0'
          The currency symbol and quantity should be surrounded by
          parentheses.

    `1'
          Print the sign string before the quantity and currency symbol.

    `2'
          Print the sign string after the quantity and currency symbol.

    `3'
          Print the sign string right before the currency symbol.

    `4'
          Print the sign string right after the currency symbol.

    `CHAR_MAX'
          "Unspecified".  Both members have this value in the standard
          `C' locale.

     The ISO standard doesn't say what you should do when the value is
     `CHAR_MAX'.  We recommend you print the sign after the currency
     symbol.

   It is not clear whether you should let these members apply to the
international currency format or not.  POSIX says you should, but
intuition plus the examples in the ISO C standard suggest you should
not.  We hope that someone who knows well the conventions for formatting
monetary quantities will tell us what we should recommend.

Non-Local Exits
***************

   Sometimes when your program detects an unusual situation inside a
deeply nested set of function calls, you would like to be able to
immediately return to an outer level of control.  This section
describes how you can do such "non-local exits" using the `setjmp' and
`longjmp' functions.