C Programming/C Reference/nonstandard/strlcpy

In computer programming, the strlcpy function is intended to replace the function strcpy (which copies a string to a destination buffer) with a secure version that cannot overflow the destination buffer. It is almost always accompanied by the strlcat function which provides a similar alternative to strcat (which appends a source string to a destination buffer).

The standard C functions that can be used to avoid buffer overflow, strncpy and strncat, have serious design flaws that make them difficult and unnecessarily slow to use correctly. strlcpy and strlcat are designed so that correct usage is as simple as possible.

These are not C standard library functions, but are available in the libraries on several Unix operating systems, including BSD, Mac OS X, Solaris, Android and IRIX, with notable exception of glibc on Linux, although it is available from libbsd instead.

Usage

size_t strlcpy(char *destination, const char *source, size_t size);
size_t strlcat(char *destination, const char *source, size_t size);

Like strncpy, strlcpy takes the destination's size as a parameter and will not write more than that many bytes, to prevent buffer overflow (assuming size is correct). But, unlike strncpy, strlcpy always writes a single NUL byte to the destination (if size is not zero). The resulting string is guaranteed to be NUL-terminated even if truncated. Also it does not waste time writing multiple NUL bytes to fill the rest of the buffer, unlike strncpy.

In addition, strlcpy counts and returns the length of the entire source string (strncpy doesn't return a length). This length can be compared to the destination buffer's size to check if it was truncated, and to work around truncation, for example:

char *copy; // this will point at our copy of the string
size_t length; // this will hold the length of the string

// Copy to a fast block of memory on the stack:
char stack_buffer[128];
length = strlcpy(stack_buffer, source, sizeof(stack_buffer));

if (length < sizeof(stack_buffer)) {
  // it fit, use the stack buffer
  copy = stack_buffer;
} else {
  // it was truncated, use a slower buffer on the heap: 
  copy = malloc(length+1);
  if (copy != NULL)
    memcpy(copy, source, length+1);
}

// Now use the copy of the string. The length is often useful, too:
use(copy, length);

// free the buffer if we allocated it:
if (copy != stack_buffer) free(copy);

strlcat is equivalent to writing the appended strings to a temporary infinitely-large buffer, and then doing a strlcpy from that buffer to the destination.

History

strlcpy and strlcat were developed by Todd C. Miller and Theo de Raadt and first implemented in OpenBSD version 2.4. It has subsequently been adopted by a number of operating systems including FreeBSD (from version 3.3), Solaris, Mac OS X and GNU-based systems through libbsd. Many application packages and libraries include their own copies of these functions, including glib, rsync, Samba, KDE, and the Linux kernel itself.

Criticism

GNU C Library maintainer Ulrich Drepper is among the critics of the strlcpy and strlcat functions; consequently these functions have not been added to glibc. Drepper argues that strlcpy and strlcat make truncation errors easier for a programmer to ignore and thus can introduce more bugs than they remove. His concern with possible truncation, when using any string function involving static allocation, is shared by others.

The alternative recommended by Drepper is:

  *((char *) mempcpy (dst, src, n)) = '\0';

Other criticisms are that the functions are non-standard and that there are implementation differences between the BSD and Solaris implementations (the return value of strlcat, when there is no NUL in the destination buffer, differs).

External links

• strlcpy and strlcat--Consistent, Safe, String Copy and Concatenation - a paper written by Miller and de Raadt, presented at Usenix 99
• strlcpy(3): size-bounded string copying and concatenation – OpenBSD Library Functions Manual
• Developer Blog discussion of strlcpy and mempcpy