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

   1 .\"     $NetBSD: dwarf_srclines.3,v 1.2 2014/03/09 16:58:04 christos Exp $
   2 .\"
   3 .\" Copyright (c) 2010 Joseph Koshy.  All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" This software is provided by Joseph Koshy ``as is'' and
  15 .\" any express or implied warranties, including, but not limited to, the
  16 .\" implied warranties of merchantability and fitness for a particular purpose
  17 .\" are disclaimed.  in no event shall Joseph Koshy be liable
  18 .\" for any direct, indirect, incidental, special, exemplary, or consequential
  19 .\" damages (including, but not limited to, procurement of substitute goods
  20 .\" or services; loss of use, data, or profits; or business interruption)
  21 .\" however caused and on any theory of liability, whether in contract, strict
  22 .\" liability, or tort (including negligence or otherwise) arising in any way
  23 .\" out of the use of this software, even if advised of the possibility of
  24 .\" such damage.
  25 .\"
  26 .\" Id: dwarf_srclines.3 2122 2011-11-09 15:35:14Z jkoshy
  27 .\"
  28 .Dd November 9, 2011
  29 .Os
  30 .Dt DWARF_SRCLINES 3
  31 .Sh NAME
  32 .Nm dwarf_srclines
  33 .Nd retrieve line number information for a debugging information entry
  34 .Sh LIBRARY
  35 .Lb libdwarf
  36 .Sh SYNOPSIS
  37 .In libdwarf.h
  38 .Ft int
  39 .Fo dwarf_srclines
  40 .Fa "Dwarf_Die die"
  41 .Fa "Dwarf_Line **lines"
  42 .Fa "Dwarf_Signed *nlines"
  43 .Fa "Dwarf_Error *err"
  44 .Fc
  45 .Sh DESCRIPTION
  46 Function
  47 .Fn dwarf_srclines
  48 returns line number information associated with a compilation unit.
  49 Line number information is returned as an array of
  50 .Vt Dwarf_Line
  51 descriptors.
  52 .Pp
  53 Argument
  54 .Ar die
  55 should reference a DWARF debugging information entry descriptor
  56 with line number information, see
  57 .Xr dwarf 3 .
  58 Argument
  59 .Ar lines
  60 should point to a location that will hold a pointer to the returned array
  61 of
  62 .Vt Dwarf_Line
  63 descriptors.
  64 Argument
  65 .Ar nlines
  66 should point to a location that will hold the number of descriptors
  67 returned.
  68 If argument
  69 .Ar err
  70 is not NULL, it will be used to store error information in case of an
  71 error.
  72 .Pp
  73 The returned
  74 .Vt Dwarf_Line
  75 descriptors may be passed to the other line number functions in the
  76 API set to retrieve specific information about each source line.
  77 .Ss Memory Management
  78 The memory area used for the array of
  79 .Vt Dwarf_Line
  80 descriptors returned in argument
  81 .Ar lines
  82 is owned by the
  83 .Lb libdwarf .
  84 The application should not attempt to free this pointer.
  85 Portable code should instead use
  86 .Fn dwarf_srclines_dealloc
  87 to indicate that the memory may be freed.
  88 .Sh RETURN VALUES
  89 Function
  90 .Fn dwarf_srclines
  91 returns
  92 .Dv DW_DLV_OK
  93 when it succeeds.
  94 In case of an error, it returns
  95 .Dv DW_DLV_ERROR
  96 and sets the argument
  97 .Ar err .
  98 .Sh ERRORS
  99 Function
 100 .Fn dwarf_srclines
 101 can fail with:
 102 .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
 103 .It Bq Er DW_DLE_ARGUMENT
 104 One of the arguments
 105 .Ar die ,
 106 .Ar lines
 107 or
 108 .Ar nlines
 109 was NULL.
 110 .It Bq Er DW_DLE_NO_ENTRY
 111 The compilation unit referenced by argument
 112 .Ar die
 113 does not have associated line number information.
 114 .It Bq Er DW_DLE_MEMORY
 115 An out of memory condition was encountered during the execution of
 116 this function.
 117 .El
 118 .Sh EXAMPLE
 119 To obtain an array of
 120 .Vt Dwarf_Line
 121 descriptors and to retrieve the source file, line number, and virtual address
 122 associated with each descriptor:
 123 .Bd -literal -offset indent
 124 int n;
 125 Dwarf_Die die;
 126 Dwarf_Error de;
 127 char *filename;
 128 Dwarf_Line *lines;
 129 Dwarf_Signed nlines;
 130 Dwarf_Addr lineaddr;
 131 Dwarf_Unsigned lineno;
 132
 133 /* variable "die" should reference a DIE for a compilation unit */
 134
 135 if (dwarf_srclines(die, &lines, &nlines, &de) != DW_DLV_OK)
 136         errx(EXIT_FAILURE, "dwarf_srclines: %s", dwarf_errmsg(de));
 137
 138 for (n = 0; n < nlines; n++) {
 139         /* Retrieve the file name for this descriptor. */
 140         if (dwarf_linesrc(lines[n], &filename, &de))
 141                 errx(EXIT_FAILURE, "dwarf_linesrc: %s",
 142                     dwarf_errmsg(de));
 143
 144         /* Retrieve the line number in the source file. */
 145         if (dwarf_lineno(lines[n], &lineno, &de))
 146                 errx(EXIT_FAILURE, "dwarf_lineno: %s",
 147                     dwarf_errmsg(de));
 148         /* Retrieve the virtual address for this line. */
 149         if (dwarf_lineaddr(lines[n], &lineaddr, &de))
 150                 errx(EXIT_FAILURE, "dwarf_lineaddr: %s",
 151                     dwarf_errmsg(de));
 152         }
 153 .Ed
 154 .Sh SEE ALSO
 155 .Xr dwarf 3 ,
 156 .Xr dwarf_line_srcfileno 3 ,
 157 .Xr dwarf_lineaddr 3 ,
 158 .Xr dwarf_linebeginstatement 3 ,
 159 .Xr dwarf_lineblock 3 ,
 160 .Xr dwarf_lineendsequence 3 ,
 161 .Xr dwarf_lineno 3 ,
 162 .Xr dwarf_lineoff 3 ,
 163 .Xr dwarf_linesrc 3 ,
 164 .Xr dwarf_srcfiles 3 ,
 165 .Xr dwarf_srclines_dealloc 3