Paul Eggert wrote: > > Here's doc I propose to add to the gnulib documentation (and similar one > > to wcscpy and wcsncpy): > > Thanks, that looks good. I too share an aversion to strncpy
ok, I'm committing this doc change: 2017-10-03 Bruno Haible <br...@clisp.org> doc: warn about misuse of strncpy and wcsncpy. * doc/posix-functions/strcpy.texi: Describe requirements on prior memory allocation. * doc/posix-functions/wcscpy.texi: Likewise. * doc/posix-functions/strncpy.texi: Describe what this function is not useful for. * doc/posix-functions/wcsncpy.texi: Likewise. diff --git a/doc/posix-functions/strcpy.texi b/doc/posix-functions/strcpy.texi index 3289362..89c6cd3 100644 --- a/doc/posix-functions/strcpy.texi +++ b/doc/posix-functions/strcpy.texi @@ -17,3 +17,6 @@ OS X 10.8. Portability problems not fixed by Gnulib: @itemize @end itemize + +Note: @code{strcpy (dst, src)} is only safe to use when you can guarantee that +there are at least @code{strlen (src) + 1} bytes allocated at @code{dst}. diff --git a/doc/posix-functions/strncpy.texi b/doc/posix-functions/strncpy.texi index 3cc6b45..5e22233 100644 --- a/doc/posix-functions/strncpy.texi +++ b/doc/posix-functions/strncpy.texi @@ -17,3 +17,12 @@ OS X 10.8. Portability problems not fixed by Gnulib: @itemize @end itemize + +Note: This function was designed for the use-case of filling a fixed-size +record with a string, before writing it to a file. This function is +@strong{not} appropriate for copying a string into a bounded memory area, +because you have no guarantee that the result will be NUL-terminated. +Even if you add the NUL byte at the end yourself, this function is +inefficient (as it spends time clearing unused memory) and will allow +silent truncation to occur, which is not a good behavior for GNU programs. +For more details, see @see{https://meyering.net/crusade-to-eliminate-strncpy/}. diff --git a/doc/posix-functions/wcscpy.texi b/doc/posix-functions/wcscpy.texi index fbac143..5e4cb01 100644 --- a/doc/posix-functions/wcscpy.texi +++ b/doc/posix-functions/wcscpy.texi @@ -19,3 +19,7 @@ Portability problems not fixed by Gnulib: On AIX and Windows platforms, @code{wchar_t} is a 16-bit type and therefore cannot accommodate all Unicode characters. @end itemize + +Note: @code{wcscpy (dst, src)} is only safe to use when you can guarantee that +there are at least @code{wcslen (src) + 1} wide characters allocated at +@code{dst}. diff --git a/doc/posix-functions/wcsncpy.texi b/doc/posix-functions/wcsncpy.texi index 4a6794a..a9a555e 100644 --- a/doc/posix-functions/wcsncpy.texi +++ b/doc/posix-functions/wcsncpy.texi @@ -16,6 +16,15 @@ IRIX 5.3, Solaris 2.5.1. Portability problems not fixed by Gnulib: @itemize @item -On AIX and Windows platforms, @code{wchar_t} is a 16-bit type and therefore cannot -accommodate all Unicode characters. +On AIX and Windows platforms, @code{wchar_t} is a 16-bit type and therefore +cannot accommodate all Unicode characters. @end itemize + +Note: This function has no real use: It cannot be used for filling a fixed-size +record with a wide string, before writing it to a file, because the wide string +encoding is platform dependent and, on some platforms, also locale dependent. +And this function is @strong{not} appropriate for copying a wide string into a +bounded memory area, because you have no guarantee that the result will be +null-terminated. Even if you add the null character at the end yourself, this +function is inefficient (as it spends time clearing unused memory) and will +allow silent truncation to occur, which is not a good behavior for GNU programs.