This is libc.info, produced by makeinfo version 4.0c from libc.texinfo.

INFO-DIR-SECTION GNU libraries
START-INFO-DIR-ENTRY
* Libc: (libc).                 C library.
END-INFO-DIR-ENTRY

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


File: libc.info,  Node: Representation of Strings,  Next: String/Array Conventions,  Up: String and Array Utilities

Representation of Strings
=========================

   This section is a quick summary of string concepts for beginning C
programmers.  It describes how character strings are represented in C
and some common pitfalls.  If you are already familiar with this
material, you can skip this section.

   A "string" is an array of `char' objects.  But string-valued
variables are usually declared to be pointers of type `char *'.  Such
variables do not include space for the text of a string; that has to be
stored somewhere else--in an array variable, a string constant, or
dynamically allocated memory (*note Memory Allocation::).  It's up to
you to store the address of the chosen memory space into the pointer
variable.  Alternatively you can store a "null pointer" in the pointer
variable.  The null pointer does not point anywhere, so attempting to
reference the string it points to gets an error.

   "string" normally refers to multibyte character strings as opposed to
wide character strings.  Wide character strings are arrays of type
`wchar_t' and as for multibyte character strings usually pointers of
type `wchar_t *' are used.

   By convention, a "null character", `'\0'', marks the end of a
multibyte character string and the "null wide character", `L'\0'',
marks the end of a wide character string.  For example, in testing to
see whether the `char *' variable P points to a null character marking
the end of a string, you can write `!*P' or `*P == '\0''.

   A null character is quite different conceptually from a null pointer,
although both are represented by the integer `0'.

   "String literals" appear in C program source as strings of
characters between double-quote characters (`"') where the initial
double-quote character is immediately preceded by a capital `L' (ell)
character (as in `L"foo"').  In ISO C, string literals can also be
formed by "string concatenation": `"a" "b"' is the same as `"ab"'.  For
wide character strings one can either use `L"a" L"b"' or `L"a" "b"'.
Modification of string literals is not allowed by the GNU C compiler,
because literals are placed in read-only storage.

   Character arrays that are declared `const' cannot be modified
either.  It's generally good style to declare non-modifiable string
pointers to be of type `const char *', since this often allows the C
compiler to detect accidental modifications as well as providing some
amount of documentation about what your program intends to do with the
string.

   The amount of memory allocated for the character array may extend
past the null character that normally marks the end of the string.  In
this document, the term "allocated size" is always used to refer to the
total amount of memory allocated for the string, while the term
"length" refers to the number of characters up to (but not including)
the terminating null character.

   A notorious source of program bugs is trying to put more characters
in a string than fit in its allocated size.  When writing code that
extends strings or moves characters into a pre-allocated array, you
should be very careful to keep track of the length of the text and make
explicit checks for overflowing the array.  Many of the library
functions _do not_ do this for you!  Remember also that you need to
allocate an extra byte to hold the null character that marks the end of
the string.

   Originally strings were sequences of bytes where each byte
represents a single character.  This is still true today if the strings
are encoded using a single-byte character encoding.  Things are
different if the strings are encoded using a multibyte encoding (for
more information on encodings see *Note Extended Char Intro::).  There
is no difference in the programming interface for these two kind of
strings; the programmer has to be aware of this and interpret the byte
sequences accordingly.

   But since there is no separate interface taking care of these
