Truncating Strings (The GNU C Library)

### 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. However, 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 was originally derived from OpenBSD 2.4, but was added in POSIX.1-2024.

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 was originally a BSD extension, but was added in POSIX.1-2024.

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 was originally derived from OpenBSD 2.4, but was added in POSIX.1-2024.

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 was originally a BSD extension, but was added in POSIX.1-2024.

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.