contrib/elftoolchain/libdwarf/dwarf_get_str.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_get_str.3 2071 2011-10-27 03:20:00Z jkoshy $
  26 .\"
  27 .Dd April 3, 2011
  28 .Os
  29 .Dt DWARF_GET_STR 3
  30 .Sh NAME
  31 .Nm dwarf_get_str
  32 .Nd retrieve a string from the DWARF string section
  33 .Sh LIBRARY
  34 .Lb libdwarf
  35 .Sh SYNOPSIS
  36 .In libdwarf.h
  37 .Ft int
  38 .Fo dwarf_get_str
  39 .Fa "Dwarf_Debug dbg"
  40 .Fa "Dwarf_Off offset"
  41 .Fa "char **string"
  42 .Fa "Dwarf_Signed *len"
  43 .Fa "Dwarf_Error *err"
  44 .Fc
  45 .Sh DESCRIPTION
  46 Function
  47 .Fn dwarf_get_str
  48 retrieves a NUL-terminated string from the DWARF string section
  49 .Dq ".debug_str" .
  50 .Pp
  51 Argument
  52 .Ar dbg
  53 should reference a DWARF debug context allocated using
  54 .Xr dwarf_init 3 .
  55 .Pp
  56 Argument
  57 .Ar offset
  58 should be an offset, relative to the
  59 .Dq ".debug_str"
  60 section, specifying the start of the desired string.
  61 .Pp
  62 Argument
  63 .Ar string
  64 should point to a location which will hold a returned
  65 pointer to a NUL-terminated string.
  66 .Pp
  67 Argument
  68 .Ar len
  69 should point to a location which will hold the length
  70 of the returned string.
  71 The returned length does not include the space needed for
  72 the NUL-terminator.
  73 .Pp
  74 If argument
  75 .Ar err
  76 is not NULL, it will be used to store error information in case of an
  77 error.
  78 .Sh RETURN VALUES
  79 Function
  80 .Fn dwarf_get_str
  81 returns
  82 .Dv DW_DLV_OK
  83 when it succeeds.
  84 It returns
  85 .Dv DW_DLV_NO_ENTRY
  86 if there is no
  87 .Dq ".debug_str"
  88 section associated with the specified debugging context,
  89 or if the provided offset
  90 .Ar offset
  91 is at the very end of
  92 .Dq ".debug_str"
  93 section.
  94 In case of an error, it returns
  95 .Dv DW_DLV_ERROR
  96 and sets the argument
  97 .Ar err .
  98 .Sh ERRORS
  99 Function
 100 .Fn dwarf_get_str
 101 can fail with:
 102 .Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY"
 103 .It Bq Er DW_DLE_ARGUMENT
 104 One of the arguments
 105 .Ar dbg ,
 106 .Ar string
 107 or
 108 .Ar len
 109 was NULL.
 110 .It Bq Er DW_DLE_ARGUMENT
 111 Argument
 112 .Ar offset
 113 was out of range.
 114 .It Bq Er DW_DLE_NO_ENTRY
 115 The debugging context
 116 .Ar dbg
 117 did not contain a
 118 .Dq ".debug_str"
 119 string section.
 120 .It Bq Er DW_DLE_NO_ENTRY
 121 Argument
 122 .Ar offset
 123 was at the very end of the
 124 .Dq ".debug_str"
 125 section.
 126 .El
 127 .Sh EXAMPLE
 128 To retrieve all the strings in the DWARF string section, use:
 129 .Bd -literal -offset indent
 130 Dwarf_Debug dbg;
 131 Dwarf_Off offset;
 132 Dwarf_Signed len;
 133 Dwarf_Error de;
 134 char *str;
 135 int ret
 136
 137 offset = 0;
 138 while ((ret = dwarf_get_str(dbg, offset, &str, &len, &de)) ==
 139         DW_DLV_OK) {
 140         /* .. Use the retrieved string. .. */
 141         offset += len + 1; /* Account for the terminating NUL. */
 142 }
 143
 144 if (ret == DW_DLV_ERROR)
 145         warnx("dwarf_get_str: %s", dwarf_errmsg(de));
 146 .Ed
 147 .Sh SEE ALSO
 148 .Xr dwarf 3 ,
 149 .Xr dwarf_init 3