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