| Message ID | 20220325184502.761115-1-dmalcolm@redhat.com |
|---|---|
| State | New |
| Headers | show |
| Series | [v3] Document that the 'access' and 'nonnull' attributes are independent | expand |
On 3/25/22 12:45, David Malcolm wrote: > On Wed, 2022-03-23 at 17:52 +0100, Sebastian Huber wrote: >> On 23/03/2022 17:31, Martin Sebor via Gcc-patches wrote: >>> >>> The concern is that the constraints implied by atttributes access >>> and >>> nonnull are independent of each other. I would suggest to document >>> that without talking about dereferencing because that's not implied >>> by either of them. E.g., something like this (feel free to tweak >>> it >>> as you see fit): >>> >>> Note that the @code{access} attribute doesn't imply the same >>> constraint as attribute @code{nonnull} (@pxref{Attribute >>> nonnull}). >>> The latter attribute should be used to annotate arguments that >>> must >>> never be null, regardless of the value of the size argument. >> >> I would not give an advice on using the nonnull attribute here. This >> attribute could have pretty dangerous effects in the function >> definition >> (removal of null pointer checks). >> > > That's a fair point. > > Here's a v3 of the patch, which tones down the advice, and mentions that > there are caveats when directing the reader to the "nonnull" attribute. > > How does this look? This version looks good to me. Thanks Martin > > gcc/ChangeLog: > * doc/extend.texi (Common Function Attributes): Document that > 'access' does not imply 'nonnull'. > > Signed-off-by: David Malcolm <dmalcolm@redhat.com> > --- > gcc/doc/extend.texi | 8 ++++++++ > 1 file changed, 8 insertions(+) > > diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi > index a4a25e86928..539dad7001d 100644 > --- a/gcc/doc/extend.texi > +++ b/gcc/doc/extend.texi > @@ -2652,6 +2652,14 @@ The mode is intended to be used as a means to help validate the expected > object size, for example in functions that call @code{__builtin_object_size}. > @xref{Object Size Checking}. > > +Note that the @code{access} attribute merely specifies how an object > +referenced by the pointer argument can be accessed; it does not imply that > +an access @strong{will} happen. Also, the @code{access} attribute does not > +imply the attribute @code{nonnull}; it may be appropriate to add both attributes > +at the declaration of a function that unconditionally manipulates a buffer via > +a pointer argument. See the @code{nonnull} attribute for more information and > +caveats. > + > @item alias ("@var{target}") > @cindex @code{alias} function attribute > The @code{alias} attribute causes the declaration to be emitted as an alias
On Fri, 2022-03-25 at 14:38 -0600, Martin Sebor wrote: > On 3/25/22 12:45, David Malcolm wrote: > > On Wed, 2022-03-23 at 17:52 +0100, Sebastian Huber wrote: > > > On 23/03/2022 17:31, Martin Sebor via Gcc-patches wrote: > > > > > > > > The concern is that the constraints implied by atttributes > > > > access > > > > and > > > > nonnull are independent of each other. I would suggest to > > > > document > > > > that without talking about dereferencing because that's not > > > > implied > > > > by either of them. E.g., something like this (feel free to > > > > tweak > > > > it > > > > as you see fit): > > > > > > > > Note that the @code{access} attribute doesn't imply the > > > > same > > > > constraint as attribute @code{nonnull} (@pxref{Attribute > > > > nonnull}). > > > > The latter attribute should be used to annotate arguments > > > > that > > > > must > > > > never be null, regardless of the value of the size > > > > argument. > > > > > > I would not give an advice on using the nonnull attribute here. > > > This > > > attribute could have pretty dangerous effects in the function > > > definition > > > (removal of null pointer checks). > > > > > > > That's a fair point. > > > > Here's a v3 of the patch, which tones down the advice, and mentions > > that > > there are caveats when directing the reader to the "nonnull" > > attribute. > > > > How does this look? > > This version looks good to me. Thanks. I tested this, and have gone ahead and pushed this to trunk (as r12-8007-g0b5723d74f3a73). Dave > > Thanks > Martin > > > > > gcc/ChangeLog: > > * doc/extend.texi (Common Function Attributes): Document > > that > > 'access' does not imply 'nonnull'. > > > > Signed-off-by: David Malcolm <dmalcolm@redhat.com> > > --- > > gcc/doc/extend.texi | 8 ++++++++ > > 1 file changed, 8 insertions(+) > > > > diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi > > index a4a25e86928..539dad7001d 100644 > > --- a/gcc/doc/extend.texi > > +++ b/gcc/doc/extend.texi > > @@ -2652,6 +2652,14 @@ The mode is intended to be used as a means > > to help validate the expected > > object size, for example in functions that call > > @code{__builtin_object_size}. > > @xref{Object Size Checking}. > > > > +Note that the @code{access} attribute merely specifies how an > > object > > +referenced by the pointer argument can be accessed; it does not > > imply that > > +an access @strong{will} happen. Also, the @code{access} attribute > > does not > > +imply the attribute @code{nonnull}; it may be appropriate to add > > both attributes > > +at the declaration of a function that unconditionally manipulates > > a buffer via > > +a pointer argument. See the @code{nonnull} attribute for more > > information and > > +caveats. > > + > > @item alias ("@var{target}") > > @cindex @code{alias} function attribute > > The @code{alias} attribute causes the declaration to be emitted > > as an alias >
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index a4a25e86928..539dad7001d 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -2652,6 +2652,14 @@ The mode is intended to be used as a means to help validate the expected object size, for example in functions that call @code{__builtin_object_size}. @xref{Object Size Checking}. +Note that the @code{access} attribute merely specifies how an object +referenced by the pointer argument can be accessed; it does not imply that +an access @strong{will} happen. Also, the @code{access} attribute does not +imply the attribute @code{nonnull}; it may be appropriate to add both attributes +at the declaration of a function that unconditionally manipulates a buffer via +a pointer argument. See the @code{nonnull} attribute for more information and +caveats. + @item alias ("@var{target}") @cindex @code{alias} function attribute The @code{alias} attribute causes the declaration to be emitted as an alias