source: public/doc/gnu-c/Object_002dlike-Macros.html@ 02598c2

Last change on this file since 02598c2 was 02598c2, checked in by Mikhail Kirillov <w96k@…>, on Oct 6, 2022 at 12:36:29 PM

Add gnu-c
  • Property mode set to 100644
File size: 7.8 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2<html>
3<!-- Copyright (C) 2022 Richard Stallman and Free Software Foundation, Inc.
4
5(The work of Trevis Rothwell and Nelson Beebe has been assigned or
6licensed to the FSF.)
7
8Permission is granted to copy, distribute and/or modify this document
9under the terms of the GNU Free Documentation License, Version 1.3 or
10any later version published by the Free Software Foundation; with the
11Invariant Sections being "GNU General Public License," with the
12Front-Cover Texts being "A GNU Manual," and with the Back-Cover
13Texts as in (a) below. A copy of the license is included in the
14section entitled "GNU Free Documentation License."
15
16(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
17modify this GNU manual. Buying copies from the FSF supports it in
18developing GNU and promoting software freedom." -->
19<!-- Created by GNU Texinfo 6.7, http://www.gnu.org/software/texinfo/ -->
20<head>
21<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
22<title>Object-like Macros (GNU C Language Manual)</title>
23
24<meta name="description" content="Object-like Macros (GNU C Language Manual)">
25<meta name="keywords" content="Object-like Macros (GNU C Language Manual)">
26<meta name="resource-type" content="document">
27<meta name="distribution" content="global">
28<meta name="Generator" content="makeinfo">
29<link href="index.html" rel="start" title="Top">
30<link href="Symbol-Index.html" rel="index" title="Symbol Index">
31<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
32<link href="Macros.html" rel="up" title="Macros">
33<link href="Function_002dlike-Macros.html" rel="next" title="Function-like Macros">
34<link href="Macros.html" rel="prev" title="Macros">
35<style type="text/css">
36<!--
37a.summary-letter {text-decoration: none}
38blockquote.indentedblock {margin-right: 0em}
39div.display {margin-left: 3.2em}
40div.example {margin-left: 3.2em}
41div.lisp {margin-left: 3.2em}
42kbd {font-style: oblique}
43pre.display {font-family: inherit}
44pre.format {font-family: inherit}
45pre.menu-comment {font-family: serif}
46pre.menu-preformatted {font-family: serif}
47span.nolinebreak {white-space: nowrap}
48span.roman {font-family: initial; font-weight: normal}
49span.sansserif {font-family: sans-serif; font-weight: normal}
50ul.no-bullet {list-style: none}
51-->
52</style>
53
54
55</head>
56
57<body lang="en">
58<span id="Object_002dlike-Macros"></span><div class="header">
59<p>
60Next: <a href="Function_002dlike-Macros.html" accesskey="n" rel="next">Function-like Macros</a>, Up: <a href="Macros.html" accesskey="u" rel="up">Macros</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Symbol-Index.html" title="Index" rel="index">Index</a>]</p>
61</div>
62<hr>
63<span id="Object_002dlike-Macros-1"></span><h4 class="subsection">26.5.1 Object-like Macros</h4>
64<span id="index-object_002dlike-macro"></span>
65<span id="index-symbolic-constants"></span>
66<span id="index-manifest-constants"></span>
67
68<p>An <em>object-like macro</em> is a simple identifier that will be
69replaced by a code fragment. It is called object-like because in most
70cases the use of the macro looks like reference to a data object in
71code that uses it. These macros are most commonly used to give
72symbolic names to numeric constants.
73</p>
74<span id="index-_0023define"></span>
75<p>The way to define macros with the <code>#define</code> directive.
76<code>#define</code> is followed by the name of the macro and then the token
77sequence it should be an abbreviation for, which is variously referred
78to as the macro&rsquo;s <em>body</em>, <em>expansion</em> or <em>replacement
79list</em>. For example,
80</p>
81<div class="example">
82<pre class="example">#define BUFFER_SIZE 1024
83</pre></div>
84
85<p>defines a macro named <code>BUFFER_SIZE</code> as an abbreviation for the
86token <code>1024</code>. If somewhere after this <code>#define</code> directive
87there comes a C statement of the form
88</p>
89<div class="example">
90<pre class="example">foo = (char *) malloc (BUFFER_SIZE);
91</pre></div>
92
93<p>then preprocessing will recognize and <em>expand</em> the macro
94<code>BUFFER_SIZE</code>, so that compilation will see the tokens:
95</p>
96<div class="example">
97<pre class="example">foo = (char *) malloc (1024);
98</pre></div>
99
100<p>By convention, macro names are written in upper case. Programs are
101easier to read when it is possible to tell at a glance which names are
102macros. Macro names that start with &lsquo;<samp>__</samp>&rsquo; are reserved for
103internal uses, and many of them are defined automatically, so don&rsquo;t
104define such macro names unless you really know what you&rsquo;re doing.
105Likewise for macro names that start with &lsquo;<samp>_</samp>&rsquo; and an upper-case letter.
106</p>
107<p>The macro&rsquo;s body ends at the end of the <code>#define</code> line. You may
108continue the definition onto multiple lines, if necessary, using
109backslash-newline. When the macro is expanded, however, it will all
110come out on one line. For example,
111</p>
112<div class="example">
113<pre class="example">#define NUMBERS 1, \
114 2, \
115 3
116int x[] = { NUMBERS };
117 &rarr; int x[] = { 1, 2, 3 };
118</pre></div>
119
120<p>The most common visible consequence of this is surprising line numbers
121in error messages.
122</p>
123<p>There is no restriction on what can go in a macro body provided it
124decomposes into valid preprocessing tokens. Parentheses need not
125balance, and the body need not resemble valid C code. (If it does not,
126you may get error messages from the C compiler when you use the macro.)
127</p>
128<p>Preprocessing scans the program sequentially. A macro definition
129takes effect right after its appearance. Therefore, the following
130input
131</p>
132<div class="example">
133<pre class="example">foo = X;
134#define X 4
135bar = X;
136</pre></div>
137
138<p>produces
139</p>
140<div class="example">
141<pre class="example">foo = X;
142bar = 4;
143</pre></div>
144
145<p>When preprocessing expands a macro name, the macro&rsquo;s expansion
146replaces the macro invocation, then the expansion is examined for more
147macros to expand. For example,
148</p>
149<div class="example">
150<pre class="example">#define TABLESIZE BUFSIZE
151#define BUFSIZE 1024
152TABLESIZE
153 &rarr; BUFSIZE
154 &rarr; 1024
155</pre></div>
156
157<p><code>TABLESIZE</code> is expanded first to produce <code>BUFSIZE</code>, then that
158macro is expanded to produce the final result, <code>1024</code>.
159</p>
160<p>Notice that <code>BUFSIZE</code> was not defined when <code>TABLESIZE</code> was
161defined. The <code>#define</code> for <code>TABLESIZE</code> uses exactly the
162expansion you specify&mdash;in this case, <code>BUFSIZE</code>&mdash;and does not
163check to see whether it too contains macro names. Only when you
164<em>use</em> <code>TABLESIZE</code> is the result of its expansion scanned for
165more macro names.
166</p>
167<p>This makes a difference if you change the definition of <code>BUFSIZE</code>
168at some point in the source file. <code>TABLESIZE</code>, defined as shown,
169will always expand using the definition of <code>BUFSIZE</code> that is
170currently in effect:
171</p>
172<div class="example">
173<pre class="example">#define BUFSIZE 1020
174#define TABLESIZE BUFSIZE
175#undef BUFSIZE
176#define BUFSIZE 37
177</pre></div>
178
179<p>Now <code>TABLESIZE</code> expands (in two stages) to <code>37</code>.
180</p>
181<p>If the expansion of a macro contains its own name, either directly or
182via intermediate macros, it is not expanded again when the expansion is
183examined for more macros. This prevents infinite recursion.
184See <a href="Self_002dReferential-Macros.html">Self-Referential Macros</a>, for the precise details.
185</p>
186<hr>
187<div class="header">
188<p>
189Next: <a href="Function_002dlike-Macros.html" accesskey="n" rel="next">Function-like Macros</a>, Up: <a href="Macros.html" accesskey="u" rel="up">Macros</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Symbol-Index.html" title="Index" rel="index">Index</a>]</p>
190</div>
191
192
193
194</body>
195</html>
Note: See TracBrowser for help on using the repository browser.