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