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_expand_frame_instructions.3 3644 2018-10-15 19:55:01Z jkoshy $ 26.\" 27.Dd November 9, 2011 28.Dt DWARF_EXPAND_FRAME_INSTRUCTIONS 3 29.Os 30.Sh NAME 31.Nm dwarf_expand_frame_instructions 32.Nd expand frame instructions 33.Sh LIBRARY 34.Lb libdwarf 35.Sh SYNOPSIS 36.In libdwarf.h 37.Ft int 38.Fo dwarf_expand_frame_instructions 39.Fa "Dwarf_Cie cie" 40.Fa "Dwarf_Ptr instructions" 41.Fa "Dwarf_Unsigned len" 42.Fa "Dwarf_Frame_Op **ret_ops" 43.Fa "Dwarf_Signed *ret_opcnt" 44.Fa "Dwarf_Error *error" 45.Fc 46.Sh DESCRIPTION 47Function 48.Fn dwarf_expand_frame_instructions 49translates DWARF frame instruction bytes into an array of 50.Vt Dwarf_Frame_Op 51descriptors. 52.Pp 53Argument 54.Ar cie 55should reference the CIE descriptor associated with the instructions 56to be translated. 57.Pp 58Arugment 59.Ar instructions 60should point to an array of frame instruction bytes, as 61returned by the functions 62.Xr dwarf_get_cie_info 3 63or 64.Xr dwarf_get_fde_instr_bytes 3 . 65.Pp 66Argument 67.Ar len 68should specify the number of the frame instruction bytes to be 69translated. 70.Pp 71Argument 72.Ar ret_ops 73should point to a location that will be set to a pointer to 74an array of translated 75.Vt Dwarf_Frame_Op 76descriptors. 77.Pp 78Argument 79.Ar ret_opcnt 80should point to a location that will hold the total number of the 81returned descriptors. 82.Pp 83If argument 84.Ar err 85is not NULL, it will be used to store error information in case of an 86error. 87.Ss Memory Management 88The memory area used for the descriptor array returned in argument 89.Ar ret_ops 90is allocated by 91.Lb libdwarf . 92Application code should use function 93.Xr dwarf_dealloc 3 94with type 95.Dv DW_DLA_FRAME_BLOCK 96to free the memory area when the descriptor array is no longer needed. 97.Sh RETURN VALUES 98Function 99.Fn dwarf_expand_frame_instructions 100returns 101.Dv DW_DLV_OK 102when it succeeds. 103In case of an error, it returns 104.Dv DW_DLV_ERROR 105and sets the argument 106.Ar err . 107.Sh EXAMPLES 108To retrieve and expand the frame instructions for a given FDE 109descriptor, use: 110.Bd -literal -offset indent 111Dwarf_Dbg dbg; 112Dwarf_Cie cie; 113Dwarf_Fde fde; 114Dwarf_Ptr fde_inst; 115Dwarf_Unsigned fde_instlen; 116Dwarf_Frame_Op *ops; 117Dwarf_Signed opcnt; 118Dwarf_Error de; 119 120/* ... assuming `dbg` references a valid DWARF debugging context, 121 `fde` references a valid FDE descriptor and `cie` holds the CIE 122 descriptor associated with the FDE descriptor ... */ 123 124if (dwarf_get_fde_instr_bytes(fde, &fde_inst, &fde_instlen, 125 &de) != DW_DLV_OK) 126 errx(EXIT_FAILURE, "dwarf_get_fde_instr_bytes failed: %s", 127 dwarf_errmsg(de)); 128 129if (dwarf_expand_frame_instructions(cie, fde_inst, fde_instlen, 130 &ops, &opcnt, &de) != DW_DLV_OK) 131 errx(EXIT_FAILURE, 132 "dwarf_expand_frame_instructions failed: %s", 133 dwarf_errmsg(de)); 134 135for (i = 0; i < opcnt; i++) { 136 /* ... use ops[i] ... */ 137} 138 139/* Free the memory area when no longer needed. */ 140dwarf_dealloc(dbg, ops, DW_DLA_FRAME_BLOCK); 141.Ed 142.Sh ERRORS 143Function 144.Fn dwarf_expand_frame_instructions 145can fail with: 146.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 147.It Bq Er DW_DLE_ARGUMENT 148One of the arguments 149.Ar cie , 150.Ar instructions , 151.Ar ret_ops 152or 153.Ar ret_opcnt 154was NULL. 155.It Bq Er DW_DLE_ARGUMENT 156Argument 157.Ar len 158was 0. 159.It Bq Er DW_DLE_MEMORY 160An out of memory condition was encountered during the execution of 161this function. 162.It Bq Er DW_DLE_FRAME_INSTR_EXEC_ERROR 163An unknown instruction was found in the instruction bytes provided 164in argument 165.Ar instructions . 166.El 167.Sh SEE ALSO 168.Xr dwarf 3 , 169.Xr dwarf_frame_instructions_dealloc 3 , 170.Xr dwarf_get_cie_index 3 , 171.Xr dwarf_get_cie_info 3 , 172.Xr dwarf_get_cie_of_fde 3 , 173.Xr dwarf_get_fde_at_pc 3 , 174.Xr dwarf_get_fde_info_for_all_regs 3 , 175.Xr dwarf_get_fde_info_for_all_regs3 3 , 176.Xr dwarf_get_fde_info_for_cfa_reg3 3 , 177.Xr dwarf_get_fde_info_for_reg 3 , 178.Xr dwarf_get_fde_info_for_reg3 3 , 179.Xr dwarf_get_fde_instr_bytes 3 , 180.Xr dwarf_get_fde_list 3 , 181.Xr dwarf_get_fde_list_eh 3 , 182.Xr dwarf_get_fde_n 3 183