[PATCH] correct FLEXPTR_* example in comment

[PATCH] correct FLEXPTR_* example in comment

[René Scharfe]

This section is about "The FLEXPTR_* variants", so use FLEXPTR_ALLOC_STR
in the example.

Signed-off-by: Rene Scharfe <l.s.r@web.de>
---
 git-compat-util.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/git-compat-util.h b/git-compat-util.h
index 590bfdd..f52e00b 100644
--- a/git-compat-util.h
+++ b/git-compat-util.h
@@ -815,7 +815,7 @@ extern FILE *fopen_for_writing(const char *path);
  * you can do:
  *
  *   struct foo *f;
- *   FLEX_ALLOC_STR(f, name, src);
+ *   FLEXPTR_ALLOC_STR(f, name, src);
  *
  * and "name" will point to a block of memory after the struct, which will be
  * freed along with the struct (but the pointer can be repointed anywhere).
-- 
2.9.3

Re: [PATCH] correct FLEXPTR_* example in comment

[Jeff King]

On Sat, Aug 13, 2016 at 11:01:21AM +0200, René Scharfe wrote:

> This section is about "The FLEXPTR_* variants", so use FLEXPTR_ALLOC_STR
> in the example.

Oops, yeah. Your patch is clearly an improvement.

Since this is obviously an easy mistake to make (using one form rather
than the other), I wondered if the compiler would catch it.

I think it would catch an accidental use of FLEXPTR instead of FLEX,
because it involves an attempted assignment of an array. But I don't
think we would catch the reverse; we'd just write the data directly on
top of the pointer. That would probably crash immediately at runtime, so
if you exercise the code at all in tests, it is OK. But something to be
aware of.

I suppose it could assert(sizeof((x)->flexname) == FLEX_ALLOC) or
something, but I'm not sure if it is worth worrying about.

-Peff

Re: [PATCH] correct FLEXPTR_* example in comment

[René Scharfe]

Am 13.08.2016 um 11:09 schrieb Jeff King:
> On Sat, Aug 13, 2016 at 11:01:21AM +0200, René Scharfe wrote:
>
>> This section is about "The FLEXPTR_* variants", so use FLEXPTR_ALLOC_STR
>> in the example.
>
> Oops, yeah. Your patch is clearly an improvement.
>
> Since this is obviously an easy mistake to make (using one form rather
> than the other), I wondered if the compiler would catch it.
>
> I think it would catch an accidental use of FLEXPTR instead of FLEX,
> because it involves an attempted assignment of an array. But I don't
> think we would catch the reverse; we'd just write the data directly on
> top of the pointer. That would probably crash immediately at runtime, so
> if you exercise the code at all in tests, it is OK. But something to be
> aware of.
>
> I suppose it could assert(sizeof((x)->flexname) == FLEX_ALLOC) or
> something, but I'm not sure if it is worth worrying about.

A compilation error or warning would be nice.  I scratched my head quite 
a bit before figuring out that the example was wrong.  Copy&paste from a 
reputable source must be correct, right? :)

René

Re: [PATCH] correct FLEXPTR_* example in comment

[René Scharfe]

Am 13.08.2016 um 11:09 schrieb Jeff King:
> On Sat, Aug 13, 2016 at 11:01:21AM +0200, René Scharfe wrote:
>
>> This section is about "The FLEXPTR_* variants", so use FLEXPTR_ALLOC_STR
>> in the example.
>
> Oops, yeah. Your patch is clearly an improvement.
>
> Since this is obviously an easy mistake to make (using one form rather
> than the other), I wondered if the compiler would catch it.
>
> I think it would catch an accidental use of FLEXPTR instead of FLEX,
> because it involves an attempted assignment of an array.

Gcc 5.4 reports "invalid use of flexible array member".

> But I don't
> think we would catch the reverse; we'd just write the data directly on
> top of the pointer. That would probably crash immediately at runtime, so
> if you exercise the code at all in tests, it is OK. But something to be
> aware of.

No hint at compile time, segfaults at runtime.

> I suppose it could assert(sizeof((x)->flexname) == FLEX_ALLOC) or
> something, but I'm not sure if it is worth worrying about.

You can't use sizeof with an actual flexible array.  It only works if 
FLEX_ARRAY is defined as 1 (for platforms without native support), and 
perhaps also if it's 0.

offsetof(struct x, arr) == sizeof(struct x) won't work either because of 
padding.

I have no idea what you can do with a flexible array that would throw a 
compile error when done with a pointer.

René

Re: [PATCH] correct FLEXPTR_* example in comment

[Jeff King]

On Sat, Aug 13, 2016 at 07:26:02PM +0200, René Scharfe wrote:

> > I suppose it could assert(sizeof((x)->flexname) == FLEX_ALLOC) or
> > something, but I'm not sure if it is worth worrying about.
> 
> You can't use sizeof with an actual flexible array.  It only works if
> FLEX_ARRAY is defined as 1 (for platforms without native support), and
> perhaps also if it's 0.
> 
> offsetof(struct x, arr) == sizeof(struct x) won't work either because of
> padding.
> 
> I have no idea what you can do with a flexible array that would throw a
> compile error when done with a pointer.

Thanks for the input. I'd say we should not worry about it. The reason
this particular "bug" persisted is because it was in a comment. People
tend to notice code that cannot possibly do anything but segfault before
they even send in patches.

-Peff