xref: /freebsd/contrib/elftoolchain/libdwarf/dwarf_srcfiles.3 (revision 2de3b87a120614a3b053be7dd845b72f1e9ce804)
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