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