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