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