libdwarf
Macros | Functions
Locations of data: DWARF2-DWARF5

Macros

#define DW_LKIND_expression   0 /* DWARF2,3,4,5 */
 
#define DW_LKIND_loclist   1 /* DWARF 2,3,4 */
 
#define DW_LKIND_GNU_exp_list   2 /* GNU DWARF4 .dwo extension */
 
#define DW_LKIND_loclists   5 /* DWARF5 loclists */
 
#define DW_LKIND_unknown   99
 

Functions

int dwarf_get_loclist_c (Dwarf_Attribute dw_attr, Dwarf_Loc_Head_c *dw_loclist_head, Dwarf_Unsigned *dw_locentry_count, Dwarf_Error *dw_error)
 Location Lists and Expressions. More...
 
int dwarf_get_loclist_head_kind (Dwarf_Loc_Head_c dw_loclist_head, unsigned int *dw_lkind, Dwarf_Error *dw_error)
 Know what kind of location data it is. More...
 
int dwarf_get_locdesc_entry_d (Dwarf_Loc_Head_c dw_loclist_head, Dwarf_Unsigned dw_index, Dwarf_Small *dw_lle_value_out, Dwarf_Unsigned *dw_rawlowpc, Dwarf_Unsigned *dw_rawhipc, Dwarf_Bool *dw_debug_addr_unavailable, Dwarf_Addr *dw_lowpc_cooked, Dwarf_Addr *dw_hipc_cooked, Dwarf_Unsigned *dw_locexpr_op_count_out, Dwarf_Locdesc_c *dw_locentry_out, Dwarf_Small *dw_loclist_source_out, Dwarf_Unsigned *dw_expression_offset_out, Dwarf_Unsigned *dw_locdesc_offset_out, Dwarf_Error *dw_error)
 Retrieve the details of a location expression. More...
 
int dwarf_get_location_op_value_c (Dwarf_Locdesc_c dw_locdesc, Dwarf_Unsigned dw_index, Dwarf_Small *dw_operator_out, Dwarf_Unsigned *dw_operand1, Dwarf_Unsigned *dw_operand2, Dwarf_Unsigned *dw_operand3, Dwarf_Unsigned *dw_offset_for_branch, Dwarf_Error *dw_error)
 Get the raw values from a single location operation. More...
 
int dwarf_loclist_from_expr_c (Dwarf_Debug dw_dbg, Dwarf_Ptr dw_expression_in, Dwarf_Unsigned dw_expression_length, Dwarf_Half dw_address_size, Dwarf_Half dw_offset_size, Dwarf_Half dw_dwarf_version, Dwarf_Loc_Head_c *dw_loc_head, Dwarf_Unsigned *dw_listlen, Dwarf_Error *dw_error)
 Generate a Dwarf_Loc_Head_c from an expression block. More...
 
void dwarf_dealloc_loc_head_c (Dwarf_Loc_Head_c dw_head)
 Dealloc (free) all memory allocated for Dwarf_Loc_Head_c. More...
 
int dwarf_load_loclists (Dwarf_Debug dw_dbg, Dwarf_Unsigned *dw_loclists_count, Dwarf_Error *dw_error)
 Load Loclists. More...
 
int dwarf_get_loclist_offset_index_value (Dwarf_Debug dw_dbg, Dwarf_Unsigned dw_context_index, Dwarf_Unsigned dw_offsetentry_index, Dwarf_Unsigned *dw_offset_value_out, Dwarf_Unsigned *dw_global_offset_value_out, Dwarf_Error *dw_error)
 Return certain loclists offsets. More...
 
int dwarf_get_loclist_head_basics (Dwarf_Loc_Head_c dw_head, Dwarf_Small *dw_lkind, Dwarf_Unsigned *dw_lle_count, Dwarf_Unsigned *dw_loclists_version, Dwarf_Unsigned *dw_loclists_index_returned, Dwarf_Unsigned *dw_bytes_total_in_rle, Dwarf_Half *dw_offset_size, Dwarf_Half *dw_address_size, Dwarf_Half *dw_segment_selector_size, Dwarf_Unsigned *dw_overall_offset_of_this_context, Dwarf_Unsigned *dw_total_length_of_this_context, Dwarf_Unsigned *dw_offset_table_offset, Dwarf_Unsigned *dw_offset_table_entrycount, Dwarf_Bool *dw_loclists_base_present, Dwarf_Unsigned *dw_loclists_base, Dwarf_Bool *dw_loclists_base_address_present, Dwarf_Unsigned *dw_loclists_base_address, Dwarf_Bool *dw_loclists_debug_addr_base_present, Dwarf_Unsigned *dw_loclists_debug_addr_base, Dwarf_Unsigned *dw_offset_this_lle_area, Dwarf_Error *dw_error)
 Return basic data about a loclists head. More...
 
