16

For the purposes of this question, I am interested only in Standard-Compliant C++, not C or C++0x, and not any implementation-specific details.

Questions arise from time to time regarding the difference between #include "" and #include <>. The argument typically boils down to two differences:

  1. Specific implementations often search different paths for the two forms. This is platform-specific, and not in the scope of this question.
  2. The Standard says #include <> is for "headers" whereas #include "" is for a "source file." Here is the relevant reference:

ISO/IEC 14882:2003(E)

16.2 Source file inclusion [cpp.include]

1 A #include directive shall identify a header or source file that can be processed by the implementation.

2 A preprocessing directive of the form 

# include  &lt h-char-sequence &gt new-line
searches a sequence of implementation-defined places for a header identified uniquely by the specified sequence between the &lt and &gt delimiters, and causes the replacement of that directive by the entire contents of the header. How the places are specified or the header identified is implementation-defined.

3 A preprocessing directive of the form 

# include "q-char-sequence" new-line
causes the replacement of that directive by the entire contents of the source file identified by the specified sequence between the " delimiters. The named source file is searched for in an implementation-defined manner. If this search is not supported, or if the search fails, the directive is reprocessed as if it read 
# include  &lt h-char-sequence &gt new-line
with the identical contained sequence (including > characters, if any) from the original directive.

(Emphasis in quote above is mine.) The implication of this difference seems to be that the Standard intends to differentiate between a 'header' and a 'source file', but nowhere does the document define either of these terms or the difference between them.

There are few other places where headers or source files are even mentioned. A few:

158) A header is not necessarily a source file, nor are the sequences delimited by in header names necessarily valid source file names (16.2).

Seems to imply a header may not reside in the filesystem, but it doesn't say that source files do, either.

2 Lexical conventions [lex]

1 The text of the program is kept in units called source files in this International Standard. A source file together with all the headers (17.4.1.2) and source files included (16.2) via the preprocessing directive #include, less any source lines skipped by any of the conditional inclusion (16.1) preprocessing directives, is called a translation unit. [Note: a C + + program need not all be translated at the same time. ]

This is the closest I could find to a definition, and it seems to imply that headers are not the "text of the program." But if you #include a header, doesn't it become part of the text of the program? This is a bit misleading.

So what is a header? What is a source file?

Community
  • 1
  • 1
John Dibling
  • 99,718
  • 31
  • 186
  • 324

5 Answers5

8

My reading is that the standard headers, included by use of <> angle brackets, need not be actual files on the filesystem; e.g. an implementation would be free to enable a set of "built-in" operations providing the functionality of iostream when it sees #include <iostream>.

On the other hand, "source files" included with #include "xxx.h" are intended to be literal files residing on the filesystem, searched in some implementation-dependent manner.

Edit: to answer your specific question, I believe that "headers" are limited only to those #includeable facilities specified in the standard: iostream, vector and friends---or by the implementation as extensions to the standard. "Source files" would be any non-standard facilities (as .h files, etc.) the programmer may write or use.

MSN
  • 53,214
  • 7
  • 75
  • 105
Derrick Turk
  • 4,246
  • 1
  • 27
  • 27
  • Does this suggest that programmers should not `#include <>` their own source files? – John Dibling Aug 12 '10 at 16:10
  • @John: that is how I read the standard. I suppose an implementation could define its own additional #include <>able "headers", but for outside code, quotes seem to be the way to go. – Derrick Turk Aug 12 '10 at 16:11
  • 3
    @John: That would apparently be implementation-defined, as there is apparently no guarantee that `<>` will ever look for an actual file. – David Thornley Aug 12 '10 at 16:13
  • @John: As I learned the oral tradition, <> is for stuff provided by the system and the compiler, and you should use "" for your own stuff, but as far as I know that is not actually *written* anywhere. – dmckee --- ex-moderator kitten Aug 12 '10 at 16:17
  • Regarding the edit: 16.2/2 (quoted in the question) says that a header is anything included with `<>`, not just the standard headers. – Mike Seymour Aug 12 '10 at 16:25
  • 1
    @Mike: Sure...now what's a header? On most systems, it's a source file somewhere. However, the Standard explicitly says it doesn't need to be. Perhaps it is a file, but encrypted with an asymmetric key so that it can be read but not changed, and such that ordinary users couldn't create one. I think the standard allows that. – David Thornley Aug 12 '10 at 16:35
  • @David: there is no definitive answer to "what is a header?", beyond "something included with `<>`"; it is what the implementation defines it to be. All the standard specifies is the effect of including the standard headers; everything else is left up to the implementation. – Mike Seymour Aug 12 '10 at 16:48
  • @Derrick et al: It's interesting to interpret the Standard that programmers should not `#include <>` their own code. The Joint Strike Fighter standard dictates the opposite (citation follows): http://www2.research.att.com/~bs/JSF-AV-rules.pdf – John Dibling Aug 12 '10 at 17:01
  • 1
    4.7 Header Files AV Rule 33 The #include directive shall use the notation to include header files. Note that relative pathnames may also be used. See also AV Rule 53, AV Rule 53.1, and AV Rule 55 for additional information regarding header file names. Rationale: The include form “filename.h” is typically used to include local header files. However, due to the unfortunate divergence in vendor implementations, only the form will be used. – John Dibling Aug 12 '10 at 17:02
  • @John: it's wrong to interpret the Standard that way, because it says nothing of the sort. It's very clear: "How the places are specified or the header identified is implementation-defined." – Mike Seymour Aug 12 '10 at 17:05
  • @John: I suspect the JSF guidelines were written to reflect the behavior of available compilers as opposed to the behavior specified by the standard. – Derrick Turk Aug 12 '10 at 17:18
  • @Derrick: I think you're probably right, but it was interesting to me as my own policy has always been the opposite. Never use #include <> for your own code. The JSF made me rethink this, and is also what spurred this question. – John Dibling Aug 12 '10 at 19:37
  • One could legitimately have a C compiler on a machine with no I/O other than a paper tape reader, which rejected all `include` directives other than the angle-bracket-delimited standard header names, and handled the standardized names internally, and which rather than producing an executable file somewhere would simply compile to RAM and execute a program as soon as compilation was complete. There is no requirement that any mechanism exist to create named files, nor any requirement to allow `#include` to use names that can't possibly be valid. – supercat Sep 29 '15 at 17:32
