docs: deprecated.rst: Expand str*cpy() replacement notes

The notes on replacing the deprecated str*cpy() functions didn't call
enough attention to the change in return type. Add these details and
clean up the language a bit more.

Signed-off-by: Kees Cook <keescook@chromium.org>
Acked-by: Gustavo A. R. Silva <gustavoars@kernel.org>
Link: https://lore.kernel.org/r/20201015231730.2138505-1-keescook@chromium.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation/process/deprecated.rst

@@ -106,23 +106,29 @@ NUL or newline terminated.
 
 strcpy()
 --------
-strcpy() performs no bounds checking on the destination
+strcpy() performs no bounds checking on the destination buffer. This
-buffer. This could result in linear overflows beyond the
+could result in linear overflows beyond the end of the buffer, leading to
-end of the buffer, leading to all kinds of misbehaviors. While
+all kinds of misbehaviors. While `CONFIG_FORTIFY_SOURCE=y` and various
-`CONFIG_FORTIFY_SOURCE=y` and various compiler flags help reduce the
+compiler flags help reduce the risk of using this function, there is
-risk of using this function, there is no good reason to add new uses of
+no good reason to add new uses of this function. The safe replacement
-this function. The safe replacement is strscpy().
+is strscpy(), though care must be given to any cases where the return
+value of strcpy() was used, since strscpy() does not return a pointer to
+the destination, but rather a count of non-NUL bytes copied (or negative
+errno when it truncates).
 
 strncpy() on NUL-terminated strings
 -----------------------------------
-Use of strncpy() does not guarantee that the destination buffer
+Use of strncpy() does not guarantee that the destination buffer will
-will be NUL terminated. This can lead to various linear read overflows
+be NUL terminated. This can lead to various linear read overflows and
-and other misbehavior due to the missing termination. It also NUL-pads the
+other misbehavior due to the missing termination. It also NUL-pads
-destination buffer if the source contents are shorter than the destination
+the destination buffer if the source contents are shorter than the
-buffer size, which may be a needless performance penalty for callers using
+destination buffer size, which may be a needless performance penalty
-only NUL-terminated strings. The safe replacement is strscpy().
+for callers using only NUL-terminated strings. The safe replacement is
-(Users of strscpy() still needing NUL-padding should instead
+strscpy(), though care must be given to any cases where the return value
-use strscpy_pad().)
+of strncpy() was used, since strscpy() does not return a pointer to the
+destination, but rather a count of non-NUL bytes copied (or negative
+errno when it truncates). Any cases still needing NUL-padding should
+instead use strscpy_pad().
 
 If a caller is using non-NUL-terminated strings, strncpy() can
 still be used, but destinations should be marked with the `__nonstring
@@ -131,10 +137,12 @@ attribute to avoid future compiler warnings.
 
 strlcpy()
 ---------
-strlcpy() reads the entire source buffer first, possibly exceeding
+strlcpy() reads the entire source buffer first (since the return value
-the given limit of bytes to copy. This is inefficient and can lead to
+is meant to match that of strlen()). This read may exceed the destination
-linear read overflows if a source string is not NUL-terminated. The
+size limit. This is both inefficient and can lead to linear read overflows
-safe replacement is strscpy().
+if a source string is not NUL-terminated. The safe replacement is strscpy(),
+though care must be given to any cases where the return value of strlcpy()
+is used, since strscpy() will return negative errno values when it truncates.
 
 %p format specifier
 -------------------