libdwarf: Locations of data: DWARF2-DWARF5

libdwarf

Loading...
Searching...
No Matches
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
DW_API 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.
DW_API 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.
DW_API 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(_d) of a location expression.
DW_API int | dwarf_get_locdesc_entry_e (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_Unsigned *dw_lle_bytecount, 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(_e) of a location expression.
DW_API 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.
DW_API 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.
DW_API void | dwarf_dealloc_loc_head_c (Dwarf_Loc_Head_c dw_head)
| Dealloc (free) all memory allocated for Dwarf_Loc_Head_c.
DW_API int | dwarf_load_loclists (Dwarf_Debug dw_dbg, Dwarf_Unsigned *dw_loclists_count, Dwarf_Error *dw_error)
| Load Loclists.
DW_API 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.
DW_API 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.
DW_API 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.
DW_API 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.

## Detailed Description

## Function Documentation

## ◆ dwarf_dealloc_loc_head_c()

DW_API void dwarf_dealloc_loc_head_c | ( | Dwarf_Loc_Head_c | dw_head | ) |

Dealloc (free) all memory allocated for Dwarf_Loc_Head_c.

Parameters

  dw_head | A head pointer.

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

## ◆ dwarf_get_location_op_value_c()

DW_API 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.

Parameters

  dw_locdesc | Pass in a valid Dwarf_Locdesc_c.
  dw_index | Pass in the operator index. zero through dw_locexpr_op_count_out-1.
  dw_operator_out | On success returns the DW_OP operator, such as DW_OP_plus .
  dw_operand1 | On success returns the value of the operand or zero.
  dw_operand2 | On success returns the value of the operand or zero.
  dw_operand3 | On success returns the value of the operand or zero.
  dw_offset_for_branch | On success returns The byte offset of the operator within the entire expression. Useful for checking the correctness of operators that branch..
  dw_error | The usual error detail return pointer.

Returns
  Returns DW_DLV_OK etc.

## ◆ dwarf_get_locdesc_entry_d()

DW_API 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(_d) of a location expression.

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_head | A loclist head pointer.
  dw_index | Pass in an index value less than dw_locentry_count .
  dw_lle_value_out | On success returns the DW_LLE value applicable, such as DW_LLE_start_end .
  dw_rawlowpc | On success returns the first operand in the expression (if the expression has an operand).
  dw_rawhipc | On success returns the second operand in the expression. (if the expression has a second operand).
  dw_debug_addr_unavailable | On 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_cooked | On success and if dw_debug_addr_unavailable FALSE returns the true low address.
  dw_hipc_cooked | On success and if dw_debug_addr_unavailable FALSE returns the true high address.
  dw_locexpr_op_count_out | On success returns the count of operations in the expression.
  dw_locentry_out | On success returns a pointer to a specific location description.
  dw_loclist_source_out | On success returns the applicable DW_LKIND value.
  dw_expression_offset_out | On success returns the offset of the expression in the applicable section.
  dw_locdesc_offset_out | On return sets the offset to the location description offset (if that is meaningful) or zero for simple location expressions.
  dw_error | The usual error detail return pointer.

Returns
  Returns DW_DLV_OK etc.

## ◆ dwarf_get_locdesc_entry_e()

DW_API int dwarf_get_locdesc_entry_e | ( | 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_Unsigned * | dw_lle_bytecount,
|  | 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(_e) of a location expression.

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.

This is identical to dwarf_get_locdesc_entry_d except that it adds a pointer argument so the caller can know the size, in bytes, of the loclist DW_LLE operation itself.

It's used by dwarfdump but it is unlikely to be of interest to most callers..

## ◆ dwarf_get_loclist_c()

DW_API 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.

This works on DWARF2 through DWARF5.

See also
  Location/expression access

Parameters

  dw_attr | The 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_head | On success returns a pointer to the created loclist head record.
  dw_locentry_count | On success returns the count of records. For an expression it will be one.
  dw_error | The usual error detail return pointer.

Returns
  Returns DW_DLV_OK etc.

## ◆ dwarf_get_loclist_context_basics()

DW_API 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.

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_head_basics()

DW_API 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.

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_head_kind()

DW_API 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.

Parameters

  dw_loclist_head | Pass in a loclist head pointer.
  dw_lkind | On success returns the loclist kind through the pointer. For example DW_LKIND_expression.
  dw_error | The usual error detail return pointer.

Returns
  Returns DW_DLV_OK etc.

## ◆ dwarf_get_loclist_lle()

DW_API 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.

Useful to print raw loclist data.

## ◆ dwarf_get_loclist_offset_index_value()

DW_API 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.

Useful with the DWARF5 .debug_loclists section.

Parameters

  dw_dbg | The Dwarf_Debug of interest.
  dw_context_index | Pass in the loclists context index.
  dw_offsetentry_index | Pass in the offset array index.
  dw_offset_value_out | On success returns the offset value at offset table[dw_offsetentry_index], an offset local to this context.
  dw_global_offset_value_out | On success returns the same offset value but with the offset of the table added in to form a section offset.
  dw_error | The 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_load_loclists()

DW_API int dwarf_load_loclists | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Unsigned * | dw_loclists_count,
|  | Dwarf_Error * | dw_error )

Load Loclists.

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_dbg | The applicable Dwarf_Debug.
  dw_loclists_count | On success, returns the number of DWARF5 loclists contexts in the section, whether this is the first or a duplicate load.
  dw_error | The 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_loclist_from_expr_c()

DW_API 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.

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_dbg | The applicable Dwarf_Debug
  dw_expression_in | Pass in a pointer to the expression bytes.
  dw_expression_length | Pass in the length, in bytes, of the expression.
  dw_address_size | Pass in the applicable address_size.
  dw_offset_size | Pass in the applicable offset size.
  dw_dwarf_version | Pass in the applicable dwarf version.
  dw_loc_head | On success returns a pointer to a dwarf location head record for use in getting to the details of the expression.
  dw_listlen | On success, sets the listlen to one.
  dw_error | The usual error detail return pointer.

Returns
  Returns DW_DLV_OK etc.