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_cie_info.3 2071 2011-10-27 03:20:00Z jkoshy $ 26.\" 27.Dd May 29, 2011 28.Os 29.Dt DWARF_GET_CIE_INFO 3 30.Sh NAME 31.Nm dwarf_get_cie_info 32.Nd retrieve information associated with a CIE descriptor 33.Sh LIBRARY 34.Lb libdwarf 35.Sh SYNOPSIS 36.In libdwarf.h 37.Ft int 38.Fo dwarf_get_cie_info 39.Fa "Dwarf_Cie cie" 40.Fa "Dwarf_Unsigned *cie_byte_len" 41.Fa "Dwarf_Small *version" 42.Fa "char **augmentation" 43.Fa "Dwarf_Unsigned *caf" 44.Fa "Dwarf_Unsigned *daf" 45.Fa "Dwarf_Half *ra" 46.Fa "Dwarf_Ptr *init_inst" 47.Fa "Dwarf_Unsigned *inst_len" 48.Fa "Dwarf_Error *err" 49.Fc 50.Sh DESCRIPTION 51Function 52.Fn dwarf_get_cie_info 53retrieves the information associated with a given CIE descriptor. 54.Pp 55Argument 56.Ar cie 57should reference a valid DWARF CIE descriptor, such as would be 58returned by function 59.Xr dwarf_get_cie_of_fde 3 . 60.Pp 61Argument 62.Ar cie_byte_len 63should point to a location that will hold the length in bytes of 64the CIE descriptor itself. 65.Pp 66Argument 67.Ar version 68should point to a location that will hold the version number of 69the CIE descriptor. 70.Pp 71Arugment 72.Ar augmentation 73should point to a location that will be set to a pointer to a 74NUL-terminated string containing augmentation data encoded as UTF-8. 75.Pp 76Argument 77.Ar caf 78should point to a location that will hold the code alignment 79factor recorded in the CIE descriptor. 80.Pp 81Arugment 82.Ar daf 83should point to a location that will hold the data alignment 84factor recorded in the CIE descriptor. 85.Pp 86Argument 87.Ar ra 88should point to a location that will hold the return address 89recorded in the CIE descriptor. 90.Pp 91Argument 92.Ar init_inst 93should point to a location that will be set to a pointer to an array 94of bytes containing the initial instructions associated with the CIE 95descriptor. 96.Pp 97Argument 98.Ar inst_len 99should point to a location that will hold the length in bytes 100of the initial instructions returned in argument 101.Ar init_inst . 102.Pp 103If argument 104.Ar err 105is not NULL, it will be used to store error information in case of an 106error. 107.Sh RETURN VALUES 108Function 109.Fn dwarf_get_cie_info 110returns 111.Dv DW_DLV_OK 112when it succeeds. 113In case of an error, it returns 114.Dv DW_DLV_ERROR 115and sets the argument 116.Ar err . 117.Sh ERRORS 118Function 119.Fn dwarf_get_cie_info 120can fail with: 121.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 122.It Bq Er DW_DLE_ARGUMENT 123One of the arguments 124.Ar cie , 125.Ar cie_byte_len , 126.Ar version , 127.Ar augmentation , 128.Ar caf , 129.Ar daf , 130.Ar ra , 131.Ar init_inst 132or 133.Ar inst_len 134was NULL. 135.El 136.Sh SEE ALSO 137.Xr dwarf 3 , 138.Xr dwarf_get_cie_index 3 , 139.Xr dwarf_get_cie_of_fde 3 , 140.Xr dwarf_get_fde_at_pc 3 , 141.Xr dwarf_get_fde_info_for_all_regs 3 , 142.Xr dwarf_get_fde_info_for_all_regs3 3 , 143.Xr dwarf_get_fde_info_for_cfa_reg3 3 , 144.Xr dwarf_get_fde_info_for_reg 3 , 145.Xr dwarf_get_fde_info_for_reg3 3 , 146.Xr dwarf_get_fde_instr_bytes 3 , 147.Xr dwarf_get_fde_list 3 , 148.Xr dwarf_get_fde_list_eh 3 , 149.Xr dwarf_get_fde_n 3 , 150.Xr dwarf_get_fde_range 3 151