1 .\" Copyright (c) 2011 Kai Wang
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25 .\" $Id: dwarf_lineno.3 3640 2018-10-14 14:09:13Z jkoshy $
32 .Nm dwarf_linebeginstatement ,
34 .Nm dwarf_lineendsequence ,
38 .Nm dwarf_line_srcfileno
39 .Nd retrieve information associated with a DWARF line descriptor
48 .Fa "Dwarf_Error *err"
51 .Fo dwarf_linebeginstatement
54 .Fa "Dwarf_Error *err"
60 .Fa "Dwarf_Error *err"
63 .Fo dwarf_lineendsequence
66 .Fa "Dwarf_Error *err"
71 .Fa "Dwarf_Unsigned *ret"
72 .Fa "Dwarf_Error *err"
77 .Fa "Dwarf_Signed *ret"
78 .Fa "Dwarf_Error *err"
84 .Fa "Dwarf_Error *err"
87 .Fo dwarf_line_srcfileno
89 .Fa "Dwarf_Unsigned *ret"
90 .Fa "Dwarf_Error *err"
93 These functions retrieve specific line information associated with
94 the line descriptor specified by argument
96 and stores it in the location pointed to by argument
100 is not NULL, it will be used to store error information in case of an
105 stores the program address corresponding to the source line specified
108 into the location pointed to by argument
112 .Fn dwarf_linebeginstatement
113 sets the location pointed to by argument
115 to 1 if the source line specified by the line descriptor
117 is the beginning of a statement, or to 0 otherwise.
121 sets the location pointed to by argument
123 to 1 if the source line specified by the line descriptor
125 is the beginning of a basic block, or to 0 otherwise.
128 .Fn dwarf_lineendsequence
129 sets the location pointed to by argument
131 to 1 if the program address associated with the line descriptor
133 is the address immediately following the end of a sequence of target
134 machine instructions, or to 0 otherwise.
138 stores the line number of the source line associated with the line
141 into the location pointed to by argument
146 stores the column number within a line associated with descriptor
148 into the location pointed to by argument
150 The retrieved column numbers are 1-based, with the value -1 indicating
151 that column number information was not available.
155 stores a pointer to a NUL-terminated string containing the source file
156 name associated with line descriptor
158 into the location pointed to by argument
160 The full path of the source file is returned if possible.
161 The memory used for the source file name string is managed by the DWARF(3)
162 library and should not be directly freed by application code.
163 Instead, portable code should use
165 to indicate that the string should be freed.
168 .Fn dwarf_line_srcfileno
169 stores the index of the source file associated with the line descriptor
171 in the location pointed to by argument
173 The returned value is 1-based index into the array of source file
175 .Xr dwarf_srcfiles 3 .
177 On success, these functions returns
179 In case of an error, they return
184 These functions may fail with the following errors:
185 .Bl -tag -width ".Bq Er DW_DLE_LINE_FILE_NUM_BAD"
186 .It Bq Er DW_DLE_ARGUMENT
187 Either of the arguments
192 .It Bq Er DW_DLE_LINE_FILE_NUM_BAD
193 The source file name associated with the line descriptor
195 could not be retrieved by function
200 .Xr dwarf_dealloc 3 ,
201 .Xr dwarf_srcfiles 3 ,