extend.texi, [...]: Move documentation of builtin versions of C library functions to one place and...

	* extend.texi, invoke.texi: Move documentation of builtin versions
	of C library functions to one place and update.

From-SVN: r37355

3 files changed, 97 insertions, 47 deletions

diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index 428ce0a..9c16415 100644
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,3 +1,8 @@
+2000-11-10  Joseph S. Myers  <jsm28@cam.ac.uk>
+
+	* extend.texi, invoke.texi: Move documentation of builtin versions
+	of C library functions to one place and update.
+
 2000-11-09  Richard Henderson  <rth@redhat.com>
 
 	* fold-const.c (fold): Compare TYPE_MAIN_VARIANT rather than
diff --git a/gcc/extend.texi b/gcc/extend.texi
index 2c6b4d1..2de3a47 100644
--- a/gcc/extend.texi
+++ b/gcc/extend.texi
@@ -3225,6 +3225,47 @@ function as well.
 
 @node Other Builtins
 @section Other built-in functions provided by GNU CC
+@cindex builtin functions
+@findex __builtin_isgreater
+@findex __builtin_isgreaterequal
+@findex __builtin_isless
+@findex __builtin_islessequal
+@findex __builtin_islessgreater
+@findex __builtin_isunordered
+@findex abort
+@findex abs
+@findex alloca
+@findex bcmp
+@findex bzero
+@findex cos
+@findex cosf
+@findex cosl
+@findex exit
+@findex _exit
+@findex fabs
+@findex fabsf
+@findex fabsl
+@findex ffs
+@findex fputs
+@findex labs
+@findex llabs
+@findex memcmp
+@findex memcpy
+@findex memset
+@findex printf
+@findex sin
+@findex sinf
+@findex sinl
+@findex sqrt
+@findex sqrtf
+@findex sqrtl
+@findex strchr
+@findex strcmp
+@findex strcpy
+@findex strlen
+@findex strpbrk
+@findex strrchr
+@findex strstr
 
 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
@@ -3235,15 +3276,47 @@ 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{abort}, @code{abs},
-@code{alloca}, @code{cos}, @code{cosf}, @code{cosl}, @code{exit},
-@code{_exit}, @code{fabs}, @code{fabsf}, @code{fabsl}, @code{ffs},
-@code{labs}, @code{memcmp}, @code{memcpy}, @code{memset}, @code{sin},
-@code{sinf}, @code{sinl}, @code{sqrt}, @code{sqrtf}, @code{sqrtl},
-@code{strcmp}, @code{strcpy}, and @code{strlen}.
+standard C library.  The versions prefixed with @code{__builtin_} 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.  Many of these functions are only optimized in certain cases; if
+not optimized in a particular case, a call to the library function will
+be emitted.
+
+The functions @code{abort}, @code{exit}, and @code{_exit} are recognized
+and presumed not to return, but otherwise are not built in.
+@code{_exit} is not recognized in strict ISO C mode (@samp{-ansi},
+@samp{-std=c89} or @samp{-std=c99}).
+
+Outside strict ISO C mode, the functions @code{alloca}, @code{bcmp},
+@code{bzero}, and @code{ffs} may be handled as builtins.  Corresponding
+versions @code{__builtin_alloca}, @code{__builtin_bcmp},
+@code{__builtin_bzero}, and @code{__builtin_ffs} are also recognized in
+strict ISO C mode.
+
+The ISO C99 function @code{llabs} is handled as a builtin except in
+strict ISO C89 mode.  There are also builtin versions of the ISO C99
+functions @code{cosf}, @code{cosl}, @code{fabsf}, @code{fabsl},
+@code{sinf}, @code{sinl}, @code{sqrtf}, and @code{sqrtl}, that are
+recognized in any mode since ISO C89 reserves these names for the
+purpose to which ISO C99 puts them.  All these functions have
+corresponding versions prefixed with @code{__builtin_}.
+
+The following ISO C89 functions are recognized as builtins unless
+@samp{-fno-builtin} is specified: @code{abs}, @code{cos}, @code{fabs},
+@code{fputs}, @code{labs}, @code{memcmp}, @code{memcpy}, @code{memset},
+@code{printf}, @code{sin}, @code{sqrt}, @code{strchr}, @code{strcmp},
+@code{strcpy}, @code{strlen}, @code{strpbrk}, @code{strrchr}, and
+@code{strstr}.  All of these functions have corresponding versions
+prefixed with @code{__builtin_}, except that the version for @code{sqrt}
+is called @code{__builtin_fsqrt}.
+
+GNU CC provides builtin versions of the ISO C99 floating point
+comparison macros (that avoid raising exceptions for unordered
+operands): @code{__builtin_isgreater}, @code{__builtin_isgreaterequal},
+@code{__builtin_isless}, @code{__builtin_islessequal},
+@code{__builtin_islessgreater}, and @code{__builtin_isunordered}.
+
 
 @table @code
 @findex __builtin_constant_p
