diff options
Diffstat (limited to 'libdwarf/dwarf_next_cu_header.3')
| -rw-r--r-- | libdwarf/dwarf_next_cu_header.3 | 210 |
1 files changed, 148 insertions, 62 deletions
diff --git a/libdwarf/dwarf_next_cu_header.3 b/libdwarf/dwarf_next_cu_header.3 index 5be00b8ec4ee..f172322daa48 100644 --- a/libdwarf/dwarf_next_cu_header.3 +++ b/libdwarf/dwarf_next_cu_header.3 @@ -1,4 +1,4 @@ -.\" Copyright (c) 2010 Kai Wang +.\" Copyright (c) 2010,2014 Kai Wang .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -22,14 +22,15 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.\" $Id: dwarf_next_cu_header.3 2074 2011-10-27 03:34:33Z jkoshy $ +.\" $Id: dwarf_next_cu_header.3 3128 2014-12-21 20:06:22Z jkoshy $ .\" -.Dd July 24, 2010 +.Dd December 21, 2014 .Os .Dt DWARF_NEXT_CU_HEADER 3 .Sh NAME .Nm dwarf_next_cu_header , -.Nm dwarf_next_cu_header_b +.Nm dwarf_next_cu_header_b , +.Nm dwarf_next_cu_header_c .Nd step through compilation units in a DWARF debug context .Sh LIBRARY .Lb libdwarf @@ -57,33 +58,71 @@ .Fa "Dwarf_Unsigned *cu_next_offset" .Fa "Dwarf_Error *err" .Fc +.Ft int +.Fo dwarf_next_cu_header_c +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Bool is_info" +.Fa "Dwarf_Unsigned *cu_length" +.Fa "Dwarf_Half *cu_version" +.Fa "Dwarf_Off *cu_abbrev_offset" +.Fa "Dwarf_Half *cu_pointer_size" +.Fa "Dwarf_Half *cu_offset_size" +.Fa "Dwarf_Half *cu_extension_size" +.Fa "Dwarf_Sig8 *type_signature" +.Fa "Dwarf_Unsigned *type_offset" +.Fa "Dwarf_Unsigned *cu_next_offset" +.Fa "Dwarf_Error *err" +.Fc .Sh DESCRIPTION -These functions are used to step through compilation unit contexts +These functions are used to step through compilation or type units associated with a DWARF debug context, optionally returning information about the unit. .Pp Function -.Fn dwarf_next_cu_header_b +.Fn dwarf_next_cu_header_c is the API recommended for new application code. +Function +.Fn dwarf_next_cu_header +and +.Fn dwarf_next_cu_header_b +can only operate on compilation units associated with the +.Dq \&.debug_info +section. +They are less general than function +.Fn dwarf_next_cu_header_c , +and are deprecated for use by new application code. +.Pp Argument .Ar dbg should reference a DWARF debug context allocated using .Xr dwarf_init 3 . +If argument +.Ar is_info +is set to 1, +the function returns information for compilation units found in the +.Dq \&.debug_info +section. +If argument +.Ar is_info +is set to 0, +the function returns information for type units found in the +.Dq \&.debug_types +sections. Argument .Ar cu_length should point to a location that will be set to the -length of the compilation unit. +length of the compilation or type unit. Argument .Ar cu_version should point to a location that will be set to the -version number for the compilation unit. +version number for the compilation or type unit. Argument .Ar cu_abbrev_offset should point to a location that will be set to the starting offset (in the .Dq .debug_abbrev section) of the set of debugging information entry abbreviations -associated with this compilation unit. +associated with this compilation or type unit. Argument .Ar cu_pointer_size should point to a location that will be set to the @@ -92,7 +131,7 @@ underlying object being debugged. Argument .Ar cu_offset_size should point to a location that will be set to the -size in bytes for a DWARF offset in the compilation unit. +size in bytes for a DWARF offset in the compilation or type unit. Argument .Ar cu_extension_size is only needed for processing MIPS/IRIX objects that use @@ -100,10 +139,26 @@ a non-standard DWARF format. It should point to a location that will be set to 4 for normal objects and to 0 for non-standard ones. Argument +.Ar type_signature +and +.Ar type_offset +is only needed for processing type units. +Argument +.Ar type_signature +should point to a location that will be set to the 64-bit unique signature +of the type described in the type unit. +Argument +.Ar type_offset +should point to a location that will be set to the offset of the debugging +information entry that describes the type. +Argument .Ar cu_next_offset should point to a location that will be set to the offset of the next compilation unit header in the .Dq \&.debug_info +section, +or the offset of the next type unit header in the +.Dq \&.debug_types section. Argument .Ar err @@ -111,42 +166,23 @@ should point to a location that will hold an error descriptor in case of an error. .Pp Function +.Fn dwarf_next_cu_header_b +is identical to function +.Fn dwarf_next_cu_header_c +except that it does not provide arguments +.Ar is_info , +.Ar type_signature +and +.Ar type_offset . +.Pp +Function .Fn dwarf_next_cu_header -is less general than -.Fn dwarf_next_cu_header_b , -and is deprecated for use by new application code. -Argument -.Ar dbg -should reference a DWARF debug context allocated using -.Xr dwarf_init 3 . -Argument -.Ar cu_length -should point to a location that will be set to the -length of the compilation unit. -Argument -.Ar cu_version -should point to a location that will be set to the -version number for the compilation unit. -Argument -.Ar cu_abbrev_offset -should point to a location that will be set to the -starting offset in the -.Dq .debug_abbrev -section of the set of debugging information entry abbreviations -associated with this compilation unit. -Argument -.Ar cu_pointer_size -should point to a location that will be set to the -size of an address in bytes for the machine architecture of the -underlying debugging object. -Argument -.Ar cu_next_offset -should point to a location that will be set to the -offset of the next compilation unit. -Argument -.Ar err -should point to a location that will hold an error descriptor in case -of an error. +is identical to function +.Fn dwarf_next_cu_header_b +except that it does not provide arguments +.Ar cu_offset_size +and +.Ar cu_extension_size . .Pp A value of NULL may be used for any of the arguments .Ar cu_length , @@ -155,30 +191,79 @@ A value of NULL may be used for any of the arguments .Ar cu_pointer_size , .Ar cu_offset_size , .Ar cu_extension_size , +.Ar type_signature , +.Ar type_offset , .Ar cu_next_offset and .Ar err if the caller is not interested in the respective value. .Ss Iterating Through Compilation Units in a Debug Context .Pp -The first call to functions -.Fn dwarf_next_cu_header_b -and -.Fn dwarf_next_cu_header -for a given debug context will return information about the first -compilation unit in the debug context. -Subsequent calls to these functions will iterate through the remaining -compilation units in the debug context. -On stepping past the last compilation unit in the debug context, -functions -.Fn dwarf_next_cu_header -and -.Fn dwarf_next_cu_header_b -return +The first call to function +.Fn dwarf_next_cu_header_c +for a given debug context with argument +.Ar is_info +set to 1 will return information about the first +compilation unit in the +.Dq \&.debug_info +section. +Subsequent calls to the function will iterate through the remaining +compilation units in the section. +On stepping past the last compilation unit in the section, +function +.Fn dwarf_next_cu_header_c +returns +.Dv DW_DLV_NO_ENTRY +and resets its internal state. +The next call to the function will restart from the first compilation +unit in the section. +.Ss Iterating Through Type Units in a Debug Context +When a DWARF debug context is allocated using +.Xr dwarf_init 3 , +an internal pointer assoicated with the context will point to the +fisrt +.Dq \&.debug_types +section found in the debug object. +The first call to function +.Fn dwarf_next_cu_header_c +for the debug context with argument +.Ar is_info +set to 0 will return information about the first +type unit in that +.Dq \&.debug_types +section. +Subsequent calls to the function will iterate through the remaining +type units in the section. +On stepping past the last type unit in the debug context, +function +.Fn dwarf_next_cu_header_c +returns +.Dv DW_DLV_NO_ENTRY +and resets its internal state. +The next call to the function will restart from the first type +unit in the +.Dq \&.debug_types +section. +.Pp +If the debug object contains multiple +.Dq \&.debug_types +sections, the function +.Fn dwarf_next_types_section +can be called to move the internal pointer to the next +.Dq \&.debug_types +section. +As a result, subsequent calls of the function +.Fn dwarf_next_cu_header_c +will operate on the new +.Dq \&.debug_types +section. +Function +.Fn dwarf_next_types_section +returns .Dv DW_DLV_NO_ENTRY -and reset their internal state. -The next call to these functions will restart from the first compilation -unit in the debug context. +when there are no more +.Dq \&.debug_types +sections left in the debug object. .Sh RETURN VALUES On success, these functions return .Dv DW_DLV_OK . @@ -200,4 +285,5 @@ was NULL. .Xr dwarf 3 , .Xr dwarf_get_cu_die_offset_given_cu_header_offset 3 , .Xr dwarf_init 3 , +.Xr dwarf_next_types_section 3 , .Xr dwarf_siblingof 3 |