Re: libelf gelf_newehdr and gelf_newphdr return types

[Mark Wielaard <mark at klomp dot org>]

On Tue, Dec 06, 2016 at 09:45:31AM -0700, Ali Bahrami wrote:
> > Which is slightly horrible. But neither the Solaris documentation, nor
> > the elfutils libelf documentation seem to actually make any promise
> > about the return value. It is only implied that, like all gelf
> > functions, zero will be returned on failure.
> > 
> > I wanted to update the elfutils gelf documentation for these functions
> > to state that the returned pointer is to the appropriate header for the
> > ELF class. Which I believe is the only sane thing to do. I don't know of
> > any libelf implementation where the comment from dwz is true.
> 
>    I'm not aware of libelf implementations where the return
> value isn't the pointer to the underlying class specific
> header, but I suppose that there could be one.
> 
> I never thought I'd argue against clarifying documentation,
> but I'm not sure that making this any more explicit is really
> helping anyone. It really doesn't make sense that a library
> that exists to provide class independent access to objects
> returns a class dependent pointer, and I think the intent
> really is that callers only pay attention to 0 vs non-zero.
> Perhaps the documentation should just say that, while the
> internals return the pointer as they always have, to maintain
> compatibility with the past.

Grin. I am not sure that will deter people from assuming
what it really points to. But OK, I'll only document that
NULL means failure.

Cheers,

Mark