Return to extend.texi CVS log

Up to [Apple XNU] / GNUtools / cc

Annotation of GNUtools/cc/extend.texi, revision 1.1

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

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.