![[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 root 1: @c Copyright (C) 1988, 1989, 1992 Free Software Foundation, Inc.
2: @c This is part of the GCC manual.
3: @c For copying conditions, see the file gcc.texi.
4:
1.1.1.3 root 5: @node Extensions
1.1 root 6: @chapter GNU Extensions to the C Language
7: @cindex extensions, C language
8: @cindex GNU extensions to the C language
9: @cindex C language extensions
10:
11: GNU C provides several language features not found in ANSI standard C.
12: (The @samp{-pedantic} option directs GNU CC to print a warning message if
13: any of these features is used.) To test for the availability of these
14: features in conditional compilation, check for a predefined macro
15: @code{__GNUC__}, which is always defined under GNU CC.
16:
17: @menu
18: * Statement Exprs:: Putting statements and declarations inside expressions.
19: * Local Labels:: Labels local to a statement-expression.
20: * Labels as Values:: Getting pointers to labels, and computed gotos.
21: * Nested Functions:: As in Algol and Pascal, lexical scoping of functions.
22: * Naming Types:: Giving a name to the type of some expression.
23: * Typeof:: @code{typeof}: referring to the type of an expression.
24: * Lvalues:: Using @samp{?:}, @samp{,} and casts in lvalues.
25: * Conditionals:: Omitting the middle operand of a @samp{?:} expression.
26: * Long Long:: Double-word integers---@code{long long int}.
27: * Zero Length:: Zero-length arrays.
28: * Variable Length:: Arrays whose length is computed at run time.
1.1.1.3 root 29: * Macro Varargs:: Macros with variable number of arguments.
1.1 root 30: * Subscripting:: Any array can be subscripted, even if not an lvalue.
31: * Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers.
32: * Initializers:: Non-constant initializers.
33: * Constructors:: Constructor expressions give structures, unions
34: or arrays as values.
35: * Labeled Elements:: Labeling elements of initializers.
36: * Cast to Union:: Casting to union type from any member of the union.
37: * Case Ranges:: `case 1 ... 9' and such.
38: * Function Attributes:: Declaring that functions have no side effects,
39: or that they can never return.
1.1.1.3 root 40: * Function Prototypes:: Prototype declarations and old-style definitions.
1.1 root 41: * Dollar Signs:: Dollar sign is allowed in identifiers.
42: * Character Escapes:: @samp{\e} stands for the character @key{ESC}.
43: * Variable Attributes:: Specifying attributes of variables.
44: * Alignment:: Inquiring about the alignment of a type or variable.
45: * Inline:: Defining inline functions (as fast as macros).
46: * Extended Asm:: Assembler instructions with C expressions as operands.
47: (With them you can define ``built-in'' functions.)
48: * Asm Labels:: Specifying the assembler name to use for a C symbol.
49: * Explicit Reg Vars:: Defining variables residing in specified registers.
50: * Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files.
51: * Incomplete Enums:: @code{enum foo;}, with details to follow.
52: @end menu
53:
54: @node Statement Exprs
55: @section Statements and Declarations within Expressions
56: @cindex statements inside expressions
57: @cindex declarations inside expressions
58: @cindex expressions containing statements
59: @cindex macros, statements in expressions
60:
1.1.1.3 root 61: A compound statement enclosed in parentheses may appear as an expression
62: in GNU C. This allows you to use loops, switches, and local variables
63: within an expression.
64:
65: Recall that a compound statement is a sequence of statements surrounded
66: by braces; in this construct, parentheses go around the braces. For
1.1 root 67: example:
68:
69: @example
70: (@{ int y = foo (); int z;
71: if (y > 0) z = y;
72: else z = - y;
73: z; @})
74: @end example
75:
76: @noindent
77: is a valid (though slightly more complex than necessary) expression
78: for the absolute value of @code{foo ()}.
79:
1.1.1.3 root 80: The last thing in the compound statement should be an expression
81: followed by a semicolon; the value of this subexpression serves as the
82: value of the entire construct. (If you use some other kind of statement
83: last within the braces, the construct has type @code{void}, and thus
84: effectively no value.)
85:
1.1 root 86: This feature is especially useful in making macro definitions ``safe'' (so
87: that they evaluate each operand exactly once). For example, the
88: ``maximum'' function is commonly defined as a macro in standard C as
89: follows:
90:
91: @example
92: #define max(a,b) ((a) > (b) ? (a) : (b))
93: @end example
94:
95: @noindent
96: @cindex side effects, macro argument
97: But this definition computes either @var{a} or @var{b} twice, with bad
98: results if the operand has side effects. In GNU C, if you know the
99: type of the operands (here let's assume @code{int}), you can define
100: the macro safely as follows:
101:
102: @example
103: #define maxint(a,b) \
104: (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @})
105: @end example
106:
107: Embedded statements are not allowed in constant expressions, such as
108: the value of an enumeration constant, the width of a bit field, or
109: the initial value of a static variable.
110:
111: If you don't know the type of the operand, you can still do this, but you
112: must use @code{typeof} (@pxref{Typeof}) or type naming (@pxref{Naming
113: Types}).
114:
115: @node Local Labels
116: @section Locally Declared Labels
117: @cindex local labels
118: @cindex macros, local labels
119:
120: Each statement expression is a scope in which @dfn{local labels} can be
121: declared. A local label is simply an identifier; you can jump to it
122: with an ordinary @code{goto} statement, but only from within the
123: statement expression it belongs to.
124:
125: A local label declaration looks like this:
126:
127: @example
128: __label__ @var{label};
129: @end example
130:
131: @noindent
132: or
133:
134: @example
135: __label__ @var{label1}, @var{label2}, @dots{};
136: @end example
137:
138: Local label declarations must come at the beginning of the statement
139: expression, right after the @samp{(@{}, before any ordinary
140: declarations.
141:
142: The label declaration defines the label @emph{name}, but does not define
143: the label itself. You must do this in the usual way, with
144: @code{@var{label}:}, within the statements of the statement expression.
145:
146: The local label feature is useful because statement expressions are
147: often used in macros. If the macro contains nested loops, a @code{goto}
148: can be useful for breaking out of them. However, an ordinary label
149: whose scope is the whole function cannot be used: if the macro can be
150: expanded several times in one function, the label will be multiply
151: defined in that function. A local label avoids this problem. For
152: example:
153:
154: @example
155: #define SEARCH(array, target) \
156: (@{ \
157: __label__ found; \
158: typeof (target) _SEARCH_target = (target); \
159: typeof (*(array)) *_SEARCH_array = (array); \
160: int i, j; \
161: int value; \
162: for (i = 0; i < max; i++) \
163: for (j = 0; j < max; j++) \
164: if (_SEARCH_array[i][j] == _SEARCH_target) \
165: @{ value = i; goto found; @} \
166: value = -1; \
167: found: \
168: value; \
169: @})
170: @end example
171:
172: @node Labels as Values
173: @section Labels as Values
174: @cindex labels as values
175: @cindex computed gotos
176: @cindex goto with computed label
177: @cindex address of a label
178:
179: You can get the address of a label defined in the current function
180: (or a containing function) with the unary operator @samp{&&}. The
181: value has type @code{void *}. This value is a constant and can be used
182: wherever a constant of that type is valid. For example:
183:
184: @example
185: void *ptr;
186: @dots{}
187: ptr = &&foo;
188: @end example
189:
190: To use these values, you need to be able to jump to one. This is done
191: with the computed goto statement@footnote{The analogous feature in
192: Fortran is called an assigned goto, but that name seems inappropriate in
193: C, where one can do more than simply store label addresses in label
194: variables.}, @code{goto *@var{exp};}. For example,
195:
196: @example
197: goto *ptr;
198: @end example
199:
200: @noindent
201: Any expression of type @code{void *} is allowed.
202:
203: One way of using these constants is in initializing a static array that
204: will serve as a jump table:
205:
206: @example
207: static void *array[] = @{ &&foo, &&bar, &&hack @};
208: @end example
209:
210: Then you can select a label with indexing, like this:
211:
212: @example
213: goto *array[i];
214: @end example
215:
216: @noindent
217: Note that this does not check whether the subscript is in bounds---array
218: indexing in C never does that.
219:
220: Such an array of label values serves a purpose much like that of the
221: @code{switch} statement. The @code{switch} statement is cleaner, so
222: use that rather than an array unless the problem does not fit a
223: @code{switch} statement very well.
224:
225: Another use of label values is in an interpreter for threaded code.
226: The labels within the interpreter function can be stored in the
227: threaded code for super-fast dispatching.
228:
1.1.1.3 root 229: You can use this mechanism to jump to code in a different function. If
230: you do that, totally unpredictable things will happen. The best way to
231: avoid this is to store the label address only in automatic variables and
232: never pass it as an argument.
233:
1.1 root 234: @node Nested Functions
235: @section Nested Functions
236: @cindex nested functions
237: @cindex downward funargs
238: @cindex thunks
239:
240: A @dfn{nested function} is a function defined inside another function.
241: The nested function's name is local to the block where it is defined.
242: For example, here we define a nested function named @code{square},
243: and call it twice:
244:
245: @example
246: foo (double a, double b)
247: @{
248: double square (double z) @{ return z * z; @}
249:
250: return square (a) + square (b);
251: @}
252: @end example
253:
254: The nested function can access all the variables of the containing
255: function that are visible at the point of its definition. This is
256: called @dfn{lexical scoping}. For example, here we show a nested
257: function which uses an inherited variable named @code{offset}:
258:
259: @example
260: bar (int *array, int offset, int size)
261: @{
262: int access (int *array, int index)
263: @{ return array[index + offset]; @}
264: int i;
265: @dots{}
266: for (i = 0; i < size; i++)
267: @dots{} access (array, i) @dots{}
268: @}
269: @end example
270:
271: It is possible to call the nested function from outside the scope of its
272: name by storing its address or passing the address to another function:
273:
274: @example
275: hack (int *array, int size)
276: @{
277: void store (int index, int value)
278: @{ array[index] = value; @}
279:
280: intermediate (store, size);
281: @}
282: @end example
283:
284: Here, the function @code{intermediate} receives the address of
285: @code{store} as an argument. If @code{intermediate} calls
286: @code{store}, the arguments given to @code{store} are used to store
287: into @code{array}. But this technique works only so long as the
288: containing function (@code{hack}, in this example) does not exit. If
289: you try to call the nested function through its address after the
290: containing function has exited, all hell will break loose.
291:
1.1.1.4 ! root 292: GNU CC implements taking the address of a nested function using a
! 293: technique called @dfn{trampolines}. A paper describing them is
! 294: available from @samp{maya.idiap.ch} in the file
! 295: @file{pub/tmb/usenix88-lexic.ps.Z}.
! 296:
1.1 root 297: A nested function can jump to a label inherited from a containing
298: function, provided the label was explicitly declared in the containing
299: function (@pxref{Local Labels}). Such a jump returns instantly to the
300: containing function, exiting the nested function which did the
301: @code{goto} and any intermediate functions as well. Here is an example:
302:
303: @example
304: bar (int *array, int offset, int size)
305: @{
306: __label__ failure;
307: int access (int *array, int index)
308: @{
309: if (index > size)
310: goto failure;
311: return array[index + offset];
312: @}
313: int i;
314: @dots{}
315: for (i = 0; i < size; i++)
316: @dots{} access (array, i) @dots{}
317: @dots{}
318: return 0;
319:
320: /* @r{Control comes here from @code{access}
321: if it detects an error.} */
322: failure:
323: return -1;
324: @}
325: @end example
326:
327: A nested function always has internal linkage. Declaring one with
328: @code{extern} is erroneous. If you need to declare the nested function
329: before its definition, use @code{auto} (which is otherwise meaningless
330: for function declarations).
331:
332: @example
333: bar (int *array, int offset, int size)
334: @{
335: __label__ failure;
336: auto int access (int *, int);
337: @dots{}
338: int access (int *array, int index)
339: @{
340: if (index > size)
341: goto failure;
342: return array[index + offset];
343: @}
344: @dots{}
345: @}
346: @end example
347:
348: @node Naming Types
349: @section Naming an Expression's Type
350: @cindex naming types
351:
352: You can give a name to the type of an expression using a @code{typedef}
353: declaration with an initializer. Here is how to define @var{name} as a
354: type name for the type of @var{exp}:
355:
356: @example
357: typedef @var{name} = @var{exp};
358: @end example
359:
360: This is useful in conjunction with the statements-within-expressions
361: feature. Here is how the two together can be used to define a safe
362: ``maximum'' macro that operates on any arithmetic type:
363:
364: @example
365: #define max(a,b) \
366: (@{typedef _ta = (a), _tb = (b); \
367: _ta _a = (a); _tb _b = (b); \
368: _a > _b ? _a : _b; @})
369: @end example
370:
371: @cindex underscores in variables in macros
372: @cindex @samp{_} in variables in macros
373: @cindex local variables in macros
374: @cindex variables, local, in macros
375: @cindex macros, local variables in
376:
377: The reason for using names that start with underscores for the local
378: variables is to avoid conflicts with variable names that occur within the
379: expressions that are substituted for @code{a} and @code{b}. Eventually we
380: hope to design a new form of declaration syntax that allows you to declare
381: variables whose scopes start only after their initializers; this will be a
382: more reliable way to prevent such conflicts.
383:
384: @node Typeof
385: @section Referring to a Type with @code{typeof}
386: @findex typeof
387: @findex sizeof
388: @cindex macros, types of arguments
389:
390: Another way to refer to the type of an expression is with @code{typeof}.
391: The syntax of using of this keyword looks like @code{sizeof}, but the
392: construct acts semantically like a type name defined with @code{typedef}.
393:
394: There are two ways of writing the argument to @code{typeof}: with an
395: expression or with a type. Here is an example with an expression:
396:
397: @example
398: typeof (x[0](1))
399: @end example
400:
401: @noindent
402: This assumes that @code{x} is an array of functions; the type described
403: is that of the values of the functions.
404:
405: Here is an example with a typename as the argument:
406:
407: @example
408: typeof (int *)
409: @end example
410:
411: @noindent
412: Here the type described is that of pointers to @code{int}.
413:
414: If you are writing a header file that must work when included in ANSI C
415: programs, write @code{__typeof__} instead of @code{typeof}.
416: @xref{Alternate Keywords}.
417:
418: A @code{typeof}-construct can be used anywhere a typedef name could be
419: used. For example, you can use it in a declaration, in a cast, or inside
420: of @code{sizeof} or @code{typeof}.
421:
422: @itemize @bullet
423: @item
424: This declares @code{y} with the type of what @code{x} points to.
425:
426: @example
427: typeof (*x) y;
428: @end example
429:
430: @item
431: This declares @code{y} as an array of such values.
432:
433: @example
434: typeof (*x) y[4];
435: @end example
436:
437: @item
438: This declares @code{y} as an array of pointers to characters:
439:
440: @example
441: typeof (typeof (char *)[4]) y;
442: @end example
443:
444: @noindent
445: It is equivalent to the following traditional C declaration:
446:
447: @example
448: char *y[4];
449: @end example
450:
451: To see the meaning of the declaration using @code{typeof}, and why it
452: might be a useful way to write, let's rewrite it with these macros:
453:
454: @example
455: #define pointer(T) typeof(T *)
456: #define array(T, N) typeof(T [N])
457: @end example
458:
459: @noindent
460: Now the declaration can be rewritten this way:
461:
462: @example
463: array (pointer (char), 4) y;
464: @end example
465:
466: @noindent
467: Thus, @code{array (pointer (char), 4)} is the type of arrays of 4
468: pointers to @code{char}.
469: @end itemize
470:
471: @node Lvalues
472: @section Generalized Lvalues
473: @cindex compound expressions as lvalues
474: @cindex expressions, compound, as lvalues
475: @cindex conditional expressions as lvalues
476: @cindex expressions, conditional, as lvalues
477: @cindex casts as lvalues
478: @cindex generalized lvalues
479: @cindex lvalues, generalized
480: @cindex extensions, @code{?:}
481: @cindex @code{?:} extensions
482: Compound expressions, conditional expressions and casts are allowed as
483: lvalues provided their operands are lvalues. This means that you can take
484: their addresses or store values into them.
485:
486: For example, a compound expression can be assigned, provided the last
487: expression in the sequence is an lvalue. These two expressions are
488: equivalent:
489:
490: @example
491: (a, b) += 5
492: a, (b += 5)
493: @end example
494:
495: Similarly, the address of the compound expression can be taken. These two
496: expressions are equivalent:
497:
498: @example
499: &(a, b)
500: a, &b
501: @end example
502:
503: A conditional expression is a valid lvalue if its type is not void and the
504: true and false branches are both valid lvalues. For example, these two
505: expressions are equivalent:
506:
507: @example
508: (a ? b : c) = 5
509: (a ? b = 5 : (c = 5))
510: @end example
511:
512: A cast is a valid lvalue if its operand is an lvalue. A simple
513: assignment whose left-hand side is a cast works by converting the
514: right-hand side first to the specified type, then to the type of the
515: inner left-hand side expression. After this is stored, the value is
516: converted back to the specified type to become the value of the
517: assignment. Thus, if @code{a} has type @code{char *}, the following two
518: expressions are equivalent:
519:
520: @example
521: (int)a = 5
522: (int)(a = (char *)(int)5)
523: @end example
524:
525: An assignment-with-arithmetic operation such as @samp{+=} applied to a cast
526: performs the arithmetic using the type resulting from the cast, and then
527: continues as in the previous case. Therefore, these two expressions are
528: equivalent:
529:
530: @example
531: (int)a += 5
532: (int)(a = (char *)(int) ((int)a + 5))
533: @end example
534:
535: You cannot take the address of an lvalue cast, because the use of its
536: address would not work out coherently. Suppose that @code{&(int)f} were
537: permitted, where @code{f} has type @code{float}. Then the following
538: statement would try to store an integer bit-pattern where a floating
539: point number belongs:
540:
541: @example
542: *&(int)f = 1;
543: @end example
544:
545: This is quite different from what @code{(int)f = 1} would do---that
546: would convert 1 to floating point and store it. Rather than cause this
1.1.1.2 root 547: inconsistency, we think it is better to prohibit use of @samp{&} on a cast.
1.1 root 548:
549: If you really do want an @code{int *} pointer with the address of
550: @code{f}, you can simply write @code{(int *)&f}.
551:
552: @node Conditionals
553: @section Conditional Expressions with Omitted Operands
554: @cindex conditional expressions, extensions
555: @cindex omitted middle-operands
556: @cindex middle-operands, omitted
557: @cindex extensions, @code{?:}
558: @cindex @code{?:} extensions
559:
560: The middle operand in a conditional expression may be omitted. Then
561: if the first operand is nonzero, its value is the value of the conditional
562: expression.
563:
564: Therefore, the expression
565:
566: @example
567: x ? : y
568: @end example
569:
570: @noindent
571: has the value of @code{x} if that is nonzero; otherwise, the value of
572: @code{y}.
573:
574: This example is perfectly equivalent to
575:
576: @example
577: x ? x : y
578: @end example
579:
580: @cindex side effect in ?:
581: @cindex ?: side effect
582: @noindent
583: In this simple case, the ability to omit the middle operand is not
584: especially useful. When it becomes useful is when the first operand does,
585: or may (if it is a macro argument), contain a side effect. Then repeating
586: the operand in the middle would perform the side effect twice. Omitting
587: the middle operand uses the value already computed without the undesirable
588: effects of recomputing it.
589:
590: @node Long Long
591: @section Double-Word Integers
592: @cindex @code{long long} data types
593: @cindex double-word arithmetic
594: @cindex multiprecision arithmetic
595:
596: GNU C supports data types for integers that are twice as long as
597: @code{long int}. Simply write @code{long long int} for a signed
598: integer, or @code{unsigned long long int} for an unsigned integer.
599:
600: You can use these types in arithmetic like any other integer types.
601: Addition, subtraction, and bitwise boolean operations on these types
602: are open-coded on all types of machines. Multiplication is open-coded
603: if the machine supports fullword-to-doubleword a widening multiply
604: instruction. Division and shifts are open-coded only on machines that
605: provide special support. The operations that are not open-coded use
606: special library routines that come with GNU CC.
607:
608: There may be pitfalls when you use @code{long long} types for function
609: arguments, unless you declare function prototypes. If a function
610: expects type @code{int} for its argument, and you pass a value of type
611: @code{long long int}, confusion will result because the caller and the
612: subroutine will disagree about the number of bytes for the argument.
613: Likewise, if the function expects @code{long long int} and you pass
614: @code{int}. The best way to avoid such problems is to use prototypes.
615:
616: @node Zero Length
617: @section Arrays of Length Zero
618: @cindex arrays of length zero
619: @cindex zero-length arrays
620: @cindex length-zero arrays
621:
622: Zero-length arrays are allowed in GNU C. They are very useful as the last
623: element of a structure which is really a header for a variable-length
624: object:
625:
626: @example
627: struct line @{
628: int length;
629: char contents[0];
630: @};
631:
632: @{
633: struct line *thisline = (struct line *)
634: malloc (sizeof (struct line) + this_length);
635: thisline->length = this_length;
636: @}
637: @end example
638:
639: In standard C, you would have to give @code{contents} a length of 1, which
640: means either you waste space or complicate the argument to @code{malloc}.
641:
642: @node Variable Length
643: @section Arrays of Variable Length
644: @cindex variable-length arrays
645: @cindex arrays of variable length
646:
647: Variable-length automatic arrays are allowed in GNU C. These arrays are
648: declared like any other automatic arrays, but with a length that is not
649: a constant expression. The storage is allocated at the point of
650: declaration and deallocated when the brace-level is exited. For
651: example:
652:
653: @example
654: FILE *
655: concat_fopen (char *s1, char *s2, char *mode)
656: @{
657: char str[strlen (s1) + strlen (s2) + 1];
658: strcpy (str, s1);
659: strcat (str, s2);
660: return fopen (str, mode);
661: @}
662: @end example
663:
664: @cindex scope of a variable length array
665: @cindex variable-length array scope
666: @cindex deallocating variable length arrays
667: Jumping or breaking out of the scope of the array name deallocates the
668: storage. Jumping into the scope is not allowed; you get an error
669: message for it.
670:
671: @cindex @code{alloca} vs variable-length arrays
672: You can use the function @code{alloca} to get an effect much like
673: variable-length arrays. The function @code{alloca} is available in
674: many other C implementations (but not in all). On the other hand,
675: variable-length arrays are more elegant.
676:
677: There are other differences between these two methods. Space allocated
678: with @code{alloca} exists until the containing @emph{function} returns.
679: The space for a variable-length array is deallocated as soon as the array
680: name's scope ends. (If you use both variable-length arrays and
681: @code{alloca} in the same function, deallocation of a variable-length array
682: will also deallocate anything more recently allocated with @code{alloca}.)
683:
684: You can also use variable-length arrays as arguments to functions:
685:
686: @example
687: struct entry
688: tester (int len, char data[len][len])
689: @{
690: @dots{}
691: @}
692: @end example
693:
694: The length of an array is computed once when the storage is allocated
695: and is remembered for the scope of the array in case you access it with
696: @code{sizeof}.
697:
698: If you want to pass the array first and the length afterward, you can
699: use a forward declaration in the parameter list---another GNU extension.
700:
701: @example
702: struct entry
703: tester (int len; char data[len][len], int len)
704: @{
705: @dots{}
706: @}
707: @end example
708:
709: @cindex parameter forward declaration
710: The @samp{int len} before the semicolon is a @dfn{parameter forward
711: declaration}, and it serves the purpose of making the name @code{len}
712: known when the declaration of @code{data} is parsed.
713:
714: You can write any number of such parameter forward declarations in the
715: parameter list. They can be separated by commas or semicolons, but the
716: last one must end with a semicolon, which is followed by the ``real''
717: parameter declarations. Each forward declaration must match a ``real''
718: declaration in parameter name and data type.
719:
1.1.1.3 root 720: @node Macro Varargs
721: @section Macros with Variable Numbers of Arguments
722: @cindex variable number of arguments
723: @cindex macro with variable arguments
724: @cindex rest argument (in macro)
725:
726: In GNU C, a macro can accept a variable number of arguments, much as a
727: function can. The syntax for defining the macro looks much like that
728: used for a function. Here is an example:
729:
730: @example
731: #define eprintf(format, args...) \
732: fprintf (stderr, format, ## args)
733: @end example
734:
735: Here @code{args} is a @dfn{rest argument}: it takes in zero or more
736: arguments, as many as the call contains. All of them plus the commas
737: between them form the value of @code{args}, which is substituted into
738: the macro body where @code{args} is used. Thus, we have these
739: expansions:
740:
741: @example
742: eprintf ("%s:%d: ", input_file_name, line_number)
743: @expansion{}
744: fprintf (stderr, "%s:%d: ", input_file_name, line_number)
745: @end example
746:
747: @noindent
748: Note that the comma after the string constant comes from the definition
749: of @code{eprintf}, whereas the last comma comes from the value of
750: @code{args}.
751:
752: The reason for using @samp{##} is to handle the case when @code{args}
753: matches no arguments at all. In this case, @code{args} has an empty
754: value. In this case, the second comma in the definition becomes an
755: embarrassment: if it got through to the expansion of the macro, we would
756: get something like this:
757:
758: @example
759: fprintf (stderr, "success!\n", )
760: @end example
761:
762: @noindent
763: which is invalid C syntax. @samp{##} gets rid of the comma, so we get
764: the following instead:
765:
766: @example
767: fprintf (stderr, "success!\n")
768: @end example
769:
770: This is a special feature of the GNU C preprocessor: @samp{##} adjacent
771: to a rest argument discards the token on the other side of the
772: @samp{##}, if the rest argument value is empty.
773:
1.1 root 774: @node Subscripting
775: @section Non-Lvalue Arrays May Have Subscripts
776: @cindex subscripting
777: @cindex arrays, non-lvalue
778:
779: @cindex subscripting and function values
780: Subscripting is allowed on arrays that are not lvalues, even though the
781: unary @samp{&} operator is not. For example, this is valid in GNU C though
782: not valid in other C dialects:
783:
784: @example
785: struct foo @{int a[4];@};
786:
787: struct foo f();
788:
789: bar (int index)
790: @{
791: return f().a[index];
792: @}
793: @end example
794:
795: @node Pointer Arith
796: @section Arithmetic on @code{void}- and Function-Pointers
797: @cindex void pointers, arithmetic
798: @cindex void, size of pointer to
799: @cindex function pointers, arithmetic
800: @cindex function, size of pointer to
801:
802: In GNU C, addition and subtraction operations are supported on pointers to
803: @code{void} and on pointers to functions. This is done by treating the
804: size of a @code{void} or of a function as 1.
805:
806: A consequence of this is that @code{sizeof} is also allowed on @code{void}
807: and on function types, and returns 1.
808:
809: The option @samp{-Wpointer-arith} requests a warning if these extensions
810: are used.
811:
812: @node Initializers
813: @section Non-Constant Initializers
814: @cindex initializers, non-constant
815: @cindex non-constant initializers
816:
817: The elements of an aggregate initializer for an automatic variable are
818: not required to be constant expressions in GNU C. Here is an example of
819: an initializer with run-time varying elements:
820:
821: @example
822: foo (float f, float g)
823: @{
824: float beat_freqs[2] = @{ f-g, f+g @};
825: @dots{}
826: @}
827: @end example
828:
829: @node Constructors
830: @section Constructor Expressions
831: @cindex constructor expressions
832: @cindex initializations in expressions
833: @cindex structures, constructor expression
834: @cindex expressions, constructor
835:
836: GNU C supports constructor expressions. A constructor looks like
837: a cast containing an initializer. Its value is an object of the
838: type specified in the cast, containing the elements specified in
839: the initializer.
840:
841: Usually, the specified type is a structure. Assume that
842: @code{struct foo} and @code{structure} are declared as shown:
843:
844: @example
845: struct foo @{int a; char b[2];@} structure;
846: @end example
847:
848: @noindent
849: Here is an example of constructing a @code{struct foo} with a constructor:
850:
851: @example
852: structure = ((struct foo) @{x + y, 'a', 0@});
853: @end example
854:
855: @noindent
856: This is equivalent to writing the following:
857:
858: @example
859: @{
860: struct foo temp = @{x + y, 'a', 0@};
861: structure = temp;
862: @}
863: @end example
864:
865: You can also construct an array. If all the elements of the constructor
866: are (made up of) simple constant expressions, suitable for use in
867: initializers, then the constructor is an lvalue and can be coerced to a
868: pointer to its first element, as shown here:
869:
870: @example
871: char **foo = (char *[]) @{ "x", "y", "z" @};
872: @end example
873:
874: Array constructors whose elements are not simple constants are
875: not very useful, because the constructor is not an lvalue. There
876: are only two valid ways to use it: to subscript it, or initialize
877: an array variable with it. The former is probably slower than a
878: @code{switch} statement, while the latter does the same thing an
879: ordinary C initializer would do. Here is an example of
880: subscripting an array constructor:
881:
882: @example
883: output = ((int[]) @{ 2, x, 28 @}) [input];
884: @end example
885:
886: Constructor expressions for scalar types and union types are is
887: also allowed, but then the constructor expression is equivalent
888: to a cast.
889:
890: @node Labeled Elements
891: @section Labeled Elements in Initializers
892: @cindex initializers with labeled elements
893: @cindex labeled elements in initializers
894: @cindex case labels in initializers
895:
896: Standard C requires the elements of an initializer to appear in a fixed
897: order, the same as the order of the elements in the array or structure
898: being initialized.
899:
900: In GNU C you can give the elements in any order, specifying the array
901: indices or structure field names they apply to.
902:
903: To specify an array index, write @samp{[@var{index}]} before the
904: element value. For example,
905:
906: @example
907: int a[6] = @{ [4] 29, [2] 15 @};
908: @end example
909:
910: @noindent
911: is equivalent to
912:
913: @example
914: int a[6] = @{ 0, 0, 15, 0, 29, 0 @};
915: @end example
916:
917: @noindent
918: The index values must be constant expressions, even if the array being
919: initialized is automatic.
920:
921: In a structure initializer, specify the name of a field to initialize
922: with @samp{@var{fieldname}:} before the element value. For example,
923: given the following structure,
924:
925: @example
926: struct point @{ int x, y; @};
927: @end example
928:
929: @noindent
930: the following initialization
931:
932: @example
933: struct point p = @{ y: yvalue, x: xvalue @};
934: @end example
935:
936: @noindent
937: is equivalent to
938:
939: @example
940: struct point p = @{ xvalue, yvalue @};
941: @end example
942:
943: You can also use an element label when initializing a union, to
944: specify which element of the union should be used. For example,
945:
946: @example
947: union foo @{ int i; double d; @};
948:
949: union foo f = @{ d: 4 @};
950: @end example
951:
952: @noindent
953: will convert 4 to a @code{double} to store it in the union using
954: the second element. By contrast, casting 4 to type @code{union foo}
955: would store it into the union as the integer @code{i}, since it is
956: an integer. (@xref{Cast to Union}.)
957:
958: You can combine this technique of naming elements with ordinary C
959: initialization of successive elements. Each initializer element that
960: does not have a label applies to the next consecutive element of the
961: array or structure. For example,
962:
963: @example
964: int a[6] = @{ [1] v1, v2, [4] v4 @};
965: @end example
966:
967: @noindent
968: is equivalent to
969:
970: @example
971: int a[6] = @{ 0, v1, v2, 0, v4, 0 @};
972: @end example
973:
974: Labeling the elements of an array initializer is especially useful
975: when the indices are characters or belong to an @code{enum} type.
976: For example:
977:
978: @example
979: int whitespace[256]
980: = @{ [' '] 1, ['\t'] 1, ['\h'] 1,
981: ['\f'] 1, ['\n'] 1, ['\r'] 1 @};
982: @end example
983:
984: @node Case Ranges
985: @section Case Ranges
986: @cindex case ranges
987: @cindex ranges in case statements
988:
989: You can specify a range of consecutive values in a single @code{case} label,
990: like this:
991:
992: @example
993: case @var{low} ... @var{high}:
994: @end example
995:
996: @noindent
997: This has the same effect as the proper number of individual @code{case}
998: labels, one for each integer value from @var{low} to @var{high}, inclusive.
999:
1000: This feature is especially useful for ranges of ASCII character codes:
1001:
1002: @example
1003: case 'A' ... 'Z':
1004: @end example
1005:
1006: @strong{Be careful:} Write spaces around the @code{...}, for otherwise
1007: it may be parsed wrong when you use it with integer values. For example,
1008: write this:
1009:
1010: @example
1011: case 1 ... 5:
1012: @end example
1013:
1014: @noindent
1015: rather than this:
1016:
1017: @example
1018: case 1...5:
1019: @end example
1020:
1021: @node Cast to Union
1022: @section Cast to a Union Type
1023: @cindex cast to a union
1024: @cindex union, casting to a
1025:
1026: A cast to union type is like any other cast, except that the type
1027: specified is a union type. You can specify the type either with
1028: @code{union @var{tag}} or with a typedef name.
1029:
1030: The types that may be cast to the union type are those of the members
1031: of the union. Thus, given the following union and variables:
1032:
1033: @example
1034: union foo @{ int i; double d; @};
1035: int x;
1036: double y;
1037: @end example
1038:
1039: @noindent
1040: both @code{x} and @code{y} can be cast to type @code{union} foo.
1041:
1042: Using the cast as the right-hand side of an assignment to a variable of
1043: union type is equivalent to storing in a member of the union:
1044:
1045: @example
1046: union foo u;
1047: @dots{}
1048: u = (union foo) x @equiv{} u.i = x
1049: u = (union foo) y @equiv{} u.d = y
1050: @end example
1051:
1052: You can also use the union cast as a function argument:
1053:
1054: @example
1055: void hack (union foo);
1056: @dots{}
1057: hack ((union foo) x);
1058: @end example
1059:
1060: @node Function Attributes
1061: @section Declaring Attributes of Functions
1062: @cindex function attributes
1063: @cindex declaring attributes of functions
1064: @cindex functions that never return
1065: @cindex functions that have no side effects
1066: @cindex @code{volatile} applied to function
1067: @cindex @code{const} applied to function
1068:
1069: In GNU C, you declare certain things about functions called in your program
1070: which help the compiler optimize function calls.
1071:
1072: A few standard library functions, such as @code{abort} and @code{exit},
1073: cannot return. GNU CC knows this automatically. Some programs define
1074: their own functions that never return. You can declare them
1075: @code{volatile} to tell the compiler this fact. For example,
1076:
1077: @example
1078: extern void volatile fatal ();
1079:
1080: void
1081: fatal (@dots{})
1082: @{
1083: @dots{} /* @r{Print error message.} */ @dots{}
1084: exit (1);
1085: @}
1086: @end example
1087:
1088: The @code{volatile} keyword tells the compiler to assume that
1089: @code{fatal} cannot return. This makes slightly better code, but more
1090: importantly it helps avoid spurious warnings of uninitialized variables.
1091:
1092: It does not make sense for a @code{volatile} function to have a return
1093: type other than @code{void}.
1094:
1095: Many functions do not examine any values except their arguments, and
1096: have no effects except the return value. Such a function can be subject
1097: to common subexpression elimination and loop optimization just as an
1098: arithmetic operator would be. These functions should be declared
1099: @code{const}. For example,
1100:
1101: @example
1102: extern int const square ();
1103: @end example
1104:
1105: @noindent
1106: says that the hypothetical function @code{square} is safe to call
1107: fewer times than the program says.
1108:
1109: @cindex pointer arguments
1110: Note that a function that has pointer arguments and examines the data
1111: pointed to must @emph{not} be declared @code{const}. Likewise, a
1112: function that calls a non-@code{const} function usually must not be
1113: @code{const}. It does not make sense for a @code{const} function to
1114: return @code{void}.
1115:
1116: We recommend placing the keyword @code{const} after the function's
1117: return type. It makes no difference in the example above, but when the
1118: return type is a pointer, it is the only way to make the function itself
1119: const. For example,
1120:
1121: @example
1122: const char *mincp (int);
1123: @end example
1124:
1125: @noindent
1126: says that @code{mincp} returns @code{const char *}---a pointer to a
1127: const object. To declare @code{mincp} const, you must write this:
1128:
1129: @example
1130: char * const mincp (int);
1131: @end example
1132:
1133: @cindex @code{#pragma}, reason for not using
1134: @cindex pragma, reason for not using
1135: Some people object to this feature, suggesting that ANSI C's
1136: @code{#pragma} should be used instead. There are two reasons for not
1137: doing this.
1138:
1139: @enumerate
1140: @item
1141: It is impossible to generate @code{#pragma} commands from a macro.
1142:
1143: @item
1144: The @code{#pragma} command is just as likely as these keywords to mean
1145: something else in another compiler.
1146: @end enumerate
1147:
1148: These two reasons apply to almost any application that might be proposed
1149: for @code{#pragma}. It is basically a mistake to use @code{#pragma} for
1150: @emph{anything}.
1151:
1.1.1.4 ! root 1152: The keyword @code{__attribute__} allows you to specify special
! 1153: attributes when making a declaration. This keyword is followed by an
! 1154: attribute specification inside double parentheses. One attribute,
! 1155: @code{format}, is currently defined for functions. Others are
! 1156: implemented for variables and structure fields (@pxref{Function
! 1157: Attributes}).
! 1158:
! 1159: @table @code
! 1160: @item format (@var{archetype}, @var{string-index}, @var{first-to-check})
! 1161: @cindex @code{format} attribute
! 1162: The @code{format} attribute specifies that a function takes @code{printf}
! 1163: or @code{scanf} style arguments which should be type-checked against a
! 1164: format string. For example, the declaration:
! 1165:
! 1166: @example
! 1167: extern int
! 1168: my_printf (void *my_object, const char *my_format, ...)
! 1169: __attribute__ ((format (printf, 2, 3)));
! 1170: @end example
! 1171:
! 1172: @noindent
! 1173: causes the compiler to check the arguments in calls to @code{my_printf}
! 1174: for consistency with the @code{printf} style format string argument
! 1175: @code{my_format}.
! 1176:
! 1177: The parameter @var{archetype} determines how the format string is
! 1178: interpreted, and should be either @code{printf} or @code{scanf}. The
! 1179: parameter @var{string-index} specifies which argument is the format
! 1180: string argument (starting from 1), while @var{first-to-check} is the
! 1181: number of the first argument to check against the format string. For
! 1182: functions where the arguments are not available to be checked (such as
! 1183: @code{vprintf}), specify the third parameter as zero. In this case the
! 1184: compiler only checks the format string for consistency.
! 1185:
! 1186: In the example above, the format string (@code{my_format}) is the second
! 1187: argument of the function @code{my_print}, and the arguments to check
! 1188: start with the third argument, so the correct parameters for the format
! 1189: attribute are 2 and 3.
! 1190:
! 1191: The @code{format} attribute allows you to identify your own functions
! 1192: which take format strings as arguments, so that GNU CC can check the
! 1193: calls to these functions for errors. The compiler always checks formats
! 1194: for the ANSI library functions @code{printf}, @code{fprintf},
! 1195: @code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf},
! 1196: @code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such
! 1197: warnings are requested (using @samp{-Wformat}), so there is no need to
! 1198: modify the header file @file{stdio.h}.
! 1199: @end table
! 1200:
1.1.1.3 root 1201: @node Function Prototypes
1202: @section Prototypes and Old-Style Function Definitions
1203: @cindex function prototype declarations
1204: @cindex old-style function definitions
1205: @cindex promotion of formal parameters
1206:
1207: GNU C extends ANSI C to allow a function prototype to override a later
1208: old-style non-prototype definition. Consider the following example:
1209:
1210: @example
1211: /* @r{Use prototypes unless the compiler is old-fashioned.} */
1212: #if __STDC__
1.1.1.4 ! root 1213: #define P(x) (x)
1.1.1.3 root 1214: #else
1.1.1.4 ! root 1215: #define P(x) ()
1.1.1.3 root 1216: #endif
1217:
1218: /* @r{Prototype function declaration.} */
1219: int isroot P((uid_t));
1220:
1221: /* @r{Old-style function definition.} */
1222: int
1223: isroot (x) /* ??? lossage here ??? */
1224: uid_t x;
1225: @{
1226: return x == 0;
1227: @}
1228: @end example
1229:
1230: Suppose the type @code{uid_t} happens to be @code{short}. ANSI C does
1231: not allow this example, because subword arguments in old-style
1232: non-prototype definitions are promoted. Therefore in this example the
1233: function definition's argument is really an @code{int}, which does not
1234: match the prototype argument type of @code{short}.
1235:
1236: This restriction of ANSI C makes it hard to write code that is portable
1237: to traditional C compilers, because the programmer does not know
1238: whether the @code{uid_t} type is @code{short}, @code{int}, or
1239: @code{long}. Therefore, in cases like these GNU C allows a prototype
1240: to override a later old-style definition. More precisely, in GNU C, a
1241: function prototype argument type overrides the argument type specified
1242: by a later old-style definition if the former type is the same as the
1243: latter type before promotion. Thus in GNU C the above example is
1244: equivalent to the following:
1245:
1246: @example
1247: int isroot (uid_t);
1248:
1249: int
1250: isroot (uid_t x)
1251: @{
1252: return x == 0;
1253: @}
1254: @end example
1255:
1.1 root 1256: @node Dollar Signs
1257: @section Dollar Signs in Identifier Names
1258: @cindex $
1259: @cindex dollar signs in identifier names
1260: @cindex identifier names, dollar signs in
1261:
1262: In GNU C, you may use dollar signs in identifier names. This is because
1263: many traditional C implementations allow such identifiers.
1264:
1.1.1.4 ! root 1265: On some machines, dollar signs are allowed in identifiers if you specify
! 1266: @w{@samp{-traditional}}. On a few systems they are allowed by default,
! 1267: even if you do not use @w{@samp{-traditional}}. But they are never
! 1268: allowed if you specify @w{@samp{-ansi}}.
1.1 root 1269:
1270: There are certain ANSI C programs (obscure, to be sure) that would
1271: compile incorrectly if dollar signs were permitted in identifiers. For
1272: example:
1273:
1274: @example
1275: #define foo(a) #a
1276: #define lose(b) foo (b)
1277: #define test$
1278: lose (test)
1279: @end example
1280:
1281: @node Character Escapes
1282: @section The Character @key{ESC} in Constants
1283:
1284: You can use the sequence @samp{\e} in a string or character constant to
1285: stand for the ASCII character @key{ESC}.
1286:
1287: @node Alignment
1288: @section Inquiring on Alignment of Types or Variables
1289: @cindex alignment
1290: @cindex type alignment
1291: @cindex variable alignment
1292:
1293: The keyword @code{__alignof__} allows you to inquire about how an object
1294: is aligned, or the minimum alignment usually required by a type. Its
1295: syntax is just like @code{sizeof}.
1296:
1297: For example, if the target machine requires a @code{double} value to be
1298: aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8.
1299: This is true on many RISC machines. On more traditional machine
1300: designs, @code{__alignof__ (double)} is 4 or even 2.
1301:
1302: Some machines never actually require alignment; they allow reference to any
1303: data type even at an odd addresses. For these machines, @code{__alignof__}
1304: reports the @emph{recommended} alignment of a type.
1305:
1306: When the operand of @code{__alignof__} is an lvalue rather than a type, the
1307: value is the largest alignment that the lvalue is known to have. It may
1308: have this alignment as a result of its data type, or because it is part of
1309: a structure and inherits alignment from that structure. For example, after
1310: this declaration:
1311:
1312: @example
1313: struct foo @{ int x; char y; @} foo1;
1314: @end example
1315:
1316: @noindent
1317: the value of @code{__alignof__ (foo1.y)} is probably 2 or 4, the same as
1318: @code{__alignof__ (int)}, even though the data type of @code{foo1.y}
1319: does not itself demand any alignment.@refill
1320:
1.1.1.4 ! root 1321: A related feature which lets you specify the alignment of an object is
! 1322: @code{__attribute__ ((aligned (@var{alignment})))}; see the following
! 1323: section.
! 1324:
1.1 root 1325: @node Variable Attributes
1326: @section Specifying Attributes of Variables
1327: @cindex attribute of variables
1328: @cindex variable attributes
1329:
1330: The keyword @code{__attribute__} allows you to specify special
1.1.1.4 ! root 1331: attributes of variables or structure fields. This keyword is followed
! 1332: by an attribute specification inside double parentheses. Four
! 1333: attributes are currently defined: @code{aligned}, @code{format},
! 1334: @code{mode} and @code{packed}. @code{format} is used for functions,
! 1335: and thus not documented here; see @ref{Function Attributes}.
! 1336:
! 1337: @table @code
! 1338: @cindex @code{aligned} attribute
! 1339: @item aligned (@var{alignment})
! 1340: This attribute specifies the alignment of the variable or structure
! 1341: field, measured in bytes. For example, the declaration:
1.1 root 1342:
1343: @example
1344: int x __attribute__ ((aligned (16))) = 0;
1345: @end example
1346:
1347: @noindent
1348: causes the compiler to allocate the global variable @code{x} on a
1.1.1.4 ! root 1349: 16-byte boundary. On a 68040, this could be used in conjunction with
1.1 root 1350: an @code{asm} expression to access the @code{move16} instruction which
1351: requires 16-byte aligned operands.
1352:
1353: You can also specify the alignment of structure fields. For example, to
1354: create a double-word aligned @code{int} pair, you could write:
1355:
1356: @example
1357: struct foo @{ int x[2] __attribute__ ((aligned (8))); @};
1358: @end example
1359:
1360: @noindent
1361: This is an alternative to creating a union with a @code{double} member
1362: that forces the union to be double-word aligned.
1363:
1364: It is not possible to specify the alignment of functions; the alignment
1365: of functions is determined by the machine's requirements and cannot be
1.1.1.3 root 1366: changed. You cannot specify alignment for a typedef name because such a
1367: name is just an alias, not a distinct type.
1.1 root 1368:
1.1.1.4 ! root 1369: The linker of your operating system imposes a maximum alignment. If the
! 1370: linker aligns each object file on a four byte boundary, then it is
! 1371: beyond the compiler's power to cause anything to be aligned to a larger
! 1372: boundary than that. For example, if the linker happens to put this object
! 1373: file at address 136 (eight more than a multiple of 64), then the compiler
! 1374: cannot guarantee an alignment of more than 8 just by aligning variables in
! 1375: the object file.
! 1376:
! 1377: @item mode (@var{mode})
! 1378: @cindex @code{mode} attribute
! 1379: This attribute specifies the data type for the declaration---whichever
! 1380: type corresponds to the mode @var{mode}. This in effect lets you
! 1381: request an integer or floating point type according to its width.
! 1382:
! 1383: @item packed
! 1384: @cindex @code{packed} attribute
! 1385: The @code{packed} attribute specifies that a variable or structure field
! 1386: should have the smallest possible alignment---one byte for a variable,
! 1387: and one bit for a field, unless you specify a larger value with the
! 1388: @code{aligned} attribute.
! 1389: @end table
1.1 root 1390:
1391: @node Inline
1392: @section An Inline Function is As Fast As a Macro
1393: @cindex inline functions
1394: @cindex integrating function code
1395: @cindex open coding
1396: @cindex macros, inline alternative
1397:
1.1.1.4 ! root 1398: By declaring a function @code{inline}, you can direct GNU CC to
! 1399: integrate that function's code into the code for its callers. This
! 1400: makes execution faster by eliminating the function-call overhead; in
! 1401: addition, if any of the actual argument values are constant, their known
! 1402: values may permit simplifications at compile time so that not all of the
! 1403: inline function's code needs to be included. Inlining of functions is
! 1404: an optimization and it really ``works'' only in optimizing compilation.
! 1405: If you don't use @samp{-O}, no function is really inline.
1.1 root 1406:
1407: To declare a function inline, use the @code{inline} keyword in its
1408: declaration, like this:
1409:
1410: @example
1411: inline int
1412: inc (int *a)
1413: @{
1414: (*a)++;
1415: @}
1416: @end example
1417:
1418: (If you are writing a header file to be included in ANSI C programs, write
1419: @code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}.)
1420:
1421: You can also make all ``simple enough'' functions inline with the option
1422: @samp{-finline-functions}. Note that certain usages in a function
1423: definition can make it unsuitable for inline substitution.
1424:
1425: @cindex inline functions, omission of
1426: When a function is both inline and @code{static}, if all calls to the
1427: function are integrated into the caller, and the function's address is
1428: never used, then the function's own assembler code is never referenced.
1429: In this case, GNU CC does not actually output assembler code for the
1430: function, unless you specify the option @samp{-fkeep-inline-functions}.
1431: Some calls cannot be integrated for various reasons (in particular,
1432: calls that precede the function's definition cannot be integrated, and
1433: neither can recursive calls within the definition). If there is a
1434: nonintegrated call, then the function is compiled to assembler code as
1435: usual. The function must also be compiled as usual if the program
1436: refers to its address, because that can't be inlined.
1437:
1438: @cindex non-static inline function
1439: When an inline function is not @code{static}, then the compiler must assume
1440: that there may be calls from other source files; since a global symbol can
1441: be defined only once in any program, the function must not be defined in
1442: the other source files, so the calls therein cannot be integrated.
1443: Therefore, a non-@code{static} inline function is always compiled on its
1444: own in the usual fashion.
1445:
1446: If you specify both @code{inline} and @code{extern} in the function
1447: definition, then the definition is used only for inlining. In no case
1448: is the function compiled on its own, not even if you refer to its
1449: address explicitly. Such an address becomes an external reference, as
1450: if you had only declared the function, and had not defined it.
1451:
1452: This combination of @code{inline} and @code{extern} has almost the
1453: effect of a macro. The way to use it is to put a function definition in
1454: a header file with these keywords, and put another copy of the
1455: definition (lacking @code{inline} and @code{extern}) in a library file.
1456: The definition in the header file will cause most calls to the function
1457: to be inlined. If any uses of the function remain, they will refer to
1458: the single copy in the library.
1459:
1.1.1.4 ! root 1460: GNU C does not inline any functions when not optimizing. It is not
! 1461: clear whether it is better to inline or not, in this case, but we found
! 1462: that a correct implementation when not optimizing was difficult. So we
! 1463: did the easy thing, and turned it off.
! 1464:
1.1 root 1465: @node Extended Asm
1466: @section Assembler Instructions with C Expression Operands
1467: @cindex extended @code{asm}
1468: @cindex @code{asm} expressions
1469: @cindex assembler instructions
1470: @cindex registers
1471:
1472: In an assembler instruction using @code{asm}, you can now specify the
1473: operands of the instruction using C expressions. This means no more
1474: guessing which registers or memory locations will contain the data you want
1475: to use.
1476:
1477: You must specify an assembler instruction template much like what appears
1478: in a machine description, plus an operand constraint string for each
1479: operand.
1480:
1481: For example, here is how to use the 68881's @code{fsinx} instruction:
1482:
1483: @example
1484: asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
1485: @end example
1486:
1487: @noindent
1488: @ifset INTERNALS
1489: Here @code{angle} is the C expression for the input operand while
1490: @code{result} is that of the output operand. Each has @samp{"f"} as its
1491: operand constraint, saying that a floating point register is required. The
1492: @samp{=} in @samp{=f} indicates that the operand is an output; all output
1493: operands' constraints must use @samp{=}. The constraints use the same
1494: language used in the machine description (@pxref{Constraints}).
1495: @end ifset
1496: @ifclear INTERNALS
1497: Here @code{angle} is the C expression for the input operand while
1498: @code{result} is that of the output operand. Each has @samp{"f"} as its
1499: operand constraint, saying that a floating point register is required. The
1500: @samp{=} in @samp{=f} indicates that the operand is an output; all output
1501: operands' constraints must use @samp{=}. The constraints use the same
1502: language used in the machine description (@pxref{Constraints,,Operand
1503: Constraints, gcc.info, Using and Porting GCC}).
1504: @end ifclear
1505:
1506: Each operand is described by an operand-constraint string followed by the C
1507: expression in parentheses. A colon separates the assembler template from
1508: the first output operand, and another separates the last output operand
1509: from the first input, if any. Commas separate output operands and separate
1510: inputs. The total number of operands is limited to ten or to the maximum
1511: number of operands in any instruction pattern in the machine description,
1512: whichever is greater.
1513:
1514: If there are no output operands, and there are input operands, then there
1515: must be two consecutive colons surrounding the place where the output
1516: operands would go.
1517:
1518: Output operand expressions must be lvalues; the compiler can check this.
1519: The input operands need not be lvalues. The compiler cannot check whether
1520: the operands have data types that are reasonable for the instruction being
1521: executed. It does not parse the assembler instruction template and does
1522: not know what it means, or whether it is valid assembler input. The
1523: extended @code{asm} feature is most often used for machine instructions
1524: that the compiler itself does not know exist.
1525:
1526: The output operands must be write-only; GNU CC will assume that the values
1527: in these operands before the instruction are dead and need not be
1528: generated. Extended asm does not support input-output or read-write
1529: operands. For this reason, the constraint character @samp{+}, which
1530: indicates such an operand, may not be used.
1531:
1532: When the assembler instruction has a read-write operand, or an operand
1533: in which only some of the bits are to be changed, you must logically
1534: split its function into two separate operands, one input operand and one
1535: write-only output operand. The connection between them is expressed by
1536: constraints which say they need to be in the same location when the
1537: instruction executes. You can use the same C expression for both
1538: operands, or different expressions. For example, here we write the
1539: (fictitious) @samp{combine} instruction with @code{bar} as its read-only
1540: source operand and @code{foo} as its read-write destination:
1541:
1542: @example
1543: asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
1544: @end example
1545:
1546: @noindent
1547: The constraint @samp{"0"} for operand 1 says that it must occupy the same
1548: location as operand 0. A digit in constraint is allowed only in an input
1549: operand, and it must refer to an output operand.
1550:
1551: Only a digit in the constraint can guarantee that one operand will be in
1552: the same place as another. The mere fact that @code{foo} is the value of
1553: both operands is not enough to guarantee that they will be in the same
1554: place in the generated assembler code. The following would not work:
1555:
1556: @example
1557: asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));
1558: @end example
1559:
1560: Various optimizations or reloading could cause operands 0 and 1 to be in
1561: different registers; GNU CC knows no reason not to do so. For example, the
1562: compiler might find a copy of the value of @code{foo} in one register and
1563: use it for operand 1, but generate the output operand 0 in a different
1564: register (copying it afterward to @code{foo}'s own address). Of course,
1565: since the register for operand 1 is not even mentioned in the assembler
1566: code, the result will not work, but GNU CC can't tell that.
1567:
1568: Some instructions clobber specific hard registers. To describe this, write
1569: a third colon after the input operands, followed by the names of the
1570: clobbered hard registers (given as strings). Here is a realistic example
1571: for the Vax:
1572:
1573: @example
1574: asm volatile ("movc3 %0,%1,%2"
1575: : /* no outputs */
1576: : "g" (from), "g" (to), "g" (count)
1577: : "r0", "r1", "r2", "r3", "r4", "r5");
1578: @end example
1579:
1580: If you refer to a particular hardware register from the assembler code,
1581: then you will probably have to list the register after the third colon
1582: to tell the compiler that the register's value is modified. In many
1583: assemblers, the register names begin with @samp{%}; to produce one
1584: @samp{%} in the assembler code, you must write @samp{%%} in the input.
1585:
1.1.1.3 root 1586: If your assembler instruction can alter the condition code register,
1587: add @samp{cc} to the list of clobbered registers. GNU CC on some
1588: machines represents the condition codes as a specific hardware
1589: register; @samp{cc} serves to name this register. On other machines,
1590: the condition code is handled differently, and specifying @samp{cc}
1591: has no effect. But it is valid no matter what the machine.
1592:
1.1.1.4 ! root 1593: If your assembler instruction modifies memory in an unpredicable
! 1594: fashion, add @samp{memory} to the list of clobbered registers.
! 1595: This will cause GNU CC to not keep memory values cached in
! 1596: registers across the assembler instruction.
! 1597:
1.1 root 1598: You can put multiple assembler instructions together in a single @code{asm}
1599: template, separated either with newlines (written as @samp{\n}) or with
1600: semicolons if the assembler allows such semicolons. The GNU assembler
1601: allows semicolons and all Unix assemblers seem to do so. The input
1602: operands are guaranteed not to use any of the clobbered registers, and
1603: neither will the output operands' addresses, so you can read and write the
1604: clobbered registers as many times as you like. Here is an example of
1605: multiple instructions in a template; it assumes that the subroutine
1606: @code{_foo} accepts arguments in registers 9 and 10:
1607:
1608: @example
1609: asm ("movl %0,r9;movl %1,r10;call _foo"
1610: : /* no outputs */
1611: : "g" (from), "g" (to)
1612: : "r9", "r10");
1613: @end example
1614:
1615: @ifset INTERNALS
1616: Unless an output operand has the @samp{&} constraint modifier, GNU CC may
1617: allocate it in the same register as an unrelated input operand, on the
1618: assumption that the inputs are consumed before the outputs are produced.
1619: This assumption may be false if the assembler code actually consists of
1620: more than one instruction. In such a case, use @samp{&} for each output
1621: operand that may not overlap an input.
1622: @xref{Modifiers}.
1623: @end ifset
1624: @ifclear INTERNALS
1625: Unless an output operand has the @samp{&} constraint modifier, GNU CC may
1626: allocate it in the same register as an unrelated input operand, on the
1627: assumption that the inputs are consumed before the outputs are produced.
1628: This assumption may be false if the assembler code actually consists of
1629: more than one instruction. In such a case, use @samp{&} for each output
1630: operand that may not overlap an input.
1631: @xref{Modifiers,,Constraint Modifier Characters,gcc.info,Using and
1632: Porting GCC}.
1633: @end ifclear
1634:
1635: If you want to test the condition code produced by an assembler instruction,
1636: you must include a branch and a label in the @code{asm} construct, as follows:
1637:
1638: @example
1639: asm ("clr %0;frob %1;beq 0f;mov #1,%0;0:"
1640: : "g" (result)
1641: : "g" (input));
1642: @end example
1643:
1644: @noindent
1645: This assumes your assembler supports local labels, as the GNU assembler
1646: and most Unix assemblers do.
1647:
1648: @cindex macros containing @code{asm}
1649: Usually the most convenient way to use these @code{asm} instructions is to
1650: encapsulate them in macros that look like functions. For example,
1651:
1652: @example
1653: #define sin(x) \
1654: (@{ double __value, __arg = (x); \
1655: asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \
1656: __value; @})
1657: @end example
1658:
1659: @noindent
1660: Here the variable @code{__arg} is used to make sure that the instruction
1661: operates on a proper @code{double} value, and to accept only those
1662: arguments @code{x} which can convert automatically to a @code{double}.
1663:
1664: Another way to make sure the instruction operates on the correct data type
1665: is to use a cast in the @code{asm}. This is different from using a
1666: variable @code{__arg} in that it converts more different types. For
1667: example, if the desired type were @code{int}, casting the argument to
1668: @code{int} would accept a pointer with no complaint, while assigning the
1669: argument to an @code{int} variable named @code{__arg} would warn about
1670: using a pointer unless the caller explicitly casts it.
1671:
1672: If an @code{asm} has output operands, GNU CC assumes for optimization
1673: purposes that the instruction has no side effects except to change the
1674: output operands. This does not mean that instructions with a side effect
1675: cannot be used, but you must be careful, because the compiler may eliminate
1676: them if the output operands aren't used, or move them out of loops, or
1677: replace two with one if they constitute a common subexpression. Also, if
1678: your instruction does have a side effect on a variable that otherwise
1679: appears not to change, the old value of the variable may be reused later if
1680: it happens to be found in a register.
1681:
1682: You can prevent an @code{asm} instruction from being deleted, moved
1683: significantly, or combined, by writing the keyword @code{volatile} after
1684: the @code{asm}. For example:
1685:
1686: @example
1687: #define set_priority(x) \
1688: asm volatile ("set_priority %0": /* no outputs */ : "g" (x))
1689: @end example
1690:
1691: @noindent
1692: An instruction without output operands will not be deleted or moved
1693: significantly, regardless, unless it is unreachable.
1694:
1695: Note that even a volatile @code{asm} instruction can be moved in ways
1696: that appear insignificant to the compiler, such as across jump
1697: instructions. You can't expect a sequence of volatile @code{asm}
1698: instructions to remain perfectly consecutive. If you want consecutive
1699: output, use a single @code{asm}.
1700:
1701: It is a natural idea to look for a way to give access to the condition
1702: code left by the assembler instruction. However, when we attempted to
1703: implement this, we found no way to make it work reliably. The problem
1704: is that output operands might need reloading, which would result in
1705: additional following ``store'' instructions. On most machines, these
1706: instructions would alter the condition code before there was time to
1707: test it. This problem doesn't arise for ordinary ``test'' and
1708: ``compare'' instructions because they don't have any output operands.
1709:
1710: If you are writing a header file that should be includable in ANSI C
1711: programs, write @code{__asm__} instead of @code{asm}. @xref{Alternate
1712: Keywords}.
1713:
1714: @node Asm Labels
1715: @section Controlling Names Used in Assembler Code
1716: @cindex assembler names for identifiers
1717: @cindex names used in assembler code
1718: @cindex identifiers, names in assembler code
1719:
1720: You can specify the name to be used in the assembler code for a C
1721: function or variable by writing the @code{asm} (or @code{__asm__})
1722: keyword after the declarator as follows:
1723:
1724: @example
1725: int foo asm ("myfoo") = 2;
1726: @end example
1727:
1728: @noindent
1729: This specifies that the name to be used for the variable @code{foo} in
1730: the assembler code should be @samp{myfoo} rather than the usual
1731: @samp{_foo}.
1732:
1733: On systems where an underscore is normally prepended to the name of a C
1734: function or variable, this feature allows you to define names for the
1735: linker that do not start with an underscore.
1736:
1737: You cannot use @code{asm} in this way in a function @emph{definition}; but
1738: you can get the same effect by writing a declaration for the function
1739: before its definition and putting @code{asm} there, like this:
1740:
1741: @example
1742: extern func () asm ("FUNC");
1743:
1744: func (x, y)
1745: int x, y;
1746: @dots{}
1747: @end example
1748:
1749: It is up to you to make sure that the assembler names you choose do not
1750: conflict with any other assembler symbols. Also, you must not use a
1751: register name; that would produce completely invalid assembler code. GNU
1752: CC does not as yet have the ability to store static variables in registers.
1753: Perhaps that will be added.
1754:
1755: @node Explicit Reg Vars
1756: @section Variables in Specified Registers
1757: @cindex explicit register variables
1758: @cindex variables in specified registers
1759: @cindex specified registers
1760: @cindex registers, global allocation
1761:
1762: GNU C allows you to put a few global variables into specified hardware
1763: registers. You can also specify the register in which an ordinary
1764: register variable should be allocated.
1765:
1766: @itemize @bullet
1767: @item
1768: Global register variables reserve registers throughout the program.
1769: This may be useful in programs such as programming language
1770: interpreters which have a couple of global variables that are accessed
1771: very often.
1772:
1773: @item
1774: Local register variables in specific registers do not reserve the
1775: registers. The compiler's data flow analysis is capable of determining
1776: where the specified registers contain live values, and where they are
1777: available for other uses.
1778:
1779: These local variables are sometimes convenient for use with the extended
1780: @code{asm} feature (@pxref{Extended Asm}), if you want to write one
1781: output of the assembler instruction directly into a particular register.
1782: (This will work provided the register you specify fits the constraints
1783: specified for that operand in the @code{asm}.)
1784: @end itemize
1785:
1786: @menu
1787: * Global Reg Vars::
1788: * Local Reg Vars::
1789: @end menu
1790:
1791: @node Global Reg Vars
1792: @subsection Defining Global Register Variables
1793: @cindex global register variables
1794: @cindex registers, global variables in
1795:
1796: You can define a global register variable in GNU C like this:
1797:
1798: @example
1799: register int *foo asm ("a5");
1800: @end example
1801:
1802: @noindent
1803: Here @code{a5} is the name of the register which should be used. Choose a
1804: register which is normally saved and restored by function calls on your
1805: machine, so that library routines will not clobber it.
1806:
1807: Naturally the register name is cpu-dependent, so you would need to
1808: conditionalize your program according to cpu type. The register
1809: @code{a5} would be a good choice on a 68000 for a variable of pointer
1810: type. On machines with register windows, be sure to choose a ``global''
1811: register that is not affected magically by the function call mechanism.
1812:
1813: In addition, operating systems on one type of cpu may differ in how they
1814: name the registers; then you would need additional conditionals. For
1815: example, some 68000 operating systems call this register @code{%a5}.
1816:
1817: Eventually there may be a way of asking the compiler to choose a register
1818: automatically, but first we need to figure out how it should choose and
1819: how to enable you to guide the choice. No solution is evident.
1820:
1821: Defining a global register variable in a certain register reserves that
1822: register entirely for this use, at least within the current compilation.
1823: The register will not be allocated for any other purpose in the functions
1824: in the current compilation. The register will not be saved and restored by
1825: these functions. Stores into this register are never deleted even if they
1826: would appear to be dead, but references may be deleted or moved or
1827: simplified.
1828:
1829: It is not safe to access the global register variables from signal
1830: handlers, or from more than one thread of control, because the system
1831: library routines may temporarily use the register for other things (unless
1832: you recompile them specially for the task at hand).
1833:
1834: @cindex @code{qsort}, and global register variables
1835: It is not safe for one function that uses a global register variable to
1836: call another such function @code{foo} by way of a third function
1837: @code{lose} that was compiled without knowledge of this variable (i.e. in a
1838: different source file in which the variable wasn't declared). This is
1839: because @code{lose} might save the register and put some other value there.
1840: For example, you can't expect a global register variable to be available in
1841: the comparison-function that you pass to @code{qsort}, since @code{qsort}
1842: might have put something else in that register. (If you are prepared to
1843: recompile @code{qsort} with the same global register variable, you can
1844: solve this problem.)
1845:
1846: If you want to recompile @code{qsort} or other source files which do not
1847: actually use your global register variable, so that they will not use that
1848: register for any other purpose, then it suffices to specify the compiler
1849: option @samp{-ffixed-@var{reg}}. You need not actually add a global
1850: register declaration to their source code.
1851:
1852: A function which can alter the value of a global register variable cannot
1853: safely be called from a function compiled without this variable, because it
1854: could clobber the value the caller expects to find there on return.
1855: Therefore, the function which is the entry point into the part of the
1856: program that uses the global register variable must explicitly save and
1857: restore the value which belongs to its caller.
1858:
1859: @cindex register variable after @code{longjmp}
1860: @cindex global register after @code{longjmp}
1861: @cindex value after @code{longjmp}
1862: @findex longjmp
1863: @findex setjmp
1864: On most machines, @code{longjmp} will restore to each global register
1865: variable the value it had at the time of the @code{setjmp}. On some
1866: machines, however, @code{longjmp} will not change the value of global
1867: register variables. To be portable, the function that called @code{setjmp}
1868: should make other arrangements to save the values of the global register
1869: variables, and to restore them in a @code{longjmp}. This way, the same
1870: thing will happen regardless of what @code{longjmp} does.
1871:
1872: All global register variable declarations must precede all function
1873: definitions. If such a declaration could appear after function
1874: definitions, the declaration would be too late to prevent the register from
1875: being used for other purposes in the preceding functions.
1876:
1877: Global register variables may not have initial values, because an
1878: executable file has no means to supply initial contents for a register.
1879:
1880: On the Sparc, there are reports that g3 @dots{} g7 are suitable
1881: registers, but certain library functions, such as @code{getwd}, as well
1882: as the subroutines for division and remainder, modify g3 and g4. g1 and
1883: g2 are local temporaries.
1884:
1885: On the 68000, a2 @dots{} a5 should be suitable, as should d2 @dots{} d7.
1886: Of course, it will not do to use more than a few of those.
1887:
1888: @node Local Reg Vars
1889: @subsection Specifying Registers for Local Variables
1890: @cindex local variables, specifying registers
1891: @cindex specifying registers for local variables
1892: @cindex registers for local variables
1893:
1894: You can define a local register variable with a specified register
1895: like this:
1896:
1897: @example
1898: register int *foo asm ("a5");
1899: @end example
1900:
1901: @noindent
1902: Here @code{a5} is the name of the register which should be used. Note
1903: that this is the same syntax used for defining global register
1904: variables, but for a local variable it would appear within a function.
1905:
1906: Naturally the register name is cpu-dependent, but this is not a
1907: problem, since specific registers are most often useful with explicit
1908: assembler instructions (@pxref{Extended Asm}). Both of these things
1909: generally require that you conditionalize your program according to
1910: cpu type.
1911:
1912: In addition, operating systems on one type of cpu may differ in how they
1913: name the registers; then you would need additional conditionals. For
1914: example, some 68000 operating systems call this register @code{%a5}.
1915:
1916: Eventually there may be a way of asking the compiler to choose a register
1917: automatically, but first we need to figure out how it should choose and
1918: how to enable you to guide the choice. No solution is evident.
1919:
1920: Defining such a register variable does not reserve the register; it
1921: remains available for other uses in places where flow control determines
1922: the variable's value is not live. However, these registers are made
1923: unavailable for use in the reload pass. I would not be surprised if
1924: excessive use of this feature leaves the compiler too few available
1925: registers to compile certain functions.
1926:
1927: @node Alternate Keywords
1928: @section Alternate Keywords
1929: @cindex alternate keywords
1930: @cindex keywords, alternate
1931:
1932: The option @samp{-traditional} disables certain keywords; @samp{-ansi}
1933: disables certain others. This causes trouble when you want to use GNU C
1934: extensions, or ANSI C features, in a general-purpose header file that
1935: should be usable by all programs, including ANSI C programs and traditional
1936: ones. The keywords @code{asm}, @code{typeof} and @code{inline} cannot be
1937: used since they won't work in a program compiled with @samp{-ansi}, while
1938: the keywords @code{const}, @code{volatile}, @code{signed}, @code{typeof}
1939: and @code{inline} won't work in a program compiled with
1940: @samp{-traditional}.@refill
1941:
1942: The way to solve these problems is to put @samp{__} at the beginning and
1943: end of each problematical keyword. For example, use @code{__asm__}
1944: instead of @code{asm}, @code{__const__} instead of @code{const}, and
1945: @code{__inline__} instead of @code{inline}.
1946:
1947: Other C compilers won't accept these alternative keywords; if you want to
1948: compile with another compiler, you can define the alternate keywords as
1949: macros to replace them with the customary keywords. It looks like this:
1950:
1951: @example
1952: #ifndef __GNUC__
1953: #define __asm__ asm
1954: #endif
1955: @end example
1956:
1957: @samp{-pedantic} causes warnings for many GNU C extensions. You can
1958: prevent such warnings within one expression by writing
1959: @code{__extension__} before the expression. @code{__extension__} has no
1960: effect aside from this.
1961:
1962: @node Incomplete Enums
1963: @section Incomplete @code{enum} Types
1964:
1965: You can define an @code{enum} tag without specifying its possible values.
1966: This results in an incomplete type, much like what you get if you write
1967: @code{struct foo} without describing the elements. A later declaration
1968: which does specify the possible values completes the type.
1969:
1970: You can't allocate variables or storage using the type while it is
1971: incomplete. However, you can work with pointers to that type.
1972:
1973: This extension may not be very useful, but it makes the handling of
1974: @code{enum} more consistent with the way @code{struct} and @code{union}
1975: are handled.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.