contrib/elftoolchain/libdwarf/dwarf_add_AT_const_value_string.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_const_value_string.3 3640 2018-10-14 14:09:13Z jkoshy $
  26 .\"
  27 .Dd September 4, 2011
  28 .Dt DWARF_ADD_AT_CONST_VALUE_STRING 3
  29 .Os
  30 .Sh NAME
  31 .Nm dwarf_add_AT_const_value_signedint ,
  32 .Nm dwarf_add_AT_const_value_string ,
  33 .Nm dwarf_add_AT_const_value_unsignedint
  34 .Nd create and attach a DW_AT_const_value attribute
  35 .Sh LIBRARY
  36 .Lb libdwarf
  37 .Sh SYNOPSIS
  38 .In libdwarf.h
  39 .Ft Dwarf_P_Attribute
  40 .Fo dwarf_add_AT_const_value_signedint
  41 .Fa "Dwarf_P_Die die"
  42 .Fa "Dwarf_Signed value"
  43 .Fa "Dwarf_Error *err"
  44 .Fc
  45 .Ft Dwarf_P_Attribute
  46 .Fo dwarf_add_AT_const_value_string
  47 .Fa "Dwarf_P_Die die"
  48 .Fa "char *str"
  49 .Fa "Dwarf_Error *err"
  50 .Fc
  51 .Ft Dwarf_P_Attribute
  52 .Fo dwarf_add_AT_const_value_unsignedint
  53 .Fa "Dwarf_P_Die die"
  54 .Fa "Dwarf_Unsigned value"
  55 .Fa "Dwarf_Error *err"
  56 .Fc
  57 .Sh DESCRIPTION
  58 These functions create a
  59 .Dv DW_AT_const_value
  60 attribute descriptor and attach it to the debugging information entry
  61 referenced by argument
  62 .Ar die .
  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 Function
  70 .Fn dwarf_add_AT_const_value_signedint
  71 creates a
  72 .Dv DW_AT_const_value
  73 attribute descriptor containing the signed value specified by argument
  74 .Ar value .
  75 The created attribute descriptor will have DWARF form
  76 .Dv DW_FORM_sdata .
  77 .Pp
  78 Function
  79 .Fn dwarf_add_AT_const_value_unsignedint
  80 creates a
  81 .Dv DW_AT_const_value
  82 attribute descriptor containing the unsigned value specified by
  83 argument
  84 .Ar value .
  85 The created attribute descriptor will have DWARF form
  86 .Dv DW_FORM_udata .
  87 .Pp
  88 Function
  89 .Fn dwarf_add_AT_const_value_string
  90 creates a
  91 .Dv DW_AT_const_value
  92 attribute descriptor containing the string pointed to by the
  93 NUL-terminated argument
  94 .Ar str .
  95 The created attribute descriptor will have DWARF form
  96 .Dv DW_FORM_strp .
  97 .Pp
  98 If argument
  99 .Ar err
 100 is not NULL, it will be used by these functions to store error
 101 information in case of an error.
 102 .Sh RETURN VALUES
 103 On success, these functions return the created attribute descriptor.
 104 In case of an error, these functions return
 105 .Dv DW_DLV_BADADDR
 106 and set the argument
 107 .Ar err .
 108 .Sh ERRORS
 109 These functions can fail with:
 110 .Bl -tag -width ".Bq Er DW_DLE_ARGUMENT"
 111 .It Bq Er DW_DLE_ARGUMENT
 112 Either of the arguments
 113 .Ar die
 114 or
 115 .Ar str
 116 was NULL.
 117 .It Bq Er DW_DLE_MEMORY
 118 An out of memory condition was encountered during execution.
 119 .El
 120 .Sh SEE ALSO
 121 .Xr dwarf 3 ,
 122 .Xr dwarf_add_AT_name 3 ,
 123 .Xr dwarf_add_AT_signed_const 3 ,
 124 .Xr dwarf_add_AT_string 3 ,
 125 .Xr dwarf_add_AT_unsigned_const 3 ,
 126 .Xr dwarf_new_die 3