   This file documents the GNU C library.

   This is Edition 0.10, last updated 2001-07-06, of `The GNU C Library
Reference Manual', for Version 2.2.x.

   Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002
Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Free Software Needs Free Documentation" and
"GNU Lesser General Public License", the Front-Cover texts being (a)
(see below), and with the Back-Cover Texts being (b) (see below).  A
copy of the license is included in the section entitled "GNU Free
Documentation License".

   (a) The FSF's Front-Cover Text is:

   A GNU Manual

   (b) The FSF's Back-Cover Text is:

   You have freedom to copy and modify this GNU Manual, like GNU
software.  Copies published by the Free Software Foundation raise
funds for GNU development.

Search Functions
================

   This section describes library functions which perform various kinds
of searching operations on strings and arrays.  These functions are
declared in the header file `string.h'.

 - Function: void * memchr (const void *BLOCK, int C, size_t SIZE)
     This function finds the first occurrence of the byte C (converted
     to an `unsigned char') in the initial SIZE bytes of the object
     beginning at BLOCK.  The return value is a pointer to the located
     byte, or a null pointer if no match was found.

 - Function: wchar_t * wmemchr (const wchar_t *BLOCK, wchar_t WC,
          size_t SIZE)
     This function finds the first occurrence of the wide character WC
     in the initial SIZE wide characters of the object beginning at
     BLOCK.  The return value is a pointer to the located wide
     character, or a null pointer if no match was found.

 - Function: void * rawmemchr (const void *BLOCK, int C)
     Often the `memchr' function is used with the knowledge that the
     byte C is available in the memory block specified by the
     parameters.  But this means that the SIZE parameter is not really
     needed and that the tests performed with it at runtime (to check
     whether the end of the block is reached) are not needed.

     The `rawmemchr' function exists for just this situation which is
     surprisingly frequent.  The interface is similar to `memchr' except
     that the SIZE parameter is missing.  The function will look beyond
     the end of the block pointed to by BLOCK in case the programmer
     made an error in assuming that the byte C is present in the block.
     In this case the result is unspecified.  Otherwise the return
     value is a pointer to the located byte.

     This function is of special interest when looking for the end of a
     string.  Since all strings are terminated by a null byte a call
     like

             rawmemchr (str, '\0')

     will never go beyond the end of the string.

     This function is a GNU extension.

 - Function: void * memrchr (const void *BLOCK, int C, size_t SIZE)
     The function `memrchr' is like `memchr', except that it searches
     backwards from the end of the block defined by BLOCK and SIZE
     (instead of forwards from the front).

 - Function: char * strchr (const char *STRING, int C)
     The `strchr' function finds the first occurrence of the character
     C (converted to a `char') in the null-terminated string beginning
     at STRING.  The return value is a pointer to the located
     character, or a null pointer if no match was found.

     For example,
          strchr ("hello, world", 'l')
              => "llo, world"
          strchr ("hello, world", '?')
              => NULL

     The terminating null character is considered to be part of the
     string, so you can use this function get a pointer to the end of a
     string by specifying a null character as the value of the C
     argument.  It would be better (but less portable) to use
     `strchrnul' in this case, though.

 - Function: wchar_t * wcschr (const wchar_t *WSTRING, int WC)
     The `wcschr' function finds the first occurrence of the wide
     character WC in the null-terminated wide character string
     beginning at WSTRING.  The return value is a pointer to the
     located wide character, or a null pointer if no match was found.

     The terminating null character is considered to be part of the wide
     character string, so you can use this function get a pointer to
     the end of a wide character string by specifying a null wude
     character as the value of the WC argument.  It would be better
     (but less portable) to use `wcschrnul' in this case, though.

 - Function: char * strchrnul (const char *STRING, int C)
     `strchrnul' is the same as `strchr' except that if it does not
     find the character, it returns a pointer to string's terminating
     null character rather than a null pointer.

     This function is a GNU extension.

 - Function: wchar_t * wcschrnul (const wchar_t *WSTRING, wchar_t WC)
     `wcschrnul' is the same as `wcschr' except that if it does not
     find the wide character, it returns a pointer to wide character
     string's terminating null wide character rather than a null
     pointer.

     This function is a GNU extension.

   One useful, but unusual, use of the `strchr' function is when one
wants to have a pointer pointing to the NUL byte terminating a string.
This is often written in this way:

       s += strlen (s);

This is almost optimal but the addition operation duplicated a bit of
the work already done in the `strlen' function.  A better solution is
this:

       s = strchr (s, '\0');

   There is no restriction on the second parameter of `strchr' so it
could very well also be the NUL character.  Those readers thinking very
hard about this might now point out that the `strchr' function is more
expensive than the `strlen' function since we have two abort criteria.
This is right.  But in the GNU C library the implementation of `strchr'
is optimized in a special way so that `strchr' actually is faster.

 - Function: char * strrchr (const char *STRING, int C)
     The function `strrchr' is like `strchr', except that it searches
     backwards from the end of the string STRING (instead of forwards
     from the front).

     For example,
          strrchr ("hello, world", 'l')
              => "ld"

 - Function: wchar_t * wcsrchr (const wchar_t *WSTRING, wchar_t C)
     The function `wcsrchr' is like `wcschr', except that it searches
     backwards from the end of the string WSTRING (instead of forwards
     from the front).

 - Function: char * strstr (const char *HAYSTACK, const char *NEEDLE)
     This is like `strchr', except that it searches HAYSTACK for a
     substring NEEDLE rather than just a single character.  It returns
     a pointer into the string HAYSTACK that is the first character of
     the substring, or a null pointer if no match was found.  If NEEDLE
     is an empty string, the function returns HAYSTACK.

     For example,
          strstr ("hello, world", "l")
              => "llo, world"
          strstr ("hello, world", "wo")
              => "world"

 - Function: wchar_t * wcsstr (const wchar_t *HAYSTACK, const wchar_t
          *NEEDLE)
     This is like `wcschr', except that it searches HAYSTACK for a
     substring NEEDLE rather than just a single wide character.  It
     returns a pointer into the string HAYSTACK that is the first wide
     character of the substring, or a null pointer if no match was
     found.  If NEEDLE is an empty string, the function returns
     HAYSTACK.

 - Function: wchar_t * wcswcs (const wchar_t *HAYSTACK, const wchar_t
          *NEEDLE)
     `wcsstr' is an depricated alias for `wcsstr'.  This is the name
     originally used in the X/Open Portability Guide before the
     Amendment 1 to ISO C90 was published.

 - Function: char * strcasestr (const char *HAYSTACK, const char
          *NEEDLE)
     This is like `strstr', except that it ignores case in searching for
     the substring.   Like `strcasecmp', it is locale dependent how
     uppercase and lowercase characters are related.

     For example,
          strstr ("hello, world", "L")
              => "llo, world"
          strstr ("hello, World", "wo")
              => "World"

 - Function: void * memmem (const void *HAYSTACK, size_t HAYSTACK-LEN,
          const void *NEEDLE, size_t NEEDLE-LEN)
     This is like `strstr', but NEEDLE and HAYSTACK are byte arrays
     rather than null-terminated strings.  NEEDLE-LEN is the length of
     NEEDLE and HAYSTACK-LEN is the length of HAYSTACK.

     This function is a GNU extension.

 - Function: size_t strspn (const char *STRING, const char *SKIPSET)
     The `strspn' ("string span") function returns the length of the
     initial substring of STRING that consists entirely of characters
     that are members of the set specified by the string SKIPSET.  The
     order of the characters in SKIPSET is not important.

     For example,
          strspn ("hello, world", "abcdefghijklmnopqrstuvwxyz")
              => 5

     Note that "character" is here used in the sense of byte.  In a
     string using a multibyte character encoding (abstract) character
     consisting of more than one byte are not treated as an entity.
     Each byte is treated separately.  The function is not
     locale-dependent.

 - Function: size_t wcsspn (const wchar_t *WSTRING, const wchar_t
          *SKIPSET)
     The `wcsspn' ("wide character string span") function returns the
     length of the initial substring of WSTRING that consists entirely
     of wide characters that are members of the set specified by the
     string SKIPSET.  The order of the wide characters in SKIPSET is not
     important.

 - Function: size_t strcspn (const char *STRING, const char *STOPSET)
     The `strcspn' ("string complement span") function returns the
     length of the initial substring of STRING that consists entirely
     of characters that are _not_ members of the set specified by the
     string STOPSET.  (In other words, it returns the offset of the
     first character in STRING that is a member of the set STOPSET.)

     For example,
          strcspn ("hello, world", " \t\n,.;!?")
              => 5

     Note that "character" is here used in the sense of byte.  In a
     string using a multibyte character encoding (abstract) character
     consisting of more than one byte are not treated as an entity.
     Each byte is treated separately.  The function is not
     locale-dependent.

 - Function: size_t wcscspn (const wchar_t *WSTRING, const wchar_t
          *STOPSET)
     The `wcscspn' ("wide character string complement span") function
     returns the length of the initial substring of WSTRING that
     consists entirely of wide characters that are _not_ members of the
     set specified by the string STOPSET.  (In other words, it returns
     the offset of the first character in STRING that is a member of
     the set STOPSET.)

 - Function: char * strpbrk (const char *STRING, const char *STOPSET)
     The `strpbrk' ("string pointer break") function is related to
     `strcspn', except that it returns a pointer to the first character
     in STRING that is a member of the set STOPSET instead of the
     length of the initial substring.  It returns a null pointer if no
     such character from STOPSET is found.

     For example,

          strpbrk ("hello, world", " \t\n,.;!?")
              => ", world"

     Note that "character" is here used in the sense of byte.  In a
     string using a multibyte character encoding (abstract) character
     consisting of more than one byte are not treated as an entity.
     Each byte is treated separately.  The function is not
     locale-dependent.

 - Function: wchar_t * wcspbrk (const wchar_t *WSTRING, const wchar_t
          *STOPSET)
     The `wcspbrk' ("wide character string pointer break") function is
     related to `wcscspn', except that it returns a pointer to the first
     wide character in WSTRING that is a member of the set STOPSET
     instead of the length of the initial substring.  It returns a null
     pointer if no such character from STOPSET is found.

Compatibility String Search Functions
-------------------------------------

 - Function: char * index (const char *STRING, int C)
     `index' is another name for `strchr'; they are exactly the same.
     New code should always use `strchr' since this name is defined in
     ISO C while `index' is a BSD invention which never was available
     on System V derived systems.

 - Function: char * rindex (const char *STRING, int C)
     `rindex' is another name for `strrchr'; they are exactly the same.
     New code should always use `strrchr' since this name is defined in
     ISO C while `rindex' is a BSD invention which never was available
     on System V derived systems.

Finding Tokens in a String
==========================

   It's fairly common for programs to have a need to do some simple
kinds of lexical analysis and parsing, such as splitting a command
string up into tokens.  You can do this with the `strtok' function,
declared in the header file `string.h'.

 - Function: char * strtok (char *restrict NEWSTRING, const char
          *restrict DELIMITERS)
     A string can be split into tokens by making a series of calls to
     the function `strtok'.

     The string to be split up is passed as the NEWSTRING argument on
     the first call only.  The `strtok' function uses this to set up
     some internal state information.  Subsequent calls to get
     additional tokens from the same string are indicated by passing a
     null pointer as the NEWSTRING argument.  Calling `strtok' with
     another non-null NEWSTRING argument reinitializes the state
     information.  It is guaranteed that no other library function ever
     calls `strtok' behind your back (which would mess up this internal
     state information).

     The DELIMITERS argument is a string that specifies a set of
     delimiters that may surround the token being extracted.  All the
     initial characters that are members of this set are discarded.
     The first character that is _not_ a member of this set of
     delimiters marks the beginning of the next token.  The end of the
     token is found by looking for the next character that is a member
     of the delimiter set.  This character in the original string
     NEWSTRING is overwritten by a null character, and the pointer to
     the beginning of the token in NEWSTRING is returned.

     On the next call to `strtok', the searching begins at the next
     character beyond the one that marked the end of the previous token.
     Note that the set of delimiters DELIMITERS do not have to be the
     same on every call in a series of calls to `strtok'.

     If the end of the string NEWSTRING is reached, or if the remainder
     of string consists only of delimiter characters, `strtok' returns
     a null pointer.

     Note that "character" is here used in the sense of byte.  In a
     string using a multibyte character encoding (abstract) character
     consisting of more than one byte are not treated as an entity.
     Each byte is treated separately.  The function is not
     locale-dependent.

     Note that "character" is here used in the sense of byte.  In a
     string using a multibyte character encoding (abstract) character
     consisting of more than one byte are not treated as an entity.
     Each byte is treated separately.  The function is not
     locale-dependent.

 - Function: wchar_t * wcstok (wchar_t *NEWSTRING, const char
          *DELIMITERS)
     A string can be split into tokens by making a series of calls to
     the function `wcstok'.

     The string to be split up is passed as the NEWSTRING argument on
     the first call only.  The `wcstok' function uses this to set up
     some internal state information.  Subsequent calls to get
     additional tokens from the same wide character string are
     indicated by passing a null pointer as the NEWSTRING argument.
     Calling `wcstok' with another non-null NEWSTRING argument
     reinitializes the state information.  It is guaranteed that no
     other library function ever calls `wcstok' behind your back (which
     would mess up this internal state information).

     The DELIMITERS argument is a wide character string that specifies
     a set of delimiters that may surround the token being extracted.
     All the initial wide characters that are members of this set are
     discarded.  The first wide character that is _not_ a member of
     this set of delimiters marks the beginning of the next token.  The
     end of the token is found by looking for the next wide character
     that is a member of the delimiter set.  This wide character in the
     original wide character string NEWSTRING is overwritten by a null
     wide character, and the pointer to the beginning of the token in
     NEWSTRING is returned.

     On the next call to `wcstok', the searching begins at the next
     wide character beyond the one that marked the end of the previous
     token.  Note that the set of delimiters DELIMITERS do not have to
     be the same on every call in a series of calls to `wcstok'.

     If the end of the wide character string NEWSTRING is reached, or
     if the remainder of string consists only of delimiter wide
     characters, `wcstok' returns a null pointer.

     Note that "character" is here used in the sense of byte.  In a
     string using a multibyte character encoding (abstract) character
     consisting of more than one byte are not treated as an entity.
     Each byte is treated separately.  The function is not
     locale-dependent.

   *Warning:* Since `strtok' and `wcstok' alter the string they is
