@node String and Array Utilities, Character Set Handling, Character Handling, Top

@c %MENU% Utilities for copying and comparing strings and arrays

@chapter String and Array Utilities

Operations on strings (null-terminated byte sequences) are an important part of

many programs.  @Theglibc{} provides an extensive set of string

utility functions, including functions for copying, concatenating,

comparing, and searching strings.  Many of these functions can also

operate on arbitrary regions of storage; for example, the @code{memcpy}

function can be used to copy the contents of any kind of array.

It's fairly common for beginning C programmers to ``reinvent the wheel''

by duplicating this functionality in their own code, but it pays to

become familiar with the library functions and to make use of them,

since this offers benefits in maintenance, efficiency, and portability.

For instance, you could easily compare one string to another in two

lines of C code, but if you use the built-in @code{strcmp} function,

you're less likely to make a mistake.  And, since these library

functions are typically highly optimized, your program may run faster

too.

@menu

* Representation of Strings::   Introduction to basic concepts.

* String/Array Conventions::    Whether to use a string function or an

				 arbitrary array function.

* String Length::               Determining the length of a string.

* Copying Strings and Arrays::  Functions to copy strings and arrays.

* Concatenating Strings::       Functions to concatenate strings while copying.

* Truncating Strings::          Functions to truncate strings while copying.

* String/Array Comparison::     Functions for byte-wise and character-wise

				 comparison.

* Collation Functions::         Functions for collating strings.

* Search Functions::            Searching for a specific element or substring.

* Finding Tokens in a String::  Splitting a string into tokens by looking

				 for delimiters.

* Erasing Sensitive Data::      Clearing memory which contains sensitive

                                 data, after it's no longer needed.

* Shuffling Bytes::             Or how to flash-cook a string.

* Obfuscating Data::            Reversibly obscuring data from casual view.

* Encode Binary Data::          Encoding and Decoding of Binary Data.

* Argz and Envz Vectors::       Null-separated string vectors.

@end menu

@node Representation of Strings

@section Representation of Strings

@cindex string, representation of

This section is a quick summary of string concepts for beginning C

programmers.  It describes how strings are represented in C

and some common pitfalls.  If you are already familiar with this

material, you can skip this section.

@cindex string

A @dfn{string} is a null-terminated array of bytes of type @code{char},

including the terminating null byte.  String-valued

