Now has example of dwarf_validate_die_sibling()

even though that is not something one
needs to use.
This is all essentially documentation changes.
Ready for release.
	modified:   doc/checkexamples.c
	modified:   doc/libdwarf.dox
	modified:   doc/libdwarf.pdf
	modified:   src/lib/libdwarf/libdwarf.h

Author: davea42

doc/checkexamples.c

@@ -384,6 +384,109 @@ void example5(Dwarf_Die in_die)
 }
 /*! @endcode */
 
+/*! @defgroup example_sibvalid using dwarf_validate_die_sibling
+    @brief A DIE tree validation.
+
+    Here we show how one uses
+    dwarf_validate_die_sibling().
+    Dwarfdump uses this function as a part of its
+    valdation of DIE trees.
+
+    It is not something you need to use.
+    But one must use it in a specific pattern
+    for it to work properly.
+
+    dwarf_validate_die_sibling() depends on data set
+    by dwarf_child() preceeding dwarf_siblingof_b() .
+    dwarf_child() records a little bit
+    of information invisibly in the Dwarf_Debug data.
+
+    @code
+*/
+
+int example_sibvalid(Dwarf_Debug dbg,
+    Dwarf_Die in_die,
+    Dwarf_Error*error)
+{
+    int        cres = DW_DLV_OK;
+    int        sibres = DW_DLV_OK;
+    Dwarf_Die  die = 0;
+    Dwarf_Die  sibdie = 0;
+    Dwarf_Die  child = 0;
+    Dwarf_Bool is_info = dwarf_get_die_infotypes_flag(die);
+
+    die = in_die;
+    for ( ; die ; die = sibdie) {
+        int vres = 0;
+        Dwarf_Unsigned offset = 0;
+
+        /* Maybe print something you extract from the DIE */
+        cres = dwarf_child(die,&child,error);
+        if (cres == DW_DLV_ERROR) {
+            if (die != in_die) {
+                dwarf_dealloc_die(die);
+            }
+            printf("dwarf_child ERROR\n");
+            return DW_DLV_ERROR;
+        }
+        if (cres == DW_DLV_OK) {
+            int lres = 0;
+
+            child = 0;
+            lres = example_sibvalid(dbg,child,error);
+            if (lres == DW_DLV_ERROR) {
+                if (die != in_die) {
+                    dwarf_dealloc_die(die);
+                }
+                dwarf_dealloc_die(child);
+                printf("example_sibvalid ERROR\n");
+                return lres;
+            }
+        }
+        sibdie = 0;
+        sibres = dwarf_siblingof_b(dbg,die,is_info,
+            &sibdie,error);
+        if (sibres == DW_DLV_ERROR) {
+            if (die != in_die) {
+                dwarf_dealloc_die(die);
+            }
+            if (child) {
+                dwarf_dealloc_die(child);
+            }
+            printf("dwarf_siblinof_b ERROR\n");
+            return DW_DLV_ERROR;
+        }
+        if (sibres == DW_DLV_NO_ENTRY) {
+            if (die != in_die) {
+                dwarf_dealloc_die(die);
+            }
+            if (child) {
+                dwarf_dealloc_die(child);
+            }
+            return DW_DLV_OK;
+        }
+        vres = dwarf_validate_die_sibling(sibdie,&offset);
+        if (vres == DW_DLV_ERROR) {
+            if (die != in_die) {
+                dwarf_dealloc_die(die);
+            }
+            if (child) {
+                dwarf_dealloc_die(child);
+            }
+            dwarf_dealloc_die(sibdie);
+            printf("Invalid sibling DIE\n");
+            return DW_DLV_ERROR;
+        }
+        /*  loop again */
+        if (die != in_die) {
+            dwarf_dealloc_die(die);
+        }
+        die = 0;
+    }
+    return DW_DLV_OK;
+}
+/*! @endcode */
+
 /*! @defgroup examplecuhdr Example walking CUs
 
     @brief Accessing all CUs looking for specific items.
@@ -824,7 +927,7 @@ int example_discr_list(Dwarf_Debug dbg,
     This example simply *assumes* the attribute
     has a form which relates to location lists
     or location expressions. Use dwarf_get_form_class()
-    to determine if this attribute fits. 
+    to determine if this attribute fits.
     Use dwarf_get_version_of_die() to help get the
     data you need.
     @see dwarf_get_form_class
@@ -1293,7 +1396,7 @@ int exampleg(Dwarf_Debug dbg, Dwarf_Error *error)
 
     This section is an SGI/MIPS extension, not created
     by modern compilers.
-    You 
+    You
 
     @code
 */
