<html lang="en">
<head>
<title>String Field - STABS</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="STABS">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Overview.html#Overview" title="Overview">
<link rel="prev" href="Stabs-Format.html#Stabs-Format" title="Stabs Format">
<link rel="next" href="C-Example.html#C-Example" title="C Example">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
Copyright (C) 1992-2019 Free Software Foundation, Inc.
Contributed by Cygnus Support.  Written by Julia Menapace, Jim Kingdon,
and David MacKenzie.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled ``GNU
Free Documentation License''.-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
--></style>
</head>
<body>
<div class="node">
<a name="String-Field"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="C-Example.html#C-Example">C Example</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="Stabs-Format.html#Stabs-Format">Stabs Format</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Overview.html#Overview">Overview</a>
<hr>
</div>

<h3 class="section">1.3 The String Field</h3>

<p>For most stabs the string field holds the meat of the
debugging information.  The flexible nature of this field
is what makes stabs extensible.  For some stab types the string field
contains only a name.  For other stab types the contents can be a great
deal more complex.

   <p>The overall format of the string field for most stab types is:

<pre class="example">     "<var>name</var>:<var>symbol-descriptor</var> <var>type-information</var>"
</pre>
   <p><var>name</var> is the name of the symbol represented by the stab; it can
contain a pair of colons (see <a href="Nested-Symbols.html#Nested-Symbols">Nested Symbols</a>).  <var>name</var> can be
omitted, which means the stab represents an unnamed object.  For
example, &lsquo;<samp><span class="samp">:t10=*2</span></samp>&rsquo; defines type 10 as a pointer to type 2, but does
not give the type a name.  Omitting the <var>name</var> field is supported by
AIX dbx and GDB after about version 4.8, but not other debuggers.  GCC
sometimes uses a single space as the name instead of omitting the name
altogether; apparently that is supported by most debuggers.

   <p>The <var>symbol-descriptor</var> following the &lsquo;<samp><span class="samp">:</span></samp>&rsquo; is an alphabetic
character that tells more specifically what kind of symbol the stab
represents. If the <var>symbol-descriptor</var> is omitted, but type
information follows, then the stab represents a local variable.  For a
list of symbol descriptors, see <a href="Symbol-Descriptors.html#Symbol-Descriptors">Symbol Descriptors</a>.  The &lsquo;<samp><span class="samp">c</span></samp>&rsquo;
symbol descriptor is an exception in that it is not followed by type
information.  See <a href="Constants.html#Constants">Constants</a>.

   <p><var>type-information</var> is either a <var>type-number</var>, or
&lsquo;<samp><var>type-number</var><span class="samp">=</span></samp>&rsquo;.  A <var>type-number</var> alone is a type
reference, referring directly to a type that has already been defined.

   <p>The &lsquo;<samp><var>type-number</var><span class="samp">=</span></samp>&rsquo; form is a type definition, where the
number represents a new type which is about to be defined.  The type
definition may refer to other types by number, and those type numbers
may be followed by &lsquo;<samp><span class="samp">=</span></samp>&rsquo; and nested definitions.  Also, the Lucid
compiler will repeat &lsquo;<samp><var>type-number</var><span class="samp">=</span></samp>&rsquo; more than once if it
wants to define several type numbers at once.

   <p>In a type definition, if the character that follows the equals sign is
non-numeric then it is a <var>type-descriptor</var>, and tells what kind of
type is about to be defined.  Any other values following the
<var>type-descriptor</var> vary, depending on the <var>type-descriptor</var>. 
See <a href="Type-Descriptors.html#Type-Descriptors">Type Descriptors</a>, for a list of <var>type-descriptor</var> values.  If
a number follows the &lsquo;<samp><span class="samp">=</span></samp>&rsquo; then the number is a <var>type-reference</var>. 
For a full description of types, <a href="Types.html#Types">Types</a>.

   <p>A <var>type-number</var> is often a single number.  The GNU and Sun tools
additionally permit a <var>type-number</var> to be a pair
(<var>file-number</var>,<var>filetype-number</var>) (the parentheses appear in the
string, and serve to distinguish the two cases).  The <var>file-number</var>
is 0 for the base source file, 1 for the first included file, 2 for the
next, and so on.  The <var>filetype-number</var> is a number starting with
1 which is incremented for each new type defined in the file. 
(Separating the file number and the type number permits the
<code>N_BINCL</code> optimization to succeed more often; see <a href="Include-Files.html#Include-Files">Include Files</a>).

   <p>There is an AIX extension for type attributes.  Following the &lsquo;<samp><span class="samp">=</span></samp>&rsquo;
are any number of type attributes.  Each one starts with &lsquo;<samp><span class="samp">@</span></samp>&rsquo; and
ends with &lsquo;<samp><span class="samp">;</span></samp>&rsquo;.  Debuggers, including AIX's dbx and GDB 4.10, skip
any type attributes they do not recognize.  GDB 4.9 and other versions
of dbx may not do this.  Because of a conflict with C<tt>++</tt>
(see <a href="Cplusplus.html#Cplusplus">Cplusplus</a>), new attributes should not be defined which begin
with a digit, &lsquo;<samp><span class="samp">(</span></samp>&rsquo;, or &lsquo;<samp><span class="samp">-</span></samp>&rsquo;; GDB may be unable to distinguish
those from the C<tt>++</tt> type descriptor &lsquo;<samp><span class="samp">@</span></samp>&rsquo;.  The attributes are:

     <dl>
<dt><code>a</code><var>boundary</var><dd><var>boundary</var> is an integer specifying the alignment.  I assume it
applies to all variables of this type.

     <br><dt><code>p</code><var>integer</var><dd>Pointer class (for checking).  Not sure what this means, or how
<var>integer</var> is interpreted.

     <br><dt><code>P</code><dd>Indicate this is a packed type, meaning that structure fields or array
elements are placed more closely in memory, to save memory at the
expense of speed.

     <br><dt><code>s</code><var>size</var><dd>Size in bits of a variable of this type.  This is fully supported by GDB
4.11 and later.

     <br><dt><code>S</code><dd>Indicate that this type is a string instead of an array of characters,
or a bitstring instead of a set.  It doesn't change the layout of the
data being represented, but does enable the debugger to know which type
it is.

     <br><dt><code>V</code><dd>Indicate that this type is a vector instead of an array.  The only
major difference between vectors and arrays is that vectors are
passed by value instead of by reference (vector coprocessor extension).

   </dl>

   <p>All of this can make the string field quite long.  All versions of GDB,
and some versions of dbx, can handle arbitrarily long strings.  But many
versions of dbx (or assemblers or linkers, I'm not sure which)
cretinously limit the strings to about 80 characters, so compilers which
must work with such systems need to split the <code>.stabs</code> directive
into several <code>.stabs</code> directives.  Each stab duplicates every field
except the string field.  The string field of every stab except the last
is marked as continued with a backslash at the end (in the assembly code
this may be written as a double backslash, depending on the assembler). 
Removing the backslashes and concatenating the string fields of each
stab produces the original, long string.  Just to be incompatible (or so
they don't have to worry about what the assembler does with
backslashes), AIX can use &lsquo;<samp><span class="samp">?</span></samp>&rsquo; instead of backslash.

   </body></html>