external/bsd/elftoolchain/dist/libdwarf/dwarf_object_init.3

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