   This file documents the GNU C library.

   This is Edition 0.08 DRAFT, last updated 11 Jan 1999, of `The GNU C
Library Reference Manual', for Version 2.1 Beta.

   Copyright (C) 1993, '94, '95, '96, '97, '98, '99 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.

String/Array Comparison
=======================

   You can use the functions in this section to perform comparisons on
the contents of strings and arrays.  As well as checking for equality,
these functions can also be used as the ordering functions for sorting
operations.  See Searching and Sorting, for an example of this.

   Unlike most comparison operations in C, the string comparison
functions return a nonzero value if the strings are _not_ equivalent
rather than if they are.  The sign of the value indicates the relative
ordering of the first characters in the strings that are not
equivalent:  a negative value indicates that the first string is "less"
than the second, while a positive value indicates that the first string
is "greater".

   The most common use of these functions is to check only for equality.
This is canonically done with an expression like `! strcmp (s1, s2)'.

   All of these functions are declared in the header file `string.h'.

 - Function: int memcmp (const void *A1, const void *A2, size_t SIZE)
     The function `memcmp' compares the SIZE bytes of memory beginning
     at A1 against the SIZE bytes of memory beginning at A2.  The value
     returned has the same sign as the difference between the first
     differing pair of bytes (interpreted as `unsigned char' objects,
     then promoted to `int').

     If the contents of the two blocks are equal, `memcmp' returns `0'.

   On arbitrary arrays, the `memcmp' function is mostly useful for
testing equality.  It usually isn't meaningful to do byte-wise ordering
comparisons on arrays of things other than bytes.  For example, a
byte-wise comparison on the bytes that make up floating-point numbers
isn't likely to tell you anything about the relationship between the
values of the floating-point numbers.

   You should also be careful about using `memcmp' to compare objects
that can contain "holes", such as the padding inserted into structure
objects to enforce alignment requirements, extra space at the end of
unions, and extra characters at the ends of strings whose length is less
than their allocated size.  The contents of these "holes" are
indeterminate and may cause strange behavior when performing byte-wise
comparisons.  For more predictable results, perform an explicit
component-wise comparison.

   For example, given a structure type definition like:

     struct foo
       {
         unsigned char tag;
         union
           {
             double f;
             long i;
             char *p;
           } value;
       };

you are better off writing a specialized comparison function to compare
`struct foo' objects instead of comparing them with `memcmp'.

 - Function: int strcmp (const char *S1, const char *S2)
     The `strcmp' function compares the string S1 against S2, returning
     a value that has the same sign as the difference between the first
     differing pair of characters (interpreted as `unsigned char'
     objects, then promoted to `int').

     If the two strings are equal, `strcmp' returns `0'.

     A consequence of the ordering used by `strcmp' is that if S1 is an
     initial substring of S2, then S1 is considered to be "less than"
     S2.

 - Function: int strcasecmp (const char *S1, const char *S2)
     This function is like `strcmp', except that differences in case are
     ignored.  How uppercase and lowercase characters are related is
     determined by the currently selected locale.  In the standard `"C"'
     locale the characters A" and a" do not match but in a locale which
     regards these characters as parts of the alphabet they do match.

     `strcasecmp' is derived from BSD.

 - Function: int strncasecmp (const char *S1, const char *S2, size_t N)
     This function is like `strncmp', except that differences in case
     are ignored.  Like `strcasecmp', it is locale dependent how
     uppercase and lowercase characters are related.

     `strncasecmp' is a GNU extension.

 - Function: int strncmp (const char *S1, const char *S2, size_t SIZE)
     This function is the similar to `strcmp', except that no more than
     SIZE characters are compared.  In other words, if the two strings
     are the same in their first SIZE characters, the return value is
     zero.

   Here are some examples showing the use of `strcmp' and `strncmp'.
These examples assume the use of the ASCII character set.  (If some
other character set--say, EBCDIC--is used instead, then the glyphs are
associated with different numeric codes, and the return values and
ordering may differ.)

     strcmp ("hello", "hello")
         => 0    /* These two strings are the same. */
     strcmp ("hello", "Hello")
         => 32   /* Comparisons are case-sensitive. */
     strcmp ("hello", "world")
         => -15  /* The character `'h'' comes before `'w''. */
     strcmp ("hello", "hello, world")
         => -44  /* Comparing a null character against a comma. */
     strncmp ("hello", "hello, world", 5)
         => 0    /* The initial 5 characters are the same. */
     strncmp ("hello, world", "hello, stupid world!!!", 5)
         => 0    /* The initial 5 characters are the same. */

 - Function: int strverscmp (const char *S1, const char *S2)
     The `strverscmp' function compares the string S1 against S2,
     considering them as holding indices/version numbers.  Return value
     follows the same conventions as found in the `strverscmp'
     function.  In fact, if S1 and S2 contain no digits, `strverscmp'
     behaves like `strcmp'.

     Basically, we compare strings normally (character by character),
     until we find a digit in each string - then we enter a special
     comparison mode, where each sequence of digits is taken as a
     whole.  If we reach the end of these two parts without noticing a
     difference, we return to the standard comparison mode.  There are
     two types of numeric parts: "integral" and "fractional" (those
     begin with a '0'). The types of the numeric parts affect the way
     we sort them:

        * integral/integral: we compare values as you would expect.

        * fractional/integral: the fractional part is less than the
          integral one.  Again, no surprise.

        * fractional/fractional: the things become a bit more complex.
          If the common prefix contains only leading zeroes, the
          longest part is less than the other one; else the comparison
          behaves normally.

          strverscmp ("no digit", "no digit")
              => 0    /* same behaviour as strcmp. */
          strverscmp ("item#99", "item#100")
              => <0   /* same prefix, but 99 < 100. */
          strverscmp ("alpha1", "alpha001")
              => >0   /* fractional part inferior to integral one. */
          strverscmp ("part1_f012", "part1_f01")
              => >0   /* two fractional parts. */
          strverscmp ("foo.009", "foo.0")
              => <0   /* idem, but with leading zeroes only. */

     This function is especially useful when dealing with filename
     sorting, because filenames frequently hold indices/version numbers.

     `strverscmp' is a GNU extension.

 - Function: int bcmp (const void *A1, const void *A2, size_t SIZE)
     This is an obsolete alias for `memcmp', derived from BSD.

Collation Functions
===================

   In some locales, the conventions for lexicographic ordering differ
from the strict numeric ordering of character codes.  For example, in
Spanish most glyphs with diacritical marks such as accents are not
considered distinct letters for the purposes of collation.  On the
other hand, the two-character sequence `ll' is treated as a single
letter that is collated immediately after `l'.

   You can use the functions `strcoll' and `strxfrm' (declared in the
header file `string.h') to compare strings using a collation ordering
appropriate for the current locale.  The locale used by these functions
in particular can be specified by setting the locale for the
`LC_COLLATE' category; see Locales.

   In the standard C locale, the collation sequence for `strcoll' is
the same as that for `strcmp'.

   Effectively, the way these functions work is by applying a mapping to
transform the characters in a string to a byte sequence that represents
the string's position in the collating sequence of the current locale.
Comparing two such byte sequences in a simple fashion is equivalent to
comparing the strings with the locale's collating sequence.

   The function `strcoll' performs this translation implicitly, in
order to do one comparison.  By contrast, `strxfrm' performs the
mapping explicitly.  If you are making multiple comparisons using the
same string or set of strings, it is likely to be more efficient to use
`strxfrm' to transform all the strings just once, and subsequently
compare the transformed strings with `strcmp'.

 - Function: int strcoll (const char *S1, const char *S2)
     The `strcoll' function is similar to `strcmp' but uses the
     collating sequence of the current locale for collation (the
     `LC_COLLATE' locale).

   Here is an example of sorting an array of strings, using `strcoll'
to compare them.  The actual sort algorithm is not written here; it
comes from `qsort' (see Array Sort Function).  The job of the code
shown here is to say how to compare the strings while sorting them.
(Later on in this section, we will show a way to do this more
efficiently using `strxfrm'.)

     /* This is the comparison function used with `qsort'. */

     int
     compare_elements (char **p1, char **p2)
     {
       return strcoll (*p1, *p2);
     }

     /* This is the entry point--the function to sort
        strings using the locale's collating sequence. */

     void
     sort_strings (char **array, int nstrings)
     {
       /* Sort `temp_array' by comparing the strings. */
       qsort (array, nstrings,
              sizeof (char *), compare_elements);
     }

 - Function: size_t strxfrm (char *TO, const char *FROM, size_t SIZE)
     The function `strxfrm' transforms STRING using the collation
     transformation determined by the locale currently selected for
     collation, and stores the transformed string in the array TO.  Up
     to SIZE characters (including a terminating null character) are
     stored.

     The behavior is undefined if the strings TO and FROM overlap; see
     Copying and Concatenation.

     The return value is the length of the entire transformed string.
     This value is not affected by the value of SIZE, but if it is
     greater or equal than SIZE, it means that the transformed string
     did not entirely fit in the array TO.  In this case, only as much
     of the string as actually fits was stored.  To get the whole
     transformed string, call `strxfrm' again with a bigger output
     array.

     The transformed string may be longer than the original string, and
     it may also be shorter.

     If SIZE is zero, no characters are stored in TO.  In this case,
     `strxfrm' simply returns the number of characters that would be
     the length of the transformed string.  This is useful for
     determining what size string to allocate.  It does not matter what
     TO is if SIZE is zero; TO may even be a null pointer.

   Here is an example of how you can use `strxfrm' when you plan to do
many comparisons.  It does the same thing as the previous example, but
much faster, because it has to transform each string only once, no
matter how many times it is compared with other strings.  Even the time
needed to allocate and free storage is much less than the time we save,
when there are many strings.

     struct sorter { char *input; char *transformed; };

     /* This is the comparison function used with `qsort'
        to sort an array of `struct sorter'. */

     int
     compare_elements (struct sorter *p1, struct sorter *p2)
     {
       return strcmp (p1->transformed, p2->transformed);
     }

     /* This is the entry point--the function to sort
        strings using the locale's collating sequence. */

     void
     sort_strings_fast (char **array, int nstrings)
     {
       struct sorter temp_array[nstrings];
       int i;

       /* Set up `temp_array'.  Each element contains
          one input string and its transformed string. */
       for (i = 0; i < nstrings; i++)
         {
           size_t length = strlen (array[i]) * 2;
           char *transformed;
           size_t transformed_length;

           temp_array[i].input = array[i];

           /* First try a buffer perhaps big enough.  */
           transformed = (char *) xmalloc (length);

           /* Transform `array[i]'.  */
           transformed_length = strxfrm (transformed, array[i], length);

           /* If the buffer was not large enough, resize it
              and try again.  */
           if (transformed_length >= length)
             {
               /* Allocate the needed space. +1 for terminating
                  `NUL' character.  */
               transformed = (char *) xrealloc (transformed,
                                                transformed_length + 1);

               /* The return value is not interesting because we know
                  how long the transformed string is.  */
               (void) strxfrm (transformed, array[i],
                               transformed_length + 1);
             }

           temp_array[i].transformed = transformed;
         }

       /* Sort `temp_array' by comparing transformed strings. */
       qsort (temp_array, sizeof (struct sorter),
              nstrings, compare_elements);

       /* Put the elements back in the permanent array
          in their sorted order. */
       for (i = 0; i < nstrings; i++)
         array[i] = temp_array[i].input;

       /* Free the strings we allocated. */
       for (i = 0; i < nstrings; i++)
         free (temp_array[i].transformed);
     }

   *Compatibility Note:*  The string collation functions are a new
feature of ISO C 89.  Older C dialects have no equivalent feature.

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: 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.

 - 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.

   One useful, but unusual, use of the `strchr' or `index' 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 when using the GNU C library is used this `strchr'
call gets optimized in a special way so that this version 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: 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.

 - 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: 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

 - 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

 - 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"

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 *NEWSTRING, const char *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.

   *Warning:* Since `strtok' alters the string it is parsing, you
should always copy the string to a temporary buffer before parsing it
with `strtok'.  If you allow `strtok' 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' 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' tries to modify it, your program will get a fatal signal
for writing in read-only memory.  See Program Error Signals.

   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 function `strtok' is 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.

 - 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 is just `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.

     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 */

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 which was added
to the C library to correctly support multiple character sets.