@@ -1305,7 +1408,7 @@ int exampleh(Dwarf_Debug dbg,Dwarf_Error *error)
     int           res = 0;
 
     res = dwarf_globals_by_type(dbg,DW_GL_WEAKS,
-        &weaks,&count,error); 
+        &weaks,&count,error);
     if (res != DW_DLV_OK) {
         return res;
     }
@@ -1333,7 +1436,7 @@ int examplej(Dwarf_Debug dbg, Dwarf_Error*error)
     int fres = 0;
 
     fres = dwarf_globals_by_type(dbg,DW_GL_FUNCS,
-            &funcs,&count,error);
+        &funcs,&count,error);
     if (fres != DW_DLV_OK) {
         return fres;
     }
@@ -1361,7 +1464,7 @@ int examplel(Dwarf_Debug dbg, Dwarf_Error *error)
     int res = 0;
 
     res = dwarf_globals_by_type(dbg,DW_GL_TYPES,
-            &types,&count,error);
+        &types,&count,error);
     if (res != DW_DLV_OK) {
         return res;
     }
@@ -1389,7 +1492,7 @@ int examplen(Dwarf_Debug dbg,Dwarf_Error *error)
     int res = 0;
 
     res = dwarf_globals_by_type(dbg,DW_GL_VARS,
-            &vars,&count,error);
+        &vars,&count,error);
     if (res != DW_DLV_OK) {
         return res;
     }
@@ -2448,9 +2551,9 @@ int examplehighpc(Dwarf_Die die,
     enum Dwarf_Form_Class formclass = DW_FORM_CLASS_UNKNOWN;
 
     res = dwarf_highpc_b(die,&localhighpc,
-         &form,&formclass, error);
+        &form,&formclass, error);
     if (res != DW_DLV_OK) {
-         return res;
+        return res;
     }
     if (form != DW_FORM_addr &&
         !dwarf_addr_form_is_indexed(form)) {
@@ -2460,7 +2563,7 @@ int examplehighpc(Dwarf_Die die,
             DW_AT_low_pc. */
         res = dwarf_lowpc(die,&low_pc,error);
         if (res != DW_DLV_OK) {
-            return res; 
+            return res;
         } else  {
             localhighpc += low_pc;
         }
@@ -2470,7 +2573,6 @@ int examplehighpc(Dwarf_Die die,
 }
 /*! @endcode */
 
-
 /*! @defgroup exampleza Reading Split Dwarf (Debug Fission) data
     @brief Example getting cu/tu name, offset
 

doc/libdwarf.dox

@@ -3,7 +3,7 @@
     @tableofcontents{HTML:3,LaTeX:3}
     @author David Anderson
     @copyright  This work is licensed under the Creative Commons Attribution 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by/4.0/ or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
-    @date 2023-04-27 v0.7.0
+    @date 2023-05-20 v0.7.0
 
     @section draft Suggestions for improvement are welcome.
 
@@ -907,6 +907,8 @@
 
     <b>Changes 0.6.0 to 0.7.0</b>
 
+    v0.7.0 released 2023-05-20 
+
     Elf section counts can exceed 16 bits 
     (on linux see <b>man 5 elf</b>)
     so some function prototype members 
@@ -919,7 +921,10 @@
     instead of Dwarf_Half.
     Without this change executables/objects
     with more than 64K sections cannot
-    be read by libdwarf.
+    be read by libdwarf.  This is unlikely
+    to affect your code since for most users
+    libdwarf takes care of this and dwarfdump
+    is aware of this change.
 
     Two functions have been removed from libdwarf.h
     and the library: dwarf_dnames_abbrev_by_code()

doc/libdwarf.pdf

@@ -2227,13 +2227,25 @@ DW_API int dwarf_die_abbrev_code(Dwarf_Die dw_die);
 DW_API int dwarf_die_abbrev_children_flag(Dwarf_Die dw_die,
     Dwarf_Half * dw_ab_has_child);
 
-/*!  @brief Validate a sibling DIE.
+/*! @brief Validate a sibling DIE.
 
     This is used by dwarfdump (when
-    dwarfdump is checking for valid DWARF but
-    it depends on the caller to have done
-    precise setup. Ignore it or read the comments
-    for this function in dwarf_die_deliv.c.
+    dwarfdump is checking for valid DWARF)
+    to try to catch a corrupt DIE tree.
+
+    @see example_sibvalid
+
+    @param dw_sibling
+    Pass in a DIE returned by dwarf_siblingof_b().
+    @param dw_offset
+    Set to zero through the pointer.
+    @return
+    Returns DW_DLV_OK if the sibling is
+    at an appropriate place in the section. 
+    Otherwise it returns DW_DLV_ERROR indicating
+    the DIE tree is corrupt.
+
+
 */
 DW_API int dwarf_validate_die_sibling(Dwarf_Die dw_sibling,
     Dwarf_Off* dw_offset);