Re: [RFC] Add stdckdint.h header for C23

[Paul Eggert]

On 6/12/23 23:28, Jakub Jelinek via Libc-alpha wrote:

On Mon, Jun 12, 2023 at 09:51:02PM +, Joseph Myers wrote:

On Sat, 10 Jun 2023, Jakub Jelinek via Gcc-patches wrote:


I have looked at gnulib stdckdint.h and they are full of workarounds
for various compilers, EDG doesn't do this, clang <= 14 can't multiply
__int128, ..., so I think the header belongs into the compiler rather
than C library, because it would be a nightmare to maintain it there.


I tend to agree. I don't see how to implement  in the C 
library, at least not for the C library's users.


It would be possible to implement  for C library internal 
use only, because then we could assume #include_next, and we could use 
the Gnulib implementation safely (that implementation is already present 
glibc internals, just under a different name). This could well be worth 
doing, because glibc internally needs ckd_add (or something equivalent) 
but glibc can't yet assume that it's built with GCC 14 (or whatever GCC 
version eventually supports ).




There is always the possibility to have the header co-owned by both
the compiler and C library, limits.h style.
Just
#if __has_include_next()
# include_next 
#endif


I don't see how you could implement __has_include_next() 
for arbitrary non-GCC compilers, which is what we'd need for glibc 
users. For glibc internals we can use "#include_next" more readily, 
since we assume a new-enough GCC. I.e. we could do something like this:


   #if 14 <= __GNUC__
   # include_next 
   #else
   # define ckd_add(r, a, b) INT_ADD_WRAPV (a, b, &(r))
   #endif

where INT_ADD_WRAPV is the already-existing glibc internal macro, and 
where we invoke ckd_add only with arguments free of side effects.

[PATCH] Document that -fno-trampolines is for Ada only [PR100735]

[Paul Eggert]

The GCC manual's documentation of -fno-trampolines was apparently
written from an Ada point of view. However, when I read it I
understandably mistook it to say that -fno-trampolines also works for
C, C++, etc. It doesn't: it is silently ignored for these languages,
and I assume for any language other than Ada.

This confusion caused me to go in the wrong direction in a Gnulib
dicussion, as I mistakenly thought that entire C apps with nested
functions could be compiled with -fno-trampolines and then use nested
C functions in stack overflow handlers where the alternate stack
is allocated via malloc. I was wrong, as this won't work on common
platforms like x86-64 where malloc yields non-executable storage.

gcc/
* doc/invoke.texi (Code Gen Options):
* doc/tm.texi.in (Trampolines):
Document that -fno-trampolines and -ftrampolines work
only with Ada.
---
 gcc/doc/invoke.texi | 5 +
 gcc/doc/tm.texi.in  | 4 
 2 files changed, 9 insertions(+)

diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 5cd4e2d993c..b55bbf3e424 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -16646,6 +16646,11 @@ Moreover, code compiled with @option{-ftrampolines} 
and code compiled with
 present.  This option must therefore be used on a program-wide basis and be
 manipulated with extreme care.
 
+For languages other than Ada, the @code{-ftrampolines} and
+@code{-fno-trampolines} options currently have no effect, and
+trampolines are always generated on platforms that need them
+for nested functions.
+
 @item -fvisibility=@r{[}default@r{|}internal@r{|}hidden@r{|}protected@r{]}
 @opindex fvisibility
 Set the default ELF image symbol visibility to the specified option---all
diff --git a/gcc/doc/tm.texi.in b/gcc/doc/tm.texi.in
index d9fbbe20e6f..20501607716 100644
--- a/gcc/doc/tm.texi.in
+++ b/gcc/doc/tm.texi.in
@@ -3828,6 +3828,10 @@ addresses.  Since GCC's generic function descriptors are
 not ABI-compliant, this option is typically used only on a
 per-language basis (notably by Ada) or when it can otherwise be
 applied to the whole program.
+For languages other than Ada, the @code{-ftrampolines} and
+@code{-fno-trampolines} options currently have no effect, and
+trampolines are always generated on platforms that need them
+for nested functions.
 
 Define the following hook if your backend either implements ABI-specified
 descriptor support, or can use GCC's generic descriptor implementation
