strlcat

Syntax

#include <string.h> size_t strlcat (char *dest, const char *src, size_t size);

Description

Concatenate characters from src to dest and nul-terminate the resulting string. As much of src is copied into dest as there is space for.

size should be the size of the destination string buffer dest plus the space for the nul-terminator. size may be computed in many cases using the sizeof operator.

strlcat may be used as a less ambiguous alternative to strncat (see section strncat). strlcat returns the length of the concatenated string whether or not it was possible to copy it all -- this makes it easier to calculate the required buffer size.

If dest is not nul-terminated, then dest is not modified.

strlcat will not examine more than size characters of dest. This is to avoid overrunning the buffer dest.

If dest and src are overlapping buffers, the behavior is undefined. One possible result is a buffer overrun - accessing out-of-bounds memory.

The original OpenBSD paper describing strlcat and strlcpy (see section strlcpy) is available on the web: http://www.openbsd.org/papers/strlcpy-paper.ps.

Return Value

The length of the string that strlcat tried to create is returned, whether or not strlcat could store it in dest. If all of src was concatenated to dst, the return value will be less than size.

If dest is not nul-terminated, then strlcat will consider dest to be size in length and return size plus the length of src.

Portability

ANSI/ISO C	No
POSIX	No

Example

The following example shows how you can check that the destination string buffer was large enough to store the source string concatenated to the destination string. In this case somestring is truncated, when it is concatenated to buf.

const char somestring[] = "bar"; char buf[5] = "foo"; if (strlcat(buf, somestring, sizeof(buf)) >= sizeof(buf)) puts("somestring was truncated, when concatenating to buf.");