1.\"	$NetBSD: dwarf_object_init.3,v 1.2 2014/03/09 16:58:04 christos Exp $
2.\"
3.\" Copyright (c) 2011 Joseph Koshy
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_object_init.3 2074 2011-10-27 03:34:33Z jkoshy
28.\"
29.Dd September 29, 2011
30.Os
31.Dt DWARF_OBJECT_INIT 3
32.Sh NAME
33.Nm dwarf_object_init
34.Nd allocate a DWARF debug descriptor with application-specific file \
35access methods
36.Sh LIBRARY
37.Lb libdwarf
38.Sh SYNOPSIS
39.In libdwarf.h
40.Ft int
41.Fo dwarf_object_init
42.Fa "Dwarf_Obj_Access_Interface *iface"
43.Fa "Dwarf_Handler errhand"
44.Fa "Dwarf_Ptr errarg"
45.Fa "Dwarf_Debug *dbg"
46.Fa "Dwarf_Error *err"
47.Fc
48.Sh DESCRIPTION
49.Pp
50The
51.Fn dwarf_object_init
52function allocates and returns a
53.Vt Dwarf_Debug
54instance that uses application-supplied access methods to read file
55content.
56.Pp
57The argument
58.Ar iface
59should point to a populated
60.Vt Dwarf_Obj_Access_Interface
61structure.
62The contents of the
63.Vt Dwarf_Obj_Access_Interface
64structure are described in the section
65.Sx "Object Access Functions"
66below.
67.Pp
68The argument
69.Ar errhand
70should point to a function to be called in case of an error.
71If this argument is
72.Dv NULL
73then a default error handling scheme is used.
74See
75.Xr dwarf 3
76for a description of the error handling schemes available.
77.Pp
78The argument
79.Ar errarg
80will be passed to the error handler function pointed to by argument
81.Ar errhand .
82.Pp
83The argument
84.Ar dbg
85should point to a memory location that will be set to a reference to
86the returned
87.Vt Dwarf_Debug
88descriptor.
89.Pp
90The argument
91.Ar err
92will be used to return a
93.Vt Dwarf_Error
94descriptor in case of an error.
95.Ss Object Access Functions
96The data structures used to specify object access methods are defined
97in
98.In libdwarf.h .
99.Bl -tag -width indent
100.It Vt "Dwarf_Obj_Access_Interface"
101This structure bundles together a set of file access methods along
102with a pointer to application-private state.
103.Bd -literal -offset indent
104typedef struct {
105	void *object;
106	const Dwarf_Obj_Access_Methods *methods;
107} Dwarf_Obj_Access_Interface;
108.Ed
109.Pp
110.Bl -tag -width ".Ar methods" -compact
111.It Ar object
112This field points to application-specific state that will be passed as
113the first parameter to the actual access object methods.
114.It Ar methods
115This structure contains pointers to the functions implementing the
116access methods, as described below.
117.El
118.It Vt Dwarf_Obj_Access_Methods
119This structure specifies the functions implementing low-level access.
120.Bd -literal -offset indent
121typedef struct {
122	int (*get_section_info)(void *obj, Dwarf_Half index,
123	    Dwarf_Obj_Access_Section *ret, int *error);
124	Dwarf_Endianness (*get_byte_order)(void *obj);
125	Dwarf_Small (*get_length_size)(void *obj);
126	Dwarf_Small (*get_pointer_size)(void *obj);
127	Dwarf_Unsigned (*get_section_count)(void *obj);
128	int (*load_section)(void *obj, Dwarf_Half ndx,
129	    Dwarf_Small **ret_data, int *error);
130} Dwarf_Obj_Access_Methods;
131.Ed
132.Pp
133.Bl -tag -width ".Ar get_section_count" -compact
134.It Ar get_byte_order
135This function should return the endianness of the DWARF object by
136returning one of the constants
137.Dv DW_OBJECT_MSB
138or
139.Dv DW_OBJECT_LSB .
140.It Ar get_length_size
141This function should return the number of bytes needed to represent a
142DWARF offset in the object being debugged.
143.It Ar get_pointer_size
144This function should return the size in bytes, in the object being
145debugged, of a memory address.
146.It Ar get_section_count
147This function should return the number of sections in the object being
148debugged.
149.It Ar get_section_info
150This function should return information about the section at the
151index
152.Ar ndx
153by filling in the structure of type
154.Vt Dwarf_Obj_Access_Section
155pointed to by argument
156.Ar ret .
157The
158.Vt Dwarf_Obj_Access_Section
159structure is described below.
160.It Ar load_section
161This function should load the section specified by argument
162.Ar ndx
163into memory and place a pointer to the section's data into
164the location pointed to by argument
165.Ar ret_data .
166.El
167.Pp
168The argument
169.Ar obj
170passed to these functions will be set to the pointer value in the
171.Ar object
172field of the associated
173.Vt Dwarf_Obj_Access_Interface
174structure.
175.Pp
176The argument
177.Ar error
178is used to return an error code in case of an error.
179.It Vt Dwarf_Obj_Access_Section
180This structure describes the layout of a section in the DWARF object.
181.Bd -literal -offset indent
182typedef struct {
183	Dwarf_Addr addr;
184	Dwarf_Unsigned size;
185	const char *name;
186} Dwarf_Obj_Access_Section;
187.Ed
188.Pp
189.Bl -tag -width ".Ar name" -compact
190.It Ar addr
191A pointer to the start of the section's data.
192.It Ar size
193The size of the section in bytes.
194.It Ar name
195A pointer to a NUL-terminated string containing the name of the
196section.
197.El
198.El
199.Sh RETURN VALUES
200On success, the
201.Fn dwarf_object_init
202function returns
203.Dv DW_DLV_OK .
204In case of an error, the function returns
205.Dv DW_DLV_ERROR
206and sets the argument
207.Ar err.
208.Sh ERRORS
209The
210.Fn dwarf_object_init
211function may fail with the following errors:
212.Bl -tag -width ".Bq Er DW_DLE_DEBUG_INFO_NULL"
213.It Bq Er DW_DLE_ARGUMENT
214One of the arguments
215.Ar iface
216or
217.Ar dbg
218was NULL.
219.It Bq Er DW_DLE_DEBUG_INFO_NULL
220The underlying object did not contain debugging information.
221.It Bq Er DW_DLE_MEMORY
222An out of memory condition was encountered during the execution of the
223function.
224.El
225.Sh SEE ALSO
226.Xr dwarf 3 ,
227.Xr dwarf_init 3 ,
228.Xr dwarf_init_elf 3 ,
229.Xr dwarf_object_finish 3
230