contrib/elftoolchain/libdwarf/dwarf_lne_set_address.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_lne_set_address.3 2074 2011-10-27 03:34:33Z jkoshy $
  26 .\"
  27 .Dd September 14, 2011
  28 .Os
  29 .Dt DWARF_LNE_SET_ADDRESS 3
  30 .Sh NAME
  31 .Nm dwarf_lne_set_address
  32 .Nd set the base address for line number information
  33 .Sh LIBRARY
  34 .Lb libdwarf
  35 .Sh SYNOPSIS
  36 .In libdwarf.h
  37 .Ft "Dwarf_Unsigned"
  38 .Fo dwarf_lne_set_address
  39 .Fa "Dwarf_P_Debug dbg"
  40 .Fa "Dwarf_Addr off"
  41 .Fa "Dwarf_Unsigned symndx"
  42 .Fa "Dwarf_Error *err"
  43 .Fc
  44 .Sh DESCRIPTION
  45 Function
  46 .Fn dwarf_lne_set_address
  47 sets the base address used by subsequent invocations of the
  48 .Xr dwarf_add_line_entry 3
  49 function.
  50 .Pp
  51 Argument
  52 .Ar dbg
  53 should reference a DWARF producer instance allocated using
  54 .Xr dwarf_producer_init 3
  55 or
  56 .Xr dwarf_producer_init_b 3 .
  57 .Pp
  58 Argument
  59 .Ar off
  60 specifies a relocatable program address.
  61 .Pp
  62 Argument
  63 .Ar symndx
  64 specifies the index of the ELF symbol to be used for relocation.
  65 .Pp
  66 If argument
  67 .Ar err
  68 is not NULL, it will be used to store error information in case
  69 of an error.
  70 .Sh RETURN VALUES
  71 On success, function
  72 .Fn dwarf_lne_set_address
  73 returns
  74 .Dv DW_DLV_OK .
  75 In case of an error, function
  76 .Fn dwarf_lne_set_address
  77 returns
  78 .Dv DW_DLV_NOCOUNT
  79 and sets the argument
  80 .Ar err .
  81 .Sh ERRORS
  82 Function
  83 .Fn dwarf_lne_set_address
  84 can fail with:
  85 .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
  86 .It Bq Er DW_DLE_ARGUMENT
  87 Argument
  88 .Ar dbg
  89 was NULL.
  90 .It Bq Er DW_DLE_ARGUMENT
  91 The argument
  92 .Ar symndx
  93 had an illegal value.
  94 .It Bq Er DW_DLE_MEMORY
  95 An out of memory condition was encountered during the execution of the
  96 function.
  97 .El
  98 .Sh SEE ALSO
  99 .Xr dwarf 3 ,
 100 .Xr dwarf_add_directory_decl 3 ,
 101 .Xr dwarf_add_file_decl 3 ,
 102 .Xr dwarf_add_line_entry 3 ,
 103 .Xr dwarf_lne_end_sequence 3 ,
 104 .Xr dwarf_producer_init 3 ,
 105 .Xr dwarf_producer_init_b 3