-- 
2.31.1

Re: [PATCH 1/4] system_data_types.7: Add '__int128'

[Paul Eggert]

On 10/2/20 4:44 PM, Alejandro Colomar wrote:


I know, they aren't perfect.
But they are still very useful,
and don't see a good reason to not document them.


"aren't perfect" is an understatement

More important, lots of things in GNU C are useful but shouldn't be documented 
in the man pages, because they're out of scope. (The syntax of GNU C strings, 
for example.) The man pages are not intended to be a guide to every feature of 
GNU C. There is the GNU C manual for that, and people can read that.

Re: [PATCH 1/4] system_data_types.7: Add '__int128'

[Paul Eggert]

On 10/2/20 1:03 PM, Alejandro Colomar wrote:

I know it's not in stdint,
but I mean that it behaves as any other stdint type.


It doesn't. There's no portable way to use scanf and printf on it. You can't 
reliably convert it to intmax_t. It doesn't have the associated _MIN and _MAX 
macros that the stdint types do. It's a completely different animal.


If all you need are a few bit-twiddling tricks on x86-64, it should work. But 
watch out if you try to do something fancy, like multiply or divide or read or 
print or atomics. There's a good reason it's excluded from intmax_t.

Re: [PATCH v4 1/2] system_data_types.7: Add 'void *'

[Paul Eggert]

On 10/2/20 11:38 AM, Alejandro Colomar wrote:


.I void *

renders with a space in between.


That's odd, as "man(7)" says "All of the arguments will be printed next to each 
other without intervening spaces". I'd play it safe and quote the arg anyway.



 > %p works with any object pointer type (or in POSIX, any pointer type),
 > not just  void *.
