What do they mean by "then in the quote directories"?

Viewed 259

In page 8 of The C Preprocessor version 10.0.1 we have the following statement:

#include "file"

This variant is used for header files of your own program. It searches for a file named file first in the directory containing the current file, then in the quote directories and then the same directories used for <file>. You can prepend directories to the list of quote directories with the ‘-iquote’ option.

What is meant by "then in the quote directories"?

4 Answers

The documentation says:

You can prepend directories to the list of quote directories with the ‘-iquote’ option.

Thus, "quote directories" are those directories that have been passed as arguments using the ‘-iquote’ option 1. The documentation for the option says:

-iquote dir

Search dir only for header files requested with "#include " file ""; they are not searched for "#include < file >", before all directories specified by -I and before the standard system directories. If dir begins with "=", then the "=" will be replaced by the sysroot prefix; see --sysroot and -isysroot.

1 And in theory, from some other source. I don't know of any other documented source for quote dirs; no default list appears to be documented. I assume the list is empty by default.

gcc accepts several kinds of command-line parameters describing include directories:

-I - searched in case of #include <file> form and in case of #include "file" form if other methods fail

-iquote - searched only in case of #include "file" form if file is not found in the directory along with including file. It defines these "quote directories".

In my experience, "quote directories" is not a standard term. Rather, this appears to be an ad hoc description of those directories searched by the quote form of #include but not by the angle-bracket form. It might be derived from the command line options used to specify directories where headers can be found (covered on pages 63-64 in the linked document).

  • -I dir Think "Include directory"; dir is added to the list of directories searched for all #include directives.
  • -isystem dir Think "system include directory"; dir is added to (the front of) the list of directories with system headers. (These headers traditionally use the angle-bracket form of #include, but that is not a requirement.) Since the directories for system headers are searched by both forms of #include, this option is largely redundant with -I (or perhaps -I should be viewed as largely redundant with this).
  • -iquote dir Think "quote include directory"; dir is added to the (initially empty) list of directories to be searched for headers specified with the quote form of #include. (These headers traditionally are ones you write, but that is not enforced.) These directories are not searched for the angle-bracket version.

So "quote directories" are the directories where headers can live for the quote form of #include but not for the angle-bracket form. Often, this level of precision is not needed, and the -I option is sufficient. (Hence no need for a standard term for "quote directories".)

The C standard says this:

6.10.2 Source file inclusion
Constraints
A #include directive shall identify a header or source file that can be processed by the implementation.
Semantics
A preprocessing directive of the form

# include <h-char-sequence> new-line

searches a sequence of implementation-defined places for a header identified uniquely by the specified sequence between the < and > 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.
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 <h-char-sequence> new-line

with the identical contained sequence (including > characters, if any) from the original directive.

In conclusion, the quote directories are the directories that are searched in an implementation-defined manner before the directories in the standard include path are searched.

Related