1/* Copyright (C) 1997, 1999, 2003 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\ 38to 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\ 43to 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\ 48to one type for @var{@1@} and @var{@2@}.\n\ 49@xref{" #mixed " Intrinsic}.\n" 50 51DEFDOC (ABS, "Absolute value.", "\ 52Returns the absolute value of @var{@1@}. 53 54If @var{@1@} is type @code{COMPLEX}, the absolute 55value is computed as: 56 57@example 58SQRT(REALPART(@var{@1@})**2+IMAGPART(@var{@1@})**2) 59@end example 60 61@noindent 62Otherwise, it is computed by negating @var{@1@} if 63it is negative, or returning @var{@1@}. 64 65@xref{Sign Intrinsic}, for how to explicitly 66compute the positive or negative form of the absolute 67value of an expression. 68") 69 70DEFDOC (CABS, "Absolute value (archaic).", ARCHAIC (ABS, Abs)) 71 72DEFDOC (DABS, "Absolute value (archaic).", ARCHAIC (ABS, Abs)) 73 74DEFDOC (IABS, "Absolute value (archaic).", ARCHAIC (ABS, Abs)) 75 76DEFDOC (CDABS, "Absolute value (archaic).", ARCHAIC (ABS, Abs)) 77 78DEFDOC (ACHAR, "ASCII character from code.", "\ 79Returns the ASCII character corresponding to the 80code specified by @var{@1@}. 81 82@xref{IAChar Intrinsic}, for the inverse of this function. 83 84@xref{Char Intrinsic}, for the function corresponding 85to the system's native character set. 86") 87 88DEFDOC (IACHAR, "ASCII code for character.", "\ 89Returns the code for the ASCII character in the 90first 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 95to the system's native character set. 96") 97 98DEFDOC (CHAR, "Character from code.", "\ 99Returns the character corresponding to the 100code specified by @var{@1@}, using the system's 101native character set. 102 103Because the system's native character set is used, 104the correspondence between character and their codes 105is not necessarily the same between GNU Fortran 106implementations. 107 108Note that no intrinsic exists to convert a numerical 109value to a printable character string. 110For example, there is no intrinsic that, given 111an @code{INTEGER} or @code{REAL} argument with the 112value @samp{154}, returns the @code{CHARACTER} 113result @samp{'154'}. 114 115Instead, you can use internal-file I/O to do this kind 116of conversion. 117For example: 118 119@smallexample 120INTEGER VALUE 121CHARACTER*10 STRING 122VALUE = 154 123WRITE (STRING, '(I10)'), VALUE 124PRINT *, STRING 125END 126@end smallexample 127 128The 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 137to the ASCII character set. 138") 139 140DEFDOC (ICHAR, "Code for character.", "\ 141Returns the code for the character in the 142first character position of @var{@1@}. 143 144Because the system's native character set is used, 145the correspondence between character and their codes 146is not necessarily the same between GNU Fortran 147implementations. 148 149Note that no intrinsic exists to convert a printable 150character string to a numerical value. 151For example, there is no intrinsic that, given 152the @code{CHARACTER} value @samp{'154'}, returns an 153@code{INTEGER} or @code{REAL} value with the value @samp{154}. 154 155Instead, you can use internal-file I/O to do this kind 156of conversion. 157For example: 158 159@smallexample 160INTEGER VALUE 161CHARACTER*10 STRING 162STRING = '154' 163READ (STRING, '(I10)'), VALUE 164PRINT *, VALUE 165END 166@end smallexample 167 168The 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 177to the ASCII character set. 178") 179 180DEFDOC (ACOS, "Arc cosine.", "\ 181Returns the arc-cosine (inverse cosine) of @var{@1@} 182in radians. 183 184@xref{Cos Intrinsic}, for the inverse of this function. 185") 186 187DEFDOC (DACOS, "Arc cosine (archaic).", ARCHAIC (ACOS, ACos)) 188 189DEFDOC (AIMAG, "Convert/extract imaginary part of complex.", "\ 190Returns the (possibly converted) imaginary part of @var{@1@}. 191 192Use of @code{@0@()} with an argument of a type 193other than @code{COMPLEX(KIND=1)} is restricted to the following case: 194 195@example 196REAL(AIMAG(@1@)) 197@end example 198 199@noindent 200This 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 206DEFDOC (DIMAG, "Convert/extract imaginary part of complex (archaic).", ARCHAIC (AIMAG, AImag)) 207 208DEFDOC (AINT, "Truncate to whole number.", "\ 209Returns @var{@1@} with the fractional portion of its 210magnitude truncated and its sign preserved. 211(Also called ``truncation towards zero''.) 212 213@xref{ANInt Intrinsic}, for how to round to nearest 214whole number. 215 216@xref{Int Intrinsic}, for how to truncate and then convert 217number to @code{INTEGER}. 218") 219 220DEFDOC (DINT, "Truncate to whole number (archaic).", ARCHAIC (AINT, AInt)) 221 222DEFDOC (INT, "Convert to @code{INTEGER} value truncated@99@to whole number.", "\ 223Returns @var{@1@} with the fractional portion of its 224magnitude truncated and its sign preserved, converted 225to type @code{INTEGER(KIND=1)}. 226 227If @var{@1@} is type @code{COMPLEX}, its real part is 228truncated and converted, and its imaginary part is disregarded. 229 230@xref{NInt Intrinsic}, for how to convert, rounded to nearest 231whole number. 232 233@xref{AInt Intrinsic}, for how to truncate to whole number 234without converting. 235") 236 237DEFDOC (IDINT, "Convert to @code{INTEGER} value truncated@99@to whole number (archaic).", ARCHAIC (INT, Int)) 238 239DEFDOC (ANINT, "Round to nearest whole number.", "\ 240Returns @var{@1@} with the fractional portion of its 241magnitude eliminated by rounding to the nearest whole 242number and with its sign preserved. 243 244A fractional portion exactly equal to 245@samp{.5} is rounded to the whole number that 246is larger in magnitude. 247(Also called ``Fortran round''.) 248 249@xref{AInt Intrinsic}, for how to truncate to 250whole number. 251 252@xref{NInt Intrinsic}, for how to round and then convert 253number to @code{INTEGER}. 254") 255 256DEFDOC (DNINT, "Round to nearest whole number (archaic).", ARCHAIC (ANINT, ANInt)) 257 258DEFDOC (NINT, "Convert to @code{INTEGER} value rounded@99@to nearest whole number.", "\ 259Returns @var{@1@} with the fractional portion of its 260magnitude eliminated by rounding to the nearest whole 261number and with its sign preserved, converted 262to type @code{INTEGER(KIND=1)}. 263 264If @var{@1@} is type @code{COMPLEX}, its real part is 265rounded and converted. 266 267A fractional portion exactly equal to 268@samp{.5} is rounded to the whole number that 269is larger in magnitude. 270(Also called ``Fortran round''.) 271 272@xref{Int Intrinsic}, for how to convert, truncate to 273whole number. 274 275@xref{ANInt Intrinsic}, for how to round to nearest whole number 276without converting. 277") 278 279DEFDOC (IDNINT, "Convert to @code{INTEGER} value rounded@99@to nearest whole number (archaic).", ARCHAIC (NINT, NInt)) 280 281DEFDOC (LOG, "Natural logarithm.", "\ 282Returns the natural logarithm of @var{@1@}, which must 283be greater than zero or, if type @code{COMPLEX}, must not 284be zero. 285 286@xref{Exp Intrinsic}, for the inverse of this function. 287 288@xref{Log10 Intrinsic}, for the `common' (base-10) logarithm function. 289") 290 291DEFDOC (ALOG, "Natural logarithm (archaic).", ARCHAIC (LOG, Log)) 292 293DEFDOC (CLOG, "Natural logarithm (archaic).", ARCHAIC (LOG, Log)) 294 295DEFDOC (DLOG, "Natural logarithm (archaic).", ARCHAIC (LOG, Log)) 296 297DEFDOC (CDLOG, "Natural logarithm (archaic).", ARCHAIC (LOG, Log)) 298 299DEFDOC (LOG10, "Common logarithm.", "\ 300Returns the common logarithm (base 10) of @var{@1@}, which must 301be greater than zero. 302 303The inverse of this function is @samp{10. ** LOG10(@var{@1@})}. 304 305@xref{Log Intrinsic}, for the natural logarithm function. 306") 307 308DEFDOC (ALOG10, "Common logarithm (archaic).", ARCHAIC (LOG10, Log10)) 309 310DEFDOC (DLOG10, "Common logarithm (archaic).", ARCHAIC (LOG10, Log10)) 311 312DEFDOC (MAX, "Maximum value.", "\ 313Returns the argument with the largest value. 314 315@xref{Min Intrinsic}, for the opposite function. 316") 317 318DEFDOC (AMAX0, "Maximum value (archaic).", "\ 319Archaic form of @code{MAX()} that is specific 320to one type for @var{@1@} and a different return type. 321@xref{Max Intrinsic}. 322") 323 324DEFDOC (AMAX1, "Maximum value (archaic).", ARCHAIC (MAX, Max)) 325 326DEFDOC (DMAX1, "Maximum value (archaic).", ARCHAIC (MAX, Max)) 327 328DEFDOC (MAX0, "Maximum value (archaic).", ARCHAIC (MAX, Max)) 329 330DEFDOC (MAX1, "Maximum value (archaic).", "\ 331Archaic form of @code{MAX()} that is specific 332to one type for @var{@1@} and a different return type. 333@xref{Max Intrinsic}. 334") 335 336DEFDOC (MIN, "Minimum value.", "\ 337Returns the argument with the smallest value. 338 339@xref{Max Intrinsic}, for the opposite function. 340") 341 342DEFDOC (AMIN0, "Minimum value (archaic).", "\ 343Archaic form of @code{MIN()} that is specific 344to one type for @var{@1@} and a different return type. 345@xref{Min Intrinsic}. 346") 347 348DEFDOC (AMIN1, "Minimum value (archaic).", ARCHAIC (MIN, Min)) 349 350DEFDOC (DMIN1, "Minimum value (archaic).", ARCHAIC (MIN, Min)) 351 352DEFDOC (MIN0, "Minimum value (archaic).", ARCHAIC (MIN, Min)) 353 354DEFDOC (MIN1, "Minimum value (archaic).", "\ 355Archaic form of @code{MIN()} that is specific 356to one type for @var{@1@} and a different return type. 357@xref{Min Intrinsic}. 358") 359 360DEFDOC (MOD, "Remainder.", "\ 361Returns remainder calculated as: 362 363@smallexample 364@var{@1@} - (INT(@var{@1@} / @var{@2@}) * @var{@2@}) 365@end smallexample 366 367@var{@2@} must not be zero. 368") 369 370DEFDOC (AMOD, "Remainder (archaic).", ARCHAIC (MOD, Mod)) 371 372DEFDOC (DMOD, "Remainder (archaic).", ARCHAIC (MOD, Mod)) 373 374DEFDOC (AND, "Boolean AND.", "\ 375Returns value resulting from boolean AND of 376pair of bits in each of @var{@1@} and @var{@2@}. 377") 378 379DEFDOC (IAND, "Boolean AND.", "\ 380Returns value resulting from boolean AND of 381pair of bits in each of @var{@1@} and @var{@2@}. 382") 383 384DEFDOC (OR, "Boolean OR.", "\ 385Returns value resulting from boolean OR of 386pair of bits in each of @var{@1@} and @var{@2@}. 387") 388 389DEFDOC (IOR, "Boolean OR.", "\ 390Returns value resulting from boolean OR of 391pair of bits in each of @var{@1@} and @var{@2@}. 392") 393 394DEFDOC (XOR, "Boolean XOR.", "\ 395Returns value resulting from boolean exclusive-OR of 396pair of bits in each of @var{@1@} and @var{@2@}. 397") 398 399DEFDOC (IEOR, "Boolean XOR.", "\ 400Returns value resulting from boolean exclusive-OR of 401pair of bits in each of @var{@1@} and @var{@2@}. 402") 403 404DEFDOC (NOT, "Boolean NOT.", "\ 405Returns value resulting from boolean NOT of each bit 406in @var{@1@}. 407") 408 409DEFDOC (ASIN, "Arc sine.", "\ 410Returns the arc-sine (inverse sine) of @var{@1@} 411in radians. 412 413@xref{Sin Intrinsic}, for the inverse of this function. 414") 415 416DEFDOC (DASIN, "Arc sine (archaic).", ARCHAIC (ASIN, ASin)) 417 418DEFDOC (ATAN, "Arc tangent.", "\ 419Returns the arc-tangent (inverse tangent) of @var{@1@} 420in radians. 421 422@xref{Tan Intrinsic}, for the inverse of this function. 423") 424 425DEFDOC (DATAN, "Arc tangent (archaic).", ARCHAIC (ATAN, ATan)) 426 427DEFDOC (ATAN2, "Arc tangent.", "\ 428Returns the arc-tangent (inverse tangent) of the complex 429number (@var{@1@}, @var{@2@}) in radians. 430 431@xref{Tan Intrinsic}, for the inverse of this function. 432") 433 434DEFDOC (DATAN2, "Arc tangent (archaic).", ARCHAIC_2 (ATAN2, ATan2)) 435 436DEFDOC (BIT_SIZE, "Number of bits in argument's type.", "\ 437Returns the number of bits (integer precision plus sign bit) 438represented by the type for @var{@1@}. 439 440@xref{BTest Intrinsic}, for how to test the value of a 441bit in a variable or array. 442 443@xref{IBSet Intrinsic}, for how to set a bit in a variable to 1. 444 445@xref{IBClr Intrinsic}, for how to set a bit in a variable to 0. 446 447") 448 449DEFDOC (BTEST, "Test bit.", "\ 450Returns @code{.TRUE.} if bit @var{@2@} in @var{@1@} is 4511, @code{.FALSE.} otherwise. 452 453(Bit 0 is the low-order (rightmost) bit, adding the value 454@ifinfo 4552**0, 456@end ifinfo 457@iftex 458@tex 459$2^0$, 460@end tex 461@end iftex 462or 1, 463to the number if set to 1; 464bit 1 is the next-higher-order bit, adding 465@ifinfo 4662**1, 467@end ifinfo 468@iftex 469@tex 470$2^1$, 471@end tex 472@end iftex 473or 2; 474bit 2 adds 475@ifinfo 4762**2, 477@end ifinfo 478@iftex 479@tex 480$2^2$, 481@end tex 482@end iftex 483or 4; and so on.) 484 485@xref{Bit_Size Intrinsic}, for how to obtain the number of bits 486in a type. 487The leftmost bit of @var{@1@} is @samp{BIT_SIZE(@var{@1@}-1)}. 488") 489 490DEFDOC (CMPLX, "Construct @code{COMPLEX(KIND=1)} value.", "\ 491If @var{@1@} is not type @code{COMPLEX}, 492constructs a value of type @code{COMPLEX(KIND=1)} from the 493real and imaginary values specified by @var{@1@} and 494@var{@2@}, respectively. 495If @var{@2@} is omitted, @samp{0.} is assumed. 496 497If @var{@1@} is type @code{COMPLEX}, 498converts it to type @code{COMPLEX(KIND=1)}. 499 500@xref{Complex Intrinsic}, for information on easily constructing 501a @code{COMPLEX} value of arbitrary precision from @code{REAL} 502arguments. 503") 504 505DEFDOC (DCMPLX, "Construct @code{COMPLEX(KIND=2)} value.", "\ 506If @var{@1@} is not type @code{COMPLEX}, 507constructs a value of type @code{COMPLEX(KIND=2)} from the 508real and imaginary values specified by @var{@1@} and 509@var{@2@}, respectively. 510If @var{@2@} is omitted, @samp{0D0} is assumed. 511 512If @var{@1@} is type @code{COMPLEX}, 513converts it to type @code{COMPLEX(KIND=2)}. 514 515Although this intrinsic is not standard Fortran, 516it is a popular extension offered by many compilers 517that support @code{DOUBLE COMPLEX}, since it offers 518the easiest way to convert to @code{DOUBLE COMPLEX} 519without using Fortran 90 features (such as the @samp{KIND=} 520argument to the @code{CMPLX()} intrinsic). 521 522(@samp{CMPLX(0D0, 0D0)} returns a single-precision 523@code{COMPLEX} result, as required by standard FORTRAN 77. 524That's why so many compilers provide @code{DCMPLX()}, since 525@samp{DCMPLX(0D0, 0D0)} returns a @code{DOUBLE COMPLEX} 526result. 527Still, @code{DCMPLX()} converts even @code{REAL*16} arguments 528to their @code{REAL*8} equivalents in most dialects of 529Fortran, so neither it nor @code{CMPLX()} allow easy 530construction of arbitrary-precision values without 531potentially forcing a conversion involving extending or 532reducing precision. 533GNU Fortran provides such an intrinsic, called @code{COMPLEX()}.) 534 535@xref{Complex Intrinsic}, for information on easily constructing 536a @code{COMPLEX} value of arbitrary precision from @code{REAL} 537arguments. 538") 539 540DEFDOC (CONJG, "Complex conjugate.", "\ 541Returns the complex conjugate: 542 543@example 544COMPLEX(REALPART(@var{@1@}), -IMAGPART(@var{@1@})) 545@end example 546") 547 548DEFDOC (DCONJG, "Complex conjugate (archaic).", ARCHAIC (CONJG, Conjg)) 549 550DEFDOC (COS, "Cosine.", "\ 551Returns the cosine of @var{@1@}, an angle measured 552in radians. 553 554@xref{ACos Intrinsic}, for the inverse of this function. 555") 556 557DEFDOC (CCOS, "Cosine (archaic).", ARCHAIC (COS, Cos)) 558 559DEFDOC (DCOS, "Cosine (archaic).", ARCHAIC (COS, Cos)) 560 561DEFDOC (CDCOS, "Cosine (archaic).", ARCHAIC (COS, Cos)) 562 563DEFDOC (COSH, "Hyperbolic cosine.", "\ 564Returns the hyperbolic cosine of @var{@1@}. 565") 566 567DEFDOC (DCOSH, "Hyperbolic cosine (archaic).", ARCHAIC (COSH, CosH)) 568 569DEFDOC (SQRT, "Square root.", "\ 570Returns the square root of @var{@1@}, which must 571not be negative. 572 573To calculate and represent the square root of a negative 574number, complex arithmetic must be used. 575For example, @samp{SQRT(COMPLEX(@var{@1@}))}. 576 577The inverse of this function is @samp{SQRT(@var{@1@}) * SQRT(@var{@1@})}. 578") 579 580DEFDOC (CSQRT, "Square root (archaic).", ARCHAIC (SQRT, SqRt)) 581 582DEFDOC (DSQRT, "Square root (archaic).", ARCHAIC (SQRT, SqRt)) 583 584DEFDOC (CDSQRT, "Square root (archaic).", ARCHAIC (SQRT, SqRt)) 585 586DEFDOC (DBLE, "Convert to double precision.", "\ 587Returns @var{@1@} converted to double precision 588(@code{REAL(KIND=2)}). 589If @var{@1@} is @code{COMPLEX}, the real part of 590@var{@1@} is used for the conversion 591and the imaginary part disregarded. 592 593@xref{Sngl Intrinsic}, for the function that converts 594to single precision. 595 596@xref{Int Intrinsic}, for the function that converts 597to @code{INTEGER}. 598 599@xref{Complex Intrinsic}, for the function that converts 600to @code{COMPLEX}. 601") 602 603DEFDOC (DIM, "Difference magnitude (non-negative subtract).", "\ 604Returns @samp{@var{@1@}-@var{@2@}} if @var{@1@} is greater than 605@var{@2@}; otherwise returns zero. 606") 607 608DEFDOC (DDIM, "Difference magnitude (archaic).", ARCHAIC_2 (DIM, DiM)) 609DEFDOC (IDIM, "Difference magnitude (archaic).", ARCHAIC_2 (DIM, DiM)) 610 611DEFDOC (DPROD, "Double-precision product.", "\ 612Returns @samp{DBLE(@var{@1@})*DBLE(@var{@2@})}. 613") 614 615DEFDOC (EXP, "Exponential.", "\ 616Returns @samp{@var{e}**@var{@1@}}, where 617@var{e} is approximately 2.7182818. 618 619@xref{Log Intrinsic}, for the inverse of this function. 620") 621 622DEFDOC (CEXP, "Exponential (archaic).", ARCHAIC (EXP, Exp)) 623 624DEFDOC (DEXP, "Exponential (archaic).", ARCHAIC (EXP, Exp)) 625 626DEFDOC (CDEXP, "Exponential (archaic).", ARCHAIC (EXP, Exp)) 627 628DEFDOC (FLOAT, "Conversion (archaic).", ARCHAIC (REAL, Real)) 629DEFDOC (DFLOAT, "Conversion (archaic).", ARCHAIC (REAL, Real)) 630 631DEFDOC (IFIX, "Conversion (archaic).", ARCHAIC (INT, Int)) 632 633DEFDOC (LONG, "Conversion to @code{INTEGER(KIND=1)} (archaic).", "\ 634Archaic form of @code{INT()} that is specific 635to one type for @var{@1@}. 636@xref{Int Intrinsic}. 637 638The precise meaning of this intrinsic might change 639in a future version of the GNU Fortran language, 640as more is learned about how it is used. 641") 642 643DEFDOC (SHORT, "Convert to @code{INTEGER(KIND=6)} value@99@truncated to whole number.", "\ 644Returns @var{@1@} with the fractional portion of its 645magnitude truncated and its sign preserved, converted 646to type @code{INTEGER(KIND=6)}. 647 648If @var{@1@} is type @code{COMPLEX}, its real part 649is truncated and converted, and its imaginary part is disregarded. 650 651@xref{Int Intrinsic}. 652 653The precise meaning of this intrinsic might change 654in a future version of the GNU Fortran language, 655as more is learned about how it is used. 656") 657 658DEFDOC (INT2, "Convert to @code{INTEGER(KIND=6)} value@99@truncated to whole number.", "\ 659Returns @var{@1@} with the fractional portion of its 660magnitude truncated and its sign preserved, converted 661to type @code{INTEGER(KIND=6)}. 662 663If @var{@1@} is type @code{COMPLEX}, its real part 664is truncated and converted, and its imaginary part is disregarded. 665 666@xref{Int Intrinsic}. 667 668The precise meaning of this intrinsic might change 669in a future version of the GNU Fortran language, 670as more is learned about how it is used. 671") 672 673DEFDOC (INT8, "Convert to @code{INTEGER(KIND=2)} value@99@truncated to whole number.", "\ 674Returns @var{@1@} with the fractional portion of its 675magnitude truncated and its sign preserved, converted 676to type @code{INTEGER(KIND=2)}. 677 678If @var{@1@} is type @code{COMPLEX}, its real part 679is truncated and converted, and its imaginary part is disregarded. 680 681@xref{Int Intrinsic}. 682 683The precise meaning of this intrinsic might change 684in a future version of the GNU Fortran language, 685as more is learned about how it is used. 686") 687 688DEFDOC (LEN, "Length of character entity.", "\ 689Returns the length of @var{@1@}. 690 691If @var{@1@} is an array, the length of an element 692of @var{@1@} is returned. 693 694Note that @var{@1@} need not be defined when this 695intrinsic is invoked, since only the length, not 696the content, of @var{@1@} is needed. 697 698@xref{Bit_Size Intrinsic}, for the function that determines 699the size of its argument in bits. 700") 701 702DEFDOC (TAN, "Tangent.", "\ 703Returns the tangent of @var{@1@}, an angle measured 704in radians. 705 706@xref{ATan Intrinsic}, for the inverse of this function. 707") 708 709DEFDOC (DTAN, "Tangent (archaic).", ARCHAIC (TAN, Tan)) 710 711DEFDOC (TANH, "Hyperbolic tangent.", "\ 712Returns the hyperbolic tangent of @var{@1@}. 713") 714 715DEFDOC (DTANH, "Hyperbolic tangent (archaic).", ARCHAIC (TANH, TanH)) 716 717DEFDOC (SNGL, "Convert (archaic).", ARCHAIC (REAL, Real)) 718 719DEFDOC (SIN, "Sine.", "\ 720Returns the sine of @var{@1@}, an angle measured 721in radians. 722 723@xref{ASin Intrinsic}, for the inverse of this function. 724") 725 726DEFDOC (CSIN, "Sine (archaic).", ARCHAIC (SIN, Sin)) 727 728DEFDOC (DSIN, "Sine (archaic).", ARCHAIC (SIN, Sin)) 729 730DEFDOC (CDSIN, "Sine (archaic).", ARCHAIC (SIN, Sin)) 731 732DEFDOC (SINH, "Hyperbolic sine.", "\ 733Returns the hyperbolic sine of @var{@1@}. 734") 735 736DEFDOC (DSINH, "Hyperbolic sine (archaic).", ARCHAIC (SINH, SinH)) 737 738DEFDOC (LSHIFT, "Left-shift bits.", "\ 739Returns @var{@1@} shifted to the left 740@var{@2@} bits. 741 742Although similar to the expression 743@samp{@var{@1@}*(2**@var{@2@})}, there 744are important differences. 745For example, the sign of the result is 746not necessarily the same as the sign of 747@var{@1@}. 748 749Currently this intrinsic is defined assuming 750the underlying representation of @var{@1@} 751is as a two's-complement integer. 752It is unclear at this point whether that 753definition will apply when a different 754representation is involved. 755 756@xref{LShift Intrinsic}, for the inverse of this function. 757 758@xref{IShft Intrinsic}, for information 759on a more widely available left-shifting 760intrinsic that is also more precisely defined. 761") 762 763DEFDOC (RSHIFT, "Right-shift bits.", "\ 764Returns @var{@1@} shifted to the right 765@var{@2@} bits. 766 767Although similar to the expression 768@samp{@var{@1@}/(2**@var{@2@})}, there 769are important differences. 770For example, the sign of the result is 771undefined. 772 773Currently this intrinsic is defined assuming 774the underlying representation of @var{@1@} 775is as a two's-complement integer. 776It is unclear at this point whether that 777definition will apply when a different 778representation is involved. 779 780@xref{RShift Intrinsic}, for the inverse of this function. 781 782@xref{IShft Intrinsic}, for information 783on a more widely available right-shifting 784intrinsic that is also more precisely defined. 785") 786 787DEFDOC (LGE, "Lexically greater than or equal.", "\ 788Returns @samp{.TRUE.} if @samp{@var{@1@}.GE.@var{@2@}}, 789@samp{.FALSE.} otherwise. 790@var{@1@} and @var{@2@} are interpreted as containing 791ASCII character codes. 792If either value contains a character not in the ASCII 793character set, the result is processor dependent. 794 795If the @var{@1@} and @var{@2@} are not the same length, 796the shorter is compared as if spaces were appended to 797it to form a value that has the same length as the longer. 798 799The lexical comparison intrinsics @code{LGe}, @code{LGt}, 800@code{LLe}, and @code{LLt} differ from the corresponding 801intrinsic operators @code{.GE.}, @code{.GT.}, 802@code{.LE.}, @code{.LT.}. 803Because the ASCII collating sequence is assumed, 804the following expressions always return @samp{.TRUE.}: 805 806@smallexample 807LGE ('0', ' ') 808LGE ('A', '0') 809LGE ('a', 'A') 810@end smallexample 811 812The following related expressions do @emph{not} always 813return @samp{.TRUE.}, as they are not necessarily evaluated 814assuming the arguments use ASCII encoding: 815 816@smallexample 817'0' .GE. ' ' 818'A' .GE. '0' 819'a' .GE. 'A' 820@end smallexample 821 822The same difference exists 823between @code{LGt} and @code{.GT.}; 824between @code{LLe} and @code{.LE.}; and 825between @code{LLt} and @code{.LT.}. 826") 827 828DEFDOC (LGT, "Lexically greater than.", "\ 829Returns @samp{.TRUE.} if @samp{@var{@1@}.GT.@var{@2@}}, 830@samp{.FALSE.} otherwise. 831@var{@1@} and @var{@2@} are interpreted as containing 832ASCII character codes. 833If either value contains a character not in the ASCII 834character set, the result is processor dependent. 835 836If the @var{@1@} and @var{@2@} are not the same length, 837the shorter is compared as if spaces were appended to 838it to form a value that has the same length as the longer. 839 840@xref{LGe Intrinsic}, for information on the distinction 841between the @code{@0@} intrinsic and the @code{.GT.} 842operator. 843") 844 845DEFDOC (LLE, "Lexically less than or equal.", "\ 846Returns @samp{.TRUE.} if @samp{@var{@1@}.LE.@var{@2@}}, 847@samp{.FALSE.} otherwise. 848@var{@1@} and @var{@2@} are interpreted as containing 849ASCII character codes. 850If either value contains a character not in the ASCII 851character set, the result is processor dependent. 852 853If the @var{@1@} and @var{@2@} are not the same length, 854the shorter is compared as if spaces were appended to 855it to form a value that has the same length as the longer. 856 857@xref{LGe Intrinsic}, for information on the distinction 858between the @code{@0@} intrinsic and the @code{.LE.} 859operator. 860") 861 862DEFDOC (LLT, "Lexically less than.", "\ 863Returns @samp{.TRUE.} if @samp{@var{@1@}.LT.@var{@2@}}, 864@samp{.FALSE.} otherwise. 865@var{@1@} and @var{@2@} are interpreted as containing 866ASCII character codes. 867If either value contains a character not in the ASCII 868character set, the result is processor dependent. 869 870If the @var{@1@} and @var{@2@} are not the same length, 871the shorter is compared as if spaces were appended to 872it to form a value that has the same length as the longer. 873 874@xref{LGe Intrinsic}, for information on the distinction 875between the @code{@0@} intrinsic and the @code{.LT.} 876operator. 877") 878 879DEFDOC (SIGN, "Apply sign to magnitude.", "\ 880Returns @samp{ABS(@var{@1@})*@var{s}}, where 881@var{s} is +1 if @samp{@var{@2@}.GE.0}, 882-1 otherwise. 883 884@xref{Abs Intrinsic}, for the function that returns 885the magnitude of a value. 886") 887 888DEFDOC (DSIGN, "Apply sign to magnitude (archaic).", ARCHAIC_2 (SIGN, Sign)) 889DEFDOC (ISIGN, "Apply sign to magnitude (archaic).", ARCHAIC_2 (SIGN, Sign)) 890 891DEFDOC (REAL, "Convert value to type @code{REAL(KIND=1)}.", "\ 892Converts @var{@1@} to @code{REAL(KIND=1)}. 893 894Use of @code{@0@()} with a @code{COMPLEX} argument 895(other than @code{COMPLEX(KIND=1)}) is restricted to the following case: 896 897@example 898REAL(REAL(@1@)) 899@end example 900 901@noindent 902This expression converts the real part of @1@ to 903@code{REAL(KIND=1)}. 904 905@xref{RealPart Intrinsic}, for information on a GNU Fortran 906intrinsic that extracts the real part of an arbitrary 907@code{COMPLEX} value. 908 909@xref{REAL() and AIMAG() of Complex}, for more information. 910") 911 912DEFDOC (DREAL, "Convert value to type @code{REAL(KIND=2)}.", "\ 913Converts @var{@1@} to @code{REAL(KIND=2)}. 914 915If @var{@1@} is type @code{COMPLEX}, its real part 916is converted (if necessary) to @code{REAL(KIND=2)}, 917and its imaginary part is disregarded. 918 919Although this intrinsic is not standard Fortran, 920it is a popular extension offered by many compilers 921that support @code{DOUBLE COMPLEX}, since it offers 922the easiest way to extract the real part of a @code{DOUBLE COMPLEX} 923value without using the Fortran 90 @code{REAL()} intrinsic 924in a way that produces a return value inconsistent with 925the way many FORTRAN 77 compilers handle @code{REAL()} of 926a @code{DOUBLE COMPLEX} value. 927 928@xref{RealPart Intrinsic}, for information on a GNU Fortran 929intrinsic that avoids these areas of confusion. 930 931@xref{Dble Intrinsic}, for information on the standard FORTRAN 77 932replacement for @code{DREAL()}. 933 934@xref{REAL() and AIMAG() of Complex}, for more information on 935this issue. 936") 937 938DEFDOC (IMAGPART, "Extract imaginary part of complex.", "\ 939The imaginary part of @var{@1@} is returned, without conversion. 940 941@emph{Note:} The way to do this in standard Fortran 90 942is @samp{AIMAG(@var{@1@})}. 943However, when, for example, @var{@1@} is @code{DOUBLE COMPLEX}, 944@samp{AIMAG(@var{@1@})} means something different for some compilers 945that are not true Fortran 90 compilers but offer some 946extensions standardized by Fortran 90 (such as the 947@code{DOUBLE COMPLEX} type, also known as @code{COMPLEX(KIND=2)}). 948 949The advantage of @code{@0@()} is that, while not necessarily 950more or less portable than @code{AIMAG()}, it is more likely to 951cause a compiler that doesn't support it to produce a diagnostic 952than generate incorrect code. 953 954@xref{REAL() and AIMAG() of Complex}, for more information. 955") 956 957DEFDOC (COMPLEX, "Build complex value from real and@99@imaginary parts.", "\ 958Returns a @code{COMPLEX} value that has @samp{@1@} and @samp{@2@} as its 959real and imaginary parts, respectively. 960 961If @var{@1@} and @var{@2@} are the same type, and that type is not 962@code{INTEGER}, no data conversion is performed, and the type of 963the resulting value has the same kind value as the types 964of @var{@1@} and @var{@2@}. 965 966If @var{@1@} and @var{@2@} are not the same type, the usual type-promotion 967rules are applied to both, converting either or both to the 968appropriate @code{REAL} type. 969The type of the resulting value has the same kind value as the 970type to which both @var{@1@} and @var{@2@} were converted, in this case. 971 972If @var{@1@} and @var{@2@} are both @code{INTEGER}, they are both converted 973to @code{REAL(KIND=1)}, and the result of the @code{@0@()} 974invocation is type @code{COMPLEX(KIND=1)}. 975 976@emph{Note:} The way to do this in standard Fortran 90 977is too hairy to describe here, but it is important to 978note that @samp{CMPLX(D1,D2)} returns a @code{COMPLEX(KIND=1)} 979result even if @samp{D1} and @samp{D2} are type @code{REAL(KIND=2)}. 980Hence the availability of @code{COMPLEX()} in GNU Fortran. 981") 982 983DEFDOC (LOC, "Address of entity in core.", "\ 984The @code{LOC()} intrinsic works the 985same way as the @code{%LOC()} construct. 986@xref{%LOC(),,The @code{%LOC()} Construct}, for 987more information. 988") 989 990DEFDOC (REALPART, "Extract real part of complex.", "\ 991The real part of @var{@1@} is returned, without conversion. 992 993@emph{Note:} The way to do this in standard Fortran 90 994is @samp{REAL(@var{@1@})}. 995However, when, for example, @var{@1@} is @code{COMPLEX(KIND=2)}, 996@samp{REAL(@var{@1@})} means something different for some compilers 997that are not true Fortran 90 compilers but offer some 998extensions standardized by Fortran 90 (such as the 999@code{DOUBLE COMPLEX} type, also known as @code{COMPLEX(KIND=2)}). 1000 1001The advantage of @code{@0@()} is that, while not necessarily 1002more or less portable than @code{REAL()}, it is more likely to 1003cause a compiler that doesn't support it to produce a diagnostic 1004than generate incorrect code. 1005 1006@xref{REAL() and AIMAG() of Complex}, for more information. 1007") 1008 1009DEFDOC (GETARG, "Obtain command-line argument.", "\ 1010Sets @var{@2@} to the @var{@1@}-th command-line argument (or to all 1011blanks if there are fewer than @var{@2@} command-line arguments); 1012@code{CALL @0@(0, @var{value})} sets @var{value} to the name of the 1013program (on systems that support this feature). 1014 1015@xref{IArgC Intrinsic}, for information on how to get the number 1016of arguments. 1017") 1018 1019DEFDOC (ABORT, "Abort the program.", "\ 1020Prints a message and potentially causes a core dump via @code{abort(3)}. 1021") 1022 1023DEFDOC (EXIT, "Terminate the program.", "\ 1024Exit the program with status @var{@1@} after closing open Fortran 1025I/O units and otherwise behaving as @code{exit(2)}. 1026If @var{@1@} is omitted the canonical `success' value 1027will be returned to the system. 1028") 1029 1030DEFDOC (IARGC, "Obtain count of command-line arguments.", "\ 1031Returns the number of command-line arguments. 1032 1033This count does not include the specification of the program 1034name itself. 1035") 1036 1037DEFDOC (CTIME_func, "Convert time to Day Mon dd hh:mm:ss yyyy.", "\ 1038Converts @var{@1@}, a system time value, such as returned by 1039@code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}, 1040and returns that string as the function value. 1041 1042@xref{Time8 Intrinsic}. 1043") 1044 1045DEFDOC (CTIME_subr, "Convert time to Day Mon dd hh:mm:ss yyyy.", "\ 1046Converts @var{@1@}, a system time value, such as returned by 1047@code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}, 1048and returns that string in @var{@2@}. 1049 1050@xref{Time8 Intrinsic}. 1051 1052Some non-GNU implementations of Fortran provide this intrinsic as 1053only a function, not as a subroutine. 1054") 1055 1056DEFDOC (DATE, "Get current date as dd-Mon-yy.", "\ 1057Returns @var{@1@} in the form @samp{@var{dd}-@var{mmm}-@var{yy}}, 1058representing the numeric day of the month @var{dd}, a three-character 1059abbreviation of the month name @var{mmm} and the last two digits of 1060the year @var{yy}, e.g.@: @samp{25-Nov-96}. 1061 1062@cindex Y2K compliance 1063@cindex Year 2000 compliance 1064This intrinsic is not recommended, due to the year 2000 approaching. 1065Therefore, programs making use of this intrinsic 1066might not be Year 2000 (Y2K) compliant. 1067@xref{CTime Intrinsic (subroutine)}, for information on obtaining more digits 1068for the current (or any) date. 1069") 1070 1071DEFDOC (DTIME_func, "Get elapsed time since last time.", "\ 1072Initially, return the number of seconds of runtime 1073since the start of the process's execution 1074as the function value, 1075and the user and system components of this in @samp{@var{@1@}(1)} 1076and @samp{@var{@1@}(2)} respectively. 1077The functions' value is equal to @samp{@var{@1@}(1) + @var{@1@}(2)}. 1078 1079Subsequent invocations of @samp{@0@()} return values accumulated since the 1080previous invocation. 1081 1082@cindex wraparound, timings 1083@cindex limits, timings 1084On some systems, the underlying timings are represented 1085using types with sufficiently small limits that overflows 1086(wraparounds) are possible, such as 32-bit types. 1087Therefore, the values returned by this intrinsic 1088might be, or become, negative, 1089or numerically less than previous values, 1090during a single run of the compiled program. 1091 1092Due to the side effects performed by this intrinsic, the function 1093form is not recommended. 1094") 1095 1096DEFDOC (DTIME_subr, "Get elapsed time since last time.", "\ 1097Initially, return the number of seconds of runtime 1098since the start of the process's execution 1099in @var{@2@}, 1100and the user and system components of this in @samp{@var{@1@}(1)} 1101and @samp{@var{@1@}(2)} respectively. 1102The value of @var{@2@} is equal to @samp{@var{@1@}(1) + @var{@1@}(2)}. 1103 1104Subsequent invocations of @samp{@0@()} set values based on accumulations 1105since the previous invocation. 1106 1107@cindex wraparound, timings 1108@cindex limits, timings 1109On some systems, the underlying timings are represented 1110using types with sufficiently small limits that overflows 1111(wraparounds) are possible, such as 32-bit types. 1112Therefore, the values returned by this intrinsic 1113might be, or become, negative, 1114or numerically less than previous values, 1115during a single run of the compiled program. 1116 1117Some non-GNU implementations of Fortran provide this intrinsic as 1118only a function, not as a subroutine. 1119") 1120 1121DEFDOC (ETIME_func, "Get elapsed time for process.", "\ 1122Return the number of seconds of runtime 1123since the start of the process's execution 1124as the function value, 1125and the user and system components of this in @samp{@var{@1@}(1)} 1126and @samp{@var{@1@}(2)} respectively. 1127The functions' value is equal to @samp{@var{@1@}(1) + @var{@1@}(2)}. 1128 1129@cindex wraparound, timings 1130@cindex limits, timings 1131On some systems, the underlying timings are represented 1132using types with sufficiently small limits that overflows 1133(wraparounds) are possible, such as 32-bit types. 1134Therefore, the values returned by this intrinsic 1135might be, or become, negative, 1136or numerically less than previous values, 1137during a single run of the compiled program. 1138") 1139 1140DEFDOC (ETIME_subr, "Get elapsed time for process.", "\ 1141Return the number of seconds of runtime 1142since the start of the process's execution 1143in @var{@2@}, 1144and the user and system components of this in @samp{@var{@1@}(1)} 1145and @samp{@var{@1@}(2)} respectively. 1146The value of @var{@2@} is equal to @samp{@var{@1@}(1) + @var{@1@}(2)}. 1147 1148@cindex wraparound, timings 1149@cindex limits, timings 1150On some systems, the underlying timings are represented 1151using types with sufficiently small limits that overflows 1152(wraparounds) are possible, such as 32-bit types. 1153Therefore, the values returned by this intrinsic 1154might be, or become, negative, 1155or numerically less than previous values, 1156during a single run of the compiled program. 1157 1158Some non-GNU implementations of Fortran provide this intrinsic as 1159only a function, not as a subroutine. 1160") 1161 1162DEFDOC (FDATE_func, "Get current time as Day Mon dd hh:mm:ss yyyy.", "\ 1163Returns the current date (using the same format as @code{CTIME()}). 1164 1165Equivalent to: 1166 1167@example 1168CTIME(TIME8()) 1169@end example 1170 1171@cindex Y10K compliance 1172@cindex Year 10000 compliance 1173@cindex wraparound, Y10K 1174@cindex limits, Y10K 1175Programs making use of this intrinsic 1176might not be Year 10000 (Y10K) compliant. 1177For example, the date might appear, 1178to such programs, to wrap around 1179(change from a larger value to a smaller one) 1180as of the Year 10000. 1181 1182@xref{CTime Intrinsic (function)}. 1183") 1184 1185DEFDOC (FDATE_subr, "Get current time as Day Mon dd hh:mm:ss yyyy.", "\ 1186Returns the current date (using the same format as @code{CTIME()}) 1187in @var{@1@}. 1188 1189Equivalent to: 1190 1191@example 1192CALL CTIME(@var{@1@}, TIME8()) 1193@end example 1194 1195@cindex Y10K compliance 1196@cindex Year 10000 compliance 1197@cindex wraparound, Y10K 1198@cindex limits, Y10K 1199Programs making use of this intrinsic 1200might not be Year 10000 (Y10K) compliant. 1201For example, the date might appear, 1202to such programs, to wrap around 1203(change from a larger value to a smaller one) 1204as of the Year 10000. 1205 1206@xref{CTime Intrinsic (subroutine)}. 1207 1208Some non-GNU implementations of Fortran provide this intrinsic as 1209only a function, not as a subroutine. 1210") 1211 1212DEFDOC (GMTIME, "Convert time to GMT time info.", "\ 1213Given a system time value @var{@1@}, fills @var{@2@} with values 1214extracted from it appropriate to the GMT time zone using 1215@code{gmtime(3)}. 1216 1217The array elements are as follows: 1218 1219@enumerate 1220@item 1221Seconds after the minute, range 0--59 or 0--61 to allow for leap 1222seconds 1223 1224@item 1225Minutes after the hour, range 0--59 1226 1227@item 1228Hours past midnight, range 0--23 1229 1230@item 1231Day of month, range 0--31 1232 1233@item 1234Number of months since January, range 0--12 1235 1236@item 1237Years since 1900 1238 1239@item 1240Number of days since Sunday, range 0--6 1241 1242@item 1243Days since January 1 1244 1245@item 1246Daylight savings indicator: positive if daylight savings is in effect, 1247zero if not, and negative if the information isn't available. 1248@end enumerate 1249") 1250 1251DEFDOC (LTIME, "Convert time to local time info.", "\ 1252Given a system time value @var{@1@}, fills @var{@2@} with values 1253extracted from it appropriate to the GMT time zone using 1254@code{localtime(3)}. 1255 1256The array elements are as follows: 1257 1258@enumerate 1259@item 1260Seconds after the minute, range 0--59 or 0--61 to allow for leap 1261seconds 1262 1263@item 1264Minutes after the hour, range 0--59 1265 1266@item 1267Hours past midnight, range 0--23 1268 1269@item 1270Day of month, range 0--31 1271 1272@item 1273Number of months since January, range 0--12 1274 1275@item 1276Years since 1900 1277 1278@item 1279Number of days since Sunday, range 0--6 1280 1281@item 1282Days since January 1 1283 1284@item 1285Daylight savings indicator: positive if daylight savings is in effect, 1286zero if not, and negative if the information isn't available. 1287@end enumerate 1288") 1289 1290DEFDOC (IDATE_unix, "Get local time info.", "\ 1291Fills @var{@1@} with the numerical values at the current local time. 1292The day (in the range 1--31), month (in the range 1--12), 1293and year appear in elements 1, 2, and 3 of @var{@1@}, respectively. 1294The year has four significant digits. 1295 1296@cindex Y10K compliance 1297@cindex Year 10000 compliance 1298@cindex wraparound, Y10K 1299@cindex limits, Y10K 1300Programs making use of this intrinsic 1301might not be Year 10000 (Y10K) compliant. 1302For example, the date might appear, 1303to such programs, to wrap around 1304(change from a larger value to a smaller one) 1305as of the Year 10000. 1306") 1307 1308DEFDOC (IDATE_vxt, "Get local time info (VAX/VMS).", "\ 1309Returns the numerical values of the current local time. 1310The month (in the range 1--12) is returned in @var{@1@}, 1311the day (in the range 1--31) in @var{@2@}, 1312and the year in @var{@3@} (in the range 0--99). 1313 1314@cindex Y2K compliance 1315@cindex Year 2000 compliance 1316@cindex wraparound, Y2K 1317@cindex limits, Y2K 1318This intrinsic is not recommended, due to the fact that 1319its return value for year wraps around century boundaries 1320(change from a larger value to a smaller one). 1321Therefore, programs making use of this intrinsic, for 1322instance, might not be Year 2000 (Y2K) compliant. 1323For example, the date might appear, 1324to such programs, to wrap around 1325as of the Year 2000. 1326 1327@xref{IDate Intrinsic (UNIX)}, for information on obtaining more digits 1328for the current date. 1329") 1330 1331DEFDOC (ITIME, "Get local time of day.", "\ 1332Returns the current local time hour, minutes, and seconds in elements 13331, 2, and 3 of @var{@1@}, respectively. 1334") 1335 1336DEFDOC (MCLOCK, "Get number of clock ticks for process.", "\ 1337Returns the number of clock ticks since the start of the process. 1338Supported on systems with @code{clock(3)} (q.v.). 1339 1340@cindex wraparound, timings 1341@cindex limits, timings 1342This intrinsic is not fully portable, such as to systems 1343with 32-bit @code{INTEGER} types but supporting times 1344wider than 32 bits. 1345Therefore, the values returned by this intrinsic 1346might be, or become, negative, 1347or numerically less than previous values, 1348during a single run of the compiled program. 1349 1350@xref{MClock8 Intrinsic}, for information on a 1351similar intrinsic that might be portable to more 1352GNU Fortran implementations, though to fewer 1353Fortran compilers. 1354 1355If the system does not support @code{clock(3)}, 1356-1 is returned. 1357") 1358 1359DEFDOC (MCLOCK8, "Get number of clock ticks for process.", "\ 1360Returns the number of clock ticks since the start of the process. 1361Supported on systems with @code{clock(3)} (q.v.). 1362 1363@cindex wraparound, timings 1364@cindex limits, timings 1365@emph{Warning:} this intrinsic does not increase the range 1366of the timing values over that returned by @code{clock(3)}. 1367On a system with a 32-bit @code{clock(3)}, 1368@code{@0@} will return a 32-bit value, 1369even though converted to an @samp{INTEGER(KIND=2)} value. 1370That means overflows of the 32-bit value can still occur. 1371Therefore, the values returned by this intrinsic 1372might be, or become, negative, 1373or numerically less than previous values, 1374during a single run of the compiled program. 1375 1376No Fortran implementations other than GNU Fortran are 1377known to support this intrinsic at the time of this 1378writing. 1379@xref{MClock Intrinsic}, for information on a 1380similar intrinsic that might be portable to more Fortran 1381compilers, though to fewer GNU Fortran implementations. 1382 1383If the system does not support @code{clock(3)}, 1384-1 is returned. 1385") 1386 1387DEFDOC (SECNDS, "Get local time offset since midnight.", "\ 1388Returns the local time in seconds since midnight minus the value 1389@var{@1@}. 1390 1391@cindex wraparound, timings 1392@cindex limits, timings 1393This values returned by this intrinsic 1394become numerically less than previous values 1395(they wrap around) during a single run of the 1396compiler program, under normal circumstances 1397(such as running through the midnight hour). 1398") 1399 1400DEFDOC (SECOND_func, "Get CPU time for process in seconds.", "\ 1401Returns the process's runtime in seconds---the same value as the 1402UNIX function @code{etime} returns. 1403 1404@cindex wraparound, timings 1405@cindex limits, timings 1406On some systems, the underlying timings are represented 1407using types with sufficiently small limits that overflows 1408(wraparounds) are possible, such as 32-bit types. 1409Therefore, the values returned by this intrinsic 1410might be, or become, negative, 1411or numerically less than previous values, 1412during a single run of the compiled program. 1413") 1414 1415DEFDOC (SECOND_subr, "Get CPU time for process@99@in seconds.", "\ 1416Returns the process's runtime in seconds in @var{@1@}---the same value 1417as the UNIX function @code{etime} returns. 1418 1419@cindex wraparound, timings 1420@cindex limits, timings 1421On some systems, the underlying timings are represented 1422using types with sufficiently small limits that overflows 1423(wraparounds) are possible, such as 32-bit types. 1424Therefore, the values returned by this intrinsic 1425might be, or become, negative, 1426or numerically less than previous values, 1427during a single run of the compiled program. 1428 1429This routine is known from Cray Fortran. @xref{CPU_Time Intrinsic}, 1430for a standard equivalent. 1431") 1432 1433DEFDOC (SYSTEM_CLOCK, "Get current system clock value.", "\ 1434Returns in @var{@1@} the current value of the system clock; this is 1435the value returned by the UNIX function @code{times(2)} 1436in this implementation, but 1437isn't in general. 1438@var{@2@} is the number of clock ticks per second and 1439@var{@3@} is the maximum value this can take, which isn't very useful 1440in this implementation since it's just the maximum C @code{unsigned 1441int} value. 1442 1443@cindex wraparound, timings 1444@cindex limits, timings 1445On some systems, the underlying timings are represented 1446using types with sufficiently small limits that overflows 1447(wraparounds) are possible, such as 32-bit types. 1448Therefore, the values returned by this intrinsic 1449might be, or become, negative, 1450or numerically less than previous values, 1451during a single run of the compiled program. 1452") 1453 1454DEFDOC (CPU_TIME, "Get current CPU time.", "\ 1455Returns in @var{@1@} the current value of the system time. 1456This implementation of the Fortran 95 intrinsic is just an alias for 1457@code{second} @xref{Second Intrinsic (subroutine)}. 1458 1459@cindex wraparound, timings 1460@cindex limits, timings 1461On some systems, the underlying timings are represented 1462using types with sufficiently small limits that overflows 1463(wraparounds) are possible, such as 32-bit types. 1464Therefore, the values returned by this intrinsic 1465might be, or become, negative, 1466or numerically less than previous values, 1467during a single run of the compiled program. 1468") 1469 1470DEFDOC (TIME8, "Get current time as time value.", "\ 1471Returns the current time encoded as a long integer 1472(in the manner of the UNIX function @code{time(3)}). 1473This value is suitable for passing to @code{CTIME}, 1474@code{GMTIME}, and @code{LTIME}. 1475 1476@cindex wraparound, timings 1477@cindex limits, timings 1478@emph{Warning:} this intrinsic does not increase the range 1479of the timing values over that returned by @code{time(3)}. 1480On a system with a 32-bit @code{time(3)}, 1481@code{@0@} will return a 32-bit value, 1482even though converted to an @samp{INTEGER(KIND=2)} value. 1483That means overflows of the 32-bit value can still occur. 1484Therefore, the values returned by this intrinsic 1485might be, or become, negative, 1486or numerically less than previous values, 1487during a single run of the compiled program. 1488 1489No Fortran implementations other than GNU Fortran are 1490known to support this intrinsic at the time of this 1491writing. 1492@xref{Time Intrinsic (UNIX)}, for information on a 1493similar intrinsic that might be portable to more Fortran 1494compilers, though to fewer GNU Fortran implementations. 1495") 1496 1497DEFDOC (TIME_unix, "Get current time as time value.", "\ 1498Returns the current time encoded as an integer 1499(in the manner of the UNIX function @code{time(3)}). 1500This value is suitable for passing to @code{CTIME}, 1501@code{GMTIME}, and @code{LTIME}. 1502 1503@cindex wraparound, timings 1504@cindex limits, timings 1505This intrinsic is not fully portable, such as to systems 1506with 32-bit @code{INTEGER} types but supporting times 1507wider than 32 bits. 1508Therefore, the values returned by this intrinsic 1509might be, or become, negative, 1510or numerically less than previous values, 1511during a single run of the compiled program. 1512 1513@xref{Time8 Intrinsic}, for information on a 1514similar intrinsic that might be portable to more 1515GNU Fortran implementations, though to fewer 1516Fortran compilers. 1517") 1518 1519#define BES(num,n,val) "\ 1520Calculates the Bessel function of the " #num " kind of \ 1521order " #n " of @var{@" #val "@}.\n\ 1522See @code{bessel(3m)}, on whose implementation the \ 1523function depends.\ 1524" 1525 1526DEFDOC (BESJ0, "Bessel function.", BES (first, 0, 1)) 1527DEFDOC (BESJ1, "Bessel function.", BES (first, 1, 1)) 1528DEFDOC (BESJN, "Bessel function.", BES (first, @var{N}, 2)) 1529DEFDOC (BESY0, "Bessel function.", BES (second, 0, 1)) 1530DEFDOC (BESY1, "Bessel function.", BES (second, 1, 1)) 1531DEFDOC (BESYN, "Bessel function.", BES (second, @var{N}, 2)) 1532DEFDOC (DBESJ0, "Bessel function (archaic).", ARCHAIC (BESJ0, BesJ0)) 1533DEFDOC (DBESJ1, "Bessel function (archaic).", ARCHAIC (BESJ1, BesJ1)) 1534DEFDOC (DBESJN, "Bessel function (archaic).", ARCHAIC_2nd (BESJN, BesJN)) 1535DEFDOC (DBESY0, "Bessel function (archaic).", ARCHAIC (BESY0, BesY0)) 1536DEFDOC (DBESY1, "Bessel function (archaic).", ARCHAIC (BESY1, BesY1)) 1537DEFDOC (DBESYN, "Bessel function (archaic).", ARCHAIC_2nd (BESYN, BesYN)) 1538 1539DEFDOC (ERF, "Error function.", "\ 1540Returns the error function of @var{@1@}. 1541See @code{erf(3m)}, which provides the implementation. 1542") 1543 1544DEFDOC (ERFC, "Complementary error function.", "\ 1545Returns the complementary error function of @var{@1@}: 1546@samp{ERFC(R) = 1 - ERF(R)} (except that the result might be more 1547accurate than explicitly evaluating that formulae would give). 1548See @code{erfc(3m)}, which provides the implementation. 1549") 1550 1551DEFDOC (DERF, "Error function (archaic).", ARCHAIC (ERF, ErF)) 1552DEFDOC (DERFC, "Complementary error function (archaic).", ARCHAIC (ERFC, ErFC)) 1553 1554DEFDOC (IRAND, "Random number.", "\ 1555Returns a uniform quasi-random number up to a system-dependent limit. 1556If @var{@1@} is 0, the next number in sequence is returned; if 1557@var{@1@} is 1, the generator is restarted by calling the UNIX function 1558@samp{srand(0)}; if @var{@1@} has any other value, 1559it is used as a new seed with @code{srand()}. 1560 1561@xref{SRand Intrinsic}. 1562 1563@emph{Note:} As typically implemented (by the routine of the same 1564name in the C library), this random number generator is a very poor 1565one, though the BSD and GNU libraries provide a much better 1566implementation than the `traditional' one. 1567On a different system you almost certainly want to use something better. 1568") 1569 1570DEFDOC (RAND, "Random number.", "\ 1571Returns a uniform quasi-random number between 0 and 1. 1572If @var{@1@} is 0, the next number in sequence is returned; if 1573@var{@1@} is 1, the generator is restarted by calling @samp{srand(0)}; 1574if @var{@1@} has any other value, it is used as a new seed with 1575@code{srand}. 1576 1577@xref{SRand Intrinsic}. 1578 1579@emph{Note:} As typically implemented (by the routine of the same 1580name in the C library), this random number generator is a very poor 1581one, though the BSD and GNU libraries provide a much better 1582implementation than the `traditional' one. 1583On a different system you 1584almost certainly want to use something better. 1585") 1586 1587DEFDOC (SRAND, "Random seed.", "\ 1588Reinitializes the generator with the seed in @var{@1@}. 1589@xref{IRand Intrinsic}. 1590@xref{Rand Intrinsic}. 1591") 1592 1593DEFDOC (ACCESS, "Check file accessibility.", "\ 1594Checks file @var{@1@} for accessibility in the mode specified by @var{@2@} and 1595returns 0 if the file is accessible in that mode, otherwise an error 1596code if the file is inaccessible or @var{@2@} is invalid. 1597See @code{access(2)}. 1598A null character (@samp{CHAR(0)}) marks the end of 1599the name in @var{@1@}---otherwise, 1600trailing blanks in @var{@1@} are ignored. 1601@var{@2@} may be a concatenation of any of the following characters: 1602 1603@table @samp 1604@item r 1605Read permission 1606 1607@item w 1608Write permission 1609 1610@item x 1611Execute permission 1612 1613@item @kbd{SPC} 1614Existence 1615@end table 1616") 1617 1618DEFDOC (CHDIR_subr, "Change directory.", "\ 1619Sets the current working directory to be @var{@1@}. 1620If the @var{@2@} argument is supplied, it contains 0 1621on success or a nonzero error code otherwise upon return. 1622See @code{chdir(3)}. 1623 1624@emph{Caution:} Using this routine during I/O to a unit connected with a 1625non-absolute file name can cause subsequent I/O on such a unit to fail 1626because the I/O library might reopen files by name. 1627 1628Some non-GNU implementations of Fortran provide this intrinsic as 1629only a function, not as a subroutine, or do not support the 1630(optional) @var{@2@} argument. 1631") 1632 1633DEFDOC (CHDIR_func, "Change directory.", "\ 1634Sets the current working directory to be @var{@1@}. 1635Returns 0 on success or a nonzero error code. 1636See @code{chdir(3)}. 1637 1638@emph{Caution:} Using this routine during I/O to a unit connected with a 1639non-absolute file name can cause subsequent I/O on such a unit to fail 1640because the I/O library might reopen files by name. 1641 1642Due to the side effects performed by this intrinsic, the function 1643form is not recommended. 1644") 1645 1646DEFDOC (CHMOD_func, "Change file modes.", "\ 1647Changes the access mode of file @var{@1@} according to the 1648specification @var{@2@}, which is given in the format of 1649@code{chmod(1)}. 1650A null character (@samp{CHAR(0)}) marks the end of 1651the name in @var{@1@}---otherwise, 1652trailing blanks in @var{@1@} are ignored. 1653Currently, @var{@1@} must not contain the single quote 1654character. 1655 1656Returns 0 on success or a nonzero error code otherwise. 1657 1658Note that this currently works 1659by actually invoking @code{/bin/chmod} (or the @code{chmod} found when 1660the library was configured) and so might fail in some circumstances and 1661will, anyway, be slow. 1662 1663Due to the side effects performed by this intrinsic, the function 1664form is not recommended. 1665") 1666 1667DEFDOC (CHMOD_subr, "Change file modes.", "\ 1668Changes the access mode of file @var{@1@} according to the 1669specification @var{@2@}, which is given in the format of 1670@code{chmod(1)}. 1671A null character (@samp{CHAR(0)}) marks the end of 1672the name in @var{@1@}---otherwise, 1673trailing blanks in @var{@1@} are ignored. 1674Currently, @var{@1@} must not contain the single quote 1675character. 1676 1677If the @var{@3@} argument is supplied, it contains 16780 on success or a nonzero error code upon return. 1679 1680Note that this currently works 1681by actually invoking @code{/bin/chmod} (or the @code{chmod} found when 1682the library was configured) and so might fail in some circumstances and 1683will, anyway, be slow. 1684 1685Some non-GNU implementations of Fortran provide this intrinsic as 1686only a function, not as a subroutine, or do not support the 1687(optional) @var{@3@} argument. 1688") 1689 1690DEFDOC (GETCWD_func, "Get current working directory.", "\ 1691Places the current working directory in @var{@1@}. 1692Returns 0 on 1693success, otherwise a nonzero error code 1694(@code{ENOSYS} if the system does not provide @code{getcwd(3)} 1695or @code{getwd(3)}). 1696") 1697 1698DEFDOC (GETCWD_subr, "Get current working directory.", "\ 1699Places the current working directory in @var{@1@}. 1700If the @var{@2@} argument is supplied, it contains 0 1701success or a nonzero error code upon return 1702(@code{ENOSYS} if the system does not provide @code{getcwd(3)} 1703or @code{getwd(3)}). 1704 1705Some non-GNU implementations of Fortran provide this intrinsic as 1706only a function, not as a subroutine, or do not support the 1707(optional) @var{@2@} argument. 1708") 1709 1710DEFDOC (FSTAT_func, "Get file information.", "\ 1711Obtains data about the file open on Fortran I/O unit @var{@1@} and 1712places them in the array @var{@2@}. 1713The values in this array are 1714extracted from the @code{stat} structure as returned by 1715@code{fstat(2)} q.v., as follows: 1716 1717@enumerate 1718@item 1719Device ID 1720 1721@item 1722Inode number 1723 1724@item 1725File mode 1726 1727@item 1728Number of links 1729 1730@item 1731Owner's uid 1732 1733@item 1734Owner's gid 1735 1736@item 1737ID of device containing directory entry for file 1738(0 if not available) 1739 1740@item 1741File size (bytes) 1742 1743@item 1744Last access time 1745 1746@item 1747Last modification time 1748 1749@item 1750Last file status change time 1751 1752@item 1753Preferred I/O block size (-1 if not available) 1754 1755@item 1756Number of blocks allocated (-1 if not available) 1757@end enumerate 1758 1759Not all these elements are relevant on all systems. 1760If an element is not relevant, it is returned as 0. 1761 1762Returns 0 on success or a nonzero error code. 1763") 1764 1765DEFDOC (FSTAT_subr, "Get file information.", "\ 1766Obtains data about the file open on Fortran I/O unit @var{@1@} and 1767places them in the array @var{@2@}. 1768The values in this array are 1769extracted from the @code{stat} structure as returned by 1770@code{fstat(2)} q.v., as follows: 1771 1772@enumerate 1773@item 1774Device ID 1775 1776@item 1777Inode number 1778 1779@item 1780File mode 1781 1782@item 1783Number of links 1784 1785@item 1786Owner's uid 1787 1788@item 1789Owner's gid 1790 1791@item 1792ID of device containing directory entry for file 1793(0 if not available) 1794 1795@item 1796File size (bytes) 1797 1798@item 1799Last access time 1800 1801@item 1802Last modification time 1803 1804@item 1805Last file status change time 1806 1807@item 1808Preferred I/O block size (-1 if not available) 1809 1810@item 1811Number of blocks allocated (-1 if not available) 1812@end enumerate 1813 1814Not all these elements are relevant on all systems. 1815If an element is not relevant, it is returned as 0. 1816 1817If the @var{@3@} argument is supplied, it contains 18180 on success or a nonzero error code upon return. 1819 1820Some non-GNU implementations of Fortran provide this intrinsic as 1821only a function, not as a subroutine, or do not support the 1822(optional) @var{@3@} argument. 1823") 1824 1825DEFDOC (LSTAT_func, "Get file information.", "\ 1826Obtains data about the given file @var{@1@} and places them in the array 1827@var{@2@}. 1828A null character (@samp{CHAR(0)}) marks the end of 1829the name in @var{@1@}---otherwise, 1830trailing blanks in @var{@1@} are ignored. 1831If @var{@1@} is a symbolic link it returns data on the 1832link itself, so the routine is available only on systems that support 1833symbolic links. 1834The values in this array are extracted from the 1835@code{stat} structure as returned by @code{fstat(2)} q.v., as follows: 1836 1837@enumerate 1838@item 1839Device ID 1840 1841@item 1842Inode number 1843 1844@item 1845File mode 1846 1847@item 1848Number of links 1849 1850@item 1851Owner's uid 1852 1853@item 1854Owner's gid 1855 1856@item 1857ID of device containing directory entry for file 1858(0 if not available) 1859 1860@item 1861File size (bytes) 1862 1863@item 1864Last access time 1865 1866@item 1867Last modification time 1868 1869@item 1870Last file status change time 1871 1872@item 1873Preferred I/O block size (-1 if not available) 1874 1875@item 1876Number of blocks allocated (-1 if not available) 1877@end enumerate 1878 1879Not all these elements are relevant on all systems. 1880If an element is not relevant, it is returned as 0. 1881 1882Returns 0 on success or a nonzero error code 1883(@code{ENOSYS} if the system does not provide @code{lstat(2)}). 1884") 1885 1886DEFDOC (LSTAT_subr, "Get file information.", "\ 1887Obtains data about the given file @var{@1@} and places them in the array 1888@var{@2@}. 1889A null character (@samp{CHAR(0)}) marks the end of 1890the name in @var{@1@}---otherwise, 1891trailing blanks in @var{@1@} are ignored. 1892If @var{@1@} is a symbolic link it returns data on the 1893link itself, so the routine is available only on systems that support 1894symbolic links. 1895The values in this array are extracted from the 1896@code{stat} structure as returned by @code{fstat(2)} q.v., as follows: 1897 1898@enumerate 1899@item 1900Device ID 1901 1902@item 1903Inode number 1904 1905@item 1906File mode 1907 1908@item 1909Number of links 1910 1911@item 1912Owner's uid 1913 1914@item 1915Owner's gid 1916 1917@item 1918ID of device containing directory entry for file 1919(0 if not available) 1920 1921@item 1922File size (bytes) 1923 1924@item 1925Last access time 1926 1927@item 1928Last modification time 1929 1930@item 1931Last file status change time 1932 1933@item 1934Preferred I/O block size (-1 if not available) 1935 1936@item 1937Number of blocks allocated (-1 if not available) 1938@end enumerate 1939 1940Not all these elements are relevant on all systems. 1941If an element is not relevant, it is returned as 0. 1942 1943If the @var{@3@} argument is supplied, it contains 19440 on success or a nonzero error code upon return 1945(@code{ENOSYS} if the system does not provide @code{lstat(2)}). 1946 1947Some non-GNU implementations of Fortran provide this intrinsic as 1948only a function, not as a subroutine, or do not support the 1949(optional) @var{@3@} argument. 1950") 1951 1952DEFDOC (STAT_func, "Get file information.", "\ 1953Obtains data about the given file @var{@1@} and places them in the array 1954@var{@2@}. 1955A null character (@samp{CHAR(0)}) marks the end of 1956the name in @var{@1@}---otherwise, 1957trailing blanks in @var{@1@} are ignored. 1958The values in this array are extracted from the 1959@code{stat} structure as returned by @code{fstat(2)} q.v., as follows: 1960 1961@enumerate 1962@item 1963Device ID 1964 1965@item 1966Inode number 1967 1968@item 1969File mode 1970 1971@item 1972Number of links 1973 1974@item 1975Owner's uid 1976 1977@item 1978Owner's gid 1979 1980@item 1981ID of device containing directory entry for file 1982(0 if not available) 1983 1984@item 1985File size (bytes) 1986 1987@item 1988Last access time 1989 1990@item 1991Last modification time 1992 1993@item 1994Last file status change time 1995 1996@item 1997Preferred I/O block size (-1 if not available) 1998 1999@item 2000Number of blocks allocated (-1 if not available) 2001@end enumerate 2002 2003Not all these elements are relevant on all systems. 2004If an element is not relevant, it is returned as 0. 2005 2006Returns 0 on success or a nonzero error code. 2007") 2008 2009DEFDOC (STAT_subr, "Get file information.", "\ 2010Obtains data about the given file @var{@1@} and places them in the array 2011@var{@2@}. 2012A null character (@samp{CHAR(0)}) marks the end of 2013the name in @var{@1@}---otherwise, 2014trailing blanks in @var{@1@} are ignored. 2015The values in this array are extracted from the 2016@code{stat} structure as returned by @code{fstat(2)} q.v., as follows: 2017 2018@enumerate 2019@item 2020Device ID 2021 2022@item 2023Inode number 2024 2025@item 2026File mode 2027 2028@item 2029Number of links 2030 2031@item 2032Owner's uid 2033 2034@item 2035Owner's gid 2036 2037@item 2038ID of device containing directory entry for file 2039(0 if not available) 2040 2041@item 2042File size (bytes) 2043 2044@item 2045Last access time 2046 2047@item 2048Last modification time 2049 2050@item 2051Last file status change time 2052 2053@item 2054Preferred I/O block size (-1 if not available) 2055 2056@item 2057Number of blocks allocated (-1 if not available) 2058@end enumerate 2059 2060Not all these elements are relevant on all systems. 2061If an element is not relevant, it is returned as 0. 2062 2063If the @var{@3@} argument is supplied, it contains 20640 on success or a nonzero error code upon return. 2065 2066Some non-GNU implementations of Fortran provide this intrinsic as 2067only a function, not as a subroutine, or do not support the 2068(optional) @var{@3@} argument. 2069") 2070 2071DEFDOC (LINK_subr, "Make hard link in file system.", "\ 2072Makes a (hard) link from file @var{@1@} to @var{@2@}. 2073A null character (@samp{CHAR(0)}) marks the end of 2074the names in @var{@1@} and @var{@2@}---otherwise, 2075trailing blanks in @var{@1@} and @var{@2@} are ignored. 2076If the @var{@3@} argument is supplied, it contains 20770 on success or a nonzero error code upon return. 2078See @code{link(2)}. 2079 2080Some non-GNU implementations of Fortran provide this intrinsic as 2081only a function, not as a subroutine, or do not support the 2082(optional) @var{@3@} argument. 2083") 2084 2085DEFDOC (LINK_func, "Make hard link in file system.", "\ 2086Makes a (hard) link from file @var{@1@} to @var{@2@}. 2087A null character (@samp{CHAR(0)}) marks the end of 2088the names in @var{@1@} and @var{@2@}---otherwise, 2089trailing blanks in @var{@1@} and @var{@2@} are ignored. 2090Returns 0 on success or a nonzero error code. 2091See @code{link(2)}. 2092 2093Due to the side effects performed by this intrinsic, the function 2094form is not recommended. 2095") 2096 2097DEFDOC (SYMLNK_subr, "Make symbolic link in file system.", "\ 2098Makes a symbolic link from file @var{@1@} to @var{@2@}. 2099A null character (@samp{CHAR(0)}) marks the end of 2100the names in @var{@1@} and @var{@2@}---otherwise, 2101trailing blanks in @var{@1@} and @var{@2@} are ignored. 2102If the @var{@3@} argument is supplied, it contains 21030 on success or a nonzero error code upon return 2104(@code{ENOSYS} if the system does not provide @code{symlink(2)}). 2105 2106Some non-GNU implementations of Fortran provide this intrinsic as 2107only a function, not as a subroutine, or do not support the 2108(optional) @var{@3@} argument. 2109") 2110 2111DEFDOC (SYMLNK_func, "Make symbolic link in file system.", "\ 2112Makes a symbolic link from file @var{@1@} to @var{@2@}. 2113A null character (@samp{CHAR(0)}) marks the end of 2114the names in @var{@1@} and @var{@2@}---otherwise, 2115trailing blanks in @var{@1@} and @var{@2@} are ignored. 2116Returns 0 on success or a nonzero error code 2117(@code{ENOSYS} if the system does not provide @code{symlink(2)}). 2118 2119Due to the side effects performed by this intrinsic, the function 2120form is not recommended. 2121") 2122 2123DEFDOC (RENAME_subr, "Rename file.", "\ 2124Renames the file @var{@1@} to @var{@2@}. 2125A null character (@samp{CHAR(0)}) marks the end of 2126the names in @var{@1@} and @var{@2@}---otherwise, 2127trailing blanks in @var{@1@} and @var{@2@} are ignored. 2128See @code{rename(2)}. 2129If the @var{@3@} argument is supplied, it contains 21300 on success or a nonzero error code upon return. 2131 2132Some non-GNU implementations of Fortran provide this intrinsic as 2133only a function, not as a subroutine, or do not support the 2134(optional) @var{@3@} argument. 2135") 2136 2137DEFDOC (RENAME_func, "Rename file.", "\ 2138Renames the file @var{@1@} to @var{@2@}. 2139A null character (@samp{CHAR(0)}) marks the end of 2140the names in @var{@1@} and @var{@2@}---otherwise, 2141trailing blanks in @var{@1@} and @var{@2@} are ignored. 2142See @code{rename(2)}. 2143Returns 0 on success or a nonzero error code. 2144 2145Due to the side effects performed by this intrinsic, the function 2146form is not recommended. 2147") 2148 2149DEFDOC (UMASK_subr, "Set file creation permissions mask.", "\ 2150Sets the file creation mask to @var{@1@} and returns the old value in 2151argument @var{@2@} if it is supplied. 2152See @code{umask(2)}. 2153 2154Some non-GNU implementations of Fortran provide this intrinsic as 2155only a function, not as a subroutine. 2156") 2157 2158DEFDOC (UMASK_func, "Set file creation permissions mask.", "\ 2159Sets the file creation mask to @var{@1@} and returns the old value. 2160See @code{umask(2)}. 2161 2162Due to the side effects performed by this intrinsic, the function 2163form is not recommended. 2164") 2165 2166DEFDOC (UNLINK_subr, "Unlink file.", "\ 2167Unlink the file @var{@1@}. 2168A null character (@samp{CHAR(0)}) marks the end of 2169the name in @var{@1@}---otherwise, 2170trailing blanks in @var{@1@} are ignored. 2171If the @var{@2@} argument is supplied, it contains 21720 on success or a nonzero error code upon return. 2173See @code{unlink(2)}. 2174 2175Some non-GNU implementations of Fortran provide this intrinsic as 2176only a function, not as a subroutine, or do not support the 2177(optional) @var{@2@} argument. 2178") 2179 2180DEFDOC (UNLINK_func, "Unlink file.", "\ 2181Unlink the file @var{@1@}. 2182A null character (@samp{CHAR(0)}) marks the end of 2183the name in @var{@1@}---otherwise, 2184trailing blanks in @var{@1@} are ignored. 2185Returns 0 on success or a nonzero error code. 2186See @code{unlink(2)}. 2187 2188Due to the side effects performed by this intrinsic, the function 2189form is not recommended. 2190") 2191 2192DEFDOC (GERROR, "Get error message for last error.", "\ 2193Returns the system error message corresponding to the last system 2194error (C @code{errno}). 2195") 2196 2197DEFDOC (IERRNO, "Get error number for last error.", "\ 2198Returns the last system error number (corresponding to the C 2199@code{errno}). 2200") 2201 2202DEFDOC (PERROR, "Print error message for last error.", "\ 2203Prints (on the C @code{stderr} stream) a newline-terminated error 2204message corresponding to the last system error. 2205This is prefixed by @var{@1@}, a colon and a space. 2206See @code{perror(3)}. 2207") 2208 2209DEFDOC (GETGID, "Get process group id.", "\ 2210Returns the group id for the current process. 2211") 2212 2213DEFDOC (GETUID, "Get process user id.", "\ 2214Returns the user id for the current process. 2215") 2216 2217DEFDOC (GETPID, "Get process id.", "\ 2218Returns the process id for the current process. 2219") 2220 2221DEFDOC (GETENV, "Get environment variable.", "\ 2222Sets @var{@2@} to the value of environment variable given by the 2223value of @var{@1@} (@code{$name} in shell terms) or to blanks if 2224@code{$name} has not been set. 2225A null character (@samp{CHAR(0)}) marks the end of 2226the name in @var{@1@}---otherwise, 2227trailing blanks in @var{@1@} are ignored. 2228") 2229 2230DEFDOC (GETLOG, "Get login name.", "\ 2231Returns the login name for the process in @var{@1@}. 2232 2233@emph{Caution:} On some systems, the @code{getlogin(3)} 2234function, which this intrinsic calls at run time, 2235is either not implemented or returns a null pointer. 2236In the latter case, this intrinsic returns blanks 2237in @var{@1@}. 2238") 2239 2240DEFDOC (HOSTNM_func, "Get host name.", "\ 2241Fills @var{@1@} with the system's host name returned by 2242@code{gethostname(2)}, returning 0 on success or a nonzero error code 2243(@code{ENOSYS} if the system does not provide @code{gethostname(2)}). 2244 2245On some systems (specifically SCO) it might be necessary to link the 2246``socket'' library if you call this routine. 2247Typically this means adding @samp{-lg2c -lsocket -lm} 2248to the @code{g77} command line when linking the program. 2249") 2250 2251DEFDOC (HOSTNM_subr, "Get host name.", "\ 2252Fills @var{@1@} with the system's host name returned by 2253@code{gethostname(2)}. 2254If the @var{@2@} argument is supplied, it contains 22550 on success or a nonzero error code upon return 2256(@code{ENOSYS} if the system does not provide @code{gethostname(2)}). 2257 2258Some non-GNU implementations of Fortran provide this intrinsic as 2259only a function, not as a subroutine, or do not support the 2260(optional) @var{@2@} argument. 2261 2262On some systems (specifically SCO) it might be necessary to link the 2263``socket'' library if you call this routine. 2264Typically this means adding @samp{-lg2c -lsocket -lm} 2265to the @code{g77} command line when linking the program. 2266") 2267 2268DEFDOC (FLUSH, "Flush buffered output.", "\ 2269Flushes Fortran unit(s) currently open for output. 2270Without the optional argument, all such units are flushed, 2271otherwise just the unit specified by @var{@1@}. 2272 2273Some non-GNU implementations of Fortran provide this intrinsic 2274as a library procedure that might or might not support the 2275(optional) @var{@1@} argument. 2276") 2277 2278DEFDOC (FNUM, "Get file descriptor from Fortran unit number.", "\ 2279Returns the Unix file descriptor number corresponding to the open 2280Fortran I/O unit @var{@1@}. 2281This could be passed to an interface to C I/O routines. 2282") 2283 2284#define IOWARN " 2285Stream I/O should not be mixed with normal record-oriented (formatted or 2286unformatted) I/O on the same unit; the results are unpredictable. 2287" 2288 2289DEFDOC (FGET_func, "Read a character from unit 5 stream-wise.", "\ 2290Reads a single character into @var{@1@} in stream mode from unit 5 2291(by-passing normal formatted input) using @code{getc(3)}. 2292Returns 0 on 2293success, @minus{}1 on end-of-file, and the error code from 2294@code{ferror(3)} otherwise. 2295" IOWARN) 2296 2297DEFDOC (FGET_subr, "Read a character from unit 5 stream-wise.", "\ 2298Reads a single character into @var{@1@} in stream mode from unit 5 2299(by-passing normal formatted output) using @code{getc(3)}. 2300Returns in 2301@var{@2@} 0 on success, @minus{}1 on end-of-file, and the error code 2302from @code{ferror(3)} otherwise. 2303" IOWARN) 2304 2305DEFDOC (FGETC_func, "Read a character stream-wise.", "\ 2306Reads a single character into @var{@2@} in stream mode from unit @var{@1@} 2307(by-passing normal formatted output) using @code{getc(3)}. 2308Returns 0 on 2309success, @minus{}1 on end-of-file, and the error code from 2310@code{ferror(3)} otherwise. 2311" IOWARN) 2312 2313DEFDOC (FGETC_subr, "Read a character stream-wise.", "\ 2314Reads a single character into @var{@2@} in stream mode from unit @var{@1@} 2315(by-passing normal formatted output) using @code{getc(3)}. 2316Returns in 2317@var{@3@} 0 on success, @minus{}1 on end-of-file, and the error code from 2318@code{ferror(3)} otherwise. 2319" IOWARN) 2320 2321DEFDOC (FPUT_func, "Write a character to unit 6 stream-wise.", "\ 2322Writes the single character @var{@1@} in stream mode to unit 6 2323(by-passing normal formatted output) using @code{getc(3)}. 2324Returns 0 on 2325success, the error code from @code{ferror(3)} otherwise. 2326" IOWARN) 2327 2328DEFDOC (FPUT_subr, "Write a character to unit 6 stream-wise.", "\ 2329Writes the single character @var{@1@} in stream mode to unit 6 2330(by-passing normal formatted output) using @code{putc(3)}. 2331Returns in 2332@var{@2@} 0 on success, the error code from @code{ferror(3)} otherwise. 2333" IOWARN) 2334 2335DEFDOC (FPUTC_func, "Write a character stream-wise.", "\ 2336Writes the single character @var{@2@} in stream mode to unit @var{@1@} 2337(by-passing normal formatted output) using @code{putc(3)}. 2338Returns 0 on 2339success, the error code from @code{ferror(3)} otherwise. 2340" IOWARN) 2341 2342DEFDOC (FPUTC_subr, "Write a character stream-wise.", "\ 2343Writes the single character @var{@1@} in stream mode to unit 6 2344(by-passing normal formatted output) using @code{putc(3)}. 2345Returns in 2346@var{@2@} 0 on success, the error code from @code{ferror(3)} otherwise. 2347" IOWARN) 2348 2349DEFDOC (FSEEK, "Position file (low-level).", "\ 2350Attempts to move Fortran unit @var{@1@} to the specified 2351@var{@2@}: absolute offset if @var{@3@}=0; relative to the 2352current offset if @var{@3@}=1; relative to the end of the file if 2353@var{@3@}=2. 2354It branches to label @var{@4@} if @var{@1@} is 2355not open or if the call otherwise fails. 2356") 2357 2358DEFDOC (FTELL_func, "Get file position (low-level).", "\ 2359Returns the current offset of Fortran unit @var{@1@} 2360(or @minus{}1 if @var{@1@} is not open). 2361") 2362 2363DEFDOC (FTELL_subr, "Get file position (low-level).", "\ 2364Sets @var{@2@} to the current offset of Fortran unit @var{@1@} 2365(or to @minus{}1 if @var{@1@} is not open). 2366 2367Some non-GNU implementations of Fortran provide this intrinsic as 2368only a function, not as a subroutine. 2369") 2370 2371DEFDOC (ISATTY, "Is unit connected to a terminal?", "\ 2372Returns @code{.TRUE.} if and only if the Fortran I/O unit 2373specified by @var{@1@} is connected 2374to a terminal device. 2375See @code{isatty(3)}. 2376") 2377 2378DEFDOC (TTYNAM_func, "Get name of terminal device for unit.", "\ 2379Returns the name of the terminal device open on logical unit 2380@var{@1@} or a blank string if @var{@1@} is not connected to a 2381terminal. 2382") 2383 2384DEFDOC (TTYNAM_subr, "Get name of terminal device for unit.", "\ 2385Sets @var{@2@} to the name of the terminal device open on logical unit 2386@var{@1@} or to a blank string if @var{@1@} is not connected to a 2387terminal. 2388 2389Some non-GNU implementations of Fortran provide this intrinsic as 2390only a function, not as a subroutine. 2391") 2392 2393DEFDOC (SIGNAL_subr, "Muck with signal handling.", "\ 2394If @var{@2@} is a an @code{EXTERNAL} routine, arranges for it to be 2395invoked with a single integer argument (of system-dependent length) 2396when signal @var{@1@} occurs. 2397If @var{@2@} is an integer, it can be 2398used to turn off handling of signal @var{@1@} or revert to its default 2399action. 2400See @code{signal(2)}. 2401 2402Note that @var{@2@} will be called using C conventions, 2403so the value of its argument in Fortran terms 2404Fortran terms is obtained by applying @code{%LOC()} (or @code{LOC()}) to it. 2405 2406The value returned by @code{signal(2)} is written to @var{@3@}, if 2407that argument is supplied. 2408Otherwise the return value is ignored. 2409 2410Some non-GNU implementations of Fortran provide this intrinsic as 2411only a function, not as a subroutine, or do not support the 2412(optional) @var{@3@} argument. 2413 2414@emph{Warning:} Use of the @code{libf2c} run-time library function 2415@samp{signal_} directly 2416(such as via @samp{EXTERNAL SIGNAL}) 2417requires use of the @code{%VAL()} construct 2418to pass an @code{INTEGER} value 2419(such as @samp{SIG_IGN} or @samp{SIG_DFL}) 2420for the @var{@2@} argument. 2421 2422However, while @samp{CALL SIGNAL(@var{signum}, %VAL(SIG_IGN))} 2423works when @samp{SIGNAL} is treated as an external procedure 2424(and resolves, at link time, to @code{libf2c}'s @samp{signal_} routine), 2425this construct is not valid when @samp{SIGNAL} is recognized 2426as the intrinsic of that name. 2427 2428Therefore, for maximum portability and reliability, 2429code such references to the @samp{SIGNAL} facility as follows: 2430 2431@smallexample 2432INTRINSIC SIGNAL 2433@dots{} 2434CALL SIGNAL(@var{signum}, SIG_IGN) 2435@end smallexample 2436 2437@code{g77} will compile such a call correctly, 2438while other compilers will generally either do so as well 2439or reject the @samp{INTRINSIC SIGNAL} statement via a diagnostic, 2440allowing you to take appropriate action. 2441") 2442 2443DEFDOC (SIGNAL_func, "Muck with signal handling.", "\ 2444If @var{@2@} is a an @code{EXTERNAL} routine, arranges for it to be 2445invoked with a single integer argument (of system-dependent length) 2446when signal @var{@1@} occurs. 2447If @var{@2@} is an integer, it can be 2448used to turn off handling of signal @var{@1@} or revert to its default 2449action. 2450See @code{signal(2)}. 2451 2452Note that @var{@2@} will be called using C conventions, 2453so the value of its argument in Fortran terms 2454is obtained by applying @code{%LOC()} (or @code{LOC()}) to it. 2455 2456The value returned by @code{signal(2)} is returned. 2457 2458Due to the side effects performed by this intrinsic, the function 2459form is not recommended. 2460 2461@emph{Warning:} If the returned value is stored in 2462an @code{INTEGER(KIND=1)} (default @code{INTEGER}) argument, 2463truncation of the original return value occurs on some systems 2464(such as Alphas, which have 64-bit pointers but 32-bit default integers), 2465with no warning issued by @code{g77} under normal circumstances. 2466 2467Therefore, the following code fragment might silently fail on 2468some systems: 2469 2470@smallexample 2471INTEGER RTN 2472EXTERNAL MYHNDL 2473RTN = SIGNAL(@var{signum}, MYHNDL) 2474@dots{} 2475! Restore original handler: 2476RTN = SIGNAL(@var{signum}, RTN) 2477@end smallexample 2478 2479The reason for the failure is that @samp{RTN} might not hold 2480all the information on the original handler for the signal, 2481thus restoring an invalid handler. 2482This bug could manifest itself as a spurious run-time failure 2483at an arbitrary point later during the program's execution, 2484for example. 2485 2486@emph{Warning:} Use of the @code{libf2c} run-time library function 2487@samp{signal_} directly 2488(such as via @samp{EXTERNAL SIGNAL}) 2489requires use of the @code{%VAL()} construct 2490to pass an @code{INTEGER} value 2491(such as @samp{SIG_IGN} or @samp{SIG_DFL}) 2492for the @var{@2@} argument. 2493 2494However, while @samp{RTN = SIGNAL(@var{signum}, %VAL(SIG_IGN))} 2495works when @samp{SIGNAL} is treated as an external procedure 2496(and resolves, at link time, to @code{libf2c}'s @samp{signal_} routine), 2497this construct is not valid when @samp{SIGNAL} is recognized 2498as the intrinsic of that name. 2499 2500Therefore, for maximum portability and reliability, 2501code such references to the @samp{SIGNAL} facility as follows: 2502 2503@smallexample 2504INTRINSIC SIGNAL 2505@dots{} 2506RTN = SIGNAL(@var{signum}, SIG_IGN) 2507@end smallexample 2508 2509@code{g77} will compile such a call correctly, 2510while other compilers will generally either do so as well 2511or reject the @samp{INTRINSIC SIGNAL} statement via a diagnostic, 2512allowing you to take appropriate action. 2513") 2514 2515DEFDOC (KILL_func, "Signal a process.", "\ 2516Sends the signal specified by @var{@2@} to the process @var{@1@}. 2517Returns 0 on success or a nonzero error code. 2518See @code{kill(2)}. 2519 2520Due to the side effects performed by this intrinsic, the function 2521form is not recommended. 2522") 2523 2524DEFDOC (KILL_subr, "Signal a process.", "\ 2525Sends the signal specified by @var{@2@} to the process @var{@1@}. 2526If the @var{@3@} argument is supplied, it contains 25270 on success or a nonzero error code upon return. 2528See @code{kill(2)}. 2529 2530Some non-GNU implementations of Fortran provide this intrinsic as 2531only a function, not as a subroutine, or do not support the 2532(optional) @var{@3@} argument. 2533") 2534 2535DEFDOC (LNBLNK, "Get last non-blank character in string.", "\ 2536Returns the index of the last non-blank character in @var{@1@}. 2537@code{LNBLNK} and @code{LEN_TRIM} are equivalent. 2538") 2539 2540DEFDOC (SLEEP, "Sleep for a specified time.", "\ 2541Causes the process to pause for @var{@1@} seconds. 2542See @code{sleep(2)}. 2543") 2544 2545DEFDOC (SYSTEM_subr, "Invoke shell (system) command.", "\ 2546Passes the command @var{@1@} to a shell (see @code{system(3)}). 2547If argument @var{@2@} is present, it contains the value returned by 2548@code{system(3)}, presumably 0 if the shell command succeeded. 2549Note that which shell is used to invoke the command is system-dependent 2550and environment-dependent. 2551 2552Some non-GNU implementations of Fortran provide this intrinsic as 2553only a function, not as a subroutine, or do not support the 2554(optional) @var{@2@} argument. 2555") 2556 2557DEFDOC (SYSTEM_func, "Invoke shell (system) command.", "\ 2558Passes the command @var{@1@} to a shell (see @code{system(3)}). 2559Returns the value returned by 2560@code{system(3)}, presumably 0 if the shell command succeeded. 2561Note that which shell is used to invoke the command is system-dependent 2562and environment-dependent. 2563 2564Due to the side effects performed by this intrinsic, the function 2565form is not recommended. 2566However, the function form can be valid in cases where the 2567actual side effects performed by the call are unimportant to 2568the application. 2569 2570For example, on a UNIX system, @samp{SAME = SYSTEM('cmp a b')} 2571does not perform any side effects likely to be important to the 2572program, so the programmer would not care if the actual system 2573call (and invocation of @code{cmp}) was optimized away in a situation 2574where the return value could be determined otherwise, or was not 2575actually needed (@samp{SAME} not actually referenced after the 2576sample assignment statement). 2577") 2578 2579DEFDOC (TIME_vxt, "Get the time as a character value.", "\ 2580Returns in @var{@1@} a character representation of the current time as 2581obtained from @code{ctime(3)}. 2582 2583@cindex Y10K compliance 2584@cindex Year 10000 compliance 2585@cindex wraparound, Y10K 2586@cindex limits, Y10K 2587Programs making use of this intrinsic 2588might not be Year 10000 (Y10K) compliant. 2589For example, the date might appear, 2590to such programs, to wrap around 2591(change from a larger value to a smaller one) 2592as of the Year 10000. 2593 2594@xref{FDate Intrinsic (subroutine)}, for an equivalent routine. 2595") 2596 2597DEFDOC (IBCLR, "Clear a bit.", "\ 2598Returns the value of @var{@1@} with bit @var{@2@} cleared (set to 2599zero). 2600@xref{BTest Intrinsic}, for information on bit positions. 2601") 2602 2603DEFDOC (IBSET, "Set a bit.", "\ 2604Returns the value of @var{@1@} with bit @var{@2@} set (to one). 2605@xref{BTest Intrinsic}, for information on bit positions. 2606") 2607 2608DEFDOC (IBITS, "Extract a bit subfield of a variable.", "\ 2609Extracts a subfield of length @var{@3@} from @var{@1@}, starting from 2610bit position @var{@2@} and extending left for @var{@3@} bits. 2611The result is right-justified and the remaining bits are zeroed. 2612The value 2613of @samp{@var{@2@}+@var{@3@}} must be less than or equal to the value 2614@samp{BIT_SIZE(@var{@1@})}. 2615@xref{Bit_Size Intrinsic}. 2616") 2617 2618DEFDOC (ISHFT, "Logical bit shift.", "\ 2619All bits representing @var{@1@} are shifted @var{@2@} places. 2620@samp{@var{@2@}.GT.0} indicates a left shift, @samp{@var{@2@}.EQ.0} 2621indicates no shift and @samp{@var{@2@}.LT.0} indicates a right shift. 2622If the absolute value of the shift count is greater than 2623@samp{BIT_SIZE(@var{@1@})}, the result is undefined. 2624Bits shifted out from the left end or the right end are lost. 2625Zeros are shifted in from the opposite end. 2626 2627@xref{IShftC Intrinsic}, for the circular-shift equivalent. 2628") 2629 2630DEFDOC (ISHFTC, "Circular bit shift.", "\ 2631The rightmost @var{@3@} bits of the argument @var{@1@} 2632are shifted circularly @var{@2@} 2633places, i.e.@: the bits shifted out of one end are shifted into 2634the opposite end. 2635No bits are lost. 2636The unshifted bits of the result are the same as 2637the unshifted bits of @var{@1@}. 2638The absolute value of the argument @var{@2@} 2639must be less than or equal to @var{@3@}. 2640The value of @var{@3@} must be greater than or equal to one and less than 2641or equal to @samp{BIT_SIZE(@var{@1@})}. 2642 2643@xref{IShft Intrinsic}, for the logical shift equivalent. 2644") 2645 2646DEFDOC (MVBITS, "Moving a bit field.", "\ 2647Moves @var{@3@} bits from positions @var{@2@} through 2648@samp{@var{@2@}+@var{@3@}-1} of @var{@1@} to positions @var{@5@} through 2649@samp{@var{@2@}+@var{@3@}-1} of @var{@4@}. The portion of argument 2650@var{@4@} not affected by the movement of bits is unchanged. Arguments 2651@var{@1@} and @var{@4@} are permitted to be the same numeric storage 2652unit. The values of @samp{@var{@2@}+@var{@3@}} and 2653@samp{@var{@5@}+@var{@3@}} must be less than or equal to 2654@samp{BIT_SIZE(@var{@1@})}. 2655") 2656 2657DEFDOC (INDEX, "Locate a CHARACTER substring.", "\ 2658Returns the position of the start of the first occurrence of string 2659@var{@2@} as a substring in @var{@1@}, counting from one. 2660If @var{@2@} doesn't occur in @var{@1@}, zero is returned. 2661") 2662 2663DEFDOC (ALARM, "Execute a routine after a given delay.", "\ 2664Causes external subroutine @var{@2@} to be executed after a delay of 2665@var{@1@} seconds by using @code{alarm(1)} to set up a signal and 2666@code{signal(2)} to catch it. 2667If @var{@3@} is supplied, it will be 2668returned with the number of seconds remaining until any previously 2669scheduled alarm was due to be delivered, or zero if there was no 2670previously scheduled alarm. 2671@xref{Signal Intrinsic (subroutine)}. 2672") 2673 2674DEFDOC (DATE_AND_TIME, "Get the current date and time.", "\ 2675Returns: 2676@table @var 2677@item @1@ 2678The date in the form @var{ccyymmdd}: century, year, month and day; 2679@item @2@ 2680The time in the form @samp{@var{hhmmss.ss}}: hours, minutes, seconds 2681and milliseconds; 2682@item @3@ 2683The difference between local time and UTC (GMT) in the form @var{Shhmm}: 2684sign, hours and minutes, e.g.@: @samp{-0500} (winter in New York); 2685@item @4@ 2686The year, month of the year, day of the month, time difference in 2687minutes from UTC, hour of the day, minutes of the hour, seconds 2688of the minute, and milliseconds 2689of the second in successive values of the array. 2690@end table 2691 2692@cindex Y10K compliance 2693@cindex Year 10000 compliance 2694@cindex wraparound, Y10K 2695@cindex limits, Y10K 2696Programs making use of this intrinsic 2697might not be Year 10000 (Y10K) compliant. 2698For example, the date might appear, 2699to such programs, to wrap around 2700(change from a larger value to a smaller one) 2701as of the Year 10000. 2702 2703On systems where a millisecond timer isn't available, the millisecond 2704value is returned as zero. 2705") 2706