In theory, no (if otherwise, I'd like to know why):


Oh, you're right. I had missed that. In GNU/Linux hosts, though, any pointer 
(including function pointers) can be given to %p.


The only platforms where %p wouldn't work on all pointers would be platforms 
like IBM i, which has both 64-bit (process local) pointers and 128-bit (tagged 
space) pointers and where you can declare and use pointers of different widths 
in the same program.

Re: [PATCH 1/4] system_data_types.7: Add '__int128'

[Paul Eggert]

On 10/2/20 12:01 PM, Alejandro Colomar wrote:

If you propose not to document the stdint types either,


This is not a stdint.h issue. __int128 is not in stdint.h and is not a system 
data type in any real sense; it's purely a compiler issue. Besides, do we start 
repeating the GCC manual too, while we're at it? At some point we need to 
restrain ourselves and stay within the scope of the man pages.


PS. Have you ever tried to use __int128 in real code? I have, to my regret. It's 
a portability and bug minefield and should not be used unless you really know 
what you're doing, which most people do not.

Re: [PATCH 1/4] system_data_types.7: Add '__int128'

[Paul Eggert]

Why describe __int128_t in these man pages at all? __int128_t is not a property 
of either the kernel or of glibc, so it's out of scope.

Re: [PATCH v4 1/2] system_data_types.7: Add 'void *'

[Paul Eggert]

On 10/2/20 8:14 AM, Alejandro Colomar wrote:


+.I void *


GNU style is a space between "void" and "*", so this should be '.I "void\ *"', 
both here and elsewhere. The backslash prevents a line break.



+Conversions from and to any other pointer type are done implicitly,
+not requiring casts at all.
+Note that this feature prevents any kind of type checking:
+the programmer should be careful not to cast a


Change "cast" to "convert", since the point is that no cast is needed.


+.PP
+The conversion specifier for
+.I void *
+for the
+.BR printf (3)
+and the
+.BR scanf (3)
+families of functions is
+.BR p ;
+resulting commonly in
+.B %p
+for printing
+.I void *
+values.


%p works with any object pointer type (or in POSIX, any pointer type), not just 
 void *.


Should also mention "void const *", "void volatile *", etc. Plus it really 
should talk about plain "void", saying that it's a placeholder as a return value 
for functions, for casting away values, and as a keyword in C11 for functions 
with no parameters (though this is being changed in the next C version!). I sent 
comments about most of this stuff already.

Re: Ping Re: Make max_align_t respect _Float128 [version 3]

[Paul Eggert]

On 09/19/2016 08:58 AM, Joseph Myers wrote:

Ping.  This patch
 is pending
review.

Thanks, the patch looks good to me. It should be safe for the uses of 
max_align_t that I know of (e.g., Emacs).

Re: Make max_align_t respect _Float128 [version 2]

[Paul Eggert]

On 09/08/2016 04:56 AM, Mark Wielaard wrote:

I don't think there is anything valgrind can do to detect that
compw really only depends on d[0] if the result is false.

valgrind (with the default --partial-loads-ok=yes) could and should do 
the same thing with cmpw that it already does with cmpl. The attached 
program compiles and runs OK with gcc -O2 and valgrind on x86-64, even 
though the machine code uses cmpl to load bytes that were not allocated.



Do gnulib and glibc syncronize?


They do at times, though not as often as we'd like. fts.c in particular 
has strayed quite a bit, to cater GNU utilities' robustness needs over 
what glibc provides. (GNU coreutils, for example, uses Gnulib fts.c even 
on glibc platforms.) At some point somebody should merge Gnulib fts.c 
back into glibc.


#include 
#include 

struct s { struct s *next; char d[]; };

int
main (void)
{
  struct s *p = malloc (offsetof (struct s, d) + 1);
  p->d[0] = 1;
  return p->d[0] == 2 && p->d[1] == 3 && p->d[2] == 4 && p->d[3] == 5;
}

Re: Make max_align_t respect _Float128 [version 2]

[Paul Eggert]

On 09/07/2016 04:52 AM, Mark Wielaard wrote:

If valgrind believes the
memory isn't in valid memory then it will complain about an invalid access.
But if the memory is accessible but uninitialised then it will just track
the undefinedness complain later if such a value is used.


I think the former is what happened in Gnulib fts.c before Gnulib was fixed.


valgrind also has --partial-loads-ok (which in newer versions defaults
to =yes):

Controls how Memcheck handles 32-, 64-, 128- and 256-bit naturally
aligned loads from addresses for which some bytes are addressable
and others are not.


Although this helps in some cases, it does not suffice in general since 
the problem can occur with 16-bit aligned loads. I think that is what 
happened with fts.c.



Does anybody have an example program of the above issue compiled with
gcc that produces false positives with valgrind?



Sure, attached. On Fedora 24 x86-64 (GCC 6.1.1 20160621, valgrind 
3.11.0), when I compile with "gcc -O2 flexouch.c" and run with "valgrind 
./a.out", valgrind complains "Invalid read of size 2". This is because 
GCC compiles "p->d[0] == 2 && p->d[1] == 3" into "cmpw $770, 8(%rax); 
sete %al", which loads the uninitialized byte p->d[1] simultaneously 
with the initialized byte p->d[0].


As mentioned previously, although flexouch.c does not conform to C11, 
this is arguably a defect in C11.


#include 
#include 

struct s { struct s *next; char d[]; };

int
main (void)
{
  struct s *p = malloc (offsetof (struct s, d) + 1);
  p->d[0] = 1;
  return p->d[0] == 2 && p->d[1] == 3;
}

Re: Make max_align_t respect _Float128 [version 2]

[Paul Eggert]

On 09/06/2016 01:40 PM, Joseph Myers wrote:
Sounds like a defect in C11 to me - none of the examples of flexible 
array

members anticipate needing to add to the size to allow for tail padding
with unknown alignment requirements.


Yes, I would prefer calling it a defect, as most code I've seen dealing 
with flexible array members does not align the tail size. However, GCC + 
valgrind does take advantage of this "defect" and I would not be 
surprised if other picky implementations do too.


The C11 standard's examples are weird, in that their flexible members 
are typically arrays of double, where the alignment in practice is 
invariably no less than that of the containing structure so our problem 
does not occur. And for the only example that calls malloc and is 
directly on point (assuming a weird platform where doubles are 
unaligned), the associated commentary says that the flexible array 
member behaves "for most purposes" as if it had the natural size, i.e., 
all bets are off unless you read the entire standard carefully! It is 
almost as if the C11 authors knew about the problem but did not want to 
call the reader's attention to it (I doubt whether that occurred -- it's 
just that it reads that way).



