Include-Files.html 6.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132
  1. <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
  2. <html>
  3. <!-- Copyright (C) 1992-2019 Free Software Foundation, Inc.
  4. Contributed by Cygnus Support. Written by Julia Menapace, Jim Kingdon,
  5. and David MacKenzie.
  6. Permission is granted to copy, distribute and/or modify this document
  7. under the terms of the GNU Free Documentation License, Version 1.3 or
  8. any later version published by the Free Software Foundation; with no
  9. Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
  10. Texts. A copy of the license is included in the section entitled "GNU
  11. Free Documentation License". -->
  12. <!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
  13. <head>
  14. <title>STABS: Include Files</title>
  15. <meta name="description" content="STABS: Include Files">
  16. <meta name="keywords" content="STABS: Include Files">
  17. <meta name="resource-type" content="document">
  18. <meta name="distribution" content="global">
  19. <meta name="Generator" content="makeinfo">
  20. <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  21. <link href="index.html#Top" rel="start" title="Top">
  22. <link href="Symbol-Types-Index.html#Symbol-Types-Index" rel="index" title="Symbol Types Index">
  23. <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
  24. <link href="Program-Structure.html#Program-Structure" rel="up" title="Program Structure">
  25. <link href="Line-Numbers.html#Line-Numbers" rel="next" title="Line Numbers">
  26. <link href="Source-Files.html#Source-Files" rel="prev" title="Source Files">
  27. <style type="text/css">
  28. <!--
  29. a.summary-letter {text-decoration: none}
  30. blockquote.smallquotation {font-size: smaller}
  31. div.display {margin-left: 3.2em}
  32. div.example {margin-left: 3.2em}
  33. div.indentedblock {margin-left: 3.2em}
  34. div.lisp {margin-left: 3.2em}
  35. div.smalldisplay {margin-left: 3.2em}
  36. div.smallexample {margin-left: 3.2em}
  37. div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
  38. div.smalllisp {margin-left: 3.2em}
  39. kbd {font-style:oblique}
  40. pre.display {font-family: inherit}
  41. pre.format {font-family: inherit}
  42. pre.menu-comment {font-family: serif}
  43. pre.menu-preformatted {font-family: serif}
  44. pre.smalldisplay {font-family: inherit; font-size: smaller}
  45. pre.smallexample {font-size: smaller}
  46. pre.smallformat {font-family: inherit; font-size: smaller}
  47. pre.smalllisp {font-size: smaller}
  48. span.nocodebreak {white-space:nowrap}
  49. span.nolinebreak {white-space:nowrap}
  50. span.roman {font-family:serif; font-weight:normal}
  51. span.sansserif {font-family:sans-serif; font-weight:normal}
  52. ul.no-bullet {list-style: none}
  53. -->
  54. </style>
  55. </head>
  56. <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
  57. <a name="Include-Files"></a>
  58. <div class="header">
  59. <p>
  60. 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="prev">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>
  61. </div>
  62. <hr>
  63. <a name="Names-of-Include-Files"></a>
  64. <h3 class="section">2.3 Names of Include Files</h3>
  65. <p>There are several schemes for dealing with include files: the
  66. traditional <code>N_SOL</code> approach, Sun&rsquo;s <code>N_BINCL</code> approach, and the
  67. XCOFF <code>C_BINCL</code> approach (which despite the similar name has little in
  68. common with <code>N_BINCL</code>).
  69. </p>
  70. <a name="index-N_005fSOL"></a>
  71. <p>An <code>N_SOL</code> symbol specifies which include file subsequent symbols
  72. refer to. The string field is the name of the file and the value is the
  73. text address corresponding to the end of the previous include file and
  74. the start of this one. To specify the main source file again, use an
  75. <code>N_SOL</code> symbol with the name of the main source file.
  76. </p>
  77. <a name="index-N_005fBINCL"></a>
  78. <a name="index-N_005fEINCL"></a>
  79. <a name="index-N_005fEXCL"></a>
  80. <p>The <code>N_BINCL</code> approach works as follows. An <code>N_BINCL</code> symbol
  81. specifies the start of an include file. In an object file, only the
  82. string is significant; the linker puts data into some of the other
  83. fields. The end of the include file is marked by an <code>N_EINCL</code>
  84. symbol (which has no string field). In an object file, there is no
  85. significant data in the <code>N_EINCL</code> symbol. <code>N_BINCL</code> and
  86. <code>N_EINCL</code> can be nested.
  87. </p>
  88. <p>If the linker detects that two source files have identical stabs between
  89. an <code>N_BINCL</code> and <code>N_EINCL</code> pair (as will generally be the case
  90. for a header file), then it only puts out the stabs once. Each
  91. additional occurrence is replaced by an <code>N_EXCL</code> symbol. I believe
  92. the GNU linker and the Sun (both SunOS4 and Solaris) linker are the only
  93. ones which supports this feature.
  94. </p>
  95. <p>A linker which supports this feature will set the value of a
  96. <code>N_BINCL</code> symbol to the total of all the characters in the stabs
  97. strings included in the header file, omitting any file numbers. The
  98. value of an <code>N_EXCL</code> symbol is the same as the value of the
  99. <code>N_BINCL</code> symbol it replaces. This information can be used to
  100. match up <code>N_EXCL</code> and <code>N_BINCL</code> symbols which have the same
  101. filename. The <code>N_EINCL</code> value, and the values of the other and
  102. description fields for all three, appear to always be zero.
  103. </p>
  104. <a name="index-C_005fBINCL"></a>
  105. <a name="index-C_005fEINCL"></a>
  106. <p>For the start of an include file in XCOFF, use the <samp>.bi</samp> assembler
  107. directive, which generates a <code>C_BINCL</code> symbol. A <samp>.ei</samp>
  108. directive, which generates a <code>C_EINCL</code> symbol, denotes the end of
  109. the include file. Both directives are followed by the name of the
  110. source file in quotes, which becomes the string for the symbol.
  111. The value of each symbol, produced automatically by the assembler
  112. and linker, is the offset into the executable of the beginning
  113. (inclusive, as you&rsquo;d expect) or end (inclusive, as you would not expect)
  114. of the portion of the COFF line table that corresponds to this include
  115. file. <code>C_BINCL</code> and <code>C_EINCL</code> do not nest.
  116. </p>
  117. <hr>
  118. <div class="header">
  119. <p>
  120. 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="prev">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>
  121. </div>
  122. </body>
  123. </html>