![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to gcc.info-7 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Apple XNU] / GNUtools / cc|
Return to gcc.info-7 CVS log | Up to [Apple XNU] / GNUtools / cc |
1.1 root 1: This is Info file gcc.info, produced by Makeinfo-1.54 from the input
2: file gcc.texi.
3:
4: This file documents the use and the internals of the GNU compiler.
5:
6: Published by the Free Software Foundation 675 Massachusetts Avenue
7: Cambridge, MA 02139 USA
8:
9: Copyright (C) 1988, 1989, 1992, 1993 Free Software Foundation, Inc.
10:
11: Permission is granted to make and distribute verbatim copies of this
12: manual provided the copyright notice and this permission notice are
13: preserved on all copies.
14:
15: Permission is granted to copy and distribute modified versions of
16: this manual under the conditions for verbatim copying, provided also
17: that the sections entitled "GNU General Public License" and "Protect
18: Your Freedom--Fight `Look And Feel'" are included exactly as in the
19: original, and provided that the entire resulting derived work is
20: distributed under the terms of a permission notice identical to this
21: one.
22:
23: Permission is granted to copy and distribute translations of this
24: manual into another language, under the above conditions for modified
25: versions, except that the sections entitled "GNU General Public
26: License" and "Protect Your Freedom--Fight `Look And Feel'", and this
27: permission notice, may be included in translations approved by the Free
28: Software Foundation instead of in the original English.
29:
30:
31: File: gcc.info, Node: Variable Length, Next: Macro Varargs, Prev: Zero Length, Up: C Extensions
32:
33: Arrays of Variable Length
34: =========================
35:
36: Variable-length automatic arrays are allowed in GNU C. These arrays
37: are declared like any other automatic arrays, but with a length that is
38: not a constant expression. The storage is allocated at the point of
39: declaration and deallocated when the brace-level is exited. For
40: example:
41:
42: FILE *
43: concat_fopen (char *s1, char *s2, char *mode)
44: {
45: char str[strlen (s1) + strlen (s2) + 1];
46: strcpy (str, s1);
47: strcat (str, s2);
48: return fopen (str, mode);
49: }
50:
51: Jumping or breaking out of the scope of the array name deallocates
52: the storage. Jumping into the scope is not allowed; you get an error
53: message for it.
54:
55: You can use the function `alloca' to get an effect much like
56: variable-length arrays. The function `alloca' is available in many
57: other C implementations (but not in all). On the other hand,
58: variable-length arrays are more elegant.
59:
60: There are other differences between these two methods. Space
61: allocated with `alloca' exists until the containing *function* returns.
62: The space for a variable-length array is deallocated as soon as the
63: array name's scope ends. (If you use both variable-length arrays and
64: `alloca' in the same function, deallocation of a variable-length array
65: will also deallocate anything more recently allocated with `alloca'.)
66:
67: You can also use variable-length arrays as arguments to functions:
68:
69: struct entry
70: tester (int len, char data[len][len])
71: {
72: ...
73: }
74:
75: The length of an array is computed once when the storage is allocated
76: and is remembered for the scope of the array in case you access it with
77: `sizeof'.
78:
79: If you want to pass the array first and the length afterward, you can
80: use a forward declaration in the parameter list--another GNU extension.
81:
82: struct entry
83: tester (int len; char data[len][len], int len)
84: {
85: ...
86: }
87:
88: The `int len' before the semicolon is a "parameter forward
89: declaration", and it serves the purpose of making the name `len' known
90: when the declaration of `data' is parsed.
91:
92: You can write any number of such parameter forward declarations in
93: the parameter list. They can be separated by commas or semicolons, but
94: the last one must end with a semicolon, which is followed by the "real"
95: parameter declarations. Each forward declaration must match a "real"
96: declaration in parameter name and data type.
97:
98:
99: File: gcc.info, Node: Macro Varargs, Next: Subscripting, Prev: Variable Length, Up: C Extensions
100:
101: Macros with Variable Numbers of Arguments
102: =========================================
103:
104: In GNU C, a macro can accept a variable number of arguments, much as
105: a function can. The syntax for defining the macro looks much like that
106: used for a function. Here is an example:
107:
108: #define eprintf(format, args...) \
109: fprintf (stderr, format , ## args)
110:
111: Here `args' is a "rest argument": it takes in zero or more
112: arguments, as many as the call contains. All of them plus the commas
113: between them form the value of `args', which is substituted into the
114: macro body where `args' is used. Thus, we have this expansion:
115:
116: eprintf ("%s:%d: ", input_file_name, line_number)
117: ==>
118: fprintf (stderr, "%s:%d: " , input_file_name, line_number)
119:
120: Note that the comma after the string constant comes from the definition
121: of `eprintf', whereas the last comma comes from the value of `args'.
122:
123: The reason for using `##' is to handle the case when `args' matches
124: no arguments at all. In this case, `args' has an empty value. In this
125: case, the second comma in the definition becomes an embarrassment: if
126: it got through to the expansion of the macro, we would get something
127: like this:
128:
129: fprintf (stderr, "success!\n" , )
130:
131: which is invalid C syntax. `##' gets rid of the comma, so we get the
132: following instead:
133:
134: fprintf (stderr, "success!\n")
135:
136: This is a special feature of the GNU C preprocessor: `##' before a
137: rest argument that is empty discards the preceding sequence of
138: non-whitespace characters from the macro definition. (If another macro
139: argument precedes, none of it is discarded.)
140:
141: It might be better to discard the last preprocessor token instead of
142: the last preceding sequence of non-whitespace characters; in fact, we
143: may someday change this feature to do so. We advise you to write the
144: macro definition so that the preceding sequence of non-whitespace
145: characters is just a single token, so that the meaning will not change
146: if we change the definition of this feature.
147:
148:
149: File: gcc.info, Node: Subscripting, Next: Pointer Arith, Prev: Macro Varargs, Up: C Extensions
150:
151: Non-Lvalue Arrays May Have Subscripts
152: =====================================
153:
154: Subscripting is allowed on arrays that are not lvalues, even though
155: the unary `&' operator is not. For example, this is valid in GNU C
156: though not valid in other C dialects:
157:
158: struct foo {int a[4];};
159:
160: struct foo f();
161:
162: bar (int index)
163: {
164: return f().a[index];
165: }
166:
167:
168: File: gcc.info, Node: Pointer Arith, Next: Initializers, Prev: Subscripting, Up: C Extensions
169:
170: Arithmetic on `void'- and Function-Pointers
171: ===========================================
172:
173: In GNU C, addition and subtraction operations are supported on
174: pointers to `void' and on pointers to functions. This is done by
175: treating the size of a `void' or of a function as 1.
176:
177: A consequence of this is that `sizeof' is also allowed on `void' and
178: on function types, and returns 1.
179:
180: The option `-Wpointer-arith' requests a warning if these extensions
181: are used.
182:
183:
184: File: gcc.info, Node: Initializers, Next: Constructors, Prev: Pointer Arith, Up: C Extensions
185:
186: Non-Constant Initializers
187: =========================
188:
189: The elements of an aggregate initializer for an automatic variable
190: are not required to be constant expressions in GNU C. Here is an
191: example of an initializer with run-time varying elements:
192:
193: foo (float f, float g)
194: {
195: float beat_freqs[2] = { f-g, f+g };
196: ...
197: }
198:
199:
200: File: gcc.info, Node: Constructors, Next: Labeled Elements, Prev: Initializers, Up: C Extensions
201:
202: Constructor Expressions
203: =======================
204:
205: GNU C supports constructor expressions. A constructor looks like a
206: cast containing an initializer. Its value is an object of the type
207: specified in the cast, containing the elements specified in the
208: initializer.
209:
210: Usually, the specified type is a structure. Assume that `struct
211: foo' and `structure' are declared as shown:
212:
213: struct foo {int a; char b[2];} structure;
214:
215: Here is an example of constructing a `struct foo' with a constructor:
216:
217: structure = ((struct foo) {x + y, 'a', 0});
218:
219: This is equivalent to writing the following:
220:
221: {
222: struct foo temp = {x + y, 'a', 0};
223: structure = temp;
224: }
225:
226: You can also construct an array. If all the elements of the
227: constructor are (made up of) simple constant expressions, suitable for
228: use in initializers, then the constructor is an lvalue and can be
229: coerced to a pointer to its first element, as shown here:
230:
231: char **foo = (char *[]) { "x", "y", "z" };
232:
233: Array constructors whose elements are not simple constants are not
234: very useful, because the constructor is not an lvalue. There are only
235: two valid ways to use it: to subscript it, or initialize an array
236: variable with it. The former is probably slower than a `switch'
237: statement, while the latter does the same thing an ordinary C
238: initializer would do. Here is an example of subscripting an array
239: constructor:
240:
241: output = ((int[]) { 2, x, 28 }) [input];
242:
243: Constructor expressions for scalar types and union types are is also
244: allowed, but then the constructor expression is equivalent to a cast.
245:
246:
247: File: gcc.info, Node: Labeled Elements, Next: Cast to Union, Prev: Constructors, Up: C Extensions
248:
249: Labeled Elements in Initializers
250: ================================
251:
252: Standard C requires the elements of an initializer to appear in a
253: fixed order, the same as the order of the elements in the array or
254: structure being initialized.
255:
256: In GNU C you can give the elements in any order, specifying the array
257: indices or structure field names they apply to.
258:
259: To specify an array index, write `[INDEX]' before the element value.
260: For example,
261:
262: int a[6] = { [4] 29, [2] 15 };
263:
264: is equivalent to
265:
266: int a[6] = { 0, 0, 15, 0, 29, 0 };
267:
268: The index values must be constant expressions, even if the array being
269: initialized is automatic.
270:
271: In a structure initializer, specify the name of a field to initialize
272: with `FIELDNAME:' before the element value. For example, given the
273: following structure,
274:
275: struct point { int x, y; };
276:
277: the following initialization
278:
279: struct point p = { y: yvalue, x: xvalue };
280:
281: is equivalent to
282:
283: struct point p = { xvalue, yvalue };
284:
285: You can also use an element label when initializing a union, to
286: specify which element of the union should be used. For example,
287:
288: union foo { int i; double d; };
289:
290: union foo f = { d: 4 };
291:
292: will convert 4 to a `double' to store it in the union using the second
293: element. By contrast, casting 4 to type `union foo' would store it
294: into the union as the integer `i', since it is an integer. (*Note Cast
295: to Union::.)
296:
297: You can combine this technique of naming elements with ordinary C
298: initialization of successive elements. Each initializer element that
299: does not have a label applies to the next consecutive element of the
300: array or structure. For example,
301:
302: int a[6] = { [1] v1, v2, [4] v4 };
303:
304: is equivalent to
305:
306: int a[6] = { 0, v1, v2, 0, v4, 0 };
307:
308: Labeling the elements of an array initializer is especially useful
309: when the indices are characters or belong to an `enum' type. For
310: example:
311:
312: int whitespace[256]
313: = { [' '] 1, ['\t'] 1, ['\h'] 1,
314: ['\f'] 1, ['\n'] 1, ['\r'] 1 };
315:
316:
317: File: gcc.info, Node: Case Ranges, Next: Function Attributes, Prev: Cast to Union, Up: C Extensions
318:
319: Case Ranges
320: ===========
321:
322: You can specify a range of consecutive values in a single `case'
323: label, like this:
324:
325: case LOW ... HIGH:
326:
327: This has the same effect as the proper number of individual `case'
328: labels, one for each integer value from LOW to HIGH, inclusive.
329:
330: This feature is especially useful for ranges of ASCII character
331: codes:
332:
333: case 'A' ... 'Z':
334:
335: *Be careful:* Write spaces around the `...', for otherwise it may be
336: parsed wrong when you use it with integer values. For example, write
337: this:
338:
339: case 1 ... 5:
340:
341: rather than this:
342:
343: case 1...5:
344:
345: *Warning to C++ users:* When compiling C++, you must write two dots
346: `..' rather than three to specify a range in case statements, thus:
347:
348: case 'A' .. 'Z':
349:
350: This is an anachronism in the GNU C++ front end, and will be
351: rectified in a future release.
352:
353:
354: File: gcc.info, Node: Cast to Union, Next: Case Ranges, Prev: Labeled Elements, Up: C Extensions
355:
356: Cast to a Union Type
357: ====================
358:
359: A cast to union type is similar to other casts, except that the type
360: specified is a union type. You can specify the type either with `union
361: TAG' or with a typedef name. A cast to union is actually a constructor
362: though, not a cast, and hence does not yield an lvalue like normal
363: casts. (*Note Constructors::.)
364:
365: The types that may be cast to the union type are those of the members
366: of the union. Thus, given the following union and variables:
367:
368: union foo { int i; double d; };
369: int x;
370: double y;
371:
372: both `x' and `y' can be cast to type `union' foo.
373:
374: Using the cast as the right-hand side of an assignment to a variable
375: of union type is equivalent to storing in a member of the union:
376:
377: union foo u;
378: ...
379: u = (union foo) x == u.i = x
380: u = (union foo) y == u.d = y
381:
382: You can also use the union cast as a function argument:
383:
384: void hack (union foo);
385: ...
386: hack ((union foo) x);
387:
388:
389: File: gcc.info, Node: Function Attributes, Next: Function Prototypes, Prev: Case Ranges, Up: C Extensions
390:
391: Declaring Attributes of Functions
392: =================================
393:
394: In GNU C, you declare certain things about functions called in your
395: program which help the compiler optimize function calls.
396:
397: A few standard library functions, such as `abort' and `exit', cannot
398: return. GNU CC knows this automatically. Some programs define their
399: own functions that never return. You can declare them `volatile' to
400: tell the compiler this fact. For example,
401:
402: typedef void voidfn ();
403:
404: volatile voidfn fatal;
405:
406: void
407: fatal (...)
408: {
409: ... /* Print error message. */ ...
410: exit (1);
411: }
412:
413: The `volatile' keyword tells the compiler to assume that `fatal'
414: cannot return. It can then optimize without regard to what would
415: happen if `fatal' ever did return. This makes slightly better code.
416: More importantly, it helps avoid spurious warnings of uninitialized
417: variables.
418:
419: Do not assume that registers saved by the calling function are
420: restored before calling the `volatile' function.
421:
422: It does not make sense for a `volatile' function to have a return
423: type other than `void'.
424:
425: Many functions do not examine any values except their arguments, and
426: have no effects except the return value. Such a function can be subject
427: to common subexpression elimination and loop optimization just as an
428: arithmetic operator would be. These functions should be declared
429: `const'. For example,
430:
431: typedef int intfn ();
432:
433: extern const intfn square;
434:
435: says that the hypothetical function `square' is safe to call fewer
436: times than the program says.
437:
438: Note that a function that has pointer arguments and examines the data
439: pointed to must *not* be declared `const'. Likewise, a function that
440: calls a non-`const' function usually must not be `const'. It does not
441: make sense for a `const' function to return `void'.
442:
443: The examples above use `typedef' because that is the only way to
444: declare a function `const' or `volatile'. A declaration like this:
445:
446: extern const int square ();
447:
448: does not have this effect; it says that the return type of `square' is
449: `const', not `square' itself.
450:
451: Some people object to this feature, suggesting that ANSI C's
452: `#pragma' should be used instead. There are two reasons for not doing
453: this.
454:
455: 1. It is impossible to generate `#pragma' commands from a macro.
456:
457: 2. There is no telling what the same `#pragma' might mean in another
458: compiler.
459:
460: These two reasons apply to almost any application that might be
461: proposed for `#pragma'. It is basically a mistake to use `#pragma' for
462: *anything*.
463:
464: The keyword `__attribute__' allows you to specify special attributes
465: when making a declaration. This keyword is followed by an attribute
466: specification inside double parentheses. One attribute, `format', is
467: currently defined for functions. Others are implemented for variables
468: and structure fields (*note Variable Attributes::.).
469:
470: `format (ARCHETYPE, STRING-INDEX, FIRST-TO-CHECK)'
471: The `format' attribute specifies that a function takes `printf' or
472: `scanf' style arguments which should be type-checked against a
473: format string. For example, the declaration:
474:
475: extern int
476: my_printf (void *my_object, const char *my_format, ...)
477: __attribute__ ((format (printf, 2, 3)));
478:
479: causes the compiler to check the arguments in calls to `my_printf'
480: for consistency with the `printf' style format string argument
481: `my_format'.
482:
483: The parameter ARCHETYPE determines how the format string is
484: interpreted, and should be either `printf' or `scanf'. The
485: parameter STRING-INDEX specifies which argument is the format
486: string argument (starting from 1), while FIRST-TO-CHECK is the
487: number of the first argument to check against the format string.
488: For functions where the arguments are not available to be checked
489: (such as `vprintf'), specify the third parameter as zero. In this
490: case the compiler only checks the format string for consistency.
491:
492: In the example above, the format string (`my_format') is the second
493: argument of the function `my_print', and the arguments to check
494: start with the third argument, so the correct parameters for the
495: format attribute are 2 and 3.
496:
497: The `format' attribute allows you to identify your own functions
498: which take format strings as arguments, so that GNU CC can check
499: the calls to these functions for errors. The compiler always
500: checks formats for the ANSI library functions `printf', `fprintf',
501: `sprintf', `scanf', `fscanf', `sscanf', `vprintf', `vfprintf' and
502: `vsprintf' whenever such warnings are requested (using
503: `-Wformat'), so there is no need to modify the header file
504: `stdio.h'.
505:
506:
507: File: gcc.info, Node: Function Prototypes, Next: Dollar Signs, Prev: Function Attributes, Up: C Extensions
508:
509: Prototypes and Old-Style Function Definitions
510: =============================================
511:
512: GNU C extends ANSI C to allow a function prototype to override a
513: later old-style non-prototype definition. Consider the following
514: example:
515:
516: /* Use prototypes unless the compiler is old-fashioned. */
517: #if __STDC__
518: #define P(x) x
519: #else
520: #define P(x) ()
521: #endif
522:
523: /* Prototype function declaration. */
524: int isroot P((uid_t));
525:
526: /* Old-style function definition. */
527: int
528: isroot (x) /* ??? lossage here ??? */
529: uid_t x;
530: {
531: return x == 0;
532: }
533:
534: Suppose the type `uid_t' happens to be `short'. ANSI C does not
535: allow this example, because subword arguments in old-style
536: non-prototype definitions are promoted. Therefore in this example the
537: function definition's argument is really an `int', which does not match
538: the prototype argument type of `short'.
539:
540: This restriction of ANSI C makes it hard to write code that is
541: portable to traditional C compilers, because the programmer does not
542: know whether the `uid_t' type is `short', `int', or `long'. Therefore,
543: in cases like these GNU C allows a prototype to override a later
544: old-style definition. More precisely, in GNU C, a function prototype
545: argument type overrides the argument type specified by a later
546: old-style definition if the former type is the same as the latter type
547: before promotion. Thus in GNU C the above example is equivalent to the
548: following:
549:
550: int isroot (uid_t);
551:
552: int
553: isroot (uid_t x)
554: {
555: return x == 0;
556: }
557:
558:
559: File: gcc.info, Node: Dollar Signs, Next: Character Escapes, Prev: Function Prototypes, Up: C Extensions
560:
561: Dollar Signs in Identifier Names
562: ================================
563:
564: In GNU C, you may use dollar signs in identifier names. This is
565: because many traditional C implementations allow such identifiers.
566:
567: On some machines, dollar signs are allowed in identifiers if you
568: specify `-traditional'. On a few systems they are allowed by default,
569: even if you do not use `-traditional'. But they are never allowed if
570: you specify `-ansi'.
571:
572: There are certain ANSI C programs (obscure, to be sure) that would
573: compile incorrectly if dollar signs were permitted in identifiers. For
574: example:
575:
576: #define foo(a) #a
577: #define lose(b) foo (b)
578: #define test$
579: lose (test)
580:
581:
582: File: gcc.info, Node: Character Escapes, Next: Variable Attributes, Prev: Dollar Signs, Up: C Extensions
583:
584: The Character ESC in Constants
585: ==============================
586:
587: You can use the sequence `\e' in a string or character constant to
588: stand for the ASCII character ESC.
589:
590:
591: File: gcc.info, Node: Alignment, Next: Inline, Prev: Variable Attributes, Up: C Extensions
592:
593: Inquiring on Alignment of Types or Variables
594: ============================================
595:
596: The keyword `__alignof__' allows you to inquire about how an object
597: is aligned, or the minimum alignment usually required by a type. Its
598: syntax is just like `sizeof'.
599:
600: For example, if the target machine requires a `double' value to be
601: aligned on an 8-byte boundary, then `__alignof__ (double)' is 8. This
602: is true on many RISC machines. On more traditional machine designs,
603: `__alignof__ (double)' is 4 or even 2.
604:
605: Some machines never actually require alignment; they allow reference
606: to any data type even at an odd addresses. For these machines,
607: `__alignof__' reports the *recommended* alignment of a type.
608:
609: When the operand of `__alignof__' is an lvalue rather than a type,
610: the value is the largest alignment that the lvalue is known to have.
611: It may have this alignment as a result of its data type, or because it
612: is part of a structure and inherits alignment from that structure. For
613: example, after this declaration:
614:
615: struct foo { int x; char y; } foo1;
616:
617: the value of `__alignof__ (foo1.y)' is probably 2 or 4, the same as
618: `__alignof__ (int)', even though the data type of `foo1.y' does not
619: itself demand any alignment.
620:
621: A related feature which lets you specify the alignment of an object
622: is `__attribute__ ((aligned (ALIGNMENT)))'; see the following section.
623:
624:
625: File: gcc.info, Node: Variable Attributes, Next: Alignment, Prev: Character Escapes, Up: C Extensions
626:
627: Specifying Attributes of Variables
628: ==================================
629:
630: The keyword `__attribute__' allows you to specify special attributes
631: of variables or structure fields. This keyword is followed by an
632: attribute specification inside double parentheses. Four attributes are
633: currently defined: `aligned', `format', `mode' and `packed'. `format'
634: is used for functions, and thus not documented here; see *Note Function
635: Attributes::.
636:
637: `aligned (ALIGNMENT)'
638: This attribute specifies a minimum alignment for the variable or
639: structure field, measured in bytes. For example, the declaration:
640:
641: int x __attribute__ ((aligned (16))) = 0;
642:
643: causes the compiler to allocate the global variable `x' on a
644: 16-byte boundary. On a 68040, this could be used in conjunction
645: with an `asm' expression to access the `move16' instruction which
646: requires 16-byte aligned operands.
647:
648: You can also specify the alignment of structure fields. For
649: example, to create a double-word aligned `int' pair, you could
650: write:
651:
652: struct foo { int x[2] __attribute__ ((aligned (8))); };
653:
654: This is an alternative to creating a union with a `double' member
655: that forces the union to be double-word aligned.
656:
657: It is not possible to specify the alignment of functions; the
658: alignment of functions is determined by the machine's requirements
659: and cannot be changed. You cannot specify alignment for a typedef
660: name because such a name is just an alias, not a distinct type.
661:
662: The `aligned' attribute can only increase the alignment; but you
663: can decrease it by specifying `packed' as well. See below.
664:
665: The linker of your operating system imposes a maximum alignment.
666: If the linker aligns each object file on a four byte boundary,
667: then it is beyond the compiler's power to cause anything to be
668: aligned to a larger boundary than that. For example, if the
669: linker happens to put this object file at address 136 (eight more
670: than a multiple of 64), then the compiler cannot guarantee an
671: alignment of more than 8 just by aligning variables in the object
672: file.
673:
674: `mode (MODE)'
675: This attribute specifies the data type for the
676: declaration--whichever type corresponds to the mode MODE. This in
677: effect lets you request an integer or floating point type
678: according to its width.
679:
680: `packed'
681: The `packed' attribute specifies that a variable or structure field
682: should have the smallest possible alignment--one byte for a
683: variable, and one bit for a field, unless you specify a larger
684: value with the `aligned' attribute.
685:
686: To specify multiple attributes, separate them by commas within the
687: double parentheses: for example, `__attribute__ ((aligned (16),
688: packed))'.
689:
690:
691: File: gcc.info, Node: Inline, Next: Extended Asm, Prev: Alignment, Up: C Extensions
692:
693: An Inline Function is As Fast As a Macro
694: ========================================
695:
696: By declaring a function `inline', you can direct GNU CC to integrate
697: that function's code into the code for its callers. This makes
698: execution faster by eliminating the function-call overhead; in
699: addition, if any of the actual argument values are constant, their known
700: values may permit simplifications at compile time so that not all of the
701: inline function's code needs to be included. The effect on code size is
702: less predictable; object code may be larger or smaller with function
703: inlining, depending on the particular case. Inlining of functions is an
704: optimization and it really "works" only in optimizing compilation. If
705: you don't use `-O', no function is really inline.
706:
707: To declare a function inline, use the `inline' keyword in its
708: declaration, like this:
709:
710: inline int
711: inc (int *a)
712: {
713: (*a)++;
714: }
715:
716: (If you are writing a header file to be included in ANSI C programs,
717: write `__inline__' instead of `inline'. *Note Alternate Keywords::.)
718:
719: You can also make all "simple enough" functions inline with the
720: option `-finline-functions'. Note that certain usages in a function
721: definition can make it unsuitable for inline substitution.
722:
723: For C++ programs, GNU CC automatically inlines member functions even
724: if they are not explicitly declared `inline'. (You can override this
725: with `-fno-default-inline'; *note Options Controlling C++ Dialect: C++
726: Dialect Options..)
727:
728: When a function is both inline and `static', if all calls to the
729: function are integrated into the caller, and the function's address is
730: never used, then the function's own assembler code is never referenced.
731: In this case, GNU CC does not actually output assembler code for the
732: function, unless you specify the option `-fkeep-inline-functions'.
733: Some calls cannot be integrated for various reasons (in particular,
734: calls that precede the function's definition cannot be integrated, and
735: neither can recursive calls within the definition). If there is a
736: nonintegrated call, then the function is compiled to assembler code as
737: usual. The function must also be compiled as usual if the program
738: refers to its address, because that can't be inlined.
739:
740: When an inline function is not `static', then the compiler must
741: assume that there may be calls from other source files; since a global
742: symbol can be defined only once in any program, the function must not
743: be defined in the other source files, so the calls therein cannot be
744: integrated. Therefore, a non-`static' inline function is always
745: compiled on its own in the usual fashion.
746:
747: If you specify both `inline' and `extern' in the function
748: definition, then the definition is used only for inlining. In no case
749: is the function compiled on its own, not even if you refer to its
750: address explicitly. Such an address becomes an external reference, as
751: if you had only declared the function, and had not defined it.
752:
753: This combination of `inline' and `extern' has almost the effect of a
754: macro. The way to use it is to put a function definition in a header
755: file with these keywords, and put another copy of the definition
756: (lacking `inline' and `extern') in a library file. The definition in
757: the header file will cause most calls to the function to be inlined.
758: If any uses of the function remain, they will refer to the single copy
759: in the library.
760:
761: GNU C does not inline any functions when not optimizing. It is not
762: clear whether it is better to inline or not, in this case, but we found
763: that a correct implementation when not optimizing was difficult. So we
764: did the easy thing, and turned it off.
765:
766:
767: File: gcc.info, Node: Extended Asm, Next: Asm Labels, Prev: Inline, Up: C Extensions
768:
769: Assembler Instructions with C Expression Operands
770: =================================================
771:
772: In an assembler instruction using `asm', you can now specify the
773: operands of the instruction using C expressions. This means no more
774: guessing which registers or memory locations will contain the data you
775: want to use.
776:
777: You must specify an assembler instruction template much like what
778: appears in a machine description, plus an operand constraint string for
779: each operand.
780:
781: For example, here is how to use the 68881's `fsinx' instruction:
782:
783: asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
784:
785: Here `angle' is the C expression for the input operand while `result'
786: is that of the output operand. Each has `"f"' as its operand
787: constraint, saying that a floating point register is required. The `='
788: in `=f' indicates that the operand is an output; all output operands'
789: constraints must use `='. The constraints use the same language used
790: in the machine description (*note Constraints::.).
791:
792: Each operand is described by an operand-constraint string followed
793: by the C expression in parentheses. A colon separates the assembler
794: template from the first output operand, and another separates the last
795: output operand from the first input, if any. Commas separate output
796: operands and separate inputs. The total number of operands is limited
797: to ten or to the maximum number of operands in any instruction pattern
798: in the machine description, whichever is greater.
799:
800: If there are no output operands, and there are input operands, then
801: there must be two consecutive colons surrounding the place where the
802: output operands would go.
803:
804: Output operand expressions must be lvalues; the compiler can check
805: this. The input operands need not be lvalues. The compiler cannot
806: check whether the operands have data types that are reasonable for the
807: instruction being executed. It does not parse the assembler
808: instruction template and does not know what it means, or whether it is
809: valid assembler input. The extended `asm' feature is most often used
810: for machine instructions that the compiler itself does not know exist.
811:
812: The output operands must be write-only; GNU CC will assume that the
813: values in these operands before the instruction are dead and need not be
814: generated. Extended asm does not support input-output or read-write
815: operands. For this reason, the constraint character `+', which
816: indicates such an operand, may not be used.
817:
818: When the assembler instruction has a read-write operand, or an
819: operand in which only some of the bits are to be changed, you must
820: logically split its function into two separate operands, one input
821: operand and one write-only output operand. The connection between them
822: is expressed by constraints which say they need to be in the same
823: location when the instruction executes. You can use the same C
824: expression for both operands, or different expressions. For example,
825: here we write the (fictitious) `combine' instruction with `bar' as its
826: read-only source operand and `foo' as its read-write destination:
827:
828: asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
829:
830: The constraint `"0"' for operand 1 says that it must occupy the same
831: location as operand 0. A digit in constraint is allowed only in an
832: input operand, and it must refer to an output operand.
833:
834: Only a digit in the constraint can guarantee that one operand will
835: be in the same place as another. The mere fact that `foo' is the value
836: of both operands is not enough to guarantee that they will be in the
837: same place in the generated assembler code. The following would not
838: work:
839:
840: asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));
841:
842: Various optimizations or reloading could cause operands 0 and 1 to
843: be in different registers; GNU CC knows no reason not to do so. For
844: example, the compiler might find a copy of the value of `foo' in one
845: register and use it for operand 1, but generate the output operand 0 in
846: a different register (copying it afterward to `foo''s own address). Of
847: course, since the register for operand 1 is not even mentioned in the
848: assembler code, the result will not work, but GNU CC can't tell that.
849:
850: Some instructions clobber specific hard registers. To describe
851: this, write a third colon after the input operands, followed by the
852: names of the clobbered hard registers (given as strings). Here is a
853: realistic example for the Vax:
854:
855: asm volatile ("movc3 %0,%1,%2"
856: : /* no outputs */
857: : "g" (from), "g" (to), "g" (count)
858: : "r0", "r1", "r2", "r3", "r4", "r5");
859:
860: If you refer to a particular hardware register from the assembler
861: code, then you will probably have to list the register after the third
862: colon to tell the compiler that the register's value is modified. In
863: many assemblers, the register names begin with `%'; to produce one `%'
864: in the assembler code, you must write `%%' in the input.
865:
866: If your assembler instruction can alter the condition code register,
867: add `cc' to the list of clobbered registers. GNU CC on some machines
868: represents the condition codes as a specific hardware register; `cc'
869: serves to name this register. On other machines, the condition code is
870: handled differently, and specifying `cc' has no effect. But it is
871: valid no matter what the machine.
872:
873: If your assembler instruction modifies memory in an unpredictable
874: fashion, add `memory' to the list of clobbered registers. This will
875: cause GNU CC to not keep memory values cached in registers across the
876: assembler instruction.
877:
878: You can put multiple assembler instructions together in a single
879: `asm' template, separated either with newlines (written as `\n') or with
880: semicolons if the assembler allows such semicolons. The GNU assembler
881: allows semicolons and all Unix assemblers seem to do so. The input
882: operands are guaranteed not to use any of the clobbered registers, and
883: neither will the output operands' addresses, so you can read and write
884: the clobbered registers as many times as you like. Here is an example
885: of multiple instructions in a template; it assumes that the subroutine
886: `_foo' accepts arguments in registers 9 and 10:
887:
888: asm ("movl %0,r9;movl %1,r10;call _foo"
889: : /* no outputs */
890: : "g" (from), "g" (to)
891: : "r9", "r10");
892:
893: Unless an output operand has the `&' constraint modifier, GNU CC may
894: allocate it in the same register as an unrelated input operand, on the
895: assumption that the inputs are consumed before the outputs are produced.
896: This assumption may be false if the assembler code actually consists of
897: more than one instruction. In such a case, use `&' for each output
898: operand that may not overlap an input. *Note Modifiers::.
899:
900: If you want to test the condition code produced by an assembler
901: instruction, you must include a branch and a label in the `asm'
902: construct, as follows:
903:
904: asm ("clr %0;frob %1;beq 0f;mov #1,%0;0:"
905: : "g" (result)
906: : "g" (input));
907:
908: This assumes your assembler supports local labels, as the GNU assembler
909: and most Unix assemblers do.
910:
911: Speaking of labels, jumps from one `asm' to another are not
912: supported. The compiler's optimizers do not know about these jumps,
913: and therefore they cannot take account of them when deciding how to
914: optimize.
915:
916: Usually the most convenient way to use these `asm' instructions is to
917: encapsulate them in macros that look like functions. For example,
918:
919: #define sin(x) \
920: ({ double __value, __arg = (x); \
921: asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \
922: __value; })
923:
924: Here the variable `__arg' is used to make sure that the instruction
925: operates on a proper `double' value, and to accept only those arguments
926: `x' which can convert automatically to a `double'.
927:
928: Another way to make sure the instruction operates on the correct
929: data type is to use a cast in the `asm'. This is different from using a
930: variable `__arg' in that it converts more different types. For
931: example, if the desired type were `int', casting the argument to `int'
932: would accept a pointer with no complaint, while assigning the argument
933: to an `int' variable named `__arg' would warn about using a pointer
934: unless the caller explicitly casts it.
935:
936: If an `asm' has output operands, GNU CC assumes for optimization
937: purposes that the instruction has no side effects except to change the
938: output operands. This does not mean that instructions with a side
939: effect cannot be used, but you must be careful, because the compiler
940: may eliminate them if the output operands aren't used, or move them out
941: of loops, or replace two with one if they constitute a common
942: subexpression. Also, if your instruction does have a side effect on a
943: variable that otherwise appears not to change, the old value of the
944: variable may be reused later if it happens to be found in a register.
945:
946: You can prevent an `asm' instruction from being deleted, moved
947: significantly, or combined, by writing the keyword `volatile' after the
948: `asm'. For example:
949:
950: #define set_priority(x) \
951: asm volatile ("set_priority %0": /* no outputs */ : "g" (x))
952:
953: An instruction without output operands will not be deleted or moved
954: significantly, regardless, unless it is unreachable.
955:
956: Note that even a volatile `asm' instruction can be moved in ways
957: that appear insignificant to the compiler, such as across jump
958: instructions. You can't expect a sequence of volatile `asm'
959: instructions to remain perfectly consecutive. If you want consecutive
960: output, use a single `asm'.
961:
962: It is a natural idea to look for a way to give access to the
963: condition code left by the assembler instruction. However, when we
964: attempted to implement this, we found no way to make it work reliably.
965: The problem is that output operands might need reloading, which would
966: result in additional following "store" instructions. On most machines,
967: these instructions would alter the condition code before there was time
968: to test it. This problem doesn't arise for ordinary "test" and
969: "compare" instructions because they don't have any output operands.
970:
971: If you are writing a header file that should be includable in ANSI C
972: programs, write `__asm__' instead of `asm'. *Note Alternate Keywords::.
973:
974:
975: File: gcc.info, Node: Asm Labels, Next: Explicit Reg Vars, Prev: Extended Asm, Up: C Extensions
976:
977: Controlling Names Used in Assembler Code
978: ========================================
979:
980: You can specify the name to be used in the assembler code for a C
981: function or variable by writing the `asm' (or `__asm__') keyword after
982: the declarator as follows:
983:
984: int foo asm ("myfoo") = 2;
985:
986: This specifies that the name to be used for the variable `foo' in the
987: assembler code should be `myfoo' rather than the usual `_foo'.
988:
989: On systems where an underscore is normally prepended to the name of
990: a C function or variable, this feature allows you to define names for
991: the linker that do not start with an underscore.
992:
993: You cannot use `asm' in this way in a function *definition*; but you
994: can get the same effect by writing a declaration for the function
995: before its definition and putting `asm' there, like this:
996:
997: extern func () asm ("FUNC");
998:
999: func (x, y)
1000: int x, y;
1001: ...
1002:
1003: It is up to you to make sure that the assembler names you choose do
1004: not conflict with any other assembler symbols. Also, you must not use a
1005: register name; that would produce completely invalid assembler code.
1006: GNU CC does not as yet have the ability to store static variables in
1007: registers. Perhaps that will be added.
1008:
1009:
1010: File: gcc.info, Node: Explicit Reg Vars, Next: Alternate Keywords, Prev: Asm Labels, Up: C Extensions
1011:
1012: Variables in Specified Registers
1013: ================================
1014:
1015: GNU C allows you to put a few global variables into specified
1016: hardware registers. You can also specify the register in which an
1017: ordinary register variable should be allocated.
1018:
1019: * Global register variables reserve registers throughout the program.
1020: This may be useful in programs such as programming language
1021: interpreters which have a couple of global variables that are
1022: accessed very often.
1023:
1024: * Local register variables in specific registers do not reserve the
1025: registers. The compiler's data flow analysis is capable of
1026: determining where the specified registers contain live values, and
1027: where they are available for other uses.
1028:
1029: These local variables are sometimes convenient for use with the
1030: extended `asm' feature (*note Extended Asm::.), if you want to
1031: write one output of the assembler instruction directly into a
1032: particular register. (This will work provided the register you
1033: specify fits the constraints specified for that operand in the
1034: `asm'.)
1035:
1036: * Menu:
1037:
1038: * Global Reg Vars::
1039: * Local Reg Vars::
1040:
1041:
1042: File: gcc.info, Node: Global Reg Vars, Next: Local Reg Vars, Up: Explicit Reg Vars
1043:
1044: Defining Global Register Variables
1045: ----------------------------------
1046:
1047: You can define a global register variable in GNU C like this:
1048:
1049: register int *foo asm ("a5");
1050:
1051: Here `a5' is the name of the register which should be used. Choose a
1052: register which is normally saved and restored by function calls on your
1053: machine, so that library routines will not clobber it.
1054:
1055: Naturally the register name is cpu-dependent, so you would need to
1056: conditionalize your program according to cpu type. The register `a5'
1057: would be a good choice on a 68000 for a variable of pointer type. On
1058: machines with register windows, be sure to choose a "global" register
1059: that is not affected magically by the function call mechanism.
1060:
1061: In addition, operating systems on one type of cpu may differ in how
1062: they name the registers; then you would need additional conditionals.
1063: For example, some 68000 operating systems call this register `%a5'.
1064:
1065: Eventually there may be a way of asking the compiler to choose a
1066: register automatically, but first we need to figure out how it should
1067: choose and how to enable you to guide the choice. No solution is
1068: evident.
1069:
1070: Defining a global register variable in a certain register reserves
1071: that register entirely for this use, at least within the current
1072: compilation. The register will not be allocated for any other purpose
1073: in the functions in the current compilation. The register will not be
1074: saved and restored by these functions. Stores into this register are
1075: never deleted even if they would appear to be dead, but references may
1076: be deleted or moved or simplified.
1077:
1078: It is not safe to access the global register variables from signal
1079: handlers, or from more than one thread of control, because the system
1080: library routines may temporarily use the register for other things
1081: (unless you recompile them specially for the task at hand).
1082:
1083: It is not safe for one function that uses a global register variable
1084: to call another such function `foo' by way of a third function `lose'
1085: that was compiled without knowledge of this variable (i.e. in a
1086: different source file in which the variable wasn't declared). This is
1087: because `lose' might save the register and put some other value there.
1088: For example, you can't expect a global register variable to be
1089: available in the comparison-function that you pass to `qsort', since
1090: `qsort' might have put something else in that register. (If you are
1091: prepared to recompile `qsort' with the same global register variable,
1092: you can solve this problem.)
1093:
1094: If you want to recompile `qsort' or other source files which do not
1095: actually use your global register variable, so that they will not use
1096: that register for any other purpose, then it suffices to specify the
1097: compiler option `-ffixed-REG'. You need not actually add a global
1098: register declaration to their source code.
1099:
1100: A function which can alter the value of a global register variable
1101: cannot safely be called from a function compiled without this variable,
1102: because it could clobber the value the caller expects to find there on
1103: return. Therefore, the function which is the entry point into the part
1104: of the program that uses the global register variable must explicitly
1105: save and restore the value which belongs to its caller.
1106:
1107: On most machines, `longjmp' will restore to each global register
1108: variable the value it had at the time of the `setjmp'. On some
1109: machines, however, `longjmp' will not change the value of global
1110: register variables. To be portable, the function that called `setjmp'
1111: should make other arrangements to save the values of the global register
1112: variables, and to restore them in a `longjmp'. This way, the same
1113: thing will happen regardless of what `longjmp' does.
1114:
1115: All global register variable declarations must precede all function
1116: definitions. If such a declaration could appear after function
1117: definitions, the declaration would be too late to prevent the register
1118: from being used for other purposes in the preceding functions.
1119:
1120: Global register variables may not have initial values, because an
1121: executable file has no means to supply initial contents for a register.
1122:
1123: On the Sparc, there are reports that g3 ... g7 are suitable
1124: registers, but certain library functions, such as `getwd', as well as
1125: the subroutines for division and remainder, modify g3 and g4. g1 and
1126: g2 are local temporaries.
1127:
1128: On the 68000, a2 ... a5 should be suitable, as should d2 ... d7. Of
1129: course, it will not do to use more than a few of those.
1130:
1131:
1132: File: gcc.info, Node: Local Reg Vars, Prev: Global Reg Vars, Up: Explicit Reg Vars
1133:
1134: Specifying Registers for Local Variables
1135: ----------------------------------------
1136:
1137: You can define a local register variable with a specified register
1138: like this:
1139:
1140: register int *foo asm ("a5");
1141:
1142: Here `a5' is the name of the register which should be used. Note that
1143: this is the same syntax used for defining global register variables,
1144: but for a local variable it would appear within a function.
1145:
1146: Naturally the register name is cpu-dependent, but this is not a
1147: problem, since specific registers are most often useful with explicit
1148: assembler instructions (*note Extended Asm::.). Both of these things
1149: generally require that you conditionalize your program according to cpu
1150: type.
1151:
1152: In addition, operating systems on one type of cpu may differ in how
1153: they name the registers; then you would need additional conditionals.
1154: For example, some 68000 operating systems call this register `%a5'.
1155:
1156: Eventually there may be a way of asking the compiler to choose a
1157: register automatically, but first we need to figure out how it should
1158: choose and how to enable you to guide the choice. No solution is
1159: evident.
1160:
1161: Defining such a register variable does not reserve the register; it
1162: remains available for other uses in places where flow control determines
1163: the variable's value is not live. However, these registers are made
1164: unavailable for use in the reload pass. I would not be surprised if
1165: excessive use of this feature leaves the compiler too few available
1166: registers to compile certain functions.
1167:
1168:
1169: File: gcc.info, Node: Alternate Keywords, Next: Incomplete Enums, Prev: Explicit Reg Vars, Up: C Extensions
1170:
1171: Alternate Keywords
1172: ==================
1173:
1174: The option `-traditional' disables certain keywords; `-ansi'
1175: disables certain others. This causes trouble when you want to use GNU C
1176: extensions, or ANSI C features, in a general-purpose header file that
1177: should be usable by all programs, including ANSI C programs and
1178: traditional ones. The keywords `asm', `typeof' and `inline' cannot be
1179: used since they won't work in a program compiled with `-ansi', while
1180: the keywords `const', `volatile', `signed', `typeof' and `inline' won't
1181: work in a program compiled with `-traditional'.
1182:
1183: The way to solve these problems is to put `__' at the beginning and
1184: end of each problematical keyword. For example, use `__asm__' instead
1185: of `asm', `__const__' instead of `const', and `__inline__' instead of
1186: `inline'.
1187:
1188: Other C compilers won't accept these alternative keywords; if you
1189: want to compile with another compiler, you can define the alternate
1190: keywords as macros to replace them with the customary keywords. It
1191: looks like this:
1192:
1193: #ifndef __GNUC__
1194: #define __asm__ asm
1195: #endif
1196:
1197: `-pedantic' causes warnings for many GNU C extensions. You can
1198: prevent such warnings within one expression by writing `__extension__'
1199: before the expression. `__extension__' has no effect aside from this.
1200:
1201:
1202: File: gcc.info, Node: Incomplete Enums, Next: Function Names, Prev: Alternate Keywords, Up: C Extensions
1203:
1204: Incomplete `enum' Types
1205: =======================
1206:
1207: You can define an `enum' tag without specifying its possible values.
1208: This results in an incomplete type, much like what you get if you write
1209: `struct foo' without describing the elements. A later declaration
1210: which does specify the possible values completes the type.
1211:
1212: You can't allocate variables or storage using the type while it is
1213: incomplete. However, you can work with pointers to that type.
1214:
1215: This extension may not be very useful, but it makes the handling of
1216: `enum' more consistent with the way `struct' and `union' are handled.
1217:
1218:
1219: File: gcc.info, Node: Function Names, Prev: Incomplete Enums, Up: C Extensions
1220:
1221: Function Names as Strings
1222: =========================
1223:
1224: GNU CC predefines two string variables to be the name of the current
1225: function. The variable `__FUNCTION__' is the name of the function as
1226: it appears in the source. The variable `__PRETTY_FUNCTION__' is the
1227: name of the function pretty printed in a language specific fashion.
1228:
1229: These names are always the same in a C function, but in a C++
1230: function they may be different. For example, this program:
1231:
1232: extern "C" {
1233: extern int printf (char *, ...);
1234: }
1235:
1236: class a {
1237: public:
1238: sub (int i)
1239: {
1240: printf ("__FUNCTION__ = %s\n", __FUNCTION__);
1241: printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__);
1242: }
1243: };
1244:
1245: int
1246: main (void)
1247: {
1248: a ax;
1249: ax.sub (0);
1250: return 0;
1251: }
1252:
1253: gives this output:
1254:
1255: __FUNCTION__ = sub
1256: __PRETTY_FUNCTION__ = int a::sub (int)
1257:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.