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