s brings rev 1.2 (document printf0()) into GCC 2.95.1.

svn path=/head/; revision=52560

contrib/gcc/extend.texi

@@ -1,7 +1,9 @@
-@c Copyright (C) 1988,89,92,93,94,96 Free Software Foundation, Inc.
+@c Copyright (C) 1988,89,92,93,94,96,99 Free Software Foundation, Inc.
 @c This is part of the GCC manual.
 @c For copying conditions, see the file gcc.texi.
 
+@c $FreeBSD$
+
 @node C Extensions
 @chapter Extensions to the C Language Family
 @cindex extensions, C language
@@ -33,6 +35,7 @@ C++ Language}, for extensions that apply @emph{only} to C++.
 * Conditionals::        Omitting the middle operand of a @samp{?:} expression.
 * Long Long::		Double-word integers---@code{long long int}.
 * Complex::             Data types for complex numbers.
+* Hex Floats::          Hexadecimal floating-point constants.
 * Zero Length::         Zero-length arrays.
 * Variable Length::     Arrays whose length is computed at run time.
 * Macro Varargs::	Macros with variable number of arguments.
@@ -63,6 +66,8 @@ C++ Language}, for extensions that apply @emph{only} to C++.
 * Function Names::	Printable strings which are the name of the current
 			 function.
 * Return Address::      Getting the return or frame address of a function.
+* Other Builtins::      Other built-in functions.
+* Deprecated Features:: Things might disappear from g++.
 @end menu
 @end ifset
 @ifclear INTERNALS
@@ -78,6 +83,7 @@ C++ Language}, for extensions that apply @emph{only} to C++.
 * Conditionals::        Omitting the middle operand of a @samp{?:} expression.
 * Long Long::		Double-word integers---@code{long long int}.
 * Complex::             Data types for complex numbers.
+* Hex Floats::          Hexadecimal floating-point constants.
 * Zero Length::         Zero-length arrays.
 * Variable Length::     Arrays whose length is computed at run time.
 * Macro Varargs::	Macros with variable number of arguments.
@@ -109,6 +115,7 @@ C++ Language}, for extensions that apply @emph{only} to C++.
 * Function Names::	Printable strings which are the name of the current
 			 function.
 * Return Address::      Getting the return or frame address of a function.
+* Deprecated Features:: Things might disappear from g++.
 @end menu
 @end ifclear
 
@@ -791,6 +798,24 @@ examine and set these two fictitious variables with your debugger.
 A future version of GDB will know how to recognize such pairs and treat
 them as a single variable with a complex type.
 
+@node Hex Floats
+@section Hex Floats
+@cindex hex floats
+GNU CC recognizes floating-point numbers written not only in the usual
+decimal notation, such as @code{1.55e1}, but also numbers such as
+@code{0x1.fp3} written in hexadecimal format.  In that format the
+@code{0x} hex introducer and the @code{p} or @code{P} exponent field are
+mandatory.  The exponent is a decimal number that indicates the power of
+2 by which the significand part will be multiplied.  Thus @code{0x1.f} is
+1 15/16, @code{p3} multiplies it by 8, and the value of @code{0x1.fp3}
+is the same as @code{1.55e1}.
+
+Unlike for floating-point numbers in the decimal notation the exponent
+is always required in the hexadecimal notation.  Otherwise the compiler
+would not be able to resolve the ambiguity of, e.g., @code{0x1.f}.  This
+could mean @code{1.0f} or @code{1.9375} since @code{f} is also the
+extension for floating-point constants of type @code{float}.
+
 @node Zero Length
 @section Arrays of Length Zero
 @cindex arrays of length zero
@@ -1286,8 +1311,9 @@ carefully.
 
 The keyword @code{__attribute__} allows you to specify special
 attributes when making a declaration.  This keyword is followed by an