variables are usually declared to be pointers of type @code{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 (@pxref{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 @dfn{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.

@cindex multibyte character

@cindex multibyte string

@cindex wide string

A @dfn{multibyte character} is a sequence of one or more bytes that

represents a single character using the locale's encoding scheme; a

null byte always represents the null character.  A @dfn{multibyte

string} is a string that consists entirely of multibyte

characters.  In contrast, a @dfn{wide string} is a null-terminated

sequence of @code{wchar_t} objects.  A wide-string variable is usually

declared to be a pointer of type @code{wchar_t *}, by analogy with

string variables and @code{char *}.  @xref{Extended Char Intro}.

@cindex null byte

@cindex null wide character

By convention, the @dfn{null byte}, @code{'\0'},

marks the end of a string and the @dfn{null wide character},

@code{L'\0'}, marks the end of a wide string.  For example, in

testing to see whether the @code{char *} variable @var{p} points to a

null byte marking the end of a string, you can write

@code{!*@var{p}} or @code{*@var{p} == '\0'}.

A null byte is quite different conceptually from a null pointer,

although both are represented by the integer constant @code{0}.

@cindex string literal

A @dfn{string literal} appears in C program source as a multibyte

string between double-quote characters (@samp{"}).  If the

initial double-quote character is immediately preceded by a capital

@samp{L} (ell) character (as in @code{L"foo"}), it is a wide string

literal.  String literals can also contribute to @dfn{string

concatenation}: @code{"a" "b"} is the same as @code{"ab"}.

For wide strings one can use either

@code{L"a" L"b"} or @code{L"a" "b"}.  Modification of string literals is

not allowed by the GNU C compiler, because literals are placed in

read-only storage.

Arrays that are declared @code{const} cannot be modified

either.  It's generally good style to declare non-modifiable string

pointers to be of type @code{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 a byte array may extend past the null byte

that marks the end of the string that the array contains.  In this

document, the term @dfn{allocated size} is always used to refer to the

total amount of memory allocated for an array, while the term

@dfn{length} refers to the number of bytes up to (but not including)

the terminating null byte.  Wide strings are similar, except their

sizes and lengths count wide characters, not bytes.

@cindex length of string

@cindex allocation size of string

@cindex size of string

@cindex string length

@cindex string allocation

A notorious source of program bugs is trying to put more bytes into a

string than fit in its allocated size.  When writing code that extends

strings or moves bytes 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

@emph{do not} do this for you!  Remember also that you need to allocate

an extra byte to hold the null byte that marks the end of the

string.

@cindex single-byte string

@cindex multibyte string

Originally strings were sequences of bytes where each byte represented 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 @ref{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

@code{memcpy} could cut a multibyte character in the middle and put an

incomplete (and therefore unusable) byte sequence in the target buffer.

@cindex wide string

To avoid these problems later versions of the @w{ISO C} standard

introduce a second set of functions which are operating on @dfn{wide

characters} (@pxref{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

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 @w{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 more easily operate

on wide characters than on multibyte characters so that a common strategy

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 strings in parallel with the discussion of

strings since there is almost always an exact equivalent

available.

@node String/Array Conventions

@section String and Array Conventions

This chapter describes both functions that work on arbitrary arrays or

blocks of memory, and functions that are specific to strings and wide

strings.

Functions that operate on arbitrary blocks of memory have names

beginning with @samp{mem} and @samp{wmem} (such as @code{memcpy} and

@code{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 @code{void *} or @code{wchar_t}.  As a matter of style, the

elements of the arrays used with the @samp{mem} functions are referred

to as ``bytes''.  You can pass any kind of pointer to these functions,

and the @code{sizeof} operator is useful in computing the value for the

size argument.  Parameters to the @samp{wmem} functions must be of type

@code{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

strings have names beginning with @samp{str} and @samp{wcs}

respectively (such as @code{strcpy} and @code{wcscpy}) and look for a

terminating null byte or null wide character 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.)

The array arguments and return values for these

functions have type @code{char *} and @code{wchar_t *} respectively, and

the array elements are referred to as ``bytes'' and ``wide

characters''.

In many cases, there are both @samp{mem} and @samp{str}/@samp{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 @samp{mem}

functions.  On the other hand, when you are manipulating

strings it is usually more convenient to use the @samp{str}/@samp{wcs}

functions, unless you already know the length of the string in advance.

The @samp{wmem} functions should be used for wide character arrays with

known size.

@cindex wint_t

@cindex parameter promotion

Some of the memory and string functions take single characters as

arguments.  Since a value of type @code{char} is automatically promoted

into a value of type @code{int} when used as a parameter, the functions

are declared with @code{int} as the type of the parameter in question.

In case of the wide character functions the situation is similar: the

parameter type for a single wide character is @code{wint_t} and not

@code{wchar_t}.  This would for many implementations not be necessary

since @code{wchar_t} is large enough to not be automatically

promoted, but since the @w{ISO C} standard does not require such a

choice of types the @code{wint_t} type is used.

@node String Length

@section String Length

You can get the length of a string using the @code{strlen} function.

This function is declared in the header file @file{string.h}.

@pindex string.h

@deftypefun size_t strlen (const char *@var{s})

@standards{ISO, string.h}

@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}

The @code{strlen} function returns the length of the

string @var{s} in bytes.  (In other words, it returns the offset of the

terminating null byte within the array.)

For example,

@smallexample

strlen ("hello, world")

    @result{} 12

@end smallexample

When applied to an array, the @code{strlen} function returns

the length of the string stored there, not its allocated size.  You can

get the allocated size of the array that holds a string using

the @code{sizeof} operator:

@smallexample

char string[32] = "hello, world";

sizeof (string)

    @result{} 32

strlen (string)

    @result{} 12

@end smallexample

But beware, this will not work unless @var{string} is the

array itself, not a pointer to it.  For example:

@smallexample

char string[32] = "hello, world";

char *ptr = string;

sizeof (string)

    @result{} 32

sizeof (ptr)

    @result{} 4  /* @r{(on a machine with 4 byte pointers)} */

@end smallexample

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 @code{wcslen} can be used or something like the following

code can be used:

@smallexample

/* @r{The input is in @code{string}.}

   @r{The length is expected in @code{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);

@}

@end smallexample

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.

@end deftypefun

The wide character equivalent is declared in @file{wchar.h}.

@deftypefun size_t wcslen (const wchar_t *@var{ws})

@standards{ISO, wchar.h}

@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}

The @code{wcslen} function is the wide character equivalent to

@code{strlen}.  The return value is the number of wide characters in the

wide string pointed to by @var{ws} (this is also the offset of

the terminating null wide character of @var{ws}).

Since there are no multi wide character sequences making up one wide

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 @w{Amendment 1} to @w{ISO C90}.

@end deftypefun

@deftypefun size_t strnlen (const char *@var{s}, size_t @var{maxlen})

@standards{GNU, string.h}

@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}

If the array @var{s} of size @var{maxlen} contains a null byte,

the @code{strnlen} function returns the length of the string @var{s} in

bytes.  Otherwise it

returns @var{maxlen}.  Therefore this function is equivalent to

@code{(strlen (@var{s}) < @var{maxlen} ? strlen (@var{s}) : @var{maxlen})}

but it

is more efficient and works even if @var{s} is not null-terminated so

long as @var{maxlen} does not exceed the size of @var{s}'s array.

@smallexample

char string[32] = "hello, world";

strnlen (string, 32)

    @result{} 12

strnlen (string, 5)

    @result{} 5

@end smallexample

This function is a GNU extension and is declared in @file{string.h}.

@end deftypefun

@deftypefun size_t wcsnlen (const wchar_t *@var{ws}, size_t @var{maxlen})

@standards{GNU, wchar.h}

@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}

@code{wcsnlen} is the wide character equivalent to @code{strnlen}.  The

@var{maxlen} parameter specifies the maximum number of wide characters.

This function is a GNU extension and is declared in @file{wchar.h}.

@end deftypefun

@node Copying Strings and Arrays

@section Copying Strings and Arrays

You can use the functions described in this section to copy the contents

of strings, wide strings, and arrays.  The @samp{str} and @samp{mem}

functions are declared in @file{string.h} while the @samp{w} functions

are declared in @file{wchar.h}.

@pindex string.h

@pindex wchar.h

@cindex copying strings and arrays

@cindex string copy functions

@cindex array copy functions

@cindex concatenating strings

@cindex string concatenation functions

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

of these functions return the address of the destination array; a few

return the address of the destination's terminating null, or of just

past the destination.

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

byte 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 @code{sprintf} (@pxref{Formatted

Output Functions}) and @code{scanf} (@pxref{Formatted Input

Functions}).

@deftypefun {void *} memcpy (void *restrict @var{to}, const void *restrict @var{from}, size_t @var{size})

@standards{ISO, string.h}

@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}

The @code{memcpy} function copies @var{size} bytes from the object

beginning at @var{from} into the object beginning at @var{to}.  The

behavior of this function is undefined if the two arrays @var{to} and

@var{from} overlap; use @code{memmove} instead if overlapping is possible.

The value returned by @code{memcpy} is the value of @var{to}.

Here is an example of how you might use @code{memcpy} to copy the

contents of an array:

@smallexample

struct foo *oldarray, *newarray;

int arraysize;

@dots{}

memcpy (new, old, arraysize * sizeof (struct foo));

@end smallexample

@end deftypefun

@deftypefun {wchar_t *} wmemcpy (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom}, size_t @var{size})

@standards{ISO, wchar.h}

@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}

The @code{wmemcpy} function copies @var{size} wide characters from the object

beginning at @var{wfrom} into the object beginning at @var{wto}.  The

behavior of this function is undefined if the two arrays @var{wto} and

@var{wfrom} overlap; use @code{wmemmove} instead if overlapping is possible.

The following is a possible implementation of @code{wmemcpy} but there

are more optimizations possible.

@smallexample

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));

@}

@end smallexample

The value returned by @code{wmemcpy} is the value of @var{wto}.

This function was introduced in @w{Amendment 1} to @w{ISO C90}.

@end deftypefun

@deftypefun {void *} mempcpy (void *restrict @var{to}, const void *restrict @var{from}, size_t @var{size})

@standards{GNU, string.h}

@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}

The @code{mempcpy} function is nearly identical to the @code{memcpy}

function.  It copies @var{size} bytes from the object beginning at

@code{from} into the object pointed to by @var{to}.  But instead of

returning the value of @var{to} it returns a pointer to the byte

following the last written byte in the object beginning at @var{to}.

I.e., the value is @code{((void *) ((char *) @var{to} + @var{size}))}.

This function is useful in situations where a number of objects shall be

copied to consecutive memory positions.

@smallexample

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;

@}

@end smallexample

This function is a GNU extension.

@end deftypefun

@deftypefun {wchar_t *} wmempcpy (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom}, size_t @var{size})

@standards{GNU, wchar.h}

@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}

The @code{wmempcpy} function is nearly identical to the @code{wmemcpy}

function.  It copies @var{size} wide characters from the object

beginning at @code{wfrom} into the object pointed to by @var{wto}.  But

instead of returning the value of @var{wto} it returns a pointer to the

wide character following the last written wide character in the object

beginning at @var{wto}.  I.e., the value is @code{@var{wto} + @var{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 @code{wmemcpy} but there

are more optimizations possible.

@smallexample

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));

@}

@end smallexample

This function is a GNU extension.

@end deftypefun

@deftypefun {void *} memmove (void *@var{to}, const void *@var{from}, size_t @var{size})

@standards{ISO, string.h}

@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}

@code{memmove} copies the @var{size} bytes at @var{from} into the

@var{size} bytes at @var{to}, even if those two blocks of space

overlap.  In the case of overlap, @code{memmove} is careful to copy the

original values of the bytes in the block at @var{from}, including those

bytes which also belong to the block at @var{to}.

The value returned by @code{memmove} is the value of @var{to}.

@end deftypefun

@deftypefun {wchar_t *} wmemmove (wchar_t *@var{wto}, const wchar_t *@var{wfrom}, size_t @var{size})

@standards{ISO, wchar.h}

@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}

@code{wmemmove} copies the @var{size} wide characters at @var{wfrom}

into the @var{size} wide characters at @var{wto}, even if those two

blocks of space overlap.  In the case of overlap, @code{wmemmove} is

careful to copy the original values of the wide characters in the block

at @var{wfrom}, including those wide characters which also belong to the

block at @var{wto}.

The following is a possible implementation of @code{wmemcpy} but there

are more optimizations possible.

@smallexample

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));

@}

@end smallexample

The value returned by @code{wmemmove} is the value of @var{wto}.

This function is a GNU extension.

@end deftypefun

@deftypefun {void *} memccpy (void *restrict @var{to}, const void *restrict @var{from}, int @var{c}, size_t @var{size})

@standards{SVID, string.h}

@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}

This function copies no more than @var{size} bytes from @var{from} to

@var{to}, stopping if a byte matching @var{c} is found.  The return

value is a pointer into @var{to} one byte past where @var{c} was copied,

or a null pointer if no byte matching @var{c} appeared in the first

@var{size} bytes of @var{from}.

@end deftypefun

@deftypefun {void *} memset (void *@var{block}, int @var{c}, size_t @var{size})

@standards{ISO, string.h}

@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}

This function copies the value of @var{c} (converted to an

@code{unsigned char}) into each of the first @var{size} bytes of the

object beginning at @var{block}.  It returns the value of @var{block}.

@end deftypefun

@deftypefun {wchar_t *} wmemset (wchar_t *@var{block}, wchar_t @var{wc}, size_t @var{size})

@standards{ISO, wchar.h}

@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}

This function copies the value of @var{wc} into each of the first

@var{size} wide characters of the object beginning at @var{block}.  It

returns the value of @var{block}.

@end deftypefun

@deftypefun {char *} strcpy (char *restrict @var{to}, const char *restrict @var{from})

@standards{ISO, string.h}

@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}

This copies bytes from the string @var{from} (up to and including

the terminating null byte) into the string @var{to}.  Like

@code{memcpy}, this function has undefined results if the strings

overlap.  The return value is the value of @var{to}.

@end deftypefun

@deftypefun {wchar_t *} wcscpy (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom})

@standards{ISO, wchar.h}

@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}

This copies wide characters from the wide string @var{wfrom} (up to and

including the terminating null wide character) into the string

@var{wto}.  Like @code{wmemcpy}, this function has undefined results if

the strings overlap.  The return value is the value of @var{wto}.

@end deftypefun

@deftypefun {char *} strdup (const char *@var{s})

@standards{SVID, string.h}

@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}

This function copies the string @var{s} into a newly

allocated string.  The string is allocated using @code{malloc}; see

@ref{Unconstrained Allocation}.  If @code{malloc} cannot allocate space

for the new string, @code{strdup} returns a null pointer.  Otherwise it

returns a pointer to the new string.

@end deftypefun

@deftypefun {wchar_t *} wcsdup (const wchar_t *@var{ws})

@standards{GNU, wchar.h}

@safety{@prelim{}@mtsafe{}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}

This function copies the wide string @var{ws}

into a newly allocated string.  The string is allocated using

@code{malloc}; see @ref{Unconstrained Allocation}.  If @code{malloc}

cannot allocate space for the new string, @code{wcsdup} returns a null

pointer.  Otherwise it returns a pointer to the new wide string.

This function is a GNU extension.

@end deftypefun

@deftypefun {char *} stpcpy (char *restrict @var{to}, const char *restrict @var{from})

@standards{Unknown origin, string.h}

@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}

This function is like @code{strcpy}, except that it returns a pointer to

the end of the string @var{to} (that is, the address of the terminating

null byte @code{to + strlen (from)}) rather than the beginning.

For example, this program uses @code{stpcpy} to concatenate @samp{foo}

and @samp{bar} to produce @samp{foobar}, which it then prints.

@smallexample

@include stpcpy.c.texi

@end smallexample

This function is part of POSIX.1-2008 and later editions, but was

available in @theglibc{} and other systems as an extension long before

it was standardized.

Its behavior is undefined if the strings overlap.  The function is

declared in @file{string.h}.

@end deftypefun

@deftypefun {wchar_t *} wcpcpy (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom})

@standards{GNU, wchar.h}

@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}

This function is like @code{wcscpy}, except that it returns a pointer to

the end of the string @var{wto} (that is, the address of the terminating

null wide character @code{wto + wcslen (wfrom)}) rather than the beginning.

This function is not part of ISO or POSIX but was found useful while

developing @theglibc{} itself.

The behavior of @code{wcpcpy} is undefined if the strings overlap.

@code{wcpcpy} is a GNU extension and is declared in @file{wchar.h}.

@end deftypefun

@deftypefn {Macro} {char *} strdupa (const char *@var{s})

@standards{GNU, string.h}

@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}

This macro is similar to @code{strdup} but allocates the new string

using @code{alloca} instead of @code{malloc} (@pxref{Variable Size

Automatic}).  This means of course the returned string has the same

limitations as any block of memory allocated using @code{alloca}.

For obvious reasons @code{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 @code{malloc} would be a lot more expensive.

@smallexample

@include strdupa.c.texi

@end smallexample

Please note that calling @code{strtok} using @var{path} directly is

invalid.  It is also not allowed to call @code{strdupa} in the argument

list of @code{strtok} since @code{strdupa} uses @code{alloca}

(@pxref{Variable Size Automatic}) can interfere with the parameter

passing.

This function is only available if GNU CC is used.

@end deftypefn

@deftypefun void bcopy (const void *@var{from}, void *@var{to}, size_t @var{size})

@standards{BSD, string.h}

@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}

This is a partially obsolete alternative for @code{memmove}, derived from

BSD.  Note that it is not quite equivalent to @code{memmove}, because the

arguments are not in the same order and there is no return value.

@end deftypefun

@deftypefun void bzero (void *@var{block}, size_t @var{size})

@standards{BSD, string.h}

@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}

This is a partially obsolete alternative for @code{memset}, derived from

BSD.  Note that it is not as general as @code{memset}, because the only

value it can store is zero.

@end deftypefun

@node Concatenating Strings

@section Concatenating Strings

@pindex string.h

@pindex wchar.h

@cindex concatenating strings

@cindex string concatenation functions

The functions described in this section concatenate the contents of a

string or wide string to another.  They follow the string-copying

functions in their conventions.  @xref{Copying Strings and Arrays}.

@samp{strcat} is declared in the header file @file{string.h} while

@samp{wcscat} is declared in @file{wchar.h}.

@deftypefun {char *} strcat (char *restrict @var{to}, const char *restrict @var{from})

@standards{ISO, string.h}

@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}

The @code{strcat} function is similar to @code{strcpy}, except that the

bytes from @var{from} are concatenated or appended to the end of

@var{to}, instead of overwriting it.  That is, the first byte from

@var{from} overwrites the null byte marking the end of @var{to}.

An equivalent definition for @code{strcat} would be:

@smallexample

char *

strcat (char *restrict to, const char *restrict from)

@{

  strcpy (to + strlen (to), from);

  return to;

@}

@end smallexample

This function has undefined results if the strings overlap.

As noted below, this function has significant performance issues.

@end deftypefun

@deftypefun {wchar_t *} wcscat (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom})

@standards{ISO, wchar.h}

@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}

The @code{wcscat} function is similar to @code{wcscpy}, except that the

wide characters from @var{wfrom} are concatenated or appended to the end of

@var{wto}, instead of overwriting it.  That is, the first wide character from

@var{wfrom} overwrites the null wide character marking the end of @var{wto}.

An equivalent definition for @code{wcscat} would be:

@smallexample

wchar_t *

wcscat (wchar_t *wto, const wchar_t *wfrom)

@{

  wcscpy (wto + wcslen (wto), wfrom);

  return wto;

@}

@end smallexample

This function has undefined results if the strings overlap.

As noted below, this function has significant performance issues.

@end deftypefun

Programmers using the @code{strcat} or @code{wcscat} function (or the

@code{strncat} or @code{wcsncat} functions defined in

a later section, 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 @code{strcat}/@code{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:

@cindex va_copy

@smallexample

/* @r{This function concatenates arbitrarily many strings.  The last}

   @r{parameter must be @code{NULL}.}  */

char *

concat (const char *str, @dots{})

@{

  va_list ap, ap2;

  size_t total = 1;

  const char *s;

  char *result;

  va_start (ap, str);

  va_copy (ap2, ap);

  /* @r{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';

      /* @r{Copy the strings.}  */

      for (s = str; s != NULL; s = va_arg (ap2, const char *))

        strcat (result, s);

    @}

  va_end (ap2);

  return result;

@}

@end smallexample

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

efficiently:

@smallexample

char *

concat (const char *str, @dots{})

@{

  va_list ap;

  size_t allocated = 100;

  char *result = (char *) malloc (allocated);

  if (result != NULL)

    @{

      char *newp;

      char *wp;

      const char *s;

      va_start (ap, str);

      wp = result;

      for (s = str; s != NULL; s = va_arg (ap, const char *))

        @{

          size_t len = strlen (s);

          /* @r{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);

        @}

      /* @r{Terminate the result string.}  */

      *wp++ = '\0';

      /* @r{Resize memory to the optimal size.}  */

      newp = realloc (result, wp - result);

      if (newp != NULL)

        result = newp;

      va_end (ap);

    @}

  return result;

@}

@end smallexample

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 @code{strcat} anymore.  We always keep track of the length

of the current intermediate result so we can save ourselves the search for the

end of the string and use @code{mempcpy}.  Please note that we also

don't use @code{stpcpy} which might seem more natural since we are handling

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 @code{strcat} she or he

should think twice and look through the program to see whether the code cannot

be rewritten to take advantage of already calculated results.  Again: it

is almost always unnecessary to use @code{strcat}.

@node Truncating Strings

@section Truncating Strings while Copying

@cindex truncating strings

@cindex string truncation

The functions described in this section copy or concatenate the

possibly-truncated contents of a string or array to another, and

similarly for wide strings.  They follow the string-copying functions

in their header conventions.  @xref{Copying Strings and Arrays}.  The

@samp{str} functions are declared in the header file @file{string.h}

and the @samp{wc} functions are declared in the file @file{wchar.h}.

@deftypefun {char *} strncpy (char *restrict @var{to}, const char *restrict @var{from}, size_t @var{size})

@standards{C90, string.h}

@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}

This function is similar to @code{strcpy} but always copies exactly

@var{size} bytes into @var{to}.

If @var{from} does not contain a null byte in its first @var{size}

bytes, @code{strncpy} copies just the first @var{size} bytes.  In this

case no null terminator is written into @var{to}.

Otherwise @var{from} must be a string with length less than

@var{size}.  In this case @code{strncpy} copies all of @var{from},

followed by enough null bytes to add up to @var{size} bytes in all.

The behavior of @code{strncpy} is undefined if the strings overlap.