1.\" Copyright (c) 2011 Kai Wang 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $Id: dwarf_get_fde_info_for_cfa_reg3.3 2071 2011-10-27 03:20:00Z jkoshy $ 26.\" 27.Dd June 12, 2011 28.Os 29.Dt DWARF_GET_FDE_INFO_FOR_CFA_REGS3 3 30.Sh NAME 31.Nm dwarf_get_fde_info_for_cfa_regs3 32.Nd retrieve a CFA register rule 33.Sh LIBRARY 34.Lb libdwarf 35.Sh SYNOPSIS 36.In libdwarf.h 37.Ft int 38.Fo dwarf_get_fde_info_for_cfa_regs3 39.Fa "Dwarf_Fde fde" 40.Fa "Dwarf_Addr pc" 41.Fa "Dwarf_Small *type" 42.Fa "Dwarf_Signed *offset_relevant" 43.Fa "Dwarf_Signed *register_num" 44.Fa "Dwarf_Signed *offset_or_block_len" 45.Fa "Dwarf_Ptr *block_ptr" 46.Fa "Dwarf_Addr *row_pc" 47.Fa "Dwarf_Error *err" 48.Fc 49.Sh DESCRIPTION 50Function 51.Fn dwarf_get_fde_info_for_cfa_reg3 52retrieves the CFA register rule for a given program counter address 53from the register rule table associated with an FDE descriptor. 54.Pp 55Argument 56.Ar fde 57should reference a valid DWARF FDE descriptor. 58.Pp 59Argument 60.Ar pc 61should hold the program counter address to be used to locate the 62desired register rule row. 63.Pp 64On successful execution, 65.Fn dwarf_get_fde_info_for_cfa_reg3 66stores information about the CFA register rule found into the locations 67pointed to by the arguments 68.Ar type , 69.Ar offset_relevant , 70.Ar register_num , 71.Ar offset_or_block_len , 72.Ar block_ptr 73and 74.Ar row_pc . 75.Pp 76Argument 77.Ar type 78should point to a location which will hold the type code of the 79register rule found. 80The returned value is one of the 81.Dv DW_EXPR_* 82contants defined in the header file 83.In libdwarf.h . 84.Pp 85If there is an offset value associated with the CFA register rule, 86the location pointed to by argument 87.Ar offset_relevant 88will be set to 1. 89.Pp 90Argument 91.Ar register_num 92should point to a location which will hold the register number associated 93with the CFA register rule. 94.Pp 95If the CFA register rule is of type 96.Dv DW_EXPR_OFFSET 97or 98.Dv DW_EXPR_VAL_OFFSET , 99the location pointed to by argument 100.Ar offset_or_block_len 101will be set to the offset value associated with the register rule, 102or to 0 if the register rule does not have an offset value. 103If the type code is 104.Dv DW_EXPR_EXPRESSION 105or 106.Dv DW_EXPR_VAL_EXPRESSION , 107the location pointed to by argument 108.Ar offset_or_block_len 109will be set to the length in bytes of the DWARF expression block 110associated with the register rule. 111.Pp 112Argument 113.Ar block_ptr 114should point to a location which will be set to a pointer to the 115content of the DWARF expression block associated with the CFA register 116rule. 117.Pp 118Argument 119.Ar row_pc 120should point to a location which will be set to the lowest program 121counter address associated with the register rule found. 122.Pp 123If argument 124.Ar err 125is not NULL, it will be used to return an error descriptor in case 126of an error. 127.Sh RETURN VALUES 128Function 129.Fn dwarf_get_fde_info_for_cfa_reg3 130returns 131.Dv DW_DLV_OK 132when it succeeds. 133In case of an error, it returns 134.Dv DW_DLV_ERROR 135and sets the argument 136.Ar err . 137.Sh ERRORS 138Function 139.Fn dwarf_get_fde_info_for_cfa_reg3 140can fail with: 141.Bl -tag -width ".Bq Er DW_DLE_PC_NOT_IN_FDE_RANGE" 142.It Bq Er DW_DLE_ARGUMENT 143One of the arguments 144.Ar block_ptr , 145.Ar fde , 146.Ar offset_or_block_len , 147.Ar offset_relevant , 148.Ar register_num , 149.Ar row_pc , 150or 151.Ar type 152was NULL. 153.It Bq Er DW_DLE_PC_NOT_IN_FDE_RANGE 154The program counter value provided in argument 155.Ar pc 156did not fall in the range covered by argument 157.Ar fde . 158.El 159.Sh SEE ALSO 160.Xr dwarf 3 , 161.Xr dwarf_get_fde_at_pc 3 , 162.Xr dwarf_get_fde_info_for_all_regs 3 , 163.Xr dwarf_get_fde_info_for_all_regs3 3 , 164.Xr dwarf_get_fde_info_for_reg 3 , 165.Xr dwarf_get_fde_info_for_reg3 3 , 166.Xr dwarf_get_fde_n 3 , 167.Xr dwarf_set_frame_cfa_value 3 , 168.Xr dwarf_set_frame_rule_table_size 3 , 169.Xr dwarf_set_frame_rule_initial_value 3 , 170.Xr dwarf_set_frame_same_value 3 , 171.Xr dwarf_set_frame_undefined_value 3 172