-attribute specification inside double parentheses.  Eight attributes,
-@code{noreturn}, @code{const}, @code{format}, @code{section},
+attribute specification inside double parentheses.  Nine attributes,
+@code{noreturn}, @code{const}, @code{format},
+@code{no_instrument_function}, @code{section},
 @code{constructor}, @code{destructor}, @code{unused} and @code{weak} are
 currently defined for functions.  Other attributes, including
 @code{section} are supported for variables declarations (@pxref{Variable
@@ -1448,6 +1474,12 @@ operands are a call to one of your own function.  The compiler always
 treats @code{gettext}, @code{dgettext}, and @code{dcgettext} in this
 manner.
 
+@item no_instrument_function
+@cindex @code{no_instrument_function} function attribute
+If @samp{-finstrument-functions} is given, profiling function calls will
+be generated at entry and exit of most user-compiled functions.
+Functions with this attribute will not be so instrumented.
+
 @item section ("section-name")
 @cindex @code{section} function attribute
 Normally, the compiler places the code it generates in the @code{text} section.
@@ -1512,6 +1544,19 @@ mangled name for the target must be used.
 
 Not all target machines support this attribute.
 
+@item no_check_memory_usage
+@cindex @code{no_check_memory_usage} function attribute
+If @samp{-fcheck-memory-usage} is given, calls to support routines will
+be generated before most memory accesses, to permit support code to
+record usage and detect uses of uninitialized or unallocated storage.
+Since the compiler cannot handle them properly, @code{asm} statements
+are not allowed.  Declaring a function with this attribute disables the
+memory checking code for that function, permitting the use of @code{asm}
+statements without requiring separate compilation with different
+options, and allowing you to write support routines of your own if you
+wish, without getting infinite recursion if they get compiled with this
+option.
+
 @item regparm (@var{number})
 @cindex functions that are passed arguments in registers on the 386
 On the Intel 386, the @code{regparm} attribute causes the compiler to
@@ -2218,10 +2263,16 @@ inc (int *a)
 
 (If you are writing a header file to be included in ANSI C programs, write
 @code{__inline__} instead of @code{inline}.  @xref{Alternate Keywords}.)
-
 You can also make all ``simple enough'' functions inline with the option
-@samp{-finline-functions}.  Note that certain usages in a function
-definition can make it unsuitable for inline substitution.
+@samp{-finline-functions}. 
+
+Note that certain usages in a function definition can make it unsuitable
+for inline substitution.  Among these usages are: use of varargs, use of
+alloca, use of variable sized data types (@pxref{Variable Length}),
+use of computed goto (@pxref{Labels as Values}), use of nonlocal goto,
+and nested functions (@pxref{Nested Functions}).  Using @samp{-Winline}
+will warn when a function marked @code{inline} could not be substituted,
+and will give the reason for the failure.
 
 Note that in C and Objective C, unlike C++, the @code{inline} keyword
 does not affect the linkage of the function.
@@ -2385,6 +2436,14 @@ asm volatile ("movc3 %0,%1,%2"
               : "r0", "r1", "r2", "r3", "r4", "r5");
 @end example
 
+It is an error for a clobber description to overlap an input or output
+operand (for example, an operand describing a register class with one
+member, mentioned in the clobber list).  Most notably, it is invalid to
+describe that an input operand is modified, but unused as output.  It has
+to be specified as an input and output operand anyway.  Note that if there
+are only unused output operands, you will then also need to specify
+@code{volatile} for the @code{asm} construct, as described below.
+
 If you refer to a particular hardware register from the assembler code,
 you will probably have to list the register after the third colon to
 tell the compiler the register's value is modified.  In some assemblers,
@@ -2489,7 +2548,7 @@ the @code{asm}.  For example:
 (@{ int __old; \
    asm volatile ("get_and_set_priority %0, %1": "=g" (__old) : "g" (new)); \
    __old; @})
-b@end example
+@end example
 
 @noindent
 If you write an @code{asm} instruction with no outputs, GNU CC will know
@@ -2525,6 +2584,96 @@ If you are writing a header file that should be includable in ANSI C
 programs, write @code{__asm__} instead of @code{asm}.  @xref{Alternate
 Keywords}.
 
+@subsection i386 floating point asm operands
+
+There are several rules on the usage of stack-like regs in
+asm_operands insns.  These rules apply only to the operands that are
+stack-like regs:
+
+@enumerate
+@item
+Given a set of input regs that die in an asm_operands, it is
+necessary to know which are implicitly popped by the asm, and
+which must be explicitly popped by gcc.
+
+An input reg that is implicitly popped by the asm must be
+explicitly clobbered, unless it is constrained to match an
+output operand.
+
+@item
+For any input reg that is implicitly popped by an asm, it is
+necessary to know how to adjust the stack to compensate for the pop.
+If any non-popped input is closer to the top of the reg-stack than
+the implicitly popped reg, it would not be possible to know what the
+stack looked like --- it's not clear how the rest of the stack ``slides
+up''.
+
+All implicitly popped input regs must be closer to the top of
+the reg-stack than any input that is not implicitly popped.
+
+It is possible that if an input dies in an insn, reload might
+use the input reg for an output reload.  Consider this example:
+
+@example
+asm ("foo" : "=t" (a) : "f" (b));
+@end example
+
+This asm says that input B is not popped by the asm, and that
+the asm pushes a result onto the reg-stack, ie, the stack is one
+deeper after the asm than it was before.  But, it is possible that
+reload will think that it can use the same reg for both the input and
+the output, if input B dies in this insn.
+
+If any input operand uses the @code{f} constraint, all output reg
+constraints must use the @code{&} earlyclobber.
+
+The asm above would be written as
+
+@example
+asm ("foo" : "=&t" (a) : "f" (b));
+@end example
+
+@item
+Some operands need to be in particular places on the stack.  All
+output operands fall in this category --- there is no other way to
+know which regs the outputs appear in unless the user indicates
+this in the constraints.
+
+Output operands must specifically indicate which reg an output
+appears in after an asm.  @code{=f} is not allowed: the operand
+constraints must select a class with a single reg.
+
+@item
+Output operands may not be ``inserted'' between existing stack regs.
+Since no 387 opcode uses a read/write operand, all output operands
+are dead before the asm_operands, and are pushed by the asm_operands.
+It makes no sense to push anywhere but the top of the reg-stack.
+
+Output operands must start at the top of the reg-stack: output
+operands may not ``skip'' a reg.
+
+@item
+Some asm statements may need extra stack space for internal
+calculations.  This can be guaranteed by clobbering stack registers
+unrelated to the inputs and outputs.
+
+@end enumerate
+
+Here are a couple of reasonable asms to want to write.  This asm
+takes one input, which is internally popped, and produces two outputs.
+
+@example
+asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp));
+@end example
+
+This asm takes two inputs, which are popped by the @code{fyl2xp1} opcode,
+and replaces them with one output.  The user must code the @code{st(1)}
+clobber for reg-stack.c to know that @code{fyl2xp1} pops both inputs.
+
+@example
+asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)");
+@end example
+
 @ifclear INTERNALS
 @c Show the details on constraints if they do not appear elsewhere in
 @c the manual
