2.3 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 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 occurrence is replaced by an N_EXCL symbol. I believe the GNU linker and the Sun (both SunOS4 and Solaris) linker are the only ones which supports this feature.

A linker which supports this feature will set the value of a N_BINCL 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 N_EXCL symbol is the same as the value of the N_BINCL symbol it replaces. This information can be used to match up N_EXCL and N_BINCL symbols which have the same filename. 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.