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 3182 2015-04-10 16:08:10Z emaste $
  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.
  70 The ELF symbol to be used
  71 for relocation is set by a prior call to the function
  72 .Xr dwarf_lne_set_address 3 .
  73 .Pp
  74 Argument
  75 .Ar lineno
  76 specifies the line number of the source line.
  77 .Pp
  78 Argument
  79 .Ar column
  80 specifies the column number within the source line.
  81 .Pp
  82 If the argument
  83 .Ar is_stmt
  84 is set to true, it indicates that the instruction at the address
  85 specified by argument
  86 .Ar off
  87 is a recommended breakpoint location, i.e., the first instruction in
  88 the instruction sequence generated by the source line.
  89 .Pp
  90 If the argument
  91 .Ar basic_block
  92 is set to true, it indicates that the instruction at the address
  93 specified by argument
  94 .Ar off
  95 is the first instruction of a basic block.
  96 .Pp
  97 If argument
  98 .Ar err
  99 is not NULL, it will be used to store error information in case
 100 of an error.
 101 .Sh RETURN VALUES
 102 On success, function
 103 .Fn dwarf_add_line_entry
 104 returns
 105 .Dv DW_DLV_OK .
 106 In case of an error, function
 107 .Fn dwarf_add_line_entry
 108 returns
 109 .Dv DW_DLV_NOCOUNT
 110 and sets the argument
 111 .Ar err .
 112 .Sh ERRORS
 113 Function
 114 .Fn dwarf_add_line_entry
 115 can fail with:
 116 .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
 117 .It Bq Er DW_DLE_ARGUMENT
 118 Argument
 119 .Ar dbg
 120 was NULL.
 121 .It Bq Er DW_DLE_ARGUMENT
 122 The function
 123 .Xr dwarf_lne_set_address 3
 124 was not called before calling this function.
 125 .It Bq Er DW_DLE_MEMORY
 126 An out of memory condition was encountered during the execution of the
 127 function.
 128 .El
 129 .Sh EXAMPLE
 130 To add line number information to the producer instance, use:
 131 .Bd -literal -offset indent
 132 Dwarf_P_Debug dbg;
 133 Dwarf_Error de;
 134 Dwarf_Unsigned dir, filendx;
 135
 136 /* ... assume dbg refers to a DWARF producer instance ... */
 137
 138 dir = dwarf_add_directory_decl(dbg, "/home/foo", &de);
 139 if (dir == DW_DLV_NOCOUNT)
 140         errx(EXIT_FAILURE, "dwarf_add_directory_decl failed: %s",
 141             dwarf_errmsg(-1));
 142
 143 filendx = dwarf_add_file_decl(dbg, "bar.c", dir, 0, 1234, &de);
 144 if (filendx == DW_DLV_NOCOUNT)
 145         errx(EXIT_FAILURE, "dwarf_add_file_decl failed: %s",
 146             dwarf_errmsg(-1));
 147
 148 if (dwarf_lne_set_address(dbg, 0x4012b0, 12, &de) != DW_DLV_OK)
 149         errx(EXIT_FAILURE, "dwarf_lne_set_address failed: %s",
 150             dwarf_errmsg(-1));
 151
 152 if (dwarf_add_line_entry(dbg, filendx, 10, 258, 0, 1, 1, &de) !=
 153     DW_DLV_OK)
 154         errx(EXIT_FAILURE, "dwarf_add_line_entry failed: %s",
 155             dwarf_errmsg(-1));
 156 .Ed
 157 .Sh SEE ALSO
 158 .Xr dwarf 3 ,
 159 .Xr dwarf_add_directory_decl 3 ,
 160 .Xr dwarf_add_file_decl 3 ,
 161 .Xr dwarf_lne_end_sequence 3 ,
 162 .Xr dwarf_lne_set_address 3 ,
 163 .Xr dwarf_producer_init 3 ,
 164 .Xr dwarf_producer_init_b 3