parsing, you should always copy the string to a temporary buffer before
parsing it with `strtok'/`wcstok' (see Copying and Concatenation).
If you allow `strtok' or `wcstok' to modify a string that came from
another part of your program, you are asking for trouble; that string
might be used for other purposes after `strtok' or `wcstok' has
modified it, and it would not have the expected value.

   The string that you are operating on might even be a constant.  Then
when `strtok' or `wcstok' tries to modify it, your program will get a
fatal signal for writing in read-only memory.  See Program Error Signals.
Even if the operation of `strtok' or `wcstok' would not
require a modification of the string (e.g., if there is exactly one
token) the string can (and in the GNU libc case will) be modified.

   This is a special case of a general principle: if a part of a program
does not have as its purpose the modification of a certain data
structure, then it is error-prone to modify the data structure
temporarily.

   The functions `strtok' and `wcstok' are not reentrant.  See
Nonreentrancy, for a discussion of where and why reentrancy is
important.

   Here is a simple example showing the use of `strtok'.

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

     ...

     const char string[] = "words separated by spaces -- and, punctuation!";
     const char delimiters[] = " .,;:!-";
     char *token, *cp;

     ...

     cp = strdupa (string);                /* Make writable copy.  */
     token = strtok (cp, delimiters);      /* token => "words" */
     token = strtok (NULL, delimiters);    /* token => "separated" */
     token = strtok (NULL, delimiters);    /* token => "by" */
     token = strtok (NULL, delimiters);    /* token => "spaces" */
     token = strtok (NULL, delimiters);    /* token => "and" */
     token = strtok (NULL, delimiters);    /* token => "punctuation" */
     token = strtok (NULL, delimiters);    /* token => NULL */

   The GNU C library contains two more functions for tokenizing a string
which overcome the limitation of non-reentrancy.  They are only
available for multibyte character strings.

 - Function: char * strtok_r (char *NEWSTRING, const char *DELIMITERS,
          char **SAVE_PTR)
     Just like `strtok', this function splits the string into several
     tokens which can be accessed by successive calls to `strtok_r'.
     The difference is that the information about the next token is
     stored in the space pointed to by the third argument, SAVE_PTR,
     which is a pointer to a string pointer.  Calling `strtok_r' with a
     null pointer for NEWSTRING and leaving SAVE_PTR between the calls
     unchanged does the job without hindering reentrancy.

     This function is defined in POSIX.1 and can be found on many
     systems which support multi-threading.

 - Function: char * strsep (char **STRING_PTR, const char *DELIMITER)
     This function has a similar functionality as `strtok_r' with the
     NEWSTRING argument replaced by the SAVE_PTR argument.  The
     initialization of the moving pointer has to be done by the user.
     Successive calls to `strsep' move the pointer along the tokens
     separated by DELIMITER, returning the address of the next token
     and updating STRING_PTR to point to the beginning of the next
     token.

     One difference between `strsep' and `strtok_r' is that if the
     input string contains more than one character from DELIMITER in a
     row `strsep' returns an empty string for each pair of characters
     from DELIMITER.  This means that a program normally should test
     for `strsep' returning an empty string before processing it.

     This function was introduced in 4.3BSD and therefore is widely
     available.

   Here is how the above example looks like when `strsep' is used.

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

     ...

     const char string[] = "words separated by spaces -- and, punctuation!";
     const char delimiters[] = " .,;:!-";
     char *running;
     char *token;

     ...

     running = strdupa (string);
     token = strsep (&running, delimiters);    /* token => "words" */
     token = strsep (&running, delimiters);    /* token => "separated" */
     token = strsep (&running, delimiters);    /* token => "by" */
     token = strsep (&running, delimiters);    /* token => "spaces" */
     token = strsep (&running, delimiters);    /* token => "" */
     token = strsep (&running, delimiters);    /* token => "" */
     token = strsep (&running, delimiters);    /* token => "" */
     token = strsep (&running, delimiters);    /* token => "and" */
     token = strsep (&running, delimiters);    /* token => "" */
     token = strsep (&running, delimiters);    /* token => "punctuation" */
     token = strsep (&running, delimiters);    /* token => "" */
     token = strsep (&running, delimiters);    /* token => NULL */

 - Function: char * basename (const char *FILENAME)
     The GNU version of the `basename' function returns the last
     component of the path in FILENAME.  This function is the preferred
     usage, since it does not modify the argument, FILENAME, and
     respects trailing slashes.  The prototype for `basename' can be
     found in `string.h'.  Note, this function is overriden by the XPG
     version, if `libgen.h' is included.

     Example of using GNU `basename':

          #include <string.h>

          int
          main (int argc, char *argv[])
          {
            char *prog = basename (argv[0]);

            if (argc < 2)
              {
                fprintf (stderr, "Usage %s <arg>\n", prog);
                exit (1);
              }

            ...
          }

     *Portability Note:* This function may produce different results on
     different systems.

 - Function: char * basename (char *PATH)
     This is the standard XPG defined `basename'. It is similar in
     spirit to the GNU version, but may modify the PATH by removing
     trailing '/' characters.  If the PATH is made up entirely of '/'
     characters, then "/" will be returned.  Also, if PATH is `NULL' or
     an empty string, then "." is returned.  The prototype for the XPG
     version can be found in `libgen.h'.

     Example of using XPG `basename':

          #include <libgen.h>

          int
          main (int argc, char *argv[])
          {
            char *prog;
            char *path = strdupa (argv[0]);

            prog = basename (path);

            if (argc < 2)
              {
                fprintf (stderr, "Usage %s <arg>\n", prog);
                exit (1);
              }

            ...

          }

 - Function: char * dirname (char *PATH)
     The `dirname' function is the compliment to the XPG version of
     `basename'.  It returns the parent directory of the file specified
     by PATH.  If PATH is `NULL', an empty string, or contains no '/'
     characters, then "." is returned.  The prototype for this function
     can be found in `libgen.h'.

