[PATCH] document -Wclass-memaccess suppression by casting (PR 81327)

[PATCH] document -Wclass-memaccess suppression by casting (PR 81327)

[Martin Sebor]

[-- Attachment #1: Type: text/plain, Size: 296 bytes --]

Attached is the documentation update for Jakub's recent change
to recognize a cast to void* as a suppression mechanism for
-Wclass-memaccess (the last sentence).

I also reworded the cumbersome first sentence a bit so the diff
looks bigger than the substantive change itself actually is.

Martin

[-- Attachment #2: gcc-wclass-memaccess-cast.diff --]
[-- Type: text/x-patch, Size: 2306 bytes --]

gcc/ChangeLog:

	* doc/invoke.texi (-Wlass-memaccess): Document suppression by casting.

Index: gcc/doc/invoke.texi
===================================================================
--- gcc/doc/invoke.texi	(revision 256650)
+++ gcc/doc/invoke.texi	(working copy)
@@ -2954,20 +2954,22 @@ C++17 it calls @code{f<void(*)()noexcept>}.
 @item -Wclass-memaccess @r{(C++ and Objective-C++ only)}
 @opindex Wclass-memaccess
 Warn when the destination of a call to a raw memory function such as
-@code{memset} or @code{memcpy} is an object of class type writing into which
-might bypass the class non-trivial or deleted constructor or copy assignment,
-violate const-correctness or encapsulation, or corrupt the virtual table.
-Modifying the representation of such objects may violate invariants maintained
-by member functions of the class.  For example, the call to @code{memset}
-below is undefined because it modifies a non-trivial class object and is,
-therefore, diagnosed.  The safe way to either initialize or clear the storage
-of objects of such types is by using the appropriate constructor or assignment
-operator, if one is available.
+@code{memset} or @code{memcpy} is an object of class type, and when writing
+into such an object might bypass the class non-trivial or deleted constructor
+or copy assignment, violate const-correctness or encapsulation, or corrupt
+the virtual table.  Modifying the representation of such objects may violate
+invariants maintained by member functions of the class.  For example, the call
+to @code{memset} below is undefined because it modifies a non-trivial class
+object and is, therefore, diagnosed.  The safe way to either initialize or
+clear the storage of objects of such types is by using the appropriate
+constructor or assignment operator, if one is available.
 @smallexample
 std::string str = "abc";
-memset (&str, 0, 3);
+memset (&str, 0, sizeof str);
 @end smallexample
-The @option{-Wclass-memaccess} option is enabled by @option{-Wall}.
+The @option{-Wclass-memaccess} option is enabled by @option{-Wall}.  Casting
+the pointer to the class object to @code{void *} or to a type that can be
+safely accessed by the raw memory function suppresses the warning.
 
 @item -Wnon-virtual-dtor @r{(C++ and Objective-C++ only)}
 @opindex Wnon-virtual-dtor

Re: [PATCH] document -Wclass-memaccess suppression by casting (PR 81327)

[Jason Merrill]

OK, thanks.

On Sat, Jan 13, 2018 at 6:14 PM, Martin Sebor <msebor@gmail.com> wrote:
> Attached is the documentation update for Jakub's recent change
> to recognize a cast to void* as a suppression mechanism for
> -Wclass-memaccess (the last sentence).
>
> I also reworded the cumbersome first sentence a bit so the diff
> looks bigger than the substantive change itself actually is.
>
> Martin

Re: [PATCH] document -Wclass-memaccess suppression by casting (PR 81327)

[Jakub Jelinek]

On Sat, Jan 13, 2018 at 04:14:38PM -0700, Martin Sebor wrote:
> -The @option{-Wclass-memaccess} option is enabled by @option{-Wall}.
> +The @option{-Wclass-memaccess} option is enabled by @option{-Wall}.  Casting

Perhaps "Explicitly casting" instead?  The implicit cast doesn't suppress it
and occurs whenever there isn't an explicit cast.

> +the pointer to the class object to @code{void *} or to a type that can be
> +safely accessed by the raw memory function suppresses the warning.
>  
>  @item -Wnon-virtual-dtor @r{(C++ and Objective-C++ only)}
>  @opindex Wnon-virtual-dtor


	Jakub

Re: [PATCH] document -Wclass-memaccess suppression by casting (PR 81327)

[Martin Sebor]

On 01/14/2018 03:31 AM, Jakub Jelinek wrote:
> On Sat, Jan 13, 2018 at 04:14:38PM -0700, Martin Sebor wrote:
>> -The @option{-Wclass-memaccess} option is enabled by @option{-Wall}.
>> +The @option{-Wclass-memaccess} option is enabled by @option{-Wall}.  Casting
>
> Perhaps "Explicitly casting" instead?  The implicit cast doesn't suppress it
> and occurs whenever there isn't an explicit cast.
>
>> +the pointer to the class object to @code{void *} or to a type that can be
>> +safely accessed by the raw memory function suppresses the warning.
>>

Sure.  I've committed r256677.

Martin

Re: [PATCH] document -Wclass-memaccess suppression by casting (PR 81327)

[Florian Weimer]

* Martin Sebor:

> +the virtual table.  Modifying the representation of such objects may violate
       ^vtable pointer?

The vtable itself is not corrupted, I assume.

Re: [PATCH] document -Wclass-memaccess suppression by casting (PR 81327)

[Jason Merrill]

On Mon, Jan 15, 2018 at 5:09 AM, Florian Weimer <fw@deneb.enyo.de> wrote:
> * Martin Sebor:
>
>> +the virtual table.  Modifying the representation of such objects may violate
>        ^vtable pointer?
>
> The vtable itself is not corrupted, I assume.

Indeed.

Jason

Re: [PATCH] document -Wclass-memaccess suppression by casting (PR 81327)

[Martin Sebor]

On 01/15/2018 03:09 AM, Florian Weimer wrote:
> * Martin Sebor:
>
>> +the virtual table.  Modifying the representation of such objects may violate
>        ^vtable pointer?
>
> The vtable itself is not corrupted, I assume.

Well, what happens is undefined, so who knows? ;)

But of course in reality, writing to an object can only overwrite
what's stored in the object, so only the vtable pointers will be
corrupted.  I doubt anyone would have misunderstood what was meant
but I've committed r256852 for the sake of being accurate.

Martin