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

   1 .\"     $NetBSD: dwarf_finish.3,v 1.2 2014/03/09 16:58:03 christos Exp $
   2 .\"
   3 .\" Copyright (c) 2009,2011 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_finish.3 2122 2011-11-09 15:35:14Z jkoshy
  27 .\"
  28 .Dd November 9, 2011
  29 .Os
  30 .Dt DWARF_FINISH 3
  31 .Sh NAME
  32 .Nm dwarf_finish ,
  33 .Nm dwarf_object_finish
  34 .Nd free resources associated with a debug descriptor
  35 .Sh LIBRARY
  36 .Lb libdwarf
  37 .Sh SYNOPSIS
  38 .In libdwarf.h
  39 .Ft int
  40 .Fn dwarf_finish "Dwarf_Debug dbg" "Dwarf_Error *err"
  41 .Ft int
  42 .Fn dwarf_object_finish "Dwarf_Debug dbg" "Dwarf_Error *err"
  43 .Sh DESCRIPTION
  44 The
  45 .Fn dwarf_finish
  46 and
  47 .Fn dwarf_object_finish
  48 functions are used to release the resources associated with a debug
  49 descriptor allocated by a prior call to
  50 .Xr dwarf_init 3
  51 and
  52 .Xr dwarf_object_init 3
  53 respectively.
  54 .Pp
  55 Argument
  56 .Ar dbg
  57 denotes a valid
  58 .Vt Dwarf_Debug
  59 instance.
  60 Argument
  61 .Ar err
  62 will be used to record error information in case of an error.
  63 .Pp
  64 After a call to
  65 .Fn dwarf_finish
  66 or
  67 .Fn dwarf_object_finish ,
  68 the argument
  69 .Ar dbg
  70 will be invalid and should not be used further.
  71 .Pp
  72 For
  73 .Vt Dwarf_Debug
  74 descriptors opened using
  75 .Xr dwarf_init 3 ,
  76 the application would need to explicitly release the
  77 .Vt Elf
  78 instance associated with the descriptor by first retrieving
  79 the instance using
  80 .Xr dwarf_get_elf 3
  81 and closing it using
  82 .Xr elf_end 3 .
  83 .Sh RETURN VALUES
  84 These functions return
  85 .Dv DW_DLV_OK
  86 if successful.
  87 In case of an error, the functions return
  88 .Dv DW_DLV_ERROR
  89 and record additional information in argument
  90 .Ar err .
  91 .Sh EXAMPLES
  92 To deallocate a
  93 .Vt Dwarf_Debug
  94 instance allocated using
  95 .Xr dwarf_elf_init 3
  96 use:
  97 .Bd -literal -offset indent
  98 Dwarf_Debug dbg;
  99 Dwarf_Error de;
 100
 101 if (dwarf_finish(dbg, &de) != DW_DLV_OK)
 102         errx(EXIT_FAILURE, "dwarf_finish: %s", dwarf_errmsg(de));
 103 .Ed
 104 .Pp
 105 To deallocate a
 106 .Vt Dwarf_Debug
 107 instance allocated using
 108 .Xr dwarf_object_init 3
 109 use:
 110 .Bd -literal -offset indent
 111 Dwarf_Debug dbg;
 112 Dwarf_Error de;
 113
 114 if (dwarf_object_finish(dbg, &de) != DW_DLV_OK)
 115         errx(EXIT_FAILURE, "dwarf_object_finish: %s",
 116             dwarf_errmsg(de));
 117 .Ed
 118 .Pp
 119 To deallocate a
 120 .Vt Dwarf_Debug
 121 instance allocated using
 122 .Xr dwarf_init 3
 123 use:
 124 .Bd -literal -offset indent
 125 Dwarf_Debug dbg;
 126 Dward_Error de;
 127 Elf *e;
 128
 129 if (dwarf_get_elf(dbg, &e, &de) != DW_DLV_OK)
 130         errx(EXIT_FAILURE, "dwarf_get_elf: %s", dwarf_errmsg(&de));
 131
 132 if (dwarf_finish(dbg, &de) != DW_DLV_OK)
 133         errx(EXIT_FAILURE, "dwarf_finish: %s", dwarf_errmsg(de));
 134
 135 (void) elf_end(e);
 136 .Ed
 137 .Sh SEE ALSO
 138 .Xr elf_end 3 ,
 139 .Xr dwarf_elf_init 3 ,
 140 .Xr dwarf_get_elf 3 ,
 141 .Xr dwarf_init 3 ,
 142 .Xr dwarf_object_init 3