A @dfn{string} is a null-terminated array of bytes of type @code{char},
including the terminating null byte. String-valued
variables are usually declared to be pointers of type @code{char *}.
-Such variables do not include space for the text of a string; that has
+Such variables do not include space for the contents of a string; that has
to be stored somewhere else---in an array variable, a string constant,
or dynamically allocated memory (@pxref{Memory Allocation}). It's up to
you to store the address of the chosen memory space into the pointer
A notorious source of program bugs is trying to put more bytes into a
string than fit in its allocated size. When writing code that extends
strings or moves bytes into a pre-allocated array, you should be
-very careful to keep track of the length of the text and make explicit
+very careful to keep track of the length of the string and make explicit
checks for overflowing the array. Many of the library functions
@emph{do not} do this for you! Remember also that you need to allocate
an extra byte to hold the null byte that marks the end of the
@samp{strcat} is declared in the header file @file{string.h} while
@samp{wcscat} is declared in @file{wchar.h}.
+As noted below, these functions are problematic as their callers may
+have performance issues.
+
@deftypefun {char *} strcat (char *restrict @var{to}, const char *restrict @var{from})
@standards{ISO, string.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
Whenever a programmer feels the need to use @code{strcat} she or he
should think twice and look through the program to see whether the code cannot
-be rewritten to take advantage of already calculated results. Again: it
-is almost always unnecessary to use @code{strcat}.
+be rewritten to take advantage of already calculated results.
+The related functions @code{strncat} and @code{wcscat}
+are almost always unnecessary, too.
+Again: it is almost always unnecessary to use functions like @code{strcat}.
@node Truncating Strings
@section Truncating Strings while Copying
@samp{str} functions are declared in the header file @file{string.h}
and the @samp{wc} functions are declared in the file @file{wchar.h}.
+As noted below, these functions are problematic as their callers may
+have truncation-related bugs and performance issues.
+
@deftypefun {char *} strncpy (char *restrict @var{to}, const char *restrict @var{from}, size_t @var{size})
@standards{C90, string.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
non-null bytes followed by zero or more null bytes. It needs to set
all @var{size} bytes of the destination, even when @var{size} is much
greater than the length of @var{from}. As noted below, this function
-is generally a poor choice for processing text.
+is generally a poor choice for processing strings.
@end deftypefun
@deftypefun {wchar_t *} wcsncpy (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom}, size_t @var{size})
This function is the wide-character counterpart of @code{strncpy} and
suffers from most of the problems that @code{strncpy} does. For
example, as noted below, this function is generally a poor choice for
-processing text.
+processing strings.
@end deftypefun
@deftypefun {char *} strndup (const char *@var{s}, size_t @var{size})
the destination string.
As noted below, this function is generally a poor choice for
-processing text.
+processing strings.
@code{strndup} is a GNU extension.
@end deftypefun
parameter list in a function call.
As noted below, this function is generally a poor choice for
-processing text.
+processing strings.
@code{strndupa} is only available if GNU CC is used.
@end deftypefn
declared in @file{string.h}.
As noted below, this function is generally a poor choice for
-processing text.
+processing strings.
@end deftypefun
@deftypefun {wchar_t *} wcpncpy (wchar_t *restrict @var{wto}, const wchar_t *restrict @var{wfrom}, size_t @var{size})
Its behavior is undefined if the strings overlap.
As noted below, this function is generally a poor choice for
-processing text.
+processing strings.
@code{wcpncpy} is a GNU extension.
@end deftypefun
As a companion to @code{strncpy}, @code{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 text. Also, this function has significant
+choice for processing strings. Also, this function has significant
performance issues. @xref{Concatenating Strings}.
@end deftypefun
The behavior of @code{wcsncat} is undefined if the strings overlap.
As noted below, this function is generally a poor choice for
-processing text. Also, this function has significant performance
+processing strings. Also, this function has significant performance
issues. @xref{Concatenating Strings}.
@end deftypefun
Because these functions can abruptly truncate strings or wide strings,
-they are generally poor choices for processing text. When coping or
+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
projects / thirdparty / glibc.git / commitdiff
