contrib/elftoolchain/libdwarf/dwarf_get_elf.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_get_elf.3 2122 2011-11-09 15:35:14Z jkoshy $
  25 .\"
  26 .Dd November 9, 2011
  27 .Os
  28 .Dt DWARF_GET_ELF 3
  29 .Sh NAME
  30 .Nm dwarf_get_elf
  31 .Nd retrieve the
  32 .Vt Elf
  33 descriptor associated with a
  34 .Vt Dwarf_Debug
  35 instance
  36 .Sh LIBRARY
  37 .Lb libdwarf
  38 .Sh SYNOPSIS
  39 .In libdwarf.h
  40 .Ft int
  41 .Fo dwarf_get_elf
  42 .Fa "Dwarf_Debug dbg"
  43 .Fa "Elf **elf"
  44 .Fa "Dwarf_Error *err"
  45 .Fc
  46 .Sh DESCRIPTION
  47 Function
  48 .Fn dwarf_get_elf
  49 returns the
  50 .Vt Elf
  51 descriptor associated with a
  52 .Vt Dwarf_Debug
  53 instance.
  54 .Pp
  55 Argument
  56 .Ar dbg
  57 should be a handle to a valid
  58 .Vt Dwarf_Debug
  59 instance returned by a prior call to
  60 .Xr dwarf_init 3
  61 or
  62 .Xr dwarf_elf_init 3 .
  63 .Pp
  64 Argument
  65 .Ar elf
  66 points a location into which a handle to an
  67 .Vt Elf
  68 descriptor will be written.
  69 .Pp
  70 Argument
  71 .Ar err
  72 is used to record error information in case of failure.
  73 .Sh RETURN VALUES
  74 On success, function
  75 .Fn dwarf_get_elf
  76 returns
  77 .Dv DW_DLV_OK .
  78 In case of an error, it returns
  79 .Dv DW_DLV_ERROR
  80 and sets argument
  81 .Ar err .
  82 .Sh EXAMPLES
  83 To retrieve the
  84 .Vt Elf
  85 instance associated with a
  86 .Vt Dwarf_Debug
  87 instance use:
  88 .Bd -literal -offset indent
  89 Dwarf_Debug dbg;
  90 Dwarf_Error de;
  91 Elf *elf;
  92
  93 \&... allocate dbg using dwarf_init() etc ...
  94
  95 if (dwarf_get_elf(dbg, &elf, &de) != DW_DLV_OK)
  96         errx(EXIT_FAILURE, "dwarf_get_elf: %s", dwarf_errmsg(de));
  97 .Ed
  98 .Sh SEE ALSO
  99 .Xr dwarf 3 ,
 100 .Xr dwarf_errmsg 3 ,
 101 .Xr dwarf_init 3 ,
 102 .Xr dwarf_finish 3 ,
 103 .Xr elf 3