int dwarf_get_loclist_context_basics (Dwarf_Debug dw_dbg, Dwarf_Unsigned dw_index, Dwarf_Unsigned *dw_header_offset, Dwarf_Small *dw_offset_size, Dwarf_Small *dw_extension_size, unsigned int *dw_version, Dwarf_Small *dw_address_size, Dwarf_Small *dw_segment_selector_size, Dwarf_Unsigned *dw_offset_entry_count, Dwarf_Unsigned *dw_offset_of_offset_array, Dwarf_Unsigned *dw_offset_of_first_locentry, Dwarf_Unsigned *dw_offset_past_last_locentry, Dwarf_Error *dw_error)
 Return basic data about a loclists context. More...
 
int dwarf_get_loclist_lle (Dwarf_Debug dw_dbg, Dwarf_Unsigned dw_contextnumber, Dwarf_Unsigned dw_entry_offset, Dwarf_Unsigned dw_endoffset, unsigned int *dw_entrylen, unsigned int *dw_entry_kind, Dwarf_Unsigned *dw_entry_operand1, Dwarf_Unsigned *dw_entry_operand2, Dwarf_Unsigned *dw_expr_ops_blocksize, Dwarf_Unsigned *dw_expr_ops_offset, Dwarf_Small **dw_expr_opsdata, Dwarf_Error *dw_error)
 Return basic data about a loclists context entry. More...
 

Detailed Description

Function Documentation

◆ dwarf_get_loclist_c()

int dwarf_get_loclist_c ( Dwarf_Attribute  dw_attr,
Dwarf_Loc_Head_c dw_loclist_head,
Dwarf_Unsigned dw_locentry_count,
Dwarf_Error dw_error 
)

This works on DWARF2 through DWARF5.

See also
Location/expression access
Parameters
dw_attrThe attribute must refer to a location expression or a location list, so must be DW_FORM_block, DW_FORM_exprloc, or a loclist reference form..
dw_loclist_headOn success returns a pointer to the created loclist head record.
dw_locentry_countOn success returns the count of records. For an expression it will be one.
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_get_loclist_head_kind()

int dwarf_get_loclist_head_kind ( Dwarf_Loc_Head_c  dw_loclist_head,
unsigned int *  dw_lkind,
Dwarf_Error dw_error 
)
Parameters
dw_loclist_headPass in a loclist head pointer.
dw_lkindOn success returns the loclist kind through the pointer. For example DW_LKIND_expression.
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_get_locdesc_entry_d()

int dwarf_get_locdesc_entry_d ( Dwarf_Loc_Head_c  dw_loclist_head,
Dwarf_Unsigned  dw_index,
Dwarf_Small dw_lle_value_out,
Dwarf_Unsigned dw_rawlowpc,
Dwarf_Unsigned dw_rawhipc,
Dwarf_Bool dw_debug_addr_unavailable,
Dwarf_Addr dw_lowpc_cooked,
Dwarf_Addr dw_hipc_cooked,
Dwarf_Unsigned dw_locexpr_op_count_out,
Dwarf_Locdesc_c dw_locentry_out,
Dwarf_Small dw_loclist_source_out,
Dwarf_Unsigned dw_expression_offset_out,
Dwarf_Unsigned dw_locdesc_offset_out,
Dwarf_Error dw_error 
)

Cooked value means the addresses from the location description after base values applied, so they are actual addresses. debug_addr_unavailable non-zero means the record from a Split Dwarf skeleton unit could not be accessed from the .dwo section or dwp object so the cooked values could not be calculated.

