Re: [Elftoolchain-developers] a detailed example of libelf and libdwarf as "the APIs to nowhere" and two suggestions for improvement in their documentation

[Joseph K. <jk...@us...>]

dw> Here I elaborate on my point in calling libelf and libdwarf the APIs
dw> to nowhere using a detailed example.
...
dw> The p_offset field looks promising, but what is it an offset from
dw> *exactly*.  Do I really just seek from the start of the file?

The semantics of the p_offset field is documented in a number
of places.

1. In the elf(5) manual page (in *BSD).

% man 5 elf
...
   p_offset  This member holds the offset from the beginning of the
                  file at which the first byte of the segment resides.

2. Chapter 4 of the "Libelf by Example" tutorial, both in the text and
   in diagrams (figure 4.1)

3. Comments in the headers.


dw> Hmm, this is interesting.  I think your comments are off by one: read
dw> each comment and pair it carefully with the name of its field.  From
dw> common/elfdefinitions.h:

Fixed in r3077, thanks for the bug report.

dw> Libdwarf presents many more elaborate examples of the above
dw> situation, some of which I have yet to solve.

True.  We need a guide to the libdwarf API in the short term.

For the long term it may be worth investing effort in designing a
cleaner API---perhaps after the 1.0 release.

Regards,
Joseph Koshy