Return to gcc.info-8 CVS log

Up to [GCC 2.x] / gcc

Annotation of gcc/gcc.info-8, revision 1.1.1.7

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

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