diff --git a/gcc/invoke.texi b/gcc/invoke.texi
index 00d4876..209cdea 100644
--- a/gcc/invoke.texi
+++ b/gcc/invoke.texi
@@ -727,8 +727,11 @@ from declaring certain functions or defining certain macros that the
 ANSI standard doesn't call for; this is to avoid interfering with any
 programs that might use these names for other things.
 
-The functions @code{alloca}, @code{abort}, @code{exit}, and
-@code{_exit} are not builtin functions when @samp{-ansi} is used.
+Functions which would normally be builtin but do not have semantics
+defined by ISO C (such as @code{alloca} and @code{ffs}) are not builtin
+functions with @samp{-ansi} is used.  @xref{Other Builtins,,Other
+built-in functions provided by GNU CC}, for details of the functions
+affected.
 
 @item -std=
 Determine the language standard.  A value for this option must be provided;
@@ -785,38 +788,11 @@ use the @samp{-fno-gnu-keywords} flag instead, which has the same effect.
 
 @item -fno-builtin
 @cindex builtin functions
-@findex abort
-@findex abs
-@findex alloca
-@findex cos
-@findex cosf
-@findex cosl
-@findex exit
-@findex _exit
-@findex fabs
-@findex fabsf
-@findex fabsl
-@findex ffs
-@findex labs
-@findex memcmp
-@findex memcpy
-@findex memset
-@findex sin
-@findex sinf
-@findex sinl
-@findex sqrt
-@findex sqrtf
-@findex sqrtl
-@findex strcmp
-@findex strcpy
-@findex strlen
-Don't recognize builtin functions that do not begin with @samp{__builtin_}
-as prefix.  Currently, the functions affected include @code{abort},
-@code{abs}, @code{alloca}, @code{cos}, @code{cosf}, @code{cosl},
-@code{exit}, @code{_exit}, @code{fabs}, @code{fabsf}, @code{fabsl},
-@code{ffs}, @code{labs}, @code{memcmp}, @code{memcpy}, @code{memset},
-@code{sin}, @code{sinf}, @code{sinl}, @code{sqrt}, @code{sqrtf},
-@code{sqrtl}, @code{strcmp}, @code{strcpy}, and @code{strlen}.
+Don't recognize builtin functions that do not begin with
+@samp{__builtin_} as prefix.  @xref{Other Builtins,,Other built-in
+functions provided by GNU CC}, for details of the functions affected,
+including those which are not builtin functions when @samp{-ansi} is
+used because they do not have an ISO standard meaning.
 
 GCC normally generates special code to handle certain builtin functions
 more efficiently; for instance, calls to @code{alloca} may become single
@@ -826,10 +802,6 @@ and faster, but since the function calls no longer appear as such, you
 cannot set a breakpoint on those calls, nor can you change the behavior
 of the functions by linking with a different library.
 
-The @samp{-ansi} option prevents @code{alloca}, @code{ffs} and @code{_exit}
-from being builtin functions, since these functions do not have an ANSI
-standard meaning.
-
 @item -fhosted
 @cindex hosted environment