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