1.\" Copyright (c) 2010 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_srcfiles.3 2075 2011-10-27 03:47:28Z jkoshy $
25.\"
26.Dd April 28, 2010
27.Os
28.Dt DWARF_SRCFILES 3
29.Sh NAME
30.Nm dwarf_srcfiles
31.Nd retrieve source file information
32.Sh LIBRARY
33.Lb libdwarf
34.Sh SYNOPSIS
35.In libdwarf.h
36.Ft int
37.Fo dwarf_srcfiles
38.Fa "Dwarf_Die die"
39.Fa "char ***filenames"
40.Fa "Dwarf_Signed *filenamecount"
41.Fa "Dwarf_Error *err"
42.Fc
43.Sh DESCRIPTION
44Function
45.Fn dwarf_srcfiles
46returns the source file names associated with a compilation unit.
47Source file names are returned as an array of NUL-terminated strings.
48.Pp
49Argument
50.Ar die
51should reference a DWARF debugging information entry descriptor with
52source file information, see
53.Xr dwarf 3 .
54Argument
55.Ar filenames
56should point to a location that will hold a pointer to the returned array
57of file names.
58Argument
59.Ar filenamecount
60should point to a location that will hold the number of file names returned.
61If argument
62.Ar err
63is not NULL, it will be used to store error information in case of an
64error.
65.Ss Memory Management
66The memory areas used for the file names and for array of pointers
67being returned are managed by the DWARF(3) library.
68The application should not attempt to directly free these memory areas.
69Portable code should indicate that the memory areas are to be freed
70by using
71.Xr dwarf_dealloc 3 .
72.Sh RETURN VALUES
73Function
74.Fn dwarf_srcfiles
75returns
76.Dv DW_DLV_OK
77when it succeeds.
78In case of an error, it returns
79.Dv DW_DLV_ERROR
80and sets the argument
81.Ar err .
82.Sh ERRORS
83Function
84.Fn dwarf_srcfiles
85can fail with:
86.Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
87.It Bq Er DW_DLE_ARGUMENT
88One of the arguments
89.Ar die ,
90.Ar filenames
91or
92.Ar filenamecount
93was NULL.
94.It Bq Er DW_DLE_NO_ENTRY
95The compilation unit referenced by argument
96.Ar die
97does not have associated source file information.
98.It Bq Er DW_DLE_MEMORY
99An out of memory condition was encountered during the execution of
100this function.
101.El
102.Sh SEE ALSO
103.Xr dwarf 3 ,
104.Xr dwarf_dealloc 3 ,
105.Xr dwarf_srclines 3
106