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_init.3 2122 2011-11-09 15:35:14Z jkoshy $ 25.\" 26.Dd November 9, 2011 27.Os 28.Dt DWARF_INIT 3 29.Sh NAME 30.Nm dwarf_init , 31.Nm dwarf_elf_init 32.Nd allocate a DWARF debug descriptor 33.Sh LIBRARY 34.Lb libdwarf 35.Sh SYNOPSIS 36.In libdwarf.h 37.Ft int 38.Fo dwarf_init 39.Fa "int fd" 40.Fa "int mode" 41.Fa "Dwarf_Handler errhand" 42.Fa "Dwarf_Ptr errarg" 43.Fa "Dwarf_Debug *ret" 44.Fa "Dwarf_Error *err" 45.Fc 46.Ft in 47.Fo dwarf_elf_init 48.Fa "Elf *elf" 49.Fa "int mode" 50.Fa "Dwarf_Handler errhand" 51.Fa "Dwarf_Ptr errarg" 52.Fa "Dwarf_Debug *ret" 53.Fa "Dwarf_Error *err" 54.Fc 55.Sh DESCRIPTION 56These functions allocate and return a 57.Vt Dwarf_Debug 58instance for the object denoted by argument 59.Ar fd 60or 61.Ar elf . 62This instance would be used for subsequent access to debugging information in the object by other functions in the DWARF(3) library. 63.Pp 64For function 65.Fn dwarf_init , 66argument 67.Ar fd 68denotes an open file descriptor referencing a compilation object. 69Function 70.Fn dwarf_init 71implicitly allocates an 72.Vt Elf 73descriptor for argument 74.Ar fd . 75.Pp 76For function 77.Fn dwarf_elf_init , 78argument 79.Ar elf 80denotes a descriptor returned by 81.Xr elf_begin 3 82or 83.Xr elf_memory 3 . 84.Pp 85Argument 86.Ar mode 87specifies the access mode desired. 88It should be at least as permissive as the mode with which 89the file descriptor 90.Ar fd 91or the ELF descriptor 92.Ar elf 93was created with. 94Legal values for argument 95.Ar mode 96are: 97.Pp 98.Bl -tag -width "DW_DLC_WRITE" -compact 99.It DW_DLC_RDWR 100Permit reading and writing of DWARF information. 101.It DW_DLC_READ 102Operate in read-only mode. 103.It DW_DLC_WRITE 104Permit writing of DWARF information. 105.El 106.Pp 107Argument 108.Ar errhand 109denotes a function to be called in case of an error. 110If this argument is 111.Dv NULL 112then a default error handling scheme is used. 113See 114.Xr dwarf 3 115for a description of the error handling scheme used by the 116DWARF(3) library. 117.Pp 118Argument 119.Ar errarg 120is passed to the error handler function denoted by argument 121.Ar errhand 122when it is invoked. 123.Pp 124Argument 125.Ar ret 126points to the memory location that will hold a 127.Vt Dwarf_Debug 128reference on a successful call these functions. 129.Pp 130Argument 131.Ar err 132references a memory location that would hold a 133.Vt Dwarf_Error 134descriptor in case of an error. 135.Ss Memory Management 136The 137.Vt Dwarf_Debug 138instance returned by these functions should be freed using 139.Fn dwarf_finish . 140.Sh RETURN VALUES 141These functions return the following values: 142.Bl -tag -width ".Bq Er DW_DLV_NO_ENTRY" 143.It Bq Er DW_DLV_OK 144This return value indicates a successful return. 145.It Bq Er DW_DLV_ERROR 146The operation failed. 147.It Bq Er DW_DLV_NO_ENTRY 148The object specified by arguments 149.Ar "fd" 150or 151.Ar "elf" 152did not contain debug information. 153.El 154.Sh IMPLEMENTATION NOTES 155The current implementation does not support access modes 156.Dv DW_DLC_RDWR 157and 158.Dv DW_DLC_WRITE . 159.Sh EXAMPLES 160To initialize a 161.Vt Dwarf_Debug 162instance from a open file descriptor referencing an ELF object, and 163with the default error handler, use: 164.Bd -literal -offset indent 165Dwarf_Error err; 166Dwarf_Debug dbg; 167 168if (dwarf_init(fd, DW_DLC_READ, NULL, NULL, &dbg, &err) != 169 DW_DLV_OK) 170 errx(EXIT_FAILURE, "dwarf_init: %s", dwarf_errmsg(err)); 171.Ed 172.Sh SEE ALSO 173.Xr dwarf 3 , 174.Xr dwarf_errmsg 3 , 175.Xr dwarf_finish 3 , 176.Xr dwarf_get_elf 3 , 177.Xr elf_begin 3 , 178.Xr elf_memory 3 179