From 4f923aafd82a0b35b47abdc738c660088f49591e Mon Sep 17 00:00:00 2001 From: Bruno Haible Date: Tue, 3 Oct 2017 22:01:42 +0200 Subject: [PATCH] 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. --- ChangeLog | 10 ++++++++++ doc/posix-functions/strcpy.texi | 3 +++ doc/posix-functions/strncpy.texi | 9 +++++++++ doc/posix-functions/wcscpy.texi | 4 ++++ doc/posix-functions/wcsncpy.texi | 13 +++++++++++-- 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 + + 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 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. -- 2.39.5