Stack Frame Access

Functions
int	dwarf_get_fde_list (Dwarf_Debug dw_dbg, Dwarf_Cie **dw_cie_data, Dwarf_Signed *dw_cie_element_count, Dwarf_Fde **dw_fde_data, Dwarf_Signed *dw_fde_element_count, Dwarf_Error *dw_error)
	Get lists of .debug_frame FDEs and CIEs. More...
int	dwarf_get_fde_list_eh (Dwarf_Debug dw_dbg, Dwarf_Cie **dw_cie_data, Dwarf_Signed *dw_cie_element_count, Dwarf_Fde **dw_fde_data, Dwarf_Signed *dw_fde_element_count, Dwarf_Error *dw_error)
	Get lists of .eh_frame FDEs and CIEs. More...
void	dwarf_dealloc_fde_cie_list (Dwarf_Debug dw_dbg, Dwarf_Cie *dw_cie_data, Dwarf_Signed dw_cie_element_count, Dwarf_Fde *dw_fde_data, Dwarf_Signed dw_fde_element_count)
	Release storage associated with FDE and CIE arrays. More...
int	dwarf_get_fde_range (Dwarf_Fde dw_fde, Dwarf_Addr *dw_low_pc, Dwarf_Unsigned *dw_func_length, Dwarf_Small **dw_fde_bytes, Dwarf_Unsigned *dw_fde_byte_length, Dwarf_Off *dw_cie_offset, Dwarf_Signed *dw_cie_index, Dwarf_Off *dw_fde_offset, Dwarf_Error *dw_error)
	Return the FDE data for a single FDE. More...
int	dwarf_get_fde_exception_info (Dwarf_Fde dw_fde, Dwarf_Signed *dw_offset_into_exception_tables, Dwarf_Error *dw_error)
	IRIX only access to C++ destructor tables. More...
int	dwarf_get_cie_of_fde (Dwarf_Fde dw_fde, Dwarf_Cie *dw_cie_returned, Dwarf_Error *dw_error)
	Given FDE get CIE. More...
int	dwarf_get_cie_info_b (Dwarf_Cie dw_cie, Dwarf_Unsigned *dw_bytes_in_cie, Dwarf_Small *dw_version, char **dw_augmenter, Dwarf_Unsigned *dw_code_alignment_factor, Dwarf_Signed *dw_data_alignment_factor, Dwarf_Half *dw_return_address_register_rule, Dwarf_Small **dw_initial_instructions, Dwarf_Unsigned *dw_initial_instructions_length, Dwarf_Half *dw_offset_size, Dwarf_Error *dw_error)
	Given a CIE get access to its content. More...
int	dwarf_get_cie_index (Dwarf_Cie dw_cie, Dwarf_Signed *dw_index, Dwarf_Error *dw_error)
	Return CIE index given CIE. More...
int	dwarf_get_fde_instr_bytes (Dwarf_Fde dw_fde, Dwarf_Small **dw_outinstrs, Dwarf_Unsigned *dw_outlen, Dwarf_Error *dw_error)
	Return length and pointer to access frame instructions. More...
int	dwarf_get_fde_info_for_all_regs3_b (Dwarf_Fde dw_fde, Dwarf_Addr dw_pc_requested, Dwarf_Regtable3 *dw_reg_table, Dwarf_Addr *dw_row_pc, Dwarf_Bool *dw_has_more_rows, Dwarf_Addr *dw_subsequent_pc, Dwarf_Error *dw_error)
	Return information on frame registers at a given pc value. More...
int	dwarf_get_fde_info_for_all_regs3 (Dwarf_Fde dw_fde, Dwarf_Addr dw_pc_requested, Dwarf_Regtable3 *dw_reg_table, Dwarf_Addr *dw_row_pc, Dwarf_Error *dw_error)
	Return information on frame registers at a given pc value. More...
int	dwarf_get_fde_info_for_reg3_c (Dwarf_Fde dw_fde, Dwarf_Half dw_table_column, Dwarf_Addr dw_pc_requested, Dwarf_Small *dw_value_type, Dwarf_Unsigned *dw_offset_relevant, Dwarf_Unsigned *dw_register, Dwarf_Signed *dw_offset, Dwarf_Block *dw_block_content, Dwarf_Addr *dw_row_pc_out, Dwarf_Bool *dw_has_more_rows, Dwarf_Addr *dw_subsequent_pc, Dwarf_Error *dw_error)
	Return details about a particular pc and register. More...
int	dwarf_get_fde_info_for_reg3_b (Dwarf_Fde dw_fde, Dwarf_Half dw_table_column, Dwarf_Addr dw_pc_requested, Dwarf_Small *dw_value_type, Dwarf_Unsigned *dw_offset_relevant, Dwarf_Unsigned *dw_register, Dwarf_Unsigned *dw_offset, Dwarf_Block *dw_block_content, Dwarf_Addr *dw_row_pc_out, Dwarf_Bool *dw_has_more_rows, Dwarf_Addr *dw_subsequent_pc, Dwarf_Error *dw_error)
	Return details about a particular pc and register. More...
