Regenerate.

git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@18649 138bc75d-0d04-0410-961f-82ee72b054a4

1 files changed, 93 insertions, 10 deletions

diff --git a/gcc/f/intdoc.texi b/gcc/f/intdoc.texi
index cd086ac3239..7db02afc9a3 100644
--- a/gcc/f/intdoc.texi
+++ b/gcc/f/intdoc.texi
@@ -7373,7 +7373,7 @@ Loc(@var{Entity})
 @end example
 
 @noindent
-Loc: @code{INTEGER(KIND=0)} function.
+Loc: @code{INTEGER(KIND=7)} function.
 
 @noindent
 @var{Entity}: Any type; cannot be a constant or expression.
@@ -9260,7 +9260,7 @@ CALL Signal(@var{Number}, @var{Handler}, @var{Status})
 or dummy/global @code{INTEGER(KIND=1)} scalar.
 
 @noindent
-@var{Status}: @code{INTEGER(KIND=1)}; OPTIONAL; scalar; INTENT(OUT).
+@var{Status}: @code{INTEGER(KIND=7)}; OPTIONAL; scalar; INTENT(OUT).
 
 @noindent
 Intrinsic groups: @code{unix}.
@@ -9271,12 +9271,13 @@ Description:
 If @var{Handler} is a an @code{EXTERNAL} routine, arranges for it to be
 invoked with a single integer argument (of system-dependent length)
 when signal @var{Number} occurs.
-If @var{Number} is an integer, it can be
-used to turn off handling of signal @var{Handler} or revert to its default
+If @var{Handler} is an integer, it can be
+used to turn off handling of signal @var{Number} or revert to its default
 action.
 See @code{signal(2)}.
 
-Note that @var{Handler} will be called using C conventions, so its value in
+Note that @var{Handler} will be called using C conventions,
+so the value of its argument in Fortran terms
 Fortran terms is obtained by applying @code{%LOC()} (or @var{LOC()}) to it.
 
 The value returned by @code{signal(2)} is written to @var{Status}, if
@@ -9287,6 +9288,34 @@ Some non-GNU implementations of Fortran provide this intrinsic as
 only a function, not as a subroutine, or do not support the
 (optional) @var{Status} argument.
 
+@emph{Warning:} Use of the @code{libf2c} run-time library function
+@samp{signal_} directly
+(such as via @samp{EXTERNAL SIGNAL})
+requires use of the @code{%VAL()} construct
+to pass an @code{INTEGER} value
+(such as @samp{SIG_IGN} or @samp{SIG_DFL})
+for the @var{Handler} argument.
+
+However, while @samp{CALL SIGNAL(@var{signum}, %VAL(SIG_IGN))}
+works when @samp{SIGNAL} is treated as an external procedure
+(and resolves, at link time, to @code{libf2c}'s @samp{signal_} routine),
+this construct is not valid when @samp{SIGNAL} is recognized
+as the intrinsic of that name.
+
+Therefore, for maximum portability and reliability,
+code such references to the @samp{SIGNAL} facility as follows:
+
+@smallexample
+INTRINSIC SIGNAL
+@dots{}
+CALL SIGNAL(@var{signum}, SIG_IGN)
+@end smallexample
+
+@code{g77} will compile such a call correctly,
+while other compilers will generally either do so as well
+or reject the @samp{INTRINSIC SIGNAL} statement via a diagnostic,
+allowing you to take appropriate action.
+
 For information on other intrinsics with the same name:
 @xref{Signal Intrinsic (function)}.
 
@@ -9303,7 +9332,7 @@ Signal(@var{Number}, @var{Handler})
 @end example
 
 @noindent
-Signal: @code{INTEGER(KIND=1)} function.
+Signal: @code{INTEGER(KIND=7)} function.
 
 @noindent
 @var{Number}: @code{INTEGER}; scalar; INTENT(IN).
@@ -9321,19 +9350,73 @@ Description:
 If @var{Handler} is a an @code{EXTERNAL} routine, arranges for it to be
 invoked with a single integer argument (of system-dependent length)
 when signal @var{Number} occurs.
-If @var{Number} is an integer, it can be
-used to turn off handling of signal @var{Handler} or revert to its default
+If @var{Handler} is an integer, it can be
+used to turn off handling of signal @var{Number} or revert to its default
 action.
 See @code{signal(2)}.
 
-Note that @var{Handler} will be called using C conventions, so its value in
-Fortran terms is obtained by applying @code{%LOC()} (or @var{LOC()}) to it.
+Note that @var{Handler} will be called using C conventions,
+so the value of its argument in Fortran terms
+is obtained by applying @code{%LOC()} (or @var{LOC()}) to it.
 
 The value returned by @code{signal(2)} is returned.
 
 Due to the side effects performed by this intrinsic, the function
 form is not recommended.
 
+@emph{Warning:} If the returned value is stored in
+an @code{INTEGER(KIND=1)} (default @code{INTEGER}) argument,
+truncation of the original return value occurs on some systems
+(such as Alphas, which have 64-bit pointers but 32-bit default integers),
+with no warning issued by @code{g77} under normal circumstances.
+
+Therefore, the following code fragment might silently fail on
+some systems:
+
+@smallexample
+INTEGER RTN
+EXTERNAL MYHNDL
+RTN = SIGNAL(@var{signum}, MYHNDL)
+@dots{}
+! Restore original handler:
+RTN = SIGNAL(@var{signum}, RTN)
+@end smallexample
+
+The reason for the failure is that @samp{RTN} might not hold
+all the information on the original handler for the signal,
+thus restoring an invalid handler.
+This bug could manifest itself as a spurious run-time failure
+at an arbitrary point later during the program's execution,
+for example.
+
+@emph{Warning:} Use of the @code{libf2c} run-time library function
+@samp{signal_} directly
+(such as via @samp{EXTERNAL SIGNAL})
+requires use of the @code{%VAL()} construct
+to pass an @code{INTEGER} value
+(such as @samp{SIG_IGN} or @samp{SIG_DFL})
+for the @var{Handler} argument.
+
+However, while @samp{RTN = SIGNAL(@var{signum}, %VAL(SIG_IGN))}
+works when @samp{SIGNAL} is treated as an external procedure
+(and resolves, at link time, to @code{libf2c}'s @samp{signal_} routine),
+this construct is not valid when @samp{SIGNAL} is recognized
+as the intrinsic of that name.
+
+Therefore, for maximum portability and reliability,
+code such references to the @samp{SIGNAL} facility as follows:
+
+@smallexample
+INTRINSIC SIGNAL
+@dots{}
+RTN = SIGNAL(@var{signum}, SIG_IGN)
+@end smallexample
+
+@code{g77} will compile such a call correctly,
+while other compilers will generally either do so as well
+or reject the @samp{INTRINSIC SIGNAL} statement via a diagnostic,
+allowing you to take appropriate action.
+
 For information on other intrinsics with the same name:
 @xref{Signal Intrinsic (subroutine)}.