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