int	dwarf_get_fde_info_for_cfa_reg3_c (Dwarf_Fde dw_fde, Dwarf_Addr dw_pc_requested, Dwarf_Small *dw_value_type, Dwarf_Unsigned *dw_offset_relevant, Dwarf_Unsigned *dw_register, Dwarf_Signed *dw_offset, Dwarf_Block *dw_block, Dwarf_Addr *dw_row_pc_out, Dwarf_Bool *dw_has_more_rows, Dwarf_Addr *dw_subsequent_pc, Dwarf_Error *dw_error)
	Get the value of the CFA for a particular pc value. More...
int	dwarf_get_fde_info_for_cfa_reg3_b (Dwarf_Fde dw_fde, Dwarf_Addr dw_pc_requested, Dwarf_Small *dw_value_type, Dwarf_Unsigned *dw_offset_relevant, Dwarf_Unsigned *dw_register, Dwarf_Unsigned *dw_offset, Dwarf_Block *dw_block, Dwarf_Addr *dw_row_pc_out, Dwarf_Bool *dw_has_more_rows, Dwarf_Addr *dw_subsequent_pc, Dwarf_Error *dw_error)
	Get the value of the CFA for a particular pc value. More...
int	dwarf_get_fde_for_die (Dwarf_Debug dw_dbg, Dwarf_Die dw_subr_die, Dwarf_Fde *dw_returned_fde, Dwarf_Error *dw_error)
	Get the fde given DW_AT_MIPS_fde in a DIE. More...
int	dwarf_get_fde_n (Dwarf_Fde *dw_fde_data, Dwarf_Unsigned dw_fde_index, Dwarf_Fde *dw_returned_fde, Dwarf_Error *dw_error)
	Retrieve an FDE from an FDE table. More...
int	dwarf_get_fde_at_pc (Dwarf_Fde *dw_fde_data, Dwarf_Addr dw_pc_of_interest, Dwarf_Fde *dw_returned_fde, Dwarf_Addr *dw_lopc, Dwarf_Addr *dw_hipc, Dwarf_Error *dw_error)
	Retrieve an FDE given a pc. More...
int	dwarf_get_cie_augmentation_data (Dwarf_Cie dw_cie, Dwarf_Small **dw_augdata, Dwarf_Unsigned *dw_augdata_len, Dwarf_Error *dw_error)
	Return .eh_frame CIE augmentation data. More...
int	dwarf_get_fde_augmentation_data (Dwarf_Fde dw_fde, Dwarf_Small **dw_augdata, Dwarf_Unsigned *dw_augdata_len, Dwarf_Error *dw_error)
	Return .eh_frame FDE augmentation data. More...
int	dwarf_expand_frame_instructions (Dwarf_Cie dw_cie, Dwarf_Small *dw_instructionspointer, Dwarf_Unsigned dw_length_in_bytes, Dwarf_Frame_Instr_Head *dw_head, Dwarf_Unsigned *dw_instr_count, Dwarf_Error *dw_error)
	Expands CIE or FDE instructions for detailed examination. Called for CIE initial instructions and FDE instructions. Call dwarf_get_fde_instr_bytes() or dwarf_get_cie_info_b() to get the initial instruction bytes and instructions byte count you wish to expand. More...
int	dwarf_get_frame_instruction (Dwarf_Frame_Instr_Head dw_head, Dwarf_Unsigned dw_instr_index, Dwarf_Unsigned *dw_instr_offset_in_instrs, Dwarf_Small *dw_cfa_operation, const char **dw_fields_description, Dwarf_Unsigned *dw_u0, Dwarf_Unsigned *dw_u1, Dwarf_Signed *dw_s0, Dwarf_Signed *dw_s1, Dwarf_Unsigned *dw_code_alignment_factor, Dwarf_Signed *dw_data_alignment_factor, Dwarf_Block *dw_expression_block, Dwarf_Error *dw_error)
	Return information about a single instruction Fields_description means a sequence of up to three letters including u,s,r,c,d,b, terminated by NUL byte. It is a string but we test individual bytes instead of using string compares. Do not free any of the returned values. More...
