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

   1 .\"     $NetBSD: dwarf_add_expr_addr.3,v 1.2 2014/03/09 16:58:03 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_add_expr_addr.3 2072 2011-10-27 03:26:49Z jkoshy
  28 .\"
  29 .Dd September 9, 2011
  30 .Os
  31 .Dt DWARF_ADD_EXPR_ADDR 3
  32 .Sh NAME
  33 .Nm dwarf_add_expr_addr ,
  34 .Nm dwarf_add_expr_addr_b
  35 .Nd add a DW_OP_addr location expression
  36 .Sh LIBRARY
  37 .Lb libdwarf
  38 .Sh SYNOPSIS
  39 .In libdwarf.h
  40 .Ft "Dwarf_Unsigned"
  41 .Fo dwarf_add_expr_addr
  42 .Fa "Dwarf_P_Expr expr"
  43 .Fa "Dwarf_Unsigned address"
  44 .Fa "Dwarf_Signed sym_index"
  45 .Fa "Dwarf_Error *err"
  46 .Fc
  47 .Ft "Dwarf_Unsigned"
  48 .Fo dwarf_add_expr_addr_b
  49 .Fa "Dwarf_P_Expr expr"
  50 .Fa "Dwarf_Unsigned address"
  51 .Fa "Dwarf_Unsigned sym_index"
  52 .Fa "Dwarf_Error *err"
  53 .Fc
  54 .Sh DESCRIPTION
  55 Function
  56 .Fn dwarf_add_expr_addr_b
  57 adds a
  58 .Dv DW_OP_addr
  59 location expression to the location expression descriptor referenced
  60 by argument
  61 .Ar expr .
  62 .Pp
  63 Argument
  64 .Ar expr
  65 should reference a location expression descriptor allocated using
  66 the function
  67 .Xr dwarf_new_expr 3 .
  68 .Pp
  69 Argument
  70 .Ar address
  71 specifies the operand, a relocatable address value.
  72 .Pp
  73 Argument
  74 .Ar sym_index
  75 specifies the ELF symbol index of the symbol to be used for
  76 relocation.
  77 .Pp
  78 If argument
  79 .Ar err
  80 is not NULL, it will be used to store error information in case
  81 of an error.
  82 .Pp
  83 Function
  84 .Fn dwarf_add_expr_addr
  85 is deprecated.
  86 It is similar to function
  87 .Fn dwarf_add_expr_addr_b
  88 except that it cannot handle all possible symbol index values.
  89 .Sh RETURN VALUES
  90 On success, these functions return the size in bytes of the location
  91 expression byte stream generated.
  92 In case of an error, these functions return
  93 .Dv DW_DLV_NOCOUNT
  94 and set the argument
  95 .Ar err .
  96 .Sh ERRORS
  97 These functions can fail with:
  98 .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
  99 .It Bq Er DW_DLE_ARGUMENT
 100 Argument
 101 .Ar expr
 102 was NULL.
 103 .It Bq Er DW_DLE_MEMORY
 104 An out of memory condition was encountered during the execution of
 105 the function.
 106 .El
 107 .Sh SEE ALSO
 108 .Xr dwarf 3 ,
 109 .Xr dwarf_add_AT_location_expr 3 ,
 110 .Xr dwarf_add_expr_gen 3 ,
 111 .Xr dwarf_expr_current_offset 3 ,
 112 .Xr dwarf_expr_into_block 3 ,
 113 .Xr dwarf_new_expr 3