gcc/f/intdoc.in

   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. */
   4
   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:
   8
   9    DEFDOC (IMP, SUMMARY, DESCRIPTION)
  10
  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.
  15
  16    Note that IMP is leveraged across multiple intrinsic names.
  17
  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
  21
  22    @ARGNO@
  23
  24    where ARGNO is a series of digits forming a number that
  25    is substituted by intdoc.c as follows:
  26
  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.
  30
  31    Hope this info is enough to encourage people to feel free to
  32    add documentation to this file!
  33
  34 */
  35
  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"
  40
  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"
  45
  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"
  50
  51 DEFDOC (ABS, "Absolute value.", "\
  52 Returns the absolute value of @var{@1@}.
  53
  54 If @var{@1@} is type @code{COMPLEX}, the absolute
  55 value is computed as:
  56
  57 @example
  58 SQRT(REALPART(@var{@1@})**2, IMAGPART(@var{@1@})**2)
  59 @end example
  60
  61 @noindent
  62 Otherwise, it is computed by negating the @var{@1@} if
  63 it is negative, or returning @var{@1@}.
  64
  65 @xref{Sign Intrinsic}, for how to explicitly
  66 compute the positive or negative form of the absolute
  67 value of an expression.
  68 ")
  69
  70 DEFDOC (CABS, "Absolute value (archaic).", ARCHAIC (ABS, Abs))
  71
  72 DEFDOC (DABS, "Absolute value (archaic).", ARCHAIC (ABS, Abs))
  73
  74 DEFDOC (IABS, "Absolute value (archaic).", ARCHAIC (ABS, Abs))
  75
  76 DEFDOC (CDABS, "Absolute value (archaic).", ARCHAIC (ABS, Abs))
  77
  78 DEFDOC (ACHAR, "ASCII character from code.", "\
  79 Returns the ASCII character corresponding to the
  80 code specified by @var{@1@}.
  81
  82 @xref{IAChar Intrinsic}, for the inverse of this function.
  83
  84 @xref{Char Intrinsic}, for the function corresponding
  85 to the system's native character set.
  86 ")
  87
  88 DEFDOC (IACHAR, "ASCII code for character.", "\
  89 Returns the code for the ASCII character in the
  90 first character position of @var{@1@}.
  91
  92 @xref{AChar Intrinsic}, for the inverse of this function.
  93
  94 @xref{IChar Intrinsic}, for the function corresponding
  95 to the system's native character set.
  96 ")
  97
  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.
 102
 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.
 107
 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'}.
 114
 115 Instead, you can use internal-file I/O to do this kind
 116 of conversion.
 117 For example:
 118
 119 @smallexample
 120 INTEGER VALUE
 121 CHARACTER*10 STRING
 122 VALUE = 154
 123 WRITE (STRING, '(I10)'), VALUE
 124 PRINT *, STRING
 125 END
 126 @end smallexample
 127
 128 The above program, when run, prints:
 129
 130 @smallexample
 131         154
 132 @end smallexample
 133
 134 @xref{IChar Intrinsic}, for the inverse of the @code{@0@} function.
 135
 136 @xref{AChar Intrinsic}, for the function corresponding
 137 to the ASCII character set.
 138 ")
 139
 140 DEFDOC (ICHAR, "Code for character.", "\
 141 Returns the code for the character in the
 142 first character position of @var{@1@}.
 143
 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.
 148
 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}.
 154
 155 Instead, you can use internal-file I/O to do this kind
 156 of conversion.
 157 For example:
 158
 159 @smallexample
 160 INTEGER VALUE
 161 CHARACTER*10 STRING
 162 STRING = '154'
 163 READ (STRING, '(I10)'), VALUE
 164 PRINT *, VALUE
 165 END
 166 @end smallexample
 167
 168 The above program, when run, prints:
 169
 170 @smallexample
 171  154
 172 @end smallexample
 173
 174 @xref{Char Intrinsic}, for the inverse of the @code{@0@} function.
 175
 176 @xref{IAChar Intrinsic}, for the function corresponding
 177 to the ASCII character set.
 178 ")
 179
 180 DEFDOC (ACOS, "Arc cosine.", "\
 181 Returns the arc-cosine (inverse cosine) of @var{@1@}
 182 in radians.
 183
 184 @xref{Cos Intrinsic}, for the inverse of this function.
 185 ")
 186
 187 DEFDOC (DACOS, "Arc cosine (archaic).", ARCHAIC (ACOS, ACos))
 188
 189 DEFDOC (AIMAG, "Convert/extract imaginary part of complex.", "\
 190 Returns the (possibly converted) imaginary part of @var{@1@}.
 191
 192 Use of @code{@0@()} with an argument of a type
 193 other than @code{COMPLEX(KIND=1)} is restricted to the following case:
 194
 195 @example
 196 REAL(AIMAG(@1@))
 197 @end example
 198
 199 @noindent
 200 This expression converts the imaginary part of @1@ to
 201 @code{REAL(KIND=1)}.
 202
 203 @xref{REAL() and AIMAG() of Complex}, for more information.
 204 ")
 205
 206 DEFDOC (DIMAG, "Convert/extract imaginary part of complex (archaic).", ARCHAIC (AIMAG, AImag))
 207
 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''.)
 212
 213 @xref{ANInt Intrinsic}, for how to round to nearest
 214 whole number.
 215
 216 @xref{Int Intrinsic}, for how to truncate and then convert
 217 number to @code{INTEGER}.
 218 ")
 219
 220 DEFDOC (DINT, "Truncate to whole number (archaic).", ARCHAIC (AINT, AInt))
 221
 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)}.
 226
 227 If @var{@1@} is type @code{COMPLEX}, its real part is
 228 truncated and converted, and its imaginary part is disregarded.
 229
 230 @xref{NInt Intrinsic}, for how to convert, rounded to nearest
 231 whole number.
 232
 233 @xref{AInt Intrinsic}, for how to truncate to whole number
 234 without converting.
 235 ")
 236
 237 DEFDOC (IDINT, "Convert to @code{INTEGER} value truncated@99@to whole number (archaic).", ARCHAIC (INT, Int))
 238
 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.
 243
 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''.)
 248
 249 @xref{AInt Intrinsic}, for how to truncate to
 250 whole number.
 251
 252 @xref{NInt Intrinsic}, for how to round and then convert
 253 number to @code{INTEGER}.
 254 ")
 255
 256 DEFDOC (DNINT, "Round to nearest whole number (archaic).", ARCHAIC (ANINT, ANInt))
 257
 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)}.
 263
 264 If @var{@1@} is type @code{COMPLEX}, its real part is
 265 rounded and converted.
 266
 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''.)
 271
 272 @xref{Int Intrinsic}, for how to convert, truncate to
 273 whole number.
 274
 275 @xref{ANInt Intrinsic}, for how to round to nearest whole number
 276 without converting.
 277 ")
 278
 279 DEFDOC (IDNINT, "Convert to @code{INTEGER} value rounded@99@to nearest whole number (archaic).", ARCHAIC (NINT, NInt))
 280
 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.
 285
 286 @xref{Exp Intrinsic}, for the inverse of this function.
 287
 288 @xref{Log10 Intrinsic}, for the base-10 logarithm function.
 289 ")
 290
 291 DEFDOC (ALOG, "Natural logarithm (archaic).", ARCHAIC (LOG, Log))
 292
 293 DEFDOC (CLOG, "Natural logarithm (archaic).", ARCHAIC (LOG, Log))
 294
 295 DEFDOC (DLOG, "Natural logarithm (archaic).", ARCHAIC (LOG, Log))
 296
 297 DEFDOC (CDLOG, "Natural logarithm (archaic).", ARCHAIC (LOG, Log))
 298
 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
 302 be zero.
 303
 304 The inverse of this function is @samp{10. ** LOG10(@var{@1@})}.
 305
 306 @xref{Log Intrinsic}, for the natural logarithm function.
 307 ")
 308
 309 DEFDOC (ALOG10, "Natural logarithm (archaic).", ARCHAIC (LOG10, Log10))
 310
 311 DEFDOC (DLOG10, "Natural logarithm (archaic).", ARCHAIC (LOG10, Log10))
 312
 313 DEFDOC (MAX, "Maximum value.", "\
 314 Returns the argument with the largest value.
 315
 316 @xref{Min Intrinsic}, for the opposite function.
 317 ")
 318
 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}.
 323 ")
 324
 325 DEFDOC (AMAX1, "Maximum value (archaic).", ARCHAIC (MAX, Max))
 326
 327 DEFDOC (DMAX1, "Maximum value (archaic).", ARCHAIC (MAX, Max))
 328
 329 DEFDOC (MAX0, "Maximum value (archaic).", ARCHAIC (MAX, Max))
 330
 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}.
 335 ")
 336
 337 DEFDOC (MIN, "Minimum value.", "\
 338 Returns the argument with the smallest value.
 339
 340 @xref{Max Intrinsic}, for the opposite function.
 341 ")
 342
 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}.
 347 ")
 348
 349 DEFDOC (AMIN1, "Minimum value (archaic).", ARCHAIC (MIN, Min))
 350
 351 DEFDOC (DMIN1, "Minimum value (archaic).", ARCHAIC (MIN, Min))
 352
 353 DEFDOC (MIN0, "Minimum value (archaic).", ARCHAIC (MIN, Min))
 354
 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}.
 359 ")
 360
 361 DEFDOC (MOD, "Remainder.", "\
 362 Returns remainder calculated as:
 363
 364 @smallexample
 365 @var{@1@} - (INT(@var{@1@} / @var{@2@}) * @var{@2@})
 366 @end smallexample
 367
 368 @var{@2@} must not be zero.
 369 ")
 370
 371 DEFDOC (AMOD, "Remainder (archaic).", ARCHAIC (MOD, Mod))
 372
 373 DEFDOC (DMOD, "Remainder (archaic).", ARCHAIC (MOD, Mod))
 374
 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@}.
 378 ")
 379
 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@}.
 383 ")
 384
 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@}.
 388 ")
 389
 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@}.
 393 ")
 394
 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@}.
 398 ")
 399
 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@}.
 403 ")
 404
 405 DEFDOC (NOT, "Boolean NOT.", "\
 406 Returns value resulting from boolean NOT of each bit
 407 in @var{@1@}.
 408 ")
 409
 410 DEFDOC (ASIN, "Arc sine.", "\
 411 Returns the arc-sine (inverse sine) of @var{@1@}
 412 in radians.
 413
 414 @xref{Sin Intrinsic}, for the inverse of this function.
 415 ")
 416
 417 DEFDOC (DASIN, "Arc sine (archaic).", ARCHAIC (ASIN, ASin))
 418
 419 DEFDOC (ATAN, "Arc tangent.", "\
 420 Returns the arc-tangent (inverse tangent) of @var{@1@}
 421 in radians.
 422
 423 @xref{Tan Intrinsic}, for the inverse of this function.
 424 ")
 425
 426 DEFDOC (DATAN, "Arc tangent (archaic).", ARCHAIC (ATAN, ATan))
 427
 428 DEFDOC (ATAN2, "Arc tangent.", "\
 429 Returns the arc-tangent (inverse tangent) of the complex
 430 number (@var{@1@}, @var{@2@}) in radians.
 431
 432 @xref{Tan Intrinsic}, for the inverse of this function.
 433 ")
 434
 435 DEFDOC (DATAN2, "Arc tangent (archaic).", ARCHAIC_2 (ATAN2, ATan2))
 436
 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@}.
 440
 441 @xref{BTest Intrinsic}, for how to test the value of a
 442 bit in a variable or array.
 443
 444 @xref{IBSet Intrinsic}, for how to set a bit in a variable to 1.
 445
 446 @xref{IBClr Intrinsic}, for how to set a bit in a variable to 0.
 447
 448 ")
 449
 450 DEFDOC (BTEST, "Test bit.", "\
 451 Returns @code{.TRUE.} if bit @var{@2@} in @var{@1@} is
 452 1, @code{.FALSE.} otherwise.
 453
 454 (Bit 0 is the low-order (rightmost) bit, adding the value
 455 @ifinfo
 456 2**0,
 457 @end ifinfo
 458 @iftex
 459 @tex
 460 $2^0$,
 461 @end tex
 462 @end iftex
 463 or 1,
 464 to the number if set to 1;
 465 bit 1 is the next-higher-order bit, adding
 466 @ifinfo
 467 2**1,
 468 @end ifinfo
 469 @iftex
 470 @tex
 471 $2^1$,
 472 @end tex
 473 @end iftex
 474 or 2;
 475 bit 2 adds
 476 @ifinfo
 477 2**2,
 478 @end ifinfo
 479 @iftex
 480 @tex
 481 $2^2$,
 482 @end tex
 483 @end iftex
 484 or 4; and so on.)
 485
 486 @xref{Bit_Size Intrinsic}, for how to obtain the number of bits
 487 in a type.
 488 The leftmost bit of @var{@1@} is @samp{BIT_SIZE(@var{@1@}-1)}.
 489 ")
 490
 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.
 497
 498 If @var{@1@} is type @code{COMPLEX},
 499 converts it to type @code{COMPLEX(KIND=1)}.
 500
 501 @xref{Complex Intrinsic}, for information on easily constructing
 502 a @code{COMPLEX} value of arbitrary precision from @code{REAL}
 503 arguments.
 504 ")
 505
 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.
 512
 513 If @var{@1@} is type @code{COMPLEX},
 514 converts it to type @code{COMPLEX(KIND=2)}.
 515
 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).
 522
 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}
 527 result.
 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
 533 reducing precision.
 534 GNU Fortran provides such an intrinsic, called @code{COMPLEX()}.)
 535
 536 @xref{Complex Intrinsic}, for information on easily constructing
 537 a @code{COMPLEX} value of arbitrary precision from @code{REAL}
 538 arguments.
 539 ")
 540
 541 DEFDOC (CONJG, "Complex conjugate.", "\
 542 Returns the complex conjugate:
 543
 544 @example
 545 COMPLEX(REALPART(@var{@1@}), -IMAGPART(@var{@1@}))
 546 @end example
 547 ")
 548
 549 DEFDOC (DCONJG, "Complex conjugate (archaic).", ARCHAIC (CONJG, Conjg))
 550
 551 DEFDOC (COS, "Cosine.", "\
 552 Returns the cosine of @var{@1@}, an angle measured
 553 in radians.
 554
 555 @xref{ACos Intrinsic}, for the inverse of this function.
 556 ")
 557
 558 DEFDOC (CCOS, "Cosine (archaic).", ARCHAIC (COS, Cos))
 559
 560 DEFDOC (DCOS, "Cosine (archaic).", ARCHAIC (COS, Cos))
 561
 562 DEFDOC (CDCOS, "Cosine (archaic).", ARCHAIC (COS, Cos))
 563
 564 DEFDOC (COSH, "Hyperbolic cosine.", "\
 565 Returns the hyperbolic cosine of @var{@1@}.
 566 ")
 567
 568 DEFDOC (DCOSH, "Hyperbolic cosine (archaic).", ARCHAIC (COSH, CosH))
 569
 570 DEFDOC (SQRT, "Square root.", "\
 571 Returns the square root of @var{@1@}, which must
 572 not be negative.
 573
 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@}))}.
 577
 578 The inverse of this function is @samp{SQRT(@var{@1@}) * SQRT(@var{@1@})}.
 579 ")
 580
 581 DEFDOC (CSQRT, "Square root (archaic).", ARCHAIC (SQRT, SqRt))
 582
 583 DEFDOC (DSQRT, "Square root (archaic).", ARCHAIC (SQRT, SqRt))
 584
 585 DEFDOC (CDSQRT, "Square root (archaic).", ARCHAIC (SQRT, SqRt))
 586
 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.
 593
 594 @xref{Sngl Intrinsic}, for the function that converts
 595 to single precision.
 596
 597 @xref{Int Intrinsic}, for the function that converts
 598 to @code{INTEGER}.
 599
 600 @xref{Complex Intrinsic}, for the function that converts
 601 to @code{COMPLEX}.
 602 ")
 603
 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.
 607 ")
 608
 609 DEFDOC (DDIM, "Difference magnitude (archaic).", ARCHAIC_2 (DIM, DiM))
 610 DEFDOC (IDIM, "Difference magnitude (archaic).", ARCHAIC_2 (DIM, DiM))
 611
 612 DEFDOC (DPROD, "Double-precision product.", "\
 613 Returns @samp{DBLE(@var{@1@})*DBLE(@var{@2@})}.
 614 ")
 615
 616 DEFDOC (EXP, "Exponential.", "\
 617 Returns @samp{@var{e}**@var{@1@}}, where
 618 @var{e} is approximately 2.7182818.
 619
 620 @xref{Log Intrinsic}, for the inverse of this function.
 621 ")
 622
 623 DEFDOC (CEXP, "Exponential (archaic).", ARCHAIC (EXP, Exp))
 624
 625 DEFDOC (DEXP, "Exponential (archaic).", ARCHAIC (EXP, Exp))
 626
 627 DEFDOC (CDEXP, "Exponential (archaic).", ARCHAIC (EXP, Exp))
 628
 629 DEFDOC (FLOAT, "Conversion (archaic).", ARCHAIC (REAL, Real))
 630 DEFDOC (DFLOAT, "Conversion (archaic).", ARCHAIC (REAL, Real))
 631
 632 DEFDOC (IFIX, "Conversion (archaic).", ARCHAIC (INT, Int))
 633
 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}.
 638
 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.
 642 ")
 643
 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)}.
 648
 649 If @var{@1@} is type @code{COMPLEX}, its real part
 650 is truncated and converted, and its imaginary part is disgregarded.
 651
 652 @xref{Int Intrinsic}.
 653
 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.
 657 ")
 658
 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)}.
 663
 664 If @var{@1@} is type @code{COMPLEX}, its real part
 665 is truncated and converted, and its imaginary part is disgregarded.
 666
 667 @xref{Int Intrinsic}.
 668
 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.
 672 ")
 673
 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)}.
 678
 679 If @var{@1@} is type @code{COMPLEX}, its real part
 680 is truncated and converted, and its imaginary part is disgregarded.
 681
 682 @xref{Int Intrinsic}.
 683
 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.
 687 ")
 688
 689 DEFDOC (LEN, "Length of character entity.", "\
 690 Returns the length of @var{@1@}.
 691
 692 If @var{@1@} is an array, the length of an element
 693 of @var{@1@} is returned.
 694
 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.
 698
 699 @xref{Bit_Size Intrinsic}, for the function that determines
 700 the size of its argument in bits.
 701 ")
 702
 703 DEFDOC (TAN, "Tangent.", "\
 704 Returns the tangent of @var{@1@}, an angle measured
 705 in radians.
 706
 707 @xref{ATan Intrinsic}, for the inverse of this function.
 708 ")
 709
 710 DEFDOC (DTAN, "Tangent (archaic).", ARCHAIC (TAN, Tan))
 711
 712 DEFDOC (TANH, "Hyperbolic tangent.", "\
 713 Returns the hyperbolic tangent of @var{@1@}.
 714 ")
 715
 716 DEFDOC (DTANH, "Hyperbolic tangent (archaic).", ARCHAIC (TANH, TanH))
 717
 718 DEFDOC (SNGL, "Convert (archaic).", ARCHAIC (REAL, Real))
 719
 720 DEFDOC (SIN, "Sine.", "\
 721 Returns the sine of @var{@1@}, an angle measured
 722 in radians.
 723
 724 @xref{ASin Intrinsic}, for the inverse of this function.
 725 ")
 726
 727 DEFDOC (CSIN, "Sine (archaic).", ARCHAIC (SIN, Sin))
 728
 729 DEFDOC (DSIN, "Sine (archaic).", ARCHAIC (SIN, Sin))
 730
 731 DEFDOC (CDSIN, "Sine (archaic).", ARCHAIC (SIN, Sin))
 732
 733 DEFDOC (SINH, "Hyperbolic sine.", "\
 734 Returns the hyperbolic sine of @var{@1@}.
 735 ")
 736
 737 DEFDOC (DSINH, "Hyperbolic sine (archaic).", ARCHAIC (SINH, SinH))
 738
 739 DEFDOC (LSHIFT, "Left-shift bits.", "\
 740 Returns @var{@1@} shifted to the left
 741 @var{@2@} bits.
 742
 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
 748 @var{@1@}.
 749
 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.
 756
 757 @xref{LShift Intrinsic}, for the inverse of this function.
 758
 759 @xref{IShft Intrinsic}, for information
 760 on a more widely available left-shifting
 761 intrinsic that is also more precisely defined.
 762 ")
 763
 764 DEFDOC (RSHIFT, "Right-shift bits.", "\
 765 Returns @var{@1@} shifted to the right
 766 @var{@2@} bits.
 767
 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
 772 undefined.
 773
 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.
 780
 781 @xref{RShift Intrinsic}, for the inverse of this function.
 782
 783 @xref{IShft Intrinsic}, for information
 784 on a more widely available right-shifting
 785 intrinsic that is also more precisely defined.
 786 ")
 787
 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.
 795
 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.
 799
 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.}:
 806
 807 @smallexample
 808 LGE ('0', ' ')
 809 LGE ('A', '0')
 810 LGE ('a', 'A')
 811 @end smallexample
 812
 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:
 816
 817 @smallexample
 818 '0' .GE. ' '
 819 'A' .GE. '0'
 820 'a' .GE. 'A'
 821 @end smallexample
 822
 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.}.
 827 ")
 828
 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.
 836
 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.
 840
 841 @xref{LGe Intrinsic}, for information on the distinction
 842 between the @code{@0@} intrinsic and the @code{.GT.}
 843 operator.
 844 ")
 845
 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.
 853
 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.
 857
 858 @xref{LGe Intrinsic}, for information on the distinction
 859 between the @code{@0@} intrinsic and the @code{.LE.}
 860 operator.
 861 ")
 862
 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.
 870
 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.
 874
 875 @xref{LGe Intrinsic}, for information on the distinction
 876 between the @code{@0@} intrinsic and the @code{.LT.}
 877 operator.
 878 ")
 879
 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},
 883 -1 otherwise.
 884
 885 @xref{Abs Intrinsic}, for the function that returns
 886 the magnitude of a value.
 887 ")
 888
 889 DEFDOC (DSIGN, "Apply sign to magnitude (archaic).", ARCHAIC_2 (SIGN, Sign))
 890 DEFDOC (ISIGN, "Apply sign to magnitude (archaic).", ARCHAIC_2 (SIGN, Sign))
 891
 892 DEFDOC (REAL, "Convert value to type @code{REAL(KIND=1)}.", "\
 893 Converts @var{@1@} to @code{REAL(KIND=1)}.
 894
 895 Use of @code{@0@()} with a @code{COMPLEX} argument
 896 (other than @code{COMPLEX(KIND=1)}) is restricted to the following case:
 897
 898 @example
 899 REAL(REAL(@1@))
 900 @end example
 901
 902 @noindent
 903 This expression converts the real part of @1@ to
 904 @code{REAL(KIND=1)}.
 905
 906 @xref{RealPart Intrinsic}, for information on a GNU Fortran
 907 intrinsic that extracts the real part of an arbitrary
 908 @code{COMPLEX} value.
 909
 910 @xref{REAL() and AIMAG() of Complex}, for more information.
 911 ")
 912
 913 DEFDOC (DREAL, "Convert value to type @code{REAL(KIND=2)}.", "\
 914 Converts @var{@1@} to @code{REAL(KIND=2)}.
 915
 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.
 919
 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.
 928
 929 @xref{RealPart Intrinsic}, for information on a GNU Fortran
 930 intrinsic that avoids these areas of confusion.
 931
 932 @xref{Dble Intrinsic}, for information on the standard FORTRAN 77
 933 replacement for @code{DREAL()}.
 934
 935 @xref{REAL() and AIMAG() of Complex}, for more information on
 936 this issue.
 937 ")
 938
 939 DEFDOC (IMAGPART, "Extract imaginary part of complex.", "\
 940 The imaginary part of @var{@1@} is returned, without conversion.
 941
 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)}).
 949
 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.
 954
 955 @xref{REAL() and AIMAG() of Complex}, for more information.
 956 ")
 957
 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.
 961
 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@}.
 966
 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.
 972
 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)}.
 976
 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.
 982 ")
 983
 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
 988 more information.
 989 ")
 990
 991 DEFDOC (REALPART, "Extract real part of complex.", "\
 992 The real part of @var{@1@} is returned, without conversion.
 993
 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)}).