Parameters
dw_loclist_headA loclist head pointer.
dw_indexPass in an index value less than dw_locentry_count .
dw_lle_value_outOn success returns the DW_LLE value applicable, such as DW_LLE_start_end .
dw_rawlowpcOn success returns the first operand in the expression (if the expression has an operand).
dw_rawhipcOn success returns the second operand in the expression. (if the expression has a second operand).
dw_debug_addr_unavailableOn success returns FALSE if the data required to calculate dw_lowpc_cooked or dw_hipc_cooked was present or TRUE if some required data was missing (for example in split dwarf).
dw_lowpc_cookedOn success and if dw_debug_addr_unavailable FALSE returns the true low address.
dw_hipc_cookedOn success and if dw_debug_addr_unavailable FALSE returns the true high address.
dw_locexpr_op_count_outOn success returns the count of operations in the expression.
dw_locentry_outOn success returns a pointer to a specific location description.
dw_loclist_source_outOn success returns the applicable DW_LKIND value.
dw_expression_offset_outOn success returns the offset of the expression in the applicable section.
dw_locdesc_offset_outOn return sets the offset to the location description offset (if that is meaningful) or zero for simple location expressions.
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_get_location_op_value_c()

int dwarf_get_location_op_value_c ( Dwarf_Locdesc_c  dw_locdesc,
Dwarf_Unsigned  dw_index,
Dwarf_Small dw_operator_out,
Dwarf_Unsigned dw_operand1,
Dwarf_Unsigned dw_operand2,
Dwarf_Unsigned dw_operand3,
Dwarf_Unsigned dw_offset_for_branch,
Dwarf_Error dw_error 
)
Parameters
dw_locdescPass in a valid Dwarf_Locdesc_c.
dw_indexPass in the operator index. zero through dw_locexpr_op_count_out-1.
dw_operator_outOn success returns the DW_OP operator, such as DW_OP_plus .
dw_operand1On success returns the value of the operand or zero.
dw_operand2On success returns the value of the operand or zero.
dw_operand3On success returns the value of the operand or zero.
dw_offset_for_branchOn success returns The byte offset of the operator within the entire expression. Useful for checking the correctness of operators that branch..
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_loclist_from_expr_c()

int dwarf_loclist_from_expr_c ( Dwarf_Debug  dw_dbg,
Dwarf_Ptr  dw_expression_in,
Dwarf_Unsigned  dw_expression_length,
Dwarf_Half  dw_address_size,
Dwarf_Half  dw_offset_size,
Dwarf_Half  dw_dwarf_version,
Dwarf_Loc_Head_c dw_loc_head,
Dwarf_Unsigned dw_listlen,
Dwarf_Error dw_error 
)

Useful if you have an expression block (from somewhere), do not have a Dwarf_Attribute available, and wish to deal with the expression.

See also
Reading a location expression
Parameters
dw_dbgThe applicable Dwarf_Debug
dw_expression_inPass in a pointer to the expression bytes.
dw_expression_lengthPass in the length, in bytes, of the expression.
dw_address_sizePass in the applicable address_size.
dw_offset_sizePass in the applicable offset size.
dw_dwarf_versionPass in the applicable dwarf version.
dw_loc_headOn success returns a pointer to a dwarf location head record for use in getting to the details of the expression.
dw_listlenOn success, sets the listlen to one.
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc.

◆ dwarf_dealloc_loc_head_c()

void dwarf_dealloc_loc_head_c ( Dwarf_Loc_Head_c  dw_head)
Parameters
dw_headA head pointer.

The caller should zero the passed-in pointer on return as it is stale at that point.

◆ dwarf_load_loclists()

int dwarf_load_loclists ( Dwarf_Debug  dw_dbg,
Dwarf_Unsigned dw_loclists_count,
Dwarf_Error dw_error 
)

This loads raw .debug_loclists (DWARF5). It is unlikely you have a reason to use this function. If CUs or DIES have been referenced in any way loading is already done. A duplicate loading attempt returns DW_DLV_OK immediately, returning dw_loclists_count filled in and does nothing else.

Doing it more than once is never necessary or harmful. There is no deallocation call made visible, deallocation happens when dwarf_finish() is called.

Parameters
dw_dbgThe applicable Dwarf_Debug.
dw_loclists_countOn success, returns the number of DWARF5 loclists contexts in the section, whether this is the first or a duplicate load.
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK if it loaded successfully or if it is a duplicate load. If no .debug_loclists present returns DW_DLV_NO_ENTRY.