int	dwarf_get_frame_instruction_a (Dwarf_Frame_Instr_Head dw_, Dwarf_Unsigned dw_instr_index, Dwarf_Unsigned *dw_instr_offset_in_instrs, Dwarf_Small *dw_cfa_operation, const char **dw_fields_description, Dwarf_Unsigned *dw_u0, Dwarf_Unsigned *dw_u1, Dwarf_Unsigned *dw_u2, Dwarf_Signed *dw_s0, Dwarf_Signed *dw_s1, Dwarf_Unsigned *dw_code_alignment_factor, Dwarf_Signed *dw_data_alignment_factor, Dwarf_Block *dw_expression_block, Dwarf_Error *dw_error)
	Expands CIE or FDE instructions for detailed examination. Called for CIE initial instructions and FDE instructions. This is the same as dwarf_get_frame_instruction() except that it adds a dw_u2 field which contains an address-space identifier if the letter a appears in dw_fields_description. The dw_u2 field is non-standard and only applies to Heterogeneous Debugging frame instructions defined by LLVM (DW_CFA_LLVM_def_aspace_cfa and DW_CFA_LLVM_def_aspace_cfa_sf) More...
void	dwarf_dealloc_frame_instr_head (Dwarf_Frame_Instr_Head dw_head)
	Deallocates the frame instruction data in dw_head. More...
int	dwarf_fde_section_offset (Dwarf_Debug dw_dbg, Dwarf_Fde dw_in_fde, Dwarf_Off *dw_fde_off, Dwarf_Off *dw_cie_off, Dwarf_Error *dw_error)
	Return FDE and CIE offsets from debugging info. More...
int	dwarf_cie_section_offset (Dwarf_Debug dw_dbg, Dwarf_Cie dw_in_cie, Dwarf_Off *dw_cie_off, Dwarf_Error *dw_error)
	Use to print CIE offsets from debugging info. More...
Dwarf_Half	dwarf_set_frame_rule_table_size (Dwarf_Debug dw_dbg, Dwarf_Half dw_value)
	Frame Rule Table Size Invariants for setting frame registers . More...
Dwarf_Half	dwarf_set_frame_rule_initial_value (Dwarf_Debug dw_dbg, Dwarf_Half dw_value)
	Frame Rule Initial Value. More...
Dwarf_Half	dwarf_set_frame_cfa_value (Dwarf_Debug dw_dbg, Dwarf_Half dw_value)
	Frame CFA Column Invariants for setting frame registers . More...
Dwarf_Half	dwarf_set_frame_same_value (Dwarf_Debug dw_dbg, Dwarf_Half dw_value)
	Frame Same Value Default Invariants for setting frame registers . More...
Dwarf_Half	dwarf_set_frame_undefined_value (Dwarf_Debug dw_dbg, Dwarf_Half dw_value)
	Frame Undefined Value Default Invariants for setting frame registers . More...

Detailed Description

Use to access DWARF2-5 .debug_frame and GNU .eh_frame sections. Does not evaluate frame instructions, but provides detailed data so it is possible do that yourself.

Function Documentation

dwarf_get_fde_list()

int dwarf_get_fde_list	(	Dwarf_Debug	dw_dbg,
		Dwarf_Cie **	dw_cie_data,
		Dwarf_Signed *	dw_cie_element_count,
		Dwarf_Fde **	dw_fde_data,
		Dwarf_Signed *	dw_fde_element_count,
		Dwarf_Error *	dw_error
	)

See DWARF5 Section 6.4 Call Frame Information, page 171.

See also

Extracting fde, cie lists.

The FDE array returned through dw_fde_data is sorted low-to-high by the lowest-pc in each FDE.

Parameters

dw_dbg	The Dwarf_Debug of interest.
dw_cie_data	On success returns a pointer to an array of pointers to CIE data.
dw_cie_element_count	On success returns a count of the number of elements in the dw_cie_data array.
dw_fde_data	On success returns a pointer to an array of pointers to FDE data.
dw_fde_element_count	On success returns a count of the number of elements in the dw_fde_data array. On success
dw_error	The usual error detail return pointer.

Returns

Returns DW_DLV_OK etc.

dwarf_get_fde_list_eh()

int dwarf_get_fde_list_eh	(	Dwarf_Debug	dw_dbg,
		Dwarf_Cie **	dw_cie_data,
		Dwarf_Signed *	dw_cie_element_count,
		Dwarf_Fde **	dw_fde_data,
		Dwarf_Signed *	dw_fde_element_count,
		Dwarf_Error *	dw_error
	)

The arguments are identical to the previous function, the difference is the section read. The GNU-defined .eh_frame section is very similar to .debug_frame but has unique features that matter when following a stack trace.

See also

dwarf_get_fde_list

dwarf_dealloc_fde_cie_list()

void dwarf_dealloc_fde_cie_list	(	Dwarf_Debug	dw_dbg,
		Dwarf_Cie *	dw_cie_data,
		Dwarf_Signed	dw_cie_element_count,
		Dwarf_Fde *	dw_fde_data,
		Dwarf_Signed	dw_fde_element_count
	)

Applies to .eh_frame and .debug_frame lists.

Parameters

dw_dbg	The Dwarf_Debug used in the list setup.
dw_cie_data	As returned from the list setup call.
dw_cie_element_count
dw_fde_data	As returned from the list setup call.
dw_fde_element_count	As returned from the list setup call.

