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