contrib/elftoolchain/libdwarf/dwarf_add_AT_location_expr.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_AT_location_expr.3 3640 2018-10-14 14:09:13Z jkoshy $
  26 .\"
  27 .Dd September 5, 2011
  28 .Dt DWARF_ADD_AT_LOCATION_EXPR 3
  29 .Os
  30 .Sh NAME
  31 .Nm dwarf_add_AT_location_expr
  32 .Nd create an attribute descriptor for a location expression
  33 .Sh LIBRARY
  34 .Lb libdwarf
  35 .Sh SYNOPSIS
  36 .In libdwarf.h
  37 .Ft "Dwarf_P_Attribute"
  38 .Fo dwarf_add_AT_location_expr
  39 .Fa "Dwarf_P_Debug dbg"
  40 .Fa "Dwarf_P_Die die"
  41 .Fa "Dwarf_Half attr"
  42 .Fa "Dwarf_P_Expr loc_expr"
  43 .Fa "Dwarf_Error *err"
  44 .Fc
  45 .Sh DESCRIPTION
  46 Function
  47 .Fn dwarf_add_AT_location_expr
  48 creates an attribute descriptor for a location expression and attaches
  49 it to the debugging information entry referenced by argument
  50 .Ar die .
  51 .Pp
  52 Argument
  53 .Ar dbg
  54 should reference a DWARF producer instance allocated using
  55 .Xr dwarf_producer_init 3
  56 or
  57 .Xr dwarf_producer_init_b 3 .
  58 .Pp
  59 Argument
  60 .Ar die
  61 should reference a debugging information entry allocated using
  62 .Xr dwarf_new_die 3 .
  63 .Pp
  64 Argument
  65 .Ar attr
  66 specifies the attribute code of the created attribute descriptor.
  67 .Pp
  68 Argument
  69 .Ar loc_expr
  70 should reference a location expression descriptor allocated using
  71 .Xr dwarf_new_expr 3 .
  72 .Pp
  73 The attribute created by function
  74 .Fn dwarf_add_AT_location_expr
  75 will have one of the DWARF forms
  76 .Dv DW_FORM_block ,
  77 .Dv DW_FORM_block1 ,
  78 .Dv DW_FORM_block2
  79 or
  80 .Dv DW_FORM_block4 ,
  81 depending on the size of the byte stream generated by the location
  82 expression descriptor referenced by argument
  83 .Ar loc_expr .
  84 .Pp
  85 If argument
  86 .Ar err
  87 is not NULL, it will be used by to store error information in case of
  88 an error.
  89 .Sh RETURN VALUES
  90 On success, function
  91 .Fn dwarf_add_AT_location_expr
  92 returns the created attribute descriptor.
  93 In case of an error, function
  94 .Fn dwarf_add_AT_location_expr
  95 returns
  96 .Dv DW_DLV_BADADDR
  97 and sets the argument
  98 .Ar err .
  99 .Sh ERRORS
 100 Function
 101 .Fn dwarf_add_AT_location_expr
 102 can fail with:
 103 .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
 104 .It Bq Er DW_DLE_ARGUMENT
 105 One of the arguments
 106 .Ar dbg ,
 107 .Ar die
 108 or
 109 .Ar loc_expr
 110 was NULL.
 111 .It Bq Er DW_DLE_MEMORY
 112 An out of memory condition was encountered during the execution of the
 113 function.
 114 .El
 115 .Sh SEE ALSO
 116 .Xr dwarf 3 ,
 117 .Xr dwarf_new_die 3 ,
 118 .Xr dwarf_new_expr 3 ,
 119 .Xr dwarf_producer_init 3 ,
 120 .Xr dwarf_producer_init_b 3