On return the pointers passed in dw_cie_data and dw_fde_data should be zeroed by the caller as they are then stale pointers.

dwarf_get_fde_range()

int dwarf_get_fde_range	(	Dwarf_Fde	dw_fde,
		Dwarf_Addr *	dw_low_pc,
		Dwarf_Unsigned *	dw_func_length,
		Dwarf_Small **	dw_fde_bytes,
		Dwarf_Unsigned *	dw_fde_byte_length,
		Dwarf_Off *	dw_cie_offset,
		Dwarf_Signed *	dw_cie_index,
		Dwarf_Off *	dw_fde_offset,
		Dwarf_Error *	dw_error
	)

Parameters

dw_fde	The FDE of interest.
dw_low_pc	On success returns the low pc value for the function involved.
dw_func_length	On success returns the length of the function code in bytes.
dw_fde_bytes	On success returns a pointer to the bytes of the FDE.
dw_fde_byte_length	On success returns the length of the dw_fde_bytes area.
dw_cie_offset	On success returns the section offset of the associated CIE.
dw_cie_index	On success returns the CIE index of the associated CIE.
dw_fde_offset	On success returns the section offset of this FDE.
dw_error	The usual error detail return pointer.

Returns

Returns DW_DLV_OK etc.

dwarf_get_fde_exception_info()

int dwarf_get_fde_exception_info	(	Dwarf_Fde	dw_fde,
		Dwarf_Signed *	dw_offset_into_exception_tables,
		Dwarf_Error *	dw_error
	)

This applies only to IRIX C++ destructor information which was never documented and is unlikely to be of interest.

dwarf_get_cie_of_fde()

int dwarf_get_cie_of_fde	(	Dwarf_Fde	dw_fde,
		Dwarf_Cie *	dw_cie_returned,
		Dwarf_Error *	dw_error
	)

Parameters

dw_fde	The FDE of interest.
dw_cie_returned	On success returns a pointer to the applicable CIE.
dw_error	The usual error detail return pointer.

Returns

Returns DW_DLV_OK etc.

dwarf_get_cie_info_b()

int dwarf_get_cie_info_b	(	Dwarf_Cie	dw_cie,
		Dwarf_Unsigned *	dw_bytes_in_cie,
		Dwarf_Small *	dw_version,
		char **	dw_augmenter,
		Dwarf_Unsigned *	dw_code_alignment_factor,
		Dwarf_Signed *	dw_data_alignment_factor,
		Dwarf_Half *	dw_return_address_register_rule,
		Dwarf_Small **	dw_initial_instructions,
		Dwarf_Unsigned *	dw_initial_instructions_length,
		Dwarf_Half *	dw_offset_size,
		Dwarf_Error *	dw_error
	)

Parameters

dw_cie	Pass in the CIE of interest.
dw_bytes_in_cie	On success, returns the length of the CIE in bytes.
dw_version	On success, returns the CIE version number.
dw_augmenter	On success, returns a pointer to the augmentation string (which could be the empty string).
dw_code_alignment_factor	On success, returns a the code_alignment_factor used to interpret CIE/FDE operations.
dw_data_alignment_factor	On success, returns a the data_alignment_factor used to interpret CIE/FDE operations.
dw_return_address_register_rule	On success, returns a register number of the return address register.
dw_initial_instructions	On success, returns a pointer to the bytes of initial_instructions in the CIE.
dw_initial_instructions_length	On success, returns the length in bytes of the initial_instructions.
dw_offset_size	On success, returns the offset_size within this CIE.
dw_error	The usual error detail return pointer.

Returns

Returns DW_DLV_OK etc.

dwarf_get_cie_index()

int dwarf_get_cie_index	(	Dwarf_Cie	dw_cie,
		Dwarf_Signed *	dw_index,
		Dwarf_Error *	dw_error
	)

Parameters

dw_cie	Pass in the CIE of interest.
dw_index	On success, returns the index (the position of the CIE in the CIE pointer array).
dw_error	The usual error detail return pointer.

Returns

Returns DW_DLV_OK etc.

dwarf_get_fde_instr_bytes()

int dwarf_get_fde_instr_bytes	(	Dwarf_Fde	dw_fde,
		Dwarf_Small **	dw_outinstrs,
		Dwarf_Unsigned *	dw_outlen,
		Dwarf_Error *	dw_error
	)

See also

dwarf_expand_frame_instructions

Using dwarf_expand_frame_instructions

Parameters

dw_fde	Pass in the FDE of interest.
dw_outinstrs	On success returns a pointer to the FDE instruction byte stream.
dw_outlen	On success returns the length of the dw_outinstrs byte stream.
dw_error	The usual error detail return pointer.

Returns

Returns DW_DLV_OK etc.

dwarf_get_fde_info_for_all_regs3_b()

