1<html lang="en"> 2<head> 3<title>Object-like Macros - 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="Macros.html#Macros" title="Macros"> 9<link rel="next" href="Function_002dlike-Macros.html#Function_002dlike-Macros" title="Function-like Macros"> 10<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 11<!-- 12Copyright (C) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 131997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 142008, 2009, 2010, 2011 15Free Software Foundation, Inc. 16 17Permission is granted to copy, distribute and/or modify this document 18under the terms of the GNU Free Documentation License, Version 1.3 or 19any later version published by the Free Software Foundation. A copy of 20the license is included in the 21section entitled ``GNU Free Documentation License''. 22 23This manual contains no Invariant Sections. The Front-Cover Texts are 24(a) (see below), and the Back-Cover Texts are (b) (see below). 25 26(a) The FSF's Front-Cover Text is: 27 28 A GNU Manual 29 30(b) The FSF's Back-Cover Text is: 31 32 You have freedom to copy and modify this GNU Manual, like GNU 33 software. Copies published by the Free Software Foundation raise 34 funds for GNU development. 35--> 36<meta http-equiv="Content-Style-Type" content="text/css"> 37<style type="text/css"><!-- 38 pre.display { font-family:inherit } 39 pre.format { font-family:inherit } 40 pre.smalldisplay { font-family:inherit; font-size:smaller } 41 pre.smallformat { font-family:inherit; font-size:smaller } 42 pre.smallexample { font-size:smaller } 43 pre.smalllisp { font-size:smaller } 44 span.sc { font-variant:small-caps } 45 span.roman { font-family:serif; font-weight:normal; } 46 span.sansserif { font-family:sans-serif; font-weight:normal; } 47--></style> 48<link rel="stylesheet" type="text/css" href="../cs.css"> 49</head> 50<body> 51<div class="node"> 52<a name="Object-like-Macros"></a> 53<a name="Object_002dlike-Macros"></a> 54<p> 55Next: <a rel="next" accesskey="n" href="Function_002dlike-Macros.html#Function_002dlike-Macros">Function-like Macros</a>, 56Up: <a rel="up" accesskey="u" href="Macros.html#Macros">Macros</a> 57<hr> 58</div> 59 60<h3 class="section">3.1 Object-like Macros</h3> 61 62<p><a name="index-object_002dlike-macro-41"></a><a name="index-symbolic-constants-42"></a><a name="index-manifest-constants-43"></a> 63An <dfn>object-like macro</dfn> is a simple identifier which will be replaced 64by a code fragment. It is called object-like because it looks like a 65data object in code that uses it. They are most commonly used to give 66symbolic names to numeric constants. 67 68 <p><a name="index-g_t_0023define-44"></a>You create macros with the ‘<samp><span class="samp">#define</span></samp>’ directive. ‘<samp><span class="samp">#define</span></samp>’ is 69followed by the name of the macro and then the token sequence it should 70be an abbreviation for, which is variously referred to as the macro's 71<dfn>body</dfn>, <dfn>expansion</dfn> or <dfn>replacement list</dfn>. For example, 72 73<pre class="smallexample"> #define BUFFER_SIZE 1024 74</pre> 75 <p class="noindent">defines a macro named <code>BUFFER_SIZE</code> as an abbreviation for the 76token <code>1024</code>. If somewhere after this ‘<samp><span class="samp">#define</span></samp>’ directive 77there comes a C statement of the form 78 79<pre class="smallexample"> foo = (char *) malloc (BUFFER_SIZE); 80</pre> 81 <p class="noindent">then the C preprocessor will recognize and <dfn>expand</dfn> the macro 82<code>BUFFER_SIZE</code>. The C compiler will see the same tokens as it would 83if you had written 84 85<pre class="smallexample"> foo = (char *) malloc (1024); 86</pre> 87 <p>By convention, macro names are written in uppercase. Programs are 88easier to read when it is possible to tell at a glance which names are 89macros. 90 91 <p>The macro's body ends at the end of the ‘<samp><span class="samp">#define</span></samp>’ line. You may 92continue the definition onto multiple lines, if necessary, using 93backslash-newline. When the macro is expanded, however, it will all 94come out on one line. For example, 95 96<pre class="smallexample"> #define NUMBERS 1, \ 97 2, \ 98 3 99 int x[] = { NUMBERS }; 100 ==> int x[] = { 1, 2, 3 }; 101</pre> 102 <p class="noindent">The most common visible consequence of this is surprising line numbers 103in error messages. 104 105 <p>There is no restriction on what can go in a macro body provided it 106decomposes into valid preprocessing tokens. Parentheses need not 107balance, and the body need not resemble valid C code. (If it does not, 108you may get error messages from the C compiler when you use the macro.) 109 110 <p>The C preprocessor scans your program sequentially. Macro definitions 111take effect at the place you write them. Therefore, the following input 112to the C preprocessor 113 114<pre class="smallexample"> foo = X; 115 #define X 4 116 bar = X; 117</pre> 118 <p class="noindent">produces 119 120<pre class="smallexample"> foo = X; 121 bar = 4; 122</pre> 123 <p>When the preprocessor expands a macro name, the macro's expansion 124replaces the macro invocation, then the expansion is examined for more 125macros to expand. For example, 126 127<pre class="smallexample"> #define TABLESIZE BUFSIZE 128 #define BUFSIZE 1024 129 TABLESIZE 130 ==> BUFSIZE 131 ==> 1024 132</pre> 133 <p class="noindent"><code>TABLESIZE</code> is expanded first to produce <code>BUFSIZE</code>, then that 134macro is expanded to produce the final result, <code>1024</code>. 135 136 <p>Notice that <code>BUFSIZE</code> was not defined when <code>TABLESIZE</code> was 137defined. The ‘<samp><span class="samp">#define</span></samp>’ for <code>TABLESIZE</code> uses exactly the 138expansion you specify—in this case, <code>BUFSIZE</code>—and does not 139check to see whether it too contains macro names. Only when you 140<em>use</em> <code>TABLESIZE</code> is the result of its expansion scanned for 141more macro names. 142 143 <p>This makes a difference if you change the definition of <code>BUFSIZE</code> 144at some point in the source file. <code>TABLESIZE</code>, defined as shown, 145will always expand using the definition of <code>BUFSIZE</code> that is 146currently in effect: 147 148<pre class="smallexample"> #define BUFSIZE 1020 149 #define TABLESIZE BUFSIZE 150 #undef BUFSIZE 151 #define BUFSIZE 37 152</pre> 153 <p class="noindent">Now <code>TABLESIZE</code> expands (in two stages) to <code>37</code>. 154 155 <p>If the expansion of a macro contains its own name, either directly or 156via intermediate macros, it is not expanded again when the expansion is 157examined for more macros. This prevents infinite recursion. 158See <a href="Self_002dReferential-Macros.html#Self_002dReferential-Macros">Self-Referential Macros</a>, for the precise details. 159 160 </body></html> 161 162