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