int dwarf_get_fde_info_for_all_regs3_b	(	Dwarf_Fde	dw_fde,
		Dwarf_Addr	dw_pc_requested,
		Dwarf_Regtable3 *	dw_reg_table,
		Dwarf_Addr *	dw_row_pc,
		Dwarf_Bool *	dw_has_more_rows,
		Dwarf_Addr *	dw_subsequent_pc,
		Dwarf_Error *	dw_error
	)

An FDE at a given pc (code address) This function is new in October 2023 version 0.9.0.

Parameters

dw_fde	Pass in the FDE of interest.
dw_pc_requested	Pass in a pc (code) address inside that FDE.
dw_reg_table	On success, returns a pointer to a struct given the frame state.
dw_row_pc	On success returns the address of the row of frame data which may be a few counts off of the pc requested.
dw_has_more_rows	On success returns FALSE if there are no more rows, otherwise returns TRUE.
dw_subsequent_pc	On success this returns the address of the next pc for which there is a register row, making access to all the rows in sequence much more efficient than just adding 1 to a pc value.
dw_error	The usual error detail return pointer.

Returns

Returns DW_DLV_OK if the dw_pc_requested is in the FDE passed in and there is some applicable row in the table.

dwarf_get_fde_info_for_all_regs3()

int dwarf_get_fde_info_for_all_regs3	(	Dwarf_Fde	dw_fde,
		Dwarf_Addr	dw_pc_requested,
		Dwarf_Regtable3 *	dw_reg_table,
		Dwarf_Addr *	dw_row_pc,
		Dwarf_Error *	dw_error
	)

Identical to dwarf_get_fde_info_for_all_regs3_b() except that this doesn't output dw_has_more_rows and dw_subsequent_pc.

If you need to iterate through all rows of the FDE, consider switching to dwarf_get_fde_info_for_all_regs3_b() as it is more efficient.

dwarf_get_fde_info_for_reg3_c()

int dwarf_get_fde_info_for_reg3_c	(	Dwarf_Fde	dw_fde,
		Dwarf_Half	dw_table_column,
		Dwarf_Addr	dw_pc_requested,
		Dwarf_Small *	dw_value_type,
		Dwarf_Unsigned *	dw_offset_relevant,
		Dwarf_Unsigned *	dw_register,
		Dwarf_Signed *	dw_offset,
		Dwarf_Block *	dw_block_content,
		Dwarf_Addr *	dw_row_pc_out,
		Dwarf_Bool *	dw_has_more_rows,
		Dwarf_Addr *	dw_subsequent_pc,
		Dwarf_Error *	dw_error
	)

It is efficient to iterate across all table_columns (registers) using this function (dwarf_get_fde_info_for_reg3_c()). Or one could instead call dwarf_get_fde_info_for_all_regs3() and index into the table it fills in.

If dw_value_type == DW_EXPR_EXPRESSION or DW_EXPR_VALUE_EXPRESSION dw_offset is not set and the caller must evaluate the expression, which usually depends on runtime frame data which cannot be calculated without a stack frame including registers (etc).

dwarf_get_fde_info_for_reg3_c() is new in libdwarf 0.8.0. It corrects the incorrect type of the dw_offset argument in dwarf_get_fde_info_for_reg3_b(). Both versions operate correctly.

Parameters

dw_fde	Pass in the FDE of interest.
dw_table_column	Pass in the table_column, column numbers in the table are 0 through the number_of_registers-1.
dw_pc_requested	Pass in the pc of interest within dw_fde.
dw_value_type	On success returns the value type, a DW_EXPR value. For example DW_EXPR_EXPRESSION
dw_offset_relevant	On success returns FALSE if the offset value is irrelevant, otherwise TRUE.
dw_register	On success returns a register number.
dw_offset	On success returns a signed register offset value when dw_value_type is DW_EXPR_OFFSET or DW_EXPER_VAL_OFFSET.
dw_block_content	On success returns a pointer to a block. For example, for DW_EXPR_EXPRESSION the block gives access to the expression bytes.
dw_row_pc_out	On success returns the address of the actual pc for this register at this pc.
dw_has_more_rows	On success returns FALSE if there are no more rows, otherwise returns TRUE.
dw_subsequent_pc	On success this returns the address of the next pc for which there is a register row, making access to all the rows in sequence much more efficient than just adding 1 to a pc value.
dw_error	The usual error detail return pointer.

Returns

Returns DW_DLV_OK if the dw_pc_requested is in the FDE passed in and there is a row for the pc in the table.

dwarf_get_fde_info_for_reg3_b()

int dwarf_get_fde_info_for_reg3_b	(	Dwarf_Fde	dw_fde,
		Dwarf_Half	dw_table_column,
		Dwarf_Addr	dw_pc_requested,
		Dwarf_Small *	dw_value_type,
		Dwarf_Unsigned *	dw_offset_relevant,
		Dwarf_Unsigned *	dw_register,
		Dwarf_Unsigned *	dw_offset,
		Dwarf_Block *	dw_block_content,
		Dwarf_Addr *	dw_row_pc_out,
		Dwarf_Bool *	dw_has_more_rows,
		Dwarf_Addr *	dw_subsequent_pc,
		Dwarf_Error *	dw_error
	)

