NAME

strlcat, strlcpy — size-bounded string concatenation and copying

SYNOPSIS

[CX] #include <string.h>

size_t strlcat(char *restrict dst, const char *restrict src,
       size_t dstsize);
size_t strlcpy(char *restrict dst, const char *restrict src,
       size_t dstsize);

DESCRIPTION

The strlcpy() and strlcat() functions copy and concatenate strings, stopping when either a NUL terminator in the source string is encountered or the specified full size of the destination buffer is reached. They NUL terminate the result if there is room. The application should ensure that room for the NUL terminator is included in dstsize.

The strlcpy() function shall copy not more than dstsize - 1 bytes from the string pointed to by src to the array pointed to by dst; a NUL byte in src and bytes that follow it shall not be copied. A terminating NUL byte shall be appended to the result, unless dstsize is 0. If copying takes place between objects that overlap, the behavior is undefined.

The strlcat() function shall append not more than dstsize - strlen(dst) - 1 bytes from the string pointed to by src to the end of the string pointed to by dst; a NUL byte in src and bytes that follow it shall not be appended. The initial byte of src shall overwrite the NUL byte at the end of dst. A terminating NUL byte shall be appended to the result, unless its location would be at or beyond dst + dstsize. If copying takes place between objects that overlap, the behavior is undefined.

The strlcpy() and strlcat() functions shall not change the setting of errno on valid input.

RETURN VALUE

Upon successful completion, the strlcpy() function shall return the length of the string pointed to by src; that is, the number of bytes in the string, not including the terminating NUL byte.

Upon successful completion, the strlcat() function shall return the initial length of the string (if any) pointed to by dst, as limited by dstsize, plus the length of the string pointed to by src; that is, the value that would be returned by strnlen(dst, dstsize) + strlen(src) before the strlcat() call.

No return values are reserved to indicate an error.

ERRORS

No errors are defined.

EXAMPLES

The following example detects truncation while combining a path prefix (including trailing <slash>) and a filename to produce a portable pathname:

char *prefix, *filenam, pathnam[_POSIX_PATH_MAX];


if (strlcpy(pathnam, prefix, sizeof pathnam) >= sizeof pathnam ||
    strlcat(pathnam, filenam, sizeof pathnam) >= sizeof pathnam)
{
    // truncation occurred
    ...
}

This code ensures there is room for the NUL terminator by:

• Calling strlcpy() with a non-zero dstsize argument.

• Only calling strlcat() if the return value of strlcpy() indicated that truncation did not occur.

APPLICATION USAGE

The return value of the strlcpy() and strlcat() functions follows the same convention as snprintf(); that is, they return the total length of the string they tried to create. If the return value is greater than or equal to dstsize, the output string has been truncated.

RATIONALE

None.

FUTURE DIRECTIONS

None.

SEE ALSO

fprintf , strlen , strncat , strncpy , wcslcat

XBD <string.h>

CHANGE HISTORY

First released in Issue 8.