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{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer
74 * @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer
75 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
76 * @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure
77 * @code{C_LOC}: C_LOC, Obtain the C address of an object
78 * @code{CEILING}: CEILING, Integer ceiling function
79 * @code{CHAR}: CHAR, Integer-to-character conversion function
80 * @code{CHDIR}: CHDIR, Change working directory
81 * @code{CHMOD}: CHMOD, Change access permissions of files
82 * @code{CMPLX}: CMPLX, Complex conversion function
83 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
84 * @code{COMPLEX}: COMPLEX, Complex conversion function
85 * @code{CONJG}: CONJG, Complex conjugate function
86 * @code{COS}: COS, Cosine function
87 * @code{COSH}: COSH, Hyperbolic cosine function
88 * @code{COUNT}: COUNT, Count occurrences of TRUE in an array
89 * @code{CPU_TIME}: CPU_TIME, CPU time subroutine
90 * @code{CSHIFT}: CSHIFT, Circular shift elements of an array
91 * @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string
92 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
93 * @code{DBLE}: DBLE, Double precision conversion function
94 * @code{DCMPLX}: DCMPLX, Double complex conversion function
95 * @code{DFLOAT}: DFLOAT, Double precision conversion function
96 * @code{DIGITS}: DIGITS, Significant digits function
97 * @code{DIM}: DIM, Positive difference
98 * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
99 * @code{DPROD}: DPROD, Double product function
100 * @code{DREAL}: DREAL, Double real part function
101 * @code{DTIME}: DTIME, Execution time subroutine (or function)
102 * @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array
103 * @code{EPSILON}: EPSILON, Epsilon function
104 * @code{ERF}: ERF, Error function
105 * @code{ERFC}: ERFC, Complementary error function
106 * @code{ETIME}: ETIME, Execution time subroutine (or function)
107 * @code{EXIT}: EXIT, Exit the program with status.
108 * @code{EXP}: EXP, Exponential function
109 * @code{EXPONENT}: EXPONENT, Exponent function
110 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
111 * @code{FGET}: FGET, Read a single character in stream mode from stdin
112 * @code{FGETC}: FGETC, Read a single character in stream mode
113 * @code{FLOAT}: FLOAT, Convert integer to default real
114 * @code{FLOOR}: FLOOR, Integer floor function
115 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
116 * @code{FNUM}: FNUM, File number function
117 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
118 * @code{FPUTC}: FPUTC, Write a single character in stream mode
119 * @code{FRACTION}: FRACTION, Fractional part of the model representation
120 * @code{FREE}: FREE, Memory de-allocation subroutine
121 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
122 * @code{FSTAT}: FSTAT, Get file status
123 * @code{FTELL}: FTELL, Current stream position
124 * @code{GERROR}: GERROR, Get last system error message
125 * @code{GETARG}: GETARG, Get command line arguments
126 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
127 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
128 * @code{GETCWD}: GETCWD, Get current working directory
129 * @code{GETENV}: GETENV, Get an environmental variable
130 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
131 * @code{GETGID}: GETGID, Group ID function
132 * @code{GETLOG}: GETLOG, Get login name
133 * @code{GETPID}: GETPID, Process ID function
134 * @code{GETUID}: GETUID, User ID function
135 * @code{GMTIME}: GMTIME, Convert time to GMT info
136 * @code{HOSTNM}: HOSTNM, Get system host name
137 * @code{HUGE}: HUGE, Largest number of a kind
138 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
139 * @code{IAND}: IAND, Bitwise logical and
140 * @code{IARGC}: IARGC, Get the number of command line arguments
141 * @code{IBCLR}: IBCLR, Clear bit
142 * @code{IBITS}: IBITS, Bit extraction
143 * @code{IBSET}: IBSET, Set bit
144 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
145 * @code{IDATE}: IDATE, Current local time (day/month/year)
146 * @code{IEOR}: IEOR, Bitwise logical exclusive or
147 * @code{IERRNO}: IERRNO, Function to get the last system error number
148 * @code{INDEX}: INDEX, Position of a substring within a string
149 * @code{INT}: INT, Convert to integer type
150 * @code{INT2}: INT2, Convert to 16-bit integer type
151 * @code{INT8}: INT8, Convert to 64-bit integer type
152 * @code{IOR}: IOR, Bitwise logical or
153 * @code{IRAND}: IRAND, Integer pseudo-random number
154 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
155 * @code{ISHFT}: ISHFT, Shift bits
156 * @code{ISHFTC}: ISHFTC, Shift bits circularly
157 * @code{ISNAN}: ISNAN, Tests for a NaN
158 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
159 * @code{KILL}: KILL, Send a signal to a process
160 * @code{KIND}: KIND, Kind of an entity
161 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
162 * @code{LEN}: LEN, Length of a character entity
163 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
164 * @code{LGE}: LGE, Lexical greater than or equal
165 * @code{LGT}: LGT, Lexical greater than
166 * @code{LINK}: LINK, Create a hard link
167 * @code{LLE}: LLE, Lexical less than or equal
168 * @code{LLT}: LLT, Lexical less than
169 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
170 * @code{LOC}: LOC, Returns the address of a variable
171 * @code{LOG}: LOG, Logarithm function
172 * @code{LOG10}: LOG10, Base 10 logarithm function
173 * @code{LOGICAL}: LOGICAL, Convert to logical type
174 * @code{LONG}: LONG, Convert to integer type
175 * @code{LSHIFT}: LSHIFT, Left shift bits
176 * @code{LSTAT}: LSTAT, Get file status
177 * @code{LTIME}: LTIME, Convert time to local time info
178 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
179 * @code{MATMUL}: MATMUL, matrix multiplication
180 * @code{MAX}: MAX, Maximum value of an argument list
181 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
182 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
183 * @code{MAXVAL}: MAXVAL, Maximum value of an array
184 * @code{MCLOCK}: MCLOCK, Time function
185 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
186 * @code{MERGE}: MERGE, Merge arrays
187 * @code{MIN}: MIN, Minimum value of an argument list
188 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
189 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
190 * @code{MINVAL}: MINVAL, Minimum value of an array
191 * @code{MOD}: MOD, Remainder function
192 * @code{MODULO}: MODULO, Modulo function
193 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
194 * @code{MVBITS}: MVBITS, Move bits from one integer to another
195 * @code{NEAREST}: NEAREST, Nearest representable number
196 * @code{NEW_LINE}: NEW_LINE, New line character
197 * @code{NINT}: NINT, Nearest whole number
198 * @code{NOT}: NOT, Logical negation
199 * @code{NULL}: NULL, Function that returns an disassociated pointer
200 * @code{OR}: OR, Bitwise logical OR
201 * @code{PACK}: PACK, Pack an array into an array of rank one
202 * @code{PERROR}: PERROR, Print system error message
203 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
204 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
205 * @code{PRODUCT}: PRODUCT, Product of array elements
206 * @code{RADIX}: RADIX, Base of a data model
207 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
208 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
209 * @code{RAND}: RAND, Real pseudo-random number
210 * @code{RANGE}: RANGE, Decimal exponent range of a real kind
211 * @code{RAN}: RAN, Real pseudo-random number
212 * @code{REAL}: REAL, Convert to real type
213 * @code{RENAME}: RENAME, Rename a file
214 * @code{REPEAT}: REPEAT, Repeated string concatenation
215 * @code{RESHAPE}: RESHAPE, Function to reshape an array
216 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
217 * @code{RSHIFT}: RSHIFT, Right shift bits
218 * @code{SCALE}: SCALE, Scale a real value
219 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
220 * @code{SECNDS}: SECNDS, Time function
221 * @code{SECOND}: SECOND, CPU time function
222 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
223 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
224 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
225 * @code{SHAPE}: SHAPE, Determine the shape of an array
226 * @code{SIGN}: SIGN, Sign copying function
227 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
228 * @code{SIN}: SIN, Sine function
229 * @code{SINH}: SINH, Hyperbolic sine function
230 * @code{SIZE}: SIZE, Function to determine the size of an array
231 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
232 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
233 * @code{SNGL}: SNGL, Convert double precision real to default real
234 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
235 * @code{SPREAD}: SPREAD, Add a dimension to an array
236 * @code{SQRT}: SQRT, Square-root function
237 * @code{SRAND}: SRAND, Reinitialize the random number generator
238 * @code{STAT}: STAT, Get file status
239 * @code{SUM}: SUM, Sum of array elements
240 * @code{SYMLNK}: SYMLNK, Create a symbolic link
241 * @code{SYSTEM}: SYSTEM, Execute a shell command
242 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
243 * @code{TAN}: TAN, Tangent function
244 * @code{TANH}: TANH, Hyperbolic tangent function
245 * @code{TIME}: TIME, Time function
246 * @code{TIME8}: TIME8, Time function (64-bit)
247 * @code{TINY}: TINY, Smallest positive number of a real kind
248 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
249 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
250 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
251 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
252 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
253 * @code{UMASK}: UMASK, Set the file creation mask
254 * @code{UNLINK}: UNLINK, Remove a file from the file system
255 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
256 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
257 * @code{XOR}: XOR, Bitwise logical exclusive or
260 @node Introduction to Intrinsics
261 @section Introduction to intrinsic procedures
263 The intrinsic procedures provided by GNU Fortran include all of the
264 intrinsic procedures required by the Fortran 95 standard, a set of
265 intrinsic procedures for backwards compatibility with G77, and a small
266 selection of intrinsic procedures from the Fortran 2003 standard. Any
267 conflict between a description here and a description in either the
268 Fortran 95 standard or the Fortran 2003 standard is unintentional, and
269 the standard(s) should be considered authoritative.
271 The enumeration of the @code{KIND} type parameter is processor defined in
272 the Fortran 95 standard. GNU Fortran defines the default integer type and
273 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
274 respectively. The standard mandates that both data types shall have
275 another kind, which have more precision. On typical target architectures
276 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
277 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
278 In the description of generic intrinsic procedures, the kind type parameter
279 will be specified by @code{KIND=*}, and in the description of specific
280 names for an intrinsic procedure the kind type parameter will be explicitly
281 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
282 brevity the optional @code{KIND=} syntax will be omitted.
284 Many of the intrinsic procedures take one or more optional arguments.
285 This document follows the convention used in the Fortran 95 standard,
286 and denotes such arguments by square brackets.
288 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
289 which can be used to restrict the set of intrinsic procedures to a
290 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
291 option, and so all intrinsic procedures described here are accepted. There
292 is one caveat. For a select group of intrinsic procedures, @command{g77}
293 implemented both a function and a subroutine. Both classes
294 have been implemented in @command{gfortran} for backwards compatibility
295 with @command{g77}. It is noted here that these functions and subroutines
296 cannot be intermixed in a given subprogram. In the descriptions that follow,
297 the applicable standard for each intrinsic procedure is noted.
302 @section @code{ABORT} --- Abort the program
304 @cindex program termination, with core dump
305 @cindex terminate program, with core dump
309 @item @emph{Description}:
310 @code{ABORT} causes immediate termination of the program. On operating
311 systems that support a core dump, @code{ABORT} will produce a core dump,
312 which is suitable for debugging purposes.
314 @item @emph{Standard}:
323 @item @emph{Return value}:
326 @item @emph{Example}:
329 integer :: i = 1, j = 2
330 if (i /= j) call abort
331 end program test_abort
334 @item @emph{See also}:
335 @ref{EXIT}, @ref{KILL}
342 @section @code{ABS} --- Absolute value
349 @cindex absolute value
352 @item @emph{Description}:
353 @code{ABS(X)} computes the absolute value of @code{X}.
355 @item @emph{Standard}:
356 F77 and later, has overloads that are GNU extensions
362 @code{RESULT = ABS(X)}
364 @item @emph{Arguments}:
365 @multitable @columnfractions .15 .70
366 @item @var{X} @tab The type of the argument shall be an @code{INTEGER(*)},
367 @code{REAL(*)}, or @code{COMPLEX(*)}.
370 @item @emph{Return value}:
371 The return value is of the same type and
372 kind as the argument except the return value is @code{REAL(*)} for a
373 @code{COMPLEX(*)} argument.
375 @item @emph{Example}:
380 complex :: z = (-1.e0,0.e0)
387 @item @emph{Specific names}:
388 @multitable @columnfractions .20 .20 .20 .25
389 @item Name @tab Argument @tab Return type @tab Standard
390 @item @code{CABS(Z)} @tab @code{COMPLEX(4) Z} @tab @code{REAL(4)} @tab F77 and later
391 @item @code{DABS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
392 @item @code{IABS(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab F77 and later
393 @item @code{ZABS(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
394 @item @code{CDABS(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
401 @section @code{ACCESS} --- Checks file access modes
403 @cindex file system, access mode
406 @item @emph{Description}:
407 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
408 exists, is readable, writable or executable. Except for the
409 executable check, @code{ACCESS} can be replaced by
410 Fortran 95's @code{INQUIRE}.
412 @item @emph{Standard}:
419 @code{RESULT = ACCESS(NAME, MODE)}
421 @item @emph{Arguments}:
422 @multitable @columnfractions .15 .70
423 @item @var{NAME} @tab Scalar @code{CHARACTER} with the file name.
424 Tailing blank are ignored unless the character @code{achar(0)} is
425 present, then all characters up to and excluding @code{achar(0)} are
427 @item @var{MODE} @tab Scalar @code{CHARACTER} with the file access mode,
428 may be any concatenation of @code{"r"} (readable), @code{"w"} (writable)
429 and @code{"x"} (executable), or @code{" "} to check for existence.
432 @item @emph{Return value}:
433 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
434 accessible in the given mode; otherwise or if an invalid argument
435 has been given for @code{MODE} the value @code{1} is returned.
437 @item @emph{Example}:
441 character(len=*), parameter :: file = 'test.dat'
442 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
443 if(access(file,' ') == 0) print *, trim(file),' is exists'
444 if(access(file,'r') == 0) print *, trim(file),' is readable'
445 if(access(file,'w') == 0) print *, trim(file),' is writable'
446 if(access(file,'x') == 0) print *, trim(file),' is executable'
447 if(access(file2,'rwx') == 0) &
448 print *, trim(file2),' is readable, writable and executable'
449 end program access_test
451 @item @emph{Specific names}:
452 @item @emph{See also}:
459 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
461 @cindex @acronym{ASCII} collating sequence
462 @cindex collating sequence, @acronym{ASCII}
465 @item @emph{Description}:
466 @code{ACHAR(I)} returns the character located at position @code{I}
467 in the @acronym{ASCII} collating sequence.
469 @item @emph{Standard}:
476 @code{RESULT = ACHAR(I)}
478 @item @emph{Arguments}:
479 @multitable @columnfractions .15 .70
480 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
483 @item @emph{Return value}:
484 The return value is of type @code{CHARACTER} with a length of one. The
485 kind type parameter is the same as @code{KIND('A')}.
487 @item @emph{Example}:
492 end program test_achar
496 See @ref{ICHAR} for a discussion of converting between numerical values
497 and formatted string representations.
499 @item @emph{See also}:
500 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
507 @section @code{ACOS} --- Arccosine function
510 @cindex trigonometric function, cosine, inverse
511 @cindex cosine, inverse
514 @item @emph{Description}:
515 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
517 @item @emph{Standard}:
524 @code{RESULT = ACOS(X)}
526 @item @emph{Arguments}:
527 @multitable @columnfractions .15 .70
528 @item @var{X} @tab The type shall be @code{REAL(*)} with a magnitude that is
532 @item @emph{Return value}:
533 The return value is of type @code{REAL(*)} and it lies in the
534 range @math{ 0 \leq \acos(x) \leq \pi}. The kind type parameter
535 is the same as @var{X}.
537 @item @emph{Example}:
540 real(8) :: x = 0.866_8
542 end program test_acos
545 @item @emph{Specific names}:
546 @multitable @columnfractions .20 .20 .20 .25
547 @item Name @tab Argument @tab Return type @tab Standard
548 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
551 @item @emph{See also}:
552 Inverse function: @ref{COS}
559 @section @code{ACOSH} --- Hyperbolic arccosine function
562 @cindex area hyperbolic cosine
563 @cindex hyperbolic arccosine
564 @cindex hyperbolic function, cosine, inverse
565 @cindex cosine, hyperbolic, inverse
568 @item @emph{Description}:
569 @code{ACOSH(X)} computes the hyperbolic arccosine of @var{X} (inverse of
572 @item @emph{Standard}:
579 @code{RESULT = ACOSH(X)}
581 @item @emph{Arguments}:
582 @multitable @columnfractions .15 .70
583 @item @var{X} @tab The type shall be @code{REAL(*)} with a magnitude that is
584 greater or equal to one.
587 @item @emph{Return value}:
588 The return value is of type @code{REAL(*)} and it lies in the
589 range @math{0 \leq \acosh (x) \leq \infty}.
591 @item @emph{Example}:
594 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
599 @item @emph{Specific names}:
600 @multitable @columnfractions .20 .20 .20 .25
601 @item Name @tab Argument @tab Return type @tab Standard
602 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
605 @item @emph{See also}:
606 Inverse function: @ref{COSH}
612 @section @code{ADJUSTL} --- Left adjust a string
614 @cindex string, adjust left
615 @cindex adjust string
618 @item @emph{Description}:
619 @code{ADJUSTL(STR)} will left adjust a string by removing leading spaces.
620 Spaces are inserted at the end of the string as needed.
622 @item @emph{Standard}:
629 @code{RESULT = ADJUSTL(STR)}
631 @item @emph{Arguments}:
632 @multitable @columnfractions .15 .70
633 @item @var{STR} @tab The type shall be @code{CHARACTER}.
636 @item @emph{Return value}:
637 The return value is of type @code{CHARACTER} where leading spaces
638 are removed and the same number of spaces are inserted on the end
641 @item @emph{Example}:
644 character(len=20) :: str = ' gfortran'
647 end program test_adjustl
650 @item @emph{See also}:
651 @ref{ADJUSTR}, @ref{TRIM}
657 @section @code{ADJUSTR} --- Right adjust a string
659 @cindex string, adjust right
660 @cindex adjust string
663 @item @emph{Description}:
664 @code{ADJUSTR(STR)} will right adjust a string by removing trailing spaces.
665 Spaces are inserted at the start of the string as needed.
667 @item @emph{Standard}:
674 @code{RESULT = ADJUSTR(STR)}
676 @item @emph{Arguments}:
677 @multitable @columnfractions .15 .70
678 @item @var{STR} @tab The type shall be @code{CHARACTER}.
681 @item @emph{Return value}:
682 The return value is of type @code{CHARACTER} where trailing spaces
683 are removed and the same number of spaces are inserted at the start
686 @item @emph{Example}:
689 character(len=20) :: str = 'gfortran'
692 end program test_adjustr
695 @item @emph{See also}:
696 @ref{ADJUSTL}, @ref{TRIM}
702 @section @code{AIMAG} --- Imaginary part of complex number
707 @cindex complex numbers, imaginary part
710 @item @emph{Description}:
711 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
712 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
713 for compatibility with @command{g77}, and their use in new code is
714 strongly discouraged.
716 @item @emph{Standard}:
717 F77 and later, has overloads that are GNU extensions
723 @code{RESULT = AIMAG(Z)}
725 @item @emph{Arguments}:
726 @multitable @columnfractions .15 .70
727 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX(*)}.
730 @item @emph{Return value}:
731 The return value is of type real with the
732 kind type parameter of the argument.
734 @item @emph{Example}:
739 z4 = cmplx(1.e0_4, 0.e0_4)
740 z8 = cmplx(0.e0_8, 1.e0_8)
741 print *, aimag(z4), dimag(z8)
742 end program test_aimag
745 @item @emph{Specific names}:
746 @multitable @columnfractions .20 .20 .20 .25
747 @item Name @tab Argument @tab Return type @tab Standard
748 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
749 @item @code{IMAG(Z)} @tab @code{COMPLEX(*) Z} @tab @code{REAL(*)} @tab GNU extension
750 @item @code{IMAGPART(Z)} @tab @code{COMPLEX(*) Z} @tab @code{REAL(*)} @tab GNU extension
757 @section @code{AINT} --- Truncate to a whole number
761 @cindex rounding, floor
764 @item @emph{Description}:
765 @code{AINT(X [, KIND])} truncates its argument to a whole number.
767 @item @emph{Standard}:
774 @code{RESULT = AINT(X [, KIND])}
776 @item @emph{Arguments}:
777 @multitable @columnfractions .15 .70
778 @item @var{X} @tab The type of the argument shall be @code{REAL(*)}.
779 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
780 expression indicating the kind parameter of
784 @item @emph{Return value}:
785 The return value is of type real with the kind type parameter of the
786 argument if the optional @var{KIND} is absent; otherwise, the kind
787 type parameter will be given by @var{KIND}. If the magnitude of
788 @var{X} is less than one, then @code{AINT(X)} returns zero. If the
789 magnitude is equal to or greater than one, then it returns the largest
790 whole number that does not exceed its magnitude. The sign is the same
791 as the sign of @var{X}.
793 @item @emph{Example}:
800 print *, aint(x4), dint(x8)
802 end program test_aint
805 @item @emph{Specific names}:
806 @multitable @columnfractions .20 .20 .20 .25
807 @item Name @tab Argument @tab Return type @tab Standard
808 @item @code{DINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
815 @section @code{ALARM} --- Execute a routine after a given delay
817 @cindex delayed execution
820 @item @emph{Description}:
821 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
822 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
823 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
824 supplied, it will be returned with the number of seconds remaining until
825 any previously scheduled alarm was due to be delivered, or zero if there
826 was no previously scheduled alarm.
828 @item @emph{Standard}:
835 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
837 @item @emph{Arguments}:
838 @multitable @columnfractions .15 .70
839 @item @var{SECONDS} @tab The type of the argument shall be a scalar
840 @code{INTEGER}. It is @code{INTENT(IN)}.
841 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
842 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
843 values may be either @code{SIG_IGN=1} to ignore the alarm generated
844 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
845 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
846 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
849 @item @emph{Example}:
852 external handler_print
854 call alarm (3, handler_print, i)
857 end program test_alarm
859 This will cause the external routine @var{handler_print} to be called
866 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
868 @cindex array, apply condition
869 @cindex array, condition testing
872 @item @emph{Description}:
873 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
874 in the array along dimension @var{DIM}.
876 @item @emph{Standard}:
880 Transformational function
883 @code{RESULT = ALL(MASK [, DIM])}
885 @item @emph{Arguments}:
886 @multitable @columnfractions .15 .70
887 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL(*)} and
888 it shall not be scalar.
889 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
890 with a value that lies between one and the rank of @var{MASK}.
893 @item @emph{Return value}:
894 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL(*)} where
895 the kind type parameter is the same as the kind type parameter of
896 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
897 an array with the rank of @var{MASK} minus 1. The shape is determined from
898 the shape of @var{MASK} where the @var{DIM} dimension is elided.
902 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
903 It also is true if @var{MASK} has zero size; otherwise, it is false.
905 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
906 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
907 is determined by applying @code{ALL} to the array sections.
910 @item @emph{Example}:
914 l = all((/.true., .true., .true./))
919 integer a(2,3), b(2,3)
923 print *, all(a .eq. b, 1)
924 print *, all(a .eq. b, 2)
925 end subroutine section
933 @section @code{ALLOCATED} --- Status of an allocatable entity
935 @cindex allocation, status
938 @item @emph{Description}:
939 @code{ALLOCATED(X)} checks the status of whether @var{X} is allocated.
941 @item @emph{Standard}:
948 @code{RESULT = ALLOCATED(X)}
950 @item @emph{Arguments}:
951 @multitable @columnfractions .15 .70
952 @item @var{X} @tab The argument shall be an @code{ALLOCATABLE} array.
955 @item @emph{Return value}:
956 The return value is a scalar @code{LOGICAL} with the default logical
957 kind type parameter. If @var{X} is allocated, @code{ALLOCATED(X)}
958 is @code{.TRUE.}; otherwise, it returns the @code{.TRUE.}
960 @item @emph{Example}:
962 program test_allocated
964 real(4), allocatable :: x(:)
965 if (allocated(x) .eqv. .false.) allocate(x(i))
966 end program test_allocated
973 @section @code{AND} --- Bitwise logical AND
975 @cindex bitwise logical and
976 @cindex logical and, bitwise
979 @item @emph{Description}:
980 Bitwise logical @code{AND}.
982 This intrinsic routine is provided for backwards compatibility with
983 GNU Fortran 77. For integer arguments, programmers should consider
984 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
986 @item @emph{Standard}:
993 @code{RESULT = AND(I, J)}
995 @item @emph{Arguments}:
996 @multitable @columnfractions .15 .70
997 @item @var{I} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
998 @item @var{J} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
1001 @item @emph{Return value}:
1002 The return type is either @code{INTEGER(*)} or @code{LOGICAL} after
1003 cross-promotion of the arguments.
1005 @item @emph{Example}:
1008 LOGICAL :: T = .TRUE., F = .FALSE.
1010 DATA a / Z'F' /, b / Z'3' /
1012 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1013 WRITE (*,*) AND(a, b)
1017 @item @emph{See also}:
1018 F95 elemental function: @ref{IAND}
1024 @section @code{ANINT} --- Nearest whole number
1028 @cindex rounding, ceiling
1031 @item @emph{Description}:
1032 @code{ANINT(X [, KIND])} rounds its argument to the nearest whole number.
1034 @item @emph{Standard}:
1040 @item @emph{Syntax}:
1041 @code{RESULT = ANINT(X [, KIND])}
1043 @item @emph{Arguments}:
1044 @multitable @columnfractions .15 .70
1045 @item @var{X} @tab The type of the argument shall be @code{REAL(*)}.
1046 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
1047 expression indicating the kind parameter of
1051 @item @emph{Return value}:
1052 The return value is of type real with the kind type parameter of the
1053 argument if the optional @var{KIND} is absent; otherwise, the kind
1054 type parameter will be given by @var{KIND}. If @var{X} is greater than
1055 zero, then @code{ANINT(X)} returns @code{AINT(X+0.5)}. If @var{X} is
1056 less than or equal to zero, then it returns @code{AINT(X-0.5)}.
1058 @item @emph{Example}:
1065 print *, anint(x4), dnint(x8)
1067 end program test_anint
1070 @item @emph{Specific names}:
1071 @multitable @columnfractions .20 .20 .20 .25
1072 @item Name @tab Argument @tab Return type @tab Standard
1073 @item @code{DNINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1080 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1082 @cindex array, apply condition
1083 @cindex array, condition testing
1086 @item @emph{Description}:
1087 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1088 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1090 @item @emph{Standard}:
1094 Transformational function
1096 @item @emph{Syntax}:
1097 @code{RESULT = ANY(MASK [, DIM])}
1099 @item @emph{Arguments}:
1100 @multitable @columnfractions .15 .70
1101 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL(*)} and
1102 it shall not be scalar.
1103 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1104 with a value that lies between one and the rank of @var{MASK}.
1107 @item @emph{Return value}:
1108 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL(*)} where
1109 the kind type parameter is the same as the kind type parameter of
1110 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1111 an array with the rank of @var{MASK} minus 1. The shape is determined from
1112 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1116 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1117 otherwise, it is false. It also is false if @var{MASK} has zero size.
1119 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1120 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1121 is determined by applying @code{ANY} to the array sections.
1124 @item @emph{Example}:
1128 l = any((/.true., .true., .true./))
1133 integer a(2,3), b(2,3)
1137 print *, any(a .eq. b, 1)
1138 print *, any(a .eq. b, 2)
1139 end subroutine section
1140 end program test_any
1147 @section @code{ASIN} --- Arcsine function
1150 @cindex trigonometric function, sine, inverse
1151 @cindex sine, inverse
1154 @item @emph{Description}:
1155 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1157 @item @emph{Standard}:
1163 @item @emph{Syntax}:
1164 @code{RESULT = ASIN(X)}
1166 @item @emph{Arguments}:
1167 @multitable @columnfractions .15 .70
1168 @item @var{X} @tab The type shall be @code{REAL(*)}, and a magnitude that is
1172 @item @emph{Return value}:
1173 The return value is of type @code{REAL(*)} and it lies in the
1174 range @math{-\pi / 2 \leq \asin (x) \leq \pi / 2}. The kind type
1175 parameter is the same as @var{X}.
1177 @item @emph{Example}:
1180 real(8) :: x = 0.866_8
1182 end program test_asin
1185 @item @emph{Specific names}:
1186 @multitable @columnfractions .20 .20 .20 .25
1187 @item Name @tab Argument @tab Return type @tab Standard
1188 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1191 @item @emph{See also}:
1192 Inverse function: @ref{SIN}
1199 @section @code{ASINH} --- Hyperbolic arcsine function
1202 @cindex area hyperbolic sine
1203 @cindex hyperbolic arcsine
1204 @cindex hyperbolic function, sine, inverse
1205 @cindex sine, hyperbolic, inverse
1208 @item @emph{Description}:
1209 @code{ASINH(X)} computes the hyperbolic arcsine of @var{X} (inverse of @code{SINH(X)}).
1211 @item @emph{Standard}:
1217 @item @emph{Syntax}:
1218 @code{RESULT = ASINH(X)}
1220 @item @emph{Arguments}:
1221 @multitable @columnfractions .15 .70
1222 @item @var{X} @tab The type shall be @code{REAL(*)}, with @var{X} a real number.
1225 @item @emph{Return value}:
1226 The return value is of type @code{REAL(*)} and it lies in the
1227 range @math{-\infty \leq \asinh (x) \leq \infty}.
1229 @item @emph{Example}:
1232 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1233 WRITE (*,*) ASINH(x)
1237 @item @emph{Specific names}:
1238 @multitable @columnfractions .20 .20 .20 .25
1239 @item Name @tab Argument @tab Return type @tab Standard
1240 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1243 @item @emph{See also}:
1244 Inverse function: @ref{SINH}
1250 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1252 @cindex pointer, status
1253 @cindex association status
1256 @item @emph{Description}:
1257 @code{ASSOCIATED(PTR [, TGT])} determines the status of the pointer @var{PTR}
1258 or if @var{PTR} is associated with the target @var{TGT}.
1260 @item @emph{Standard}:
1266 @item @emph{Syntax}:
1267 @code{RESULT = ASSOCIATED(PTR [, TGT])}
1269 @item @emph{Arguments}:
1270 @multitable @columnfractions .15 .70
1271 @item @var{PTR} @tab @var{PTR} shall have the @code{POINTER} attribute and
1272 it can be of any type.
1273 @item @var{TGT} @tab (Optional) @var{TGT} shall be a @code{POINTER} or
1274 a @code{TARGET}. It must have the same type, kind type parameter, and
1275 array rank as @var{PTR}.
1277 The status of neither @var{PTR} nor @var{TGT} can be undefined.
1279 @item @emph{Return value}:
1280 @code{ASSOCIATED(PTR)} returns a scalar value of type @code{LOGICAL(4)}.
1281 There are several cases:
1283 @item (A) If the optional @var{TGT} is not present, then @code{ASSOCIATED(PTR)}
1284 is true if @var{PTR} is associated with a target; otherwise, it returns false.
1285 @item (B) If @var{TGT} is present and a scalar target, the result is true if
1287 is not a 0 sized storage sequence and the target associated with @var{PTR}
1288 occupies the same storage units. If @var{PTR} is disassociated, then the
1290 @item (C) If @var{TGT} is present and an array target, the result is true if
1291 @var{TGT} and @var{PTR} have the same shape, are not 0 sized arrays, are
1292 arrays whose elements are not 0 sized storage sequences, and @var{TGT} and
1293 @var{PTR} occupy the same storage units in array element order.
1294 As in case(B), the result is false, if @var{PTR} is disassociated.
1295 @item (D) If @var{TGT} is present and an scalar pointer, the result is true if
1296 target associated with @var{PTR} and the target associated with @var{TGT}
1297 are not 0 sized storage sequences and occupy the same storage units.
1298 The result is false, if either @var{TGT} or @var{PTR} is disassociated.
1299 @item (E) If @var{TGT} is present and an array pointer, the result is true if
1300 target associated with @var{PTR} and the target associated with @var{TGT}
1301 have the same shape, are not 0 sized arrays, are arrays whose elements are
1302 not 0 sized storage sequences, and @var{TGT} and @var{PTR} occupy the same
1303 storage units in array element order.
1304 The result is false, if either @var{TGT} or @var{PTR} is disassociated.
1307 @item @emph{Example}:
1309 program test_associated
1311 real, target :: tgt(2) = (/1., 2./)
1312 real, pointer :: ptr(:)
1314 if (associated(ptr) .eqv. .false.) call abort
1315 if (associated(ptr,tgt) .eqv. .false.) call abort
1316 end program test_associated
1319 @item @emph{See also}:
1326 @section @code{ATAN} --- Arctangent function
1329 @cindex trigonometric function, tangent, inverse
1330 @cindex tangent, inverse
1333 @item @emph{Description}:
1334 @code{ATAN(X)} computes the arctangent of @var{X}.
1336 @item @emph{Standard}:
1342 @item @emph{Syntax}:
1343 @code{RESULT = ATAN(X)}
1345 @item @emph{Arguments}:
1346 @multitable @columnfractions .15 .70
1347 @item @var{X} @tab The type shall be @code{REAL(*)}.
1350 @item @emph{Return value}:
1351 The return value is of type @code{REAL(*)} and it lies in the
1352 range @math{ - \pi / 2 \leq \atan (x) \leq \pi / 2}.
1354 @item @emph{Example}:
1357 real(8) :: x = 2.866_8
1359 end program test_atan
1362 @item @emph{Specific names}:
1363 @multitable @columnfractions .20 .20 .20 .25
1364 @item Name @tab Argument @tab Return type @tab Standard
1365 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1368 @item @emph{See also}:
1369 Inverse function: @ref{TAN}
1376 @section @code{ATAN2} --- Arctangent function
1379 @cindex trigonometric function, tangent, inverse
1380 @cindex tangent, inverse
1383 @item @emph{Description}:
1384 @code{ATAN2(Y,X)} computes the arctangent of the complex number
1387 @item @emph{Standard}:
1393 @item @emph{Syntax}:
1394 @code{RESULT = ATAN2(Y,X)}
1396 @item @emph{Arguments}:
1397 @multitable @columnfractions .15 .70
1398 @item @var{Y} @tab The type shall be @code{REAL(*)}.
1399 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1400 If @var{Y} is zero, then @var{X} must be nonzero.
1403 @item @emph{Return value}:
1404 The return value has the same type and kind type parameter as @var{Y}.
1405 It is the principal value of the complex number @math{X + i Y}. If
1406 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1407 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1408 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1409 is negative. Finally, if @var{X} is zero, then the magnitude of the result
1412 @item @emph{Example}:
1415 real(4) :: x = 1.e0_4, y = 0.5e0_4
1417 end program test_atan2
1420 @item @emph{Specific names}:
1421 @multitable @columnfractions .20 .20 .20 .25
1422 @item Name @tab Argument @tab Return type @tab Standard
1423 @item @code{DATAN2(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1430 @section @code{ATANH} --- Hyperbolic arctangent function
1433 @cindex area hyperbolic tangent
1434 @cindex hyperbolic arctangent
1435 @cindex hyperbolic function, tangent, inverse
1436 @cindex tangent, hyperbolic, inverse
1439 @item @emph{Description}:
1440 @code{ATANH(X)} computes the hyperbolic arctangent of @var{X} (inverse
1443 @item @emph{Standard}:
1449 @item @emph{Syntax}:
1450 @code{RESULT = ATANH(X)}
1452 @item @emph{Arguments}:
1453 @multitable @columnfractions .15 .70
1454 @item @var{X} @tab The type shall be @code{REAL(*)} with a magnitude
1455 that is less than or equal to one.
1458 @item @emph{Return value}:
1459 The return value is of type @code{REAL(*)} and it lies in the
1460 range @math{-\infty \leq \atanh(x) \leq \infty}.
1462 @item @emph{Example}:
1465 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1466 WRITE (*,*) ATANH(x)
1470 @item @emph{Specific names}:
1471 @multitable @columnfractions .20 .20 .20 .25
1472 @item Name @tab Argument @tab Return type @tab Standard
1473 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1476 @item @emph{See also}:
1477 Inverse function: @ref{TANH}
1483 @section @code{BESJ0} --- Bessel function of the first kind of order 0
1486 @cindex Bessel function, first kind
1489 @item @emph{Description}:
1490 @code{BESJ0(X)} computes the Bessel function of the first kind of order 0
1493 @item @emph{Standard}:
1499 @item @emph{Syntax}:
1500 @code{RESULT = BESJ0(X)}
1502 @item @emph{Arguments}:
1503 @multitable @columnfractions .15 .70
1504 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1507 @item @emph{Return value}:
1508 The return value is of type @code{REAL(*)} and it lies in the
1509 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}.
1511 @item @emph{Example}:
1514 real(8) :: x = 0.0_8
1516 end program test_besj0
1519 @item @emph{Specific names}:
1520 @multitable @columnfractions .20 .20 .20 .25
1521 @item Name @tab Argument @tab Return type @tab Standard
1522 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1529 @section @code{BESJ1} --- Bessel function of the first kind of order 1
1532 @cindex Bessel function, first kind
1535 @item @emph{Description}:
1536 @code{BESJ1(X)} computes the Bessel function of the first kind of order 1
1539 @item @emph{Standard}:
1545 @item @emph{Syntax}:
1546 @code{RESULT = BESJ1(X)}
1548 @item @emph{Arguments}:
1549 @multitable @columnfractions .15 .70
1550 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1553 @item @emph{Return value}:
1554 The return value is of type @code{REAL(*)} and it lies in the
1555 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }.
1557 @item @emph{Example}:
1560 real(8) :: x = 1.0_8
1562 end program test_besj1
1565 @item @emph{Specific names}:
1566 @multitable @columnfractions .20 .20 .20 .25
1567 @item Name @tab Argument @tab Return type @tab Standard
1568 @item @code{DBESJ1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1575 @section @code{BESJN} --- Bessel function of the first kind
1578 @cindex Bessel function, first kind
1581 @item @emph{Description}:
1582 @code{BESJN(N, X)} computes the Bessel function of the first kind of order
1585 If both arguments are arrays, their ranks and shapes shall conform.
1587 @item @emph{Standard}:
1593 @item @emph{Syntax}:
1594 @code{RESULT = BESJN(N, X)}
1596 @item @emph{Arguments}:
1597 @multitable @columnfractions .15 .70
1598 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER(*)}.
1599 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL(*)}.
1602 @item @emph{Return value}:
1603 The return value is a scalar of type @code{REAL(*)}.
1605 @item @emph{Example}:
1608 real(8) :: x = 1.0_8
1610 end program test_besjn
1613 @item @emph{Specific names}:
1614 @multitable @columnfractions .20 .20 .20 .25
1615 @item Name @tab Argument @tab Return type @tab Standard
1616 @item @code{DBESJN(X)} @tab @code{INTEGER(*) N} @tab @code{REAL(8)} @tab GNU extension
1617 @item @tab @code{REAL(8) X} @tab @tab
1624 @section @code{BESY0} --- Bessel function of the second kind of order 0
1627 @cindex Bessel function, second kind
1630 @item @emph{Description}:
1631 @code{BESY0(X)} computes the Bessel function of the second kind of order 0
1634 @item @emph{Standard}:
1640 @item @emph{Syntax}:
1641 @code{RESULT = BESY0(X)}
1643 @item @emph{Arguments}:
1644 @multitable @columnfractions .15 .70
1645 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1648 @item @emph{Return value}:
1649 The return value is a scalar of type @code{REAL(*)}.
1651 @item @emph{Example}:
1654 real(8) :: x = 0.0_8
1656 end program test_besy0
1659 @item @emph{Specific names}:
1660 @multitable @columnfractions .20 .20 .20 .25
1661 @item Name @tab Argument @tab Return type @tab Standard
1662 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1669 @section @code{BESY1} --- Bessel function of the second kind of order 1
1672 @cindex Bessel function, second kind
1675 @item @emph{Description}:
1676 @code{BESY1(X)} computes the Bessel function of the second kind of order 1
1679 @item @emph{Standard}:
1685 @item @emph{Syntax}:
1686 @code{RESULT = BESY1(X)}
1688 @item @emph{Arguments}:
1689 @multitable @columnfractions .15 .70
1690 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1693 @item @emph{Return value}:
1694 The return value is a scalar of type @code{REAL(*)}.
1696 @item @emph{Example}:
1699 real(8) :: x = 1.0_8
1701 end program test_besy1
1704 @item @emph{Specific names}:
1705 @multitable @columnfractions .20 .20 .20 .25
1706 @item Name @tab Argument @tab Return type @tab Standard
1707 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1714 @section @code{BESYN} --- Bessel function of the second kind
1717 @cindex Bessel function, second kind
1720 @item @emph{Description}:
1721 @code{BESYN(N, X)} computes the Bessel function of the second kind of order
1724 If both arguments are arrays, their ranks and shapes shall conform.
1726 @item @emph{Standard}:
1732 @item @emph{Syntax}:
1733 @code{RESULT = BESYN(N, X)}
1735 @item @emph{Arguments}:
1736 @multitable @columnfractions .15 .70
1737 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER(*)}.
1738 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL(*)}.
1741 @item @emph{Return value}:
1742 The return value is a scalar of type @code{REAL(*)}.
1744 @item @emph{Example}:
1747 real(8) :: x = 1.0_8
1749 end program test_besyn
1752 @item @emph{Specific names}:
1753 @multitable @columnfractions .20 .20 .20 .25
1754 @item Name @tab Argument @tab Return type @tab Standard
1755 @item @code{DBESYN(N,X)} @tab @code{INTEGER(*) N} @tab @code{REAL(8)} @tab GNU extension
1756 @item @tab @code{REAL(8) X} @tab @tab
1763 @section @code{BIT_SIZE} --- Bit size inquiry function
1765 @cindex bits, number of
1766 @cindex size of a variable, in bits
1769 @item @emph{Description}:
1770 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1771 represented by the type of @var{I}.
1773 @item @emph{Standard}:
1779 @item @emph{Syntax}:
1780 @code{RESULT = BIT_SIZE(I)}
1782 @item @emph{Arguments}:
1783 @multitable @columnfractions .15 .70
1784 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
1787 @item @emph{Return value}:
1788 The return value is of type @code{INTEGER(*)}
1790 @item @emph{Example}:
1792 program test_bit_size
1797 end program test_bit_size
1804 @section @code{BTEST} --- Bit test function
1806 @cindex bits, testing
1809 @item @emph{Description}:
1810 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
1813 @item @emph{Standard}:
1819 @item @emph{Syntax}:
1820 @code{RESULT = BTEST(I, POS)}
1822 @item @emph{Arguments}:
1823 @multitable @columnfractions .15 .70
1824 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
1825 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
1828 @item @emph{Return value}:
1829 The return value is of type @code{LOGICAL}
1831 @item @emph{Example}:
1834 integer :: i = 32768 + 1024 + 64
1838 bool = btest(i, pos)
1841 end program test_btest
1847 @section @code{C_ASSOCIATED} --- Status of a C pointer
1848 @fnindex C_ASSOCIATED
1849 @cindex association status, C pointer
1850 @cindex pointer, C association status
1853 @item @emph{Description}:
1854 @code{C_ASSOICATED(c_prt1[, c_ptr2])} determines the status of the C pointer @var{c_ptr1}
1855 or if @var{c_ptr1} is associated with the target @var{c_ptr2}.
1857 @item @emph{Standard}:
1863 @item @emph{Syntax}:
1864 @code{RESULT = C_ASSOICATED(c_prt1[, c_ptr2])}
1866 @item @emph{Arguments}:
1867 @multitable @columnfractions .15 .70
1868 @item @var{c_ptr1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
1869 @item @var{c_ptr2} @tab (Optional) Scalar of the same type as @var{c_ptr1}.
1872 @item @emph{Return value}:
1873 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
1874 @var{c_ptr1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr2}
1875 point to different addresses.
1877 @item @emph{Example}:
1879 subroutine association_test(a,b)
1880 use iso_c_binding, only: c_associated, c_loc, c_ptr
1884 if(c_associated(b, c_loc(a))) &
1885 stop 'b and a do not point to same target'
1886 end subroutine association_test
1889 @item @emph{See also}:
1890 @ref{C_LOC}, @ref{C_FUNLOC}
1895 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
1897 @cindex pointer, C address of procedures
1900 @item @emph{Description}:
1901 @code{C_FUNLOC(x)} determines the C address of the argument.
1903 @item @emph{Standard}:
1909 @item @emph{Syntax}:
1910 @code{RESULT = C_FUNLOC(x)}
1912 @item @emph{Arguments}:
1913 @multitable @columnfractions .15 .70
1914 @item @var{x} @tab Interoperable function or pointer to such function.
1917 @item @emph{Return value}:
1918 The return value is of type @code{C_FUNPTR} and contains the C address
1921 @item @emph{Example}:
1927 subroutine sub(a) bind(c)
1937 subroutine my_routine(p) bind(c,name='myC_func')
1939 type(c_funptr), intent(in) :: p
1942 call my_routine(c_funloc(sub))
1946 @item @emph{See also}:
1947 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
1951 @node C_F_PROCPOINTER
1952 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
1953 @fnindex C_F_PROCPOINTER
1954 @cindex pointer, C address of pointers
1957 @item @emph{Description}:
1958 @code{C_F_PROCPOINTER(cptr, fptr)} Assign the target of the C function pointer
1959 @var{cptr} to the Fortran procedure pointer @var{fptr}.
1961 Note: Due to the currently lacking support of procedure pointers in GNU Fortran
1962 this function is not fully operable.
1964 @item @emph{Standard}:
1970 @item @emph{Syntax}:
1971 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
1973 @item @emph{Arguments}:
1974 @multitable @columnfractions .15 .70
1975 @item @var{cptr} @tab scalar of the type @code{C_FUNPTR}. It is
1977 @item @var{fptr} @tab procedure pointer interoperable with @var{cptr}. It is
1981 @item @emph{Example}:
1989 real(c_float), intent(in) :: a
1990 real(c_float) :: func
1994 function getIterFunc() bind(c,name="getIterFunc")
1996 type(c_funptr) :: getIterFunc
1999 type(c_funptr) :: cfunptr
2000 procedure(func), pointer :: myFunc
2001 cfunptr = getIterFunc()
2002 call c_f_procpointer(cfunptr, myFunc)
2006 @item @emph{See also}:
2007 @ref{C_LOC}, @ref{C_F_POINTER}
2012 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2013 @fnindex C_F_POINTER
2014 @cindex pointer, convert C to Fortran
2017 @item @emph{Description}:
2018 @code{C_F_POINTER(cptr, fptr[, shape])} Assign the target the C pointer
2019 @var{cptr} to the Fortran pointer @var{fptr} and specify its
2022 @item @emph{Standard}:
2028 @item @emph{Syntax}:
2029 @code{CALL C_F_POINTER(cptr, fptr[, shape])}
2031 @item @emph{Arguments}:
2032 @multitable @columnfractions .15 .70
2033 @item @var{cptr} @tab scalar of the type @code{C_PTR}. It is
2035 @item @var{fptr} @tab pointer interoperable with @var{cptr}. It is
2037 @item @var{shape} @tab (Optional) Rank-one array of type @code{INTEGER}
2038 with @code{INTENT(IN)}. It shall be present
2039 if and only if @var{fptr} is an array. The size
2040 must be equal to the rank of @var{fptr}.
2043 @item @emph{Example}:
2049 subroutine my_routine(p) bind(c,name='myC_func')
2051 type(c_ptr), intent(out) :: p
2055 real,pointer :: a(:)
2056 call my_routine(cptr)
2057 call c_f_pointer(cptr, a, [12])
2061 @item @emph{See also}:
2062 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2067 @section @code{C_LOC} --- Obtain the C address of an object
2069 @cindex procedure pointer, convert C to Fortran
2072 @item @emph{Description}:
2073 @code{C_LOC(x)} determines the C address of the argument.
2075 @item @emph{Standard}:
2081 @item @emph{Syntax}:
2082 @code{RESULT = C_LOC(x)}
2084 @item @emph{Arguments}:
2085 @multitable @columnfractions .15 .70
2086 @item @var{x} @tab Associated scalar pointer or interoperable scalar
2087 or allocated allocatable variable with @code{TARGET}
2091 @item @emph{Return value}:
2092 The return value is of type @code{C_PTR} and contains the C address
2095 @item @emph{Example}:
2097 subroutine association_test(a,b)
2098 use iso_c_binding, only: c_associated, c_loc, c_ptr
2102 if(c_associated(b, c_loc(a))) &
2103 stop 'b and a do not point to same target'
2104 end subroutine association_test
2107 @item @emph{See also}:
2108 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2113 @section @code{CEILING} --- Integer ceiling function
2116 @cindex rounding, ceiling
2119 @item @emph{Description}:
2120 @code{CEILING(X)} returns the least integer greater than or equal to @var{X}.
2122 @item @emph{Standard}:
2128 @item @emph{Syntax}:
2129 @code{RESULT = CEILING(X [, KIND])}
2131 @item @emph{Arguments}:
2132 @multitable @columnfractions .15 .70
2133 @item @var{X} @tab The type shall be @code{REAL(*)}.
2134 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
2135 expression indicating the kind parameter of
2139 @item @emph{Return value}:
2140 The return value is of type @code{INTEGER(KIND)}
2142 @item @emph{Example}:
2144 program test_ceiling
2147 print *, ceiling(x) ! returns 64
2148 print *, ceiling(y) ! returns -63
2149 end program test_ceiling
2152 @item @emph{See also}:
2153 @ref{FLOOR}, @ref{NINT}
2160 @section @code{CHAR} --- Character conversion function
2162 @cindex conversion, to character
2165 @item @emph{Description}:
2166 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2168 @item @emph{Standard}:
2174 @item @emph{Syntax}:
2175 @code{RESULT = CHAR(I [, KIND])}
2177 @item @emph{Arguments}:
2178 @multitable @columnfractions .15 .70
2179 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
2180 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
2181 expression indicating the kind parameter of
2185 @item @emph{Return value}:
2186 The return value is of type @code{CHARACTER(1)}
2188 @item @emph{Example}:
2194 print *, i, c ! returns 'J'
2195 end program test_char
2199 See @ref{ICHAR} for a discussion of converting between numerical values
2200 and formatted string representations.
2202 @item @emph{See also}:
2203 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2210 @section @code{CHDIR} --- Change working directory
2212 @cindex system, working directory
2215 @item @emph{Description}:
2216 Change current working directory to a specified path.
2218 This intrinsic is provided in both subroutine and function forms; however,
2219 only one form can be used in any given program unit.
2221 @item @emph{Standard}:
2225 Subroutine, function
2227 @item @emph{Syntax}:
2228 @multitable @columnfractions .80
2229 @item @code{CALL CHDIR(NAME [, STATUS])}
2230 @item @code{STATUS = CHDIR(NAME)}
2233 @item @emph{Arguments}:
2234 @multitable @columnfractions .15 .70
2235 @item @var{NAME} @tab The type shall be @code{CHARACTER(*)} and shall
2236 specify a valid path within the file system.
2237 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2238 kind. Returns 0 on success, and a system specific
2239 and nonzero error code otherwise.
2242 @item @emph{Example}:
2245 CHARACTER(len=255) :: path
2247 WRITE(*,*) TRIM(path)
2250 WRITE(*,*) TRIM(path)
2254 @item @emph{See also}:
2261 @section @code{CHMOD} --- Change access permissions of files
2263 @cindex file system, change access mode
2266 @item @emph{Description}:
2267 @code{CHMOD} changes the permissions of a file. This function invokes
2268 @code{/bin/chmod} and might therefore not work on all platforms.
2270 This intrinsic is provided in both subroutine and function forms; however,
2271 only one form can be used in any given program unit.
2273 @item @emph{Standard}:
2277 Subroutine, function
2279 @item @emph{Syntax}:
2280 @multitable @columnfractions .80
2281 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2282 @item @code{STATUS = CHMOD(NAME, MODE)}
2285 @item @emph{Arguments}:
2286 @multitable @columnfractions .15 .70
2287 @item @var{NAME} @tab Scalar @code{CHARACTER} with the file name.
2288 Trailing blanks are ignored unless the character @code{achar(0)} is
2289 present, then all characters up to and excluding @code{achar(0)} are
2290 used as the file name.
2292 @item @var{MODE} @tab Scalar @code{CHARACTER} giving the file permission.
2293 @var{MODE} uses the same syntax as the @var{MODE} argument of
2296 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2297 @code{0} on success and nonzero otherwise.
2300 @item @emph{Return value}:
2301 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2304 @item @emph{Example}:
2305 @code{CHMOD} as subroutine
2310 call chmod('test.dat','u+x',status)
2311 print *, 'Status: ', status
2312 end program chmod_test
2314 @code{CHMOD} as function:
2319 status = chmod('test.dat','u+x')
2320 print *, 'Status: ', status
2321 end program chmod_test
2329 @section @code{CMPLX} --- Complex conversion function
2331 @cindex complex numbers, conversion to
2332 @cindex conversion, to complex
2335 @item @emph{Description}:
2336 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2337 the real component. If @var{Y} is present it is converted to the imaginary
2338 component. If @var{Y} is not present then the imaginary component is set to
2339 0.0. If @var{X} is complex then @var{Y} must not be present.
2341 @item @emph{Standard}:
2347 @item @emph{Syntax}:
2348 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2350 @item @emph{Arguments}:
2351 @multitable @columnfractions .15 .70
2352 @item @var{X} @tab The type may be @code{INTEGER(*)}, @code{REAL(*)},
2353 or @code{COMPLEX(*)}.
2354 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2355 @code{COMPLEX(*)}.) May be @code{INTEGER(*)}
2357 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
2358 expression indicating the kind parameter of
2362 @item @emph{Return value}:
2363 The return value is of @code{COMPLEX} type, with a kind equal to
2364 @var{KIND} if it is specified. If @var{KIND} is not specified, the
2365 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2366 @var{X} and @var{Y}.
2368 @item @emph{Example}:
2375 print *, z, cmplx(x)
2376 end program test_cmplx
2379 @item @emph{See also}:
2385 @node COMMAND_ARGUMENT_COUNT
2386 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2387 @fnindex COMMAND_ARGUMENT_COUNT
2388 @cindex command-line arguments
2389 @cindex command-line arguments, number of
2390 @cindex arguments, to program
2393 @item @emph{Description}:
2394 @code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the
2395 command line when the containing program was invoked.
2397 @item @emph{Standard}:
2403 @item @emph{Syntax}:
2404 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2406 @item @emph{Arguments}:
2407 @multitable @columnfractions .15 .70
2411 @item @emph{Return value}:
2412 The return value is of type @code{INTEGER(4)}
2414 @item @emph{Example}:
2416 program test_command_argument_count
2418 count = command_argument_count()
2420 end program test_command_argument_count
2423 @item @emph{See also}:
2424 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2430 @section @code{COMPLEX} --- Complex conversion function
2432 @cindex complex numbers, conversion to
2433 @cindex conversion, to complex
2436 @item @emph{Description}:
2437 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2438 to the real component and @var{Y} is converted to the imaginary
2441 @item @emph{Standard}:
2447 @item @emph{Syntax}:
2448 @code{RESULT = COMPLEX(X, Y)}
2450 @item @emph{Arguments}:
2451 @multitable @columnfractions .15 .70
2452 @item @var{X} @tab The type may be @code{INTEGER(*)} or @code{REAL(*)}.
2453 @item @var{Y} @tab The type may be @code{INTEGER(*)} or @code{REAL(*)}.
2456 @item @emph{Return value}:
2457 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2458 value is of default @code{COMPLEX} type.
2460 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2461 type and one is of @code{INTEGER} type, then the return value is of
2462 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2463 argument with the highest precision.
2465 @item @emph{Example}:
2467 program test_complex
2470 print *, complex(i, x)
2471 end program test_complex
2474 @item @emph{See also}:
2481 @section @code{CONJG} --- Complex conjugate function
2484 @cindex complex conjugate
2487 @item @emph{Description}:
2488 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
2489 then the result is @code{(x, -y)}
2491 @item @emph{Standard}:
2492 F77 and later, has overloads that are GNU extensions
2497 @item @emph{Syntax}:
2500 @item @emph{Arguments}:
2501 @multitable @columnfractions .15 .70
2502 @item @var{Z} @tab The type shall be @code{COMPLEX(*)}.
2505 @item @emph{Return value}:
2506 The return value is of type @code{COMPLEX(*)}.
2508 @item @emph{Example}:
2511 complex :: z = (2.0, 3.0)
2512 complex(8) :: dz = (2.71_8, -3.14_8)
2517 end program test_conjg
2520 @item @emph{Specific names}:
2521 @multitable @columnfractions .20 .20 .20 .25
2522 @item Name @tab Argument @tab Return type @tab Standard
2523 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
2530 @section @code{COS} --- Cosine function
2536 @cindex trigonometric function, cosine
2540 @item @emph{Description}:
2541 @code{COS(X)} computes the cosine of @var{X}.
2543 @item @emph{Standard}:
2544 F77 and later, has overloads that are GNU extensions
2549 @item @emph{Syntax}:
2550 @code{RESULT = COS(X)}
2552 @item @emph{Arguments}:
2553 @multitable @columnfractions .15 .70
2554 @item @var{X} @tab The type shall be @code{REAL(*)} or
2558 @item @emph{Return value}:
2559 The return value is of type @code{REAL(*)} and it lies in the
2560 range @math{ -1 \leq \cos (x) \leq 1}. The kind type
2561 parameter is the same as @var{X}.
2563 @item @emph{Example}:
2568 end program test_cos
2571 @item @emph{Specific names}:
2572 @multitable @columnfractions .20 .20 .20 .25
2573 @item Name @tab Argument @tab Return type @tab Standard
2574 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
2575 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab F77 and later
2576 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2577 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2580 @item @emph{See also}:
2581 Inverse function: @ref{ACOS}
2588 @section @code{COSH} --- Hyperbolic cosine function
2591 @cindex hyperbolic cosine
2592 @cindex hyperbolic function, cosine
2593 @cindex cosine, hyperbolic
2596 @item @emph{Description}:
2597 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2599 @item @emph{Standard}:
2605 @item @emph{Syntax}:
2608 @item @emph{Arguments}:
2609 @multitable @columnfractions .15 .70
2610 @item @var{X} @tab The type shall be @code{REAL(*)}.
2613 @item @emph{Return value}:
2614 The return value is of type @code{REAL(*)} and it is positive
2615 (@math{ \cosh (x) \geq 0 }.
2617 @item @emph{Example}:
2620 real(8) :: x = 1.0_8
2622 end program test_cosh
2625 @item @emph{Specific names}:
2626 @multitable @columnfractions .20 .20 .20 .25
2627 @item Name @tab Argument @tab Return type @tab Standard
2628 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
2631 @item @emph{See also}:
2632 Inverse function: @ref{ACOSH}
2639 @section @code{COUNT} --- Count function
2641 @cindex array, conditionally count elements
2642 @cindex array, element counting
2643 @cindex array, number of elements
2646 @item @emph{Description}:
2648 @code{COUNT(MASK [, DIM [, KIND]])} counts the number of @code{.TRUE.}
2649 elements of @var{MASK} along the dimension of @var{DIM}. If @var{DIM} is
2650 omitted it is taken to be @code{1}. @var{DIM} is a scaler of type
2651 @code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n}
2652 is the rank of @var{MASK}.
2654 @item @emph{Standard}:
2658 Transformational function
2660 @item @emph{Syntax}:
2661 @code{RESULT = COUNT(MASK [, DIM [, KIND]])}
2663 @item @emph{Arguments}:
2664 @multitable @columnfractions .15 .70
2665 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
2666 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
2667 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2668 expression indicating the kind parameter of
2672 @item @emph{Return value}:
2673 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
2674 @var{KIND} is absent, the return value is of default integer kind.
2675 The result has a rank equal to that of @var{MASK}.
2677 @item @emph{Example}:
2680 integer, dimension(2,3) :: a, b
2681 logical, dimension(2,3) :: mask
2682 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
2683 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
2684 print '(3i3)', a(1,:)
2685 print '(3i3)', a(2,:)
2687 print '(3i3)', b(1,:)
2688 print '(3i3)', b(2,:)
2691 print '(3l3)', mask(1,:)
2692 print '(3l3)', mask(2,:)
2694 print '(3i3)', count(mask)
2696 print '(3i3)', count(mask, 1)
2698 print '(3i3)', count(mask, 2)
2699 end program test_count
2706 @section @code{CPU_TIME} --- CPU elapsed time in seconds
2708 @cindex time, elapsed
2711 @item @emph{Description}:
2712 Returns a @code{REAL(*)} value representing the elapsed CPU time in
2713 seconds. This is useful for testing segments of code to determine
2716 @item @emph{Standard}:
2722 @item @emph{Syntax}:
2723 @code{CALL CPU_TIME(TIME)}
2725 @item @emph{Arguments}:
2726 @multitable @columnfractions .15 .70
2727 @item @var{TIME} @tab The type shall be @code{REAL(*)} with @code{INTENT(OUT)}.
2730 @item @emph{Return value}:
2733 @item @emph{Example}:
2735 program test_cpu_time
2736 real :: start, finish
2737 call cpu_time(start)
2738 ! put code to test here
2739 call cpu_time(finish)
2740 print '("Time = ",f6.3," seconds.")',finish-start
2741 end program test_cpu_time
2744 @item @emph{See also}:
2745 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
2751 @section @code{CSHIFT} --- Circular shift elements of an array
2753 @cindex array, shift circularly
2754 @cindex array, permutation
2755 @cindex array, rotate
2758 @item @emph{Description}:
2759 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
2760 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
2761 taken to be @code{1}. @var{DIM} is a scaler of type @code{INTEGER} in the
2762 range of @math{1 /leq DIM /leq n)} where @math{n} is the rank of @var{ARRAY}.
2763 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
2764 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
2765 sections of @var{ARRAY} along the given dimension are shifted. Elements
2766 shifted out one end of each rank one section are shifted back in the other end.
2768 @item @emph{Standard}:
2772 Transformational function
2774 @item @emph{Syntax}:
2775 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
2777 @item @emph{Arguments}:
2778 @multitable @columnfractions .15 .70
2779 @item @var{ARRAY} @tab Shall be an array of any type.
2780 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
2781 @item @var{DIM} @tab The type shall be @code{INTEGER}.
2784 @item @emph{Return value}:
2785 Returns an array of same type and rank as the @var{ARRAY} argument.
2787 @item @emph{Example}:
2790 integer, dimension(3,3) :: a
2791 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
2792 print '(3i3)', a(1,:)
2793 print '(3i3)', a(2,:)
2794 print '(3i3)', a(3,:)
2795 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
2797 print '(3i3)', a(1,:)
2798 print '(3i3)', a(2,:)
2799 print '(3i3)', a(3,:)
2800 end program test_cshift
2807 @section @code{CTIME} --- Convert a time into a string
2809 @cindex time, conversion to string
2810 @cindex conversion, to string
2813 @item @emph{Description}:
2814 @code{CTIME} converts a system time value, such as returned by
2815 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
2817 This intrinsic is provided in both subroutine and function forms; however,
2818 only one form can be used in any given program unit.
2820 @item @emph{Standard}:
2824 Subroutine, function
2826 @item @emph{Syntax}:
2827 @multitable @columnfractions .80
2828 @item @code{CALL CTIME(TIME, RESULT)}.
2829 @item @code{RESULT = CTIME(TIME)}, (not recommended).
2832 @item @emph{Arguments}:
2833 @multitable @columnfractions .15 .70
2834 @item @var{TIME} @tab The type shall be of type @code{INTEGER(KIND=8)}.
2835 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER}.
2838 @item @emph{Return value}:
2839 The converted date and time as a string.
2841 @item @emph{Example}:
2845 character(len=30) :: date
2848 ! Do something, main part of the program
2851 print *, 'Program was started on ', date
2852 end program test_ctime
2855 @item @emph{See Also}:
2856 @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
2862 @section @code{DATE_AND_TIME} --- Date and time subroutine
2863 @fnindex DATE_AND_TIME
2864 @cindex date, current
2865 @cindex current date
2866 @cindex time, current
2867 @cindex current time
2870 @item @emph{Description}:
2871 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
2872 time information from the real-time system clock. @var{DATE} is
2873 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
2874 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
2875 representing the difference with respect to Coordinated Universal Time (UTC).
2876 Unavailable time and date parameters return blanks.
2878 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
2880 @multitable @columnfractions .15 .30 .40
2881 @item @tab @code{VALUE(1)}: @tab The year
2882 @item @tab @code{VALUE(2)}: @tab The month
2883 @item @tab @code{VALUE(3)}: @tab The day of the month
2884 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
2885 @item @tab @code{VALUE(5)}: @tab The hour of the day
2886 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
2887 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
2888 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
2891 @item @emph{Standard}:
2897 @item @emph{Syntax}:
2898 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
2900 @item @emph{Arguments}:
2901 @multitable @columnfractions .15 .70
2902 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(8)} or larger.
2903 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(10)} or larger.
2904 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(5)} or larger.
2905 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
2908 @item @emph{Return value}:
2911 @item @emph{Example}:
2913 program test_time_and_date
2914 character(8) :: date
2915 character(10) :: time
2916 character(5) :: zone
2917 integer,dimension(8) :: values
2918 ! using keyword arguments
2919 call date_and_time(date,time,zone,values)
2920 call date_and_time(DATE=date,ZONE=zone)
2921 call date_and_time(TIME=time)
2922 call date_and_time(VALUES=values)
2923 print '(a,2x,a,2x,a)', date, time, zone
2924 print '(8i5))', values
2925 end program test_time_and_date
2928 @item @emph{See also}:
2929 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
2935 @section @code{DBLE} --- Double conversion function
2937 @cindex conversion, to real
2940 @item @emph{Description}:
2941 @code{DBLE(X)} Converts @var{X} to double precision real type.
2943 @item @emph{Standard}:
2949 @item @emph{Syntax}:
2950 @code{RESULT = DBLE(X)}
2952 @item @emph{Arguments}:
2953 @multitable @columnfractions .15 .70
2954 @item @var{X} @tab The type shall be @code{INTEGER(*)}, @code{REAL(*)},
2955 or @code{COMPLEX(*)}.
2958 @item @emph{Return value}:
2959 The return value is of type double precision real.
2961 @item @emph{Example}:
2966 complex :: z = (2.3,1.14)
2967 print *, dble(x), dble(i), dble(z)
2968 end program test_dble
2971 @item @emph{See also}:
2972 @ref{DFLOAT}, @ref{FLOAT}, @ref{REAL}
2978 @section @code{DCMPLX} --- Double complex conversion function
2980 @cindex complex numbers, conversion to
2981 @cindex conversion, to complex
2984 @item @emph{Description}:
2985 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
2986 converted to the real component. If @var{Y} is present it is converted to the
2987 imaginary component. If @var{Y} is not present then the imaginary component is
2988 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
2990 @item @emph{Standard}:
2996 @item @emph{Syntax}:
2997 @code{RESULT = DCMPLX(X [, Y])}
2999 @item @emph{Arguments}:
3000 @multitable @columnfractions .15 .70
3001 @item @var{X} @tab The type may be @code{INTEGER(*)}, @code{REAL(*)},
3002 or @code{COMPLEX(*)}.
3003 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX(*)}.) May be
3004 @code{INTEGER(*)} or @code{REAL(*)}.
3007 @item @emph{Return value}:
3008 The return value is of type @code{COMPLEX(8)}
3010 @item @emph{Example}:
3020 print *, dcmplx(x,i)
3021 end program test_dcmplx
3028 @section @code{DFLOAT} --- Double conversion function
3030 @cindex conversion, to real
3033 @item @emph{Description}:
3034 @code{DFLOAT(X)} Converts @var{X} to double precision real type.
3036 @item @emph{Standard}:
3042 @item @emph{Syntax}:
3043 @code{RESULT = DFLOAT(X)}
3045 @item @emph{Arguments}:
3046 @multitable @columnfractions .15 .70
3047 @item @var{X} @tab The type shall be @code{INTEGER(*)}.
3050 @item @emph{Return value}:
3051 The return value is of type double precision real.
3053 @item @emph{Example}:
3058 end program test_dfloat
3061 @item @emph{See also}:
3062 @ref{DBLE}, @ref{FLOAT}, @ref{REAL}
3068 @section @code{DIGITS} --- Significant digits function
3070 @cindex model representation, significant digits
3073 @item @emph{Description}:
3074 @code{DIGITS(X)} returns the number of significant digits of the internal model
3075 representation of @var{X}. For example, on a system using a 32-bit
3076 floating point representation, a default real number would likely return 24.
3078 @item @emph{Standard}:
3084 @item @emph{Syntax}:
3085 @code{RESULT = DIGITS(X)}
3087 @item @emph{Arguments}:
3088 @multitable @columnfractions .15 .70
3089 @item @var{X} @tab The type may be @code{INTEGER(*)} or @code{REAL(*)}.
3092 @item @emph{Return value}:
3093 The return value is of type @code{INTEGER}.
3095 @item @emph{Example}:
3098 integer :: i = 12345
3104 end program test_digits
3111 @section @code{DIM} --- Positive difference
3115 @cindex positive difference
3118 @item @emph{Description}:
3119 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3120 otherwise returns zero.
3122 @item @emph{Standard}:
3128 @item @emph{Syntax}:
3129 @code{RESULT = DIM(X, Y)}
3131 @item @emph{Arguments}:
3132 @multitable @columnfractions .15 .70
3133 @item @var{X} @tab The type shall be @code{INTEGER(*)} or @code{REAL(*)}
3134 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3137 @item @emph{Return value}:
3138 The return value is of type @code{INTEGER(*)} or @code{REAL(*)}.
3140 @item @emph{Example}:
3146 x = dim(4.345_8, 2.111_8)
3149 end program test_dim
3152 @item @emph{Specific names}:
3153 @multitable @columnfractions .20 .20 .20 .25
3154 @item Name @tab Argument @tab Return type @tab Standard
3155 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X,Y} @tab @code{INTEGER(4)} @tab F77 and later
3156 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X,Y} @tab @code{REAL(8)} @tab F77 and later
3163 @section @code{DOT_PRODUCT} --- Dot product function
3164 @fnindex DOT_PRODUCT
3166 @cindex vector product
3167 @cindex product, vector
3170 @item @emph{Description}:
3171 @code{DOT_PRODUCT(X,Y)} computes the dot product multiplication of two vectors
3172 @var{X} and @var{Y}. The two vectors may be either numeric or logical
3173 and must be arrays of rank one and of equal size. If the vectors are
3174 @code{INTEGER(*)} or @code{REAL(*)}, the result is @code{SUM(X*Y)}. If the
3175 vectors are @code{COMPLEX(*)}, the result is @code{SUM(CONJG(X)*Y)}. If the
3176 vectors are @code{LOGICAL}, the result is @code{ANY(X.AND.Y)}.
3178 @item @emph{Standard}:
3182 Transformational function
3184 @item @emph{Syntax}:
3185 @code{RESULT = DOT_PRODUCT(X, Y)}
3187 @item @emph{Arguments}:
3188 @multitable @columnfractions .15 .70
3189 @item @var{X} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3190 @item @var{Y} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3193 @item @emph{Return value}:
3194 If the arguments are numeric, the return value is a scaler of numeric type,
3195 @code{INTEGER(*)}, @code{REAL(*)}, or @code{COMPLEX(*)}. If the arguments are
3196 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3198 @item @emph{Example}:
3200 program test_dot_prod
3201 integer, dimension(3) :: a, b
3208 print *, dot_product(a,b)
3209 end program test_dot_prod
3216 @section @code{DPROD} --- Double product function
3218 @cindex product, double-precision
3221 @item @emph{Description}:
3222 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3224 @item @emph{Standard}:
3230 @item @emph{Syntax}:
3231 @code{RESULT = DPROD(X, Y)}
3233 @item @emph{Arguments}:
3234 @multitable @columnfractions .15 .70
3235 @item @var{X} @tab The type shall be @code{REAL}.
3236 @item @var{Y} @tab The type shall be @code{REAL}.
3239 @item @emph{Return value}:
3240 The return value is of type @code{REAL(8)}.
3242 @item @emph{Example}:
3250 end program test_dprod
3257 @section @code{DREAL} --- Double real part function
3259 @cindex complex numbers, real part
3262 @item @emph{Description}:
3263 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3265 @item @emph{Standard}:
3271 @item @emph{Syntax}:
3272 @code{RESULT = DREAL(Z)}
3274 @item @emph{Arguments}:
3275 @multitable @columnfractions .15 .70
3276 @item @var{Z} @tab The type shall be @code{COMPLEX(8)}.
3279 @item @emph{Return value}:
3280 The return value is of type @code{REAL(8)}.
3282 @item @emph{Example}:
3285 complex(8) :: z = (1.3_8,7.2_8)
3287 end program test_dreal
3290 @item @emph{See also}:
3298 @section @code{DTIME} --- Execution time subroutine (or function)
3300 @cindex time, elapsed
3301 @cindex elapsed time
3304 @item @emph{Description}:
3305 @code{DTIME(TARRAY, RESULT)} initially returns the number of seconds of runtime
3306 since the start of the process's execution in @var{RESULT}. @var{TARRAY}
3307 returns the user and system components of this time in @code{TARRAY(1)} and
3308 @code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) +
3311 Subsequent invocations of @code{DTIME} return values accumulated since the
3312 previous invocation.
3314 On some systems, the underlying timings are represented using types with
3315 sufficiently small limits that overflows (wrap around) are possible, such as
3316 32-bit types. Therefore, the values returned by this intrinsic might be, or
3317 become, negative, or numerically less than previous values, during a single
3318 run of the compiled program.
3320 This intrinsic is provided in both subroutine and function forms; however,
3321 only one form can be used in any given program unit.
3323 @var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
3325 @multitable @columnfractions .15 .30 .40
3326 @item @tab @code{TARRAY(1)}: @tab User time in seconds.
3327 @item @tab @code{TARRAY(2)}: @tab System time in seconds.
3328 @item @tab @code{RESULT}: @tab Run time since start in seconds.
3331 @item @emph{Standard}:
3335 Subroutine, function
3337 @item @emph{Syntax}:
3338 @multitable @columnfractions .80
3339 @item @code{CALL DTIME(TARRAY, RESULT)}.
3340 @item @code{RESULT = DTIME(TARRAY)}, (not recommended).
3343 @item @emph{Arguments}:
3344 @multitable @columnfractions .15 .70
3345 @item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
3346 @item @var{RESULT}@tab The type shall be @code{REAL}.
3349 @item @emph{Return value}:
3350 Elapsed time in seconds since the start of program execution.
3352 @item @emph{Example}:
3356 real, dimension(2) :: tarray
3358 call dtime(tarray, result)
3362 do i=1,100000000 ! Just a delay
3365 call dtime(tarray, result)
3369 end program test_dtime
3376 @section @code{EOSHIFT} --- End-off shift elements of an array
3378 @cindex array, shift
3381 @item @emph{Description}:
3382 @code{EOSHIFT(ARRAY, SHIFT[,BOUNDARY, DIM])} performs an end-off shift on
3383 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
3384 omitted it is taken to be @code{1}. @var{DIM} is a scaler of type
3385 @code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n} is the
3386 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
3387 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
3388 then all complete rank one sections of @var{ARRAY} along the given dimension are
3389 shifted. Elements shifted out one end of each rank one section are dropped. If
3390 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3391 is copied back in the other end. If @var{BOUNDARY} is not present then the
3392 following are copied in depending on the type of @var{ARRAY}.
3394 @multitable @columnfractions .15 .80
3395 @item @emph{Array Type} @tab @emph{Boundary Value}
3396 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
3397 @item Logical @tab @code{.FALSE.}.
3398 @item Character(@var{len}) @tab @var{len} blanks.
3401 @item @emph{Standard}:
3405 Transformational function
3407 @item @emph{Syntax}:
3408 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3410 @item @emph{Arguments}:
3411 @multitable @columnfractions .15 .70
3412 @item @var{ARRAY} @tab May be any type, not scaler.
3413 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3414 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3415 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3418 @item @emph{Return value}:
3419 Returns an array of same type and rank as the @var{ARRAY} argument.
3421 @item @emph{Example}:
3423 program test_eoshift
3424 integer, dimension(3,3) :: a
3425 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3426 print '(3i3)', a(1,:)
3427 print '(3i3)', a(2,:)
3428 print '(3i3)', a(3,:)
3429 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3431 print '(3i3)', a(1,:)
3432 print '(3i3)', a(2,:)
3433 print '(3i3)', a(3,:)
3434 end program test_eoshift
3441 @section @code{EPSILON} --- Epsilon function
3443 @cindex model representation, epsilon
3446 @item @emph{Description}:
3447 @code{EPSILON(X)} returns a nearly negligible number relative to @code{1}.
3449 @item @emph{Standard}:
3455 @item @emph{Syntax}:
3456 @code{RESULT = EPSILON(X)}
3458 @item @emph{Arguments}:
3459 @multitable @columnfractions .15 .70
3460 @item @var{X} @tab The type shall be @code{REAL(*)}.
3463 @item @emph{Return value}:
3464 The return value is of same type as the argument.
3466 @item @emph{Example}:
3468 program test_epsilon
3473 end program test_epsilon
3480 @section @code{ERF} --- Error function
3482 @cindex error function
3485 @item @emph{Description}:
3486 @code{ERF(X)} computes the error function of @var{X}.
3488 @item @emph{Standard}:
3494 @item @emph{Syntax}:
3495 @code{RESULT = ERF(X)}
3497 @item @emph{Arguments}:
3498 @multitable @columnfractions .15 .70
3499 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
3502 @item @emph{Return value}:
3503 The return value is a scalar of type @code{REAL(*)} and it is positive
3504 (@math{ - 1 \leq erf (x) \leq 1 }.
3506 @item @emph{Example}:
3509 real(8) :: x = 0.17_8
3511 end program test_erf
3514 @item @emph{Specific names}:
3515 @multitable @columnfractions .20 .20 .20 .25
3516 @item Name @tab Argument @tab Return type @tab Standard
3517 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3524 @section @code{ERFC} --- Error function
3526 @cindex error function, complementary
3529 @item @emph{Description}:
3530 @code{ERFC(X)} computes the complementary error function of @var{X}.
3532 @item @emph{Standard}:
3538 @item @emph{Syntax}:
3539 @code{RESULT = ERFC(X)}
3541 @item @emph{Arguments}:
3542 @multitable @columnfractions .15 .70
3543 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
3546 @item @emph{Return value}:
3547 The return value is a scalar of type @code{REAL(*)} and it is positive
3548 (@math{ 0 \leq erfc (x) \leq 2 }.
3550 @item @emph{Example}:
3553 real(8) :: x = 0.17_8
3555 end program test_erfc
3558 @item @emph{Specific names}:
3559 @multitable @columnfractions .20 .20 .20 .25
3560 @item Name @tab Argument @tab Return type @tab Standard
3561 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3568 @section @code{ETIME} --- Execution time subroutine (or function)
3570 @cindex time, elapsed
3573 @item @emph{Description}:
3574 @code{ETIME(TARRAY, RESULT)} returns the number of seconds of runtime
3575 since the start of the process's execution in @var{RESULT}. @var{TARRAY}
3576 returns the user and system components of this time in @code{TARRAY(1)} and
3577 @code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) + TARRAY(2)}.
3579 On some systems, the underlying timings are represented using types with
3580 sufficiently small limits that overflows (wrap around) are possible, such as
3581 32-bit types. Therefore, the values returned by this intrinsic might be, or
3582 become, negative, or numerically less than previous values, during a single
3583 run of the compiled program.
3585 This intrinsic is provided in both subroutine and function forms; however,
3586 only one form can be used in any given program unit.
3588 @var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
3590 @multitable @columnfractions .15 .30 .60
3591 @item @tab @code{TARRAY(1)}: @tab User time in seconds.
3592 @item @tab @code{TARRAY(2)}: @tab System time in seconds.
3593 @item @tab @code{RESULT}: @tab Run time since start in seconds.
3596 @item @emph{Standard}:
3600 Subroutine, function
3602 @item @emph{Syntax}:
3603 @multitable @columnfractions .80
3604 @item @code{CALL ETIME(TARRAY, RESULT)}.
3605 @item @code{RESULT = ETIME(TARRAY)}, (not recommended).
3608 @item @emph{Arguments}:
3609 @multitable @columnfractions .15 .70
3610 @item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
3611 @item @var{RESULT}@tab The type shall be @code{REAL}.
3614 @item @emph{Return value}:
3615 Elapsed time in seconds since the start of program execution.
3617 @item @emph{Example}:
3621 real, dimension(2) :: tarray
3623 call ETIME(tarray, result)
3627 do i=1,100000000 ! Just a delay
3630 call ETIME(tarray, result)
3634 end program test_etime
3637 @item @emph{See also}:
3645 @section @code{EXIT} --- Exit the program with status.
3647 @cindex program termination
3648 @cindex terminate program
3651 @item @emph{Description}:
3652 @code{EXIT} causes immediate termination of the program with status. If status
3653 is omitted it returns the canonical @emph{success} for the system. All Fortran
3654 I/O units are closed.
3656 @item @emph{Standard}:
3662 @item @emph{Syntax}:
3663 @code{CALL EXIT([STATUS])}
3665 @item @emph{Arguments}:
3666 @multitable @columnfractions .15 .70
3667 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
3670 @item @emph{Return value}:
3671 @code{STATUS} is passed to the parent process on exit.
3673 @item @emph{Example}:
3676 integer :: STATUS = 0
3677 print *, 'This program is going to exit.'
3679 end program test_exit
3682 @item @emph{See also}:
3683 @ref{ABORT}, @ref{KILL}
3689 @section @code{EXP} --- Exponential function
3695 @cindex exponential function
3696 @cindex logarithmic function, inverse
3699 @item @emph{Description}:
3700 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
3702 @item @emph{Standard}:
3703 F77 and later, has overloads that are GNU extensions
3708 @item @emph{Syntax}:
3709 @code{RESULT = EXP(X)}
3711 @item @emph{Arguments}:
3712 @multitable @columnfractions .15 .70
3713 @item @var{X} @tab The type shall be @code{REAL(*)} or
3717 @item @emph{Return value}:
3718 The return value has same type and kind as @var{X}.
3720 @item @emph{Example}:
3725 end program test_exp
3728 @item @emph{Specific names}:
3729 @multitable @columnfractions .20 .20 .20 .25
3730 @item Name @tab Argument @tab Return type @tab Standard
3731 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
3732 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab F77 and later
3733 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3734 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3741 @section @code{EXPONENT} --- Exponent function
3743 @cindex real number, exponent
3744 @cindex floating point, exponent
3747 @item @emph{Description}:
3748 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
3749 is zero the value returned is zero.
3751 @item @emph{Standard}:
3757 @item @emph{Syntax}:
3758 @code{RESULT = EXPONENT(X)}
3760 @item @emph{Arguments}:
3761 @multitable @columnfractions .15 .70
3762 @item @var{X} @tab The type shall be @code{REAL(*)}.
3765 @item @emph{Return value}:
3766 The return value is of type default @code{INTEGER}.
3768 @item @emph{Example}:
3770 program test_exponent
3775 print *, exponent(0.0)
3776 end program test_exponent
3783 @section @code{FDATE} --- Get the current time as a string
3785 @cindex time, current
3786 @cindex current time
3787 @cindex date, current
3788 @cindex current date
3791 @item @emph{Description}:
3792 @code{FDATE(DATE)} returns the current date (using the same format as
3793 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
3796 This intrinsic is provided in both subroutine and function forms; however,
3797 only one form can be used in any given program unit.
3799 @var{DATE} is an @code{INTENT(OUT)} @code{CHARACTER} variable.
3801 @item @emph{Standard}:
3805 Subroutine, function
3807 @item @emph{Syntax}:
3808 @multitable @columnfractions .80
3809 @item @code{CALL FDATE(DATE)}.
3810 @item @code{DATE = FDATE()}, (not recommended).
3813 @item @emph{Arguments}:
3814 @multitable @columnfractions .15 .70
3815 @item @var{DATE}@tab The type shall be of type @code{CHARACTER}.
3818 @item @emph{Return value}:
3819 The current date as a string.
3821 @item @emph{Example}:
3825 character(len=30) :: date
3827 print *, 'Program started on ', date
3828 do i = 1, 100000000 ! Just a delay
3832 print *, 'Program ended on ', date
3833 end program test_fdate
3840 @section @code{FLOAT} --- Convert integer to default real
3842 @cindex conversion, to real
3845 @item @emph{Description}:
3846 @code{FLOAT(I)} converts the integer @var{I} to a default real value.
3848 @item @emph{Standard}:
3854 @item @emph{Syntax}:
3855 @code{RESULT = FLOAT(I)}
3857 @item @emph{Arguments}:
3858 @multitable @columnfractions .15 .70
3859 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
3862 @item @emph{Return value}:
3863 The return value is of type default @code{REAL}.
3865 @item @emph{Example}:
3869 if (float(i) /= 1.) call abort
3870 end program test_float
3873 @item @emph{See also}:
3874 @ref{DBLE}, @ref{DFLOAT}, @ref{REAL}
3880 @section @code{FGET} --- Read a single character in stream mode from stdin
3882 @cindex read character, stream mode
3883 @cindex stream mode, read character
3884 @cindex file operation, read character
3887 @item @emph{Description}:
3888 Read a single character in stream mode from stdin by bypassing normal
3889 formatted output. Stream I/O should not be mixed with normal record-oriented
3890 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
3892 This intrinsic is provided in both subroutine and function forms; however,
3893 only one form can be used in any given program unit.
3895 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
3896 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
3897 Programmers should consider the use of new stream IO feature in new code
3898 for future portability. See also @ref{Fortran 2003 status}.
3900 @item @emph{Standard}:
3904 Subroutine, function
3906 @item @emph{Syntax}:
3907 @code{CALL FGET(C [, STATUS])}
3909 @item @emph{Arguments}:
3910 @multitable @columnfractions .15 .70
3911 @item @var{C} @tab The type shall be @code{CHARACTER}.
3912 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
3913 Returns 0 on success, -1 on end-of-file, and a
3914 system specific positive error code otherwise.
3917 @item @emph{Example}:
3920 INTEGER, PARAMETER :: strlen = 100
3921 INTEGER :: status, i = 1
3922 CHARACTER(len=strlen) :: str = ""
3924 WRITE (*,*) 'Enter text:'
3926 CALL fget(str(i:i), status)
3927 if (status /= 0 .OR. i > strlen) exit
3930 WRITE (*,*) TRIM(str)
3934 @item @emph{See also}:
3935 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
3941 @section @code{FGETC} --- Read a single character in stream mode
3943 @cindex read character, stream mode
3944 @cindex stream mode, read character
3945 @cindex file operation, read character
3948 @item @emph{Description}:
3949 Read a single character in stream mode by bypassing normal formatted output.
3950 Stream I/O should not be mixed with normal record-oriented (formatted or
3951 unformatted) I/O on the same unit; the results are unpredictable.
3953 This intrinsic is provided in both subroutine and function forms; however,
3954 only one form can be used in any given program unit.
3956 Note that the @code{FGET} intrinsic is provided for backwards compatibility
3957 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
3958 Programmers should consider the use of new stream IO feature in new code
3959 for future portability. See also @ref{Fortran 2003 status}.
3961 @item @emph{Standard}:
3965 Subroutine, function
3967 @item @emph{Syntax}:
3968 @code{CALL FGETC(UNIT, C [, STATUS])}
3970 @item @emph{Arguments}:
3971 @multitable @columnfractions .15 .70
3972 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
3973 @item @var{C} @tab The type shall be @code{CHARACTER}.
3974 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
3975 -1 on end-of-file and a system specific positive error code otherwise.
3978 @item @emph{Example}:
3981 INTEGER :: fd = 42, status
3984 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
3986 CALL fgetc(fd, c, status)
3987 IF (status /= 0) EXIT
3994 @item @emph{See also}:
3995 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4001 @section @code{FLOOR} --- Integer floor function
4004 @cindex rounding, floor
4007 @item @emph{Description}:
4008 @code{FLOOR(X)} returns the greatest integer less than or equal to @var{X}.
4010 @item @emph{Standard}:
4016 @item @emph{Syntax}:
4017 @code{RESULT = FLOOR(X [, KIND])}
4019 @item @emph{Arguments}:
4020 @multitable @columnfractions .15 .70
4021 @item @var{X} @tab The type shall be @code{REAL(*)}.
4022 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
4023 expression indicating the kind parameter of
4027 @item @emph{Return value}:
4028 The return value is of type @code{INTEGER(KIND)}
4030 @item @emph{Example}:
4035 print *, floor(x) ! returns 63
4036 print *, floor(y) ! returns -64
4037 end program test_floor
4040 @item @emph{See also}:
4041 @ref{CEILING}, @ref{NINT}
4048 @section @code{FLUSH} --- Flush I/O unit(s)
4050 @cindex file operation, flush
4053 @item @emph{Description}:
4054 Flushes Fortran unit(s) currently open for output. Without the optional
4055 argument, all units are flushed, otherwise just the unit specified.
4057 @item @emph{Standard}:
4063 @item @emph{Syntax}:
4064 @code{CALL FLUSH(UNIT)}
4066 @item @emph{Arguments}:
4067 @multitable @columnfractions .15 .70
4068 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4072 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4073 statement that should be preferred over the @code{FLUSH} intrinsic.
4080 @section @code{FNUM} --- File number function
4082 @cindex file operation, file number
4085 @item @emph{Description}:
4086 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4087 open Fortran I/O unit @code{UNIT}.
4089 @item @emph{Standard}:
4095 @item @emph{Syntax}:
4096 @code{RESULT = FNUM(UNIT)}
4098 @item @emph{Arguments}:
4099 @multitable @columnfractions .15 .70
4100 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4103 @item @emph{Return value}:
4104 The return value is of type @code{INTEGER}
4106 @item @emph{Example}:
4110 open (unit=10, status = "scratch")
4114 end program test_fnum
4121 @section @code{FPUT} --- Write a single character in stream mode to stdout
4123 @cindex write character, stream mode
4124 @cindex stream mode, write character
4125 @cindex file operation, write character
4128 @item @emph{Description}:
4129 Write a single character in stream mode to stdout by bypassing normal
4130 formatted output. Stream I/O should not be mixed with normal record-oriented
4131 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4133 This intrinsic is provided in both subroutine and function forms; however,
4134 only one form can be used in any given program unit.
4136 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4137 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4138 Programmers should consider the use of new stream IO feature in new code
4139 for future portability. See also @ref{Fortran 2003 status}.
4141 @item @emph{Standard}:
4145 Subroutine, function
4147 @item @emph{Syntax}:
4148 @code{CALL FPUT(C [, STATUS])}
4150 @item @emph{Arguments}:
4151 @multitable @columnfractions .15 .70
4152 @item @var{C} @tab The type shall be @code{CHARACTER}.
4153 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
4154 -1 on end-of-file and a system specific positive error code otherwise.
4157 @item @emph{Example}:
4160 CHARACTER(len=10) :: str = "gfortran"
4162 DO i = 1, len_trim(str)
4168 @item @emph{See also}:
4169 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4175 @section @code{FPUTC} --- Write a single character in stream mode
4177 @cindex write character, stream mode
4178 @cindex stream mode, write character
4179 @cindex file operation, write character
4182 @item @emph{Description}:
4183 Write a single character in stream mode by bypassing normal formatted
4184 output. Stream I/O should not be mixed with normal record-oriented
4185 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4187 This intrinsic is provided in both subroutine and function forms; however,
4188 only one form can be used in any given program unit.
4190 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4191 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4192 Programmers should consider the use of new stream IO feature in new code
4193 for future portability. See also @ref{Fortran 2003 status}.
4195 @item @emph{Standard}:
4199 Subroutine, function
4201 @item @emph{Syntax}:
4202 @code{CALL FPUTC(UNIT, C [, STATUS])}
4204 @item @emph{Arguments}:
4205 @multitable @columnfractions .15 .70
4206 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4207 @item @var{C} @tab The type shall be @code{CHARACTER}.
4208 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
4209 -1 on end-of-file and a system specific positive error code otherwise.
4212 @item @emph{Example}:
4215 CHARACTER(len=10) :: str = "gfortran"
4216 INTEGER :: fd = 42, i
4218 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4219 DO i = 1, len_trim(str)
4220 CALL fputc(fd, str(i:i))
4226 @item @emph{See also}:
4227 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4233 @section @code{FRACTION} --- Fractional part of the model representation
4235 @cindex real number, fraction
4236 @cindex floating point, fraction
4239 @item @emph{Description}:
4240 @code{FRACTION(X)} returns the fractional part of the model
4241 representation of @code{X}.
4243 @item @emph{Standard}:
4249 @item @emph{Syntax}:
4250 @code{Y = FRACTION(X)}
4252 @item @emph{Arguments}:
4253 @multitable @columnfractions .15 .70
4254 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
4257 @item @emph{Return value}:
4258 The return value is of the same type and kind as the argument.
4259 The fractional part of the model representation of @code{X} is returned;
4260 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
4262 @item @emph{Example}:
4264 program test_fraction
4267 print *, fraction(x), x * radix(x)**(-exponent(x))
4268 end program test_fraction
4276 @section @code{FREE} --- Frees memory
4278 @cindex pointer, cray
4281 @item @emph{Description}:
4282 Frees memory previously allocated by @code{MALLOC()}. The @code{FREE}
4283 intrinsic is an extension intended to be used with Cray pointers, and is
4284 provided in GNU Fortran to allow user to compile legacy code. For
4285 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
4288 @item @emph{Standard}:
4294 @item @emph{Syntax}:
4295 @code{CALL FREE(PTR)}
4297 @item @emph{Arguments}:
4298 @multitable @columnfractions .15 .70
4299 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
4300 location of the memory that should be de-allocated.
4303 @item @emph{Return value}:
4306 @item @emph{Example}:
4307 See @code{MALLOC} for an example.
4309 @item @emph{See also}:
4316 @section @code{FSEEK} --- Low level file positioning subroutine
4318 @cindex file operation, seek
4319 @cindex file operation, position
4322 @item @emph{Description}:
4323 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
4324 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
4325 if set to 1, @var{OFFSET} is taken to be relative to the current position
4326 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
4327 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
4330 This intrinsic routine is not fully backwards compatible with @command{g77}.
4331 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
4332 @var{STATUS} variable. If FSEEK is used in old code, change
4334 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
4339 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
4340 IF (status /= 0) GOTO label
4343 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
4344 Programmers should consider the use of new stream IO feature in new code
4345 for future portability. See also @ref{Fortran 2003 status}.
4347 @item @emph{Standard}:
4353 @item @emph{Syntax}:
4354 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
4356 @item @emph{Arguments}:
4357 @multitable @columnfractions .15 .70
4358 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
4359 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
4360 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
4361 Its value shall be either 0, 1 or 2.
4362 @item @var{STATUS} @tab (Optional) shall be a scalar of type
4366 @item @emph{Example}:
4369 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
4370 INTEGER :: fd, offset, ierr
4376 OPEN(UNIT=fd, FILE="fseek.test")
4377 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
4378 print *, FTELL(fd), ierr
4380 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
4381 print *, FTELL(fd), ierr
4383 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
4384 print *, FTELL(fd), ierr
4390 @item @emph{See also}:
4397 @section @code{FSTAT} --- Get file status
4399 @cindex file system, file status
4402 @item @emph{Description}:
4403 @code{FSTAT} is identical to @ref{STAT}, except that information about an
4404 already opened file is obtained.
4406 The elements in @code{BUFF} are the same as described by @ref{STAT}.
4408 This intrinsic is provided in both subroutine and function forms; however,
4409 only one form can be used in any given program unit.
4411 @item @emph{Standard}:
4415 Subroutine, function
4417 @item @emph{Syntax}:
4418 @code{CALL FSTAT(UNIT, BUFF [, STATUS])}
4420 @item @emph{Arguments}:
4421 @multitable @columnfractions .15 .70
4422 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
4423 @item @var{BUFF} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
4424 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
4425 on success and a system specific error code otherwise.
4428 @item @emph{Example}:
4429 See @ref{STAT} for an example.
4431 @item @emph{See also}:
4432 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
4438 @section @code{FTELL} --- Current stream position
4440 @cindex file operation, position
4443 @item @emph{Description}:
4444 Retrieves the current position within an open file.
4446 This intrinsic is provided in both subroutine and function forms; however,
4447 only one form can be used in any given program unit.
4449 @item @emph{Standard}:
4453 Subroutine, function
4455 @item @emph{Syntax}:
4456 @multitable @columnfractions .80
4457 @item @code{CALL FTELL(UNIT, OFFSET)}
4458 @item @code{OFFSET = FTELL(UNIT)}
4461 @item @emph{Arguments}:
4462 @multitable @columnfractions .15 .70
4463 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
4464 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
4467 @item @emph{Return value}:
4468 In either syntax, @var{OFFSET} is set to the current offset of unit
4469 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
4471 @item @emph{Example}:
4475 OPEN(10, FILE="temp.dat")
4481 @item @emph{See also}:
4488 @section @code{GERROR} --- Get last system error message
4490 @cindex system, error handling
4493 @item @emph{Description}:
4494 Returns the system error message corresponding to the last system error.
4495 This resembles the functionality of @code{strerror(3)} in C.
4497 @item @emph{Standard}:
4503 @item @emph{Syntax}:
4504 @code{CALL GERROR(RESULT)}
4506 @item @emph{Arguments}:
4507 @multitable @columnfractions .15 .70
4508 @item @var{RESULT} @tab Shall of type @code{CHARACTER(*)}.
4511 @item @emph{Example}:
4514 CHARACTER(len=100) :: msg
4520 @item @emph{See also}:
4521 @ref{IERRNO}, @ref{PERROR}
4527 @section @code{GETARG} --- Get command line arguments
4529 @cindex command-line arguments
4530 @cindex arguments, to program
4533 @item @emph{Description}:
4534 Retrieve the @var{N}th argument that was passed on the
4535 command line when the containing program was invoked.
4537 This intrinsic routine is provided for backwards compatibility with
4538 GNU Fortran 77. In new code, programmers should consider the use of
4539 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
4542 @item @emph{Standard}:
4548 @item @emph{Syntax}:
4549 @code{CALL GETARG(N, ARG)}
4551 @item @emph{Arguments}:
4552 @multitable @columnfractions .15 .70
4553 @item @var{N} @tab Shall be of type @code{INTEGER(4)}, @math{@var{N} \geq 0}
4554 @item @var{ARG} @tab Shall be of type @code{CHARACTER(*)}.
4557 @item @emph{Return value}:
4558 After @code{GETARG} returns, the @var{ARG} argument holds the @var{N}th
4559 command line argument. If @var{ARG} can not hold the argument, it is
4560 truncated to fit the length of @var{ARG}. If there are less than @var{N}
4561 arguments specified at the command line, @var{ARG} will be filled with blanks.
4562 If @math{@var{N} = 0}, @var{ARG} is set to the name of the program (on systems
4563 that support this feature).
4565 @item @emph{Example}:
4569 CHARACTER(len=32) :: arg
4578 @item @emph{See also}:
4579 GNU Fortran 77 compatibility function: @ref{IARGC}
4581 F2003 functions and subroutines: @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT},
4582 @ref{COMMAND_ARGUMENT_COUNT}
4588 @section @code{GET_COMMAND} --- Get the entire command line
4589 @fnindex GET_COMMAND
4590 @cindex command-line arguments
4591 @cindex arguments, to program
4594 @item @emph{Description}:
4595 Retrieve the entire command line that was used to invoke the program.
4597 @item @emph{Standard}:
4603 @item @emph{Syntax}:
4604 @code{CALL GET_COMMAND(CMD)}
4606 @item @emph{Arguments}:
4607 @multitable @columnfractions .15 .70
4608 @item @var{CMD} @tab Shall be of type @code{CHARACTER(*)}.
4611 @item @emph{Return value}:
4612 Stores the entire command line that was used to invoke the program in @var{ARG}.
4613 If @var{ARG} is not large enough, the command will be truncated.
4615 @item @emph{Example}:
4617 PROGRAM test_get_command
4618 CHARACTER(len=255) :: cmd
4619 CALL get_command(cmd)
4620 WRITE (*,*) TRIM(cmd)
4624 @item @emph{See also}:
4625 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4630 @node GET_COMMAND_ARGUMENT
4631 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
4632 @fnindex GET_COMMAND_ARGUMENT
4633 @cindex command-line arguments
4634 @cindex arguments, to program
4637 @item @emph{Description}:
4638 Retrieve the @var{N}th argument that was passed on the
4639 command line when the containing program was invoked.
4641 @item @emph{Standard}:
4647 @item @emph{Syntax}:
4648 @code{CALL GET_COMMAND_ARGUMENT(N, ARG)}
4650 @item @emph{Arguments}:
4651 @multitable @columnfractions .15 .70
4652 @item @var{N} @tab Shall be of type @code{INTEGER(4)}, @math{@var{N} \geq 0}
4653 @item @var{ARG} @tab Shall be of type @code{CHARACTER(*)}.
4656 @item @emph{Return value}:
4657 After @code{GET_COMMAND_ARGUMENT} returns, the @var{ARG} argument holds the
4658 @var{N}th command line argument. If @var{ARG} can not hold the argument, it is
4659 truncated to fit the length of @var{ARG}. If there are less than @var{N}
4660 arguments specified at the command line, @var{ARG} will be filled with blanks.
4661 If @math{@var{N} = 0}, @var{ARG} is set to the name of the program (on systems
4662 that support this feature).
4664 @item @emph{Example}:
4666 PROGRAM test_get_command_argument
4668 CHARACTER(len=32) :: arg
4672 CALL get_command_argument(i, arg)
4673 IF (LEN_TRIM(arg) == 0) EXIT
4675 WRITE (*,*) TRIM(arg)
4681 @item @emph{See also}:
4682 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
4688 @section @code{GETCWD} --- Get current working directory
4690 @cindex system, working directory
4693 @item @emph{Description}:
4694 Get current working directory.
4696 This intrinsic is provided in both subroutine and function forms; however,
4697 only one form can be used in any given program unit.
4699 @item @emph{Standard}:
4703 Subroutine, function
4705 @item @emph{Syntax}:
4706 @code{CALL GETCWD(CWD [, STATUS])}
4708 @item @emph{Arguments}:
4709 @multitable @columnfractions .15 .70
4710 @item @var{CWD} @tab The type shall be @code{CHARACTER(*)}.
4711 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
4712 a system specific and nonzero error code otherwise.
4715 @item @emph{Example}:
4718 CHARACTER(len=255) :: cwd
4720 WRITE(*,*) TRIM(cwd)
4724 @item @emph{See also}:
4731 @section @code{GETENV} --- Get an environmental variable
4733 @cindex environment variable
4736 @item @emph{Description}:
4737 Get the @var{VALUE} of the environmental variable @var{ENVVAR}.
4739 This intrinsic routine is provided for backwards compatibility with
4740 GNU Fortran 77. In new code, programmers should consider the use of
4741 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
4744 @item @emph{Standard}:
4750 @item @emph{Syntax}:
4751 @code{CALL GETENV(ENVVAR, VALUE)}
4753 @item @emph{Arguments}:
4754 @multitable @columnfractions .15 .70
4755 @item @var{ENVVAR} @tab Shall be of type @code{CHARACTER(*)}.
4756 @item @var{VALUE} @tab Shall be of type @code{CHARACTER(*)}.
4759 @item @emph{Return value}:
4760 Stores the value of @var{ENVVAR} in @var{VALUE}. If @var{VALUE} is
4761 not large enough to hold the data, it is truncated. If @var{ENVVAR}
4762 is not set, @var{VALUE} will be filled with blanks.
4764 @item @emph{Example}:
4767 CHARACTER(len=255) :: homedir
4768 CALL getenv("HOME", homedir)
4769 WRITE (*,*) TRIM(homedir)
4773 @item @emph{See also}:
4774 @ref{GET_ENVIRONMENT_VARIABLE}
4779 @node GET_ENVIRONMENT_VARIABLE
4780 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
4781 @fnindex GET_ENVIRONMENT_VARIABLE
4782 @cindex environment variable
4785 @item @emph{Description}:
4786 Get the @var{VALUE} of the environmental variable @var{ENVVAR}.
4788 @item @emph{Standard}:
4794 @item @emph{Syntax}:
4795 @code{CALL GET_ENVIRONMENT_VARIABLE(ENVVAR, VALUE)}
4797 @item @emph{Arguments}:
4798 @multitable @columnfractions .15 .70
4799 @item @var{ENVVAR} @tab Shall be of type @code{CHARACTER(*)}.
4800 @item @var{VALUE} @tab Shall be of type @code{CHARACTER(*)}.
4803 @item @emph{Return value}:
4804 Stores the value of @var{ENVVAR} in @var{VALUE}. If @var{VALUE} is
4805 not large enough to hold the data, it is truncated. If @var{ENVVAR}
4806 is not set, @var{VALUE} will be filled with blanks.
4808 @item @emph{Example}:
4811 CHARACTER(len=255) :: homedir
4812 CALL get_environment_variable("HOME", homedir)
4813 WRITE (*,*) TRIM(homedir)
4821 @section @code{GETGID} --- Group ID function
4823 @cindex system, group id
4826 @item @emph{Description}:
4827 Returns the numerical group ID of the current process.
4829 @item @emph{Standard}:
4835 @item @emph{Syntax}:
4836 @code{RESULT = GETGID()}
4838 @item @emph{Return value}:
4839 The return value of @code{GETGID} is an @code{INTEGER} of the default
4843 @item @emph{Example}:
4844 See @code{GETPID} for an example.
4846 @item @emph{See also}:
4847 @ref{GETPID}, @ref{GETUID}
4853 @section @code{GETLOG} --- Get login name
4855 @cindex system, login name
4859 @item @emph{Description}:
4860 Gets the username under which the program is running.
4862 @item @emph{Standard}:
4868 @item @emph{Syntax}:
4869 @code{CALL GETLOG(LOGIN)}
4871 @item @emph{Arguments}:
4872 @multitable @columnfractions .15 .70
4873 @item @var{LOGIN} @tab Shall be of type @code{CHARACTER(*)}.
4876 @item @emph{Return value}:
4877 Stores the current user name in @var{LOGIN}. (On systems where POSIX
4878 functions @code{geteuid} and @code{getpwuid} are not available, and
4879 the @code{getlogin} function is not implemented either, this will
4880 return a blank string.)
4882 @item @emph{Example}:
4885 CHARACTER(32) :: login
4891 @item @emph{See also}:
4898 @section @code{GETPID} --- Process ID function
4900 @cindex system, process id
4904 @item @emph{Description}:
4905 Returns the numerical process identifier of the current process.
4907 @item @emph{Standard}:
4913 @item @emph{Syntax}:
4914 @code{RESULT = GETPID()}
4916 @item @emph{Return value}:
4917 The return value of @code{GETPID} is an @code{INTEGER} of the default
4921 @item @emph{Example}:
4924 print *, "The current process ID is ", getpid()
4925 print *, "Your numerical user ID is ", getuid()
4926 print *, "Your numerical group ID is ", getgid()
4930 @item @emph{See also}:
4931 @ref{GETGID}, @ref{GETUID}
4937 @section @code{GETUID} --- User ID function
4939 @cindex system, user id
4943 @item @emph{Description}:
4944 Returns the numerical user ID of the current process.
4946 @item @emph{Standard}:
4952 @item @emph{Syntax}:
4953 @code{RESULT = GETUID()}
4955 @item @emph{Return value}:
4956 The return value of @code{GETUID} is an @code{INTEGER} of the default
4960 @item @emph{Example}:
4961 See @code{GETPID} for an example.
4963 @item @emph{See also}:
4964 @ref{GETPID}, @ref{GETLOG}
4970 @section @code{GMTIME} --- Convert time to GMT info
4972 @cindex time, conversion to GMT info
4975 @item @emph{Description}:
4976 Given a system time value @var{STIME} (as provided by the @code{TIME8()}
4977 intrinsic), fills @var{TARRAY} with values extracted from it appropriate
4978 to the UTC time zone (Universal Coordinated Time, also known in some
4979 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
4981 @item @emph{Standard}:
4987 @item @emph{Syntax}:
4988 @code{CALL GMTIME(STIME, TARRAY)}
4990 @item @emph{Arguments}:
4991 @multitable @columnfractions .15 .70
4992 @item @var{STIME} @tab An @code{INTEGER(*)} scalar expression
4993 corresponding to a system time, with
4995 @item @var{TARRAY} @tab A default @code{INTEGER} array with 9 elements,
4996 with @code{INTENT(OUT)}.
4999 @item @emph{Return value}:
5000 The elements of @var{TARRAY} are assigned as follows:
5002 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5004 @item Minutes after the hour, range 0--59
5005 @item Hours past midnight, range 0--23
5006 @item Day of month, range 0--31
5007 @item Number of months since January, range 0--12
5008 @item Years since 1900
5009 @item Number of days since Sunday, range 0--6
5010 @item Days since January 1
5011 @item Daylight savings indicator: positive if daylight savings is in
5012 effect, zero if not, and negative if the information is not
5016 @item @emph{See also}:
5017 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5024 @section @code{HOSTNM} --- Get system host name
5026 @cindex system, host name
5029 @item @emph{Description}:
5030 Retrieves the host name of the system on which the program is running.
5032 This intrinsic is provided in both subroutine and function forms; however,
5033 only one form can be used in any given program unit.
5035 @item @emph{Standard}:
5039 Subroutine, function
5041 @item @emph{Syntax}:
5042 @multitable @columnfractions .80
5043 @item @code{CALL HOSTNM(NAME[, STATUS])}
5044 @item @code{STATUS = HOSTNM(NAME)}
5047 @item @emph{Arguments}:
5048 @multitable @columnfractions .15 .70
5049 @item @var{NAME} @tab Shall of type @code{CHARACTER(*)}.
5050 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5051 Returns 0 on success, or a system specific error
5055 @item @emph{Return value}:
5056 In either syntax, @var{NAME} is set to the current hostname if it can
5057 be obtained, or to a blank string otherwise.
5064 @section @code{HUGE} --- Largest number of a kind
5066 @cindex limits, largest number
5067 @cindex model representation, largest number
5070 @item @emph{Description}:
5071 @code{HUGE(X)} returns the largest number that is not an infinity in
5072 the model of the type of @code{X}.
5074 @item @emph{Standard}:
5080 @item @emph{Syntax}:
5081 @code{RESULT = HUGE(X)}
5083 @item @emph{Arguments}:
5084 @multitable @columnfractions .15 .70
5085 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5088 @item @emph{Return value}:
5089 The return value is of the same type and kind as @var{X}
5091 @item @emph{Example}:
5093 program test_huge_tiny
5094 print *, huge(0), huge(0.0), huge(0.0d0)
5095 print *, tiny(0.0), tiny(0.0d0)
5096 end program test_huge_tiny
5103 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
5105 @cindex @acronym{ASCII} collating sequence
5106 @cindex collating sequence, @acronym{ASCII}
5107 @cindex conversion, to integer
5110 @item @emph{Description}:
5111 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
5112 in the first character position of @code{C}.
5114 @item @emph{Standard}:
5120 @item @emph{Syntax}:
5121 @code{RESULT = IACHAR(C [, KIND])}
5123 @item @emph{Arguments}:
5124 @multitable @columnfractions .15 .70
5125 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5126 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5127 expression indicating the kind parameter of
5131 @item @emph{Return value}:
5132 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5133 @var{KIND} is absent, the return value is of default integer kind.
5135 @item @emph{Example}:
5140 end program test_iachar
5144 See @ref{ICHAR} for a discussion of converting between numerical values
5145 and formatted string representations.
5147 @item @emph{See also}:
5148 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
5155 @section @code{IAND} --- Bitwise logical and
5157 @cindex bitwise logical and
5158 @cindex logical and, bitwise
5161 @item @emph{Description}:
5162 Bitwise logical @code{AND}.
5164 @item @emph{Standard}:
5170 @item @emph{Syntax}:
5171 @code{RESULT = IAND(I, J)}
5173 @item @emph{Arguments}:
5174 @multitable @columnfractions .15 .70
5175 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5176 @item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
5177 kind as @var{I}. (As a GNU extension, different kinds are also
5181 @item @emph{Return value}:
5182 The return type is @code{INTEGER(*)}, of the same kind as the
5183 arguments. (If the argument kinds differ, it is of the same kind as
5184 the larger argument.)
5186 @item @emph{Example}:
5190 DATA a / Z'F' /, b / Z'3' /
5191 WRITE (*,*) IAND(a, b)
5195 @item @emph{See also}:
5196 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5203 @section @code{IARGC} --- Get the number of command line arguments
5205 @cindex command-line arguments
5206 @cindex command-line arguments, number of
5207 @cindex arguments, to program
5210 @item @emph{Description}:
5211 @code{IARGC()} returns the number of arguments passed on the
5212 command line when the containing program was invoked.
5214 This intrinsic routine is provided for backwards compatibility with
5215 GNU Fortran 77. In new code, programmers should consider the use of
5216 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
5219 @item @emph{Standard}:
5225 @item @emph{Syntax}:
5226 @code{RESULT = IARGC()}
5228 @item @emph{Arguments}:
5231 @item @emph{Return value}:
5232 The number of command line arguments, type @code{INTEGER(4)}.
5234 @item @emph{Example}:
5237 @item @emph{See also}:
5238 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
5240 F2003 functions and subroutines: @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT},
5241 @ref{COMMAND_ARGUMENT_COUNT}
5247 @section @code{IBCLR} --- Clear bit
5253 @item @emph{Description}:
5254 @code{IBCLR} returns the value of @var{I} with the bit at position
5255 @var{POS} set to zero.
5257 @item @emph{Standard}:
5263 @item @emph{Syntax}:
5264 @code{RESULT = IBCLR(I, POS)}
5266 @item @emph{Arguments}:
5267 @multitable @columnfractions .15 .70
5268 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5269 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
5272 @item @emph{Return value}:
5273 The return value is of type @code{INTEGER(*)} and of the same kind as
5276 @item @emph{See also}:
5277 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5284 @section @code{IBITS} --- Bit extraction
5287 @cindex bits, extract
5290 @item @emph{Description}:
5291 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
5292 starting from bit position @var{POS} and extending left for @var{LEN}
5293 bits. The result is right-justified and the remaining bits are
5294 zeroed. The value of @code{POS+LEN} must be less than or equal to the
5295 value @code{BIT_SIZE(I)}.
5297 @item @emph{Standard}:
5303 @item @emph{Syntax}:
5304 @code{RESULT = IBITS(I, POS, LEN)}
5306 @item @emph{Arguments}:
5307 @multitable @columnfractions .15 .70
5308 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5309 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
5310 @item @var{LEN} @tab The type shall be @code{INTEGER(*)}.
5313 @item @emph{Return value}:
5314 The return value is of type @code{INTEGER(*)} and of the same kind as
5317 @item @emph{See also}:
5318 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
5324 @section @code{IBSET} --- Set bit
5329 @item @emph{Description}:
5330 @code{IBSET} returns the value of @var{I} with the bit at position
5331 @var{POS} set to one.
5333 @item @emph{Standard}:
5339 @item @emph{Syntax}:
5340 @code{RESULT = IBSET(I, POS)}
5342 @item @emph{Arguments}:
5343 @multitable @columnfractions .15 .70
5344 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5345 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
5348 @item @emph{Return value}:
5349 The return value is of type @code{INTEGER(*)} and of the same kind as
5352 @item @emph{See also}:
5353 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5360 @section @code{ICHAR} --- Character-to-integer conversion function
5362 @cindex conversion, to integer
5365 @item @emph{Description}:
5366 @code{ICHAR(C)} returns the code for the character in the first character
5367 position of @code{C} in the system's native character set.
5368 The correspondence between characters and their codes is not necessarily
5369 the same across different GNU Fortran implementations.
5371 @item @emph{Standard}:
5377 @item @emph{Syntax}:
5378 @code{RESULT = ICHAR(C [, KIND])}
5380 @item @emph{Arguments}:
5381 @multitable @columnfractions .15 .70
5382 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5383 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5384 expression indicating the kind parameter of
5388 @item @emph{Return value}:
5389 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5390 @var{KIND} is absent, the return value is of default integer kind.
5392 @item @emph{Example}:
5397 end program test_ichar
5401 No intrinsic exists to convert between a numeric value and a formatted
5402 character string representation -- for instance, given the
5403 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
5404 @code{REAL} value with the value 154, or vice versa. Instead, this
5405 functionality is provided by internal-file I/O, as in the following
5410 character(len=10) string, string2
5413 ! Convert a string to a numeric value
5414 read (string,'(I10)') value
5417 ! Convert a value to a formatted string
5418 write (string2,'(I10)') value
5420 end program read_val
5423 @item @emph{See also}:
5424 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
5431 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
5433 @cindex date, current
5434 @cindex current date
5437 @item @emph{Description}:
5438 @code{IDATE(TARRAY)} Fills @var{TARRAY} with the numerical values at the
5439 current local time. The day (in the range 1-31), month (in the range 1-12),
5440 and year appear in elements 1, 2, and 3 of @var{TARRAY}, respectively.
5441 The year has four significant digits.
5443 @item @emph{Standard}:
5449 @item @emph{Syntax}:
5450 @code{CALL IDATE(TARRAY)}
5452 @item @emph{Arguments}:
5453 @multitable @columnfractions .15 .70
5454 @item @var{TARRAY} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
5455 the kind shall be the default integer kind.
5458 @item @emph{Return value}:
5461 @item @emph{Example}:
5464 integer, dimension(3) :: tarray
5469 end program test_idate
5476 @section @code{IEOR} --- Bitwise logical exclusive or
5478 @cindex bitwise logical exclusive or
5479 @cindex logical exclusive or, bitwise
5482 @item @emph{Description}:
5483 @code{IEOR} returns the bitwise boolean exclusive-OR of @var{I} and
5486 @item @emph{Standard}:
5492 @item @emph{Syntax}:
5493 @code{RESULT = IEOR(I, J)}
5495 @item @emph{Arguments}:
5496 @multitable @columnfractions .15 .70
5497 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5498 @item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
5499 kind as @var{I}. (As a GNU extension, different kinds are also
5503 @item @emph{Return value}:
5504 The return type is @code{INTEGER(*)}, of the same kind as the
5505 arguments. (If the argument kinds differ, it is of the same kind as
5506 the larger argument.)
5508 @item @emph{See also}:
5509 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5515 @section @code{IERRNO} --- Get the last system error number
5517 @cindex system, error handling
5520 @item @emph{Description}:
5521 Returns the last system error number, as given by the C @code{errno()}
5524 @item @emph{Standard}:
5530 @item @emph{Syntax}:
5531 @code{RESULT = IERRNO()}
5533 @item @emph{Arguments}:
5536 @item @emph{Return value}:
5537 The return value is of type @code{INTEGER} and of the default integer
5540 @item @emph{See also}:
5547 @section @code{INDEX} --- Position of a substring within a string
5549 @cindex substring position
5550 @cindex string, find substring
5553 @item @emph{Description}:
5554 Returns the position of the start of the first occurrence of string
5555 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
5556 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
5557 the @var{BACK} argument is present and true, the return value is the
5558 start of the last occurrence rather than the first.
5560 @item @emph{Standard}:
5566 @item @emph{Syntax}:
5567 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
5569 @item @emph{Arguments}:
5570 @multitable @columnfractions .15 .70
5571 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER(*)}, with
5573 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER(*)}, with
5575 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL(*)}, with
5577 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5578 expression indicating the kind parameter of
5582 @item @emph{Return value}:
5583 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5584 @var{KIND} is absent, the return value is of default integer kind.
5586 @item @emph{See also}:
5587 @ref{SCAN}, @ref{VERIFY}
5593 @section @code{INT} --- Convert to integer type
5597 @cindex conversion, to integer
5600 @item @emph{Description}:
5601 Convert to integer type
5603 @item @emph{Standard}:
5609 @item @emph{Syntax}:
5610 @code{RESULT = INT(A [, KIND))}
5612 @item @emph{Arguments}:
5613 @multitable @columnfractions .15 .70
5614 @item @var{A} @tab Shall be of type @code{INTEGER(*)},
5615 @code{REAL(*)}, or @code{COMPLEX(*)}.
5616 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
5617 expression indicating the kind parameter of
5621 @item @emph{Return value}:
5622 These functions return a @code{INTEGER(*)} variable or array under
5623 the following rules:
5627 If @var{A} is of type @code{INTEGER(*)}, @code{INT(A) = A}
5629 If @var{A} is of type @code{REAL(*)} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
5630 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
5631 the range of @var{A} and whose sign is the same as the sign of @var{A}.
5633 If @var{A} is of type @code{COMPLEX(*)}, rule B is applied to the real part of @var{A}.
5636 @item @emph{Example}:
5640 complex :: z = (-3.7, 1.0)
5642 print *, int(z), int(z,8)
5646 @item @emph{Specific names}:
5647 @multitable @columnfractions .20 .20 .20 .25
5648 @item Name @tab Argument @tab Return type @tab Standard
5649 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab F77 and later
5650 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab F77 and later
5658 @section @code{INT2} --- Convert to 16-bit integer type
5661 @cindex conversion, to integer
5664 @item @emph{Description}:
5665 Convert to a @code{KIND=2} integer type. This is equivalent to the
5666 standard @code{INT} intrinsic with an optional argument of
5667 @code{KIND=2}, and is only included for backwards compatibility.
5669 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
5671 @item @emph{Standard}:
5677 @item @emph{Syntax}:
5678 @code{RESULT = INT2(A)}
5680 @item @emph{Arguments}:
5681 @multitable @columnfractions .15 .70
5682 @item @var{A} @tab Shall be of type @code{INTEGER(*)},
5683 @code{REAL(*)}, or @code{COMPLEX(*)}.
5686 @item @emph{Return value}:
5687 The return value is a @code{INTEGER(2)} variable.
5689 @item @emph{See also}:
5690 @ref{INT}, @ref{INT8}, @ref{LONG}
5696 @section @code{INT8} --- Convert to 64-bit integer type
5698 @cindex conversion, to integer
5701 @item @emph{Description}:
5702 Convert to a @code{KIND=8} integer type. This is equivalent to the
5703 standard @code{INT} intrinsic with an optional argument of
5704 @code{KIND=8}, and is only included for backwards compatibility.
5706 @item @emph{Standard}:
5712 @item @emph{Syntax}:
5713 @code{RESULT = INT8(A)}
5715 @item @emph{Arguments}:
5716 @multitable @columnfractions .15 .70
5717 @item @var{A} @tab Shall be of type @code{INTEGER(*)},
5718 @code{REAL(*)}, or @code{COMPLEX(*)}.
5721 @item @emph{Return value}:
5722 The return value is a @code{INTEGER(8)} variable.
5724 @item @emph{See also}:
5725 @ref{INT}, @ref{INT2}, @ref{LONG}
5731 @section @code{IOR} --- Bitwise logical or
5733 @cindex bitwise logical or
5734 @cindex logical or, bitwise
5737 @item @emph{Description}:
5738 @code{IEOR} returns the bitwise boolean OR of @var{I} and
5741 @item @emph{Standard}:
5747 @item @emph{Syntax}:
5748 @code{RESULT = IEOR(I, J)}
5750 @item @emph{Arguments}:
5751 @multitable @columnfractions .15 .70
5752 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5753 @item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
5754 kind as @var{I}. (As a GNU extension, different kinds are also
5758 @item @emph{Return value}:
5759 The return type is @code{INTEGER(*)}, of the same kind as the
5760 arguments. (If the argument kinds differ, it is of the same kind as
5761 the larger argument.)
5763 @item @emph{See also}:
5764 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5770 @section @code{IRAND} --- Integer pseudo-random number
5772 @cindex random number generation
5775 @item @emph{Description}:
5776 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
5777 distribution between 0 and a system-dependent limit (which is in most
5778 cases 2147483647). If @var{FLAG} is 0, the next number
5779 in the current sequence is returned; if @var{FLAG} is 1, the generator
5780 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
5781 it is used as a new seed with @code{SRAND}.
5783 This intrinsic routine is provided for backwards compatibility with
5784 GNU Fortran 77. It implements a simple modulo generator as provided
5785 by @command{g77}. For new code, one should consider the use of
5786 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
5788 @item @emph{Standard}:
5794 @item @emph{Syntax}:
5795 @code{RESULT = IRAND(FLAG)}
5797 @item @emph{Arguments}:
5798 @multitable @columnfractions .15 .70
5799 @item @var{FLAG} @tab Shall be a scalar @code{INTEGER} of kind 4.
5802 @item @emph{Return value}:
5803 The return value is of @code{INTEGER(kind=4)} type.
5805 @item @emph{Example}:
5808 integer,parameter :: seed = 86456
5811 print *, irand(), irand(), irand(), irand()
5812 print *, irand(seed), irand(), irand(), irand()
5813 end program test_irand
5821 @section @code{ISATTY} --- Whether a unit is a terminal device.
5823 @cindex system, terminal
5826 @item @emph{Description}:
5827 Determine whether a unit is connected to a terminal device.
5829 @item @emph{Standard}:
5835 @item @emph{Syntax}:
5836 @code{RESULT = ISATTY(UNIT)}
5838 @item @emph{Arguments}:
5839 @multitable @columnfractions .15 .70
5840 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER(*)}.
5843 @item @emph{Return value}:
5844 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
5845 device, @code{.FALSE.} otherwise.
5847 @item @emph{Example}:
5850 INTEGER(kind=1) :: unit
5852 write(*,*) isatty(unit=unit)
5856 @item @emph{See also}:
5863 @section @code{ISHFT} --- Shift bits
5868 @item @emph{Description}:
5869 @code{ISHFT} returns a value corresponding to @var{I} with all of the
5870 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
5871 zero corresponds to a left shift, a value of zero corresponds to no
5872 shift, and a value less than zero corresponds to a right shift. If the
5873 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
5874 value is undefined. Bits shifted out from the left end or right end are
5875 lost; zeros are shifted in from the opposite end.
5877 @item @emph{Standard}:
5883 @item @emph{Syntax}:
5884 @code{RESULT = ISHFT(I, SHIFT)}
5886 @item @emph{Arguments}:
5887 @multitable @columnfractions .15 .70
5888 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5889 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
5892 @item @emph{Return value}:
5893 The return value is of type @code{INTEGER(*)} and of the same kind as
5896 @item @emph{See also}:
5903 @section @code{ISHFTC} --- Shift bits circularly
5905 @cindex bits, shift circular
5908 @item @emph{Description}:
5909 @code{ISHFTC} returns a value corresponding to @var{I} with the
5910 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
5911 is, bits shifted out one end are shifted into the opposite end. A value
5912 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
5913 zero corresponds to no shift, and a value less than zero corresponds to
5914 a right shift. The absolute value of @var{SHIFT} must be less than
5915 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
5916 equivalent to @code{BIT_SIZE(I)}.
5918 @item @emph{Standard}:
5924 @item @emph{Syntax}:
5925 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
5927 @item @emph{Arguments}:
5928 @multitable @columnfractions .15 .70
5929 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5930 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
5931 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER(*)};
5932 the value must be greater than zero and less than or equal to
5936 @item @emph{Return value}:
5937 The return value is of type @code{INTEGER(*)} and of the same kind as
5940 @item @emph{See also}:
5947 @section @code{ISNAN} --- Test for a NaN
5952 @item @emph{Description}:
5953 @code{ISNAN} tests whether a floating-point value is an IEEE
5955 @item @emph{Standard}:
5961 @item @emph{Syntax}:
5964 @item @emph{Arguments}:
5965 @multitable @columnfractions .15 .70
5966 @item @var{X} @tab Variable of the type @code{REAL}.
5970 @item @emph{Return value}:
5971 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
5972 if @var{X} is a NaN and @code{FALSE} otherwise.
5974 @item @emph{Example}:
5981 if (isnan(x)) stop '"x" is a NaN'
5982 end program test_nan
5989 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
5991 @cindex time, current
5992 @cindex current time
5995 @item @emph{Description}:
5996 @code{IDATE(TARRAY)} Fills @var{TARRAY} with the numerical values at the
5997 current local time. The hour (in the range 1-24), minute (in the range 1-60),
5998 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{TARRAY},
6001 @item @emph{Standard}:
6007 @item @emph{Syntax}:
6008 @code{CALL ITIME(TARRAY)}
6010 @item @emph{Arguments}:
6011 @multitable @columnfractions .15 .70
6012 @item @var{TARRAY} @tab The type shall be @code{INTEGER, DIMENSION(3)}
6013 and the kind shall be the default integer kind.
6016 @item @emph{Return value}:
6020 @item @emph{Example}:
6023 integer, dimension(3) :: tarray
6028 end program test_itime
6035 @section @code{KILL} --- Send a signal to a process
6039 @item @emph{Description}:
6040 @item @emph{Standard}:
6041 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
6044 This intrinsic is provided in both subroutine and function forms; however,
6045 only one form can be used in any given program unit.
6048 Subroutine, function
6050 @item @emph{Syntax}:
6051 @code{CALL KILL(PID, SIGNAL [, STATUS])}
6053 @item @emph{Arguments}:
6054 @multitable @columnfractions .15 .70
6055 @item @var{PID} @tab Shall be a scalar @code{INTEGER}, with
6057 @item @var{SIGNAL} @tab Shall be a scalar @code{INTEGER}, with
6059 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
6060 @code{INTEGER(8)}. Returns 0 on success, or a
6061 system-specific error code otherwise.
6064 @item @emph{See also}:
6065 @ref{ABORT}, @ref{EXIT}
6071 @section @code{KIND} --- Kind of an entity
6076 @item @emph{Description}:
6077 @code{KIND(X)} returns the kind value of the entity @var{X}.
6079 @item @emph{Standard}:
6085 @item @emph{Syntax}:
6088 @item @emph{Arguments}:
6089 @multitable @columnfractions .15 .70
6090 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
6091 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
6094 @item @emph{Return value}:
6095 The return value is a scalar of type @code{INTEGER} and of the default
6098 @item @emph{Example}:
6101 integer,parameter :: kc = kind(' ')
6102 integer,parameter :: kl = kind(.true.)
6104 print *, "The default character kind is ", kc
6105 print *, "The default logical kind is ", kl
6106 end program test_kind
6114 @section @code{LBOUND} --- Lower dimension bounds of an array
6116 @cindex array, lower bound
6119 @item @emph{Description}:
6120 Returns the lower bounds of an array, or a single lower bound
6121 along the @var{DIM} dimension.
6122 @item @emph{Standard}:
6128 @item @emph{Syntax}:
6129 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
6131 @item @emph{Arguments}:
6132 @multitable @columnfractions .15 .70
6133 @item @var{ARRAY} @tab Shall be an array, of any type.
6134 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER(*)}.
6135 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6136 expression indicating the kind parameter of
6140 @item @emph{Return value}:
6141 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6142 @var{KIND} is absent, the return value is of default integer kind.
6143 If @var{DIM} is absent, the result is an array of the lower bounds of
6144 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
6145 corresponding to the lower bound of the array along that dimension. If
6146 @var{ARRAY} is an expression rather than a whole array or array
6147 structure component, or if it has a zero extent along the relevant
6148 dimension, the lower bound is taken to be 1.
6150 @item @emph{See also}:
6157 @section @code{LEN} --- Length of a character entity
6159 @cindex string, length
6162 @item @emph{Description}:
6163 Returns the length of a character string. If @var{STRING} is an array,
6164 the length of an element of @var{STRING} is returned. Note that
6165 @var{STRING} need not be defined when this intrinsic is invoked, since
6166 only the length, not the content, of @var{STRING} is needed.
6168 @item @emph{Standard}:
6174 @item @emph{Syntax}:
6175 @code{L = LEN(STRING [, KIND])}
6177 @item @emph{Arguments}:
6178 @multitable @columnfractions .15 .70
6179 @item @var{STRING} @tab Shall be a scalar or array of type
6180 @code{CHARACTER(*)}, with @code{INTENT(IN)}
6181 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6182 expression indicating the kind parameter of
6186 @item @emph{Return value}:
6187 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6188 @var{KIND} is absent, the return value is of default integer kind.
6190 @item @emph{See also}:
6191 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
6197 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
6199 @cindex string, length, without trailing whitespace
6202 @item @emph{Description}:
6203 Returns the length of a character string, ignoring any trailing blanks.
6205 @item @emph{Standard}:
6211 @item @emph{Syntax}:
6212 @code{RESULT = LEN_TRIM(STRING [, KIND])}
6214 @item @emph{Arguments}:
6215 @multitable @columnfractions .15 .70
6216 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)},
6217 with @code{INTENT(IN)}
6218 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6219 expression indicating the kind parameter of
6223 @item @emph{Return value}:
6224 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6225 @var{KIND} is absent, the return value is of default integer kind.
6227 @item @emph{See also}:
6228 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
6234 @section @code{LGE} --- Lexical greater than or equal
6236 @cindex lexical comparison of strings
6237 @cindex string, comparison
6240 @item @emph{Description}:
6241 Determines whether one string is lexically greater than or equal to
6242 another string, where the two strings are interpreted as containing
6243 ASCII character codes. If the String A and String B are not the same
6244 length, the shorter is compared as if spaces were appended to it to form
6245 a value that has the same length as the longer.
6247 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6248 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6249 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6250 that the latter use the processor's character ordering (which is not
6251 ASCII on some targets), whereas the former always use the ASCII
6254 @item @emph{Standard}:
6260 @item @emph{Syntax}:
6261 @code{RESULT = LGE(STRING_A, STRING_B)}
6263 @item @emph{Arguments}:
6264 @multitable @columnfractions .15 .70
6265 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6266 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6269 @item @emph{Return value}:
6270 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
6271 otherwise, based on the ASCII ordering.
6273 @item @emph{See also}:
6274 @ref{LGT}, @ref{LLE}, @ref{LLT}
6280 @section @code{LGT} --- Lexical greater than
6282 @cindex lexical comparison of strings
6283 @cindex string, comparison
6286 @item @emph{Description}:
6287 Determines whether one string is lexically greater than another string,
6288 where the two strings are interpreted as containing ASCII character
6289 codes. If the String A and String B are not the same length, the
6290 shorter is compared as if spaces were appended to it to form a value
6291 that has the same length as the longer.
6293 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6294 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6295 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6296 that the latter use the processor's character ordering (which is not
6297 ASCII on some targets), whereas the former always use the ASCII
6300 @item @emph{Standard}:
6306 @item @emph{Syntax}:
6307 @code{RESULT = LGT(STRING_A, STRING_B)}
6309 @item @emph{Arguments}:
6310 @multitable @columnfractions .15 .70
6311 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6312 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6315 @item @emph{Return value}:
6316 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
6317 otherwise, based on the ASCII ordering.
6319 @item @emph{See also}:
6320 @ref{LGE}, @ref{LLE}, @ref{LLT}
6326 @section @code{LINK} --- Create a hard link
6328 @cindex file system, create link
6329 @cindex file system, hard link
6332 @item @emph{Description}:
6333 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
6334 character (@code{CHAR(0)}) can be used to mark the end of the names in
6335 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
6336 names are ignored. If the @var{STATUS} argument is supplied, it
6337 contains 0 on success or a nonzero error code upon return; see
6340 This intrinsic is provided in both subroutine and function forms;
6341 however, only one form can be used in any given program unit.
6343 @item @emph{Standard}:
6347 Subroutine, function
6349 @item @emph{Syntax}:
6350 @multitable @columnfractions .80
6351 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
6352 @item @code{STATUS = LINK(PATH1, PATH2)}
6355 @item @emph{Arguments}:
6356 @multitable @columnfractions .15 .70
6357 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
6358 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
6359 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
6362 @item @emph{See also}:
6363 @ref{SYMLNK}, @ref{UNLINK}
6369 @section @code{LLE} --- Lexical less than or equal
6371 @cindex lexical comparison of strings
6372 @cindex string, comparison
6375 @item @emph{Description}:
6376 Determines whether one string is lexically less than or equal to another
6377 string, where the two strings are interpreted as containing ASCII
6378 character codes. If the String A and String B are not the same length,
6379 the shorter is compared as if spaces were appended to it to form a value
6380 that has the same length as the longer.
6382 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6383 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6384 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6385 that the latter use the processor's character ordering (which is not
6386 ASCII on some targets), whereas the former always use the ASCII
6389 @item @emph{Standard}:
6395 @item @emph{Syntax}:
6396 @code{RESULT = LLE(STRING_A, STRING_B)}
6398 @item @emph{Arguments}:
6399 @multitable @columnfractions .15 .70
6400 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6401 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6404 @item @emph{Return value}:
6405 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
6406 otherwise, based on the ASCII ordering.
6408 @item @emph{See also}:
6409 @ref{LGE}, @ref{LGT}, @ref{LLT}
6415 @section @code{LLT} --- Lexical less than
6417 @cindex lexical comparison of strings
6418 @cindex string, comparison
6421 @item @emph{Description}:
6422 Determines whether one string is lexically less than another string,
6423 where the two strings are interpreted as containing ASCII character
6424 codes. If the String A and String B are not the same length, the
6425 shorter is compared as if spaces were appended to it to form a value
6426 that has the same length as the longer.
6428 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6429 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6430 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6431 that the latter use the processor's character ordering (which is not
6432 ASCII on some targets), whereas the former always use the ASCII
6435 @item @emph{Standard}:
6441 @item @emph{Syntax}:
6442 @code{RESULT = LLT(STRING_A, STRING_B)}
6444 @item @emph{Arguments}:
6445 @multitable @columnfractions .15 .70
6446 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6447 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6450 @item @emph{Return value}:
6451 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
6452 otherwise, based on the ASCII ordering.
6454 @item @emph{See also}:
6455 @ref{LGE}, @ref{LGT}, @ref{LLE}
6461 @section @code{LNBLNK} --- Index of the last non-blank character in a string
6463 @cindex string, find non-blank character
6466 @item @emph{Description}:
6467 Returns the length of a character string, ignoring any trailing blanks.
6468 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
6469 included for backwards compatibility.
6471 @item @emph{Standard}:
6477 @item @emph{Syntax}:
6478 @code{RESULT = LNBLNK(STRING)}
6480 @item @emph{Arguments}:
6481 @multitable @columnfractions .15 .70
6482 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)},
6483 with @code{INTENT(IN)}
6486 @item @emph{Return value}:
6487 The return value is of @code{INTEGER(kind=4)} type.
6489 @item @emph{See also}:
6490 @ref{INDEX}, @ref{LEN_TRIM}
6496 @section @code{LOC} --- Returns the address of a variable
6498 @cindex location of a variable in memory
6501 @item @emph{Description}:
6502 @code{LOC(X)} returns the address of @var{X} as an integer.
6504 @item @emph{Standard}:
6510 @item @emph{Syntax}:
6511 @code{RESULT = LOC(X)}
6513 @item @emph{Arguments}:
6514 @multitable @columnfractions .15 .70
6515 @item @var{X} @tab Variable of any type.
6518 @item @emph{Return value}:
6519 The return value is of type @code{INTEGER}, with a @code{KIND}
6520 corresponding to the size (in bytes) of a memory address on the target
6523 @item @emph{Example}:
6530 end program test_loc
6537 @section @code{LOG} --- Logarithm function
6544 @cindex exponential function, inverse
6545 @cindex logarithmic function
6548 @item @emph{Description}:
6549 @code{LOG(X)} computes the logarithm of @var{X}.
6551 @item @emph{Standard}:
6557 @item @emph{Syntax}:
6558 @code{RESULT = LOG(X)}
6560 @item @emph{Arguments}:
6561 @multitable @columnfractions .15 .70
6562 @item @var{X} @tab The type shall be @code{REAL(*)} or
6566 @item @emph{Return value}:
6567 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
6568 The kind type parameter is the same as @var{X}.
6570 @item @emph{Example}:
6573 real(8) :: x = 1.0_8
6574 complex :: z = (1.0, 2.0)
6577 end program test_log
6580 @item @emph{Specific names}:
6581 @multitable @columnfractions .20 .20 .20 .25
6582 @item Name @tab Argument @tab Return type @tab Standard
6583 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
6584 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
6585 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
6586 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
6587 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
6594 @section @code{LOG10} --- Base 10 logarithm function
6598 @cindex exponential function, inverse
6599 @cindex logarithmic function
6602 @item @emph{Description}:
6603 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
6605 @item @emph{Standard}:
6611 @item @emph{Syntax}:
6612 @code{RESULT = LOG10(X)}
6614 @item @emph{Arguments}:
6615 @multitable @columnfractions .15 .70
6616 @item @var{X} @tab The type shall be @code{REAL(*)}.
6619 @item @emph{Return value}:
6620 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
6621 The kind type parameter is the same as @var{X}.
6623 @item @emph{Example}:
6626 real(8) :: x = 10.0_8
6628 end program test_log10
6631 @item @emph{Specific names}:
6632 @multitable @columnfractions .20 .20 .20 .25
6633 @item Name @tab Argument @tab Return type @tab Standard
6634 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab F95 and later
6635 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
6642 @section @code{LOGICAL} --- Convert to logical type
6644 @cindex conversion, to logical
6647 @item @emph{Description}:
6648 Converts one kind of @code{LOGICAL} variable to another.
6650 @item @emph{Standard}:
6656 @item @emph{Syntax}:
6657 @code{RESULT = LOGICAL(L [, KIND])}
6659 @item @emph{Arguments}:
6660 @multitable @columnfractions .15 .70
6661 @item @var{L} @tab The type shall be @code{LOGICAL(*)}.
6662 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
6663 expression indicating the kind parameter of
6667 @item @emph{Return value}:
6668 The return value is a @code{LOGICAL} value equal to @var{L}, with a
6669 kind corresponding to @var{KIND}, or of the default logical kind if
6670 @var{KIND} is not given.
6672 @item @emph{See also}:
6673 @ref{INT}, @ref{REAL}, @ref{CMPLX}
6679 @section @code{LONG} --- Convert to integer type
6681 @cindex conversion, to integer
6684 @item @emph{Description}:
6685 Convert to a @code{KIND=4} integer type, which is the same size as a C
6686 @code{long} integer. This is equivalent to the standard @code{INT}
6687 intrinsic with an optional argument of @code{KIND=4}, and is only
6688 included for backwards compatibility.
6690 @item @emph{Standard}:
6696 @item @emph{Syntax}:
6697 @code{RESULT = LONG(A)}
6699 @item @emph{Arguments}:
6700 @multitable @columnfractions .15 .70
6701 @item @var{A} @tab Shall be of type @code{INTEGER(*)},
6702 @code{REAL(*)}, or @code{COMPLEX(*)}.
6705 @item @emph{Return value}:
6706 The return value is a @code{INTEGER(4)} variable.
6708 @item @emph{See also}:
6709 @ref{INT}, @ref{INT2}, @ref{INT8}
6715 @section @code{LSHIFT} --- Left shift bits
6717 @cindex bits, shift left
6720 @item @emph{Description}:
6721 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
6722 bits shifted left by @var{SHIFT} places. If the absolute value of
6723 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
6724 Bits shifted out from the left end are lost; zeros are shifted in from
6727 This function has been superseded by the @code{ISHFT} intrinsic, which
6728 is standard in Fortran 95 and later.
6730 @item @emph{Standard}:
6736 @item @emph{Syntax}:
6737 @code{RESULT = LSHIFT(I, SHIFT)}
6739 @item @emph{Arguments}:
6740 @multitable @columnfractions .15 .70
6741 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
6742 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
6745 @item @emph{Return value}:
6746 The return value is of type @code{INTEGER(*)} and of the same kind as
6749 @item @emph{See also}:
6750 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}
6757 @section @code{LSTAT} --- Get file status
6759 @cindex file system, file status
6762 @item @emph{Description}:
6763 @code{LSTAT} is identical to @ref{STAT}, except that if path is a symbolic link,
6764 then the link itself is statted, not the file that it refers to.
6766 The elements in @code{BUFF} are the same as described by @ref{STAT}.
6768 This intrinsic is provided in both subroutine and function forms; however,
6769 only one form can be used in any given program unit.
6771 @item @emph{Standard}:
6775 Subroutine, function
6777 @item @emph{Syntax}:
6778 @code{CALL LSTAT(FILE, BUFF [, STATUS])}
6780 @item @emph{Arguments}:
6781 @multitable @columnfractions .15 .70
6782 @item @var{FILE} @tab The type shall be @code{CHARACTER(*)}, a valid path within the file system.
6783 @item @var{BUFF} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
6784 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
6785 on success and a system specific error code otherwise.
6788 @item @emph{Example}:
6789 See @ref{STAT} for an example.
6791 @item @emph{See also}:
6792 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
6798 @section @code{LTIME} --- Convert time to local time info
6800 @cindex time, conversion to local time info
6803 @item @emph{Description}:
6804 Given a system time value @var{STIME} (as provided by the @code{TIME8()}
6805 intrinsic), fills @var{TARRAY} with values extracted from it appropriate
6806 to the local time zone using @code{localtime(3)}.
6808 @item @emph{Standard}:
6814 @item @emph{Syntax}:
6815 @code{CALL LTIME(STIME, TARRAY)}
6817 @item @emph{Arguments}:
6818 @multitable @columnfractions .15 .70
6819 @item @var{STIME} @tab An @code{INTEGER(*)} scalar expression
6820 corresponding to a system time, with
6822 @item @var{TARRAY} @tab A default @code{INTEGER} array with 9 elements,
6823 with @code{INTENT(OUT)}.
6826 @item @emph{Return value}:
6827 The elements of @var{TARRAY} are assigned as follows:
6829 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
6831 @item Minutes after the hour, range 0--59
6832 @item Hours past midnight, range 0--23
6833 @item Day of month, range 0--31
6834 @item Number of months since January, range 0--12
6835 @item Years since 1900
6836 @item Number of days since Sunday, range 0--6
6837 @item Days since January 1
6838 @item Daylight savings indicator: positive if daylight savings is in
6839 effect, zero if not, and negative if the information is not
6843 @item @emph{See also}:
6844 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
6851 @section @code{MALLOC} --- Allocate dynamic memory
6853 @cindex pointer, cray
6856 @item @emph{Description}:
6857 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
6858 returns the address of the allocated memory. The @code{MALLOC} intrinsic
6859 is an extension intended to be used with Cray pointers, and is provided
6860 in GNU Fortran to allow the user to compile legacy code. For new code
6861 using Fortran 95 pointers, the memory allocation intrinsic is
6864 @item @emph{Standard}:
6870 @item @emph{Syntax}:
6871 @code{PTR = MALLOC(SIZE)}
6873 @item @emph{Arguments}:
6874 @multitable @columnfractions .15 .70
6875 @item @var{SIZE} @tab The type shall be @code{INTEGER(*)}.
6878 @item @emph{Return value}:
6879 The return value is of type @code{INTEGER(K)}, with @var{K} such that
6880 variables of type @code{INTEGER(K)} have the same size as
6881 C pointers (@code{sizeof(void *)}).
6883 @item @emph{Example}:
6884 The following example demonstrates the use of @code{MALLOC} and
6885 @code{FREE} with Cray pointers. This example is intended to run on
6886 32-bit systems, where the default integer kind is suitable to store
6887 pointers; on 64-bit systems, ptr_x would need to be declared as
6888 @code{integer(kind=8)}.
6897 ptr_x = malloc(20*8)
6899 x(i) = sqrt(1.0d0 / i)
6907 end program test_malloc
6910 @item @emph{See also}:
6917 @section @code{MATMUL} --- matrix multiplication
6919 @cindex matrix multiplication
6920 @cindex product, matrix
6923 @item @emph{Description}:
6924 Performs a matrix multiplication on numeric or logical arguments.
6926 @item @emph{Standard}:
6930 Transformational function
6932 @item @emph{Syntax}:
6933 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
6935 @item @emph{Arguments}:
6936 @multitable @columnfractions .15 .70
6937 @item @var{MATRIX_A} @tab An array of @code{INTEGER(*)},
6938 @code{REAL(*)}, @code{COMPLEX(*)}, or
6939 @code{LOGICAL(*)} type, with a rank of
6941 @item @var{MATRIX_B} @tab An array of @code{INTEGER(*)},
6942 @code{REAL(*)}, or @code{COMPLEX(*)} type if
6943 @var{MATRIX_A} is of a numeric type;
6944 otherwise, an array of @code{LOGICAL(*)}
6945 type. The rank shall be one or two, and the
6946 first (or only) dimension of @var{MATRIX_B}
6947 shall be equal to the last (or only)
6948 dimension of @var{MATRIX_A}.
6951 @item @emph{Return value}:
6952 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
6953 kind of the result follow the usual type and kind promotion rules, as
6954 for the @code{*} or @code{.AND.} operators.
6956 @item @emph{See also}:
6962 @section @code{MAX} --- Maximum value of an argument list
6969 @cindex maximum value
6972 @item @emph{Description}:
6973 Returns the argument with the largest (most positive) value.
6975 @item @emph{Standard}:
6981 @item @emph{Syntax}:
6982 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
6984 @item @emph{Arguments}:
6985 @multitable @columnfractions .15 .70
6986 @item @var{A1} @tab The type shall be @code{INTEGER(*)} or
6988 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
6989 as @var{A1}. (As a GNU extension,
6990 arguments of different kinds are
6994 @item @emph{Return value}:
6995 The return value corresponds to the maximum value among the arguments,
6996 and has the same type and kind as the first argument.
6998 @item @emph{Specific names}:
6999 @multitable @columnfractions .20 .20 .20 .25
7000 @item Name @tab Argument @tab Return type @tab Standard
7001 @item @code{MAX0(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab F77 and later
7002 @item @code{AMAX0(I)} @tab @code{INTEGER(4) I} @tab @code{REAL(MAX(X))} @tab F77 and later
7003 @item @code{MAX1(X)} @tab @code{REAL(*) X} @tab @code{INT(MAX(X))} @tab F77 and later
7004 @item @code{AMAX1(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab F77 and later
7005 @item @code{DMAX1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
7008 @item @emph{See also}:
7009 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
7016 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
7017 @fnindex MAXEXPONENT
7018 @cindex model representation, maximum exponent
7021 @item @emph{Description}:
7022 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
7025 @item @emph{Standard}:
7031 @item @emph{Syntax}:
7032 @code{RESULT = MAXEXPONENT(X)}
7034 @item @emph{Arguments}:
7035 @multitable @columnfractions .15 .70
7036 @item @var{X} @tab Shall be of type @code{REAL}.
7039 @item @emph{Return value}:
7040 The return value is of type @code{INTEGER} and of the default integer
7043 @item @emph{Example}:
7049 print *, minexponent(x), maxexponent(x)
7050 print *, minexponent(y), maxexponent(y)
7051 end program exponents
7058 @section @code{MAXLOC} --- Location of the maximum value within an array
7060 @cindex array, location of maximum element
7063 @item @emph{Description}:
7064 Determines the location of the element in the array with the maximum
7065 value, or, if the @var{DIM} argument is supplied, determines the
7066 locations of the maximum element along each row of the array in the
7067 @var{DIM} direction. If @var{MASK} is present, only the elements for
7068 which @var{MASK} is @code{.TRUE.} are considered. If more than one
7069 element in the array has the maximum value, the location returned is
7070 that of the first such element in array element order. If the array has
7071 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7072 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
7073 and all of the elements of @var{MASK} along a given row are zero, the
7074 result value for that row is zero.
7076 @item @emph{Standard}:
7080 Transformational function
7082 @item @emph{Syntax}:
7083 @multitable @columnfractions .80
7084 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
7085 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
7088 @item @emph{Arguments}:
7089 @multitable @columnfractions .15 .70
7090 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7091 @code{REAL(*)}, or @code{CHARACTER(*)}.
7092 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7093 @code{INTEGER(*)}, with a value between one
7094 and the rank of @var{ARRAY}, inclusive. It
7095 may not be an optional dummy argument.
7096 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL(*)},
7097 and conformable with @var{ARRAY}.
7100 @item @emph{Return value}:
7101 If @var{DIM} is absent, the result is a rank-one array with a length
7102 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
7103 is an array with a rank one less than the rank of @var{ARRAY}, and a
7104 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7105 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
7106 of one, the result is a scalar. In all cases, the result is of default
7107 @code{INTEGER} type.
7109 @item @emph{See also}:
7110 @ref{MAX}, @ref{MAXVAL}
7117 @section @code{MAXVAL} --- Maximum value of an array
7119 @cindex array, maximum value
7120 @cindex maximum value
7123 @item @emph{Description}:
7124 Determines the maximum value of the elements in an array value, or, if
7125 the @var{DIM} argument is supplied, determines the maximum value along
7126 each row of the array in the @var{DIM} direction. If @var{MASK} is
7127 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7128 considered. If the array has zero size, or all of the elements of
7129 @var{MASK} are @code{.FALSE.}, then the result is the most negative
7130 number of the type and kind of @var{ARRAY} if @var{ARRAY} is numeric, or
7131 a string of nulls if @var{ARRAY} is of character type.
7133 @item @emph{Standard}:
7137 Transformational function
7139 @item @emph{Syntax}:
7140 @multitable @columnfractions .80
7141 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
7142 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
7145 @item @emph{Arguments}:
7146 @multitable @columnfractions .15 .70
7147 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7148 @code{REAL(*)}, or @code{CHARACTER(*)}.
7149 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7150 @code{INTEGER(*)}, with a value between one
7151 and the rank of @var{ARRAY}, inclusive. It
7152 may not be an optional dummy argument.
7153 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL(*)},
7154 and conformable with @var{ARRAY}.
7157 @item @emph{Return value}:
7158 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7159 is a scalar. If @var{DIM} is present, the result is an array with a
7160 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7161 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
7162 cases, the result is of the same type and kind as @var{ARRAY}.
7164 @item @emph{See also}:
7165 @ref{MAX}, @ref{MAXLOC}
7171 @section @code{MCLOCK} --- Time function
7173 @cindex time, clock ticks
7177 @item @emph{Description}:
7178 Returns the number of clock ticks since the start of the process, based
7179 on the UNIX function @code{clock(3)}.
7181 This intrinsic is not fully portable, such as to systems with 32-bit
7182 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
7183 the values returned by this intrinsic might be, or become, negative, or
7184 numerically less than previous values, during a single run of the
7187 @item @emph{Standard}:
7193 @item @emph{Syntax}:
7194 @code{RESULT = MCLOCK()}
7196 @item @emph{Return value}:
7197 The return value is a scalar of type @code{INTEGER(4)}, equal to the
7198 number of clock ticks since the start of the process, or @code{-1} if
7199 the system does not support @code{clock(3)}.
7201 @item @emph{See also}:
7202 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
7209 @section @code{MCLOCK8} --- Time function (64-bit)
7211 @cindex time, clock ticks
7215 @item @emph{Description}:
7216 Returns the number of clock ticks since the start of the process, based
7217 on the UNIX function @code{clock(3)}.
7219 @emph{Warning:} this intrinsic does not increase the range of the timing
7220 values over that returned by @code{clock(3)}. On a system with a 32-bit
7221 @code{clock(3)}, @code{MCLOCK8()} will return a 32-bit value, even though
7222 it is converted to a 64-bit @code{INTEGER(8)} value. That means
7223 overflows of the 32-bit value can still occur. Therefore, the values
7224 returned by this intrinsic might be or become negative or numerically
7225 less than previous values during a single run of the compiled program.
7227 @item @emph{Standard}:
7233 @item @emph{Syntax}:
7234 @code{RESULT = MCLOCK8()}
7236 @item @emph{Return value}:
7237 The return value is a scalar of type @code{INTEGER(8)}, equal to the
7238 number of clock ticks since the start of the process, or @code{-1} if
7239 the system does not support @code{clock(3)}.
7241 @item @emph{See also}:
7242 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
7249 @section @code{MERGE} --- Merge variables
7251 @cindex array, merge arrays
7252 @cindex array, combine arrays
7255 @item @emph{Description}:
7256 Select values from two arrays according to a logical mask. The result
7257 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
7258 @var{FSOURCE} if it is @code{.FALSE.}.
7260 @item @emph{Standard}:
7266 @item @emph{Syntax}:
7267 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
7269 @item @emph{Arguments}:
7270 @multitable @columnfractions .15 .70
7271 @item @var{TSOURCE} @tab May be of any type.
7272 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
7274 @item @var{MASK} @tab Shall be of type @code{LOGICAL(*)}.
7277 @item @emph{Return value}:
7278 The result is of the same type and type parameters as @var{TSOURCE}.
7285 @section @code{MIN} --- Minimum value of an argument list
7292 @cindex minimum value
7295 @item @emph{Description}:
7296 Returns the argument with the smallest (most negative) value.
7298 @item @emph{Standard}:
7304 @item @emph{Syntax}:
7305 @code{RESULT = MIN(A1, A2 [, A3, ...])}
7307 @item @emph{Arguments}:
7308 @multitable @columnfractions .15 .70
7309 @item @var{A1} @tab The type shall be @code{INTEGER(*)} or
7311 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7312 as @var{A1}. (As a GNU extension,
7313 arguments of different kinds are
7317 @item @emph{Return value}:
7318 The return value corresponds to the maximum value among the arguments,
7319 and has the same type and kind as the first argument.
7321 @item @emph{Specific names}:
7322 @multitable @columnfractions .20 .20 .20 .25
7323 @item Name @tab Argument @tab Return type @tab Standard
7324 @item @code{MIN0(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab F77 and later
7325 @item @code{AMIN0(I)} @tab @code{INTEGER(4) I} @tab @code{REAL(MIN(X))} @tab F77 and later
7326 @item @code{MIN1(X)} @tab @code{REAL(*) X} @tab @code{INT(MIN(X))} @tab F77 and later
7327 @item @code{AMIN1(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab F77 and later
7328 @item @code{DMIN1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
7331 @item @emph{See also}:
7332 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
7338 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
7339 @fnindex MINEXPONENT
7340 @cindex model representation, minimum exponent
7343 @item @emph{Description}:
7344 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
7347 @item @emph{Standard}:
7353 @item @emph{Syntax}:
7354 @code{RESULT = MINEXPONENT(X)}
7356 @item @emph{Arguments}:
7357 @multitable @columnfractions .15 .70
7358 @item @var{X} @tab Shall be of type @code{REAL}.
7361 @item @emph{Return value}:
7362 The return value is of type @code{INTEGER} and of the default integer
7365 @item @emph{Example}:
7366 See @code{MAXEXPONENT} for an example.
7372 @section @code{MINLOC} --- Location of the minimum value within an array
7374 @cindex array, location of minimum element
7377 @item @emph{Description}:
7378 Determines the location of the element in the array with the minimum
7379 value, or, if the @var{DIM} argument is supplied, determines the
7380 locations of the minimum element along each row of the array in the
7381 @var{DIM} direction. If @var{MASK} is present, only the elements for
7382 which @var{MASK} is @code{.TRUE.} are considered. If more than one
7383 element in the array has the minimum value, the location returned is
7384 that of the first such element in array element order. If the array has
7385 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7386 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
7387 and all of the elements of @var{MASK} along a given row are zero, the
7388 result value for that row is zero.
7390 @item @emph{Standard}:
7394 Transformational function
7396 @item @emph{Syntax}:
7397 @multitable @columnfractions .80
7398 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
7399 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
7402 @item @emph{Arguments}:
7403 @multitable @columnfractions .15 .70
7404 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7405 @code{REAL(*)}, or @code{CHARACTER(*)}.
7406 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7407 @code{INTEGER(*)}, with a value between one
7408 and the rank of @var{ARRAY}, inclusive. It
7409 may not be an optional dummy argument.
7410 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL(*)},
7411 and conformable with @var{ARRAY}.
7414 @item @emph{Return value}:
7415 If @var{DIM} is absent, the result is a rank-one array with a length
7416 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
7417 is an array with a rank one less than the rank of @var{ARRAY}, and a
7418 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7419 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
7420 of one, the result is a scalar. In all cases, the result is of default
7421 @code{INTEGER} type.
7423 @item @emph{See also}:
7424 @ref{MIN}, @ref{MINVAL}
7431 @section @code{MINVAL} --- Minimum value of an array
7433 @cindex array, minimum value
7434 @cindex minimum value
7437 @item @emph{Description}:
7438 Determines the minimum value of the elements in an array value, or, if
7439 the @var{DIM} argument is supplied, determines the minimum value along
7440 each row of the array in the @var{DIM} direction. If @var{MASK} is
7441 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7442 considered. If the array has zero size, or all of the elements of
7443 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
7444 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
7445 @var{ARRAY} is of character type.
7447 @item @emph{Standard}:
7451 Transformational function
7453 @item @emph{Syntax}:
7454 @multitable @columnfractions .80
7455 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
7456 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
7459 @item @emph{Arguments}:
7460 @multitable @columnfractions .15 .70
7461 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7462 @code{REAL(*)}, or @code{CHARACTER(*)}.
7463 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7464 @code{INTEGER(*)}, with a value between one
7465 and the rank of @var{ARRAY}, inclusive. It
7466 may not be an optional dummy argument.
7467 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL(*)},
7468 and conformable with @var{ARRAY}.
7471 @item @emph{Return value}:
7472 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7473 is a scalar. If @var{DIM} is present, the result is an array with a
7474 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7475 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
7476 cases, the result is of the same type and kind as @var{ARRAY}.
7478 @item @emph{See also}:
7479 @ref{MIN}, @ref{MINLOC}
7486 @section @code{MOD} --- Remainder function
7491 @cindex division, remainder
7494 @item @emph{Description}:
7495 @code{MOD(A,P)} computes the remainder of the division of A by P. It is
7496 calculated as @code{A - (INT(A/P) * P)}.
7498 @item @emph{Standard}:
7504 @item @emph{Syntax}:
7505 @code{RESULT = MOD(A, P)}
7507 @item @emph{Arguments}:
7508 @multitable @columnfractions .15 .70
7509 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
7510 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
7514 @item @emph{Return value}:
7515 The kind of the return value is the result of cross-promoting
7516 the kinds of the arguments.
7518 @item @emph{Example}:
7522 print *, mod(17.5,5.5)
7523 print *, mod(17.5d0,5.5)
7524 print *, mod(17.5,5.5d0)
7527 print *, mod(-17.5,5.5)
7528 print *, mod(-17.5d0,5.5)
7529 print *, mod(-17.5,5.5d0)
7532 print *, mod(17.5,-5.5)
7533 print *, mod(17.5d0,-5.5)
7534 print *, mod(17.5,-5.5d0)
7535 end program test_mod
7538 @item @emph{Specific names}:
7539 @multitable @columnfractions .20 .20 .20 .25
7540 @item Name @tab Arguments @tab Return type @tab Standard
7541 @item @code{AMOD(A,P)} @tab @code{REAL(4)} @tab @code{REAL(4)} @tab F95 and later
7542 @item @code{DMOD(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab F95 and later
7549 @section @code{MODULO} --- Modulo function
7552 @cindex division, modulo
7555 @item @emph{Description}:
7556 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
7558 @item @emph{Standard}:
7564 @item @emph{Syntax}:
7565 @code{RESULT = MODULO(A, P)}
7567 @item @emph{Arguments}:
7568 @multitable @columnfractions .15 .70
7569 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
7570 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
7573 @item @emph{Return value}:
7574 The type and kind of the result are those of the arguments.
7576 @item If @var{A} and @var{P} are of type @code{INTEGER}:
7577 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
7578 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
7580 @item If @var{A} and @var{P} are of type @code{REAL}:
7581 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
7583 In all cases, if @var{P} is zero the result is processor-dependent.
7585 @item @emph{Example}:
7588 print *, modulo(17,3)
7589 print *, modulo(17.5,5.5)
7591 print *, modulo(-17,3)
7592 print *, modulo(-17.5,5.5)
7594 print *, modulo(17,-3)
7595 print *, modulo(17.5,-5.5)
7604 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
7606 @cindex moving allocation
7607 @cindex allocation, moving
7610 @item @emph{Description}:
7611 @code{MOVE_ALLOC(SRC, DEST)} moves the allocation from @var{SRC} to
7612 @var{DEST}. @var{SRC} will become deallocated in the process.
7614 @item @emph{Standard}:
7620 @item @emph{Syntax}:
7621 @code{CALL MOVE_ALLOC(SRC, DEST)}
7623 @item @emph{Arguments}:
7624 @multitable @columnfractions .15 .70
7625 @item @var{SRC} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
7626 of any type and kind.
7627 @item @var{DEST} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
7628 of the same type, kind and rank as @var{SRC}
7631 @item @emph{Return value}:
7634 @item @emph{Example}:
7636 program test_move_alloc
7637 integer, allocatable :: a(:), b(:)
7641 call move_alloc(a, b)
7642 print *, allocated(a), allocated(b)
7644 end program test_move_alloc
7651 @section @code{MVBITS} --- Move bits from one integer to another
7656 @item @emph{Description}:
7657 Moves @var{LEN} bits from positions @var{FROMPOS} through
7658 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
7659 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
7660 affected by the movement of bits is unchanged. The values of
7661 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
7662 @code{BIT_SIZE(FROM)}.
7664 @item @emph{Standard}:
7668 Elemental subroutine
7670 @item @emph{Syntax}:
7671 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
7673 @item @emph{Arguments}:
7674 @multitable @columnfractions .15 .70
7675 @item @var{FROM} @tab The type shall be @code{INTEGER(*)}.
7676 @item @var{FROMPOS} @tab The type shall be @code{INTEGER(*)}.
7677 @item @var{LEN} @tab The type shall be @code{INTEGER(*)}.
7678 @item @var{TO} @tab The type shall be @code{INTEGER(*)}, of the
7679 same kind as @var{FROM}.
7680 @item @var{TOPOS} @tab The type shall be @code{INTEGER(*)}.
7683 @item @emph{See also}:
7684 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
7690 @section @code{NEAREST} --- Nearest representable number
7692 @cindex real number, nearest different
7693 @cindex floating point, nearest different
7696 @item @emph{Description}:
7697 @code{NEAREST(X, S)} returns the processor-representable number nearest
7698 to @code{X} in the direction indicated by the sign of @code{S}.
7700 @item @emph{Standard}:
7706 @item @emph{Syntax}:
7707 @code{RESULT = NEAREST(X, S)}
7709 @item @emph{Arguments}:
7710 @multitable @columnfractions .15 .70
7711 @item @var{X} @tab Shall be of type @code{REAL}.
7712 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
7716 @item @emph{Return value}:
7717 The return value is of the same type as @code{X}. If @code{S} is
7718 positive, @code{NEAREST} returns the processor-representable number
7719 greater than @code{X} and nearest to it. If @code{S} is negative,
7720 @code{NEAREST} returns the processor-representable number smaller than
7721 @code{X} and nearest to it.
7723 @item @emph{Example}:
7725 program test_nearest
7727 x = nearest(42.0, 1.0)
7728 y = nearest(42.0, -1.0)
7729 write (*,"(3(G20.15))") x, y, x - y
7730 end program test_nearest
7737 @section @code{NEW_LINE} --- New line character
7740 @cindex output, newline
7743 @item @emph{Description}:
7744 @code{NEW_LINE(C)} returns the new-line character.
7746 @item @emph{Standard}:
7752 @item @emph{Syntax}:
7753 @code{RESULT = NEW_LINE(C)}
7755 @item @emph{Arguments}:
7756 @multitable @columnfractions .15 .70
7757 @item @var{C} @tab The argument shall be a scalar or array of the
7758 type @code{CHARACTER}.
7761 @item @emph{Return value}:
7762 Returns a @var{CHARACTER} scalar of length one with the new-line character of
7763 the same kind as parameter @var{C}.
7765 @item @emph{Example}:
7769 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
7777 @section @code{NINT} --- Nearest whole number
7780 @cindex rounding, nearest whole number
7783 @item @emph{Description}:
7784 @code{NINT(X)} rounds its argument to the nearest whole number.
7786 @item @emph{Standard}:
7792 @item @emph{Syntax}:
7793 @code{RESULT = NINT(X)}
7795 @item @emph{Arguments}:
7796 @multitable @columnfractions .15 .70
7797 @item @var{X} @tab The type of the argument shall be @code{REAL}.
7800 @item @emph{Return value}:
7801 Returns @var{A} with the fractional portion of its magnitude eliminated by
7802 rounding to the nearest whole number and with its sign preserved,
7803 converted to an @code{INTEGER} of the default kind.
7805 @item @emph{Example}:
7812 print *, nint(x4), idnint(x8)
7813 end program test_nint
7816 @item @emph{Specific names}:
7817 @multitable @columnfractions .25 .25 .25
7818 @item Name @tab Argument @tab Standard
7819 @item @code{IDNINT(X)} @tab @code{REAL(8)} @tab F95 and later
7822 @item @emph{See also}:
7823 @ref{CEILING}, @ref{FLOOR}
7830 @section @code{NOT} --- Logical negation
7832 @cindex bits, negate
7833 @cindex bitwise logical not
7834 @cindex logical not, bitwise
7837 @item @emph{Description}:
7838 @code{NOT} returns the bitwise boolean inverse of @var{I}.
7840 @item @emph{Standard}:
7846 @item @emph{Syntax}:
7847 @code{RESULT = NOT(I)}
7849 @item @emph{Arguments}:
7850 @multitable @columnfractions .15 .70
7851 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
7854 @item @emph{Return value}:
7855 The return type is @code{INTEGER(*)}, of the same kind as the
7858 @item @emph{See also}:
7859 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
7866 @section @code{NULL} --- Function that returns an disassociated pointer
7868 @cindex pointer, status
7869 @cindex pointer, disassociated
7872 @item @emph{Description}:
7873 Returns a disassociated pointer.
7875 If @var{MOLD} is present, a dissassociated pointer of the same type is
7876 returned, otherwise the type is determined by context.
7878 In Fortran 95, @var{MOLD} is optional. Please note that F2003 includes
7879 cases where it is required.
7881 @item @emph{Standard}:
7885 Transformational function
7887 @item @emph{Syntax}:
7888 @code{PTR => NULL([MOLD])}
7890 @item @emph{Arguments}:
7891 @multitable @columnfractions .15 .70
7892 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
7893 status and of any type.
7896 @item @emph{Return value}:
7897 A disassociated pointer.
7899 @item @emph{Example}:
7901 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
7904 @item @emph{See also}:
7911 @section @code{OR} --- Bitwise logical OR
7913 @cindex bitwise logical or
7914 @cindex logical or, bitwise
7917 @item @emph{Description}:
7918 Bitwise logical @code{OR}.
7920 This intrinsic routine is provided for backwards compatibility with
7921 GNU Fortran 77. For integer arguments, programmers should consider
7922 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
7924 @item @emph{Standard}:
7930 @item @emph{Syntax}:
7931 @code{RESULT = OR(X, Y)}
7933 @item @emph{Arguments}:
7934 @multitable @columnfractions .15 .70
7935 @item @var{X} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
7936 @item @var{Y} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
7939 @item @emph{Return value}:
7940 The return type is either @code{INTEGER(*)} or @code{LOGICAL}
7941 after cross-promotion of the arguments.
7943 @item @emph{Example}:
7946 LOGICAL :: T = .TRUE., F = .FALSE.
7948 DATA a / Z'F' /, b / Z'3' /
7950 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
7951 WRITE (*,*) OR(a, b)
7955 @item @emph{See also}:
7956 F95 elemental function: @ref{IOR}
7962 @section @code{PACK} --- Pack an array into an array of rank one
7964 @cindex array, packing
7965 @cindex array, reduce dimension
7966 @cindex array, gather elements
7969 @item @emph{Description}:
7970 Stores the elements of @var{ARRAY} in an array of rank one.
7972 The beginning of the resulting array is made up of elements whose @var{MASK}
7973 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
7976 @item @emph{Standard}:
7980 Transformational function
7982 @item @emph{Syntax}:
7983 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
7985 @item @emph{Arguments}:
7986 @multitable @columnfractions .15 .70
7987 @item @var{ARRAY} @tab Shall be an array of any type.
7988 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
7989 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
7991 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
7992 as @var{ARRAY} and of rank one. If present, the number of elements in
7993 @var{VECTOR} shall be equal to or greater than the number of true elements
7994 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
7995 @var{VECTOR} shall be equal to or greater than the number of elements in
7999 @item @emph{Return value}:
8000 The result is an array of rank one and the same type as that of @var{ARRAY}.
8001 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
8002 number of @code{TRUE} values in @var{MASK} otherwise.
8004 @item @emph{Example}:
8005 Gathering nonzero elements from an array:
8009 m = (/ 1, 0, 0, 0, 5, 0 /)
8010 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
8014 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
8018 m = (/ 1, 0, 0, 2 /)
8019 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
8023 @item @emph{See also}:
8030 @section @code{PERROR} --- Print system error message
8032 @cindex system, error handling
8035 @item @emph{Description}:
8036 Prints (on the C @code{stderr} stream) a newline-terminated error
8037 message corresponding to the last system error. This is prefixed by
8038 @var{STRING}, a colon and a space. See @code{perror(3)}.
8040 @item @emph{Standard}:
8046 @item @emph{Syntax}:
8047 @code{CALL PERROR(STRING)}
8049 @item @emph{Arguments}:
8050 @multitable @columnfractions .15 .70
8051 @item @var{STRING} @tab A scalar of default @code{CHARACTER} type.
8054 @item @emph{See also}:
8061 @section @code{PRECISION} --- Decimal precision of a real kind
8063 @cindex model representation, precision
8066 @item @emph{Description}:
8067 @code{PRECISION(X)} returns the decimal precision in the model of the
8070 @item @emph{Standard}:
8076 @item @emph{Syntax}:
8077 @code{RESULT = PRECISION(X)}
8079 @item @emph{Arguments}:
8080 @multitable @columnfractions .15 .70
8081 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8084 @item @emph{Return value}:
8085 The return value is of type @code{INTEGER} and of the default integer
8088 @item @emph{Example}:
8090 program prec_and_range
8091 real(kind=4) :: x(2)
8092 complex(kind=8) :: y
8094 print *, precision(x), range(x)
8095 print *, precision(y), range(y)
8096 end program prec_and_range
8103 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
8107 @item @emph{Description}:
8108 Determines whether an optional dummy argument is present.
8110 @item @emph{Standard}:
8116 @item @emph{Syntax}:
8117 @code{RESULT = PRESENT(A)}
8119 @item @emph{Arguments}:
8120 @multitable @columnfractions .15 .70
8121 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
8122 value, or a dummy procedure. It shall be the name of an optional dummy argument
8123 accessible within the current subroutine or function.
8126 @item @emph{Return value}:
8127 Returns either @code{TRUE} if the optional argument @var{A} is present, or
8128 @code{FALSE} otherwise.
8130 @item @emph{Example}:
8132 PROGRAM test_present
8133 WRITE(*,*) f(), f(42) ! "F T"
8135 LOGICAL FUNCTION f(x)
8136 INTEGER, INTENT(IN), OPTIONAL :: x
8146 @section @code{PRODUCT} --- Product of array elements
8148 @cindex array, product
8149 @cindex array, multiply elements
8150 @cindex array, conditionally multiply elements
8151 @cindex multiply array elements
8154 @item @emph{Description}:
8155 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
8156 the corresponding element in @var{MASK} is @code{TRUE}.
8158 @item @emph{Standard}:
8162 Transformational function
8164 @item @emph{Syntax}:
8165 @code{RESULT = PRODUCT(ARRAY[, MASK])}
8166 @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
8168 @item @emph{Arguments}:
8169 @multitable @columnfractions .15 .70
8170 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
8171 @code{REAL(*)} or @code{COMPLEX(*)}.
8172 @item @var{DIM} @tab (Optional) shall be a scalar of type
8173 @code{INTEGER} with a value in the range from 1 to n, where n
8174 equals the rank of @var{ARRAY}.
8175 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
8176 and either be a scalar or an array of the same shape as @var{ARRAY}.
8179 @item @emph{Return value}:
8180 The result is of the same type as @var{ARRAY}.
8182 If @var{DIM} is absent, a scalar with the product of all elements in
8183 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
8184 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
8185 dimension @var{DIM} dropped is returned.
8188 @item @emph{Example}:
8190 PROGRAM test_product
8191 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
8192 print *, PRODUCT(x) ! all elements, product = 120
8193 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
8197 @item @emph{See also}:
8204 @section @code{RADIX} --- Base of a model number
8206 @cindex model representation, base
8207 @cindex model representation, radix
8210 @item @emph{Description}:
8211 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
8213 @item @emph{Standard}:
8219 @item @emph{Syntax}:
8220 @code{RESULT = RADIX(X)}
8222 @item @emph{Arguments}:
8223 @multitable @columnfractions .15 .70
8224 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
8227 @item @emph{Return value}:
8228 The return value is a scalar of type @code{INTEGER} and of the default
8231 @item @emph{Example}:
8234 print *, "The radix for the default integer kind is", radix(0)
8235 print *, "The radix for the default real kind is", radix(0.0)
8236 end program test_radix
8244 @section @code{RAN} --- Real pseudo-random number
8246 @cindex random number generation
8249 @item @emph{Description}:
8250 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
8251 provided as an alias for @code{RAND}. See @ref{RAND} for complete
8254 @item @emph{Standard}:
8260 @item @emph{See also}:
8261 @ref{RAND}, @ref{RANDOM_NUMBER}
8267 @section @code{RAND} --- Real pseudo-random number
8269 @cindex random number generation
8272 @item @emph{Description}:
8273 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
8274 distribution between 0 and 1. If @var{FLAG} is 0, the next number
8275 in the current sequence is returned; if @var{FLAG} is 1, the generator
8276 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
8277 it is used as a new seed with @code{SRAND}.
8279 This intrinsic routine is provided for backwards compatibility with
8280 GNU Fortran 77. It implements a simple modulo generator as provided
8281 by @command{g77}. For new code, one should consider the use of
8282 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
8284 @item @emph{Standard}:
8290 @item @emph{Syntax}:
8291 @code{RESULT = RAND(FLAG)}
8293 @item @emph{Arguments}:
8294 @multitable @columnfractions .15 .70
8295 @item @var{FLAG} @tab Shall be a scalar @code{INTEGER} of kind 4.
8298 @item @emph{Return value}:
8299 The return value is of @code{REAL} type and the default kind.
8301 @item @emph{Example}:
8304 integer,parameter :: seed = 86456
8307 print *, rand(), rand(), rand(), rand()
8308 print *, rand(seed), rand(), rand(), rand()
8309 end program test_rand
8312 @item @emph{See also}:
8313 @ref{SRAND}, @ref{RANDOM_NUMBER}
8320 @section @code{RANDOM_NUMBER} --- Pseudo-random number
8321 @fnindex RANDOM_NUMBER
8322 @cindex random number generation
8325 @item @emph{Description}:
8326 Returns a single pseudorandom number or an array of pseudorandom numbers
8327 from the uniform distribution over the range @math{ 0 \leq x < 1}.
8329 The runtime-library implements George Marsaglia's KISS (Keep It Simple
8330 Stupid) random number generator (RNG). This RNG combines:
8332 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
8333 with a period of @math{2^{32}},
8334 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
8335 @item Two 16-bit multiply-with-carry generators with a period of
8336 @math{597273182964842497 > 2^{59}}.
8338 The overall period exceeds @math{2^{123}}.
8340 Please note, this RNG is thread safe if used within OpenMP directives,
8341 i. e. its state will be consistent while called from multiple threads.
8342 However, the KISS generator does not create random numbers in parallel
8343 from multiple sources, but in sequence from a single source. If an
8344 OpenMP-enabled application heavily relies on random numbers, one should
8345 consider employing a dedicated parallel random number generator instead.
8347 @item @emph{Standard}:
8353 @item @emph{Syntax}:
8354 @code{RANDOM_NUMBER(HARVEST)}
8356 @item @emph{Arguments}:
8357 @multitable @columnfractions .15 .70
8358 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL(*)}.
8361 @item @emph{Example}:
8363 program test_random_number
8365 CALL init_random_seed() ! see example of RANDOM_SEED
8366 CALL RANDOM_NUMBER(r)
8370 @item @emph{See also}:
8377 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
8378 @fnindex RANDOM_SEED
8379 @cindex random number generation, seeding
8380 @cindex seeding a random number generator
8383 @item @emph{Description}:
8384 Restarts or queries the state of the pseudorandom number generator used by
8385 @code{RANDOM_NUMBER}.
8387 If @code{RANDOM_SEED} is called without arguments, it is initialized to
8388 a default state. The example below shows how to initialize the random
8389 seed based on the system's time.
8391 @item @emph{Standard}:
8397 @item @emph{Syntax}:
8398 @code{CALL RANDOM_SEED(SIZE, PUT, GET)}
8400 @item @emph{Arguments}:
8401 @multitable @columnfractions .15 .70
8402 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
8403 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
8404 of the arrays used with the @var{PUT} and @var{GET} arguments.
8405 @item @var{PUT} @tab (Optional) Shall be an array of type default
8406 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
8407 the array must be larger than or equal to the number returned by the
8408 @var{SIZE} argument.
8409 @item @var{GET} @tab (Optional) Shall be an array of type default
8410 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
8411 of the array must be larger than or equal to the number returned by
8412 the @var{SIZE} argument.
8415 @item @emph{Example}:
8417 SUBROUTINE init_random_seed()
8418 INTEGER :: i, n, clock
8419 INTEGER, DIMENSION(:), ALLOCATABLE :: seed
8421 CALL RANDOM_SEED(size = n)
8424 CALL SYSTEM_CLOCK(COUNT=clock)
8426 seed = clock + 37 * (/ (i - 1, i = 1, n) /)
8427 CALL RANDOM_SEED(PUT = seed)
8433 @item @emph{See also}:
8440 @section @code{RANGE} --- Decimal exponent range of a real kind
8442 @cindex model representation, range
8445 @item @emph{Description}:
8446 @code{RANGE(X)} returns the decimal exponent range in the model of the
8449 @item @emph{Standard}:
8455 @item @emph{Syntax}:
8456 @code{RESULT = RANGE(X)}
8458 @item @emph{Arguments}:
8459 @multitable @columnfractions .15 .70
8460 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8463 @item @emph{Return value}:
8464 The return value is of type @code{INTEGER} and of the default integer
8467 @item @emph{Example}:
8468 See @code{PRECISION} for an example.
8474 @section @code{REAL} --- Convert to real type
8477 @cindex conversion, to real
8478 @cindex complex numbers, real part
8481 @item @emph{Description}:
8482 @code{REAL(X [, KIND])} converts its argument @var{X} to a real type. The
8483 @code{REALPART(X)} function is provided for compatibility with @command{g77},
8484 and its use is strongly discouraged.
8486 @item @emph{Standard}:
8492 @item @emph{Syntax}:
8493 @multitable @columnfractions .80
8494 @item @code{RESULT = REAL(X [, KIND])}
8495 @item @code{RESULT = REALPART(Z)}
8498 @item @emph{Arguments}:
8499 @multitable @columnfractions .15 .70
8500 @item @var{X} @tab Shall be @code{INTEGER(*)}, @code{REAL(*)}, or
8502 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
8503 expression indicating the kind parameter of
8507 @item @emph{Return value}:
8508 These functions return a @code{REAL(*)} variable or array under
8509 the following rules:
8513 @code{REAL(X)} is converted to a default real type if @var{X} is an
8514 integer or real variable.
8516 @code{REAL(X)} is converted to a real type with the kind type parameter
8517 of @var{X} if @var{X} is a complex variable.
8519 @code{REAL(X, KIND)} is converted to a real type with kind type
8520 parameter @var{KIND} if @var{X} is a complex, integer, or real
8524 @item @emph{Example}:
8527 complex :: x = (1.0, 2.0)
8528 print *, real(x), real(x,8), realpart(x)
8529 end program test_real
8532 @item @emph{See also}:
8533 @ref{DBLE}, @ref{DFLOAT}, @ref{FLOAT}
8540 @section @code{RENAME} --- Rename a file
8542 @cindex file system, rename file
8545 @item @emph{Description}:
8546 Renames a file from file @var{PATH1} to @var{PATH2}. A null
8547 character (@code{CHAR(0)}) can be used to mark the end of the names in
8548 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
8549 names are ignored. If the @var{STATUS} argument is supplied, it
8550 contains 0 on success or a nonzero error code upon return; see
8553 This intrinsic is provided in both subroutine and function forms;
8554 however, only one form can be used in any given program unit.
8556 @item @emph{Standard}:
8560 Subroutine, function
8562 @item @emph{Syntax}:
8563 @multitable @columnfractions .80
8564 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
8565 @item @code{STATUS = RENAME(PATH1, PATH2)}
8568 @item @emph{Arguments}:
8569 @multitable @columnfractions .15 .70
8570 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
8571 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
8572 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
8575 @item @emph{See also}:
8583 @section @code{REPEAT} --- Repeated string concatenation
8585 @cindex string, repeat
8586 @cindex string, concatenate
8589 @item @emph{Description}:
8590 Concatenates @var{NCOPIES} copies of a string.
8592 @item @emph{Standard}:
8596 Transformational function
8598 @item @emph{Syntax}:
8599 @code{RESULT = REPEAT(STRING, NCOPIES)}
8601 @item @emph{Arguments}:
8602 @multitable @columnfractions .15 .70
8603 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER(*)}.
8604 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER(*)}.
8607 @item @emph{Return value}:
8608 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
8611 @item @emph{Example}:
8614 write(*,*) repeat("x", 5) ! "xxxxx"
8622 @section @code{RESHAPE} --- Function to reshape an array
8624 @cindex array, change dimensions
8625 @cindex array, transmogrify
8628 @item @emph{Description}:
8629 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
8630 the new array may be padded with elements from @var{PAD} or permuted
8631 as defined by @var{ORDER}.
8633 @item @emph{Standard}:
8637 Transformational function
8639 @item @emph{Syntax}:
8640 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
8642 @item @emph{Arguments}:
8643 @multitable @columnfractions .15 .70
8644 @item @var{SOURCE} @tab Shall be an array of any type.
8645 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
8646 array of rank one. Its values must be positive or zero.
8647 @item @var{PAD} @tab (Optional) shall be an array of the same
8648 type as @var{SOURCE}.
8649 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
8650 and an array of the same shape as @var{SHAPE}. Its values shall
8651 be a permutation of the numbers from 1 to n, where n is the size of
8652 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
8656 @item @emph{Return value}:
8657 The result is an array of shape @var{SHAPE} with the same type as
8660 @item @emph{Example}:
8662 PROGRAM test_reshape
8663 INTEGER, DIMENSION(4) :: x
8664 WRITE(*,*) SHAPE(x) ! prints "4"
8665 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
8669 @item @emph{See also}:
8676 @section @code{RRSPACING} --- Reciprocal of the relative spacing
8678 @cindex real number, relative spacing
8679 @cindex floating point, relative spacing
8683 @item @emph{Description}:
8684 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
8685 model numbers near @var{X}.
8687 @item @emph{Standard}:
8693 @item @emph{Syntax}:
8694 @code{RESULT = RRSPACING(X)}
8696 @item @emph{Arguments}:
8697 @multitable @columnfractions .15 .70
8698 @item @var{X} @tab Shall be of type @code{REAL}.
8701 @item @emph{Return value}:
8702 The return value is of the same type and kind as @var{X}.
8703 The value returned is equal to
8704 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
8706 @item @emph{See also}:
8713 @section @code{RSHIFT} --- Right shift bits
8715 @cindex bits, shift right
8718 @item @emph{Description}:
8719 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
8720 bits shifted right by @var{SHIFT} places. If the absolute value of
8721 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
8722 Bits shifted out from the left end are lost; zeros are shifted in from
8725 This function has been superseded by the @code{ISHFT} intrinsic, which
8726 is standard in Fortran 95 and later.
8728 @item @emph{Standard}:
8734 @item @emph{Syntax}:
8735 @code{RESULT = RSHIFT(I, SHIFT)}
8737 @item @emph{Arguments}:
8738 @multitable @columnfractions .15 .70
8739 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
8740 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
8743 @item @emph{Return value}:
8744 The return value is of type @code{INTEGER(*)} and of the same kind as
8747 @item @emph{See also}:
8748 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}
8755 @section @code{SCALE} --- Scale a real value
8757 @cindex real number, scale
8758 @cindex floating point, scale
8761 @item @emph{Description}:
8762 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
8764 @item @emph{Standard}:
8770 @item @emph{Syntax}:
8771 @code{RESULT = SCALE(X, I)}
8773 @item @emph{Arguments}:
8774 @multitable @columnfractions .15 .70
8775 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
8776 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
8779 @item @emph{Return value}:
8780 The return value is of the same type and kind as @var{X}.
8781 Its value is @code{X * RADIX(X)**I}.
8783 @item @emph{Example}:
8786 real :: x = 178.1387e-4
8788 print *, scale(x,i), x*radix(x)**i
8789 end program test_scale
8797 @section @code{SCAN} --- Scan a string for the presence of a set of characters
8799 @cindex string, find subset
8802 @item @emph{Description}:
8803 Scans a @var{STRING} for any of the characters in a @var{SET}
8806 If @var{BACK} is either absent or equals @code{FALSE}, this function
8807 returns the position of the leftmost character of @var{STRING} that is
8808 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
8809 is returned. If no character of @var{SET} is found in @var{STRING}, the
8812 @item @emph{Standard}:
8818 @item @emph{Syntax}:
8819 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
8821 @item @emph{Arguments}:
8822 @multitable @columnfractions .15 .70
8823 @item @var{STRING} @tab Shall be of type @code{CHARACTER(*)}.
8824 @item @var{SET} @tab Shall be of type @code{CHARACTER(*)}.
8825 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
8826 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8827 expression indicating the kind parameter of
8831 @item @emph{Return value}:
8832 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8833 @var{KIND} is absent, the return value is of default integer kind.
8835 @item @emph{Example}:
8838 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
8839 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
8840 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
8844 @item @emph{See also}:
8845 @ref{INDEX}, @ref{VERIFY}
8851 @section @code{SECNDS} --- Time function
8853 @cindex time, elapsed
8854 @cindex elapsed time
8857 @item @emph{Description}:
8858 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
8859 @var{X} is a reference time, also in seconds. If this is zero, the time in
8860 seconds from midnight is returned. This function is non-standard and its
8863 @item @emph{Standard}:
8869 @item @emph{Syntax}:
8870 @code{RESULT = SECNDS (X)}
8872 @item @emph{Arguments}:
8873 @multitable @columnfractions .15 .70
8874 @item @var{T} @tab Shall be of type @code{REAL(4)}.
8875 @item @var{X} @tab Shall be of type @code{REAL(4)}.
8878 @item @emph{Return value}:
8881 @item @emph{Example}:
8886 print *, secnds (0.0) ! seconds since midnight
8887 t1 = secnds (0.0) ! reference time
8888 do i = 1, 10000000 ! do something
8890 t2 = secnds (t1) ! elapsed time
8891 print *, "Something took ", t2, " seconds."
8892 end program test_secnds
8899 @section @code{SECOND} --- CPU time function
8901 @cindex time, elapsed
8902 @cindex elapsed time
8905 @item @emph{Description}:
8906 Returns a @code{REAL(4)} value representing the elapsed CPU time in
8907 seconds. This provides the same functionality as the standard
8908 @code{CPU_TIME} intrinsic, and is only included for backwards
8911 This intrinsic is provided in both subroutine and function forms;
8912 however, only one form can be used in any given program unit.
8914 @item @emph{Standard}:
8918 Subroutine, function
8920 @item @emph{Syntax}:
8921 @multitable @columnfractions .80
8922 @item @code{CALL SECOND(TIME)}
8923 @item @code{TIME = SECOND()}
8926 @item @emph{Arguments}:
8927 @multitable @columnfractions .15 .70
8928 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
8931 @item @emph{Return value}:
8932 In either syntax, @var{TIME} is set to the process's current runtime in
8935 @item @emph{See also}:
8942 @node SELECTED_INT_KIND
8943 @section @code{SELECTED_INT_KIND} --- Choose integer kind
8944 @fnindex SELECTED_INT_KIND
8945 @cindex integer kind
8946 @cindex kind, integer
8949 @item @emph{Description}:
8950 @code{SELECTED_INT_KIND(I)} return the kind value of the smallest integer
8951 type that can represent all values ranging from @math{-10^I} (exclusive)
8952 to @math{10^I} (exclusive). If there is no integer kind that accommodates
8953 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
8955 @item @emph{Standard}:
8959 Transformational function
8961 @item @emph{Syntax}:
8962 @code{RESULT = SELECTED_INT_KIND(I)}
8964 @item @emph{Arguments}:
8965 @multitable @columnfractions .15 .70
8966 @item @var{I} @tab Shall be a scalar and of type @code{INTEGER}.
8969 @item @emph{Example}:
8971 program large_integers
8972 integer,parameter :: k5 = selected_int_kind(5)
8973 integer,parameter :: k15 = selected_int_kind(15)
8974 integer(kind=k5) :: i5
8975 integer(kind=k15) :: i15
8977 print *, huge(i5), huge(i15)
8979 ! The following inequalities are always true
8980 print *, huge(i5) >= 10_k5**5-1
8981 print *, huge(i15) >= 10_k15**15-1
8982 end program large_integers
8988 @node SELECTED_REAL_KIND
8989 @section @code{SELECTED_REAL_KIND} --- Choose real kind
8990 @fnindex SELECTED_REAL_KIND
8995 @item @emph{Description}:
8996 @code{SELECTED_REAL_KIND(P,R)} return the kind value of a real data type
8997 with decimal precision greater of at least @code{P} digits and exponent
8998 range greater at least @code{R}.
9000 @item @emph{Standard}:
9004 Transformational function
9006 @item @emph{Syntax}:
9007 @code{RESULT = SELECTED_REAL_KIND(P, R)}
9009 @item @emph{Arguments}:
9010 @multitable @columnfractions .15 .70
9011 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9012 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9014 At least one argument shall be present.
9016 @item @emph{Return value}:
9018 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
9019 a real data type with decimal precision of at least @code{P} digits and a
9020 decimal exponent range of at least @code{R}. If more than one real data
9021 type meet the criteria, the kind of the data type with the smallest
9022 decimal precision is returned. If no real data type matches the criteria,
9025 @item -1 if the processor does not support a real data type with a
9026 precision greater than or equal to @code{P}
9027 @item -2 if the processor does not support a real type with an exponent
9028 range greater than or equal to @code{R}
9029 @item -3 if neither is supported.
9032 @item @emph{Example}:
9035 integer,parameter :: p6 = selected_real_kind(6)
9036 integer,parameter :: p10r100 = selected_real_kind(10,100)
9037 integer,parameter :: r400 = selected_real_kind(r=400)
9039 real(kind=p10r100) :: y
9040 real(kind=r400) :: z
9042 print *, precision(x), range(x)
9043 print *, precision(y), range(y)
9044 print *, precision(z), range(z)
9045 end program real_kinds
9052 @section @code{SET_EXPONENT} --- Set the exponent of the model
9053 @fnindex SET_EXPONENT
9054 @cindex real number, set exponent
9055 @cindex floating point, set exponent
9058 @item @emph{Description}:
9059 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
9060 is that that of @var{X} and whose exponent part is @var{I}.
9062 @item @emph{Standard}:
9068 @item @emph{Syntax}:
9069 @code{RESULT = SET_EXPONENT(X, I)}
9071 @item @emph{Arguments}:
9072 @multitable @columnfractions .15 .70
9073 @item @var{X} @tab Shall be of type @code{REAL}.
9074 @item @var{I} @tab Shall be of type @code{INTEGER}.
9077 @item @emph{Return value}:
9078 The return value is of the same type and kind as @var{X}.
9079 The real number whose fractional part
9080 is that that of @var{X} and whose exponent part if @var{I} is returned;
9081 it is @code{FRACTION(X) * RADIX(X)**I}.
9083 @item @emph{Example}:
9086 REAL :: x = 178.1387e-4
9088 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
9097 @section @code{SHAPE} --- Determine the shape of an array
9099 @cindex array, shape
9102 @item @emph{Description}:
9103 Determines the shape of an array.
9105 @item @emph{Standard}:
9111 @item @emph{Syntax}:
9112 @code{RESULT = SHAPE(SOURCE)}
9114 @item @emph{Arguments}:
9115 @multitable @columnfractions .15 .70
9116 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
9117 If @var{SOURCE} is a pointer it must be associated and allocatable
9118 arrays must be allocated.
9121 @item @emph{Return value}:
9122 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
9123 has dimensions. The elements of the resulting array correspond to the extend
9124 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
9125 the result is the rank one array of size zero.
9127 @item @emph{Example}:
9130 INTEGER, DIMENSION(-1:1, -1:2) :: A
9131 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
9132 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
9136 @item @emph{See also}:
9137 @ref{RESHAPE}, @ref{SIZE}
9143 @section @code{SIGN} --- Sign copying function
9147 @cindex sign copying
9150 @item @emph{Description}:
9151 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
9153 @item @emph{Standard}:
9159 @item @emph{Syntax}:
9160 @code{RESULT = SIGN(A, B)}
9162 @item @emph{Arguments}:
9163 @multitable @columnfractions .15 .70
9164 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
9165 @item @var{B} @tab Shall be of the same type and kind as @var{A}
9168 @item @emph{Return value}:
9169 The kind of the return value is that of @var{A} and @var{B}.
9170 If @math{B\ge 0} then the result is @code{ABS(A)}, else
9171 it is @code{-ABS(A)}.
9173 @item @emph{Example}:
9176 print *, sign(-12,1)
9177 print *, sign(-12,0)
9178 print *, sign(-12,-1)
9180 print *, sign(-12.,1.)
9181 print *, sign(-12.,0.)
9182 print *, sign(-12.,-1.)
9183 end program test_sign
9186 @item @emph{Specific names}:
9187 @multitable @columnfractions .20 .20 .20 .25
9188 @item Name @tab Arguments @tab Return type @tab Standard
9189 @item @code{ISIGN(A,P)} @tab @code{INTEGER(4)} @tab @code{INTEGER(4)} @tab f95, gnu
9190 @item @code{DSIGN(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab f95, gnu
9197 @section @code{SIGNAL} --- Signal handling subroutine (or function)
9199 @cindex system, signal handling
9202 @item @emph{Description}:
9203 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
9204 @var{HANDLER} to be executed with a single integer argument when signal
9205 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
9206 turn off handling of signal @var{NUMBER} or revert to its default
9207 action. See @code{signal(2)}.
9209 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
9210 is supplied, it is set to the value returned by @code{signal(2)}.
9212 @item @emph{Standard}:
9216 Subroutine, function
9218 @item @emph{Syntax}:
9219 @multitable @columnfractions .80
9220 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
9221 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
9224 @item @emph{Arguments}:
9225 @multitable @columnfractions .15 .70
9226 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
9227 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
9228 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
9229 @code{INTEGER}. It is @code{INTENT(IN)}.
9230 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
9231 integer. It has @code{INTENT(OUT)}.
9234 @item @emph{Return value}:
9235 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
9237 @item @emph{Example}:
9241 external handler_print
9243 call signal (12, handler_print)
9247 end program test_signal
9254 @section @code{SIN} --- Sine function
9260 @cindex trigonometric function, sine
9264 @item @emph{Description}:
9265 @code{SIN(X)} computes the sine of @var{X}.
9267 @item @emph{Standard}:
9273 @item @emph{Syntax}:
9274 @code{RESULT = SIN(X)}
9276 @item @emph{Arguments}:
9277 @multitable @columnfractions .15 .70
9278 @item @var{X} @tab The type shall be @code{REAL(*)} or
9282 @item @emph{Return value}:
9283 The return value has same type and kind as @var{X}.
9285 @item @emph{Example}:
9290 end program test_sin
9293 @item @emph{Specific names}:
9294 @multitable @columnfractions .20 .20 .20 .25
9295 @item Name @tab Argument @tab Return type @tab Standard
9296 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
9297 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
9298 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9299 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9302 @item @emph{See also}:
9309 @section @code{SINH} --- Hyperbolic sine function
9312 @cindex hyperbolic sine
9313 @cindex hyperbolic function, sine
9314 @cindex sine, hyperbolic
9317 @item @emph{Description}:
9318 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
9320 @item @emph{Standard}:
9326 @item @emph{Syntax}:
9327 @code{RESULT = SINH(X)}
9329 @item @emph{Arguments}:
9330 @multitable @columnfractions .15 .70
9331 @item @var{X} @tab The type shall be @code{REAL(*)}.
9334 @item @emph{Return value}:
9335 The return value is of type @code{REAL(*)}.
9337 @item @emph{Example}:
9340 real(8) :: x = - 1.0_8
9342 end program test_sinh
9345 @item @emph{Specific names}:
9346 @multitable @columnfractions .20 .20 .20 .25
9347 @item Name @tab Argument @tab Return type @tab Standard
9348 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
9351 @item @emph{See also}:
9358 @section @code{SIZE} --- Determine the size of an array
9361 @cindex array, number of elements
9362 @cindex array, count elements
9365 @item @emph{Description}:
9366 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
9367 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
9369 @item @emph{Standard}:
9375 @item @emph{Syntax}:
9376 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
9378 @item @emph{Arguments}:
9379 @multitable @columnfractions .15 .70
9380 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
9381 a pointer it must be associated and allocatable arrays must be allocated.
9382 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
9383 and its value shall be in the range from 1 to n, where n equals the rank
9385 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9386 expression indicating the kind parameter of
9390 @item @emph{Return value}:
9391 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9392 @var{KIND} is absent, the return value is of default integer kind.
9394 @item @emph{Example}:
9397 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
9401 @item @emph{See also}:
9402 @ref{SHAPE}, @ref{RESHAPE}
9407 @section @code{SIZEOF} --- Size in bytes of an expression
9409 @cindex expression size
9410 @cindex size of an expression
9413 @item @emph{Description}:
9414 @code{SIZEOF(X)} calculates the number of bytes of storage the
9415 expression @code{X} occupies.
9417 @item @emph{Standard}:
9423 @item @emph{Syntax}:
9424 @code{N = SIZEOF(X)}
9426 @item @emph{Arguments}:
9427 @multitable @columnfractions .15 .70
9428 @item @var{X} @tab The argument shall be of any type, rank or shape.
9431 @item @emph{Return value}:
9432 The return value is of type integer and of the system-dependent kind
9433 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
9434 number of bytes occupied by the argument. If the argument has the
9435 @code{POINTER} attribute, the number of bytes of the storage area pointed
9436 to is returned. If the argument is of a derived type with @code{POINTER}
9437 or @code{ALLOCATABLE} components, the return value doesn't account for
9438 the sizes of the data pointed to by these components.
9440 @item @emph{Example}:
9444 print *, (sizeof(s)/sizeof(r) == 5)
9447 The example will print @code{.TRUE.} unless you are using a platform
9448 where default @code{REAL} variables are unusually padded.
9452 @section @code{SLEEP} --- Sleep for the specified number of seconds
9454 @cindex delayed execution
9457 @item @emph{Description}:
9458 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
9460 @item @emph{Standard}:
9466 @item @emph{Syntax}:
9467 @code{CALL SLEEP(SECONDS)}
9469 @item @emph{Arguments}:
9470 @multitable @columnfractions .15 .70
9471 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
9474 @item @emph{Example}:
9485 @section @code{SNGL} --- Convert double precision real to default real
9487 @cindex conversion, to real
9490 @item @emph{Description}:
9491 @code{SNGL(A)} converts the double precision real @var{A}
9492 to a default real value. This is an archaic form of @code{REAL}
9493 that is specific to one type for @var{A}.
9495 @item @emph{Standard}:
9501 @item @emph{Syntax}:
9502 @code{RESULT = SNGL(A)}
9504 @item @emph{Arguments}:
9505 @multitable @columnfractions .15 .70
9506 @item @var{A} @tab The type shall be a double precision @code{REAL}.
9509 @item @emph{Return value}:
9510 The return value is of type default @code{REAL}.
9512 @item @emph{See also}:
9519 @section @code{SPACING} --- Smallest distance between two numbers of a given type
9521 @cindex real number, relative spacing
9522 @cindex floating point, relative spacing
9525 @item @emph{Description}:
9526 Determines the distance between the argument @var{X} and the nearest
9527 adjacent number of the same type.
9529 @item @emph{Standard}:
9535 @item @emph{Syntax}:
9536 @code{RESULT = SPACING(X)}
9538 @item @emph{Arguments}:
9539 @multitable @columnfractions .15 .70
9540 @item @var{X} @tab Shall be of type @code{REAL(*)}.
9543 @item @emph{Return value}:
9544 The result is of the same type as the input argument @var{X}.
9546 @item @emph{Example}:
9548 PROGRAM test_spacing
9549 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
9550 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
9552 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
9553 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
9557 @item @emph{See also}:
9564 @section @code{SPREAD} --- Add a dimension to an array
9566 @cindex array, increase dimension
9567 @cindex array, duplicate elements
9568 @cindex array, duplicate dimensions
9571 @item @emph{Description}:
9572 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
9573 dimension @var{DIM}.
9575 @item @emph{Standard}:
9579 Transformational function
9581 @item @emph{Syntax}:
9582 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
9584 @item @emph{Arguments}:
9585 @multitable @columnfractions .15 .70
9586 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
9587 a rank less than seven.
9588 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
9589 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
9590 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
9593 @item @emph{Return value}:
9594 The result is an array of the same type as @var{SOURCE} and has rank n+1
9595 where n equals the rank of @var{SOURCE}.
9597 @item @emph{Example}:
9600 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
9601 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
9602 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
9606 @item @emph{See also}:
9613 @section @code{SQRT} --- Square-root function
9623 @item @emph{Description}:
9624 @code{SQRT(X)} computes the square root of @var{X}.
9626 @item @emph{Standard}:
9632 @item @emph{Syntax}:
9633 @code{RESULT = SQRT(X)}
9635 @item @emph{Arguments}:
9636 @multitable @columnfractions .15 .70
9637 @item @var{X} @tab The type shall be @code{REAL(*)} or
9641 @item @emph{Return value}:
9642 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
9643 The kind type parameter is the same as @var{X}.
9645 @item @emph{Example}:
9648 real(8) :: x = 2.0_8
9649 complex :: z = (1.0, 2.0)
9652 end program test_sqrt
9655 @item @emph{Specific names}:
9656 @multitable @columnfractions .20 .20 .20 .25
9657 @item Name @tab Argument @tab Return type @tab Standard
9658 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
9659 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab F95 and later
9660 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
9661 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
9668 @section @code{SRAND} --- Reinitialize the random number generator
9670 @cindex random number generation, seeding
9671 @cindex seeding a random number generator
9674 @item @emph{Description}:
9675 @code{SRAND} reinitializes the pseudo-random number generator
9676 called by @code{RAND} and @code{IRAND}. The new seed used by the
9677 generator is specified by the required argument @var{SEED}.
9679 @item @emph{Standard}:
9685 @item @emph{Syntax}:
9686 @code{CALL SRAND(SEED)}
9688 @item @emph{Arguments}:
9689 @multitable @columnfractions .15 .70
9690 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
9693 @item @emph{Return value}:
9696 @item @emph{Example}:
9697 See @code{RAND} and @code{IRAND} for examples.
9700 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
9701 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
9702 to generate pseudo-random numbers. Please note that in
9703 GNU Fortran, these two sets of intrinsics (@code{RAND},
9704 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
9705 @code{RANDOM_SEED} on the other hand) access two independent
9706 pseudo-random number generators.
9708 @item @emph{See also}:
9709 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
9716 @section @code{STAT} --- Get file status
9718 @cindex file system, file status
9721 @item @emph{Description}:
9722 This function returns information about a file. No permissions are required on
9723 the file itself, but execute (search) permission is required on all of the
9724 directories in path that lead to the file.
9726 The elements that are obtained and stored in the array @code{BUFF}:
9727 @multitable @columnfractions .15 .70
9728 @item @code{buff(1)} @tab Device ID
9729 @item @code{buff(2)} @tab Inode number
9730 @item @code{buff(3)} @tab File mode
9731 @item @code{buff(4)} @tab Number of links
9732 @item @code{buff(5)} @tab Owner's uid
9733 @item @code{buff(6)} @tab Owner's gid
9734 @item @code{buff(7)} @tab ID of device containing directory entry for file (0 if not available)
9735 @item @code{buff(8)} @tab File size (bytes)
9736 @item @code{buff(9)} @tab Last access time
9737 @item @code{buff(10)} @tab Last modification time
9738 @item @code{buff(11)} @tab Last file status change time
9739 @item @code{buff(12)} @tab Preferred I/O block size (-1 if not available)
9740 @item @code{buff(13)} @tab Number of blocks allocated (-1 if not available)
9743 Not all these elements are relevant on all systems.
9744 If an element is not relevant, it is returned as 0.
9746 This intrinsic is provided in both subroutine and function forms; however,
9747 only one form can be used in any given program unit.
9749 @item @emph{Standard}:
9753 Subroutine, function
9755 @item @emph{Syntax}:
9756 @code{CALL STAT(FILE,BUFF[,STATUS])}
9758 @item @emph{Arguments}:
9759 @multitable @columnfractions .15 .70
9760 @item @var{FILE} @tab The type shall be @code{CHARACTER(*)}, a valid path within the file system.
9761 @item @var{BUFF} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
9762 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
9763 on success and a system specific error code otherwise.
9766 @item @emph{Example}:
9769 INTEGER, DIMENSION(13) :: buff
9772 CALL STAT("/etc/passwd", buff, status)
9774 IF (status == 0) THEN
9775 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
9776 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
9777 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
9778 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
9779 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
9780 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
9781 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
9782 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
9783 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
9784 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
9785 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
9786 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
9787 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
9792 @item @emph{See also}:
9793 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
9799 @section @code{SUM} --- Sum of array elements
9802 @cindex array, add elements
9803 @cindex array, conditionally add elements
9804 @cindex sum array elements
9807 @item @emph{Description}:
9808 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
9809 the corresponding element in @var{MASK} is @code{TRUE}.
9811 @item @emph{Standard}:
9815 Transformational function
9817 @item @emph{Syntax}:
9818 @code{RESULT = SUM(ARRAY[, MASK])}
9819 @code{RESULT = SUM(ARRAY, DIM[, MASK])}
9821 @item @emph{Arguments}:
9822 @multitable @columnfractions .15 .70
9823 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
9824 @code{REAL(*)} or @code{COMPLEX(*)}.
9825 @item @var{DIM} @tab (Optional) shall be a scalar of type
9826 @code{INTEGER} with a value in the range from 1 to n, where n
9827 equals the rank of @var{ARRAY}.
9828 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
9829 and either be a scalar or an array of the same shape as @var{ARRAY}.
9832 @item @emph{Return value}:
9833 The result is of the same type as @var{ARRAY}.
9835 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
9836 is returned. Otherwise, an array of rank n-1, where n equals the rank of
9837 @var{ARRAY},and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
9838 dropped is returned.
9840 @item @emph{Example}:
9843 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
9844 print *, SUM(x) ! all elements, sum = 15
9845 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
9849 @item @emph{See also}:
9856 @section @code{SYMLNK} --- Create a symbolic link
9858 @cindex file system, create link
9859 @cindex file system, soft link
9862 @item @emph{Description}:
9863 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
9864 character (@code{CHAR(0)}) can be used to mark the end of the names in
9865 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
9866 names are ignored. If the @var{STATUS} argument is supplied, it
9867 contains 0 on success or a nonzero error code upon return; see
9868 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
9869 @code{ENOSYS} is returned.
9871 This intrinsic is provided in both subroutine and function forms;
9872 however, only one form can be used in any given program unit.
9874 @item @emph{Standard}:
9878 Subroutine, function
9880 @item @emph{Syntax}:
9881 @multitable @columnfractions .80
9882 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
9883 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
9886 @item @emph{Arguments}:
9887 @multitable @columnfractions .15 .70
9888 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
9889 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
9890 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9893 @item @emph{See also}:
9894 @ref{LINK}, @ref{UNLINK}
9901 @section @code{SYSTEM} --- Execute a shell command
9903 @cindex system, system call
9906 @item @emph{Description}:
9907 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
9908 argument @var{STATUS} is present, it contains the value returned by
9909 @code{system(3)}, which is presumably 0 if the shell command succeeded.
9910 Note that which shell is used to invoke the command is system-dependent
9911 and environment-dependent.
9913 This intrinsic is provided in both subroutine and function forms;
9914 however, only one form can be used in any given program unit.
9916 @item @emph{Standard}:
9920 Subroutine, function
9922 @item @emph{Syntax}:
9923 @multitable @columnfractions .80
9924 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
9925 @item @code{STATUS = SYSTEM(COMMAND)}
9928 @item @emph{Arguments}:
9929 @multitable @columnfractions .15 .70
9930 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
9931 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9934 @item @emph{See also}:
9940 @section @code{SYSTEM_CLOCK} --- Time function
9941 @fnindex SYSTEM_CLOCK
9942 @cindex time, clock ticks
9946 @item @emph{Description}:
9947 Determines the @var{COUNT} of milliseconds of wall clock time since
9948 the Epoch (00:00:00 UTC, January 1, 1970) modulo @var{COUNT_MAX},
9949 @var{COUNT_RATE} determines the number of clock ticks per second.
9950 @var{COUNT_RATE} and @var{COUNT_MAX} are constant and specific to
9953 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
9954 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero
9956 @item @emph{Standard}:
9962 @item @emph{Syntax}:
9963 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
9965 @item @emph{Arguments}:
9966 @item @emph{Arguments}:
9967 @multitable @columnfractions .15 .70
9968 @item @var{COUNT} @tab (Optional) shall be a scalar of type default
9969 @code{INTEGER} with @code{INTENT(OUT)}.
9970 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type default
9971 @code{INTEGER} with @code{INTENT(OUT)}.
9972 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type default
9973 @code{INTEGER} with @code{INTENT(OUT)}.
9976 @item @emph{Example}:
9978 PROGRAM test_system_clock
9979 INTEGER :: count, count_rate, count_max
9980 CALL SYSTEM_CLOCK(count, count_rate, count_max)
9981 WRITE(*,*) count, count_rate, count_max
9985 @item @emph{See also}:
9986 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
9992 @section @code{TAN} --- Tangent function
9995 @cindex trigonometric function, tangent
9999 @item @emph{Description}:
10000 @code{TAN(X)} computes the tangent of @var{X}.
10002 @item @emph{Standard}:
10005 @item @emph{Class}:
10008 @item @emph{Syntax}:
10009 @code{RESULT = TAN(X)}
10011 @item @emph{Arguments}:
10012 @multitable @columnfractions .15 .70
10013 @item @var{X} @tab The type shall be @code{REAL(*)}.
10016 @item @emph{Return value}:
10017 The return value is of type @code{REAL(*)}. The kind type parameter is
10018 the same as @var{X}.
10020 @item @emph{Example}:
10023 real(8) :: x = 0.165_8
10025 end program test_tan
10028 @item @emph{Specific names}:
10029 @multitable @columnfractions .20 .20 .20 .25
10030 @item Name @tab Argument @tab Return type @tab Standard
10031 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
10034 @item @emph{See also}:
10041 @section @code{TANH} --- Hyperbolic tangent function
10044 @cindex hyperbolic tangent
10045 @cindex hyperbolic function, tangent
10046 @cindex tangent, hyperbolic
10049 @item @emph{Description}:
10050 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
10052 @item @emph{Standard}:
10055 @item @emph{Class}:
10058 @item @emph{Syntax}:
10061 @item @emph{Arguments}:
10062 @multitable @columnfractions .15 .70
10063 @item @var{X} @tab The type shall be @code{REAL(*)}.
10066 @item @emph{Return value}:
10067 The return value is of type @code{REAL(*)} and lies in the range
10068 @math{ - 1 \leq tanh(x) \leq 1 }.
10070 @item @emph{Example}:
10073 real(8) :: x = 2.1_8
10075 end program test_tanh
10078 @item @emph{Specific names}:
10079 @multitable @columnfractions .20 .20 .20 .25
10080 @item Name @tab Argument @tab Return type @tab Standard
10081 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
10084 @item @emph{See also}:
10091 @section @code{TIME} --- Time function
10093 @cindex time, current
10094 @cindex current time
10097 @item @emph{Description}:
10098 Returns the current time encoded as an integer (in the manner of the
10099 UNIX function @code{time(3)}). This value is suitable for passing to
10100 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10102 This intrinsic is not fully portable, such as to systems with 32-bit
10103 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
10104 the values returned by this intrinsic might be, or become, negative, or
10105 numerically less than previous values, during a single run of the
10108 See @ref{TIME8}, for information on a similar intrinsic that might be
10109 portable to more GNU Fortran implementations, though to fewer Fortran
10112 @item @emph{Standard}:
10115 @item @emph{Class}:
10118 @item @emph{Syntax}:
10119 @code{RESULT = TIME()}
10121 @item @emph{Return value}:
10122 The return value is a scalar of type @code{INTEGER(4)}.
10124 @item @emph{See also}:
10125 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
10132 @section @code{TIME8} --- Time function (64-bit)
10134 @cindex time, current
10135 @cindex current time
10138 @item @emph{Description}:
10139 Returns the current time encoded as an integer (in the manner of the
10140 UNIX function @code{time(3)}). This value is suitable for passing to
10141 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10143 @emph{Warning:} this intrinsic does not increase the range of the timing
10144 values over that returned by @code{time(3)}. On a system with a 32-bit
10145 @code{time(3)}, @code{TIME8()} will return a 32-bit value, even though
10146 it is converted to a 64-bit @code{INTEGER(8)} value. That means
10147 overflows of the 32-bit value can still occur. Therefore, the values
10148 returned by this intrinsic might be or become negative or numerically
10149 less than previous values during a single run of the compiled program.
10151 @item @emph{Standard}:
10154 @item @emph{Class}:
10157 @item @emph{Syntax}:
10158 @code{RESULT = TIME8()}
10160 @item @emph{Return value}:
10161 The return value is a scalar of type @code{INTEGER(8)}.
10163 @item @emph{See also}:
10164 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
10171 @section @code{TINY} --- Smallest positive number of a real kind
10173 @cindex limits, smallest number
10174 @cindex model representation, smallest number
10177 @item @emph{Description}:
10178 @code{TINY(X)} returns the smallest positive (non zero) number
10179 in the model of the type of @code{X}.
10181 @item @emph{Standard}:
10184 @item @emph{Class}:
10187 @item @emph{Syntax}:
10188 @code{RESULT = TINY(X)}
10190 @item @emph{Arguments}:
10191 @multitable @columnfractions .15 .70
10192 @item @var{X} @tab Shall be of type @code{REAL}.
10195 @item @emph{Return value}:
10196 The return value is of the same type and kind as @var{X}
10198 @item @emph{Example}:
10199 See @code{HUGE} for an example.
10205 @section @code{TRANSFER} --- Transfer bit patterns
10211 @item @emph{Description}:
10212 Interprets the bitwise representation of @var{SOURCE} in memory as if it
10213 is the representation of a variable or array of the same type and type
10214 parameters as @var{MOLD}.
10216 This is approximately equivalent to the C concept of @emph{casting} one
10219 @item @emph{Standard}:
10222 @item @emph{Class}:
10223 Transformational function
10225 @item @emph{Syntax}:
10226 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
10228 @item @emph{Arguments}:
10229 @multitable @columnfractions .15 .70
10230 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
10231 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
10232 @item @var{SIZE} @tab (Optional) shall be a scalar of type
10236 @item @emph{Return value}:
10237 The result has the same type as @var{MOLD}, with the bit level
10238 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
10239 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
10240 but @var{MOLD} is an array (of any size or shape), the result is a one-
10241 dimensional array of the minimum length needed to contain the entirety
10242 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
10243 and @var{MOLD} is a scalar, the result is a scalar.
10245 If the bitwise representation of the result is longer than that of
10246 @var{SOURCE}, then the leading bits of the result correspond to those of
10247 @var{SOURCE} and any trailing bits are filled arbitrarily.
10249 When the resulting bit representation does not correspond to a valid
10250 representation of a variable of the same type as @var{MOLD}, the results
10251 are undefined, and subsequent operations on the result cannot be
10252 guaranteed to produce sensible behavior. For example, it is possible to
10253 create @code{LOGICAL} variables for which @code{@var{VAR}} and
10254 @code{.NOT.@var{VAR}} both appear to be true.
10256 @item @emph{Example}:
10258 PROGRAM test_transfer
10259 integer :: x = 2143289344
10260 print *, transfer(x, 1.0) ! prints "NaN" on i686
10268 @section @code{TRANSPOSE} --- Transpose an array of rank two
10270 @cindex array, transpose
10271 @cindex matrix, transpose
10275 @item @emph{Description}:
10276 Transpose an array of rank two. Element (i, j) of the result has the value
10277 @code{MATRIX(j, i)}, for all i, j.
10279 @item @emph{Standard}:
10282 @item @emph{Class}:
10283 Transformational function
10285 @item @emph{Syntax}:
10286 @code{RESULT = TRANSPOSE(MATRIX)}
10288 @item @emph{Arguments}:
10289 @multitable @columnfractions .15 .70
10290 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
10293 @item @emph{Return value}:
10294 The result has the the same type as @var{MATRIX}, and has shape
10295 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
10301 @section @code{TRIM} --- Remove trailing blank characters of a string
10303 @cindex string, remove trailing whitespace
10306 @item @emph{Description}:
10307 Removes trailing blank characters of a string.
10309 @item @emph{Standard}:
10312 @item @emph{Class}:
10313 Transformational function
10315 @item @emph{Syntax}:
10316 @code{RESULT = TRIM(STRING)}
10318 @item @emph{Arguments}:
10319 @multitable @columnfractions .15 .70
10320 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)}.
10323 @item @emph{Return value}:
10324 A scalar of type @code{CHARACTER(*)} which length is that of @var{STRING}
10325 less the number of trailing blanks.
10327 @item @emph{Example}:
10330 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
10331 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
10335 @item @emph{See also}:
10336 @ref{ADJUSTL}, @ref{ADJUSTR}
10342 @section @code{TTYNAM} --- Get the name of a terminal device.
10344 @cindex system, terminal
10347 @item @emph{Description}:
10348 Get the name of a terminal device. For more information,
10349 see @code{ttyname(3)}.
10351 This intrinsic is provided in both subroutine and function forms;
10352 however, only one form can be used in any given program unit.
10354 @item @emph{Standard}:
10357 @item @emph{Class}:
10358 Subroutine, function
10360 @item @emph{Syntax}:
10361 @multitable @columnfractions .80
10362 @item @code{CALL TTYNAM(UNIT, NAME)}
10363 @item @code{NAME = TTYNAM(UNIT)}
10366 @item @emph{Arguments}:
10367 @multitable @columnfractions .15 .70
10368 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER(*)}.
10369 @item @var{NAME} @tab Shall be of type @code{CHARACTER(*)}.
10372 @item @emph{Example}:
10374 PROGRAM test_ttynam
10377 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
10382 @item @emph{See also}:
10389 @section @code{UBOUND} --- Upper dimension bounds of an array
10391 @cindex array, upper bound
10394 @item @emph{Description}:
10395 Returns the upper bounds of an array, or a single upper bound
10396 along the @var{DIM} dimension.
10397 @item @emph{Standard}:
10400 @item @emph{Class}:
10403 @item @emph{Syntax}:
10404 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
10406 @item @emph{Arguments}:
10407 @multitable @columnfractions .15 .70
10408 @item @var{ARRAY} @tab Shall be an array, of any type.
10409 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER(*)}.
10410 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
10411 expression indicating the kind parameter of
10415 @item @emph{Return value}:
10416 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10417 @var{KIND} is absent, the return value is of default integer kind.
10418 If @var{DIM} is absent, the result is an array of the upper bounds of
10419 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
10420 corresponding to the upper bound of the array along that dimension. If
10421 @var{ARRAY} is an expression rather than a whole array or array
10422 structure component, or if it has a zero extent along the relevant
10423 dimension, the upper bound is taken to be the number of elements along
10424 the relevant dimension.
10426 @item @emph{See also}:
10433 @section @code{UMASK} --- Set the file creation mask
10435 @cindex file system, file creation mask
10438 @item @emph{Description}:
10439 Sets the file creation mask to @var{MASK} and returns the old value in
10440 argument @var{OLD} if it is supplied. See @code{umask(2)}.
10442 @item @emph{Standard}:
10445 @item @emph{Class}:
10448 @item @emph{Syntax}:
10449 @code{CALL UMASK(MASK [, OLD])}
10451 @item @emph{Arguments}:
10452 @multitable @columnfractions .15 .70
10453 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER(*)}.
10454 @item @var{MASK} @tab (Optional) Shall be a scalar of type
10463 @section @code{UNLINK} --- Remove a file from the file system
10465 @cindex file system, remove file
10468 @item @emph{Description}:
10469 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
10470 used to mark the end of the name in @var{PATH}; otherwise, trailing
10471 blanks in the file name are ignored. If the @var{STATUS} argument is
10472 supplied, it contains 0 on success or a nonzero error code upon return;
10473 see @code{unlink(2)}.
10475 This intrinsic is provided in both subroutine and function forms;
10476 however, only one form can be used in any given program unit.
10478 @item @emph{Standard}:
10481 @item @emph{Class}:
10482 Subroutine, function
10484 @item @emph{Syntax}:
10485 @multitable @columnfractions .80
10486 @item @code{CALL UNLINK(PATH [, STATUS])}
10487 @item @code{STATUS = UNLINK(PATH)}
10490 @item @emph{Arguments}:
10491 @multitable @columnfractions .15 .70
10492 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
10493 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10496 @item @emph{See also}:
10497 @ref{LINK}, @ref{SYMLNK}
10503 @section @code{UNPACK} --- Unpack an array of rank one into an array
10505 @cindex array, unpacking
10506 @cindex array, increase dimension
10507 @cindex array, scatter elements
10510 @item @emph{Description}:
10511 Store the elements of @var{VECTOR} in an array of higher rank.
10513 @item @emph{Standard}:
10516 @item @emph{Class}:
10517 Transformational function
10519 @item @emph{Syntax}:
10520 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
10522 @item @emph{Arguments}:
10523 @multitable @columnfractions .15 .70
10524 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
10525 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
10526 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
10527 @item @var{FIELD} @tab Shall be of the sam type as @var{VECTOR} and have
10528 the same shape as @var{MASK}.
10531 @item @emph{Return value}:
10532 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
10533 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
10535 @item @emph{Example}:
10537 PROGRAM test_unpack
10538 integer :: vector(2) = (/1,1/)
10539 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
10540 integer :: field(2,2) = 0, unity(2,2)
10542 ! result: unity matrix
10543 unity = unpack(vector, reshape(mask, (/2,2/)), field)
10547 @item @emph{See also}:
10548 @ref{PACK}, @ref{SPREAD}
10554 @section @code{VERIFY} --- Scan a string for the absence of a set of characters
10556 @cindex string, find missing set
10559 @item @emph{Description}:
10560 Verifies that all the characters in a @var{SET} are present in a @var{STRING}.
10562 If @var{BACK} is either absent or equals @code{FALSE}, this function
10563 returns the position of the leftmost character of @var{STRING} that is
10564 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
10565 is returned. If all characters of @var{SET} are found in @var{STRING}, the
10568 @item @emph{Standard}:
10571 @item @emph{Class}:
10574 @item @emph{Syntax}:
10575 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
10577 @item @emph{Arguments}:
10578 @multitable @columnfractions .15 .70
10579 @item @var{STRING} @tab Shall be of type @code{CHARACTER(*)}.
10580 @item @var{SET} @tab Shall be of type @code{CHARACTER(*)}.
10581 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
10582 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10583 expression indicating the kind parameter of
10587 @item @emph{Return value}:
10588 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10589 @var{KIND} is absent, the return value is of default integer kind.
10591 @item @emph{Example}:
10593 PROGRAM test_verify
10594 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
10595 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
10596 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
10597 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
10598 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
10602 @item @emph{See also}:
10603 @ref{SCAN}, @ref{INDEX}
10609 @section @code{XOR} --- Bitwise logical exclusive OR
10611 @cindex bitwise logical exclusive or
10612 @cindex logical exclusive or, bitwise
10615 @item @emph{Description}:
10616 Bitwise logical exclusive or.
10618 This intrinsic routine is provided for backwards compatibility with
10619 GNU Fortran 77. For integer arguments, programmers should consider
10620 the use of the @ref{IEOR} intrinsic defined by the Fortran standard.
10622 @item @emph{Standard}:
10625 @item @emph{Class}:
10628 @item @emph{Syntax}:
10629 @code{RESULT = XOR(X, Y)}
10631 @item @emph{Arguments}:
10632 @multitable @columnfractions .15 .70
10633 @item @var{X} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
10634 @item @var{Y} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
10637 @item @emph{Return value}:
10638 The return type is either @code{INTEGER(*)} or @code{LOGICAL}
10639 after cross-promotion of the arguments.
10641 @item @emph{Example}:
10644 LOGICAL :: T = .TRUE., F = .FALSE.
10646 DATA a / Z'F' /, b / Z'3' /
10648 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
10649 WRITE (*,*) XOR(a, b)
10653 @item @emph{See also}:
10654 F95 elemental function: @ref{IEOR}