mirror/glibc
2
0
Fork 0
mirror of git://sourceware.org/git/glibc.git synced 2024-11-27 03:41:23 +08:00
Code Issues Packages Projects Releases Wiki Activity

manual: Manual update for strlcat, strlcpy, wcslcat, wclscpy

Browse Source 
Co-authored-by: Florian Weimer <fweimer@redhat.com>
Reviewed-by: Siddhesh Poyarekar <siddhesh@sourceware.org>
This commit is contained in:
Paul Eggert 2023-06-14 18:10:27 +02:00 committed by Florian Weimer
parent b54e5d1c92
commit d2fda60e7c
2 changed files with 101 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
manual/maint.texi
View File

@ -371,6 +371,10 @@ The following functions and macros are fortified in @theglibc{}:
@item @code{strcpy}
@item @code{strlcat}
@item @code{strlcpy}
@item @code{strncat}
@item @code{strncpy}
@ -411,6 +415,10 @@ The following functions and macros are fortified in @theglibc{}:
@item @code{wcscpy}
@item @code{wcslcat}
@item @code{wcslcpy}
@item @code{wcsncat}
@item @code{wcsncpy}

96
manual/string.texi
View File

@ -726,8 +726,8 @@ This function has undefined results if the strings overlap.
As noted below, this function has significant performance issues.
@end deftypefun
Programmers using the @code{strcat} or @code{wcscat} function (or the
@code{strncat} or @code{wcsncat} functions defined in
Programmers using the @code{strcat} or @code{wcscat} functions (or the
@code{strlcat}, @code{strncat} and @code{wcsncat} functions defined in
a later section, for that matter)
can easily be recognized as lazy and reckless. In almost all situations
the lengths of the participating strings are known (it better should be
@ -848,7 +848,8 @@ function. The example would work for wide characters the same way.
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.
The related functions @code{strncat} and @code{wcscat}
The related functions @code{strlcat}, @code{strncat},
@code{wcscat} and @code{wcsncat}
are almost always unnecessary, too.
Again: it is almost always unnecessary to use functions like @code{strcat}.
@ -1076,6 +1077,95 @@ processing strings. Also, this function has significant performance
issues. @xref{Concatenating Strings}.
@end deftypefun
@deftypefun size_t strlcpy (char *restrict @var{to}, const char *restrict @var{from}, size_t @var{size})
@standards{BSD, string.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function copies the string @var{from} to the destination array
@var{to}, limiting the result's size (including the null terminator)
to @var{size}. The caller should ensure that @var{size} includes room
for the result's terminating null byte.
If @var{size} is greater than the length of the string @var{from},
this function copies the non-null bytes of the string
@var{from} to the destination array @var{to},
and terminates the copy with a null byte. Like other
string functions such as @code{strcpy}, but unlike @code{strncpy}, any
remaining bytes in the destination array remain unchanged.
If @var{size} is nonzero and less than or equal to the the length of the string
@var{from}, this function copies only the first @samp{@var{size} - 1}
bytes to the destination array @var{to}, and writes a terminating null
byte to the last byte of the array.
This function returns the length of the string @var{from}. This means
that truncation occurs if and only if the returned value is greater
than or equal to @var{size}.
The behavior is undefined if @var{to} or @var{from} is a null pointer,
or if the destination array's size is less than @var{size}, or if the
string @var{from} overlaps the first @var{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 @var{from}
even when @var{size} is small.
This function is derived from OpenBSD 2.4.
@end deftypefun
@deftypefun size_t wcslcpy (wchar_t *restrict @var{to}, const wchar_t *restrict @var{from}, size_t @var{size})
@standards{BSD, string.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function is a variant of @code{strlcpy} for wide strings.
The @var{size} argument counts the length of the destination buffer in
wide characters (and not bytes).
This function is derived from BSD.
@end deftypefun
@deftypefun size_t strlcat (char *restrict @var{to}, const char *restrict @var{from}, size_t @var{size})
@standards{BSD, string.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function appends the string @var{from} to the
string @var{to}, limiting the result's total size (including the null
terminator) to @var{size}. The caller should ensure that @var{size}
includes room for the result's terminating null byte.
This function copies as much as possible of the string @var{from} into
the array at @var{to} of @var{size} bytes, starting at the terminating
null byte of the original string @var{to}. In effect, this appends
the string @var{from} to the string @var{to}. Although the resulting
string will contain a null terminator, it can be truncated (not all
bytes in @var{from} may be copied).
This function returns the sum of the original length of @var{to} and
the length of @var{from}. This means that truncation occurs if and
only if the returned value is greater than or equal to @var{size}.
The behavior is undefined if @var{to} or @var{from} is a null pointer,
or if the destination array's size is less than @var{size}, or if the
destination array does not contain a null byte in its first @var{size}
bytes, or if the string @var{from} overlaps the first @var{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. @xref{Concatenating Strings}.
This function is derived from OpenBSD 2.4.
@end deftypefun
@deftypefun size_t wcslcat (wchar_t *restrict @var{to}, const wchar_t *restrict @var{from}, size_t @var{size})
@standards{BSD, string.h}
@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
This function is a variant of @code{strlcat} for wide strings.
The @var{size} argument counts the length of the destination buffer in
wide characters (and not bytes).
This function is derived from BSD.
@end deftypefun
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