doc/stabs/Include-Files.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 1992-2021 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". -->
<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>STABS: Include Files</title>

<meta name="description" content="STABS: Include Files">
<meta name="keywords" content="STABS: Include Files">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Symbol-Types-Index.html#Symbol-Types-Index" rel="index" title="Symbol Types Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Program-Structure.html#Program-Structure" rel="up" title="Program Structure">
<link href="Line-Numbers.html#Line-Numbers" rel="next" title="Line Numbers">
<link href="Source-Files.html#Source-Files" rel="previous" title="Source Files">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Include-Files"></a>
<div class="header">
<p>
Next: <a href="Line-Numbers.html#Line-Numbers" accesskey="n" rel="next">Line Numbers</a>, Previous: <a href="Source-Files.html#Source-Files" accesskey="p" rel="previous">Source Files</a>, Up: <a href="Program-Structure.html#Program-Structure" accesskey="u" rel="up">Program Structure</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Symbol-Types-Index.html#Symbol-Types-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Names-of-Include-Files"></a>
<h3 class="section">2.3 Names of Include Files</h3>

<p>There are several schemes for dealing with include files: the
traditional <code>N_SOL</code> approach, Sun&rsquo;s <code>N_BINCL</code> approach, and the
XCOFF <code>C_BINCL</code> approach (which despite the similar name has little in
common with <code>N_BINCL</code>).
</p>
<a name="index-N_005fSOL"></a>
<p>An <code>N_SOL</code> symbol specifies which include file subsequent symbols
refer to.  The string field is the name of the file and the value is the
text address corresponding to the end of the previous include file and
the start of this one.  To specify the main source file again, use an
<code>N_SOL</code> symbol with the name of the main source file.
</p>
<a name="index-N_005fBINCL"></a>
<a name="index-N_005fEINCL"></a>
<a name="index-N_005fEXCL"></a>
<p>The <code>N_BINCL</code> approach works as follows.  An <code>N_BINCL</code> symbol
specifies the start of an include file.  In an object file, only the
string is significant; the linker puts data into some of the other
fields.  The end of the include file is marked by an <code>N_EINCL</code>
symbol (which has no string field).  In an object file, there is no
significant data in the <code>N_EINCL</code> symbol.  <code>N_BINCL</code> and
<code>N_EINCL</code> can be nested.
</p>
<p>If the linker detects that two source files have identical stabs between
an <code>N_BINCL</code> and <code>N_EINCL</code> pair (as will generally be the case
for a header file), then it only puts out the stabs once.  Each
additional occurrence is replaced by an <code>N_EXCL</code> symbol.  I believe
the GNU linker and the Sun (both SunOS4 and Solaris) linker are the only
ones which supports this feature.
</p>
<p>A linker which supports this feature will set the value of a
<code>N_BINCL</code> symbol to the total of all the characters in the stabs
strings included in the header file, omitting any file numbers.  The
value of an <code>N_EXCL</code> symbol is the same as the value of the
<code>N_BINCL</code> symbol it replaces.  This information can be used to
match up <code>N_EXCL</code> and <code>N_BINCL</code> symbols which have the same
filename.  The <code>N_EINCL</code> value, and the values of the other and
description fields for all three, appear to always be zero.
</p>
<a name="index-C_005fBINCL"></a>
<a name="index-C_005fEINCL"></a>
<p>For the start of an include file in XCOFF, use the <samp>.bi</samp> assembler
directive, which generates a <code>C_BINCL</code> symbol.  A <samp>.ei</samp>
directive, which generates a <code>C_EINCL</code> symbol, denotes the end of
the include file.  Both directives are followed by the name of the
source file in quotes, which becomes the string for the symbol.
The value of each symbol, produced automatically by the assembler
and linker, is the offset into the executable of the beginning
(inclusive, as you&rsquo;d expect) or end (inclusive, as you would not expect)
of the portion of the COFF line table that corresponds to this include
file.  <code>C_BINCL</code> and <code>C_EINCL</code> do not nest.
</p>
<hr>
<div class="header">
<p>
Next: <a href="Line-Numbers.html#Line-Numbers" accesskey="n" rel="next">Line Numbers</a>, Previous: <a href="Source-Files.html#Source-Files" accesskey="p" rel="previous">Source Files</a>, Up: <a href="Program-Structure.html#Program-Structure" accesskey="u" rel="up">Program Structure</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Symbol-Types-Index.html#Symbol-Types-Index" title="Index" rel="index">Index</a>]</p>
</div>


</body>
</html>