contrib/elftoolchain/libdwarf/dwarf_add_AT_signed_const.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_signed_const.3 3640 2018-10-14 14:09:13Z jkoshy $
  26 .\"
  27 .Dd September 4, 2011
  28 .Dt DWARF_ADD_AT_SIGNED_CONST 3
  29 .Os
  30 .Sh NAME
  31 .Nm dwarf_add_AT_signed_const ,
  32 .Nm dwarf_add_AT_unsigned_const
  33 .Nd create and attach constant class attributes
  34 .Sh LIBRARY
  35 .Lb libdwarf
  36 .Sh SYNOPSIS
  37 .In libdwarf.h
  38 .Ft Dwarf_P_Attribute
  39 .Fo dwarf_add_AT_signed_const
  40 .Fa "Dwarf_P_Debug dbg"
  41 .Fa "Dwarf_P_Die die"
  42 .Fa "Dwarf_Half attr"
  43 .Fa "Dwarf_Signed value"
  44 .Fa "Dwarf_Error *err"
  45 .Fc
  46 .Ft Dwarf_P_Attribute
  47 .Fo dwarf_add_AT_unsigned_const
  48 .Fa "Dwarf_P_Debug dbg"
  49 .Fa "Dwarf_P_Die die"
  50 .Fa "Dwarf_Half attr"
  51 .Fa "Dwarf_Unsigned value"
  52 .Fa "Dwarf_Error *err"
  53 .Fc
  54 .Sh DESCRIPTION
  55 These functions create attribute descriptors belonging to the
  56 .Sq constant
  57 class
  58 and attach them to the debugging information entry referenced by
  59 argument
  60 .Ar die .
  61 .Pp
  62 Argument
  63 .Ar dbg
  64 should reference a DWARF producer instance allocated using
  65 .Xr dwarf_producer_init 3
  66 or
  67 .Xr dwarf_producer_init_b 3 .
  68 .Pp
  69 Argument
  70 .Ar die
  71 should reference a debugging information entry allocated using
  72 .Xr dwarf_new_die 3 .
  73 .Pp
  74 Argument
  75 .Ar attr
  76 specifies the attribute code of the created attribute descriptor.
  77 .Pp
  78 Function
  79 .Fn dwarf_add_AT_signed_const
  80 creates an attribute descriptor with the signed value specified in
  81 argument
  82 .Ar value .
  83 .Pp
  84 Function
  85 .Fn dwarf_add_AT_unsigned_const
  86 creates an attribute descriptor with the unsigned value specified in
  87 argument
  88 .Ar value .
  89 .Pp
  90 The attribute created by these function will have one of the
  91 DWARF forms
  92 .Dv DW_FORM_data1 ,
  93 .Dv DW_FORM_data2 ,
  94 .Dv DW_FORM_data4
  95 or
  96 .Dv DW_FORM_data8 ,
  97 depending on the size of the value specified in argument
  98 .Ar value .
  99 .Pp
 100 If argument
 101 .Ar err
 102 is not NULL, it will be used by these functions to store error
 103 information in case of an error.
 104 .Sh RETURN VALUES
 105 On success, these functions return the created attribute descriptor.
 106 In case of an error, these functions return
 107 .Dv DW_DLV_BADADDR
 108 and set the argument
 109 .Ar err .
 110 .Sh ERRORS
 111 These functions can fail with:
 112 .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
 113 .It Bq Er DW_DLE_ARGUMENT
 114 Either of the arguments
 115 .Ar dbg
 116 or
 117 .Ar die
 118 was NULL.
 119 .It Bq Er DW_DLE_MEMORY
 120 An out of memory condition was encountered during execution.
 121 .El
 122 .Sh SEE ALSO
 123 .Xr dwarf 3 ,
 124 .Xr dwarf_add_AT_const_value_signedint 3 ,
 125 .Xr dwarf_add_AT_const_value_unsignedint 3 ,
 126 .Xr dwarf_add_AT_dataref 3 ,
 127 .Xr dwarf_add_AT_ref_address 3 ,
 128 .Xr dwarf_add_AT_targ_address_b 3 ,
 129 .Xr dwarf_new_die 3 ,
 130 .Xr dwarf_producer_init 3 ,
 131 .Xr dwarf_producer_init_b 3