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