strfry
======

   The function below addresses the perennial programming quandary:
"How do I take good data in string form and painlessly turn it into
garbage?"  This is actually a fairly simple task for C programmers who
do not use the GNU C library string functions, but for programs based
on the GNU C library, the `strfry' function is the preferred method for
destroying string data.

   The prototype for this function is in `string.h'.

 - Function: char * strfry (char *STRING)
     `strfry' creates a pseudorandom anagram of a string, replacing the
     input with the anagram in place.  For each position in the string,
     `strfry' swaps it with a position in the string selected at random
     (from a uniform distribution).  The two positions may be the same.

     The return value of `strfry' is always STRING.

     *Portability Note:*  This function is unique to the GNU C library.

Trivial Encryption
==================

   The `memfrob' function converts an array of data to something
unrecognizable and back again.  It is not encryption in its usual sense
since it is easy for someone to convert the encrypted data back to clear
text.  The transformation is analogous to Usenet's "Rot13" encryption
method for obscuring offensive jokes from sensitive eyes and such.
Unlike Rot13, `memfrob' works on arbitrary binary data, not just text.

   For true encryption, see Cryptographic Functions.

   This function is declared in `string.h'.

 - Function: void * memfrob (void *MEM, size_t LENGTH)
     `memfrob' transforms (frobnicates) each byte of the data structure
     at MEM, which is LENGTH bytes long, by bitwise exclusive oring it
     with binary 00101010.  It does the transformation in place and its
     return value is always MEM.

     Note that `memfrob' a second time on the same data structure
     returns it to its original state.

     This is a good function for hiding information from someone who
     doesn't want to see it or doesn't want to see it very much.  To
     really prevent people from retrieving the information, use
     stronger encryption such as that described in Cryptographic Functions.

     *Portability Note:*  This function is unique to the GNU C library.

