diff mbox

__attribute__ ((malloc)) doc fix (PR other/56955)

Message ID 537CF259.8050109@cs.ucla.edu
State New
Headers show

Commit Message

Paul Eggert May 21, 2014, 6:37 p.m. UTC 
Attached is a proposed documentation patch for __attribute__ ((malloc)), 
taken from:

https://gcc.gnu.org/bugzilla/show_bug.cgi?id=56955#c9

Richard Biener suggested that I forward it to this list.

Comments

Richard Biener May 22, 2014, 8 a.m. UTC | #1 
On Wed, May 21, 2014 at 8:37 PM, Paul Eggert <eggert@cs.ucla.edu> wrote:
> Attached is a proposed documentation patch for __attribute__ ((malloc)),
> taken from:
>
> https://gcc.gnu.org/bugzilla/show_bug.cgi?id=56955#c9
>
> Richard Biener suggested that I forward it to this list.

Thanks Paul.  Re-reading this I wonder if the wording is clear enough to
disallow for example

struct S { struct S *p; };

struct S * __attribute__((malloc)) allocS (void)
{
  struct S *s = malloc (sizeof (struct S));
  s->p = s;
  return s;
}

the function returns an initialized S, but it's pointers do
not alias any other pointer valid when the function returns(?).

That is, the constraint is rather that pointers extracted from the
memory pointed to by the return value do not point to "valid"
objects.

For the above doing

struct S *s = allocS();
s->s->s = 0;

would be DSEd (because s->s points to 'nothing').

Can you try to clarify the wording (I'm not a native speaker).

Thanks,
Richard.
diff mbox

Patch

Index: gcc/ChangeLog
===================================================================
--- gcc/ChangeLog	(revision 210629)
+++ gcc/ChangeLog	(working copy)
@@ -1,3 +1,10 @@ 
+2014-05-20  Paul Eggert  <eggert@cs.ucla.edu>
+
+	PR other/56955
+	* doc/extend.texi (Function Attributes): Fix  __attribute__ ((malloc))
+	documentation; the old documentation didn't clearly state the
+	constraints on the contents of the pointed-to storage.
+
 2014-05-19  David Wohlferd <dw@LimeGreenSocks.com>
 
 	* doc/extend.texi: Create Label Attributes section,
Index: gcc/doc/extend.texi
===================================================================
--- gcc/doc/extend.texi	(revision 210629)
+++ gcc/doc/extend.texi	(working copy)
@@ -3207,15 +3207,20 @@ 
 
 @item malloc
 @cindex @code{malloc} attribute
-The @code{malloc} attribute is used to tell the compiler that a function
-may be treated as if any non-@code{NULL} pointer it returns cannot
-alias any other pointer valid when the function returns and that the memory
-has undefined content.
-This often improves optimization.
-Standard functions with this property include @code{malloc} and
-@code{calloc}.  @code{realloc}-like functions do not have this
-property as the memory pointed to does not have undefined content.
+This tells the compiler that a function is @code{malloc}-like, i.e.,
+that if the function returns a non-null pointer @var{P}, then @var{P}
+cannot alias any other pointer valid when the function returns, and
+moreover the contents of any storage addressed by @var{P} cannot
+contain a pointer that aliases any other pointer valid when the
+function returns.
 
+Using this attribute often improves optimization.  Functions like
+@code{malloc} and @code{calloc} have this property because they return
+a pointer to uninitialized or zeroed-out storage.  However, functions
+like @code{realloc} do not have this property, as they can return a
+pointer to storage containing pointers that alias already-valid
+pointers.
+
 @item mips16/nomips16
 @cindex @code{mips16} attribute
 @cindex @code{nomips16} attribute