Annotation of src/external/bsd/elftoolchain/dist/libdwarf/dwarf_lineno.3, Revision 1.1.1.2
1.1.1.2 ! christos 1: .\" $NetBSD$
! 2: .\"
1.1 christos 3: .\" Copyright (c) 2011 Kai Wang
4: .\" All rights reserved.
5: .\"
6: .\" Redistribution and use in source and binary forms, with or without
7: .\" modification, are permitted provided that the following conditions
8: .\" are met:
9: .\" 1. Redistributions of source code must retain the above copyright
10: .\" notice, this list of conditions and the following disclaimer.
11: .\" 2. Redistributions in binary form must reproduce the above copyright
12: .\" notice, this list of conditions and the following disclaimer in the
13: .\" documentation and/or other materials provided with the distribution.
14: .\"
15: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25: .\" SUCH DAMAGE.
26: .\"
27: .\" Id: dwarf_lineno.3 2074 2011-10-27 03:34:33Z jkoshy
28: .\"
29: .Dd February 5, 2011
30: .Os
31: .Dt DWARF_LINENO 3
32: .Sh NAME
33: .Nm dwarf_lineaddr ,
34: .Nm dwarf_linebeginstatement ,
35: .Nm dwarf_lineblock ,
36: .Nm dwarf_lineendsequence ,
37: .Nm dwarf_lineno ,
38: .Nm dwarf_lineoff ,
39: .Nm dwarf_linesrc ,
40: .Nm dwarf_line_srcfileno
41: .Nd retrieve information associated with a DWARF line descriptor
42: .Sh LIBRARY
43: .Lb libdwarf
44: .Sh SYNOPSIS
45: .In libdwarf.h
46: .Ft int
47: .Fo dwarf_lineaddr
48: .Fa "Dwarf_Line ln"
49: .Fa "Dwarf_Addr *ret"
50: .Fa "Dwarf_Error *err"
51: .Fc
52: .Ft int
53: .Fo dwarf_linebeginstatement
54: .Fa "Dwarf_Line ln"
55: .Fa "Dwarf_Bool *ret"
56: .Fa "Dwarf_Error *err"
57: .Fc
58: .Ft int
59: .Fo dwarf_lineblock
60: .Fa "Dwarf_Line ln"
61: .Fa "Dwarf_Bool *ret"
62: .Fa "Dwarf_Error *err"
63: .Fc
64: .Ft int
65: .Fo dwarf_lineendsequence
66: .Fa "Dwarf_Line ln"
67: .Fa "Dwarf_Bool *ret"
68: .Fa "Dwarf_Error *err"
69: .Fc
70: .Ft int
71: .Fo dwarf_lineno
72: .Fa "Dwarf_Line ln"
73: .Fa "Dwarf_Unsigned *ret"
74: .Fa "Dwarf_Error *err"
75: .Fc
76: .Ft int
77: .Fo dwarf_lineoff
78: .Fa "Dwarf_Line ln"
79: .Fa "Dwarf_Signed *ret"
80: .Fa "Dwarf_Error *err"
81: .Fc
82: .Ft int
83: .Fo dwarf_linesrc
84: .Fa "Dwarf_Line ln"
85: .Fa "char **ret"
86: .Fa "Dwarf_Error *err"
87: .Fc
88: .Ft int
89: .Fo dwarf_line_srcfileno
90: .Fa "Dwarf_Line ln"
91: .Fa "Dwarf_Unsigned *ret"
92: .Fa "Dwarf_Error *err"
93: .Fc
94: .Sh DESCRIPTION
95: These functions retrieve specific line information associated with
96: the line descriptor specified by argument
97: .Ar ln ,
98: and stores it in the location pointed to by argument
99: .Ar ret .
100: If argument
101: .Ar err
102: is not NULL, it will be used to store error information in case of an
103: error.
104: .Pp
105: Function
106: .Fn dwarf_lineaddr
107: stores the program address corresponding to the source line specified
108: in argument
109: .Ar ln
110: into the location pointed to by argument
111: .Ar ret .
112: .Pp
113: Function
114: .Fn dwarf_linebeginstatement
115: sets the location pointed to by argument
116: .Ar ret
117: to 1 if the source line specified by the line descriptor
118: .Ar ln
119: is the beginning of a statement, or to 0 otherwise.
120: .Pp
121: Function
122: .Fn dwarf_lineblock
123: sets the location pointed to by argument
124: .Ar ret
125: to 1 if the source line specified by the line descriptor
126: .Ar ln
127: is the beginning of a basic block, or to 0 otherwise.
128: .Pp
129: Function
130: .Fn dwarf_lineendsequence
131: sets the location pointed to by argument
132: .Ar ret
133: to 1 if the program address associated with the line descriptor
134: .Ar ln
135: is the address immediately following the end of a sequence of target
136: machine instructions, or to 0 otherwise.
137: .Pp
138: Function
139: .Fn dwarf_lineno
140: stores the line number of the source line associated with the line
141: descriptor
142: .Ar ln
143: into the location pointed to by argument
144: .Ar ret .
145: .Pp
146: Function
147: .Fn dwarf_lineoff
148: stores the column number within a line associated with descriptor
149: .Ar ln
150: into the location pointed to by argument
151: .Ar ret .
152: The retrieved column numbers are 1-based, with the value -1 indicating
153: that column number information was not available.
154: .Pp
155: Function
156: .Fn dwarf_linesrc
157: stores a pointer to a NUL-terminated string containing the source file
158: name associated with line descriptor
159: .Ar ln
160: into the location pointed to by argument
161: .Ar ret .
162: The full path of the source file is returned if possible.
163: The memory used for the source file name string is managed by the DWARF(3)
164: library and should not be directly freed by application code.
165: Instead, portable code should use
166: .Xr dwarf_dealloc 3
167: to indicate that the string should be freed.
168: .Pp
169: Function
170: .Fn dwarf_line_srcfileno
171: stores the index of the source file associated with the line descriptor
172: .Ar ln
173: in the location pointed to by argument
174: .Ar ret .
175: The returned value is 1-based index into the array of source file
176: names returned by
177: .Xr dwarf_srcfiles 3 .
178: .Sh RETURN VALUES
179: On success, these functions returns
180: .Dv DW_DLV_OK .
181: In case of an error, they return
182: .Dv DW_DLV_ERROR
183: and set the argument
184: .Ar err .
185: .Sh ERRORS
186: These functions may fail with the following errors:
187: .Bl -tag -width ".Bq Er DW_DLE_LINE_FILE_NUM_BAD"
188: .It Bq Er DW_DLE_ARGUMENT
189: Either of the arguments
190: .Va ln
191: or
192: .Va ret
193: was NULL.
194: .It Bq Er DW_DLE_LINE_FILE_NUM_BAD
195: The source file name associated with the line descriptor
196: .Ar ln
197: could not be retrieved by function
198: .Fn dwarf_linesrc .
199: .El
200: .Sh SEE ALSO
201: .Xr dwarf 3 ,
202: .Xr dwarf_dealloc 3 ,
203: .Xr dwarf_srcfiles 3 ,
204: .Xr dwarf_srclines 3
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to dwarf_lineno.3 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / external / bsd / elftoolchain / dist / libdwarf