libdwarf/dwarf_add_line_entry.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_add_line_entry.3 2953 2013-06-30 20:21:38Z kaiwang27 $
  26 .\"
  27 .Dd June 30, 2013
  28 .Os
  29 .Dt DWARF_ADD_LINE_ENTRY 3
  30 .Sh NAME
  31 .Nm dwarf_add_line_entry
  32 .Nd add a line number information entry to a producer instance
  33 .Sh LIBRARY
  34 .Lb libdwarf
  35 .Sh SYNOPSIS
  36 .In libdwarf.h
  37 .Ft "Dwarf_Unsigned"
  38 .Fo dwarf_add_line_entry
  39 .Fa "Dwarf_P_Debug dbg"
  40 .Fa "Dwarf_Unsigned filendx"
  41 .Fa "Dwarf_Addr off"
  42 .Fa "Dwarf_Unsigned lineno"
  43 .Fa "Dwarf_Signed column"
  44 .Fa "Dwarf_Bool is_stmt"
  45 .Fa "Dwarf_Bool basic_block"
  46 .Fa "Dwarf_Error *err"
  47 .Fc
  48 .Sh DESCRIPTION
  49 Function
  50 .Fn dwarf_add_line_entry
  51 adds a line number information entry to a DWARF producer instance.
  52 .Pp
  53 Argument
  54 .Ar dbg
  55 should reference a DWARF producer instance allocated using
  56 .Xr dwarf_producer_init 3
  57 or
  58 .Xr dwarf_producer_init_b 3 .
  59 .Pp
  60 Argument
  61 .Ar filendx
  62 specifies the index of the source file that contains the source line
  63 in question.
  64 Valid source file indices are those returned by the function
  65 .Xr dwarf_add_file_decl 3 .
  66 .Pp
  67 Argument
  68 .Ar off
  69 specifies a relocatable program address. The ELF symbol to be used
  70 for relocation is set by a prior call to the function
  71 .Xr dwarf_lne_set_address 3 .
  72 .Pp
  73 Argument
  74 .Ar lineno
  75 specifies the line number of the source line.
  76 .Pp
  77 Argument
  78 .Ar column
  79 specifies the column number within the source line.
  80 .Pp
  81 If the argument
  82 .Ar is_stmt
  83 is set to true, it indicates that the instruction at the address
  84 specified by argument
  85 .Ar off
  86 is a recommended breakpoint location, i.e., the first instruction in
  87 the instruction sequence generated by the source line.
  88 .Pp
  89 If the argument
  90 .Ar basic_block
  91 is set to true, it indicates that the instruction at the address
  92 specified by argument
  93 .Ar off
  94 is the first instruction of a basic block.
  95 .Pp
  96 If argument
  97 .Ar err
  98 is not NULL, it will be used to store error information in case
  99 of an error.
 100 .Sh RETURN VALUES
 101 On success, function
 102 .Fn dwarf_add_line_entry
 103 returns
 104 .Dv DW_DLV_OK .
 105 In case of an error, function
 106 .Fn dwarf_add_line_entry
 107 returns
 108 .Dv DW_DLV_NOCOUNT
 109 and sets the argument
 110 .Ar err .
 111 .Sh ERRORS
 112 Function
 113 .Fn dwarf_add_line_entry
 114 can fail with:
 115 .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
 116 .It Bq Er DW_DLE_ARGUMENT
 117 Argument
 118 .Ar dbg
 119 was NULL.
 120 .It Bq Er DW_DLE_ARGUMENT
 121 The function
 122 .Xr dwarf_lne_set_address 3
 123 was not called before calling this function.
 124 .It Bq Er DW_DLE_MEMORY
 125 An out of memory condition was encountered during the execution of the
 126 function.
 127 .El
 128 .Sh EXAMPLE
 129 To add line number information to the producer instance, use:
 130 .Bd -literal -offset indent
 131 Dwarf_P_Debug dbg;
 132 Dwarf_Error de;
 133 Dwarf_Unsigned dir, filendx;
 134
 135 /* ... assume dbg refers to a DWARF producer instance ... */
 136
 137 dir = dwarf_add_directory_decl(dbg, "/home/foo", &de);
 138 if (dir == DW_DLV_NOCOUNT)
 139         errx(EXIT_FAILURE, "dwarf_add_directory_decl failed: %s",
 140             dwarf_errmsg(-1));
 141
 142 filendx = dwarf_add_file_decl(dbg, "bar.c", dir, 0, 1234, &de);
 143 if (filendx == DW_DLV_NOCOUNT)
 144         errx(EXIT_FAILURE, "dwarf_add_file_decl failed: %s",
 145             dwarf_errmsg(-1));
 146
 147 if (dwarf_lne_set_address(dbg, 0x4012b0, 12, &de) != DW_DLV_OK)
 148         errx(EXIT_FAILURE, "dwarf_lne_set_address failed: %s",
 149             dwarf_errmsg(-1));
 150
 151 if (dwarf_add_line_entry(dbg, filendx, 10, 258, 0, 1, 1, &de) !=
 152     DW_DLV_OK)
 153         errx(EXIT_FAILURE, "dwarf_add_line_entry failed: %s",
 154             dwarf_errmsg(-1));
 155 .Ed
 156 .Sh SEE ALSO
 157 .Xr dwarf 3 ,
 158 .Xr dwarf_add_directory_decl 3 ,
 159 .Xr dwarf_add_file_decl 3 ,
 160 .Xr dwarf_lne_end_sequence 3 ,
 161 .Xr dwarf_lne_set_address 3 ,
 162 .Xr dwarf_producer_init 3 ,
 163 .Xr dwarf_producer_init_b 3