1<html lang="en"> 2<head> 3<title>Computed Includes - The C Preprocessor</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="The C Preprocessor"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Header-Files.html#Header-Files" title="Header Files"> 9<link rel="prev" href="Alternatives-to-Wrapper-_0023ifndef.html#Alternatives-to-Wrapper-_0023ifndef" title="Alternatives to Wrapper #ifndef"> 10<link rel="next" href="Wrapper-Headers.html#Wrapper-Headers" title="Wrapper Headers"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<!-- 13Copyright (C) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 141997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 152008, 2009, 2010, 2011 16Free Software Foundation, Inc. 17 18Permission is granted to copy, distribute and/or modify this document 19under the terms of the GNU Free Documentation License, Version 1.3 or 20any later version published by the Free Software Foundation. A copy of 21the license is included in the 22section entitled ``GNU Free Documentation License''. 23 24This manual contains no Invariant Sections. The Front-Cover Texts are 25(a) (see below), and the Back-Cover Texts are (b) (see below). 26 27(a) The FSF's Front-Cover Text is: 28 29 A GNU Manual 30 31(b) The FSF's Back-Cover Text is: 32 33 You have freedom to copy and modify this GNU Manual, like GNU 34 software. Copies published by the Free Software Foundation raise 35 funds for GNU development. 36--> 37<meta http-equiv="Content-Style-Type" content="text/css"> 38<style type="text/css"><!-- 39 pre.display { font-family:inherit } 40 pre.format { font-family:inherit } 41 pre.smalldisplay { font-family:inherit; font-size:smaller } 42 pre.smallformat { font-family:inherit; font-size:smaller } 43 pre.smallexample { font-size:smaller } 44 pre.smalllisp { font-size:smaller } 45 span.sc { font-variant:small-caps } 46 span.roman { font-family:serif; font-weight:normal; } 47 span.sansserif { font-family:sans-serif; font-weight:normal; } 48--></style> 49<link rel="stylesheet" type="text/css" href="../cs.css"> 50</head> 51<body> 52<div class="node"> 53<a name="Computed-Includes"></a> 54<p> 55Next: <a rel="next" accesskey="n" href="Wrapper-Headers.html#Wrapper-Headers">Wrapper Headers</a>, 56Previous: <a rel="previous" accesskey="p" href="Alternatives-to-Wrapper-_0023ifndef.html#Alternatives-to-Wrapper-_0023ifndef">Alternatives to Wrapper #ifndef</a>, 57Up: <a rel="up" accesskey="u" href="Header-Files.html#Header-Files">Header Files</a> 58<hr> 59</div> 60 61<h3 class="section">2.6 Computed Includes</h3> 62 63<p><a name="index-computed-includes-34"></a><a name="index-macros-in-include-35"></a> 64Sometimes it is necessary to select one of several different header 65files to be included into your program. They might specify 66configuration parameters to be used on different sorts of operating 67systems, for instance. You could do this with a series of conditionals, 68 69<pre class="smallexample"> #if SYSTEM_1 70 # include "system_1.h" 71 #elif SYSTEM_2 72 # include "system_2.h" 73 #elif SYSTEM_3 74 ... 75 #endif 76</pre> 77 <p>That rapidly becomes tedious. Instead, the preprocessor offers the 78ability to use a macro for the header name. This is called a 79<dfn>computed include</dfn>. Instead of writing a header name as the direct 80argument of ‘<samp><span class="samp">#include</span></samp>’, you simply put a macro name there instead: 81 82<pre class="smallexample"> #define SYSTEM_H "system_1.h" 83 ... 84 #include SYSTEM_H 85</pre> 86 <p class="noindent"><code>SYSTEM_H</code> will be expanded, and the preprocessor will look for 87<samp><span class="file">system_1.h</span></samp> as if the ‘<samp><span class="samp">#include</span></samp>’ had been written that way 88originally. <code>SYSTEM_H</code> could be defined by your Makefile with a 89<samp><span class="option">-D</span></samp> option. 90 91 <p>You must be careful when you define the macro. ‘<samp><span class="samp">#define</span></samp>’ saves 92tokens, not text. The preprocessor has no way of knowing that the macro 93will be used as the argument of ‘<samp><span class="samp">#include</span></samp>’, so it generates 94ordinary tokens, not a header name. This is unlikely to cause problems 95if you use double-quote includes, which are close enough to string 96constants. If you use angle brackets, however, you may have trouble. 97 98 <p>The syntax of a computed include is actually a bit more general than the 99above. If the first non-whitespace character after ‘<samp><span class="samp">#include</span></samp>’ is 100not ‘<samp><span class="samp">"</span></samp>’ or ‘<samp><span class="samp"><</span></samp>’, then the entire line is macro-expanded 101like running text would be. 102 103 <p>If the line expands to a single string constant, the contents of that 104string constant are the file to be included. CPP does not re-examine the 105string for embedded quotes, but neither does it process backslash 106escapes in the string. Therefore 107 108<pre class="smallexample"> #define HEADER "a\"b" 109 #include HEADER 110</pre> 111 <p class="noindent">looks for a file named <samp><span class="file">a\"b</span></samp>. CPP searches for the file according 112to the rules for double-quoted includes. 113 114 <p>If the line expands to a token stream beginning with a ‘<samp><span class="samp"><</span></samp>’ token 115and including a ‘<samp><span class="samp">></span></samp>’ token, then the tokens between the ‘<samp><span class="samp"><</span></samp>’ and 116the first ‘<samp><span class="samp">></span></samp>’ are combined to form the filename to be included. 117Any whitespace between tokens is reduced to a single space; then any 118space after the initial ‘<samp><span class="samp"><</span></samp>’ is retained, but a trailing space 119before the closing ‘<samp><span class="samp">></span></samp>’ is ignored. CPP searches for the file 120according to the rules for angle-bracket includes. 121 122 <p>In either case, if there are any tokens on the line after the file name, 123an error occurs and the directive is not processed. It is also an error 124if the result of expansion does not match either of the two expected 125forms. 126 127 <p>These rules are implementation-defined behavior according to the C 128standard. To minimize the risk of different compilers interpreting your 129computed includes differently, we recommend you use only a single 130object-like macro which expands to a string constant. This will also 131minimize confusion for people reading your program. 132 133 </body></html> 134 135