Identical to dwarf_get_fde_info_for_reg3_c() except that this returns dw_offset as a Dwarf_Unsigned, which was never appropriate, and required you to cast that value to Dwarf_Signed to use it properly..

Please switch to using dwarf_get_fde_info_for_reg3_c()

dwarf_get_fde_info_for_cfa_reg3_c()

int dwarf_get_fde_info_for_cfa_reg3_c	(	Dwarf_Fde	dw_fde,
		Dwarf_Addr	dw_pc_requested,
		Dwarf_Small *	dw_value_type,
		Dwarf_Unsigned *	dw_offset_relevant,
		Dwarf_Unsigned *	dw_register,
		Dwarf_Signed *	dw_offset,
		Dwarf_Block *	dw_block,
		Dwarf_Addr *	dw_row_pc_out,
		Dwarf_Bool *	dw_has_more_rows,
		Dwarf_Addr *	dw_subsequent_pc,
		Dwarf_Error *	dw_error
	)

See also

dwarf_get_fde_info_for_reg3_c() has essentially the same return values as dwarf_get_fde_info_for_reg3_c but it refers to the CFA (which is not part of the register table) so this function has no table column argument.

New in September 2023, release 0.8.0. dwarf_get_fde_info_for_cfa_reg3_c() returns dw_offset as a signed type. dwarf_get_fde_info_for_cfa_reg3_b() returns dw_offset as an unsigned type, requiring the caller to cast to Dwarf_Signed before using the value. Both versions exist and operate properly.

If dw_value_type == DW_EXPR_EXPRESSION or DW_EXPR_VALUE_EXPRESSION dw_offset is not set and the caller must evaluate the expression, which usually depends on runtime frame data which cannot be calculated without a stack frame including register values (etc).

dwarf_get_fde_info_for_cfa_reg3_b()

int dwarf_get_fde_info_for_cfa_reg3_b	(	Dwarf_Fde	dw_fde,
		Dwarf_Addr	dw_pc_requested,
		Dwarf_Small *	dw_value_type,
		Dwarf_Unsigned *	dw_offset_relevant,
		Dwarf_Unsigned *	dw_register,
		Dwarf_Unsigned *	dw_offset,
		Dwarf_Block *	dw_block,
		Dwarf_Addr *	dw_row_pc_out,
		Dwarf_Bool *	dw_has_more_rows,
		Dwarf_Addr *	dw_subsequent_pc,
		Dwarf_Error *	dw_error
	)

See also

dwarf_get_fde_info_for_cfa_reg3_c

This is the earlier version that returns a dw_offset of type Dwarf_Unsigned, requiring you to cast to Dwarf_Signed to work with the value.

dwarf_get_fde_for_die()

int dwarf_get_fde_for_die	(	Dwarf_Debug	dw_dbg,
		Dwarf_Die	dw_subr_die,
		Dwarf_Fde *	dw_returned_fde,
		Dwarf_Error *	dw_error
	)

This is essentially useless as only SGI/MIPS compilers from the 1990's had DW_AT_MIPS_fde in DW_TAG_subprogram DIEs and this relies on that attribute to work.

dwarf_get_fde_n()

int dwarf_get_fde_n	(	Dwarf_Fde *	dw_fde_data,
		Dwarf_Unsigned	dw_fde_index,
		Dwarf_Fde *	dw_returned_fde,
		Dwarf_Error *	dw_error
	)

This is just like indexing into the FDE array but with extra checking of the pointer and index.

See also

dwarf_get_fde_list

dwarf_get_fde_at_pc()

int dwarf_get_fde_at_pc	(	Dwarf_Fde *	dw_fde_data,
		Dwarf_Addr	dw_pc_of_interest,
		Dwarf_Fde *	dw_returned_fde,
		Dwarf_Addr *	dw_lopc,
		Dwarf_Addr *	dw_hipc,
		Dwarf_Error *	dw_error
	)

Using binary search this finds the FDE that contains this dw_pc_of_interest That works because libdwarf ensures the array of FDEs is sorted by the low-pc

See also

dwarf_get_fde_list

Parameters

dw_fde_data	Pass in a pointer an array of fde pointers.
dw_pc_of_interest	The pc value of interest.
dw_returned_fde	On success a pointer to the applicable FDE is set through the pointer.
dw_lopc	On success a pointer to the low pc in dw_returned_fde is set through the pointer.
dw_hipc	On success a pointer to the high pc (one past the actual last byte address) in dw_returned_fde is set through the pointer.
dw_error	The usual error detail return pointer.

Returns

