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.

5 files changed, 37 insertions, 2 deletions

diff --git a/ChangeLog b/ChangeLog
index c2b565073c..7bc49abd0d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2017-10-03  Bruno Haible  <bruno@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.
+
 2017-10-02  Paul Eggert  <eggert@cs.ucla.edu>
 
 	fsuage: fix typo in previous change
diff --git a/doc/posix-functions/strcpy.texi b/doc/posix-functions/strcpy.texi
index 32893620cd..89c6cd32d1 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 3cc6b45ffc..5e222334dd 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 fbac143a09..5e4cb01e87 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 4a6794a9d6..a9a555ee2f 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.