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

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