1.\" $NetBSD: dwarf_producer_init.3,v 1.6 2024/03/03 17:37:32 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_producer_init.3 3963 2022-03-12 16:07:32Z jkoshy 28.\" 29.Dd August 20, 2011 30.Dt DWARF_PRODUCER_INIT 3 31.Os 32.Sh NAME 33.Nm dwarf_producer_init , 34.Nm dwarf_producer_init_b 35.Nd allocate a DWARF producer descriptor 36.Sh LIBRARY 37.Lb libdwarf 38.Sh SYNOPSIS 39.In libdwarf.h 40.Ft Dwarf_P_Debug 41.Fo dwarf_producer_init 42.Fa "Dwarf_Unsigned flags" 43.Fa "Dwarf_Callback_Func func" 44.Fa "Dwarf_Handler errhand" 45.Fa "Dwarf_Ptr errarg" 46.Fa "Dwarf_Error *err" 47.Fc 48.Ft Dwarf_P_Debug 49.Fo dwarf_producer_init_b 50.Fa "Dwarf_Unsigned flags" 51.Fa "Dwarf_Callback_Func_b func" 52.Fa "Dwarf_Handler errhand" 53.Fa "Dwarf_Ptr errarg" 54.Fa "Dwarf_Error *error" 55.Fc 56.Sh DESCRIPTION 57These functions allocate and return a 58.Vt Dwarf_P_Debug 59descriptor representing a DWARF producer instance. 60.Pp 61The argument 62.Fa errhand 63should contain the address of a function to be called in case of an 64error. 65If this argument is 66.Dv NULL , 67the default error handling scheme is used, see 68.Xr dwarf 3 . 69.Pp 70The argument 71.Fa errarg 72will be passed to the error handler function when it is invoked. 73.Pp 74The argument 75.Fa err 76references a memory location that would hold a 77.Vt Dwarf_Error 78descriptor in case of an error. 79.Pp 80The argument 81.Fa flags 82specifies additional characteristics of the DWARF producer instance. 83The following flags are recognized: 84.Bl -tag -width "Dv DW_DLC_ISA_MIPS" 85.It Dv DW_DLC_ISA_IA64 86.Pq Deprecated 87The target instruction set architecture is IA64. 88This flag is deprecated. 89Application code should use the 90.Xr dwarf_producer_set_isa 3 91function to specify target instruction set architecture. 92.It Dv DW_DLC_ISA_MIPS 93.Pq Deprecated 94The target instruction set architecture is MIPS. 95This flag is deprecated. 96Application code should use the 97.Xr dwarf_producer_set_isa 3 98function to specify target instruction set architecture. 99.It Dv DW_DLC_SIZE_32 100.Pq Default 101The target address size is 32-bit. 102.It Dv DW_DLC_SIZE_64 103The target address size is 64-bit. 104.It Dv DW_DLC_STREAM_RELOCATIONS 105.Pq Default 106Generate stream relocations. 107.It Dv DW_DLC_SYMBOLIC_RELOCATIONS 108Generate symbolic relocations. 109.It Dv DW_DLC_TARGET_BIGENDIAN 110The target is big endian. 111.It Dv DW_DLC_TARGET_LITTLEENDIAN 112The target is little endian. 113.It Dv DW_DLC_WRITE 114.Pq Required 115Permit writing of DWARF information. 116.El 117.Pp 118The following flags are mutually exclusive. 119.Bl -bullet -compact 120.It 121Flags 122.Dv DW_DLC_ISA_IA64 123and 124.Dv DW_DLC_ISA_MIPS . 125.It 126Flags 127.Dv DW_DLC_SIZE_32 128and 129.Dv DW_DLC_SIZE_64 . 130.It 131Flags 132.Dv DW_DLC_STREAM_RELOCATIONS 133and 134.Dv DW_DLC_SYMBOLIC_RELOCATIONS . 135.It 136Flags 137.Dv DW_DLC_TARGET_BIGENDIAN 138and 139.Dv DW_DLC_TARGET_LITTLEENDIAN . 140.El 141If neither of the flags 142.Dv DW_DLC_TARGET_BIGENDIAN 143and 144.Dv DW_DLC_TARGET_LITTLEENDIAN 145is set, the target's endianness is assumed to be the same as the host's 146endianness. 147.Pp 148Argument 149.Fa func 150should point to an application-provided callback function of type 151.Vt Dwarf_Callback_Func_b . 152The type 153.Vt Dwarf_Callback_Func_b 154is defined in the header file 155.In libdwarf.h 156as: 157.Bd -literal -offset indent 158typedef int (*Dwarf_Callback_Func_b)(char *name, int size, 159 Dwarf_Unsigned type, Dwarf_Unsigned flags, Dwarf_Unsigned link, 160 Dwarf_Unsigned info, Dwarf_Unsigned *index, int *error); 161.Ed 162.Pp 163This function is called by the 164.Lb libdwarf 165once for each section in the object file that the library needs to 166create. 167The arguments to this callback function specify the values in the ELF 168section header for the section being created: 169.Pp 170.Bl -tag -width indent -compact -offset indent 171.It Ar name 172The name of the section being created. 173.It Ar size 174The 175.Va sh_size 176value in the section header. 177.It Ar type 178The 179.Va sh_type 180value in the section header. 181.It Ar flags 182The 183.Va sh_flags 184value in the section header. 185.It Ar link 186The 187.Va sh_link 188value in the section header. 189.It Ar info 190The 191.Va sh_info 192value in the section header. 193.El 194.Pp 195On success, the callback function should return the section index 196value of the created section, and set the location pointed to by 197argument 198.Fa index 199to the symbol table index of the symbol that associated with the newly 200created section. 201This symbol table index will be used in relocation entries 202referring to the created section. 203.Pp 204In case of failure, the callback function should return -1 and set the 205location pointed to by argument 206.Fa error 207to an application-defined error code. 208This application returned error code is currently ignored by the 209library. 210.Pp 211Function 212.Fn dwarf_producer_init 213is deprecated. 214Function 215.Fn dwarf_producer_init 216is identical to function 217.Fn dwarf_producer_init_b 218except that the callback function it expects can not properly handle 219arbitrary section symbol index values. 220.Ss Memory Management 221The 222.Vt Dwarf_P_Debug 223instance returned by these functions should be freed using the 224function 225.Fn dwarf_producer_finish . 226.Sh RETURN VALUES 227On success, these functions return the created DWARF producer 228descriptor. 229In case of an error, they return 230.Dv DW_DLV_BADADDR 231and set the argument 232.Fa err . 233.Sh EXAMPLES 234To initialize a 235.Vt Dwarf_P_Debug 236instance for a MIPS32 big endian object, use: 237.Bd -literal -offset indent 238Dwarf_P_Debug dbg; 239Dwarf_Unsigned flags; 240Dwarf_Error de; 241 242/* ... assume cb_func points to the callback function ... */ 243 244flags = DW_DLC_WRITE | DW_DLC_SIZE_32 | DW_DLC_ISA_MIPS | 245 DW_DLC_STREAM_RELOCATIONS | DW_DLC_TARGET_BIGENDIAN; 246if ((dbg = dwarf_producer_init(flags, cb_func, NULL, NULL, &de)) == 247 DW_DLV_BADADDR) 248 warnx("dwarf_producer_init failed: %s", dwarf_errmsg(-1)); 249.Ed 250.Sh ERRORS 251These functions can fail with: 252.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" 253.It Bq Er DW_DLE_ARGUMENT 254Argument 255.Fa func 256was 257.Dv NULL . 258.It Bq Er DW_DLE_ARGUMENT 259The flag 260.Dv DW_DLC_WRITE 261was not set in argument 262.Fa flags . 263.It Bq Er DW_DLE_ARGUMENT 264The flags 265.Dv DW_DLC_SIZE_32 266and 267.Dv DW_DLC_SIZE_64 268were both set in argument 269.Fa flags . 270.It Bq Er DW_DLE_ARGUMENT 271The flags 272.Dv DW_DLC_ISA_IA64 273and 274.Dv DW_DLC_ISA_MIPS 275were both set in argument 276.Fa flags . 277.It Bq Er DW_DLE_ARGUMENT 278The flags 279.Dv DW_DLC_TARGET_BIGENDIAN 280and 281.Dv DW_DLC_TARGET_LITTLEENDIAN 282were both set in argument 283.Fa flags . 284.It Bq Er DW_DLE_ARGUMENT 285The flags 286.Dv DW_DLC_STREAM_RELOCATIONS 287and 288.Dv DW_DLC_SYMBOLIC_RELOCATIONS 289were both set in argument 290.Fa flags . 291.It Bq Er DW_DLE_MEMORY 292An out of memory condition was encountered. 293.El 294.Sh SEE ALSO 295.Xr dwarf 3 , 296.Xr dwarf_errmsg 3 , 297.Xr dwarf_producer_finish 3 , 298.Xr dwarf_producer_set_isa 3 , 299.Xr dwarf_transform_to_disk_form 3 300