Encode Binary Data
==================

   To store or transfer binary data in environments which only support
text one has to encode the binary data by mapping the input bytes to
characters in the range allowed for storing or transfering.  SVID
systems (and nowadays XPG compliant systems) provide minimal support for
this task.

 - Function: char * l64a (long int N)
     This function encodes a 32-bit input value using characters from
     the basic character set.  It returns a pointer to a 6 character
     buffer which contains an encoded version of N.  To encode a series
     of bytes the user must copy the returned string to a destination
     buffer.  It returns the empty string if N is zero, which is
     somewhat bizarre but mandated by the standard.
     *Warning:* Since a static buffer is used this function should not
     be used in multi-threaded programs.  There is no thread-safe
     alternative to this function in the C library.
     *Compatibility Note:* The XPG standard states that the return
     value of `l64a' is undefined if N is negative.  In the GNU
     implementation, `l64a' treats its argument as unsigned, so it will
     return a sensible encoding for any nonzero N; however, portable
     programs should not rely on this.

     To encode a large buffer `l64a' must be called in a loop, once for
     each 32-bit word of the buffer.  For example, one could do
     something like this:

          char *
          encode (const void *buf, size_t len)
          {
            /* We know in advance how long the buffer has to be. */
            unsigned char *in = (unsigned char *) buf;
            char *out = malloc (6 + ((len + 3) / 4) * 6 + 1);
            char *cp = out;

            /* Encode the length. */
            /* Using `htonl' is necessary so that the data can be
               decoded even on machines with different byte order. */

            cp = mempcpy (cp, l64a (htonl (len)), 6);

            while (len > 3)
              {
                unsigned long int n = *in++;
                n = (n << 8) | *in++;
                n = (n << 8) | *in++;
                n = (n << 8) | *in++;
                len -= 4;
                if (n)
                  cp = mempcpy (cp, l64a (htonl (n)), 6);
                else
                      /* `l64a' returns the empty string for n==0, so we
                         must generate its encoding ("......") by hand. */
                  cp = stpcpy (cp, "......");
              }
            if (len > 0)
              {
                unsigned long int n = *in++;
                if (--len > 0)
                  {
                    n = (n << 8) | *in++;
                    if (--len > 0)
                      n = (n << 8) | *in;
                  }
                memcpy (cp, l64a (htonl (n)), 6);
                cp += 6;
              }
            *cp = '\0';
            return out;
          }

     It is strange that the library does not provide the complete
     functionality needed but so be it.

   To decode data produced with `l64a' the following function should be
used.

 - Function: long int a64l (const char *STRING)
     The parameter STRING should contain a string which was produced by
     a call to `l64a'.  The function processes at least 6 characters of
     this string, and decodes the characters it finds according to the
     table below.  It stops decoding when it finds a character not in
     the table, rather like `atoi'; if you have a buffer which has been
     broken into lines, you must be careful to skip over the
     end-of-line characters.

     The decoded number is returned as a `long int' value.

   The `l64a' and `a64l' functions use a base 64 encoding, in which
