Documentation: Improve -Wstringop-overflow documentation [PR 113515]

This option can warn about things other than string and memory functions.
Say so explicitly, and give an example.  I also did some copy-editing
of the text and added some paragraph breaks.

gcc/ChangeLog
	PR c/113515
	* doc/invoke.texi (Warning Options): Improve -Wstringop-overflow
	documentation.

1 files changed, 29 insertions, 6 deletions

diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 304de88..fd1ce06 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -8229,20 +8229,28 @@ void f (char *d)
 @item -Wno-stringop-overflow
 @item -Wstringop-overflow
 @itemx -Wstringop-overflow=@var{type}
-Warn for calls to string manipulation functions such as @code{memcpy} and
-@code{strcpy} that are determined to overflow the destination buffer.  The
+Warn for code that can be statically determined to cause buffer overflows or
+memory overruns, such as calls to @code{memcpy} and
+@code{strcpy} that overflow the destination buffer.  The
 optional argument is one greater than the type of Object Size Checking to
 perform to determine the size of the destination.  @xref{Object Size Checking}.
-The argument is meaningful only for functions that operate on character arrays
-but not for raw memory functions like @code{memcpy} which always make use
-of Object Size type-0.  The option also warns for calls that specify a size
+The argument is meaningful only for string functions
+that operate on character arrays; raw memory functions like @code{memcpy}
+always use type-zero Object Size Checking.
+
+The option also warns for calls that specify a size
 in excess of the largest possible object or at most @code{SIZE_MAX / 2} bytes.
+
 The option produces the best results with optimization enabled but can detect
 a small subset of simple buffer overflows even without optimization in
 calls to the GCC built-in functions like @code{__builtin_memcpy} that
 correspond to the standard functions.  In any case, the option warns about
 just a subset of buffer overflows detected by the corresponding overflow
-checking built-ins.  For example, the option issues a warning for
+checking built-ins, such as @code{__builtin___memcpy_chk}, which can perform
+run-time checking if the access cannot be identified as safe
+at compile time.
+
+For example, the option issues a warning for
 the @code{strcpy} call below because it copies at least 5 characters
 (the string @code{"blue"} including the terminating NUL) into the buffer
 of size 4.
@@ -8264,6 +8272,21 @@ const char* f (enum Color clr)
 @}
 @end smallexample
 
+The effect of this option is not limited to string or memory
+manipulation functions.  In this example, a warning is diagnosed
+because a 1-element array is passed to a function requiring at least a
+4-element array argument:
+
+@smallexample
+void f (int[static 4]);
+
+void g (void)
+@{
+  int *p = (int *) malloc (1 * sizeof(int));
+  f (p);   // warning here
+@}
+@end smallexample
+
 Option @option{-Wstringop-overflow=2} is enabled by default.
 
 @table @gcctabopt