Go to main content

man pages section 3: Basic Library Functions

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

strcpy_s(3C)

Name

strcat, strncat, strlcat, strcpy, strncpy, strlcpy, stpcpy, stpncpy, strcpy_s, strncpy_s, strcat_s, strncat_s - string copying and concatenation operations

Synopsis

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

C11 Bounds Checking Interfaces

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

Description

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.

strcat(), strncat(), strlcat()

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;

strcpy(), stpcpy(), strncpy(), stpncpy(), strlcpy()

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.

C11 Bounds Checking Interfaces

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.

Errors

The C11 bounds checking interface functions will fail if:

EINVAL

Null pointer is passed or source and destination overlap

ERANGE

A size argument is not a valid value

EOVERFLOW

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

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.

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
MT-Level
See below
Standard
See below

MT-Level

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.

Standard

See standards(7) for descriptions of the following standards:

INTERFACES
APPLICABLE STANDARDS
strcat(), strcpy(), strncat(), strncpy()
  • C89 through C11,
  • POSIX.1-1990 through 2008,
  • SUS through SUSv4,
  • XPG1 through XPG7
stpcpy(), stpncpy()
  • POSIX.1-2008,
  • SUSv4,
  • XPG7
strcat_s(), strcpy_s(), strncat_s(), strncpy_s()
C11 Annex K
strlcat(), strlcpy()
None

See Also

strdup(3C), string(3C), wcscat(3C), wcscpy(3C), attributes(7), standards(7), runtime_constraint_handler(3C)

Appendix E, Security Considerations When Using C Functions, in Developer’s Guide to Oracle Solaris 11.4 Security

History

Support for the following functions is available in Oracle Solaris starting with the listed release:

FUNCTION
RELEASE
strcat_s(), strcpy_s(), strncat_s(), strncpy_s()
11.4.0
stpcpy(), stpncpy()
11.0.0
strlcat(), strlcpy()
8
strcat(), strcpy(), strncat(), strncpy()
1.0