1 .\" Copyright (c) 2011 Kai Wang
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
25 .\" $Id: dwarf_producer_init.3 3644 2018-10-15 19:55:01Z jkoshy $
28 .Dt DWARF_PRODUCER_INIT 3
31 .Nm dwarf_producer_init ,
32 .Nm dwarf_producer_init_b
33 .Nd allocate a DWARF producer descriptor
39 .Fo dwarf_producer_init
40 .Fa "Dwarf_Unsigned flags"
41 .Fa "Dwarf_Callback_Func func"
42 .Fa "Dwarf_Handler errhand"
43 .Fa "Dwarf_Ptr errarg"
44 .Fa "Dwarf_Error *err"
47 .Fo dwarf_producer_init_b
48 .Fa "Dwarf_Unsigned flags"
49 .Fa "Dwarf_Callback_Func_b func"
50 .Fa "Dwarf_Handler errhand"
51 .Fa "Dwarf_Ptr errarg"
52 .Fa "Dwarf_Error *error"
55 These functions allocate and return a
57 descriptor representing a DWARF producer instance.
61 should contain the address of a function to be called in case of an
65 the default error handling scheme is used, see
70 will be passed to the error handler function when it is invoked.
74 references a memory location that would hold a
76 descriptor in case of an error.
80 specifies additional characteristics of the DWARF producer instance.
81 The following flags are recognized:
82 .Bl -tag -width "Dv DW_DLC_ISA_MIPS"
83 .It Dv DW_DLC_ISA_IA64
85 The target instruction set architecture is IA64.
86 This flag is deprecated.
87 Application code should use the
88 .Xr dwarf_producer_set_isa 3
89 function to specify target instruction set architecture.
90 .It Dv DW_DLC_ISA_MIPS
92 The target instruction set architecture is MIPS.
93 This flag is deprecated.
94 Application code should use the
95 .Xr dwarf_producer_set_isa 3
96 function to specify target instruction set architecture.
99 The target address size is 32-bit.
100 .It Dv DW_DLC_SIZE_64
101 The target address size is 64-bit.
102 .It Dv DW_DLC_STREAM_RELOCATIONS
104 Generate stream relocations.
105 .It Dv DW_DLC_SYMBOLIC_RELOCATIONS
106 Generate symbolic relocations.
107 .It Dv DW_DLC_TARGET_BIGENDIAN
108 The target is big endian.
109 .It Dv DW_DLC_TARGET_LITTLEENDIAN
110 The target is little endian.
113 Permit writing of DWARF information.
116 The following flags are mutually exclusive.
122 .Dv DW_DLC_ISA_MIPS .
130 .Dv DW_DLC_STREAM_RELOCATIONS
132 .Dv DW_DLC_SYMBOLIC_RELOCATIONS .
135 .Dv DW_DLC_TARGET_BIGENDIAN
137 .Dv DW_DLC_TARGET_LITTLEENDIAN .
139 If neither of the flags
140 .Dv DW_DLC_TARGET_BIGENDIAN
142 .Dv DW_DLC_TARGET_LITTLEENDIAN
143 is set, the target's endianness is assumed to be the same as the host's
148 should point to an application-provided callback function of type
149 .Vt Dwarf_Callback_Func_b .
151 .Vt Dwarf_Callback_Func_b
152 is defined in the header file
155 .Bd -literal -offset indent
156 typedef int (*Dwarf_Callback_Func_b)(char *name, int size,
157 Dwarf_Unsigned type, Dwarf_Unsigned flags, Dwarf_Unsigned link,
158 Dwarf_Unsigned info, Dwarf_Unsigned *index, int *error);
161 This function is called by the
163 once for each section in the object file that the library needs to
165 The arguments to this callback function specify the values in the ELF
166 section header for the section being created:
168 .Bl -tag -width indent -compact -offset indent
170 The name of the section being created.
174 value in the section header.
178 value in the section header.
182 value in the section header.
186 value in the section header.
190 value in the section header.
193 On success, the callback function should return the section index
194 value of the created section, and set the location pointed to by
197 to the symbol table index of the symbol that associated with the newly
199 This symbol table index will be used in relocation entries
200 referring to the created section.
202 In case of failure, the callback function should return -1 and set the
203 location pointed to by argument
205 to an application-defined error code.
206 This application returned error code is currently ignored by the
210 .Fn dwarf_producer_init
213 .Fn dwarf_producer_init
214 is identical to function
215 .Fn dwarf_producer_init_b
216 except that the callback function it expects can not properly handle
217 arbitrary section symbol index values.
218 .Ss Memory Management
221 instance returned by these functions should be freed using the
223 .Fn dwarf_producer_finish .
225 On success, these functions return the created DWARF producer
227 In case of an error, they return
234 instance for a MIPS32 big endian object, use:
235 .Bd -literal -offset indent
237 Dwarf_Unsigned flags;
240 /* ... assume cb_func points to the callback function ... */
242 flags = DW_DLC_WRITE | DW_DLC_SIZE_32 | DW_DLC_ISA_MIPS |
243 DW_DLC_STREAM_RELOCATIONS | DW_DLC_TARGET_BIGENDIAN;
244 if ((dbg = dwarf_producer_init(flags, cb_func, NULL, NULL, &de)) ==
246 warnx("dwarf_producer_init failed: %s", dwarf_errmsg(-1));
249 These functions can fail with:
250 .Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY"
251 .It Bq Er DW_DLE_ARGUMENT
255 .It Bq Er DW_DLE_ARGUMENT
258 was not set in argument
260 .It Bq Er DW_DLE_ARGUMENT
265 were both set in argument
267 .It Bq Er DW_DLE_ARGUMENT
272 were both set in argument
274 .It Bq Er DW_DLE_ARGUMENT
276 .Dv DW_DLC_TARGET_BIGENDIAN
278 .Dv DW_DLC_TARGET_LITTLEENDIAN
279 were both set in argument
281 .It Bq Er DW_DLE_ARGUMENT
283 .Dv DW_DLC_STREAM_RELOCATIONS
285 .Dv DW_DLC_SYMBOLIC_RELOCATIONS
286 were both set in argument
288 .It Bq Er DW_DLE_MEMORY
289 An out of memory condition was encountered.
294 .Xr dwarf_producer_finish 3 ,
295 .Xr dwarf_producer_set_isa 3 ,
296 .Xr dwarf_transform_to_disk_form 3