each character of an encoded string represents six bits of an input
word.  These symbols are used for the base 64 digits:

        0     1     2     3     4     5     6     7
0       `.'   `/'   `0'   `1'   `2'   `3'   `4'   `5'
8       `6'   `7'   `8'   `9'   `A'   `B'   `C'   `D'
16      `E'   `F'   `G'   `H'   `I'   `J'   `K'   `L'
24      `M'   `N'   `O'   `P'   `Q'   `R'   `S'   `T'
32      `U'   `V'   `W'   `X'   `Y'   `Z'   `a'   `b'
40      `c'   `d'   `e'   `f'   `g'   `h'   `i'   `j'
48      `k'   `l'   `m'   `n'   `o'   `p'   `q'   `r'
56      `s'   `t'   `u'   `v'   `w'   `x'   `y'   `z'

   This encoding scheme is not standard.  There are some other encoding
methods which are much more widely used (UU encoding, MIME encoding).
Generally, it is better to use one of these encodings.

Argz and Envz Vectors
=====================

   "argz vectors" are vectors of strings in a contiguous block of
memory, each element separated from its neighbors by null-characters
(`'\0'').

   "Envz vectors" are an extension of argz vectors where each element
is a name-value pair, separated by a `'='' character (as in a Unix
environment).

Argz Functions
--------------

   Each argz vector is represented by a pointer to the first element, of
