Return to gcc.info-7 CVS log

Up to [Apple XNU] / GNUtools / cc

Annotation of GNUtools/cc/gcc.info-7, revision 1.1

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

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