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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.