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 3181 2015-04-10 13:22:51Z emaste $ 26.\" 27.Dd November 9, 2011 28.Os 29.Dt DWARF_EXPAND_FRAME_INSTRUCTIONS 3 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 ERRORS 108Function 109.Fn dwarf_expand_frame_instructions 110can fail with: 111.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 112.It Bq Er DW_DLE_ARGUMENT 113One of the arguments 114.Ar cie , 115.Ar instructions , 116.Ar ret_ops 117or 118.Ar ret_opcnt 119was NULL. 120.It Bq Er DW_DLE_ARGUMENT 121Argument 122.Ar len 123was 0. 124.It Bq Er DW_DLE_MEMORY 125An out of memory condition was encountered during the execution of 126this function. 127.It Bq Er DW_DLE_FRAME_INSTR_EXEC_ERROR 128An unknown instruction was found in the instruction bytes provided 129in argument 130.Ar instructions . 131.El 132.Sh EXAMPLE 133To retrieve and expand the frame instructions for a given FDE 134descriptor, use: 135.Bd -literal -offset indent 136Dwarf_Dbg dbg; 137Dwarf_Cie cie; 138Dwarf_Fde fde; 139Dwarf_Ptr fde_inst; 140Dwarf_Unsigned fde_instlen; 141Dwarf_Frame_Op *ops; 142Dwarf_Signed opcnt; 143Dwarf_Error de; 144 145/* ... assuming `dbg` references a valid DWARF debugging context, 146 `fde` references a valid FDE descriptor and `cie` holds the CIE 147 descriptor associated with the FDE descriptor ... */ 148 149if (dwarf_get_fde_instr_bytes(fde, &fde_inst, &fde_instlen, 150 &de) != DW_DLV_OK) 151 errx(EXIT_FAILURE, "dwarf_get_fde_instr_bytes failed: %s", 152 dwarf_errmsg(de)); 153 154if (dwarf_expand_frame_instructions(cie, fde_inst, fde_instlen, 155 &ops, &opcnt, &de) != DW_DLV_OK) 156 errx(EXIT_FAILURE, 157 "dwarf_expand_frame_instructions failed: %s", 158 dwarf_errmsg(de)); 159 160for (i = 0; i < opcnt; i++) { 161 /* ... use ops[i] ... */ 162} 163 164/* Free the memory area when no longer needed. */ 165dwarf_dealloc(dbg, ops, DW_DLA_FRAME_BLOCK); 166.Ed 167.Sh SEE ALSO 168.Xr dwarf 3 , 169.Xr dwarf_frame_instructions_dealloc 3 , 170.Xr dwarf_get_cie_info 3 , 171.Xr dwarf_get_cie_index 3 , 172.Xr dwarf_get_cie_of_fde , 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