propagate from branch 'com.redhat.elfutils.nickc.pending' (head 28d6423325f0cc14a133eb6b92a8c3604e437ba6)
to branch 'com.redhat.elfutils' (head 6ef48518ed8497626058574c787852bd939d46ee)
diff --git a/libdw/libdw.h b/libdw/libdw.h
index 6242d04..4720739 100644
--- a/libdw/libdw.h
+++ b/libdw/libdw.h
@@ -252,14 +252,24 @@
extern int dwarf_child (Dwarf_Die *die, Dwarf_Die *result)
__nonnull_attribute__ (2);
-/* Return sibling of given DIE. */
+/* Locates the first sibling of DIE and places it in RESULT.
+ Returns 0 if a sibling was found, -1 if something went wrong.
+ Returns 1 if no sibling could be found and, if RESULT is not
+ the same as DIE, it sets RESULT->addr to the address of the
+ (non-sibling) DIE that follows this one, or NULL if this DIE
+ was the last one in the cokmpilation unit. */
extern int dwarf_siblingof (Dwarf_Die *die, Dwarf_Die *result)
__nonnull_attribute__ (2);
/* Check whether the DIE has children. */
extern int dwarf_haschildren (Dwarf_Die *die) __nonnull_attribute__ (1);
-/* Get attributes of the DIE. */
+/* Walks the attributes of DIE, starting at the one OFFSET bytes in,
+ calling the CALLBACK function for each one. Stops if the callback
+ function ever returns a value other than DWARF_CB_OK and returns the
+ offset of the offending attribute. If the end of the attributes
+ is reached 1 is returned. If something goes wrong -1 is returned and
+ the dwarf error number is set. */
extern ptrdiff_t dwarf_getattrs (Dwarf_Die *die,
int (*callback) (Dwarf_Attribute *, void *),
void *arg, ptrdiff_t offset)