strcat, strncat, strlcat, strcpy, strncpy, strlcpy, stpcpy, stpncpy, strcpy_s, strncpy_s, strcat_s, strncat_s - string copying and concatenation operations
#include <string.h> char *strcat(char *restrict s1, const char *restrict s2);
char *strncat(char *restrict s1, const char *restrict s2, size_t n);
size_t strlcat(char *dst, const char *src, size_t dstsize);
char *strcpy(char *restrict s1, const char *restrict s2);
char *strncpy(char *restrict s1, const char *restrict s2, size_t n);
size_t strlcpy(char *dst, const char *src, size_t dstsize);
char *stpcpy(char *restrict s1, const char *restrict s2);
char *stpncpy(char *restrict s1, const char *restrict s2, size_t n);
#define __STDC_WANT_LIB_EXT1__ 1 #include <string.h> errno_t strcpy_s(char *restrict s1, rsize_t s1max, const char *restrict s2);
errno_t strncpy_s(char *restrict s1, rsize_t s1max, const char *restrict s2, rsize_t n);
errno_t strcat_s(char *restrict s1, rsize_t s1max, const char *restrict s2);
errno_t strncat_s(char *restrict s1, rsize_t s1max, const char *restrict s2, rsize_t n);
These functions copy data from one string (array of characters) to another. Depending on the function, strings may be either terminated by a null character or consist of a length of n bytes. All character counts are measured in individual bytes, even if a string with multibyte characters is used, which may result in copying only part of a multibyte character if the full character does not fit within the byte count specified. They do not check for null pointers, and programs may crash if passing null or otherwise invalid pointers to these functions, or specifying sizes larger than the memory allocation in use for the string. Use of adi(7) may help in detecting buffer overflows or invalid pointer usage in code.
The strcat(), stpcpy(), and strcpy() functions do not check for overflow of the array. Use of one of the bounds-checking variants is recommended instead of those functions.
The strcat() function appends a copy of string s2, including the terminating null character, to the end of string s1. The strncat() function appends at most n bytes. Each returns a pointer to the null-terminated result. The initial character of s2 is written over the null character at the end of s1. If copying takes place between objects that overlap, the behavior of strcat(), strncat(), and strlcat() is undefined.
The strlcat() function appends at most (dstsize-strlen(dst)-1) characters of src to dst (dstsize being the size of the string buffer dst). If the string pointed to by dst contains a null-terminated string that fits into dstsize bytes when strlcat() is called, the string pointed to by dst will be a null-terminated string that fits in dstsize bytes (including the terminating null character) when it completes, and the initial character of src will override the null character at the end of dst. If the string pointed to by dst is longer than dstsize bytes when strlcat() is called, the string pointed to by dst will not be changed. The function returns min{dstsize, strlen(dst)} + strlen(src). Insufficient space can be checked for as follows:
if (strlcat(dst, src, dstsize) >= dstsize) return −1;
The strcpy() and stpcpy() functions copy string s2 to s1, including the terminating null character, stopping after the null character has been copied. The strcpy() function returns s1. The stpcpy() function returns a pointer to the terminating null character copied into the s1 array.
The strncpy() and stpncpy() functions copy not more than n bytes (bytes that follow a null byte are not copied) from the array pointed to by s2 to the array pointed to by s1. If the array pointed to by s2 is a string that is shorter than n bytes, null bytes are appended to the copy in the array pointed to by s1, until n bytes in all are written. If the array pointed to by s2 is a string that is n bytes or longer, the resulting s1 will not be null terminated. The strncpy() function returns s1. If s1 contains null bytes, stpncpy() returns a pointer to the first such null byte. Otherwise, it returns &s1[n].
The strlcpy() function copies at most dstsize−1 characters (dstsize being the size of the string buffer dst) from src to dst, truncating src if necessary. The result is always null-terminated. The function returns strlen(src). Insufficient space can be checked for as follows:
if (strlcpy(dst, src, dstsize) >= dstsize) return −1;
If copying takes place between objects that overlap, the behavior of these functions is undefined.
The strcpy_s(), strncpy_s(), strcat_s(), strncat_s(), and strlen_s() functions are part of the C11 bounds checking interfaces specified in the C11 standard, Annex K. Each of these functions provides similar functionality to their respective non-bounds checking counterpart functions, but with additional safety checks in the form of explicit runtime constraints as defined in the C11 standard. See runtime_constraint_handler(3C) and INCITS/ISO/IEC 9899:2011.
If no runtime constraint violation is detected, the strcpy_s(), strncpy_s(), strcat_s() and strncat_s() functions return zero. If a runtime constraint violation is detected and the handler returns, they return a non-zero value.
The C11 bounds checking interface functions will fail if:
Null pointer is passed or source and destination overlap
A size argument is not a valid value
Destination array is too small
The other functions described in this page do not check if a null pointer is passed, and programs passing null pointers to them may crash.
Usage of the strlcat() and strlcpy() functions is recommended over the other variants to avoid buffer overflows and make code easier to review and maintain.
It is not possible to limit the strcat() and strcpy() functions to a maximum buffer size. Although one can calculate the amount of space needed before calling strcat or strcpy, the use of these functions will always force reviewers to follow the logic, and hinder automated scanning of source code for vulnerabilities.
strncpy() is not guaranteed to null-terminate the destination buffer. This fact, together with the side effect that it will add null bytes if there is space left make it a useful function for updating fixed-length structures that reside on disk, for example, wtmpx(5).
strncat() is hard to use safely as it requires the remaining size of the destination buffer to be calculated by the caller.
See attributes(7) for descriptions of the following attributes:
|
The strcat(), strncat(), strlcat(), strcpy(), strncpy(), strlcpy(), stpcpy(), and stpncpy() functions are Async-Signal-Safe.
The strcpy_s(), strncpy_s(), strcat_s(), and strncat_s() functions cannot be used safely in a multithreaded application due to the runtime constraint handler. For more information, see the runtime_constraint_handler(3C) man page.
See standards(7) for descriptions of the following standards:
|
strdup(3C), string(3C), wcscat(3C), wcscpy(3C), attributes(7), standards(7), runtime_constraint_handler(3C)
Support for the following functions is available in Oracle Solaris starting with the listed release:
|