---

5.6 Truncating Strings while Copying

The functions described in this section copy or concatenate the possibly-truncated contents of a string or array to another, and similarly for wide strings. They follow the string-copying functions in their header conventions. See Copying Strings and Arrays. The ‘str’ functions are declared in the header file string.h and the ‘wc’ functions are declared in the file wchar.h.

As noted below, these functions are problematic as their callers may have truncation-related bugs and performance issues.

Function: char * strncpy (char *restrict to, const char *restrict from, size_t size) ¶

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This function is similar to strcpy but always copies exactly size bytes into to.

If from does not contain a null byte in its first size bytes, strncpy copies just the first size bytes. In this case no null terminator is written into to.

Otherwise from must be a string with length less than size. In this case strncpy copies all of from, followed by enough null bytes to add up to size bytes in all.

The behavior of strncpy is undefined if the strings overlap.

This function was designed for now-rarely-used arrays consisting of non-null bytes followed by zero or more null bytes. It needs to set all size bytes of the destination, even when size is much greater than the length of from. As noted below, this function is generally a poor choice for processing strings.

Function: wchar_t * wcsncpy (wchar_t *restrict wto, const wchar_t *restrict wfrom, size_t size) ¶

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This function is similar to wcscpy but always copies exactly size wide characters into wto.

If wfrom does not contain a null wide character in its first size wide characters, then wcsncpy copies just the first size wide characters. In this case no null terminator is written into wto.

Otherwise wfrom must be a wide string with length less than size. In this case wcsncpy copies all of wfrom, followed by enough null wide characters to add up to size wide characters in all.

The behavior of wcsncpy is undefined if the strings overlap.

This function is the wide-character counterpart of strncpy and suffers from most of the problems that strncpy does. For example, as noted below, this function is generally a poor choice for processing strings.

Function: char * strndup (const char *s, size_t size) ¶

Preliminary: | MT-Safe | AS-Unsafe heap | AC-Unsafe mem | See POSIX Safety Concepts.

This function is similar to strdup but always copies at most size bytes into the newly allocated string.

If the length of s is more than size, then strndup copies just the first size bytes and adds a closing null byte. Otherwise all bytes are copied and the string is terminated.

This function differs from strncpy in that it always terminates the destination string.

As noted below, this function is generally a poor choice for processing strings.

strndup is a GNU extension.

Macro: char * strndupa (const char *s, size_t size) ¶

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This function is similar to strndup but like strdupa it allocates the new string using alloca see Automatic Storage with Variable Size. The same advantages and limitations of strdupa are valid for strndupa, too.

This function is implemented only as a macro, just like strdupa. Just as strdupa this macro also must not be used inside the parameter list in a function call.

As noted below, this function is generally a poor choice for processing strings.

strndupa is only available if GNU CC is used.

Function: char * stpncpy (char *restrict to, const char *restrict from, size_t size) ¶

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This function is similar to stpcpy but copies always exactly size bytes into to.

If the length of from is more than size, then stpncpy copies just the first size bytes and returns a pointer to the byte directly following the one which was copied last. Note that in this case there is no null terminator written into to.

If the length of from is less than size, then stpncpy copies all of from, followed by enough null bytes to add up to size bytes in all. This behavior is rarely useful, but it is implemented to be useful in contexts where this behavior of the strncpy is used. stpncpy returns a pointer to the first written null byte.

This function is not part of ISO or POSIX but was found useful while developing the GNU C Library itself.

Its behavior is undefined if the strings overlap. The function is declared in string.h.

As noted below, this function is generally a poor choice for processing strings.

Function: wchar_t * wcpncpy (wchar_t *restrict wto, const wchar_t *restrict wfrom, size_t size) ¶

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This function is similar to wcpcpy but copies always exactly wsize wide characters into wto.

If the length of wfrom is more than size, then wcpncpy copies just the first size wide characters and returns a pointer to the wide character directly following the last non-null wide character which was copied last. Note that in this case there is no null terminator written into wto.

If the length of wfrom is less than size, then wcpncpy copies all of wfrom, followed by enough null wide characters to add up to size wide characters in all. This behavior is rarely useful, but it is implemented to be useful in contexts where this behavior of the wcsncpy is used. wcpncpy returns a pointer to the first written null wide character.

This function is not part of ISO or POSIX but was found useful while developing the GNU C Library itself.

Its behavior is undefined if the strings overlap.

As noted below, this function is generally a poor choice for processing strings.

wcpncpy is a GNU extension.

Function: char * strncat (char *restrict to, const char *restrict from, size_t size) ¶

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This function is like strcat except that not more than size bytes from from are appended to the end of to, and from need not be null-terminated. A single null byte is also always appended to to, so the total allocated size of to must be at least size + 1 bytes longer than its initial length.

The strncat function could be implemented like this:

char *
strncat (char *to, const char *from, size_t size)
{
  size_t len = strlen (to);
  memcpy (to + len, from, strnlen (from, size));
  to[len + strnlen (from, size)] = '\0';
  return to;
}

