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