1001
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.
1006
1007 @xref{REAL() and AIMAG() of Complex}, for more information.
1008 ")
1009
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).
1015
1016 @xref{IArgC Intrinsic}, for information on how to get the number
1017 of arguments.
1018 ")
1019
1020 DEFDOC (ABORT, "Abort the program.", "\
1021 Prints a message and potentially causes a core dump via @code{abort(3)}.
1022 ")
1023
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.
1029 ")
1030
1031 DEFDOC (IARGC, "Obtain count of command-line arguments.", "\
1032 Returns the number of command-line arguments.
1033
1034 This count does not include the specification of the program
1035 name itself.
1036 ")
1037
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.
1042
1043 @xref{Time8 Intrinsic}.
1044 ")
1045
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@}.
1050
1051 @xref{Time8 Intrinsic}.
1052
1053 Some non-GNU implementations of Fortran provide this intrinsic as
1054 only a function, not as a subroutine.
1055 ")
1056
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}.
1062
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.
1066 ")
1067
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)}.
1075
1076 Subsequent invocations of @samp{@0@()} return values accumulated since the
1077 previous invocation.
1078
1079 Due to the side effects performed by this intrinsic, the function
1080 form is not recommended.
1081 ")
1082
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
1086 in @var{@1@},
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)}.
1090
1091 Subsequent invocations of @samp{@0@()} set values based on accumulations
1092 since the previous invocation.
1093
1094 Some non-GNU implementations of Fortran provide this intrinsic as
1095 only a function, not as a subroutine.
1096 ")
1097
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)}.
1105 ")
1106
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
1110 in @var{@1@},
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)}.
1114
1115 Some non-GNU implementations of Fortran provide this intrinsic as
1116 only a function, not as a subroutine.
1117 ")
1118
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()}).
1121
1122 Equivalent to:
1123
1124 @example
1125 CTIME(TIME8())
1126 @end example
1127
1128 @xref{CTime Intrinsic (function)}.
1129 ")
1130
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()})
1133 in @var{@1@}.
1134
1135 Equivalent to:
1136
1137 @example
1138 CALL CTIME(@var{@1@}, TIME8())
1139 @end example
1140
1141 @xref{CTime Intrinsic (subroutine)}.
1142
1143 Some non-GNU implementations of Fortran provide this intrinsic as
1144 only a function, not as a subroutine.
1145 ")
1146
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
1150 @code{gmtime(3)}.
1151
1152 The array elements are as follows:
1153
1154 @enumerate
1155 @item
1156 Seconds after the minute, range 0--59 or 0--61 to allow for leap
1157 seconds
1158
1159 @item
1160 Minutes after the hour, range 0--59
1161
1162 @item
1163 Hours past midnight, range 0--23
1164
1165 @item
1166 Day of month, range 0--31
1167
1168 @item
1169 Number of months since January, range 0--12
1170
1171 @item
1172 Years since 1900
1173
1174 @item
1175 Number of days since Sunday, range 0--6
1176
1177 @item
1178 Days since January 1
1179
1180 @item
1181 Daylight savings indicator: positive if daylight savings is in effect,
1182 zero if not, and negative if the information isn't available.
1183 @end enumerate
1184 ")
1185
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)}.
1190
1191 The array elements are as follows:
1192
1193 @enumerate
1194 @item
1195 Seconds after the minute, range 0--59 or 0--61 to allow for leap
1196 seconds
1197
1198 @item
1199 Minutes after the hour, range 0--59
1200
1201 @item
1202 Hours past midnight, range 0--23
1203
1204 @item
1205 Day of month, range 0--31
1206
1207 @item
1208 Number of months since January, range 0--12
1209
1210 @item
1211 Years since 1900
1212
1213 @item
1214 Number of days since Sunday, range 0--6
1215
1216 @item
1217 Days since January 1
1218
1219 @item
1220 Daylight savings indicator: positive if daylight savings is in effect,
1221 zero if not, and negative if the information isn't available.
1222 @end enumerate
1223 ")
1224
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,
1228 respectively.
1229 The year has four significant digits.
1230 ")
1231
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).
1237
1238 This intrinsic is not recommended, due to the year 2000 approaching.
1239 ")
1240
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.
1244 ")
1245
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.).
1249
1250 This intrinsic is not fully portable, such as to systems
1251 with 32-bit @code{INTEGER} types but supporting times
1252 wider than 32 bits.
1253 @xref{MClock8 Intrinsic}, for information on a
1254 similar intrinsic that might be portable to more
1255 GNU Fortran implementations, though to fewer
1256 Fortran compilers.
1257
1258 If the system does not support @code{clock(3)},
1259 -1 is returned.
1260 ")
1261
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.).
1265
1266 No Fortran implementations other than GNU Fortran are
1267 known to support this intrinsic at the time of this
1268 writing.
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.
1272
1273 If the system does not support @code{clock(3)},
1274 -1 is returned.
1275 ")
1276
1277 DEFDOC (SECNDS, "Get local time offset since midnight.", "\
1278 Returns the local time in seconds since midnight minus the value
1279 @var{@1@}.
1280 ")
1281
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.
1285 ")
1286
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.
1290
1291 This routine is known from Cray Fortran.  @xref{CPU_Time Intrinsic}
1292 for a standard equivalent.
1293 ")
1294
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
1299 isn't in general.
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
1303 int} value.
1304 ")
1305
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)}.
1310 ")
1311
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}.
1317
1318 No Fortran implementations other than GNU Fortran are
1319 known to support this intrinsic at the time of this
1320 writing.
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.
1324 ")
1325
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}.
1331
1332 This intrinsic is not fully portable, such as to systems
1333 with 32-bit @code{INTEGER} types but supporting times
1334 wider than 32 bits.
1335 @xref{Time8 Intrinsic}, for information on a
1336 similar intrinsic that might be portable to more
1337 GNU Fortran implementations, though to fewer
1338 Fortran compilers.
1339 ")
1340
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 \
1345 function depends.\
1346 "
1347
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))
1360
1361 DEFDOC (ERF, "Error function.", "\
1362 Returns the error function of @var{@1@}.
1363 See @code{erf(3m)}, which provides the implementation.
1364 ")
1365
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.
1371 ")
1372
1373 DEFDOC (DERF, "Error function (archaic).", ARCHAIC (ERF, ErF))
1374 DEFDOC (DERFC, "Complementary error function (archaic).", ARCHAIC (ERFC, ErFC))
1375
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()}.
1382
1383 @xref{SRand Intrinsic}.
1384
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.
1390 ")
1391
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
1397 @code{srand}.
1398
1399 @xref{SRand Intrinsic}.
1400
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.
1407 ")
1408
1409 DEFDOC (SRAND, "Random seed.", "\
1410 Reinitialises the generator with the seed in @var{@1@}.
1411 @xref{IRand Intrinsic}.
1412 @xref{Rand Intrinsic}.
1413 ")
1414
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:
1424
1425 @table @samp
1426 @item r
1427 Read permission
1428
1429 @item w
1430 Write permission
1431
1432 @item x
1433 Execute permission
1434
1435 @item @kbd{SPC}
1436 Existence
1437 @end table
1438 ")
1439
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)}.
1445
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.
1449
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.
1453 ")
1454
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)}.
1459
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.
1463
1464 Due to the side effects performed by this intrinsic, the function
1465 form is not recommended.
1466 ")
1467
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
1471 @code{chmod(1)}.
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
1476 character.
1477
1478 Returns 0 on success or a non-zero error code otherwise.
1479
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.
1484
1485 Due to the side effects performed by this intrinsic, the function
1486 form is not recommended.
1487 ")
1488
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
1492 @code{chmod(1)}.
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
1497 character.
1498
1499 If the @var{@3@} argument is supplied, it contains
1500 0 on success or a non-zero error code upon return.
1501
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.
1506
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.
1510 ")
1511
1512 DEFDOC (GETCWD_func, "Get current working directory.", "\
1513 Places the current working directory in @var{@1@}.
1514 Returns 0 on
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)}).
1518 ")
1519
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)}).
1526
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.
1530 ")
1531
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:
1538
1539 @enumerate
1540 @item
1541 File mode
1542
1543 @item
1544 Inode number
1545
1546 @item
1547 ID of device containing directory entry for file
1548
1549 @item
1550 Device id (if relevant)
1551
1552 @item
1553 Number of links
1554
1555 @item
1556 Owner's uid
1557
1558 @item
1559 Owner's gid
1560
1561 @item
1562 File size (bytes)
1563
1564 @item
1565 Last access time
1566
1567 @item
1568 Last modification time
1569
1570 @item
1571 Last file status change time
1572
1573 @item
1574 Preferred I/O block size
1575
1576 @item
1577 Number of blocks allocated
1578 @end enumerate
1579
1580 Not all these elements are relevant on all systems.
1581 If an element is not relevant, it is returned as 0.
1582
1583 Returns 0 on success or a non-zero error code.
1584 ")
1585
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:
1592
1593 @enumerate
1594 @item
1595 File mode
1596
1597 @item
1598 Inode number
1599
1600 @item
1601 ID of device containing directory entry for file
1602
1603 @item
1604 Device id (if relevant)
1605
1606 @item
1607 Number of links
1608
1609 @item
1610 Owner's uid
1611
1612 @item
1613 Owner's gid
1614
1615 @item
1616 File size (bytes)
1617
1618 @item
1619 Last access time
1620
1621 @item
1622 Last modification time
1623
1624 @item
1625 Last file status change time
1626
1627 @item
1628 Preferred I/O block size
1629
1630 @item
1631 Number of blocks allocated
1632 @end enumerate
1633
1634 Not all these elements are relevant on all systems.
1635 If an element is not relevant, it is returned as 0.
1636
1637 If the @var{@3@} argument is supplied, it contains
1638 0 on success or a non-zero error code upon return.
1639
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.
1643 ")
1644
1645 DEFDOC (LSTAT_func, "Get file information.", "\
1646 Obtains data about the given file @var{@1@} and places them in the array
1647 @var{@2@}.
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
1653 symbolic links.
1654 The values in this array are extracted from the
1655 @code{stat} structure as returned by @code{fstat(2)} q.v., as follows:
1656
1657 @enumerate
1658 @item
1659 File mode
1660
1661 @item
1662 Inode number
1663
1664 @item
1665 ID of device containing directory entry for file
1666
1667 @item
1668 Device id (if relevant)
1669
1670 @item
1671 Number of links
1672
1673 @item
1674 Owner's uid
1675
1676 @item
1677 Owner's gid
1678
1679 @item
1680 File size (bytes)
1681
1682 @item
1683 Last access time
1684
1685 @item
1686 Last modification time
1687
1688 @item
1689 Last file status change time
1690
1691 @item
1692 Preferred I/O block size
1693
1694 @item
1695 Number of blocks allocated
1696 @end enumerate
1697
1698 Not all these elements are relevant on all systems.
1699 If an element is not relevant, it is returned as 0.
1700
1701 Returns 0 on success or a non-zero error code
1702 (@code{ENOSYS} if the system does not provide @code{lstat(2)}).
1703 ")
1704
1705 DEFDOC (LSTAT_subr, "Get file information.", "\
1706 Obtains data about the given file @var{@1@} and places them in the array
1707 @var{@2@}.
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
1713 symbolic links.
1714 The values in this array are extracted from the
1715 @code{stat} structure as returned by @code{fstat(2)} q.v., as follows:
1716
1717 @enumerate
1718 @item
1719 File mode
1720
1721 @item
1722 Inode number
1723
1724 @item
1725 ID of device containing directory entry for file
1726
1727 @item
1728 Device id (if relevant)
1729
1730 @item
1731 Number of links
1732
1733 @item
1734 Owner's uid
1735
1736 @item
1737 Owner's gid
1738
1739 @item
1740 File size (bytes)
1741
1742 @item
1743 Last access time
1744
1745 @item
1746 Last modification time
1747
1748 @item
1749 Last file status change time
1750
1751 @item
1752 Preferred I/O block size
1753
1754 @item
1755 Number of blocks allocated
1756 @end enumerate
1757
1758 Not all these elements are relevant on all systems.
1759 If an element is not relevant, it is returned as 0.
1760
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)}).
1764
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.
1768 ")
1769
1770 DEFDOC (STAT_func, "Get file information.", "\
1771 Obtains data about the given file @var{@1@} and places them in the array
1772 @var{@2@}.
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:
1778
1779 @enumerate
1780 @item
1781 File mode
1782
1783 @item
1784 Inode number
1785
1786 @item
1787 ID of device containing directory entry for file
1788
1789 @item
1790 Device id (if relevant)
1791
1792 @item
1793 Number of links
1794
1795 @item
1796 Owner's uid
1797
1798 @item
1799 Owner's gid
1800
1801 @item
1802 File size (bytes)
1803
1804 @item
1805 Last access time
1806
1807 @item
1808 Last modification time
1809
1810 @item
1811 Last file status change time
1812
1813 @item
1814 Preferred I/O block size
1815
1816 @item
1817 Number of blocks allocated
1818 @end enumerate
1819
1820 Not all these elements are relevant on all systems.
1821 If an element is not relevant, it is returned as 0.
1822
1823 Returns 0 on success or a non-zero error code.
1824 ")
1825
1826 DEFDOC (STAT_subr, "Get file information.", "\
1827 Obtains data about the given file @var{@1@} and places them in the array
1828 @var{@2@}.
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:
1834
1835 @enumerate
1836 @item
1837 File mode
1838
1839 @item
1840 Inode number
1841
1842 @item
1843 ID of device containing directory entry for file
1844
1845 @item
1846 Device id (if relevant)
1847
1848 @item
1849 Number of links
1850
1851 @item
1852 Owner's uid
1853
1854 @item
1855 Owner's gid
1856
1857 @item
1858 File size (bytes)
1859
1860 @item
1861 Last access time
1862
1863 @item
1864 Last modification time
1865
1866 @item
1867 Last file status change time
1868
1869 @item
1870 Preferred I/O block size
1871
1872 @item
1873 Number of blocks allocated
1874 @end enumerate
1875
1876 Not all these elements are relevant on all systems.
1877 If an element is not relevant, it is returned as 0.
1878
1879 If the @var{@3@} argument is supplied, it contains
1880 0 on success or a non-zero error code upon return.
1881
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.
1885 ")
1886
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.
1894 See @code{link(2)}.
1895
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.
1899 ")
1900
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.
1907 See @code{link(2)}.
1908
1909 Due to the side effects performed by this intrinsic, the function
1910 form is not recommended.
1911 ")
1912
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)}).
1921
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.
1925 ")
1926
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)}).
1934
1935 Due to the side effects performed by this intrinsic, the function
1936 form is not recommended.
1937 ")
1938
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.
1947
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.
1951 ")
1952
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.
1960
1961 Due to the side effects performed by this intrinsic, the function
1962 form is not recommended.
1963 ")
1964
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)}.
1969
1970 Some non-GNU implementations of Fortran provide this intrinsic as
1971 only a function, not as a subroutine.
1972 ")
1973
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)}.
1977
1978 Due to the side effects performed by this intrinsic, the function
1979 form is not recommended.
1980 ")
1981
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)}.
1990
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.
1994 ")
1995
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)}.
2003
2004 Due to the side effects performed by this intrinsic, the function
2005 form is not recommended.
2006 ")
2007
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}).
2011 ")
2012
2013 DEFDOC (IERRNO, "Get error number for last error.", "\
2014 Returns the last system error number (corresponding to the C
2015 @code{errno}).
2016 ")
2017
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)}.
2023 ")
2024
2025 DEFDOC (GETGID, "Get process group id.", "\
2026 Returns the group id for the current process.
2027 ")
2028
2029 DEFDOC (GETUID, "Get process user id.", "\
2030 Returns the user id for the current process.
2031 ")
2032
2033 DEFDOC (GETPID, "Get process id.", "\
2034 Returns the process id for the current process.
2035 ")
2036
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.
2044 ")
2045
2046 DEFDOC (GETLOG, "Get login name.", "\
2047 Returns the login name for the process in @var{@1@}.
2048
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
2053 in @var{@1@}.
2054 ")
2055
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)}).
2060
2061 On some systems (specifically SCO) it may be necessary to link the
2062 ``socket'' library if you call this routine.
2063 Typically this means adding @samp{-lg2c -lsocket -lm}
2064 to the @code{g77} command line when linking the program.
2065 ")
2066
2067 DEFDOC (HOSTNM_subr, "Get host name.", "\
2068 Fills @var{@1@} with the system's host name returned by
2069 @code{gethostname(2)}.
2070 If the @var{@2@} argument is supplied, it contains
2071 0 on success or a non-zero error code upon return
2072 (@code{ENOSYS} if the system does not provide @code{gethostname(2)}).
2073
2074 Some non-GNU implementations of Fortran provide this intrinsic as
2075 only a function, not as a subroutine, or do not support the
2076 (optional) @var{@2@} argument.
2077
2078 On some systems (specifically SCO) it may be necessary to link the
2079 ``socket'' library if you call this routine.
2080 Typically this means adding @samp{-lg2c -lsocket -lm}
2081 to the @code{g77} command line when linking the program.
2082 ")
2083
2084 DEFDOC (FLUSH, "Flush buffered output.", "\
2085 Flushes Fortran unit(s) currently open for output.
2086 Without the optional argument, all such units are flushed,
2087 otherwise just the unit specified by @var{@1@}.
2088
2089 Some non-GNU implementations of Fortran provide this intrinsic
2090 as a library procedure that might or might not support the
2091 (optional) @var{@1@} argument.
2092 ")
2093
2094 DEFDOC (FNUM, "Get file descriptor from Fortran unit number.", "\
2095 Returns the Unix file descriptor number corresponding to the open
2096 Fortran I/O unit @var{@1@}.
2097 This could be passed to an interface to C I/O routines.
2098 ")
2099
2100 #define IOWARN "
2101 Stream I/O should not be mixed with normal record-oriented (formatted or
2102 unformatted) I/O on the same unit; the results are unpredictable.
2103 "
2104
2105 DEFDOC (FGET_func, "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 input) using @code{getc(3)}.
2108 Returns 0 on
2109 success, @minus{}1 on end-of-file, and the error code from
2110 @code{ferror(3)} otherwise.
2111 " IOWARN)
2112
2113 DEFDOC (FGET_subr, "Read a character from unit 5 stream-wise.", "\
2114 Reads a single character into @var{@1@} in stream mode from unit 5
2115 (by-passing normal formatted output) using @code{getc(3)}.
2116 Returns in
2117 @var{@2@} 0 on success, @minus{}1 on end-of-file, and the error code
2118 from @code{ferror(3)} otherwise.
2119 " IOWARN)
2120
2121 DEFDOC (FGETC_func, "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)}.
2124 Returns 0 on
2125 success, @minus{}1 on end-of-file, and the error code from
2126 @code{ferror(3)} otherwise.
2127 " IOWARN)
2128
2129 DEFDOC (FGETC_subr, "Read a character stream-wise.", "\
2130 Reads a single character into @var{@2@} in stream mode from unit @var{@1@}
2131 (by-passing normal formatted output) using @code{getc(3)}.
2132 Returns in
2133 @var{@3@} 0 on success, @minus{}1 on end-of-file, and the error code from
2134 @code{ferror(3)} otherwise.
2135 " IOWARN)
2136
2137 DEFDOC (FPUT_func, "Write a character to unit 6 stream-wise.", "\
2138 Writes the single character @var{@1@} in stream mode to unit 6
2139 (by-passing normal formatted output) using @code{getc(3)}.
2140 Returns 0 on
2141 success, the error code from @code{ferror(3)} otherwise.
2142 " IOWARN)
2143
2144 DEFDOC (FPUT_subr, "Write a character to unit 6 stream-wise.", "\
2145 Writes the single character @var{@1@} in stream mode to unit 6
2146 (by-passing normal formatted output) using @code{putc(3)}.
2147 Returns in
2148 @var{@2@} 0 on success, the error code from @code{ferror(3)} otherwise.
2149 " IOWARN)
2150
2151 DEFDOC (FPUTC_func, "Write a character stream-wise.", "\
2152 Writes the single character @var{@2@} in stream mode to unit @var{@1@}
2153 (by-passing normal formatted output) using @code{putc(3)}.
2154 Returns 0 on
2155 success, the error code from @code{ferror(3)} otherwise.
2156 " IOWARN)
2157
2158 DEFDOC (FPUTC_subr, "Write a character stream-wise.", "\
2159 Writes the single character @var{@1@} in stream mode to unit 6
2160 (by-passing normal formatted output) using @code{putc(3)}.
2161 Returns in
2162 @var{@2@} 0 on success, the error code from @code{ferror(3)} otherwise.
2163 " IOWARN)
2164
2165 DEFDOC (FSEEK, "Position file (low-level).", "\
2166 Attempts to move Fortran unit @var{@1@} to the specified
2167 @var{@2@}: absolute offset if @var{@3@}=0; relative to the
2168 current offset if @var{@3@}=1; relative to the end of the file if
2169 @var{@3@}=2.
2170 It branches to label @var{@4@} if @var{@1@} is
2171 not open or if the call otherwise fails.
2172 ")
2173
2174 DEFDOC (FTELL_func, "Get file position (low-level).", "\
2175 Returns the current offset of Fortran unit @var{@1@}
2176 (or @minus{}1 if @var{@1@} is not open).
2177 ")
2178
2179 DEFDOC (FTELL_subr, "Get file position (low-level).", "\
2180 Sets @var{@2@} to the current offset of Fortran unit @var{@1@}
2181 (or to @minus{}1 if @var{@1@} is not open).
2182
2183 Some non-GNU implementations of Fortran provide this intrinsic as
2184 only a function, not as a subroutine.
2185 ")
2186
2187 DEFDOC (ISATTY, "Is unit connected to a terminal?", "\
2188 Returns @code{.TRUE.} if and only if the Fortran I/O unit
2189 specified by @var{@1@} is connected
2190 to a terminal device.
2191 See @code{isatty(3)}.
2192 ")
2193
2194 DEFDOC (TTYNAM_func, "Get name of terminal device for unit.", "\
2195 Returns the name of the terminal device open on logical unit
2196 @var{@1@} or a blank string if @var{@1@} is not connected to a
2197 terminal.
2198 ")
2199
2200 DEFDOC (TTYNAM_subr, "Get name of terminal device for unit.", "\
2201 Sets @var{@1@} to the name of the terminal device open on logical unit
2202 @var{@2@} or a blank string if @var{@2@} is not connected to a
2203 terminal.
2204
2205 Some non-GNU implementations of Fortran provide this intrinsic as
2206 only a function, not as a subroutine.
2207 ")
2208
2209 DEFDOC (SIGNAL_subr, "Muck with signal handling.", "\
2210 If @var{@2@} is a an @code{EXTERNAL} routine, arranges for it to be
2211 invoked with a single integer argument (of system-dependent length)
2212 when signal @var{@1@} occurs.
2213 If @var{@2@} is an integer, it can be
2214 used to turn off handling of signal @var{@1@} or revert to its default
2215 action.
2216 See @code{signal(2)}.
2217
2218 Note that @var{@2@} will be called using C conventions,
2219 so the value of its argument in Fortran terms
2220 Fortran terms is obtained by applying @code{%LOC()} (or @var{LOC()}) to it.
2221
2222 The value returned by @code{signal(2)} is written to @var{@3@}, if
2223 that argument is supplied.
2224 Otherwise the return value is ignored.
2225
2226 Some non-GNU implementations of Fortran provide this intrinsic as
2227 only a function, not as a subroutine, or do not support the
2228 (optional) @var{@3@} argument.
2229
2230 @emph{Warning:} Use of the @code{libf2c} run-time library function
2231 @samp{signal_} directly
2232 (such as via @samp{EXTERNAL SIGNAL})
2233 requires use of the @code{%VAL()} construct
2234 to pass an @code{INTEGER} value
2235 (such as @samp{SIG_IGN} or @samp{SIG_DFL})
2236 for the @var{@2@} argument.
2237
2238 However, while @samp{CALL SIGNAL(@var{signum}, %VAL(SIG_IGN))}
2239 works when @samp{SIGNAL} is treated as an external procedure
2240 (and resolves, at link time, to @code{libf2c}'s @samp{signal_} routine),
2241 this construct is not valid when @samp{SIGNAL} is recognized
2242 as the intrinsic of that name.
2243
2244 Therefore, for maximum portability and reliability,
2245 code such references to the @samp{SIGNAL} facility as follows:
2246
2247 @smallexample
2248 INTRINSIC SIGNAL
2249 @dots{}
2250 CALL SIGNAL(@var{signum}, SIG_IGN)
2251 @end smallexample
2252
2253 @code{g77} will compile such a call correctly,
2254 while other compilers will generally either do so as well
2255 or reject the @samp{INTRINSIC SIGNAL} statement via a diagnostic,
2256 allowing you to take appropriate action.
2257 ")
2258
2259 DEFDOC (SIGNAL_func, "Muck with signal handling.", "\
2260 If @var{@2@} is a an @code{EXTERNAL} routine, arranges for it to be
2261 invoked with a single integer argument (of system-dependent length)
2262 when signal @var{@1@} occurs.
2263 If @var{@2@} is an integer, it can be
2264 used to turn off handling of signal @var{@1@} or revert to its default
2265 action.
2266 See @code{signal(2)}.
2267
2268 Note that @var{@2@} will be called using C conventions,
2269 so the value of its argument in Fortran terms
2270 is obtained by applying @code{%LOC()} (or @var{LOC()}) to it.
2271
2272 The value returned by @code{signal(2)} is returned.
2273
2274 Due to the side effects performed by this intrinsic, the function
2275 form is not recommended.
2276
2277 @emph{Warning:} If the returned value is stored in
2278 an @code{INTEGER(KIND=1)} (default @code{INTEGER}) argument,
2279 truncation of the original return value occurs on some systems
2280 (such as Alphas, which have 64-bit pointers but 32-bit default integers),
2281 with no warning issued by @code{g77} under normal circumstances.
2282
2283 Therefore, the following code fragment might silently fail on
2284 some systems:
2285
2286 @smallexample
2287 INTEGER RTN
2288 EXTERNAL MYHNDL
2289 RTN = SIGNAL(@var{signum}, MYHNDL)
2290 @dots{}
2291 ! Restore original handler:
2292 RTN = SIGNAL(@var{signum}, RTN)
2293 @end smallexample
2294
2295 The reason for the failure is that @samp{RTN} might not hold
2296 all the information on the original handler for the signal,
2297 thus restoring an invalid handler.
2298 This bug could manifest itself as a spurious run-time failure
2299 at an arbitrary point later during the program's execution,
2300 for example.
2301
2302 @emph{Warning:} Use of the @code{libf2c} run-time library function
2303 @samp{signal_} directly
2304 (such as via @samp{EXTERNAL SIGNAL})
2305 requires use of the @code{%VAL()} construct
2306 to pass an @code{INTEGER} value
2307 (such as @samp{SIG_IGN} or @samp{SIG_DFL})
2308 for the @var{@2@} argument.
2309
2310 However, while @samp{RTN = SIGNAL(@var{signum}, %VAL(SIG_IGN))}
2311 works when @samp{SIGNAL} is treated as an external procedure
2312 (and resolves, at link time, to @code{libf2c}'s @samp{signal_} routine),
2313 this construct is not valid when @samp{SIGNAL} is recognized
2314 as the intrinsic of that name.
2315
2316 Therefore, for maximum portability and reliability,
2317 code such references to the @samp{SIGNAL} facility as follows:
2318
2319 @smallexample
2320 INTRINSIC SIGNAL
2321 @dots{}
2322 RTN = SIGNAL(@var{signum}, SIG_IGN)
2323 @end smallexample
2324
2325 @code{g77} will compile such a call correctly,
2326 while other compilers will generally either do so as well
2327 or reject the @samp{INTRINSIC SIGNAL} statement via a diagnostic,
2328 allowing you to take appropriate action.
2329 ")
2330
2331 DEFDOC (KILL_func, "Signal a process.", "\
2332 Sends the signal specified by @var{@2@} to the process @var{@1@}.
2333 Returns 0 on success or a non-zero error code.
2334 See @code{kill(2)}.
2335
2336 Due to the side effects performed by this intrinsic, the function
2337 form is not recommended.
2338 ")
2339
2340 DEFDOC (KILL_subr, "Signal a process.", "\
2341 Sends the signal specified by @var{@2@} to the process @var{@1@}.
2342 If the @var{@3@} argument is supplied, it contains
2343 0 on success or a non-zero error code upon return.
2344 See @code{kill(2)}.
2345
2346 Some non-GNU implementations of Fortran provide this intrinsic as
2347 only a function, not as a subroutine, or do not support the
2348 (optional) @var{@3@} argument.
2349 ")
2350
2351 DEFDOC (LNBLNK, "Get last non-blank character in string.", "\
2352 Returns the index of the last non-blank character in @var{@1@}.
2353 @code{LNBLNK} and @code{LEN_TRIM} are equivalent.
2354 ")
2355
2356 DEFDOC (SLEEP, "Sleep for a specified time.", "\
2357 Causes the process to pause for @var{@1@} seconds.
2358 See @code{sleep(2)}.
2359 ")
2360
2361 DEFDOC (SYSTEM_subr, "Invoke shell (system) command.", "\
2362 Passes the command @var{@1@} to a shell (see @code{system(3)}).
2363 If argument @var{@2@} is present, it contains the value returned by
2364 @code{system(3)}, presumably 0 if the shell command succeeded.
2365 Note that which shell is used to invoke the command is system-dependent
2366 and environment-dependent.
2367
2368 Some non-GNU implementations of Fortran provide this intrinsic as
2369 only a function, not as a subroutine, or do not support the
2370 (optional) @var{@2@} argument.
2371 ")
2372
2373 DEFDOC (SYSTEM_func, "Invoke shell (system) command.", "\
2374 Passes the command @var{@1@} to a shell (see @code{system(3)}).
2375 Returns the value returned by
2376 @code{system(3)}, presumably 0 if the shell command succeeded.
2377 Note that which shell is used to invoke the command is system-dependent
2378 and environment-dependent.
2379
2380 Due to the side effects performed by this intrinsic, the function
2381 form is not recommended.
2382 However, the function form can be valid in cases where the
2383 actual side effects performed by the call are unimportant to
2384 the application.
2385
2386 For example, on a UNIX system, @samp{SAME = SYSTEM('cmp a b')}
2387 does not perform any side effects likely to be important to the
2388 program, so the programmer would not care if the actual system
2389 call (and invocation of @code{cmp}) was optimized away in a situation
2390 where the return value could be determined otherwise, or was not
2391 actually needed (@samp{SAME} not actually referenced after the
2392 sample assignment statement).
2393 ")
2394
2395 DEFDOC (TIME_vxt, "Get the time as a character value.", "\
2396 Returns in @var{@1@} a character representation of the current time as
2397 obtained from @code{ctime(3)}.
2398
2399 @xref{Fdate Intrinsic (subroutine)} for an equivalent routine.
2400 ")
2401
2402 DEFDOC (IBCLR, "Clear a bit.", "\
2403 Returns the value of @var{@1@} with bit @var{@2@} cleared (set to
2404 zero).
2405 @xref{BTest Intrinsic} for information on bit positions.
2406 ")
2407
2408 DEFDOC (IBSET, "Set a bit.", "\
2409 Returns the value of @var{@1@} with bit @var{@2@} set (to one).
2410 @xref{BTest Intrinsic} for information on bit positions.
2411 ")
2412
2413 DEFDOC (IBITS, "Extract a bit subfield of a variable.", "\
2414 Extracts a subfield of length @var{@3@} from @var{@1@}, starting from
2415 bit position @var{@2@} and extending left for @var{@3@} bits.
2416 The result is right-justified and the remaining bits are zeroed.
2417 The value
2418 of @samp{@var{@2@}+@var{@3@}} must be less than or equal to the value
2419 @samp{BIT_SIZE(@var{@1@})}.
2420 @xref{Bit_Size Intrinsic}.
2421 ")
2422
2423 DEFDOC (ISHFT, "Logical bit shift.", "\
2424 All bits representing @var{@1@} are shifted @var{@2@} places.
2425 @samp{@var{@2@}.GT.0} indicates a left shift, @samp{@var{@2@}.EQ.0}
2426 indicates no shift and @samp{@var{@2@}.LT.0} indicates a right shift.
2427 If the absolute value of the shift count is greater than
2428 @samp{BIT_SIZE(@var{@1@})}, the result is undefined.
2429 Bits shifted out from the left end or the right end, as the case may be,
2430 are lost.
2431 Zeros are shifted in from the opposite end.
2432
2433 @xref{IShftC Intrinsic} for the circular-shift equivalent.
2434 ")
2435
2436 DEFDOC (ISHFTC, "Circular bit shift.", "\
2437 The rightmost @var{@3@} bits of the argument @var{@1@}
2438 are shifted circularly @var{@2@}
2439 places, i.e.@: the bits shifted out of one end are shifted into
2440 the opposite end.
2441 No bits are lost.
2442 The unshifted bits of the result are the same as
2443 the unshifted bits of @var{@1@}.
2444 The  absolute value of the argument @var{@2@}
2445 must be less than or equal to @var{@3@}.
2446 The value of @var{@3@} must be greater than or equal to one and less than
2447 or equal to @samp{BIT_SIZE(@var{@1@})}.
2448
2449 @xref{IShft Intrinsic} for the logical shift equivalent.
2450 ")
2451
2452 DEFDOC (MVBITS, "Moving a bit field.", "\
2453 Moves @var{@3@} bits from positions @var{@2@} through
2454 @samp{@var{@2@}+@var{@3@}-1} of @var{@1@} to positions @var{@5@} through
2455 @samp{@var{@2@}+@var{@3@}-1} of @var{@4@}.  The portion of argument
2456 @var{@4@} not affected by the movement of bits is unchanged.  Arguments
2457 @var{@1@} and @var{@4@} are permitted to be the same numeric storage
2458 unit.  The values of @samp{@var{@2@}+@var{@3@}} and
2459 @samp{@var{@5@}+@var{@3@}} must be less than or equal to
2460 @samp{BIT_SIZE(@var{@1@})}.
2461 ")
2462
2463 DEFDOC (INDEX, "Locate a CHARACTER substring.", "\
2464 Returns the position of the start of the first occurrence of string
2465 @var{@2@} as a substring in @var{@1@}, counting from one.
2466 If @var{@2@} doesn't occur in @var{@1@}, zero is returned.
2467 ")
2468
2469 DEFDOC (ALARM, "Execute a routine after a given delay.", "\
2470 Causes external subroutine @var{@2@} to be executed after a delay of
2471 @var{@1@} seconds by using @code{alarm(1)} to set up a signal and
2472 @code{signal(2)} to catch it.
2473 If @var{@3@} is supplied, it will be
2474 returned with the number of seconds remaining until any previously
2475 scheduled alarm was due to be delivered, or zero if there was no
2476 previously scheduled alarm.
2477 @xref{Signal Intrinsic (subroutine)}.
2478 ")
2479
2480 DEFDOC (DATE_AND_TIME, "Get the current date and time.", "\
2481 Returns:
2482 @table @var
2483 @item @1@
2484 The date in the form @var{ccyymmdd}: century, year, month and day;
2485 @item @2@
2486 The time in the form @samp{@var{hhmmss.ss}}: hours, minutes, seconds
2487 and milliseconds;
2488 @item @3@
2489 The difference between local time and UTC (GMT) in the form @var{Shhmm}:
2490 sign, hours and minutes, e.g.@: @samp{-0500} (winter in New York);
2491 @item @4@
2492 The year, month of the year, day of the month, time difference in
2493 minutes from UTC, hour of the day, minutes of the hour and milliseconds
2494 of the second in successive values of the array.
2495 @end table
2496
2497 On systems where a millisecond timer isn't available, the millisecond
2498 value is returned as zero.
2499 ")