strlcpy

Syntax

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

Description

Copy characters from src to dest and nul-terminate the resulting string. Up to size - 1 characters are copied to dest.

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.

strlcpy is a less ambiguous version of strncpy (see section strncpy). Unlike strncpy, strlcpy always nul-terminates the destination dest for non-zero sizes size. strlcpy returns the length of the string whether or not it was possible to copy it all -- this makes it easier to calculate the required buffer size.

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 strlcpy and strlcat (see section strlcat) is available on the web: http://www.openbsd.org/papers/strlcpy-paper.ps.

Return Value

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

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. In this case somestring is truncated to fit into buf.

const char somestring[] = "foo"; char buf[3]; if (strlcpy(buf, somestring, sizeof(buf)) >= sizeof(buf)) puts("somestring was truncated, when copying to buf.");