type `char *', and a size, of type `size_t', both of which can be
initialized to `0' to represent an empty argz vector.  All argz
functions accept either a pointer and a size argument, or pointers to
them, if they will be modified.

   The argz functions use `malloc'/`realloc' to allocate/grow argz
vectors, and so any argz vector creating using these functions may be
freed by using `free'; conversely, any argz function that may grow a
string expects that string to have been allocated using `malloc' (those
argz functions that only examine their arguments or modify them in
place will work on any sort of memory).  See Unconstrained Allocation.

   All argz functions that do memory allocation have a return type of
`error_t', and return `0' for success, and `ENOMEM' if an allocation
error occurs.

   These functions are declared in the standard include file `argz.h'.

 - Function: error_t argz_create (char *const ARGV[], char **ARGZ,
          size_t *ARGZ_LEN)
     The `argz_create' function converts the Unix-style argument vector
     ARGV (a vector of pointers to normal C strings, terminated by
     `(char *)0'; see Program Arguments) into an argz vector with
     the same elements, which is returned in ARGZ and ARGZ_LEN.

 - Function: error_t argz_create_sep (const char *STRING, int SEP, char
          **ARGZ, size_t *ARGZ_LEN)
     The `argz_create_sep' function converts the null-terminated string
     STRING into an argz vector (returned in ARGZ and ARGZ_LEN) by
     splitting it into elements at every occurrence of the character
     SEP.

 - Function: size_t argz_count (const char *ARGZ, size_t ARG_LEN)
     Returns the number of elements in the argz vector ARGZ and
     ARGZ_LEN.

 - Function: void argz_extract (char *ARGZ, size_t ARGZ_LEN, char
          **ARGV)
     The `argz_extract' function converts the argz vector ARGZ and
     ARGZ_LEN into a Unix-style argument vector stored in ARGV, by
     putting pointers to every element in ARGZ into successive
     positions in ARGV, followed by a terminator of `0'.  ARGV must be
     pre-allocated with enough space to hold all the elements in ARGZ
     plus the terminating `(char *)0' (`(argz_count (ARGZ, ARGZ_LEN) +
     1) * sizeof (char *)' bytes should be enough).  Note that the
     string pointers stored into ARGV point into ARGZ--they are not
     copies--and so ARGZ must be copied if it will be changed while
     ARGV is still active.  This function is useful for passing the
     elements in ARGZ to an exec function (see Executing a File).

 - Function: void argz_stringify (char *ARGZ, size_t LEN, int SEP)
     The `argz_stringify' converts ARGZ into a normal string with the
     elements separated by the character SEP, by replacing each `'\0''
     inside ARGZ (except the last one, which terminates the string)
     with SEP.  This is handy for printing ARGZ in a readable manner.

 - Function: error_t argz_add (char **ARGZ, size_t *ARGZ_LEN, const
          char *STR)
     The `argz_add' function adds the string STR to the end of the argz
     vector `*ARGZ', and updates `*ARGZ' and `*ARGZ_LEN' accordingly.

 - Function: error_t argz_add_sep (char **ARGZ, size_t *ARGZ_LEN, const
          char *STR, int DELIM)
     The `argz_add_sep' function is similar to `argz_add', but STR is
     split into separate elements in the result at occurrences of the
     character DELIM.  This is useful, for instance, for adding the
     components of a Unix search path to an argz vector, by using a
     value of `':'' for DELIM.

 - Function: error_t argz_append (char **ARGZ, size_t *ARGZ_LEN, const
          char *BUF, size_t BUF_LEN)
     The `argz_append' function appends BUF_LEN bytes starting at BUF
     to the argz vector `*ARGZ', reallocating `*ARGZ' to accommodate
     it, and adding BUF_LEN to `*ARGZ_LEN'.

 - Function: error_t argz_delete (char **ARGZ, size_t *ARGZ_LEN, char
          *ENTRY)
     If ENTRY points to the beginning of one of the elements in the
     argz vector `*ARGZ', the `argz_delete' function will remove this
     entry and reallocate `*ARGZ', modifying `*ARGZ' and `*ARGZ_LEN'
     accordingly.  Note that as destructive argz functions usually
     reallocate their argz argument, pointers into argz vectors such as
     ENTRY will then become invalid.

 - Function: error_t argz_insert (char **ARGZ, size_t *ARGZ_LEN, char
          *BEFORE, const char *ENTRY)
     The `argz_insert' function inserts the string ENTRY into the argz
     vector `*ARGZ' at a point just before the existing element pointed
     to by BEFORE, reallocating `*ARGZ' and updating `*ARGZ' and
     `*ARGZ_LEN'.  If BEFORE is `0', ENTRY is added to the end instead
     (as if by `argz_add').  Since the first element is in fact the
     same as `*ARGZ', passing in `*ARGZ' as the value of BEFORE will
     result in ENTRY being inserted at the beginning.

 - Function: char * argz_next (char *ARGZ, size_t ARGZ_LEN, const char
          *ENTRY)
     The `argz_next' function provides a convenient way of iterating
     over the elements in the argz vector ARGZ.  It returns a pointer
     to the next element in ARGZ after the element ENTRY, or `0' if
     there are no elements following ENTRY.  If ENTRY is `0', the first
     element of ARGZ is returned.

     This behavior suggests two styles of iteration:

              char *entry = 0;
              while ((entry = argz_next (ARGZ, ARGZ_LEN, entry)))
                ACTION;

     (the double parentheses are necessary to make some C compilers
     shut up about what they consider a questionable `while'-test) and:

              char *entry;
              for (entry = ARGZ;
                   entry;
                   entry = argz_next (ARGZ, ARGZ_LEN, entry))
                ACTION;

     Note that the latter depends on ARGZ having a value of `0' if it
     is empty (rather than a pointer to an empty block of memory); this
     invariant is maintained for argz vectors created by the functions
     here.

 - Function: error_t argz_replace (char **ARGZ, size_t *ARGZ_LEN,
          const char *STR, const char *WITH, unsigned *REPLACE_COUNT)
     Replace any occurrences of the string STR in ARGZ with WITH,
     reallocating ARGZ as necessary.  If REPLACE_COUNT is non-zero,
     `*REPLACE_COUNT' will be incremented by number of replacements
     performed.

Envz Functions
--------------

   Envz vectors are just argz vectors with additional constraints on
the form of each element; as such, argz functions can also be used on
them, where it makes sense.

   Each element in an envz vector is a name-value pair, separated by a
`'='' character; if multiple `'='' characters are present in an
element, those after the first are considered part of the value, and
treated like all other non-`'\0'' characters.

   If _no_ `'='' characters are present in an element, that element is
considered the name of a "null" entry, as distinct from an entry with an
empty value: `envz_get' will return `0' if given the name of null
entry, whereas an entry with an empty value would result in a value of
`""'; `envz_entry' will still find such entries, however.  Null entries
can be removed with `envz_strip' function.

   As with argz functions, envz functions that may allocate memory (and
thus fail) have a return type of `error_t', and return either `0' or
`ENOMEM'.

   These functions are declared in the standard include file `envz.h'.

 - Function: char * envz_entry (const char *ENVZ, size_t ENVZ_LEN,
          const char *NAME)
     The `envz_entry' function finds the entry in ENVZ with the name
     NAME, and returns a pointer to the whole entry--that is, the argz
     element which begins with NAME followed by a `'='' character.  If
     there is no entry with that name, `0' is returned.

 - Function: char * envz_get (const char *ENVZ, size_t ENVZ_LEN, const
          char *NAME)
     The `envz_get' function finds the entry in ENVZ with the name NAME
     (like `envz_entry'), and returns a pointer to the value portion of
     that entry (following the `'='').  If there is no entry with that
     name (or only a null entry), `0' is returned.

 - Function: error_t envz_add (char **ENVZ, size_t *ENVZ_LEN, const
          char *NAME, const char *VALUE)
     The `envz_add' function adds an entry to `*ENVZ' (updating `*ENVZ'
     and `*ENVZ_LEN') with the name NAME, and value VALUE.  If an entry
     with the same name already exists in ENVZ, it is removed first.
     If VALUE is `0', then the new entry will the special null type of
     entry (mentioned above).

 - Function: error_t envz_merge (char **ENVZ, size_t *ENVZ_LEN, const
          char *ENVZ2, size_t ENVZ2_LEN, int OVERRIDE)
     The `envz_merge' function adds each entry in ENVZ2 to ENVZ, as if
     with `envz_add', updating `*ENVZ' and `*ENVZ_LEN'.  If OVERRIDE is
     true, then values in ENVZ2 will supersede those with the same name
     in ENVZ, otherwise not.

     Null entries are treated just like other entries in this respect,
     so a null entry in ENVZ can prevent an entry of the same name in
     ENVZ2 from being added to ENVZ, if OVERRIDE is false.

 - Function: void envz_strip (char **ENVZ, size_t *ENVZ_LEN)
     The `envz_strip' function removes any null entries from ENVZ,
     updating `*ENVZ' and `*ENVZ_LEN'.

Character Set Handling
**********************

   Character sets used in the early days of computing had only six,
seven, or eight bits for each character: there was never a case where
more than eight bits (one byte) were used to represent a single
character.  The limitations of this approach became more apparent as
more people grappled with non-Roman character sets, where not all the
characters that make up a language's character set can be represented
by 2^8 choices.  This chapter shows the functionality that was added to
the C library to support multiple character sets.