contrib/elftoolchain/libdwarf/dwarf_init.3

   1 .\" Copyright (c) 2009 Joseph Koshy.  All rights reserved.
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided that the following conditions
   5 .\" are met:
   6 .\" 1. Redistributions of source code must retain the above copyright
   7 .\"    notice, this list of conditions and the following disclaimer.
   8 .\" 2. Redistributions in binary form must reproduce the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer in the
  10 .\"    documentation and/or other materials provided with the distribution.
  11 .\"
  12 .\" This software is provided by Joseph Koshy ``as is'' and
  13 .\" any express or implied warranties, including, but not limited to, the
  14 .\" implied warranties of merchantability and fitness for a particular purpose
  15 .\" are disclaimed.  in no event shall Joseph Koshy be liable
  16 .\" for any direct, indirect, incidental, special, exemplary, or consequential
  17 .\" damages (including, but not limited to, procurement of substitute goods
  18 .\" or services; loss of use, data, or profits; or business interruption)
  19 .\" however caused and on any theory of liability, whether in contract, strict
  20 .\" liability, or tort (including negligence or otherwise) arising in any way
  21 .\" out of the use of this software, even if advised of the possibility of
  22 .\" such damage.
  23 .\"
  24 .\" $Id: dwarf_init.3 3644 2018-10-15 19:55:01Z jkoshy $
  25 .\"
  26 .Dd November 9, 2011
  27 .Dt DWARF_INIT 3
  28 .Os
  29 .Sh NAME
  30 .Nm dwarf_init ,
  31 .Nm dwarf_elf_init
  32 .Nd allocate a DWARF debug descriptor
  33 .Sh LIBRARY
  34 .Lb libdwarf
  35 .Sh SYNOPSIS
  36 .In libdwarf.h
  37 .Ft int
  38 .Fo dwarf_init
  39 .Fa "int fd"
  40 .Fa "int mode"
  41 .Fa "Dwarf_Handler errhand"
  42 .Fa "Dwarf_Ptr errarg"
  43 .Fa "Dwarf_Debug *ret"
  44 .Fa "Dwarf_Error *err"
  45 .Fc
  46 .Ft in
  47 .Fo dwarf_elf_init
  48 .Fa "Elf *elf"
  49 .Fa "int mode"
  50 .Fa "Dwarf_Handler errhand"
  51 .Fa "Dwarf_Ptr errarg"
  52 .Fa "Dwarf_Debug *ret"
  53 .Fa "Dwarf_Error *err"
  54 .Fc
  55 .Sh DESCRIPTION
  56 These functions allocate and return a
  57 .Vt Dwarf_Debug
  58 instance for the object denoted by argument
  59 .Ar fd
  60 or
  61 .Ar elf .
  62 This instance would be used for subsequent access to debugging information in the object by other functions in the DWARF(3) library.
  63 .Pp
  64 For function
  65 .Fn dwarf_init ,
  66 argument
  67 .Ar fd
  68 denotes an open file descriptor referencing a compilation object.
  69 Function
  70 .Fn dwarf_init
  71 implicitly allocates an
  72 .Vt Elf
  73 descriptor for argument
  74 .Ar fd .
  75 .Pp
  76 For function
  77 .Fn dwarf_elf_init ,
  78 argument
  79 .Ar elf
  80 denotes a descriptor returned by
  81 .Xr elf_begin 3
  82 or
  83 .Xr elf_memory 3 .
  84 .Pp
  85 Argument
  86 .Ar mode
  87 specifies the access mode desired.
  88 It should be at least as permissive as the mode with which
  89 the file descriptor
  90 .Ar fd
  91 or the ELF descriptor
  92 .Ar elf
  93 was created with.
  94 Legal values for argument
  95 .Ar mode
  96 are:
  97 .Pp
  98 .Bl -tag -width "DW_DLC_WRITE" -compact
  99 .It DW_DLC_RDWR
 100 Permit reading and writing of DWARF information.
 101 .It DW_DLC_READ
 102 Operate in read-only mode.
 103 .It DW_DLC_WRITE
 104 Permit writing of DWARF information.
 105 .El
 106 .Pp
 107 Argument
 108 .Ar errhand
 109 denotes a function to be called in case of an error.
 110 If this argument is
 111 .Dv NULL
 112 then a default error handling scheme is used.
 113 See
 114 .Xr dwarf 3
 115 for a description of the error handling scheme used by the
 116 DWARF(3) library.
 117 .Pp
 118 Argument
 119 .Ar errarg
 120 is passed to the error handler function denoted by argument
 121 .Ar errhand
 122 when it is invoked.
 123 .Pp
 124 Argument
 125 .Ar ret
 126 points to the memory location that will hold a
 127 .Vt Dwarf_Debug
 128 reference on a successful call these functions.
 129 .Pp
 130 Argument
 131 .Ar err
 132 references a memory location that would hold a
 133 .Vt Dwarf_Error
 134 descriptor in case of an error.
 135 .Ss Memory Management
 136 The
 137 .Vt Dwarf_Debug
 138 instance returned by these functions should be freed using
 139 .Fn dwarf_finish .
 140 .Sh IMPLEMENTATION NOTES
 141 The current implementation does not support access modes
 142 .Dv DW_DLC_RDWR
 143 and
 144 .Dv DW_DLC_WRITE .
 145 .Sh RETURN VALUES
 146 These functions return the following values:
 147 .Bl -tag -width ".Bq Er DW_DLV_NO_ENTRY"
 148 .It Bq Er DW_DLV_OK
 149 This return value indicates a successful return.
 150 .It Bq Er DW_DLV_ERROR
 151 The operation failed.
 152 .It Bq Er DW_DLV_NO_ENTRY
 153 The object specified by arguments
 154 .Ar "fd"
 155 or
 156 .Ar "elf"
 157 did not contain debug information.
 158 .El
 159 .Sh EXAMPLES
 160 To initialize a
 161 .Vt Dwarf_Debug
 162 instance from a open file descriptor referencing an ELF object, and
 163 with the default error handler, use:
 164 .Bd -literal -offset indent
 165 Dwarf_Error err;
 166 Dwarf_Debug dbg;
 167
 168 if (dwarf_init(fd, DW_DLC_READ, NULL, NULL, &dbg, &err) !=
 169     DW_DLV_OK)
 170         errx(EXIT_FAILURE, "dwarf_init: %s", dwarf_errmsg(err));
 171 .Ed
 172 .Sh SEE ALSO
 173 .Xr dwarf 3 ,
 174 .Xr dwarf_errmsg 3 ,
 175 .Xr dwarf_finish 3 ,
 176 .Xr dwarf_get_elf 3 ,
 177 .Xr elf_begin 3 ,
 178 .Xr elf_memory 3