contrib/elftoolchain/libdwarf/dwarf_lineno.3

   1 .\" Copyright (c) 2011 Kai Wang
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   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.
  12 .\"
  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
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $Id: dwarf_lineno.3 2074 2011-10-27 03:34:33Z jkoshy $
  26 .\"
  27 .Dd February 5, 2011
  28 .Os
  29 .Dt DWARF_LINENO 3
  30 .Sh NAME
  31 .Nm dwarf_lineaddr ,
  32 .Nm dwarf_linebeginstatement ,
  33 .Nm dwarf_lineblock ,
  34 .Nm dwarf_lineendsequence ,
  35 .Nm dwarf_lineno ,
  36 .Nm dwarf_lineoff ,
  37 .Nm dwarf_linesrc ,
  38 .Nm dwarf_line_srcfileno
  39 .Nd retrieve information associated with a DWARF line descriptor
  40 .Sh LIBRARY
  41 .Lb libdwarf
  42 .Sh SYNOPSIS
  43 .In libdwarf.h
  44 .Ft int
  45 .Fo dwarf_lineaddr
  46 .Fa "Dwarf_Line ln"
  47 .Fa "Dwarf_Addr *ret"
  48 .Fa "Dwarf_Error *err"
  49 .Fc
  50 .Ft int
  51 .Fo dwarf_linebeginstatement
  52 .Fa "Dwarf_Line ln"
  53 .Fa "Dwarf_Bool *ret"
  54 .Fa "Dwarf_Error *err"
  55 .Fc
  56 .Ft int
  57 .Fo dwarf_lineblock
  58 .Fa "Dwarf_Line ln"
  59 .Fa "Dwarf_Bool *ret"
  60 .Fa "Dwarf_Error *err"
  61 .Fc
  62 .Ft int
  63 .Fo dwarf_lineendsequence
  64 .Fa "Dwarf_Line ln"
  65 .Fa "Dwarf_Bool *ret"
  66 .Fa "Dwarf_Error *err"
  67 .Fc
  68 .Ft int
  69 .Fo dwarf_lineno
  70 .Fa "Dwarf_Line ln"
  71 .Fa "Dwarf_Unsigned *ret"
  72 .Fa "Dwarf_Error *err"
  73 .Fc
  74 .Ft int
  75 .Fo dwarf_lineoff
  76 .Fa "Dwarf_Line ln"
  77 .Fa "Dwarf_Signed *ret"
  78 .Fa "Dwarf_Error *err"
  79 .Fc
  80 .Ft int
  81 .Fo dwarf_linesrc
  82 .Fa "Dwarf_Line ln"
  83 .Fa "char **ret"
  84 .Fa "Dwarf_Error *err"
  85 .Fc
  86 .Ft int
  87 .Fo dwarf_line_srcfileno
  88 .Fa "Dwarf_Line ln"
  89 .Fa "Dwarf_Unsigned *ret"
  90 .Fa "Dwarf_Error *err"
  91 .Fc
  92 .Sh DESCRIPTION
  93 These functions retrieve specific line information associated with
  94 the line descriptor specified by argument
  95 .Ar ln ,
  96 and stores it in the location pointed to by argument
  97 .Ar ret .
  98 If argument
  99 .Ar err
 100 is not NULL, it will be used to store error information in case of an
 101 error.
 102 .Pp
 103 Function
 104 .Fn dwarf_lineaddr
 105 stores the program address corresponding to the source line specified
 106 in argument
 107 .Ar ln
 108 into the location pointed to by argument
 109 .Ar ret .
 110 .Pp
 111 Function
 112 .Fn dwarf_linebeginstatement
 113 sets the location pointed to by argument
 114 .Ar ret
 115 to 1 if the source line specified by the line descriptor
 116 .Ar ln
 117 is the beginning of a statement, or to 0 otherwise.
 118 .Pp
 119 Function
 120 .Fn dwarf_lineblock
 121 sets the location pointed to by argument
 122 .Ar ret
 123 to 1 if the source line specified by the line descriptor
 124 .Ar ln
 125 is the beginning of a basic block, or to 0 otherwise.
 126 .Pp
 127 Function
 128 .Fn dwarf_lineendsequence
 129 sets the location pointed to by argument
 130 .Ar ret
 131 to 1 if the program address associated with the line descriptor
 132 .Ar ln
 133 is the address immediately following the end of a sequence of target
 134 machine instructions, or to 0 otherwise.
 135 .Pp
 136 Function
 137 .Fn dwarf_lineno
 138 stores the line number of the source line associated with the line
 139 descriptor
 140 .Ar ln
 141 into the location pointed to by argument
 142 .Ar ret .
 143 .Pp
 144 Function
 145 .Fn dwarf_lineoff
 146 stores the column number within a line associated with descriptor
 147 .Ar ln
 148 into the location pointed to by argument
 149 .Ar ret .
 150 The retrieved column numbers are 1-based, with the value -1 indicating
 151 that column number information was not available.
 152 .Pp
 153 Function
 154 .Fn dwarf_linesrc
 155 stores a pointer to a NUL-terminated string containing the source file
 156 name associated with line descriptor
 157 .Ar ln
 158 into the location pointed to by argument
 159 .Ar ret .
 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
 164 .Xr dwarf_dealloc 3
 165 to indicate that the string should be freed.
 166 .Pp
 167 Function
 168 .Fn dwarf_line_srcfileno
 169 stores the index of the source file associated with the line descriptor
 170 .Ar ln
 171 in the location pointed to by argument
 172 .Ar ret .
 173 The returned value is 1-based index into the array of source file
 174 names returned by
 175 .Xr dwarf_srcfiles 3 .
 176 .Sh RETURN VALUES
 177 On success, these functions returns
 178 .Dv DW_DLV_OK .
 179 In case of an error, they return
 180 .Dv DW_DLV_ERROR
 181 and set the argument
 182 .Ar err .
 183 .Sh ERRORS
 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
 188 .Va ln
 189 or
 190 .Va ret
 191 was NULL.
 192 .It Bq Er DW_DLE_LINE_FILE_NUM_BAD
 193 The source file name associated with the line descriptor
 194 .Ar ln
 195 could not be retrieved by function
 196 .Fn dwarf_linesrc .
 197 .El
 198 .Sh SEE ALSO
 199 .Xr dwarf 3 ,
 200 .Xr dwarf_dealloc 3 ,
 201 .Xr dwarf_srcfiles 3 ,
 202 .Xr dwarf_srclines 3