gcc/ChangeLog PR c/109708 * doc/invoke.texi (Warning Options): Fix broken example and clean up/reorganize the others. Also describe what the short-form options mean. --- gcc/doc/invoke.texi | 56 +++++++++++++++++++++++++++------------------ 1 file changed, 34 insertions(+), 22 deletions(-)
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi index 930c5dc7236..f7a6e11d20e 100644 --- a/gcc/doc/invoke.texi +++ b/gcc/doc/invoke.texi @@ -9423,51 +9423,63 @@ levels but may yield different results with optimization than without. @table @gcctabopt @item -Wdangling-pointer=1 -At level 1 the warning diagnoses only unconditional uses of dangling pointers. -For example +At level 1, the warning diagnoses only unconditional uses of dangling pointers. + +@item -Wdangling-pointer=2 +At level 2, in addition to unconditional uses the warning also diagnoses +conditional uses of dangling pointers. +@end table + +The short form @option{-Wdangling-pointer} is equivalent to +@option{-Wdangling-pointer=2}, while @option{-Wno-dangling-pointer} and +@option{-Wdangling-pointer=0} have the same effect of disabling the warnings. +@option{-Wdangling-pointer=2} is included in @option{-Wall}. + +This example triggers the warning at level 1; the address of the unnamed +temporary is unconditionally referenced outside of its scope. + @smallexample -int f (int c1, int c2, x) +char f (char c1, char c2, char c3) @{ - char *p = strchr ((char[])@{ c1, c2 @}, c3); - // warning: dangling pointer to a compound literal - return p ? *p : 'x'; + char *p; + @{ + p = (char[]) @{ c1, c2, c3 @}; + @} + // warning: using dangling pointer 'p' to an unnamed temporary + return *p; @} @end smallexample + In the following function the store of the address of the local variable -@code{x} in the escaped pointer @code{*p} also triggers the warning. +@code{x} in the escaped pointer @code{*p} triggers the warning at +level 1. + @smallexample void g (int **p) @{ int x = 7; - // warning: storing the address of a local variable in *p + // warning: storing the address of local variable 'x' in '*p' *p = &x; @} @end smallexample -@item -Wdangling-pointer=2 -At level 2, in addition to unconditional uses the warning also diagnoses -conditional uses of dangling pointers. - -For example, because the array @var{a} in the following function is out of -scope when the pointer @var{s} that was set to point is used, the warning -triggers at this level. +In this example, the array @var{a} is out of +scope when the pointer @var{s} is used. Since the code that sets @code{s} +is conditional, the warning triggers at level 2. @smallexample -void f (char *s) +extern void frob (const char *); +void h (char *s) @{ if (!s) @{ char a[12] = "tmpname"; s = a; @} - // warning: dangling pointer to a may be used - strcat (s, ".tmp"); - ... + // warning: dangling pointer 's' to 'a' may be used + frob (s); @} @end smallexample -@end table - -@option{-Wdangling-pointer=2} is included in @option{-Wall}. @opindex Wdate-time @opindex Wno-date-time -- 2.31.1