📄 cpp.html
字号:
<HTML><HEAD><!-- This HTML file has been created by texi2html 1.52 from cpp.texi on 22 March 1999 --><TITLE>The C Preprocessor</TITLE></HEAD><BODY><H1>The C Preprocessor</H1><H2>Last revised July 1992</H2><H2>for GCC version 2</H2><ADDRESS>Richard M. Stallman</ADDRESS><P><P><HR><P><H1><A NAME="SEC1" HREF="cpp_toc.html#TOC1">Transformations Made Globally</A></H1><P></P><P>Most C preprocessor features are inactive unless you give specific directivesto request their use. (Preprocessing directives are lines starting with<SAMP>`#'</SAMP>; see section <A HREF="cpp.html#SEC2">Preprocessing Directives</A>). But there are three transformations that thepreprocessor always makes on all the input it receives, even in the absenceof directives.</P><UL><LI>All C comments are replaced with single spaces.<LI>Backslash-Newline sequences are deleted, no matter where. Thisfeature allows you to break long lines for cosmetic purposes withoutchanging their meaning.<LI>Predefined macro names are replaced with their expansions(see section <A HREF="cpp.html#SEC12">Predefined Macros</A>).</UL><P>The first two transformations are done <EM>before</EM> nearly all other parsingand before preprocessing directives are recognized. Thus, for example, youcan split a line cosmetically with Backslash-Newline anywhere (exceptwhen trigraphs are in use; see below).</P><PRE>/**/ # /**/ defi\ne FO\O 10\20</PRE><P>is equivalent into <SAMP>`#define FOO 1020'</SAMP>. You can split even an escapesequence with Backslash-Newline. For example, you can split <CODE>"foo\bar"</CODE>between the <SAMP>`\'</SAMP> and the <SAMP>`b'</SAMP> to get</P><PRE>"foo\\bar"</PRE><P>This behavior is unclean: in all other contexts, a Backslash can beinserted in a string constant as an ordinary character by writing a doubleBackslash, and this creates an exception. But the ANSI C standard requiresit. (Strict ANSI C does not allow Newlines in string constants, so theydo not consider this a problem.)</P><P>But there are a few exceptions to all three transformations.</P><UL><LI>C comments and predefined macro names are not recognized inside a<SAMP>`#include'</SAMP> directive in which the file name is delimited with<SAMP>`<'</SAMP> and <SAMP>`>'</SAMP>.<LI>C comments and predefined macro names are never recognized within acharacter or string constant. (Strictly speaking, this is the rule,not an exception, but it is worth noting here anyway.)<LI>Backslash-Newline may not safely be used within an ANSI "trigraph".Trigraphs are converted before Backslash-Newline is deleted. If youwrite what looks like a trigraph with a Backslash-Newline inside, theBackslash-Newline is deleted as usual, but it is then too late torecognize the trigraph.This exception is relevant only if you use the <SAMP>`-trigraphs'</SAMP>option to enable trigraph processing. See section <A HREF="cpp.html#SEC41">Invoking the C Preprocessor</A>.</UL><H2><A NAME="SEC2" HREF="cpp_toc.html#TOC2">Preprocessing Directives</A></H2><P><A NAME="IDX1"></A><A NAME="IDX2"></A>Most preprocessor features are active only if you use preprocessing directivesto request their use.</P><P>Preprocessing directives are lines in your program that start with <SAMP>`#'</SAMP>.The <SAMP>`#'</SAMP> is followed by an identifier that is the <EM>directive name</EM>.For example, <SAMP>`#define'</SAMP> is the directive that defines a macro.Whitespace is also allowed before and after the <SAMP>`#'</SAMP>.</P><P>The set of valid directive names is fixed. Programs cannot define newpreprocessing directives.</P><P>Some directive names require arguments; these make up the rest of the directiveline and must be separated from the directive name by whitespace. For example,<SAMP>`#define'</SAMP> must be followed by a macro name and the intended expansionof the macro. See section <A HREF="cpp.html#SEC10">Simple Macros</A>.</P><P>A preprocessing directive cannot be more than one line in normal circumstances.It may be split cosmetically with Backslash-Newline, but that has no effecton its meaning. Comments containing Newlines can also divide thedirective into multiple lines, but the comments are changed to Spacesbefore the directive is interpreted. The only way a significant Newlinecan occur in a preprocessing directive is within a string constant orcharacter constant. Note thatmost C compilers that might be applied to the output from the preprocessordo not accept string or character constants containing Newlines.</P><P>The <SAMP>`#'</SAMP> and the directive name cannot come from a macro expansion. Forexample, if <SAMP>`foo'</SAMP> is defined as a macro expanding to <SAMP>`define'</SAMP>,that does not make <SAMP>`#foo'</SAMP> a valid preprocessing directive.</P><H2><A NAME="SEC3" HREF="cpp_toc.html#TOC3">Header Files</A></H2><P><A NAME="IDX3"></A>A header file is a file containing C declarations and macro definitions(see section <A HREF="cpp.html#SEC9">Macros</A>) to be shared between several source files. You requestthe use of a header file in your program with the C preprocessing directive<SAMP>`#include'</SAMP>.</P><H3><A NAME="SEC4" HREF="cpp_toc.html#TOC4">Uses of Header Files</A></H3><P>Header files serve two kinds of purposes.</P><UL><LI><A NAME="IDX4"></A>System header files declare the interfaces to parts of the operatingsystem. You include them in your program to supply the definitions anddeclarations you need to invoke system calls and libraries.<LI>Your own header files contain declarations for interfaces between thesource files of your program. Each time you have a group of relateddeclarations and macro definitions all or most of which are needed inseveral different source files, it is a good idea to create a headerfile for them.</UL><P>Including a header file produces the same results in C compilation ascopying the header file into each source file that needs it. But suchcopying would be time-consuming and error-prone. With a header file, therelated declarations appear in only one place. If they need to be changed,they can be changed in one place, and programs that include the header filewill automatically use the new version when next recompiled. The headerfile eliminates the labor of finding and changing all the copies as well asthe risk that a failure to find one copy will result in inconsistencieswithin a program.</P><P>The usual convention is to give header files names that end with<TT>`.h'</TT>. Avoid unusual characters in header file names, as theyreduce portability.</P><H3><A NAME="SEC5" HREF="cpp_toc.html#TOC5">The <SAMP>`#include'</SAMP> Directive</A></H3><P><A NAME="IDX5"></A>Both user and system header files are included using the preprocessingdirective <SAMP>`#include'</SAMP>. It has three variants:</P><DL COMPACT><DT><CODE>#include <<VAR>file</VAR>></CODE><DD>This variant is used for system header files. It searches for a filenamed <VAR>file</VAR> in a list of directories specified by you, then in astandard list of system directories. You specify directories tosearch for header files with the command option <SAMP>`-I'</SAMP>(see section <A HREF="cpp.html#SEC41">Invoking the C Preprocessor</A>). The option <SAMP>`-nostdinc'</SAMP> inhibits searchingthe standard system directories; in this case only the directoriesyou specify are searched.The parsing of this form of <SAMP>`#include'</SAMP> is slightly specialbecause comments are not recognized within the <SAMP>`<...>'</SAMP>.Thus, in <SAMP>`#include <x/*y>'</SAMP> the <SAMP>`/*'</SAMP> does not start a commentand the directive specifies inclusion of a system header file named<TT>`x/*y'</TT>. Of course, a header file with such a name is unlikely toexist on Unix, where shell wildcard features would make it hard tomanipulate.The argument <VAR>file</VAR> may not contain a <SAMP>`>'</SAMP> character. It may,however, contain a <SAMP>`<'</SAMP> character.<DT><CODE>#include "<VAR>file</VAR>"</CODE><DD>This variant is used for header files of your own program. Itsearches for a file named <VAR>file</VAR> first in the current directory,then in the same directories used for system header files. Thecurrent directory is the directory of the current input file. It istried first because it is presumed to be the location of the filesthat the current input file refers to. (If the <SAMP>`-I-'</SAMP> option isused, the special treatment of the current directory is inhibited.)The argument <VAR>file</VAR> may not contain <SAMP>`"'</SAMP> characters. Ifbackslashes occur within <VAR>file</VAR>, they are considered ordinary textcharacters, not escape characters. None of the character escapesequences appropriate to string constants in C are processed. Thus,<SAMP>`#include "x\n\\y"'</SAMP> specifies a filename containing threebackslashes. It is not clear why this behavior is ever useful, butthe ANSI standard specifies it.<DT><CODE>#include <VAR>anything else</VAR></CODE><DD><A NAME="IDX6"></A>This variant is called a <EM>computed #include</EM>. Any <SAMP>`#include'</SAMP>directive whose argument does not fit the above two forms is a computedinclude. The text <VAR>anything else</VAR> is checked for macro calls,which are expanded (see section <A HREF="cpp.html#SEC9">Macros</A>). When this is done, the resultmust fit one of the above two variants--in particular, the expandedtext must in the end be surrounded by either quotes or angle braces.This feature allows you to define a macro which controls the file nameto be used at a later point in the program. One application of this isto allow a site-specific configuration file for your program to specifythe names of the system include files to be used. This can help inporting the program to various operating systems in which the necessarysystem header files are found in different places.</DL><H3><A NAME="SEC6" HREF="cpp_toc.html#TOC6">How <SAMP>`#include'</SAMP> Works</A></H3><P>The <SAMP>`#include'</SAMP> directive works by directing the C preprocessor to scanthe specified file as input before continuing with the rest of the currentfile. The output from the preprocessor contains the output alreadygenerated, followed by the output resulting from the included file,followed by the output that comes from the text after the <SAMP>`#include'</SAMP>directive. For example, given a header file <TT>`header.h'</TT> as follows,</P><PRE>char *test ();</PRE><P>and a main program called <TT>`program.c'</TT> that uses the header file,like this,</P><PRE>int x;#include "header.h"main (){ printf (test ());}</PRE><P>the output generated by the C preprocessor for <TT>`program.c'</TT> as inputwould be</P><PRE>int x;char *test ();main (){ printf (test ());}</PRE><P>Included files are not limited to declarations and macro definitions; thoseare merely the typical uses. Any fragment of a C program can be includedfrom another file. The include file could even contain the beginning of astatement that is concluded in the containing file, or the end of astatement that was started in the including file. However, a comment or astring or character constant may not start in the included file and finishin the including file. An unterminated comment, string constant orcharacter constant in an included file is considered to end (with an errormessage) at the end of the file.</P><P>It is possible for a header file to begin or end a syntactic unit suchas a function definition, but that would be very confusing, so don't doit.</P><P>The line following the <SAMP>`#include'</SAMP> directive is always treated as aseparate line by the C preprocessor even if the included file lacks a finalnewline.</P><H3><A NAME="SEC7" HREF="cpp_toc.html#TOC7">Once-Only Include Files</A></H3><P><A NAME="IDX7"></A><A NAME="IDX8"></A></P><P>Very often, one header file includes another. It can easily result that acertain header file is included more than once. This may lead to errors,if the header file defines structure types or typedefs, and is certainlywasteful. Therefore, we often wish to prevent multiple inclusion of aheader file.</P><P>The standard way to do this is to enclose the entire real contents of thefile in a conditional, like this:</P><PRE>#ifndef FILE_FOO_SEEN#define FILE_FOO_SEEN<VAR>the entire file</VAR>#endif /* FILE_FOO_SEEN */</PRE><P>The macro <CODE>FILE_FOO_SEEN</CODE> indicates that the file has been includedonce already. In a user header file, the macro name should not beginwith <SAMP>`_'</SAMP>. In a system header file, this name should begin with<SAMP>`__'</SAMP> to avoid conflicts with user programs. In any kind of headerfile, the macro name should contain the name of the file and someadditional text, to avoid conflicts with other header files.</P><P>The GNU C preprocessor is programmed to notice when a header file usesthis particular construct and handle it efficiently. If a header fileis contained entirely in a <SAMP>`#ifndef'</SAMP> conditional, then it recordsthat fact. If a subsequent <SAMP>`#include'</SAMP> specifies the same file,and the macro in the <SAMP>`#ifndef'</SAMP> is already defined, then the fileis entirely skipped, without even reading it.</P><P><A NAME="IDX9"></A>There is also an explicit directive to tell the preprocessor that it neednot include a file more than once. This is called <SAMP>`#pragma once'</SAMP>,and was used <EM>in addition to</EM> the <SAMP>`#ifndef'</SAMP> conditional aroundthe contents of the header file. <SAMP>`#pragma once'</SAMP> is now obsoleteand should not be used at all.</P><P><A NAME="IDX10"></A>In the Objective C language, there is a variant of <SAMP>`#include'</SAMP>called <SAMP>`#import'</SAMP> which includes a file, but does so at most once.⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -