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