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