Names of Include Files
======================

   There are several schemes for dealing with include files: the
traditional `N_SOL' approach, Sun's `N_BINCL' approach, and the XCOFF
`C_BINCL' approach (which despite the similar name has little in common
with `N_BINCL').

   An `N_SOL' 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
`N_SOL' symbol with the name of the main source file.

   The `N_BINCL' approach works as follows.  An `N_BINCL' symbol
specifies the start of an include file.  In an object file, only the
string is significant; the Sun linker puts data into some of the other
fields.  The end of the include file is marked by an `N_EINCL' symbol
(which has no string field).  In an object file, there is no
significant data in the `N_EINCL' symbol.  `N_BINCL' and `N_EINCL' can
be nested.

   If the linker detects that two source files have identical stabs
between an `N_BINCL' and `N_EINCL' pair (as will generally be the case
for a header file), then it only puts out the stabs once.  Each
additional occurance is replaced by an `N_EXCL' symbol.  I believe the
Sun (SunOS4, not sure about Solaris) linker is the only one which
supports this feature.

   The SunOS4 linker sets the value of a `N_BINCL' symbol to the total
of all the characters in the stabs strings included in the header file,
omitting the file number.  The value of an `N_EXCL' symbol is the same
as the value of the `N_BINCL' symbol it replaces.  I do not know if
this information is used by anything.  The `N_EINCL' value, and the
values of the other and description fields for all three, appear to
always be zero.

   For the start of an include file in XCOFF, use the `.bi' assembler
directive, which generates a `C_BINCL' symbol.  A `.ei' directive,
which generates a `C_EINCL' 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'd
expect) or end (inclusive, as you would not expect) of the portion of
the COFF line table that corresponds to this include file.  `C_BINCL'
and `C_EINCL' do not nest.