diff options
Diffstat (limited to 'contrib/gcc/f/intdoc.in')
| -rw-r--r-- | contrib/gcc/f/intdoc.in | 229 |
1 files changed, 207 insertions, 22 deletions
diff --git a/contrib/gcc/f/intdoc.in b/contrib/gcc/f/intdoc.in index 203dd61..565b771 100644 --- a/contrib/gcc/f/intdoc.in +++ b/contrib/gcc/f/intdoc.in @@ -1043,9 +1043,9 @@ and returns that string as the function value. ") DEFDOC (CTIME_subr, "Convert time to Day Mon dd hh:mm:ss yyyy.", "\ -Converts @var{@2@}, a system time value, such as returned by +Converts @var{@1@}, a system time value, such as returned by @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}, -and returns that string in @var{@1@}. +and returns that string in @var{@2@}. @xref{Time8 Intrinsic}. @@ -1059,7 +1059,11 @@ representing the numeric day of the month @var{dd}, a three-character abbreviation of the month name @var{mmm} and the last two digits of the year @var{yy}, e.g.@: @samp{25-Nov-96}. +@cindex Y2K compliance +@cindex Year 2000 compliance This intrinsic is not recommended, due to the year 2000 approaching. +Therefore, programs making use of this intrinsic +might not be Year 2000 (Y2K) compliant. @xref{CTime Intrinsic (subroutine)}, for information on obtaining more digits for the current (or any) date. ") @@ -1075,6 +1079,16 @@ The functions' value is equal to @samp{@var{@1@}(1) + @var{@1@}(2)}. Subsequent invocations of @samp{@0@()} return values accumulated since the previous invocation. +@cindex wraparound, timings +@cindex limits, timings +On some systems, the underlying timings are represented +using types with sufficiently small limits that overflows +(wraparounds) are possible, such as 32-bit types. +Therefore, the values returned by this intrinsic +might be, or become, negative, +or numerically less than previous values, +during a single run of the compiled program. + Due to the side effects performed by this intrinsic, the function form is not recommended. ") @@ -1082,14 +1096,24 @@ form is not recommended. DEFDOC (DTIME_subr, "Get elapsed time since last time.", "\ Initially, return the number of seconds of runtime since the start of the process's execution -in @var{@1@}, -and the user and system components of this in @samp{@var{@2@}(1)} -and @samp{@var{@2@}(2)} respectively. -The value of @var{@1@} is equal to @samp{@var{@2@}(1) + @var{@2@}(2)}. +in @var{@2@}, +and the user and system components of this in @samp{@var{@1@}(1)} +and @samp{@var{@1@}(2)} respectively. +The value of @var{@2@} is equal to @samp{@var{@1@}(1) + @var{@1@}(2)}. Subsequent invocations of @samp{@0@()} set values based on accumulations since the previous invocation. +@cindex wraparound, timings +@cindex limits, timings +On some systems, the underlying timings are represented +using types with sufficiently small limits that overflows +(wraparounds) are possible, such as 32-bit types. +Therefore, the values returned by this intrinsic +might be, or become, negative, +or numerically less than previous values, +during a single run of the compiled program. + Some non-GNU implementations of Fortran provide this intrinsic as only a function, not as a subroutine. ") @@ -1101,15 +1125,35 @@ as the function value, and the user and system components of this in @samp{@var{@1@}(1)} and @samp{@var{@1@}(2)} respectively. The functions' value is equal to @samp{@var{@1@}(1) + @var{@1@}(2)}. + +@cindex wraparound, timings +@cindex limits, timings +On some systems, the underlying timings are represented +using types with sufficiently small limits that overflows +(wraparounds) are possible, such as 32-bit types. +Therefore, the values returned by this intrinsic +might be, or become, negative, +or numerically less than previous values, +during a single run of the compiled program. ") DEFDOC (ETIME_subr, "Get elapsed time for process.", "\ Return the number of seconds of runtime since the start of the process's execution -in @var{@1@}, -and the user and system components of this in @samp{@var{@2@}(1)} -and @samp{@var{@2@}(2)} respectively. -The value of @var{@1@} is equal to @samp{@var{@2@}(1) + @var{@2@}(2)}. +in @var{@2@}, +and the user and system components of this in @samp{@var{@1@}(1)} +and @samp{@var{@1@}(2)} respectively. +The value of @var{@2@} is equal to @samp{@var{@1@}(1) + @var{@1@}(2)}. + +@cindex wraparound, timings +@cindex limits, timings +On some systems, the underlying timings are represented +using types with sufficiently small limits that overflows +(wraparounds) are possible, such as 32-bit types. +Therefore, the values returned by this intrinsic +might be, or become, negative, +or numerically less than previous values, +during a single run of the compiled program. Some non-GNU implementations of Fortran provide this intrinsic as only a function, not as a subroutine. @@ -1124,6 +1168,17 @@ Equivalent to: CTIME(TIME8()) @end example +@cindex Y10K compliance +@cindex Year 10000 compliance +@cindex wraparound, Y10K +@cindex limits, Y10K +Programs making use of this intrinsic +might not be Year 10000 (Y10K) compliant. +For example, the date might appear, +to such programs, to wrap around +(change from a larger value to a smaller one) +as of the Year 10000. + @xref{CTime Intrinsic (function)}. ") @@ -1137,6 +1192,17 @@ Equivalent to: CALL CTIME(@var{@1@}, TIME8()) @end example +@cindex Y10K compliance +@cindex Year 10000 compliance +@cindex wraparound, Y10K +@cindex limits, Y10K +Programs making use of this intrinsic +might not be Year 10000 (Y10K) compliant. +For example, the date might appear, +to such programs, to wrap around +(change from a larger value to a smaller one) +as of the Year 10000. + @xref{CTime Intrinsic (subroutine)}. Some non-GNU implementations of Fortran provide this intrinsic as @@ -1226,6 +1292,17 @@ Fills @var{@1@} with the numerical values at the current local time of day, month (in the range 1--12), and year in elements 1, 2, and 3, respectively. The year has four significant digits. + +@cindex Y10K compliance +@cindex Year 10000 compliance +@cindex wraparound, Y10K +@cindex limits, Y10K +Programs making use of this intrinsic +might not be Year 10000 (Y10K) compliant. +For example, the date might appear, +to such programs, to wrap around +(change from a larger value to a smaller one) +as of the Year 10000. ") DEFDOC (IDATE_vxt, "Get local time info (VAX/VMS).", "\ @@ -1234,7 +1311,20 @@ The month (in the range 1--12) is returned in @var{@1@}, the day (in the range 1--7) in @var{@2@}, and the year in @var{@3@} (in the range 0--99). +@cindex Y2K compliance +@cindex Year 2000 compliance +@cindex wraparound, Y2K +@cindex limits, Y2K This intrinsic is not recommended, due to the year 2000 approaching. +Therefore, programs making use of this intrinsic +might not be Year 2000 (Y2K) compliant. +For example, the date might appear, +to such programs, to wrap around +(change from a larger value to a smaller one) +as of the Year 2000. + +@xref{IDate Intrinsic (UNIX)}, for information on obtaining more digits +for the current date. ") DEFDOC (ITIME, "Get local time of day.", "\ @@ -1246,9 +1336,16 @@ DEFDOC (MCLOCK, "Get number of clock ticks for process.", "\ Returns the number of clock ticks since the start of the process. Supported on systems with @code{clock(3)} (q.v.). +@cindex wraparound, timings +@cindex limits, timings This intrinsic is not fully portable, such as to systems with 32-bit @code{INTEGER} types but supporting times wider than 32 bits. +Therefore, the values returned by this intrinsic +might be, or become, negative, +or numerically less than previous values, +during a single run of the compiled program. + @xref{MClock8 Intrinsic}, for information on a similar intrinsic that might be portable to more GNU Fortran implementations, though to fewer @@ -1262,12 +1359,18 @@ DEFDOC (MCLOCK8, "Get number of clock ticks for process.", "\ Returns the number of clock ticks since the start of the process. Supported on systems with @code{clock(3)} (q.v.). +@cindex wraparound, timings +@cindex limits, timings @emph{Warning:} this intrinsic does not increase the range of the timing values over that returned by @code{clock(3)}. On a system with a 32-bit @code{clock(3)}, @code{@0@} will return a 32-bit value, even though converted to an @samp{INTEGER(KIND=2)} value. That means overflows of the 32-bit value can still occur. +Therefore, the values returned by this intrinsic +might be, or become, negative, +or numerically less than previous values, +during a single run of the compiled program. No Fortran implementations other than GNU Fortran are known to support this intrinsic at the time of this @@ -1283,17 +1386,45 @@ If the system does not support @code{clock(3)}, DEFDOC (SECNDS, "Get local time offset since midnight.", "\ Returns the local time in seconds since midnight minus the value @var{@1@}. + +@cindex wraparound, timings +@cindex limits, timings +This values returned by this intrinsic +become numerically less than previous values +(they wrap around) during a single run of the +compiler program, under normal circumstances +(such as running through the midnight hour). ") DEFDOC (SECOND_func, "Get CPU time for process in seconds.", "\ Returns the process's runtime in seconds---the same value as the UNIX function @code{etime} returns. + +@cindex wraparound, timings +@cindex limits, timings +On some systems, the underlying timings are represented +using types with sufficiently small limits that overflows +(wraparounds) are possible, such as 32-bit types. +Therefore, the values returned by this intrinsic +might be, or become, negative, +or numerically less than previous values, +during a single run of the compiled program. ") DEFDOC (SECOND_subr, "Get CPU time for process@99@in seconds.", "\ Returns the process's runtime in seconds in @var{@1@}---the same value as the UNIX function @code{etime} returns. +@cindex wraparound, timings +@cindex limits, timings +On some systems, the underlying timings are represented +using types with sufficiently small limits that overflows +(wraparounds) are possible, such as 32-bit types. +Therefore, the values returned by this intrinsic +might be, or become, negative, +or numerically less than previous values, +during a single run of the compiled program. + This routine is known from Cray Fortran. @xref{CPU_Time Intrinsic}, for a standard equivalent. ") @@ -1307,12 +1438,32 @@ isn't in general. @var{@3@} is the maximum value this can take, which isn't very useful in this implementation since it's just the maximum C @code{unsigned int} value. + +@cindex wraparound, timings +@cindex limits, timings +On some systems, the underlying timings are represented +using types with sufficiently small limits that overflows +(wraparounds) are possible, such as 32-bit types. +Therefore, the values returned by this intrinsic +might be, or become, negative, +or numerically less than previous values, +during a single run of the compiled program. ") DEFDOC (CPU_TIME, "Get current CPU time.", "\ Returns in @var{@1@} the current value of the system time. This implementation of the Fortran 95 intrinsic is just an alias for @code{second} @xref{Second Intrinsic (subroutine)}. + +@cindex wraparound, timings +@cindex limits, timings +On some systems, the underlying timings are represented +using types with sufficiently small limits that overflows +(wraparounds) are possible, such as 32-bit types. +Therefore, the values returned by this intrinsic +might be, or become, negative, +or numerically less than previous values, +during a single run of the compiled program. ") DEFDOC (TIME8, "Get current time as time value.", "\ @@ -1321,12 +1472,18 @@ Returns the current time encoded as a long integer This value is suitable for passing to @code{CTIME}, @code{GMTIME}, and @code{LTIME}. +@cindex wraparound, timings +@cindex limits, timings @emph{Warning:} this intrinsic does not increase the range of the timing values over that returned by @code{time(3)}. On a system with a 32-bit @code{time(3)}, @code{@0@} will return a 32-bit value, even though converted to an @samp{INTEGER(KIND=2)} value. That means overflows of the 32-bit value can still occur. +Therefore, the values returned by this intrinsic +might be, or become, negative, +or numerically less than previous values, +during a single run of the compiled program. No Fortran implementations other than GNU Fortran are known to support this intrinsic at the time of this @@ -1342,9 +1499,16 @@ Returns the current time encoded as an integer This value is suitable for passing to @code{CTIME}, @code{GMTIME}, and @code{LTIME}. +@cindex wraparound, timings +@cindex limits, timings This intrinsic is not fully portable, such as to systems with 32-bit @code{INTEGER} types but supporting times wider than 32 bits. +Therefore, the values returned by this intrinsic +might be, or become, negative, +or numerically less than previous values, +during a single run of the compiled program. + @xref{Time8 Intrinsic}, for information on a similar intrinsic that might be portable to more GNU Fortran implementations, though to fewer @@ -1378,7 +1542,7 @@ See @code{erf(3m)}, which provides the implementation. DEFDOC (ERFC, "Complementary error function.", "\ Returns the complementary error function of @var{@1@}: -@samp{ERFC(R) = 1 - ERF(R)} (except that the result may be more +@samp{ERFC(R) = 1 - ERF(R)} (except that the result might be more accurate than explicitly evaluating that formulae would give). See @code{erfc(3m)}, which provides the implementation. ") @@ -1458,7 +1622,7 @@ See @code{chdir(3)}. @emph{Caution:} Using this routine during I/O to a unit connected with a non-absolute file name can cause subsequent I/O on such a unit to fail -because the I/O library may reopen files by name. +because the I/O library might reopen files by name. Some non-GNU implementations of Fortran provide this intrinsic as only a function, not as a subroutine, or do not support the @@ -1472,7 +1636,7 @@ See @code{chdir(3)}. @emph{Caution:} Using this routine during I/O to a unit connected with a non-absolute file name can cause subsequent I/O on such a unit to fail -because the I/O library may reopen files by name. +because the I/O library might reopen files by name. Due to the side effects performed by this intrinsic, the function form is not recommended. @@ -1492,7 +1656,7 @@ Returns 0 on success or a non-zero error code otherwise. Note that this currently works by actually invoking @code{/bin/chmod} (or the @code{chmod} found when -the library was configured) and so may fail in some circumstances and +the library was configured) and so might fail in some circumstances and will, anyway, be slow. Due to the side effects performed by this intrinsic, the function @@ -1514,7 +1678,7 @@ If the @var{@3@} argument is supplied, it contains Note that this currently works by actually invoking @code{/bin/chmod} (or the @code{chmod} found when -the library was configured) and so may fail in some circumstances and +the library was configured) and so might fail in some circumstances and will, anyway, be slow. Some non-GNU implementations of Fortran provide this intrinsic as @@ -2077,7 +2241,7 @@ Fills @var{@1@} with the system's host name returned by @code{gethostname(2)}, returning 0 on success or a non-zero error code (@code{ENOSYS} if the system does not provide @code{gethostname(2)}). -On some systems (specifically SCO) it may be necessary to link the +On some systems (specifically SCO) it might be necessary to link the ``socket'' library if you call this routine. Typically this means adding @samp{-lg2c -lsocket -lm} to the @code{g77} command line when linking the program. @@ -2094,7 +2258,7 @@ Some non-GNU implementations of Fortran provide this intrinsic as only a function, not as a subroutine, or do not support the (optional) @var{@2@} argument. -On some systems (specifically SCO) it may be necessary to link the +On some systems (specifically SCO) it might be necessary to link the ``socket'' library if you call this routine. Typically this means adding @samp{-lg2c -lsocket -lm} to the @code{g77} command line when linking the program. @@ -2217,8 +2381,8 @@ terminal. ") DEFDOC (TTYNAM_subr, "Get name of terminal device for unit.", "\ -Sets @var{@1@} to the name of the terminal device open on logical unit -@var{@2@} or a blank string if @var{@2@} is not connected to a +Sets @var{@2@} to the name of the terminal device open on logical unit +@var{@1@} or to a blank string if @var{@1@} is not connected to a terminal. Some non-GNU implementations of Fortran provide this intrinsic as @@ -2415,7 +2579,18 @@ DEFDOC (TIME_vxt, "Get the time as a character value.", "\ Returns in @var{@1@} a character representation of the current time as obtained from @code{ctime(3)}. -@xref{Fdate Intrinsic (subroutine)}, for an equivalent routine. +@cindex Y10K compliance +@cindex Year 10000 compliance +@cindex wraparound, Y10K +@cindex limits, Y10K +Programs making use of this intrinsic +might not be Year 10000 (Y10K) compliant. +For example, the date might appear, +to such programs, to wrap around +(change from a larger value to a smaller one) +as of the Year 10000. + +@xref{FDate Intrinsic (subroutine)}, for an equivalent routine. ") DEFDOC (IBCLR, "Clear a bit.", "\ @@ -2445,8 +2620,7 @@ All bits representing @var{@1@} are shifted @var{@2@} places. indicates no shift and @samp{@var{@2@}.LT.0} indicates a right shift. If the absolute value of the shift count is greater than @samp{BIT_SIZE(@var{@1@})}, the result is undefined. -Bits shifted out from the left end or the right end, as the case may be, -are lost. +Bits shifted out from the left end or the right end are lost. Zeros are shifted in from the opposite end. @xref{IShftC Intrinsic}, for the circular-shift equivalent. @@ -2514,6 +2688,17 @@ of the minute, and milliseconds of the second in successive values of the array. @end table +@cindex Y10K compliance +@cindex Year 10000 compliance +@cindex wraparound, Y10K +@cindex limits, Y10K +Programs making use of this intrinsic +might not be Year 10000 (Y10K) compliant. +For example, the date might appear, +to such programs, to wrap around +(change from a larger value to a smaller one) +as of the Year 10000. + On systems where a millisecond timer isn't available, the millisecond value is returned as zero. ") |
