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

   1 .\"     $NetBSD: dwarf_add_AT_const_value_string.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_const_value_string.3 2072 2011-10-27 03:26:49Z jkoshy
  28 .\"
  29 .Dd September 4, 2011
  30 .Os
  31 .Dt DWARF_ADD_AT_CONST_VALUE_STRING 3
  32 .Sh NAME
  33 .Nm dwarf_add_AT_const_value_signedint ,
  34 .Nm dwarf_add_AT_const_value_string ,
  35 .Nm dwarf_add_AT_const_value_unsignedint
  36 .Nd create and attach a DW_AT_const_value attribute
  37 .Sh LIBRARY
  38 .Lb libdwarf
  39 .Sh SYNOPSIS
  40 .In libdwarf.h
  41 .Ft Dwarf_P_Attribute
  42 .Fo dwarf_add_AT_const_value_signedint
  43 .Fa "Dwarf_P_Die die"
  44 .Fa "Dwarf_Signed value"
  45 .Fa "Dwarf_Error *err"
  46 .Fc
  47 .Ft Dwarf_P_Attribute
  48 .Fo dwarf_add_AT_const_value_string
  49 .Fa "Dwarf_P_Die die"
  50 .Fa "char *str"
  51 .Fa "Dwarf_Error *err"
  52 .Fc
  53 .Ft Dwarf_P_Attribute
  54 .Fo dwarf_add_AT_const_value_unsignedint
  55 .Fa "Dwarf_P_Die die"
  56 .Fa "Dwarf_Unsigned value"
  57 .Fa "Dwarf_Error *err"
  58 .Fc
  59 .Sh DESCRIPTION
  60 These functions create a
  61 .Dv DW_AT_const_value
  62 attribute descriptor and attach it to the debugging information entry
  63 referenced by argument
  64 .Ar die .
  65 .Pp
  66 Argument
  67 .Ar die
  68 should reference a debugging information entry allocated using
  69 .Xr dwarf_new_die 3 .
  70 .Pp
  71 Function
  72 .Fn dwarf_add_AT_const_value_signedint
  73 creates a
  74 .Dv DW_AT_const_value
  75 attribute descriptor containing the signed value specified by argument
  76 .Ar value .
  77 The created attribute descriptor will have DWARF form
  78 .Dv DW_FORM_sdata .
  79 .Pp
  80 Function
  81 .Fn dwarf_add_AT_const_value_unsignedint
  82 creates a
  83 .Dv DW_AT_const_value
  84 attribute descriptor containing the unsigned value specified by
  85 argument
  86 .Ar value .
  87 The created attribute descriptor will have DWARF form
  88 .Dv DW_FORM_udata .
  89 .Pp
  90 Function
  91 .Fn dwarf_add_AT_const_value_string
  92 creates a
  93 .Dv DW_AT_const_value
  94 attribute descriptor containing the string pointed to by the
  95 NUL-terminated argument
  96 .Ar str .
  97 The created attribute descriptor will have DWARF form
  98 .Dv DW_FORM_strp .
  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 die
 116 or
 117 .Ar str
 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_name 3 ,
 125 .Xr dwarf_add_AT_signed_const 3 ,
 126 .Xr dwarf_add_AT_string 3 ,
 127 .Xr dwarf_add_AT_unsigned_const 3 ,
 128 .Xr dwarf_new_die 3