1 /* Copyright (C) 1997 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
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
58 SQRT(REALPART(@var{@1@})**2, IMAGPART(@var{@1@})**2)
62 Otherwise, it is computed by negating the @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
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}
115 Instead, you can use internal-file I/O to do this kind
123 WRITE (STRING, '(I10)'), VALUE
128 The above program, when run, prints:
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
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
163 READ (STRING, '(I10)'), VALUE
168 The above program, when run, prints:
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@}
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:
200 This expression converts the imaginary part of @1@ to
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
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
233 @xref{AInt Intrinsic}, for how to truncate to whole number
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
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
275 @xref{ANInt Intrinsic}, for how to round to nearest whole number
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
286 @xref{Exp Intrinsic}, for the inverse of this function.
288 @xref{Log10 Intrinsic}, for the 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, "Natural logarithm.", "\
300 Returns the natural logarithm of @var{@1@}, which must
301 be greater than zero or, if type @code{COMPLEX}, must not
304 The inverse of this function is @samp{10. ** LOG10(@var{@1@})}.
306 @xref{Log Intrinsic}, for the natural logarithm function.
309 DEFDOC (ALOG10, "Natural logarithm (archaic).", ARCHAIC (LOG10, Log10))
311 DEFDOC (DLOG10, "Natural logarithm (archaic).", ARCHAIC (LOG10, Log10))
313 DEFDOC (MAX, "Maximum value.", "\
314 Returns the argument with the largest value.
316 @xref{Min Intrinsic}, for the opposite function.
319 DEFDOC (AMAX0, "Maximum value (archaic).", "\
320 Archaic form of @code{MAX()} that is specific
321 to one type for @var{@1@} and a different return type.
322 @xref{Max Intrinsic}.
325 DEFDOC (AMAX1, "Maximum value (archaic).", ARCHAIC (MAX, Max))
327 DEFDOC (DMAX1, "Maximum value (archaic).", ARCHAIC (MAX, Max))
329 DEFDOC (MAX0, "Maximum value (archaic).", ARCHAIC (MAX, Max))
331 DEFDOC (MAX1, "Maximum value (archaic).", "\
332 Archaic form of @code{MAX()} that is specific
333 to one type for @var{@1@} and a different return type.
334 @xref{Max Intrinsic}.
337 DEFDOC (MIN, "Minimum value.", "\
338 Returns the argument with the smallest value.
340 @xref{Max Intrinsic}, for the opposite function.
343 DEFDOC (AMIN0, "Minimum value (archaic).", "\
344 Archaic form of @code{MIN()} that is specific
345 to one type for @var{@1@} and a different return type.
346 @xref{Min Intrinsic}.
349 DEFDOC (AMIN1, "Minimum value (archaic).", ARCHAIC (MIN, Min))
351 DEFDOC (DMIN1, "Minimum value (archaic).", ARCHAIC (MIN, Min))
353 DEFDOC (MIN0, "Minimum value (archaic).", ARCHAIC (MIN, Min))
355 DEFDOC (MIN1, "Minimum value (archaic).", "\
356 Archaic form of @code{MIN()} that is specific
357 to one type for @var{@1@} and a different return type.
358 @xref{Min Intrinsic}.
361 DEFDOC (MOD, "Remainder.", "\
362 Returns remainder calculated as:
365 @var{@1@} - (INT(@var{@1@} / @var{@2@}) * @var{@2@})
368 @var{@2@} must not be zero.
371 DEFDOC (AMOD, "Remainder (archaic).", ARCHAIC (MOD, Mod))
373 DEFDOC (DMOD, "Remainder (archaic).", ARCHAIC (MOD, Mod))
375 DEFDOC (AND, "Boolean AND.", "\
376 Returns value resulting from boolean AND of
377 pair of bits in each of @var{@1@} and @var{@2@}.
380 DEFDOC (IAND, "Boolean AND.", "\
381 Returns value resulting from boolean AND of
382 pair of bits in each of @var{@1@} and @var{@2@}.
385 DEFDOC (OR, "Boolean OR.", "\
386 Returns value resulting from boolean OR of
387 pair of bits in each of @var{@1@} and @var{@2@}.
390 DEFDOC (IOR, "Boolean OR.", "\
391 Returns value resulting from boolean OR of
392 pair of bits in each of @var{@1@} and @var{@2@}.
395 DEFDOC (XOR, "Boolean XOR.", "\
396 Returns value resulting from boolean exclusive-OR of
397 pair of bits in each of @var{@1@} and @var{@2@}.
400 DEFDOC (IEOR, "Boolean XOR.", "\
401 Returns value resulting from boolean exclusive-OR of
402 pair of bits in each of @var{@1@} and @var{@2@}.
405 DEFDOC (NOT, "Boolean NOT.", "\
406 Returns value resulting from boolean NOT of each bit
410 DEFDOC (ASIN, "Arc sine.", "\
411 Returns the arc-sine (inverse sine) of @var{@1@}
414 @xref{Sin Intrinsic}, for the inverse of this function.
417 DEFDOC (DASIN, "Arc sine (archaic).", ARCHAIC (ASIN, ASin))
419 DEFDOC (ATAN, "Arc tangent.", "\
420 Returns the arc-tangent (inverse tangent) of @var{@1@}
423 @xref{Tan Intrinsic}, for the inverse of this function.
426 DEFDOC (DATAN, "Arc tangent (archaic).", ARCHAIC (ATAN, ATan))
428 DEFDOC (ATAN2, "Arc tangent.", "\
429 Returns the arc-tangent (inverse tangent) of the complex
430 number (@var{@1@}, @var{@2@}) in radians.
432 @xref{Tan Intrinsic}, for the inverse of this function.
435 DEFDOC (DATAN2, "Arc tangent (archaic).", ARCHAIC_2 (ATAN2, ATan2))
437 DEFDOC (BIT_SIZE, "Number of bits in argument's type.", "\
438 Returns the number of bits (integer precision plus sign bit)
439 represented by the type for @var{@1@}.
441 @xref{BTest Intrinsic}, for how to test the value of a
442 bit in a variable or array.
444 @xref{IBSet Intrinsic}, for how to set a bit in a variable to 1.
446 @xref{IBClr Intrinsic}, for how to set a bit in a variable to 0.
450 DEFDOC (BTEST, "Test bit.", "\
451 Returns @code{.TRUE.} if bit @var{@2@} in @var{@1@} is
452 1, @code{.FALSE.} otherwise.
454 (Bit 0 is the low-order (rightmost) bit, adding the value
464 to the number if set to 1;
465 bit 1 is the next-higher-order bit, adding
486 @xref{Bit_Size Intrinsic}, for how to obtain the number of bits
488 The leftmost bit of @var{@1@} is @samp{BIT_SIZE(@var{@1@}-1)}.
491 DEFDOC (CMPLX, "Construct @code{COMPLEX(KIND=1)} value.", "\
492 If @var{@1@} is not type @code{COMPLEX},
493 constructs a value of type @code{COMPLEX(KIND=1)} from the
494 real and imaginary values specified by @var{@1@} and
495 @var{@2@}, respectively.
496 If @var{@2@} is omitted, @samp{0.} is assumed.
498 If @var{@1@} is type @code{COMPLEX},
499 converts it to type @code{COMPLEX(KIND=1)}.
501 @xref{Complex Intrinsic}, for information on easily constructing
502 a @code{COMPLEX} value of arbitrary precision from @code{REAL}
506 DEFDOC (DCMPLX, "Construct @code{COMPLEX(KIND=2)} value.", "\
507 If @var{@1@} is not type @code{COMPLEX},
508 constructs a value of type @code{COMPLEX(KIND=2)} from the
509 real and imaginary values specified by @var{@1@} and
510 @var{@2@}, respectively.
511 If @var{@2@} is omitted, @samp{0D0} is assumed.
513 If @var{@1@} is type @code{COMPLEX},
514 converts it to type @code{COMPLEX(KIND=2)}.
516 Although this intrinsic is not standard Fortran,
517 it is a popular extension offered by many compilers
518 that support @code{DOUBLE COMPLEX}, since it offers
519 the easiest way to convert to @code{DOUBLE COMPLEX}
520 without using Fortran 90 features (such as the @samp{KIND=}
521 argument to the @code{CMPLX()} intrinsic).
523 (@samp{CMPLX(0D0, 0D0)} returns a single-precision
524 @code{COMPLEX} result, as required by standard FORTRAN 77.
525 That's why so many compilers provide @code{DCMPLX()}, since
526 @samp{DCMPLX(0D0, 0D0)} returns a @code{DOUBLE COMPLEX}
528 Still, @code{DCMPLX()} converts even @code{REAL*16} arguments
529 to their @code{REAL*8} equivalents in most dialects of
530 Fortran, so neither it nor @code{CMPLX()} allow easy
531 construction of arbitrary-precision values without
532 potentially forcing a conversion involving extending or
534 GNU Fortran provides such an intrinsic, called @code{COMPLEX()}.)
536 @xref{Complex Intrinsic}, for information on easily constructing
537 a @code{COMPLEX} value of arbitrary precision from @code{REAL}
541 DEFDOC (CONJG, "Complex conjugate.", "\
542 Returns the complex conjugate:
545 COMPLEX(REALPART(@var{@1@}), -IMAGPART(@var{@1@}))
549 DEFDOC (DCONJG, "Complex conjugate (archaic).", ARCHAIC (CONJG, Conjg))
551 DEFDOC (COS, "Cosine.", "\
552 Returns the cosine of @var{@1@}, an angle measured
555 @xref{ACos Intrinsic}, for the inverse of this function.
558 DEFDOC (CCOS, "Cosine (archaic).", ARCHAIC (COS, Cos))
560 DEFDOC (DCOS, "Cosine (archaic).", ARCHAIC (COS, Cos))
562 DEFDOC (CDCOS, "Cosine (archaic).", ARCHAIC (COS, Cos))
564 DEFDOC (COSH, "Hyperbolic cosine.", "\
565 Returns the hyperbolic cosine of @var{@1@}.
568 DEFDOC (DCOSH, "Hyperbolic cosine (archaic).", ARCHAIC (COSH, CosH))
570 DEFDOC (SQRT, "Square root.", "\
571 Returns the square root of @var{@1@}, which must
574 To calculate and represent the square root of a negative
575 number, complex arithmetic must be used.
576 For example, @samp{SQRT(COMPLEX(@var{@1@}))}.
578 The inverse of this function is @samp{SQRT(@var{@1@}) * SQRT(@var{@1@})}.
581 DEFDOC (CSQRT, "Square root (archaic).", ARCHAIC (SQRT, SqRt))
583 DEFDOC (DSQRT, "Square root (archaic).", ARCHAIC (SQRT, SqRt))
585 DEFDOC (CDSQRT, "Square root (archaic).", ARCHAIC (SQRT, SqRt))
587 DEFDOC (DBLE, "Convert to double precision.", "\
588 Returns @var{@1@} converted to double precision
589 (@code{REAL(KIND=2)}).
590 If @var{@1@} is @code{COMPLEX}, the real part of
591 @var{@1@} is used for the conversion
592 and the imaginary part disregarded.
594 @xref{Sngl Intrinsic}, for the function that converts
597 @xref{Int Intrinsic}, for the function that converts
600 @xref{Complex Intrinsic}, for the function that converts
604 DEFDOC (DIM, "Difference magnitude (non-negative subtract).", "\
605 Returns @samp{@var{@1@}-@var{@2@}} if @var{@1@} is greater than
606 @var{@2@}; otherwise returns zero.
609 DEFDOC (DDIM, "Difference magnitude (archaic).", ARCHAIC_2 (DIM, DiM))
610 DEFDOC (IDIM, "Difference magnitude (archaic).", ARCHAIC_2 (DIM, DiM))
612 DEFDOC (DPROD, "Double-precision product.", "\
613 Returns @samp{DBLE(@var{@1@})*DBLE(@var{@2@})}.
616 DEFDOC (EXP, "Exponential.", "\
617 Returns @samp{@var{e}**@var{@1@}}, where
618 @var{e} is approximately 2.7182818.
620 @xref{Log Intrinsic}, for the inverse of this function.
623 DEFDOC (CEXP, "Exponential (archaic).", ARCHAIC (EXP, Exp))
625 DEFDOC (DEXP, "Exponential (archaic).", ARCHAIC (EXP, Exp))
627 DEFDOC (CDEXP, "Exponential (archaic).", ARCHAIC (EXP, Exp))
629 DEFDOC (FLOAT, "Conversion (archaic).", ARCHAIC (REAL, Real))
630 DEFDOC (DFLOAT, "Conversion (archaic).", ARCHAIC (REAL, Real))
632 DEFDOC (IFIX, "Conversion (archaic).", ARCHAIC (INT, Int))
634 DEFDOC (LONG, "Conversion to @code{INTEGER(KIND=1)} (archaic).", "\
635 Archaic form of @code{INT()} that is specific
636 to one type for @var{@1@}.
637 @xref{Int Intrinsic}.
639 The precise meaning of this intrinsic might change
640 in a future version of the GNU Fortran language,
641 as more is learned about how it is used.
644 DEFDOC (SHORT, "Convert to @code{INTEGER(KIND=6)} value@99@truncated to whole number.", "\
645 Returns @var{@1@} with the fractional portion of its
646 magnitude truncated and its sign preserved, converted
647 to type @code{INTEGER(KIND=6)}.
649 If @var{@1@} is type @code{COMPLEX}, its real part
650 is truncated and converted, and its imaginary part is disgregarded.
652 @xref{Int Intrinsic}.
654 The precise meaning of this intrinsic might change
655 in a future version of the GNU Fortran language,
656 as more is learned about how it is used.
659 DEFDOC (INT2, "Convert to @code{INTEGER(KIND=6)} value@99@truncated to whole number.", "\
660 Returns @var{@1@} with the fractional portion of its
661 magnitude truncated and its sign preserved, converted
662 to type @code{INTEGER(KIND=6)}.
664 If @var{@1@} is type @code{COMPLEX}, its real part
665 is truncated and converted, and its imaginary part is disgregarded.
667 @xref{Int Intrinsic}.
669 The precise meaning of this intrinsic might change
670 in a future version of the GNU Fortran language,
671 as more is learned about how it is used.
674 DEFDOC (INT8, "Convert to @code{INTEGER(KIND=2)} value@99@truncated to whole number.", "\
675 Returns @var{@1@} with the fractional portion of its
676 magnitude truncated and its sign preserved, converted
677 to type @code{INTEGER(KIND=2)}.
679 If @var{@1@} is type @code{COMPLEX}, its real part
680 is truncated and converted, and its imaginary part is disgregarded.
682 @xref{Int Intrinsic}.
684 The precise meaning of this intrinsic might change
685 in a future version of the GNU Fortran language,
686 as more is learned about how it is used.
689 DEFDOC (LEN, "Length of character entity.", "\
690 Returns the length of @var{@1@}.
692 If @var{@1@} is an array, the length of an element
693 of @var{@1@} is returned.
695 Note that @var{@1@} need not be defined when this
696 intrinsic is invoked, since only the length, not
697 the content, of @var{@1@} is needed.
699 @xref{Bit_Size Intrinsic}, for the function that determines
700 the size of its argument in bits.
703 DEFDOC (TAN, "Tangent.", "\
704 Returns the tangent of @var{@1@}, an angle measured
707 @xref{ATan Intrinsic}, for the inverse of this function.
710 DEFDOC (DTAN, "Tangent (archaic).", ARCHAIC (TAN, Tan))
712 DEFDOC (TANH, "Hyperbolic tangent.", "\
713 Returns the hyperbolic tangent of @var{@1@}.
716 DEFDOC (DTANH, "Hyperbolic tangent (archaic).", ARCHAIC (TANH, TanH))
718 DEFDOC (SNGL, "Convert (archaic).", ARCHAIC (REAL, Real))
720 DEFDOC (SIN, "Sine.", "\
721 Returns the sine of @var{@1@}, an angle measured
724 @xref{ASin Intrinsic}, for the inverse of this function.
727 DEFDOC (CSIN, "Sine (archaic).", ARCHAIC (SIN, Sin))
729 DEFDOC (DSIN, "Sine (archaic).", ARCHAIC (SIN, Sin))
731 DEFDOC (CDSIN, "Sine (archaic).", ARCHAIC (SIN, Sin))
733 DEFDOC (SINH, "Hyperbolic sine.", "\
734 Returns the hyperbolic sine of @var{@1@}.
737 DEFDOC (DSINH, "Hyperbolic sine (archaic).", ARCHAIC (SINH, SinH))
739 DEFDOC (LSHIFT, "Left-shift bits.", "\
740 Returns @var{@1@} shifted to the left
743 Although similar to the expression
744 @samp{@var{@1@}*(2**@var{@2@})}, there
745 are important differences.
746 For example, the sign of the result is
747 not necessarily the same as the sign of
750 Currently this intrinsic is defined assuming
751 the underlying representation of @var{@1@}
752 is as a two's-complement integer.
753 It is unclear at this point whether that
754 definition will apply when a different
755 representation is involved.
757 @xref{LShift Intrinsic}, for the inverse of this function.
759 @xref{IShft Intrinsic}, for information
760 on a more widely available left-shifting
761 intrinsic that is also more precisely defined.
764 DEFDOC (RSHIFT, "Right-shift bits.", "\
765 Returns @var{@1@} shifted to the right
768 Although similar to the expression
769 @samp{@var{@1@}/(2**@var{@2@})}, there
770 are important differences.
771 For example, the sign of the result is
774 Currently this intrinsic is defined assuming
775 the underlying representation of @var{@1@}
776 is as a two's-complement integer.
777 It is unclear at this point whether that
778 definition will apply when a different
779 representation is involved.
781 @xref{RShift Intrinsic}, for the inverse of this function.
783 @xref{IShft Intrinsic}, for information
784 on a more widely available right-shifting
785 intrinsic that is also more precisely defined.
788 DEFDOC (LGE, "Lexically greater than or equal.", "\
789 Returns @samp{.TRUE.} if @samp{@var{@1@}.GE.@var{@2@}},
790 @samp{.FALSE.} otherwise.
791 @var{@1@} and @var{@2@} are interpreted as containing
792 ASCII character codes.
793 If either value contains a character not in the ASCII
794 character set, the result is processor dependent.
796 If the @var{@1@} and @var{@2@} are not the same length,
797 the shorter is compared as if spaces were appended to
798 it to form a value that has the same length as the longer.
800 The lexical comparison intrinsics @code{LGe}, @code{LGt},
801 @code{LLe}, and @code{LLt} differ from the corresponding
802 intrinsic operators @code{.GE.}, @code{.GT.},
803 @code{.LE.}, @code{.LT.}.
804 Because the ASCII collating sequence is assumed,
805 the following expressions always return @samp{.TRUE.}:
813 The following related expressions do @emph{not} always
814 return @samp{.TRUE.}, as they are not necessarily evaluated
815 assuming the arguments use ASCII encoding:
823 The same difference exists
824 between @code{LGt} and @code{.GT.};
825 between @code{LLe} and @code{.LE.}; and
826 between @code{LLt} and @code{.LT.}.
829 DEFDOC (LGT, "Lexically greater than.", "\
830 Returns @samp{.TRUE.} if @samp{@var{@1@}.GT.@var{@2@}},
831 @samp{.FALSE.} otherwise.
832 @var{@1@} and @var{@2@} are interpreted as containing
833 ASCII character codes.
834 If either value contains a character not in the ASCII
835 character set, the result is processor dependent.
837 If the @var{@1@} and @var{@2@} are not the same length,
838 the shorter is compared as if spaces were appended to
839 it to form a value that has the same length as the longer.
841 @xref{LGe Intrinsic}, for information on the distinction
842 between the @code{@0@} intrinsic and the @code{.GT.}
846 DEFDOC (LLE, "Lexically less than or equal.", "\
847 Returns @samp{.TRUE.} if @samp{@var{@1@}.LE.@var{@2@}},
848 @samp{.FALSE.} otherwise.
849 @var{@1@} and @var{@2@} are interpreted as containing
850 ASCII character codes.
851 If either value contains a character not in the ASCII
852 character set, the result is processor dependent.
854 If the @var{@1@} and @var{@2@} are not the same length,
855 the shorter is compared as if spaces were appended to
856 it to form a value that has the same length as the longer.
858 @xref{LGe Intrinsic}, for information on the distinction
859 between the @code{@0@} intrinsic and the @code{.LE.}
863 DEFDOC (LLT, "Lexically less than.", "\
864 Returns @samp{.TRUE.} if @samp{@var{@1@}.LT.@var{@2@}},
865 @samp{.FALSE.} otherwise.
866 @var{@1@} and @var{@2@} are interpreted as containing
867 ASCII character codes.
868 If either value contains a character not in the ASCII
869 character set, the result is processor dependent.
871 If the @var{@1@} and @var{@2@} are not the same length,
872 the shorter is compared as if spaces were appended to
873 it to form a value that has the same length as the longer.
875 @xref{LGe Intrinsic}, for information on the distinction
876 between the @code{@0@} intrinsic and the @code{.LT.}
880 DEFDOC (SIGN, "Apply sign to magnitude.", "\
881 Returns @samp{ABS(@var{@1@})*@var{s}}, where
882 @var{s} is +1 if @samp{@var{@2@}.GE.0},
885 @xref{Abs Intrinsic}, for the function that returns
886 the magnitude of a value.
889 DEFDOC (DSIGN, "Apply sign to magnitude (archaic).", ARCHAIC_2 (SIGN, Sign))
890 DEFDOC (ISIGN, "Apply sign to magnitude (archaic).", ARCHAIC_2 (SIGN, Sign))
892 DEFDOC (REAL, "Convert value to type @code{REAL(KIND=1)}.", "\
893 Converts @var{@1@} to @code{REAL(KIND=1)}.
895 Use of @code{@0@()} with a @code{COMPLEX} argument
896 (other than @code{COMPLEX(KIND=1)}) is restricted to the following case:
903 This expression converts the real part of @1@ to
906 @xref{RealPart Intrinsic}, for information on a GNU Fortran
907 intrinsic that extracts the real part of an arbitrary
908 @code{COMPLEX} value.
910 @xref{REAL() and AIMAG() of Complex}, for more information.
913 DEFDOC (DREAL, "Convert value to type @code{REAL(KIND=2)}.", "\
914 Converts @var{@1@} to @code{REAL(KIND=2)}.
916 If @var{@1@} is type @code{COMPLEX}, its real part
917 is converted (if necessary) to @code{REAL(KIND=2)},
918 and its imaginary part is disregarded.
920 Although this intrinsic is not standard Fortran,
921 it is a popular extension offered by many compilers
922 that support @code{DOUBLE COMPLEX}, since it offers
923 the easiest way to extract the real part of a @code{DOUBLE COMPLEX}
924 value without using the Fortran 90 @code{REAL()} intrinsic
925 in a way that produces a return value inconsistent with
926 the way many FORTRAN 77 compilers handle @code{REAL()} of
927 a @code{DOUBLE COMPLEX} value.
929 @xref{RealPart Intrinsic}, for information on a GNU Fortran
930 intrinsic that avoids these areas of confusion.
932 @xref{Dble Intrinsic}, for information on the standard FORTRAN 77
933 replacement for @code{DREAL()}.
935 @xref{REAL() and AIMAG() of Complex}, for more information on
939 DEFDOC (IMAGPART, "Extract imaginary part of complex.", "\
940 The imaginary part of @var{@1@} is returned, without conversion.
942 @emph{Note:} The way to do this in standard Fortran 90
943 is @samp{AIMAG(@var{@1@})}.
944 However, when, for example, @var{@1@} is @code{DOUBLE COMPLEX},
945 @samp{AIMAG(@var{@1@})} means something different for some compilers
946 that are not true Fortran 90 compilers but offer some
947 extensions standardized by Fortran 90 (such as the
948 @code{DOUBLE COMPLEX} type, also known as @code{COMPLEX(KIND=2)}).
950 The advantage of @code{@0@()} is that, while not necessarily
951 more or less portable than @code{AIMAG()}, it is more likely to
952 cause a compiler that doesn't support it to produce a diagnostic
953 than generate incorrect code.
955 @xref{REAL() and AIMAG() of Complex}, for more information.
958 DEFDOC (COMPLEX, "Build complex value from real and@99@imaginary parts.", "\
959 Returns a @code{COMPLEX} value that has @samp{@1@} and @samp{@2@} as its
960 real and imaginary parts, respectively.
962 If @var{@1@} and @var{@2@} are the same type, and that type is not
963 @code{INTEGER}, no data conversion is performed, and the type of
964 the resulting value has the same kind value as the types
965 of @var{@1@} and @var{@2@}.
967 If @var{@1@} and @var{@2@} are not the same type, the usual type-promotion
968 rules are applied to both, converting either or both to the
969 appropriate @code{REAL} type.
970 The type of the resulting value has the same kind value as the
971 type to which both @var{@1@} and @var{@2@} were converted, in this case.
973 If @var{@1@} and @var{@2@} are both @code{INTEGER}, they are both converted
974 to @code{REAL(KIND=1)}, and the result of the @code{@0@()}
975 invocation is type @code{COMPLEX(KIND=1)}.
977 @emph{Note:} The way to do this in standard Fortran 90
978 is too hairy to describe here, but it is important to
979 note that @samp{CMPLX(D1,D2)} returns a @code{COMPLEX(KIND=1)}
980 result even if @samp{D1} and @samp{D2} are type @code{REAL(KIND=2)}.
981 Hence the availability of @code{COMPLEX()} in GNU Fortran.
984 DEFDOC (LOC, "Address of entity in core.", "\
985 The @code{LOC()} intrinsic works the
986 same way as the @code{%LOC()} construct.
987 @xref{%LOC(),,The @code{%LOC()} Construct}, for
991 DEFDOC (REALPART, "Extract real part of complex.", "\
992 The real part of @var{@1@} is returned, without conversion.
994 @emph{Note:} The way to do this in standard Fortran 90
995 is @samp{REAL(@var{@1@})}.
996 However, when, for example, @var{@1@} is @code{COMPLEX(KIND=2)},
997 @samp{REAL(@var{@1@})} means something different for some compilers
998 that are not true Fortran 90 compilers but offer some
999 extensions standardized by Fortran 90 (such as the
1000 @code{DOUBLE COMPLEX} type, also known as @code{COMPLEX(KIND=2)}).
1002 The advantage of @code{@0@()} is that, while not necessarily
1003 more or less portable than @code{REAL()}, it is more likely to
1004 cause a compiler that doesn't support it to produce a diagnostic
1005 than generate incorrect code.
1007 @xref{REAL() and AIMAG() of Complex}, for more information.
1010 DEFDOC (GETARG, "Obtain command-line argument.", "\
1011 Sets @var{@2@} to the @var{@1@}-th command-line argument (or to all
1012 blanks if there are fewer than @var{@2@} command-line arguments);
1013 @code{CALL @0@(0, @var{value})} sets @var{value} to the name of the
1014 program (on systems that support this feature).
1016 @xref{IArgC Intrinsic}, for information on how to get the number
1020 DEFDOC (ABORT, "Abort the program.", "\
1021 Prints a message and potentially causes a core dump via @code{abort(3)}.
1024 DEFDOC (EXIT, "Terminate the program.", "\
1025 Exit the program with status @var{@1@} after closing open Fortran
1026 I/O units and otherwise behaving as @code{exit(2)}.
1027 If @var{@1@} is omitted the canonical `success' value
1028 will be returned to the system.
1031 DEFDOC (IARGC, "Obtain count of command-line arguments.", "\
1032 Returns the number of command-line arguments.
1034 This count does not include the specification of the program
1038 DEFDOC (CTIME_func, "Convert time to Day Mon dd hh:mm:ss yyyy.", "\
1039 Converts @var{@1@}, a system time value, such as returned by
1040 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995},
1041 and returns that string as the function value.
1043 @xref{Time8 Intrinsic}.
1046 DEFDOC (CTIME_subr, "Convert time to Day Mon dd hh:mm:ss yyyy.", "\
1047 Converts @var{@2@}, a system time value, such as returned by
1048 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995},
1049 and returns that string in @var{@1@}.
1051 @xref{Time8 Intrinsic}.
1053 Some non-GNU implementations of Fortran provide this intrinsic as
1054 only a function, not as a subroutine.
1057 DEFDOC (DATE, "Get current date as dd-Mon-yy.", "\
1058 Returns @var{@1@} in the form @samp{@var{dd}-@var{mmm}-@var{yy}},
1059 representing the numeric day of the month @var{dd}, a three-character
1060 abbreviation of the month name @var{mmm} and the last two digits of
1061 the year @var{yy}, e.g.@ @samp{25-Nov-96}.
1063 This intrinsic is not recommended, due to the year 2000 approaching.
1064 @xref{CTime Intrinsic (subroutine)}, for information on obtaining more digits
1065 for the current (or any) date.
1068 DEFDOC (DTIME_func, "Get elapsed time since last time.", "\
1069 Initially, return the number of seconds of runtime
1070 since the start of the process's execution
1071 as the function value,
1072 and the user and system components of this in @samp{@var{@1@}(1)}
1073 and @samp{@var{@1@}(2)} respectively.
1074 The functions' value is equal to @samp{@var{@1@}(1) + @var{@1@}(2)}.
1076 Subsequent invocations of @samp{@0@()} return values accumulated since the
1077 previous invocation.
1079 Due to the side effects performed by this intrinsic, the function
1080 form is not recommended.
1083 DEFDOC (DTIME_subr, "Get elapsed time since last time.", "\
1084 Initially, return the number of seconds of runtime
1085 since the start of the process's execution
1087 and the user and system components of this in @samp{@var{@2@}(1)}
1088 and @samp{@var{@2@}(2)} respectively.
1089 The value of @var{@1@} is equal to @samp{@var{@2@}(1) + @var{@2@}(2)}.
1091 Subsequent invocations of @samp{@0@()} set values based on accumulations
1092 since the previous invocation.
1094 Some non-GNU implementations of Fortran provide this intrinsic as
1095 only a function, not as a subroutine.
1098 DEFDOC (ETIME_func, "Get elapsed time for process.", "\
1099 Return the number of seconds of runtime
1100 since the start of the process's execution
1101 as the function value,
1102 and the user and system components of this in @samp{@var{@1@}(1)}
1103 and @samp{@var{@1@}(2)} respectively.
1104 The functions' value is equal to @samp{@var{@1@}(1) + @var{@1@}(2)}.
1107 DEFDOC (ETIME_subr, "Get elapsed time for process.", "\
1108 Return the number of seconds of runtime
1109 since the start of the process's execution
1111 and the user and system components of this in @samp{@var{@2@}(1)}
1112 and @samp{@var{@2@}(2)} respectively.
1113 The value of @var{@1@} is equal to @samp{@var{@2@}(1) + @var{@2@}(2)}.
1115 Some non-GNU implementations of Fortran provide this intrinsic as
1116 only a function, not as a subroutine.
1119 DEFDOC (FDATE_func, "Get current time as Day Mon dd hh:mm:ss yyyy.", "\
1120 Returns the current date (using the same format as @code{CTIME()}).
1128 @xref{CTime Intrinsic (function)}.
1131 DEFDOC (FDATE_subr, "Get current time as Day Mon dd hh:mm:ss yyyy.", "\
1132 Returns the current date (using the same format as @code{CTIME()})
1138 CALL CTIME(@var{@1@}, TIME8())
1141 @xref{CTime Intrinsic (subroutine)}.
1143 Some non-GNU implementations of Fortran provide this intrinsic as
1144 only a function, not as a subroutine.
1147 DEFDOC (GMTIME, "Convert time to GMT time info.", "\
1148 Given a system time value @var{@1@}, fills @var{@2@} with values
1149 extracted from it appropriate to the GMT time zone using
1152 The array elements are as follows:
1156 Seconds after the minute, range 0--59 or 0--61 to allow for leap
1160 Minutes after the hour, range 0--59
1163 Hours past midnight, range 0--23
1166 Day of month, range 0--31
1169 Number of months since January, range 0--12
1175 Number of days since Sunday, range 0--6
1178 Days since January 1
1181 Daylight savings indicator: positive if daylight savings is in effect,
1182 zero if not, and negative if the information isn't available.
1186 DEFDOC (LTIME, "Convert time to local time info.", "\
1187 Given a system time value @var{@1@}, fills @var{@2@} with values
1188 extracted from it appropriate to the GMT time zone using
1189 @code{localtime(3)}.
1191 The array elements are as follows:
1195 Seconds after the minute, range 0--59 or 0--61 to allow for leap
1199 Minutes after the hour, range 0--59
1202 Hours past midnight, range 0--23
1205 Day of month, range 0--31
1208 Number of months since January, range 0--12
1214 Number of days since Sunday, range 0--6
1217 Days since January 1
1220 Daylight savings indicator: positive if daylight savings is in effect,
1221 zero if not, and negative if the information isn't available.
1225 DEFDOC (IDATE_unix, "Get local time info.", "\
1226 Fills @var{@1@} with the numerical values at the current local time
1227 of day, month (in the range 1--12), and year in elements 1, 2, and 3,
1229 The year has four significant digits.
1232 DEFDOC (IDATE_vxt, "Get local time info (VAX/VMS).", "\
1233 Returns the numerical values of the current local time.
1234 The month (in the range 1--12) is returned in @var{@1@},
1235 the day (in the range 1--7) in @var{@2@},
1236 and the year in @var{@3@} (in the range 0--99).
1238 This intrinsic is not recommended, due to the year 2000 approaching.
1241 DEFDOC (ITIME, "Get local time of day.", "\
1242 Returns the current local time hour, minutes, and seconds in elements
1243 1, 2, and 3 of @var{@1@}, respectively.
1246 DEFDOC (MCLOCK, "Get number of clock ticks for process.", "\
1247 Returns the number of clock ticks since the start of the process.
1248 Supported on systems with @code{clock(3)} (q.v.).
1250 This intrinsic is not fully portable, such as to systems
1251 with 32-bit @code{INTEGER} types but supporting times
1253 @xref{MClock8 Intrinsic}, for information on a
1254 similar intrinsic that might be portable to more
1255 GNU Fortran implementations, though to fewer
1258 If the system does not support @code{clock(3)},
1262 DEFDOC (MCLOCK8, "Get number of clock ticks for process.", "\
1263 Returns the number of clock ticks since the start of the process.
1264 Supported on systems with @code{clock(3)} (q.v.).
1266 No Fortran implementations other than GNU Fortran are
1267 known to support this intrinsic at the time of this
1269 @xref{MClock Intrinsic}, for information on a
1270 similar intrinsic that might be portable to more Fortran
1271 compilers, though to fewer GNU Fortran implementations.
1273 If the system does not support @code{clock(3)},
1277 DEFDOC (SECNDS, "Get local time offset since midnight.", "\
1278 Returns the local time in seconds since midnight minus the value
1282 DEFDOC (SECOND_func, "Get CPU time for process in seconds.", "\
1283 Returns the process's runtime in seconds---the same value as the
1284 UNIX function @code{etime} returns.
1287 DEFDOC (SECOND_subr, "Get CPU time for process@99@in seconds.", "\
1288 Returns the process's runtime in seconds in @var{@1@}---the same value
1289 as the UNIX function @code{etime} returns.
1291 This routine is known from Cray Fortran. @xref{CPU_Time Intrinsic}
1292 for a standard equivalent.
1295 DEFDOC (SYSTEM_CLOCK, "Get current system clock value.", "\
1296 Returns in @var{@1@} the current value of the system clock; this is
1297 the value returned by the UNIX function @code{times(2)}
1298 in this implementation, but
1300 @var{@2@} is the number of clock ticks per second and
1301 @var{@3@} is the maximum value this can take, which isn't very useful
1302 in this implementation since it's just the maximum C @code{unsigned
1306 DEFDOC (CPU_TIME, "Get current CPU time.", "\
1307 Returns in @var{@1@} the current value of the system time.
1308 This implementation of the Fortran 95 intrinsic is just an alias for
1309 @code{second} @xref{Second Intrinsic (subroutine)}.
1312 DEFDOC (TIME8, "Get current time as time value.", "\
1313 Returns the current time encoded as a long integer
1314 (in the manner of the UNIX function @code{time(3)}).
1315 This value is suitable for passing to @code{CTIME},
1316 @code{GMTIME}, and @code{LTIME}.
1318 No Fortran implementations other than GNU Fortran are
1319 known to support this intrinsic at the time of this
1321 @xref{Time Intrinsic (UNIX)}, for information on a
1322 similar intrinsic that might be portable to more Fortran
1323 compilers, though to fewer GNU Fortran implementations.
1326 DEFDOC (TIME_unix, "Get current time as time value.", "\
1327 Returns the current time encoded as an integer
1328 (in the manner of the UNIX function @code{time(3)}).
1329 This value is suitable for passing to @code{CTIME},
1330 @code{GMTIME}, and @code{LTIME}.
1332 This intrinsic is not fully portable, such as to systems
1333 with 32-bit @code{INTEGER} types but supporting times
1335 @xref{Time8 Intrinsic}, for information on a
1336 similar intrinsic that might be portable to more
1337 GNU Fortran implementations, though to fewer
1341 #define BES(num,n,val) "\
1342 Calculates the Bessel function of the " #num " kind of \
1343 order " #n " of @var{@" #val "@}.\n\
1344 See @code{bessel(3m)}, on whose implementation the \
1348 DEFDOC (BESJ0, "Bessel function.", BES (first, 0, 1))
1349 DEFDOC (BESJ1, "Bessel function.", BES (first, 1, 1))
1350 DEFDOC (BESJN, "Bessel function.", BES (first, @var{N}, 2))
1351 DEFDOC (BESY0, "Bessel function.", BES (second, 0, 1))
1352 DEFDOC (BESY1, "Bessel function.", BES (second, 1, 1))
1353 DEFDOC (BESYN, "Bessel function.", BES (second, @var{N}, 2))
1354 DEFDOC (DBESJ0, "Bessel function (archaic).", ARCHAIC (BESJ0, BesJ0))
1355 DEFDOC (DBESJ1, "Bessel function (archaic).", ARCHAIC (BESJ1, BesJ1))
1356 DEFDOC (DBESJN, "Bessel function (archaic).", ARCHAIC_2nd (BESJN, BesJN))
1357 DEFDOC (DBESY0, "Bessel function (archaic).", ARCHAIC (BESY0, BesY0))
1358 DEFDOC (DBESY1, "Bessel function (archaic).", ARCHAIC (BESY1, BesY1))
1359 DEFDOC (DBESYN, "Bessel function (archaic).", ARCHAIC_2nd (BESYN, BesYN))
1361 DEFDOC (ERF, "Error function.", "\
1362 Returns the error function of @var{@1@}.
1363 See @code{erf(3m)}, which provides the implementation.
1366 DEFDOC (ERFC, "Complementary error function.", "\
1367 Returns the complementary error function of @var{@1@}:
1368 @samp{ERFC(R) = 1 - ERF(R)} (except that the result may be more
1369 accurate than explicitly evaluating that formulae would give).
1370 See @code{erfc(3m)}, which provides the implementation.
1373 DEFDOC (DERF, "Error function (archaic).", ARCHAIC (ERF, ErF))
1374 DEFDOC (DERFC, "Complementary error function (archaic).", ARCHAIC (ERFC, ErFC))
1376 DEFDOC (IRAND, "Random number.", "\
1377 Returns a uniform quasi-random number up to a system-dependent limit.
1378 If @var{@1@} is 0, the next number in sequence is returned; if
1379 @var{@1@} is 1, the generator is restarted by calling the UNIX function
1380 @samp{srand(0)}; if @var{@1@} has any other value,
1381 it is used as a new seed with @code{srand()}.
1383 @xref{SRand Intrinsic}.
1385 @emph{Note:} As typically implemented (by the routine of the same
1386 name in the C library), this random number generator is a very poor
1387 one, though the BSD and GNU libraries provide a much better
1388 implementation than the `traditional' one.
1389 On a different system you almost certainly want to use something better.
1392 DEFDOC (RAND, "Random number.", "\
1393 Returns a uniform quasi-random number between 0 and 1.
1394 If @var{@1@} is 0, the next number in sequence is returned; if
1395 @var{@1@} is 1, the generator is restarted by calling @samp{srand(0)};
1396 if @var{@1@} has any other value, it is used as a new seed with
1399 @xref{SRand Intrinsic}.
1401 @emph{Note:} As typically implemented (by the routine of the same
1402 name in the C library), this random number generator is a very poor
1403 one, though the BSD and GNU libraries provide a much better
1404 implementation than the `traditional' one.
1405 On a different system you
1406 almost certainly want to use something better.
1409 DEFDOC (SRAND, "Random seed.", "\
1410 Reinitialises the generator with the seed in @var{@1@}.
1411 @xref{IRand Intrinsic}.
1412 @xref{Rand Intrinsic}.
1415 DEFDOC (ACCESS, "Check file accessibility.", "\
1416 Checks file @var{@1@} for accessibility in the mode specified by @var{@2@} and
1417 returns 0 if the file is accessible in that mode, otherwise an error
1418 code if the file is inaccessible or @var{@2@} is invalid.
1419 See @code{access(2)}.
1420 A null character (@samp{CHAR(0)}) marks the end of
1421 the name in @var{@1@}---otherwise,
1422 trailing blanks in @var{@1@} are ignored.
1423 @var{@2@} may be a concatenation of any of the following characters:
1440 DEFDOC (CHDIR_subr, "Change directory.", "\
1441 Sets the current working directory to be @var{@1@}.
1442 If the @var{@2@} argument is supplied, it contains 0
1443 on success or a non-zero error code otherwise upon return.
1444 See @code{chdir(3)}.
1446 @emph{Caution:} Using this routine during I/O to a unit connected with a
1447 non-absolute file name can cause subsequent I/O on such a unit to fail
1448 because the I/O library may reopen files by name.
1450 Some non-GNU implementations of Fortran provide this intrinsic as
1451 only a function, not as a subroutine, or do not support the
1452 (optional) @var{@2@} argument.
1455 DEFDOC (CHDIR_func, "Change directory.", "\
1456 Sets the current working directory to be @var{@1@}.
1457 Returns 0 on success or a non-zero error code.
1458 See @code{chdir(3)}.
1460 @emph{Caution:} Using this routine during I/O to a unit connected with a
1461 non-absolute file name can cause subsequent I/O on such a unit to fail
1462 because the I/O library may reopen files by name.
1464 Due to the side effects performed by this intrinsic, the function
1465 form is not recommended.
1468 DEFDOC (CHMOD_func, "Change file modes.", "\
1469 Changes the access mode of file @var{@1@} according to the
1470 specification @var{@2@}, which is given in the format of
1472 A null character (@samp{CHAR(0)}) marks the end of
1473 the name in @var{@1@}---otherwise,
1474 trailing blanks in @var{@1@} are ignored.
1475 Currently, @var{@1@} must not contain the single quote
1478 Returns 0 on success or a non-zero error code otherwise.
1480 Note that this currently works
1481 by actually invoking @code{/bin/chmod} (or the @code{chmod} found when
1482 the library was configured) and so may fail in some circumstances and
1483 will, anyway, be slow.
1485 Due to the side effects performed by this intrinsic, the function
1486 form is not recommended.
1489 DEFDOC (CHMOD_subr, "Change file modes.", "\
1490 Changes the access mode of file @var{@1@} according to the
1491 specification @var{@2@}, which is given in the format of
1493 A null character (@samp{CHAR(0)}) marks the end of
1494 the name in @var{@1@}---otherwise,
1495 trailing blanks in @var{@1@} are ignored.
1496 Currently, @var{@1@} must not contain the single quote
1499 If the @var{@3@} argument is supplied, it contains
1500 0 on success or a non-zero error code upon return.
1502 Note that this currently works
1503 by actually invoking @code{/bin/chmod} (or the @code{chmod} found when
1504 the library was configured) and so may fail in some circumstances and
1505 will, anyway, be slow.
1507 Some non-GNU implementations of Fortran provide this intrinsic as
1508 only a function, not as a subroutine, or do not support the
1509 (optional) @var{@3@} argument.
1512 DEFDOC (GETCWD_func, "Get current working directory.", "\
1513 Places the current working directory in @var{@1@}.
1515 success, otherwise a non-zero error code
1516 (@code{ENOSYS} if the system does not provide @code{getcwd(3)}
1517 or @code{getwd(3)}).
1520 DEFDOC (GETCWD_subr, "Get current working directory.", "\
1521 Places the current working directory in @var{@1@}.
1522 If the @var{@2@} argument is supplied, it contains 0
1523 success or a non-zero error code upon return
1524 (@code{ENOSYS} if the system does not provide @code{getcwd(3)}
1525 or @code{getwd(3)}).
1527 Some non-GNU implementations of Fortran provide this intrinsic as
1528 only a function, not as a subroutine, or do not support the
1529 (optional) @var{@2@} argument.
1532 DEFDOC (FSTAT_func, "Get file information.", "\
1533 Obtains data about the file open on Fortran I/O unit @var{@1@} and
1534 places them in the array @var{@2@}.
1535 The values in this array are
1536 extracted from the @code{stat} structure as returned by
1537 @code{fstat(2)} q.v., as follows:
1547 ID of device containing directory entry for file
1550 Device id (if relevant)
1568 Last modification time
1571 Last file status change time
1574 Preferred I/O block size
1577 Number of blocks allocated
1580 Not all these elements are relevant on all systems.
1581 If an element is not relevant, it is returned as 0.
1583 Returns 0 on success or a non-zero error code.
1586 DEFDOC (FSTAT_subr, "Get file information.", "\
1587 Obtains data about the file open on Fortran I/O unit @var{@1@} and
1588 places them in the array @var{@2@}.
1589 The values in this array are
1590 extracted from the @code{stat} structure as returned by
1591 @code{fstat(2)} q.v., as follows:
1601 ID of device containing directory entry for file
1604 Device id (if relevant)
1622 Last modification time
1625 Last file status change time
1628 Preferred I/O block size
1631 Number of blocks allocated
1634 Not all these elements are relevant on all systems.
1635 If an element is not relevant, it is returned as 0.
1637 If the @var{@3@} argument is supplied, it contains
1638 0 on success or a non-zero error code upon return.
1640 Some non-GNU implementations of Fortran provide this intrinsic as
1641 only a function, not as a subroutine, or do not support the
1642 (optional) @var{@3@} argument.
1645 DEFDOC (LSTAT_func, "Get file information.", "\
1646 Obtains data about the given file @var{@1@} and places them in the array
1648 A null character (@samp{CHAR(0)}) marks the end of
1649 the name in @var{@1@}---otherwise,
1650 trailing blanks in @var{@1@} are ignored.
1651 If @var{@1@} is a symbolic link it returns data on the
1652 link itself, so the routine is available only on systems that support
1654 The values in this array are extracted from the
1655 @code{stat} structure as returned by @code{fstat(2)} q.v., as follows:
1665 ID of device containing directory entry for file
1668 Device id (if relevant)
1686 Last modification time
1689 Last file status change time
1692 Preferred I/O block size
1695 Number of blocks allocated
1698 Not all these elements are relevant on all systems.
1699 If an element is not relevant, it is returned as 0.
1701 Returns 0 on success or a non-zero error code
1702 (@code{ENOSYS} if the system does not provide @code{lstat(2)}).
1705 DEFDOC (LSTAT_subr, "Get file information.", "\
1706 Obtains data about the given file @var{@1@} and places them in the array
1708 A null character (@samp{CHAR(0)}) marks the end of
1709 the name in @var{@1@}---otherwise,
1710 trailing blanks in @var{@1@} are ignored.
1711 If @var{@1@} is a symbolic link it returns data on the
1712 link itself, so the routine is available only on systems that support
1714 The values in this array are extracted from the
1715 @code{stat} structure as returned by @code{fstat(2)} q.v., as follows:
1725 ID of device containing directory entry for file
1728 Device id (if relevant)
1746 Last modification time
1749 Last file status change time
1752 Preferred I/O block size
1755 Number of blocks allocated
1758 Not all these elements are relevant on all systems.
1759 If an element is not relevant, it is returned as 0.
1761 If the @var{@3@} argument is supplied, it contains
1762 0 on success or a non-zero error code upon return
1763 (@code{ENOSYS} if the system does not provide @code{lstat(2)}).
1765 Some non-GNU implementations of Fortran provide this intrinsic as
1766 only a function, not as a subroutine, or do not support the
1767 (optional) @var{@3@} argument.
1770 DEFDOC (STAT_func, "Get file information.", "\
1771 Obtains data about the given file @var{@1@} and places them in the array
1773 A null character (@samp{CHAR(0)}) marks the end of
1774 the name in @var{@1@}---otherwise,
1775 trailing blanks in @var{@1@} are ignored.
1776 The values in this array are extracted from the
1777 @code{stat} structure as returned by @code{fstat(2)} q.v., as follows:
1787 ID of device containing directory entry for file
1790 Device id (if relevant)
1808 Last modification time
1811 Last file status change time
1814 Preferred I/O block size
1817 Number of blocks allocated
1820 Not all these elements are relevant on all systems.
1821 If an element is not relevant, it is returned as 0.
1823 Returns 0 on success or a non-zero error code.
1826 DEFDOC (STAT_subr, "Get file information.", "\
1827 Obtains data about the given file @var{@1@} and places them in the array
1829 A null character (@samp{CHAR(0)}) marks the end of
1830 the name in @var{@1@}---otherwise,
1831 trailing blanks in @var{@1@} are ignored.
1832 The values in this array are extracted from the
1833 @code{stat} structure as returned by @code{fstat(2)} q.v., as follows:
1843 ID of device containing directory entry for file
1846 Device id (if relevant)
1864 Last modification time
1867 Last file status change time
1870 Preferred I/O block size
1873 Number of blocks allocated
1876 Not all these elements are relevant on all systems.
1877 If an element is not relevant, it is returned as 0.
1879 If the @var{@3@} argument is supplied, it contains
1880 0 on success or a non-zero error code upon return.
1882 Some non-GNU implementations of Fortran provide this intrinsic as
1883 only a function, not as a subroutine, or do not support the
1884 (optional) @var{@3@} argument.
1887 DEFDOC (LINK_subr, "Make hard link in file system.", "\
1888 Makes a (hard) link from file @var{@1@} to @var{@2@}.
1889 A null character (@samp{CHAR(0)}) marks the end of
1890 the names in @var{@1@} and @var{@2@}---otherwise,
1891 trailing blanks in @var{@1@} and @var{@2@} are ignored.
1892 If the @var{@3@} argument is supplied, it contains
1893 0 on success or a non-zero error code upon return.
1896 Some non-GNU implementations of Fortran provide this intrinsic as
1897 only a function, not as a subroutine, or do not support the
1898 (optional) @var{@3@} argument.
1901 DEFDOC (LINK_func, "Make hard link in file system.", "\
1902 Makes a (hard) link from file @var{@1@} to @var{@2@}.
1903 A null character (@samp{CHAR(0)}) marks the end of
1904 the names in @var{@1@} and @var{@2@}---otherwise,
1905 trailing blanks in @var{@1@} and @var{@2@} are ignored.
1906 Returns 0 on success or a non-zero error code.
1909 Due to the side effects performed by this intrinsic, the function
1910 form is not recommended.
1913 DEFDOC (SYMLNK_subr, "Make symbolic link in file system.", "\
1914 Makes a symbolic link from file @var{@1@} to @var{@2@}.
1915 A null character (@samp{CHAR(0)}) marks the end of
1916 the names in @var{@1@} and @var{@2@}---otherwise,
1917 trailing blanks in @var{@1@} and @var{@2@} are ignored.
1918 If the @var{@3@} argument is supplied, it contains
1919 0 on success or a non-zero error code upon return
1920 (@code{ENOSYS} if the system does not provide @code{symlink(2)}).
1922 Some non-GNU implementations of Fortran provide this intrinsic as
1923 only a function, not as a subroutine, or do not support the
1924 (optional) @var{@3@} argument.
1927 DEFDOC (SYMLNK_func, "Make symbolic link in file system.", "\
1928 Makes a symbolic link from file @var{@1@} to @var{@2@}.
1929 A null character (@samp{CHAR(0)}) marks the end of
1930 the names in @var{@1@} and @var{@2@}---otherwise,
1931 trailing blanks in @var{@1@} and @var{@2@} are ignored.
1932 Returns 0 on success or a non-zero error code
1933 (@code{ENOSYS} if the system does not provide @code{symlink(2)}).
1935 Due to the side effects performed by this intrinsic, the function
1936 form is not recommended.
1939 DEFDOC (RENAME_subr, "Rename file.", "\
1940 Renames the file @var{@1@} to @var{@2@}.
1941 A null character (@samp{CHAR(0)}) marks the end of
1942 the names in @var{@1@} and @var{@2@}---otherwise,
1943 trailing blanks in @var{@1@} and @var{@2@} are ignored.
1944 See @code{rename(2)}.
1945 If the @var{@3@} argument is supplied, it contains
1946 0 on success or a non-zero error code upon return.
1948 Some non-GNU implementations of Fortran provide this intrinsic as
1949 only a function, not as a subroutine, or do not support the
1950 (optional) @var{@3@} argument.
1953 DEFDOC (RENAME_func, "Rename file.", "\
1954 Renames the file @var{@1@} to @var{@2@}.
1955 A null character (@samp{CHAR(0)}) marks the end of
1956 the names in @var{@1@} and @var{@2@}---otherwise,
1957 trailing blanks in @var{@1@} and @var{@2@} are ignored.
1958 See @code{rename(2)}.
1959 Returns 0 on success or a non-zero error code.
1961 Due to the side effects performed by this intrinsic, the function
1962 form is not recommended.
1965 DEFDOC (UMASK_subr, "Set file creation permissions mask.", "\
1966 Sets the file creation mask to @var{@1@} and returns the old value in
1967 argument @var{@2@} if it is supplied.
1968 See @code{umask(2)}.
1970 Some non-GNU implementations of Fortran provide this intrinsic as
1971 only a function, not as a subroutine.
1974 DEFDOC (UMASK_func, "Set file creation permissions mask.", "\
1975 Sets the file creation mask to @var{@1@} and returns the old value.
1976 See @code{umask(2)}.
1978 Due to the side effects performed by this intrinsic, the function
1979 form is not recommended.
1982 DEFDOC (UNLINK_subr, "Unlink file.", "\
1983 Unlink the file @var{@1@}.
1984 A null character (@samp{CHAR(0)}) marks the end of
1985 the name in @var{@1@}---otherwise,
1986 trailing blanks in @var{@1@} are ignored.
1987 If the @var{@2@} argument is supplied, it contains
1988 0 on success or a non-zero error code upon return.
1989 See @code{unlink(2)}.
1991 Some non-GNU implementations of Fortran provide this intrinsic as
1992 only a function, not as a subroutine, or do not support the
1993 (optional) @var{@2@} argument.
1996 DEFDOC (UNLINK_func, "Unlink file.", "\
1997 Unlink the file @var{@1@}.
1998 A null character (@samp{CHAR(0)}) marks the end of
1999 the name in @var{@1@}---otherwise,
2000 trailing blanks in @var{@1@} are ignored.
2001 Returns 0 on success or a non-zero error code.
2002 See @code{unlink(2)}.
2004 Due to the side effects performed by this intrinsic, the function
2005 form is not recommended.
2008 DEFDOC (GERROR, "Get error message for last error.", "\
2009 Returns the system error message corresponding to the last system
2010 error (C @code{errno}).
2013 DEFDOC (IERRNO, "Get error number for last error.", "\
2014 Returns the last system error number (corresponding to the C
2018 DEFDOC (PERROR, "Print error message for last error.", "\
2019 Prints (on the C @code{stderr} stream) a newline-terminated error
2020 message corresponding to the last system error.
2021 This is prefixed by @var{@1@}, a colon and a space.
2022 See @code{perror(3)}.
2025 DEFDOC (GETGID, "Get process group id.", "\
2026 Returns the group id for the current process.
2029 DEFDOC (GETUID, "Get process user id.", "\
2030 Returns the user id for the current process.
2033 DEFDOC (GETPID, "Get process id.", "\
2034 Returns the process id for the current process.
2037 DEFDOC (GETENV, "Get environment variable.", "\
2038 Sets @var{@2@} to the value of environment variable given by the
2039 value of @var{@1@} (@code{$name} in shell terms) or to blanks if
2040 @code{$name} has not been set.
2041 A null character (@samp{CHAR(0)}) marks the end of
2042 the name in @var{@1@}---otherwise,
2043 trailing blanks in @var{@1@} are ignored.
2046 DEFDOC (GETLOG, "Get login name.", "\
2047 Returns the login name for the process in @var{@1@}.
2049 @emph{Caution:} On some systems, the @code{getlogin(3)}
2050 function, which this intrinsic calls at run time,
2051 is either not implemented or returns a null pointer.
2052 In the latter case, this intrinsic returns blanks
2056 DEFDOC (HOSTNM_func, "Get host name.", "\
2057 Fills @var{@1@} with the system's host name returned by
2058 @code{gethostname(2)}, returning 0 on success or a non-zero error code
2059 (@code{ENOSYS} if the system does not provide @code{gethostname(2)}).
2062 DEFDOC (HOSTNM_subr, "Get host name.", "\
2063 Fills @var{@1@} with the system's host name returned by
2064 @code{gethostname(2)}.
2065 If the @var{@2@} argument is supplied, it contains
2066 0 on success or a non-zero error code upon return
2067 (@code{ENOSYS} if the system does not provide @code{gethostname(2)}).
2069 Some non-GNU implementations of Fortran provide this intrinsic as
2070 only a function, not as a subroutine, or do not support the
2071 (optional) @var{@2@} argument.
2074 /* Fixme: stream I/O */
2076 DEFDOC (FLUSH, "Flush buffered output.", "\
2077 Flushes Fortran unit(s) currently open for output.
2078 Without the optional argument, all such units are flushed,
2079 otherwise just the unit specified by @var{@1@}.
2081 Some non-GNU implementations of Fortran provide this intrinsic
2082 as a library procedure that might or might not support the
2083 (optional) @var{@1@} argument.
2086 DEFDOC (FNUM, "Get file descriptor from Fortran unit number.", "\
2087 Returns the Unix file descriptor number corresponding to the open
2088 Fortran I/O unit @var{@1@}.
2089 This could be passed to an interface to C I/O routines.
2093 Stream I/O should not be mixed with normal record-oriented (formatted or
2094 unformatted) I/O on the same unit; the results are unpredictable.
2097 DEFDOC (FGET_func, "Read a character from unit 5 stream-wise.", "\
2098 Reads a single character into @var{@1@} in stream mode from unit 5
2099 (by-passing normal formatted input) using @code{getc(3)}.
2101 success, @minus{}1 on end-of-file, and the error code from
2102 @code{ferror(3)} otherwise.
2105 DEFDOC (FGET_subr, "Read a character from unit 5 stream-wise.", "\
2106 Reads a single character into @var{@1@} in stream mode from unit 5
2107 (by-passing normal formatted output) using @code{getc(3)}.
2109 @var{@2@} 0 on success, @minus{}1 on end-of-file, and the error code
2110 from @code{ferror(3)} otherwise.
2113 DEFDOC (FGETC_func, "Read a character stream-wise.", "\
2114 Reads a single character into @var{@2@} in stream mode from unit @var{@1@}
2115 (by-passing normal formatted output) using @code{getc(3)}.
2117 success, @minus{}1 on end-of-file, and the error code from
2118 @code{ferror(3)} otherwise.
2121 DEFDOC (FGETC_subr, "Read a character stream-wise.", "\
2122 Reads a single character into @var{@2@} in stream mode from unit @var{@1@}
2123 (by-passing normal formatted output) using @code{getc(3)}.
2125 @var{@3@} 0 on success, @minus{}1 on end-of-file, and the error code from
2126 @code{ferror(3)} otherwise.
2129 DEFDOC (FPUT_func, "Write a character to unit 6 stream-wise.", "\
2130 Writes the single character @var{@1@} in stream mode to unit 6
2131 (by-passing normal formatted output) using @code{getc(3)}.
2133 success, the error code from @code{ferror(3)} otherwise.
2136 DEFDOC (FPUT_subr, "Write a character to unit 6 stream-wise.", "\
2137 Writes the single character @var{@1@} in stream mode to unit 6
2138 (by-passing normal formatted output) using @code{putc(3)}.
2140 @var{@2@} 0 on success, the error code from @code{ferror(3)} otherwise.
2143 DEFDOC (FPUTC_func, "Write a character stream-wise.", "\
2144 Writes the single character @var{@2@} in stream mode to unit @var{@1@}
2145 (by-passing normal formatted output) using @code{putc(3)}.
2147 success, the error code from @code{ferror(3)} otherwise.
2150 DEFDOC (FPUTC_subr, "Write a character stream-wise.", "\
2151 Writes the single character @var{@1@} in stream mode to unit 6
2152 (by-passing normal formatted output) using @code{putc(3)}.
2154 @var{@2@} 0 on success, the error code from @code{ferror(3)} otherwise.
2157 DEFDOC (FSEEK, "Position file (low-level).", "\
2158 Attempts to move Fortran unit @var{@1@} to the specified
2159 @var{Offset}: absolute offset if @var{@2@}=0; relative to the
2160 current offset if @var{@2@}=1; relative to the end of the file if
2162 It branches to label @var{@3@} if @var{@1@} is
2163 not open or if the call otherwise fails.
2166 DEFDOC (FTELL_func, "Get file position (low-level).", "\
2167 Returns the current offset of Fortran unit @var{@1@}
2168 (or @minus{}1 if @var{@1@} is not open).
2171 DEFDOC (FTELL_subr, "Get file position (low-level).", "\
2172 Sets @var{@2@} to the current offset of Fortran unit @var{@1@}
2173 (or to @minus{}1 if @var{@1@} is not open).
2175 Some non-GNU implementations of Fortran provide this intrinsic as
2176 only a function, not as a subroutine.
2179 DEFDOC (ISATTY, "Is unit connected to a terminal?", "\
2180 Returns @code{.TRUE.} if and only if the Fortran I/O unit
2181 specified by @var{@1@} is connected
2182 to a terminal device.
2183 See @code{isatty(3)}.
2186 DEFDOC (TTYNAM_func, "Get name of terminal device for unit.", "\
2187 Returns the name of the terminal device open on logical unit
2188 @var{@1@} or a blank string if @var{@1@} is not connected to a
2192 DEFDOC (TTYNAM_subr, "Get name of terminal device for unit.", "\
2193 Sets @var{@1@} to the name of the terminal device open on logical unit
2194 @var{@2@} or a blank string if @var{@2@} is not connected to a
2197 Some non-GNU implementations of Fortran provide this intrinsic as
2198 only a function, not as a subroutine.
2201 DEFDOC (SIGNAL_subr, "Muck with signal handling.", "\
2202 If @var{@2@} is a an @code{EXTERNAL} routine, arranges for it to be
2203 invoked with a single integer argument (of system-dependent length)
2204 when signal @var{@1@} occurs.
2205 If @var{@2@} is an integer, it can be
2206 used to turn off handling of signal @var{@1@} or revert to its default
2208 See @code{signal(2)}.
2210 Note that @var{@2@} will be called using C conventions,
2211 so the value of its argument in Fortran terms
2212 Fortran terms is obtained by applying @code{%LOC()} (or @var{LOC()}) to it.
2214 The value returned by @code{signal(2)} is written to @var{@3@}, if
2215 that argument is supplied.
2216 Otherwise the return value is ignored.
2218 Some non-GNU implementations of Fortran provide this intrinsic as
2219 only a function, not as a subroutine, or do not support the
2220 (optional) @var{@3@} argument.
2222 @emph{Warning:} Use of the @code{libf2c} run-time library function
2223 @samp{signal_} directly
2224 (such as via @samp{EXTERNAL SIGNAL})
2225 requires use of the @code{%VAL()} construct
2226 to pass an @code{INTEGER} value
2227 (such as @samp{SIG_IGN} or @samp{SIG_DFL})
2228 for the @var{@2@} argument.
2230 However, while @samp{CALL SIGNAL(@var{signum}, %VAL(SIG_IGN))}
2231 works when @samp{SIGNAL} is treated as an external procedure
2232 (and resolves, at link time, to @code{libf2c}'s @samp{signal_} routine),
2233 this construct is not valid when @samp{SIGNAL} is recognized
2234 as the intrinsic of that name.
2236 Therefore, for maximum portability and reliability,
2237 code such references to the @samp{SIGNAL} facility as follows:
2242 CALL SIGNAL(@var{signum}, SIG_IGN)
2245 @code{g77} will compile such a call correctly,
2246 while other compilers will generally either do so as well
2247 or reject the @samp{INTRINSIC SIGNAL} statement via a diagnostic,
2248 allowing you to take appropriate action.
2251 DEFDOC (SIGNAL_func, "Muck with signal handling.", "\
2252 If @var{@2@} is a an @code{EXTERNAL} routine, arranges for it to be
2253 invoked with a single integer argument (of system-dependent length)
2254 when signal @var{@1@} occurs.
2255 If @var{@2@} is an integer, it can be
2256 used to turn off handling of signal @var{@1@} or revert to its default
2258 See @code{signal(2)}.
2260 Note that @var{@2@} will be called using C conventions,
2261 so the value of its argument in Fortran terms
2262 is obtained by applying @code{%LOC()} (or @var{LOC()}) to it.
2264 The value returned by @code{signal(2)} is returned.
2266 Due to the side effects performed by this intrinsic, the function
2267 form is not recommended.
2269 @emph{Warning:} If the returned value is stored in
2270 an @code{INTEGER(KIND=1)} (default @code{INTEGER}) argument,
2271 truncation of the original return value occurs on some systems
2272 (such as Alphas, which have 64-bit pointers but 32-bit default integers),
2273 with no warning issued by @code{g77} under normal circumstances.
2275 Therefore, the following code fragment might silently fail on
2281 RTN = SIGNAL(@var{signum}, MYHNDL)
2283 ! Restore original handler:
2284 RTN = SIGNAL(@var{signum}, RTN)
2287 The reason for the failure is that @samp{RTN} might not hold
2288 all the information on the original handler for the signal,
2289 thus restoring an invalid handler.
2290 This bug could manifest itself as a spurious run-time failure
2291 at an arbitrary point later during the program's execution,
2294 @emph{Warning:} Use of the @code{libf2c} run-time library function
2295 @samp{signal_} directly
2296 (such as via @samp{EXTERNAL SIGNAL})
2297 requires use of the @code{%VAL()} construct
2298 to pass an @code{INTEGER} value
2299 (such as @samp{SIG_IGN} or @samp{SIG_DFL})
2300 for the @var{@2@} argument.
2302 However, while @samp{RTN = SIGNAL(@var{signum}, %VAL(SIG_IGN))}
2303 works when @samp{SIGNAL} is treated as an external procedure
2304 (and resolves, at link time, to @code{libf2c}'s @samp{signal_} routine),
2305 this construct is not valid when @samp{SIGNAL} is recognized
2306 as the intrinsic of that name.
2308 Therefore, for maximum portability and reliability,
2309 code such references to the @samp{SIGNAL} facility as follows:
2314 RTN = SIGNAL(@var{signum}, SIG_IGN)
2317 @code{g77} will compile such a call correctly,
2318 while other compilers will generally either do so as well
2319 or reject the @samp{INTRINSIC SIGNAL} statement via a diagnostic,
2320 allowing you to take appropriate action.
2323 DEFDOC (KILL_func, "Signal a process.", "\
2324 Sends the signal specified by @var{@2@} to the process @var{@1@}.
2325 Returns 0 on success or a non-zero error code.
2328 Due to the side effects performed by this intrinsic, the function
2329 form is not recommended.
2332 DEFDOC (KILL_subr, "Signal a process.", "\
2333 Sends the signal specified by @var{@2@} to the process @var{@1@}.
2334 If the @var{@3@} argument is supplied, it contains
2335 0 on success or a non-zero error code upon return.
2338 Some non-GNU implementations of Fortran provide this intrinsic as
2339 only a function, not as a subroutine, or do not support the
2340 (optional) @var{@3@} argument.
2343 DEFDOC (LNBLNK, "Get last non-blank character in string.", "\
2344 Returns the index of the last non-blank character in @var{@1@}.
2345 @code{LNBLNK} and @code{LEN_TRIM} are equivalent.
2348 DEFDOC (SLEEP, "Sleep for a specified time.", "\
2349 Causes the process to pause for @var{@1@} seconds.
2350 See @code{sleep(2)}.
2353 DEFDOC (SYSTEM_subr, "Invoke shell (system) command.", "\
2354 Passes the command @var{@1@} to a shell (see @code{system(3)}).
2355 If argument @var{@2@} is present, it contains the value returned by
2356 @code{system(3)}, presumably 0 if the shell command succeeded.
2357 Note that which shell is used to invoke the command is system-dependent
2358 and environment-dependent.
2360 Some non-GNU implementations of Fortran provide this intrinsic as
2361 only a function, not as a subroutine, or do not support the
2362 (optional) @var{@2@} argument.
2365 DEFDOC (SYSTEM_func, "Invoke shell (system) command.", "\
2366 Passes the command @var{@1@} to a shell (see @code{system(3)}).
2367 Returns the value returned by
2368 @code{system(3)}, presumably 0 if the shell command succeeded.
2369 Note that which shell is used to invoke the command is system-dependent
2370 and environment-dependent.
2372 Due to the side effects performed by this intrinsic, the function
2373 form is not recommended.
2374 However, the function form can be valid in cases where the
2375 actual side effects performed by the call are unimportant to
2378 For example, on a UNIX system, @samp{SAME = SYSTEM('cmp a b')}
2379 does not perform any side effects likely to be important to the
2380 program, so the programmer would not care if the actual system
2381 call (and invocation of @code{cmp}) was optimized away in a situation
2382 where the return value could be determined otherwise, or was not
2383 actually needed (@samp{SAME} not actually referenced after the
2384 sample assignment statement).
2387 DEFDOC (TIME_vxt, "Get the time as a character value.", "\
2388 Returns in @var{@1@} a character representation of the current time as
2389 obtained from @code{ctime(3)}.
2391 @xref{Fdate Intrinsic (subroutine)} for an equivalent routine.
2394 DEFDOC (IBCLR, "Clear a bit.", "\
2395 Returns the value of @var{@1@} with bit @var{@2@} cleared (set to
2397 @xref{BTest Intrinsic} for information on bit positions.
2400 DEFDOC (IBSET, "Set a bit.", "\
2401 Returns the value of @var{@1@} with bit @var{@2@} set (to one).
2402 @xref{BTest Intrinsic} for information on bit positions.
2405 DEFDOC (IBITS, "Extract a bit subfield of a variable.", "\
2406 Extracts a subfield of length @var{@3@} from @var{@1@}, starting from
2407 bit position @var{@2@} and extending left for @var{@3@} bits.
2408 The result is right-justified and the remaining bits are zeroed.
2410 of @samp{@var{@2@}+@var{@3@}} must be less than or equal to the value
2411 @samp{BIT_SIZE(@var{@1@})}.
2412 @xref{Bit_Size Intrinsic}.
2415 DEFDOC (ISHFT, "Logical bit shift.", "\
2416 All bits representing @var{@1@} are shifted @var{@2@} places.
2417 @samp{@var{@2@}.GT.0} indicates a left shift, @samp{@var{@2@}.EQ.0}
2418 indicates no shift and @samp{@var{@2@}.LT.0} indicates a right shift.
2419 If the absolute value of the shift count is greater than
2420 @samp{BIT_SIZE(@var{@1@})}, the result is undefined.
2421 Bits shifted out from the left end or the right end, as the case may be,
2423 Zeros are shifted in from the opposite end.
2425 @xref{IShftC Intrinsic} for the circular-shift equivalent.
2428 DEFDOC (ISHFTC, "Circular bit shift.", "\
2429 The rightmost @var{@3@} bits of the argument @var{@1@}
2430 are shifted circularly @var{@2@}
2431 places, i.e.@ the bits shifted out of one end are shifted into
2434 The unshifted bits of the result are the same as
2435 the unshifted bits of @var{@1@}.
2436 The absolute value of the argument @var{@2@}
2437 must be less than or equal to @var{@3@}.
2438 The value of @var{@3@} must be greater than or equal to one and less than
2439 or equal to @samp{BIT_SIZE(@var{@1@})}.
2441 @xref{IShft Intrinsic} for the logical shift equivalent.
2444 DEFDOC (MVBITS, "Moving a bit field.", "\
2445 Moves @var{@3@} bits from positions @var{@2@} through
2446 @samp{@var{@2@}+@var{@3@}-1} of @var{@1@} to positions @var{@5@} through
2447 @samp{@var{@2@}+@var{@3@}-1} of @var{@4@}. The portion of argument
2448 @var{@4@} not affected by the movement of bits is unchanged. Arguments
2449 @var{@1@} and @var{@4@} are permitted to be the same numeric storage
2450 unit. The values of @samp{@var{@2@}+@var{@3@}} and
2451 @samp{@var{@5@}+@var{@3@}} must be less than or equal to
2452 @samp{BIT_SIZE(@var{@1@})}.
2455 DEFDOC (INDEX, "Locate a CHARACTER substring.", "\
2456 Returns the position of the start of the first occurrence of string
2457 @var{@2@} as a substring in @var{@1@}, counting from one.
2458 If @var{@2@} doesn't occur in @var{@1@}, zero is returned.
2461 DEFDOC (ALARM, "Execute a routine after a given delay.", "\
2462 Causes external subroutine @var{@2@} to be executed after a delay of
2463 @var{@1@} seconds by using @code{alarm(1)} to set up a signal and
2464 @code{signal(2)} to catch it.
2465 If @var{@3@} is supplied, it will be
2466 returned with the number of seconds remaining until any previously
2467 scheduled alarm was due to be delivered, or zero if there was no
2468 previously scheduled alarm.
2469 @xref{Signal Intrinsic (subroutine)}.