Returns DW_DLV_OK if the dw_pc_of_interest found in some FDE in the array. If no FDE is found containing dw_pc_of_interest DW_DLV_NO_ENTRY is returned.

dwarf_get_cie_augmentation_data()

int dwarf_get_cie_augmentation_data	(	Dwarf_Cie	dw_cie,
		Dwarf_Small **	dw_augdata,
		Dwarf_Unsigned *	dw_augdata_len,
		Dwarf_Error *	dw_error
	)

GNU .eh_frame CIE augmentation information. See Linux Standard Base Core Specification version 3.0 .

See also

https://gcc.gnu.org/legacy-ml/gcc/2003-12/msg01168.html

Parameters

dw_cie	The CIE of interest.
dw_augdata	On success returns a pointer to the augmentation data.
dw_augdata_len	On success returns the length in bytes of the augmentation data.
dw_error	The usual error detail return pointer.

Returns

Returns DW_DLV_OK etc. If the augmentation data length is zero it returns DW_DLV_NO_ENTRY.

dwarf_get_fde_augmentation_data()

int dwarf_get_fde_augmentation_data	(	Dwarf_Fde	dw_fde,
		Dwarf_Small **	dw_augdata,
		Dwarf_Unsigned *	dw_augdata_len,
		Dwarf_Error *	dw_error
	)

GNU .eh_frame FDE augmentation information. See Linux Standard Base Core Specification version 3.0 .

See also

https://gcc.gnu.org/legacy-ml/gcc/2003-12/msg01168.html

Parameters

dw_fde	The FDE of interest.
dw_augdata	On success returns a pointer to the augmentation data.
dw_augdata_len	On success returns the length in bytes of the augmentation data.
dw_error	The usual error detail return pointer.

Returns

Returns DW_DLV_OK etc. If the augmentation data length is zero it returns DW_DLV_NO_ENTRY.

dwarf_expand_frame_instructions()

int dwarf_expand_frame_instructions	(	Dwarf_Cie	dw_cie,
		Dwarf_Small *	dw_instructionspointer,
		Dwarf_Unsigned	dw_length_in_bytes,
		Dwarf_Frame_Instr_Head *	dw_head,
		Dwarf_Unsigned *	dw_instr_count,
		Dwarf_Error *	dw_error
	)

Combined with dwarf_get_frame_instruction() or dwarf_get_frame_instruction_a() (the second is like the first but adds an argument for LLVM address space numbers) it enables detailed access to frame instruction fields for evaluation or printing.

Free allocated memory with dwarf_dealloc_frame_instr_head().

See also

Using dwarf_expand_frame_instructions

Parameters

dw_cie	The cie relevant to the instructions.
dw_instructionspointer	points to the instructions
dw_length_in_bytes	byte length of the instruction sequence.
dw_head	The address of an allocated dw_head
dw_instr_count	Returns the number of instructions in the byte stream
dw_error	Error return details

Returns

On success returns DW_DLV_OK

dwarf_get_frame_instruction()

int dwarf_get_frame_instruction	(	Dwarf_Frame_Instr_Head	dw_head,
		Dwarf_Unsigned	dw_instr_index,
		Dwarf_Unsigned *	dw_instr_offset_in_instrs,
		Dwarf_Small *	dw_cfa_operation,
		const char **	dw_fields_description,
		Dwarf_Unsigned *	dw_u0,
		Dwarf_Unsigned *	dw_u1,
		Dwarf_Signed *	dw_s0,
		Dwarf_Signed *	dw_s1,
		Dwarf_Unsigned *	dw_code_alignment_factor,
		Dwarf_Signed *	dw_data_alignment_factor,
		Dwarf_Block *	dw_expression_block,
		Dwarf_Error *	dw_error
	)

See also

Using dwarf_expand_frame_instructions

Parameters

dw_head	A head record
dw_instr_index	index 0 < i < instr_count
dw_instr_offset_in_instrs	Returns the byte offset of this instruction within instructions.
dw_cfa_operation	Returns a DW_CFA opcode.
dw_fields_description	Returns a string. Do not free.
dw_u0	May be set to an unsigned value
dw_u1	May be set to an unsigned value
dw_s0	May be set to a signed value
dw_s1	May be set to a signed value
dw_code_alignment_factor	May be set by the call
dw_data_alignment_factor	May be set by the call
dw_expression_block	Pass in a pointer to a block
dw_error	If DW_DLV_ERROR and the argument is non-NULL, returns details about the error.

Returns

On success returns DW_DLV_OK If there is no such instruction with that index it returns DW_DLV_NO_ENTRY On error it returns DW_DLV_ERROR and if dw_error is NULL it pushes back a pointer to a Dwarf_Error to the caller.

Frame expressions have a variety of formats and content. The dw_fields parameter is set to a pointer to a short string with some set of the letters s,u,r,d,c,b,a which enables determining exactly which values the call sets. Some examples: A s in fields[0] means s0 is a signed number.

