* config/arm/arm.c (is_load_address): Rename to... (arm_memory_load_p) ... this
[official-gcc.git] / gcc / f / intdoc.in
blob9d00bc761a676b22541a4bfdbb40320663046cc9
1 /* Copyright (C) 1997, 1999 Free Software Foundation, Inc.
2  * This is part of the G77 manual.
3  * For copying conditions, see the file g77.texi. */
5 /* This is the file containing the verbage for the
6    intrinsics.  It consists of a data base built up
7    via DEFDOC macros of the form:
9    DEFDOC (IMP, SUMMARY, DESCRIPTION)
11    IMP is the implementation keyword used in the intrin module.
12    SUMMARY is the short summary to go in the "* Menu:" section
13    of the Info document.  DESCRIPTION is the longer description
14    to go in the documentation itself.
16    Note that IMP is leveraged across multiple intrinsic names.
18    To make for more accurate and consistent documentation,
19    the translation made by intdoc.c of the text in SUMMARY
20    and DESCRIPTION includes the special sequence
22    @ARGNO@
24    where ARGNO is a series of digits forming a number that
25    is substituted by intdoc.c as follows:
27    0     The initial-caps form of the intrinsic name (e.g. Float).
28    1-98  The initial-caps form of the ARGNO'th argument.
29    99    (SUMMARY only) a newline plus the appropriate # of spaces.
31    Hope this info is enough to encourage people to feel free to
32    add documentation to this file!
36 #define ARCHAIC(upper,mixed) \
37   "Archaic form of @code{" #upper "()} that is specific\n\
38 to one type for @var{@1@}.\n\
39 @xref{" #mixed " Intrinsic}.\n"
41 #define ARCHAIC_2nd(upper,mixed) \
42   "Archaic form of @code{" #upper "()} that is specific\n\
43 to one type for @var{@2@}.\n\
44 @xref{" #mixed " Intrinsic}.\n"
46 #define ARCHAIC_2(upper,mixed) \
47   "Archaic form of @code{" #upper "()} that is specific\n\
48 to one type for @var{@1@} and @var{@2@}.\n\
49 @xref{" #mixed " Intrinsic}.\n"
51 DEFDOC (ABS, "Absolute value.", "\
52 Returns the absolute value of @var{@1@}.
54 If @var{@1@} is type @code{COMPLEX}, the absolute
55 value is computed as:
57 @example
58 SQRT(REALPART(@var{@1@})**2+IMAGPART(@var{@1@})**2)
59 @end example
61 @noindent
62 Otherwise, it is computed by negating @var{@1@} if
63 it is negative, or returning @var{@1@}.
65 @xref{Sign Intrinsic}, for how to explicitly
66 compute the positive or negative form of the absolute
67 value of an expression.
70 DEFDOC (CABS, "Absolute value (archaic).", ARCHAIC (ABS, Abs))
72 DEFDOC (DABS, "Absolute value (archaic).", ARCHAIC (ABS, Abs))
74 DEFDOC (IABS, "Absolute value (archaic).", ARCHAIC (ABS, Abs))
76 DEFDOC (CDABS, "Absolute value (archaic).", ARCHAIC (ABS, Abs))
78 DEFDOC (ACHAR, "ASCII character from code.", "\
79 Returns the ASCII character corresponding to the
80 code specified by @var{@1@}.
82 @xref{IAChar Intrinsic}, for the inverse of this function.
84 @xref{Char Intrinsic}, for the function corresponding
85 to the system's native character set.
88 DEFDOC (IACHAR, "ASCII code for character.", "\
89 Returns the code for the ASCII character in the
90 first character position of @var{@1@}.
92 @xref{AChar Intrinsic}, for the inverse of this function.
94 @xref{IChar Intrinsic}, for the function corresponding
95 to the system's native character set.
98 DEFDOC (CHAR, "Character from code.", "\
99 Returns the character corresponding to the
100 code specified by @var{@1@}, using the system's
101 native character set.
103 Because the system's native character set is used,
104 the correspondence between character and their codes
105 is not necessarily the same between GNU Fortran
106 implementations.
108 Note that no intrinsic exists to convert a numerical
109 value to a printable character string.
110 For example, there is no intrinsic that, given
111 an @code{INTEGER} or @code{REAL} argument with the
112 value @samp{154}, returns the @code{CHARACTER}
113 result @samp{'154'}.
115 Instead, you can use internal-file I/O to do this kind
116 of conversion.
117 For example:
119 @smallexample
120 INTEGER VALUE
121 CHARACTER*10 STRING
122 VALUE = 154
123 WRITE (STRING, '(I10)'), VALUE
124 PRINT *, STRING
126 @end smallexample
128 The above program, when run, prints:
130 @smallexample
131         154
132 @end smallexample
134 @xref{IChar Intrinsic}, for the inverse of the @code{@0@} function.
136 @xref{AChar Intrinsic}, for the function corresponding
137 to the ASCII character set.
140 DEFDOC (ICHAR, "Code for character.", "\
141 Returns the code for the character in the
142 first character position of @var{@1@}.
144 Because the system's native character set is used,
145 the correspondence between character and their codes
146 is not necessarily the same between GNU Fortran
147 implementations.
149 Note that no intrinsic exists to convert a printable
150 character string to a numerical value.
151 For example, there is no intrinsic that, given
152 the @code{CHARACTER} value @samp{'154'}, returns an
153 @code{INTEGER} or @code{REAL} value with the value @samp{154}.
155 Instead, you can use internal-file I/O to do this kind
156 of conversion.
157 For example:
159 @smallexample
160 INTEGER VALUE
161 CHARACTER*10 STRING
162 STRING = '154'
163 READ (STRING, '(I10)'), VALUE
164 PRINT *, VALUE
166 @end smallexample
168 The above program, when run, prints:
170 @smallexample
171  154
172 @end smallexample
174 @xref{Char Intrinsic}, for the inverse of the @code{@0@} function.
176 @xref{IAChar Intrinsic}, for the function corresponding
177 to the ASCII character set.
180 DEFDOC (ACOS, "Arc cosine.", "\
181 Returns the arc-cosine (inverse cosine) of @var{@1@}
182 in radians.
184 @xref{Cos Intrinsic}, for the inverse of this function.
187 DEFDOC (DACOS, "Arc cosine (archaic).", ARCHAIC (ACOS, ACos))
189 DEFDOC (AIMAG, "Convert/extract imaginary part of complex.", "\
190 Returns the (possibly converted) imaginary part of @var{@1@}.
192 Use of @code{@0@()} with an argument of a type
193 other than @code{COMPLEX(KIND=1)} is restricted to the following case:
195 @example
196 REAL(AIMAG(@1@))
197 @end example
199 @noindent
200 This expression converts the imaginary part of @1@ to
201 @code{REAL(KIND=1)}.
203 @xref{REAL() and AIMAG() of Complex}, for more information.
206 DEFDOC (DIMAG, "Convert/extract imaginary part of complex (archaic).", ARCHAIC (AIMAG, AImag))
208 DEFDOC (AINT, "Truncate to whole number.", "\
209 Returns @var{@1@} with the fractional portion of its
210 magnitude truncated and its sign preserved.
211 (Also called ``truncation towards zero''.)
213 @xref{ANInt Intrinsic}, for how to round to nearest
214 whole number.
216 @xref{Int Intrinsic}, for how to truncate and then convert
217 number to @code{INTEGER}.
220 DEFDOC (DINT, "Truncate to whole number (archaic).", ARCHAIC (AINT, AInt))
222 DEFDOC (INT, "Convert to @code{INTEGER} value truncated@99@to whole number.", "\
223 Returns @var{@1@} with the fractional portion of its
224 magnitude truncated and its sign preserved, converted
225 to type @code{INTEGER(KIND=1)}.
227 If @var{@1@} is type @code{COMPLEX}, its real part is
228 truncated and converted, and its imaginary part is disregarded.
230 @xref{NInt Intrinsic}, for how to convert, rounded to nearest
231 whole number.
233 @xref{AInt Intrinsic}, for how to truncate to whole number
234 without converting.
237 DEFDOC (IDINT, "Convert to @code{INTEGER} value truncated@99@to whole number (archaic).", ARCHAIC (INT, Int))
239 DEFDOC (ANINT, "Round to nearest whole number.", "\
240 Returns @var{@1@} with the fractional portion of its
241 magnitude eliminated by rounding to the nearest whole
242 number and with its sign preserved.
244 A fractional portion exactly equal to
245 @samp{.5} is rounded to the whole number that
246 is larger in magnitude.
247 (Also called ``Fortran round''.)
249 @xref{AInt Intrinsic}, for how to truncate to
250 whole number.
252 @xref{NInt Intrinsic}, for how to round and then convert
253 number to @code{INTEGER}.
256 DEFDOC (DNINT, "Round to nearest whole number (archaic).", ARCHAIC (ANINT, ANInt))
258 DEFDOC (NINT, "Convert to @code{INTEGER} value rounded@99@to nearest whole number.", "\
259 Returns @var{@1@} with the fractional portion of its
260 magnitude eliminated by rounding to the nearest whole
261 number and with its sign preserved, converted
262 to type @code{INTEGER(KIND=1)}.
264 If @var{@1@} is type @code{COMPLEX}, its real part is
265 rounded and converted.
267 A fractional portion exactly equal to
268 @samp{.5} is rounded to the whole number that
269 is larger in magnitude.
270 (Also called ``Fortran round''.)
272 @xref{Int Intrinsic}, for how to convert, truncate to
273 whole number.
275 @xref{ANInt Intrinsic}, for how to round to nearest whole number
276 without converting.
279 DEFDOC (IDNINT, "Convert to @code{INTEGER} value rounded@99@to nearest whole number (archaic).", ARCHAIC (NINT, NInt))
281 DEFDOC (LOG, "Natural logarithm.", "\
282 Returns the natural logarithm of @var{@1@}, which must
283 be greater than zero or, if type @code{COMPLEX}, must not
284 be zero.
286 @xref{Exp Intrinsic}, for the inverse of this function.
288 @xref{Log10 Intrinsic}, for the `common' (base-10) logarithm function.
291 DEFDOC (ALOG, "Natural logarithm (archaic).", ARCHAIC (LOG, Log))
293 DEFDOC (CLOG, "Natural logarithm (archaic).", ARCHAIC (LOG, Log))
295 DEFDOC (DLOG, "Natural logarithm (archaic).", ARCHAIC (LOG, Log))
297 DEFDOC (CDLOG, "Natural logarithm (archaic).", ARCHAIC (LOG, Log))
299 DEFDOC (LOG10, "Common logarithm.", "\
300 Returns the common logarithm (base 10) of @var{@1@}, which must
301 be greater than zero.
303 The inverse of this function is @samp{10. ** LOG10(@var{@1@})}.
305 @xref{Log Intrinsic}, for the natural logarithm function.
308 DEFDOC (ALOG10, "Common logarithm (archaic).", ARCHAIC (LOG10, Log10))
310 DEFDOC (DLOG10, "Common logarithm (archaic).", ARCHAIC (LOG10, Log10))
312 DEFDOC (MAX, "Maximum value.", "\
313 Returns the argument with the largest value.
315 @xref{Min Intrinsic}, for the opposite function.
318 DEFDOC (AMAX0, "Maximum value (archaic).", "\
319 Archaic form of @code{MAX()} that is specific
320 to one type for @var{@1@} and a different return type.
321 @xref{Max Intrinsic}.
324 DEFDOC (AMAX1, "Maximum value (archaic).", ARCHAIC (MAX, Max))
326 DEFDOC (DMAX1, "Maximum value (archaic).", ARCHAIC (MAX, Max))
328 DEFDOC (MAX0, "Maximum value (archaic).", ARCHAIC (MAX, Max))
330 DEFDOC (MAX1, "Maximum value (archaic).", "\
331 Archaic form of @code{MAX()} that is specific
332 to one type for @var{@1@} and a different return type.
333 @xref{Max Intrinsic}.
336 DEFDOC (MIN, "Minimum value.", "\
337 Returns the argument with the smallest value.
339 @xref{Max Intrinsic}, for the opposite function.
342 DEFDOC (AMIN0, "Minimum value (archaic).", "\
343 Archaic form of @code{MIN()} that is specific
344 to one type for @var{@1@} and a different return type.
345 @xref{Min Intrinsic}.
348 DEFDOC (AMIN1, "Minimum value (archaic).", ARCHAIC (MIN, Min))
350 DEFDOC (DMIN1, "Minimum value (archaic).", ARCHAIC (MIN, Min))
352 DEFDOC (MIN0, "Minimum value (archaic).", ARCHAIC (MIN, Min))
354 DEFDOC (MIN1, "Minimum value (archaic).", "\
355 Archaic form of @code{MIN()} that is specific
356 to one type for @var{@1@} and a different return type.
357 @xref{Min Intrinsic}.
360 DEFDOC (MOD, "Remainder.", "\
361 Returns remainder calculated as:
363 @smallexample
364 @var{@1@} - (INT(@var{@1@} / @var{@2@}) * @var{@2@})
365 @end smallexample
367 @var{@2@} must not be zero.
370 DEFDOC (AMOD, "Remainder (archaic).", ARCHAIC (MOD, Mod))
372 DEFDOC (DMOD, "Remainder (archaic).", ARCHAIC (MOD, Mod))
374 DEFDOC (AND, "Boolean AND.", "\
375 Returns value resulting from boolean AND of
376 pair of bits in each of @var{@1@} and @var{@2@}.
379 DEFDOC (IAND, "Boolean AND.", "\
380 Returns value resulting from boolean AND of
381 pair of bits in each of @var{@1@} and @var{@2@}.
384 DEFDOC (OR, "Boolean OR.", "\
385 Returns value resulting from boolean OR of
386 pair of bits in each of @var{@1@} and @var{@2@}.
389 DEFDOC (IOR, "Boolean OR.", "\
390 Returns value resulting from boolean OR of
391 pair of bits in each of @var{@1@} and @var{@2@}.
394 DEFDOC (XOR, "Boolean XOR.", "\
395 Returns value resulting from boolean exclusive-OR of
396 pair of bits in each of @var{@1@} and @var{@2@}.
399 DEFDOC (IEOR, "Boolean XOR.", "\
400 Returns value resulting from boolean exclusive-OR of
401 pair of bits in each of @var{@1@} and @var{@2@}.
404 DEFDOC (NOT, "Boolean NOT.", "\
405 Returns value resulting from boolean NOT of each bit
406 in @var{@1@}.
409 DEFDOC (ASIN, "Arc sine.", "\
410 Returns the arc-sine (inverse sine) of @var{@1@}
411 in radians.
413 @xref{Sin Intrinsic}, for the inverse of this function.
416 DEFDOC (DASIN, "Arc sine (archaic).", ARCHAIC (ASIN, ASin))
418 DEFDOC (ATAN, "Arc tangent.", "\
419 Returns the arc-tangent (inverse tangent) of @var{@1@}
420 in radians.
422 @xref{Tan Intrinsic}, for the inverse of this function.
425 DEFDOC (DATAN, "Arc tangent (archaic).", ARCHAIC (ATAN, ATan))
427 DEFDOC (ATAN2, "Arc tangent.", "\
428 Returns the arc-tangent (inverse tangent) of the complex
429 number (@var{@1@}, @var{@2@}) in radians.
431 @xref{Tan Intrinsic}, for the inverse of this function.
434 DEFDOC (DATAN2, "Arc tangent (archaic).", ARCHAIC_2 (ATAN2, ATan2))
436 DEFDOC (BIT_SIZE, "Number of bits in argument's type.", "\
437 Returns the number of bits (integer precision plus sign bit)
438 represented by the type for @var{@1@}.
440 @xref{BTest Intrinsic}, for how to test the value of a
441 bit in a variable or array.
443 @xref{IBSet Intrinsic}, for how to set a bit in a variable to 1.
445 @xref{IBClr Intrinsic}, for how to set a bit in a variable to 0.
449 DEFDOC (BTEST, "Test bit.", "\
450 Returns @code{.TRUE.} if bit @var{@2@} in @var{@1@} is
451 1, @code{.FALSE.} otherwise.
453 (Bit 0 is the low-order (rightmost) bit, adding the value 
454 @ifinfo
455 2**0,
456 @end ifinfo
457 @iftex
458 @tex
459 $2^0$,
460 @end tex
461 @end iftex
462 or 1,
463 to the number if set to 1;
464 bit 1 is the next-higher-order bit, adding 
465 @ifinfo
466 2**1,
467 @end ifinfo
468 @iftex
469 @tex
470 $2^1$,
471 @end tex
472 @end iftex
473 or 2;
474 bit 2 adds 
475 @ifinfo
476 2**2,
477 @end ifinfo
478 @iftex
479 @tex
480 $2^2$,
481 @end tex
482 @end iftex
483 or 4; and so on.)
485 @xref{Bit_Size Intrinsic}, for how to obtain the number of bits
486 in a type.
487 The leftmost bit of @var{@1@} is @samp{BIT_SIZE(@var{@1@}-1)}.
490 DEFDOC (CMPLX, "Construct @code{COMPLEX(KIND=1)} value.", "\
491 If @var{@1@} is not type @code{COMPLEX},
492 constructs a value of type @code{COMPLEX(KIND=1)} from the
493 real and imaginary values specified by @var{@1@} and
494 @var{@2@}, respectively.
495 If @var{@2@} is omitted, @samp{0.} is assumed.
497 If @var{@1@} is type @code{COMPLEX},
498 converts it to type @code{COMPLEX(KIND=1)}.
500 @xref{Complex Intrinsic}, for information on easily constructing
501 a @code{COMPLEX} value of arbitrary precision from @code{REAL}
502 arguments.
505 DEFDOC (DCMPLX, "Construct @code{COMPLEX(KIND=2)} value.", "\
506 If @var{@1@} is not type @code{COMPLEX},
507 constructs a value of type @code{COMPLEX(KIND=2)} from the
508 real and imaginary values specified by @var{@1@} and
509 @var{@2@}, respectively.
510 If @var{@2@} is omitted, @samp{0D0} is assumed.
512 If @var{@1@} is type @code{COMPLEX},
513 converts it to type @code{COMPLEX(KIND=2)}.
515 Although this intrinsic is not standard Fortran,
516 it is a popular extension offered by many compilers
517 that support @code{DOUBLE COMPLEX}, since it offers
518 the easiest way to convert to @code{DOUBLE COMPLEX}
519 without using Fortran 90 features (such as the @samp{KIND=}
520 argument to the @code{CMPLX()} intrinsic).
522 (@samp{CMPLX(0D0, 0D0)} returns a single-precision
523 @code{COMPLEX} result, as required by standard FORTRAN 77.
524 That's why so many compilers provide @code{DCMPLX()}, since
525 @samp{DCMPLX(0D0, 0D0)} returns a @code{DOUBLE COMPLEX}
526 result.
527 Still, @code{DCMPLX()} converts even @code{REAL*16} arguments
528 to their @code{REAL*8} equivalents in most dialects of
529 Fortran, so neither it nor @code{CMPLX()} allow easy
530 construction of arbitrary-precision values without
531 potentially forcing a conversion involving extending or
532 reducing precision.
533 GNU Fortran provides such an intrinsic, called @code{COMPLEX()}.)
535 @xref{Complex Intrinsic}, for information on easily constructing
536 a @code{COMPLEX} value of arbitrary precision from @code{REAL}
537 arguments.
540 DEFDOC (CONJG, "Complex conjugate.", "\
541 Returns the complex conjugate:
543 @example
544 COMPLEX(REALPART(@var{@1@}), -IMAGPART(@var{@1@}))
545 @end example
548 DEFDOC (DCONJG, "Complex conjugate (archaic).", ARCHAIC (CONJG, Conjg))
550 DEFDOC (COS, "Cosine.", "\
551 Returns the cosine of @var{@1@}, an angle measured
552 in radians.
554 @xref{ACos Intrinsic}, for the inverse of this function.
557 DEFDOC (CCOS, "Cosine (archaic).", ARCHAIC (COS, Cos))
559 DEFDOC (DCOS, "Cosine (archaic).", ARCHAIC (COS, Cos))
561 DEFDOC (CDCOS, "Cosine (archaic).", ARCHAIC (COS, Cos))
563 DEFDOC (COSH, "Hyperbolic cosine.", "\
564 Returns the hyperbolic cosine of @var{@1@}.
567 DEFDOC (DCOSH, "Hyperbolic cosine (archaic).", ARCHAIC (COSH, CosH))
569 DEFDOC (SQRT, "Square root.", "\
570 Returns the square root of @var{@1@}, which must
571 not be negative.
573 To calculate and represent the square root of a negative
574 number, complex arithmetic must be used.
575 For example, @samp{SQRT(COMPLEX(@var{@1@}))}.
577 The inverse of this function is @samp{SQRT(@var{@1@}) * SQRT(@var{@1@})}.
580 DEFDOC (CSQRT, "Square root (archaic).", ARCHAIC (SQRT, SqRt))
582 DEFDOC (DSQRT, "Square root (archaic).", ARCHAIC (SQRT, SqRt))
584 DEFDOC (CDSQRT, "Square root (archaic).", ARCHAIC (SQRT, SqRt))
586 DEFDOC (DBLE, "Convert to double precision.", "\
587 Returns @var{@1@} converted to double precision
588 (@code{REAL(KIND=2)}).
589 If @var{@1@} is @code{COMPLEX}, the real part of
590 @var{@1@} is used for the conversion
591 and the imaginary part disregarded.
593 @xref{Sngl Intrinsic}, for the function that converts
594 to single precision.
596 @xref{Int Intrinsic}, for the function that converts
597 to @code{INTEGER}.
599 @xref{Complex Intrinsic}, for the function that converts
600 to @code{COMPLEX}.
603 DEFDOC (DIM, "Difference magnitude (non-negative subtract).", "\
604 Returns @samp{@var{@1@}-@var{@2@}} if @var{@1@} is greater than
605 @var{@2@}; otherwise returns zero.
608 DEFDOC (DDIM, "Difference magnitude (archaic).", ARCHAIC_2 (DIM, DiM))
609 DEFDOC (IDIM, "Difference magnitude (archaic).", ARCHAIC_2 (DIM, DiM))
611 DEFDOC (DPROD, "Double-precision product.", "\
612 Returns @samp{DBLE(@var{@1@})*DBLE(@var{@2@})}.
615 DEFDOC (EXP, "Exponential.", "\
616 Returns @samp{@var{e}**@var{@1@}}, where
617 @var{e} is approximately 2.7182818.
619 @xref{Log Intrinsic}, for the inverse of this function.
622 DEFDOC (CEXP, "Exponential (archaic).", ARCHAIC (EXP, Exp))
624 DEFDOC (DEXP, "Exponential (archaic).", ARCHAIC (EXP, Exp))
626 DEFDOC (CDEXP, "Exponential (archaic).", ARCHAIC (EXP, Exp))
628 DEFDOC (FLOAT, "Conversion (archaic).", ARCHAIC (REAL, Real))
629 DEFDOC (DFLOAT, "Conversion (archaic).", ARCHAIC (REAL, Real))
631 DEFDOC (IFIX, "Conversion (archaic).", ARCHAIC (INT, Int))
633 DEFDOC (LONG, "Conversion to @code{INTEGER(KIND=1)} (archaic).", "\
634 Archaic form of @code{INT()} that is specific
635 to one type for @var{@1@}.
636 @xref{Int Intrinsic}.
638 The precise meaning of this intrinsic might change
639 in a future version of the GNU Fortran language,
640 as more is learned about how it is used.
643 DEFDOC (SHORT, "Convert to @code{INTEGER(KIND=6)} value@99@truncated to whole number.", "\
644 Returns @var{@1@} with the fractional portion of its
645 magnitude truncated and its sign preserved, converted
646 to type @code{INTEGER(KIND=6)}.
648 If @var{@1@} is type @code{COMPLEX}, its real part
649 is truncated and converted, and its imaginary part is disregarded.
651 @xref{Int Intrinsic}.
653 The precise meaning of this intrinsic might change
654 in a future version of the GNU Fortran language,
655 as more is learned about how it is used.
658 DEFDOC (INT2, "Convert to @code{INTEGER(KIND=6)} value@99@truncated to whole number.", "\
659 Returns @var{@1@} with the fractional portion of its
660 magnitude truncated and its sign preserved, converted
661 to type @code{INTEGER(KIND=6)}.
663 If @var{@1@} is type @code{COMPLEX}, its real part
664 is truncated and converted, and its imaginary part is disregarded.
666 @xref{Int Intrinsic}.
668 The precise meaning of this intrinsic might change
669 in a future version of the GNU Fortran language,
670 as more is learned about how it is used.
673 DEFDOC (INT8, "Convert to @code{INTEGER(KIND=2)} value@99@truncated to whole number.", "\
674 Returns @var{@1@} with the fractional portion of its
675 magnitude truncated and its sign preserved, converted
676 to type @code{INTEGER(KIND=2)}.
678 If @var{@1@} is type @code{COMPLEX}, its real part
679 is truncated and converted, and its imaginary part is disregarded.
681 @xref{Int Intrinsic}.
683 The precise meaning of this intrinsic might change
684 in a future version of the GNU Fortran language,
685 as more is learned about how it is used.
688 DEFDOC (LEN, "Length of character entity.", "\
689 Returns the length of @var{@1@}.
691 If @var{@1@} is an array, the length of an element
692 of @var{@1@} is returned.
694 Note that @var{@1@} need not be defined when this
695 intrinsic is invoked, since only the length, not
696 the content, of @var{@1@} is needed.
698 @xref{Bit_Size Intrinsic}, for the function that determines
699 the size of its argument in bits.
702 DEFDOC (TAN, "Tangent.", "\
703 Returns the tangent of @var{@1@}, an angle measured
704 in radians.
706 @xref{ATan Intrinsic}, for the inverse of this function.
709 DEFDOC (DTAN, "Tangent (archaic).", ARCHAIC (TAN, Tan))
711 DEFDOC (TANH, "Hyperbolic tangent.", "\
712 Returns the hyperbolic tangent of @var{@1@}.
715 DEFDOC (DTANH, "Hyperbolic tangent (archaic).", ARCHAIC (TANH, TanH))
717 DEFDOC (SNGL, "Convert (archaic).", ARCHAIC (REAL, Real))
719 DEFDOC (SIN, "Sine.", "\
720 Returns the sine of @var{@1@}, an angle measured
721 in radians.
723 @xref{ASin Intrinsic}, for the inverse of this function.
726 DEFDOC (CSIN, "Sine (archaic).", ARCHAIC (SIN, Sin))
728 DEFDOC (DSIN, "Sine (archaic).", ARCHAIC (SIN, Sin))
730 DEFDOC (CDSIN, "Sine (archaic).", ARCHAIC (SIN, Sin))
732 DEFDOC (SINH, "Hyperbolic sine.", "\
733 Returns the hyperbolic sine of @var{@1@}.
736 DEFDOC (DSINH, "Hyperbolic sine (archaic).", ARCHAIC (SINH, SinH))
738 DEFDOC (LSHIFT, "Left-shift bits.", "\
739 Returns @var{@1@} shifted to the left
740 @var{@2@} bits.
742 Although similar to the expression
743 @samp{@var{@1@}*(2**@var{@2@})}, there
744 are important differences.
745 For example, the sign of the result is
746 not necessarily the same as the sign of
747 @var{@1@}.
749 Currently this intrinsic is defined assuming
750 the underlying representation of @var{@1@}
751 is as a two's-complement integer.
752 It is unclear at this point whether that
753 definition will apply when a different
754 representation is involved.
756 @xref{LShift Intrinsic}, for the inverse of this function.
758 @xref{IShft Intrinsic}, for information
759 on a more widely available left-shifting
760 intrinsic that is also more precisely defined.
763 DEFDOC (RSHIFT, "Right-shift bits.", "\
764 Returns @var{@1@} shifted to the right
765 @var{@2@} bits.
767 Although similar to the expression
768 @samp{@var{@1@}/(2**@var{@2@})}, there
769 are important differences.
770 For example, the sign of the result is
771 undefined.
773 Currently this intrinsic is defined assuming
774 the underlying representation of @var{@1@}
775 is as a two's-complement integer.
776 It is unclear at this point whether that
777 definition will apply when a different
778 representation is involved.
780 @xref{RShift Intrinsic}, for the inverse of this function.
782 @xref{IShft Intrinsic}, for information
783 on a more widely available right-shifting
784 intrinsic that is also more precisely defined.
787 DEFDOC (LGE, "Lexically greater than or equal.", "\
788 Returns @samp{.TRUE.} if @samp{@var{@1@}.GE.@var{@2@}},
789 @samp{.FALSE.} otherwise.
790 @var{@1@} and @var{@2@} are interpreted as containing
791 ASCII character codes.
792 If either value contains a character not in the ASCII
793 character set, the result is processor dependent.
795 If the @var{@1@} and @var{@2@} are not the same length,
796 the shorter is compared as if spaces were appended to
797 it to form a value that has the same length as the longer.
799 The lexical comparison intrinsics @code{LGe}, @code{LGt},
800 @code{LLe}, and @code{LLt} differ from the corresponding
801 intrinsic operators @code{.GE.}, @code{.GT.},
802 @code{.LE.}, @code{.LT.}.
803 Because the ASCII collating sequence is assumed,
804 the following expressions always return @samp{.TRUE.}:
806 @smallexample
807 LGE ('0', ' ')
808 LGE ('A', '0')
809 LGE ('a', 'A')
810 @end smallexample
812 The following related expressions do @emph{not} always
813 return @samp{.TRUE.}, as they are not necessarily evaluated
814 assuming the arguments use ASCII encoding:
816 @smallexample
817 '0' .GE. ' '
818 'A' .GE. '0'
819 'a' .GE. 'A'
820 @end smallexample
822 The same difference exists
823 between @code{LGt} and @code{.GT.};
824 between @code{LLe} and @code{.LE.}; and
825 between @code{LLt} and @code{.LT.}.
828 DEFDOC (LGT, "Lexically greater than.", "\
829 Returns @samp{.TRUE.} if @samp{@var{@1@}.GT.@var{@2@}},
830 @samp{.FALSE.} otherwise.
831 @var{@1@} and @var{@2@} are interpreted as containing
832 ASCII character codes.
833 If either value contains a character not in the ASCII
834 character set, the result is processor dependent.
836 If the @var{@1@} and @var{@2@} are not the same length,
837 the shorter is compared as if spaces were appended to
838 it to form a value that has the same length as the longer.
840 @xref{LGe Intrinsic}, for information on the distinction
841 between the @code{@0@} intrinsic and the @code{.GT.}
842 operator.
845 DEFDOC (LLE, "Lexically less than or equal.", "\
846 Returns @samp{.TRUE.} if @samp{@var{@1@}.LE.@var{@2@}},
847 @samp{.FALSE.} otherwise.
848 @var{@1@} and @var{@2@} are interpreted as containing
849 ASCII character codes.
850 If either value contains a character not in the ASCII
851 character set, the result is processor dependent.
853 If the @var{@1@} and @var{@2@} are not the same length,
854 the shorter is compared as if spaces were appended to
855 it to form a value that has the same length as the longer.
857 @xref{LGe Intrinsic}, for information on the distinction
858 between the @code{@0@} intrinsic and the @code{.LE.}
859 operator.
862 DEFDOC (LLT, "Lexically less than.", "\
863 Returns @samp{.TRUE.} if @samp{@var{@1@}.LT.@var{@2@}},
864 @samp{.FALSE.} otherwise.
865 @var{@1@} and @var{@2@} are interpreted as containing
866 ASCII character codes.
867 If either value contains a character not in the ASCII
868 character set, the result is processor dependent.
870 If the @var{@1@} and @var{@2@} are not the same length,
871 the shorter is compared as if spaces were appended to
872 it to form a value that has the same length as the longer.
874 @xref{LGe Intrinsic}, for information on the distinction
875 between the @code{@0@} intrinsic and the @code{.LT.}
876 operator.
879 DEFDOC (SIGN, "Apply sign to magnitude.", "\
880 Returns @samp{ABS(@var{@1@})*@var{s}}, where
881 @var{s} is +1 if @samp{@var{@2@}.GE.0},
882 -1 otherwise.
884 @xref{Abs Intrinsic}, for the function that returns
885 the magnitude of a value.
888 DEFDOC (DSIGN, "Apply sign to magnitude (archaic).", ARCHAIC_2 (SIGN, Sign))
889 DEFDOC (ISIGN, "Apply sign to magnitude (archaic).", ARCHAIC_2 (SIGN, Sign))
891 DEFDOC (REAL, "Convert value to type @code{REAL(KIND=1)}.", "\
892 Converts @var{@1@} to @code{REAL(KIND=1)}.
894 Use of @code{@0@()} with a @code{COMPLEX} argument
895 (other than @code{COMPLEX(KIND=1)}) is restricted to the following case:
897 @example
898 REAL(REAL(@1@))
899 @end example
901 @noindent
902 This expression converts the real part of @1@ to
903 @code{REAL(KIND=1)}.
905 @xref{RealPart Intrinsic}, for information on a GNU Fortran
906 intrinsic that extracts the real part of an arbitrary
907 @code{COMPLEX} value.
909 @xref{REAL() and AIMAG() of Complex}, for more information.
912 DEFDOC (DREAL, "Convert value to type @code{REAL(KIND=2)}.", "\
913 Converts @var{@1@} to @code{REAL(KIND=2)}.
915 If @var{@1@} is type @code{COMPLEX}, its real part
916 is converted (if necessary) to @code{REAL(KIND=2)},
917 and its imaginary part is disregarded.
919 Although this intrinsic is not standard Fortran,
920 it is a popular extension offered by many compilers
921 that support @code{DOUBLE COMPLEX}, since it offers
922 the easiest way to extract the real part of a @code{DOUBLE COMPLEX}
923 value without using the Fortran 90 @code{REAL()} intrinsic
924 in a way that produces a return value inconsistent with
925 the way many FORTRAN 77 compilers handle @code{REAL()} of
926 a @code{DOUBLE COMPLEX} value.
928 @xref{RealPart Intrinsic}, for information on a GNU Fortran
929 intrinsic that avoids these areas of confusion.
931 @xref{Dble Intrinsic}, for information on the standard FORTRAN 77
932 replacement for @code{DREAL()}.
934 @xref{REAL() and AIMAG() of Complex}, for more information on
935 this issue.
938 DEFDOC (IMAGPART, "Extract imaginary part of complex.", "\
939 The imaginary part of @var{@1@} is returned, without conversion.
941 @emph{Note:} The way to do this in standard Fortran 90
942 is @samp{AIMAG(@var{@1@})}.
943 However, when, for example, @var{@1@} is @code{DOUBLE COMPLEX},
944 @samp{AIMAG(@var{@1@})} means something different for some compilers
945 that are not true Fortran 90 compilers but offer some
946 extensions standardized by Fortran 90 (such as the
947 @code{DOUBLE COMPLEX} type, also known as @code{COMPLEX(KIND=2)}).
949 The advantage of @code{@0@()} is that, while not necessarily
950 more or less portable than @code{AIMAG()}, it is more likely to
951 cause a compiler that doesn't support it to produce a diagnostic
952 than generate incorrect code.
954 @xref{REAL() and AIMAG() of Complex}, for more information.
957 DEFDOC (COMPLEX, "Build complex value from real and@99@imaginary parts.", "\
958 Returns a @code{COMPLEX} value that has @samp{@1@} and @samp{@2@} as its
959 real and imaginary parts, respectively.
961 If @var{@1@} and @var{@2@} are the same type, and that type is not
962 @code{INTEGER}, no data conversion is performed, and the type of
963 the resulting value has the same kind value as the types
964 of @var{@1@} and @var{@2@}.
966 If @var{@1@} and @var{@2@} are not the same type, the usual type-promotion
967 rules are applied to both, converting either or both to the
968 appropriate @code{REAL} type.
969 The type of the resulting value has the same kind value as the
970 type to which both @var{@1@} and @var{@2@} were converted, in this case.
972 If @var{@1@} and @var{@2@} are both @code{INTEGER}, they are both converted
973 to @code{REAL(KIND=1)}, and the result of the @code{@0@()}
974 invocation is type @code{COMPLEX(KIND=1)}.
976 @emph{Note:} The way to do this in standard Fortran 90
977 is too hairy to describe here, but it is important to
978 note that @samp{CMPLX(D1,D2)} returns a @code{COMPLEX(KIND=1)}
979 result even if @samp{D1} and @samp{D2} are type @code{REAL(KIND=2)}.
980 Hence the availability of @code{COMPLEX()} in GNU Fortran.
983 DEFDOC (LOC, "Address of entity in core.", "\
984 The @code{LOC()} intrinsic works the
985 same way as the @code{%LOC()} construct.
986 @xref{%LOC(),,The @code{%LOC()} Construct}, for
987 more information.
990 DEFDOC (REALPART, "Extract real part of complex.", "\
991 The real part of @var{@1@} is returned, without conversion.
993 @emph{Note:} The way to do this in standard Fortran 90
994 is @samp{REAL(@var{@1@})}.
995 However, when, for example, @var{@1@} is @code{COMPLEX(KIND=2)},
996 @samp{REAL(@var{@1@})} means something different for some compilers
997 that are not true Fortran 90 compilers but offer some
998 extensions standardized by Fortran 90 (such as the
999 @code{DOUBLE COMPLEX} type, also known as @code{COMPLEX(KIND=2)}).
1001 The advantage of @code{@0@()} is that, while not necessarily
1002 more or less portable than @code{REAL()}, it is more likely to
1003 cause a compiler that doesn't support it to produce a diagnostic
1004 than generate incorrect code.
1006 @xref{REAL() and AIMAG() of Complex}, for more information.
1009 DEFDOC (GETARG, "Obtain command-line argument.", "\
1010 Sets @var{@2@} to the @var{@1@}-th command-line argument (or to all
1011 blanks if there are fewer than @var{@2@} command-line arguments);
1012 @code{CALL @0@(0, @var{value})} sets @var{value} to the name of the
1013 program (on systems that support this feature).
1015 @xref{IArgC Intrinsic}, for information on how to get the number
1016 of arguments.
1019 DEFDOC (ABORT, "Abort the program.", "\
1020 Prints a message and potentially causes a core dump via @code{abort(3)}.
1023 DEFDOC (EXIT, "Terminate the program.", "\
1024 Exit the program with status @var{@1@} after closing open Fortran
1025 I/O units and otherwise behaving as @code{exit(2)}.
1026 If @var{@1@} is omitted the canonical `success' value
1027 will be returned to the system.
1030 DEFDOC (IARGC, "Obtain count of command-line arguments.", "\
1031 Returns the number of command-line arguments.
1033 This count does not include the specification of the program
1034 name itself.
1037 DEFDOC (CTIME_func, "Convert time to Day Mon dd hh:mm:ss yyyy.", "\
1038 Converts @var{@1@}, a system time value, such as returned by
1039 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995},
1040 and returns that string as the function value.
1042 @xref{Time8 Intrinsic}.
1045 DEFDOC (CTIME_subr, "Convert time to Day Mon dd hh:mm:ss yyyy.", "\
1046 Converts @var{@1@}, a system time value, such as returned by
1047 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995},
1048 and returns that string in @var{@2@}.
1050 @xref{Time8 Intrinsic}.
1052 Some non-GNU implementations of Fortran provide this intrinsic as
1053 only a function, not as a subroutine.
1056 DEFDOC (DATE, "Get current date as dd-Mon-yy.", "\
1057 Returns @var{@1@} in the form @samp{@var{dd}-@var{mmm}-@var{yy}},
1058 representing the numeric day of the month @var{dd}, a three-character
1059 abbreviation of the month name @var{mmm} and the last two digits of
1060 the year @var{yy}, e.g.@: @samp{25-Nov-96}.
1062 @cindex Y2K compliance
1063 @cindex Year 2000 compliance
1064 This intrinsic is not recommended, due to the year 2000 approaching.
1065 Therefore, programs making use of this intrinsic
1066 might not be Year 2000 (Y2K) compliant.
1067 @xref{CTime Intrinsic (subroutine)}, for information on obtaining more digits
1068 for the current (or any) date.
1071 DEFDOC (DTIME_func, "Get elapsed time since last time.", "\
1072 Initially, return the number of seconds of runtime
1073 since the start of the process's execution
1074 as the function value,
1075 and the user and system components of this in @samp{@var{@1@}(1)}
1076 and @samp{@var{@1@}(2)} respectively.
1077 The functions' value is equal to @samp{@var{@1@}(1) + @var{@1@}(2)}.
1079 Subsequent invocations of @samp{@0@()} return values accumulated since the
1080 previous invocation.
1082 @cindex wraparound, timings
1083 @cindex limits, timings
1084 On some systems, the underlying timings are represented
1085 using types with sufficiently small limits that overflows
1086 (wraparounds) are possible, such as 32-bit types.
1087 Therefore, the values returned by this intrinsic
1088 might be, or become, negative,
1089 or numerically less than previous values,
1090 during a single run of the compiled program.
1092 Due to the side effects performed by this intrinsic, the function
1093 form is not recommended.
1096 DEFDOC (DTIME_subr, "Get elapsed time since last time.", "\
1097 Initially, return the number of seconds of runtime
1098 since the start of the process's execution
1099 in @var{@2@},
1100 and the user and system components of this in @samp{@var{@1@}(1)}
1101 and @samp{@var{@1@}(2)} respectively.
1102 The value of @var{@2@} is equal to @samp{@var{@1@}(1) + @var{@1@}(2)}.
1104 Subsequent invocations of @samp{@0@()} set values based on accumulations
1105 since the previous invocation.
1107 @cindex wraparound, timings
1108 @cindex limits, timings
1109 On some systems, the underlying timings are represented
1110 using types with sufficiently small limits that overflows
1111 (wraparounds) are possible, such as 32-bit types.
1112 Therefore, the values returned by this intrinsic
1113 might be, or become, negative,
1114 or numerically less than previous values,
1115 during a single run of the compiled program.
1117 Some non-GNU implementations of Fortran provide this intrinsic as
1118 only a function, not as a subroutine.
1121 DEFDOC (ETIME_func, "Get elapsed time for process.", "\
1122 Return the number of seconds of runtime
1123 since the start of the process's execution
1124 as the function value,
1125 and the user and system components of this in @samp{@var{@1@}(1)}
1126 and @samp{@var{@1@}(2)} respectively.
1127 The functions' value is equal to @samp{@var{@1@}(1) + @var{@1@}(2)}.
1129 @cindex wraparound, timings
1130 @cindex limits, timings
1131 On some systems, the underlying timings are represented
1132 using types with sufficiently small limits that overflows
1133 (wraparounds) are possible, such as 32-bit types.
1134 Therefore, the values returned by this intrinsic
1135 might be, or become, negative,
1136 or numerically less than previous values,
1137 during a single run of the compiled program.
1140 DEFDOC (ETIME_subr, "Get elapsed time for process.", "\
1141 Return the number of seconds of runtime
1142 since the start of the process's execution
1143 in @var{@2@},
1144 and the user and system components of this in @samp{@var{@1@}(1)}
1145 and @samp{@var{@1@}(2)} respectively.
1146 The value of @var{@2@} is equal to @samp{@var{@1@}(1) + @var{@1@}(2)}.
1148 @cindex wraparound, timings
1149 @cindex limits, timings
1150 On some systems, the underlying timings are represented
1151 using types with sufficiently small limits that overflows
1152 (wraparounds) are possible, such as 32-bit types.
1153 Therefore, the values returned by this intrinsic
1154 might be, or become, negative,
1155 or numerically less than previous values,
1156 during a single run of the compiled program.
1158 Some non-GNU implementations of Fortran provide this intrinsic as
1159 only a function, not as a subroutine.
1162 DEFDOC (FDATE_func, "Get current time as Day Mon dd hh:mm:ss yyyy.", "\
1163 Returns the current date (using the same format as @code{CTIME()}).
1165 Equivalent to:
1167 @example
1168 CTIME(TIME8())
1169 @end example
1171 @cindex Y10K compliance
1172 @cindex Year 10000 compliance
1173 @cindex wraparound, Y10K
1174 @cindex limits, Y10K
1175 Programs making use of this intrinsic
1176 might not be Year 10000 (Y10K) compliant.
1177 For example, the date might appear,
1178 to such programs, to wrap around
1179 (change from a larger value to a smaller one)
1180 as of the Year 10000.
1182 @xref{CTime Intrinsic (function)}.
1185 DEFDOC (FDATE_subr, "Get current time as Day Mon dd hh:mm:ss yyyy.", "\
1186 Returns the current date (using the same format as @code{CTIME()})
1187 in @var{@1@}.
1189 Equivalent to:
1191 @example
1192 CALL CTIME(@var{@1@}, TIME8())
1193 @end example
1195 @cindex Y10K compliance
1196 @cindex Year 10000 compliance
1197 @cindex wraparound, Y10K
1198 @cindex limits, Y10K
1199 Programs making use of this intrinsic
1200 might not be Year 10000 (Y10K) compliant.
1201 For example, the date might appear,
1202 to such programs, to wrap around
1203 (change from a larger value to a smaller one)
1204 as of the Year 10000.
1206 @xref{CTime Intrinsic (subroutine)}.
1208 Some non-GNU implementations of Fortran provide this intrinsic as
1209 only a function, not as a subroutine.
1212 DEFDOC (GMTIME, "Convert time to GMT time info.", "\
1213 Given a system time value @var{@1@}, fills @var{@2@} with values
1214 extracted from it appropriate to the GMT time zone using
1215 @code{gmtime(3)}.
1217 The array elements are as follows:
1219 @enumerate
1220 @item
1221 Seconds after the minute, range 0--59 or 0--61 to allow for leap
1222 seconds
1224 @item
1225 Minutes after the hour, range 0--59
1227 @item
1228 Hours past midnight, range 0--23
1230 @item
1231 Day of month, range 0--31
1233 @item
1234 Number of months since January, range 0--12
1236 @item
1237 Years since 1900
1239 @item
1240 Number of days since Sunday, range 0--6
1242 @item
1243 Days since January 1
1245 @item
1246 Daylight savings indicator: positive if daylight savings is in effect,
1247 zero if not, and negative if the information isn't available.
1248 @end enumerate
1251 DEFDOC (LTIME, "Convert time to local time info.", "\
1252 Given a system time value @var{@1@}, fills @var{@2@} with values
1253 extracted from it appropriate to the GMT time zone using
1254 @code{localtime(3)}.
1256 The array elements are as follows:
1258 @enumerate
1259 @item
1260 Seconds after the minute, range 0--59 or 0--61 to allow for leap
1261 seconds
1263 @item
1264 Minutes after the hour, range 0--59
1266 @item
1267 Hours past midnight, range 0--23
1269 @item
1270 Day of month, range 0--31
1272 @item
1273 Number of months since January, range 0--12
1275 @item
1276 Years since 1900
1278 @item
1279 Number of days since Sunday, range 0--6
1281 @item
1282 Days since January 1
1284 @item
1285 Daylight savings indicator: positive if daylight savings is in effect,
1286 zero if not, and negative if the information isn't available.
1287 @end enumerate
1290 DEFDOC (IDATE_unix, "Get local time info.", "\
1291 Fills @var{@1@} with the numerical values at the current local time
1292 of day, month (in the range 1--12), and year in elements 1, 2, and 3,
1293 respectively.
1294 The year has four significant digits.
1296 @cindex Y10K compliance
1297 @cindex Year 10000 compliance
1298 @cindex wraparound, Y10K
1299 @cindex limits, Y10K
1300 Programs making use of this intrinsic
1301 might not be Year 10000 (Y10K) compliant.
1302 For example, the date might appear,
1303 to such programs, to wrap around
1304 (change from a larger value to a smaller one)
1305 as of the Year 10000.
1308 DEFDOC (IDATE_vxt, "Get local time info (VAX/VMS).", "\
1309 Returns the numerical values of the current local time.
1310 The month (in the range 1--12) is returned in @var{@1@},
1311 the day (in the range 1--7) in @var{@2@},
1312 and the year in @var{@3@} (in the range 0--99).
1314 @cindex Y2K compliance
1315 @cindex Year 2000 compliance
1316 @cindex wraparound, Y2K
1317 @cindex limits, Y2K
1318 This intrinsic is not recommended, due to the year 2000 approaching.
1319 Therefore, programs making use of this intrinsic
1320 might not be Year 2000 (Y2K) compliant.
1321 For example, the date might appear,
1322 to such programs, to wrap around
1323 (change from a larger value to a smaller one)
1324 as of the Year 2000.
1326 @xref{IDate Intrinsic (UNIX)}, for information on obtaining more digits
1327 for the current date.
1330 DEFDOC (ITIME, "Get local time of day.", "\
1331 Returns the current local time hour, minutes, and seconds in elements
1332 1, 2, and 3 of @var{@1@}, respectively.
1335 DEFDOC (MCLOCK, "Get number of clock ticks for process.", "\
1336 Returns the number of clock ticks since the start of the process.
1337 Supported on systems with @code{clock(3)} (q.v.).
1339 @cindex wraparound, timings
1340 @cindex limits, timings
1341 This intrinsic is not fully portable, such as to systems
1342 with 32-bit @code{INTEGER} types but supporting times
1343 wider than 32 bits.
1344 Therefore, the values returned by this intrinsic
1345 might be, or become, negative,
1346 or numerically less than previous values,
1347 during a single run of the compiled program.
1349 @xref{MClock8 Intrinsic}, for information on a
1350 similar intrinsic that might be portable to more
1351 GNU Fortran implementations, though to fewer
1352 Fortran compilers.
1354 If the system does not support @code{clock(3)},
1355 -1 is returned.
1358 DEFDOC (MCLOCK8, "Get number of clock ticks for process.", "\
1359 Returns the number of clock ticks since the start of the process.
1360 Supported on systems with @code{clock(3)} (q.v.).
1362 @cindex wraparound, timings
1363 @cindex limits, timings
1364 @emph{Warning:} this intrinsic does not increase the range
1365 of the timing values over that returned by @code{clock(3)}.
1366 On a system with a 32-bit @code{clock(3)},
1367 @code{@0@} will return a 32-bit value,
1368 even though converted to an @samp{INTEGER(KIND=2)} value.
1369 That means overflows of the 32-bit value can still occur.
1370 Therefore, the values returned by this intrinsic
1371 might be, or become, negative,
1372 or numerically less than previous values,
1373 during a single run of the compiled program.
1375 No Fortran implementations other than GNU Fortran are
1376 known to support this intrinsic at the time of this
1377 writing.
1378 @xref{MClock Intrinsic}, for information on a
1379 similar intrinsic that might be portable to more Fortran
1380 compilers, though to fewer GNU Fortran implementations.
1382 If the system does not support @code{clock(3)},
1383 -1 is returned.
1386 DEFDOC (SECNDS, "Get local time offset since midnight.", "\
1387 Returns the local time in seconds since midnight minus the value
1388 @var{@1@}.
1390 @cindex wraparound, timings
1391 @cindex limits, timings
1392 This values returned by this intrinsic
1393 become numerically less than previous values
1394 (they wrap around) during a single run of the
1395 compiler program, under normal circumstances
1396 (such as running through the midnight hour).
1399 DEFDOC (SECOND_func, "Get CPU time for process in seconds.", "\
1400 Returns the process's runtime in seconds---the same value as the
1401 UNIX function @code{etime} returns.
1403 @cindex wraparound, timings
1404 @cindex limits, timings
1405 On some systems, the underlying timings are represented
1406 using types with sufficiently small limits that overflows
1407 (wraparounds) are possible, such as 32-bit types.
1408 Therefore, the values returned by this intrinsic
1409 might be, or become, negative,
1410 or numerically less than previous values,
1411 during a single run of the compiled program.
1414 DEFDOC (SECOND_subr, "Get CPU time for process@99@in seconds.", "\
1415 Returns the process's runtime in seconds in @var{@1@}---the same value
1416 as the UNIX function @code{etime} returns.
1418 @cindex wraparound, timings
1419 @cindex limits, timings
1420 On some systems, the underlying timings are represented
1421 using types with sufficiently small limits that overflows
1422 (wraparounds) are possible, such as 32-bit types.
1423 Therefore, the values returned by this intrinsic
1424 might be, or become, negative,
1425 or numerically less than previous values,
1426 during a single run of the compiled program.
1428 This routine is known from Cray Fortran.  @xref{CPU_Time Intrinsic},
1429 for a standard equivalent.
1432 DEFDOC (SYSTEM_CLOCK, "Get current system clock value.", "\
1433 Returns in @var{@1@} the current value of the system clock; this is
1434 the value returned by the UNIX function @code{times(2)}
1435 in this implementation, but
1436 isn't in general.
1437 @var{@2@} is the number of clock ticks per second and
1438 @var{@3@} is the maximum value this can take, which isn't very useful
1439 in this implementation since it's just the maximum C @code{unsigned
1440 int} value.
1442 @cindex wraparound, timings
1443 @cindex limits, timings
1444 On some systems, the underlying timings are represented
1445 using types with sufficiently small limits that overflows
1446 (wraparounds) are possible, such as 32-bit types.
1447 Therefore, the values returned by this intrinsic
1448 might be, or become, negative,
1449 or numerically less than previous values,
1450 during a single run of the compiled program.
1453 DEFDOC (CPU_TIME, "Get current CPU time.", "\
1454 Returns in @var{@1@} the current value of the system time.
1455 This implementation of the Fortran 95 intrinsic is just an alias for
1456 @code{second} @xref{Second Intrinsic (subroutine)}.
1458 @cindex wraparound, timings
1459 @cindex limits, timings
1460 On some systems, the underlying timings are represented
1461 using types with sufficiently small limits that overflows
1462 (wraparounds) are possible, such as 32-bit types.
1463 Therefore, the values returned by this intrinsic
1464 might be, or become, negative,
1465 or numerically less than previous values,
1466 during a single run of the compiled program.
1469 DEFDOC (TIME8, "Get current time as time value.", "\
1470 Returns the current time encoded as a long integer
1471 (in the manner of the UNIX function @code{time(3)}).
1472 This value is suitable for passing to @code{CTIME},
1473 @code{GMTIME}, and @code{LTIME}.
1475 @cindex wraparound, timings
1476 @cindex limits, timings
1477 @emph{Warning:} this intrinsic does not increase the range
1478 of the timing values over that returned by @code{time(3)}.
1479 On a system with a 32-bit @code{time(3)},
1480 @code{@0@} will return a 32-bit value,
1481 even though converted to an @samp{INTEGER(KIND=2)} value.
1482 That means overflows of the 32-bit value can still occur.
1483 Therefore, the values returned by this intrinsic
1484 might be, or become, negative,
1485 or numerically less than previous values,
1486 during a single run of the compiled program.
1488 No Fortran implementations other than GNU Fortran are
1489 known to support this intrinsic at the time of this
1490 writing.
1491 @xref{Time Intrinsic (UNIX)}, for information on a
1492 similar intrinsic that might be portable to more Fortran
1493 compilers, though to fewer GNU Fortran implementations.
1496 DEFDOC (TIME_unix, "Get current time as time value.", "\
1497 Returns the current time encoded as an integer
1498 (in the manner of the UNIX function @code{time(3)}).
1499 This value is suitable for passing to @code{CTIME},
1500 @code{GMTIME}, and @code{LTIME}.
1502 @cindex wraparound, timings
1503 @cindex limits, timings
1504 This intrinsic is not fully portable, such as to systems
1505 with 32-bit @code{INTEGER} types but supporting times
1506 wider than 32 bits.
1507 Therefore, the values returned by this intrinsic
1508 might be, or become, negative,
1509 or numerically less than previous values,
1510 during a single run of the compiled program.
1512 @xref{Time8 Intrinsic}, for information on a
1513 similar intrinsic that might be portable to more
1514 GNU Fortran implementations, though to fewer
1515 Fortran compilers.
1518 #define BES(num,n,val) "\
1519 Calculates the Bessel function of the " #num " kind of \
1520 order " #n " of @var{@" #val "@}.\n\
1521 See @code{bessel(3m)}, on whose implementation the \
1522 function depends.\
1525 DEFDOC (BESJ0, "Bessel function.", BES (first, 0, 1))
1526 DEFDOC (BESJ1, "Bessel function.", BES (first, 1, 1))
1527 DEFDOC (BESJN, "Bessel function.", BES (first, @var{N}, 2))
1528 DEFDOC (BESY0, "Bessel function.", BES (second, 0, 1))
1529 DEFDOC (BESY1, "Bessel function.", BES (second, 1, 1))
1530 DEFDOC (BESYN, "Bessel function.", BES (second, @var{N}, 2))
1531 DEFDOC (DBESJ0, "Bessel function (archaic).", ARCHAIC (BESJ0, BesJ0))
1532 DEFDOC (DBESJ1, "Bessel function (archaic).", ARCHAIC (BESJ1, BesJ1))
1533 DEFDOC (DBESJN, "Bessel function (archaic).", ARCHAIC_2nd (BESJN, BesJN))
1534 DEFDOC (DBESY0, "Bessel function (archaic).", ARCHAIC (BESY0, BesY0))
1535 DEFDOC (DBESY1, "Bessel function (archaic).", ARCHAIC (BESY1, BesY1))
1536 DEFDOC (DBESYN, "Bessel function (archaic).", ARCHAIC_2nd (BESYN, BesYN))
1538 DEFDOC (ERF, "Error function.", "\
1539 Returns the error function of @var{@1@}.
1540 See @code{erf(3m)}, which provides the implementation.
1543 DEFDOC (ERFC, "Complementary error function.", "\
1544 Returns the complementary error function of @var{@1@}:
1545 @samp{ERFC(R) = 1 - ERF(R)} (except that the result might be more
1546 accurate than explicitly evaluating that formulae would give).
1547 See @code{erfc(3m)}, which provides the implementation.
1550 DEFDOC (DERF, "Error function (archaic).", ARCHAIC (ERF, ErF))
1551 DEFDOC (DERFC, "Complementary error function (archaic).", ARCHAIC (ERFC, ErFC))
1553 DEFDOC (IRAND, "Random number.", "\
1554 Returns a uniform quasi-random number up to a system-dependent limit.
1555 If @var{@1@} is 0, the next number in sequence is returned; if
1556 @var{@1@} is 1, the generator is restarted by calling the UNIX function
1557 @samp{srand(0)}; if @var{@1@} has any other value,
1558 it is used as a new seed with @code{srand()}.
1560 @xref{SRand Intrinsic}.
1562 @emph{Note:} As typically implemented (by the routine of the same
1563 name in the C library), this random number generator is a very poor
1564 one, though the BSD and GNU libraries provide a much better
1565 implementation than the `traditional' one.
1566 On a different system you almost certainly want to use something better.
1569 DEFDOC (RAND, "Random number.", "\
1570 Returns a uniform quasi-random number between 0 and 1.
1571 If @var{@1@} is 0, the next number in sequence is returned; if
1572 @var{@1@} is 1, the generator is restarted by calling @samp{srand(0)};
1573 if @var{@1@} has any other value, it is used as a new seed with
1574 @code{srand}.
1576 @xref{SRand Intrinsic}.
1578 @emph{Note:} As typically implemented (by the routine of the same
1579 name in the C library), this random number generator is a very poor
1580 one, though the BSD and GNU libraries provide a much better
1581 implementation than the `traditional' one.
1582 On a different system you
1583 almost certainly want to use something better.
1586 DEFDOC (SRAND, "Random seed.", "\
1587 Reinitializes the generator with the seed in @var{@1@}.
1588 @xref{IRand Intrinsic}.
1589 @xref{Rand Intrinsic}.
1592 DEFDOC (ACCESS, "Check file accessibility.", "\
1593 Checks file @var{@1@} for accessibility in the mode specified by @var{@2@} and
1594 returns 0 if the file is accessible in that mode, otherwise an error
1595 code if the file is inaccessible or @var{@2@} is invalid.
1596 See @code{access(2)}.
1597 A null character (@samp{CHAR(0)}) marks the end of
1598 the name in @var{@1@}---otherwise,
1599 trailing blanks in @var{@1@} are ignored.
1600 @var{@2@} may be a concatenation of any of the following characters:
1602 @table @samp
1603 @item r
1604 Read permission
1606 @item w
1607 Write permission
1609 @item x
1610 Execute permission
1612 @item @kbd{SPC}
1613 Existence
1614 @end table
1617 DEFDOC (CHDIR_subr, "Change directory.", "\
1618 Sets the current working directory to be @var{@1@}.
1619 If the @var{@2@} argument is supplied, it contains 0
1620 on success or a nonzero error code otherwise upon return.
1621 See @code{chdir(3)}.
1623 @emph{Caution:} Using this routine during I/O to a unit connected with a
1624 non-absolute file name can cause subsequent I/O on such a unit to fail
1625 because the I/O library might reopen files by name.
1627 Some non-GNU implementations of Fortran provide this intrinsic as
1628 only a function, not as a subroutine, or do not support the
1629 (optional) @var{@2@} argument.
1632 DEFDOC (CHDIR_func, "Change directory.", "\
1633 Sets the current working directory to be @var{@1@}.
1634 Returns 0 on success or a nonzero error code.
1635 See @code{chdir(3)}.
1637 @emph{Caution:} Using this routine during I/O to a unit connected with a
1638 non-absolute file name can cause subsequent I/O on such a unit to fail
1639 because the I/O library might reopen files by name.
1641 Due to the side effects performed by this intrinsic, the function
1642 form is not recommended.
1645 DEFDOC (CHMOD_func, "Change file modes.", "\
1646 Changes the access mode of file @var{@1@} according to the
1647 specification @var{@2@}, which is given in the format of
1648 @code{chmod(1)}.
1649 A null character (@samp{CHAR(0)}) marks the end of
1650 the name in @var{@1@}---otherwise,
1651 trailing blanks in @var{@1@} are ignored.
1652 Currently, @var{@1@} must not contain the single quote
1653 character.
1655 Returns 0 on success or a nonzero error code otherwise.
1657 Note that this currently works
1658 by actually invoking @code{/bin/chmod} (or the @code{chmod} found when
1659 the library was configured) and so might fail in some circumstances and
1660 will, anyway, be slow.
1662 Due to the side effects performed by this intrinsic, the function
1663 form is not recommended.
1666 DEFDOC (CHMOD_subr, "Change file modes.", "\
1667 Changes the access mode of file @var{@1@} according to the
1668 specification @var{@2@}, which is given in the format of
1669 @code{chmod(1)}.
1670 A null character (@samp{CHAR(0)}) marks the end of
1671 the name in @var{@1@}---otherwise,
1672 trailing blanks in @var{@1@} are ignored.
1673 Currently, @var{@1@} must not contain the single quote
1674 character.
1676 If the @var{@3@} argument is supplied, it contains
1677 0 on success or a nonzero error code upon return.
1679 Note that this currently works
1680 by actually invoking @code{/bin/chmod} (or the @code{chmod} found when
1681 the library was configured) and so might fail in some circumstances and
1682 will, anyway, be slow.
1684 Some non-GNU implementations of Fortran provide this intrinsic as
1685 only a function, not as a subroutine, or do not support the
1686 (optional) @var{@3@} argument.
1689 DEFDOC (GETCWD_func, "Get current working directory.", "\
1690 Places the current working directory in @var{@1@}.
1691 Returns 0 on
1692 success, otherwise a nonzero error code
1693 (@code{ENOSYS} if the system does not provide @code{getcwd(3)}
1694 or @code{getwd(3)}).
1697 DEFDOC (GETCWD_subr, "Get current working directory.", "\
1698 Places the current working directory in @var{@1@}.
1699 If the @var{@2@} argument is supplied, it contains 0
1700 success or a nonzero error code upon return
1701 (@code{ENOSYS} if the system does not provide @code{getcwd(3)}
1702 or @code{getwd(3)}).
1704 Some non-GNU implementations of Fortran provide this intrinsic as
1705 only a function, not as a subroutine, or do not support the
1706 (optional) @var{@2@} argument.
1709 DEFDOC (FSTAT_func, "Get file information.", "\
1710 Obtains data about the file open on Fortran I/O unit @var{@1@} and
1711 places them in the array @var{@2@}.
1712 The values in this array are
1713 extracted from the @code{stat} structure as returned by
1714 @code{fstat(2)} q.v., as follows:
1716 @enumerate
1717 @item
1718 Device ID
1720 @item
1721 Inode number
1723 @item
1724 File mode
1726 @item
1727 Number of links
1729 @item
1730 Owner's uid
1732 @item
1733 Owner's gid
1735 @item
1736 ID of device containing directory entry for file
1737 (0 if not available)
1739 @item
1740 File size (bytes)
1742 @item
1743 Last access time
1745 @item
1746 Last modification time
1748 @item
1749 Last file status change time
1751 @item
1752 Preferred I/O block size (-1 if not available)
1754 @item
1755 Number of blocks allocated (-1 if not available)
1756 @end enumerate
1758 Not all these elements are relevant on all systems.
1759 If an element is not relevant, it is returned as 0.
1761 Returns 0 on success or a nonzero error code.
1764 DEFDOC (FSTAT_subr, "Get file information.", "\
1765 Obtains data about the file open on Fortran I/O unit @var{@1@} and
1766 places them in the array @var{@2@}.
1767 The values in this array are
1768 extracted from the @code{stat} structure as returned by
1769 @code{fstat(2)} q.v., as follows:
1771 @enumerate
1772 @item
1773 Device ID
1775 @item
1776 Inode number
1778 @item
1779 File mode
1781 @item
1782 Number of links
1784 @item
1785 Owner's uid
1787 @item
1788 Owner's gid
1790 @item
1791 ID of device containing directory entry for file
1792 (0 if not available)
1794 @item
1795 File size (bytes)
1797 @item
1798 Last access time
1800 @item
1801 Last modification time
1803 @item
1804 Last file status change time
1806 @item
1807 Preferred I/O block size (-1 if not available)
1809 @item
1810 Number of blocks allocated (-1 if not available)
1811 @end enumerate
1813 Not all these elements are relevant on all systems.
1814 If an element is not relevant, it is returned as 0.
1816 If the @var{@3@} argument is supplied, it contains
1817 0 on success or a nonzero error code upon return.
1819 Some non-GNU implementations of Fortran provide this intrinsic as
1820 only a function, not as a subroutine, or do not support the
1821 (optional) @var{@3@} argument.
1824 DEFDOC (LSTAT_func, "Get file information.", "\
1825 Obtains data about the given file @var{@1@} and places them in the array
1826 @var{@2@}.
1827 A null character (@samp{CHAR(0)}) marks the end of
1828 the name in @var{@1@}---otherwise,
1829 trailing blanks in @var{@1@} are ignored.
1830 If @var{@1@} is a symbolic link it returns data on the
1831 link itself, so the routine is available only on systems that support
1832 symbolic links.
1833 The values in this array are extracted from the
1834 @code{stat} structure as returned by @code{fstat(2)} q.v., as follows:
1836 @enumerate
1837 @item
1838 Device ID
1840 @item
1841 Inode number
1843 @item
1844 File mode
1846 @item
1847 Number of links
1849 @item
1850 Owner's uid
1852 @item
1853 Owner's gid
1855 @item
1856 ID of device containing directory entry for file
1857 (0 if not available)
1859 @item
1860 File size (bytes)
1862 @item
1863 Last access time
1865 @item
1866 Last modification time
1868 @item
1869 Last file status change time
1871 @item
1872 Preferred I/O block size (-1 if not available)
1874 @item
1875 Number of blocks allocated (-1 if not available)
1876 @end enumerate
1878 Not all these elements are relevant on all systems.
1879 If an element is not relevant, it is returned as 0.
1881 Returns 0 on success or a nonzero error code
1882 (@code{ENOSYS} if the system does not provide @code{lstat(2)}).
1885 DEFDOC (LSTAT_subr, "Get file information.", "\
1886 Obtains data about the given file @var{@1@} and places them in the array
1887 @var{@2@}.
1888 A null character (@samp{CHAR(0)}) marks the end of
1889 the name in @var{@1@}---otherwise,
1890 trailing blanks in @var{@1@} are ignored.
1891 If @var{@1@} is a symbolic link it returns data on the
1892 link itself, so the routine is available only on systems that support
1893 symbolic links.
1894 The values in this array are extracted from the
1895 @code{stat} structure as returned by @code{fstat(2)} q.v., as follows:
1897 @enumerate
1898 @item
1899 Device ID
1901 @item
1902 Inode number
1904 @item
1905 File mode
1907 @item
1908 Number of links
1910 @item
1911 Owner's uid
1913 @item
1914 Owner's gid
1916 @item
1917 ID of device containing directory entry for file
1918 (0 if not available)
1920 @item
1921 File size (bytes)
1923 @item
1924 Last access time
1926 @item
1927 Last modification time
1929 @item
1930 Last file status change time
1932 @item
1933 Preferred I/O block size (-1 if not available)
1935 @item
1936 Number of blocks allocated (-1 if not available)
1937 @end enumerate
1939 Not all these elements are relevant on all systems.
1940 If an element is not relevant, it is returned as 0.
1942 If the @var{@3@} argument is supplied, it contains
1943 0 on success or a nonzero error code upon return
1944 (@code{ENOSYS} if the system does not provide @code{lstat(2)}).
1946 Some non-GNU implementations of Fortran provide this intrinsic as
1947 only a function, not as a subroutine, or do not support the
1948 (optional) @var{@3@} argument.
1951 DEFDOC (STAT_func, "Get file information.", "\
1952 Obtains data about the given file @var{@1@} and places them in the array
1953 @var{@2@}.
1954 A null character (@samp{CHAR(0)}) marks the end of
1955 the name in @var{@1@}---otherwise,
1956 trailing blanks in @var{@1@} are ignored.
1957 The values in this array are extracted from the
1958 @code{stat} structure as returned by @code{fstat(2)} q.v., as follows:
1960 @enumerate
1961 @item
1962 Device ID
1964 @item
1965 Inode number
1967 @item
1968 File mode
1970 @item
1971 Number of links
1973 @item
1974 Owner's uid
1976 @item
1977 Owner's gid
1979 @item
1980 ID of device containing directory entry for file
1981 (0 if not available)
1983 @item
1984 File size (bytes)
1986 @item
1987 Last access time
1989 @item
1990 Last modification time
1992 @item
1993 Last file status change time
1995 @item
1996 Preferred I/O block size (-1 if not available)
1998 @item
1999 Number of blocks allocated (-1 if not available)
2000 @end enumerate
2002 Not all these elements are relevant on all systems.
2003 If an element is not relevant, it is returned as 0.
2005 Returns 0 on success or a nonzero error code.
2008 DEFDOC (STAT_subr, "Get file information.", "\
2009 Obtains data about the given file @var{@1@} and places them in the array
2010 @var{@2@}.
2011 A null character (@samp{CHAR(0)}) marks the end of
2012 the name in @var{@1@}---otherwise,
2013 trailing blanks in @var{@1@} are ignored.
2014 The values in this array are extracted from the
2015 @code{stat} structure as returned by @code{fstat(2)} q.v., as follows:
2017 @enumerate
2018 @item
2019 Device ID
2021 @item
2022 Inode number
2024 @item
2025 File mode
2027 @item
2028 Number of links
2030 @item
2031 Owner's uid
2033 @item
2034 Owner's gid
2036 @item
2037 ID of device containing directory entry for file
2038 (0 if not available)
2040 @item
2041 File size (bytes)
2043 @item
2044 Last access time
2046 @item
2047 Last modification time
2049 @item
2050 Last file status change time
2052 @item
2053 Preferred I/O block size (-1 if not available)
2055 @item
2056 Number of blocks allocated (-1 if not available)
2057 @end enumerate
2059 Not all these elements are relevant on all systems.
2060 If an element is not relevant, it is returned as 0.
2062 If the @var{@3@} argument is supplied, it contains
2063 0 on success or a nonzero error code upon return.
2065 Some non-GNU implementations of Fortran provide this intrinsic as
2066 only a function, not as a subroutine, or do not support the
2067 (optional) @var{@3@} argument.
2070 DEFDOC (LINK_subr, "Make hard link in file system.", "\
2071 Makes a (hard) link from file @var{@1@} to @var{@2@}.
2072 A null character (@samp{CHAR(0)}) marks the end of
2073 the names in @var{@1@} and @var{@2@}---otherwise,
2074 trailing blanks in @var{@1@} and @var{@2@} are ignored.
2075 If the @var{@3@} argument is supplied, it contains
2076 0 on success or a nonzero error code upon return.
2077 See @code{link(2)}.
2079 Some non-GNU implementations of Fortran provide this intrinsic as
2080 only a function, not as a subroutine, or do not support the
2081 (optional) @var{@3@} argument.
2084 DEFDOC (LINK_func, "Make hard link in file system.", "\
2085 Makes a (hard) link from file @var{@1@} to @var{@2@}.
2086 A null character (@samp{CHAR(0)}) marks the end of
2087 the names in @var{@1@} and @var{@2@}---otherwise,
2088 trailing blanks in @var{@1@} and @var{@2@} are ignored.
2089 Returns 0 on success or a nonzero error code.
2090 See @code{link(2)}.
2092 Due to the side effects performed by this intrinsic, the function
2093 form is not recommended.
2096 DEFDOC (SYMLNK_subr, "Make symbolic link in file system.", "\
2097 Makes a symbolic link from file @var{@1@} to @var{@2@}.
2098 A null character (@samp{CHAR(0)}) marks the end of
2099 the names in @var{@1@} and @var{@2@}---otherwise,
2100 trailing blanks in @var{@1@} and @var{@2@} are ignored.
2101 If the @var{@3@} argument is supplied, it contains
2102 0 on success or a nonzero error code upon return
2103 (@code{ENOSYS} if the system does not provide @code{symlink(2)}).
2105 Some non-GNU implementations of Fortran provide this intrinsic as
2106 only a function, not as a subroutine, or do not support the
2107 (optional) @var{@3@} argument.
2110 DEFDOC (SYMLNK_func, "Make symbolic link in file system.", "\
2111 Makes a symbolic link from file @var{@1@} to @var{@2@}.
2112 A null character (@samp{CHAR(0)}) marks the end of
2113 the names in @var{@1@} and @var{@2@}---otherwise,
2114 trailing blanks in @var{@1@} and @var{@2@} are ignored.
2115 Returns 0 on success or a nonzero error code
2116 (@code{ENOSYS} if the system does not provide @code{symlink(2)}).
2118 Due to the side effects performed by this intrinsic, the function
2119 form is not recommended.
2122 DEFDOC (RENAME_subr, "Rename file.", "\
2123 Renames the file @var{@1@} to @var{@2@}.
2124 A null character (@samp{CHAR(0)}) marks the end of
2125 the names in @var{@1@} and @var{@2@}---otherwise,
2126 trailing blanks in @var{@1@} and @var{@2@} are ignored.
2127 See @code{rename(2)}.
2128 If the @var{@3@} argument is supplied, it contains
2129 0 on success or a nonzero error code upon return.
2131 Some non-GNU implementations of Fortran provide this intrinsic as
2132 only a function, not as a subroutine, or do not support the
2133 (optional) @var{@3@} argument.
2136 DEFDOC (RENAME_func, "Rename file.", "\
2137 Renames the file @var{@1@} to @var{@2@}.
2138 A null character (@samp{CHAR(0)}) marks the end of
2139 the names in @var{@1@} and @var{@2@}---otherwise,
2140 trailing blanks in @var{@1@} and @var{@2@} are ignored.
2141 See @code{rename(2)}.
2142 Returns 0 on success or a nonzero error code.
2144 Due to the side effects performed by this intrinsic, the function
2145 form is not recommended.
2148 DEFDOC (UMASK_subr, "Set file creation permissions mask.", "\
2149 Sets the file creation mask to @var{@1@} and returns the old value in
2150 argument @var{@2@} if it is supplied.
2151 See @code{umask(2)}.
2153 Some non-GNU implementations of Fortran provide this intrinsic as
2154 only a function, not as a subroutine.
2157 DEFDOC (UMASK_func, "Set file creation permissions mask.", "\
2158 Sets the file creation mask to @var{@1@} and returns the old value.
2159 See @code{umask(2)}.
2161 Due to the side effects performed by this intrinsic, the function
2162 form is not recommended.
2165 DEFDOC (UNLINK_subr, "Unlink file.", "\
2166 Unlink the file @var{@1@}.
2167 A null character (@samp{CHAR(0)}) marks the end of
2168 the name in @var{@1@}---otherwise,
2169 trailing blanks in @var{@1@} are ignored.
2170 If the @var{@2@} argument is supplied, it contains
2171 0 on success or a nonzero error code upon return.
2172 See @code{unlink(2)}.
2174 Some non-GNU implementations of Fortran provide this intrinsic as
2175 only a function, not as a subroutine, or do not support the
2176 (optional) @var{@2@} argument.
2179 DEFDOC (UNLINK_func, "Unlink file.", "\
2180 Unlink the file @var{@1@}.
2181 A null character (@samp{CHAR(0)}) marks the end of
2182 the name in @var{@1@}---otherwise,
2183 trailing blanks in @var{@1@} are ignored.
2184 Returns 0 on success or a nonzero error code.
2185 See @code{unlink(2)}.
2187 Due to the side effects performed by this intrinsic, the function
2188 form is not recommended.
2191 DEFDOC (GERROR, "Get error message for last error.", "\
2192 Returns the system error message corresponding to the last system
2193 error (C @code{errno}).
2196 DEFDOC (IERRNO, "Get error number for last error.", "\
2197 Returns the last system error number (corresponding to the C
2198 @code{errno}).
2201 DEFDOC (PERROR, "Print error message for last error.", "\
2202 Prints (on the C @code{stderr} stream) a newline-terminated error
2203 message corresponding to the last system error.
2204 This is prefixed by @var{@1@}, a colon and a space.
2205 See @code{perror(3)}.
2208 DEFDOC (GETGID, "Get process group id.", "\
2209 Returns the group id for the current process.
2212 DEFDOC (GETUID, "Get process user id.", "\
2213 Returns the user id for the current process.
2216 DEFDOC (GETPID, "Get process id.", "\
2217 Returns the process id for the current process.
2220 DEFDOC (GETENV, "Get environment variable.", "\
2221 Sets @var{@2@} to the value of environment variable given by the
2222 value of @var{@1@} (@code{$name} in shell terms) or to blanks if
2223 @code{$name} has not been set.
2224 A null character (@samp{CHAR(0)}) marks the end of
2225 the name in @var{@1@}---otherwise,
2226 trailing blanks in @var{@1@} are ignored.
2229 DEFDOC (GETLOG, "Get login name.", "\
2230 Returns the login name for the process in @var{@1@}.
2232 @emph{Caution:} On some systems, the @code{getlogin(3)}
2233 function, which this intrinsic calls at run time,
2234 is either not implemented or returns a null pointer.
2235 In the latter case, this intrinsic returns blanks
2236 in @var{@1@}.
2239 DEFDOC (HOSTNM_func, "Get host name.", "\
2240 Fills @var{@1@} with the system's host name returned by
2241 @code{gethostname(2)}, returning 0 on success or a nonzero error code
2242 (@code{ENOSYS} if the system does not provide @code{gethostname(2)}).
2244 On some systems (specifically SCO) it might be necessary to link the
2245 ``socket'' library if you call this routine.
2246 Typically this means adding @samp{-lg2c -lsocket -lm}
2247 to the @code{g77} command line when linking the program.
2250 DEFDOC (HOSTNM_subr, "Get host name.", "\
2251 Fills @var{@1@} with the system's host name returned by
2252 @code{gethostname(2)}.
2253 If the @var{@2@} argument is supplied, it contains
2254 0 on success or a nonzero error code upon return
2255 (@code{ENOSYS} if the system does not provide @code{gethostname(2)}).
2257 Some non-GNU implementations of Fortran provide this intrinsic as
2258 only a function, not as a subroutine, or do not support the
2259 (optional) @var{@2@} argument.
2261 On some systems (specifically SCO) it might be necessary to link the
2262 ``socket'' library if you call this routine.
2263 Typically this means adding @samp{-lg2c -lsocket -lm}
2264 to the @code{g77} command line when linking the program.
2267 DEFDOC (FLUSH, "Flush buffered output.", "\
2268 Flushes Fortran unit(s) currently open for output.
2269 Without the optional argument, all such units are flushed,
2270 otherwise just the unit specified by @var{@1@}.
2272 Some non-GNU implementations of Fortran provide this intrinsic
2273 as a library procedure that might or might not support the
2274 (optional) @var{@1@} argument.
2277 DEFDOC (FNUM, "Get file descriptor from Fortran unit number.", "\
2278 Returns the Unix file descriptor number corresponding to the open
2279 Fortran I/O unit @var{@1@}.
2280 This could be passed to an interface to C I/O routines.
2283 #define IOWARN "
2284 Stream I/O should not be mixed with normal record-oriented (formatted or
2285 unformatted) I/O on the same unit; the results are unpredictable.
2288 DEFDOC (FGET_func, "Read a character from unit 5 stream-wise.", "\
2289 Reads a single character into @var{@1@} in stream mode from unit 5
2290 (by-passing normal formatted input) using @code{getc(3)}.
2291 Returns 0 on
2292 success, @minus{}1 on end-of-file, and the error code from
2293 @code{ferror(3)} otherwise.
2294 " IOWARN)
2296 DEFDOC (FGET_subr, "Read a character from unit 5 stream-wise.", "\
2297 Reads a single character into @var{@1@} in stream mode from unit 5
2298 (by-passing normal formatted output) using @code{getc(3)}.
2299 Returns in
2300 @var{@2@} 0 on success, @minus{}1 on end-of-file, and the error code
2301 from @code{ferror(3)} otherwise.
2302 " IOWARN)
2304 DEFDOC (FGETC_func, "Read a character stream-wise.", "\
2305 Reads a single character into @var{@2@} in stream mode from unit @var{@1@}
2306 (by-passing normal formatted output) using @code{getc(3)}.
2307 Returns 0 on
2308 success, @minus{}1 on end-of-file, and the error code from
2309 @code{ferror(3)} otherwise.
2310 " IOWARN)
2312 DEFDOC (FGETC_subr, "Read a character stream-wise.", "\
2313 Reads a single character into @var{@2@} in stream mode from unit @var{@1@}
2314 (by-passing normal formatted output) using @code{getc(3)}.
2315 Returns in
2316 @var{@3@} 0 on success, @minus{}1 on end-of-file, and the error code from
2317 @code{ferror(3)} otherwise.
2318 " IOWARN)
2320 DEFDOC (FPUT_func, "Write a character to unit 6 stream-wise.", "\
2321 Writes the single character @var{@1@} in stream mode to unit 6
2322 (by-passing normal formatted output) using @code{getc(3)}.
2323 Returns 0 on
2324 success, the error code from @code{ferror(3)} otherwise.
2325 " IOWARN)
2327 DEFDOC (FPUT_subr, "Write a character to unit 6 stream-wise.", "\
2328 Writes the single character @var{@1@} in stream mode to unit 6
2329 (by-passing normal formatted output) using @code{putc(3)}.
2330 Returns in
2331 @var{@2@} 0 on success, the error code from @code{ferror(3)} otherwise.
2332 " IOWARN)
2334 DEFDOC (FPUTC_func, "Write a character stream-wise.", "\
2335 Writes the single character @var{@2@} in stream mode to unit @var{@1@}
2336 (by-passing normal formatted output) using @code{putc(3)}.
2337 Returns 0 on
2338 success, the error code from @code{ferror(3)} otherwise.
2339 " IOWARN)
2341 DEFDOC (FPUTC_subr, "Write a character stream-wise.", "\
2342 Writes the single character @var{@1@} in stream mode to unit 6
2343 (by-passing normal formatted output) using @code{putc(3)}.
2344 Returns in
2345 @var{@2@} 0 on success, the error code from @code{ferror(3)} otherwise.
2346 " IOWARN)
2348 DEFDOC (FSEEK, "Position file (low-level).", "\
2349 Attempts to move Fortran unit @var{@1@} to the specified
2350 @var{@2@}: absolute offset if @var{@3@}=0; relative to the
2351 current offset if @var{@3@}=1; relative to the end of the file if
2352 @var{@3@}=2.
2353 It branches to label @var{@4@} if @var{@1@} is
2354 not open or if the call otherwise fails.
2357 DEFDOC (FTELL_func, "Get file position (low-level).", "\
2358 Returns the current offset of Fortran unit @var{@1@}
2359 (or @minus{}1 if @var{@1@} is not open).
2362 DEFDOC (FTELL_subr, "Get file position (low-level).", "\
2363 Sets @var{@2@} to the current offset of Fortran unit @var{@1@}
2364 (or to @minus{}1 if @var{@1@} is not open).
2366 Some non-GNU implementations of Fortran provide this intrinsic as
2367 only a function, not as a subroutine.
2370 DEFDOC (ISATTY, "Is unit connected to a terminal?", "\
2371 Returns @code{.TRUE.} if and only if the Fortran I/O unit
2372 specified by @var{@1@} is connected
2373 to a terminal device.
2374 See @code{isatty(3)}.
2377 DEFDOC (TTYNAM_func, "Get name of terminal device for unit.", "\
2378 Returns the name of the terminal device open on logical unit
2379 @var{@1@} or a blank string if @var{@1@} is not connected to a
2380 terminal.
2383 DEFDOC (TTYNAM_subr, "Get name of terminal device for unit.", "\
2384 Sets @var{@2@} to the name of the terminal device open on logical unit
2385 @var{@1@} or to a blank string if @var{@1@} is not connected to a
2386 terminal.
2388 Some non-GNU implementations of Fortran provide this intrinsic as
2389 only a function, not as a subroutine.
2392 DEFDOC (SIGNAL_subr, "Muck with signal handling.", "\
2393 If @var{@2@} is a an @code{EXTERNAL} routine, arranges for it to be
2394 invoked with a single integer argument (of system-dependent length)
2395 when signal @var{@1@} occurs.
2396 If @var{@2@} is an integer, it can be
2397 used to turn off handling of signal @var{@1@} or revert to its default
2398 action.
2399 See @code{signal(2)}.
2401 Note that @var{@2@} will be called using C conventions,
2402 so the value of its argument in Fortran terms
2403 Fortran terms is obtained by applying @code{%LOC()} (or @var{LOC()}) to it.
2405 The value returned by @code{signal(2)} is written to @var{@3@}, if
2406 that argument is supplied.
2407 Otherwise the return value is ignored.
2409 Some non-GNU implementations of Fortran provide this intrinsic as
2410 only a function, not as a subroutine, or do not support the
2411 (optional) @var{@3@} argument.
2413 @emph{Warning:} Use of the @code{libf2c} run-time library function
2414 @samp{signal_} directly
2415 (such as via @samp{EXTERNAL SIGNAL})
2416 requires use of the @code{%VAL()} construct
2417 to pass an @code{INTEGER} value
2418 (such as @samp{SIG_IGN} or @samp{SIG_DFL})
2419 for the @var{@2@} argument.
2421 However, while @samp{CALL SIGNAL(@var{signum}, %VAL(SIG_IGN))}
2422 works when @samp{SIGNAL} is treated as an external procedure
2423 (and resolves, at link time, to @code{libf2c}'s @samp{signal_} routine),
2424 this construct is not valid when @samp{SIGNAL} is recognized
2425 as the intrinsic of that name.
2427 Therefore, for maximum portability and reliability,
2428 code such references to the @samp{SIGNAL} facility as follows:
2430 @smallexample
2431 INTRINSIC SIGNAL
2432 @dots{}
2433 CALL SIGNAL(@var{signum}, SIG_IGN)
2434 @end smallexample
2436 @code{g77} will compile such a call correctly,
2437 while other compilers will generally either do so as well
2438 or reject the @samp{INTRINSIC SIGNAL} statement via a diagnostic,
2439 allowing you to take appropriate action.
2442 DEFDOC (SIGNAL_func, "Muck with signal handling.", "\
2443 If @var{@2@} is a an @code{EXTERNAL} routine, arranges for it to be
2444 invoked with a single integer argument (of system-dependent length)
2445 when signal @var{@1@} occurs.
2446 If @var{@2@} is an integer, it can be
2447 used to turn off handling of signal @var{@1@} or revert to its default
2448 action.
2449 See @code{signal(2)}.
2451 Note that @var{@2@} will be called using C conventions,
2452 so the value of its argument in Fortran terms
2453 is obtained by applying @code{%LOC()} (or @var{LOC()}) to it.
2455 The value returned by @code{signal(2)} is returned.
2457 Due to the side effects performed by this intrinsic, the function
2458 form is not recommended.
2460 @emph{Warning:} If the returned value is stored in
2461 an @code{INTEGER(KIND=1)} (default @code{INTEGER}) argument,
2462 truncation of the original return value occurs on some systems
2463 (such as Alphas, which have 64-bit pointers but 32-bit default integers),
2464 with no warning issued by @code{g77} under normal circumstances.
2466 Therefore, the following code fragment might silently fail on
2467 some systems:
2469 @smallexample
2470 INTEGER RTN
2471 EXTERNAL MYHNDL
2472 RTN = SIGNAL(@var{signum}, MYHNDL)
2473 @dots{}
2474 ! Restore original handler:
2475 RTN = SIGNAL(@var{signum}, RTN)
2476 @end smallexample
2478 The reason for the failure is that @samp{RTN} might not hold
2479 all the information on the original handler for the signal,
2480 thus restoring an invalid handler.
2481 This bug could manifest itself as a spurious run-time failure
2482 at an arbitrary point later during the program's execution,
2483 for example.
2485 @emph{Warning:} Use of the @code{libf2c} run-time library function
2486 @samp{signal_} directly
2487 (such as via @samp{EXTERNAL SIGNAL})
2488 requires use of the @code{%VAL()} construct
2489 to pass an @code{INTEGER} value
2490 (such as @samp{SIG_IGN} or @samp{SIG_DFL})
2491 for the @var{@2@} argument.
2493 However, while @samp{RTN = SIGNAL(@var{signum}, %VAL(SIG_IGN))}
2494 works when @samp{SIGNAL} is treated as an external procedure
2495 (and resolves, at link time, to @code{libf2c}'s @samp{signal_} routine),
2496 this construct is not valid when @samp{SIGNAL} is recognized
2497 as the intrinsic of that name.
2499 Therefore, for maximum portability and reliability,
2500 code such references to the @samp{SIGNAL} facility as follows:
2502 @smallexample
2503 INTRINSIC SIGNAL
2504 @dots{}
2505 RTN = SIGNAL(@var{signum}, SIG_IGN)
2506 @end smallexample
2508 @code{g77} will compile such a call correctly,
2509 while other compilers will generally either do so as well
2510 or reject the @samp{INTRINSIC SIGNAL} statement via a diagnostic,
2511 allowing you to take appropriate action.
2514 DEFDOC (KILL_func, "Signal a process.", "\
2515 Sends the signal specified by @var{@2@} to the process @var{@1@}.
2516 Returns 0 on success or a nonzero error code.
2517 See @code{kill(2)}.
2519 Due to the side effects performed by this intrinsic, the function
2520 form is not recommended.
2523 DEFDOC (KILL_subr, "Signal a process.", "\
2524 Sends the signal specified by @var{@2@} to the process @var{@1@}.
2525 If the @var{@3@} argument is supplied, it contains
2526 0 on success or a nonzero error code upon return.
2527 See @code{kill(2)}.
2529 Some non-GNU implementations of Fortran provide this intrinsic as
2530 only a function, not as a subroutine, or do not support the
2531 (optional) @var{@3@} argument.
2534 DEFDOC (LNBLNK, "Get last non-blank character in string.", "\
2535 Returns the index of the last non-blank character in @var{@1@}.
2536 @code{LNBLNK} and @code{LEN_TRIM} are equivalent.
2539 DEFDOC (SLEEP, "Sleep for a specified time.", "\
2540 Causes the process to pause for @var{@1@} seconds.
2541 See @code{sleep(2)}.
2544 DEFDOC (SYSTEM_subr, "Invoke shell (system) command.", "\
2545 Passes the command @var{@1@} to a shell (see @code{system(3)}).
2546 If argument @var{@2@} is present, it contains the value returned by
2547 @code{system(3)}, presumably 0 if the shell command succeeded.
2548 Note that which shell is used to invoke the command is system-dependent
2549 and environment-dependent.
2551 Some non-GNU implementations of Fortran provide this intrinsic as
2552 only a function, not as a subroutine, or do not support the
2553 (optional) @var{@2@} argument.
2556 DEFDOC (SYSTEM_func, "Invoke shell (system) command.", "\
2557 Passes the command @var{@1@} to a shell (see @code{system(3)}).
2558 Returns the value returned by
2559 @code{system(3)}, presumably 0 if the shell command succeeded.
2560 Note that which shell is used to invoke the command is system-dependent
2561 and environment-dependent.
2563 Due to the side effects performed by this intrinsic, the function
2564 form is not recommended.
2565 However, the function form can be valid in cases where the
2566 actual side effects performed by the call are unimportant to
2567 the application.
2569 For example, on a UNIX system, @samp{SAME = SYSTEM('cmp a b')}
2570 does not perform any side effects likely to be important to the
2571 program, so the programmer would not care if the actual system
2572 call (and invocation of @code{cmp}) was optimized away in a situation
2573 where the return value could be determined otherwise, or was not
2574 actually needed (@samp{SAME} not actually referenced after the
2575 sample assignment statement).
2578 DEFDOC (TIME_vxt, "Get the time as a character value.", "\
2579 Returns in @var{@1@} a character representation of the current time as
2580 obtained from @code{ctime(3)}.
2582 @cindex Y10K compliance
2583 @cindex Year 10000 compliance
2584 @cindex wraparound, Y10K
2585 @cindex limits, Y10K
2586 Programs making use of this intrinsic
2587 might not be Year 10000 (Y10K) compliant.
2588 For example, the date might appear,
2589 to such programs, to wrap around
2590 (change from a larger value to a smaller one)
2591 as of the Year 10000.
2593 @xref{FDate Intrinsic (subroutine)}, for an equivalent routine.
2596 DEFDOC (IBCLR, "Clear a bit.", "\
2597 Returns the value of @var{@1@} with bit @var{@2@} cleared (set to
2598 zero).
2599 @xref{BTest Intrinsic}, for information on bit positions.
2602 DEFDOC (IBSET, "Set a bit.", "\
2603 Returns the value of @var{@1@} with bit @var{@2@} set (to one).
2604 @xref{BTest Intrinsic}, for information on bit positions.
2607 DEFDOC (IBITS, "Extract a bit subfield of a variable.", "\
2608 Extracts a subfield of length @var{@3@} from @var{@1@}, starting from
2609 bit position @var{@2@} and extending left for @var{@3@} bits.
2610 The result is right-justified and the remaining bits are zeroed.
2611 The value
2612 of @samp{@var{@2@}+@var{@3@}} must be less than or equal to the value
2613 @samp{BIT_SIZE(@var{@1@})}.
2614 @xref{Bit_Size Intrinsic}.
2617 DEFDOC (ISHFT, "Logical bit shift.", "\
2618 All bits representing @var{@1@} are shifted @var{@2@} places.
2619 @samp{@var{@2@}.GT.0} indicates a left shift, @samp{@var{@2@}.EQ.0}
2620 indicates no shift and @samp{@var{@2@}.LT.0} indicates a right shift.
2621 If the absolute value of the shift count is greater than
2622 @samp{BIT_SIZE(@var{@1@})}, the result is undefined.
2623 Bits shifted out from the left end or the right end are lost.
2624 Zeros are shifted in from the opposite end.
2626 @xref{IShftC Intrinsic}, for the circular-shift equivalent.
2629 DEFDOC (ISHFTC, "Circular bit shift.", "\
2630 The rightmost @var{@3@} bits of the argument @var{@1@}
2631 are shifted circularly @var{@2@}
2632 places, i.e.@: the bits shifted out of one end are shifted into 
2633 the opposite end.
2634 No bits are lost.
2635 The unshifted bits of the result are the same as
2636 the unshifted bits of @var{@1@}.
2637 The  absolute value of the argument @var{@2@}
2638 must be less than or equal to @var{@3@}.  
2639 The value of @var{@3@} must be greater than or equal to one and less than 
2640 or equal to @samp{BIT_SIZE(@var{@1@})}.
2642 @xref{IShft Intrinsic}, for the logical shift equivalent.
2645 DEFDOC (MVBITS, "Moving a bit field.", "\
2646 Moves @var{@3@} bits from positions @var{@2@} through
2647 @samp{@var{@2@}+@var{@3@}-1} of @var{@1@} to positions @var{@5@} through
2648 @samp{@var{@2@}+@var{@3@}-1} of @var{@4@}.  The portion of argument
2649 @var{@4@} not affected by the movement of bits is unchanged.  Arguments
2650 @var{@1@} and @var{@4@} are permitted to be the same numeric storage
2651 unit.  The values of @samp{@var{@2@}+@var{@3@}} and
2652 @samp{@var{@5@}+@var{@3@}} must be less than or equal to
2653 @samp{BIT_SIZE(@var{@1@})}.
2656 DEFDOC (INDEX, "Locate a CHARACTER substring.", "\
2657 Returns the position of the start of the first occurrence of string
2658 @var{@2@} as a substring in @var{@1@}, counting from one.
2659 If @var{@2@} doesn't occur in @var{@1@}, zero is returned.
2662 DEFDOC (ALARM, "Execute a routine after a given delay.", "\
2663 Causes external subroutine @var{@2@} to be executed after a delay of
2664 @var{@1@} seconds by using @code{alarm(1)} to set up a signal and
2665 @code{signal(2)} to catch it.
2666 If @var{@3@} is supplied, it will be
2667 returned with the number of seconds remaining until any previously
2668 scheduled alarm was due to be delivered, or zero if there was no
2669 previously scheduled alarm.
2670 @xref{Signal Intrinsic (subroutine)}.
2673 DEFDOC (DATE_AND_TIME, "Get the current date and time.", "\
2674 Returns:
2675 @table @var
2676 @item @1@
2677 The date in the form @var{ccyymmdd}: century, year, month and day;
2678 @item @2@
2679 The time in the form @samp{@var{hhmmss.ss}}: hours, minutes, seconds
2680 and milliseconds;
2681 @item @3@
2682 The difference between local time and UTC (GMT) in the form @var{Shhmm}:
2683 sign, hours and minutes, e.g.@: @samp{-0500} (winter in New York);
2684 @item @4@
2685 The year, month of the year, day of the month, time difference in
2686 minutes from UTC, hour of the day, minutes of the hour, seconds
2687 of the minute, and milliseconds
2688 of the second in successive values of the array.
2689 @end table
2691 @cindex Y10K compliance
2692 @cindex Year 10000 compliance
2693 @cindex wraparound, Y10K
2694 @cindex limits, Y10K
2695 Programs making use of this intrinsic
2696 might not be Year 10000 (Y10K) compliant.
2697 For example, the date might appear,
2698 to such programs, to wrap around
2699 (change from a larger value to a smaller one)
2700 as of the Year 10000.
2702 On systems where a millisecond timer isn't available, the millisecond
2703 value is returned as zero.