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_add_frame_fde.3 2072 2011-10-27 03:26:49Z jkoshy $ 26.\" 27.Dd September 26, 2011 28.Os 29.Dt DWARF_ADD_FRAME_FDE 3 30.Sh NAME 31.Nm dwarf_add_frame_fde 32.Nd add a call frame descriptor to a DWARF producer instance 33.Sh LIBRARY 34.Lb libdwarf 35.Sh SYNOPSIS 36.In libdwarf.h 37.Ft "Dwarf_Unsigned" 38.Fo dwarf_add_frame_fde 39.Fa "Dwarf_P_Debug dbg" 40.Fa "Dwarf_P_Fde fde" 41.Fa "Dwarf_P_Die die" 42.Fa "Dwarf_Unsigned cie" 43.Fa "Dwarf_Addr virt_addr" 44.Fa "Dwarf_Unsigned code_len" 45.Fa "Dwarf_Unsigned symbol_index" 46.Fa "Dwarf_Error *err" 47.Fc 48.Ft "Dwarf_Unsigned" 49.Fo dwarf_add_frame_fde_b 50.Fa "Dwarf_P_Debug dbg" 51.Fa "Dwarf_P_Fde fde" 52.Fa "Dwarf_P_Die die" 53.Fa "Dwarf_Unsigned cie" 54.Fa "Dwarf_Addr virt_addr" 55.Fa "Dwarf_Unsigned code_len" 56.Fa "Dwarf_Unsigned symbol_index" 57.Fa "Dwarf_Unsigned end_symbol_index" 58.Fa "Dwarf_Addr offset_from_end_sym" 59.Fa "Dwarf_Error *err" 60.Fc 61.Sh DESCRIPTION 62Function 63.Fn dwarf_add_frame_fde_b 64adds the call frame descriptor referenced by argument 65.Ar fde 66to a producer instance. 67.Pp 68Argument 69.Ar dbg 70should reference a DWARF producer instance allocated using 71.Xr dwarf_producer_init 3 72or 73.Xr dwarf_producer_init_b 3 . 74.Pp 75Argument 76.Ar fde 77should reference a frame descriptor allocated using 78.Xr dwarf_new_fde 3 . 79.Pp 80Argument 81.Ar die 82is ignored by this implementation of the 83.Lb libdwarf . 84.Pp 85Argument 86.Ar cie 87specifies the index of call frame common information entry for 88the frame descriptor. 89Valid indices are those returned by the function 90.Xr dwarf_add_frame_cie 3 . 91.Pp 92Argument 93.Ar symbol_index 94specifies the ELF symbol index of the first symbol to be used for 95relocation. 96.Pp 97The meaning of the arguments 98.Ar virt_addr , 99.Ar code_len 100and 101.Ar offset_from_end_sym 102depend on the value of argument 103.Ar end_symbol_index : 104.Bl -bullet 105.It 106If the argument 107.Ar end_symbol_index 108is zero, the argument 109.Ar virt_addr 110specifies the relocatable address of the start of the function 111associated with the frame descriptor, the argument 112.Ar code_len 113specifies the size in bytes of the machine instructions for this 114function, the argument 115.Ar symbol_index 116specifies the ELF symbol to be used for relocating the address in 117argument 118.Ar virt_addr , 119and the argument 120.Ar offset_from_end_symbol 121is ignored. 122.It 123If the argument 124.Ar end_symbol_index 125is non-zero, it specifies the ELF symbol index of the second symbol to 126be used for relocation. 127In this case, the argument 128.Ar virt_addr 129specifies an offset from the relocatable symbol specified by argument 130.Ar symbol_index , 131the argument 132.Ar offset_from_end_symbol 133should specify an offset from the symbol named by the argument 134.Ar end_symbol_index , 135and the argument 136.Ar code_len 137will be ignored. 138The 139.Dv DW_DLC_SYMBOLIC_RELOCATIONS 140flag should also have been set on the DWARF producer instance. 141.Pp 142Application code can retrieve the relocation entries for the symbol 143pair by calling function 144.Xr dwarf_get_relocation_info 3 . 145The relocation entry for the first symbol will have type 146.Dv dwarf_drt_first_of_length_pair 147and the relocation entry for the second symbol will have type 148.Dv dwarf_drt_second_of_length_pair . 149.El 150.Pp 151If argument 152.Ar err 153is not NULL, it will be used to store error information in case 154of an error. 155.Pp 156Function 157.Fn dwarf_add_frame_fde 158is similar to function 159.Fn dwarf_add_frame_fde_b 160except that it supports only one relocation symbol. 161.Sh RETURN VALUES 162On success, these functions return the index value for 163the added frame descriptor. 164In case of an error, these functions return 165.Dv DW_DLV_NOCOUNT 166and set the argument 167.Ar err . 168.Sh ERRORS 169These functions can fail with: 170.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 171.It Bq Er DW_DLE_ARGUMENT 172One of the arguments 173.Ar dbg 174or 175.Ar fde 176was NULL. 177.It Bq Er DW_DLE_ARGUMENT 178The frame descriptor referenced by argument 179.Ar fde 180did not belong to the producer instance referenced by argument 181.Ar dbg . 182.It Bq Er DW_DLE_ARGUMENT 183The common information entry index specified by argument 184.Ar cie 185was invalid. 186.It Bq Er DW_DLE_ARGUMENT 187Argument 188.Ar end_symbol_index 189was non-zero, but the flag 190.Dv DW_DLC_SYMBOLIC_RELOCATIONS 191was not set on the producer instance. 192.El 193.Sh SEE ALSO 194.Xr dwarf 3 , 195.Xr dwarf_add_fde_inst 3 , 196.Xr dwarf_add_frame_cie 3 , 197.Xr dwarf_fde_cfa_offset 3 , 198.Xr dwarf_get_relocation_info 3 , 199.Xr dwarf_new_fde 3 , 200.Xr dwarf_producer_init 3 , 201.Xr dwarf_producer_init_b 3 202