A b somewhere in fields means the expression block passed in has been filled in.

A r in fields[1] means u1 is set to a register number.

A d in fields means data_alignment_factor is set

A c in fields means code_alignment_factor is set

An a in fields means an LLVM address space value and only exists if calling dwarf_get_frame_instruction_a().

The possible frame instruction formats are:

"" "b" "r" "rb" "rr" "rsd" "rsda" "ru" "rua" "rud"
"sd" "u" "uc"

are the possible frame instruction formats.

dwarf_get_frame_instruction_a()

int dwarf_get_frame_instruction_a	(	Dwarf_Frame_Instr_Head	dw_,
		Dwarf_Unsigned	dw_instr_index,
		Dwarf_Unsigned *	dw_instr_offset_in_instrs,
		Dwarf_Small *	dw_cfa_operation,
		const char **	dw_fields_description,
		Dwarf_Unsigned *	dw_u0,
		Dwarf_Unsigned *	dw_u1,
		Dwarf_Unsigned *	dw_u2,
		Dwarf_Signed *	dw_s0,
		Dwarf_Signed *	dw_s1,
		Dwarf_Unsigned *	dw_code_alignment_factor,
		Dwarf_Signed *	dw_data_alignment_factor,
		Dwarf_Block *	dw_expression_block,
		Dwarf_Error *	dw_error
	)

Where multiplication is called for (via dw_code_alignment_factor or dw_data_alignment_factor) to produce an offset there is no need to check for overflow as libdwarf has already verified there is no overflow.

The return values are the same except here we have: an a in fields[2] or fields[3] means dw_u2 is an address-space identifier for the LLVM CFA instruction.

dwarf_dealloc_frame_instr_head()

void dwarf_dealloc_frame_instr_head

(

Dwarf_Frame_Instr_Head

dw_head

)

Parameters

dw_head

A head pointer. Frees all data created by dwarf_expand_frame_instructions() and makes the head pointer stale. The caller should set to NULL.

dwarf_fde_section_offset()

int dwarf_fde_section_offset	(	Dwarf_Debug	dw_dbg,
		Dwarf_Fde	dw_in_fde,
		Dwarf_Off *	dw_fde_off,
		Dwarf_Off *	dw_cie_off,
		Dwarf_Error *	dw_error
	)

Parameters

dw_dbg	The Dwarf_Debug of interest
dw_in_fde	Pass in the FDE of interest.
dw_fde_off	On success returns the section offset of the FDE.
dw_cie_off	On success returns the section offset of the CIE.
dw_error	Error return details

Returns

Returns DW_DLV_OK etc.

dwarf_cie_section_offset()

int dwarf_cie_section_offset	(	Dwarf_Debug	dw_dbg,
		Dwarf_Cie	dw_in_cie,
		Dwarf_Off *	dw_cie_off,
		Dwarf_Error *	dw_error
	)

Parameters

dw_dbg	The Dwarf_Debug of interest
dw_in_cie	Pass in the CIE of interest.
dw_cie_off	On success returns the section offset of the CIE.
dw_error	Error return details

Returns

Returns DW_DLV_OK etc.

dwarf_set_frame_rule_table_size()

Dwarf_Half dwarf_set_frame_rule_table_size	(	Dwarf_Debug	dw_dbg,
		Dwarf_Half	dw_value
	)

Parameters

dw_dbg	The Dwarf_Debug of interest.
dw_value	Pass in the value to record for the library to use.

Returns

Returns the previous value.

dwarf_set_frame_rule_initial_value()

Dwarf_Half dwarf_set_frame_rule_initial_value	(	Dwarf_Debug	dw_dbg,
		Dwarf_Half	dw_value
	)

Invariants for setting frame registers

Parameters

dw_dbg	The Dwarf_Debug of interest.
dw_value	Pass in the value to record for the library to use.

Returns

Returns the previous value.

dwarf_set_frame_cfa_value()

Dwarf_Half dwarf_set_frame_cfa_value	(	Dwarf_Debug	dw_dbg,
		Dwarf_Half	dw_value
	)

Parameters

dw_dbg	The Dwarf_Debug of interest.
dw_value	Pass in the value to record for the library to use.

Returns

Returns the previous value.

dwarf_set_frame_same_value()

Dwarf_Half dwarf_set_frame_same_value	(	Dwarf_Debug	dw_dbg,
		Dwarf_Half	dw_value
	)

Parameters

dw_dbg	The Dwarf_Debug of interest.
dw_value	Pass in the value to record for the library to use.

Returns

Returns the previous value.

dwarf_set_frame_undefined_value()

Dwarf_Half dwarf_set_frame_undefined_value	(	Dwarf_Debug	dw_dbg,
		Dwarf_Half	dw_value
	)

Parameters

dw_dbg	The Dwarf_Debug of interest.
dw_value	Pass in the value to record for the library to use.

Returns

Returns the previous value.