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

   1 .\"     $NetBSD: dwarf_add_AT_ref_address.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_AT_ref_address.3 2072 2011-10-27 03:26:49Z jkoshy
  28 .\"
  29 .Dd September 7, 2011
  30 .Os
  31 .Dt DWARF_ADD_AT_REF_ADDRESS 3
  32 .Sh NAME
  33 .Nm dwarf_add_AT_ref_address
  34 .Nd create a reference class attribute descriptor
  35 .Sh LIBRARY
  36 .Lb libdwarf
  37 .Sh SYNOPSIS
  38 .In libdwarf.h
  39 .Ft "Dwarf_P_Attribute"
  40 .Fo dwarf_add_AT_ref_address
  41 .Fa "Dwarf_P_Debug dbg"
  42 .Fa "Dwarf_P_Die die"
  43 .Fa "Dwarf_Half attr"
  44 .Fa "Dwarf_Unsigned pc_value"
  45 .Fa "Dwarf_Unsigned sym_index"
  46 .Fa "Dwarf_Error *err"
  47 .Fc
  48 .Sh DESCRIPTION
  49 Function
  50 .Fn dwarf_add_AT_ref_address
  51 creates a
  52 .Sq reference
  53 class attribute descriptor containing a relocatable address value.
  54 The created attribute will use DWARF form
  55 .Dv DW_FORM_ref_addr .
  56 .Pp
  57 Argument
  58 .Ar dbg
  59 should reference a DWARF producer instance allocated using
  60 .Xr dwarf_producer_init 3
  61 or
  62 .Xr dwarf_producer_init_b 3 .
  63 .Pp
  64 Argument
  65 .Ar die
  66 should reference a debugging information entry allocated using
  67 .Xr dwarf_new_die 3 .
  68 .Pp
  69 Argument
  70 .Ar attr
  71 specifies the attribute code of the created attribute.
  72 .Pp
  73 Argument
  74 .Ar pc_value
  75 contains a relocatable address which will become the value of the
  76 created attribute.
  77 .Pp
  78 Argument
  79 .Ar sym_index
  80 should specify the ELF symbol index of the symbol to be used when
  81 relocating the address value.
  82 .Pp
  83 If argument
  84 .Ar err
  85 is not NULL, it will be used to store error information in case
  86 of an error.
  87 .Sh RETURN VALUES
  88 On success, function
  89 .Fn dwarf_add_AT_ref_address
  90 returns the created attribute descriptor.
  91 In case of an error, function
  92 .Fn dwarf_add_AT_ref_address
  93 returns
  94 .Dv DW_DLV_BADADDR
  95 and sets the argument
  96 .Ar err .
  97 .Sh ERRORS
  98 Function
  99 .Fn dwarf_add_AT_ref_address
 100 can fail with:
 101 .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
 102 .It Bq Er DW_DLE_ARGUMENT
 103 Either of the arguments
 104 .Ar dbg
 105 or
 106 .Ar die
 107 was NULL.
 108 .It Bq Er DW_DLE_MEMORY
 109 An out of memory condition was encountered during execution.
 110 .El
 111 .Sh SEE ALSO
 112 .Xr dwarf 3 ,
 113 .Xr dwarf_add_AT_dataref 3 ,
 114 .Xr dwarf_add_AT_reference 3 ,
 115 .Xr dwarf_add_AT_signed_const 3 ,
 116 .Xr dwarf_add_AT_unsigned_const 3 ,
 117 .Xr dwarf_new_die 3 ,
 118 .Xr dwarf_producer_init 3 ,
 119 .Xr dwarf_producer_init_b 3