◆ dwarf_get_loclist_offset_index_value()

int dwarf_get_loclist_offset_index_value ( Dwarf_Debug  dw_dbg,
Dwarf_Unsigned  dw_context_index,
Dwarf_Unsigned  dw_offsetentry_index,
Dwarf_Unsigned dw_offset_value_out,
Dwarf_Unsigned dw_global_offset_value_out,
Dwarf_Error dw_error 
)

Useful with the DWARF5 .debug_loclists section.

Parameters
dw_dbgThe Dwarf_Debug of interest.
dw_context_indexPass in the loclists context index.
dw_offsetentry_indexPass in the offset array index.
dw_offset_value_outOn success returns the offset value at offset table[dw_offsetentry_index], an offset local to this context.
dw_global_offset_value_outOn success returns the same offset value but with the offset of the table added in to form a section offset.
dw_errorThe usual error detail return pointer.
Returns
Returns DW_DLV_OK etc. If one of the indexes passed in is out of range it returns DW_DLV_NO_ENTRY.

◆ dwarf_get_loclist_head_basics()

int dwarf_get_loclist_head_basics ( Dwarf_Loc_Head_c  dw_head,
Dwarf_Small dw_lkind,
Dwarf_Unsigned dw_lle_count,
Dwarf_Unsigned dw_loclists_version,
Dwarf_Unsigned dw_loclists_index_returned,
Dwarf_Unsigned dw_bytes_total_in_rle,
Dwarf_Half dw_offset_size,
Dwarf_Half dw_address_size,
Dwarf_Half dw_segment_selector_size,
Dwarf_Unsigned dw_overall_offset_of_this_context,
Dwarf_Unsigned dw_total_length_of_this_context,
Dwarf_Unsigned dw_offset_table_offset,
Dwarf_Unsigned dw_offset_table_entrycount,
Dwarf_Bool dw_loclists_base_present,
Dwarf_Unsigned dw_loclists_base,
Dwarf_Bool dw_loclists_base_address_present,
Dwarf_Unsigned dw_loclists_base_address,
Dwarf_Bool dw_loclists_debug_addr_base_present,
Dwarf_Unsigned dw_loclists_debug_addr_base,
Dwarf_Unsigned dw_offset_this_lle_area,
Dwarf_Error dw_error 
)

Used by dwarfdump to print basic data from the data generated to look at a specific loclist context as returned by dwarf_loclists_index_get_lle_head() or dwarf_loclists_offset_get_lle_head. Here we know there was a Dwarf_Attribute so additional things are known as compared to calling dwarf_get_loclist_context_basics See DWARF5 Section 7.20 Location List Table page 243.

◆ dwarf_get_loclist_context_basics()

int dwarf_get_loclist_context_basics ( Dwarf_Debug  dw_dbg,
Dwarf_Unsigned  dw_index,
Dwarf_Unsigned dw_header_offset,
Dwarf_Small dw_offset_size,
Dwarf_Small dw_extension_size,
unsigned int *  dw_version,
Dwarf_Small dw_address_size,
Dwarf_Small dw_segment_selector_size,
Dwarf_Unsigned dw_offset_entry_count,
Dwarf_Unsigned dw_offset_of_offset_array,
Dwarf_Unsigned dw_offset_of_first_locentry,
Dwarf_Unsigned dw_offset_past_last_locentry,
Dwarf_Error dw_error 
)

Some of the same values as from dwarf_get_loclist_head_basics but here without any dependence on data derived from a CU context. Useful to print raw loclist data.

◆ dwarf_get_loclist_lle()

int dwarf_get_loclist_lle ( Dwarf_Debug  dw_dbg,
Dwarf_Unsigned  dw_contextnumber,
Dwarf_Unsigned  dw_entry_offset,
Dwarf_Unsigned  dw_endoffset,
unsigned int *  dw_entrylen,
unsigned int *  dw_entry_kind,
Dwarf_Unsigned dw_entry_operand1,
Dwarf_Unsigned dw_entry_operand2,
Dwarf_Unsigned dw_expr_ops_blocksize,
Dwarf_Unsigned dw_expr_ops_offset,
Dwarf_Small **  dw_expr_opsdata,
Dwarf_Error dw_error 
)

Useful to print raw loclist data.