1.\" $NetBSD: dwarf_get_fde_info_for_reg3.3,v 1.6 2024/03/03 17:37:31 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 3962 2022-03-12 15:56:10Z jkoshy 28.\" 29.Dd November 9, 2011 30.Dt DWARF_GET_FDE_INFO_FOR_REG3 3 31.Os 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.Fa fde 61should reference a valid DWARF FDE descriptor. 62.Pp 63Arugment 64.Fa table_column 65should hold the column number of the register rule desired. 66.Pp 67Argument 68.Fa 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.Fa type , 77.Fa offset_relevant , 78.Fa register_num , 79.Fa offset_or_block_len , 80.Fa block_ptr 81and 82.Fa row_pc . 83.Pp 84Argument 85.Fa 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.Fa offset_relevant 96will be set to 1. 97.Pp 98Argument 99.Fa 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.Fa 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.Fa 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.Fa 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.Fa 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.Fa err 133is not 134.Dv NULL , 135it will be used to return an error descriptor in case of an error. 136.Sh RETURN VALUES 137Function 138.Fn dwarf_get_fde_info_for_reg3 139returns 140.Dv DW_DLV_OK 141when it succeeds. 142In case of an error, it returns 143.Dv DW_DLV_ERROR 144and sets the argument 145.Fa err . 146.Sh EXAMPLES 147To retrieve the register rules at column 3 from a rule table 148associated with a FDE descriptor: 149.Bd -literal -offset indent 150Dwarf_Fde fde; 151Dwarf_Off fde_offset, cie_offset; 152Dwarf_Unsigned func_len, fde_length; 153Dwarf_Signed cie_index, offset_relevant, register_num; 154Dwarf_Signed offset_or_block_len; 155Dwarf_Addr low_pc, row_pc; 156Dwarf_Ptr fde_addr, block_ptr; 157Dwarf_Small type; 158Dwarf_Error de; 159 160/* ... assuming `fde` references a valid FDE descriptor... */ 161if (dwarf_get_fde_range(fde, &low_pc, &func_len, &fde_addr, 162 &fde_length, &cie_offset, &cie_index, &fde_offset, 163 &de) != DW_DLV_OK) 164 errx(EXIT_FAILURE, "dwarf_get_fde_range failed: %s", 165 dwarf_errmsg(de)); 166 167/* Iterate all the table rows. */ 168for (pc = low_pc; pc < low_pc + func_len; pc++) { 169 if (dwarf_get_fde_info_for_reg3(fde, 3, pc, &type, 170 &offset_relevant, ®ister_num, &offset_or_block_len, 171 &block_ptr, &row_pc, &de) != DW_DLV_OK) { 172 warnx("dwarf_get_fde_info_for_reg3 failed: %s", 173 dwarf_errmsg(de)); 174 continue; 175 } 176 /* ... use the retrieved register rule ... */ 177} 178.Ed 179.Sh ERRORS 180Function 181.Fn dwarf_get_fde_info_for_reg3 182can fail with: 183.Bl -tag -width ".Bq Er DW_DLE_FRAME_TABLE_COL_BAD" 184.It Bq Er DW_DLE_ARGUMENT 185One of the arguments 186.Fa block_ptr , 187.Fa fde , 188.Fa offset_or_block_len , 189.Fa offset_relevant , 190.Fa register_num , 191.Fa row_pc , 192or 193.Fa type 194was 195.Dv NULL . 196.It Bq Er DW_DLE_FRAME_TABLE_COL_BAD 197The column number provided in argument 198.Fa table_column 199was too large. 200.It Bq Er DW_DLE_PC_NOT_IN_FDE_RANGE 201The program counter value provided in argument 202.Fa pc 203did not fall in the range covered by argument 204.Fa fde . 205.El 206.Sh SEE ALSO 207.Xr dwarf 3 , 208.Xr dwarf_get_fde_at_pc 3 , 209.Xr dwarf_get_fde_info_for_all_regs 3 , 210.Xr dwarf_get_fde_info_for_all_regs3 3 , 211.Xr dwarf_get_fde_info_for_cfa_reg3 3 , 212.Xr dwarf_get_fde_info_for_reg 3 , 213.Xr dwarf_get_fde_n 3 , 214.Xr dwarf_set_frame_cfa_value 3 , 215.Xr dwarf_set_frame_rule_initial_value 3 , 216.Xr dwarf_set_frame_rule_table_size 3 , 217.Xr dwarf_set_frame_same_value 3 , 218.Xr dwarf_set_frame_undefined_value 3 219