@@ -2594,7 +2743,9 @@ very often.
 Local register variables in specific registers do not reserve the
 registers.  The compiler's data flow analysis is capable of determining
 where the specified registers contain live values, and where they are
-available for other uses.
+available for other uses.  Stores into local register variables may be deleted
+when they appear to be dead according to dataflow analysis.  References
+to local register variables may be deleted or moved or simplified.
 
 These local variables are sometimes convenient for use with the extended
 @code{asm} feature (@pxref{Extended Asm}), if you want to write one
@@ -2745,6 +2896,10 @@ this variable in the register you specify at all times.  You may not
 code an explicit reference to this register in an @code{asm} statement
 and assume it will always refer to this variable.
 
+Stores into local register variables may be deleted when they appear to be dead
+according to dataflow analysis.  References to local register variables may
+be deleted or moved or simplified.
+
 @node Alternate Keywords
 @section Alternate Keywords
 @cindex alternate keywords
@@ -2775,6 +2930,7 @@ macros to replace them with the customary keywords.  It looks like this:
 #endif
 @end example
 
+@findex __extension__
 @samp{-pedantic} causes warnings for many GNU C extensions.  You can
 prevent such warnings within one expression by writing
 @code{__extension__} before the expression.  @code{__extension__} has no
@@ -2851,6 +3007,7 @@ These functions may be used to get information about the callers of a
 function.
 
 @table @code
+@findex __builtin_return_address
 @item __builtin_return_address (@var{level})
 This function returns the return address of the current function, or of
 one of its callers.  The @var{level} argument is number of frames to
@@ -2867,6 +3024,7 @@ of the stack has been reached, this function will return @code{0}.
 This function should only be used with a non-zero argument for debugging
 purposes.
 
+@findex __builtin_frame_address
 @item __builtin_frame_address (@var{level})
 This function is similar to @code{__builtin_return_address}, but it
 returns the address of the function frame rather than the return address
@@ -2887,6 +3045,86 @@ The caveats that apply to @code{__builtin_return_address} apply to this
 function as well.
 @end table
 
