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 (see Formatted Output Functions) and scanf (see Formatted Input Functions).
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:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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 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 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.
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.
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.
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.
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 (see 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.
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
(see Variable Size Automatic) can interfere with the parameter
passing.
This function is only available if GNU CC is used.
This function is similar to strndup but like strdupa it
allocates the new string using alloca
see 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.
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.
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.
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 lastparameter 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 versionsunderstand. */
__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.
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:
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:
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.
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.
Published under the terms of the GNU General Public License