gcc/doc/interface.texi

   1 @c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
   2 @c 1999, 2000, 2001 Free Software Foundation, Inc.
   3 @c This is part of the GCC manual.
   4 @c For copying conditions, see the file gcc.texi.
   5
   6 @node Interface
   7 @chapter Interfacing to GCC Output
   8 @cindex interfacing to GCC output
   9 @cindex run-time conventions
  10 @cindex function call conventions
  11 @cindex conventions, run-time
  12
  13 GCC is normally configured to use the same function calling convention
  14 normally in use on the target system.  This is done with the
  15 machine-description macros described (@pxref{Target Macros}).
  16
  17 @cindex unions, returning
  18 @cindex structures, returning
  19 @cindex returning structures and unions
  20 However, returning of structure and union values is done differently on
  21 some target machines.  As a result, functions compiled with PCC
  22 returning such types cannot be called from code compiled with GCC,
  23 and vice versa.  This does not cause trouble often because few Unix
  24 library routines return structures or unions.
  25
  26 GCC code returns structures and unions that are 1, 2, 4 or 8 bytes
  27 long in the same registers used for @code{int} or @code{double} return
  28 values.  (GCC typically allocates variables of such types in
  29 registers also.)  Structures and unions of other sizes are returned by
  30 storing them into an address passed by the caller (usually in a
  31 register).  The machine-description macros @code{STRUCT_VALUE} and
  32 @code{STRUCT_INCOMING_VALUE} tell GCC where to pass this address.
  33
  34 By contrast, PCC on most target machines returns structures and unions
  35 of any size by copying the data into an area of static storage, and then
  36 returning the address of that storage as if it were a pointer value.
  37 The caller must copy the data from that memory area to the place where
  38 the value is wanted.  This is slower than the method used by GCC, and
  39 fails to be reentrant.
  40
  41 On some target machines, such as RISC machines and the 80386, the
  42 standard system convention is to pass to the subroutine the address of
  43 where to return the value.  On these machines, GCC has been
  44 configured to be compatible with the standard compiler, when this method
  45 is used.  It may not be compatible for structures of 1, 2, 4 or 8 bytes.
  46
  47 @cindex argument passing
  48 @cindex passing arguments
  49 GCC uses the system's standard convention for passing arguments.  On
  50 some machines, the first few arguments are passed in registers; in
  51 others, all are passed on the stack.  It would be possible to use
  52 registers for argument passing on any machine, and this would probably
  53 result in a significant speedup.  But the result would be complete
  54 incompatibility with code that follows the standard convention.  So this
  55 change is practical only if you are switching to GCC as the sole C
  56 compiler for the system.  We may implement register argument passing on
  57 certain machines once we have a complete GNU system so that we can
  58 compile the libraries with GCC@.
  59
  60 On some machines (particularly the Sparc), certain types of arguments
  61 are passed ``by invisible reference''.  This means that the value is
  62 stored in memory, and the address of the memory location is passed to
  63 the subroutine.
  64
  65 @cindex @code{longjmp} and automatic variables
  66 If you use @code{longjmp}, beware of automatic variables.  ISO C says that
  67 automatic variables that are not declared @code{volatile} have undefined
  68 values after a @code{longjmp}.  And this is all GCC promises to do,
  69 because it is very difficult to restore register variables correctly, and
  70 one of GCC's features is that it can put variables in registers without
  71 your asking it to.
  72
  73 If you want a variable to be unaltered by @code{longjmp}, and you don't
  74 want to write @code{volatile} because old C compilers don't accept it,
  75 just take the address of the variable.  If a variable's address is ever
  76 taken, even if just to compute it and ignore it, then the variable cannot
  77 go in a register:
  78
  79 @example
  80 @{
  81   int careful;
  82   &careful;
  83   @dots{}
  84 @}
  85 @end example
  86
  87 @cindex arithmetic libraries
  88 @cindex math libraries
  89 @opindex msoft-float
  90 Code compiled with GCC may call certain library routines.  Most of
  91 them handle arithmetic for which there are no instructions.  This
  92 includes multiply and divide on some machines, and floating point
  93 operations on any machine for which floating point support is disabled
  94 with @option{-msoft-float}.  Some standard parts of the C library, such as
  95 @code{bcopy} or @code{memcpy}, are also called automatically.  The usual
  96 function call interface is used for calling the library routines.
  97
  98 Some of these routines can be defined in mostly machine-independent C;
  99 they appear in @file{libgcc2.c}.  Others must be hand-written in
 100 assembly language for each processor.  Wherever they are defined, they
 101 are compiled into the support library, @file{libgcc.a}, which is
 102 automatically searched when you link programs with GCC@.