+@node Other Builtins
+@section Other built-in functions provided by GNU CC
+
+GNU CC provides a large number of built-in functions other than the ones
+mentioned above.  Some of these are for internal use in the processing
+of exceptions or variable-length argument lists and will not be
+documented here because they may change from time to time; we do not
+recommend general use of these functions.
+
+The remaining functions are provided for optimization purposes.
+
+GNU CC includes builtin versions of many of the functions in the
+standard C library.  These will always be treated as having the same
+meaning as the C library function even if you specify the
+@samp{-fno-builtin} (@pxref{C Dialect Options}) option.  These functions
+correspond to the C library functions @code{alloca}, @code{ffs},
+@code{abs}, @code{fabsf}, @code{fabs}, @code{fabsl}, @code{labs},
+@code{memcpy}, @code{memcmp}, @code{strcmp}, @code{strcpy},
+@code{strlen}, @code{sqrtf}, @code{sqrt}, @code{sqrtl}, @code{sinf},
+@code{sin}, @code{sinl}, @code{cosf}, @code{cos}, and @code{cosl}.
+
+@findex __builtin_constant_p
+You can use the builtin function @code{__builtin_constant_p} to
+determine if a value is known to be constant at compile-time and hence
+that GNU CC can perform constant-folding on expressions involving that
+value.  The argument of the function is the value to test.  The function
+returns the integer 1 if the argument is known to be a compile-time
+constant and 0 if it is not known to be a compile-time constant.  A
+return of 0 does not indicate that the value is @emph{not} a constant,
+but merely that GNU CC cannot prove it is a constant with the specified
+value of the @samp{-O} option.
+
+You would typically use this function in an embedded application where
+memory was a critical resource.  If you have some complex calculation,
+you may want it to be folded if it involves constants, but need to call
+a function if it does not.  For example:
+
+@smallexample
+#define Scale_Value(X)  \
+  (__builtin_constant_p (X) ? ((X) * SCALE + OFFSET) : Scale (X))
+@end smallexample
+
+You may use this builtin function in either a macro or an inline
+function.  However, if you use it in an inlined function and pass an
+argument of the function as the argument to the builtin, GNU CC will
+never return 1 when you call the inline function with a string constant
+or constructor expression (@pxref{Constructors}) and will not return 1
+when you pass a constant numeric value to the inline function unless you
+specify the @samp{-O} option.
+
+@node Deprecated Features
+@section Deprecated Features
+
+In the past, the GNU C++ compiler was extended to experiment with new
+features, at a time when the C++ language was still evolving. Now that
+the C++ standard is complete, some of those features are superceded by
+superior alternatives. Using the old features might cause a warning in
+some cases that the feature will be dropped in the future. In other
+cases, the feature might be gone already.
+
+While the list below is not exhaustive, it documents some of the options
+that are now deprecated:
+
+@table @code
+@item -fthis-is-variable
+In early versions of C++, assignment to this could be used to implement
+application-defined memory allocation. Now, allocation functions
+(@samp{operator new}) are the standard-conforming way to achieve the
+same effect.
+
+@item -fexternal-templates
+@itemx -falt-external-templates
+These are two of the many ways for g++ to implement template
+instantiation. @xref{Template Instantiation}. The C++ standard clearly
+defines how template definitions have to be organized across
+implementation units. g++ has an implicit instantiation mechanism that
+should work just fine for standard-conforming code.
+
+@end table
+
 @node C++ Extensions
 @chapter Extensions to the C++ Language
 @cindex extensions, C++ language
@@ -2909,8 +3147,11 @@ Predefined Macros,cpp.info,The C Preprocessor}).
                          declarations and definitions.
 * Template Instantiation:: Methods for ensuring that exactly one copy of
                          each needed template instantiation is emitted.
+* Bound member functions:: You can extract a function pointer to the
+                        method denoted by a @samp{->*} or @samp{.*} expression.
 * C++ Signatures::	You can specify abstract types to get subtype
 			 polymorphism independent from inheritance.
+                        
 @end menu
 
 @node Naming Results
@@ -3318,14 +3559,12 @@ instances required by your explicit instantiations (but not by any
 other files) without having to specify them as well.
 
 g++ has extended the template instantiation syntax outlined in the
-Working Paper to allow forward declaration of explicit instantiations,
-explicit instantiation of members of template classes and instantiation
-of the compiler support data for a template class (i.e. the vtable)
-without instantiating any of its members:
+Working Paper to allow forward declaration of explicit instantiations
+and instantiation of the compiler support data for a template class
+(i.e. the vtable) without instantiating any of its members:
 
 @example
 extern template int max (int, int);
-template void Foo<int>::f ();
 inline template class Foo<int>;
 @end example
 
@@ -3372,6 +3611,40 @@ be the same in all translation units, or things are likely to break.
 more discussion of these pragmas.
 @end enumerate
 
+@node Bound member functions
+@section Extracting the function pointer from a bound pointer to member function
+
+@cindex pmf
+@cindex pointer to member function
+@cindex bound pointer to member function
+
+In C++, pointer to member functions (PMFs) are implemented using a wide
+pointer of sorts to handle all the possible call mechanisms; the PMF
+needs to store information about how to adjust the @samp{this} pointer,
+and if the function pointed to is virtual, where to find the vtable, and
+where in the vtable to look for the member function.  If you are using
+PMFs in an inner loop, you should really reconsider that decision.  If
+that is not an option, you can extract the pointer to the function that
+would be called for a given object/PMF pair and call it directly inside
+the inner loop, to save a bit of time.
+
+Note that you will still be paying the penalty for the call through a
+function pointer; on most modern architectures, such a call defeats the
+branch prediction features of the CPU.  This is also true of normal
+virtual function calls.
+
+The syntax for this extension is
+
+@example
+extern A a;
+extern int (A::*fp)();
+typedef int (*fptr)(A *);
+
+fptr p = (fptr)(a.*fp);
+@end example
+
+You must specify @samp{-Wno-pmf-conversions} to use this extension.
+
 @node C++ Signatures
 @section Type Abstraction using Signatures