![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to extend.texi CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Apple XNU] / GNUtools / cc|
Return to extend.texi CVS log | Up to [Apple XNU] / GNUtools / cc |
1.1 root 1: @c Copyright (C) 1988, 1989, 1992, 1993 Free Software Foundation, Inc.
2: @c This is part of the GCC manual.
3: @c For copying conditions, see the file gcc.texi.
4:
5: @node C Extensions
6: @chapter Extensions to the C Language Family
7: @cindex extensions, C language
8: @cindex C language extensions
9:
10: GNU C provides several language features not found in ANSI standard C.
11: (The @samp{-pedantic} option directs GNU CC to print a warning message if
12: any of these features is used.) To test for the availability of these
13: features in conditional compilation, check for a predefined macro
14: @code{__GNUC__}, which is always defined under GNU CC.
15:
16: These extensions are available in C and in the languages derived from
17: it, C++ and Objective C. @xref{C++ Extensions,,Extensions to the
18: C++ Language}, for extensions that apply @emph{only} to C++.
19:
20: @c The only difference between the two versions of this menu is that the
21: @c version for clear INTERNALS has an extra node, "Constraints" (which
22: @c appears in a separate chapter in the other version of the manual).
23: @ifset INTERNALS
24: @menu
25: * Statement Exprs:: Putting statements and declarations inside expressions.
26: * Local Labels:: Labels local to a statement-expression.
27: * Labels as Values:: Getting pointers to labels, and computed gotos.
28: * Nested Functions:: As in Algol and Pascal, lexical scoping of functions.
29: * Constructing Calls:: Dispatching a call to another function.
30: * Naming Types:: Giving a name to the type of some expression.
31: * Typeof:: @code{typeof}: referring to the type of an expression.
32: * Lvalues:: Using @samp{?:}, @samp{,} and casts in lvalues.
33: * Conditionals:: Omitting the middle operand of a @samp{?:} expression.
34: * Long Long:: Double-word integers---@code{long long int}.
35: * Complex:: Data types for complex numbers.
36: * Zero Length:: Zero-length arrays.
37: * Variable Length:: Arrays whose length is computed at run time.
38: * Macro Varargs:: Macros with variable number of arguments.
39: * Subscripting:: Any array can be subscripted, even if not an lvalue.
40: * Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers.
41: * Initializers:: Non-constant initializers.
42: * Constructors:: Constructor expressions give structures, unions
43: or arrays as values.
44: * Labeled Elements:: Labeling elements of initializers.
45: * Cast to Union:: Casting to union type from any member of the union.
46: * Case Ranges:: `case 1 ... 9' and such.
47: * Function Attributes:: Declaring that functions have no side effects,
48: or that they can never return.
49: * Function Prototypes:: Prototype declarations and old-style definitions.
50: * Dollar Signs:: Dollar sign is allowed in identifiers.
51: * Character Escapes:: @samp{\e} stands for the character @key{ESC}.
52: * Variable Attributes:: Specifying attributes of variables.
53: * Alignment:: Inquiring about the alignment of a type or variable.
54: * Inline:: Defining inline functions (as fast as macros).
55: * Extended Asm:: Assembler instructions with C expressions as operands.
56: (With them you can define ``built-in'' functions.)
57: * Asm Labels:: Specifying the assembler name to use for a C symbol.
58: * Explicit Reg Vars:: Defining variables residing in specified registers.
59: * Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files.
60: * Incomplete Enums:: @code{enum foo;}, with details to follow.
61: * Function Names:: Printable strings which are the name of the current
62: function.
63: @end menu
64: @end ifset
65: @ifclear INTERNALS
66: @menu
67: * Statement Exprs:: Putting statements and declarations inside expressions.
68: * Local Labels:: Labels local to a statement-expression.
69: * Labels as Values:: Getting pointers to labels, and computed gotos.
70: * Nested Functions:: As in Algol and Pascal, lexical scoping of functions.
71: * Constructing Calls:: Dispatching a call to another function.
72: * Naming Types:: Giving a name to the type of some expression.
73: * Typeof:: @code{typeof}: referring to the type of an expression.
74: * Lvalues:: Using @samp{?:}, @samp{,} and casts in lvalues.
75: * Conditionals:: Omitting the middle operand of a @samp{?:} expression.
76: * Long Long:: Double-word integers---@code{long long int}.
77: * Complex:: Data types for complex numbers.
78: * Zero Length:: Zero-length arrays.
79: * Variable Length:: Arrays whose length is computed at run time.
80: * Macro Varargs:: Macros with variable number of arguments.
81: * Subscripting:: Any array can be subscripted, even if not an lvalue.
82: * Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers.
83: * Initializers:: Non-constant initializers.
84: * Constructors:: Constructor expressions give structures, unions
85: or arrays as values.
86: * Labeled Elements:: Labeling elements of initializers.
87: * Cast to Union:: Casting to union type from any member of the union.
88: * Case Ranges:: `case 1 ... 9' and such.
89: * Function Attributes:: Declaring that functions have no side effects,
90: or that they can never return.
91: * Function Prototypes:: Prototype declarations and old-style definitions.
92: * Dollar Signs:: Dollar sign is allowed in identifiers.
93: * Character Escapes:: @samp{\e} stands for the character @key{ESC}.
94: * Variable Attributes:: Specifying attributes of variables.
95: * Alignment:: Inquiring about the alignment of a type or variable.
96: * Inline:: Defining inline functions (as fast as macros).
97: * Extended Asm:: Assembler instructions with C expressions as operands.
98: (With them you can define ``built-in'' functions.)
99: * Constraints:: Constraints for asm operands
100: * Asm Labels:: Specifying the assembler name to use for a C symbol.
101: * Explicit Reg Vars:: Defining variables residing in specified registers.
102: * Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files.
103: * Incomplete Enums:: @code{enum foo;}, with details to follow.
104: * Function Names:: Printable strings which are the name of the current
105: function.
106: @end menu
107: @end ifclear
108:
109: @node Statement Exprs
110: @section Statements and Declarations in Expressions
111: @cindex statements inside expressions
112: @cindex declarations inside expressions
113: @cindex expressions containing statements
114: @cindex macros, statements in expressions
115:
116: @c the above section title wrapped and causes an underfull hbox.. i
117: @c changed it from "within" to "in". --mew 4feb93
118:
119: A compound statement enclosed in parentheses may appear as an expression
120: in GNU C. This allows you to use loops, switches, and local variables
121: within an expression.
122:
123: Recall that a compound statement is a sequence of statements surrounded
124: by braces; in this construct, parentheses go around the braces. For
125: example:
126:
127: @example
128: (@{ int y = foo (); int z;
129: if (y > 0) z = y;
130: else z = - y;
131: z; @})
132: @end example
133:
134: @noindent
135: is a valid (though slightly more complex than necessary) expression
136: for the absolute value of @code{foo ()}.
137:
138: The last thing in the compound statement should be an expression
139: followed by a semicolon; the value of this subexpression serves as the
140: value of the entire construct. (If you use some other kind of statement
141: last within the braces, the construct has type @code{void}, and thus
142: effectively no value.)
143:
144: This feature is especially useful in making macro definitions ``safe'' (so
145: that they evaluate each operand exactly once). For example, the
146: ``maximum'' function is commonly defined as a macro in standard C as
147: follows:
148:
149: @example
150: #define max(a,b) ((a) > (b) ? (a) : (b))
151: @end example
152:
153: @noindent
154: @cindex side effects, macro argument
155: But this definition computes either @var{a} or @var{b} twice, with bad
156: results if the operand has side effects. In GNU C, if you know the
157: type of the operands (here let's assume @code{int}), you can define
158: the macro safely as follows:
159:
160: @example
161: #define maxint(a,b) \
162: (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @})
163: @end example
164:
165: Embedded statements are not allowed in constant expressions, such as
166: the value of an enumeration constant, the width of a bit field, or
167: the initial value of a static variable.
168:
169: If you don't know the type of the operand, you can still do this, but you
170: must use @code{typeof} (@pxref{Typeof}) or type naming (@pxref{Naming
171: Types}).
172:
173: @node Local Labels
174: @section Locally Declared Labels
175: @cindex local labels
176: @cindex macros, local labels
177:
178: Each statement expression is a scope in which @dfn{local labels} can be
179: declared. A local label is simply an identifier; you can jump to it
180: with an ordinary @code{goto} statement, but only from within the
181: statement expression it belongs to.
182:
183: A local label declaration looks like this:
184:
185: @example
186: __label__ @var{label};
187: @end example
188:
189: @noindent
190: or
191:
192: @example
193: __label__ @var{label1}, @var{label2}, @dots{};
194: @end example
195:
196: Local label declarations must come at the beginning of the statement
197: expression, right after the @samp{(@{}, before any ordinary
198: declarations.
199:
200: The label declaration defines the label @emph{name}, but does not define
201: the label itself. You must do this in the usual way, with
202: @code{@var{label}:}, within the statements of the statement expression.
203:
204: The local label feature is useful because statement expressions are
205: often used in macros. If the macro contains nested loops, a @code{goto}
206: can be useful for breaking out of them. However, an ordinary label
207: whose scope is the whole function cannot be used: if the macro can be
208: expanded several times in one function, the label will be multiply
209: defined in that function. A local label avoids this problem. For
210: example:
211:
212: @example
213: #define SEARCH(array, target) \
214: (@{ \
215: __label__ found; \
216: typeof (target) _SEARCH_target = (target); \
217: typeof (*(array)) *_SEARCH_array = (array); \
218: int i, j; \
219: int value; \
220: for (i = 0; i < max; i++) \
221: for (j = 0; j < max; j++) \
222: if (_SEARCH_array[i][j] == _SEARCH_target) \
223: @{ value = i; goto found; @} \
224: value = -1; \
225: found: \
226: value; \
227: @})
228: @end example
229:
230: @node Labels as Values
231: @section Labels as Values
232: @cindex labels as values
233: @cindex computed gotos
234: @cindex goto with computed label
235: @cindex address of a label
236:
237: You can get the address of a label defined in the current function
238: (or a containing function) with the unary operator @samp{&&}. The
239: value has type @code{void *}. This value is a constant and can be used
240: wherever a constant of that type is valid. For example:
241:
242: @example
243: void *ptr;
244: @dots{}
245: ptr = &&foo;
246: @end example
247:
248: To use these values, you need to be able to jump to one. This is done
249: with the computed goto statement@footnote{The analogous feature in
250: Fortran is called an assigned goto, but that name seems inappropriate in
251: C, where one can do more than simply store label addresses in label
252: variables.}, @code{goto *@var{exp};}. For example,
253:
254: @example
255: goto *ptr;
256: @end example
257:
258: @noindent
259: Any expression of type @code{void *} is allowed.
260:
261: One way of using these constants is in initializing a static array that
262: will serve as a jump table:
263:
264: @example
265: static void *array[] = @{ &&foo, &&bar, &&hack @};
266: @end example
267:
268: Then you can select a label with indexing, like this:
269:
270: @example
271: goto *array[i];
272: @end example
273:
274: @noindent
275: Note that this does not check whether the subscript is in bounds---array
276: indexing in C never does that.
277:
278: Such an array of label values serves a purpose much like that of the
279: @code{switch} statement. The @code{switch} statement is cleaner, so
280: use that rather than an array unless the problem does not fit a
281: @code{switch} statement very well.
282:
283: Another use of label values is in an interpreter for threaded code.
284: The labels within the interpreter function can be stored in the
285: threaded code for super-fast dispatching.
286:
287: You can use this mechanism to jump to code in a different function. If
288: you do that, totally unpredictable things will happen. The best way to
289: avoid this is to store the label address only in automatic variables and
290: never pass it as an argument.
291:
292: @node Nested Functions
293: @section Nested Functions
294: @cindex nested functions
295: @cindex downward funargs
296: @cindex thunks
297:
298: A @dfn{nested function} is a function defined inside another function.
299: (Nested functions are not supported for GNU C++.) The nested function's
300: name is local to the block where it is defined. For example, here we
301: define a nested function named @code{square}, and call it twice:
302:
303: @example
304: @group
305: foo (double a, double b)
306: @{
307: double square (double z) @{ return z * z; @}
308:
309: return square (a) + square (b);
310: @}
311: @end group
312: @end example
313:
314: The nested function can access all the variables of the containing
315: function that are visible at the point of its definition. This is
316: called @dfn{lexical scoping}. For example, here we show a nested
317: function which uses an inherited variable named @code{offset}:
318:
319: @example
320: bar (int *array, int offset, int size)
321: @{
322: int access (int *array, int index)
323: @{ return array[index + offset]; @}
324: int i;
325: @dots{}
326: for (i = 0; i < size; i++)
327: @dots{} access (array, i) @dots{}
328: @}
329: @end example
330:
331: Nested function definitions are permitted within functions in the places
332: where variable definitions are allowed; that is, in any block, before
333: the first statement in the block.
334:
335: It is possible to call the nested function from outside the scope of its
336: name by storing its address or passing the address to another function:
337:
338: @example
339: hack (int *array, int size)
340: @{
341: void store (int index, int value)
342: @{ array[index] = value; @}
343:
344: intermediate (store, size);
345: @}
346: @end example
347:
348: Here, the function @code{intermediate} receives the address of
349: @code{store} as an argument. If @code{intermediate} calls @code{store},
350: the arguments given to @code{store} are used to store into @code{array}.
351: But this technique works only so long as the containing function
352: (@code{hack}, in this example) does not exit.
353:
354: If you try to call the nested function through its address after the
355: containing function has exited, all hell will break loose. If you try
356: to call it after a containing scope level has exited, and if it refers
357: to some of the variables that are no longer in scope, you may be lucky,
358: but it's not wise to take the risk. If, however, the nested function
359: does not refer to anything that has gone out of scope, you should be
360: safe.
361:
362: GNU CC implements taking the address of a nested function using a
363: technique called @dfn{trampolines}. A paper describing them is
364: available from @samp{maya.idiap.ch} in directory @file{pub/tmb},
365: file @file{usenix88-lexic.ps.Z}.
366:
367: A nested function can jump to a label inherited from a containing
368: function, provided the label was explicitly declared in the containing
369: function (@pxref{Local Labels}). Such a jump returns instantly to the
370: containing function, exiting the nested function which did the
371: @code{goto} and any intermediate functions as well. Here is an example:
372:
373: @example
374: @group
375: bar (int *array, int offset, int size)
376: @{
377: __label__ failure;
378: int access (int *array, int index)
379: @{
380: if (index > size)
381: goto failure;
382: return array[index + offset];
383: @}
384: int i;
385: @dots{}
386: for (i = 0; i < size; i++)
387: @dots{} access (array, i) @dots{}
388: @dots{}
389: return 0;
390:
391: /* @r{Control comes here from @code{access}
392: if it detects an error.} */
393: failure:
394: return -1;
395: @}
396: @end group
397: @end example
398:
399: A nested function always has internal linkage. Declaring one with
400: @code{extern} is erroneous. If you need to declare the nested function
401: before its definition, use @code{auto} (which is otherwise meaningless
402: for function declarations).
403:
404: @example
405: bar (int *array, int offset, int size)
406: @{
407: __label__ failure;
408: auto int access (int *, int);
409: @dots{}
410: int access (int *array, int index)
411: @{
412: if (index > size)
413: goto failure;
414: return array[index + offset];
415: @}
416: @dots{}
417: @}
418: @end example
419:
420: @node Constructing Calls
421: @section Constructing Function Calls
422: @cindex constructing calls
423: @cindex forwarding calls
424:
425: Using the built-in functions described below, you can record
426: the arguments a function received, and call another function
427: with the same arguments, without knowing the number or types
428: of the arguments.
429:
430: You can also record the return value of that function call,
431: and later return that value, without knowing what data type
432: the function tried to return (as long as your caller expects
433: that data type).
434:
435: @table @code
436: @findex __builtin_apply_args
437: @item __builtin_apply_args ()
438: This built-in function returns a pointer of type @code{void *} to data
439: describing how to perform a call with the same arguments as were passed
440: to the current function.
441:
442: The function saves the arg pointer register, structure value address,
443: and all registers that might be used to pass arguments to a function
444: into a block of memory allocated on the stack. Then it returns the
445: address of that block.
446:
447: @findex __builtin_apply
448: @item __builtin_apply (@var{function}, @var{arguments}, @var{size})
449: This built-in function invokes @var{function} (type @code{void (*)()})
450: with a copy of the parameters described by @var{arguments} (type
451: @code{void *}) and @var{size} (type @code{int}).
452:
453: The value of @var{arguments} should be the value returned by
454: @code{__builtin_apply_args}. The argument @var{size} specifies the size
455: of the stack argument data, in bytes.
456:
457: This function returns a pointer of type @code{void *} to data describing
458: how to return whatever value was returned by @var{function}. The data
459: is saved in a block of memory allocated on the stack.
460:
461: It is not always simple to compute the proper value for @var{size}. The
462: value is used by @code{__builtin_apply} to compute the amount of data
463: that should be pushed on the stack and copied from the incoming argument
464: area.
465:
466: @findex __builtin_return
467: @item __builtin_return (@var{result})
468: This built-in function returns the value described by @var{result} from
469: the containing function. You should specify, for @var{result}, a value
470: returned by @code{__builtin_apply}.
471: @end table
472:
473: @node Naming Types
474: @section Naming an Expression's Type
475: @cindex naming types
476:
477: You can give a name to the type of an expression using a @code{typedef}
478: declaration with an initializer. Here is how to define @var{name} as a
479: type name for the type of @var{exp}:
480:
481: @example
482: typedef @var{name} = @var{exp};
483: @end example
484:
485: This is useful in conjunction with the statements-within-expressions
486: feature. Here is how the two together can be used to define a safe
487: ``maximum'' macro that operates on any arithmetic type:
488:
489: @example
490: #define max(a,b) \
491: (@{typedef _ta = (a), _tb = (b); \
492: _ta _a = (a); _tb _b = (b); \
493: _a > _b ? _a : _b; @})
494: @end example
495:
496: @cindex underscores in variables in macros
497: @cindex @samp{_} in variables in macros
498: @cindex local variables in macros
499: @cindex variables, local, in macros
500: @cindex macros, local variables in
501:
502: The reason for using names that start with underscores for the local
503: variables is to avoid conflicts with variable names that occur within the
504: expressions that are substituted for @code{a} and @code{b}. Eventually we
505: hope to design a new form of declaration syntax that allows you to declare
506: variables whose scopes start only after their initializers; this will be a
507: more reliable way to prevent such conflicts.
508:
509: @node Typeof
510: @section Referring to a Type with @code{typeof}
511: @findex typeof
512: @findex sizeof
513: @cindex macros, types of arguments
514:
515: Another way to refer to the type of an expression is with @code{typeof}.
516: The syntax of using of this keyword looks like @code{sizeof}, but the
517: construct acts semantically like a type name defined with @code{typedef}.
518:
519: There are two ways of writing the argument to @code{typeof}: with an
520: expression or with a type. Here is an example with an expression:
521:
522: @example
523: typeof (x[0](1))
524: @end example
525:
526: @noindent
527: This assumes that @code{x} is an array of functions; the type described
528: is that of the values of the functions.
529:
530: Here is an example with a typename as the argument:
531:
532: @example
533: typeof (int *)
534: @end example
535:
536: @noindent
537: Here the type described is that of pointers to @code{int}.
538:
539: If you are writing a header file that must work when included in ANSI C
540: programs, write @code{__typeof__} instead of @code{typeof}.
541: @xref{Alternate Keywords}.
542:
543: A @code{typeof}-construct can be used anywhere a typedef name could be
544: used. For example, you can use it in a declaration, in a cast, or inside
545: of @code{sizeof} or @code{typeof}.
546:
547: @itemize @bullet
548: @item
549: This declares @code{y} with the type of what @code{x} points to.
550:
551: @example
552: typeof (*x) y;
553: @end example
554:
555: @item
556: This declares @code{y} as an array of such values.
557:
558: @example
559: typeof (*x) y[4];
560: @end example
561:
562: @item
563: This declares @code{y} as an array of pointers to characters:
564:
565: @example
566: typeof (typeof (char *)[4]) y;
567: @end example
568:
569: @noindent
570: It is equivalent to the following traditional C declaration:
571:
572: @example
573: char *y[4];
574: @end example
575:
576: To see the meaning of the declaration using @code{typeof}, and why it
577: might be a useful way to write, let's rewrite it with these macros:
578:
579: @example
580: #define pointer(T) typeof(T *)
581: #define array(T, N) typeof(T [N])
582: @end example
583:
584: @noindent
585: Now the declaration can be rewritten this way:
586:
587: @example
588: array (pointer (char), 4) y;
589: @end example
590:
591: @noindent
592: Thus, @code{array (pointer (char), 4)} is the type of arrays of 4
593: pointers to @code{char}.
594: @end itemize
595:
596: @node Lvalues
597: @section Generalized Lvalues
598: @cindex compound expressions as lvalues
599: @cindex expressions, compound, as lvalues
600: @cindex conditional expressions as lvalues
601: @cindex expressions, conditional, as lvalues
602: @cindex casts as lvalues
603: @cindex generalized lvalues
604: @cindex lvalues, generalized
605: @cindex extensions, @code{?:}
606: @cindex @code{?:} extensions
607: Compound expressions, conditional expressions and casts are allowed as
608: lvalues provided their operands are lvalues. This means that you can take
609: their addresses or store values into them.
610:
611: For example, a compound expression can be assigned, provided the last
612: expression in the sequence is an lvalue. These two expressions are
613: equivalent:
614:
615: @example
616: (a, b) += 5
617: a, (b += 5)
618: @end example
619:
620: Similarly, the address of the compound expression can be taken. These two
621: expressions are equivalent:
622:
623: @example
624: &(a, b)
625: a, &b
626: @end example
627:
628: A conditional expression is a valid lvalue if its type is not void and the
629: true and false branches are both valid lvalues. For example, these two
630: expressions are equivalent:
631:
632: @example
633: (a ? b : c) = 5
634: (a ? b = 5 : (c = 5))
635: @end example
636:
637: A cast is a valid lvalue if its operand is an lvalue. A simple
638: assignment whose left-hand side is a cast works by converting the
639: right-hand side first to the specified type, then to the type of the
640: inner left-hand side expression. After this is stored, the value is
641: converted back to the specified type to become the value of the
642: assignment. Thus, if @code{a} has type @code{char *}, the following two
643: expressions are equivalent:
644:
645: @example
646: (int)a = 5
647: (int)(a = (char *)(int)5)
648: @end example
649:
650: An assignment-with-arithmetic operation such as @samp{+=} applied to a cast
651: performs the arithmetic using the type resulting from the cast, and then
652: continues as in the previous case. Therefore, these two expressions are
653: equivalent:
654:
655: @example
656: (int)a += 5
657: (int)(a = (char *)(int) ((int)a + 5))
658: @end example
659:
660: You cannot take the address of an lvalue cast, because the use of its
661: address would not work out coherently. Suppose that @code{&(int)f} were
662: permitted, where @code{f} has type @code{float}. Then the following
663: statement would try to store an integer bit-pattern where a floating
664: point number belongs:
665:
666: @example
667: *&(int)f = 1;
668: @end example
669:
670: This is quite different from what @code{(int)f = 1} would do---that
671: would convert 1 to floating point and store it. Rather than cause this
672: inconsistency, we think it is better to prohibit use of @samp{&} on a cast.
673:
674: If you really do want an @code{int *} pointer with the address of
675: @code{f}, you can simply write @code{(int *)&f}.
676:
677: @node Conditionals
678: @section Conditionals with Omitted Operands
679: @cindex conditional expressions, extensions
680: @cindex omitted middle-operands
681: @cindex middle-operands, omitted
682: @cindex extensions, @code{?:}
683: @cindex @code{?:} extensions
684:
685: The middle operand in a conditional expression may be omitted. Then
686: if the first operand is nonzero, its value is the value of the conditional
687: expression.
688:
689: Therefore, the expression
690:
691: @example
692: x ? : y
693: @end example
694:
695: @noindent
696: has the value of @code{x} if that is nonzero; otherwise, the value of
697: @code{y}.
698:
699: This example is perfectly equivalent to
700:
701: @example
702: x ? x : y
703: @end example
704:
705: @cindex side effect in ?:
706: @cindex ?: side effect
707: @noindent
708: In this simple case, the ability to omit the middle operand is not
709: especially useful. When it becomes useful is when the first operand does,
710: or may (if it is a macro argument), contain a side effect. Then repeating
711: the operand in the middle would perform the side effect twice. Omitting
712: the middle operand uses the value already computed without the undesirable
713: effects of recomputing it.
714:
715: @node Long Long
716: @section Double-Word Integers
717: @cindex @code{long long} data types
718: @cindex double-word arithmetic
719: @cindex multiprecision arithmetic
720:
721: GNU C supports data types for integers that are twice as long as
722: @code{long int}. Simply write @code{long long int} for a signed
723: integer, or @code{unsigned long long int} for an unsigned integer.
724: To make an integer constant of type @code{long long int}, add the suffix
725: @code{LL} to the integer. To make an integer constant of type
726: @code{unsigned long long int}, add the suffix @code{ULL} to the integer.
727:
728: You can use these types in arithmetic like any other integer types.
729: Addition, subtraction, and bitwise boolean operations on these types
730: are open-coded on all types of machines. Multiplication is open-coded
731: if the machine supports fullword-to-doubleword a widening multiply
732: instruction. Division and shifts are open-coded only on machines that
733: provide special support. The operations that are not open-coded use
734: special library routines that come with GNU CC.
735:
736: There may be pitfalls when you use @code{long long} types for function
737: arguments, unless you declare function prototypes. If a function
738: expects type @code{int} for its argument, and you pass a value of type
739: @code{long long int}, confusion will result because the caller and the
740: subroutine will disagree about the number of bytes for the argument.
741: Likewise, if the function expects @code{long long int} and you pass
742: @code{int}. The best way to avoid such problems is to use prototypes.
743:
744: @node Complex
745: @section Complex Numbers
746: @cindex complex numbers
747:
748: GNU C supports complex data types. You can declare both complex integer
749: types and complex floating types, using the keyword @code{__complex__}.
750:
751: For example, @samp{__complex__ double x;} declares @code{x} as a
752: variable whose real part and imaginary part are both of type
753: @code{double}. @samp{__complex__ short int y;} declares @code{y} to
754: have real and imaginary parts of type @code{short int}; this is not
755: likely to be useful, but it shows that the set of complex types is
756: complete.
757:
758: To write a constant with a complex data type, use the suffix @samp{i} or
759: @samp{j} (either one; they are equivalent). For example, @code{2.5fi}
760: has type @code{__complex__ float} and @code{3i} has type
761: @code{__complex__ int}. Such a constant always has a pure imaginary
762: value, but you can form any complex value you like by adding one to a
763: real constant.
764:
765: To extract the real part of a complex-valued expression @var{exp}, write
766: @code{__real__ @var{exp}}. Likewise, use @code{__imag__} to
767: extract the imaginary part.
768:
769: The operator @samp{~} performs complex conjugation when used on a value
770: with a complex type.
771:
772: GNU CC can allocate complex automatic variables in a noncontiguous
773: fashion; it's even possible for the real part to be in a register while
774: the imaginary part is on the stack (or vice-versa). None of the
775: supported debugging info formats has a way to represent noncontiguous
776: allocation like this, so GNU CC describes a noncontiguous complex
777: variable as if it were two separate variables of noncomplex type.
778: If the variable's actual name is @code{foo}, the two fictitious
779: variables are named @code{foo$real} and @code{foo$imag}. You can
780: examine and set these two fictitious variables with your debugger.
781:
782: A future version of GDB will know how to recognize such pairs and treat
783: them as a single variable with a complex type.
784:
785: @node Zero Length
786: @section Arrays of Length Zero
787: @cindex arrays of length zero
788: @cindex zero-length arrays
789: @cindex length-zero arrays
790:
791: Zero-length arrays are allowed in GNU C. They are very useful as the last
792: element of a structure which is really a header for a variable-length
793: object:
794:
795: @example
796: struct line @{
797: int length;
798: char contents[0];
799: @};
800:
801: @{
802: struct line *thisline = (struct line *)
803: malloc (sizeof (struct line) + this_length);
804: thisline->length = this_length;
805: @}
806: @end example
807:
808: In standard C, you would have to give @code{contents} a length of 1, which
809: means either you waste space or complicate the argument to @code{malloc}.
810:
811: @node Variable Length
812: @section Arrays of Variable Length
813: @cindex variable-length arrays
814: @cindex arrays of variable length
815:
816: Variable-length automatic arrays are allowed in GNU C. These arrays are
817: declared like any other automatic arrays, but with a length that is not
818: a constant expression. The storage is allocated at the point of
819: declaration and deallocated when the brace-level is exited. For
820: example:
821:
822: @example
823: FILE *
824: concat_fopen (char *s1, char *s2, char *mode)
825: @{
826: char str[strlen (s1) + strlen (s2) + 1];
827: strcpy (str, s1);
828: strcat (str, s2);
829: return fopen (str, mode);
830: @}
831: @end example
832:
833: @cindex scope of a variable length array
834: @cindex variable-length array scope
835: @cindex deallocating variable length arrays
836: Jumping or breaking out of the scope of the array name deallocates the
837: storage. Jumping into the scope is not allowed; you get an error
838: message for it.
839:
840: @cindex @code{alloca} vs variable-length arrays
841: You can use the function @code{alloca} to get an effect much like
842: variable-length arrays. The function @code{alloca} is available in
843: many other C implementations (but not in all). On the other hand,
844: variable-length arrays are more elegant.
845:
846: There are other differences between these two methods. Space allocated
847: with @code{alloca} exists until the containing @emph{function} returns.
848: The space for a variable-length array is deallocated as soon as the array
849: name's scope ends. (If you use both variable-length arrays and
850: @code{alloca} in the same function, deallocation of a variable-length array
851: will also deallocate anything more recently allocated with @code{alloca}.)
852:
853: You can also use variable-length arrays as arguments to functions:
854:
855: @example
856: struct entry
857: tester (int len, char data[len][len])
858: @{
859: @dots{}
860: @}
861: @end example
862:
863: The length of an array is computed once when the storage is allocated
864: and is remembered for the scope of the array in case you access it with
865: @code{sizeof}.
866:
867: If you want to pass the array first and the length afterward, you can
868: use a forward declaration in the parameter list---another GNU extension.
869:
870: @example
871: struct entry
872: tester (int len; char data[len][len], int len)
873: @{
874: @dots{}
875: @}
876: @end example
877:
878: @cindex parameter forward declaration
879: The @samp{int len} before the semicolon is a @dfn{parameter forward
880: declaration}, and it serves the purpose of making the name @code{len}
881: known when the declaration of @code{data} is parsed.
882:
883: You can write any number of such parameter forward declarations in the
884: parameter list. They can be separated by commas or semicolons, but the
885: last one must end with a semicolon, which is followed by the ``real''
886: parameter declarations. Each forward declaration must match a ``real''
887: declaration in parameter name and data type.
888:
889: @node Macro Varargs
890: @section Macros with Variable Numbers of Arguments
891: @cindex variable number of arguments
892: @cindex macro with variable arguments
893: @cindex rest argument (in macro)
894:
895: In GNU C, a macro can accept a variable number of arguments, much as a
896: function can. The syntax for defining the macro looks much like that
897: used for a function. Here is an example:
898:
899: @example
900: #define eprintf(format, args...) \
901: fprintf (stderr, format , ## args)
902: @end example
903:
904: Here @code{args} is a @dfn{rest argument}: it takes in zero or more
905: arguments, as many as the call contains. All of them plus the commas
906: between them form the value of @code{args}, which is substituted into
907: the macro body where @code{args} is used. Thus, we have this expansion:
908:
909: @example
910: eprintf ("%s:%d: ", input_file_name, line_number)
911: @expansion{}
912: fprintf (stderr, "%s:%d: " , input_file_name, line_number)
913: @end example
914:
915: @noindent
916: Note that the comma after the string constant comes from the definition
917: of @code{eprintf}, whereas the last comma comes from the value of
918: @code{args}.
919:
920: The reason for using @samp{##} is to handle the case when @code{args}
921: matches no arguments at all. In this case, @code{args} has an empty
922: value. In this case, the second comma in the definition becomes an
923: embarrassment: if it got through to the expansion of the macro, we would
924: get something like this:
925:
926: @example
927: fprintf (stderr, "success!\n" , )
928: @end example
929:
930: @noindent
931: which is invalid C syntax. @samp{##} gets rid of the comma, so we get
932: the following instead:
933:
934: @example
935: fprintf (stderr, "success!\n")
936: @end example
937:
938: This is a special feature of the GNU C preprocessor: @samp{##} before a
939: rest argument that is empty discards the preceding sequence of
940: non-whitespace characters from the macro definition. (If another macro
941: argument precedes, none of it is discarded.)
942:
943: It might be better to discard the last preprocessor token instead of the
944: last preceding sequence of non-whitespace characters; in fact, we may
945: someday change this feature to do so. We advise you to write the macro
946: definition so that the preceding sequence of non-whitespace characters
947: is just a single token, so that the meaning will not change if we change
948: the definition of this feature.
949:
950: @node Subscripting
951: @section Non-Lvalue Arrays May Have Subscripts
952: @cindex subscripting
953: @cindex arrays, non-lvalue
954:
955: @cindex subscripting and function values
956: Subscripting is allowed on arrays that are not lvalues, even though the
957: unary @samp{&} operator is not. For example, this is valid in GNU C though
958: not valid in other C dialects:
959:
960: @example
961: @group
962: struct foo @{int a[4];@};
963:
964: struct foo f();
965:
966: bar (int index)
967: @{
968: return f().a[index];
969: @}
970: @end group
971: @end example
972:
973: @node Pointer Arith
974: @section Arithmetic on @code{void}- and Function-Pointers
975: @cindex void pointers, arithmetic
976: @cindex void, size of pointer to
977: @cindex function pointers, arithmetic
978: @cindex function, size of pointer to
979:
980: In GNU C, addition and subtraction operations are supported on pointers to
981: @code{void} and on pointers to functions. This is done by treating the
982: size of a @code{void} or of a function as 1.
983:
984: A consequence of this is that @code{sizeof} is also allowed on @code{void}
985: and on function types, and returns 1.
986:
987: The option @samp{-Wpointer-arith} requests a warning if these extensions
988: are used.
989:
990: @node Initializers
991: @section Non-Constant Initializers
992: @cindex initializers, non-constant
993: @cindex non-constant initializers
994:
995: The elements of an aggregate initializer for an automatic variable are
996: not required to be constant expressions in GNU C. Here is an example of
997: an initializer with run-time varying elements:
998:
999: @example
1000: foo (float f, float g)
1001: @{
1002: float beat_freqs[2] = @{ f-g, f+g @};
1003: @dots{}
1004: @}
1005: @end example
1006:
1007: @node Constructors
1008: @section Constructor Expressions
1009: @cindex constructor expressions
1010: @cindex initializations in expressions
1011: @cindex structures, constructor expression
1012: @cindex expressions, constructor
1013:
1014: GNU C supports constructor expressions. A constructor looks like
1015: a cast containing an initializer. Its value is an object of the
1016: type specified in the cast, containing the elements specified in
1017: the initializer.
1018:
1019: Usually, the specified type is a structure. Assume that
1020: @code{struct foo} and @code{structure} are declared as shown:
1021:
1022: @example
1023: struct foo @{int a; char b[2];@} structure;
1024: @end example
1025:
1026: @noindent
1027: Here is an example of constructing a @code{struct foo} with a constructor:
1028:
1029: @example
1030: structure = ((struct foo) @{x + y, 'a', 0@});
1031: @end example
1032:
1033: @noindent
1034: This is equivalent to writing the following:
1035:
1036: @example
1037: @{
1038: struct foo temp = @{x + y, 'a', 0@};
1039: structure = temp;
1040: @}
1041: @end example
1042:
1043: You can also construct an array. If all the elements of the constructor
1044: are (made up of) simple constant expressions, suitable for use in
1045: initializers, then the constructor is an lvalue and can be coerced to a
1046: pointer to its first element, as shown here:
1047:
1048: @example
1049: char **foo = (char *[]) @{ "x", "y", "z" @};
1050: @end example
1051:
1052: Array constructors whose elements are not simple constants are
1053: not very useful, because the constructor is not an lvalue. There
1054: are only two valid ways to use it: to subscript it, or initialize
1055: an array variable with it. The former is probably slower than a
1056: @code{switch} statement, while the latter does the same thing an
1057: ordinary C initializer would do. Here is an example of
1058: subscripting an array constructor:
1059:
1060: @example
1061: output = ((int[]) @{ 2, x, 28 @}) [input];
1062: @end example
1063:
1064: Constructor expressions for scalar types and union types are is
1065: also allowed, but then the constructor expression is equivalent
1066: to a cast.
1067:
1068: @node Labeled Elements
1069: @section Labeled Elements in Initializers
1070: @cindex initializers with labeled elements
1071: @cindex labeled elements in initializers
1072: @cindex case labels in initializers
1073:
1074: Standard C requires the elements of an initializer to appear in a fixed
1075: order, the same as the order of the elements in the array or structure
1076: being initialized.
1077:
1078: In GNU C you can give the elements in any order, specifying the array
1079: indices or structure field names they apply to.
1080:
1081: To specify an array index, write @samp{[@var{index}] =} before the
1082: element value. For example,
1083:
1084: @example
1085: int a[6] = @{ [4] = 29, [2] = 15 @};
1086: @end example
1087:
1088: @noindent
1089: is equivalent to
1090:
1091: @example
1092: int a[6] = @{ 0, 0, 15, 0, 29, 0 @};
1093: @end example
1094:
1095: @noindent
1096: The index values must be constant expressions, even if the array being
1097: initialized is automatic.
1098:
1099: In a structure initializer, specify the name of a field to initialize
1100: with @samp{@var{fieldname}:} before the element value. For example,
1101: given the following structure,
1102:
1103: @example
1104: struct point @{ int x, y; @};
1105: @end example
1106:
1107: @noindent
1108: the following initialization
1109:
1110: @example
1111: struct point p = @{ y: yvalue, x: xvalue @};
1112: @end example
1113:
1114: @noindent
1115: is equivalent to
1116:
1117: @example
1118: struct point p = @{ xvalue, yvalue @};
1119: @end example
1120:
1121: Another syntax which has the same meaning is @samp{.@var{fieldname} =}.,
1122: as shown here:
1123:
1124: @example
1125: struct point p = @{ .y = yvalue, .x = xvalue @};
1126: @end example
1127:
1128: You can also use an element label (with either the colon syntax or the
1129: period-equal syntax) when initializing a union, to specify which element
1130: of the union should be used. For example,
1131:
1132: @example
1133: union foo @{ int i; double d; @};
1134:
1135: union foo f = @{ d: 4 @};
1136: @end example
1137:
1138: @noindent
1139: will convert 4 to a @code{double} to store it in the union using
1140: the second element. By contrast, casting 4 to type @code{union foo}
1141: would store it into the union as the integer @code{i}, since it is
1142: an integer. (@xref{Cast to Union}.)
1143:
1144: You can combine this technique of naming elements with ordinary C
1145: initialization of successive elements. Each initializer element that
1146: does not have a label applies to the next consecutive element of the
1147: array or structure. For example,
1148:
1149: @example
1150: int a[6] = @{ [1] = v1, v2, [4] = v4 @};
1151: @end example
1152:
1153: @noindent
1154: is equivalent to
1155:
1156: @example
1157: int a[6] = @{ 0, v1, v2, 0, v4, 0 @};
1158: @end example
1159:
1160: Labeling the elements of an array initializer is especially useful
1161: when the indices are characters or belong to an @code{enum} type.
1162: For example:
1163:
1164: @example
1165: int whitespace[256]
1166: = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1,
1167: ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @};
1168: @end example
1169:
1170: @node Case Ranges
1171: @section Case Ranges
1172: @cindex case ranges
1173: @cindex ranges in case statements
1174:
1175: You can specify a range of consecutive values in a single @code{case} label,
1176: like this:
1177:
1178: @example
1179: case @var{low} ... @var{high}:
1180: @end example
1181:
1182: @noindent
1183: This has the same effect as the proper number of individual @code{case}
1184: labels, one for each integer value from @var{low} to @var{high}, inclusive.
1185:
1186: This feature is especially useful for ranges of ASCII character codes:
1187:
1188: @example
1189: case 'A' ... 'Z':
1190: @end example
1191:
1192: @strong{Be careful:} Write spaces around the @code{...}, for otherwise
1193: it may be parsed wrong when you use it with integer values. For example,
1194: write this:
1195:
1196: @example
1197: case 1 ... 5:
1198: @end example
1199:
1200: @noindent
1201: rather than this:
1202:
1203: @example
1204: case 1...5:
1205: @end example
1206:
1207: @quotation
1208: @emph{Warning to C++ users:} When compiling C++, you must write two dots
1209: @samp{..} rather than three to specify a range in case statements, thus:
1210:
1211: @example
1212: case 'A' .. 'Z':
1213: @end example
1214:
1215: @noindent
1216: This is an anachronism in the GNU C++ front end, and will be rectified
1217: in a future release.
1218: @end quotation
1219:
1220: @node Cast to Union
1221: @section Cast to a Union Type
1222: @cindex cast to a union
1223: @cindex union, casting to a
1224:
1225: A cast to union type is similar to other casts, except that the type
1226: specified is a union type. You can specify the type either with
1227: @code{union @var{tag}} or with a typedef name. A cast to union is actually
1228: a constructor though, not a cast, and hence does not yield an lvalue like
1229: normal casts. (@xref{Constructors}.)
1230:
1231: The types that may be cast to the union type are those of the members
1232: of the union. Thus, given the following union and variables:
1233:
1234: @example
1235: union foo @{ int i; double d; @};
1236: int x;
1237: double y;
1238: @end example
1239:
1240: @noindent
1241: both @code{x} and @code{y} can be cast to type @code{union} foo.
1242:
1243: Using the cast as the right-hand side of an assignment to a variable of
1244: union type is equivalent to storing in a member of the union:
1245:
1246: @example
1247: union foo u;
1248: @dots{}
1249: u = (union foo) x @equiv{} u.i = x
1250: u = (union foo) y @equiv{} u.d = y
1251: @end example
1252:
1253: You can also use the union cast as a function argument:
1254:
1255: @example
1256: void hack (union foo);
1257: @dots{}
1258: hack ((union foo) x);
1259: @end example
1260:
1261: @node Function Attributes
1262: @section Declaring Attributes of Functions
1263: @cindex function attributes
1264: @cindex declaring attributes of functions
1265: @cindex functions that never return
1266: @cindex functions that have no side effects
1267: @cindex @code{volatile} applied to function
1268: @cindex @code{const} applied to function
1269: @cindex functions with @code{printf} or @code{scanf} style arguments
1270:
1271: In GNU C, you declare certain things about functions called in your program
1272: which help the compiler optimize function calls and check your code more
1273: carefully.
1274:
1275: The keyword @code{__attribute__} allows you to specify special
1276: attributes when making a declaration. This keyword is followed by an
1277: attribute specification inside double parentheses. Three attributes,
1278: @code{noreturn}, @code{const} and @code{format}, are currently defined
1279: for functions. Others are implemented for variables and structure fields
1280: (@pxref{Variable Attributes}).
1281:
1282: @table @code
1283: @cindex @code{noreturn} function attribute
1284: @item noreturn
1285: A few standard library functions, such as @code{abort} and @code{exit},
1286: cannot return. GNU CC knows this automatically. Some programs define
1287: their own functions that never return. You can declare them
1288: @code{noreturn} to tell the compiler this fact. For example,
1289:
1290: @smallexample
1291: void fatal () __attribute__ ((noreturn));
1292:
1293: void
1294: fatal (@dots{})
1295: @{
1296: @dots{} /* @r{Print error message.} */ @dots{}
1297: exit (1);
1298: @}
1299: @end smallexample
1300:
1301: The @code{noreturn} keyword tells the compiler to assume that
1302: @code{fatal} cannot return. It can then optimize without regard to what
1303: would happen if @code{fatal} ever did return. This makes slightly
1304: better code. More importantly, it helps avoid spurious warnings of
1305: uninitialized variables.
1306:
1307: Do not assume that registers saved by the calling function are
1308: restored before calling the @code{noreturn} function.
1309:
1310: It does not make sense for a @code{noreturn} function to have a return
1311: type other than @code{void}.
1312:
1313: The attribute @code{noreturn} is not implemented in GNU C versions
1314: earlier than 2.5. An alternative way to declare that a function does
1315: not return, which works in the current version and in some older
1316: versions, is as follows:
1317:
1318: @smallexample
1319: typedef void voidfn ();
1320:
1321: volatile voidfn fatal;
1322: @end smallexample
1323:
1324: @cindex @code{const} function attribute
1325: @item const
1326: Many functions do not examine any values except their arguments, and
1327: have no effects except the return value. Such a function can be subject
1328: to common subexpression elimination and loop optimization just as an
1329: arithmetic operator would be. These functions should be declared
1330: with the attribute @code{const}. For example,
1331:
1332: @smallexample
1333: int square (int) __attribute__ ((const));
1334: @end smallexample
1335:
1336: @noindent
1337: says that the hypothetical function @code{square} is safe to call
1338: fewer times than the program says.
1339:
1340: The attribute @code{const} is not implemented in GNU C versions earlier
1341: than 2.5. An alternative way to declare that a function has no side
1342: effects, which works in the current version and in some older versions,
1343: is as follows:
1344:
1345: @smallexample
1346: typedef int intfn ();
1347:
1348: extern const intfn square;
1349: @end smallexample
1350:
1351: @cindex pointer arguments
1352: Note that a function that has pointer arguments and examines the data
1353: pointed to must @emph{not} be declared @code{const}. Likewise, a
1354: function that calls a non-@code{const} function usually must not be
1355: @code{const}. It does not make sense for a @code{const} function to
1356: return @code{void}.
1357:
1358: @item format (@var{archetype}, @var{string-index}, @var{first-to-check})
1359: @cindex @code{format} function attribute
1360: The @code{format} attribute specifies that a function takes @code{printf}
1361: or @code{scanf} style arguments which should be type-checked against a
1362: format string. For example, the declaration:
1363:
1364: @smallexample
1365: extern int
1366: my_printf (void *my_object, const char *my_format, ...)
1367: __attribute__ ((format (printf, 2, 3)));
1368: @end smallexample
1369:
1370: @noindent
1371: causes the compiler to check the arguments in calls to @code{my_printf}
1372: for consistency with the @code{printf} style format string argument
1373: @code{my_format}.
1374:
1375: The parameter @var{archetype} determines how the format string is
1376: interpreted, and should be either @code{printf} or @code{scanf}. The
1377: parameter @var{string-index} specifies which argument is the format
1378: string argument (starting from 1), while @var{first-to-check} is the
1379: number of the first argument to check against the format string. For
1380: functions where the arguments are not available to be checked (such as
1381: @code{vprintf}), specify the third parameter as zero. In this case the
1382: compiler only checks the format string for consistency.
1383:
1384: In the example above, the format string (@code{my_format}) is the second
1385: argument of the function @code{my_print}, and the arguments to check
1386: start with the third argument, so the correct parameters for the format
1387: attribute are 2 and 3.
1388:
1389: The @code{format} attribute allows you to identify your own functions
1390: which take format strings as arguments, so that GNU CC can check the
1391: calls to these functions for errors. The compiler always checks formats
1392: for the ANSI library functions @code{printf}, @code{fprintf},
1393: @code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf},
1394: @code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such
1395: warnings are requested (using @samp{-Wformat}), so there is no need to
1396: modify the header file @file{stdio.h}.
1397: @end table
1398:
1399: You can specify multiple attributes in a declaration by separating them
1400: by commas within the double parentheses. Currently it is never useful
1401: to do this for a function, but it can be useful for a variable.
1402:
1403: @cindex @code{#pragma}, reason for not using
1404: @cindex pragma, reason for not using
1405: Some people object to the @code{__attribute__} feature, suggesting that ANSI C's
1406: @code{#pragma} should be used instead. There are two reasons for not
1407: doing this.
1408:
1409: @enumerate
1410: @item
1411: It is impossible to generate @code{#pragma} commands from a macro.
1412:
1413: @item
1414: There is no telling what the same @code{#pragma} might mean in another
1415: compiler.
1416: @end enumerate
1417:
1418: These two reasons apply to almost any application that might be proposed
1419: for @code{#pragma}. It is basically a mistake to use @code{#pragma} for
1420: @emph{anything}.
1421:
1422: @node Function Prototypes
1423: @section Prototypes and Old-Style Function Definitions
1424: @cindex function prototype declarations
1425: @cindex old-style function definitions
1426: @cindex promotion of formal parameters
1427:
1428: GNU C extends ANSI C to allow a function prototype to override a later
1429: old-style non-prototype definition. Consider the following example:
1430:
1431: @example
1432: /* @r{Use prototypes unless the compiler is old-fashioned.} */
1433: #if __STDC__
1434: #define P(x) x
1435: #else
1436: #define P(x) ()
1437: #endif
1438:
1439: /* @r{Prototype function declaration.} */
1440: int isroot P((uid_t));
1441:
1442: /* @r{Old-style function definition.} */
1443: int
1444: isroot (x) /* ??? lossage here ??? */
1445: uid_t x;
1446: @{
1447: return x == 0;
1448: @}
1449: @end example
1450:
1451: Suppose the type @code{uid_t} happens to be @code{short}. ANSI C does
1452: not allow this example, because subword arguments in old-style
1453: non-prototype definitions are promoted. Therefore in this example the
1454: function definition's argument is really an @code{int}, which does not
1455: match the prototype argument type of @code{short}.
1456:
1457: This restriction of ANSI C makes it hard to write code that is portable
1458: to traditional C compilers, because the programmer does not know
1459: whether the @code{uid_t} type is @code{short}, @code{int}, or
1460: @code{long}. Therefore, in cases like these GNU C allows a prototype
1461: to override a later old-style definition. More precisely, in GNU C, a
1462: function prototype argument type overrides the argument type specified
1463: by a later old-style definition if the former type is the same as the
1464: latter type before promotion. Thus in GNU C the above example is
1465: equivalent to the following:
1466:
1467: @example
1468: int isroot (uid_t);
1469:
1470: int
1471: isroot (uid_t x)
1472: @{
1473: return x == 0;
1474: @}
1475: @end example
1476:
1477: @node Dollar Signs
1478: @section Dollar Signs in Identifier Names
1479: @cindex $
1480: @cindex dollar signs in identifier names
1481: @cindex identifier names, dollar signs in
1482:
1483: In GNU C, you may use dollar signs in identifier names. This is because
1484: many traditional C implementations allow such identifiers.
1485:
1486: On some machines, dollar signs are allowed in identifiers if you specify
1487: @w{@samp{-traditional}}. On a few systems they are allowed by default,
1488: even if you do not use @w{@samp{-traditional}}. But they are never
1489: allowed if you specify @w{@samp{-ansi}}.
1490:
1491: There are certain ANSI C programs (obscure, to be sure) that would
1492: compile incorrectly if dollar signs were permitted in identifiers. For
1493: example:
1494:
1495: @example
1496: #define foo(a) #a
1497: #define lose(b) foo (b)
1498: #define test$
1499: lose (test)
1500: @end example
1501:
1502: @node Character Escapes
1503: @section The Character @key{ESC} in Constants
1504:
1505: You can use the sequence @samp{\e} in a string or character constant to
1506: stand for the ASCII character @key{ESC}.
1507:
1508: @node Alignment
1509: @section Inquiring on Alignment of Types or Variables
1510: @cindex alignment
1511: @cindex type alignment
1512: @cindex variable alignment
1513:
1514: The keyword @code{__alignof__} allows you to inquire about how an object
1515: is aligned, or the minimum alignment usually required by a type. Its
1516: syntax is just like @code{sizeof}.
1517:
1518: For example, if the target machine requires a @code{double} value to be
1519: aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8.
1520: This is true on many RISC machines. On more traditional machine
1521: designs, @code{__alignof__ (double)} is 4 or even 2.
1522:
1523: Some machines never actually require alignment; they allow reference to any
1524: data type even at an odd addresses. For these machines, @code{__alignof__}
1525: reports the @emph{recommended} alignment of a type.
1526:
1527: When the operand of @code{__alignof__} is an lvalue rather than a type, the
1528: value is the largest alignment that the lvalue is known to have. It may
1529: have this alignment as a result of its data type, or because it is part of
1530: a structure and inherits alignment from that structure. For example, after
1531: this declaration:
1532:
1533: @example
1534: struct foo @{ int x; char y; @} foo1;
1535: @end example
1536:
1537: @noindent
1538: the value of @code{__alignof__ (foo1.y)} is probably 2 or 4, the same as
1539: @code{__alignof__ (int)}, even though the data type of @code{foo1.y}
1540: does not itself demand any alignment.@refill
1541:
1542: A related feature which lets you specify the alignment of an object is
1543: @code{__attribute__ ((aligned (@var{alignment})))}; see the following
1544: section.
1545:
1546: @node Variable Attributes
1547: @section Specifying Attributes of Variables
1548: @cindex attribute of variables
1549: @cindex variable attributes
1550:
1551: The keyword @code{__attribute__} allows you to specify special
1552: attributes of variables or structure fields. This keyword is followed
1553: by an attribute specification inside double parentheses. Four
1554: attributes are currently defined: @code{aligned}, @code{format},
1555: @code{mode} and @code{packed}. @code{format} is used for functions,
1556: and thus not documented here; see @ref{Function Attributes}.
1557:
1558: @table @code
1559: @cindex @code{aligned} attribute
1560: @item aligned (@var{alignment})
1561: This attribute specifies a minimum alignment for the variable or
1562: structure field, measured in bytes. For example, the declaration:
1563:
1564: @smallexample
1565: int x __attribute__ ((aligned (16))) = 0;
1566: @end smallexample
1567:
1568: @noindent
1569: causes the compiler to allocate the global variable @code{x} on a
1570: 16-byte boundary. On a 68040, this could be used in conjunction with
1571: an @code{asm} expression to access the @code{move16} instruction which
1572: requires 16-byte aligned operands.
1573:
1574: You can also specify the alignment of structure fields. For example, to
1575: create a double-word aligned @code{int} pair, you could write:
1576:
1577: @smallexample
1578: struct foo @{ int x[2] __attribute__ ((aligned (8))); @};
1579: @end smallexample
1580:
1581: @noindent
1582: This is an alternative to creating a union with a @code{double} member
1583: that forces the union to be double-word aligned.
1584:
1585: It is not possible to specify the alignment of functions; the alignment
1586: of functions is determined by the machine's requirements and cannot be
1587: changed. You cannot specify alignment for a typedef name because such a
1588: name is just an alias, not a distinct type.
1589:
1590: The @code{aligned} attribute can only increase the alignment; but you
1591: can decrease it by specifying @code{packed} as well. See below.
1592:
1593: The linker of your operating system imposes a maximum alignment. If the
1594: linker aligns each object file on a four byte boundary, then it is
1595: beyond the compiler's power to cause anything to be aligned to a larger
1596: boundary than that. For example, if the linker happens to put this object
1597: file at address 136 (eight more than a multiple of 64), then the compiler
1598: cannot guarantee an alignment of more than 8 just by aligning variables in
1599: the object file.
1600:
1601: @item mode (@var{mode})
1602: @cindex @code{mode} attribute
1603: This attribute specifies the data type for the declaration---whichever
1604: type corresponds to the mode @var{mode}. This in effect lets you
1605: request an integer or floating point type according to its width.
1606:
1607: @item packed
1608: @cindex @code{packed} attribute
1609: The @code{packed} attribute specifies that a variable or structure field
1610: should have the smallest possible alignment---one byte for a variable,
1611: and one bit for a field, unless you specify a larger value with the
1612: @code{aligned} attribute.
1613: @end table
1614:
1615: To specify multiple attributes, separate them by commas within the
1616: double parentheses: for example, @samp{__attribute__ ((aligned (16),
1617: packed))}.
1618:
1619: @node Inline
1620: @section An Inline Function is As Fast As a Macro
1621: @cindex inline functions
1622: @cindex integrating function code
1623: @cindex open coding
1624: @cindex macros, inline alternative
1625:
1626: By declaring a function @code{inline}, you can direct GNU CC to
1627: integrate that function's code into the code for its callers. This
1628: makes execution faster by eliminating the function-call overhead; in
1629: addition, if any of the actual argument values are constant, their known
1630: values may permit simplifications at compile time so that not all of the
1631: inline function's code needs to be included. The effect on code size is
1632: less predictable; object code may be larger or smaller with function
1633: inlining, depending on the particular case. Inlining of functions is an
1634: optimization and it really ``works'' only in optimizing compilation. If
1635: you don't use @samp{-O}, no function is really inline.
1636:
1637: To declare a function inline, use the @code{inline} keyword in its
1638: declaration, like this:
1639:
1640: @example
1641: inline int
1642: inc (int *a)
1643: @{
1644: (*a)++;
1645: @}
1646: @end example
1647:
1648: (If you are writing a header file to be included in ANSI C programs, write
1649: @code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.)
1650:
1651: You can also make all ``simple enough'' functions inline with the option
1652: @samp{-finline-functions}. Note that certain usages in a function
1653: definition can make it unsuitable for inline substitution.
1654:
1655: @cindex automatic @code{inline} for C++ member fns
1656: @cindex @code{inline} automatic for C++ member fns
1657: @cindex member fns, automatically @code{inline}
1658: @cindex C++ member fns, automatically @code{inline}
1659: For C++ programs, GNU CC automatically inlines member functions even if
1660: they are not explicitly declared @code{inline}.
1661: (You can override this with @w{@samp{-fno-default-inline}};
1662: @pxref{C++ Dialect Options,,Options Controlling C++ Dialect}.)
1663:
1664: @cindex inline functions, omission of
1665: When a function is both inline and @code{static}, if all calls to the
1666: function are integrated into the caller, and the function's address is
1667: never used, then the function's own assembler code is never referenced.
1668: In this case, GNU CC does not actually output assembler code for the
1669: function, unless you specify the option @samp{-fkeep-inline-functions}.
1670: Some calls cannot be integrated for various reasons (in particular,
1671: calls that precede the function's definition cannot be integrated, and
1672: neither can recursive calls within the definition). If there is a
1673: nonintegrated call, then the function is compiled to assembler code as
1674: usual. The function must also be compiled as usual if the program
1675: refers to its address, because that can't be inlined.
1676:
1677: @cindex non-static inline function
1678: When an inline function is not @code{static}, then the compiler must assume
1679: that there may be calls from other source files; since a global symbol can
1680: be defined only once in any program, the function must not be defined in
1681: the other source files, so the calls therein cannot be integrated.
1682: Therefore, a non-@code{static} inline function is always compiled on its
1683: own in the usual fashion.
1684:
1685: If you specify both @code{inline} and @code{extern} in the function
1686: definition, then the definition is used only for inlining. In no case
1687: is the function compiled on its own, not even if you refer to its
1688: address explicitly. Such an address becomes an external reference, as
1689: if you had only declared the function, and had not defined it.
1690:
1691: This combination of @code{inline} and @code{extern} has almost the
1692: effect of a macro. The way to use it is to put a function definition in
1693: a header file with these keywords, and put another copy of the
1694: definition (lacking @code{inline} and @code{extern}) in a library file.
1695: The definition in the header file will cause most calls to the function
1696: to be inlined. If any uses of the function remain, they will refer to
1697: the single copy in the library.
1698:
1699: GNU C does not inline any functions when not optimizing. It is not
1700: clear whether it is better to inline or not, in this case, but we found
1701: that a correct implementation when not optimizing was difficult. So we
1702: did the easy thing, and turned it off.
1703:
1704: @node Extended Asm
1705: @section Assembler Instructions with C Expression Operands
1706: @cindex extended @code{asm}
1707: @cindex @code{asm} expressions
1708: @cindex assembler instructions
1709: @cindex registers
1710:
1711: In an assembler instruction using @code{asm}, you can now specify the
1712: operands of the instruction using C expressions. This means no more
1713: guessing which registers or memory locations will contain the data you want
1714: to use.
1715:
1716: You must specify an assembler instruction template much like what appears
1717: in a machine description, plus an operand constraint string for each
1718: operand.
1719:
1720: For example, here is how to use the 68881's @code{fsinx} instruction:
1721:
1722: @example
1723: asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
1724: @end example
1725:
1726: @noindent
1727: Here @code{angle} is the C expression for the input operand while
1728: @code{result} is that of the output operand. Each has @samp{"f"} as its
1729: operand constraint, saying that a floating point register is required. The
1730: @samp{=} in @samp{=f} indicates that the operand is an output; all output
1731: operands' constraints must use @samp{=}. The constraints use the same
1732: language used in the machine description (@pxref{Constraints}).
1733:
1734: Each operand is described by an operand-constraint string followed by the C
1735: expression in parentheses. A colon separates the assembler template from
1736: the first output operand, and another separates the last output operand
1737: from the first input, if any. Commas separate output operands and separate
1738: inputs. The total number of operands is limited to ten or to the maximum
1739: number of operands in any instruction pattern in the machine description,
1740: whichever is greater.
1741:
1742: If there are no output operands, and there are input operands, then there
1743: must be two consecutive colons surrounding the place where the output
1744: operands would go.
1745:
1746: Output operand expressions must be lvalues; the compiler can check this.
1747: The input operands need not be lvalues. The compiler cannot check whether
1748: the operands have data types that are reasonable for the instruction being
1749: executed. It does not parse the assembler instruction template and does
1750: not know what it means, or whether it is valid assembler input. The
1751: extended @code{asm} feature is most often used for machine instructions
1752: that the compiler itself does not know exist.
1753:
1754: The output operands must be write-only; GNU CC will assume that the values
1755: in these operands before the instruction are dead and need not be
1756: generated. Extended asm does not support input-output or read-write
1757: operands. For this reason, the constraint character @samp{+}, which
1758: indicates such an operand, may not be used.
1759:
1760: When the assembler instruction has a read-write operand, or an operand
1761: in which only some of the bits are to be changed, you must logically
1762: split its function into two separate operands, one input operand and one
1763: write-only output operand. The connection between them is expressed by
1764: constraints which say they need to be in the same location when the
1765: instruction executes. You can use the same C expression for both
1766: operands, or different expressions. For example, here we write the
1767: (fictitious) @samp{combine} instruction with @code{bar} as its read-only
1768: source operand and @code{foo} as its read-write destination:
1769:
1770: @example
1771: asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
1772: @end example
1773:
1774: @noindent
1775: The constraint @samp{"0"} for operand 1 says that it must occupy the same
1776: location as operand 0. A digit in constraint is allowed only in an input
1777: operand, and it must refer to an output operand.
1778:
1779: Only a digit in the constraint can guarantee that one operand will be in
1780: the same place as another. The mere fact that @code{foo} is the value of
1781: both operands is not enough to guarantee that they will be in the same
1782: place in the generated assembler code. The following would not work:
1783:
1784: @example
1785: asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));
1786: @end example
1787:
1788: Various optimizations or reloading could cause operands 0 and 1 to be in
1789: different registers; GNU CC knows no reason not to do so. For example, the
1790: compiler might find a copy of the value of @code{foo} in one register and
1791: use it for operand 1, but generate the output operand 0 in a different
1792: register (copying it afterward to @code{foo}'s own address). Of course,
1793: since the register for operand 1 is not even mentioned in the assembler
1794: code, the result will not work, but GNU CC can't tell that.
1795:
1796: Some instructions clobber specific hard registers. To describe this, write
1797: a third colon after the input operands, followed by the names of the
1798: clobbered hard registers (given as strings). Here is a realistic example
1799: for the Vax:
1800:
1801: @example
1802: asm volatile ("movc3 %0,%1,%2"
1803: : /* no outputs */
1804: : "g" (from), "g" (to), "g" (count)
1805: : "r0", "r1", "r2", "r3", "r4", "r5");
1806: @end example
1807:
1808: If you refer to a particular hardware register from the assembler code,
1809: then you will probably have to list the register after the third colon
1810: to tell the compiler that the register's value is modified. In many
1811: assemblers, the register names begin with @samp{%}; to produce one
1812: @samp{%} in the assembler code, you must write @samp{%%} in the input.
1813:
1814: If your assembler instruction can alter the condition code register,
1815: add @samp{cc} to the list of clobbered registers. GNU CC on some
1816: machines represents the condition codes as a specific hardware
1817: register; @samp{cc} serves to name this register. On other machines,
1818: the condition code is handled differently, and specifying @samp{cc}
1819: has no effect. But it is valid no matter what the machine.
1820:
1821: If your assembler instruction modifies memory in an unpredictable
1822: fashion, add @samp{memory} to the list of clobbered registers.
1823: This will cause GNU CC to not keep memory values cached in
1824: registers across the assembler instruction.
1825:
1826: You can put multiple assembler instructions together in a single @code{asm}
1827: template, separated either with newlines (written as @samp{\n}) or with
1828: semicolons if the assembler allows such semicolons. The GNU assembler
1829: allows semicolons and all Unix assemblers seem to do so. The input
1830: operands are guaranteed not to use any of the clobbered registers, and
1831: neither will the output operands' addresses, so you can read and write the
1832: clobbered registers as many times as you like. Here is an example of
1833: multiple instructions in a template; it assumes that the subroutine
1834: @code{_foo} accepts arguments in registers 9 and 10:
1835:
1836: @example
1837: asm ("movl %0,r9;movl %1,r10;call _foo"
1838: : /* no outputs */
1839: : "g" (from), "g" (to)
1840: : "r9", "r10");
1841: @end example
1842:
1843: Unless an output operand has the @samp{&} constraint modifier, GNU CC may
1844: allocate it in the same register as an unrelated input operand, on the
1845: assumption that the inputs are consumed before the outputs are produced.
1846: This assumption may be false if the assembler code actually consists of
1847: more than one instruction. In such a case, use @samp{&} for each output
1848: operand that may not overlap an input.
1849: @xref{Modifiers}.
1850:
1851: If you want to test the condition code produced by an assembler instruction,
1852: you must include a branch and a label in the @code{asm} construct, as follows:
1853:
1854: @example
1855: asm ("clr %0;frob %1;beq 0f;mov #1,%0;0:"
1856: : "g" (result)
1857: : "g" (input));
1858: @end example
1859:
1860: @noindent
1861: This assumes your assembler supports local labels, as the GNU assembler
1862: and most Unix assemblers do.
1863:
1864: Speaking of labels, jumps from one @code{asm} to another are not
1865: supported. The compiler's optimizers do not know about these jumps,
1866: and therefore they cannot take account of them when deciding how to
1867: optimize.
1868:
1869: @cindex macros containing @code{asm}
1870: Usually the most convenient way to use these @code{asm} instructions is to
1871: encapsulate them in macros that look like functions. For example,
1872:
1873: @example
1874: #define sin(x) \
1875: (@{ double __value, __arg = (x); \
1876: asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \
1877: __value; @})
1878: @end example
1879:
1880: @noindent
1881: Here the variable @code{__arg} is used to make sure that the instruction
1882: operates on a proper @code{double} value, and to accept only those
1883: arguments @code{x} which can convert automatically to a @code{double}.
1884:
1885: Another way to make sure the instruction operates on the correct data type
1886: is to use a cast in the @code{asm}. This is different from using a
1887: variable @code{__arg} in that it converts more different types. For
1888: example, if the desired type were @code{int}, casting the argument to
1889: @code{int} would accept a pointer with no complaint, while assigning the
1890: argument to an @code{int} variable named @code{__arg} would warn about
1891: using a pointer unless the caller explicitly casts it.
1892:
1893: If an @code{asm} has output operands, GNU CC assumes for optimization
1894: purposes that the instruction has no side effects except to change the
1895: output operands. This does not mean that instructions with a side effect
1896: cannot be used, but you must be careful, because the compiler may eliminate
1897: them if the output operands aren't used, or move them out of loops, or
1898: replace two with one if they constitute a common subexpression. Also, if
1899: your instruction does have a side effect on a variable that otherwise
1900: appears not to change, the old value of the variable may be reused later if
1901: it happens to be found in a register.
1902:
1903: You can prevent an @code{asm} instruction from being deleted, moved
1904: significantly, or combined, by writing the keyword @code{volatile} after
1905: the @code{asm}. For example:
1906:
1907: @example
1908: #define set_priority(x) \
1909: asm volatile ("set_priority %0": /* no outputs */ : "g" (x))
1910: @end example
1911:
1912: @noindent
1913: An instruction without output operands will not be deleted or moved
1914: significantly, regardless, unless it is unreachable.
1915:
1916: Note that even a volatile @code{asm} instruction can be moved in ways
1917: that appear insignificant to the compiler, such as across jump
1918: instructions. You can't expect a sequence of volatile @code{asm}
1919: instructions to remain perfectly consecutive. If you want consecutive
1920: output, use a single @code{asm}.
1921:
1922: It is a natural idea to look for a way to give access to the condition
1923: code left by the assembler instruction. However, when we attempted to
1924: implement this, we found no way to make it work reliably. The problem
1925: is that output operands might need reloading, which would result in
1926: additional following ``store'' instructions. On most machines, these
1927: instructions would alter the condition code before there was time to
1928: test it. This problem doesn't arise for ordinary ``test'' and
1929: ``compare'' instructions because they don't have any output operands.
1930:
1931: If you are writing a header file that should be includable in ANSI C
1932: programs, write @code{__asm__} instead of @code{asm}. @xref{Alternate
1933: Keywords}.
1934:
1935: @ifclear INTERNALS
1936: @c Show the details on constraints if they do not appear elsewhere in
1937: @c the manual
1938: @include md.texi
1939: @end ifclear
1940:
1941: @node Asm Labels
1942: @section Controlling Names Used in Assembler Code
1943: @cindex assembler names for identifiers
1944: @cindex names used in assembler code
1945: @cindex identifiers, names in assembler code
1946:
1947: You can specify the name to be used in the assembler code for a C
1948: function or variable by writing the @code{asm} (or @code{__asm__})
1949: keyword after the declarator as follows:
1950:
1951: @example
1952: int foo asm ("myfoo") = 2;
1953: @end example
1954:
1955: @noindent
1956: This specifies that the name to be used for the variable @code{foo} in
1957: the assembler code should be @samp{myfoo} rather than the usual
1958: @samp{_foo}.
1959:
1960: On systems where an underscore is normally prepended to the name of a C
1961: function or variable, this feature allows you to define names for the
1962: linker that do not start with an underscore.
1963:
1964: You cannot use @code{asm} in this way in a function @emph{definition}; but
1965: you can get the same effect by writing a declaration for the function
1966: before its definition and putting @code{asm} there, like this:
1967:
1968: @example
1969: extern func () asm ("FUNC");
1970:
1971: func (x, y)
1972: int x, y;
1973: @dots{}
1974: @end example
1975:
1976: It is up to you to make sure that the assembler names you choose do not
1977: conflict with any other assembler symbols. Also, you must not use a
1978: register name; that would produce completely invalid assembler code. GNU
1979: CC does not as yet have the ability to store static variables in registers.
1980: Perhaps that will be added.
1981:
1982: @node Explicit Reg Vars
1983: @section Variables in Specified Registers
1984: @cindex explicit register variables
1985: @cindex variables in specified registers
1986: @cindex specified registers
1987: @cindex registers, global allocation
1988:
1989: GNU C allows you to put a few global variables into specified hardware
1990: registers. You can also specify the register in which an ordinary
1991: register variable should be allocated.
1992:
1993: @itemize @bullet
1994: @item
1995: Global register variables reserve registers throughout the program.
1996: This may be useful in programs such as programming language
1997: interpreters which have a couple of global variables that are accessed
1998: very often.
1999:
2000: @item
2001: Local register variables in specific registers do not reserve the
2002: registers. The compiler's data flow analysis is capable of determining
2003: where the specified registers contain live values, and where they are
2004: available for other uses.
2005:
2006: These local variables are sometimes convenient for use with the extended
2007: @code{asm} feature (@pxref{Extended Asm}), if you want to write one
2008: output of the assembler instruction directly into a particular register.
2009: (This will work provided the register you specify fits the constraints
2010: specified for that operand in the @code{asm}.)
2011: @end itemize
2012:
2013: @menu
2014: * Global Reg Vars::
2015: * Local Reg Vars::
2016: @end menu
2017:
2018: @node Global Reg Vars
2019: @subsection Defining Global Register Variables
2020: @cindex global register variables
2021: @cindex registers, global variables in
2022:
2023: You can define a global register variable in GNU C like this:
2024:
2025: @example
2026: register int *foo asm ("a5");
2027: @end example
2028:
2029: @noindent
2030: Here @code{a5} is the name of the register which should be used. Choose a
2031: register which is normally saved and restored by function calls on your
2032: machine, so that library routines will not clobber it.
2033:
2034: Naturally the register name is cpu-dependent, so you would need to
2035: conditionalize your program according to cpu type. The register
2036: @code{a5} would be a good choice on a 68000 for a variable of pointer
2037: type. On machines with register windows, be sure to choose a ``global''
2038: register that is not affected magically by the function call mechanism.
2039:
2040: In addition, operating systems on one type of cpu may differ in how they
2041: name the registers; then you would need additional conditionals. For
2042: example, some 68000 operating systems call this register @code{%a5}.
2043:
2044: Eventually there may be a way of asking the compiler to choose a register
2045: automatically, but first we need to figure out how it should choose and
2046: how to enable you to guide the choice. No solution is evident.
2047:
2048: Defining a global register variable in a certain register reserves that
2049: register entirely for this use, at least within the current compilation.
2050: The register will not be allocated for any other purpose in the functions
2051: in the current compilation. The register will not be saved and restored by
2052: these functions. Stores into this register are never deleted even if they
2053: would appear to be dead, but references may be deleted or moved or
2054: simplified.
2055:
2056: It is not safe to access the global register variables from signal
2057: handlers, or from more than one thread of control, because the system
2058: library routines may temporarily use the register for other things (unless
2059: you recompile them specially for the task at hand).
2060:
2061: @cindex @code{qsort}, and global register variables
2062: It is not safe for one function that uses a global register variable to
2063: call another such function @code{foo} by way of a third function
2064: @code{lose} that was compiled without knowledge of this variable (i.e. in a
2065: different source file in which the variable wasn't declared). This is
2066: because @code{lose} might save the register and put some other value there.
2067: For example, you can't expect a global register variable to be available in
2068: the comparison-function that you pass to @code{qsort}, since @code{qsort}
2069: might have put something else in that register. (If you are prepared to
2070: recompile @code{qsort} with the same global register variable, you can
2071: solve this problem.)
2072:
2073: If you want to recompile @code{qsort} or other source files which do not
2074: actually use your global register variable, so that they will not use that
2075: register for any other purpose, then it suffices to specify the compiler
2076: option @samp{-ffixed-@var{reg}}. You need not actually add a global
2077: register declaration to their source code.
2078:
2079: A function which can alter the value of a global register variable cannot
2080: safely be called from a function compiled without this variable, because it
2081: could clobber the value the caller expects to find there on return.
2082: Therefore, the function which is the entry point into the part of the
2083: program that uses the global register variable must explicitly save and
2084: restore the value which belongs to its caller.
2085:
2086: @cindex register variable after @code{longjmp}
2087: @cindex global register after @code{longjmp}
2088: @cindex value after @code{longjmp}
2089: @findex longjmp
2090: @findex setjmp
2091: On most machines, @code{longjmp} will restore to each global register
2092: variable the value it had at the time of the @code{setjmp}. On some
2093: machines, however, @code{longjmp} will not change the value of global
2094: register variables. To be portable, the function that called @code{setjmp}
2095: should make other arrangements to save the values of the global register
2096: variables, and to restore them in a @code{longjmp}. This way, the same
2097: thing will happen regardless of what @code{longjmp} does.
2098:
2099: All global register variable declarations must precede all function
2100: definitions. If such a declaration could appear after function
2101: definitions, the declaration would be too late to prevent the register from
2102: being used for other purposes in the preceding functions.
2103:
2104: Global register variables may not have initial values, because an
2105: executable file has no means to supply initial contents for a register.
2106:
2107: On the Sparc, there are reports that g3 @dots{} g7 are suitable
2108: registers, but certain library functions, such as @code{getwd}, as well
2109: as the subroutines for division and remainder, modify g3 and g4. g1 and
2110: g2 are local temporaries.
2111:
2112: On the 68000, a2 @dots{} a5 should be suitable, as should d2 @dots{} d7.
2113: Of course, it will not do to use more than a few of those.
2114:
2115: @node Local Reg Vars
2116: @subsection Specifying Registers for Local Variables
2117: @cindex local variables, specifying registers
2118: @cindex specifying registers for local variables
2119: @cindex registers for local variables
2120:
2121: You can define a local register variable with a specified register
2122: like this:
2123:
2124: @example
2125: register int *foo asm ("a5");
2126: @end example
2127:
2128: @noindent
2129: Here @code{a5} is the name of the register which should be used. Note
2130: that this is the same syntax used for defining global register
2131: variables, but for a local variable it would appear within a function.
2132:
2133: Naturally the register name is cpu-dependent, but this is not a
2134: problem, since specific registers are most often useful with explicit
2135: assembler instructions (@pxref{Extended Asm}). Both of these things
2136: generally require that you conditionalize your program according to
2137: cpu type.
2138:
2139: In addition, operating systems on one type of cpu may differ in how they
2140: name the registers; then you would need additional conditionals. For
2141: example, some 68000 operating systems call this register @code{%a5}.
2142:
2143: Eventually there may be a way of asking the compiler to choose a register
2144: automatically, but first we need to figure out how it should choose and
2145: how to enable you to guide the choice. No solution is evident.
2146:
2147: Defining such a register variable does not reserve the register; it
2148: remains available for other uses in places where flow control determines
2149: the variable's value is not live. However, these registers are made
2150: unavailable for use in the reload pass. I would not be surprised if
2151: excessive use of this feature leaves the compiler too few available
2152: registers to compile certain functions.
2153:
2154: @node Alternate Keywords
2155: @section Alternate Keywords
2156: @cindex alternate keywords
2157: @cindex keywords, alternate
2158:
2159: The option @samp{-traditional} disables certain keywords; @samp{-ansi}
2160: disables certain others. This causes trouble when you want to use GNU C
2161: extensions, or ANSI C features, in a general-purpose header file that
2162: should be usable by all programs, including ANSI C programs and traditional
2163: ones. The keywords @code{asm}, @code{typeof} and @code{inline} cannot be
2164: used since they won't work in a program compiled with @samp{-ansi}, while
2165: the keywords @code{const}, @code{volatile}, @code{signed}, @code{typeof}
2166: and @code{inline} won't work in a program compiled with
2167: @samp{-traditional}.@refill
2168:
2169: The way to solve these problems is to put @samp{__} at the beginning and
2170: end of each problematical keyword. For example, use @code{__asm__}
2171: instead of @code{asm}, @code{__const__} instead of @code{const}, and
2172: @code{__inline__} instead of @code{inline}.
2173:
2174: Other C compilers won't accept these alternative keywords; if you want to
2175: compile with another compiler, you can define the alternate keywords as
2176: macros to replace them with the customary keywords. It looks like this:
2177:
2178: @example
2179: #ifndef __GNUC__
2180: #define __asm__ asm
2181: #endif
2182: @end example
2183:
2184: @samp{-pedantic} causes warnings for many GNU C extensions. You can
2185: prevent such warnings within one expression by writing
2186: @code{__extension__} before the expression. @code{__extension__} has no
2187: effect aside from this.
2188:
2189: @node Incomplete Enums
2190: @section Incomplete @code{enum} Types
2191:
2192: You can define an @code{enum} tag without specifying its possible values.
2193: This results in an incomplete type, much like what you get if you write
2194: @code{struct foo} without describing the elements. A later declaration
2195: which does specify the possible values completes the type.
2196:
2197: You can't allocate variables or storage using the type while it is
2198: incomplete. However, you can work with pointers to that type.
2199:
2200: This extension may not be very useful, but it makes the handling of
2201: @code{enum} more consistent with the way @code{struct} and @code{union}
2202: are handled.
2203:
2204: @node Function Names
2205: @section Function Names as Strings
2206:
2207: GNU CC predefines two string variables to be the name of the current function.
2208: The variable @code{__FUNCTION__} is the name of the function as it appears
2209: in the source. The variable @code{__PRETTY_FUNCTION__} is the name of
2210: the function pretty printed in a language specific fashion.
2211:
2212: These names are always the same in a C function, but in a C++ function
2213: they may be different. For example, this program:
2214:
2215: @smallexample
2216: extern "C" @{
2217: extern int printf (char *, ...);
2218: @}
2219:
2220: class a @{
2221: public:
2222: sub (int i)
2223: @{
2224: printf ("__FUNCTION__ = %s\n", __FUNCTION__);
2225: printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__);
2226: @}
2227: @};
2228:
2229: int
2230: main (void)
2231: @{
2232: a ax;
2233: ax.sub (0);
2234: return 0;
2235: @}
2236: @end smallexample
2237:
2238: @noindent
2239: gives this output:
2240:
2241: @smallexample
2242: __FUNCTION__ = sub
2243: __PRETTY_FUNCTION__ = int a::sub (int)
2244: @end smallexample
2245:
2246: @node C++ Extensions
2247: @chapter Extensions to the C++ Language
2248: @cindex extensions, C++ language
2249: @cindex C++ language extensions
2250:
2251: The GNU compiler provides these extensions to the C++ language (and you
2252: can also use most of the C language extensions in your C++ programs). If you
2253: want to write code that checks whether these features are available, you can
2254: test for the GNU compiler the same way as for C programs: check for a
2255: predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to
2256: test specifically for GNU C++ (@pxref{Standard Predefined,,Standard
2257: Predefined Macros,cpp.info,The C Preprocessor}).
2258:
2259: @menu
2260: * Naming Results:: Giving a name to C++ function return values.
2261: * Min and Max:: C++ Minimum and maximum operators.
2262: * Destructors and Goto:: Goto is safe to use in C++ even when destructors
2263: are needed.
2264: * C++ Interface:: You can use a single C++ header file for both
2265: declarations and definitions.
2266: @end menu
2267:
2268: @node Naming Results
2269: @section Named Return Values in C++
2270:
2271: @cindex @code{return}, in C++ function header
2272: @cindex return value, named, in C++
2273: @cindex named return value in C++
2274: @cindex C++ named return value
2275: GNU C++ extends the function-definition syntax to allow you to specify a
2276: name for the result of a function outside the body of the definition, in
2277: C++ programs:
2278:
2279: @example
2280: @group
2281: @var{type}
2282: @var{functionname} (@var{args}) return @var{resultname};
2283: @{
2284: @dots{}
2285: @var{body}
2286: @dots{}
2287: @}
2288: @end group
2289: @end example
2290:
2291: You can use this feature to avoid an extra constructor call when
2292: a function result has a class type. For example, consider a function
2293: @code{m}, declared as @w{@samp{X v = m ();}}, whose result is of class
2294: @code{X}:
2295:
2296: @example
2297: X
2298: m ()
2299: @{
2300: X b;
2301: b.a = 23;
2302: return b;
2303: @}
2304: @end example
2305:
2306: @cindex implicit argument: return value
2307: Although @code{m} appears to have no arguments, in fact it has one implicit
2308: argument: the address of the return value. At invocation, the address
2309: of enough space to hold @code{v} is sent in as the implicit argument.
2310: Then @code{b} is constructed and its @code{a} field is set to the value
2311: 23. Finally, a copy constructor (a constructor of the form @samp{X(X&)})
2312: is applied to @code{b}, with the (implicit) return value location as the
2313: target, so that @code{v} is now bound to the return value.
2314:
2315: But this is wasteful. The local @code{b} is declared just to hold
2316: something that will be copied right out. While a compiler that
2317: combined an ``elision'' algorithm with interprocedural data flow
2318: analysis could conceivably eliminate all of this, it is much more
2319: practical to allow you to assist the compiler in generating
2320: efficient code by manipulating the return value explicitly,
2321: thus avoiding the local variable and copy constructor altogether.
2322:
2323: Using the extended GNU C++ function-definition syntax, you can avoid the
2324: temporary allocation and copying by naming @code{r} as your return value
2325: as the outset, and assigning to its @code{a} field directly:
2326:
2327: @example
2328: X
2329: m () return r;
2330: @{
2331: r.a = 23;
2332: @}
2333: @end example
2334:
2335: @noindent
2336: The declaration of @code{r} is a standard, proper declaration, whose effects
2337: are executed @strong{before} any of the body of @code{m}.
2338:
2339: Functions of this type impose no additional restrictions; in particular,
2340: you can execute @code{return} statements, or return implicitly by
2341: reaching the end of the function body (``falling off the edge'').
2342: Cases like
2343:
2344: @example
2345: X
2346: m () return r (23);
2347: @{
2348: return;
2349: @}
2350: @end example
2351:
2352: @noindent
2353: (or even @w{@samp{X m () return r (23); @{ @}}}) are unambiguous, since
2354: the return value @code{r} has been initialized in either case. The
2355: following code may be hard to read, but also works predictably:
2356:
2357: @example
2358: X
2359: m () return r;
2360: @{
2361: X b;
2362: return b;
2363: @}
2364: @end example
2365:
2366: The return value slot denoted by @code{r} is initialized at the outset,
2367: but the statement @samp{return b;} overrides this value. The compiler
2368: deals with this by destroying @code{r} (calling the destructor if there
2369: is one, or doing nothing if there is not), and then reinitializing
2370: @code{r} with @code{b}.
2371:
2372: This extension is provided primarily to help people who use overloaded
2373: operators, where there is a great need to control not just the
2374: arguments, but the return values of functions. For classes where the
2375: copy constructor incurs a heavy performance penalty (especially in the
2376: common case where there is a quick default constructor), this is a major
2377: savings. The disadvantage of this extension is that you do not control
2378: when the default constructor for the return value is called: it is
2379: always called at the beginning.
2380:
2381: @node Min and Max
2382: @section Minimum and Maximum Operators in C++
2383:
2384: It is very convenient to have operators which return the ``minimum'' or the
2385: ``maximum'' of two arguments. In GNU C++ (but not in GNU C),
2386:
2387: @table @code
2388: @item @var{a} <? @var{b}
2389: @findex <?
2390: @cindex minimum operator
2391: is the @dfn{minimum}, returning the smaller of the numeric values
2392: @var{a} and @var{b};
2393:
2394: @item @var{a} >? @var{b}
2395: @findex >?
2396: @cindex maximum operator
2397: is the @dfn{maximum}, returning the larger of the numeric values @var{a}
2398: and @var{b}.
2399: @end table
2400:
2401: These operations are not primitive in ordinary C++, since you can
2402: use a macro to return the minimum of two things in C++, as in the
2403: following example.
2404:
2405: @example
2406: #define MIN(X,Y) ((X) < (Y) ? : (X) : (Y))
2407: @end example
2408:
2409: @noindent
2410: You might then use @w{@samp{int min = MIN (i, j);}} to set @var{min} to
2411: the minimum value of variables @var{i} and @var{j}.
2412:
2413: However, side effects in @code{X} or @code{Y} may cause unintended
2414: behavior. For example, @code{MIN (i++, j++)} will fail, incrementing
2415: the smaller counter twice. A GNU C extension allows you to write safe
2416: macros that avoid this kind of problem (@pxref{Naming Types,,Naming an
2417: Expression's Type}). However, writing @code{MIN} and @code{MAX} as
2418: macros also forces you to use function-call notation notation for a
2419: fundamental arithmetic operation. Using GNU C++ extensions, you can
2420: write @w{@samp{int min = i <? j;}} instead.
2421:
2422: Since @code{<?} and @code{>?} are built into the compiler, they properly
2423: handle expressions with side-effects; @w{@samp{int min = i++ <? j++;}}
2424: works correctly.
2425:
2426: @node Destructors and Goto
2427: @section @code{goto} and Destructors in GNU C++
2428:
2429: @cindex @code{goto} in C++
2430: @cindex destructors vs @code{goto}
2431: In C++ programs, you can safely use the @code{goto} statement. When you
2432: use it to exit a block which contains aggregates requiring destructors,
2433: the destructors will run before the @code{goto} transfers control. (In
2434: ANSI C++, @code{goto} is restricted to targets within the current
2435: block.)
2436:
2437: @cindex constructors vs @code{goto}
2438: The compiler still forbids using @code{goto} to @emph{enter} a scope
2439: that requires constructors.
2440:
2441: @node C++ Interface
2442: @section Declarations and Definitions in One Header
2443:
2444: @cindex interface and implementation headers, C++
2445: @cindex C++ interface and implementation headers
2446: C++ object definitions can be quite complex. In principle, your source
2447: code will need two kinds of things for each object that you use across
2448: more than one source file. First, you need an @dfn{interface}
2449: specification, describing its structure with type declarations and
2450: function prototypes. Second, you need the @dfn{implementation} itself.
2451: It can be tedious to maintain a separate interface description in a
2452: header file, in parallel to the actual implementation. It is also
2453: dangerous, since separate interface and implementation definitions may
2454: not remain parallel.
2455:
2456: @cindex pragmas, interface and implementation
2457: With GNU C++, you can use a single header file for both purposes.
2458:
2459: @quotation
2460: @emph{Warning:} The mechanism to specify this is in transition. For the
2461: nonce, you must use one of two @code{#pragma} commands; in a future
2462: release of GNU C++, an alternative mechanism will make these
2463: @code{#pragma} commands unnecessary.
2464: @end quotation
2465:
2466: The header file contains the full definitions, but is marked with
2467: @samp{#pragma interface} in the source code. This allows the compiler
2468: to use the header file only as an interface specification when ordinary
2469: source files incorporate it with @code{#include}. In the single source
2470: file where the full implementation belongs, you can use either a naming
2471: convention or @samp{#pragma implementation} to indicate this alternate
2472: use of the header file.
2473:
2474: @table @code
2475: @item #pragma interface
2476: @kindex #pragma interface
2477: Use this directive in @emph{header files} that define object classes, to save
2478: space in most of the object files that use those classes. Normally,
2479: local copies of certain information (backup copies of inline member
2480: functions, debugging information, and the internal tables that implement
2481: virtual functions) must be kept in each object file that includes class
2482: definitions. You can use this pragma to avoid such duplication. When a
2483: header file containing @samp{#pragma interface} is included in a
2484: compilation, this auxiliary information will not be generated (unless
2485: the main input source file itself uses @samp{#pragma implementation}).
2486: Instead, the object files will contain references to be resolved at link
2487: time.
2488:
2489: @item #pragma implementation
2490: @itemx #pragma implementation "@var{objects}.h"
2491: @kindex #pragma implementation
2492: Use this pragma in a @emph{main input file}, when you want full output from
2493: included header files to be generated (and made globally visible). The
2494: included header file, in turn, should use @samp{#pragma interface}.
2495: Backup copies of inline member functions, debugging information, and the
2496: internal tables used to implement virtual functions are all generated in
2497: implementation files.
2498:
2499: @cindex implied @code{#pragma implementation}
2500: @cindex @code{#pragma implementation}, implied
2501: @cindex naming convention, implementation headers
2502: @samp{#pragma implementation} is @emph{implied} whenever the
2503: basename@footnote{A file's @dfn{basename} is the name stripped of all
2504: leading path information and of trailing suffixes, such as @samp{.h} or
2505: @samp{.C} or @samp{.cc}.} of your source file matches the basename of a
2506: header file it includes. There is no way to turn this off (other than
2507: using a different name for one of the two files). In the same vein, if
2508: you use @samp{#pragma implementation} with no argument, it applies to an
2509: include file with the same basename as your source file. For example, in
2510: @file{allclass.cc}, @samp{#pragma implementation} by itself is
2511: equivalent to @samp{#pragma implementation "allclass.h"}; but even if
2512: you do not say @samp{#pragma implementation} at all, @file{allclass.h}
2513: is treated as an implementation file whenever you include it from
2514: @file{allclass.cc}.
2515:
2516: If you use an explicit @samp{#pragma implementation}, it must appear in
2517: your source file @emph{before} you include the affected header files.
2518:
2519: Use the string argument if you want a single implementation file to
2520: include code from multiple header files. (You must also use
2521: @samp{#include} to include the header file; @samp{#pragma
2522: implementation} only specifies how to use the file---it doesn't actually
2523: include it.)
2524:
2525: There is no way to split up the contents of a single header file into
2526: multiple implementation files.
2527: @end table
2528:
2529: @cindex inlining and C++ pragmas
2530: @cindex C++ pragmas, effect on inlining
2531: @cindex pragmas in C++, effect on inlining
2532: @samp{#pragma implementation} and @samp{#pragma interface} also have an
2533: effect on function inlining.
2534:
2535: If you define a class in a header file marked with @samp{#pragma
2536: interface}, the effect on a function defined in that class is similar to
2537: an explicit @code{extern} declaration---the compiler emits no code at
2538: all to define an independent version of the function. Its definition
2539: is used only for inlining with its callers.
2540:
2541: Conversely, when you include the same header file in a main source file
2542: that declares it as @samp{#pragma implementation}, the compiler emits
2543: code for the function itself; this defines a version of the function
2544: that can be found via pointers (or by callers compiled without
2545: inlining).
2546:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.