contrib/elftoolchain/libdwarf/dwarf_finish.3

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