mingw/info/stabs/String-Field.html

   1 <html lang="en">
   2 <head>
   3 <title>STABS</title>
   4 <meta http-equiv="Content-Type" content="text/html">
   5 <meta name="description" content="STABS">
   6 <meta name="generator" content="makeinfo 4.3">
   7 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home">
   8 </head>
   9 <body>
  10 <div class="node">
  11 <p>
  12 Node:<a name="String%20Field">String Field</a>,
  13 Next:<a rel="next" accesskey="n" href="C-Example.html#C%20Example">C Example</a>,
  14 Previous:<a rel="previous" accesskey="p" href="Stabs-Format.html#Stabs%20Format">Stabs Format</a>,
  15 Up:<a rel="up" accesskey="u" href="Overview.html#Overview">Overview</a>
  16 <hr><br>
  17 </div>
  18
  19 <h3 class="section">The String Field</h3>
  20
  21    <p>For most stabs the string field holds the meat of the
  22 debugging information.  The flexible nature of this field
  23 is what makes stabs extensible.  For some stab types the string field
  24 contains only a name.  For other stab types the contents can be a great
  25 deal more complex.
  26
  27    <p>The overall format of the string field for most stab types is:
  28
  29 <pre class="example">     "<var>name</var>:<var>symbol-descriptor</var> <var>type-information</var>"
  30      </pre>
  31
  32    <p><var>name</var> is the name of the symbol represented by the stab; it can
  33 contain a pair of colons (see <a href="Nested-Symbols.html#Nested%20Symbols">Nested Symbols</a>).  <var>name</var> can be
  34 omitted, which means the stab represents an unnamed object.  For
  35 example, <code>:t10=*2</code> defines type 10 as a pointer to type 2, but does
  36 not give the type a name.  Omitting the <var>name</var> field is supported by
  37 AIX dbx and GDB after about version 4.8, but not other debuggers.  GCC
  38 sometimes uses a single space as the name instead of omitting the name
  39 altogether; apparently that is supported by most debuggers.
  40
  41    <p>The <var>symbol-descriptor</var> following the <code>:</code> is an alphabetic
  42 character that tells more specifically what kind of symbol the stab
  43 represents. If the <var>symbol-descriptor</var> is omitted, but type
  44 information follows, then the stab represents a local variable.  For a
  45 list of symbol descriptors, see <a href="Symbol-Descriptors.html#Symbol%20Descriptors">Symbol Descriptors</a>.  The <code>c</code>
  46 symbol descriptor is an exception in that it is not followed by type
  47 information.  See <a href="Constants.html#Constants">Constants</a>.
  48
  49    <p><var>type-information</var> is either a <var>type-number</var>, or
  50 <code></code><var>type-number</var><code>=</code>.  A <var>type-number</var> alone is a type
  51 reference, referring directly to a type that has already been defined.
  52
  53    <p>The <code></code><var>type-number</var><code>=</code> form is a type definition, where the
  54 number represents a new type which is about to be defined.  The type
  55 definition may refer to other types by number, and those type numbers
  56 may be followed by <code>=</code> and nested definitions.  Also, the Lucid
  57 compiler will repeat <code></code><var>type-number</var><code>=</code> more than once if it
  58 wants to define several type numbers at once.
  59
  60    <p>In a type definition, if the character that follows the equals sign is
  61 non-numeric then it is a <var>type-descriptor</var>, and tells what kind of
  62 type is about to be defined.  Any other values following the
  63 <var>type-descriptor</var> vary, depending on the <var>type-descriptor</var>.
  64 See <a href="Type-Descriptors.html#Type%20Descriptors">Type Descriptors</a>, for a list of <var>type-descriptor</var> values.  If
  65 a number follows the <code>=</code> then the number is a <var>type-reference</var>.
  66 For a full description of types, <a href="Types.html#Types">Types</a>.
  67
  68    <p>A <var>type-number</var> is often a single number.  The GNU and Sun tools
  69 additionally permit a <var>type-number</var> to be a pair
  70 (<var>file-number</var>,<var>filetype-number</var>) (the parentheses appear in the
  71 string, and serve to distinguish the two cases).  The <var>file-number</var>
  72 is 0 for the base source file, 1 for the first included file, 2 for the
  73 next, and so on.  The <var>filetype-number</var> is a number starting with
  74 1 which is incremented for each new type defined in the file.
  75 (Separating the file number and the type number permits the
  76 <code>N_BINCL</code> optimization to succeed more often; see <a href="Include-Files.html#Include%20Files">Include Files</a>).
  77
  78    <p>There is an AIX extension for type attributes.  Following the <code>=</code>
  79 are any number of type attributes.  Each one starts with <code>@</code> and
  80 ends with <code>;</code>.  Debuggers, including AIX's dbx and GDB 4.10, skip
  81 any type attributes they do not recognize.  GDB 4.9 and other versions
  82 of dbx may not do this.  Because of a conflict with C++
  83 (see <a href="Cplusplus.html#Cplusplus">Cplusplus</a>), new attributes should not be defined which begin
  84 with a digit, <code>(</code>, or <code>-</code>; GDB may be unable to distinguish
  85 those from the C++ type descriptor <code>@</code>.  The attributes are:
  86
  87      <dl>
  88 <dt><code>a</code><var>boundary</var><code></code>
  89      <dd><var>boundary</var> is an integer specifying the alignment.  I assume it
  90 applies to all variables of this type.
  91
  92      <br><dt><code>p</code><var>integer</var><code></code>
  93      <dd>Pointer class (for checking).  Not sure what this means, or how
  94 <var>integer</var> is interpreted.
  95
  96      <br><dt><code>P</code>
  97      <dd>Indicate this is a packed type, meaning that structure fields or array
  98 elements are placed more closely in memory, to save memory at the
  99 expense of speed.
 100
 101      <br><dt><code>s</code><var>size</var><code></code>
 102      <dd>Size in bits of a variable of this type.  This is fully supported by GDB
 103 4.11 and later.
 104
 105      <br><dt><code>S</code>
 106      <dd>Indicate that this type is a string instead of an array of characters,
 107 or a bitstring instead of a set.  It doesn't change the layout of the
 108 data being represented, but does enable the debugger to know which type
 109 it is.
 110 </dl>
 111
 112    <p>All of this can make the string field quite long.  All versions of GDB,
 113 and some versions of dbx, can handle arbitrarily long strings.  But many
 114 versions of dbx (or assemblers or linkers, I'm not sure which)
 115 cretinously limit the strings to about 80 characters, so compilers which
 116 must work with such systems need to split the <code>.stabs</code> directive
 117 into several <code>.stabs</code> directives.  Each stab duplicates every field
 118 except the string field.  The string field of every stab except the last
 119 is marked as continued with a backslash at the end (in the assembly code
 120 this may be written as a double backslash, depending on the assembler).
 121 Removing the backslashes and concatenating the string fields of each
 122 stab produces the original, long string.  Just to be incompatible (or so
 123 they don't have to worry about what the assembler does with
 124 backslashes), AIX can use <code>?</code> instead of backslash.
 125
 126    </body></html>
 127