home *** CD-ROM | disk | FTP | other *** search
/ The CDPD Public Domain Collection for CDTV 3 / CDPDIII.bin / pd / programming / gnuc / info / gcc.info-6 < prev    next >
Encoding:
GNU Info File  |  1992-12-28  |  41.3 KB  |  941 lines

  1. This is Info file gcc.info, produced by Makeinfo-1.49 from the input
  2. file gcc.texi.
  3.  
  4.    This file documents the use and the internals of the GNU compiler.
  5.  
  6.    Copyright (C) 1988, 1989, 1992 Free Software Foundation, Inc.
  7.  
  8.    Permission is granted to make and distribute verbatim copies of this
  9. manual provided the copyright notice and this permission notice are
  10. preserved on all copies.
  11.  
  12.    Permission is granted to copy and distribute modified versions of
  13. this manual under the conditions for verbatim copying, provided also
  14. that the sections entitled "GNU General Public License" and "Protect
  15. Your Freedom--Fight `Look And Feel'" are included exactly as in the
  16. original, and provided that the entire resulting derived work is
  17. distributed under the terms of a permission notice identical to this
  18. one.
  19.  
  20.    Permission is granted to copy and distribute translations of this
  21. manual into another language, under the above conditions for modified
  22. versions, except that the sections entitled "GNU General Public
  23. License" and "Protect Your Freedom--Fight `Look And Feel'", and this
  24. permission notice, may be included in translations approved by the Free
  25. Software Foundation instead of in the original English.
  26.  
  27. 
  28. File: gcc.info,  Node: Function Prototypes,  Next: Dollar Signs,  Prev: Function Attributes,  Up: Extensions
  29.  
  30. Prototypes and Old-Style Function Definitions
  31. =============================================
  32.  
  33.    GNU C extends ANSI C to allow a function prototype to override a
  34. later old-style non-prototype definition.  Consider the following
  35. example:
  36.  
  37.      /* Use prototypes unless the compiler is old-fashioned.  */
  38.      #if __STDC__
  39.      #define P(x) (x)
  40.      #else
  41.      #define P(x) ()
  42.      #endif
  43.      
  44.      /* Prototype function declaration.  */
  45.      int isroot P((uid_t));
  46.      
  47.      /* Old-style function definition.  */
  48.      int
  49.      isroot (x)   /* ??? lossage here ??? */
  50.           uid_t x;
  51.      {
  52.        return x == 0;
  53.      }
  54.  
  55.    Suppose the type `uid_t' happens to be `short'.  ANSI C does not
  56. allow this example, because subword arguments in old-style
  57. non-prototype definitions are promoted.  Therefore in this example the
  58. function definition's argument is really an `int', which does not match
  59. the prototype argument type of `short'.
  60.  
  61.    This restriction of ANSI C makes it hard to write code that is
  62. portable to traditional C compilers, because the programmer does not
  63. know whether the `uid_t' type is `short', `int', or `long'.  Therefore,
  64. in cases like these GNU C allows a prototype to override a later
  65. old-style definition.  More precisely, in GNU C, a function prototype
  66. argument type overrides the argument type specified by a later
  67. old-style definition if the former type is the same as the latter type
  68. before promotion.  Thus in GNU C the above example is equivalent to the
  69. following:
  70.  
  71.      int isroot (uid_t);
  72.      
  73.      int
  74.      isroot (uid_t x)
  75.      {
  76.        return x == 0;
  77.      }
  78.  
  79. 
  80. File: gcc.info,  Node: Dollar Signs,  Next: Character Escapes,  Prev: Function Prototypes,  Up: Extensions
  81.  
  82. Dollar Signs in Identifier Names
  83. ================================
  84.  
  85.    In GNU C, you may use dollar signs in identifier names.  This is
  86. because many traditional C implementations allow such identifiers.
  87.  
  88.    On some machines, dollar signs are allowed in identifiers if you
  89. specify `-traditional'.  On a few systems they are allowed by default,
  90. even if you do not use `-traditional'.  But they are never allowed if
  91. you specify `-ansi'.
  92.  
  93.    There are certain ANSI C programs (obscure, to be sure) that would
  94. compile incorrectly if dollar signs were permitted in identifiers.  For
  95. example:
  96.  
  97.      #define foo(a) #a
  98.      #define lose(b) foo (b)
  99.      #define test$
  100.      lose (test)
  101.  
  102. 
  103. File: gcc.info,  Node: Character Escapes,  Next: Variable Attributes,  Prev: Dollar Signs,  Up: Extensions
  104.  
  105. The Character ESC in Constants
  106. ==============================
  107.  
  108.    You can use the sequence `\e' in a string or character constant to
  109. stand for the ASCII character ESC.
  110.  
  111. 
  112. File: gcc.info,  Node: Alignment,  Next: Inline,  Prev: Variable Attributes,  Up: Extensions
  113.  
  114. Inquiring on Alignment of Types or Variables
  115. ============================================
  116.  
  117.    The keyword `__alignof__' allows you to inquire about how an object
  118. is aligned, or the minimum alignment usually required by a type.  Its
  119. syntax is just like `sizeof'.
  120.  
  121.    For example, if the target machine requires a `double' value to be
  122. aligned on an 8-byte boundary, then `__alignof__ (double)' is 8. This
  123. is true on many RISC machines.  On more traditional machine designs,
  124. `__alignof__ (double)' is 4 or even 2.
  125.  
  126.    Some machines never actually require alignment; they allow reference
  127. to any data type even at an odd addresses.  For these machines,
  128. `__alignof__' reports the *recommended* alignment of a type.
  129.  
  130.    When the operand of `__alignof__' is an lvalue rather than a type,
  131. the value is the largest alignment that the lvalue is known to have. 
  132. It may have this alignment as a result of its data type, or because it
  133. is part of a structure and inherits alignment from that structure. For
  134. example, after this declaration:
  135.  
  136.      struct foo { int x; char y; } foo1;
  137.  
  138. the value of `__alignof__ (foo1.y)' is probably 2 or 4, the same as
  139. `__alignof__ (int)', even though the data type of `foo1.y' does not
  140. itself demand any alignment.
  141.  
  142.    A related feature which lets you specify the alignment of an object
  143. is `__attribute__ ((aligned (ALIGNMENT)))'; see the following section.
  144.  
  145. 
  146. File: gcc.info,  Node: Variable Attributes,  Next: Alignment,  Prev: Character Escapes,  Up: Extensions
  147.  
  148. Specifying Attributes of Variables
  149. ==================================
  150.  
  151.    The keyword `__attribute__' allows you to specify special attributes
  152. of variables or structure fields.  This keyword is followed by an
  153. attribute specification inside double parentheses.  Four attributes are
  154. currently defined: `aligned', `format', `mode' and `packed'.  `format'
  155. is used for functions, and thus not documented here; see *Note Function
  156. Attributes::.
  157.  
  158. `aligned (ALIGNMENT)'
  159.      This attribute specifies the alignment of the variable or structure
  160.      field, measured in bytes.  For example, the declaration:
  161.  
  162.           int x __attribute__ ((aligned (16))) = 0;
  163.  
  164.      causes the compiler to allocate the global variable `x' on a
  165.      16-byte boundary.  On a 68040, this could be used in conjunction
  166.      with an `asm' expression to access the `move16' instruction which
  167.      requires 16-byte aligned operands.
  168.  
  169.      You can also specify the alignment of structure fields.  For
  170.      example, to create a double-word aligned `int' pair, you could
  171.      write:
  172.  
  173.           struct foo { int x[2] __attribute__ ((aligned (8))); };
  174.  
  175.      This is an alternative to creating a union with a `double' member
  176.      that forces the union to be double-word aligned.
  177.  
  178.      It is not possible to specify the alignment of functions; the
  179.      alignment of functions is determined by the machine's requirements
  180.      and cannot be changed.  You cannot specify alignment for a typedef
  181.      name because such a name is just an alias, not a distinct type.
  182.  
  183.      The linker of your operating system imposes a maximum alignment. 
  184.      If the linker aligns each object file on a four byte boundary,
  185.      then it is beyond the compiler's power to cause anything to be
  186.      aligned to a larger boundary than that.  For example, if  the
  187.      linker happens to put this object file at address 136 (eight more
  188.      than a multiple of 64), then the compiler cannot guarantee an
  189.      alignment of more than 8 just by aligning variables in the object
  190.      file.
  191.  
  192. `mode (MODE)'
  193.      This attribute specifies the data type for the
  194.      declaration--whichever type corresponds to the mode MODE.  This in
  195.      effect lets you request an integer or floating point type
  196.      according to its width.
  197.  
  198. `packed'
  199.      The `packed' attribute specifies that a variable or structure field
  200.      should have the smallest possible alignment--one byte for a
  201.      variable, and one bit for a field, unless you specify a larger
  202.      value with the `aligned' attribute.
  203.  
  204. 
  205. File: gcc.info,  Node: Inline,  Next: Extended Asm,  Prev: Alignment,  Up: Extensions
  206.  
  207. An Inline Function is As Fast As a Macro
  208. ========================================
  209.  
  210.    By declaring a function `inline', you can direct GNU CC to integrate
  211. that function's code into the code for its callers.  This makes
  212. execution faster by eliminating the function-call overhead; in
  213. addition, if any of the actual argument values are constant, their known
  214. values may permit simplifications at compile time so that not all of the
  215. inline function's code needs to be included.  Inlining of functions is
  216. an optimization and it really "works" only in optimizing compilation.
  217. If you don't use `-O', no function is really inline.
  218.  
  219.    To declare a function inline, use the `inline' keyword in its
  220. declaration, like this:
  221.  
  222.      inline int
  223.      inc (int *a)
  224.      {
  225.        (*a)++;
  226.      }
  227.  
  228.    (If you are writing a header file to be included in ANSI C programs,
  229. write `__inline__' instead of `inline'.  *Note Alternate Keywords::.)
  230.  
  231.    You can also make all "simple enough" functions inline with the
  232. option `-finline-functions'.  Note that certain usages in a function
  233. definition can make it unsuitable for inline substitution.
  234.  
  235.    When a function is both inline and `static', if all calls to the
  236. function are integrated into the caller, and the function's address is
  237. never used, then the function's own assembler code is never referenced.
  238. In this case, GNU CC does not actually output assembler code for the
  239. function, unless you specify the option `-fkeep-inline-functions'. Some
  240. calls cannot be integrated for various reasons (in particular, calls
  241. that precede the function's definition cannot be integrated, and
  242. neither can recursive calls within the definition).  If there is a
  243. nonintegrated call, then the function is compiled to assembler code as
  244. usual.  The function must also be compiled as usual if the program
  245. refers to its address, because that can't be inlined.
  246.  
  247.    When an inline function is not `static', then the compiler must
  248. assume that there may be calls from other source files; since a global
  249. symbol can be defined only once in any program, the function must not
  250. be defined in the other source files, so the calls therein cannot be
  251. integrated. Therefore, a non-`static' inline function is always
  252. compiled on its own in the usual fashion.
  253.  
  254.    If you specify both `inline' and `extern' in the function
  255. definition, then the definition is used only for inlining.  In no case
  256. is the function compiled on its own, not even if you refer to its
  257. address explicitly.  Such an address becomes an external reference, as
  258. if you had only declared the function, and had not defined it.
  259.  
  260.    This combination of `inline' and `extern' has almost the effect of a
  261. macro.  The way to use it is to put a function definition in a header
  262. file with these keywords, and put another copy of the definition
  263. (lacking `inline' and `extern') in a library file. The definition in
  264. the header file will cause most calls to the function to be inlined. 
  265. If any uses of the function remain, they will refer to the single copy
  266. in the library.
  267.  
  268.    GNU C does not inline any functions when not optimizing.  It is not
  269. clear whether it is better to inline or not, in this case, but we found
  270. that a correct implementation when not optimizing was difficult.  So we
  271. did the easy thing, and turned it off.
  272.  
  273. 
  274. File: gcc.info,  Node: Extended Asm,  Next: Asm Labels,  Prev: Inline,  Up: Extensions
  275.  
  276. Assembler Instructions with C Expression Operands
  277. =================================================
  278.  
  279.    In an assembler instruction using `asm', you can now specify the
  280. operands of the instruction using C expressions.  This means no more
  281. guessing which registers or memory locations will contain the data you
  282. want to use.
  283.  
  284.    You must specify an assembler instruction template much like what
  285. appears in a machine description, plus an operand constraint string for
  286. each operand.
  287.  
  288.    For example, here is how to use the 68881's `fsinx' instruction:
  289.  
  290.      asm ("fsinx %1,%0" : "=f" (result) : "f" (angle));
  291.  
  292. Here `angle' is the C expression for the input operand while `result'
  293. is that of the output operand.  Each has `"f"' as its operand
  294. constraint, saying that a floating point register is required.  The `='
  295. in `=f' indicates that the operand is an output; all output operands'
  296. constraints must use `='.  The constraints use the same language used
  297. in the machine description (*note Constraints::.).
  298.  
  299. Each operand is described by an operand-constraint string followed by
  300. the C expression in parentheses.  A colon separates the assembler
  301. template from the first output operand, and another separates the last
  302. output operand from the first input, if any.  Commas separate output
  303. operands and separate inputs.  The total number of operands is limited
  304. to ten or to the maximum number of operands in any instruction pattern
  305. in the machine description, whichever is greater.
  306.  
  307.    If there are no output operands, and there are input operands, then
  308. there must be two consecutive colons surrounding the place where the
  309. output operands would go.
  310.  
  311.    Output operand expressions must be lvalues; the compiler can check
  312. this. The input operands need not be lvalues.  The compiler cannot
  313. check whether the operands have data types that are reasonable for the
  314. instruction being executed.  It does not parse the assembler
  315. instruction template and does not know what it means, or whether it is
  316. valid assembler input.  The extended `asm' feature is most often used
  317. for machine instructions that the compiler itself does not know exist.
  318.  
  319.    The output operands must be write-only; GNU CC will assume that the
  320. values in these operands before the instruction are dead and need not be
  321. generated.  Extended asm does not support input-output or read-write
  322. operands.  For this reason, the constraint character `+', which
  323. indicates such an operand, may not be used.
  324.  
  325.    When the assembler instruction has a read-write operand, or an
  326. operand in which only some of the bits are to be changed, you must
  327. logically split its function into two separate operands, one input
  328. operand and one write-only output operand.  The connection between them
  329. is expressed by constraints which say they need to be in the same
  330. location when the instruction executes.  You can use the same C
  331. expression for both operands, or different expressions.  For example,
  332. here we write the (fictitious) `combine' instruction with `bar' as its
  333. read-only source operand and `foo' as its read-write destination:
  334.  
  335.      asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar));
  336.  
  337. The constraint `"0"' for operand 1 says that it must occupy the same
  338. location as operand 0.  A digit in constraint is allowed only in an
  339. input operand, and it must refer to an output operand.
  340.  
  341.    Only a digit in the constraint can guarantee that one operand will
  342. be in the same place as another.  The mere fact that `foo' is the value
  343. of both operands is not enough to guarantee that they will be in the
  344. same place in the generated assembler code.  The following would not
  345. work:
  346.  
  347.      asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar));
  348.  
  349.    Various optimizations or reloading could cause operands 0 and 1 to
  350. be in different registers; GNU CC knows no reason not to do so.  For
  351. example, the compiler might find a copy of the value of `foo' in one
  352. register and use it for operand 1, but generate the output operand 0 in
  353. a different register (copying it afterward to `foo''s own address).  Of
  354. course, since the register for operand 1 is not even mentioned in the
  355. assembler code, the result will not work, but GNU CC can't tell that.
  356.  
  357.    Some instructions clobber specific hard registers.  To describe
  358. this, write a third colon after the input operands, followed by the
  359. names of the clobbered hard registers (given as strings).  Here is a
  360. realistic example for the Vax:
  361.  
  362.      asm volatile ("movc3 %0,%1,%2"
  363.                    : /* no outputs */
  364.                    : "g" (from), "g" (to), "g" (count)
  365.                    : "r0", "r1", "r2", "r3", "r4", "r5");
  366.  
  367.    If you refer to a particular hardware register from the assembler
  368. code, then you will probably have to list the register after the third
  369. colon to tell the compiler that the register's value is modified.  In
  370. many assemblers, the register names begin with `%'; to produce one `%'
  371. in the assembler code, you must write `%%' in the input.
  372.  
  373.    If your assembler instruction can alter the condition code register,
  374. add `cc' to the list of clobbered registers.  GNU CC on some machines
  375. represents the condition codes as a specific hardware register; `cc'
  376. serves to name this register.  On other machines, the condition code is
  377. handled differently, and specifying `cc' has no effect.  But it is
  378. valid no matter what the machine.
  379.  
  380.    If your assembler instruction modifies memory in an unpredicable
  381. fashion, add `memory' to the list of clobbered registers. This will
  382. cause GNU CC to not keep memory values cached in registers across the
  383. assembler instruction.
  384.  
  385.    You can put multiple assembler instructions together in a single
  386. `asm' template, separated either with newlines (written as `\n') or with
  387. semicolons if the assembler allows such semicolons.  The GNU assembler
  388. allows semicolons and all Unix assemblers seem to do so.  The input
  389. operands are guaranteed not to use any of the clobbered registers, and
  390. neither will the output operands' addresses, so you can read and write
  391. the clobbered registers as many times as you like.  Here is an example
  392. of multiple instructions in a template; it assumes that the subroutine
  393. `_foo' accepts arguments in registers 9 and 10:
  394.  
  395.      asm ("movl %0,r9;movl %1,r10;call _foo"
  396.           : /* no outputs */
  397.           : "g" (from), "g" (to)
  398.           : "r9", "r10");
  399.  
  400.    Unless an output operand has the `&' constraint modifier, GNU CC may
  401. allocate it in the same register as an unrelated input operand, on the
  402. assumption that the inputs are consumed before the outputs are produced.
  403. This assumption may be false if the assembler code actually consists of
  404. more than one instruction.  In such a case, use `&' for each output
  405. operand that may not overlap an input. *Note Modifiers::.
  406.  
  407.    If you want to test the condition code produced by an assembler
  408. instruction, you must include a branch and a label in the `asm'
  409. construct, as follows:
  410.  
  411.      asm ("clr %0;frob %1;beq 0f;mov #1,%0;0:"
  412.           : "g" (result)
  413.           : "g" (input));
  414.  
  415. This assumes your assembler supports local labels, as the GNU assembler
  416. and most Unix assemblers do.
  417.  
  418.    Usually the most convenient way to use these `asm' instructions is to
  419. encapsulate them in macros that look like functions.  For example,
  420.  
  421.      #define sin(x)       \
  422.      ({ double __value, __arg = (x);   \
  423.         asm ("fsinx %1,%0": "=f" (__value): "f" (__arg));  \
  424.         __value; })
  425.  
  426. Here the variable `__arg' is used to make sure that the instruction
  427. operates on a proper `double' value, and to accept only those arguments
  428. `x' which can convert automatically to a `double'.
  429.  
  430.    Another way to make sure the instruction operates on the correct
  431. data type is to use a cast in the `asm'.  This is different from using a
  432. variable `__arg' in that it converts more different types.  For
  433. example, if the desired type were `int', casting the argument to `int'
  434. would accept a pointer with no complaint, while assigning the argument
  435. to an `int' variable named `__arg' would warn about using a pointer
  436. unless the caller explicitly casts it.
  437.  
  438.    If an `asm' has output operands, GNU CC assumes for optimization
  439. purposes that the instruction has no side effects except to change the
  440. output operands.  This does not mean that instructions with a side
  441. effect cannot be used, but you must be careful, because the compiler
  442. may eliminate them if the output operands aren't used, or move them out
  443. of loops, or replace two with one if they constitute a common
  444. subexpression.  Also, if your instruction does have a side effect on a
  445. variable that otherwise appears not to change, the old value of the
  446. variable may be reused later if it happens to be found in a register.
  447.  
  448.    You can prevent an `asm' instruction from being deleted, moved
  449. significantly, or combined, by writing the keyword `volatile' after the
  450. `asm'.  For example:
  451.  
  452.      #define set_priority(x)  \
  453.      asm volatile ("set_priority %0": /* no outputs */ : "g" (x))
  454.  
  455. An instruction without output operands will not be deleted or moved
  456. significantly, regardless, unless it is unreachable.
  457.  
  458.    Note that even a volatile `asm' instruction can be moved in ways
  459. that appear insignificant to the compiler, such as across jump
  460. instructions.  You can't expect a sequence of volatile `asm'
  461. instructions to remain perfectly consecutive.  If you want consecutive
  462. output, use a single `asm'.
  463.  
  464.    It is a natural idea to look for a way to give access to the
  465. condition code left by the assembler instruction.  However, when we
  466. attempted to implement this, we found no way to make it work reliably. 
  467. The problem is that output operands might need reloading, which would
  468. result in additional following "store" instructions.  On most machines,
  469. these instructions would alter the condition code before there was time
  470. to test it.  This problem doesn't arise for ordinary "test" and
  471. "compare" instructions because they don't have any output operands.
  472.  
  473.    If you are writing a header file that should be includable in ANSI C
  474. programs, write `__asm__' instead of `asm'.  *Note Alternate Keywords::.
  475.  
  476. 
  477. File: gcc.info,  Node: Asm Labels,  Next: Explicit Reg Vars,  Prev: Extended Asm,  Up: Extensions
  478.  
  479. Controlling Names Used in Assembler Code
  480. ========================================
  481.  
  482.    You can specify the name to be used in the assembler code for a C
  483. function or variable by writing the `asm' (or `__asm__') keyword after
  484. the declarator as follows:
  485.  
  486.      int foo asm ("myfoo") = 2;
  487.  
  488. This specifies that the name to be used for the variable `foo' in the
  489. assembler code should be `myfoo' rather than the usual `_foo'.
  490.  
  491.    On systems where an underscore is normally prepended to the name of
  492. a C function or variable, this feature allows you to define names for
  493. the linker that do not start with an underscore.
  494.  
  495.    You cannot use `asm' in this way in a function *definition*; but you
  496. can get the same effect by writing a declaration for the function
  497. before its definition and putting `asm' there, like this:
  498.  
  499.      extern func () asm ("FUNC");
  500.      
  501.      func (x, y)
  502.           int x, y;
  503.      ...
  504.  
  505.    It is up to you to make sure that the assembler names you choose do
  506. not conflict with any other assembler symbols.  Also, you must not use a
  507. register name; that would produce completely invalid assembler code. 
  508. GNU CC does not as yet have the ability to store static variables in
  509. registers. Perhaps that will be added.
  510.  
  511. 
  512. File: gcc.info,  Node: Explicit Reg Vars,  Next: Alternate Keywords,  Prev: Asm Labels,  Up: Extensions
  513.  
  514. Variables in Specified Registers
  515. ================================
  516.  
  517.    GNU C allows you to put a few global variables into specified
  518. hardware registers.  You can also specify the register in which an
  519. ordinary register variable should be allocated.
  520.  
  521.    * Global register variables reserve registers throughout the program.
  522.      This may be useful in programs such as programming language
  523.      interpreters which have a couple of global variables that are
  524.      accessed very often.
  525.  
  526.    * Local register variables in specific registers do not reserve the
  527.      registers.  The compiler's data flow analysis is capable of
  528.      determining where the specified registers contain live values, and
  529.      where they are available for other uses.
  530.  
  531.      These local variables are sometimes convenient for use with the
  532.      extended `asm' feature (*note Extended Asm::.), if you want to
  533.      write one output of the assembler instruction directly into a
  534.      particular register. (This will work provided the register you
  535.      specify fits the constraints specified for that operand in the
  536.      `asm'.)
  537.  
  538. * Menu:
  539.  
  540. * Global Reg Vars::
  541. * Local Reg Vars::
  542.  
  543. 
  544. File: gcc.info,  Node: Global Reg Vars,  Next: Local Reg Vars,  Up: Explicit Reg Vars
  545.  
  546. Defining Global Register Variables
  547. ----------------------------------
  548.  
  549.    You can define a global register variable in GNU C like this:
  550.  
  551.      register int *foo asm ("a5");
  552.  
  553. Here `a5' is the name of the register which should be used.  Choose a
  554. register which is normally saved and restored by function calls on your
  555. machine, so that library routines will not clobber it.
  556.  
  557.    Naturally the register name is cpu-dependent, so you would need to
  558. conditionalize your program according to cpu type.  The register `a5'
  559. would be a good choice on a 68000 for a variable of pointer type.  On
  560. machines with register windows, be sure to choose a "global" register
  561. that is not affected magically by the function call mechanism.
  562.  
  563.    In addition, operating systems on one type of cpu may differ in how
  564. they name the registers; then you would need additional conditionals. 
  565. For example, some 68000 operating systems call this register `%a5'.
  566.  
  567.    Eventually there may be a way of asking the compiler to choose a
  568. register automatically, but first we need to figure out how it should
  569. choose and how to enable you to guide the choice.  No solution is
  570. evident.
  571.  
  572.    Defining a global register variable in a certain register reserves
  573. that register entirely for this use, at least within the current
  574. compilation. The register will not be allocated for any other purpose
  575. in the functions in the current compilation.  The register will not be
  576. saved and restored by these functions.  Stores into this register are
  577. never deleted even if they would appear to be dead, but references may
  578. be deleted or moved or simplified.
  579.  
  580.    It is not safe to access the global register variables from signal
  581. handlers, or from more than one thread of control, because the system
  582. library routines may temporarily use the register for other things
  583. (unless you recompile them specially for the task at hand).
  584.  
  585.    It is not safe for one function that uses a global register variable
  586. to call another such function `foo' by way of a third function `lose'
  587. that was compiled without knowledge of this variable (i.e. in a
  588. different source file in which the variable wasn't declared).  This is
  589. because `lose' might save the register and put some other value there.
  590. For example, you can't expect a global register variable to be
  591. available in the comparison-function that you pass to `qsort', since
  592. `qsort' might have put something else in that register.  (If you are
  593. prepared to recompile `qsort' with the same global register variable,
  594. you can solve this problem.)
  595.  
  596.    If you want to recompile `qsort' or other source files which do not
  597. actually use your global register variable, so that they will not use
  598. that register for any other purpose, then it suffices to specify the
  599. compiler option `-ffixed-REG'.  You need not actually add a global
  600. register declaration to their source code.
  601.  
  602.    A function which can alter the value of a global register variable
  603. cannot safely be called from a function compiled without this variable,
  604. because it could clobber the value the caller expects to find there on
  605. return. Therefore, the function which is the entry point into the part
  606. of the program that uses the global register variable must explicitly
  607. save and restore the value which belongs to its caller.
  608.  
  609.    On most machines, `longjmp' will restore to each global register
  610. variable the value it had at the time of the `setjmp'.  On some
  611. machines, however, `longjmp' will not change the value of global
  612. register variables.  To be portable, the function that called `setjmp'
  613. should make other arrangements to save the values of the global register
  614. variables, and to restore them in a `longjmp'.  This way, the same
  615. thing will happen regardless of what `longjmp' does.
  616.  
  617.    All global register variable declarations must precede all function
  618. definitions.  If such a declaration could appear after function
  619. definitions, the declaration would be too late to prevent the register
  620. from being used for other purposes in the preceding functions.
  621.  
  622.    Global register variables may not have initial values, because an
  623. executable file has no means to supply initial contents for a register.
  624.  
  625.    On the Sparc, there are reports that g3 ... g7 are suitable
  626. registers, but certain library functions, such as `getwd', as well as
  627. the subroutines for division and remainder, modify g3 and g4.  g1 and
  628. g2 are local temporaries.
  629.  
  630.    On the 68000, a2 ... a5 should be suitable, as should d2 ... d7. Of
  631. course, it will not do to use more than a few of those.
  632.  
  633. 
  634. File: gcc.info,  Node: Local Reg Vars,  Prev: Global Reg Vars,  Up: Explicit Reg Vars
  635.  
  636. Specifying Registers for Local Variables
  637. ----------------------------------------
  638.  
  639.    You can define a local register variable with a specified register
  640. like this:
  641.  
  642.      register int *foo asm ("a5");
  643.  
  644. Here `a5' is the name of the register which should be used.  Note that
  645. this is the same syntax used for defining global register variables,
  646. but for a local variable it would appear within a function.
  647.  
  648.    Naturally the register name is cpu-dependent, but this is not a
  649. problem, since specific registers are most often useful with explicit
  650. assembler instructions (*note Extended Asm::.).  Both of these things
  651. generally require that you conditionalize your program according to cpu
  652. type.
  653.  
  654.    In addition, operating systems on one type of cpu may differ in how
  655. they name the registers; then you would need additional conditionals. 
  656. For example, some 68000 operating systems call this register `%a5'.
  657.  
  658.    Eventually there may be a way of asking the compiler to choose a
  659. register automatically, but first we need to figure out how it should
  660. choose and how to enable you to guide the choice.  No solution is
  661. evident.
  662.  
  663.    Defining such a register variable does not reserve the register; it
  664. remains available for other uses in places where flow control determines
  665. the variable's value is not live.  However, these registers are made
  666. unavailable for use in the reload pass.  I would not be surprised if
  667. excessive use of this feature leaves the compiler too few available
  668. registers to compile certain functions.
  669.  
  670. 
  671. File: gcc.info,  Node: Alternate Keywords,  Next: Incomplete Enums,  Prev: Explicit Reg Vars,  Up: Extensions
  672.  
  673. Alternate Keywords
  674. ==================
  675.  
  676.    The option `-traditional' disables certain keywords; `-ansi'
  677. disables certain others.  This causes trouble when you want to use GNU C
  678. extensions, or ANSI C features, in a general-purpose header file that
  679. should be usable by all programs, including ANSI C programs and
  680. traditional ones.  The keywords `asm', `typeof' and `inline' cannot be
  681. used since they won't work in a program compiled with `-ansi', while
  682. the keywords `const', `volatile', `signed', `typeof' and `inline' won't
  683. work in a program compiled with `-traditional'.
  684.  
  685.    The way to solve these problems is to put `__' at the beginning and
  686. end of each problematical keyword.  For example, use `__asm__' instead
  687. of `asm', `__const__' instead of `const', and `__inline__' instead of
  688. `inline'.
  689.  
  690.    Other C compilers won't accept these alternative keywords; if you
  691. want to compile with another compiler, you can define the alternate
  692. keywords as macros to replace them with the customary keywords.  It
  693. looks like this:
  694.  
  695.      #ifndef __GNUC__
  696.      #define __asm__ asm
  697.      #endif
  698.  
  699.    `-pedantic' causes warnings for many GNU C extensions.  You can
  700. prevent such warnings within one expression by writing `__extension__'
  701. before the expression.  `__extension__' has no effect aside from this.
  702.  
  703. 
  704. File: gcc.info,  Node: Incomplete Enums,  Prev: Alternate Keywords,  Up: Extensions
  705.  
  706. Incomplete `enum' Types
  707. =======================
  708.  
  709.    You can define an `enum' tag without specifying its possible values.
  710. This results in an incomplete type, much like what you get if you write
  711. `struct foo' without describing the elements.  A later declaration
  712. which does specify the possible values completes the type.
  713.  
  714.    You can't allocate variables or storage using the type while it is
  715. incomplete.  However, you can work with pointers to that type.
  716.  
  717.    This extension may not be very useful, but it makes the handling of
  718. `enum' more consistent with the way `struct' and `union' are handled.
  719.  
  720. 
  721. File: gcc.info,  Node: Trouble,  Next: Bugs,  Prev: Extensions,  Up: Top
  722.  
  723. Known Causes of Trouble with GNU CC
  724. ***********************************
  725.  
  726.    This section describes known problems that affect users of GNU CC. 
  727. Most of these are not GNU CC bugs per se--if they were, we would fix
  728. them. But the result for a user may be like the result of a bug.
  729.  
  730.    Some of these problems are due to bugs in other software, some are
  731. missing features that are too much work to add, and some are places
  732. where people's opinions differ as to what is best.
  733.  
  734. * Menu:
  735.  
  736. * Actual Bugs::              Bugs we will fix later.
  737. * Installation Problems::     Problems that manifest when you install GNU CC.
  738. * Cross-Compiler Problems::   Common problems of cross compiling with GNU CC.
  739. * Interoperation::      Problems using GNU CC with other compilers,
  740.                and with certain linkers, assemblers and debuggers.
  741. * Incompatibilities::   GNU CC is incompatible with traditional C.
  742. * Disappointments::     Regrettable things we can't change, but not quite bugs.
  743. * Protoize Caveats::    Things to watch out for when using `protoize'.
  744. * Non-bugs::        Things we think are right, but some others disagree.
  745.  
  746. 
  747. File: gcc.info,  Node: Actual Bugs,  Next: Installation Problems,  Up: Trouble
  748.  
  749. Actual Bugs We Haven't Fixed Yet
  750. ================================
  751.  
  752.    * Loop unrolling doesn't work properly for certain C++ programs. 
  753.      This is because of difficulty in updating the debugging
  754.      information within the loop being unrolled.  We plan to revamp the
  755.      representation of debugging information so that this will work
  756.      properly, but we have not done this in version 2.3 because we
  757.      don't want to delay it any further.
  758.  
  759. 
  760. File: gcc.info,  Node: Installation Problems,  Next: Cross-Compiler Problems,  Prev: Actual Bugs,  Up: Trouble
  761.  
  762. Installation Problems
  763. =====================
  764.  
  765.    This is a list of problems (and some apparent problems which don't
  766. really mean anything is wrong) that show up during installation of GNU
  767. CC.
  768.  
  769.    * On certain systems, defining certain environment variables such as
  770.      `CC' can interfere with the functioning of `make'.
  771.  
  772.    * If you encounter seemingly strange errors when trying to build the
  773.      compiler in a directory other than the source directory, it could
  774.      be because you have previously configured the compiler in the
  775.      source directory.  Make sure you have done all the necessary
  776.      preparations. *Note Other Dir::.
  777.  
  778.    * In previous versions of GNU CC, the `gcc' driver program looked for
  779.      `as' and `ld' in various places such as files beginning with
  780.      `/usr/local/lib/gcc-'.  GNU CC version 2 looks for them in the
  781.      directory `/usr/local/lib/gcc-lib/TARGET/VERSION'.
  782.  
  783.      Thus, to use a version of `as' or `ld' that is not the system
  784.      default, for example `gas' or GNU `ld', you must put them in that
  785.      directory (or make links to them from that directory).
  786.  
  787.    * Some commands executed when making the compiler may fail (return a
  788.      non-zero status) and be ignored by `make'.  These failures, which
  789.      are often due to files that were not found, are expected, and can
  790.      safely be ignored.
  791.  
  792.    * It is normal to have warnings in compiling certain files about
  793.      unreachable code and about enumeration type clashes.  These files'
  794.      names begin with `insn-'.
  795.  
  796.    * Sometimes `make' recompiles parts of the compiler when installing
  797.      the compiler.  In one case, this was traced down to a bug in
  798.      `make'.  Either ignore the problem or switch to GNU Make.
  799.  
  800.    * On some 386 systems, building the compiler never finishes because
  801.      `enquire' hangs due to a hardware problem in the motherboard--it
  802.      reports floating point exceptions to the kernel incorrectly.  You
  803.      can install GNU CC except for `float.h' by patching out the
  804.      command to run `enquire'.  You may also be able to fix the problem
  805.      for real by getting a replacement motherboard.  This problem was
  806.      observed in Revision E of the Micronics motherboard, and is fixed
  807.      in Revision F.
  808.  
  809.    * Sometimes on a Sun 4 you may observe a crash in the program
  810.      `genflags' or `genoutput' while building GNU CC.  This is said to
  811.      be due to a bug in `sh'.  You can probably get around it by running
  812.      `genflags' or `genoutput' manually and then retrying the `make'.
  813.  
  814.    * If you use the 1.31 version of the MIPS assembler (such as was
  815.      shipped with Ultrix 3.1), you will need to use the
  816.      -fno-delayed-branch switch when optimizing floating point code. 
  817.      Otherwise, the assembler will complain when the GCC compiler fills
  818.      a branch delay slot with a floating point instruction, such as
  819.      add.d.
  820.  
  821.    * Users have reported some problems with version 2.0 of the MIPS
  822.      compiler tools that were shipped with Ultrix 4.1.  Version 2.10
  823.      which came with Ultrix 4.2 seems to work fine.
  824.  
  825.    * Some versions of the MIPS linker will issue an assertion failure
  826.      when linking code that uses `alloca' against shared libraries on
  827.      RISC-OS 5.0, and DEC's OSF/1 systems.  This is a bug in the
  828.      linker, that is supposed to be fixed in future revisions. To
  829.      protect against this, GCC passes `-non_shared' to the linker
  830.      unless you pass an explicit `-shared' switch.
  831.  
  832.    * On System V release 3, you may get this error message while
  833.      linking:
  834.  
  835.           ld fatal: failed to write symbol name SOMETHING
  836.            in strings table for file WHATEVER
  837.  
  838.      This indicates that the disk is full or your ULIMIT won't allow
  839.      the file to be as large as it needs to be.
  840.  
  841.    * On HP 9000 series 300 or 400 running HP-UX release 8.0, there is a
  842.      bug in the assembler that must be fixed before GNU CC can be
  843.      built.  This bug manifests itself during the first stage of
  844.      compilation, while building `libgcc2.a':
  845.  
  846.           _floatdisf
  847.           cc1: warning: `-g' option not supported on this version of GCC
  848.           cc1: warning: `-g1' option not supported on this version of GCC
  849.           ./gcc: Internal compiler error: program as got fatal signal 11
  850.  
  851.      A patched version of the assembler is available by anonymous ftp
  852.      from `altdorf.ai.mit.edu' as the file
  853.      `archive/cph/hpux-8.0-assembler'.  If you have HP software support,
  854.      the patch can also be obtained directly from HP, as described in
  855.      the following note:
  856.  
  857.           This is the patched assembler, to patch SR#1653-010439, where
  858.           the assembler aborts on floating point constants.
  859.  
  860.           The bug is not really in the assembler, but in the shared
  861.           library version of the function "cvtnum(3c)".  The bug on
  862.           "cvtnum(3c)" is SR#4701-078451.  Anyway, the attached
  863.           assembler uses the archive library version of "cvtnum(3c)"
  864.           and thus does not exhibit the bug.
  865.  
  866.      This patch is also known as PHCO_0800.
  867.  
  868.    * Another assembler problem on the HP PA results in an error message
  869.      like this while compiling part of `libgcc2.a':
  870.  
  871.           as: /usr/tmp/cca08196.s @line#30 [err#1060]
  872.             Argument 1 or 3 in FARG upper
  873.                    - lookahead = RTNVAL=GR
  874.  
  875.      This happens because HP changed the assembler syntax after system
  876.      release 8.02.  GNU CC assumes the newer syntax; if your assembler
  877.      wants the older syntax, comment out this line in the file
  878.      `pa1-hpux.h':
  879.  
  880.           #define HP_FP_ARG_DESCRIPTOR_REVERSED
  881.  
  882.    * Some versions of the Pyramid C compiler are reported to be unable
  883.      to compile GNU CC.  You must use an older version of GNU CC for
  884.      bootstrapping.  One indication of this problem is if you get a
  885.      crash when GNU CC compiles the function `muldi3' in file
  886.      `libgcc2.c'.
  887.  
  888.      You may be able to succeed by getting GNU CC version 1, installing
  889.      it, and using it to compile GNU CC version 2.  The bug in the
  890.      Pyramid C compiler does not seem to affect GNU CC version 1.
  891.  
  892.    * On the Tower models 4N0 and 6N0, by default a process is not
  893.      allowed to have more than one megabyte of memory.  GNU CC cannot
  894.      compile itself (or many other programs) with `-O' in that much
  895.      memory.
  896.  
  897.      To solve this problem, reconfigure the kernel adding the following
  898.      line to the configuration file:
  899.  
  900.           MAXUMEM = 4096
  901.  
  902.    * On the Altos 3068, programs compiled with GNU CC won't work unless
  903.      you fix a kernel bug.  This happens using system versions V.2.2
  904.      1.0gT1 and V.2.2 1.0e and perhaps later versions as well.  See the
  905.      file `README.ALTOS'.
  906.  
  907.    * You will get several sorts of compilation and linking errors on the
  908.      we32k if you don't follow the special instructions.  *Note WE32K
  909.      Install::.
  910.  
  911. 
  912. File: gcc.info,  Node: Cross-Compiler Problems,  Next: Interoperation,  Prev: Installation Problems,  Up: Trouble
  913.  
  914. Cross-Compiler Problems
  915. =======================
  916.  
  917.    * Cross compilation can run into trouble for certain machines because
  918.      some target machines' assemblers require floating point numbers to
  919.      be written as *integer* constants in certain contexts.
  920.  
  921.      The compiler writes these integer constants by examining the
  922.      floating point value as an integer and printing that integer,
  923.      because this is simple to write and independent of the details of
  924.      the floating point representation.  But this does not work if the
  925.      compiler is running on a different machine with an incompatible
  926.      floating point format, or even a different byte-ordering.
  927.  
  928.      In addition, correct constant folding of floating point values
  929.      requires representing them in the target machine's format. (The C
  930.      standard does not quite require this, but in practice it is the
  931.      only way to win.)
  932.  
  933.      It is now possible to overcome these problems by defining macros
  934.      such as `REAL_VALUE_TYPE'.  But doing so is a substantial amount of
  935.      work for each target machine.  *Note Cross-compilation::.
  936.  
  937.    * At present, the program `mips-tfile' which adds debug support to
  938.      object files on MIPS systems does not work in a cross compile
  939.      environment.
  940.  
  941.