differences the byte-based string functions are sometimes hard to use.
Since the count parameters of these functions specify bytes a call to
`strncpy' could cut a multibyte character in the middle and put an
incomplete (and therefore unusable) byte sequence in the target buffer.

   To avoid these problems later versions of the ISO C standard
introduce a second set of functions which are operating on "wide
characters" (*note Extended Char Intro::).  These functions don't have
the problems the single-byte versions have since every wide character is
a legal, interpretable value.  This does not mean that cutting wide
character strings at arbitrary points is without problems.  It normally
is for alphabet-based languages (except for non-normalized text) but
languages based on syllables still have the problem that more than one
wide character is necessary to complete a logical unit.  This is a
higher level problem which the C library functions are not designed to
solve.  But it is at least good that no invalid byte sequences can be
created.  Also, the higher level functions can also much easier operate
on wide character than on multibyte characters so that a general advise
is to use wide characters internally whenever text is more than simply
copied.

   The remaining of this chapter will discuss the functions for handling
wide character strings in parallel with the discussion of the multibyte
character strings since there is almost always an exact equivalent
available.


File: libc.info,  Node: String/Array Conventions,  Next: String Length,  Prev: Representation of Strings,  Up: String and Array Utilities

String and Array Conventions
============================

   This chapter describes both functions that work on arbitrary arrays
or blocks of memory, and functions that are specific to null-terminated
arrays of characters and wide characters.

   Functions that operate on arbitrary blocks of memory have names
beginning with `mem' and `wmem' (such as `memcpy' and `wmemcpy') and
invariably take an argument which specifies the size (in bytes and wide
characters respectively) of the block of memory to operate on.  The
array arguments and return values for these functions have type `void
*' or `wchar_t'.  As a matter of style, the elements of the arrays used
with the `mem' functions are referred to as "bytes".  You can pass any
kind of pointer to these functions, and the `sizeof' operator is useful
in computing the value for the size argument.  Parameters to the `wmem'
functions must be of type `wchar_t *'.  These functions are not really
usable with anything but arrays of this type.

   In contrast, functions that operate specifically on strings and wide
character strings have names beginning with `str' and `wcs'
respectively (such as `strcpy' and `wcscpy') and look for a null
character to terminate the string instead of requiring an explicit size
argument to be passed.  (Some of these functions accept a specified
maximum length, but they also check for premature termination with a
null character.)  The array arguments and return values for these
functions have type `char *' and `wchar_t *' respectively, and the
array elements are referred to as "characters" and "wide characters".

   In many cases, there are both `mem' and `str'/`wcs' versions of a
function.  The one that is more appropriate to use depends on the exact
situation.  When your program is manipulating arbitrary arrays or
blocks of storage, then you should always use the `mem' functions.  On
the other hand, when you are manipulating null-terminated strings it is
usually more convenient to use the `str'/`wcs' functions, unless you
already know the length of the string in advance.  The `wmem' functions
should be used for wide character arrays with known size.

   Some of the memory and string functions take single characters as
arguments.  Since a value of type `char' is automatically promoted into
an value of type `int' when used as a parameter, the functions are
declared with `int' as the type of the parameter in question.  In case
of the wide character function the situation is similarly: the
parameter type for a single wide character is `wint_t' and not
`wchar_t'.  This would for many implementations not be necessary since
the `wchar_t' is large enough to not be automatically promoted, but
since the ISO C standard does not require such a choice of types the
`wint_t' type is used.


File: libc.info,  Node: String Length,  Next: Copying and Concatenation,  Prev: String/Array Conventions,  Up: String and Array Utilities

String Length
=============

   You can get the length of a string using the `strlen' function.
This function is declared in the header file `string.h'.

 - Function: size_t strlen (const char *S)
     The `strlen' function returns the length of the null-terminated
     string S in bytes.  (In other words, it returns the offset of the
     terminating null character within the array.)

     For example,
          strlen ("hello, world")
              => 12

     When applied to a character array, the `strlen' function returns
     the length of the string stored there, not its allocated size.
     You can get the allocated size of the character array that holds a
     string using the `sizeof' operator:

          char string[32] = "hello, world";
          sizeof (string)
              => 32
          strlen (string)
              => 12

     But beware, this will not work unless STRING is the character
     array itself, not a pointer to it.  For example:

          char string[32] = "hello, world";
          char *ptr = string;
          sizeof (string)
              => 32
          sizeof (ptr)
              => 4  /* (on a machine with 4 byte pointers) */

     This is an easy mistake to make when you are working with
     functions that take string arguments; those arguments are always
     pointers, not arrays.

     It must also be noted that for multibyte encoded strings the return
     value does not have to correspond to the number of characters in
     the string.  To get this value the string can be converted to wide
     characters and `wcslen' can be used or something like the following
     code can be used:

          /* The input is in `string'.
             The length is expected in `n'.  */
          {
            mbstate_t t;
            char *scopy = string;
            /* In initial state.  */
            memset (&t, '\0', sizeof (t));
            /* Determine number of characters.  */
            n = mbsrtowcs (NULL, &scopy, strlen (scopy), &t);
          }

     This is cumbersome to do so if the number of characters (as
     opposed to bytes) is needed often it is better to work with wide
     characters.

   The wide character equivalent is declared in `wchar.h'.

 - Function: size_t wcslen (const wchar_t *WS)
     The `wcslen' function is the wide character equivalent to
     `strlen'.  The return value is the number of wide characters in the
     wide character string pointed to by WS (this is also the offset of
     the terminating null wide character of WS).

     Since there are no multi wide character sequences making up one
     character the return value is not only the offset in the array, it
     is also the number of wide characters.

     This function was introduced in Amendment 1 to ISO C90.

 - Function: size_t strnlen (const char *S, size_t MAXLEN)
     The `strnlen' function returns the length of the string S in bytes
     if this length is smaller than MAXLEN bytes.  Otherwise it returns
     MAXLEN.  Therefore this function is equivalent to `(strlen (S) < n
     ? strlen (S) : MAXLEN)' but it is more efficient and works even if
     the string S is not null-terminated.

          char string[32] = "hello, world";
          strnlen (string, 32)
              => 12
          strnlen (string, 5)
              => 5

     This function is a GNU extension and is declared in `string.h'.

 - Function: size_t wcsnlen (const wchar_t *WS, size_t MAXLEN)
     `wcsnlen' is the wide character equivalent to `strnlen'.  The
     MAXLEN parameter specifies the maximum number of wide characters.

     This function is a GNU extension and is declared in `wchar.h'.


File: libc.info,  Node: Copying and Concatenation,  Next: String/Array Comparison,  Prev: String Length,  Up: String and Array Utilities

Copying and Concatenation
=========================

   You can use the functions described in this section to copy the
contents of strings and arrays, or to append the contents of one string
to another.  The `str' and `mem' functions are declared in the header
file `string.h' while the `wstr' and `wmem' functions are declared in
the file `wchar.h'.

   A helpful way to remember the ordering of the arguments to the
functions in this section is that it corresponds to an assignment
expression, with the destination array specified to the left of the
source array.  All of these functions return the address of the
destination array.

   Most of these functions do not work properly if the source and
destination arrays overlap.  For example, if the beginning of the
destination array overlaps the end of the source array, the original
contents of that part of the source array may get overwritten before it
is copied.  Even worse, in the case of the string functions, the null
character marking the end of the string may be lost, and the copy
function might get stuck in a loop trashing all the memory allocated to
your program.

   All functions that have problems copying between overlapping arrays
are explicitly identified in this manual.  In addition to functions in
this section, there are a few others like `sprintf' (*note Formatted
Output Functions::) and `scanf' (*note Formatted Input Functions::).

 - Function: void * memcpy (void *restrict TO, const void *restrict
          FROM, size_t SIZE)
     The `memcpy' function copies SIZE bytes from the object beginning
     at FROM into the object beginning at TO.  The behavior of this
     function is undefined if the two arrays TO and FROM overlap; use
     `memmove' instead if overlapping is possible.

     The value returned by `memcpy' is the value of TO.

     Here is an example of how you might use `memcpy' to copy the
     contents of an array:

          struct foo *oldarray, *newarray;
          int arraysize;
          ...
          memcpy (new, old, arraysize * sizeof (struct foo));

 - Function: wchar_t * wmemcpy (wchar_t *restrict WTO, const wchar_t
          *restruct WFROM, size_t SIZE)
     The `wmemcpy' function copies SIZE wide characters from the object
     beginning at WFROM into the object beginning at WTO.  The behavior
     of this function is undefined if the two arrays WTO and WFROM
     overlap; use `wmemmove' instead if overlapping is possible.

     The following is a possible implementation of `wmemcpy' but there
     are more optimizations possible.

          wchar_t *
          wmemcpy (wchar_t *restrict wto, const wchar_t *restrict wfrom,
                   size_t size)
          {
            return (wchar_t *) memcpy (wto, wfrom, size * sizeof (wchar_t));
          }

     The value returned by `wmemcpy' is the value of WTO.

     This function was introduced in Amendment 1 to ISO C90.

 - Function: void * mempcpy (void *restrict TO, const void *restrict
          FROM, size_t SIZE)
     The `mempcpy' function is nearly identical to the `memcpy'
     function.  It copies SIZE bytes from the object beginning at
     `from' into the object pointed to by TO.  But instead of returning
     the value of TO it returns a pointer to the byte following the
     last written byte in the object beginning at TO.  I.e., the value
     is `((void *) ((char *) TO + SIZE))'.

     This function is useful in situations where a number of objects
     shall be copied to consecutive memory positions.

          void *
          combine (void *o1, size_t s1, void *o2, size_t s2)
          {
            void *result = malloc (s1 + s2);
            if (result != NULL)
              mempcpy (mempcpy (result, o1, s1), o2, s2);
            return result;
          }

     This function is a GNU extension.

 - Function: wchar_t * wmempcpy (wchar_t *restrict WTO, const wchar_t
          *restrict WFROM, size_t SIZE)
     The `wmempcpy' function is nearly identical to the `wmemcpy'
     function.  It copies SIZE wide characters from the object
     beginning at `wfrom' into the object pointed to by WTO.  But
     instead of returning the value of WTO it returns a pointer to the
     wide character following the last written wide character in the
     object beginning at WTO.  I.e., the value is `WTO + SIZE'.

     This function is useful in situations where a number of objects
     shall be copied to consecutive memory positions.

     The following is a possible implementation of `wmemcpy' but there
     are more optimizations possible.

          wchar_t *
          wmempcpy (wchar_t *restrict wto, const wchar_t *restrict wfrom,
                    size_t size)
          {
            return (wchar_t *) mempcpy (wto, wfrom, size * sizeof (wchar_t));
          }

     This function is a GNU extension.

 - Function: void * memmove (void *TO, const void *FROM, size_t SIZE)
     `memmove' copies the SIZE bytes at FROM into the SIZE bytes at TO,
     even if those two blocks of space overlap.  In the case of
     overlap, `memmove' is careful to copy the original values of the
     bytes in the block at FROM, including those bytes which also
     belong to the block at TO.

     The value returned by `memmove' is the value of TO.

 - Function: wchar_t * wmemmove (wchar *WTO, const wchar_t *WFROM,
          size_t SIZE)
     `wmemmove' copies the SIZE wide characters at WFROM into the SIZE
     wide characters at WTO, even if those two blocks of space overlap.
     In the case of overlap, `memmove' is careful to copy the original
     values of the wide characters in the block at WFROM, including
     those wide characters which also belong to the block at WTO.

     The following is a possible implementation of `wmemcpy' but there
     are more optimizations possible.

          wchar_t *
          wmempcpy (wchar_t *restrict wto, const wchar_t *restrict wfrom,
                    size_t size)
          {
            return (wchar_t *) mempcpy (wto, wfrom, size * sizeof (wchar_t));
          }

     The value returned by `wmemmove' is the value of WTO.

     This function is a GNU extension.

 - Function: void * memccpy (void *restrict TO, const void *restrict
          FROM, int C, size_t SIZE)
     This function copies no more than SIZE bytes from FROM to TO,
     stopping if a byte matching C is found.  The return value is a
     pointer into TO one byte past where C was copied, or a null
     pointer if no byte matching C appeared in the first SIZE bytes of
     FROM.

 - Function: void * memset (void *BLOCK, int C, size_t SIZE)
     This function copies the value of C (converted to an `unsigned
     char') into each of the first SIZE bytes of the object beginning
     at BLOCK.  It returns the value of BLOCK.

 - Function: wchar_t * wmemset (wchar_t *BLOCK, wchar_t WC, size_t SIZE)
     This function copies the value of WC into each of the first SIZE
     wide characters of the object beginning at BLOCK.  It returns the
     value of BLOCK.

 - Function: char * strcpy (char *restrict TO, const char *restrict
          FROM)
     This copies characters from the string FROM (up to and including
     the terminating null character) into the string TO.  Like
     `memcpy', this function has undefined results if the strings
     overlap.  The return value is the value of TO.

 - Function: wchar_t * wcscpy (wchar_t *restrict WTO, const wchar_t
          *restrict WFROM)
     This copies wide characters from the string WFROM (up to and
     including the terminating null wide character) into the string
     WTO.  Like `wmemcpy', this function has undefined results if the
     strings overlap.  The return value is the value of WTO.

 - Function: char * strncpy (char *restrict TO, const char *restrict
          FROM, size_t SIZE)
     This function is similar to `strcpy' but always copies exactly
     SIZE characters into TO.

     If the length of FROM is more than SIZE, then `strncpy' copies
     just the first SIZE characters.  Note that in this case there is
     no null terminator written into TO.

     If the length of FROM is less than SIZE, then `strncpy' copies all
     of FROM, followed by enough null characters to add up to SIZE
     characters in all.  This behavior is rarely useful, but it is
     specified by the ISO C standard.

     The behavior of `strncpy' is undefined if the strings overlap.

     Using `strncpy' as opposed to `strcpy' is a way to avoid bugs
     relating to writing past the end of the allocated space for TO.
     However, it can also make your program much slower in one common
     case: copying a string which is probably small into a potentially
     large buffer.  In this case, SIZE may be large, and when it is,
     `strncpy' will waste a considerable amount of time copying null
     characters.

 - Function: wchar_t * wcsncpy (wchar_t *restrict WTO, const wchar_t
          *restrict WFROM, size_t SIZE)
     This function is similar to `wcscpy' but always copies exactly
     SIZE wide characters into WTO.

     If the length of WFROM is more than SIZE, then `wcsncpy' copies
     just the first SIZE wide characters.  Note that in this case there
     is no null terminator written into WTO.

     If the length of WFROM is less than SIZE, then `wcsncpy' copies
     all of WFROM, followed by enough null wide characters to add up to
     SIZE wide characters in all.  This behavior is rarely useful, but
     it is specified by the ISO C standard.

     The behavior of `wcsncpy' is undefined if the strings overlap.

     Using `wcsncpy' as opposed to `wcscpy' is a way to avoid bugs
     relating to writing past the end of the allocated space for WTO.
     However, it can also make your program much slower in one common
     case: copying a string which is probably small into a potentially
     large buffer.  In this case, SIZE may be large, and when it is,
     `wcsncpy' will waste a considerable amount of time copying null
     wide characters.

 - Function: char * strdup (const char *S)
     This function copies the null-terminated string S into a newly
     allocated string.  The string is allocated using `malloc'; see
     *Note Unconstrained Allocation::.  If `malloc' cannot allocate
     space for the new string, `strdup' returns a null pointer.
     Otherwise it returns a pointer to the new string.

 - Function: wchar_t * wcsdup (const wchar_t *WS)
     This function copies the null-terminated wide character string WS
     into a newly allocated string.  The string is allocated using
     `malloc'; see *Note Unconstrained Allocation::.  If `malloc'
     cannot allocate space for the new string, `wcsdup' returns a null
     pointer.  Otherwise it returns a pointer to the new wide character
     string.

     This function is a GNU extension.

 - Function: char * strndup (const char *S, size_t SIZE)
     This function is similar to `strdup' but always copies at most
     SIZE characters into the newly allocated string.

     If the length of S is more than SIZE, then `strndup' copies just
     the first SIZE characters and adds a closing null terminator.
     Otherwise all characters are copied and the string is terminated.

     This function is different to `strncpy' in that it always
     terminates the destination string.

     `strndup' is a GNU extension.

 - Function: char * stpcpy (char *restrict TO, const char *restrict
          FROM)
     This function is like `strcpy', except that it returns a pointer to
     the end of the string TO (that is, the address of the terminating
     null character `to + strlen (from)') rather than the beginning.

     For example, this program uses `stpcpy' to concatenate `foo' and
     `bar' to produce `foobar', which it then prints.

          #include <string.h>
          #include <stdio.h>
          
          int
          main (void)
          {
            char buffer[10];
            char *to = buffer;
            to = stpcpy (to, "foo");
            to = stpcpy (to, "bar");
            puts (buffer);
            return 0;
          }

     This function is not part of the ISO or POSIX standards, and is not
     customary on Unix systems, but we did not invent it either.
     Perhaps it comes from MS-DOG.

     Its behavior is undefined if the strings overlap.  The function is
     declared in `string.h'.

 - Function: wchar_t * wcpcpy (wchar_t *restrict WTO, const wchar_t
          *restrict WFROM)
     This function is like `wcscpy', except that it returns a pointer to
     the end of the string WTO (that is, the address of the terminating
     null character `wto + strlen (wfrom)') rather than the beginning.

     This function is not part of ISO or POSIX but was found useful
     while developing the GNU C Library itself.

     The behavior of `wcpcpy' is undefined if the strings overlap.

     `wcpcpy' is a GNU extension and is declared in `wchar.h'.

 - Function: char * stpncpy (char *restrict TO, const char *restrict
          FROM, size_t SIZE)
     This function is similar to `stpcpy' but copies always exactly
     SIZE characters into TO.

     If the length of FROM is more then SIZE, then `stpncpy' copies
     just the first SIZE characters and returns a pointer to the
     character directly following the one which was copied last.  Note
     that in this case there is no null terminator written into TO.

     If the length of FROM is less than SIZE, then `stpncpy' copies all
     of FROM, followed by enough null characters to add up to SIZE
     characters in all.  This behavior is rarely useful, but it is
     implemented to be useful in contexts where this behavior of the
     `strncpy' is used.  `stpncpy' returns a pointer to the _first_
     written null character.

     This function is not part of ISO or POSIX but was found useful
     while developing the GNU C Library itself.

     Its behavior is undefined if the strings overlap.  The function is
     declared in `string.h'.

 - Function: wchar_t * wcpncpy (wchar_t *restrict WTO, const wchar_t
          *restrict WFROM, size_t SIZE)
     This function is similar to `wcpcpy' but copies always exactly
     WSIZE characters into WTO.

     If the length of WFROM is more then SIZE, then `wcpncpy' copies
     just the first SIZE wide characters and returns a pointer to the
     wide character directly following the one which was copied last.
     Note that in this case there is no null terminator written into
     WTO.

     If the length of WFROM is less than SIZE, then `wcpncpy' copies
     all of WFROM, followed by enough null characters to add up to SIZE
     characters in all.  This behavior is rarely useful, but it is
     implemented to be useful in contexts where this behavior of the
     `wcsncpy' is used.  `wcpncpy' returns a pointer to the _first_
     written null character.

     This function is not part of ISO or POSIX but was found useful
     while developing the GNU C Library itself.

     Its behavior is undefined if the strings overlap.

     `wcpncpy' is a GNU extension and is declared in `wchar.h'.

 - Macro: char * strdupa (const char *S)
     This macro is similar to `strdup' but allocates the new string
     using `alloca' instead of `malloc' (*note Variable Size
     Automatic::).  This means of course the returned string has the
     same limitations as any block of memory allocated using `alloca'.

     For obvious reasons `strdupa' is implemented only as a macro; you
     cannot get the address of this function.  Despite this limitation
     it is a useful function.  The following code shows a situation
     where using `malloc' would be a lot more expensive.

          #include <paths.h>
          #include <string.h>
          #include <stdio.h>
          
          const char path[] = _PATH_STDPATH;
          
          int
          main (void)
          {
            char *wr_path = strdupa (path);
            char *cp = strtok (wr_path, ":");
          
            while (cp != NULL)
              {
                puts (cp);
                cp = strtok (NULL, ":");
              }
            return 0;
          }

     Please note that calling `strtok' using PATH directly is invalid.
     It is also not allowed to call `strdupa' in the argument list of
     `strtok' since `strdupa' uses `alloca' (*note Variable Size
     Automatic::) can interfere with the parameter passing.

     This function is only available if GNU CC is used.

 - Macro: char * strndupa (const char *S, size_t SIZE)
     This function is similar to `strndup' but like `strdupa' it
     allocates the new string using `alloca' *note Variable Size
     Automatic::.  The same advantages and limitations of `strdupa' are
     valid for `strndupa', too.

     This function is implemented only as a macro, just like `strdupa'.
     Just as `strdupa' this macro also must not be used inside the
     parameter list in a function call.

     `strndupa' is only available if GNU CC is used.

 - Function: char * strcat (char *restrict TO, const char *restrict
          FROM)
     The `strcat' function is similar to `strcpy', except that the
     characters from FROM are concatenated or appended to the end of
     TO, instead of overwriting it.  That is, the first character from
     FROM overwrites the null character marking the end of TO.

     An equivalent definition for `strcat' would be:

          char *
          strcat (char *restrict to, const char *restrict from)
          {
            strcpy (to + strlen (to), from);
            return to;
          }

     This function has undefined results if the strings overlap.

 - Function: wchar_t * wcscat (wchar_t *restrict WTO, const wchar_t
          *restrict WFROM)
     The `wcscat' function is similar to `wcscpy', except that the
     characters from WFROM are concatenated or appended to the end of
     WTO, instead of overwriting it.  That is, the first character from
     WFROM overwrites the null character marking the end of WTO.

     An equivalent definition for `wcscat' would be:

          wchar_t *
          wcscat (wchar_t *wto, const wchar_t *wfrom)
          {
            wcscpy (wto + wcslen (wto), wfrom);
            return wto;
          }

     This function has undefined results if the strings overlap.

   Programmers using the `strcat' or `wcscat' function (or the
following `strncat' or `wcsncar' functions for that matter) can easily
be recognized as lazy and reckless.  In almost all situations the
lengths of the participating strings are known (it better should be
since how can one otherwise ensure the allocated size of the buffer is
sufficient?)  Or at least, one could know them if one keeps track of the
results of the various function calls.  But then it is very inefficient
to use `strcat'/`wcscat'.  A lot of time is wasted finding the end of
the destination string so that the actual copying can start.  This is a
common example:

     /* This function concatenates arbitrarily many strings.  The last
        parameter must be `NULL'.  */
     char *
     concat (const char *str, ...)
     {
       va_list ap, ap2;
       size_t total = 1;
       const char *s;
       char *result;
     
       va_start (ap, str);
       /* Actually `va_copy', but this is the name more gcc versions
          understand.  */
       __va_copy (ap2, ap);
     
       /* Determine how much space we need.  */
       for (s = str; s != NULL; s = va_arg (ap, const char *))
         total += strlen (s);
     
       va_end (ap);
     
       result = (char *) malloc (total);
       if (result != NULL)
         {
           result[0] = '\0';
     
           /* Copy the strings.  */
           for (s = str; s != NULL; s = va_arg (ap2, const char *))
             strcat (result, s);
         }
     
       va_end (ap2);
     
       return result;
     }

   This looks quite simple, especially the second loop where the strings
are actually copied.  But these innocent lines hide a major performance
penalty.  Just imagine that ten strings of 100 bytes each have to be
concatenated.  For the second string we search the already stored 100
bytes for the end of the string so that we can append the next string.
For all strings in total the comparisons necessary to find the end of
the intermediate results sums up to 5500!  If we combine the copying
with the search for the allocation we can write this function more
efficient:

     char *
     concat (const char *str, ...)
     {
       va_list ap;
       size_t allocated = 100;
       char *result = (char *) malloc (allocated);
       char *wp;
     
       if (allocated != NULL)
         {
           char *newp;
     
           va_start (ap, atr);
     
           wp = result;
           for (s = str; s != NULL; s = va_arg (ap, const char *))
             {
               size_t len = strlen (s);
     
               /* Resize the allocated memory if necessary.  */
               if (wp + len + 1 > result + allocated)
                 {
                   allocated = (allocated + len) * 2;
                   newp = (char *) realloc (result, allocated);
                   if (newp == NULL)
                     {
                       free (result);
                       return NULL;
                     }
                   wp = newp + (wp - result);
                   result = newp;
                 }
     
               wp = mempcpy (wp, s, len);
             }
     
           /* Terminate the result string.  */
           *wp++ = '\0';
     
           /* Resize memory to the optimal size.  */
           newp = realloc (result, wp - result);
           if (newp != NULL)
             result = newp;
     
           va_end (ap);
         }
     
       return result;
     }

   With a bit more knowledge about the input strings one could fine-tune
the memory allocation.  The difference we are pointing to here is that
we don't use `strcat' anymore.  We always keep track of the length of
the current intermediate result so we can safe us the search for the
end of the string and use `mempcpy'.  Please note that we also don't
use `stpcpy' which might seem more natural since we handle with
strings.  But this is not necessary since we already know the length of
the string and therefore can use the faster memory copying function.
The example would work for wide characters the same way.

   Whenever a programmer feels the need to use `strcat' she or he
should think twice and look through the program whether the code cannot
be rewritten to take advantage of already calculated results.  Again: it
is almost always unnecessary to use `strcat'.

 - Function: char * strncat (char *restrict TO, const char *restrict
          FROM, size_t SIZE)
     This function is like `strcat' except that not more than SIZE
     characters from FROM are appended to the end of TO.  A single null
     character is also always appended to TO, so the total allocated
     size of TO must be at least `SIZE + 1' bytes longer than its
     initial length.

     The `strncat' function could be implemented like this:

          char *
          strncat (char *to, const char *from, size_t size)
          {
            to[strlen (to) + size] = '\0';
            strncpy (to + strlen (to), from, size);
            return to;
          }

     The behavior of `strncat' is undefined if the strings overlap.

 - Function: wchar_t * wcsncat (wchar_t *restrict WTO, const wchar_t
          *restrict WFROM, size_t SIZE)
     This function is like `wcscat' except that not more than SIZE
     characters from FROM are appended to the end of TO.  A single null
     character is also always appended to TO, so the total allocated
     size of TO must be at least `SIZE + 1' bytes longer than its
     initial length.

     The `wcsncat' function could be implemented like this:

          wchar_t *
          wcsncat (wchar_t *restrict wto, const wchar_t *restrict wfrom,
                   size_t size)
          {
            wto[wcslen (to) + size] = L'\0';
            wcsncpy (wto + wcslen (wto), wfrom, size);
            return wto;
          }

     The behavior of `wcsncat' is undefined if the strings overlap.

   Here is an example showing the use of `strncpy' and `strncat' (the
wide character version is equivalent).  Notice how, in the call to
`strncat', the SIZE parameter is computed to avoid overflowing the
character array `buffer'.

     #include <string.h>
     #include <stdio.h>
     
     #define SIZE 10
     
     static char buffer[SIZE];
     
     main ()
     {
       strncpy (buffer, "hello", SIZE);
       puts (buffer);
       strncat (buffer, ", world", SIZE - strlen (buffer) - 1);
       puts (buffer);
     }

The output produced by this program looks like:

     hello
     hello, wo

 - Function: void bcopy (const void *FROM, void *TO, size_t SIZE)
     This is a partially obsolete alternative for `memmove', derived
     from BSD.  Note that it is not quite equivalent to `memmove',
     because the arguments are not in the same order and there is no
     return value.

 - Function: void bzero (void *BLOCK, size_t SIZE)
     This is a partially obsolete alternative for `memset', derived from
     BSD.  Note that it is not as general as `memset', because the only
     value it can store is zero.


File: libc.info,  Node: String/Array Comparison,  Next: Collation Functions,  Prev: Copying and Concatenation,  Up: String and Array Utilities

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.  *Note 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'.

 - Function: int wmemcmp (const wchar_t *A1, const wchar_t *A2, size_t
          SIZE)
     The function `wmemcmp' compares the SIZE wide characters beginning
     at A1 against the SIZE wide characters beginning at A2.  The value
     returned is smaller than or larger than zero depending on whether
     the first differing wide character is A1 is smaller or larger than
     the corresponding character in A2.

     If the contents of the two blocks are equal, `wmemcmp' 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.

   `wmemcmp' is really only useful to compare arrays of type `wchar_t'
since the function looks at `sizeof (wchar_t)' bytes at a time and this
number of bytes is system dependent.

   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.

     `strcmp' does not take sorting conventions of the language the
     strings are written in into account.  To get that one has to use
     `strcoll'.

 - Function: int wcscmp (const wchar_t *WS1, const wchar_t *WS2)
     The `wcscmp' function compares the wide character string WS1
     against WS2.  The value returned is smaller than or larger than
     zero depending on whether the first differing wide character is
     WS1 is smaller or larger than the corresponding character in WS2.

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

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

     `wcscmp' does not take sorting conventions of the language the
     strings are written in into account.  To get that one has to use
     `wcscoll'.

 - 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 wcscasecmp (const wchar_t *WS1, const wchar_T *WS2)
     This function is like `wcscmp', 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.

     `wcscasecmp' 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 wide characters are compared.  In other words, if the two
     strings are the same in their first SIZE wide characters, the
     return value is zero.

 - Function: int wcsncmp (const wchar_t *WS1, const wchar_t *WS2,
          size_t SIZE)
     This function is the similar to `wcscmp', except that no more than
     SIZE wide characters are compared.  In other words, if the two
     strings are the same in their first SIZE wide characters, the
     return value is zero.

 - 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 wcsncasecmp (const wchar_t *WS1, const wchar_t *S2,
          size_t N)
     This function is like `wcsncmp', except that differences in case
     are ignored.  Like `wcscasecmp', it is locale dependent how
     uppercase and lowercase characters are related.

     `wcsncasecmp' is a GNU extension.

   Here are some examples showing the use of `strcmp' and `strncmp'
(equivalent examples can be constructed for the wide character
functions).  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 behavior 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.