The behavior of strncat is undefined if the strings overlap.

As a companion to strncpy, strncat was designed for now-rarely-used arrays consisting of non-null bytes followed by zero or more null bytes. As noted below, this function is generally a poor choice for processing strings. Also, this function has significant performance issues. See Concatenating Strings.

Function: wchar_t * wcsncat (wchar_t *restrict wto, const wchar_t *restrict wfrom, size_t size) ¶

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This function is like wcscat except that not more than size wide characters from from are appended to the end of to, and from need not be null-terminated. A single null wide character is also always appended to to, so the total allocated size of to must be at least wcsnlen (wfrom, size) + 1 wide characters longer than its initial length.

The wcsncat function could be implemented like this:

wchar_t *
wcsncat (wchar_t *restrict wto, const wchar_t *restrict wfrom,
         size_t size)
{
  size_t len = wcslen (wto);
  memcpy (wto + len, wfrom, wcsnlen (wfrom, size) * sizeof (wchar_t));
  wto[len + wcsnlen (wfrom, size)] = L'\0';
  return wto;
}

The behavior of wcsncat is undefined if the strings overlap.

As noted below, this function is generally a poor choice for processing strings. Also, this function has significant performance issues. See Concatenating Strings.

Function: size_t strlcpy (char *restrict to, const char *restrict from, size_t size) ¶

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This function copies the string from to the destination array to, limiting the result’s size (including the null terminator) to size. The caller should ensure that size includes room for the result’s terminating null byte.

If size is greater than the length of the string from, this function copies the non-null bytes of the string from to the destination array to, and terminates the copy with a null byte. Like other string functions such as strcpy, but unlike strncpy, any remaining bytes in the destination array remain unchanged.

If size is nonzero and less than or equal to the the length of the string from, this function copies only the first ‘size - 1’ bytes to the destination array to, and writes a terminating null byte to the last byte of the array.

This function returns the length of the string from. This means that truncation occurs if and only if the returned value is greater than or equal to size.

The behavior is undefined if to or from is a null pointer, or if the destination array’s size is less than size, or if the string from overlaps the first size bytes of the destination array.

As noted below, this function is generally a poor choice for processing strings. Also, this function has a performance issue, as its time cost is proportional to the length of from even when size is small.

This function is derived from OpenBSD 2.4.

Function: size_t wcslcpy (wchar_t *restrict to, const wchar_t *restrict from, size_t size) ¶

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This function is a variant of strlcpy for wide strings. The size argument counts the length of the destination buffer in wide characters (and not bytes).

This function is derived from BSD.

Function: size_t strlcat (char *restrict to, const char *restrict from, size_t size) ¶

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This function appends the string from to the string to, limiting the result’s total size (including the null terminator) to size. The caller should ensure that size includes room for the result’s terminating null byte.

This function copies as much as possible of the string from into the array at to of size bytes, starting at the terminating null byte of the original string to. In effect, this appends the string from to the string to. Although the resulting string will contain a null terminator, it can be truncated (not all bytes in from may be copied).

This function returns the sum of the original length of to and the length of from. This means that truncation occurs if and only if the returned value is greater than or equal to size.

The behavior is undefined if to or from is a null pointer, or if the destination array’s size is less than size, or if the destination array does not contain a null byte in its first size bytes, or if the string from overlaps the first size bytes of the destination array.

As noted below, this function is generally a poor choice for processing strings. Also, this function has significant performance issues. See Concatenating Strings.

This function is derived from OpenBSD 2.4.

Function: size_t wcslcat (wchar_t *restrict to, const wchar_t *restrict from, size_t size) ¶

Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

This function is a variant of strlcat for wide strings. The size argument counts the length of the destination buffer in wide characters (and not bytes).

This function is derived from BSD.

Because these functions can abruptly truncate strings or wide strings, they are generally poor choices for processing them. When copying or concatening multibyte strings, they can truncate within a multibyte character so that the result is not a valid multibyte string. When combining or concatenating multibyte or wide strings, they may truncate the output after a combining character, resulting in a corrupted grapheme. They can cause bugs even when processing single-byte strings: for example, when calculating an ASCII-only user name, a truncated name can identify the wrong user.

Although some buffer overruns can be prevented by manually replacing calls to copying functions with calls to truncation functions, there are often easier and safer automatic techniques, such as fortification (see Fortification of function calls) and AddressSanitizer (see Program Instrumentation Options in Using GCC). Because truncation functions can mask application bugs that would otherwise be caught by the automatic techniques, these functions should be used only when the application’s underlying logic requires truncation.

Note: GNU programs should not truncate strings or wide strings to fit arbitrary size limits. See Writing Robust Programs in The GNU Coding Standards. Instead of string-truncation functions, it is usually better to use dynamic memory allocation (see Unconstrained Allocation) and functions such as strdup or asprintf to construct strings.