4

Isn't this saying that a header may be implemented as a source file, but there again may not be? as for "what is a source file", it seems very sensible for the standard not to spell this out, given the many ways that "files" are implemented.

  • A long time ago, I worked on a Forth system that didn't have files, although there was an optional file system available. It used disk blocks instead. Assuming sufficient system size (it wasn't big), etc., would it have been possible to implement standard C++95 on it? – David Thornley Aug 12 '10 at 16:19
  • @David Yes, I remember that well - I wrote my own FORTH system in about 1981. Mine didn't even have the ability to access the CP/M file system, it only used blocks, but you could certainly implement files on top of the blocks, so I'd say "yes". –  Aug 12 '10 at 16:22
  • Absolutely sensible, and I expect that's the answer to my question. Coming from a Windows-application background, a header has always been a source file. Understanding that C++ goes well beyond just traditional apps running on a box, I was hoping to get more insight about what the differences are. – John Dibling Aug 12 '10 at 19:40
  • @DavidThornley: I don't see why not; an implementation could legitimately specify that `#include "1537@301" will be interpreted as a request to interpret 1537 bytes of data starting in block 301 as source text to be inserted at the current location. It could also legitimately specify that "fopen" will interpret "filenames" the same way. – supercat Sep 29 '15 at 17:37
2

The standard headers (string, iostream) don't necessarily have to be files with those names, or even files at all. As long as when you say

#include <iostream>

a certain list of declarations come into scope, the Standard is satisfied. Exactly how that comes about is an implementation detail. (when the Standard was being written, DOS could only handle 8.3 filenames, but some of the standard header names were longer than that)

James Curran
  • 101,701
  • 37
  • 181
  • 258
  • It seems to me that this particular case could have been handled by the "as if" rule, though. There are clearly defined effects of `#include `, as well as other possible effects, and the "as if" rule by itself would seem to cover that. – David Thornley Aug 12 '10 at 16:16
2

As your quotes say: a header is something included using <>, and a source file is the file being compiled, or something included using "". Exactly where the contents of these come from, and what non-standard headers are available, is up to the implementation. All the Standard specifies is what is defined if you include the standard headers.

By convention, headers are generally system-wide things, and source files are generally local to a project (for some definition of project), but the standard wisely doesn't get bogged down in anything to do with project organisation; it just gives very general definitions that are compatible with such conventions, leaving the details to the implementation and/or the user.

Nearly all of the standard deals with the program after it's been preprocessed, at which time there are no such things as source files or headers, just the translations units that your last quote defines.

Mike Seymour
  • 249,747
  • 28
  • 448
  • 644
0

Hmmm...

My casual understanding has been that the distinction between <> includes and "" includes was inherited from c and (though not defined by the standards) the de facto meaning was that <> searched paths for system and compiler provided headers and "" also searched local and user specified paths.

The definition above seem to agree in some sense with that usage, but restricts the use of "header" to things provided by the compiler or system exclusive of code provided by the user, even if they have the traditional "interface goes in the header" form.

Anyway, very interesting.

dmckee --- ex-moderator kitten
  • 98,632
  • 24
  • 142
  • 234
  • The standard doesn't restrict the use of "header" - it leaves it up to the implementation. If the implementor decides it can be user code, then it can be user code. – Mike Seymour Aug 12 '10 at 16:38