mingw/info/stabs/Include-Files.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="Include%20Files">Include Files</a>,
  13 Next:<a rel="next" accesskey="n" href="Line-Numbers.html#Line%20Numbers">Line Numbers</a>,
  14 Previous:<a rel="previous" accesskey="p" href="Source-Files.html#Source%20Files">Source Files</a>,
  15 Up:<a rel="up" accesskey="u" href="Program-Structure.html#Program%20Structure">Program Structure</a>
  16 <hr><br>
  17 </div>
  18
  19 <h3 class="section">Names of Include Files</h3>
  20
  21    <p>There are several schemes for dealing with include files: the
  22 traditional <code>N_SOL</code> approach, Sun's <code>N_BINCL</code> approach, and the
  23 XCOFF <code>C_BINCL</code> approach (which despite the similar name has little in
  24 common with <code>N_BINCL</code>).
  25
  26    <p>An <code>N_SOL</code> symbol specifies which include file subsequent symbols
  27 refer to.  The string field is the name of the file and the value is the
  28 text address corresponding to the end of the previous include file and
  29 the start of this one.  To specify the main source file again, use an
  30 <code>N_SOL</code> symbol with the name of the main source file.
  31
  32    <p>The <code>N_BINCL</code> approach works as follows.  An <code>N_BINCL</code> symbol
  33 specifies the start of an include file.  In an object file, only the
  34 string is significant; the linker puts data into some of the other
  35 fields.  The end of the include file is marked by an <code>N_EINCL</code>
  36 symbol (which has no string field).  In an object file, there is no
  37 significant data in the <code>N_EINCL</code> symbol.  <code>N_BINCL</code> and
  38 <code>N_EINCL</code> can be nested.
  39
  40    <p>If the linker detects that two source files have identical stabs between
  41 an <code>N_BINCL</code> and <code>N_EINCL</code> pair (as will generally be the case
  42 for a header file), then it only puts out the stabs once.  Each
  43 additional occurrence is replaced by an <code>N_EXCL</code> symbol.  I believe
  44 the GNU linker and the Sun (both SunOS4 and Solaris) linker are the only
  45 ones which supports this feature.
  46
  47    <p>A linker which supports this feature will set the value of a
  48 <code>N_BINCL</code> symbol to the total of all the characters in the stabs
  49 strings included in the header file, omitting any file numbers.  The
  50 value of an <code>N_EXCL</code> symbol is the same as the value of the
  51 <code>N_BINCL</code> symbol it replaces.  This information can be used to
  52 match up <code>N_EXCL</code> and <code>N_BINCL</code> symbols which have the same
  53 filename.  The <code>N_EINCL</code> value, and the values of the other and
  54 description fields for all three, appear to always be zero.
  55
  56    <p>For the start of an include file in XCOFF, use the <code>.bi</code> assembler
  57 directive, which generates a <code>C_BINCL</code> symbol.  A <code>.ei</code>
  58 directive, which generates a <code>C_EINCL</code> symbol, denotes the end of
  59 the include file.  Both directives are followed by the name of the
  60 source file in quotes, which becomes the string for the symbol.
  61 The value of each symbol, produced automatically by the assembler
  62 and linker, is the offset into the executable of the beginning
  63 (inclusive, as you'd expect) or end (inclusive, as you would not expect)
  64 of the portion of the COFF line table that corresponds to this include
  65 file.  <code>C_BINCL</code> and <code>C_EINCL</code> do not nest.
  66
  67    </body></html>
  68