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_reg.3 3644 2018-10-15 19:55:01Z jkoshy $ 26.\" 27.Dd June 4, 2011 28.Dt DWARF_GET_FDE_INFO_FOR_REG 3 29.Os 30.Sh NAME 31.Nm dwarf_get_fde_info_for_reg 32.Nd retrieve 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_reg 39.Fa "Dwarf_Fde fde" 40.Fa "Dwarf_Half table_column" 41.Fa "Dwarf_Addr pc" 42.Fa "Dwarf_Signed *offset_relevant" 43.Fa "Dwarf_Signed *register_num" 44.Fa "Dwarf_Signed *offset" 45.Fa "Dwarf_Addr *row_pc" 46.Fa "Dwarf_Error *error" 47.Fc 48.Sh DESCRIPTION 49Function 50.Fn dwarf_get_fde_info_for_reg 51retrieves a register rule from the register rule table associated with 52a given FDE descriptor, given a program counter address and rule 53column number. 54.Pp 55Argument 56.Ar fde 57should reference a valid DWARF FDE descriptor. 58.Pp 59Arugment 60.Ar table_column 61should hold the column number of the register rule desired. 62.Pp 63Argument 64.Ar pc 65should hold the program counter address to be used to locate the 66desired register rule row. 67.Pp 68On successful execution, 69.Fn dwarf_get_fde_info_for_reg 70stores information about the register rule found into the locations 71pointed to by the arguments 72.Ar offset_relevant , 73.Ar register_num , 74.Ar offset 75and 76.Ar row_pc . 77.Pp 78If there is an offset value associated with the register rule, 79the location pointed to by argument 80.Ar offset_relevant 81will be set to 1. 82.Pp 83Argument 84.Ar register_num 85should point to a location which will hold the register number associated 86with the register rule. 87.Pp 88Argument 89.Ar offset 90should point to a location which will be set to the offset value 91associated with the register rule, or to 0 if the register rule 92does not have an offset value. 93.Pp 94Argument 95.Ar row_pc 96should point to a location which will be set to the lowest program 97counter address associated with the register rule found. 98.Pp 99If argument 100.Ar err 101is not NULL, it will be used to return an error descriptor in case 102of an error. 103.Ss COMPATIBILITY 104Function 105.Fn dwarf_get_fde_info_for_reg 106is deprecated since it only supports DWARF2 frame sections. 107Applications should instead use function 108.Xr dwarf_get_fde_info_for_reg3 3 109which supports both DWARF2 and DWARF3 frame sections. 110.Sh RETURN VALUES 111Function 112.Fn dwarf_get_fde_info_for_reg 113returns 114.Dv DW_DLV_OK 115when it succeeds. 116In case of an error, it returns 117.Dv DW_DLV_ERROR 118and sets the argument 119.Ar err . 120.Sh ERRORS 121Function 122.Fn dwarf_get_fde_info_for_reg 123can fail with: 124.Bl -tag -width ".Bq Er DW_DLE_FRAME_TABLE_COL_BAD" 125.It Bq Er DW_DLE_ARGUMENT 126One of the arguments 127.Ar fde , 128.Ar offset_relevant , 129.Ar register_num , 130.Ar offset 131or 132.Ar row_pc 133was NULL. 134.It Bq Er DW_DLE_FRAME_TABLE_COL_BAD 135The column number provided in argument 136.Ar table_column 137was too large. 138.It Bq Er DW_DLE_PC_NOT_IN_FDE_RANGE 139The program counter value provided in argument 140.Ar pc 141did not fall in the range covered by argument 142.Ar fde . 143.El 144.Sh SEE ALSO 145.Xr dwarf 3 , 146.Xr dwarf_get_fde_at_pc 3 , 147.Xr dwarf_get_fde_info_for_all_regs 3 , 148.Xr dwarf_get_fde_info_for_all_regs3 3 , 149.Xr dwarf_get_fde_info_for_cfa_reg3 3 , 150.Xr dwarf_get_fde_info_for_reg3 3 , 151.Xr dwarf_get_fde_n 3 , 152.Xr dwarf_set_frame_cfa_value 3 , 153.Xr dwarf_set_frame_rule_initial_value 3 , 154.Xr dwarf_set_frame_rule_table_size 3 , 155.Xr dwarf_set_frame_same_value 3 , 156.Xr dwarf_set_frame_undefined_value 3 157