1*2de3b87aSKai Wang.\" Copyright (c) 2010 Joseph Koshy. All rights reserved. 2*2de3b87aSKai Wang.\" 3*2de3b87aSKai Wang.\" Redistribution and use in source and binary forms, with or without 4*2de3b87aSKai Wang.\" modification, are permitted provided that the following conditions 5*2de3b87aSKai Wang.\" are met: 6*2de3b87aSKai Wang.\" 1. Redistributions of source code must retain the above copyright 7*2de3b87aSKai Wang.\" notice, this list of conditions and the following disclaimer. 8*2de3b87aSKai Wang.\" 2. Redistributions in binary form must reproduce the above copyright 9*2de3b87aSKai Wang.\" notice, this list of conditions and the following disclaimer in the 10*2de3b87aSKai Wang.\" documentation and/or other materials provided with the distribution. 11*2de3b87aSKai Wang.\" 12*2de3b87aSKai Wang.\" This software is provided by Joseph Koshy ``as is'' and 13*2de3b87aSKai Wang.\" any express or implied warranties, including, but not limited to, the 14*2de3b87aSKai Wang.\" implied warranties of merchantability and fitness for a particular purpose 15*2de3b87aSKai Wang.\" are disclaimed. in no event shall Joseph Koshy be liable 16*2de3b87aSKai Wang.\" for any direct, indirect, incidental, special, exemplary, or consequential 17*2de3b87aSKai Wang.\" damages (including, but not limited to, procurement of substitute goods 18*2de3b87aSKai Wang.\" or services; loss of use, data, or profits; or business interruption) 19*2de3b87aSKai Wang.\" however caused and on any theory of liability, whether in contract, strict 20*2de3b87aSKai Wang.\" liability, or tort (including negligence or otherwise) arising in any way 21*2de3b87aSKai Wang.\" out of the use of this software, even if advised of the possibility of 22*2de3b87aSKai Wang.\" such damage. 23*2de3b87aSKai Wang.\" 24*2de3b87aSKai Wang.\" $Id: dwarf_srcfiles.3 2075 2011-10-27 03:47:28Z jkoshy $ 25*2de3b87aSKai Wang.\" 26*2de3b87aSKai Wang.Dd April 28, 2010 27*2de3b87aSKai Wang.Os 28*2de3b87aSKai Wang.Dt DWARF_SRCFILES 3 29*2de3b87aSKai Wang.Sh NAME 30*2de3b87aSKai Wang.Nm dwarf_srcfiles 31*2de3b87aSKai Wang.Nd retrieve source file information 32*2de3b87aSKai Wang.Sh LIBRARY 33*2de3b87aSKai Wang.Lb libdwarf 34*2de3b87aSKai Wang.Sh SYNOPSIS 35*2de3b87aSKai Wang.In libdwarf.h 36*2de3b87aSKai Wang.Ft int 37*2de3b87aSKai Wang.Fo dwarf_srcfiles 38*2de3b87aSKai Wang.Fa "Dwarf_Die die" 39*2de3b87aSKai Wang.Fa "char ***filenames" 40*2de3b87aSKai Wang.Fa "Dwarf_Signed *filenamecount" 41*2de3b87aSKai Wang.Fa "Dwarf_Error *err" 42*2de3b87aSKai Wang.Fc 43*2de3b87aSKai Wang.Sh DESCRIPTION 44*2de3b87aSKai WangFunction 45*2de3b87aSKai Wang.Fn dwarf_srcfiles 46*2de3b87aSKai Wangreturns the source file names associated with a compilation unit. 47*2de3b87aSKai WangSource file names are returned as an array of NUL-terminated strings. 48*2de3b87aSKai Wang.Pp 49*2de3b87aSKai WangArgument 50*2de3b87aSKai Wang.Ar die 51*2de3b87aSKai Wangshould reference a DWARF debugging information entry descriptor with 52*2de3b87aSKai Wangsource file information, see 53*2de3b87aSKai Wang.Xr dwarf 3 . 54*2de3b87aSKai WangArgument 55*2de3b87aSKai Wang.Ar filenames 56*2de3b87aSKai Wangshould point to a location that will hold a pointer to the returned array 57*2de3b87aSKai Wangof file names. 58*2de3b87aSKai WangArgument 59*2de3b87aSKai Wang.Ar filenamecount 60*2de3b87aSKai Wangshould point to a location that will hold the number of file names returned. 61*2de3b87aSKai WangIf argument 62*2de3b87aSKai Wang.Ar err 63*2de3b87aSKai Wangis not NULL, it will be used to store error information in case of an 64*2de3b87aSKai Wangerror. 65*2de3b87aSKai Wang.Ss Memory Management 66*2de3b87aSKai WangThe memory areas used for the file names and for array of pointers 67*2de3b87aSKai Wangbeing returned are managed by the DWARF(3) library. 68*2de3b87aSKai WangThe application should not attempt to directly free these memory areas. 69*2de3b87aSKai WangPortable code should indicate that the memory areas are to be freed 70*2de3b87aSKai Wangby using 71*2de3b87aSKai Wang.Xr dwarf_dealloc 3 . 72*2de3b87aSKai Wang.Sh RETURN VALUES 73*2de3b87aSKai WangFunction 74*2de3b87aSKai Wang.Fn dwarf_srcfiles 75*2de3b87aSKai Wangreturns 76*2de3b87aSKai Wang.Dv DW_DLV_OK 77*2de3b87aSKai Wangwhen it succeeds. 78*2de3b87aSKai WangIn case of an error, it returns 79*2de3b87aSKai Wang.Dv DW_DLV_ERROR 80*2de3b87aSKai Wangand sets the argument 81*2de3b87aSKai Wang.Ar err . 82*2de3b87aSKai Wang.Sh ERRORS 83*2de3b87aSKai WangFunction 84*2de3b87aSKai Wang.Fn dwarf_srcfiles 85*2de3b87aSKai Wangcan fail with: 86*2de3b87aSKai Wang.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT" 87*2de3b87aSKai Wang.It Bq Er DW_DLE_ARGUMENT 88*2de3b87aSKai WangOne of the arguments 89*2de3b87aSKai Wang.Ar die , 90*2de3b87aSKai Wang.Ar filenames 91*2de3b87aSKai Wangor 92*2de3b87aSKai Wang.Ar filenamecount 93*2de3b87aSKai Wangwas NULL. 94*2de3b87aSKai Wang.It Bq Er DW_DLE_NO_ENTRY 95*2de3b87aSKai WangThe compilation unit referenced by argument 96*2de3b87aSKai Wang.Ar die 97*2de3b87aSKai Wangdoes not have associated source file information. 98*2de3b87aSKai Wang.It Bq Er DW_DLE_MEMORY 99*2de3b87aSKai WangAn out of memory condition was encountered during the execution of 100*2de3b87aSKai Wangthis function. 101*2de3b87aSKai Wang.El 102*2de3b87aSKai Wang.Sh SEE ALSO 103*2de3b87aSKai Wang.Xr dwarf 3 , 104*2de3b87aSKai Wang.Xr dwarf_dealloc 3 , 105*2de3b87aSKai Wang.Xr dwarf_srclines 3 106