]> Savannah Git Hosting - gnulib.git/commitdiff
doc: warn about misuse of strncpy and wcsncpy.
authorBruno Haible <bruno@clisp.org>
Tue, 3 Oct 2017 20:01:42 +0000 (22:01 +0200)
committerBruno Haible <bruno@clisp.org>
Tue, 3 Oct 2017 20:01:42 +0000 (22:01 +0200)
* 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.

ChangeLog
doc/posix-functions/strcpy.texi
doc/posix-functions/strncpy.texi
doc/posix-functions/wcscpy.texi
doc/posix-functions/wcsncpy.texi

index c2b565073cac5d2814eb88ae5b575055b2033a29..7bc49abd0d368ac300dd5f0abe0178d842f617d9 100644 (file)
--- 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
index 32893620cd4a4fa8a6074d385aec9783ee0e67a2..89c6cd32d1d90fa67d114a438b3d1e7bf3c800ca 100644 (file)
@@ -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}.
index 3cc6b45ffc745185462b68c9299179b5a6698a90..5e222334ddd11d8907967baf0bd965cb44a29702 100644 (file)
@@ -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/}.
index fbac143a09cde50406449458a855dad0fded5fac..5e4cb01e8715a231f67d67c97371e001553cd78a 100644 (file)
@@ -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}.
index 4a6794a9d624db08944869ba12f47f80f4398441..a9a555ee2fb8667bb7667246da7e6c60ad3b8b2b 100644 (file)
@@ -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.