C11's prohibition of using alignof on incomplete types.) This is why

Structures with flexible array members are not incomplete types.

Ah, right you are. Sorry, I confused C11 alignof with Gnulib alignof. On 
pre-C11 platforms, the Gnulib substitute alignof does not work on such 
structures, so code like Gnulib fts.c that is intended to be portable to 
pre-C11 compilers can't use that C11 feature. I have corrected the 
Gnulib manual's documentation of this limitation.

Re: Make max_align_t respect _Float128 [version 2]

[Paul Eggert]

On 09/06/2016 08:16 AM, Joseph Myers wrote:

I don't think there's any such requirement in the case of flexible array
members; if you use malloc to allocate a structure with a flexible array
member, you can access as many trailing array elements as would fit within
the allocated size, whether or not that size is a multiple of either the
alignment of the structure, or the alignment of max_align_t.


Although I would prefer you to be correct I'm afraid the standard 
doesn't agree, as C11's wording appears to allow the GCC optimization in 
question. (At least, draft N1570 does; I don't have the final standard.) 
C11 section 6.7.2.1 paragraph 18 says:


"when a . (or ->) operator has a left operand that is (a pointer to) a 
structure with a flexible array member and the right operand names that 
member, it behaves as if that member were replaced with the longest 
array (with the same element type) that would not make the structure 
larger than the object being accessed"


Suppose 'short' size and alignment is 2, and the following code 
allocates and uses 7 bytes:


  struct s { short n; char a[]; } *p = malloc (offsetof (struct s, a) + 5);

  return >a[5];

A strict reading of C11 says this code is supposed to behave as if 'char 
a[];' were replaced by 'char a[4];'. It is not the 'char a[5]' that one 
might expect, because using 'char a[5];' would mean the size of struct s 
(after alignment) would be 8, whereas the size of the object being 
accessed is only 7. Hence the above return expression has a subscript error.


One way to correct the code is to increase malloc's argument up to a 
multiple of alignof(max_align_t). (One cannot portably use 
alignof(struct s) due to C11's prohibition of using alignof on 
incomplete types.) This is why gnulib/lib/fts.c uses max_align_t.

Re: Make max_align_t respect _Float128

[Paul Eggert]

On 08/26/2016 02:45 PM, Florian Weimer wrote:
In the end, max_align_t is ignored by allocators, and applications 
cannot rely on it as a result. 


Hmm, well, in that case I suppose I should change Emacs to ignore 
max_align_t as well. Thanks for the heads-up.

Re: Make max_align_t respect _Float128

[Paul Eggert]

On 08/26/2016 01:54 PM, Joseph Myers wrote:

Such an increase is of course an ABI change, but a reasonably safe
one, in that max_align_t doesn't tend to appear in library interfaces
(rather, it's something to use when writing allocators and similar
code;


It should be fine, though I would like to mention a thin-ice area. Emacs 
uses max_align_t to infer whether malloc returns a pointer that is a 
multiple of 8, with macros like this:


  // in src/lisp.h:
  #define GCALIGNMENT 8

  // in src/alloc.c:
  #define MALLOC_IS_GC_ALIGNED (__alignof__ (max_align_t) % GCALIGNMENT 
== 0)


If __alignof__ (max_align_t) is greater than malloc alignment, the 
assumption behind the above code is wrong, i.e., MALLOC_IS_GC_ALIGNED 
might return 1 even though the correct value is 0. As it happens, Emacs 
will work on x86 since GCALIGNMENT is 8; but if GCALIGNMENT were 
increased to 16 the definition of MALLOC_IS_GC_ALIGNED would become 
incorrect with the proposed GCC patch.



(I think glibc malloc alignment should also increase to 16-byte on
32-bit x86 so it works for allocating objects of these types, which is
now straightforward given the fix made for 32-bit powerpc.)


Yes. I hope the above note helps explain why malloc alignment should be 
at least max_align_t.



OK to commit?


For what it's worth, it looks good to me.


[in your followup email]


Well, the patch could use __SIZEOF_FLOAT128__ just as well as __i386__
(the effect would be an extra union member


s/union/struct/. Though I've always wondered why it is a struct and not 
a union. Maybe change it to union while we're doing an ABI change anyway?

Re: [C/C++ PATCH] Implement -Wshift-negative-value (PR c/65179)

[Paul Eggert]

On 05/08/2015 09:59 AM, Joseph Myers wrote:

Paul, although glibc's copy of parts of tzcode is a bit out of date, it
looks like the currenthttps://github.com/eggert/tz.git  still has the
problematic code in private.h, relying on left-shifting -1 which has
undefined behavior in C99/C11 (implementation-defined in C90, as per
DR#081).
Thanks for reporting that.  I installed the attached patch into the 
experimental tz version on github https://github.com/eggert/tz, with 
the intent that this fix propagate into the next tz release and thus 
into glibc etc.


From b8f4f998104e74fc2c4a3759317b5153e95db16e Mon Sep 17 00:00:00 2001
From: Paul Eggert egg...@cs.ucla.edu
Date: Fri, 8 May 2015 14:47:40 -0700
Subject: [PATCH] Avoid left-shift-into-sign-bit undefined behavior

Problem reported by Joseph Myers in:
https://gcc.gnu.org/ml/gcc-patches/2015-05/msg00704.html
* localtime.c (detzcode, detzcode64): Don't rely on
undefined behavior with left shift into sign bit.
Port better to non-2's-complement machines.
* private.h (TWOS_COMPLEMENT, MAXVAL, MINVAL): New macros.
* private.h (time_t_min, time_t_max):
* zic.c (min_time, max_time): Use them to avoid undefined behavior.
* zdump.c (atime_shift): New constant.
(absolute_min_time, absolute_max_time):
Use it to avoid undefined behavior.
---
 localtime.c | 32 +++-
 private.h   | 23 ++-
 zdump.c |  6 --
 zic.c   |  4 ++--
 4 files changed, 47 insertions(+), 18 deletions(-)

diff --git a/localtime.c b/localtime.c
index a2d9aa8..423e13e 100644
--- a/localtime.c
+++ b/localtime.c
@@ -216,22 +216,44 @@ detzcode(const char *const codep)
 {
 	register int_fast32_t	result;
 	register int		i;
+	int_fast32_t one = 1;
+	int_fast32_t halfmaxval = one  (32 - 2);
+	int_fast32_t maxval = halfmaxval - 1 + halfmaxval;
+	int_fast32_t minval = -1 - maxval;
 
-	result = (codep[0]  0x80) ? -1 : 0;
-	for (i = 0; i  4; ++i)
+	result = codep[0]  0x7f;
+	for (i = 1; i  4; ++i)
 		result = (result  8) | (codep[i]  0xff);
+
+	if (codep[0]  0x80) {
+	  /* Do two's-complement negation even on non-two's-complement machines.
+	 If the result would be minval - 1, return minval.  */
+	  result -= !TWOS_COMPLEMENT(int_fast32_t)  result != 0;
+	  result += minval;
+	}
 	return result;
 }
 
 static int_fast64_t
 detzcode64(const char *const codep)
 {
-	register int_fast64_t result;
+	register uint_fast64_t result;
 	register int	i;
+	int_fast64_t one = 1;
+	int_fast64_t halfmaxval = one  (64 - 2);
+	int_fast64_t maxval = halfmaxval - 1 + halfmaxval;
+	int_fast64_t minval = -TWOS_COMPLEMENT(int_fast64_t) - maxval;
 
-	result = (codep[0]  0x80) ? -1 : 0;
-	for (i = 0; i  8; ++i)
+	result = codep[0]  0x7f;
+	for (i = 1; i  8; ++i)
 		result = (result  8) | (codep[i]  0xff);
+
+	if (codep[0]  0x80) {
+	  /* Do two's-complement negation even on non-two's-complement machines.
+	 If the result would be minval - 1, return minval.  */
+	  result -= !TWOS_COMPLEMENT(int_fast64_t)  result != 0;
+	  result += minval;
+	}
 	return result;
 }
 
diff --git a/private.h b/private.h
index 61cf922..f277e7a 100644
--- a/private.h
+++ b/private.h
@@ -472,15 +472,20 @@ time_t time2posix_z(timezone_t, time_t) ATTRIBUTE_PURE;
 #define TYPE_SIGNED(type) (((type) -1)  0)
 #endif /* !defined TYPE_SIGNED */
 
-/* The minimum and maximum finite time values.  */
-static time_t const time_t_min =
-  (TYPE_SIGNED(time_t)
-   ? (time_t) -1  (CHAR_BIT * sizeof (time_t) - 1)
-   : 0);
-static time_t const time_t_max =
-  (TYPE_SIGNED(time_t)
-   ? - (~ 0  0) - ((time_t) -1  (CHAR_BIT * sizeof (time_t) - 1))
-   : -1);
+#define TWOS_COMPLEMENT(t) ((t) ~ (t) 0  0)
+
+/* Max and min values of the integer type T, of which only the bottom
+   B bits are used, and where the highest-order used bit is considered
+   to be a sign bit if T is signed.  */
+#define MAXVAL(t, b)		\
+  ((t) (((t) 1  ((b) - 1 - TYPE_SIGNED(t)))			\
+	- 1 + ((t) 1  ((b) - 1 - TYPE_SIGNED(t)
+#define MINVAL(t, b)		\
+  ((t) (TYPE_SIGNED(t) ? - TWOS_COMPLEMENT(t) - MAXVAL(t, b) : 0))
+
+/* The minimum and maximum finite time values.  This assumes no padding.  */
+static time_t const time_t_min = MINVAL(time_t, TYPE_BIT(time_t));
+static time_t const time_t_max = MAXVAL(time_t, TYPE_BIT(time_t));
 
 #ifndef INT_STRLEN_MAXIMUM
 /*
diff --git a/zdump.c b/zdump.c
index 13bbb0e..adb806c 100644
--- a/zdump.c
+++ b/zdump.c
@@ -246,13 +246,15 @@ extern int	optind;
 extern char *	tzname[2];
 
 /* The minimum and maximum finite time values.  */
+enum { atime_shift = CHAR_BIT * sizeof (time_t) - 2 };
 static time_t const absolute_min_time =
   ((time_t) -1  0
-   ? (time_t) -1  (CHAR_BIT * sizeof (time_t) - 1)
+   ? (- ((time_t) ~ (time_t) 0  0)
+  - (((time_t) 1  atime_shift) - 1 + ((time_t) 1  atime_shift)))
: 0);
 static time_t const absolute_max_time =
   ((time_t) -1  0
-   ? - (~ 0  0) - ((time_t) -1  (CHAR_BIT * sizeof (time_t) - 1))
+   ? (((time_t) 1  atime_shift) - 1 + ((time_t) 1

Re: [PATCH] __attribute__ ((malloc)) doc fix (PR other/56955)

[Paul Eggert]

Richard Biener wrote:

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


Sure.  I've filed a clarified version on PR 56955 and am attaching it 
here for convenience.
Index: gcc/ChangeLog
===
--- gcc/ChangeLog   (revision 210804)
+++ gcc/ChangeLog   (working copy)
@@ -1,3 +1,10 @@
+2014-05-22  Paul Eggert  egg...@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-22  Richard Biener  rguent...@suse.de
 
* tree-ssa-alias.c (ref_maybe_used_by_call_p_1): Handle
Index: gcc/doc/extend.texi
===
--- gcc/doc/extend.texi (revision 210804)
+++ gcc/doc/extend.texi (working copy)
@@ -3207,15 +3207,17 @@
 
 @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 the pointer @var{P} returned by the function cannot alias any
+other pointer valid when the function returns, and moreover no
+pointers to valid objects occur in any storage addressed by @var{P}.
 
+Using this attribute can improve 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.
+
 @item mips16/nomips16
 @cindex @code{mips16} attribute
 @cindex @code{nomips16} attribute

[PATCH] __attribute__ ((malloc)) doc fix (PR other/56955)

[Paul Eggert]

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.
Index: gcc/ChangeLog
===
--- gcc/ChangeLog	(revision 210629)
+++ gcc/ChangeLog	(working copy)
@@ -1,3 +1,10 @@
+2014-05-20  Paul Eggert  egg...@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 d...@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