2 Copyright (C) 2005, 2006, 2007
3 Free Software Foundation, Inc.
4 This is part of the GNU Fortran manual.
5 For copying conditions, see the file gfortran.texi.
7 Permission is granted to copy, distribute and/or modify this document
8 under the terms of the GNU Free Documentation License, Version 1.2 or
9 any later version published by the Free Software Foundation; with the
10 Invariant Sections being ``GNU General Public License'' and ``Funding
11 Free Software'', the Front-Cover texts being (a) (see below), and with
12 the Back-Cover Texts being (b) (see below). A copy of the license is
13 included in the gfdl(7) man page.
16 Some basic guidelines for editing this document:
18 (1) The intrinsic procedures are to be listed in alphabetical order.
19 (2) The generic name is to be used.
20 (3) The specific names are included in the function index and in a
21 table at the end of the node (See ABS entry).
22 (4) Try to maintain the same style for each entry.
28 \gdef\acos{\mathop{\rm acos}\nolimits}
29 \gdef\asin{\mathop{\rm asin}\nolimits}
30 \gdef\atan{\mathop{\rm atan}\nolimits}
31 \gdef\acosh{\mathop{\rm acosh}\nolimits}
32 \gdef\asinh{\mathop{\rm asinh}\nolimits}
33 \gdef\atanh{\mathop{\rm atanh}\nolimits}
37 @node Intrinsic Procedures
38 @chapter Intrinsic Procedures
39 @cindex intrinsic procedures
42 * Introduction: Introduction to Intrinsics
43 * @code{ABORT}: ABORT, Abort the program
44 * @code{ABS}: ABS, Absolute value
45 * @code{ACCESS}: ACCESS, Checks file access modes
46 * @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence
47 * @code{ACOS}: ACOS, Arccosine function
48 * @code{ACOSH}: ACOSH, Hyperbolic arccosine function
49 * @code{ADJUSTL}: ADJUSTL, Left adjust a string
50 * @code{ADJUSTR}: ADJUSTR, Right adjust a string
51 * @code{AIMAG}: AIMAG, Imaginary part of complex number
52 * @code{AINT}: AINT, Truncate to a whole number
53 * @code{ALARM}: ALARM, Set an alarm clock
54 * @code{ALL}: ALL, Determine if all values are true
55 * @code{ALLOCATED}: ALLOCATED, Status of allocatable entity
56 * @code{AND}: AND, Bitwise logical AND
57 * @code{ANINT}: ANINT, Nearest whole number
58 * @code{ANY}: ANY, Determine if any values are true
59 * @code{ASIN}: ASIN, Arcsine function
60 * @code{ASINH}: ASINH, Hyperbolic arcsine function
61 * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair
62 * @code{ATAN}: ATAN, Arctangent function
63 * @code{ATAN2}: ATAN2, Arctangent function
64 * @code{ATANH}: ATANH, Hyperbolic arctangent function
65 * @code{BESJ0}: BESJ0, Bessel function of the first kind of order 0
66 * @code{BESJ1}: BESJ1, Bessel function of the first kind of order 1
67 * @code{BESJN}: BESJN, Bessel function of the first kind
68 * @code{BESY0}: BESY0, Bessel function of the second kind of order 0
69 * @code{BESY1}: BESY1, Bessel function of the second kind of order 1
70 * @code{BESYN}: BESYN, Bessel function of the second kind
71 * @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function
72 * @code{BTEST}: BTEST, Bit test function
73 * @code{CEILING}: CEILING, Integer ceiling function
74 * @code{CHAR}: CHAR, Integer-to-character conversion function
75 * @code{CHDIR}: CHDIR, Change working directory
76 * @code{CHMOD}: CHMOD, Change access permissions of files
77 * @code{CMPLX}: CMPLX, Complex conversion function
78 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
79 * @code{CONJG}: CONJG, Complex conjugate function
80 * @code{COS}: COS, Cosine function
81 * @code{COSH}: COSH, Hyperbolic cosine function
82 * @code{COUNT}: COUNT, Count occurrences of TRUE in an array
83 * @code{CPU_TIME}: CPU_TIME, CPU time subroutine
84 * @code{CSHIFT}: CSHIFT, Circular array shift function
85 * @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string
86 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
87 * @code{DBLE}: DBLE, Double precision conversion function
88 * @code{DCMPLX}: DCMPLX, Double complex conversion function
89 * @code{DFLOAT}: DFLOAT, Double precision conversion function
90 * @code{DIGITS}: DIGITS, Significant digits function
91 * @code{DIM}: DIM, Dim function
92 * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
93 * @code{DPROD}: DPROD, Double product function
94 * @code{DREAL}: DREAL, Double real part function
95 * @code{DTIME}: DTIME, Execution time subroutine (or function)
96 * @code{EOSHIFT}: EOSHIFT, End-off shift function
97 * @code{EPSILON}: EPSILON, Epsilon function
98 * @code{ERF}: ERF, Error function
99 * @code{ERFC}: ERFC, Complementary error function
100 * @code{ETIME}: ETIME, Execution time subroutine (or function)
101 * @code{EXIT}: EXIT, Exit the program with status.
102 * @code{EXP}: EXP, Exponential function
103 * @code{EXPONENT}: EXPONENT, Exponent function
104 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
105 * @code{FGET}: FGET, Read a single character in stream mode from stdin
106 * @code{FGETC}: FGETC, Read a single character in stream mode
107 * @code{FLOAT}: FLOAT, Convert integer to default real
108 * @code{FLOOR}: FLOOR, Integer floor function
109 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
110 * @code{FNUM}: FNUM, File number function
111 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
112 * @code{FPUTC}: FPUTC, Write a single character in stream mode
113 * @code{FRACTION}: FRACTION, Fractional part of the model representation
114 * @code{FREE}: FREE, Memory de-allocation subroutine
115 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
116 * @code{FSTAT}: FSTAT, Get file status
117 * @code{FTELL}: FTELL, Current stream position
118 * @code{GERROR}: GERROR, Get last system error message
119 * @code{GETARG}: GETARG, Get command line arguments
120 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
121 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
122 * @code{GETCWD}: GETCWD, Get current working directory
123 * @code{GETENV}: GETENV, Get an environmental variable
124 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
125 * @code{GETGID}: GETGID, Group ID function
126 * @code{GETLOG}: GETLOG, Get login name
127 * @code{GETPID}: GETPID, Process ID function
128 * @code{GETUID}: GETUID, User ID function
129 * @code{GMTIME}: GMTIME, Convert time to GMT info
130 * @code{HOSTNM}: HOSTNM, Get system host name
131 * @code{HUGE}: HUGE, Largest number of a kind
132 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
133 * @code{IAND}: IAND, Bitwise logical and
134 * @code{IARGC}: IARGC, Get the number of command line arguments
135 * @code{IBCLR}: IBCLR, Clear bit
136 * @code{IBITS}: IBITS, Bit extraction
137 * @code{IBSET}: IBSET, Set bit
138 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
139 * @code{IDATE}: IDATE, Current local time (day/month/year)
140 * @code{IEOR}: IEOR, Bitwise logical exclusive or
141 * @code{IERRNO}: IERRNO, Function to get the last system error number
142 * @code{INDEX}: INDEX, Position of a substring within a string
143 * @code{INT}: INT, Convert to integer type
144 * @code{INT2}: INT2, Convert to 16-bit integer type
145 * @code{INT8}: INT8, Convert to 64-bit integer type
146 * @code{IOR}: IOR, Bitwise logical or
147 * @code{IRAND}: IRAND, Integer pseudo-random number
148 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
149 * @code{ISHFT}: ISHFT, Shift bits
150 * @code{ISHFTC}: ISHFTC, Shift bits circularly
151 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
152 * @code{KILL}: KILL, Send a signal to a process
153 * @code{KIND}: KIND, Kind of an entity
154 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
155 * @code{LEN}: LEN, Length of a character entity
156 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
157 * @code{LGE}: LGE, Lexical greater than or equal
158 * @code{LGT}: LGT, Lexical greater than
159 * @code{LINK}: LINK, Create a hard link
160 * @code{LLE}: LLE, Lexical less than or equal
161 * @code{LLT}: LLT, Lexical less than
162 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
163 * @code{LOC}: LOC, Returns the address of a variable
164 * @code{LOG}: LOG, Logarithm function
165 * @code{LOG10}: LOG10, Base 10 logarithm function
166 * @code{LOGICAL}: LOGICAL, Convert to logical type
167 * @code{LONG}: LONG, Convert to integer type
168 * @code{LSHIFT}: LSHIFT, Left shift bits
169 * @code{LSTAT}: LSTAT, Get file status
170 * @code{LTIME}: LTIME, Convert time to local time info
171 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
172 * @code{MATMUL}: MATMUL, matrix multiplication
173 * @code{MAX}: MAX, Maximum value of an argument list
174 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
175 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
176 * @code{MAXVAL}: MAXVAL, Maximum value of an array
177 * @code{MCLOCK}: MCLOCK, Time function
178 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
179 * @code{MERGE}: MERGE, Merge arrays
180 * @code{MIN}: MIN, Minimum value of an argument list
181 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
182 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
183 * @code{MINVAL}: MINVAL, Minimum value of an array
184 * @code{MOD}: MOD, Remainder function
185 * @code{MODULO}: MODULO, Modulo function
186 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
187 * @code{MVBITS}: MVBITS, Move bits from one integer to another
188 * @code{NEAREST}: NEAREST, Nearest representable number
189 * @code{NEW_LINE}: NEW_LINE, New line character
190 * @code{NINT}: NINT, Nearest whole number
191 * @code{NOT}: NOT, Logical negation
192 * @code{NULL}: NULL, Function that returns an disassociated pointer
193 * @code{OR}: OR, Bitwise logical OR
194 * @code{PACK}: PACK, Pack an array into an array of rank one
195 * @code{PERROR}: PERROR, Print system error message
196 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
197 * @code{PRESENT}: PRESENT, Determine whether an optional argument is specified
198 * @code{PRODUCT}: PRODUCT, Product of array elements
199 * @code{RADIX}: RADIX, Base of a data model
200 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
201 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
202 * @code{RAND}: RAND, Real pseudo-random number
203 * @code{RANGE}: RANGE, Decimal exponent range of a real kind
204 * @code{RAN}: RAN, Real pseudo-random number
205 * @code{REAL}: REAL, Convert to real type
206 * @code{RENAME}: RENAME, Rename a file
207 * @code{REPEAT}: REPEAT, Repeated string concatenation
208 * @code{RESHAPE}: RESHAPE, Function to reshape an array
209 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
210 * @code{RSHIFT}: RSHIFT, Right shift bits
211 * @code{SCALE}: SCALE, Scale a real value
212 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
213 * @code{SECNDS}: SECNDS, Time function
214 * @code{SECOND}: SECOND, CPU time function
215 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
216 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
217 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
218 * @code{SHAPE}: SHAPE, Determine the shape of an array
219 * @code{SIGN}: SIGN, Sign copying function
220 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
221 * @code{SIN}: SIN, Sine function
222 * @code{SINH}: SINH, Hyperbolic sine function
223 * @code{SIZE}: SIZE, Function to determine the size of an array
224 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
225 * @code{SNGL}: SNGL, Convert double precision real to default real
226 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
227 * @code{SPREAD}: SPREAD, Add a dimension to an array
228 * @code{SQRT}: SQRT, Square-root function
229 * @code{SRAND}: SRAND, Reinitialize the random number generator
230 * @code{STAT}: STAT, Get file status
231 * @code{SUM}: SUM, Sum of array elements
232 * @code{SYMLNK}: SYMLNK, Create a symbolic link
233 * @code{SYSTEM}: SYSTEM, Execute a shell command
234 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
235 * @code{TAN}: TAN, Tangent function
236 * @code{TANH}: TANH, Hyperbolic tangent function
237 * @code{TIME}: TIME, Time function
238 * @code{TIME8}: TIME8, Time function (64-bit)
239 * @code{TINY}: TINY, Smallest positive number of a real kind
240 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
241 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
242 * @code{TRIM}: TRIM, Function to remove trailing blank characters of a string
243 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
244 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
245 * @code{UMASK}: UMASK, Set the file creation mask
246 * @code{UNLINK}: UNLINK, Remove a file from the file system
247 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
248 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
249 * @code{XOR}: XOR, Bitwise logical exclusive or
252 @node Introduction to Intrinsics
253 @section Introduction to intrinsic procedures
255 The intrinsic procedures provided by GNU Fortran include all of the
256 intrinsic procedures required by the Fortran 95 standard, a set of
257 intrinsic procedures for backwards compatibility with G77, and a small
258 selection of intrinsic procedures from the Fortran 2003 standard. Any
259 conflict between a description here and a description in either the
260 Fortran 95 standard or the Fortran 2003 standard is unintentional, and
261 the standard(s) should be considered authoritative.
263 The enumeration of the @code{KIND} type parameter is processor defined in
264 the Fortran 95 standard. GNU Fortran defines the default integer type and
265 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
266 respectively. The standard mandates that both data types shall have
267 another kind, which have more precision. On typical target architectures
268 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
269 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
270 In the description of generic intrinsic procedures, the kind type parameter
271 will be specified by @code{KIND=*}, and in the description of specific
272 names for an intrinsic procedure the kind type parameter will be explicitly
273 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
274 brevity the optional @code{KIND=} syntax will be omitted.
276 Many of the intrinsic procedures take one or more optional arguments.
277 This document follows the convention used in the Fortran 95 standard,
278 and denotes such arguments by square brackets.
280 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
281 which can be used to restrict the set of intrinsic procedures to a
282 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
283 option, and so all intrinsic procedures described here are accepted. There
284 is one caveat. For a select group of intrinsic procedures, @command{g77}
285 implemented both a function and a subroutine. Both classes
286 have been implemented in @command{gfortran} for backwards compatibility
287 with @command{g77}. It is noted here that these functions and subroutines
288 cannot be intermixed in a given subprogram. In the descriptions that follow,
289 the applicable standard for each intrinsic procedure is noted.
294 @section @code{ABORT} --- Abort the program
295 @cindex @code{ABORT} intrinsic
299 @item @emph{Description}:
300 @code{ABORT} causes immediate termination of the program. On operating
301 systems that support a core dump, @code{ABORT} will produce a core dump,
302 which is suitable for debugging purposes.
304 @item @emph{Standard}:
308 Non-elemental subroutine
313 @item @emph{Return value}:
316 @item @emph{Example}:
319 integer :: i = 1, j = 2
320 if (i /= j) call abort
321 end program test_abort
324 @item @emph{See also}:
325 @ref{EXIT}, @ref{KILL}
332 @section @code{ABS} --- Absolute value
333 @cindex @code{ABS} intrinsic
334 @cindex @code{CABS} intrinsic
335 @cindex @code{DABS} intrinsic
336 @cindex @code{IABS} intrinsic
337 @cindex @code{ZABS} intrinsic
338 @cindex @code{CDABS} intrinsic
339 @cindex absolute value
342 @item @emph{Description}:
343 @code{ABS(X)} computes the absolute value of @code{X}.
345 @item @emph{Standard}:
346 F77 and later, has overloads that are GNU extensions
352 @code{RESULT = ABS(X)}
354 @item @emph{Arguments}:
355 @multitable @columnfractions .15 .70
356 @item @var{X} @tab The type of the argument shall be an @code{INTEGER(*)},
357 @code{REAL(*)}, or @code{COMPLEX(*)}.
360 @item @emph{Return value}:
361 The return value is of the same type and
362 kind as the argument except the return value is @code{REAL(*)} for a
363 @code{COMPLEX(*)} argument.
365 @item @emph{Example}:
370 complex :: z = (-1.e0,0.e0)
377 @item @emph{Specific names}:
378 @multitable @columnfractions .20 .20 .20 .25
379 @item Name @tab Argument @tab Return type @tab Standard
380 @item @code{CABS(Z)} @tab @code{COMPLEX(4) Z} @tab @code{REAL(4)} @tab F77 and later
381 @item @code{DABS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
382 @item @code{IABS(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab F77 and later
383 @item @code{ZABS(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
384 @item @code{CDABS(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
391 @section @code{ACCESS} --- Checks file access modes
392 @cindex @code{ACCESS}
393 @cindex file system operations
396 @item @emph{Description}:
397 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
398 exists, is readable, writable or executable. Except for the
399 executable check, @code{ACCESS} can be replaced by
400 Fortran 95's @code{INQUIRE}.
402 @item @emph{Standard}:
409 @code{RESULT = ACCESS(NAME, MODE)}
411 @item @emph{Arguments}:
412 @multitable @columnfractions .15 .70
413 @item @var{NAME} @tab Scalar @code{CHARACTER} with the file name.
414 Tailing blank are ignored unless the character @code{achar(0)} is
415 present, then all characters up to and excluding @code{achar(0)} are
417 @item @var{MODE} @tab Scalar @code{CHARACTER} with the file access mode,
418 may be any concatenation of @code{"r"} (readable), @code{"w"} (writable)
419 and @code{"x"} (executable), or @code{" "} to check for existence.
422 @item @emph{Return value}:
423 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
424 accessible in the given mode; otherwise or if an invalid argument
425 has been given for @code{MODE} the value @code{1} is returned.
427 @item @emph{Example}:
431 character(len=*), parameter :: file = 'test.dat'
432 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
433 if(access(file,' ') == 0) print *, trim(file),' is exists'
434 if(access(file,'r') == 0) print *, trim(file),' is readable'
435 if(access(file,'w') == 0) print *, trim(file),' is writable'
436 if(access(file,'x') == 0) print *, trim(file),' is executable'
437 if(access(file2,'rwx') == 0) &
438 print *, trim(file2),' is readable, writable and executable'
439 end program access_test
441 @item @emph{Specific names}:
442 @item @emph{See also}:
449 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
450 @cindex @code{ACHAR} intrinsic
451 @cindex @acronym{ASCII} collating sequence
454 @item @emph{Description}:
455 @code{ACHAR(I)} returns the character located at position @code{I}
456 in the @acronym{ASCII} collating sequence.
458 @item @emph{Standard}:
465 @code{RESULT = ACHAR(I)}
467 @item @emph{Arguments}:
468 @multitable @columnfractions .15 .70
469 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
472 @item @emph{Return value}:
473 The return value is of type @code{CHARACTER} with a length of one. The
474 kind type parameter is the same as @code{KIND('A')}.
476 @item @emph{Example}:
481 end program test_achar
485 See @ref{ICHAR} for a discussion of converting between numerical values
486 and formatted string representations.
488 @item @emph{See also}:
489 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
496 @section @code{ACOS} --- Arccosine function
497 @cindex @code{ACOS} intrinsic
498 @cindex @code{DACOS} intrinsic
499 @cindex trigonometric functions (inverse)
502 @item @emph{Description}:
503 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
505 @item @emph{Standard}:
512 @code{RESULT = ACOS(X)}
514 @item @emph{Arguments}:
515 @multitable @columnfractions .15 .70
516 @item @var{X} @tab The type shall be @code{REAL(*)} with a magnitude that is
520 @item @emph{Return value}:
521 The return value is of type @code{REAL(*)} and it lies in the
522 range @math{ 0 \leq \acos(x) \leq \pi}. The kind type parameter
523 is the same as @var{X}.
525 @item @emph{Example}:
528 real(8) :: x = 0.866_8
530 end program test_acos
533 @item @emph{Specific names}:
534 @multitable @columnfractions .20 .20 .20 .25
535 @item Name @tab Argument @tab Return type @tab Standard
536 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
539 @item @emph{See also}:
540 Inverse function: @ref{COS}
547 @section @code{ACOSH} --- Hyperbolic arccosine function
548 @cindex @code{ACOSH} intrinsic
549 @cindex @code{DACOSH} intrinsic
550 @cindex hyperbolic arccosine
551 @cindex hyperbolic cosine (inverse)
554 @item @emph{Description}:
555 @code{ACOSH(X)} computes the hyperbolic arccosine of @var{X} (inverse of
558 @item @emph{Standard}:
565 @code{RESULT = ACOSH(X)}
567 @item @emph{Arguments}:
568 @multitable @columnfractions .15 .70
569 @item @var{X} @tab The type shall be @code{REAL(*)} with a magnitude that is
570 greater or equal to one.
573 @item @emph{Return value}:
574 The return value is of type @code{REAL(*)} and it lies in the
575 range @math{0 \leq \acosh (x) \leq \infty}.
577 @item @emph{Example}:
580 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
585 @item @emph{Specific names}:
586 @multitable @columnfractions .20 .20 .20 .25
587 @item Name @tab Argument @tab Return type @tab Standard
588 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
591 @item @emph{See also}:
592 Inverse function: @ref{COSH}
598 @section @code{ADJUSTL} --- Left adjust a string
599 @cindex @code{ADJUSTL} intrinsic
600 @cindex adjust string
603 @item @emph{Description}:
604 @code{ADJUSTL(STR)} will left adjust a string by removing leading spaces.
605 Spaces are inserted at the end of the string as needed.
607 @item @emph{Standard}:
614 @code{RESULT = ADJUSTL(STR)}
616 @item @emph{Arguments}:
617 @multitable @columnfractions .15 .70
618 @item @var{STR} @tab The type shall be @code{CHARACTER}.
621 @item @emph{Return value}:
622 The return value is of type @code{CHARACTER} where leading spaces
623 are removed and the same number of spaces are inserted on the end
626 @item @emph{Example}:
629 character(len=20) :: str = ' gfortran'
632 end program test_adjustl
639 @section @code{ADJUSTR} --- Right adjust a string
640 @cindex @code{ADJUSTR} intrinsic
641 @cindex adjust string
644 @item @emph{Description}:
645 @code{ADJUSTR(STR)} will right adjust a string by removing trailing spaces.
646 Spaces are inserted at the start of the string as needed.
648 @item @emph{Standard}:
655 @code{RESULT = ADJUSTR(STR)}
657 @item @emph{Arguments}:
658 @multitable @columnfractions .15 .70
659 @item @var{STR} @tab The type shall be @code{CHARACTER}.
662 @item @emph{Return value}:
663 The return value is of type @code{CHARACTER} where trailing spaces
664 are removed and the same number of spaces are inserted at the start
667 @item @emph{Example}:
670 character(len=20) :: str = 'gfortran'
673 end program test_adjustr
680 @section @code{AIMAG} --- Imaginary part of complex number
681 @cindex @code{AIMAG} intrinsic
682 @cindex @code{DIMAG} intrinsic
683 @cindex @code{IMAG} intrinsic
684 @cindex @code{IMAGPART} intrinsic
685 @cindex imaginary part of a complex number
688 @item @emph{Description}:
689 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
690 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
691 for compatibility with @command{g77}, and their use in new code is
692 strongly discouraged.
694 @item @emph{Standard}:
695 F77 and later, has overloads that are GNU extensions
701 @code{RESULT = AIMAG(Z)}
703 @item @emph{Arguments}:
704 @multitable @columnfractions .15 .70
705 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX(*)}.
708 @item @emph{Return value}:
709 The return value is of type real with the
710 kind type parameter of the argument.
712 @item @emph{Example}:
717 z4 = cmplx(1.e0_4, 0.e0_4)
718 z8 = cmplx(0.e0_8, 1.e0_8)
719 print *, aimag(z4), dimag(z8)
720 end program test_aimag
723 @item @emph{Specific names}:
724 @multitable @columnfractions .20 .20 .20 .25
725 @item Name @tab Argument @tab Return type @tab Standard
726 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
727 @item @code{IMAG(Z)} @tab @code{COMPLEX(*) Z} @tab @code{REAL(*)} @tab GNU extension
728 @item @code{IMAGPART(Z)} @tab @code{COMPLEX(*) Z} @tab @code{REAL(*)} @tab GNU extension
735 @section @code{AINT} --- Truncate to a whole number
736 @cindex @code{AINT} intrinsic
737 @cindex @code{DINT} intrinsic
741 @item @emph{Description}:
742 @code{AINT(X [, KIND])} truncates its argument to a whole number.
744 @item @emph{Standard}:
751 @code{RESULT = AINT(X [, KIND])}
753 @item @emph{Arguments}:
754 @multitable @columnfractions .15 .70
755 @item @var{X} @tab The type of the argument shall be @code{REAL(*)}.
756 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
757 expression indicating the kind parameter of
761 @item @emph{Return value}:
762 The return value is of type real with the kind type parameter of the
763 argument if the optional @var{KIND} is absent; otherwise, the kind
764 type parameter will be given by @var{KIND}. If the magnitude of
765 @var{X} is less than one, then @code{AINT(X)} returns zero. If the
766 magnitude is equal to or greater than one, then it returns the largest
767 whole number that does not exceed its magnitude. The sign is the same
768 as the sign of @var{X}.
770 @item @emph{Example}:
777 print *, aint(x4), dint(x8)
779 end program test_aint
782 @item @emph{Specific names}:
783 @multitable @columnfractions .20 .20 .20 .25
784 @item Name @tab Argument @tab Return type @tab Standard
785 @item @code{DINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
792 @section @code{ALARM} --- Execute a routine after a given delay
793 @cindex @code{ALARM} intrinsic
796 @item @emph{Description}:
797 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
798 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
799 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
800 supplied, it will be returned with the number of seconds remaining until
801 any previously scheduled alarm was due to be delivered, or zero if there
802 was no previously scheduled alarm.
804 @item @emph{Standard}:
811 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
813 @item @emph{Arguments}:
814 @multitable @columnfractions .15 .70
815 @item @var{SECONDS} @tab The type of the argument shall be a scalar
816 @code{INTEGER}. It is @code{INTENT(IN)}.
817 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
818 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
819 values may be either @code{SIG_IGN=1} to ignore the alarm generated
820 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
821 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
822 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
825 @item @emph{Example}:
828 external handler_print
830 call alarm (3, handler_print, i)
833 end program test_alarm
835 This will cause the external routine @var{handler_print} to be called
842 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
843 @cindex @code{ALL} intrinsic
847 @item @emph{Description}:
848 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
849 in the array along dimension @var{DIM}.
851 @item @emph{Standard}:
855 transformational function
858 @code{RESULT = ALL(MASK [, DIM])}
860 @item @emph{Arguments}:
861 @multitable @columnfractions .15 .70
862 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL(*)} and
863 it shall not be scalar.
864 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
865 with a value that lies between one and the rank of @var{MASK}.
868 @item @emph{Return value}:
869 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL(*)} where
870 the kind type parameter is the same as the kind type parameter of
871 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
872 an array with the rank of @var{MASK} minus 1. The shape is determined from
873 the shape of @var{MASK} where the @var{DIM} dimension is elided.
877 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
878 It also is true if @var{MASK} has zero size; otherwise, it is false.
880 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
881 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
882 is determined by applying @code{ALL} to the array sections.
885 @item @emph{Example}:
889 l = all((/.true., .true., .true./))
894 integer a(2,3), b(2,3)
898 print *, all(a .eq. b, 1)
899 print *, all(a .eq. b, 2)
900 end subroutine section
908 @section @code{ALLOCATED} --- Status of an allocatable entity
909 @cindex @code{ALLOCATED} intrinsic
910 @cindex allocation status
913 @item @emph{Description}:
914 @code{ALLOCATED(X)} checks the status of whether @var{X} is allocated.
916 @item @emph{Standard}:
923 @code{RESULT = ALLOCATED(X)}
925 @item @emph{Arguments}:
926 @multitable @columnfractions .15 .70
927 @item @var{X} @tab The argument shall be an @code{ALLOCATABLE} array.
930 @item @emph{Return value}:
931 The return value is a scalar @code{LOGICAL} with the default logical
932 kind type parameter. If @var{X} is allocated, @code{ALLOCATED(X)}
933 is @code{.TRUE.}; otherwise, it returns the @code{.TRUE.}
935 @item @emph{Example}:
937 program test_allocated
939 real(4), allocatable :: x(:)
940 if (allocated(x) .eqv. .false.) allocate(x(i))
941 end program test_allocated
948 @section @code{AND} --- Bitwise logical AND
949 @cindex @code{AND} intrinsic
950 @cindex bit operations
953 @item @emph{Description}:
954 Bitwise logical @code{AND}.
956 This intrinsic routine is provided for backwards compatibility with
957 GNU Fortran 77. For integer arguments, programmers should consider
958 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
960 @item @emph{Standard}:
964 Non-elemental function
967 @code{RESULT = AND(I, J)}
969 @item @emph{Arguments}:
970 @multitable @columnfractions .15 .70
971 @item @var{I} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
972 @item @var{J} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
975 @item @emph{Return value}:
976 The return type is either @code{INTEGER(*)} or @code{LOGICAL} after
977 cross-promotion of the arguments.
979 @item @emph{Example}:
982 LOGICAL :: T = .TRUE., F = ..FALSE.
984 DATA a / Z'F' /, b / Z'3' /
986 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
987 WRITE (*,*) AND(a, b)
991 @item @emph{See also}:
992 F95 elemental function: @ref{IAND}
998 @section @code{ANINT} --- Nearest whole number
999 @cindex @code{ANINT} intrinsic
1000 @cindex @code{DNINT} intrinsic
1001 @cindex whole number
1004 @item @emph{Description}:
1005 @code{ANINT(X [, KIND])} rounds its argument to the nearest whole number.
1007 @item @emph{Standard}:
1013 @item @emph{Syntax}:
1014 @code{RESULT = ANINT(X [, KIND])}
1016 @item @emph{Arguments}:
1017 @multitable @columnfractions .15 .70
1018 @item @var{X} @tab The type of the argument shall be @code{REAL(*)}.
1019 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
1020 expression indicating the kind parameter of
1024 @item @emph{Return value}:
1025 The return value is of type real with the kind type parameter of the
1026 argument if the optional @var{KIND} is absent; otherwise, the kind
1027 type parameter will be given by @var{KIND}. If @var{X} is greater than
1028 zero, then @code{ANINT(X)} returns @code{AINT(X+0.5)}. If @var{X} is
1029 less than or equal to zero, then it returns @code{AINT(X-0.5)}.
1031 @item @emph{Example}:
1038 print *, anint(x4), dnint(x8)
1040 end program test_anint
1043 @item @emph{Specific names}:
1044 @multitable @columnfractions .20 .20 .20 .25
1045 @item Name @tab Argument @tab Return type @tab Standard
1046 @item @code{DNINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1053 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1054 @cindex @code{ANY} intrinsic
1058 @item @emph{Description}:
1059 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1060 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1062 @item @emph{Standard}:
1066 transformational function
1068 @item @emph{Syntax}:
1069 @code{RESULT = ANY(MASK [, DIM])}
1071 @item @emph{Arguments}:
1072 @multitable @columnfractions .15 .70
1073 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL(*)} and
1074 it shall not be scalar.
1075 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1076 with a value that lies between one and the rank of @var{MASK}.
1079 @item @emph{Return value}:
1080 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL(*)} where
1081 the kind type parameter is the same as the kind type parameter of
1082 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1083 an array with the rank of @var{MASK} minus 1. The shape is determined from
1084 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1088 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1089 otherwise, it is false. It also is false if @var{MASK} has zero size.
1091 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1092 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1093 is determined by applying @code{ANY} to the array sections.
1096 @item @emph{Example}:
1100 l = any((/.true., .true., .true./))
1105 integer a(2,3), b(2,3)
1109 print *, any(a .eq. b, 1)
1110 print *, any(a .eq. b, 2)
1111 end subroutine section
1112 end program test_any
1119 @section @code{ASIN} --- Arcsine function
1120 @cindex @code{ASIN} intrinsic
1121 @cindex @code{DASIN} intrinsic
1122 @cindex trigonometric functions (inverse)
1125 @item @emph{Description}:
1126 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1128 @item @emph{Standard}:
1134 @item @emph{Syntax}:
1135 @code{RESULT = ASIN(X)}
1137 @item @emph{Arguments}:
1138 @multitable @columnfractions .15 .70
1139 @item @var{X} @tab The type shall be @code{REAL(*)}, and a magnitude that is
1143 @item @emph{Return value}:
1144 The return value is of type @code{REAL(*)} and it lies in the
1145 range @math{-\pi / 2 \leq \asin (x) \leq \pi / 2}. The kind type
1146 parameter is the same as @var{X}.
1148 @item @emph{Example}:
1151 real(8) :: x = 0.866_8
1153 end program test_asin
1156 @item @emph{Specific names}:
1157 @multitable @columnfractions .20 .20 .20 .25
1158 @item Name @tab Argument @tab Return type @tab Standard
1159 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1162 @item @emph{See also}:
1163 Inverse function: @ref{SIN}
1170 @section @code{ASINH} --- Hyperbolic arcsine function
1171 @cindex @code{ASINH} intrinsic
1172 @cindex @code{DASINH} intrinsic
1173 @cindex hyperbolic arcsine
1174 @cindex hyperbolic sine (inverse)
1177 @item @emph{Description}:
1178 @code{ASINH(X)} computes the hyperbolic arcsine of @var{X} (inverse of @code{SINH(X)}).
1180 @item @emph{Standard}:
1186 @item @emph{Syntax}:
1187 @code{RESULT = ASINH(X)}
1189 @item @emph{Arguments}:
1190 @multitable @columnfractions .15 .70
1191 @item @var{X} @tab The type shall be @code{REAL(*)}, with @var{X} a real number.
1194 @item @emph{Return value}:
1195 The return value is of type @code{REAL(*)} and it lies in the
1196 range @math{-\infty \leq \asinh (x) \leq \infty}.
1198 @item @emph{Example}:
1201 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1202 WRITE (*,*) ASINH(x)
1206 @item @emph{Specific names}:
1207 @multitable @columnfractions .20 .20 .20 .25
1208 @item Name @tab Argument @tab Return type @tab Standard
1209 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1212 @item @emph{See also}:
1213 Inverse function: @ref{SINH}
1219 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1220 @cindex @code{ASSOCIATED} intrinsic
1221 @cindex pointer status
1224 @item @emph{Description}:
1225 @code{ASSOCIATED(PTR [, TGT])} determines the status of the pointer @var{PTR}
1226 or if @var{PTR} is associated with the target @var{TGT}.
1228 @item @emph{Standard}:
1234 @item @emph{Syntax}:
1235 @code{RESULT = ASSOCIATED(PTR [, TGT])}
1237 @item @emph{Arguments}:
1238 @multitable @columnfractions .15 .70
1239 @item @var{PTR} @tab @var{PTR} shall have the @code{POINTER} attribute and
1240 it can be of any type.
1241 @item @var{TGT} @tab (Optional) @var{TGT} shall be a @code{POINTER} or
1242 a @code{TARGET}. It must have the same type, kind type parameter, and
1243 array rank as @var{PTR}.
1245 The status of neither @var{PTR} nor @var{TGT} can be undefined.
1247 @item @emph{Return value}:
1248 @code{ASSOCIATED(PTR)} returns a scalar value of type @code{LOGICAL(4)}.
1249 There are several cases:
1251 @item (A) If the optional @var{TGT} is not present, then @code{ASSOCIATED(PTR)}
1252 is true if @var{PTR} is associated with a target; otherwise, it returns false.
1253 @item (B) If @var{TGT} is present and a scalar target, the result is true if
1255 is not a 0 sized storage sequence and the target associated with @var{PTR}
1256 occupies the same storage units. If @var{PTR} is disassociated, then the
1258 @item (C) If @var{TGT} is present and an array target, the result is true if
1259 @var{TGT} and @var{PTR} have the same shape, are not 0 sized arrays, are
1260 arrays whose elements are not 0 sized storage sequences, and @var{TGT} and
1261 @var{PTR} occupy the same storage units in array element order.
1262 As in case(B), the result is false, if @var{PTR} is disassociated.
1263 @item (D) If @var{TGT} is present and an scalar pointer, the result is true if
1264 target associated with @var{PTR} and the target associated with @var{TGT}
1265 are not 0 sized storage sequences and occupy the same storage units.
1266 The result is false, if either @var{TGT} or @var{PTR} is disassociated.
1267 @item (E) If @var{TGT} is present and an array pointer, the result is true if
1268 target associated with @var{PTR} and the target associated with @var{TGT}
1269 have the same shape, are not 0 sized arrays, are arrays whose elements are
1270 not 0 sized storage sequences, and @var{TGT} and @var{PTR} occupy the same
1271 storage units in array element order.
1272 The result is false, if either @var{TGT} or @var{PTR} is disassociated.
1275 @item @emph{Example}:
1277 program test_associated
1279 real, target :: tgt(2) = (/1., 2./)
1280 real, pointer :: ptr(:)
1282 if (associated(ptr) .eqv. .false.) call abort
1283 if (associated(ptr,tgt) .eqv. .false.) call abort
1284 end program test_associated
1287 @item @emph{See also}:
1294 @section @code{ATAN} --- Arctangent function
1295 @cindex @code{ATAN} intrinsic
1296 @cindex @code{DATAN} intrinsic
1297 @cindex trigonometric functions (inverse)
1300 @item @emph{Description}:
1301 @code{ATAN(X)} computes the arctangent of @var{X}.
1303 @item @emph{Standard}:
1309 @item @emph{Syntax}:
1310 @code{RESULT = ATAN(X)}
1312 @item @emph{Arguments}:
1313 @multitable @columnfractions .15 .70
1314 @item @var{X} @tab The type shall be @code{REAL(*)}.
1317 @item @emph{Return value}:
1318 The return value is of type @code{REAL(*)} and it lies in the
1319 range @math{ - \pi / 2 \leq \atan (x) \leq \pi / 2}.
1321 @item @emph{Example}:
1324 real(8) :: x = 2.866_8
1326 end program test_atan
1329 @item @emph{Specific names}:
1330 @multitable @columnfractions .20 .20 .20 .25
1331 @item Name @tab Argument @tab Return type @tab Standard
1332 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1335 @item @emph{See also}:
1336 Inverse function: @ref{TAN}
1343 @section @code{ATAN2} --- Arctangent function
1344 @cindex @code{ATAN2} intrinsic
1345 @cindex @code{DATAN2} intrinsic
1346 @cindex trigonometric functions (inverse)
1349 @item @emph{Description}:
1350 @code{ATAN2(Y,X)} computes the arctangent of the complex number
1353 @item @emph{Standard}:
1359 @item @emph{Syntax}:
1360 @code{RESULT = ATAN2(Y,X)}
1362 @item @emph{Arguments}:
1363 @multitable @columnfractions .15 .70
1364 @item @var{Y} @tab The type shall be @code{REAL(*)}.
1365 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1366 If @var{Y} is zero, then @var{X} must be nonzero.
1369 @item @emph{Return value}:
1370 The return value has the same type and kind type parameter as @var{Y}.
1371 It is the principal value of the complex number @math{X + i Y}. If
1372 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1373 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1374 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1375 is negative. Finally, if @var{X} is zero, then the magnitude of the result
1378 @item @emph{Example}:
1381 real(4) :: x = 1.e0_4, y = 0.5e0_4
1383 end program test_atan2
1386 @item @emph{Specific names}:
1387 @multitable @columnfractions .20 .20 .20 .25
1388 @item Name @tab Argument @tab Return type @tab Standard
1389 @item @code{DATAN2(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1396 @section @code{ATANH} --- Hyperbolic arctangent function
1397 @cindex @code{ASINH} intrinsic
1398 @cindex @code{DASINH} intrinsic
1399 @cindex hyperbolic arctangent
1400 @cindex hyperbolic tangent (inverse)
1403 @item @emph{Description}:
1404 @code{ATANH(X)} computes the hyperbolic arctangent of @var{X} (inverse
1407 @item @emph{Standard}:
1413 @item @emph{Syntax}:
1414 @code{RESULT = ATANH(X)}
1416 @item @emph{Arguments}:
1417 @multitable @columnfractions .15 .70
1418 @item @var{X} @tab The type shall be @code{REAL(*)} with a magnitude
1419 that is less than or equal to one.
1422 @item @emph{Return value}:
1423 The return value is of type @code{REAL(*)} and it lies in the
1424 range @math{-\infty \leq \atanh(x) \leq \infty}.
1426 @item @emph{Example}:
1429 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1430 WRITE (*,*) ATANH(x)
1434 @item @emph{Specific names}:
1435 @multitable @columnfractions .20 .20 .20 .25
1436 @item Name @tab Argument @tab Return type @tab Standard
1437 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1440 @item @emph{See also}:
1441 Inverse function: @ref{TANH}
1447 @section @code{BESJ0} --- Bessel function of the first kind of order 0
1448 @cindex @code{BESJ0} intrinsic
1449 @cindex @code{DBESJ0} intrinsic
1453 @item @emph{Description}:
1454 @code{BESJ0(X)} computes the Bessel function of the first kind of order 0
1457 @item @emph{Standard}:
1463 @item @emph{Syntax}:
1464 @code{RESULT = BESJ0(X)}
1466 @item @emph{Arguments}:
1467 @multitable @columnfractions .15 .70
1468 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1471 @item @emph{Return value}:
1472 The return value is of type @code{REAL(*)} and it lies in the
1473 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}.
1475 @item @emph{Example}:
1478 real(8) :: x = 0.0_8
1480 end program test_besj0
1483 @item @emph{Specific names}:
1484 @multitable @columnfractions .20 .20 .20 .25
1485 @item Name @tab Argument @tab Return type @tab Standard
1486 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1493 @section @code{BESJ1} --- Bessel function of the first kind of order 1
1494 @cindex @code{BESJ1} intrinsic
1495 @cindex @code{DBESJ1} intrinsic
1499 @item @emph{Description}:
1500 @code{BESJ1(X)} computes the Bessel function of the first kind of order 1
1503 @item @emph{Standard}:
1509 @item @emph{Syntax}:
1510 @code{RESULT = BESJ1(X)}
1512 @item @emph{Arguments}:
1513 @multitable @columnfractions .15 .70
1514 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1517 @item @emph{Return value}:
1518 The return value is of type @code{REAL(*)} and it lies in the
1519 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }.
1521 @item @emph{Example}:
1524 real(8) :: x = 1.0_8
1526 end program test_besj1
1529 @item @emph{Specific names}:
1530 @multitable @columnfractions .20 .20 .20 .25
1531 @item Name @tab Argument @tab Return type @tab Standard
1532 @item @code{DBESJ1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1539 @section @code{BESJN} --- Bessel function of the first kind
1540 @cindex @code{BESJN} intrinsic
1541 @cindex @code{DBESJN} intrinsic
1545 @item @emph{Description}:
1546 @code{BESJN(N, X)} computes the Bessel function of the first kind of order
1549 @item @emph{Standard}:
1555 @item @emph{Syntax}:
1556 @code{RESULT = BESJN(N, X)}
1558 @item @emph{Arguments}:
1559 @multitable @columnfractions .15 .70
1560 @item @var{N} @tab The type shall be @code{INTEGER(*)}, and it shall be scalar.
1561 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1564 @item @emph{Return value}:
1565 The return value is a scalar of type @code{REAL(*)}.
1567 @item @emph{Example}:
1570 real(8) :: x = 1.0_8
1572 end program test_besjn
1575 @item @emph{Specific names}:
1576 @multitable @columnfractions .20 .20 .20 .25
1577 @item Name @tab Argument @tab Return type @tab Standard
1578 @item @code{DBESJN(X)} @tab @code{INTEGER(*) N} @tab @code{REAL(8)} @tab GNU extension
1579 @item @tab @code{REAL(8) X} @tab @tab
1586 @section @code{BESY0} --- Bessel function of the second kind of order 0
1587 @cindex @code{BESY0} intrinsic
1588 @cindex @code{DBESY0} intrinsic
1592 @item @emph{Description}:
1593 @code{BESY0(X)} computes the Bessel function of the second kind of order 0
1596 @item @emph{Standard}:
1602 @item @emph{Syntax}:
1603 @code{RESULT = BESY0(X)}
1605 @item @emph{Arguments}:
1606 @multitable @columnfractions .15 .70
1607 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1610 @item @emph{Return value}:
1611 The return value is a scalar of type @code{REAL(*)}.
1613 @item @emph{Example}:
1616 real(8) :: x = 0.0_8
1618 end program test_besy0
1621 @item @emph{Specific names}:
1622 @multitable @columnfractions .20 .20 .20 .25
1623 @item Name @tab Argument @tab Return type @tab Standard
1624 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1631 @section @code{BESY1} --- Bessel function of the second kind of order 1
1632 @cindex @code{BESY1} intrinsic
1633 @cindex @code{DBESY1} intrinsic
1637 @item @emph{Description}:
1638 @code{BESY1(X)} computes the Bessel function of the second kind of order 1
1641 @item @emph{Standard}:
1647 @item @emph{Syntax}:
1648 @code{RESULT = BESY1(X)}
1650 @item @emph{Arguments}:
1651 @multitable @columnfractions .15 .70
1652 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1655 @item @emph{Return value}:
1656 The return value is a scalar of type @code{REAL(*)}.
1658 @item @emph{Example}:
1661 real(8) :: x = 1.0_8
1663 end program test_besy1
1666 @item @emph{Specific names}:
1667 @multitable @columnfractions .20 .20 .20 .25
1668 @item Name @tab Argument @tab Return type @tab Standard
1669 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1676 @section @code{BESYN} --- Bessel function of the second kind
1677 @cindex @code{BESYN} intrinsic
1678 @cindex @code{DBESYN} intrinsic
1682 @item @emph{Description}:
1683 @code{BESYN(N, X)} computes the Bessel function of the second kind of order
1686 @item @emph{Standard}:
1692 @item @emph{Syntax}:
1693 @code{RESULT = BESYN(N, X)}
1695 @item @emph{Arguments}:
1696 @multitable @columnfractions .15 .70
1697 @item @var{N} @tab The type shall be @code{INTEGER(*)}, and it shall be scalar.
1698 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1701 @item @emph{Return value}:
1702 The return value is a scalar of type @code{REAL(*)}.
1704 @item @emph{Example}:
1707 real(8) :: x = 1.0_8
1709 end program test_besyn
1712 @item @emph{Specific names}:
1713 @multitable @columnfractions .20 .20 .20 .25
1714 @item Name @tab Argument @tab Return type @tab Standard
1715 @item @code{DBESYN(N,X)} @tab @code{INTEGER(*) N} @tab @code{REAL(8)} @tab GNU extension
1716 @item @tab @code{REAL(8) X} @tab @tab
1723 @section @code{BIT_SIZE} --- Bit size inquiry function
1724 @cindex @code{BIT_SIZE} intrinsic
1725 @cindex bit size of a variable
1726 @cindex size of a variable, in bits
1729 @item @emph{Description}:
1730 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1731 represented by the type of @var{I}.
1733 @item @emph{Standard}:
1739 @item @emph{Syntax}:
1740 @code{RESULT = BIT_SIZE(I)}
1742 @item @emph{Arguments}:
1743 @multitable @columnfractions .15 .70
1744 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
1747 @item @emph{Return value}:
1748 The return value is of type @code{INTEGER(*)}
1750 @item @emph{Example}:
1752 program test_bit_size
1757 end program test_bit_size
1764 @section @code{BTEST} --- Bit test function
1765 @cindex @code{BTEST} intrinsic
1766 @cindex bit operations
1769 @item @emph{Description}:
1770 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
1773 @item @emph{Standard}:
1779 @item @emph{Syntax}:
1780 @code{RESULT = BTEST(I, POS)}
1782 @item @emph{Arguments}:
1783 @multitable @columnfractions .15 .70
1784 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
1785 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
1788 @item @emph{Return value}:
1789 The return value is of type @code{LOGICAL}
1791 @item @emph{Example}:
1794 integer :: i = 32768 + 1024 + 64
1798 bool = btest(i, pos)
1801 end program test_btest
1808 @section @code{CEILING} --- Integer ceiling function
1809 @cindex @code{CEILING} intrinsic
1813 @item @emph{Description}:
1814 @code{CEILING(X)} returns the least integer greater than or equal to @var{X}.
1816 @item @emph{Standard}:
1822 @item @emph{Syntax}:
1823 @code{RESULT = CEILING(X [, KIND])}
1825 @item @emph{Arguments}:
1826 @multitable @columnfractions .15 .70
1827 @item @var{X} @tab The type shall be @code{REAL(*)}.
1828 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
1829 expression indicating the kind parameter of
1833 @item @emph{Return value}:
1834 The return value is of type @code{INTEGER(KIND)}
1836 @item @emph{Example}:
1838 program test_ceiling
1841 print *, ceiling(x) ! returns 64
1842 print *, ceiling(y) ! returns -63
1843 end program test_ceiling
1846 @item @emph{See also}:
1847 @ref{FLOOR}, @ref{NINT}
1854 @section @code{CHAR} --- Character conversion function
1855 @cindex @code{CHAR} intrinsic
1856 @cindex conversion function (character)
1859 @item @emph{Description}:
1860 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
1862 @item @emph{Standard}:
1868 @item @emph{Syntax}:
1869 @code{RESULT = CHAR(I [, KIND])}
1871 @item @emph{Arguments}:
1872 @multitable @columnfractions .15 .70
1873 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
1874 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
1875 expression indicating the kind parameter of
1879 @item @emph{Return value}:
1880 The return value is of type @code{CHARACTER(1)}
1882 @item @emph{Example}:
1888 print *, i, c ! returns 'J'
1889 end program test_char
1893 See @ref{ICHAR} for a discussion of converting between numerical values
1894 and formatted string representations.
1896 @item @emph{See also}:
1897 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
1904 @section @code{CHDIR} --- Change working directory
1905 @cindex @code{CHDIR} intrinsic
1906 @cindex file system operations
1909 @item @emph{Description}:
1910 Change current working directory to a specified path.
1912 This intrinsic is provided in both subroutine and function forms; however,
1913 only one form can be used in any given program unit.
1915 @item @emph{Standard}:
1919 Subroutine, non-elemental function
1921 @item @emph{Syntax}:
1922 @multitable @columnfractions .80
1923 @item @code{CALL CHDIR(NAME [, STATUS])}
1924 @item @code{STATUS = CHDIR(NAME)}
1927 @item @emph{Arguments}:
1928 @multitable @columnfractions .15 .70
1929 @item @var{NAME} @tab The type shall be @code{CHARACTER(*)} and shall
1930 specify a valid path within the file system.
1931 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
1932 kind. Returns 0 on success, and a system specific
1933 and non-zero error code otherwise.
1936 @item @emph{Example}:
1939 CHARACTER(len=255) :: path
1941 WRITE(*,*) TRIM(path)
1944 WRITE(*,*) TRIM(path)
1948 @item @emph{See also}:
1955 @section @code{CHMOD} --- Change access permissions of files
1956 @cindex @code{CHMOD} intrinsic
1957 @cindex file system operations
1960 @item @emph{Description}:
1961 @code{CHMOD} changes the permissions of a file. This function invokes
1962 @code{/bin/chmod} and might therefore not work on all platforms.
1964 This intrinsic is provided in both subroutine and function forms; however,
1965 only one form can be used in any given program unit.
1967 @item @emph{Standard}:
1971 Subroutine, non-elemental function
1973 @item @emph{Syntax}:
1974 @multitable @columnfractions .80
1975 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
1976 @item @code{STATUS = CHMOD(NAME, MODE)}
1979 @item @emph{Arguments}:
1980 @multitable @columnfractions .15 .70
1981 @item @var{NAME} @tab Scalar @code{CHARACTER} with the file name.
1982 Trailing blanks are ignored unless the character @code{achar(0)} is
1983 present, then all characters up to and excluding @code{achar(0)} are
1984 used as the file name.
1986 @item @var{MODE} @tab Scalar @code{CHARACTER} giving the file permission.
1987 @var{MODE} uses the same syntax as the @var{MODE} argument of
1990 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
1991 @code{0} on success and non-zero otherwise.
1994 @item @emph{Return value}:
1995 In either syntax, @var{STATUS} is set to @code{0} on success and non-zero
1998 @item @emph{Example}:
1999 @code{CHMOD} as subroutine
2004 call chmod('test.dat','u+x',status)
2005 print *, 'Status: ', status
2006 end program chmod_test
2008 @code{CHMOD} as non-elemental function:
2013 status = chmod('test.dat','u+x')
2014 print *, 'Status: ', status
2015 end program chmod_test
2023 @section @code{CMPLX} --- Complex conversion function
2024 @cindex @code{CMPLX} intrinsic
2025 @cindex complex numbers, conversion to
2028 @item @emph{Description}:
2029 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2030 the real component. If @var{Y} is present it is converted to the imaginary
2031 component. If @var{Y} is not present then the imaginary component is set to
2032 0.0. If @var{X} is complex then @var{Y} must not be present.
2034 @item @emph{Standard}:
2040 @item @emph{Syntax}:
2041 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2043 @item @emph{Arguments}:
2044 @multitable @columnfractions .15 .70
2045 @item @var{X} @tab The type may be @code{INTEGER(*)}, @code{REAL(*)},
2046 or @code{COMPLEX(*)}.
2047 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2048 @code{COMPLEX(*)}.) May be @code{INTEGER(*)}
2050 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
2051 expression indicating the kind parameter of
2055 @item @emph{Return value}:
2056 The return value is of type @code{COMPLEX(*)}
2058 @item @emph{Example}:
2065 print *, z, cmplx(x)
2066 end program test_cmplx
2072 @node COMMAND_ARGUMENT_COUNT
2073 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2074 @cindex @code{COMMAND_ARGUMENT_COUNT} intrinsic
2075 @cindex command-line arguments, to program
2078 @item @emph{Description}:
2079 @code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the
2080 command line when the containing program was invoked.
2082 @item @emph{Standard}:
2088 @item @emph{Syntax}:
2089 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2091 @item @emph{Arguments}:
2092 @multitable @columnfractions .15 .70
2096 @item @emph{Return value}:
2097 The return value is of type @code{INTEGER(4)}
2099 @item @emph{Example}:
2101 program test_command_argument_count
2103 count = command_argument_count()
2105 end program test_command_argument_count
2108 @item @emph{See also}:
2109 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2115 @section @code{CONJG} --- Complex conjugate function
2116 @cindex @code{CONJG} intrinsic
2117 @cindex @code{DCONJG} intrinsic
2118 @cindex complex conjugate
2120 @item @emph{Description}:
2121 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
2122 then the result is @code{(x, -y)}
2124 @item @emph{Standard}:
2125 F77 and later, has overloads that are GNU extensions
2130 @item @emph{Syntax}:
2133 @item @emph{Arguments}:
2134 @multitable @columnfractions .15 .70
2135 @item @var{Z} @tab The type shall be @code{COMPLEX(*)}.
2138 @item @emph{Return value}:
2139 The return value is of type @code{COMPLEX(*)}.
2141 @item @emph{Example}:
2144 complex :: z = (2.0, 3.0)
2145 complex(8) :: dz = (2.71_8, -3.14_8)
2150 end program test_conjg
2153 @item @emph{Specific names}:
2154 @multitable @columnfractions .20 .20 .20 .25
2155 @item Name @tab Argument @tab Return type @tab Standard
2156 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
2163 @section @code{COS} --- Cosine function
2164 @cindex @code{COS} intrinsic
2165 @cindex @code{DCOS} intrinsic
2166 @cindex @code{CCOS} intrinsic
2167 @cindex @code{ZCOS} intrinsic
2168 @cindex @code{CDCOS} intrinsic
2169 @cindex trigonometric functions
2172 @item @emph{Description}:
2173 @code{COS(X)} computes the cosine of @var{X}.
2175 @item @emph{Standard}:
2176 F77 and later, has overloads that are GNU extensions
2181 @item @emph{Syntax}:
2182 @code{RESULT = COS(X)}
2184 @item @emph{Arguments}:
2185 @multitable @columnfractions .15 .70
2186 @item @var{X} @tab The type shall be @code{REAL(*)} or
2190 @item @emph{Return value}:
2191 The return value is of type @code{REAL(*)} and it lies in the
2192 range @math{ -1 \leq \cos (x) \leq 1}. The kind type
2193 parameter is the same as @var{X}.
2195 @item @emph{Example}:
2200 end program test_cos
2203 @item @emph{Specific names}:
2204 @multitable @columnfractions .20 .20 .20 .25
2205 @item Name @tab Argument @tab Return type @tab Standard
2206 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
2207 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab F77 and later
2208 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2209 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2212 @item @emph{See also}:
2213 Inverse function: @ref{ACOS}
2220 @section @code{COSH} --- Hyperbolic cosine function
2221 @cindex @code{COSH} intrinsic
2222 @cindex @code{DCOSH} intrinsic
2223 @cindex hyperbolic cosine
2226 @item @emph{Description}:
2227 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2229 @item @emph{Standard}:
2235 @item @emph{Syntax}:
2238 @item @emph{Arguments}:
2239 @multitable @columnfractions .15 .70
2240 @item @var{X} @tab The type shall be @code{REAL(*)}.
2243 @item @emph{Return value}:
2244 The return value is of type @code{REAL(*)} and it is positive
2245 (@math{ \cosh (x) \geq 0 }.
2247 @item @emph{Example}:
2250 real(8) :: x = 1.0_8
2252 end program test_cosh
2255 @item @emph{Specific names}:
2256 @multitable @columnfractions .20 .20 .20 .25
2257 @item Name @tab Argument @tab Return type @tab Standard
2258 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
2261 @item @emph{See also}:
2262 Inverse function: @ref{ACOSH}
2269 @section @code{COUNT} --- Count function
2270 @cindex @code{COUNT} intrinsic
2274 @item @emph{Description}:
2275 @code{COUNT(MASK [, DIM])} counts the number of @code{.TRUE.} elements of
2276 @var{MASK} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
2277 taken to be @code{1}. @var{DIM} is a scaler of type @code{INTEGER} in the
2278 range of @math{1 /leq DIM /leq n)} where @math{n} is the rank of @var{MASK}.
2280 @item @emph{Standard}:
2284 transformational function
2286 @item @emph{Syntax}:
2287 @code{RESULT = COUNT(MASK [, DIM])}
2289 @item @emph{Arguments}:
2290 @multitable @columnfractions .15 .70
2291 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
2292 @item @var{DIM} @tab The type shall be @code{INTEGER}.
2295 @item @emph{Return value}:
2296 The return value is of type @code{INTEGER} with rank equal to that of
2299 @item @emph{Example}:
2302 integer, dimension(2,3) :: a, b
2303 logical, dimension(2,3) :: mask
2304 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
2305 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
2306 print '(3i3)', a(1,:)
2307 print '(3i3)', a(2,:)
2309 print '(3i3)', b(1,:)
2310 print '(3i3)', b(2,:)
2313 print '(3l3)', mask(1,:)
2314 print '(3l3)', mask(2,:)
2316 print '(3i3)', count(mask)
2318 print '(3i3)', count(mask, 1)
2320 print '(3i3)', count(mask, 2)
2321 end program test_count
2328 @section @code{CPU_TIME} --- CPU elapsed time in seconds
2329 @cindex @code{CPU_TIME} intrinsic
2330 @cindex time, elapsed
2331 @cindex elapsed time
2334 @item @emph{Description}:
2335 Returns a @code{REAL(*)} value representing the elapsed CPU time in
2336 seconds. This is useful for testing segments of code to determine
2339 @item @emph{Standard}:
2345 @item @emph{Syntax}:
2346 @code{CALL CPU_TIME(TIME)}
2348 @item @emph{Arguments}:
2349 @multitable @columnfractions .15 .70
2350 @item @var{TIME} @tab The type shall be @code{REAL(*)} with @code{INTENT(OUT)}.
2353 @item @emph{Return value}:
2356 @item @emph{Example}:
2358 program test_cpu_time
2359 real :: start, finish
2360 call cpu_time(start)
2361 ! put code to test here
2362 call cpu_time(finish)
2363 print '("Time = ",f6.3," seconds.")',finish-start
2364 end program test_cpu_time
2371 @section @code{CSHIFT} --- Circular shift function
2372 @cindex @code{CSHIFT} intrinsic
2373 @cindex bit operations
2376 @item @emph{Description}:
2377 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
2378 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
2379 taken to be @code{1}. @var{DIM} is a scaler of type @code{INTEGER} in the
2380 range of @math{1 /leq DIM /leq n)} where @math{n} is the rank of @var{ARRAY}.
2381 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
2382 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
2383 sections of @var{ARRAY} along the given dimension are shifted. Elements
2384 shifted out one end of each rank one section are shifted back in the other end.
2386 @item @emph{Standard}:
2390 transformational function
2392 @item @emph{Syntax}:
2393 @code{RESULT = CSHIFT(A, SHIFT [, DIM])}
2395 @item @emph{Arguments}:
2396 @multitable @columnfractions .15 .70
2397 @item @var{ARRAY} @tab May be any type, not scaler.
2398 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
2399 @item @var{DIM} @tab The type shall be @code{INTEGER}.
2402 @item @emph{Return value}:
2403 Returns an array of same type and rank as the @var{ARRAY} argument.
2405 @item @emph{Example}:
2408 integer, dimension(3,3) :: a
2409 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
2410 print '(3i3)', a(1,:)
2411 print '(3i3)', a(2,:)
2412 print '(3i3)', a(3,:)
2413 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
2415 print '(3i3)', a(1,:)
2416 print '(3i3)', a(2,:)
2417 print '(3i3)', a(3,:)
2418 end program test_cshift
2425 @section @code{CTIME} --- Convert a time into a string
2426 @cindex @code{CTIME} intrinsic
2427 @cindex time, conversion function
2430 @item @emph{Description}:
2431 @code{CTIME} converts a system time value, such as returned by
2432 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
2434 This intrinsic is provided in both subroutine and function forms; however,
2435 only one form can be used in any given program unit.
2437 @item @emph{Standard}:
2443 @item @emph{Syntax}:
2444 @multitable @columnfractions .80
2445 @item @code{CALL CTIME(TIME, RESULT)}.
2446 @item @code{RESULT = CTIME(TIME)}, (not recommended).
2449 @item @emph{Arguments}:
2450 @multitable @columnfractions .15 .70
2451 @item @var{TIME} @tab The type shall be of type @code{INTEGER(KIND=8)}.
2452 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER}.
2455 @item @emph{Return value}:
2456 The converted date and time as a string.
2458 @item @emph{Example}:
2462 character(len=30) :: date
2465 ! Do something, main part of the program
2468 print *, 'Program was started on ', date
2469 end program test_ctime
2472 @item @emph{See Also}:
2473 @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
2480 @section @code{DATE_AND_TIME} --- Date and time subroutine
2481 @cindex @code{DATE_AND_TIME} intrinsic
2482 @cindex date, current
2483 @cindex current date
2484 @cindex time, current
2485 @cindex current time
2488 @item @emph{Description}:
2489 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
2490 time information from the real-time system clock. @var{DATE} is
2491 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
2492 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
2493 representing the difference with respect to Coordinated Universal Time (UTC).
2494 Unavailable time and date parameters return blanks.
2496 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
2498 @multitable @columnfractions .15 .30 .40
2499 @item @tab @code{VALUE(1)}: @tab The year
2500 @item @tab @code{VALUE(2)}: @tab The month
2501 @item @tab @code{VALUE(3)}: @tab The day of the month
2502 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
2503 @item @tab @code{VALUE(5)}: @tab The hour of the day
2504 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
2505 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
2506 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
2509 @item @emph{Standard}:
2515 @item @emph{Syntax}:
2516 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
2518 @item @emph{Arguments}:
2519 @multitable @columnfractions .15 .70
2520 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(8)} or larger.
2521 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(10)} or larger.
2522 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(5)} or larger.
2523 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
2526 @item @emph{Return value}:
2529 @item @emph{Example}:
2531 program test_time_and_date
2532 character(8) :: date
2533 character(10) :: time
2534 character(5) :: zone
2535 integer,dimension(8) :: values
2536 ! using keyword arguments
2537 call date_and_time(date,time,zone,values)
2538 call date_and_time(DATE=date,ZONE=zone)
2539 call date_and_time(TIME=time)
2540 call date_and_time(VALUES=values)
2541 print '(a,2x,a,2x,a)', date, time, zone
2542 print '(8i5))', values
2543 end program test_time_and_date
2550 @section @code{DBLE} --- Double conversion function
2551 @cindex @code{DBLE} intrinsic
2552 @cindex double conversion
2555 @item @emph{Description}:
2556 @code{DBLE(X)} Converts @var{X} to double precision real type.
2558 @item @emph{Standard}:
2564 @item @emph{Syntax}:
2565 @code{RESULT = DBLE(X)}
2567 @item @emph{Arguments}:
2568 @multitable @columnfractions .15 .70
2569 @item @var{X} @tab The type shall be @code{INTEGER(*)}, @code{REAL(*)},
2570 or @code{COMPLEX(*)}.
2573 @item @emph{Return value}:
2574 The return value is of type double precision real.
2576 @item @emph{Example}:
2581 complex :: z = (2.3,1.14)
2582 print *, dble(x), dble(i), dble(z)
2583 end program test_dble
2586 @item @emph{See also}:
2587 @ref{DFLOAT}, @ref{FLOAT}, @ref{REAL}
2593 @section @code{DCMPLX} --- Double complex conversion function
2594 @cindex @code{DCMPLX} intrinsic
2595 @cindex complex numbers, conversion to
2598 @item @emph{Description}:
2599 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
2600 converted to the real component. If @var{Y} is present it is converted to the
2601 imaginary component. If @var{Y} is not present then the imaginary component is
2602 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
2604 @item @emph{Standard}:
2610 @item @emph{Syntax}:
2611 @code{RESULT = DCMPLX(X [, Y])}
2613 @item @emph{Arguments}:
2614 @multitable @columnfractions .15 .70
2615 @item @var{X} @tab The type may be @code{INTEGER(*)}, @code{REAL(*)},
2616 or @code{COMPLEX(*)}.
2617 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX(*)}.) May be
2618 @code{INTEGER(*)} or @code{REAL(*)}.
2621 @item @emph{Return value}:
2622 The return value is of type @code{COMPLEX(8)}
2624 @item @emph{Example}:
2634 print *, dcmplx(x,i)
2635 end program test_dcmplx
2642 @section @code{DFLOAT} --- Double conversion function
2643 @cindex @code{DFLOAT} intrinsic
2644 @cindex double float conversion
2647 @item @emph{Description}:
2648 @code{DFLOAT(X)} Converts @var{X} to double precision real type.
2650 @item @emph{Standard}:
2656 @item @emph{Syntax}:
2657 @code{RESULT = DFLOAT(X)}
2659 @item @emph{Arguments}:
2660 @multitable @columnfractions .15 .70
2661 @item @var{X} @tab The type shall be @code{INTEGER(*)}.
2664 @item @emph{Return value}:
2665 The return value is of type double precision real.
2667 @item @emph{Example}:
2672 end program test_dfloat
2675 @item @emph{See also}:
2676 @ref{DBLE}, @ref{FLOAT}, @ref{REAL}
2682 @section @code{DIGITS} --- Significant digits function
2683 @cindex @code{DIGITS} intrinsic
2684 @cindex digits, significant
2687 @item @emph{Description}:
2688 @code{DIGITS(X)} returns the number of significant digits of the internal model
2689 representation of @var{X}. For example, on a system using a 32-bit
2690 floating point representation, a default real number would likely return 24.
2692 @item @emph{Standard}:
2698 @item @emph{Syntax}:
2699 @code{RESULT = DIGITS(X)}
2701 @item @emph{Arguments}:
2702 @multitable @columnfractions .15 .70
2703 @item @var{X} @tab The type may be @code{INTEGER(*)} or @code{REAL(*)}.
2706 @item @emph{Return value}:
2707 The return value is of type @code{INTEGER}.
2709 @item @emph{Example}:
2712 integer :: i = 12345
2718 end program test_digits
2725 @section @code{DIM} --- Dim function
2726 @cindex @code{DIM} intrinsic
2727 @cindex @code{IDIM} intrinsic
2728 @cindex @code{DDIM} intrinsic
2732 @item @emph{Description}:
2733 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
2734 otherwise returns zero.
2736 @item @emph{Standard}:
2742 @item @emph{Syntax}:
2743 @code{RESULT = DIM(X, Y)}
2745 @item @emph{Arguments}:
2746 @multitable @columnfractions .15 .70
2747 @item @var{X} @tab The type shall be @code{INTEGER(*)} or @code{REAL(*)}
2748 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
2751 @item @emph{Return value}:
2752 The return value is of type @code{INTEGER(*)} or @code{REAL(*)}.
2754 @item @emph{Example}:
2760 x = dim(4.345_8, 2.111_8)
2763 end program test_dim
2766 @item @emph{Specific names}:
2767 @multitable @columnfractions .20 .20 .20 .25
2768 @item Name @tab Argument @tab Return type @tab Standard
2769 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X,Y} @tab @code{INTEGER(4)} @tab F77 and later
2770 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X,Y} @tab @code{REAL(8)} @tab F77 and later
2777 @section @code{DOT_PRODUCT} --- Dot product function
2778 @cindex @code{DOT_PRODUCT} intrinsic
2782 @item @emph{Description}:
2783 @code{DOT_PRODUCT(X,Y)} computes the dot product multiplication of two vectors
2784 @var{X} and @var{Y}. The two vectors may be either numeric or logical
2785 and must be arrays of rank one and of equal size. If the vectors are
2786 @code{INTEGER(*)} or @code{REAL(*)}, the result is @code{SUM(X*Y)}. If the
2787 vectors are @code{COMPLEX(*)}, the result is @code{SUM(CONJG(X)*Y)}. If the
2788 vectors are @code{LOGICAL}, the result is @code{ANY(X.AND.Y)}.
2790 @item @emph{Standard}:
2794 transformational function
2796 @item @emph{Syntax}:
2797 @code{RESULT = DOT_PRODUCT(X, Y)}
2799 @item @emph{Arguments}:
2800 @multitable @columnfractions .15 .70
2801 @item @var{X} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
2802 @item @var{Y} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
2805 @item @emph{Return value}:
2806 If the arguments are numeric, the return value is a scaler of numeric type,
2807 @code{INTEGER(*)}, @code{REAL(*)}, or @code{COMPLEX(*)}. If the arguments are
2808 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
2810 @item @emph{Example}:
2812 program test_dot_prod
2813 integer, dimension(3) :: a, b
2820 print *, dot_product(a,b)
2821 end program test_dot_prod
2828 @section @code{DPROD} --- Double product function
2829 @cindex @code{DPROD} intrinsic
2830 @cindex double-precision product
2833 @item @emph{Description}:
2834 @code{DPROD(X,Y)} returns the product @code{X*Y}.
2836 @item @emph{Standard}:
2842 @item @emph{Syntax}:
2843 @code{RESULT = DPROD(X, Y)}
2845 @item @emph{Arguments}:
2846 @multitable @columnfractions .15 .70
2847 @item @var{X} @tab The type shall be @code{REAL}.
2848 @item @var{Y} @tab The type shall be @code{REAL}.
2851 @item @emph{Return value}:
2852 The return value is of type @code{REAL(8)}.
2854 @item @emph{Example}:
2863 end program test_dprod
2870 @section @code{DREAL} --- Double real part function
2871 @cindex @code{DREAL} intrinsic
2872 @cindex double-precision real part
2875 @item @emph{Description}:
2876 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
2878 @item @emph{Standard}:
2884 @item @emph{Syntax}:
2885 @code{RESULT = DREAL(Z)}
2887 @item @emph{Arguments}:
2888 @multitable @columnfractions .15 .70
2889 @item @var{Z} @tab The type shall be @code{COMPLEX(8)}.
2892 @item @emph{Return value}:
2893 The return value is of type @code{REAL(8)}.
2895 @item @emph{Example}:
2898 complex(8) :: z = (1.3_8,7.2_8)
2900 end program test_dreal
2903 @item @emph{See also}:
2911 @section @code{DTIME} --- Execution time subroutine (or function)
2912 @cindex @code{DTIME} intrinsic
2913 @cindex time, elapsed
2914 @cindex elapsed time
2917 @item @emph{Description}:
2918 @code{DTIME(TARRAY, RESULT)} initially returns the number of seconds of runtime
2919 since the start of the process's execution in @var{RESULT}. @var{TARRAY}
2920 returns the user and system components of this time in @code{TARRAY(1)} and
2921 @code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) +
2924 Subsequent invocations of @code{DTIME} return values accumulated since the
2925 previous invocation.
2927 On some systems, the underlying timings are represented using types with
2928 sufficiently small limits that overflows (wrap around) are possible, such as
2929 32-bit types. Therefore, the values returned by this intrinsic might be, or
2930 become, negative, or numerically less than previous values, during a single
2931 run of the compiled program.
2933 If @code{DTIME} is invoked as a function, it can not be invoked as a
2934 subroutine, and vice versa.
2936 @var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
2938 @multitable @columnfractions .15 .30 .40
2939 @item @tab @code{TARRAY(1)}: @tab User time in seconds.
2940 @item @tab @code{TARRAY(2)}: @tab System time in seconds.
2941 @item @tab @code{RESULT}: @tab Run time since start in seconds.
2944 @item @emph{Standard}:
2950 @item @emph{Syntax}:
2951 @multitable @columnfractions .80
2952 @item @code{CALL DTIME(TARRAY, RESULT)}.
2953 @item @code{RESULT = DTIME(TARRAY)}, (not recommended).
2956 @item @emph{Arguments}:
2957 @multitable @columnfractions .15 .70
2958 @item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
2959 @item @var{RESULT}@tab The type shall be @code{REAL}.
2962 @item @emph{Return value}:
2963 Elapsed time in seconds since the start of program execution.
2965 @item @emph{Example}:
2969 real, dimension(2) :: tarray
2971 call dtime(tarray, result)
2975 do i=1,100000000 ! Just a delay
2978 call dtime(tarray, result)
2982 end program test_dtime
2989 @section @code{EOSHIFT} --- End-off shift function
2990 @cindex @code{EOSHIFT} intrinsic
2991 @cindex bit operations
2994 @item @emph{Description}:
2995 @code{EOSHIFT(ARRAY, SHIFT[,BOUNDARY, DIM])} performs an end-off shift on
2996 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
2997 omitted it is taken to be @code{1}. @var{DIM} is a scaler of type
2998 @code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n} is the
2999 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
3000 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
3001 then all complete rank one sections of @var{ARRAY} along the given dimension are
3002 shifted. Elements shifted out one end of each rank one section are dropped. If
3003 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3004 is copied back in the other end. If @var{BOUNDARY} is not present then the
3005 following are copied in depending on the type of @var{ARRAY}.
3007 @multitable @columnfractions .15 .80
3008 @item @emph{Array Type} @tab @emph{Boundary Value}
3009 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
3010 @item Logical @tab @code{.FALSE.}.
3011 @item Character(@var{len}) @tab @var{len} blanks.
3014 @item @emph{Standard}:
3018 transformational function
3020 @item @emph{Syntax}:
3021 @code{RESULT = EOSHIFT(A, SHIFT [, BOUNDARY, DIM])}
3023 @item @emph{Arguments}:
3024 @multitable @columnfractions .15 .70
3025 @item @var{ARRAY} @tab May be any type, not scaler.
3026 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3027 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3028 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3031 @item @emph{Return value}:
3032 Returns an array of same type and rank as the @var{ARRAY} argument.
3034 @item @emph{Example}:
3036 program test_eoshift
3037 integer, dimension(3,3) :: a
3038 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3039 print '(3i3)', a(1,:)
3040 print '(3i3)', a(2,:)
3041 print '(3i3)', a(3,:)
3042 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3044 print '(3i3)', a(1,:)
3045 print '(3i3)', a(2,:)
3046 print '(3i3)', a(3,:)
3047 end program test_eoshift
3054 @section @code{EPSILON} --- Epsilon function
3055 @cindex @code{EPSILON} intrinsic
3056 @cindex epsilon, significant
3059 @item @emph{Description}:
3060 @code{EPSILON(X)} returns a nearly negligible number relative to @code{1}.
3062 @item @emph{Standard}:
3068 @item @emph{Syntax}:
3069 @code{RESULT = EPSILON(X)}
3071 @item @emph{Arguments}:
3072 @multitable @columnfractions .15 .70
3073 @item @var{X} @tab The type shall be @code{REAL(*)}.
3076 @item @emph{Return value}:
3077 The return value is of same type as the argument.
3079 @item @emph{Example}:
3081 program test_epsilon
3086 end program test_epsilon
3093 @section @code{ERF} --- Error function
3094 @cindex @code{ERF} intrinsic
3095 @cindex error function
3098 @item @emph{Description}:
3099 @code{ERF(X)} computes the error function of @var{X}.
3101 @item @emph{Standard}:
3107 @item @emph{Syntax}:
3108 @code{RESULT = ERF(X)}
3110 @item @emph{Arguments}:
3111 @multitable @columnfractions .15 .70
3112 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
3115 @item @emph{Return value}:
3116 The return value is a scalar of type @code{REAL(*)} and it is positive
3117 (@math{ - 1 \leq erf (x) \leq 1 }.
3119 @item @emph{Example}:
3122 real(8) :: x = 0.17_8
3124 end program test_erf
3127 @item @emph{Specific names}:
3128 @multitable @columnfractions .20 .20 .20 .25
3129 @item Name @tab Argument @tab Return type @tab Standard
3130 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3137 @section @code{ERFC} --- Error function
3138 @cindex @code{ERFC} intrinsic
3139 @cindex error function
3142 @item @emph{Description}:
3143 @code{ERFC(X)} computes the complementary error function of @var{X}.
3145 @item @emph{Standard}:
3151 @item @emph{Syntax}:
3152 @code{RESULT = ERFC(X)}
3154 @item @emph{Arguments}:
3155 @multitable @columnfractions .15 .70
3156 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
3159 @item @emph{Return value}:
3160 The return value is a scalar of type @code{REAL(*)} and it is positive
3161 (@math{ 0 \leq erfc (x) \leq 2 }.
3163 @item @emph{Example}:
3166 real(8) :: x = 0.17_8
3168 end program test_erfc
3171 @item @emph{Specific names}:
3172 @multitable @columnfractions .20 .20 .20 .25
3173 @item Name @tab Argument @tab Return type @tab Standard
3174 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3181 @section @code{ETIME} --- Execution time subroutine (or function)
3182 @cindex @code{ETIME} intrinsic
3183 @cindex time, elapsed
3186 @item @emph{Description}:
3187 @code{ETIME(TARRAY, RESULT)} returns the number of seconds of runtime
3188 since the start of the process's execution in @var{RESULT}. @var{TARRAY}
3189 returns the user and system components of this time in @code{TARRAY(1)} and
3190 @code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) + TARRAY(2)}.
3192 On some systems, the underlying timings are represented using types with
3193 sufficiently small limits that overflows (wrap around) are possible, such as
3194 32-bit types. Therefore, the values returned by this intrinsic might be, or
3195 become, negative, or numerically less than previous values, during a single
3196 run of the compiled program.
3198 If @code{ETIME} is invoked as a function, it can not be invoked as a
3199 subroutine, and vice versa.
3201 @var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
3203 @multitable @columnfractions .15 .30 .60
3204 @item @tab @code{TARRAY(1)}: @tab User time in seconds.
3205 @item @tab @code{TARRAY(2)}: @tab System time in seconds.
3206 @item @tab @code{RESULT}: @tab Run time since start in seconds.
3209 @item @emph{Standard}:
3215 @item @emph{Syntax}:
3216 @multitable @columnfractions .80
3217 @item @code{CALL ETIME(TARRAY, RESULT)}.
3218 @item @code{RESULT = ETIME(TARRAY)}, (not recommended).
3221 @item @emph{Arguments}:
3222 @multitable @columnfractions .15 .70
3223 @item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
3224 @item @var{RESULT}@tab The type shall be @code{REAL}.
3227 @item @emph{Return value}:
3228 Elapsed time in seconds since the start of program execution.
3230 @item @emph{Example}:
3234 real, dimension(2) :: tarray
3236 call ETIME(tarray, result)
3240 do i=1,100000000 ! Just a delay
3243 call ETIME(tarray, result)
3247 end program test_etime
3250 @item @emph{See also}:
3258 @section @code{EXIT} --- Exit the program with status.
3259 @cindex @code{EXIT} intrinsic
3260 @cindex exit program
3263 @item @emph{Description}:
3264 @code{EXIT} causes immediate termination of the program with status. If status
3265 is omitted it returns the canonical @emph{success} for the system. All Fortran
3266 I/O units are closed.
3268 @item @emph{Standard}:
3274 @item @emph{Syntax}:
3275 @code{CALL EXIT([STATUS])}
3277 @item @emph{Arguments}:
3278 @multitable @columnfractions .15 .70
3279 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
3282 @item @emph{Return value}:
3283 @code{STATUS} is passed to the parent process on exit.
3285 @item @emph{Example}:
3288 integer :: STATUS = 0
3289 print *, 'This program is going to exit.'
3291 end program test_exit
3294 @item @emph{See also}:
3295 @ref{ABORT}, @ref{KILL}
3301 @section @code{EXP} --- Exponential function
3302 @cindex @code{EXP} intrinsic
3303 @cindex @code{DEXP} intrinsic
3304 @cindex @code{CEXP} intrinsic
3305 @cindex @code{ZEXP} intrinsic
3306 @cindex @code{CDEXP} intrinsic
3310 @item @emph{Description}:
3311 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
3313 @item @emph{Standard}:
3314 F77 and later, has overloads that are GNU extensions
3319 @item @emph{Syntax}:
3320 @code{RESULT = EXP(X)}
3322 @item @emph{Arguments}:
3323 @multitable @columnfractions .15 .70
3324 @item @var{X} @tab The type shall be @code{REAL(*)} or
3328 @item @emph{Return value}:
3329 The return value has same type and kind as @var{X}.
3331 @item @emph{Example}:
3336 end program test_exp
3339 @item @emph{Specific names}:
3340 @multitable @columnfractions .20 .20 .20 .25
3341 @item Name @tab Argument @tab Return type @tab Standard
3342 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
3343 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab F77 and later
3344 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3345 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3352 @section @code{EXPONENT} --- Exponent function
3353 @cindex @code{EXPONENT} intrinsic
3354 @cindex exponent part of a real number
3357 @item @emph{Description}:
3358 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
3359 is zero the value returned is zero.
3361 @item @emph{Standard}:
3367 @item @emph{Syntax}:
3368 @code{RESULT = EXPONENT(X)}
3370 @item @emph{Arguments}:
3371 @multitable @columnfractions .15 .70
3372 @item @var{X} @tab The type shall be @code{REAL(*)}.
3375 @item @emph{Return value}:
3376 The return value is of type default @code{INTEGER}.
3378 @item @emph{Example}:
3380 program test_exponent
3385 print *, exponent(0.0)
3386 end program test_exponent
3393 @section @code{FDATE} --- Get the current time as a string
3394 @cindex @code{FDATE} intrinsic
3395 @cindex time, current
3396 @cindex current time
3397 @cindex date, current
3398 @cindex current date
3401 @item @emph{Description}:
3402 @code{FDATE(DATE)} returns the current date (using the same format as
3403 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
3406 If @code{FDATE} is invoked as a function, it can not be invoked as a
3407 subroutine, and vice versa.
3409 @var{DATE} is an @code{INTENT(OUT)} @code{CHARACTER} variable.
3411 @item @emph{Standard}:
3417 @item @emph{Syntax}:
3418 @multitable @columnfractions .80
3419 @item @code{CALL FDATE(DATE)}.
3420 @item @code{DATE = FDATE()}, (not recommended).
3423 @item @emph{Arguments}:
3424 @multitable @columnfractions .15 .70
3425 @item @var{DATE}@tab The type shall be of type @code{CHARACTER}.
3428 @item @emph{Return value}:
3429 The current date as a string.
3431 @item @emph{Example}:
3435 character(len=30) :: date
3437 print *, 'Program started on ', date
3438 do i = 1, 100000000 ! Just a delay
3442 print *, 'Program ended on ', date
3443 end program test_fdate
3451 @section @code{FLOAT} --- Convert integer to default real
3452 @cindex @code{FLOAT} intrinsic
3453 @cindex conversion function (float)
3456 @item @emph{Description}:
3457 @code{FLOAT(I)} converts the integer @var{I} to a default real value.
3459 @item @emph{Standard}:
3465 @item @emph{Syntax}:
3466 @code{RESULT = FLOAT(I)}
3468 @item @emph{Arguments}:
3469 @multitable @columnfractions .15 .70
3470 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
3473 @item @emph{Return value}:
3474 The return value is of type default @code{REAL}.
3476 @item @emph{Example}:
3480 if (float(i) /= 1.) call abort
3481 end program test_float
3484 @item @emph{See also}:
3485 @ref{DBLE}, @ref{DFLOAT}, @ref{REAL}
3491 @section @code{FGET} --- Read a single character in stream mode from stdin
3492 @cindex @code{FGET} intrinsic
3493 @cindex file operations
3494 @cindex stream operations
3497 @item @emph{Description}:
3498 Read a single character in stream mode from stdin by bypassing normal
3499 formatted output. Stream I/O should not be mixed with normal record-oriented
3500 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
3502 This intrinsic routine is provided for backwards compatibility with
3503 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
3504 Programmers should consider the use of new stream IO feature in new code
3505 for future portability. See also @ref{Fortran 2003 status}.
3507 @item @emph{Standard}:
3511 Non-elemental subroutine
3513 @item @emph{Syntax}:
3514 @code{CALL FGET(C [, STATUS])}
3516 @item @emph{Arguments}:
3517 @multitable @columnfractions .15 .70
3518 @item @var{C} @tab The type shall be @code{CHARACTER}.
3519 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
3520 Returns 0 on success, -1 on end-of-file, and a
3521 system specific positive error code otherwise.
3524 @item @emph{Example}:
3527 INTEGER, PARAMETER :: strlen = 100
3528 INTEGER :: status, i = 1
3529 CHARACTER(len=strlen) :: str = ""
3531 WRITE (*,*) 'Enter text:'
3533 CALL fget(str(i:i), status)
3534 if (status /= 0 .OR. i > strlen) exit
3537 WRITE (*,*) TRIM(str)
3541 @item @emph{See also}:
3542 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
3548 @section @code{FGETC} --- Read a single character in stream mode
3549 @cindex @code{FGETC} intrinsic
3550 @cindex file operations
3551 @cindex stream operations
3554 @item @emph{Description}:
3555 Read a single character in stream mode by bypassing normal formatted output.
3556 Stream I/O should not be mixed with normal record-oriented (formatted or
3557 unformatted) I/O on the same unit; the results are unpredictable.
3559 This intrinsic routine is provided for backwards compatibility with
3560 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
3561 Programmers should consider the use of new stream IO feature in new code
3562 for future portability. See also @ref{Fortran 2003 status}.
3564 @item @emph{Standard}:
3568 Non-elemental subroutine
3570 @item @emph{Syntax}:
3571 @code{CALL FGETC(UNIT, C [, STATUS])}
3573 @item @emph{Arguments}:
3574 @multitable @columnfractions .15 .70
3575 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
3576 @item @var{C} @tab The type shall be @code{CHARACTER}.
3577 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
3578 -1 on end-of-file and a system specific positive error code otherwise.
3581 @item @emph{Example}:
3584 INTEGER :: fd = 42, status
3587 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
3589 CALL fgetc(fd, c, status)
3590 IF (status /= 0) EXIT
3597 @item @emph{See also}:
3598 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
3604 @section @code{FLOOR} --- Integer floor function
3605 @cindex @code{FLOOR} intrinsic
3609 @item @emph{Description}:
3610 @code{FLOOR(X)} returns the greatest integer less than or equal to @var{X}.
3612 @item @emph{Standard}:
3618 @item @emph{Syntax}:
3619 @code{RESULT = FLOOR(X [, KIND])}
3621 @item @emph{Arguments}:
3622 @multitable @columnfractions .15 .70
3623 @item @var{X} @tab The type shall be @code{REAL(*)}.
3624 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
3625 expression indicating the kind parameter of
3629 @item @emph{Return value}:
3630 The return value is of type @code{INTEGER(KIND)}
3632 @item @emph{Example}:
3637 print *, floor(x) ! returns 63
3638 print *, floor(y) ! returns -64
3639 end program test_floor
3642 @item @emph{See also}:
3643 @ref{CEILING}, @ref{NINT}
3650 @section @code{FLUSH} --- Flush I/O unit(s)
3651 @cindex @code{FLUSH} intrinsic
3652 @cindex flush output files
3655 @item @emph{Description}:
3656 Flushes Fortran unit(s) currently open for output. Without the optional
3657 argument, all units are flushed, otherwise just the unit specified.
3659 @item @emph{Standard}:
3663 Non-elemental subroutine
3665 @item @emph{Syntax}:
3666 @code{CALL FLUSH(UNIT)}
3668 @item @emph{Arguments}:
3669 @multitable @columnfractions .15 .70
3670 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
3674 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
3675 statement that should be preferred over the @code{FLUSH} intrinsic.
3682 @section @code{FNUM} --- File number function
3683 @cindex @code{FNUM} intrinsic
3687 @item @emph{Description}:
3688 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
3689 open Fortran I/O unit @code{UNIT}.
3691 @item @emph{Standard}:
3695 Non-elemental function
3697 @item @emph{Syntax}:
3698 @code{RESULT = FNUM(UNIT)}
3700 @item @emph{Arguments}:
3701 @multitable @columnfractions .15 .70
3702 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
3705 @item @emph{Return value}:
3706 The return value is of type @code{INTEGER}
3708 @item @emph{Example}:
3712 open (unit=10, status = "scratch")
3716 end program test_fnum
3723 @section @code{FPUT} --- Write a single character in stream mode to stdout
3724 @cindex @code{FPUT} intrinsic
3725 @cindex file operations
3726 @cindex stream operations
3729 @item @emph{Description}:
3730 Write a single character in stream mode to stdout by bypassing normal
3731 formatted output. Stream I/O should not be mixed with normal record-oriented
3732 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
3734 This intrinsic routine is provided for backwards compatibility with
3735 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
3736 Programmers should consider the use of new stream IO feature in new code
3737 for future portability. See also @ref{Fortran 2003 status}.
3739 @item @emph{Standard}:
3743 Non-elemental subroutine
3745 @item @emph{Syntax}:
3746 @code{CALL FPUT(C [, STATUS])}
3748 @item @emph{Arguments}:
3749 @multitable @columnfractions .15 .70
3750 @item @var{C} @tab The type shall be @code{CHARACTER}.
3751 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
3752 -1 on end-of-file and a system specific positive error code otherwise.
3755 @item @emph{Example}:
3758 CHARACTER(len=*) :: str = "gfortran"
3760 DO i = 1, len_trim(str)
3766 @item @emph{See also}:
3767 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
3773 @section @code{FPUTC} --- Write a single character in stream mode
3774 @cindex @code{FPUTC} intrinsic
3775 @cindex file operations
3776 @cindex stream operations
3779 @item @emph{Description}:
3780 Write a single character in stream mode by bypassing normal formatted
3781 output. Stream I/O should not be mixed with normal record-oriented
3782 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
3784 This intrinsic routine is provided for backwards compatibility with
3785 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
3786 Programmers should consider the use of new stream IO feature in new code
3787 for future portability. See also @ref{Fortran 2003 status}.
3789 @item @emph{Standard}:
3793 Non-elemental subroutine
3795 @item @emph{Syntax}:
3796 @code{CALL FPUTC(UNIT, C [, STATUS])}
3798 @item @emph{Arguments}:
3799 @multitable @columnfractions .15 .70
3800 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
3801 @item @var{C} @tab The type shall be @code{CHARACTER}.
3802 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
3803 -1 on end-of-file and a system specific positive error code otherwise.
3806 @item @emph{Example}:
3809 CHARACTER(len=*) :: str = "gfortran"
3810 INTEGER :: fd = 42, i
3812 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
3813 DO i = 1, len_trim(str)
3814 CALL fputc(fd, str(i:i))
3820 @item @emph{See also}:
3821 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
3827 @section @code{FRACTION} --- Fractional part of the model representation
3828 @cindex @code{FRACTION} intrinsic
3829 @cindex fractional part
3832 @item @emph{Description}:
3833 @code{FRACTION(X)} returns the fractional part of the model
3834 representation of @code{X}.
3836 @item @emph{Standard}:
3842 @item @emph{Syntax}:
3843 @code{Y = FRACTION(X)}
3845 @item @emph{Arguments}:
3846 @multitable @columnfractions .15 .70
3847 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
3850 @item @emph{Return value}:
3851 The return value is of the same type and kind as the argument.
3852 The fractional part of the model representation of @code{X} is returned;
3853 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
3855 @item @emph{Example}:
3857 program test_fraction
3860 print *, fraction(x), x * radix(x)**(-exponent(x))
3861 end program test_fraction
3869 @section @code{FREE} --- Frees memory
3870 @cindex @code{FREE} intrinsic
3871 @cindex Cray pointers
3874 @item @emph{Description}:
3875 Frees memory previously allocated by @code{MALLOC()}. The @code{FREE}
3876 intrinsic is an extension intended to be used with Cray pointers, and is
3877 provided in GNU Fortran to allow user to compile legacy code. For
3878 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
3881 @item @emph{Standard}:
3887 @item @emph{Syntax}:
3888 @code{CALL FREE(PTR)}
3890 @item @emph{Arguments}:
3891 @multitable @columnfractions .15 .70
3892 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
3893 location of the memory that should be de-allocated.
3896 @item @emph{Return value}:
3899 @item @emph{Example}:
3900 See @code{MALLOC} for an example.
3902 @item @emph{See also}:
3909 @section @code{FSEEK} --- Low level file positioning subroutine
3910 @cindex @code{FSEEK} intrinsic
3911 @cindex file system operations
3913 Not yet implemented in GNU Fortran.
3916 @item @emph{Description}:
3918 @item @emph{Standard}:
3924 @item @emph{Syntax}:
3925 @item @emph{Arguments}:
3926 @item @emph{Return value}:
3927 @item @emph{Example}:
3928 @item @emph{Specific names}:
3929 @item @emph{See also}:
3930 @uref{http://gcc.gnu.org/bugzilla/show_bug.cgi?id=19292, g77 features lacking in gfortran}
3937 @section @code{FSTAT} --- Get file status
3938 @cindex @code{FSTAT} intrinsic
3939 @cindex file system operations
3942 @item @emph{Description}:
3943 @code{FSTAT} is identical to @ref{STAT}, except that information about an
3944 already opened file is obtained.
3946 The elements in @code{BUFF} are the same as described by @ref{STAT}.
3948 @item @emph{Standard}:
3952 Non-elemental subroutine
3954 @item @emph{Syntax}:
3955 @code{CALL FSTAT(UNIT, BUFF [, STATUS])}
3957 @item @emph{Arguments}:
3958 @multitable @columnfractions .15 .70
3959 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
3960 @item @var{BUFF} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
3961 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
3962 on success and a system specific error code otherwise.
3965 @item @emph{Example}:
3966 See @ref{STAT} for an example.
3968 @item @emph{See also}:
3969 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
3975 @section @code{FTELL} --- Current stream position
3976 @cindex @code{FTELL} intrinsic
3979 @item @emph{Description}:
3980 Retrieves the current position within an open file.
3982 This intrinsic is provided in both subroutine and function forms; however,
3983 only one form can be used in any given program unit.
3985 @item @emph{Standard}:
3989 Subroutine, function
3991 @item @emph{Syntax}:
3992 @multitable @columnfractions .80
3993 @item @code{CALL FTELL(UNIT, OFFSET)}
3994 @item @code{OFFSET = FTELL(UNIT)}
3997 @item @emph{Arguments}:
3998 @multitable @columnfractions .15 .70
3999 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
4000 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
4003 @item @emph{Return value}:
4004 In either syntax, @var{OFFSET} is set to the current offset of unit
4005 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
4007 @item @emph{Example}:
4011 OPEN(10, FILE="temp.dat")
4017 @item @emph{See also}:
4024 @section @code{GERROR} --- Get last system error message
4025 @cindex @code{GERROR} intrinsic
4028 @item @emph{Description}:
4029 Returns the system error message corresponding to the last system error.
4030 This resembles the functionality of @code{strerror(3)} in C.
4032 @item @emph{Standard}:
4038 @item @emph{Syntax}:
4039 @code{CALL GERROR(RESULT)}
4041 @item @emph{Arguments}:
4042 @multitable @columnfractions .15 .70
4043 @item @var{RESULT} @tab Shall of type @code{CHARACTER(*)}.
4046 @item @emph{Example}:
4049 CHARACTER(len=100) :: msg
4055 @item @emph{See also}:
4056 @ref{IERRNO}, @ref{PERROR}
4062 @section @code{GETARG} --- Get command line arguments
4063 @cindex @code{GETARG} intrinsic
4064 @cindex command-line arguments, to program
4067 @item @emph{Description}:
4068 Retrieve the @var{N}th argument that was passed on the
4069 command line when the containing program was invoked.
4071 This intrinsic routine is provided for backwards compatibility with
4072 GNU Fortran 77. In new code, programmers should consider the use of
4073 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
4076 @item @emph{Standard}:
4082 @item @emph{Syntax}:
4083 @code{CALL GETARG(N, ARG)}
4085 @item @emph{Arguments}:
4086 @multitable @columnfractions .15 .70
4087 @item @var{N} @tab Shall be of type @code{INTEGER(4)}, @math{@var{N} \geq 0}
4088 @item @var{ARG} @tab Shall be of type @code{CHARACTER(*)}.
4091 @item @emph{Return value}:
4092 After @code{GETARG} returns, the @var{ARG} argument holds the @var{N}th
4093 command line argument. If @var{ARG} can not hold the argument, it is
4094 truncated to fit the length of @var{ARG}. If there are less than @var{N}
4095 arguments specified at the command line, @var{ARG} will be filled with blanks.
4096 If @math{@var{N} = 0}, @var{ARG} is set to the name of the program (on systems
4097 that support this feature).
4099 @item @emph{Example}:
4103 CHARACTER(len=32) :: arg
4112 @item @emph{See also}:
4113 GNU Fortran 77 compatibility function: @ref{IARGC}
4115 F2003 functions and subroutines: @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT},
4116 @ref{COMMAND_ARGUMENT_COUNT}
4122 @section @code{GET_COMMAND} --- Get the entire command line
4123 @cindex @code{GET_COMMAND} intrinsic
4124 @cindex command-line arguments, to program
4127 @item @emph{Description}:
4128 Retrieve the entire command line that was used to invoke the program.
4130 @item @emph{Standard}:
4136 @item @emph{Syntax}:
4137 @code{CALL GET_COMMAND(CMD)}
4139 @item @emph{Arguments}:
4140 @multitable @columnfractions .15 .70
4141 @item @var{CMD} @tab Shall be of type @code{CHARACTER(*)}.
4144 @item @emph{Return value}:
4145 Stores the entire command line that was used to invoke the program in @var{ARG}.
4146 If @var{ARG} is not large enough, the command will be truncated.
4148 @item @emph{Example}:
4150 PROGRAM test_get_command
4151 CHARACTER(len=255) :: cmd
4152 CALL get_command(cmd)
4153 WRITE (*,*) TRIM(cmd)
4157 @item @emph{See also}:
4158 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4163 @node GET_COMMAND_ARGUMENT
4164 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
4165 @cindex @code{GET_COMMAND_ARGUMENT} intrinsic
4166 @cindex command-line arguments, to program
4169 @item @emph{Description}:
4170 Retrieve the @var{N}th argument that was passed on the
4171 command line when the containing program was invoked.
4173 @item @emph{Standard}:
4179 @item @emph{Syntax}:
4180 @code{CALL GET_COMMAND_ARGUMENT(N, ARG)}
4182 @item @emph{Arguments}:
4183 @multitable @columnfractions .15 .70
4184 @item @var{N} @tab Shall be of type @code{INTEGER(4)}, @math{@var{N} \geq 0}
4185 @item @var{ARG} @tab Shall be of type @code{CHARACTER(*)}.
4188 @item @emph{Return value}:
4189 After @code{GET_COMMAND_ARGUMENT} returns, the @var{ARG} argument holds the
4190 @var{N}th command line argument. If @var{ARG} can not hold the argument, it is
4191 truncated to fit the length of @var{ARG}. If there are less than @var{N}
4192 arguments specified at the command line, @var{ARG} will be filled with blanks.
4193 If @math{@var{N} = 0}, @var{ARG} is set to the name of the program (on systems
4194 that support this feature).
4196 @item @emph{Example}:
4198 PROGRAM test_get_command_argument
4200 CHARACTER(len=32) :: arg
4204 CALL get_command_argument(i, arg)
4205 IF (LEN_TRIM(arg) == 0) EXIT
4207 WRITE (*,*) TRIM(arg)
4213 @item @emph{See also}:
4214 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
4220 @section @code{GETCWD} --- Get current working directory
4221 @cindex @code{GETCWD} intrinsic
4222 @cindex file system operations
4225 @item @emph{Description}:
4226 Get current working directory.
4228 @item @emph{Standard}:
4232 Non-elemental subroutine.
4234 @item @emph{Syntax}:
4235 @code{CALL GETCWD(CWD [, STATUS])}
4237 @item @emph{Arguments}:
4238 @multitable @columnfractions .15 .70
4239 @item @var{CWD} @tab The type shall be @code{CHARACTER(*)}.
4240 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
4241 a system specific and non-zero error code otherwise.
4244 @item @emph{Example}:
4247 CHARACTER(len=255) :: cwd
4249 WRITE(*,*) TRIM(cwd)
4253 @item @emph{See also}:
4260 @section @code{GETENV} --- Get an environmental variable
4261 @cindex @code{GETENV} intrinsic
4262 @cindex environment variable
4265 @item @emph{Description}:
4266 Get the @var{VALUE} of the environmental variable @var{ENVVAR}.
4268 This intrinsic routine is provided for backwards compatibility with
4269 GNU Fortran 77. In new code, programmers should consider the use of
4270 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
4273 @item @emph{Standard}:
4279 @item @emph{Syntax}:
4280 @code{CALL GETENV(ENVVAR, VALUE)}
4282 @item @emph{Arguments}:
4283 @multitable @columnfractions .15 .70
4284 @item @var{ENVVAR} @tab Shall be of type @code{CHARACTER(*)}.
4285 @item @var{VALUE} @tab Shall be of type @code{CHARACTER(*)}.
4288 @item @emph{Return value}:
4289 Stores the value of @var{ENVVAR} in @var{VALUE}. If @var{VALUE} is
4290 not large enough to hold the data, it is truncated. If @var{ENVVAR}
4291 is not set, @var{VALUE} will be filled with blanks.
4293 @item @emph{Example}:
4296 CHARACTER(len=255) :: homedir
4297 CALL getenv("HOME", homedir)
4298 WRITE (*,*) TRIM(homedir)
4302 @item @emph{See also}:
4303 @ref{GET_ENVIRONMENT_VARIABLE}
4308 @node GET_ENVIRONMENT_VARIABLE
4309 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
4310 @cindex @code{GET_ENVIRONMENT_VARIABLE} intrinsic
4311 @cindex environment variable
4314 @item @emph{Description}:
4315 Get the @var{VALUE} of the environmental variable @var{ENVVAR}.
4317 @item @emph{Standard}:
4323 @item @emph{Syntax}:
4324 @code{CALL GET_ENVIRONMENT_VARIABLE(ENVVAR, VALUE)}
4326 @item @emph{Arguments}:
4327 @multitable @columnfractions .15 .70
4328 @item @var{ENVVAR} @tab Shall be of type @code{CHARACTER(*)}.
4329 @item @var{VALUE} @tab Shall be of type @code{CHARACTER(*)}.
4332 @item @emph{Return value}:
4333 Stores the value of @var{ENVVAR} in @var{VALUE}. If @var{VALUE} is
4334 not large enough to hold the data, it is truncated. If @var{ENVVAR}
4335 is not set, @var{VALUE} will be filled with blanks.
4337 @item @emph{Example}:
4340 CHARACTER(len=255) :: homedir
4341 CALL get_environment_variable("HOME", homedir)
4342 WRITE (*,*) TRIM(homedir)
4350 @section @code{GETGID} --- Group ID function
4351 @cindex @code{GETGID} intrinsic
4352 @cindex file system operations
4355 @item @emph{Description}:
4356 Returns the numerical group ID of the current process.
4358 @item @emph{Standard}:
4364 @item @emph{Syntax}:
4365 @code{RESULT = GETGID()}
4367 @item @emph{Return value}:
4368 The return value of @code{GETGID} is an @code{INTEGER} of the default
4372 @item @emph{Example}:
4373 See @code{GETPID} for an example.
4375 @item @emph{See also}:
4376 @ref{GETPID}, @ref{GETUID}
4382 @section @code{GETLOG} --- Get login name
4383 @cindex @code{GETLOG} intrinsic
4386 @item @emph{Description}:
4387 Gets the username under which the program is running.
4389 @item @emph{Standard}:
4395 @item @emph{Syntax}:
4396 @code{CALL GETLOG(LOGIN)}
4398 @item @emph{Arguments}:
4399 @multitable @columnfractions .15 .70
4400 @item @var{LOGIN} @tab Shall be of type @code{CHARACTER(*)}.
4403 @item @emph{Return value}:
4404 Stores the current user name in @var{LOGIN}. (On systems where
4405 the @code{getlogin(3)} function is not implemented, this will
4406 return a blank string.)
4408 @item @emph{Example}:
4411 CHARACTER(32) :: login
4417 @item @emph{See also}:
4424 @section @code{GETPID} --- Process ID function
4425 @cindex @code{GETPID} intrinsic
4426 @cindex process ID, current
4429 @item @emph{Description}:
4430 Returns the numerical process identifier of the current process.
4432 @item @emph{Standard}:
4438 @item @emph{Syntax}:
4439 @code{RESULT = GETPID()}
4441 @item @emph{Return value}:
4442 The return value of @code{GETPID} is an @code{INTEGER} of the default
4446 @item @emph{Example}:
4449 print *, "The current process ID is ", getpid()
4450 print *, "Your numerical user ID is ", getuid()
4451 print *, "Your numerical group ID is ", getgid()
4455 @item @emph{See also}:
4456 @ref{GETGID}, @ref{GETUID}
4462 @section @code{GETUID} --- User ID function
4463 @cindex @code{GETUID} intrinsic
4464 @cindex user ID, current
4467 @item @emph{Description}:
4468 Returns the numerical user ID of the current process.
4470 @item @emph{Standard}:
4476 @item @emph{Syntax}:
4477 @code{RESULT = GETUID()}
4479 @item @emph{Return value}:
4480 The return value of @code{GETUID} is an @code{INTEGER} of the default
4484 @item @emph{Example}:
4485 See @code{GETPID} for an example.
4487 @item @emph{See also}:
4488 @ref{GETPID}, @ref{GETLOG}
4494 @section @code{GMTIME} --- Convert time to GMT info
4495 @cindex @code{GMTIME} intrinsic
4496 @cindex time, conversion function
4499 @item @emph{Description}:
4500 Given a system time value @var{STIME} (as provided by the @code{TIME8()}
4501 intrinsic), fills @var{TARRAY} with values extracted from it appropriate
4502 to the UTC time zone (Universal Coordinated Time, also known in some
4503 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
4505 @item @emph{Standard}:
4511 @item @emph{Syntax}:
4512 @code{CALL GMTIME(STIME, TARRAY)}
4514 @item @emph{Arguments}:
4515 @multitable @columnfractions .15 .70
4516 @item @var{STIME} @tab An @code{INTEGER(*)} scalar expression
4517 corresponding to a system time, with
4519 @item @var{TARRAY} @tab A default @code{INTEGER} array with 9 elements,
4520 with @code{INTENT(OUT)}.
4523 @item @emph{Return value}:
4524 The elements of @var{TARRAY} are assigned as follows:
4526 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
4528 @item Minutes after the hour, range 0--59
4529 @item Hours past midnight, range 0--23
4530 @item Day of month, range 0--31
4531 @item Number of months since January, range 0--12
4532 @item Years since 1900
4533 @item Number of days since Sunday, range 0--6
4534 @item Days since January 1
4535 @item Daylight savings indicator: positive if daylight savings is in
4536 effect, zero if not, and negative if the information is not
4540 @item @emph{See also}:
4541 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
4548 @section @code{HOSTNM} --- Get system host name
4549 @cindex @code{HOSTNM} intrinsic
4552 @item @emph{Description}:
4553 Retrieves the host name of the system on which the program is running.
4555 This intrinsic is provided in both subroutine and function forms; however,
4556 only one form can be used in any given program unit.
4558 @item @emph{Standard}:
4562 Subroutine, function
4564 @item @emph{Syntax}:
4565 @multitable @columnfractions .80
4566 @item @code{CALL HOSTNM(NAME[, STATUS])}
4567 @item @code{STATUS = HOSTNM(NAME)}
4570 @item @emph{Arguments}:
4571 @multitable @columnfractions .15 .70
4572 @item @var{NAME} @tab Shall of type @code{CHARACTER(*)}.
4573 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4574 Returns 0 on success, or a system specific error
4578 @item @emph{Return value}:
4579 In either syntax, @var{NAME} is set to the current hostname if it can
4580 be obtained, or to a blank string otherwise.
4587 @section @code{HUGE} --- Largest number of a kind
4588 @cindex @code{HUGE} intrinsic
4592 @item @emph{Description}:
4593 @code{HUGE(X)} returns the largest number that is not an infinity in
4594 the model of the type of @code{X}.
4596 @item @emph{Standard}:
4602 @item @emph{Syntax}:
4603 @code{RESULT = HUGE(X)}
4605 @item @emph{Arguments}:
4606 @multitable @columnfractions .15 .70
4607 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
4610 @item @emph{Return value}:
4611 The return value is of the same type and kind as @var{X}
4613 @item @emph{Example}:
4615 program test_huge_tiny
4616 print *, huge(0), huge(0.0), huge(0.0d0)
4617 print *, tiny(0.0), tiny(0.0d0)
4618 end program test_huge_tiny
4625 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
4626 @cindex @code{IACHAR} intrinsic
4627 @cindex @acronym{ASCII} collating sequence
4628 @cindex conversion function (character)
4631 @item @emph{Description}:
4632 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
4633 in the first character position of @code{C}.
4635 @item @emph{Standard}:
4641 @item @emph{Syntax}:
4642 @code{RESULT = IACHAR(C)}
4644 @item @emph{Arguments}:
4645 @multitable @columnfractions .15 .70
4646 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
4649 @item @emph{Return value}:
4650 The return value is of type @code{INTEGER} and of the default integer
4653 @item @emph{Example}:
4658 end program test_iachar
4662 See @ref{ICHAR} for a discussion of converting between numerical values
4663 and formatted string representations.
4665 @item @emph{See also}:
4666 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
4673 @section @code{IAND} --- Bitwise logical and
4674 @cindex @code{IAND} intrinsic
4675 @cindex bit operations
4678 @item @emph{Description}:
4679 Bitwise logical @code{AND}.
4681 @item @emph{Standard}:
4687 @item @emph{Syntax}:
4688 @code{RESULT = IAND(I, J)}
4690 @item @emph{Arguments}:
4691 @multitable @columnfractions .15 .70
4692 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
4693 @item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
4694 kind as @var{I}. (As a GNU extension, different kinds are also
4698 @item @emph{Return value}:
4699 The return type is @code{INTEGER(*)}, of the same kind as the
4700 arguments. (If the argument kinds differ, it is of the same kind as
4701 the larger argument.)
4703 @item @emph{Example}:
4707 DATA a / Z'F' /, b / Z'3' /
4708 WRITE (*,*) IAND(a, b)
4712 @item @emph{See also}:
4713 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
4720 @section @code{IARGC} --- Get the number of command line arguments
4721 @cindex @code{IARGC} intrinsic
4722 @cindex command-line arguments, to program
4725 @item @emph{Description}:
4726 @code{IARGC()} returns the number of arguments passed on the
4727 command line when the containing program was invoked.
4729 This intrinsic routine is provided for backwards compatibility with
4730 GNU Fortran 77. In new code, programmers should consider the use of
4731 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
4734 @item @emph{Standard}:
4738 Non-elemental Function
4740 @item @emph{Syntax}:
4741 @code{RESULT = IARGC()}
4743 @item @emph{Arguments}:
4746 @item @emph{Return value}:
4747 The number of command line arguments, type @code{INTEGER(4)}.
4749 @item @emph{Example}:
4752 @item @emph{See also}:
4753 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
4755 F2003 functions and subroutines: @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT},
4756 @ref{COMMAND_ARGUMENT_COUNT}
4762 @section @code{IBCLR} --- Clear bit
4763 @cindex @code{IBCLR} intrinsic
4764 @cindex bit operations
4767 @item @emph{Description}:
4768 @code{IBCLR} returns the value of @var{I} with the bit at position
4769 @var{POS} set to zero.
4771 @item @emph{Standard}:
4777 @item @emph{Syntax}:
4778 @code{RESULT = IBCLR(I, POS)}
4780 @item @emph{Arguments}:
4781 @multitable @columnfractions .15 .70
4782 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
4783 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
4786 @item @emph{Return value}:
4787 The return value is of type @code{INTEGER(*)} and of the same kind as
4790 @item @emph{See also}:
4791 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
4798 @section @code{IBITS} --- Bit extraction
4799 @cindex @code{IBITS} intrinsic
4800 @cindex bit operations
4803 @item @emph{Description}:
4804 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
4805 starting from bit position @var{POS} and extending left for @var{LEN}
4806 bits. The result is right-justified and the remaining bits are
4807 zeroed. The value of @code{POS+LEN} must be less than or equal to the
4808 value @code{BIT_SIZE(I)}.
4810 @item @emph{Standard}:
4816 @item @emph{Syntax}:
4817 @code{RESULT = IBITS(I, POS, LEN)}
4819 @item @emph{Arguments}:
4820 @multitable @columnfractions .15 .70
4821 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
4822 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
4823 @item @var{LEN} @tab The type shall be @code{INTEGER(*)}.
4826 @item @emph{Return value}:
4827 The return value is of type @code{INTEGER(*)} and of the same kind as
4830 @item @emph{See also}:
4831 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
4837 @section @code{IBSET} --- Set bit
4838 @cindex @code{IBSET} intrinsic
4839 @cindex bit operations
4842 @item @emph{Description}:
4843 @code{IBSET} returns the value of @var{I} with the bit at position
4844 @var{POS} set to one.
4846 @item @emph{Standard}:
4852 @item @emph{Syntax}:
4853 @code{RESULT = IBSET(I, POS)}
4855 @item @emph{Arguments}:
4856 @multitable @columnfractions .15 .70
4857 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
4858 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
4861 @item @emph{Return value}:
4862 The return value is of type @code{INTEGER(*)} and of the same kind as
4865 @item @emph{See also}:
4866 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
4873 @section @code{ICHAR} --- Character-to-integer conversion function
4874 @cindex @code{ICHAR} intrinsic
4875 @cindex conversion function (character)
4878 @item @emph{Description}:
4879 @code{ICHAR(C)} returns the code for the character in the first character
4880 position of @code{C} in the system's native character set.
4881 The correspondence between characters and their codes is not necessarily
4882 the same across different GNU Fortran implementations.
4884 @item @emph{Standard}:
4890 @item @emph{Syntax}:
4891 @code{RESULT = ICHAR(C)}
4893 @item @emph{Arguments}:
4894 @multitable @columnfractions .15 .70
4895 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
4898 @item @emph{Return value}:
4899 The return value is of type @code{INTEGER} and of the default integer
4902 @item @emph{Example}:
4907 end program test_ichar
4911 No intrinsic exists to convert between a numeric value and a formatted
4912 character string representation -- for instance, given the
4913 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
4914 @code{REAL} value with the value 154, or vice versa. Instead, this
4915 functionality is provided by internal-file I/O, as in the following
4920 character(len=10) string, string2
4923 ! Convert a string to a numeric value
4924 read (string,'(I10)') value
4927 ! Convert a value to a formatted string
4928 write (string2,'(I10)') value
4930 end program read_val
4933 @item @emph{See also}:
4934 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
4941 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
4942 @cindex @code{IDATE} intrinsic
4945 @item @emph{Description}:
4946 @code{IDATE(TARRAY)} Fills @var{TARRAY} with the numerical values at the
4947 current local time. The day (in the range 1-31), month (in the range 1-12),
4948 and year appear in elements 1, 2, and 3 of @var{TARRAY}, respectively.
4949 The year has four significant digits.
4951 @item @emph{Standard}:
4957 @item @emph{Syntax}:
4958 @code{CALL IDATE(TARRAY)}
4960 @item @emph{Arguments}:
4961 @multitable @columnfractions .15 .70
4962 @item @var{TARRAY} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
4963 the kind shall be the default integer kind.
4966 @item @emph{Return value}:
4969 @item @emph{Example}:
4972 integer, dimension(3) :: tarray
4977 end program test_idate
4984 @section @code{IEOR} --- Bitwise logical exclusive or
4985 @cindex @code{IEOR} intrinsic
4986 @cindex bit operations
4989 @item @emph{Description}:
4990 @code{IEOR} returns the bitwise boolean exclusive-OR of @var{I} and
4993 @item @emph{Standard}:
4999 @item @emph{Syntax}:
5000 @code{RESULT = IEOR(I, J)}
5002 @item @emph{Arguments}:
5003 @multitable @columnfractions .15 .70
5004 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5005 @item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
5006 kind as @var{I}. (As a GNU extension, different kinds are also
5010 @item @emph{Return value}:
5011 The return type is @code{INTEGER(*)}, of the same kind as the
5012 arguments. (If the argument kinds differ, it is of the same kind as
5013 the larger argument.)
5015 @item @emph{See also}:
5016 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5022 @section @code{IERRNO} --- Get the last system error number
5023 @cindex @code{IERRNO} intrinsic
5026 @item @emph{Description}:
5027 Returns the last system error number, as given by the C @code{errno()}
5030 @item @emph{Standard}:
5036 @item @emph{Syntax}:
5037 @code{RESULT = IERRNO()}
5039 @item @emph{Arguments}:
5042 @item @emph{Return value}:
5043 The return value is of type @code{INTEGER} and of the default integer
5046 @item @emph{See also}:
5053 @section @code{INDEX} --- Position of a substring within a string
5054 @cindex @code{INDEX} intrinsic
5057 @item @emph{Description}:
5058 Returns the position of the start of the first occurrence of string
5059 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
5060 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
5061 the @var{BACK} argument is present and true, the return value is the
5062 start of the last occurrence rather than the first.
5064 @item @emph{Standard}:
5070 @item @emph{Syntax}:
5071 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK])}
5073 @item @emph{Arguments}:
5074 @multitable @columnfractions .15 .70
5075 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER(*)}, with
5077 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER(*)}, with
5079 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL(*)}, with
5083 @item @emph{Return value}:
5084 The return value is of type @code{INTEGER} and of the default integer
5087 @item @emph{See also}:
5093 @section @code{INT} --- Convert to integer type
5094 @cindex @code{INT} intrinsic
5095 @cindex @code{IFIX} intrinsic
5096 @cindex @code{IDINT} intrinsic
5097 @cindex conversion function (integer)
5100 @item @emph{Description}:
5101 Convert to integer type
5103 @item @emph{Standard}:
5109 @item @emph{Syntax}:
5110 @code{RESULT = INT(A [, KIND))}
5112 @item @emph{Arguments}:
5113 @multitable @columnfractions .15 .70
5114 @item @var{A} @tab Shall be of type @code{INTEGER(*)},
5115 @code{REAL(*)}, or @code{COMPLEX(*)}.
5116 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
5117 expression indicating the kind parameter of
5121 @item @emph{Return value}:
5122 These functions return a @code{INTEGER(*)} variable or array under
5123 the following rules:
5127 If @var{A} is of type @code{INTEGER(*)}, @code{INT(A) = A}
5129 If @var{A} is of type @code{REAL(*)} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
5130 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
5131 the range of @var{A} and whose sign is the same as the sign of @var{A}.
5133 If @var{A} is of type @code{COMPLEX(*)}, rule B is applied to the real part of @var{A}.
5136 @item @emph{Example}:
5140 complex :: z = (-3.7, 1.0)
5142 print *, int(z), int(z,8)
5146 @item @emph{Specific names}:
5147 @multitable @columnfractions .20 .20 .20 .25
5148 @item Name @tab Argument @tab Return type @tab Standard
5149 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab F77 and later
5150 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab F77 and later
5153 @comment @item @emph{See also}:
5159 @section @code{INT2} --- Convert to 16-bit integer type
5160 @cindex @code{INT2} intrinsic
5161 @cindex @code{SHORT} intrinsic
5162 @cindex conversion function (integer)
5165 @item @emph{Description}:
5166 Convert to a @code{KIND=2} integer type. This is equivalent to the
5167 standard @code{INT} intrinsic with an optional argument of
5168 @code{KIND=2}, and is only included for backwards compatibility.
5170 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
5172 @item @emph{Standard}:
5178 @item @emph{Syntax}:
5179 @code{RESULT = INT2(A)}
5181 @item @emph{Arguments}:
5182 @multitable @columnfractions .15 .70
5183 @item @var{A} @tab Shall be of type @code{INTEGER(*)},
5184 @code{REAL(*)}, or @code{COMPLEX(*)}.
5187 @item @emph{Return value}:
5188 The return value is a @code{INTEGER(2)} variable.
5190 @comment @item @emph{See also}:
5191 @ref{INT}, @ref{INT8}, @ref{LONG}
5197 @section @code{INT8} --- Convert to 64-bit integer type
5198 @cindex @code{INT8} intrinsic
5199 @cindex conversion function (integer)
5202 @item @emph{Description}:
5203 Convert to a @code{KIND=8} integer type. This is equivalent to the
5204 standard @code{INT} intrinsic with an optional argument of
5205 @code{KIND=8}, and is only included for backwards compatibility.
5207 @item @emph{Standard}:
5213 @item @emph{Syntax}:
5214 @code{RESULT = INT8(A)}
5216 @item @emph{Arguments}:
5217 @multitable @columnfractions .15 .70
5218 @item @var{A} @tab Shall be of type @code{INTEGER(*)},
5219 @code{REAL(*)}, or @code{COMPLEX(*)}.
5222 @item @emph{Return value}:
5223 The return value is a @code{INTEGER(8)} variable.
5225 @comment @item @emph{See also}:
5226 @ref{INT}, @ref{INT2}, @ref{LONG}
5232 @section @code{IOR} --- Bitwise logical or
5233 @cindex @code{IOR} intrinsic
5234 @cindex bit operations
5237 @item @emph{Description}:
5238 @code{IEOR} returns the bitwise boolean OR of @var{I} and
5241 @item @emph{Standard}:
5247 @item @emph{Syntax}:
5248 @code{RESULT = IEOR(I, J)}
5250 @item @emph{Arguments}:
5251 @multitable @columnfractions .15 .70
5252 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5253 @item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
5254 kind as @var{I}. (As a GNU extension, different kinds are also
5258 @item @emph{Return value}:
5259 The return type is @code{INTEGER(*)}, of the same kind as the
5260 arguments. (If the argument kinds differ, it is of the same kind as
5261 the larger argument.)
5263 @item @emph{See also}:
5264 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5270 @section @code{IRAND} --- Integer pseudo-random number
5271 @cindex @code{IRAND} intrinsic
5272 @cindex random numbers
5275 @item @emph{Description}:
5276 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
5277 distribution between 0 and a system-dependent limit (which is in most
5278 cases 2147483647). If @var{FLAG} is 0, the next number
5279 in the current sequence is returned; if @var{FLAG} is 1, the generator
5280 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
5281 it is used as a new seed with @code{SRAND}.
5283 @item @emph{Standard}:
5287 Non-elemental function
5289 @item @emph{Syntax}:
5290 @code{RESULT = IRAND(FLAG)}
5292 @item @emph{Arguments}:
5293 @multitable @columnfractions .15 .70
5294 @item @var{FLAG} @tab Shall be a scalar @code{INTEGER} of kind 4.
5297 @item @emph{Return value}:
5298 The return value is of @code{INTEGER(kind=4)} type.
5300 @item @emph{Example}:
5303 integer,parameter :: seed = 86456
5306 print *, irand(), irand(), irand(), irand()
5307 print *, irand(seed), irand(), irand(), irand()
5308 end program test_irand
5316 @section @code{ISATTY} --- Whether a unit is a terminal device.
5317 @cindex @code{ISATTY} intrinsic
5320 @item @emph{Description}:
5321 Determine whether a unit is connected to a terminal device.
5323 @item @emph{Standard}:
5327 Non-elemental function.
5329 @item @emph{Syntax}:
5330 @code{RESULT = ISATTY(UNIT)}
5332 @item @emph{Arguments}:
5333 @multitable @columnfractions .15 .70
5334 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER(*)}.
5337 @item @emph{Return value}:
5338 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
5339 device, @code{.FALSE.} otherwise.
5341 @item @emph{Example}:
5344 INTEGER(kind=1) :: unit
5346 write(*,*) isatty(unit=unit)
5350 @item @emph{See also}:
5357 @section @code{ISHFT} --- Shift bits
5358 @cindex @code{ISHFT} intrinsic
5359 @cindex bit operations
5362 @item @emph{Description}:
5363 @code{ISHFT} returns a value corresponding to @var{I} with all of the
5364 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
5365 zero corresponds to a left shift, a value of zero corresponds to no
5366 shift, and a value less than zero corresponds to a right shift. If the
5367 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
5368 value is undefined. Bits shifted out from the left end or right end are
5369 lost; zeros are shifted in from the opposite end.
5371 @item @emph{Standard}:
5377 @item @emph{Syntax}:
5378 @code{RESULT = ISHFT(I, SHIFT)}
5380 @item @emph{Arguments}:
5381 @multitable @columnfractions .15 .70
5382 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5383 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
5386 @item @emph{Return value}:
5387 The return value is of type @code{INTEGER(*)} and of the same kind as
5390 @item @emph{See also}:
5397 @section @code{ISHFTC} --- Shift bits circularly
5398 @cindex @code{ISHFTC} intrinsic
5399 @cindex bit operations
5402 @item @emph{Description}:
5403 @code{ISHFTC} returns a value corresponding to @var{I} with the
5404 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
5405 is, bits shifted out one end are shifted into the opposite end. A value
5406 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
5407 zero corresponds to no shift, and a value less than zero corresponds to
5408 a right shift. The absolute value of @var{SHIFT} must be less than
5409 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
5410 equivalent to @code{BIT_SIZE(I)}.
5412 @item @emph{Standard}:
5418 @item @emph{Syntax}:
5419 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
5421 @item @emph{Arguments}:
5422 @multitable @columnfractions .15 .70
5423 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5424 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
5425 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER(*)};
5426 the value must be greater than zero and less than or equal to
5430 @item @emph{Return value}:
5431 The return value is of type @code{INTEGER(*)} and of the same kind as
5434 @item @emph{See also}:
5441 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
5442 @cindex @code{ITIME} intrinsic
5445 @item @emph{Description}:
5446 @code{IDATE(TARRAY)} Fills @var{TARRAY} with the numerical values at the
5447 current local time. The hour (in the range 1-24), minute (in the range 1-60),
5448 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{TARRAY},
5451 @item @emph{Standard}:
5457 @item @emph{Syntax}:
5458 @code{CALL ITIME(TARRAY)}
5460 @item @emph{Arguments}:
5461 @multitable @columnfractions .15 .70
5462 @item @var{TARRAY} @tab The type shall be @code{INTEGER, DIMENSION(3)}
5463 and the kind shall be the default integer kind.
5466 @item @emph{Return value}:
5470 @item @emph{Example}:
5473 integer, dimension(3) :: tarray
5478 end program test_itime
5485 @section @code{KILL} --- Send a signal to a process
5486 @cindex @code{KILL} intrinsic
5489 @item @emph{Description}:
5490 @item @emph{Standard}:
5491 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
5497 @item @emph{Syntax}:
5498 @code{CALL KILL(PID, SIGNAL [, STATUS])}
5500 @item @emph{Arguments}:
5501 @multitable @columnfractions .15 .70
5502 @item @var{PID} @tab Shall be a scalar @code{INTEGER}, with
5504 @item @var{SIGNAL} @tab Shall be a scalar @code{INTEGER}, with
5506 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
5507 @code{INTEGER(8)}. Returns 0 on success, or a
5508 system-specific error code otherwise.
5511 @item @emph{See also}:
5512 @ref{ABORT}, @ref{EXIT}
5518 @section @code{KIND} --- Kind of an entity
5519 @cindex @code{KIND} intrinsic
5522 @item @emph{Description}:
5523 @code{KIND(X)} returns the kind value of the entity @var{X}.
5525 @item @emph{Standard}:
5531 @item @emph{Syntax}:
5534 @item @emph{Arguments}:
5535 @multitable @columnfractions .15 .70
5536 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
5537 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
5540 @item @emph{Return value}:
5541 The return value is a scalar of type @code{INTEGER} and of the default
5544 @item @emph{Example}:
5547 integer,parameter :: kc = kind(' ')
5548 integer,parameter :: kl = kind(.true.)
5550 print *, "The default character kind is ", kc
5551 print *, "The default logical kind is ", kl
5552 end program test_kind
5560 @section @code{LBOUND} --- Lower dimension bounds of an array
5561 @cindex @code{LBOUND} intrinsic
5564 @item @emph{Description}:
5565 Returns the lower bounds of an array, or a single lower bound
5566 along the @var{DIM} dimension.
5567 @item @emph{Standard}:
5573 @item @emph{Syntax}:
5574 @code{RESULT = LBOUND(ARRAY [, DIM])}
5576 @item @emph{Arguments}:
5577 @multitable @columnfractions .15 .70
5578 @item @var{ARRAY} @tab Shall be an array, of any type.
5579 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER(*)}.
5582 @item @emph{Return value}:
5583 If @var{DIM} is absent, the result is an array of the lower bounds of
5584 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
5585 corresponding to the lower bound of the array along that dimension. If
5586 @var{ARRAY} is an expression rather than a whole array or array
5587 structure component, or if it has a zero extent along the relevant
5588 dimension, the lower bound is taken to be 1.
5590 @item @emph{See also}:
5597 @section @code{LEN} --- Length of a character entity
5598 @cindex @code{LEN} intrinsic
5601 @item @emph{Description}:
5602 Returns the length of a character string. If @var{STRING} is an array,
5603 the length of an element of @var{STRING} is returned. Note that
5604 @var{STRING} need not be defined when this intrinsic is invoked, since
5605 only the length, not the content, of @var{STRING} is needed.
5607 @item @emph{Standard}:
5613 @item @emph{Syntax}:
5614 @code{L = LEN(STRING)}
5616 @item @emph{Arguments}:
5617 @multitable @columnfractions .15 .70
5618 @item @var{STRING} @tab Shall be a scalar or array of type
5619 @code{CHARACTER(*)}, with @code{INTENT(IN)}
5622 @item @emph{Return value}:
5623 The return value is an @code{INTEGER} of the default kind.
5625 @item @emph{See also}:
5626 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
5632 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
5633 @cindex @code{LEN_TRIM} intrinsic
5636 @item @emph{Description}:
5637 Returns the length of a character string, ignoring any trailing blanks.
5639 @item @emph{Standard}:
5645 @item @emph{Syntax}:
5646 @code{RESULT = LEN_TRIM(STRING)}
5648 @item @emph{Arguments}:
5649 @multitable @columnfractions .15 .70
5650 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)},
5651 with @code{INTENT(IN)}
5654 @item @emph{Return value}:
5655 The return value is an @code{INTEGER} of the default kind.
5657 @item @emph{See also}:
5658 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
5664 @section @code{LGE} --- Lexical greater than or equal
5665 @cindex @code{LGE} intrinsic
5666 @cindex comparison (lexical)
5667 @cindex lexical comparison
5670 @item @emph{Description}:
5671 Determines whether one string is lexically greater than or equal to
5672 another string, where the two strings are interpreted as containing
5673 ASCII character codes. If the String A and String B are not the same
5674 length, the shorter is compared as if spaces were appended to it to form
5675 a value that has the same length as the longer.
5677 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
5678 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
5679 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
5680 that the latter use the processor's character ordering (which is not
5681 ASCII on some targets), whereas the former always use the ASCII
5684 @item @emph{Standard}:
5690 @item @emph{Syntax}:
5691 @code{RESULT = LGE(STRING_A, STRING_B)}
5693 @item @emph{Arguments}:
5694 @multitable @columnfractions .15 .70
5695 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
5696 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
5699 @item @emph{Return value}:
5700 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
5701 otherwise, based on the ASCII ordering.
5703 @item @emph{See also}:
5704 @ref{LGT}, @ref{LLE}, @ref{LLT}
5710 @section @code{LGT} --- Lexical greater than
5711 @cindex @code{LGT} intrinsic
5712 @cindex comparison (lexical)
5713 @cindex lexical comparison
5716 @item @emph{Description}:
5717 Determines whether one string is lexically greater than another string,
5718 where the two strings are interpreted as containing ASCII character
5719 codes. If the String A and String B are not the same length, the
5720 shorter is compared as if spaces were appended to it to form a value
5721 that has the same length as the longer.
5723 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
5724 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
5725 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
5726 that the latter use the processor's character ordering (which is not
5727 ASCII on some targets), whereas the former always use the ASCII
5730 @item @emph{Standard}:
5736 @item @emph{Syntax}:
5737 @code{RESULT = LGT(STRING_A, STRING_B)}
5739 @item @emph{Arguments}:
5740 @multitable @columnfractions .15 .70
5741 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
5742 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
5745 @item @emph{Return value}:
5746 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
5747 otherwise, based on the ASCII ordering.
5749 @item @emph{See also}:
5750 @ref{LGE}, @ref{LLE}, @ref{LLT}
5756 @section @code{LINK} --- Create a hard link
5757 @cindex @code{LINK} intrinsic
5758 @cindex file system operations
5761 @item @emph{Description}:
5762 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
5763 character (@code{CHAR(0)}) can be used to mark the end of the names in
5764 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
5765 names are ignored. If the @var{STATUS} argument is supplied, it
5766 contains 0 on success or a nonzero error code upon return; see
5769 This intrinsic is provided in both subroutine and function forms;
5770 however, only one form can be used in any given program unit.
5772 @item @emph{Standard}:
5776 Subroutine, non-elemental function
5778 @item @emph{Syntax}:
5779 @multitable @columnfractions .80
5780 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
5781 @item @code{STATUS = LINK(PATH1, PATH2)}
5784 @item @emph{Arguments}:
5785 @multitable @columnfractions .15 .70
5786 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
5787 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
5788 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
5791 @item @emph{See also}:
5792 @ref{SYMLNK}, @ref{UNLINK}
5798 @section @code{LLE} --- Lexical less than or equal
5799 @cindex @code{LLE} intrinsic
5800 @cindex comparison (lexical)
5801 @cindex lexical comparison
5804 @item @emph{Description}:
5805 Determines whether one string is lexically less than or equal to another
5806 string, where the two strings are interpreted as containing ASCII
5807 character codes. If the String A and String B are not the same length,
5808 the shorter is compared as if spaces were appended to it to form a value
5809 that has the same length as the longer.
5811 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
5812 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
5813 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
5814 that the latter use the processor's character ordering (which is not
5815 ASCII on some targets), whereas the former always use the ASCII
5818 @item @emph{Standard}:
5824 @item @emph{Syntax}:
5825 @code{RESULT = LLE(STRING_A, STRING_B)}
5827 @item @emph{Arguments}:
5828 @multitable @columnfractions .15 .70
5829 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
5830 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
5833 @item @emph{Return value}:
5834 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
5835 otherwise, based on the ASCII ordering.
5837 @item @emph{See also}:
5838 @ref{LGE}, @ref{LGT}, @ref{LLT}
5844 @section @code{LLT} --- Lexical less than
5845 @cindex @code{LLT} intrinsic
5846 @cindex comparison (lexical)
5847 @cindex lexical comparison
5850 @item @emph{Description}:
5851 Determines whether one string is lexically less than another string,
5852 where the two strings are interpreted as containing ASCII character
5853 codes. If the String A and String B are not the same length, the
5854 shorter is compared as if spaces were appended to it to form a value
5855 that has the same length as the longer.
5857 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
5858 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
5859 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
5860 that the latter use the processor's character ordering (which is not
5861 ASCII on some targets), whereas the former always use the ASCII
5864 @item @emph{Standard}:
5870 @item @emph{Syntax}:
5871 @code{RESULT = LLT(STRING_A, STRING_B)}
5873 @item @emph{Arguments}:
5874 @multitable @columnfractions .15 .70
5875 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
5876 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
5879 @item @emph{Return value}:
5880 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
5881 otherwise, based on the ASCII ordering.
5883 @item @emph{See also}:
5884 @ref{LGE}, @ref{LGT}, @ref{LLE}
5890 @section @code{LNBLNK} --- Index of the last non-blank character in a string
5891 @cindex @code{LNBLNK} intrinsic
5894 @item @emph{Description}:
5895 Returns the length of a character string, ignoring any trailing blanks.
5896 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
5897 included for backwards compatibility.
5899 @item @emph{Standard}:
5905 @item @emph{Syntax}:
5906 @code{RESULT = LNBLNK(STRING)}
5908 @item @emph{Arguments}:
5909 @multitable @columnfractions .15 .70
5910 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)},
5911 with @code{INTENT(IN)}
5914 @item @emph{Return value}:
5915 The return value is of @code{INTEGER(kind=4)} type.
5917 @item @emph{See also}:
5918 @ref{INDEX}, @ref{LEN_TRIM}
5924 @section @code{LOC} --- Returns the address of a variable
5925 @cindex @code{LOC} intrinsic
5926 @cindex location of a variable in memory
5929 @item @emph{Description}:
5930 @code{LOC(X)} returns the address of @var{X} as an integer.
5932 @item @emph{Standard}:
5938 @item @emph{Syntax}:
5939 @code{RESULT = LOC(X)}
5941 @item @emph{Arguments}:
5942 @multitable @columnfractions .15 .70
5943 @item @var{X} @tab Variable of any type.
5946 @item @emph{Return value}:
5947 The return value is of type @code{INTEGER}, with a @code{KIND}
5948 corresponding to the size (in bytes) of a memory address on the target
5951 @item @emph{Example}:
5958 end program test_loc
5965 @section @code{LOG} --- Logarithm function
5966 @cindex @code{LOG} intrinsic
5967 @cindex @code{ALOG} intrinsic
5968 @cindex @code{DLOG} intrinsic
5969 @cindex @code{CLOG} intrinsic
5970 @cindex @code{ZLOG} intrinsic
5971 @cindex @code{CDLOG} intrinsic
5975 @item @emph{Description}:
5976 @code{LOG(X)} computes the logarithm of @var{X}.
5978 @item @emph{Standard}:
5984 @item @emph{Syntax}:
5985 @code{RESULT = LOG(X)}
5987 @item @emph{Arguments}:
5988 @multitable @columnfractions .15 .70
5989 @item @var{X} @tab The type shall be @code{REAL(*)} or
5993 @item @emph{Return value}:
5994 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
5995 The kind type parameter is the same as @var{X}.
5997 @item @emph{Example}:
6000 real(8) :: x = 1.0_8
6001 complex :: z = (1.0, 2.0)
6004 end program test_log
6007 @item @emph{Specific names}:
6008 @multitable @columnfractions .20 .20 .20 .25
6009 @item Name @tab Argument @tab Return type @tab Standard
6010 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
6011 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
6012 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
6013 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
6014 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
6021 @section @code{LOG10} --- Base 10 logarithm function
6022 @cindex @code{LOG10} intrinsic
6023 @cindex @code{ALOG10} intrinsic
6024 @cindex @code{DLOG10} intrinsic
6028 @item @emph{Description}:
6029 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
6031 @item @emph{Standard}:
6037 @item @emph{Syntax}:
6038 @code{RESULT = LOG10(X)}
6040 @item @emph{Arguments}:
6041 @multitable @columnfractions .15 .70
6042 @item @var{X} @tab The type shall be @code{REAL(*)} or
6046 @item @emph{Return value}:
6047 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
6048 The kind type parameter is the same as @var{X}.
6050 @item @emph{Example}:
6053 real(8) :: x = 10.0_8
6055 end program test_log10
6058 @item @emph{Specific names}:
6059 @multitable @columnfractions .20 .20 .20 .25
6060 @item Name @tab Argument @tab Return type @tab Standard
6061 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab F95 and later
6062 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
6069 @section @code{LOGICAL} --- Convert to logical type
6070 @cindex @code{LOGICAL} intrinsic
6071 @cindex conversion function (logical)
6074 @item @emph{Description}:
6075 Converts one kind of @code{LOGICAL} variable to another.
6077 @item @emph{Standard}:
6083 @item @emph{Syntax}:
6084 @code{RESULT = LOGICAL(L [, KIND])}
6086 @item @emph{Arguments}:
6087 @multitable @columnfractions .15 .70
6088 @item @var{L} @tab The type shall be @code{LOGICAL(*)}.
6089 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
6090 expression indicating the kind parameter of
6094 @item @emph{Return value}:
6095 The return value is a @code{LOGICAL} value equal to @var{L}, with a
6096 kind corresponding to @var{KIND}, or of the default logical kind if
6097 @var{KIND} is not given.
6099 @item @emph{See also}:
6100 @ref{INT}, @ref{REAL}, @ref{CMPLX}
6106 @section @code{LONG} --- Convert to integer type
6107 @cindex @code{LONG} intrinsic
6108 @cindex conversion function (integer)
6111 @item @emph{Description}:
6112 Convert to a @code{KIND=4} integer type, which is the same size as a C
6113 @code{long} integer. This is equivalent to the standard @code{INT}
6114 intrinsic with an optional argument of @code{KIND=4}, and is only
6115 included for backwards compatibility.
6117 @item @emph{Standard}:
6123 @item @emph{Syntax}:
6124 @code{RESULT = LONG(A)}
6126 @item @emph{Arguments}:
6127 @multitable @columnfractions .15 .70
6128 @item @var{A} @tab Shall be of type @code{INTEGER(*)},
6129 @code{REAL(*)}, or @code{COMPLEX(*)}.
6132 @item @emph{Return value}:
6133 The return value is a @code{INTEGER(4)} variable.
6135 @comment @item @emph{See also}:
6136 @ref{INT}, @ref{INT2}, @ref{INT8}
6142 @section @code{LSHIFT} --- Left shift bits
6143 @cindex @code{LSHIFT} intrinsic
6144 @cindex bit operations
6147 @item @emph{Description}:
6148 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
6149 bits shifted left by @var{SHIFT} places. If the absolute value of
6150 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
6151 Bits shifted out from the left end are lost; zeros are shifted in from
6154 This function has been superseded by the @code{ISHFT} intrinsic, which
6155 is standard in Fortran 95 and later.
6157 @item @emph{Standard}:
6163 @item @emph{Syntax}:
6164 @code{RESULT = LSHIFT(I, SHIFT)}
6166 @item @emph{Arguments}:
6167 @multitable @columnfractions .15 .70
6168 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
6169 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
6172 @item @emph{Return value}:
6173 The return value is of type @code{INTEGER(*)} and of the same kind as
6176 @item @emph{See also}:
6177 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}
6184 @section @code{LSTAT} --- Get file status
6185 @cindex @code{LSTAT} intrinsic
6186 @cindex file system operations
6189 @item @emph{Description}:
6190 @code{LSTAT} is identical to @ref{STAT}, except that if path is a symbolic link,
6191 then the link itself is statted, not the file that it refers to.
6193 The elements in @code{BUFF} are the same as described by @ref{STAT}.
6195 @item @emph{Standard}:
6199 Non-elemental subroutine
6201 @item @emph{Syntax}:
6202 @code{CALL LSTAT(FILE, BUFF [, STATUS])}
6204 @item @emph{Arguments}:
6205 @multitable @columnfractions .15 .70
6206 @item @var{FILE} @tab The type shall be @code{CHARACTER(*)}, a valid path within the file system.
6207 @item @var{BUFF} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
6208 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
6209 on success and a system specific error code otherwise.
6212 @item @emph{Example}:
6213 See @ref{STAT} for an example.
6215 @item @emph{See also}:
6216 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
6222 @section @code{LTIME} --- Convert time to local time info
6223 @cindex @code{LTIME} intrinsic
6224 @cindex time, conversion function
6227 @item @emph{Description}:
6228 Given a system time value @var{STIME} (as provided by the @code{TIME8()}
6229 intrinsic), fills @var{TARRAY} with values extracted from it appropriate
6230 to the local time zone using @code{localtime(3)}.
6232 @item @emph{Standard}:
6238 @item @emph{Syntax}:
6239 @code{CALL LTIME(STIME, TARRAY)}
6241 @item @emph{Arguments}:
6242 @multitable @columnfractions .15 .70
6243 @item @var{STIME} @tab An @code{INTEGER(*)} scalar expression
6244 corresponding to a system time, with
6246 @item @var{TARRAY} @tab A default @code{INTEGER} array with 9 elements,
6247 with @code{INTENT(OUT)}.
6250 @item @emph{Return value}:
6251 The elements of @var{TARRAY} are assigned as follows:
6253 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
6255 @item Minutes after the hour, range 0--59
6256 @item Hours past midnight, range 0--23
6257 @item Day of month, range 0--31
6258 @item Number of months since January, range 0--12
6259 @item Years since 1900
6260 @item Number of days since Sunday, range 0--6
6261 @item Days since January 1
6262 @item Daylight savings indicator: positive if daylight savings is in
6263 effect, zero if not, and negative if the information is not
6267 @item @emph{See also}:
6268 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
6275 @section @code{MALLOC} --- Allocate dynamic memory
6276 @cindex @code{MALLOC} intrinsic
6277 @cindex Cray pointers
6280 @item @emph{Description}:
6281 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
6282 returns the address of the allocated memory. The @code{MALLOC} intrinsic
6283 is an extension intended to be used with Cray pointers, and is provided
6284 in GNU Fortran to allow the user to compile legacy code. For new code
6285 using Fortran 95 pointers, the memory allocation intrinsic is
6288 @item @emph{Standard}:
6292 Non-elemental function
6294 @item @emph{Syntax}:
6295 @code{PTR = MALLOC(SIZE)}
6297 @item @emph{Arguments}:
6298 @multitable @columnfractions .15 .70
6299 @item @var{SIZE} @tab The type shall be @code{INTEGER(*)}.
6302 @item @emph{Return value}:
6303 The return value is of type @code{INTEGER(K)}, with @var{K} such that
6304 variables of type @code{INTEGER(K)} have the same size as
6305 C pointers (@code{sizeof(void *)}).
6307 @item @emph{Example}:
6308 The following example demonstrates the use of @code{MALLOC} and
6309 @code{FREE} with Cray pointers. This example is intended to run on
6310 32-bit systems, where the default integer kind is suitable to store
6311 pointers; on 64-bit systems, ptr_x would need to be declared as
6312 @code{integer(kind=8)}.
6321 ptr_x = malloc(20*8)
6323 x(i) = sqrt(1.0d0 / i)
6331 end program test_malloc
6334 @item @emph{See also}:
6341 @section @code{MATMUL} --- matrix multiplication
6342 @cindex @code{MATMUL} intrinsic
6343 @cindex matrix operations
6346 @item @emph{Description}:
6347 Performs a matrix multiplication on numeric or logical arguments.
6349 @item @emph{Standard}:
6353 Transformational function
6355 @item @emph{Syntax}:
6356 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
6358 @item @emph{Arguments}:
6359 @multitable @columnfractions .15 .70
6360 @item @var{MATRIX_A} @tab An array of @code{INTEGER(*)},
6361 @code{REAL(*)}, @code{COMPLEX(*)}, or
6362 @code{LOGICAL(*)} type, with a rank of
6364 @item @var{MATRIX_B} @tab An array of @code{INTEGER(*)},
6365 @code{REAL(*)}, or @code{COMPLEX(*)} type if
6366 @var{MATRIX_A} is of a numeric type;
6367 otherwise, an array of @code{LOGICAL(*)}
6368 type. The rank shall be one or two, and the
6369 first (or only) dimension of @var{MATRIX_B}
6370 shall be equal to the last (or only)
6371 dimension of @var{MATRIX_A}.
6374 @item @emph{Return value}:
6375 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
6376 kind of the result follow the usual type and kind promotion rules, as
6377 for the @code{*} or @code{.AND.} operators.
6379 @item @emph{See also}:
6385 @section @code{MAX} --- Maximum value of an argument list
6386 @cindex @code{MAX} intrinsic
6387 @cindex @code{MAX0} intrinsic
6388 @cindex @code{AMAX0} intrinsic
6389 @cindex @code{MAX1} intrinsic
6390 @cindex @code{AMAX1} intrinsic
6391 @cindex @code{DMAX1} intrinsic
6394 @item @emph{Description}:
6395 Returns the argument with the largest (most positive) value.
6397 @item @emph{Standard}:
6403 @item @emph{Syntax}:
6404 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
6406 @item @emph{Arguments}:
6407 @multitable @columnfractions .15 .70
6408 @item @var{A1} @tab The type shall be @code{INTEGER(*)} or
6410 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
6411 as @var{A1}. (As a GNU extension,
6412 arguments of different kinds are
6416 @item @emph{Return value}:
6417 The return value corresponds to the maximum value among the arguments,
6418 and has the same type and kind as the first argument.
6420 @item @emph{Specific names}:
6421 @multitable @columnfractions .20 .20 .20 .25
6422 @item Name @tab Argument @tab Return type @tab Standard
6423 @item @code{MAX0(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab F77 and later
6424 @item @code{AMAX0(I)} @tab @code{INTEGER(4) I} @tab @code{REAL(MAX(X))} @tab F77 and later
6425 @item @code{MAX1(X)} @tab @code{REAL(*) X} @tab @code{INT(MAX(X))} @tab F77 and later
6426 @item @code{AMAX1(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab F77 and later
6427 @item @code{DMAX1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
6430 @item @emph{See also}:
6431 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
6438 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
6439 @cindex @code{MAXEXPONENT} intrinsic
6440 @cindex maximum exponent
6441 @cindex exponent, maximum
6444 @item @emph{Description}:
6445 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
6448 @item @emph{Standard}:
6454 @item @emph{Syntax}:
6455 @code{RESULT = MAXEXPONENT(X)}
6457 @item @emph{Arguments}:
6458 @multitable @columnfractions .15 .70
6459 @item @var{X} @tab Shall be of type @code{REAL}.
6462 @item @emph{Return value}:
6463 The return value is of type @code{INTEGER} and of the default integer
6466 @item @emph{Example}:
6472 print *, minexponent(x), maxexponent(x)
6473 print *, minexponent(y), maxexponent(y)
6474 end program exponents
6481 @section @code{MAXLOC} --- Location of the maximum value within an array
6482 @cindex @code{MAXLOC} intrinsic
6485 @item @emph{Description}:
6486 Determines the location of the element in the array with the maximum
6487 value, or, if the @var{DIM} argument is supplied, determines the
6488 locations of the maximum element along each row of the array in the
6489 @var{DIM} direction. If @var{MASK} is present, only the elements for
6490 which @var{MASK} is @code{.TRUE.} are considered. If more than one
6491 element in the array has the maximum value, the location returned is
6492 that of the first such element in array element order. If the array has
6493 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
6494 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
6495 and all of the elements of @var{MASK} along a given row are zero, the
6496 result value for that row is zero.
6498 @item @emph{Standard}:
6502 Transformational function
6504 @item @emph{Syntax}:
6505 @multitable @columnfractions .80
6506 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
6507 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
6510 @item @emph{Arguments}:
6511 @multitable @columnfractions .15 .70
6512 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
6513 @code{REAL(*)}, or @code{CHARACTER(*)}.
6514 @item @var{DIM} @tab (Optional) Shall be a scalar of type
6515 @code{INTEGER(*)}, with a value between one
6516 and the rank of @var{ARRAY}, inclusive. It
6517 may not be an optional dummy argument.
6518 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL(*)},
6519 and conformable with @var{ARRAY}.
6522 @item @emph{Return value}:
6523 If @var{DIM} is absent, the result is a rank-one array with a length
6524 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
6525 is an array with a rank one less than the rank of @var{ARRAY}, and a
6526 size corresponding to the size of @var{ARRAY} with the @var{DIM}
6527 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
6528 of one, the result is a scalar. In all cases, the result is of default
6529 @code{INTEGER} type.
6531 @item @emph{See also}:
6532 @ref{MAX}, @ref{MAXVAL}
6539 @section @code{MAXVAL} --- Maximum value of an array
6540 @cindex @code{MAXVAL} intrinsic
6543 @item @emph{Description}:
6544 Determines the maximum value of the elements in an array value, or, if
6545 the @var{DIM} argument is supplied, determines the maximum value along
6546 each row of the array in the @var{DIM} direction. If @var{MASK} is
6547 present, only the elements for which @var{MASK} is @code{.TRUE.} are
6548 considered. If the array has zero size, or all of the elements of
6549 @var{MASK} are @code{.FALSE.}, then the result is the most negative
6550 number of the type and kind of @var{ARRAY} if @var{ARRAY} is numeric, or
6551 a string of nulls if @var{ARRAY} is of character type.
6553 @item @emph{Standard}:
6557 Transformational function
6559 @item @emph{Syntax}:
6560 @multitable @columnfractions .80
6561 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
6562 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
6565 @item @emph{Arguments}:
6566 @multitable @columnfractions .15 .70
6567 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
6568 @code{REAL(*)}, or @code{CHARACTER(*)}.
6569 @item @var{DIM} @tab (Optional) Shall be a scalar of type
6570 @code{INTEGER(*)}, with a value between one
6571 and the rank of @var{ARRAY}, inclusive. It
6572 may not be an optional dummy argument.
6573 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL(*)},
6574 and conformable with @var{ARRAY}.
6577 @item @emph{Return value}:
6578 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
6579 is a scalar. If @var{DIM} is present, the result is an array with a
6580 rank one less than the rank of @var{ARRAY}, and a size corresponding to
6581 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
6582 cases, the result is of the same type and kind as @var{ARRAY}.
6584 @item @emph{See also}:
6585 @ref{MAX}, @ref{MAXLOC}
6591 @section @code{MCLOCK} --- Time function
6592 @cindex @code{MCLOCK} intrinsic
6593 @cindex time, clock ticks
6597 @item @emph{Description}:
6598 Returns the number of clock ticks since the start of the process, based
6599 on the UNIX function @code{clock(3)}.
6601 This intrinsic is not fully portable, such as to systems with 32-bit
6602 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
6603 the values returned by this intrinsic might be, or become, negative, or
6604 numerically less than previous values, during a single run of the
6607 @item @emph{Standard}:
6611 Non-elemental function
6613 @item @emph{Syntax}:
6614 @code{RESULT = MCLOCK()}
6616 @item @emph{Return value}:
6617 The return value is a scalar of type @code{INTEGER(4)}, equal to the
6618 number of clock ticks since the start of the process, or @code{-1} if
6619 the system does not support @code{clock(3)}.
6621 @item @emph{See also}:
6622 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
6629 @section @code{MCLOCK8} --- Time function (64-bit)
6630 @cindex @code{MCLOCK8} intrinsic
6631 @cindex time, current
6632 @cindex current time
6635 @item @emph{Description}:
6636 Returns the number of clock ticks since the start of the process, based
6637 on the UNIX function @code{clock(3)}.
6639 @emph{Warning:} this intrinsic does not increase the range of the timing
6640 values over that returned by @code{clock(3)}. On a system with a 32-bit
6641 @code{clock(3)}, @code{MCLOCK8()} will return a 32-bit value, even though
6642 it is converted to a 64-bit @code{INTEGER(8)} value. That means
6643 overflows of the 32-bit value can still occur. Therefore, the values
6644 returned by this intrinsic might be or become negative or numerically
6645 less than previous values during a single run of the compiled program.
6647 @item @emph{Standard}:
6651 Non-elemental function
6653 @item @emph{Syntax}:
6654 @code{RESULT = MCLOCK8()}
6656 @item @emph{Return value}:
6657 The return value is a scalar of type @code{INTEGER(8)}, equal to the
6658 number of clock ticks since the start of the process, or @code{-1} if
6659 the system does not support @code{clock(3)}.
6661 @item @emph{See also}:
6662 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
6669 @section @code{MERGE} --- Merge variables
6670 @cindex @code{MERGE} intrinsic
6673 @item @emph{Description}:
6674 Select values from two arrays according to a logical mask. The result
6675 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
6676 @var{FSOURCE} if it is @code{.FALSE.}.
6678 @item @emph{Standard}:
6684 @item @emph{Syntax}:
6685 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
6687 @item @emph{Arguments}:
6688 @multitable @columnfractions .15 .70
6689 @item @var{TSOURCE} @tab May be of any type.
6690 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
6692 @item @var{MASK} @tab Shall be of type @code{LOGICAL(*)}.
6695 @item @emph{Return value}:
6696 The result is of the same type and type parameters as @var{TSOURCE}.
6703 @section @code{MIN} --- Minimum value of an argument list
6704 @cindex @code{MIN} intrinsic
6705 @cindex @code{MIN0} intrinsic
6706 @cindex @code{AMIN0} intrinsic
6707 @cindex @code{MIN1} intrinsic
6708 @cindex @code{AMIN1} intrinsic
6709 @cindex @code{DMIN1} intrinsic
6712 @item @emph{Description}:
6713 Returns the argument with the smallest (most negative) value.
6715 @item @emph{Standard}:
6721 @item @emph{Syntax}:
6722 @code{RESULT = MIN(A1, A2 [, A3, ...])}
6724 @item @emph{Arguments}:
6725 @multitable @columnfractions .15 .70
6726 @item @var{A1} @tab The type shall be @code{INTEGER(*)} or
6728 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
6729 as @var{A1}. (As a GNU extension,
6730 arguments of different kinds are
6734 @item @emph{Return value}:
6735 The return value corresponds to the maximum value among the arguments,
6736 and has the same type and kind as the first argument.
6738 @item @emph{Specific names}:
6739 @multitable @columnfractions .20 .20 .20 .25
6740 @item Name @tab Argument @tab Return type @tab Standard
6741 @item @code{MIN0(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab F77 and later
6742 @item @code{AMIN0(I)} @tab @code{INTEGER(4) I} @tab @code{REAL(MIN(X))} @tab F77 and later
6743 @item @code{MIN1(X)} @tab @code{REAL(*) X} @tab @code{INT(MIN(X))} @tab F77 and later
6744 @item @code{AMIN1(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab F77 and later
6745 @item @code{DMIN1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
6748 @item @emph{See also}:
6749 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
6755 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
6756 @cindex @code{MINEXPONENT} intrinsic
6757 @cindex minimum exponent
6758 @cindex exponent, minimum
6761 @item @emph{Description}:
6762 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
6765 @item @emph{Standard}:
6771 @item @emph{Syntax}:
6772 @code{RESULT = MINEXPONENT(X)}
6774 @item @emph{Arguments}:
6775 @multitable @columnfractions .15 .70
6776 @item @var{X} @tab Shall be of type @code{REAL}.
6779 @item @emph{Return value}:
6780 The return value is of type @code{INTEGER} and of the default integer
6783 @item @emph{Example}:
6784 See @code{MAXEXPONENT} for an example.
6790 @section @code{MINLOC} --- Location of the minimum value within an array
6791 @cindex @code{MINLOC} intrinsic
6794 @item @emph{Description}:
6795 Determines the location of the element in the array with the minimum
6796 value, or, if the @var{DIM} argument is supplied, determines the
6797 locations of the minimum element along each row of the array in the
6798 @var{DIM} direction. If @var{MASK} is present, only the elements for
6799 which @var{MASK} is @code{.TRUE.} are considered. If more than one
6800 element in the array has the minimum value, the location returned is
6801 that of the first such element in array element order. If the array has
6802 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
6803 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
6804 and all of the elements of @var{MASK} along a given row are zero, the
6805 result value for that row is zero.
6807 @item @emph{Standard}:
6811 Transformational function
6813 @item @emph{Syntax}:
6814 @multitable @columnfractions .80
6815 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
6816 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
6819 @item @emph{Arguments}:
6820 @multitable @columnfractions .15 .70
6821 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
6822 @code{REAL(*)}, or @code{CHARACTER(*)}.
6823 @item @var{DIM} @tab (Optional) Shall be a scalar of type
6824 @code{INTEGER(*)}, with a value between one
6825 and the rank of @var{ARRAY}, inclusive. It
6826 may not be an optional dummy argument.
6827 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL(*)},
6828 and conformable with @var{ARRAY}.
6831 @item @emph{Return value}:
6832 If @var{DIM} is absent, the result is a rank-one array with a length
6833 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
6834 is an array with a rank one less than the rank of @var{ARRAY}, and a
6835 size corresponding to the size of @var{ARRAY} with the @var{DIM}
6836 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
6837 of one, the result is a scalar. In all cases, the result is of default
6838 @code{INTEGER} type.
6840 @item @emph{See also}:
6841 @ref{MIN}, @ref{MINVAL}
6848 @section @code{MINVAL} --- Minimum value of an array
6849 @cindex @code{MINVAL} intrinsic
6852 @item @emph{Description}:
6853 Determines the minimum value of the elements in an array value, or, if
6854 the @var{DIM} argument is supplied, determines the minimum value along
6855 each row of the array in the @var{DIM} direction. If @var{MASK} is
6856 present, only the elements for which @var{MASK} is @code{.TRUE.} are
6857 considered. If the array has zero size, or all of the elements of
6858 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
6859 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
6860 @var{ARRAY} is of character type.
6862 @item @emph{Standard}:
6866 Transformational function
6868 @item @emph{Syntax}:
6869 @multitable @columnfractions .80
6870 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
6871 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
6874 @item @emph{Arguments}:
6875 @multitable @columnfractions .15 .70
6876 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
6877 @code{REAL(*)}, or @code{CHARACTER(*)}.
6878 @item @var{DIM} @tab (Optional) Shall be a scalar of type
6879 @code{INTEGER(*)}, with a value between one
6880 and the rank of @var{ARRAY}, inclusive. It
6881 may not be an optional dummy argument.
6882 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL(*)},
6883 and conformable with @var{ARRAY}.
6886 @item @emph{Return value}:
6887 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
6888 is a scalar. If @var{DIM} is present, the result is an array with a
6889 rank one less than the rank of @var{ARRAY}, and a size corresponding to
6890 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
6891 cases, the result is of the same type and kind as @var{ARRAY}.
6893 @item @emph{See also}:
6894 @ref{MIN}, @ref{MINLOC}
6901 @section @code{MOD} --- Remainder function
6902 @cindex @code{MOD} intrinsic
6903 @cindex @code{AMOD} intrinsic
6904 @cindex @code{DMOD} intrinsic
6908 @item @emph{Description}:
6909 @code{MOD(A,P)} computes the remainder of the division of A by P. It is
6910 calculated as @code{A - (INT(A/P) * P)}.
6912 @item @emph{Standard}:
6918 @item @emph{Syntax}:
6919 @code{RESULT = MOD(A, P)}
6921 @item @emph{Arguments}:
6922 @multitable @columnfractions .15 .70
6923 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
6924 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
6928 @item @emph{Return value}:
6929 The kind of the return value is the result of cross-promoting
6930 the kinds of the arguments.
6932 @item @emph{Example}:
6936 print *, mod(17.5,5.5)
6937 print *, mod(17.5d0,5.5)
6938 print *, mod(17.5,5.5d0)
6941 print *, mod(-17.5,5.5)
6942 print *, mod(-17.5d0,5.5)
6943 print *, mod(-17.5,5.5d0)
6946 print *, mod(17.5,-5.5)
6947 print *, mod(17.5d0,-5.5)
6948 print *, mod(17.5,-5.5d0)
6949 end program test_mod
6952 @item @emph{Specific names}:
6953 @multitable @columnfractions .20 .20 .20 .25
6954 @item Name @tab Arguments @tab Return type @tab Standard
6955 @item @code{AMOD(A,P)} @tab @code{REAL(4)} @tab @code{REAL(4)} @tab F95 and later
6956 @item @code{DMOD(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab F95 and later
6963 @section @code{MODULO} --- Modulo function
6964 @cindex @code{MODULO} intrinsic
6968 @item @emph{Description}:
6969 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
6971 @item @emph{Standard}:
6977 @item @emph{Syntax}:
6978 @code{RESULT = MODULO(A, P)}
6980 @item @emph{Arguments}:
6981 @multitable @columnfractions .15 .70
6982 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
6983 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
6986 @item @emph{Return value}:
6987 The type and kind of the result are those of the arguments.
6989 @item If @var{A} and @var{P} are of type @code{INTEGER}:
6990 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
6991 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
6993 @item If @var{A} and @var{P} are of type @code{REAL}:
6994 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
6996 In all cases, if @var{P} is zero the result is processor-dependent.
6998 @item @emph{Example}:
7001 print *, modulo(17,3)
7002 print *, modulo(17.5,5.5)
7004 print *, modulo(-17,3)
7005 print *, modulo(-17.5,5.5)
7007 print *, modulo(17,-3)
7008 print *, modulo(17.5,-5.5)
7009 end program test_mod
7017 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
7018 @cindex @code{MOVE_ALLOC} intrinsic
7019 @cindex moving allocation
7020 @cindex allocation, moving
7023 @item @emph{Description}:
7024 @code{MOVE_ALLOC(SRC, DEST)} moves the allocation from @var{SRC} to
7025 @var{DEST}. @var{SRC} will become deallocated in the process.
7027 @item @emph{Standard}:
7033 @item @emph{Syntax}:
7034 @code{CALL MOVE_ALLOC(SRC, DEST)}
7036 @item @emph{Arguments}:
7037 @multitable @columnfractions .15 .70
7038 @item @var{SRC} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
7039 of any type and kind.
7040 @item @var{DEST} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
7041 of the same type, kind and rank as @var{SRC}
7044 @item @emph{Return value}:
7047 @item @emph{Example}:
7049 program test_move_alloc
7050 integer, allocatable :: a(:), b(:)
7054 call move_alloc(a, b)
7055 print *, allocated(a), allocated(b)
7057 end program test_move_alloc
7064 @section @code{MVBITS} --- Move bits from one integer to another
7065 @cindex @code{MVBITS} intrinsic
7066 @cindex bit operations
7069 @item @emph{Description}:
7070 Moves @var{LEN} bits from positions @var{FROMPOS} through
7071 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
7072 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
7073 affected by the movement of bits is unchanged. The values of
7074 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
7075 @code{BIT_SIZE(FROM)}.
7077 @item @emph{Standard}:
7083 @item @emph{Syntax}:
7084 @code{RESULT = MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
7086 @item @emph{Arguments}:
7087 @multitable @columnfractions .15 .70
7088 @item @var{FROM} @tab The type shall be @code{INTEGER(*)}.
7089 @item @var{FROMPOS} @tab The type shall be @code{INTEGER(*)}.
7090 @item @var{LEN} @tab The type shall be @code{INTEGER(*)}.
7091 @item @var{TO} @tab The type shall be @code{INTEGER(*)}, of the
7092 same kind as @var{FROM}.
7093 @item @var{TOPOS} @tab The type shall be @code{INTEGER(*)}.
7096 @item @emph{Return value}:
7097 The return value is of type @code{INTEGER(*)} and of the same kind as
7100 @item @emph{See also}:
7101 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
7108 @section @code{NEAREST} --- Nearest representable number
7109 @cindex @code{NEAREST} intrinsic
7110 @cindex processor-representable number
7113 @item @emph{Description}:
7114 @code{NEAREST(X, S)} returns the processor-representable number nearest
7115 to @code{X} in the direction indicated by the sign of @code{S}.
7117 @item @emph{Standard}:
7123 @item @emph{Syntax}:
7124 @code{RESULT = NEAREST(X, S)}
7126 @item @emph{Arguments}:
7127 @multitable @columnfractions .15 .70
7128 @item @var{X} @tab Shall be of type @code{REAL}.
7129 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
7133 @item @emph{Return value}:
7134 The return value is of the same type as @code{X}. If @code{S} is
7135 positive, @code{NEAREST} returns the processor-representable number
7136 greater than @code{X} and nearest to it. If @code{S} is negative,
7137 @code{NEAREST} returns the processor-representable number smaller than
7138 @code{X} and nearest to it.
7140 @item @emph{Example}:
7142 program test_nearest
7144 x = nearest(42.0, 1.0)
7145 y = nearest(42.0, -1.0)
7146 write (*,"(3(G20.15))") x, y, x - y
7147 end program test_nearest
7154 @section @code{NEW_LINE} --- New line character
7155 @cindex @code{NEW_LINE} intrinsic
7156 @cindex @code{NEW_LINE} intrinsic
7159 @item @emph{Description}:
7160 @code{NEW_LINE(C)} returns the new-line character.
7162 @item @emph{Standard}:
7168 @item @emph{Syntax}:
7169 @code{RESULT = NEW_LINE(C)}
7171 @item @emph{Arguments}:
7172 @multitable @columnfractions .15 .70
7173 @item @var{C} @tab The argument shall be a scalar or array of the
7174 type @code{CHARACTER}.
7177 @item @emph{Return value}:
7178 Returns a @var{CHARACTER} scalar of length one with the new-line character of
7179 the same kind as parameter @var{C}.
7181 @item @emph{Example}:
7185 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
7193 @section @code{NINT} --- Nearest whole number
7194 @cindex @code{NINT} intrinsic
7195 @cindex @code{IDNINT} intrinsic
7196 @cindex whole number
7199 @item @emph{Description}:
7200 @code{NINT(X)} rounds its argument to the nearest whole number.
7202 @item @emph{Standard}:
7208 @item @emph{Syntax}:
7209 @code{RESULT = NINT(X)}
7211 @item @emph{Arguments}:
7212 @multitable @columnfractions .15 .70
7213 @item @var{X} @tab The type of the argument shall be @code{REAL}.
7216 @item @emph{Return value}:
7217 Returns @var{A} with the fractional portion of its magnitude eliminated by
7218 rounding to the nearest whole number and with its sign preserved,
7219 converted to an @code{INTEGER} of the default kind.
7221 @item @emph{Example}:
7228 print *, nint(x4), idnint(x8)
7229 end program test_nint
7232 @item @emph{Specific names}:
7233 @multitable @columnfractions .25 .25 .25
7234 @item Name @tab Argument @tab Standard
7235 @item @code{IDNINT(X)} @tab @code{REAL(8)} @tab F95 and later
7238 @item @emph{See also}:
7239 @ref{CEILING}, @ref{FLOOR}
7246 @section @code{NOT} --- Logical negation
7247 @cindex @code{NOT} intrinsic
7248 @cindex bit operations
7251 @item @emph{Description}:
7252 @code{NOT} returns the bitwise boolean inverse of @var{I}.
7254 @item @emph{Standard}:
7260 @item @emph{Syntax}:
7261 @code{RESULT = NOT(I)}
7263 @item @emph{Arguments}:
7264 @multitable @columnfractions .15 .70
7265 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
7268 @item @emph{Return value}:
7269 The return type is @code{INTEGER(*)}, of the same kind as the
7272 @item @emph{See also}:
7273 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
7280 @section @code{NULL} --- Function that returns an disassociated pointer
7281 @cindex @code{NULL} intrinsic
7282 @cindex undocumented intrinsic
7284 Intrinsic implemented, documentation pending.
7287 @item @emph{Description}:
7288 @item @emph{Standard}:
7292 Transformational function
7294 @item @emph{Syntax}:
7295 @item @emph{Arguments}:
7296 @item @emph{Return value}:
7297 @item @emph{Example}:
7298 @item @emph{See also}:
7305 @section @code{OR} --- Bitwise logical OR
7306 @cindex @code{OR} intrinsic
7307 @cindex bit operations
7310 @item @emph{Description}:
7311 Bitwise logical @code{OR}.
7313 This intrinsic routine is provided for backwards compatibility with
7314 GNU Fortran 77. For integer arguments, programmers should consider
7315 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
7317 @item @emph{Standard}:
7321 Non-elemental function
7323 @item @emph{Syntax}:
7324 @code{RESULT = OR(X, Y)}
7326 @item @emph{Arguments}:
7327 @multitable @columnfractions .15 .70
7328 @item @var{X} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
7329 @item @var{Y} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
7332 @item @emph{Return value}:
7333 The return type is either @code{INTEGER(*)} or @code{LOGICAL}
7334 after cross-promotion of the arguments.
7336 @item @emph{Example}:
7339 LOGICAL :: T = .TRUE., F = ..FALSE.
7341 DATA a / Z'F' /, b / Z'3' /
7343 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
7344 WRITE (*,*) OR(a, b)
7348 @item @emph{See also}:
7349 F95 elemental function: @ref{IOR}
7355 @section @code{PACK} --- Pack an array into an array of rank one
7356 @cindex @code{PACK} intrinsic
7357 @cindex undocumented intrinsic
7359 Intrinsic implemented, documentation pending.
7362 @item @emph{Description}:
7363 @item @emph{Standard}:
7367 Transformational function
7369 @item @emph{Syntax}:
7370 @item @emph{Arguments}:
7371 @item @emph{Return value}:
7372 @item @emph{Example}:
7373 @item @emph{Specific names}:
7374 @item @emph{See also}:
7381 @section @code{PERROR} --- Print system error message
7382 @cindex @code{PERROR} intrinsic
7385 @item @emph{Description}:
7386 Prints (on the C @code{stderr} stream) a newline-terminated error
7387 message corresponding to the last system error. This is prefixed by
7388 @var{STRING}, a colon and a space. See @code{perror(3)}.
7390 @item @emph{Standard}:
7396 @item @emph{Syntax}:
7397 @code{CALL PERROR(STRING)}
7399 @item @emph{Arguments}:
7400 @multitable @columnfractions .15 .70
7401 @item @var{STRING} @tab A scalar of default @code{CHARACTER} type.
7404 @item @emph{See also}:
7411 @section @code{PRECISION} --- Decimal precision of a real kind
7412 @cindex @code{PRECISION} intrinsic
7413 @cindex precision of a real variable
7416 @item @emph{Description}:
7417 @code{PRECISION(X)} returns the decimal precision in the model of the
7420 @item @emph{Standard}:
7426 @item @emph{Syntax}:
7427 @code{RESULT = PRECISION(X)}
7429 @item @emph{Arguments}:
7430 @multitable @columnfractions .15 .70
7431 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
7434 @item @emph{Return value}:
7435 The return value is of type @code{INTEGER} and of the default integer
7438 @item @emph{Example}:
7440 program prec_and_range
7441 real(kind=4) :: x(2)
7442 complex(kind=8) :: y
7444 print *, precision(x), range(x)
7445 print *, precision(y), range(y)
7446 end program prec_and_range
7453 @section @code{PRESENT} --- Determine whether an optional argument is specified
7454 @cindex @code{PRESENT} intrinsic
7455 @cindex undocumented intrinsic
7457 Intrinsic implemented, documentation pending.
7460 @item @emph{Description}:
7461 @item @emph{Standard}:
7467 @item @emph{Syntax}:
7468 @item @emph{Arguments}:
7469 @item @emph{Return value}:
7470 @item @emph{Example}:
7471 @item @emph{See also}:
7477 @section @code{PRODUCT} --- Product of array elements
7478 @cindex @code{PRODUCT} intrinsic
7479 @cindex undocumented intrinsic
7481 Intrinsic implemented, documentation pending.
7484 @item @emph{Description}:
7485 @item @emph{Standard}:
7489 Transformational function
7491 @item @emph{Syntax}:
7492 @item @emph{Arguments}:
7493 @item @emph{Return value}:
7494 @item @emph{Example}:
7495 @item @emph{Specific names}:
7496 @item @emph{See also}:
7503 @section @code{RADIX} --- Base of a model number
7504 @cindex @code{RADIX} intrinsic
7508 @item @emph{Description}:
7509 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
7511 @item @emph{Standard}:
7517 @item @emph{Syntax}:
7518 @code{RESULT = RADIX(X)}
7520 @item @emph{Arguments}:
7521 @multitable @columnfractions .15 .70
7522 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
7525 @item @emph{Return value}:
7526 The return value is a scalar of type @code{INTEGER} and of the default
7529 @item @emph{Example}:
7532 print *, "The radix for the default integer kind is", radix(0)
7533 print *, "The radix for the default real kind is", radix(0.0)
7534 end program test_radix
7542 @section @code{RAN} --- Real pseudo-random number
7543 @cindex @code{RAN} intrinsic
7544 @cindex random numbers
7547 @item @emph{Description}:
7548 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
7549 provided as an alias for @code{RAND}. See @ref{RAND} for complete
7552 @item @emph{Standard}:
7556 Non-elemental function
7558 @item @emph{See also}:
7559 @ref{RAND}, @ref{RANDOM_NUMBER}
7565 @section @code{RAND} --- Real pseudo-random number
7566 @cindex @code{RAND} intrinsic
7567 @cindex random numbers
7570 @item @emph{Description}:
7571 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
7572 distribution between 0 and 1. If @var{FLAG} is 0, the next number
7573 in the current sequence is returned; if @var{FLAG} is 1, the generator
7574 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
7575 it is used as a new seed with @code{SRAND}.
7577 @item @emph{Standard}:
7581 Non-elemental function
7583 @item @emph{Syntax}:
7584 @code{RESULT = RAND(FLAG)}
7586 @item @emph{Arguments}:
7587 @multitable @columnfractions .15 .70
7588 @item @var{FLAG} @tab Shall be a scalar @code{INTEGER} of kind 4.
7591 @item @emph{Return value}:
7592 The return value is of @code{REAL} type and the default kind.
7594 @item @emph{Example}:
7597 integer,parameter :: seed = 86456
7600 print *, rand(), rand(), rand(), rand()
7601 print *, rand(seed), rand(), rand(), rand()
7602 end program test_rand
7605 @item @emph{See also}:
7606 @ref{SRAND}, @ref{RANDOM_NUMBER}
7613 @section @code{RANDOM_NUMBER} --- Pseudo-random number
7614 @cindex @code{RANDOM_NUMBER} intrinsic
7615 @cindex random numbers
7618 @item @emph{Description}:
7619 Returns a single pseudorandom number or an array of pseudorandom numbers
7620 from the uniform distribution over the range @math{ 0 \leq x < 1}.
7622 @item @emph{Standard}:
7626 Elemental subroutine
7628 @item @emph{Syntax}:
7629 @code{RANDOM_NUMBER(HARVEST)}
7631 @item @emph{Arguments}:
7632 @multitable @columnfractions .15 .70
7633 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL(*)}.
7636 @item @emph{Example}:
7638 program test_random_number
7640 CALL init_random_seed() ! see example of RANDOM_SEED
7641 CALL RANDOM_NUMBER(r)
7646 The implemented random number generator is thread safe if used within
7647 OpenMP directives, i. e. its state will be consistent while called from
7648 multiple threads. Please note that the currently implemented KISS generator
7649 does not create random numbers in parallel from multiple sources, but in
7650 sequence from a single source. If your OpenMP-enabled application heavily
7651 relies on random numbers, you should consider employing a dedicated parallel
7652 random number generator instead.
7654 @item @emph{See also}:
7661 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
7662 @cindex @code{RANDOM_SEED} intrinsic
7663 @cindex random numbers
7666 @item @emph{Description}:
7667 Restarts or queries the state of the pseudorandom number generator used by
7668 @code{RANDOM_NUMBER}.
7670 If @code{RANDOM_SEED} is called without arguments, it is initialized to
7671 a default state. The example below shows how to initialize the random
7672 seed based on the system's time.
7674 @item @emph{Standard}:
7680 @item @emph{Syntax}:
7681 @code{CALL RANDOM_SEED(SIZE, PUT, GET)}
7683 @item @emph{Arguments}:
7684 @multitable @columnfractions .15 .70
7685 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
7686 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
7687 of the arrays used with the @var{PUT} and @var{GET} arguments.
7688 @item @var{PUT} @tab (Optional) Shall be an array of type default
7689 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
7690 the array must be larger than or equal to the number returned by the
7691 @var{SIZE} argument.
7692 @item @var{GET} @tab (Optional) Shall be an array of type default
7693 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
7694 of the array must be larger than or equal to the number returned by
7695 the @var{SIZE} argument.
7698 @item @emph{Example}:
7700 SUBROUTINE init_random_seed()
7701 INTEGER :: i, n, clock
7702 INTEGER, DIMENSION(:), ALLOCATABLE :: seed
7704 CALL RANDOM_SEED(size = n)
7707 CALL SYSTEM_CLOCK(COUNT=clock)
7709 seed = clock + 37 * (/ (i - 1, i = 1, n) /)
7710 CALL RANDOM_SEED(PUT = seed)
7716 @item @emph{See also}:
7723 @section @code{RANGE} --- Decimal exponent range of a real kind
7724 @cindex @code{RANGE} intrinsic
7725 @cindex range of a real variable
7728 @item @emph{Description}:
7729 @code{RANGE(X)} returns the decimal exponent range in the model of the
7732 @item @emph{Standard}:
7738 @item @emph{Syntax}:
7739 @code{RESULT = RANGE(X)}
7741 @item @emph{Arguments}:
7742 @multitable @columnfractions .15 .70
7743 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
7746 @item @emph{Return value}:
7747 The return value is of type @code{INTEGER} and of the default integer
7750 @item @emph{Example}:
7751 See @code{PRECISION} for an example.
7757 @section @code{REAL} --- Convert to real type
7758 @cindex @code{REAL} intrinsic
7759 @cindex @code{REALPART} intrinsic
7763 @item @emph{Description}:
7764 @code{REAL(X [, KIND])} converts its argument @var{X} to a real type. The
7765 @code{REALPART(X)} function is provided for compatibility with @command{g77},
7766 and its use is strongly discouraged.
7768 @item @emph{Standard}:
7774 @item @emph{Syntax}:
7775 @multitable @columnfractions .80
7776 @item @code{RESULT = REAL(X [, KIND])}
7777 @item @code{RESULT = REALPART(Z)}
7780 @item @emph{Arguments}:
7781 @multitable @columnfractions .15 .70
7782 @item @var{X} @tab Shall be @code{INTEGER(*)}, @code{REAL(*)}, or
7784 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
7785 expression indicating the kind parameter of
7789 @item @emph{Return value}:
7790 These functions return a @code{REAL(*)} variable or array under
7791 the following rules:
7795 @code{REAL(X)} is converted to a default real type if @var{X} is an
7796 integer or real variable.
7798 @code{REAL(X)} is converted to a real type with the kind type parameter
7799 of @var{X} if @var{X} is a complex variable.
7801 @code{REAL(X, KIND)} is converted to a real type with kind type
7802 parameter @var{KIND} if @var{X} is a complex, integer, or real
7806 @item @emph{Example}:
7809 complex :: x = (1.0, 2.0)
7810 print *, real(x), real(x,8), realpart(x)
7811 end program test_real
7814 @item @emph{See also}:
7815 @ref{DBLE}, @ref{DFLOAT}, @ref{FLOAT}
7822 @section @code{RENAME} --- Rename a file
7823 @cindex @code{RENAME} intrinsic
7824 @cindex file system operations
7827 @item @emph{Description}:
7828 Renames a file from file @var{PATH1} to @var{PATH2}. A null
7829 character (@code{CHAR(0)}) can be used to mark the end of the names in
7830 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
7831 names are ignored. If the @var{STATUS} argument is supplied, it
7832 contains 0 on success or a nonzero error code upon return; see
7835 This intrinsic is provided in both subroutine and function forms;
7836 however, only one form can be used in any given program unit.
7838 @item @emph{Standard}:
7842 Subroutine, non-elemental function
7844 @item @emph{Syntax}:
7845 @multitable @columnfractions .80
7846 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
7847 @item @code{STATUS = RENAME(PATH1, PATH2)}
7850 @item @emph{Arguments}:
7851 @multitable @columnfractions .15 .70
7852 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
7853 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
7854 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
7857 @item @emph{See also}:
7865 @section @code{REPEAT} --- Repeated string concatenation
7866 @cindex @code{REPEAT} intrinsic
7867 @cindex string manipulation
7869 Intrinsic implemented, documentation pending.
7872 @item @emph{Description}:
7873 @item @emph{Standard}:
7877 Transformational function
7879 @item @emph{Syntax}:
7880 @item @emph{Arguments}:
7881 @item @emph{Return value}:
7882 @item @emph{Example}:
7883 @item @emph{See also}:
7889 @section @code{RESHAPE} --- Function to reshape an array
7890 @cindex @code{RESHAPE} intrinsic
7891 @cindex array manipulation
7893 Intrinsic implemented, documentation pending.
7896 @item @emph{Description}:
7897 @item @emph{Standard}:
7901 Transformational function
7903 @item @emph{Syntax}:
7904 @item @emph{Arguments}:
7905 @item @emph{Return value}:
7906 @item @emph{Example}:
7907 @item @emph{See also}:
7914 @section @code{RRSPACING} --- Reciprocal of the relative spacing
7915 @cindex @code{RRSPACING} intrinsic
7918 @item @emph{Description}:
7919 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
7920 model numbers near @var{X}.
7922 @item @emph{Standard}:
7928 @item @emph{Syntax}:
7929 @code{RESULT = RRSPACING(X)}
7931 @item @emph{Arguments}:
7932 @multitable @columnfractions .15 .70
7933 @item @var{X} @tab Shall be of type @code{REAL}.
7936 @item @emph{Return value}:
7937 The return value is of the same type and kind as @var{X}.
7938 The value returned is equal to
7939 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
7946 @section @code{RSHIFT} --- Right shift bits
7947 @cindex @code{RSHIFT} intrinsic
7948 @cindex bit operations
7951 @item @emph{Description}:
7952 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
7953 bits shifted right by @var{SHIFT} places. If the absolute value of
7954 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
7955 Bits shifted out from the left end are lost; zeros are shifted in from
7958 This function has been superseded by the @code{ISHFT} intrinsic, which
7959 is standard in Fortran 95 and later.
7961 @item @emph{Standard}:
7967 @item @emph{Syntax}:
7968 @code{RESULT = RSHIFT(I, SHIFT)}
7970 @item @emph{Arguments}:
7971 @multitable @columnfractions .15 .70
7972 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
7973 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
7976 @item @emph{Return value}:
7977 The return value is of type @code{INTEGER(*)} and of the same kind as
7980 @item @emph{See also}:
7981 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}
7988 @section @code{SCALE} --- Scale a real value
7989 @cindex @code{SCALE} intrinsic
7992 @item @emph{Description}:
7993 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
7995 @item @emph{Standard}:
8001 @item @emph{Syntax}:
8002 @code{RESULT = SCALE(X, I)}
8004 @item @emph{Arguments}:
8005 @multitable @columnfractions .15 .70
8006 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
8007 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
8010 @item @emph{Return value}:
8011 The return value is of the same type and kind as @var{X}.
8012 Its value is @code{X * RADIX(X)**I}.
8014 @item @emph{Example}:
8017 real :: x = 178.1387e-4
8019 print *, scale(x,i), x*radix(x)**i
8020 end program test_scale
8028 @section @code{SCAN} --- Scan a string for the presence of a set of characters
8029 @cindex @code{SCAN} intrinsic
8030 @cindex string manipulation
8032 Intrinsic implemented, documentation pending.
8035 @item @emph{Description}:
8036 @item @emph{Standard}:
8042 @item @emph{Syntax}:
8043 @item @emph{Arguments}:
8044 @item @emph{Return value}:
8045 @item @emph{Example}:
8046 @item @emph{See also}:
8052 @section @code{SECNDS} --- Time function
8053 @cindex @code{SECNDS} intrinsic
8054 @cindex time, current
8055 @cindex current time
8058 @item @emph{Description}:
8059 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
8060 @var{X} is a reference time, also in seconds. If this is zero, the time in
8061 seconds from midnight is returned. This function is non-standard and its
8064 @item @emph{Standard}:
8068 Non-elemental function
8070 @item @emph{Syntax}:
8071 @code{RESULT = SECNDS (X)}
8073 @item @emph{Arguments}:
8074 @multitable @columnfractions .15 .70
8075 @item @var{T} @tab Shall be of type @code{REAL(4)}.
8076 @item @var{X} @tab Shall be of type @code{REAL(4)}.
8079 @item @emph{Return value}:
8082 @item @emph{Example}:
8086 print *, secnds (0.0) ! seconds since midnight
8087 t1 = secnds (0.0) ! reference time
8088 do i = 1, 10000000 ! do something
8090 t2 = secnds (t1) ! elapsed time
8091 print *, "Something took ", t2, " seconds."
8092 end program test_secnds
8099 @section @code{SECOND} --- CPU time function
8100 @cindex @code{SECOND} intrinsic
8101 @cindex time, elapsed
8102 @cindex elapsed time
8105 @item @emph{Description}:
8106 Returns a @code{REAL(4)} value representing the elapsed CPU time in
8107 seconds. This provides the same functionality as the standard
8108 @code{CPU_TIME} intrinsic, and is only included for backwards
8111 This intrinsic is provided in both subroutine and function forms;
8112 however, only one form can be used in any given program unit.
8114 @item @emph{Standard}:
8118 Subroutine, non-elemental function
8120 @item @emph{Syntax}:
8121 @multitable @columnfractions .80
8122 @item @code{CALL SECOND(TIME)}
8123 @item @code{TIME = SECOND()}
8126 @item @emph{Arguments}:
8127 @multitable @columnfractions .15 .70
8128 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
8131 @item @emph{Return value}:
8132 In either syntax, @var{TIME} is set to the process's current runtime in
8135 @item @emph{See also}:
8142 @node SELECTED_INT_KIND
8143 @section @code{SELECTED_INT_KIND} --- Choose integer kind
8144 @cindex @code{SELECTED_INT_KIND} intrinsic
8145 @cindex integer kind
8148 @item @emph{Description}:
8149 @code{SELECTED_INT_KIND(I)} return the kind value of the smallest integer
8150 type that can represent all values ranging from @math{-10^I} (exclusive)
8151 to @math{10^I} (exclusive). If there is no integer kind that accommodates
8152 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
8154 @item @emph{Standard}:
8158 Transformational function
8160 @item @emph{Syntax}:
8161 @code{RESULT = SELECTED_INT_KIND(I)}
8163 @item @emph{Arguments}:
8164 @multitable @columnfractions .15 .70
8165 @item @var{I} @tab Shall be a scalar and of type @code{INTEGER}.
8168 @item @emph{Example}:
8170 program large_integers
8171 integer,parameter :: k5 = selected_int_kind(5)
8172 integer,parameter :: k15 = selected_int_kind(15)
8173 integer(kind=k5) :: i5
8174 integer(kind=k15) :: i15
8176 print *, huge(i5), huge(i15)
8178 ! The following inequalities are always true
8179 print *, huge(i5) >= 10_k5**5-1
8180 print *, huge(i15) >= 10_k15**15-1
8181 end program large_integers
8187 @node SELECTED_REAL_KIND
8188 @section @code{SELECTED_REAL_KIND} --- Choose real kind
8189 @cindex @code{SELECTED_REAL_KIND} intrinsic
8193 @item @emph{Description}:
8194 @code{SELECTED_REAL_KIND(P,R)} return the kind value of a real data type
8195 with decimal precision greater of at least @code{P} digits and exponent
8196 range greater at least @code{R}.
8198 @item @emph{Standard}:
8202 Transformational function
8204 @item @emph{Syntax}:
8205 @code{RESULT = SELECTED_REAL_KIND(P, R)}
8207 @item @emph{Arguments}:
8208 @multitable @columnfractions .15 .70
8209 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
8210 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
8212 At least one argument shall be present.
8214 @item @emph{Return value}:
8216 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
8217 a real data type with decimal precision of at least @code{P} digits and a
8218 decimal exponent range of at least @code{R}. If more than one real data
8219 type meet the criteria, the kind of the data type with the smallest
8220 decimal precision is returned. If no real data type matches the criteria,
8223 @item -1 if the processor does not support a real data type with a
8224 precision greater than or equal to @code{P}
8225 @item -2 if the processor does not support a real type with an exponent
8226 range greater than or equal to @code{R}
8227 @item -3 if neither is supported.
8230 @item @emph{Example}:
8233 integer,parameter :: p6 = selected_real_kind(6)
8234 integer,parameter :: p10r100 = selected_real_kind(10,100)
8235 integer,parameter :: r400 = selected_real_kind(r=400)
8237 real(kind=p10r100) :: y
8238 real(kind=r400) :: z
8240 print *, precision(x), range(x)
8241 print *, precision(y), range(y)
8242 print *, precision(z), range(z)
8243 end program real_kinds
8250 @section @code{SET_EXPONENT} --- Set the exponent of the model
8251 @cindex @code{SET_EXPONENT} intrinsic
8252 @cindex exponent part of a real number
8255 @item @emph{Description}:
8256 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
8257 is that that of @var{X} and whose exponent part is @var{I}.
8259 @item @emph{Standard}:
8265 @item @emph{Syntax}:
8266 @code{RESULT = SET_EXPONENT(X, I)}
8268 @item @emph{Arguments}:
8269 @multitable @columnfractions .15 .70
8270 @item @var{X} @tab Shall be of type @code{REAL}.
8271 @item @var{I} @tab Shall be of type @code{INTEGER}.
8274 @item @emph{Return value}:
8275 The return value is of the same type and kind as @var{X}.
8276 The real number whose fractional part
8277 is that that of @var{X} and whose exponent part if @var{I} is returned;
8278 it is @code{FRACTION(X) * RADIX(X)**I}.
8280 @item @emph{Example}:
8283 real :: x = 178.1387e-4
8285 print *, set_exponent(x), fraction(x) * radix(x)**i
8286 end program test_setexp
8294 @section @code{SHAPE} --- Determine the shape of an array
8295 @cindex @code{SHAPE} intrinsic
8296 @cindex array manipulation
8298 Intrinsic implemented, documentation pending.
8301 @item @emph{Description}:
8302 @item @emph{Standard}:
8308 @item @emph{Syntax}:
8309 @item @emph{Arguments}:
8310 @item @emph{Return value}:
8311 @item @emph{Example}:
8312 @item @emph{See also}:
8319 @section @code{SIGN} --- Sign copying function
8320 @cindex @code{SIGN} intrinsic
8321 @cindex @code{ISIGN} intrinsic
8322 @cindex @code{DSIGN} intrinsic
8323 @cindex sign copying
8326 @item @emph{Description}:
8327 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
8329 @item @emph{Standard}:
8335 @item @emph{Syntax}:
8336 @code{RESULT = SIGN(A, B)}
8338 @item @emph{Arguments}:
8339 @multitable @columnfractions .15 .70
8340 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8341 @item @var{B} @tab Shall be a scalar of the same type and kind as @var{A}
8344 @item @emph{Return value}:
8345 The kind of the return value is that of @var{A} and @var{B}.
8346 If @math{B\ge 0} then the result is @code{ABS(A)}, else
8347 it is @code{-ABS(A)}.
8349 @item @emph{Example}:
8352 print *, sign(-12,1)
8353 print *, sign(-12,0)
8354 print *, sign(-12,-1)
8356 print *, sign(-12.,1.)
8357 print *, sign(-12.,0.)
8358 print *, sign(-12.,-1.)
8359 end program test_sign
8362 @item @emph{Specific names}:
8363 @multitable @columnfractions .20 .20 .20 .25
8364 @item Name @tab Arguments @tab Return type @tab Standard
8365 @item @code{ISIGN(A,P)} @tab @code{INTEGER(4)} @tab @code{INTEGER(4)} @tab f95, gnu
8366 @item @code{DSIGN(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab f95, gnu
8373 @section @code{SIGNAL} --- Signal handling subroutine (or function)
8374 @cindex @code{SIGNAL} intrinsic
8375 @cindex signal handling
8378 @item @emph{Description}:
8379 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
8380 @var{HANDLER} to be executed with a single integer argument when signal
8381 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
8382 turn off handling of signal @var{NUMBER} or revert to its default
8383 action. See @code{signal(2)}.
8385 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
8386 is supplied, it is set to the value returned by @code{signal(2)}.
8388 @item @emph{Standard}:
8392 Subroutine, non-elemental function
8394 @item @emph{Syntax}:
8395 @multitable @columnfractions .80
8396 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
8397 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
8400 @item @emph{Arguments}:
8401 @multitable @columnfractions .15 .70
8402 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
8403 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
8404 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
8405 @code{INTEGER}. It is @code{INTENT(IN)}.
8406 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
8407 integer. It has @code{INTENT(OUT)}.
8410 @item @emph{Return value}:
8411 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
8413 @item @emph{Example}:
8417 external handler_print
8419 call signal (12, handler_print)
8423 end program test_signal
8430 @section @code{SIN} --- Sine function
8431 @cindex @code{SIN} intrinsic
8432 @cindex @code{DSIN} intrinsic
8433 @cindex @code{CSIN} intrinsic
8434 @cindex @code{ZSIN} intrinsic
8435 @cindex @code{CDSIN} intrinsic
8436 @cindex trigonometric functions
8439 @item @emph{Description}:
8440 @code{SIN(X)} computes the sine of @var{X}.
8442 @item @emph{Standard}:
8448 @item @emph{Syntax}:
8449 @code{RESULT = SIN(X)}
8451 @item @emph{Arguments}:
8452 @multitable @columnfractions .15 .70
8453 @item @var{X} @tab The type shall be @code{REAL(*)} or
8457 @item @emph{Return value}:
8458 The return value has same type and kind as @var{X}.
8460 @item @emph{Example}:
8465 end program test_sin
8468 @item @emph{Specific names}:
8469 @multitable @columnfractions .20 .20 .20 .25
8470 @item Name @tab Argument @tab Return type @tab Standard
8471 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
8472 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
8473 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
8474 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
8477 @item @emph{See also}:
8484 @section @code{SINH} --- Hyperbolic sine function
8485 @cindex @code{SINH} intrinsic
8486 @cindex @code{DSINH} intrinsic
8487 @cindex hyperbolic sine
8490 @item @emph{Description}:
8491 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
8493 @item @emph{Standard}:
8499 @item @emph{Syntax}:
8500 @code{RESULT = SINH(X)}
8502 @item @emph{Arguments}:
8503 @multitable @columnfractions .15 .70
8504 @item @var{X} @tab The type shall be @code{REAL(*)}.
8507 @item @emph{Return value}:
8508 The return value is of type @code{REAL(*)}.
8510 @item @emph{Example}:
8513 real(8) :: x = - 1.0_8
8515 end program test_sinh
8518 @item @emph{Specific names}:
8519 @multitable @columnfractions .20 .20 .20 .25
8520 @item Name @tab Argument @tab Return type @tab Standard
8521 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
8524 @item @emph{See also}:
8531 @section @code{SIZE} --- Determine the size of an array
8532 @cindex @code{SIZE} intrinsic
8533 @cindex array manipulation
8535 Intrinsic implemented, documentation pending.
8538 @item @emph{Description}:
8539 @item @emph{Standard}:
8545 @item @emph{Syntax}:
8546 @item @emph{Arguments}:
8547 @item @emph{Return value}:
8548 @item @emph{Example}:
8549 @item @emph{See also}:
8555 @section @code{SLEEP} --- Sleep for the specified number of seconds
8556 @cindex @code{SLEEP} intrinsic
8559 @item @emph{Description}:
8560 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
8562 @item @emph{Standard}:
8568 @item @emph{Syntax}:
8569 @code{CALL SLEEP(SECONDS)}
8571 @item @emph{Arguments}:
8572 @multitable @columnfractions .15 .70
8573 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
8576 @item @emph{Example}:
8587 @section @code{SNGL} --- Convert double precision real to default real
8588 @cindex @code{SNGL} intrinsic
8589 @cindex conversion function (real)
8592 @item @emph{Description}:
8593 @code{SNGL(A)} converts the double precision real @var{A}
8594 to a default real value. This is an archaic form of @code{REAL}
8595 that is specific to one type for @var{A}.
8597 @item @emph{Standard}:
8603 @item @emph{Syntax}:
8604 @code{RESULT = SNGL(A)}
8606 @item @emph{Arguments}:
8607 @multitable @columnfractions .15 .70
8608 @item @var{A} @tab The type shall be a double precision @code{REAL}.
8611 @item @emph{Return value}:
8612 The return value is of type default @code{REAL}.
8614 @item @emph{See also}:
8621 @section @code{SPACING} --- Smallest distance between two numbers of a given type
8622 @cindex @code{SPACING} intrinsic
8623 @cindex undocumented intrinsic
8625 Intrinsic implemented, documentation pending.
8628 @item @emph{Description}:
8629 @item @emph{Standard}:
8635 @item @emph{Syntax}:
8636 @item @emph{Arguments}:
8637 @item @emph{Return value}:
8638 @item @emph{Example}:
8639 @item @emph{See also}:
8645 @section @code{SPREAD} --- Add a dimension to an array
8646 @cindex @code{SPREAD} intrinsic
8647 @cindex array manipulation
8649 Intrinsic implemented, documentation pending.
8652 @item @emph{Description}:
8653 @item @emph{Standard}:
8657 Transformational function
8659 @item @emph{Syntax}:
8660 @item @emph{Arguments}:
8661 @item @emph{Return value}:
8662 @item @emph{Example}:
8663 @item @emph{See also}:
8669 @section @code{SQRT} --- Square-root function
8670 @cindex @code{SQRT} intrinsic
8671 @cindex @code{DSQRT} intrinsic
8672 @cindex @code{CSQRT} intrinsic
8673 @cindex @code{ZSQRT} intrinsic
8674 @cindex @code{CDSQRT} intrinsic
8678 @item @emph{Description}:
8679 @code{SQRT(X)} computes the square root of @var{X}.
8681 @item @emph{Standard}:
8687 @item @emph{Syntax}:
8688 @code{RESULT = SQRT(X)}
8690 @item @emph{Arguments}:
8691 @multitable @columnfractions .15 .70
8692 @item @var{X} @tab The type shall be @code{REAL(*)} or
8696 @item @emph{Return value}:
8697 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
8698 The kind type parameter is the same as @var{X}.
8700 @item @emph{Example}:
8703 real(8) :: x = 2.0_8
8704 complex :: z = (1.0, 2.0)
8707 end program test_sqrt
8710 @item @emph{Specific names}:
8711 @multitable @columnfractions .20 .20 .20 .25
8712 @item Name @tab Argument @tab Return type @tab Standard
8713 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
8714 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab F95 and later
8715 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
8716 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
8723 @section @code{SRAND} --- Reinitialize the random number generator
8724 @cindex @code{SRAND} intrinsic
8725 @cindex random numbers
8728 @item @emph{Description}:
8729 @code{SRAND} reinitializes the pseudo-random number generator
8730 called by @code{RAND} and @code{IRAND}. The new seed used by the
8731 generator is specified by the required argument @var{SEED}.
8733 @item @emph{Standard}:
8737 Non-elemental subroutine
8739 @item @emph{Syntax}:
8740 @code{CALL SRAND(SEED)}
8742 @item @emph{Arguments}:
8743 @multitable @columnfractions .15 .70
8744 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
8747 @item @emph{Return value}:
8750 @item @emph{Example}:
8751 See @code{RAND} and @code{IRAND} for examples.
8754 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
8755 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
8756 to generate pseudo-random numbers. Please note that in
8757 GNU Fortran, these two sets of intrinsics (@code{RAND},
8758 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
8759 @code{RANDOM_SEED} on the other hand) access two independent
8760 pseudo-random number generators.
8762 @item @emph{See also}:
8763 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
8770 @section @code{STAT} --- Get file status
8771 @cindex @code{STAT} intrinsic
8772 @cindex file system operations
8775 @item @emph{Description}:
8776 This function returns information about a file. No permissions are required on
8777 the file itself, but execute (search) permission is required on all of the
8778 directories in path that lead to the file.
8780 The elements that are obtained and stored in the array @code{BUFF}:
8781 @multitable @columnfractions .15 .70
8782 @item @code{buff(1)} @tab Device ID
8783 @item @code{buff(2)} @tab Inode number
8784 @item @code{buff(3)} @tab File mode
8785 @item @code{buff(4)} @tab Number of links
8786 @item @code{buff(5)} @tab Owner's uid
8787 @item @code{buff(6)} @tab Owner's gid
8788 @item @code{buff(7)} @tab ID of device containing directory entry for file (0 if not available)
8789 @item @code{buff(8)} @tab File size (bytes)
8790 @item @code{buff(9)} @tab Last access time
8791 @item @code{buff(10)} @tab Last modification time
8792 @item @code{buff(11)} @tab Last file status change time
8793 @item @code{buff(12)} @tab Preferred I/O block size (-1 if not available)
8794 @item @code{buff(13)} @tab Number of blocks allocated (-1 if not available)
8797 Not all these elements are relevant on all systems.
8798 If an element is not relevant, it is returned as 0.
8801 @item @emph{Standard}:
8805 Non-elemental subroutine
8807 @item @emph{Syntax}:
8808 @code{CALL STAT(FILE,BUFF[,STATUS])}
8810 @item @emph{Arguments}:
8811 @multitable @columnfractions .15 .70
8812 @item @var{FILE} @tab The type shall be @code{CHARACTER(*)}, a valid path within the file system.
8813 @item @var{BUFF} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
8814 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
8815 on success and a system specific error code otherwise.
8818 @item @emph{Example}:
8821 INTEGER, DIMENSION(13) :: buff
8824 CALL STAT("/etc/passwd", buff, status)
8826 IF (status == 0) THEN
8827 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
8828 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
8829 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
8830 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
8831 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
8832 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
8833 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
8834 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
8835 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
8836 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
8837 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
8838 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
8839 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
8844 @item @emph{See also}:
8845 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
8851 @section @code{SUM} --- Sum of array elements
8852 @cindex @code{SUM} intrinsic
8853 @cindex array manipulation
8855 Intrinsic implemented, documentation pending.
8858 @item @emph{Description}:
8859 @item @emph{Standard}:
8863 Transformational function
8865 @item @emph{Syntax}:
8866 @item @emph{Arguments}:
8867 @item @emph{Return value}:
8868 @item @emph{Example}:
8869 @item @emph{See also}:
8876 @section @code{SYMLNK} --- Create a symbolic link
8877 @cindex @code{SYMLNK} intrinsic
8878 @cindex file system operations
8881 @item @emph{Description}:
8882 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
8883 character (@code{CHAR(0)}) can be used to mark the end of the names in
8884 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
8885 names are ignored. If the @var{STATUS} argument is supplied, it
8886 contains 0 on success or a nonzero error code upon return; see
8887 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
8888 @code{ENOSYS} is returned.
8890 This intrinsic is provided in both subroutine and function forms;
8891 however, only one form can be used in any given program unit.
8893 @item @emph{Standard}:
8897 Subroutine, non-elemental function
8899 @item @emph{Syntax}:
8900 @multitable @columnfractions .80
8901 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
8902 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
8905 @item @emph{Arguments}:
8906 @multitable @columnfractions .15 .70
8907 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
8908 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
8909 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
8912 @item @emph{See also}:
8913 @ref{LINK}, @ref{UNLINK}
8920 @section @code{SYSTEM} --- Execute a shell command
8921 @cindex @code{SYSTEM} intrinsic
8924 @item @emph{Description}:
8925 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
8926 argument @var{STATUS} is present, it contains the value returned by
8927 @code{system(3)}, which is presumably 0 if the shell command succeeded.
8928 Note that which shell is used to invoke the command is system-dependent
8929 and environment-dependent.
8931 This intrinsic is provided in both subroutine and function forms;
8932 however, only one form can be used in any given program unit.
8934 @item @emph{Standard}:
8938 Subroutine, non-elemental function
8940 @item @emph{Syntax}:
8941 @multitable @columnfractions .80
8942 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
8943 @item @code{STATUS = SYSTEM(COMMAND)}
8946 @item @emph{Arguments}:
8947 @multitable @columnfractions .15 .70
8948 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
8949 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
8952 @item @emph{See also}:
8958 @section @code{SYSTEM_CLOCK} --- Time function
8959 @cindex @code{SYSTEM_CLOCK} intrinsic
8960 @cindex time, current
8961 @cindex current time
8963 Intrinsic implemented, documentation pending.
8966 @item @emph{Description}:
8967 @item @emph{Standard}:
8973 @item @emph{Syntax}:
8974 @item @emph{Arguments}:
8975 @item @emph{Return value}:
8976 @item @emph{Example}:
8977 @item @emph{See also}:
8983 @section @code{TAN} --- Tangent function
8984 @cindex @code{TAN} intrinsic
8985 @cindex @code{DTAN} intrinsic
8986 @cindex trigonometric functions
8989 @item @emph{Description}:
8990 @code{TAN(X)} computes the tangent of @var{X}.
8992 @item @emph{Standard}:
8998 @item @emph{Syntax}:
8999 @code{RESULT = TAN(X)}
9001 @item @emph{Arguments}:
9002 @multitable @columnfractions .15 .70
9003 @item @var{X} @tab The type shall be @code{REAL(*)}.
9006 @item @emph{Return value}:
9007 The return value is of type @code{REAL(*)}. The kind type parameter is
9008 the same as @var{X}.
9010 @item @emph{Example}:
9013 real(8) :: x = 0.165_8
9015 end program test_tan
9018 @item @emph{Specific names}:
9019 @multitable @columnfractions .20 .20 .20 .25
9020 @item Name @tab Argument @tab Return type @tab Standard
9021 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
9024 @item @emph{See also}:
9031 @section @code{TANH} --- Hyperbolic tangent function
9032 @cindex @code{TANH} intrinsic
9033 @cindex @code{DTANH} intrinsic
9034 @cindex hyperbolic tangent
9037 @item @emph{Description}:
9038 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
9040 @item @emph{Standard}:
9046 @item @emph{Syntax}:
9049 @item @emph{Arguments}:
9050 @multitable @columnfractions .15 .70
9051 @item @var{X} @tab The type shall be @code{REAL(*)}.
9054 @item @emph{Return value}:
9055 The return value is of type @code{REAL(*)} and lies in the range
9056 @math{ - 1 \leq tanh(x) \leq 1 }.
9058 @item @emph{Example}:
9061 real(8) :: x = 2.1_8
9063 end program test_tanh
9066 @item @emph{Specific names}:
9067 @multitable @columnfractions .20 .20 .20 .25
9068 @item Name @tab Argument @tab Return type @tab Standard
9069 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
9072 @item @emph{See also}:
9079 @section @code{TIME} --- Time function
9080 @cindex @code{TIME} intrinsic
9081 @cindex time, current
9082 @cindex current time
9085 @item @emph{Description}:
9086 Returns the current time encoded as an integer (in the manner of the
9087 UNIX function @code{time(3)}). This value is suitable for passing to
9088 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
9090 This intrinsic is not fully portable, such as to systems with 32-bit
9091 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
9092 the values returned by this intrinsic might be, or become, negative, or
9093 numerically less than previous values, during a single run of the
9096 See @ref{TIME8}, for information on a similar intrinsic that might be
9097 portable to more GNU Fortran implementations, though to fewer Fortran
9100 @item @emph{Standard}:
9104 Non-elemental function
9106 @item @emph{Syntax}:
9107 @code{RESULT = TIME()}
9109 @item @emph{Return value}:
9110 The return value is a scalar of type @code{INTEGER(4)}.
9112 @item @emph{See also}:
9113 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
9120 @section @code{TIME8} --- Time function (64-bit)
9121 @cindex @code{TIME8} intrinsic
9122 @cindex time, current
9123 @cindex current time
9126 @item @emph{Description}:
9127 Returns the current time encoded as an integer (in the manner of the
9128 UNIX function @code{time(3)}). This value is suitable for passing to
9129 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
9131 @emph{Warning:} this intrinsic does not increase the range of the timing
9132 values over that returned by @code{time(3)}. On a system with a 32-bit
9133 @code{time(3)}, @code{TIME8()} will return a 32-bit value, even though
9134 it is converted to a 64-bit @code{INTEGER(8)} value. That means
9135 overflows of the 32-bit value can still occur. Therefore, the values
9136 returned by this intrinsic might be or become negative or numerically
9137 less than previous values during a single run of the compiled program.
9139 @item @emph{Standard}:
9143 Non-elemental function
9145 @item @emph{Syntax}:
9146 @code{RESULT = TIME8()}
9148 @item @emph{Return value}:
9149 The return value is a scalar of type @code{INTEGER(8)}.
9151 @item @emph{See also}:
9152 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
9159 @section @code{TINY} --- Smallest positive number of a real kind
9160 @cindex @code{TINY} intrinsic
9164 @item @emph{Description}:
9165 @code{TINY(X)} returns the smallest positive (non zero) number
9166 in the model of the type of @code{X}.
9168 @item @emph{Standard}:
9174 @item @emph{Syntax}:
9175 @code{RESULT = TINY(X)}
9177 @item @emph{Arguments}:
9178 @multitable @columnfractions .15 .70
9179 @item @var{X} @tab Shall be of type @code{REAL}.
9182 @item @emph{Return value}:
9183 The return value is of the same type and kind as @var{X}
9185 @item @emph{Example}:
9186 See @code{HUGE} for an example.
9192 @section @code{TRANSFER} --- Transfer bit patterns
9193 @cindex @code{TRANSFER} intrinsic
9194 @cindex bit operations
9196 Intrinsic implemented, documentation pending.
9199 @item @emph{Description}:
9200 @item @emph{Standard}:
9204 Transformational function
9206 @item @emph{Syntax}:
9207 @item @emph{Arguments}:
9208 @item @emph{Return value}:
9209 @item @emph{Example}:
9210 @item @emph{See also}:
9216 @section @code{TRANSPOSE} --- Transpose an array of rank two
9217 @cindex @code{TRANSPOSE} intrinsic
9218 @cindex matrix manipulation
9220 Intrinsic implemented, documentation pending.
9223 @item @emph{Description}:
9224 @item @emph{Standard}:
9228 Transformational function
9230 @item @emph{Syntax}:
9231 @item @emph{Arguments}:
9232 @item @emph{Return value}:
9233 @item @emph{Example}:
9234 @item @emph{See also}:
9240 @section @code{TRIM} --- Function to remove trailing blank characters of a string
9241 @cindex @code{TRIM} intrinsic
9242 @cindex string manipulation
9244 Intrinsic implemented, documentation pending.
9247 @item @emph{Description}:
9248 @item @emph{Standard}:
9252 Transformational function
9254 @item @emph{Syntax}:
9255 @item @emph{Arguments}:
9256 @item @emph{Return value}:
9257 @item @emph{Example}:
9258 @item @emph{See also}:
9264 @section @code{TTYNAM} --- Get the name of a terminal device.
9265 @cindex @code{TTYNAM} intrinsic
9268 @item @emph{Description}:
9269 Get the name of a terminal device. For more information,
9270 see @code{ttyname(3)}.
9272 This intrinsic is provided in both subroutine and function forms;
9273 however, only one form can be used in any given program unit.
9275 @item @emph{Standard}:
9279 Subroutine, non-elemental function
9281 @item @emph{Syntax}:
9282 @multitable @columnfractions .80
9283 @item @code{CALL TTYNAM(UNIT, NAME)}
9284 @item @code{NAME = TTYNAM(UNIT)}
9287 @item @emph{Arguments}:
9288 @multitable @columnfractions .15 .70
9289 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER(*)}.
9290 @item @var{NAME} @tab Shall be of type @code{CHARACTER(*)}.
9293 @item @emph{Example}:
9298 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
9303 @item @emph{See also}:
9310 @section @code{UBOUND} --- Upper dimension bounds of an array
9311 @cindex @code{UBOUND} intrinsic
9314 @item @emph{Description}:
9315 Returns the upper bounds of an array, or a single upper bound
9316 along the @var{DIM} dimension.
9317 @item @emph{Standard}:
9323 @item @emph{Syntax}:
9324 @code{RESULT = UBOUND(ARRAY [, DIM])}
9326 @item @emph{Arguments}:
9327 @multitable @columnfractions .15 .70
9328 @item @var{ARRAY} @tab Shall be an array, of any type.
9329 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER(*)}.
9332 @item @emph{Return value}:
9333 If @var{DIM} is absent, the result is an array of the upper bounds of
9334 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
9335 corresponding to the upper bound of the array along that dimension. If
9336 @var{ARRAY} is an expression rather than a whole array or array
9337 structure component, or if it has a zero extent along the relevant
9338 dimension, the upper bound is taken to be the number of elements along
9339 the relevant dimension.
9341 @item @emph{See also}:
9348 @section @code{UMASK} --- Set the file creation mask
9349 @cindex @code{UMASK} intrinsic
9350 @cindex file system operations
9353 @item @emph{Description}:
9354 Sets the file creation mask to @var{MASK} and returns the old value in
9355 argument @var{OLD} if it is supplied. See @code{umask(2)}.
9357 @item @emph{Standard}:
9363 @item @emph{Syntax}:
9364 @code{CALL UMASK(MASK [, OLD])}
9366 @item @emph{Arguments}:
9367 @multitable @columnfractions .15 .70
9368 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER(*)}.
9369 @item @var{MASK} @tab (Optional) Shall be a scalar of type
9378 @section @code{UNLINK} --- Remove a file from the file system
9379 @cindex @code{UNLINK} intrinsic
9380 @cindex file system operations
9383 @item @emph{Description}:
9384 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
9385 used to mark the end of the name in @var{PATH}; otherwise, trailing
9386 blanks in the file name are ignored. If the @var{STATUS} argument is
9387 supplied, it contains 0 on success or a nonzero error code upon return;
9388 see @code{unlink(2)}.
9390 This intrinsic is provided in both subroutine and function forms;
9391 however, only one form can be used in any given program unit.
9393 @item @emph{Standard}:
9397 Subroutine, non-elemental function
9399 @item @emph{Syntax}:
9400 @multitable @columnfractions .80
9401 @item @code{CALL UNLINK(PATH [, STATUS])}
9402 @item @code{STATUS = UNLINK(PATH)}
9405 @item @emph{Arguments}:
9406 @multitable @columnfractions .15 .70
9407 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
9408 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9411 @item @emph{See also}:
9412 @ref{LINK}, @ref{SYMLNK}
9418 @section @code{UNPACK} --- Unpack an array of rank one into an array
9419 @cindex @code{UNPACK} intrinsic
9420 @cindex array manipulation
9422 Intrinsic implemented, documentation pending.
9425 @item @emph{Description}:
9426 @item @emph{Standard}:
9430 Transformational function
9432 @item @emph{Syntax}:
9433 @item @emph{Arguments}:
9434 @item @emph{Return value}:
9435 @item @emph{Example}:
9437 @item @emph{See also}:
9444 @section @code{VERIFY} --- Scan a string for the absence of a set of characters
9445 @cindex @code{VERIFY} intrinsic
9446 @cindex string manipulation
9448 Intrinsic implemented, documentation pending.
9451 @item @emph{Description}:
9452 @item @emph{Standard}:
9458 @item @emph{Syntax}:
9459 @item @emph{Arguments}:
9460 @item @emph{Return value}:
9461 @item @emph{Example}:
9462 @item @emph{Specific names}:
9463 @item @emph{See also}:
9469 @section @code{XOR} --- Bitwise logical exclusive OR
9470 @cindex @code{XOR} intrinsic
9471 @cindex bit operations
9474 @item @emph{Description}:
9475 Bitwise logical exclusive or.
9477 This intrinsic routine is provided for backwards compatibility with
9478 GNU Fortran 77. For integer arguments, programmers should consider
9479 the use of the @ref{IEOR} intrinsic defined by the Fortran standard.
9481 @item @emph{Standard}:
9485 Non-elemental function
9487 @item @emph{Syntax}:
9488 @code{RESULT = XOR(X, Y)}
9490 @item @emph{Arguments}:
9491 @multitable @columnfractions .15 .70
9492 @item @var{X} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
9493 @item @var{Y} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
9496 @item @emph{Return value}:
9497 The return type is either @code{INTEGER(*)} or @code{LOGICAL}
9498 after cross-promotion of the arguments.
9500 @item @emph{Example}:
9503 LOGICAL :: T = .TRUE., F = .FALSE.
9505 DATA a / Z,'F' /, b / Z'3' /
9507 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
9508 WRITE (*,*) XOR(a, b)
9512 @item @emph{See also}:
9513 F95 elemental function: @ref{IEOR}