external/bsd/elftoolchain/dist/libdwarf/dwarf_lineno.3

   1 .\"     $NetBSD: dwarf_lineno.3,v 1.2 2014/03/09 16:58:04 christos Exp $
   2 .\"
   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