The GNU C Library - Copying and Concatenation

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. These functions are declared in the header file `string.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).

Function void * memcpy (void *to, const void *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 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.

Function void * memccpy (void *to, const void *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 char * strcpy (char *to, const char *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 char * strncpy (char *to, const char *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 ANSI 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 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 char * stpcpy (char *to, const char *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) 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 ANSI 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.

Function char * strcat (char *to, const char *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 *to, const char *from)
	{
	  strcpy (to + strlen (to), from);
	  return to;
	}

This function has undefined results if the strings overlap.

Function char * strncat (char *to, const char *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)
	{
	  strncpy (to + strlen (to), from, size);
	  return to;
	}

The behavior of strncat is undefined if the strings overlap.

Here is an example showing the use of strncpy and strncat . 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 (void *from, const 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.

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. Some machines have special instructions for zeroing memory, so bzero might be more efficient than memset .