2 Copyright (C) 2005, 2006, 2007, 2008, 2009
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 ``Funding Free Software'', the Front-Cover
11 Texts being (a) (see below), and with the Back-Cover Texts being (b)
12 (see below). A copy of the license is included in the gfdl(7) man page.
15 Some basic guidelines for editing this document:
17 (1) The intrinsic procedures are to be listed in alphabetical order.
18 (2) The generic name is to be used.
19 (3) The specific names are included in the function index and in a
20 table at the end of the node (See ABS entry).
21 (4) Try to maintain the same style for each entry.
27 \gdef\acos{\mathop{\rm acos}\nolimits}
28 \gdef\asin{\mathop{\rm asin}\nolimits}
29 \gdef\atan{\mathop{\rm atan}\nolimits}
30 \gdef\acosh{\mathop{\rm acosh}\nolimits}
31 \gdef\asinh{\mathop{\rm asinh}\nolimits}
32 \gdef\atanh{\mathop{\rm atanh}\nolimits}
36 @node Intrinsic Procedures
37 @chapter Intrinsic Procedures
38 @cindex intrinsic procedures
41 * Introduction: Introduction to Intrinsics
42 * @code{ABORT}: ABORT, Abort the program
43 * @code{ABS}: ABS, Absolute value
44 * @code{ACCESS}: ACCESS, Checks file access modes
45 * @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence
46 * @code{ACOS}: ACOS, Arccosine function
47 * @code{ACOSH}: ACOSH, Hyperbolic arccosine function
48 * @code{ADJUSTL}: ADJUSTL, Left adjust a string
49 * @code{ADJUSTR}: ADJUSTR, Right adjust a string
50 * @code{AIMAG}: AIMAG, Imaginary part of complex number
51 * @code{AINT}: AINT, Truncate to a whole number
52 * @code{ALARM}: ALARM, Set an alarm clock
53 * @code{ALL}: ALL, Determine if all values are true
54 * @code{ALLOCATED}: ALLOCATED, Status of allocatable entity
55 * @code{AND}: AND, Bitwise logical AND
56 * @code{ANINT}: ANINT, Nearest whole number
57 * @code{ANY}: ANY, Determine if any values are true
58 * @code{ASIN}: ASIN, Arcsine function
59 * @code{ASINH}: ASINH, Hyperbolic arcsine function
60 * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair
61 * @code{ATAN}: ATAN, Arctangent function
62 * @code{ATAN2}: ATAN2, Arctangent function
63 * @code{ATANH}: ATANH, Hyperbolic arctangent function
64 * @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0
65 * @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1
66 * @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind
67 * @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0
68 * @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1
69 * @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind
70 * @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function
71 * @code{BTEST}: BTEST, Bit test function
72 * @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer
73 * @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer
74 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
75 * @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure
76 * @code{C_LOC}: C_LOC, Obtain the C address of an object
77 * @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression
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{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function
107 * @code{ETIME}: ETIME, Execution time subroutine (or function)
108 * @code{EXIT}: EXIT, Exit the program with status.
109 * @code{EXP}: EXP, Exponential function
110 * @code{EXPONENT}: EXPONENT, Exponent function
111 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
112 * @code{FGET}: FGET, Read a single character in stream mode from stdin
113 * @code{FGETC}: FGETC, Read a single character in stream mode
114 * @code{FLOAT}: FLOAT, Convert integer to default real
115 * @code{FLOOR}: FLOOR, Integer floor function
116 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
117 * @code{FNUM}: FNUM, File number function
118 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
119 * @code{FPUTC}: FPUTC, Write a single character in stream mode
120 * @code{FRACTION}: FRACTION, Fractional part of the model representation
121 * @code{FREE}: FREE, Memory de-allocation subroutine
122 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
123 * @code{FSTAT}: FSTAT, Get file status
124 * @code{FTELL}: FTELL, Current stream position
125 * @code{GAMMA}: GAMMA, Gamma function
126 * @code{GERROR}: GERROR, Get last system error message
127 * @code{GETARG}: GETARG, Get command line arguments
128 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
129 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
130 * @code{GETCWD}: GETCWD, Get current working directory
131 * @code{GETENV}: GETENV, Get an environmental variable
132 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
133 * @code{GETGID}: GETGID, Group ID function
134 * @code{GETLOG}: GETLOG, Get login name
135 * @code{GETPID}: GETPID, Process ID function
136 * @code{GETUID}: GETUID, User ID function
137 * @code{GMTIME}: GMTIME, Convert time to GMT info
138 * @code{HOSTNM}: HOSTNM, Get system host name
139 * @code{HUGE}: HUGE, Largest number of a kind
140 * @code{HYPOT}: HYPOT, Euclidian distance function
141 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
142 * @code{IAND}: IAND, Bitwise logical and
143 * @code{IARGC}: IARGC, Get the number of command line arguments
144 * @code{IBCLR}: IBCLR, Clear bit
145 * @code{IBITS}: IBITS, Bit extraction
146 * @code{IBSET}: IBSET, Set bit
147 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
148 * @code{IDATE}: IDATE, Current local time (day/month/year)
149 * @code{IEOR}: IEOR, Bitwise logical exclusive or
150 * @code{IERRNO}: IERRNO, Function to get the last system error number
151 * @code{INDEX}: INDEX intrinsic, Position of a substring within a string
152 * @code{INT}: INT, Convert to integer type
153 * @code{INT2}: INT2, Convert to 16-bit integer type
154 * @code{INT8}: INT8, Convert to 64-bit integer type
155 * @code{IOR}: IOR, Bitwise logical or
156 * @code{IRAND}: IRAND, Integer pseudo-random number
157 * @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value
158 * @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value
159 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
160 * @code{ISHFT}: ISHFT, Shift bits
161 * @code{ISHFTC}: ISHFTC, Shift bits circularly
162 * @code{ISNAN}: ISNAN, Tests for a NaN
163 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
164 * @code{KILL}: KILL, Send a signal to a process
165 * @code{KIND}: KIND, Kind of an entity
166 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
167 * @code{LEADZ}: LEADZ, Number of leading zero bits of an integer
168 * @code{LEN}: LEN, Length of a character entity
169 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
170 * @code{LGE}: LGE, Lexical greater than or equal
171 * @code{LGT}: LGT, Lexical greater than
172 * @code{LINK}: LINK, Create a hard link
173 * @code{LLE}: LLE, Lexical less than or equal
174 * @code{LLT}: LLT, Lexical less than
175 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
176 * @code{LOC}: LOC, Returns the address of a variable
177 * @code{LOG}: LOG, Logarithm function
178 * @code{LOG10}: LOG10, Base 10 logarithm function
179 * @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
180 * @code{LOGICAL}: LOGICAL, Convert to logical type
181 * @code{LONG}: LONG, Convert to integer type
182 * @code{LSHIFT}: LSHIFT, Left shift bits
183 * @code{LSTAT}: LSTAT, Get file status
184 * @code{LTIME}: LTIME, Convert time to local time info
185 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
186 * @code{MATMUL}: MATMUL, matrix multiplication
187 * @code{MAX}: MAX, Maximum value of an argument list
188 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
189 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
190 * @code{MAXVAL}: MAXVAL, Maximum value of an array
191 * @code{MCLOCK}: MCLOCK, Time function
192 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
193 * @code{MERGE}: MERGE, Merge arrays
194 * @code{MIN}: MIN, Minimum value of an argument list
195 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
196 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
197 * @code{MINVAL}: MINVAL, Minimum value of an array
198 * @code{MOD}: MOD, Remainder function
199 * @code{MODULO}: MODULO, Modulo function
200 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
201 * @code{MVBITS}: MVBITS, Move bits from one integer to another
202 * @code{NEAREST}: NEAREST, Nearest representable number
203 * @code{NEW_LINE}: NEW_LINE, New line character
204 * @code{NINT}: NINT, Nearest whole number
205 * @code{NOT}: NOT, Logical negation
206 * @code{NULL}: NULL, Function that returns an disassociated pointer
207 * @code{OR}: OR, Bitwise logical OR
208 * @code{PACK}: PACK, Pack an array into an array of rank one
209 * @code{PERROR}: PERROR, Print system error message
210 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
211 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
212 * @code{PRODUCT}: PRODUCT, Product of array elements
213 * @code{RADIX}: RADIX, Base of a data model
214 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
215 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
216 * @code{RAND}: RAND, Real pseudo-random number
217 * @code{RANGE}: RANGE, Decimal exponent range
218 * @code{RAN}: RAN, Real pseudo-random number
219 * @code{REAL}: REAL, Convert to real type
220 * @code{RENAME}: RENAME, Rename a file
221 * @code{REPEAT}: REPEAT, Repeated string concatenation
222 * @code{RESHAPE}: RESHAPE, Function to reshape an array
223 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
224 * @code{RSHIFT}: RSHIFT, Right shift bits
225 * @code{SCALE}: SCALE, Scale a real value
226 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
227 * @code{SECNDS}: SECNDS, Time function
228 * @code{SECOND}: SECOND, CPU time function
229 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind
230 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
231 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
232 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
233 * @code{SHAPE}: SHAPE, Determine the shape of an array
234 * @code{SIGN}: SIGN, Sign copying function
235 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
236 * @code{SIN}: SIN, Sine function
237 * @code{SINH}: SINH, Hyperbolic sine function
238 * @code{SIZE}: SIZE, Function to determine the size of an array
239 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
240 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
241 * @code{SNGL}: SNGL, Convert double precision real to default real
242 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
243 * @code{SPREAD}: SPREAD, Add a dimension to an array
244 * @code{SQRT}: SQRT, Square-root function
245 * @code{SRAND}: SRAND, Reinitialize the random number generator
246 * @code{STAT}: STAT, Get file status
247 * @code{SUM}: SUM, Sum of array elements
248 * @code{SYMLNK}: SYMLNK, Create a symbolic link
249 * @code{SYSTEM}: SYSTEM, Execute a shell command
250 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
251 * @code{TAN}: TAN, Tangent function
252 * @code{TANH}: TANH, Hyperbolic tangent function
253 * @code{TIME}: TIME, Time function
254 * @code{TIME8}: TIME8, Time function (64-bit)
255 * @code{TINY}: TINY, Smallest positive number of a real kind
256 * @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer
257 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
258 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
259 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
260 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
261 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
262 * @code{UMASK}: UMASK, Set the file creation mask
263 * @code{UNLINK}: UNLINK, Remove a file from the file system
264 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
265 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
266 * @code{XOR}: XOR, Bitwise logical exclusive or
269 @node Introduction to Intrinsics
270 @section Introduction to intrinsic procedures
272 The intrinsic procedures provided by GNU Fortran include all of the
273 intrinsic procedures required by the Fortran 95 standard, a set of
274 intrinsic procedures for backwards compatibility with G77, and a
275 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
276 standards. Any conflict between a description here and a description in
277 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
278 2008 standard is unintentional, and the standard(s) should be considered
281 The enumeration of the @code{KIND} type parameter is processor defined in
282 the Fortran 95 standard. GNU Fortran defines the default integer type and
283 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
284 respectively. The standard mandates that both data types shall have
285 another kind, which have more precision. On typical target architectures
286 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
287 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
288 In the description of generic intrinsic procedures, the kind type parameter
289 will be specified by @code{KIND=*}, and in the description of specific
290 names for an intrinsic procedure the kind type parameter will be explicitly
291 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
292 brevity the optional @code{KIND=} syntax will be omitted.
294 Many of the intrinsic procedures take one or more optional arguments.
295 This document follows the convention used in the Fortran 95 standard,
296 and denotes such arguments by square brackets.
298 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
299 which can be used to restrict the set of intrinsic procedures to a
300 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
301 option, and so all intrinsic procedures described here are accepted. There
302 is one caveat. For a select group of intrinsic procedures, @command{g77}
303 implemented both a function and a subroutine. Both classes
304 have been implemented in @command{gfortran} for backwards compatibility
305 with @command{g77}. It is noted here that these functions and subroutines
306 cannot be intermixed in a given subprogram. In the descriptions that follow,
307 the applicable standard for each intrinsic procedure is noted.
312 @section @code{ABORT} --- Abort the program
314 @cindex program termination, with core dump
315 @cindex terminate program, with core dump
319 @item @emph{Description}:
320 @code{ABORT} causes immediate termination of the program. On operating
321 systems that support a core dump, @code{ABORT} will produce a core dump even if
322 the option @option{-fno-dump-core} is in effect, which is suitable for debugging
324 @c TODO: Check if this (with -fno-dump-core) is correct.
326 @item @emph{Standard}:
335 @item @emph{Return value}:
338 @item @emph{Example}:
341 integer :: i = 1, j = 2
342 if (i /= j) call abort
343 end program test_abort
346 @item @emph{See also}:
347 @ref{EXIT}, @ref{KILL}
354 @section @code{ABS} --- Absolute value
361 @cindex absolute value
364 @item @emph{Description}:
365 @code{ABS(A)} computes the absolute value of @code{A}.
367 @item @emph{Standard}:
368 Fortran 77 and later, has overloads that are GNU extensions
374 @code{RESULT = ABS(A)}
376 @item @emph{Arguments}:
377 @multitable @columnfractions .15 .70
378 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
379 @code{REAL}, or @code{COMPLEX}.
382 @item @emph{Return value}:
383 The return value is of the same type and
384 kind as the argument except the return value is @code{REAL} for a
385 @code{COMPLEX} argument.
387 @item @emph{Example}:
392 complex :: z = (-1.e0,0.e0)
399 @item @emph{Specific names}:
400 @multitable @columnfractions .20 .20 .20 .25
401 @item Name @tab Argument @tab Return type @tab Standard
402 @item @code{CABS(A)} @tab @code{COMPLEX(4) Z} @tab @code{REAL(4)} @tab Fortran 77 and later
403 @item @code{DABS(A)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
404 @item @code{IABS(A)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab Fortran 77 and later
405 @item @code{ZABS(A)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
406 @item @code{CDABS(A)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
413 @section @code{ACCESS} --- Checks file access modes
415 @cindex file system, access mode
418 @item @emph{Description}:
419 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
420 exists, is readable, writable or executable. Except for the
421 executable check, @code{ACCESS} can be replaced by
422 Fortran 95's @code{INQUIRE}.
424 @item @emph{Standard}:
431 @code{RESULT = ACCESS(NAME, MODE)}
433 @item @emph{Arguments}:
434 @multitable @columnfractions .15 .70
435 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
436 file name. Tailing blank are ignored unless the character @code{achar(0)}
437 is present, then all characters up to and excluding @code{achar(0)} are
439 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
440 file access mode, may be any concatenation of @code{"r"} (readable),
441 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
445 @item @emph{Return value}:
446 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
447 accessible in the given mode; otherwise or if an invalid argument
448 has been given for @code{MODE} the value @code{1} is returned.
450 @item @emph{Example}:
454 character(len=*), parameter :: file = 'test.dat'
455 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
456 if(access(file,' ') == 0) print *, trim(file),' is exists'
457 if(access(file,'r') == 0) print *, trim(file),' is readable'
458 if(access(file,'w') == 0) print *, trim(file),' is writable'
459 if(access(file,'x') == 0) print *, trim(file),' is executable'
460 if(access(file2,'rwx') == 0) &
461 print *, trim(file2),' is readable, writable and executable'
462 end program access_test
464 @item @emph{Specific names}:
465 @item @emph{See also}:
472 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
474 @cindex @acronym{ASCII} collating sequence
475 @cindex collating sequence, @acronym{ASCII}
478 @item @emph{Description}:
479 @code{ACHAR(I)} returns the character located at position @code{I}
480 in the @acronym{ASCII} collating sequence.
482 @item @emph{Standard}:
483 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
489 @code{RESULT = ACHAR(I [, KIND])}
491 @item @emph{Arguments}:
492 @multitable @columnfractions .15 .70
493 @item @var{I} @tab The type shall be @code{INTEGER}.
494 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
495 expression indicating the kind parameter of the result.
498 @item @emph{Return value}:
499 The return value is of type @code{CHARACTER} with a length of one.
500 If the @var{KIND} argument is present, the return value is of the
501 specified kind and of the default kind otherwise.
503 @item @emph{Example}:
508 end program test_achar
512 See @ref{ICHAR} for a discussion of converting between numerical values
513 and formatted string representations.
515 @item @emph{See also}:
516 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
523 @section @code{ACOS} --- Arccosine function
526 @cindex trigonometric function, cosine, inverse
527 @cindex cosine, inverse
530 @item @emph{Description}:
531 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
533 @item @emph{Standard}:
540 @code{RESULT = ACOS(X)}
542 @item @emph{Arguments}:
543 @multitable @columnfractions .15 .70
544 @item @var{X} @tab The type shall be @code{REAL} with a magnitude that is
545 less than or equal to one.
548 @item @emph{Return value}:
549 The return value is of type @code{REAL} and it lies in the
550 range @math{ 0 \leq \acos(x) \leq \pi}. The return value if of the same
553 @item @emph{Example}:
556 real(8) :: x = 0.866_8
558 end program test_acos
561 @item @emph{Specific names}:
562 @multitable @columnfractions .20 .20 .20 .25
563 @item Name @tab Argument @tab Return type @tab Standard
564 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
567 @item @emph{See also}:
568 Inverse function: @ref{COS}
575 @section @code{ACOSH} --- Hyperbolic arccosine function
578 @cindex area hyperbolic cosine
579 @cindex hyperbolic arccosine
580 @cindex hyperbolic function, cosine, inverse
581 @cindex cosine, hyperbolic, inverse
584 @item @emph{Description}:
585 @code{ACOSH(X)} computes the hyperbolic arccosine of @var{X} (inverse of
588 @item @emph{Standard}:
589 Fortran 2008 and later
595 @code{RESULT = ACOSH(X)}
597 @item @emph{Arguments}:
598 @multitable @columnfractions .15 .70
599 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
602 @item @emph{Return value}:
603 The return value has the same type and kind as @var{X}
605 @item @emph{Example}:
608 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
613 @item @emph{Specific names}:
614 @multitable @columnfractions .20 .20 .20 .25
615 @item Name @tab Argument @tab Return type @tab Standard
616 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
619 @item @emph{See also}:
620 Inverse function: @ref{COSH}
626 @section @code{ADJUSTL} --- Left adjust a string
628 @cindex string, adjust left
629 @cindex adjust string
632 @item @emph{Description}:
633 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
634 Spaces are inserted at the end of the string as needed.
636 @item @emph{Standard}:
643 @code{RESULT = ADJUSTL(STRING)}
645 @item @emph{Arguments}:
646 @multitable @columnfractions .15 .70
647 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
650 @item @emph{Return value}:
651 The return value is of type @code{CHARACTER} and of the same kind as
652 @var{STRING} where leading spaces are removed and the same number of
653 spaces are inserted on the end of @var{STRING}.
655 @item @emph{Example}:
658 character(len=20) :: str = ' gfortran'
661 end program test_adjustl
664 @item @emph{See also}:
665 @ref{ADJUSTR}, @ref{TRIM}
671 @section @code{ADJUSTR} --- Right adjust a string
673 @cindex string, adjust right
674 @cindex adjust string
677 @item @emph{Description}:
678 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
679 Spaces are inserted at the start of the string as needed.
681 @item @emph{Standard}:
688 @code{RESULT = ADJUSTR(STRING)}
690 @item @emph{Arguments}:
691 @multitable @columnfractions .15 .70
692 @item @var{STR} @tab The type shall be @code{CHARACTER}.
695 @item @emph{Return value}:
696 The return value is of type @code{CHARACTER} and of the same kind as
697 @var{STRING} where trailing spaces are removed and the same number of
698 spaces are inserted at the start of @var{STRING}.
700 @item @emph{Example}:
703 character(len=20) :: str = 'gfortran'
706 end program test_adjustr
709 @item @emph{See also}:
710 @ref{ADJUSTL}, @ref{TRIM}
716 @section @code{AIMAG} --- Imaginary part of complex number
721 @cindex complex numbers, imaginary part
724 @item @emph{Description}:
725 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
726 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
727 for compatibility with @command{g77}, and their use in new code is
728 strongly discouraged.
730 @item @emph{Standard}:
731 Fortran 77 and later, has overloads that are GNU extensions
737 @code{RESULT = AIMAG(Z)}
739 @item @emph{Arguments}:
740 @multitable @columnfractions .15 .70
741 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
744 @item @emph{Return value}:
745 The return value is of type @code{REAL} with the
746 kind type parameter of the argument.
748 @item @emph{Example}:
753 z4 = cmplx(1.e0_4, 0.e0_4)
754 z8 = cmplx(0.e0_8, 1.e0_8)
755 print *, aimag(z4), dimag(z8)
756 end program test_aimag
759 @item @emph{Specific names}:
760 @multitable @columnfractions .20 .20 .20 .25
761 @item Name @tab Argument @tab Return type @tab Standard
762 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
763 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
764 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
771 @section @code{AINT} --- Truncate to a whole number
775 @cindex rounding, floor
778 @item @emph{Description}:
779 @code{AINT(A [, KIND])} truncates its argument to a whole number.
781 @item @emph{Standard}:
788 @code{RESULT = AINT(A [, KIND])}
790 @item @emph{Arguments}:
791 @multitable @columnfractions .15 .70
792 @item @var{A} @tab The type of the argument shall be @code{REAL}.
793 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
794 expression indicating the kind parameter of the result.
797 @item @emph{Return value}:
798 The return value is of type @code{REAL} with the kind type parameter of the
799 argument if the optional @var{KIND} is absent; otherwise, the kind
800 type parameter will be given by @var{KIND}. If the magnitude of
801 @var{X} is less than one, @code{AINT(X)} returns zero. If the
802 magnitude is equal to or greater than one then it returns the largest
803 whole number that does not exceed its magnitude. The sign is the same
804 as the sign of @var{X}.
806 @item @emph{Example}:
813 print *, aint(x4), dint(x8)
815 end program test_aint
818 @item @emph{Specific names}:
819 @multitable @columnfractions .20 .20 .20 .25
820 @item Name @tab Argument @tab Return type @tab Standard
821 @item @code{DINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
828 @section @code{ALARM} --- Execute a routine after a given delay
830 @cindex delayed execution
833 @item @emph{Description}:
834 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
835 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
836 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
837 supplied, it will be returned with the number of seconds remaining until
838 any previously scheduled alarm was due to be delivered, or zero if there
839 was no previously scheduled alarm.
841 @item @emph{Standard}:
848 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
850 @item @emph{Arguments}:
851 @multitable @columnfractions .15 .70
852 @item @var{SECONDS} @tab The type of the argument shall be a scalar
853 @code{INTEGER}. It is @code{INTENT(IN)}.
854 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
855 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
856 values may be either @code{SIG_IGN=1} to ignore the alarm generated
857 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
858 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
859 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
862 @item @emph{Example}:
865 external handler_print
867 call alarm (3, handler_print, i)
870 end program test_alarm
872 This will cause the external routine @var{handler_print} to be called
879 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
881 @cindex array, apply condition
882 @cindex array, condition testing
885 @item @emph{Description}:
886 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
887 in the array along dimension @var{DIM}.
889 @item @emph{Standard}:
893 Transformational function
896 @code{RESULT = ALL(MASK [, DIM])}
898 @item @emph{Arguments}:
899 @multitable @columnfractions .15 .70
900 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
901 it shall not be scalar.
902 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
903 with a value that lies between one and the rank of @var{MASK}.
906 @item @emph{Return value}:
907 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
908 the kind type parameter is the same as the kind type parameter of
909 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
910 an array with the rank of @var{MASK} minus 1. The shape is determined from
911 the shape of @var{MASK} where the @var{DIM} dimension is elided.
915 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
916 It also is true if @var{MASK} has zero size; otherwise, it is false.
918 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
919 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
920 is determined by applying @code{ALL} to the array sections.
923 @item @emph{Example}:
927 l = all((/.true., .true., .true./))
932 integer a(2,3), b(2,3)
936 print *, all(a .eq. b, 1)
937 print *, all(a .eq. b, 2)
938 end subroutine section
946 @section @code{ALLOCATED} --- Status of an allocatable entity
948 @cindex allocation, status
951 @item @emph{Description}:
952 @code{ALLOCATED(ARRAY)} checks the status of whether @var{X} is allocated.
954 @item @emph{Standard}:
961 @code{RESULT = ALLOCATED(ARRAY)}
963 @item @emph{Arguments}:
964 @multitable @columnfractions .15 .70
965 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
968 @item @emph{Return value}:
969 The return value is a scalar @code{LOGICAL} with the default logical
970 kind type parameter. If @var{ARRAY} is allocated, @code{ALLOCATED(ARRAY)}
971 is @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
973 @item @emph{Example}:
975 program test_allocated
977 real(4), allocatable :: x(:)
978 if (.not. allocated(x)) allocate(x(i))
979 end program test_allocated
986 @section @code{AND} --- Bitwise logical AND
988 @cindex bitwise logical and
989 @cindex logical and, bitwise
992 @item @emph{Description}:
993 Bitwise logical @code{AND}.
995 This intrinsic routine is provided for backwards compatibility with
996 GNU Fortran 77. For integer arguments, programmers should consider
997 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
999 @item @emph{Standard}:
1005 @item @emph{Syntax}:
1006 @code{RESULT = AND(I, J)}
1008 @item @emph{Arguments}:
1009 @multitable @columnfractions .15 .70
1010 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1011 type or a scalar @code{LOGICAL} type.
1012 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1015 @item @emph{Return value}:
1016 The return type is either a scalar @code{INTEGER} or a scalar
1017 @code{LOGICAL}. If the kind type parameters differ, then the
1018 smaller kind type is implicitly converted to larger kind, and the
1019 return has the larger kind.
1021 @item @emph{Example}:
1024 LOGICAL :: T = .TRUE., F = .FALSE.
1026 DATA a / Z'F' /, b / Z'3' /
1028 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1029 WRITE (*,*) AND(a, b)
1033 @item @emph{See also}:
1034 Fortran 95 elemental function: @ref{IAND}
1040 @section @code{ANINT} --- Nearest whole number
1044 @cindex rounding, ceiling
1047 @item @emph{Description}:
1048 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1050 @item @emph{Standard}:
1051 Fortran 77 and later
1056 @item @emph{Syntax}:
1057 @code{RESULT = ANINT(A [, KIND])}
1059 @item @emph{Arguments}:
1060 @multitable @columnfractions .15 .70
1061 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1062 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1063 expression indicating the kind parameter of the result.
1066 @item @emph{Return value}:
1067 The return value is of type real with the kind type parameter of the
1068 argument if the optional @var{KIND} is absent; otherwise, the kind
1069 type parameter will be given by @var{KIND}. If @var{A} is greater than
1070 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1071 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1073 @item @emph{Example}:
1080 print *, anint(x4), dnint(x8)
1082 end program test_anint
1085 @item @emph{Specific names}:
1086 @multitable @columnfractions .20 .20 .20 .25
1087 @item Name @tab Argument @tab Return type @tab Standard
1088 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1095 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1097 @cindex array, apply condition
1098 @cindex array, condition testing
1101 @item @emph{Description}:
1102 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1103 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1105 @item @emph{Standard}:
1106 Fortran 95 and later
1109 Transformational function
1111 @item @emph{Syntax}:
1112 @code{RESULT = ANY(MASK [, DIM])}
1114 @item @emph{Arguments}:
1115 @multitable @columnfractions .15 .70
1116 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1117 it shall not be scalar.
1118 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1119 with a value that lies between one and the rank of @var{MASK}.
1122 @item @emph{Return value}:
1123 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1124 the kind type parameter is the same as the kind type parameter of
1125 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1126 an array with the rank of @var{MASK} minus 1. The shape is determined from
1127 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1131 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1132 otherwise, it is false. It also is false if @var{MASK} has zero size.
1134 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1135 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1136 is determined by applying @code{ANY} to the array sections.
1139 @item @emph{Example}:
1143 l = any((/.true., .true., .true./))
1148 integer a(2,3), b(2,3)
1152 print *, any(a .eq. b, 1)
1153 print *, any(a .eq. b, 2)
1154 end subroutine section
1155 end program test_any
1162 @section @code{ASIN} --- Arcsine function
1165 @cindex trigonometric function, sine, inverse
1166 @cindex sine, inverse
1169 @item @emph{Description}:
1170 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1172 @item @emph{Standard}:
1173 Fortran 77 and later
1178 @item @emph{Syntax}:
1179 @code{RESULT = ASIN(X)}
1181 @item @emph{Arguments}:
1182 @multitable @columnfractions .15 .70
1183 @item @var{X} @tab The type shall be @code{REAL}, and a magnitude that is
1184 less than or equal to one.
1187 @item @emph{Return value}:
1188 The return value is of type @code{REAL} and it lies in the
1189 range @math{-\pi / 2 \leq \asin (x) \leq \pi / 2}. The kind type
1190 parameter is the same as @var{X}.
1192 @item @emph{Example}:
1195 real(8) :: x = 0.866_8
1197 end program test_asin
1200 @item @emph{Specific names}:
1201 @multitable @columnfractions .20 .20 .20 .25
1202 @item Name @tab Argument @tab Return type @tab Standard
1203 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1206 @item @emph{See also}:
1207 Inverse function: @ref{SIN}
1214 @section @code{ASINH} --- Hyperbolic arcsine function
1217 @cindex area hyperbolic sine
1218 @cindex hyperbolic arcsine
1219 @cindex hyperbolic function, sine, inverse
1220 @cindex sine, hyperbolic, inverse
1223 @item @emph{Description}:
1224 @code{ASINH(X)} computes the hyperbolic arcsine of @var{X} (inverse of @code{SINH(X)}).
1226 @item @emph{Standard}:
1227 Fortran 2008 and later
1232 @item @emph{Syntax}:
1233 @code{RESULT = ASINH(X)}
1235 @item @emph{Arguments}:
1236 @multitable @columnfractions .15 .70
1237 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1240 @item @emph{Return value}:
1241 The return value is of the same type and kind as @var{X}.
1243 @item @emph{Example}:
1246 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1247 WRITE (*,*) ASINH(x)
1251 @item @emph{Specific names}:
1252 @multitable @columnfractions .20 .20 .20 .25
1253 @item Name @tab Argument @tab Return type @tab Standard
1254 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1257 @item @emph{See also}:
1258 Inverse function: @ref{SINH}
1264 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1266 @cindex pointer, status
1267 @cindex association status
1270 @item @emph{Description}:
1271 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1272 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1274 @item @emph{Standard}:
1275 Fortran 95 and later
1280 @item @emph{Syntax}:
1281 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1283 @item @emph{Arguments}:
1284 @multitable @columnfractions .15 .70
1285 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1286 and it can be of any type.
1287 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1288 a target. It must have the same type, kind type parameter, and
1289 array rank as @var{POINTER}.
1291 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1294 @item @emph{Return value}:
1295 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1296 There are several cases:
1298 @item (A) When the optional @var{TARGET} is not present then
1299 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1300 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1301 @var{TARGET} is not a zero-sized storage sequence and the target associated with @var{POINTER} occupies the same storage units. If @var{POINTER} is
1302 disassociated, the result is false.
1303 @item (C) If @var{TARGET} is present and an array target, the result is true if
1304 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1305 are arrays whose elements are not zero-sized storage sequences, and
1306 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1308 As in case(B), the result is false, if @var{POINTER} is disassociated.
1309 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1310 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1311 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1313 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1314 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1315 target associated with @var{POINTER} and the target associated with @var{TARGET}
1316 have the same shape, are not zero-sized arrays, are arrays whose elements are
1317 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1318 the same storage units in array element order.
1319 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1322 @item @emph{Example}:
1324 program test_associated
1326 real, target :: tgt(2) = (/1., 2./)
1327 real, pointer :: ptr(:)
1329 if (associated(ptr) .eqv. .false.) call abort
1330 if (associated(ptr,tgt) .eqv. .false.) call abort
1331 end program test_associated
1334 @item @emph{See also}:
1341 @section @code{ATAN} --- Arctangent function
1344 @cindex trigonometric function, tangent, inverse
1345 @cindex tangent, inverse
1348 @item @emph{Description}:
1349 @code{ATAN(X)} computes the arctangent of @var{X}.
1351 @item @emph{Standard}:
1352 Fortran 77 and later
1357 @item @emph{Syntax}:
1358 @code{RESULT = ATAN(X)}
1360 @item @emph{Arguments}:
1361 @multitable @columnfractions .15 .70
1362 @item @var{X} @tab The type shall be @code{REAL}.
1365 @item @emph{Return value}:
1366 The return value is of type @code{REAL} and it lies in the
1367 range @math{ - \pi / 2 \leq \atan (x) \leq \pi / 2}.
1369 @item @emph{Example}:
1372 real(8) :: x = 2.866_8
1374 end program test_atan
1377 @item @emph{Specific names}:
1378 @multitable @columnfractions .20 .20 .20 .25
1379 @item Name @tab Argument @tab Return type @tab Standard
1380 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1383 @item @emph{See also}:
1384 Inverse function: @ref{TAN}
1391 @section @code{ATAN2} --- Arctangent function
1394 @cindex trigonometric function, tangent, inverse
1395 @cindex tangent, inverse
1398 @item @emph{Description}:
1399 @code{ATAN2(Y, X)} computes the arctangent of the complex number
1402 @item @emph{Standard}:
1403 Fortran 77 and later
1408 @item @emph{Syntax}:
1409 @code{RESULT = ATAN2(Y, X)}
1411 @item @emph{Arguments}:
1412 @multitable @columnfractions .15 .70
1413 @item @var{Y} @tab The type shall be @code{REAL}.
1414 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1415 If @var{Y} is zero, then @var{X} must be nonzero.
1418 @item @emph{Return value}:
1419 The return value has the same type and kind type parameter as @var{Y}.
1420 It is the principal value of the complex number @math{X + i Y}. If
1421 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1422 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1423 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1424 is negative. Finally, if @var{X} is zero, then the magnitude of the result
1427 @item @emph{Example}:
1430 real(4) :: x = 1.e0_4, y = 0.5e0_4
1432 end program test_atan2
1435 @item @emph{Specific names}:
1436 @multitable @columnfractions .20 .20 .20 .25
1437 @item Name @tab Argument @tab Return type @tab Standard
1438 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X}, @code{REAL(8) Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1445 @section @code{ATANH} --- Hyperbolic arctangent function
1448 @cindex area hyperbolic tangent
1449 @cindex hyperbolic arctangent
1450 @cindex hyperbolic function, tangent, inverse
1451 @cindex tangent, hyperbolic, inverse
1454 @item @emph{Description}:
1455 @code{ATANH(X)} computes the hyperbolic arctangent of @var{X} (inverse
1458 @item @emph{Standard}:
1459 Fortran 2008 and later
1464 @item @emph{Syntax}:
1465 @code{RESULT = ATANH(X)}
1467 @item @emph{Arguments}:
1468 @multitable @columnfractions .15 .70
1469 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1472 @item @emph{Return value}:
1473 The return value has same type and kind as @var{X}.
1475 @item @emph{Example}:
1478 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1479 WRITE (*,*) ATANH(x)
1483 @item @emph{Specific names}:
1484 @multitable @columnfractions .20 .20 .20 .25
1485 @item Name @tab Argument @tab Return type @tab Standard
1486 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1489 @item @emph{See also}:
1490 Inverse function: @ref{TANH}
1496 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
1500 @cindex Bessel function, first kind
1503 @item @emph{Description}:
1504 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1505 order 0 of @var{X}. This function is available under the name
1506 @code{BESJ0} as a GNU extension.
1508 @item @emph{Standard}:
1509 Fortran 2008 and later
1514 @item @emph{Syntax}:
1515 @code{RESULT = BESSEL_J0(X)}
1517 @item @emph{Arguments}:
1518 @multitable @columnfractions .15 .70
1519 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1522 @item @emph{Return value}:
1523 The return value is of type @code{REAL} and lies in the
1524 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
1527 @item @emph{Example}:
1530 real(8) :: x = 0.0_8
1532 end program test_besj0
1535 @item @emph{Specific names}:
1536 @multitable @columnfractions .20 .20 .20 .25
1537 @item Name @tab Argument @tab Return type @tab Standard
1538 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1545 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
1549 @cindex Bessel function, first kind
1552 @item @emph{Description}:
1553 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1554 order 1 of @var{X}. This function is available under the name
1555 @code{BESJ1} as a GNU extension.
1557 @item @emph{Standard}:
1563 @item @emph{Syntax}:
1564 @code{RESULT = BESSEL_J1(X)}
1566 @item @emph{Arguments}:
1567 @multitable @columnfractions .15 .70
1568 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1571 @item @emph{Return value}:
1572 The return value is of type @code{REAL} and it lies in the
1573 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
1576 @item @emph{Example}:
1579 real(8) :: x = 1.0_8
1581 end program test_besj1
1584 @item @emph{Specific names}:
1585 @multitable @columnfractions .20 .20 .20 .25
1586 @item Name @tab Argument @tab Return type @tab Standard
1587 @item @code{DBESJ1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1594 @section @code{BESSEL_JN} --- Bessel function of the first kind
1598 @cindex Bessel function, first kind
1601 @item @emph{Description}:
1602 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1603 order @var{N} of @var{X}. This function is available under the name
1604 @code{BESJN} as a GNU extension.
1606 If both arguments are arrays, their ranks and shapes shall conform.
1608 @item @emph{Standard}:
1609 Fortran 2008 and later
1614 @item @emph{Syntax}:
1615 @code{RESULT = BESSEL_JN(N, X)}
1617 @item @emph{Arguments}:
1618 @multitable @columnfractions .15 .70
1619 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
1620 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL}.
1623 @item @emph{Return value}:
1624 The return value is a scalar of type @code{REAL}. It has the same
1627 @item @emph{Example}:
1630 real(8) :: x = 1.0_8
1632 end program test_besjn
1635 @item @emph{Specific names}:
1636 @multitable @columnfractions .20 .20 .20 .25
1637 @item Name @tab Argument @tab Return type @tab Standard
1638 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1639 @item @tab @code{REAL(8) X} @tab @tab
1646 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1650 @cindex Bessel function, second kind
1653 @item @emph{Description}:
1654 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1655 order 0 of @var{X}. This function is available under the name
1656 @code{BESY0} as a GNU extension.
1658 @item @emph{Standard}:
1659 Fortran 2008 and later
1664 @item @emph{Syntax}:
1665 @code{RESULT = BESSEL_Y0(X)}
1667 @item @emph{Arguments}:
1668 @multitable @columnfractions .15 .70
1669 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1672 @item @emph{Return value}:
1673 The return value is a scalar of type @code{REAL}. It has the same
1676 @item @emph{Example}:
1679 real(8) :: x = 0.0_8
1681 end program test_besy0
1684 @item @emph{Specific names}:
1685 @multitable @columnfractions .20 .20 .20 .25
1686 @item Name @tab Argument @tab Return type @tab Standard
1687 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1694 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1698 @cindex Bessel function, second kind
1701 @item @emph{Description}:
1702 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1703 order 1 of @var{X}. This function is available under the name
1704 @code{BESY1} as a GNU extension.
1706 @item @emph{Standard}:
1707 Fortran 2008 and later
1712 @item @emph{Syntax}:
1713 @code{RESULT = BESSEL_Y1(X)}
1715 @item @emph{Arguments}:
1716 @multitable @columnfractions .15 .70
1717 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1720 @item @emph{Return value}:
1721 The return value is a scalar of type @code{REAL}. It has the same
1724 @item @emph{Example}:
1727 real(8) :: x = 1.0_8
1729 end program test_besy1
1732 @item @emph{Specific names}:
1733 @multitable @columnfractions .20 .20 .20 .25
1734 @item Name @tab Argument @tab Return type @tab Standard
1735 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1742 @section @code{BESSEL_YN} --- Bessel function of the second kind
1746 @cindex Bessel function, second kind
1749 @item @emph{Description}:
1750 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1751 order @var{N} of @var{X}. This function is available under the name
1752 @code{BESYN} as a GNU extension.
1754 If both arguments are arrays, their ranks and shapes shall conform.
1756 @item @emph{Standard}:
1757 Fortran 2008 and later
1762 @item @emph{Syntax}:
1763 @code{RESULT = BESSEL_YN(N, X)}
1765 @item @emph{Arguments}:
1766 @multitable @columnfractions .15 .70
1767 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
1768 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL}.
1771 @item @emph{Return value}:
1772 The return value is a scalar of type @code{REAL}. It has the same
1775 @item @emph{Example}:
1778 real(8) :: x = 1.0_8
1780 end program test_besyn
1783 @item @emph{Specific names}:
1784 @multitable @columnfractions .20 .20 .20 .25
1785 @item Name @tab Argument @tab Return type @tab Standard
1786 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1787 @item @tab @code{REAL(8) X} @tab @tab
1794 @section @code{BIT_SIZE} --- Bit size inquiry function
1796 @cindex bits, number of
1797 @cindex size of a variable, in bits
1800 @item @emph{Description}:
1801 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1802 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
1803 independent of the actual value of @var{I}.
1805 @item @emph{Standard}:
1806 Fortran 95 and later
1811 @item @emph{Syntax}:
1812 @code{RESULT = BIT_SIZE(I)}
1814 @item @emph{Arguments}:
1815 @multitable @columnfractions .15 .70
1816 @item @var{I} @tab The type shall be @code{INTEGER}.
1819 @item @emph{Return value}:
1820 The return value is of type @code{INTEGER}
1822 @item @emph{Example}:
1824 program test_bit_size
1829 end program test_bit_size
1836 @section @code{BTEST} --- Bit test function
1838 @cindex bits, testing
1841 @item @emph{Description}:
1842 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
1843 in @var{I} is set. The counting of the bits starts at 0.
1845 @item @emph{Standard}:
1846 Fortran 95 and later
1851 @item @emph{Syntax}:
1852 @code{RESULT = BTEST(I, POS)}
1854 @item @emph{Arguments}:
1855 @multitable @columnfractions .15 .70
1856 @item @var{I} @tab The type shall be @code{INTEGER}.
1857 @item @var{POS} @tab The type shall be @code{INTEGER}.
1860 @item @emph{Return value}:
1861 The return value is of type @code{LOGICAL}
1863 @item @emph{Example}:
1866 integer :: i = 32768 + 1024 + 64
1870 bool = btest(i, pos)
1873 end program test_btest
1879 @section @code{C_ASSOCIATED} --- Status of a C pointer
1880 @fnindex C_ASSOCIATED
1881 @cindex association status, C pointer
1882 @cindex pointer, C association status
1885 @item @emph{Description}:
1886 @code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
1887 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
1889 @item @emph{Standard}:
1890 Fortran 2003 and later
1895 @item @emph{Syntax}:
1896 @code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
1898 @item @emph{Arguments}:
1899 @multitable @columnfractions .15 .70
1900 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
1901 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
1904 @item @emph{Return value}:
1905 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
1906 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
1907 point to different addresses.
1909 @item @emph{Example}:
1911 subroutine association_test(a,b)
1912 use iso_c_binding, only: c_associated, c_loc, c_ptr
1916 if(c_associated(b, c_loc(a))) &
1917 stop 'b and a do not point to same target'
1918 end subroutine association_test
1921 @item @emph{See also}:
1922 @ref{C_LOC}, @ref{C_FUNLOC}
1927 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
1929 @cindex pointer, C address of procedures
1932 @item @emph{Description}:
1933 @code{C_FUNLOC(x)} determines the C address of the argument.
1935 @item @emph{Standard}:
1936 Fortran 2003 and later
1941 @item @emph{Syntax}:
1942 @code{RESULT = C_FUNLOC(x)}
1944 @item @emph{Arguments}:
1945 @multitable @columnfractions .15 .70
1946 @item @var{x} @tab Interoperable function or pointer to such function.
1949 @item @emph{Return value}:
1950 The return value is of type @code{C_FUNPTR} and contains the C address
1953 @item @emph{Example}:
1959 subroutine sub(a) bind(c)
1969 subroutine my_routine(p) bind(c,name='myC_func')
1971 type(c_funptr), intent(in) :: p
1974 call my_routine(c_funloc(sub))
1978 @item @emph{See also}:
1979 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
1983 @node C_F_PROCPOINTER
1984 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
1985 @fnindex C_F_PROCPOINTER
1986 @cindex pointer, C address of pointers
1989 @item @emph{Description}:
1990 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
1991 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
1993 Note: Due to the currently lacking support of procedure pointers in GNU Fortran
1994 this function is not fully operable.
1996 @item @emph{Standard}:
1997 Fortran 2003 and later
2002 @item @emph{Syntax}:
2003 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2005 @item @emph{Arguments}:
2006 @multitable @columnfractions .15 .70
2007 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
2009 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
2013 @item @emph{Example}:
2021 real(c_float), intent(in) :: a
2022 real(c_float) :: func
2026 function getIterFunc() bind(c,name="getIterFunc")
2028 type(c_funptr) :: getIterFunc
2031 type(c_funptr) :: cfunptr
2032 procedure(func), pointer :: myFunc
2033 cfunptr = getIterFunc()
2034 call c_f_procpointer(cfunptr, myFunc)
2038 @item @emph{See also}:
2039 @ref{C_LOC}, @ref{C_F_POINTER}
2044 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2045 @fnindex C_F_POINTER
2046 @cindex pointer, convert C to Fortran
2049 @item @emph{Description}:
2050 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} Assign the target the C pointer
2051 @var{CPTR} to the Fortran pointer @var{FPTR} and specify its
2054 @item @emph{Standard}:
2055 Fortran 2003 and later
2060 @item @emph{Syntax}:
2061 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2063 @item @emph{Arguments}:
2064 @multitable @columnfractions .15 .70
2065 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
2067 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
2069 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2070 with @code{INTENT(IN)}. It shall be present
2071 if and only if @var{fptr} is an array. The size
2072 must be equal to the rank of @var{fptr}.
2075 @item @emph{Example}:
2081 subroutine my_routine(p) bind(c,name='myC_func')
2083 type(c_ptr), intent(out) :: p
2087 real,pointer :: a(:)
2088 call my_routine(cptr)
2089 call c_f_pointer(cptr, a, [12])
2093 @item @emph{See also}:
2094 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2099 @section @code{C_LOC} --- Obtain the C address of an object
2101 @cindex procedure pointer, convert C to Fortran
2104 @item @emph{Description}:
2105 @code{C_LOC(X)} determines the C address of the argument.
2107 @item @emph{Standard}:
2108 Fortran 2003 and later
2113 @item @emph{Syntax}:
2114 @code{RESULT = C_LOC(X)}
2116 @item @emph{Arguments}:
2117 @multitable @columnfractions .15 .70
2118 @item @var{X} @tab Associated scalar pointer or interoperable scalar
2119 or allocated allocatable variable with @code{TARGET} attribute.
2122 @item @emph{Return value}:
2123 The return value is of type @code{C_PTR} and contains the C address
2126 @item @emph{Example}:
2128 subroutine association_test(a,b)
2129 use iso_c_binding, only: c_associated, c_loc, c_ptr
2133 if(c_associated(b, c_loc(a))) &
2134 stop 'b and a do not point to same target'
2135 end subroutine association_test
2138 @item @emph{See also}:
2139 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2144 @section @code{C_SIZEOF} --- Size in bytes of an expression
2146 @cindex expression size
2147 @cindex size of an expression
2150 @item @emph{Description}:
2151 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
2152 expression @code{X} occupies.
2154 @item @emph{Standard}:
2160 @item @emph{Syntax}:
2161 @code{N = C_SIZEOF(X)}
2163 @item @emph{Arguments}:
2164 @multitable @columnfractions .15 .70
2165 @item @var{X} @tab The argument shall be of any type, rank or shape.
2168 @item @emph{Return value}:
2169 The return value is of type integer and of the system-dependent kind
2170 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
2171 number of bytes occupied by the argument. If the argument has the
2172 @code{POINTER} attribute, the number of bytes of the storage area pointed
2173 to is returned. If the argument is of a derived type with @code{POINTER}
2174 or @code{ALLOCATABLE} components, the return value doesn't account for
2175 the sizes of the data pointed to by these components.
2177 @item @emph{Example}:
2181 real(c_float) :: r, s(5)
2182 print *, (c_sizeof(s)/c_sizeof(r) == 5)
2185 The example will print @code{.TRUE.} unless you are using a platform
2186 where default @code{REAL} variables are unusually padded.
2188 @item @emph{See also}:
2194 @section @code{CEILING} --- Integer ceiling function
2197 @cindex rounding, ceiling
2200 @item @emph{Description}:
2201 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
2203 @item @emph{Standard}:
2204 Fortran 95 and later
2209 @item @emph{Syntax}:
2210 @code{RESULT = CEILING(A [, KIND])}
2212 @item @emph{Arguments}:
2213 @multitable @columnfractions .15 .70
2214 @item @var{A} @tab The type shall be @code{REAL}.
2215 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2216 expression indicating the kind parameter of the result.
2219 @item @emph{Return value}:
2220 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
2221 and a default-kind @code{INTEGER} otherwise.
2223 @item @emph{Example}:
2225 program test_ceiling
2228 print *, ceiling(x) ! returns 64
2229 print *, ceiling(y) ! returns -63
2230 end program test_ceiling
2233 @item @emph{See also}:
2234 @ref{FLOOR}, @ref{NINT}
2241 @section @code{CHAR} --- Character conversion function
2243 @cindex conversion, to character
2246 @item @emph{Description}:
2247 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2249 @item @emph{Standard}:
2250 Fortran 77 and later
2255 @item @emph{Syntax}:
2256 @code{RESULT = CHAR(I [, KIND])}
2258 @item @emph{Arguments}:
2259 @multitable @columnfractions .15 .70
2260 @item @var{I} @tab The type shall be @code{INTEGER}.
2261 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2262 expression indicating the kind parameter of the result.
2265 @item @emph{Return value}:
2266 The return value is of type @code{CHARACTER(1)}
2268 @item @emph{Example}:
2274 print *, i, c ! returns 'J'
2275 end program test_char
2279 See @ref{ICHAR} for a discussion of converting between numerical values
2280 and formatted string representations.
2282 @item @emph{See also}:
2283 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2290 @section @code{CHDIR} --- Change working directory
2292 @cindex system, working directory
2295 @item @emph{Description}:
2296 Change current working directory to a specified path.
2298 This intrinsic is provided in both subroutine and function forms; however,
2299 only one form can be used in any given program unit.
2301 @item @emph{Standard}:
2305 Subroutine, function
2307 @item @emph{Syntax}:
2308 @multitable @columnfractions .80
2309 @item @code{CALL CHDIR(NAME [, STATUS])}
2310 @item @code{STATUS = CHDIR(NAME)}
2313 @item @emph{Arguments}:
2314 @multitable @columnfractions .15 .70
2315 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
2316 kind and shall specify a valid path within the file system.
2317 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2318 kind. Returns 0 on success, and a system specific and nonzero error code
2322 @item @emph{Example}:
2325 CHARACTER(len=255) :: path
2327 WRITE(*,*) TRIM(path)
2330 WRITE(*,*) TRIM(path)
2334 @item @emph{See also}:
2341 @section @code{CHMOD} --- Change access permissions of files
2343 @cindex file system, change access mode
2346 @item @emph{Description}:
2347 @code{CHMOD} changes the permissions of a file. This function invokes
2348 @code{/bin/chmod} and might therefore not work on all platforms.
2350 This intrinsic is provided in both subroutine and function forms; however,
2351 only one form can be used in any given program unit.
2353 @item @emph{Standard}:
2357 Subroutine, function
2359 @item @emph{Syntax}:
2360 @multitable @columnfractions .80
2361 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2362 @item @code{STATUS = CHMOD(NAME, MODE)}
2365 @item @emph{Arguments}:
2366 @multitable @columnfractions .15 .70
2368 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
2369 file name. Trailing blanks are ignored unless the character
2370 @code{achar(0)} is present, then all characters up to and excluding
2371 @code{achar(0)} are used as the file name.
2373 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
2374 file permission. @var{MODE} uses the same syntax as the @var{MODE}
2375 argument of @code{/bin/chmod}.
2377 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2378 @code{0} on success and nonzero otherwise.
2381 @item @emph{Return value}:
2382 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2385 @item @emph{Example}:
2386 @code{CHMOD} as subroutine
2391 call chmod('test.dat','u+x',status)
2392 print *, 'Status: ', status
2393 end program chmod_test
2395 @code{CHMOD} as function:
2400 status = chmod('test.dat','u+x')
2401 print *, 'Status: ', status
2402 end program chmod_test
2410 @section @code{CMPLX} --- Complex conversion function
2412 @cindex complex numbers, conversion to
2413 @cindex conversion, to complex
2416 @item @emph{Description}:
2417 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2418 the real component. If @var{Y} is present it is converted to the imaginary
2419 component. If @var{Y} is not present then the imaginary component is set to
2420 0.0. If @var{X} is complex then @var{Y} must not be present.
2422 @item @emph{Standard}:
2423 Fortran 77 and later
2428 @item @emph{Syntax}:
2429 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2431 @item @emph{Arguments}:
2432 @multitable @columnfractions .15 .70
2433 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
2435 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2436 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
2437 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2438 expression indicating the kind parameter of the result.
2441 @item @emph{Return value}:
2442 The return value is of @code{COMPLEX} type, with a kind equal to
2443 @var{KIND} if it is specified. If @var{KIND} is not specified, the
2444 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2445 @var{X} and @var{Y}.
2447 @item @emph{Example}:
2454 print *, z, cmplx(x)
2455 end program test_cmplx
2458 @item @emph{See also}:
2464 @node COMMAND_ARGUMENT_COUNT
2465 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2466 @fnindex COMMAND_ARGUMENT_COUNT
2467 @cindex command-line arguments
2468 @cindex command-line arguments, number of
2469 @cindex arguments, to program
2472 @item @emph{Description}:
2473 @code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the
2474 command line when the containing program was invoked.
2476 @item @emph{Standard}:
2477 Fortran 2003 and later
2482 @item @emph{Syntax}:
2483 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2485 @item @emph{Arguments}:
2486 @multitable @columnfractions .15 .70
2490 @item @emph{Return value}:
2491 The return value is an @code{INTEGER} of default kind.
2493 @item @emph{Example}:
2495 program test_command_argument_count
2497 count = command_argument_count()
2499 end program test_command_argument_count
2502 @item @emph{See also}:
2503 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2509 @section @code{COMPLEX} --- Complex conversion function
2511 @cindex complex numbers, conversion to
2512 @cindex conversion, to complex
2515 @item @emph{Description}:
2516 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2517 to the real component and @var{Y} is converted to the imaginary
2520 @item @emph{Standard}:
2526 @item @emph{Syntax}:
2527 @code{RESULT = COMPLEX(X, Y)}
2529 @item @emph{Arguments}:
2530 @multitable @columnfractions .15 .70
2531 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
2532 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
2535 @item @emph{Return value}:
2536 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2537 value is of default @code{COMPLEX} type.
2539 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2540 type and one is of @code{INTEGER} type, then the return value is of
2541 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2542 argument with the highest precision.
2544 @item @emph{Example}:
2546 program test_complex
2549 print *, complex(i, x)
2550 end program test_complex
2553 @item @emph{See also}:
2560 @section @code{CONJG} --- Complex conjugate function
2563 @cindex complex conjugate
2566 @item @emph{Description}:
2567 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
2568 then the result is @code{(x, -y)}
2570 @item @emph{Standard}:
2571 Fortran 77 and later, has overloads that are GNU extensions
2576 @item @emph{Syntax}:
2579 @item @emph{Arguments}:
2580 @multitable @columnfractions .15 .70
2581 @item @var{Z} @tab The type shall be @code{COMPLEX}.
2584 @item @emph{Return value}:
2585 The return value is of type @code{COMPLEX}.
2587 @item @emph{Example}:
2590 complex :: z = (2.0, 3.0)
2591 complex(8) :: dz = (2.71_8, -3.14_8)
2596 end program test_conjg
2599 @item @emph{Specific names}:
2600 @multitable @columnfractions .20 .20 .20 .25
2601 @item Name @tab Argument @tab Return type @tab Standard
2602 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
2609 @section @code{COS} --- Cosine function
2615 @cindex trigonometric function, cosine
2619 @item @emph{Description}:
2620 @code{COS(X)} computes the cosine of @var{X}.
2622 @item @emph{Standard}:
2623 Fortran 77 and later, has overloads that are GNU extensions
2628 @item @emph{Syntax}:
2629 @code{RESULT = COS(X)}
2631 @item @emph{Arguments}:
2632 @multitable @columnfractions .15 .70
2633 @item @var{X} @tab The type shall be @code{REAL} or
2637 @item @emph{Return value}:
2638 The return value is of type @code{REAL} and it lies in the
2639 range @math{ -1 \leq \cos (x) \leq 1}. The kind type
2640 parameter is the same as @var{X}.
2642 @item @emph{Example}:
2647 end program test_cos
2650 @item @emph{Specific names}:
2651 @multitable @columnfractions .20 .20 .20 .25
2652 @item Name @tab Argument @tab Return type @tab Standard
2653 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
2654 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
2655 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2656 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2659 @item @emph{See also}:
2660 Inverse function: @ref{ACOS}
2667 @section @code{COSH} --- Hyperbolic cosine function
2670 @cindex hyperbolic cosine
2671 @cindex hyperbolic function, cosine
2672 @cindex cosine, hyperbolic
2675 @item @emph{Description}:
2676 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2678 @item @emph{Standard}:
2679 Fortran 77 and later
2684 @item @emph{Syntax}:
2687 @item @emph{Arguments}:
2688 @multitable @columnfractions .15 .70
2689 @item @var{X} @tab The type shall be @code{REAL}.
2692 @item @emph{Return value}:
2693 The return value is of type @code{REAL} and it is positive
2694 (@math{ \cosh (x) \geq 0 }). For a @code{REAL} argument @var{X},
2695 @math{ \cosh (x) \geq 1 }.
2696 The return value is of the same kind as @var{X}.
2698 @item @emph{Example}:
2701 real(8) :: x = 1.0_8
2703 end program test_cosh
2706 @item @emph{Specific names}:
2707 @multitable @columnfractions .20 .20 .20 .25
2708 @item Name @tab Argument @tab Return type @tab Standard
2709 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
2712 @item @emph{See also}:
2713 Inverse function: @ref{ACOSH}
2720 @section @code{COUNT} --- Count function
2722 @cindex array, conditionally count elements
2723 @cindex array, element counting
2724 @cindex array, number of elements
2727 @item @emph{Description}:
2729 @code{COUNT(MASK [, DIM [, KIND]])} counts the number of @code{.TRUE.}
2730 elements of @var{MASK} along the dimension of @var{DIM}. If @var{DIM} is
2731 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
2732 @code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n}
2733 is the rank of @var{MASK}.
2735 @item @emph{Standard}:
2736 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
2739 Transformational function
2741 @item @emph{Syntax}:
2742 @code{RESULT = COUNT(MASK [, DIM [, KIND]])}
2744 @item @emph{Arguments}:
2745 @multitable @columnfractions .15 .70
2746 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
2747 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
2748 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2749 expression indicating the kind parameter of the result.
2752 @item @emph{Return value}:
2753 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
2754 @var{KIND} is absent, the return value is of default integer kind.
2755 The result has a rank equal to that of @var{MASK}.
2757 @item @emph{Example}:
2760 integer, dimension(2,3) :: a, b
2761 logical, dimension(2,3) :: mask
2762 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
2763 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
2764 print '(3i3)', a(1,:)
2765 print '(3i3)', a(2,:)
2767 print '(3i3)', b(1,:)
2768 print '(3i3)', b(2,:)
2771 print '(3l3)', mask(1,:)
2772 print '(3l3)', mask(2,:)
2774 print '(3i3)', count(mask)
2776 print '(3i3)', count(mask, 1)
2778 print '(3i3)', count(mask, 2)
2779 end program test_count
2786 @section @code{CPU_TIME} --- CPU elapsed time in seconds
2788 @cindex time, elapsed
2791 @item @emph{Description}:
2792 Returns a @code{REAL} value representing the elapsed CPU time in
2793 seconds. This is useful for testing segments of code to determine
2796 If a time source is available, time will be reported with microsecond
2797 resolution. If no time source is available, @var{TIME} is set to
2800 Note that @var{TIME} may contain a, system dependent, arbitrary offset
2801 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
2802 value is meaningless, only differences between subsequent calls to
2803 this subroutine, as shown in the example below, should be used.
2806 @item @emph{Standard}:
2807 Fortran 95 and later
2812 @item @emph{Syntax}:
2813 @code{CALL CPU_TIME(TIME)}
2815 @item @emph{Arguments}:
2816 @multitable @columnfractions .15 .70
2817 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
2820 @item @emph{Return value}:
2823 @item @emph{Example}:
2825 program test_cpu_time
2826 real :: start, finish
2827 call cpu_time(start)
2828 ! put code to test here
2829 call cpu_time(finish)
2830 print '("Time = ",f6.3," seconds.")',finish-start
2831 end program test_cpu_time
2834 @item @emph{See also}:
2835 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
2841 @section @code{CSHIFT} --- Circular shift elements of an array
2843 @cindex array, shift circularly
2844 @cindex array, permutation
2845 @cindex array, rotate
2848 @item @emph{Description}:
2849 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
2850 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
2851 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
2852 range of @math{1 /leq DIM /leq n)} where @math{n} is the rank of @var{ARRAY}.
2853 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
2854 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
2855 sections of @var{ARRAY} along the given dimension are shifted. Elements
2856 shifted out one end of each rank one section are shifted back in the other end.
2858 @item @emph{Standard}:
2859 Fortran 95 and later
2862 Transformational function
2864 @item @emph{Syntax}:
2865 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
2867 @item @emph{Arguments}:
2868 @multitable @columnfractions .15 .70
2869 @item @var{ARRAY} @tab Shall be an array of any type.
2870 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
2871 @item @var{DIM} @tab The type shall be @code{INTEGER}.
2874 @item @emph{Return value}:
2875 Returns an array of same type and rank as the @var{ARRAY} argument.
2877 @item @emph{Example}:
2880 integer, dimension(3,3) :: a
2881 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
2882 print '(3i3)', a(1,:)
2883 print '(3i3)', a(2,:)
2884 print '(3i3)', a(3,:)
2885 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
2887 print '(3i3)', a(1,:)
2888 print '(3i3)', a(2,:)
2889 print '(3i3)', a(3,:)
2890 end program test_cshift
2897 @section @code{CTIME} --- Convert a time into a string
2899 @cindex time, conversion to string
2900 @cindex conversion, to string
2903 @item @emph{Description}:
2904 @code{CTIME} converts a system time value, such as returned by
2905 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
2907 This intrinsic is provided in both subroutine and function forms; however,
2908 only one form can be used in any given program unit.
2910 @item @emph{Standard}:
2914 Subroutine, function
2916 @item @emph{Syntax}:
2917 @multitable @columnfractions .80
2918 @item @code{CALL CTIME(TIME, RESULT)}.
2919 @item @code{RESULT = CTIME(TIME)}, (not recommended).
2922 @item @emph{Arguments}:
2923 @multitable @columnfractions .15 .70
2924 @item @var{TIME} @tab The type shall be of type @code{INTEGER(KIND=8)}.
2925 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
2929 @item @emph{Return value}:
2930 The converted date and time as a string.
2932 @item @emph{Example}:
2936 character(len=30) :: date
2939 ! Do something, main part of the program
2942 print *, 'Program was started on ', date
2943 end program test_ctime
2946 @item @emph{See Also}:
2947 @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
2953 @section @code{DATE_AND_TIME} --- Date and time subroutine
2954 @fnindex DATE_AND_TIME
2955 @cindex date, current
2956 @cindex current date
2957 @cindex time, current
2958 @cindex current time
2961 @item @emph{Description}:
2962 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
2963 time information from the real-time system clock. @var{DATE} is
2964 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
2965 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
2966 representing the difference with respect to Coordinated Universal Time (UTC).
2967 Unavailable time and date parameters return blanks.
2969 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
2971 @multitable @columnfractions .15 .30 .40
2972 @item @tab @code{VALUE(1)}: @tab The year
2973 @item @tab @code{VALUE(2)}: @tab The month
2974 @item @tab @code{VALUE(3)}: @tab The day of the month
2975 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
2976 @item @tab @code{VALUE(5)}: @tab The hour of the day
2977 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
2978 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
2979 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
2982 @item @emph{Standard}:
2983 Fortran 95 and later
2988 @item @emph{Syntax}:
2989 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
2991 @item @emph{Arguments}:
2992 @multitable @columnfractions .15 .70
2993 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
2994 or larger, and of default kind.
2995 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
2996 or larger, and of default kind.
2997 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
2998 or larger, and of default kind.
2999 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
3002 @item @emph{Return value}:
3005 @item @emph{Example}:
3007 program test_time_and_date
3008 character(8) :: date
3009 character(10) :: time
3010 character(5) :: zone
3011 integer,dimension(8) :: values
3012 ! using keyword arguments
3013 call date_and_time(date,time,zone,values)
3014 call date_and_time(DATE=date,ZONE=zone)
3015 call date_and_time(TIME=time)
3016 call date_and_time(VALUES=values)
3017 print '(a,2x,a,2x,a)', date, time, zone
3018 print '(8i5))', values
3019 end program test_time_and_date
3022 @item @emph{See also}:
3023 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
3029 @section @code{DBLE} --- Double conversion function
3031 @cindex conversion, to real
3034 @item @emph{Description}:
3035 @code{DBLE(A)} Converts @var{A} to double precision real type.
3037 @item @emph{Standard}:
3038 Fortran 77 and later
3043 @item @emph{Syntax}:
3044 @code{RESULT = DBLE(A)}
3046 @item @emph{Arguments}:
3047 @multitable @columnfractions .15 .70
3048 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
3052 @item @emph{Return value}:
3053 The return value is of type double precision real.
3055 @item @emph{Example}:
3060 complex :: z = (2.3,1.14)
3061 print *, dble(x), dble(i), dble(z)
3062 end program test_dble
3065 @item @emph{See also}:
3066 @ref{DFLOAT}, @ref{FLOAT}, @ref{REAL}
3072 @section @code{DCMPLX} --- Double complex conversion function
3074 @cindex complex numbers, conversion to
3075 @cindex conversion, to complex
3078 @item @emph{Description}:
3079 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3080 converted to the real component. If @var{Y} is present it is converted to the
3081 imaginary component. If @var{Y} is not present then the imaginary component is
3082 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
3084 @item @emph{Standard}:
3090 @item @emph{Syntax}:
3091 @code{RESULT = DCMPLX(X [, Y])}
3093 @item @emph{Arguments}:
3094 @multitable @columnfractions .15 .70
3095 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3097 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
3098 @code{INTEGER} or @code{REAL}.
3101 @item @emph{Return value}:
3102 The return value is of type @code{COMPLEX(8)}
3104 @item @emph{Example}:
3114 print *, dcmplx(x,i)
3115 end program test_dcmplx
3122 @section @code{DFLOAT} --- Double conversion function
3124 @cindex conversion, to real
3127 @item @emph{Description}:
3128 @code{DFLOAT(A)} Converts @var{A} to double precision real type.
3130 @item @emph{Standard}:
3136 @item @emph{Syntax}:
3137 @code{RESULT = DFLOAT(A)}
3139 @item @emph{Arguments}:
3140 @multitable @columnfractions .15 .70
3141 @item @var{A} @tab The type shall be @code{INTEGER}.
3144 @item @emph{Return value}:
3145 The return value is of type double precision real.
3147 @item @emph{Example}:
3152 end program test_dfloat
3155 @item @emph{See also}:
3156 @ref{DBLE}, @ref{FLOAT}, @ref{REAL}
3162 @section @code{DIGITS} --- Significant binary digits function
3164 @cindex model representation, significant digits
3167 @item @emph{Description}:
3168 @code{DIGITS(X)} returns the number of significant binary digits of the internal
3169 model representation of @var{X}. For example, on a system using a 32-bit
3170 floating point representation, a default real number would likely return 24.
3172 @item @emph{Standard}:
3173 Fortran 95 and later
3178 @item @emph{Syntax}:
3179 @code{RESULT = DIGITS(X)}
3181 @item @emph{Arguments}:
3182 @multitable @columnfractions .15 .70
3183 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3186 @item @emph{Return value}:
3187 The return value is of type @code{INTEGER}.
3189 @item @emph{Example}:
3192 integer :: i = 12345
3198 end program test_digits
3205 @section @code{DIM} --- Positive difference
3209 @cindex positive difference
3212 @item @emph{Description}:
3213 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3214 otherwise returns zero.
3216 @item @emph{Standard}:
3217 Fortran 77 and later
3222 @item @emph{Syntax}:
3223 @code{RESULT = DIM(X, Y)}
3225 @item @emph{Arguments}:
3226 @multitable @columnfractions .15 .70
3227 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
3228 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3231 @item @emph{Return value}:
3232 The return value is of type @code{INTEGER} or @code{REAL}.
3234 @item @emph{Example}:
3240 x = dim(4.345_8, 2.111_8)
3243 end program test_dim
3246 @item @emph{Specific names}:
3247 @multitable @columnfractions .20 .20 .20 .25
3248 @item Name @tab Argument @tab Return type @tab Standard
3249 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X,Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
3250 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X,Y} @tab @code{REAL(8)} @tab Fortran 77 and later
3257 @section @code{DOT_PRODUCT} --- Dot product function
3258 @fnindex DOT_PRODUCT
3260 @cindex vector product
3261 @cindex product, vector
3264 @item @emph{Description}:
3265 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
3266 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
3267 either numeric or logical and must be arrays of rank one and of equal size. If
3268 the vectors are @code{INTEGER} or @code{REAL}, the result is
3269 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
3270 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
3271 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
3273 @item @emph{Standard}:
3274 Fortran 95 and later
3277 Transformational function
3279 @item @emph{Syntax}:
3280 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
3282 @item @emph{Arguments}:
3283 @multitable @columnfractions .15 .70
3284 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3285 @item @var{VECTOR_B} @tab The type shall be numeric if @var{VECTOR_A} is of numeric type or @code{LOGICAL} if @var{VECTOR_A} is of type @code{LOGICAL}. @var{VECTOR_B} shall be a rank-one array.
3288 @item @emph{Return value}:
3289 If the arguments are numeric, the return value is a scalar of numeric type,
3290 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
3291 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3293 @item @emph{Example}:
3295 program test_dot_prod
3296 integer, dimension(3) :: a, b
3303 print *, dot_product(a,b)
3304 end program test_dot_prod
3311 @section @code{DPROD} --- Double product function
3313 @cindex product, double-precision
3316 @item @emph{Description}:
3317 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3319 @item @emph{Standard}:
3320 Fortran 77 and later
3325 @item @emph{Syntax}:
3326 @code{RESULT = DPROD(X, Y)}
3328 @item @emph{Arguments}:
3329 @multitable @columnfractions .15 .70
3330 @item @var{X} @tab The type shall be @code{REAL}.
3331 @item @var{Y} @tab The type shall be @code{REAL}.
3334 @item @emph{Return value}:
3335 The return value is of type @code{REAL(8)}.
3337 @item @emph{Example}:
3345 end program test_dprod
3352 @section @code{DREAL} --- Double real part function
3354 @cindex complex numbers, real part
3357 @item @emph{Description}:
3358 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3360 @item @emph{Standard}:
3366 @item @emph{Syntax}:
3367 @code{RESULT = DREAL(A)}
3369 @item @emph{Arguments}:
3370 @multitable @columnfractions .15 .70
3371 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
3374 @item @emph{Return value}:
3375 The return value is of type @code{REAL(8)}.
3377 @item @emph{Example}:
3380 complex(8) :: z = (1.3_8,7.2_8)
3382 end program test_dreal
3385 @item @emph{See also}:
3393 @section @code{DTIME} --- Execution time subroutine (or function)
3395 @cindex time, elapsed
3396 @cindex elapsed time
3399 @item @emph{Description}:
3400 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
3401 since the start of the process's execution in @var{TIME}. @var{VALUES}
3402 returns the user and system components of this time in @code{VALUES(1)} and
3403 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
3406 Subsequent invocations of @code{DTIME} return values accumulated since the
3407 previous invocation.
3409 On some systems, the underlying timings are represented using types with
3410 sufficiently small limits that overflows (wrap around) are possible, such as
3411 32-bit types. Therefore, the values returned by this intrinsic might be, or
3412 become, negative, or numerically less than previous values, during a single
3413 run of the compiled program.
3415 Please note, that this implementation is thread safe if used within OpenMP
3416 directives, i.e., its state will be consistent while called from multiple
3417 threads. However, if @code{DTIME} is called from multiple threads, the result
3418 is still the time since the last invocation. This may not give the intended
3419 results. If possible, use @code{CPU_TIME} instead.
3421 This intrinsic is provided in both subroutine and function forms; however,
3422 only one form can be used in any given program unit.
3424 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3426 @multitable @columnfractions .15 .30 .40
3427 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3428 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3429 @item @tab @code{TIME}: @tab Run time since start in seconds.
3432 @item @emph{Standard}:
3436 Subroutine, function
3438 @item @emph{Syntax}:
3439 @multitable @columnfractions .80
3440 @item @code{CALL DTIME(VALUES, TIME)}.
3441 @item @code{TIME = DTIME(VALUES)}, (not recommended).
3444 @item @emph{Arguments}:
3445 @multitable @columnfractions .15 .70
3446 @item @var{VALUES}@tab The type shall be @code{REAL, DIMENSION(2)}.
3447 @item @var{TIME}@tab The type shall be @code{REAL}.
3450 @item @emph{Return value}:
3451 Elapsed time in seconds since the last invocation or since the start of program
3452 execution if not called before.
3454 @item @emph{Example}:
3458 real, dimension(2) :: tarray
3460 call dtime(tarray, result)
3464 do i=1,100000000 ! Just a delay
3467 call dtime(tarray, result)
3471 end program test_dtime
3474 @item @emph{See also}:
3482 @section @code{EOSHIFT} --- End-off shift elements of an array
3484 @cindex array, shift
3487 @item @emph{Description}:
3488 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
3489 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
3490 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
3491 @code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n} is the
3492 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
3493 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
3494 then all complete rank one sections of @var{ARRAY} along the given dimension are
3495 shifted. Elements shifted out one end of each rank one section are dropped. If
3496 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3497 is copied back in the other end. If @var{BOUNDARY} is not present then the
3498 following are copied in depending on the type of @var{ARRAY}.
3500 @multitable @columnfractions .15 .80
3501 @item @emph{Array Type} @tab @emph{Boundary Value}
3502 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
3503 @item Logical @tab @code{.FALSE.}.
3504 @item Character(@var{len}) @tab @var{len} blanks.
3507 @item @emph{Standard}:
3508 Fortran 95 and later
3511 Transformational function
3513 @item @emph{Syntax}:
3514 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3516 @item @emph{Arguments}:
3517 @multitable @columnfractions .15 .70
3518 @item @var{ARRAY} @tab May be any type, not scalar.
3519 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3520 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3521 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3524 @item @emph{Return value}:
3525 Returns an array of same type and rank as the @var{ARRAY} argument.
3527 @item @emph{Example}:
3529 program test_eoshift
3530 integer, dimension(3,3) :: a
3531 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3532 print '(3i3)', a(1,:)
3533 print '(3i3)', a(2,:)
3534 print '(3i3)', a(3,:)
3535 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3537 print '(3i3)', a(1,:)
3538 print '(3i3)', a(2,:)
3539 print '(3i3)', a(3,:)
3540 end program test_eoshift
3547 @section @code{EPSILON} --- Epsilon function
3549 @cindex model representation, epsilon
3552 @item @emph{Description}:
3553 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
3554 as @var{X} such that @math{1 + E > 1}.
3556 @item @emph{Standard}:
3557 Fortran 95 and later
3562 @item @emph{Syntax}:
3563 @code{RESULT = EPSILON(X)}
3565 @item @emph{Arguments}:
3566 @multitable @columnfractions .15 .70
3567 @item @var{X} @tab The type shall be @code{REAL}.
3570 @item @emph{Return value}:
3571 The return value is of same type as the argument.
3573 @item @emph{Example}:
3575 program test_epsilon
3580 end program test_epsilon
3587 @section @code{ERF} --- Error function
3589 @cindex error function
3592 @item @emph{Description}:
3593 @code{ERF(X)} computes the error function of @var{X}.
3595 @item @emph{Standard}:
3596 Fortran 2008 and later
3601 @item @emph{Syntax}:
3602 @code{RESULT = ERF(X)}
3604 @item @emph{Arguments}:
3605 @multitable @columnfractions .15 .70
3606 @item @var{X} @tab The type shall be @code{REAL}.
3609 @item @emph{Return value}:
3610 The return value is of type @code{REAL}, of the same kind as
3611 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
3613 @item @emph{Example}:
3616 real(8) :: x = 0.17_8
3618 end program test_erf
3621 @item @emph{Specific names}:
3622 @multitable @columnfractions .20 .20 .20 .25
3623 @item Name @tab Argument @tab Return type @tab Standard
3624 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3631 @section @code{ERFC} --- Error function
3633 @cindex error function, complementary
3636 @item @emph{Description}:
3637 @code{ERFC(X)} computes the complementary error function of @var{X}.
3639 @item @emph{Standard}:
3640 Fortran 2008 and later
3645 @item @emph{Syntax}:
3646 @code{RESULT = ERFC(X)}
3648 @item @emph{Arguments}:
3649 @multitable @columnfractions .15 .70
3650 @item @var{X} @tab The type shall be @code{REAL}.
3653 @item @emph{Return value}:
3654 The return value is of type @code{REAL} and of the same kind as @var{X}.
3655 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
3657 @item @emph{Example}:
3660 real(8) :: x = 0.17_8
3662 end program test_erfc
3665 @item @emph{Specific names}:
3666 @multitable @columnfractions .20 .20 .20 .25
3667 @item Name @tab Argument @tab Return type @tab Standard
3668 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3675 @section @code{ERFC_SCALED} --- Error function
3676 @fnindex ERFC_SCALED
3677 @cindex error function, complementary, exponentially-scaled
3680 @item @emph{Description}:
3681 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
3682 error function of @var{X}.
3684 @item @emph{Standard}:
3685 Fortran 2008 and later
3690 @item @emph{Syntax}:
3691 @code{RESULT = ERFC_SCALED(X)}
3693 @item @emph{Arguments}:
3694 @multitable @columnfractions .15 .70
3695 @item @var{X} @tab The type shall be @code{REAL}.
3698 @item @emph{Return value}:
3699 The return value is of type @code{REAL} and of the same kind as @var{X}.
3701 @item @emph{Example}:
3703 program test_erfc_scaled
3704 real(8) :: x = 0.17_8
3706 end program test_erfc_scaled
3713 @section @code{ETIME} --- Execution time subroutine (or function)
3715 @cindex time, elapsed
3718 @item @emph{Description}:
3719 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
3720 since the start of the process's execution in @var{TIME}. @var{VALUES}
3721 returns the user and system components of this time in @code{VALUES(1)} and
3722 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
3724 On some systems, the underlying timings are represented using types with
3725 sufficiently small limits that overflows (wrap around) are possible, such as
3726 32-bit types. Therefore, the values returned by this intrinsic might be, or
3727 become, negative, or numerically less than previous values, during a single
3728 run of the compiled program.
3730 This intrinsic is provided in both subroutine and function forms; however,
3731 only one form can be used in any given program unit.
3733 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3735 @multitable @columnfractions .15 .30 .60
3736 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3737 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3738 @item @tab @code{TIME}: @tab Run time since start in seconds.
3741 @item @emph{Standard}:
3745 Subroutine, function
3747 @item @emph{Syntax}:
3748 @multitable @columnfractions .80
3749 @item @code{CALL ETIME(VALUES, TIME)}.
3750 @item @code{TIME = ETIME(VALUES)}, (not recommended).
3753 @item @emph{Arguments}:
3754 @multitable @columnfractions .15 .70
3755 @item @var{VALUES}@tab The type shall be @code{REAL, DIMENSION(2)}.
3756 @item @var{TIME}@tab The type shall be @code{REAL}.
3759 @item @emph{Return value}:
3760 Elapsed time in seconds since the start of program execution.
3762 @item @emph{Example}:
3766 real, dimension(2) :: tarray
3768 call ETIME(tarray, result)
3772 do i=1,100000000 ! Just a delay
3775 call ETIME(tarray, result)
3779 end program test_etime
3782 @item @emph{See also}:
3790 @section @code{EXIT} --- Exit the program with status.
3792 @cindex program termination
3793 @cindex terminate program
3796 @item @emph{Description}:
3797 @code{EXIT} causes immediate termination of the program with status. If status
3798 is omitted it returns the canonical @emph{success} for the system. All Fortran
3799 I/O units are closed.
3801 @item @emph{Standard}:
3807 @item @emph{Syntax}:
3808 @code{CALL EXIT([STATUS])}
3810 @item @emph{Arguments}:
3811 @multitable @columnfractions .15 .70
3812 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
3815 @item @emph{Return value}:
3816 @code{STATUS} is passed to the parent process on exit.
3818 @item @emph{Example}:
3821 integer :: STATUS = 0
3822 print *, 'This program is going to exit.'
3824 end program test_exit
3827 @item @emph{See also}:
3828 @ref{ABORT}, @ref{KILL}
3834 @section @code{EXP} --- Exponential function
3840 @cindex exponential function
3841 @cindex logarithmic function, inverse
3844 @item @emph{Description}:
3845 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
3847 @item @emph{Standard}:
3848 Fortran 77 and later, has overloads that are GNU extensions
3853 @item @emph{Syntax}:
3854 @code{RESULT = EXP(X)}
3856 @item @emph{Arguments}:
3857 @multitable @columnfractions .15 .70
3858 @item @var{X} @tab The type shall be @code{REAL} or
3862 @item @emph{Return value}:
3863 The return value has same type and kind as @var{X}.
3865 @item @emph{Example}:
3870 end program test_exp
3873 @item @emph{Specific names}:
3874 @multitable @columnfractions .20 .20 .20 .25
3875 @item Name @tab Argument @tab Return type @tab Standard
3876 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3877 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
3878 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3879 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3886 @section @code{EXPONENT} --- Exponent function
3888 @cindex real number, exponent
3889 @cindex floating point, exponent
3892 @item @emph{Description}:
3893 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
3894 is zero the value returned is zero.
3896 @item @emph{Standard}:
3897 Fortran 95 and later
3902 @item @emph{Syntax}:
3903 @code{RESULT = EXPONENT(X)}
3905 @item @emph{Arguments}:
3906 @multitable @columnfractions .15 .70
3907 @item @var{X} @tab The type shall be @code{REAL}.
3910 @item @emph{Return value}:
3911 The return value is of type default @code{INTEGER}.
3913 @item @emph{Example}:
3915 program test_exponent
3920 print *, exponent(0.0)
3921 end program test_exponent
3928 @section @code{FDATE} --- Get the current time as a string
3930 @cindex time, current
3931 @cindex current time
3932 @cindex date, current
3933 @cindex current date
3936 @item @emph{Description}:
3937 @code{FDATE(DATE)} returns the current date (using the same format as
3938 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
3941 This intrinsic is provided in both subroutine and function forms; however,
3942 only one form can be used in any given program unit.
3944 @var{DATE} is an @code{INTENT(OUT)} @code{CHARACTER} variable of the
3947 @item @emph{Standard}:
3951 Subroutine, function
3953 @item @emph{Syntax}:
3954 @multitable @columnfractions .80
3955 @item @code{CALL FDATE(DATE)}.
3956 @item @code{DATE = FDATE()}, (not recommended).
3959 @item @emph{Arguments}:
3960 @multitable @columnfractions .15 .70
3961 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
3965 @item @emph{Return value}:
3966 The current date as a string.
3968 @item @emph{Example}:
3972 character(len=30) :: date
3974 print *, 'Program started on ', date
3975 do i = 1, 100000000 ! Just a delay
3979 print *, 'Program ended on ', date
3980 end program test_fdate
3987 @section @code{FLOAT} --- Convert integer to default real
3989 @cindex conversion, to real
3992 @item @emph{Description}:
3993 @code{FLOAT(A)} converts the integer @var{A} to a default real value.
3995 @item @emph{Standard}:
3996 Fortran 77 and later
4001 @item @emph{Syntax}:
4002 @code{RESULT = FLOAT(A)}
4004 @item @emph{Arguments}:
4005 @multitable @columnfractions .15 .70
4006 @item @var{A} @tab The type shall be @code{INTEGER}.
4009 @item @emph{Return value}:
4010 The return value is of type default @code{REAL}.
4012 @item @emph{Example}:
4016 if (float(i) /= 1.) call abort
4017 end program test_float
4020 @item @emph{See also}:
4021 @ref{DBLE}, @ref{DFLOAT}, @ref{REAL}
4027 @section @code{FGET} --- Read a single character in stream mode from stdin
4029 @cindex read character, stream mode
4030 @cindex stream mode, read character
4031 @cindex file operation, read character
4034 @item @emph{Description}:
4035 Read a single character in stream mode from stdin by bypassing normal
4036 formatted output. Stream I/O should not be mixed with normal record-oriented
4037 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4039 This intrinsic is provided in both subroutine and function forms; however,
4040 only one form can be used in any given program unit.
4042 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4043 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4044 Programmers should consider the use of new stream IO feature in new code
4045 for future portability. See also @ref{Fortran 2003 status}.
4047 @item @emph{Standard}:
4051 Subroutine, function
4053 @item @emph{Syntax}:
4054 @code{CALL FGET(C [, STATUS])}
4056 @item @emph{Arguments}:
4057 @multitable @columnfractions .15 .70
4058 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4060 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4061 Returns 0 on success, -1 on end-of-file, and a system specific positive
4062 error code otherwise.
4065 @item @emph{Example}:
4068 INTEGER, PARAMETER :: strlen = 100
4069 INTEGER :: status, i = 1
4070 CHARACTER(len=strlen) :: str = ""
4072 WRITE (*,*) 'Enter text:'
4074 CALL fget(str(i:i), status)
4075 if (status /= 0 .OR. i > strlen) exit
4078 WRITE (*,*) TRIM(str)
4082 @item @emph{See also}:
4083 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4089 @section @code{FGETC} --- Read a single character in stream mode
4091 @cindex read character, stream mode
4092 @cindex stream mode, read character
4093 @cindex file operation, read character
4096 @item @emph{Description}:
4097 Read a single character in stream mode by bypassing normal formatted output.
4098 Stream I/O should not be mixed with normal record-oriented (formatted or
4099 unformatted) I/O on the same unit; the results are unpredictable.
4101 This intrinsic is provided in both subroutine and function forms; however,
4102 only one form can be used in any given program unit.
4104 Note that the @code{FGET} intrinsic is provided for backwards compatibility
4105 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4106 Programmers should consider the use of new stream IO feature in new code
4107 for future portability. See also @ref{Fortran 2003 status}.
4109 @item @emph{Standard}:
4113 Subroutine, function
4115 @item @emph{Syntax}:
4116 @code{CALL FGETC(UNIT, C [, STATUS])}
4118 @item @emph{Arguments}:
4119 @multitable @columnfractions .15 .70
4120 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4121 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4123 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4124 Returns 0 on success, -1 on end-of-file and a system specific positive
4125 error code otherwise.
4128 @item @emph{Example}:
4131 INTEGER :: fd = 42, status
4134 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4136 CALL fgetc(fd, c, status)
4137 IF (status /= 0) EXIT
4144 @item @emph{See also}:
4145 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4151 @section @code{FLOOR} --- Integer floor function
4154 @cindex rounding, floor
4157 @item @emph{Description}:
4158 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
4160 @item @emph{Standard}:
4161 Fortran 95 and later
4166 @item @emph{Syntax}:
4167 @code{RESULT = FLOOR(A [, KIND])}
4169 @item @emph{Arguments}:
4170 @multitable @columnfractions .15 .70
4171 @item @var{A} @tab The type shall be @code{REAL}.
4172 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4173 expression indicating the kind parameter of the result.
4176 @item @emph{Return value}:
4177 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
4178 and of default-kind @code{INTEGER} otherwise.
4180 @item @emph{Example}:
4185 print *, floor(x) ! returns 63
4186 print *, floor(y) ! returns -64
4187 end program test_floor
4190 @item @emph{See also}:
4191 @ref{CEILING}, @ref{NINT}
4198 @section @code{FLUSH} --- Flush I/O unit(s)
4200 @cindex file operation, flush
4203 @item @emph{Description}:
4204 Flushes Fortran unit(s) currently open for output. Without the optional
4205 argument, all units are flushed, otherwise just the unit specified.
4207 @item @emph{Standard}:
4213 @item @emph{Syntax}:
4214 @code{CALL FLUSH(UNIT)}
4216 @item @emph{Arguments}:
4217 @multitable @columnfractions .15 .70
4218 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4222 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4223 statement that should be preferred over the @code{FLUSH} intrinsic.
4230 @section @code{FNUM} --- File number function
4232 @cindex file operation, file number
4235 @item @emph{Description}:
4236 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4237 open Fortran I/O unit @code{UNIT}.
4239 @item @emph{Standard}:
4245 @item @emph{Syntax}:
4246 @code{RESULT = FNUM(UNIT)}
4248 @item @emph{Arguments}:
4249 @multitable @columnfractions .15 .70
4250 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4253 @item @emph{Return value}:
4254 The return value is of type @code{INTEGER}
4256 @item @emph{Example}:
4260 open (unit=10, status = "scratch")
4264 end program test_fnum
4271 @section @code{FPUT} --- Write a single character in stream mode to stdout
4273 @cindex write character, stream mode
4274 @cindex stream mode, write character
4275 @cindex file operation, write character
4278 @item @emph{Description}:
4279 Write a single character in stream mode to stdout by bypassing normal
4280 formatted output. Stream I/O should not be mixed with normal record-oriented
4281 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4283 This intrinsic is provided in both subroutine and function forms; however,
4284 only one form can be used in any given program unit.
4286 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4287 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4288 Programmers should consider the use of new stream IO feature in new code
4289 for future portability. See also @ref{Fortran 2003 status}.
4291 @item @emph{Standard}:
4295 Subroutine, function
4297 @item @emph{Syntax}:
4298 @code{CALL FPUT(C [, STATUS])}
4300 @item @emph{Arguments}:
4301 @multitable @columnfractions .15 .70
4302 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4304 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4305 Returns 0 on success, -1 on end-of-file and a system specific positive
4306 error code otherwise.
4309 @item @emph{Example}:
4312 CHARACTER(len=10) :: str = "gfortran"
4314 DO i = 1, len_trim(str)
4320 @item @emph{See also}:
4321 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4327 @section @code{FPUTC} --- Write a single character in stream mode
4329 @cindex write character, stream mode
4330 @cindex stream mode, write character
4331 @cindex file operation, write character
4334 @item @emph{Description}:
4335 Write a single character in stream mode by bypassing normal formatted
4336 output. Stream I/O should not be mixed with normal record-oriented
4337 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4339 This intrinsic is provided in both subroutine and function forms; however,
4340 only one form can be used in any given program unit.
4342 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4343 @command{g77}. 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}:
4351 Subroutine, function
4353 @item @emph{Syntax}:
4354 @code{CALL FPUTC(UNIT, C [, STATUS])}
4356 @item @emph{Arguments}:
4357 @multitable @columnfractions .15 .70
4358 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4359 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4361 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4362 Returns 0 on success, -1 on end-of-file and a system specific positive
4363 error code otherwise.
4366 @item @emph{Example}:
4369 CHARACTER(len=10) :: str = "gfortran"
4370 INTEGER :: fd = 42, i
4372 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4373 DO i = 1, len_trim(str)
4374 CALL fputc(fd, str(i:i))
4380 @item @emph{See also}:
4381 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4387 @section @code{FRACTION} --- Fractional part of the model representation
4389 @cindex real number, fraction
4390 @cindex floating point, fraction
4393 @item @emph{Description}:
4394 @code{FRACTION(X)} returns the fractional part of the model
4395 representation of @code{X}.
4397 @item @emph{Standard}:
4398 Fortran 95 and later
4403 @item @emph{Syntax}:
4404 @code{Y = FRACTION(X)}
4406 @item @emph{Arguments}:
4407 @multitable @columnfractions .15 .70
4408 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
4411 @item @emph{Return value}:
4412 The return value is of the same type and kind as the argument.
4413 The fractional part of the model representation of @code{X} is returned;
4414 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
4416 @item @emph{Example}:
4418 program test_fraction
4421 print *, fraction(x), x * radix(x)**(-exponent(x))
4422 end program test_fraction
4430 @section @code{FREE} --- Frees memory
4432 @cindex pointer, cray
4435 @item @emph{Description}:
4436 Frees memory previously allocated by @code{MALLOC()}. The @code{FREE}
4437 intrinsic is an extension intended to be used with Cray pointers, and is
4438 provided in GNU Fortran to allow user to compile legacy code. For
4439 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
4442 @item @emph{Standard}:
4448 @item @emph{Syntax}:
4449 @code{CALL FREE(PTR)}
4451 @item @emph{Arguments}:
4452 @multitable @columnfractions .15 .70
4453 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
4454 location of the memory that should be de-allocated.
4457 @item @emph{Return value}:
4460 @item @emph{Example}:
4461 See @code{MALLOC} for an example.
4463 @item @emph{See also}:
4470 @section @code{FSEEK} --- Low level file positioning subroutine
4472 @cindex file operation, seek
4473 @cindex file operation, position
4476 @item @emph{Description}:
4477 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
4478 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
4479 if set to 1, @var{OFFSET} is taken to be relative to the current position
4480 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
4481 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
4484 This intrinsic routine is not fully backwards compatible with @command{g77}.
4485 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
4486 @var{STATUS} variable. If FSEEK is used in old code, change
4488 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
4493 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
4494 IF (status /= 0) GOTO label
4497 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
4498 Programmers should consider the use of new stream IO feature in new code
4499 for future portability. See also @ref{Fortran 2003 status}.
4501 @item @emph{Standard}:
4507 @item @emph{Syntax}:
4508 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
4510 @item @emph{Arguments}:
4511 @multitable @columnfractions .15 .70
4512 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
4513 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
4514 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
4515 Its value shall be either 0, 1 or 2.
4516 @item @var{STATUS} @tab (Optional) shall be a scalar of type
4520 @item @emph{Example}:
4523 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
4524 INTEGER :: fd, offset, ierr
4530 OPEN(UNIT=fd, FILE="fseek.test")
4531 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
4532 print *, FTELL(fd), ierr
4534 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
4535 print *, FTELL(fd), ierr
4537 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
4538 print *, FTELL(fd), ierr
4544 @item @emph{See also}:
4551 @section @code{FSTAT} --- Get file status
4553 @cindex file system, file status
4556 @item @emph{Description}:
4557 @code{FSTAT} is identical to @ref{STAT}, except that information about an
4558 already opened file is obtained.
4560 The elements in @code{VALUES} are the same as described by @ref{STAT}.
4562 This intrinsic is provided in both subroutine and function forms; however,
4563 only one form can be used in any given program unit.
4565 @item @emph{Standard}:
4569 Subroutine, function
4571 @item @emph{Syntax}:
4572 @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
4574 @item @emph{Arguments}:
4575 @multitable @columnfractions .15 .70
4576 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
4577 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
4578 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
4579 on success and a system specific error code otherwise.
4582 @item @emph{Example}:
4583 See @ref{STAT} for an example.
4585 @item @emph{See also}:
4586 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
4592 @section @code{FTELL} --- Current stream position
4594 @cindex file operation, position
4597 @item @emph{Description}:
4598 Retrieves the current position within an open file.
4600 This intrinsic is provided in both subroutine and function forms; however,
4601 only one form can be used in any given program unit.
4603 @item @emph{Standard}:
4607 Subroutine, function
4609 @item @emph{Syntax}:
4610 @multitable @columnfractions .80
4611 @item @code{CALL FTELL(UNIT, OFFSET)}
4612 @item @code{OFFSET = FTELL(UNIT)}
4615 @item @emph{Arguments}:
4616 @multitable @columnfractions .15 .70
4617 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
4618 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
4621 @item @emph{Return value}:
4622 In either syntax, @var{OFFSET} is set to the current offset of unit
4623 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
4625 @item @emph{Example}:
4629 OPEN(10, FILE="temp.dat")
4635 @item @emph{See also}:
4642 @section @code{GAMMA} --- Gamma function
4645 @cindex Gamma function
4646 @cindex Factorial function
4649 @item @emph{Description}:
4650 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
4651 integer values of @var{X} the Gamma function simplifies to the factorial
4652 function @math{\Gamma(x)=(x-1)!}.
4656 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
4660 @item @emph{Standard}:
4661 Fortran 2008 and later
4666 @item @emph{Syntax}:
4669 @item @emph{Arguments}:
4670 @multitable @columnfractions .15 .70
4671 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
4672 nor a negative integer.
4675 @item @emph{Return value}:
4676 The return value is of type @code{REAL} of the same kind as @var{X}.
4678 @item @emph{Example}:
4682 x = gamma(x) ! returns 1.0
4683 end program test_gamma
4686 @item @emph{Specific names}:
4687 @multitable @columnfractions .20 .20 .20 .25
4688 @item Name @tab Argument @tab Return type @tab Standard
4689 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4690 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4693 @item @emph{See also}:
4694 Logarithm of the Gamma function: @ref{LOG_GAMMA}
4701 @section @code{GERROR} --- Get last system error message
4703 @cindex system, error handling
4706 @item @emph{Description}:
4707 Returns the system error message corresponding to the last system error.
4708 This resembles the functionality of @code{strerror(3)} in C.
4710 @item @emph{Standard}:
4716 @item @emph{Syntax}:
4717 @code{CALL GERROR(RESULT)}
4719 @item @emph{Arguments}:
4720 @multitable @columnfractions .15 .70
4721 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
4724 @item @emph{Example}:
4727 CHARACTER(len=100) :: msg
4733 @item @emph{See also}:
4734 @ref{IERRNO}, @ref{PERROR}
4740 @section @code{GETARG} --- Get command line arguments
4742 @cindex command-line arguments
4743 @cindex arguments, to program
4746 @item @emph{Description}:
4747 Retrieve the @var{POS}-th argument that was passed on the
4748 command line when the containing program was invoked.
4750 This intrinsic routine is provided for backwards compatibility with
4751 GNU Fortran 77. In new code, programmers should consider the use of
4752 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
4755 @item @emph{Standard}:
4761 @item @emph{Syntax}:
4762 @code{CALL GETARG(POS, VALUE)}
4764 @item @emph{Arguments}:
4765 @multitable @columnfractions .15 .70
4766 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
4767 the default integer kind; @math{@var{POS} \geq 0}
4768 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
4770 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
4773 @item @emph{Return value}:
4774 After @code{GETARG} returns, the @var{VALUE} argument holds the
4775 @var{POS}th command line argument. If @var{VALUE} can not hold the
4776 argument, it is truncated to fit the length of @var{VALUE}. If there are
4777 less than @var{POS} arguments specified at the command line, @var{VALUE}
4778 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
4779 to the name of the program (on systems that support this feature).
4781 @item @emph{Example}:
4785 CHARACTER(len=32) :: arg
4794 @item @emph{See also}:
4795 GNU Fortran 77 compatibility function: @ref{IARGC}
4797 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
4798 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4804 @section @code{GET_COMMAND} --- Get the entire command line
4805 @fnindex GET_COMMAND
4806 @cindex command-line arguments
4807 @cindex arguments, to program
4810 @item @emph{Description}:
4811 Retrieve the entire command line that was used to invoke the program.
4813 @item @emph{Standard}:
4814 Fortran 2003 and later
4819 @item @emph{Syntax}:
4820 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
4822 @item @emph{Arguments}:
4823 @multitable @columnfractions .15 .70
4824 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
4826 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
4828 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
4832 @item @emph{Return value}:
4833 If @var{COMMAND} is present, stores the entire command line that was used
4834 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
4835 assigned the length of the command line. If @var{STATUS} is present, it
4836 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
4837 short to store the command line, or a positive value in case of an error.
4839 @item @emph{Example}:
4841 PROGRAM test_get_command
4842 CHARACTER(len=255) :: cmd
4843 CALL get_command(cmd)
4844 WRITE (*,*) TRIM(cmd)
4848 @item @emph{See also}:
4849 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4854 @node GET_COMMAND_ARGUMENT
4855 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
4856 @fnindex GET_COMMAND_ARGUMENT
4857 @cindex command-line arguments
4858 @cindex arguments, to program
4861 @item @emph{Description}:
4862 Retrieve the @var{NUMBER}-th argument that was passed on the
4863 command line when the containing program was invoked.
4865 @item @emph{Standard}:
4866 Fortran 2003 and later
4871 @item @emph{Syntax}:
4872 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
4874 @item @emph{Arguments}:
4875 @multitable @columnfractions .15 .70
4876 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
4877 default kind, @math{@var{NUMBER} \geq 0}
4878 @item @var{VALUE} @tab Shall be a scalar of type @code{CHARACTER}
4879 and of default kind.
4880 @item @var{LENGTH} @tab (Option) Shall be a scalar of type @code{INTEGER}
4881 and of default kind.
4882 @item @var{STATUS} @tab (Option) Shall be a scalar of type @code{INTEGER}
4883 and of default kind.
4886 @item @emph{Return value}:
4887 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
4888 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
4889 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
4890 arguments specified at the command line, @var{VALUE} will be filled with blanks.
4891 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
4892 systems that support this feature). The @var{LENGTH} argument contains the
4893 length of the @var{NUMBER}-th command line argument. If the argument retrieval
4894 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
4895 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
4898 @item @emph{Example}:
4900 PROGRAM test_get_command_argument
4902 CHARACTER(len=32) :: arg
4906 CALL get_command_argument(i, arg)
4907 IF (LEN_TRIM(arg) == 0) EXIT
4909 WRITE (*,*) TRIM(arg)
4915 @item @emph{See also}:
4916 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
4922 @section @code{GETCWD} --- Get current working directory
4924 @cindex system, working directory
4927 @item @emph{Description}:
4928 Get current working directory.
4930 This intrinsic is provided in both subroutine and function forms; however,
4931 only one form can be used in any given program unit.
4933 @item @emph{Standard}:
4937 Subroutine, function
4939 @item @emph{Syntax}:
4940 @code{CALL GETCWD(C [, STATUS])}
4942 @item @emph{Arguments}:
4943 @multitable @columnfractions .15 .70
4944 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
4945 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
4946 a system specific and nonzero error code otherwise.
4949 @item @emph{Example}:
4952 CHARACTER(len=255) :: cwd
4954 WRITE(*,*) TRIM(cwd)
4958 @item @emph{See also}:
4965 @section @code{GETENV} --- Get an environmental variable
4967 @cindex environment variable
4970 @item @emph{Description}:
4971 Get the @var{VALUE} of the environmental variable @var{NAME}.
4973 This intrinsic routine is provided for backwards compatibility with
4974 GNU Fortran 77. In new code, programmers should consider the use of
4975 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
4978 @item @emph{Standard}:
4984 @item @emph{Syntax}:
4985 @code{CALL GETENV(NAME, VALUE)}
4987 @item @emph{Arguments}:
4988 @multitable @columnfractions .15 .70
4989 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
4990 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
4993 @item @emph{Return value}:
4994 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
4995 not large enough to hold the data, it is truncated. If @var{NAME}
4996 is not set, @var{VALUE} will be filled with blanks.
4998 @item @emph{Example}:
5001 CHARACTER(len=255) :: homedir
5002 CALL getenv("HOME", homedir)
5003 WRITE (*,*) TRIM(homedir)
5007 @item @emph{See also}:
5008 @ref{GET_ENVIRONMENT_VARIABLE}
5013 @node GET_ENVIRONMENT_VARIABLE
5014 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
5015 @fnindex GET_ENVIRONMENT_VARIABLE
5016 @cindex environment variable
5019 @item @emph{Description}:
5020 Get the @var{VALUE} of the environmental variable @var{NAME}.
5022 @item @emph{Standard}:
5023 Fortran 2003 and later
5028 @item @emph{Syntax}:
5029 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
5031 @item @emph{Arguments}:
5032 @multitable @columnfractions .15 .70
5033 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
5034 and of default kind.
5035 @item @var{VALUE} @tab Shall be a scalar of type @code{CHARACTER}
5036 and of default kind.
5037 @item @var{LENGTH} @tab Shall be a scalar of type @code{INTEGER}
5038 and of default kind.
5039 @item @var{STATUS} @tab Shall be a scalar of type @code{INTEGER}
5040 and of default kind.
5041 @item @var{TRIM_NAME} @tab Shall be a scalar of type @code{LOGICAL}
5042 and of default kind.
5045 @item @emph{Return value}:
5046 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5047 not large enough to hold the data, it is truncated. If @var{NAME}
5048 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
5049 contains the length needed for storing the environment variable @var{NAME}
5050 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
5051 but too short for the environment variable; it is 1 if the environment
5052 variable does not exist and 2 if the processor does not support environment
5053 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
5054 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
5055 are significant; otherwise they are not part of the environment variable
5058 @item @emph{Example}:
5061 CHARACTER(len=255) :: homedir
5062 CALL get_environment_variable("HOME", homedir)
5063 WRITE (*,*) TRIM(homedir)
5071 @section @code{GETGID} --- Group ID function
5073 @cindex system, group id
5076 @item @emph{Description}:
5077 Returns the numerical group ID of the current process.
5079 @item @emph{Standard}:
5085 @item @emph{Syntax}:
5086 @code{RESULT = GETGID()}
5088 @item @emph{Return value}:
5089 The return value of @code{GETGID} is an @code{INTEGER} of the default
5093 @item @emph{Example}:
5094 See @code{GETPID} for an example.
5096 @item @emph{See also}:
5097 @ref{GETPID}, @ref{GETUID}
5103 @section @code{GETLOG} --- Get login name
5105 @cindex system, login name
5109 @item @emph{Description}:
5110 Gets the username under which the program is running.
5112 @item @emph{Standard}:
5118 @item @emph{Syntax}:
5119 @code{CALL GETLOG(C)}
5121 @item @emph{Arguments}:
5122 @multitable @columnfractions .15 .70
5123 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
5126 @item @emph{Return value}:
5127 Stores the current user name in @var{LOGIN}. (On systems where POSIX
5128 functions @code{geteuid} and @code{getpwuid} are not available, and
5129 the @code{getlogin} function is not implemented either, this will
5130 return a blank string.)
5132 @item @emph{Example}:
5135 CHARACTER(32) :: login
5141 @item @emph{See also}:
5148 @section @code{GETPID} --- Process ID function
5150 @cindex system, process id
5154 @item @emph{Description}:
5155 Returns the numerical process identifier of the current process.
5157 @item @emph{Standard}:
5163 @item @emph{Syntax}:
5164 @code{RESULT = GETPID()}
5166 @item @emph{Return value}:
5167 The return value of @code{GETPID} is an @code{INTEGER} of the default
5171 @item @emph{Example}:
5174 print *, "The current process ID is ", getpid()
5175 print *, "Your numerical user ID is ", getuid()
5176 print *, "Your numerical group ID is ", getgid()
5180 @item @emph{See also}:
5181 @ref{GETGID}, @ref{GETUID}
5187 @section @code{GETUID} --- User ID function
5189 @cindex system, user id
5193 @item @emph{Description}:
5194 Returns the numerical user ID of the current process.
5196 @item @emph{Standard}:
5202 @item @emph{Syntax}:
5203 @code{RESULT = GETUID()}
5205 @item @emph{Return value}:
5206 The return value of @code{GETUID} is an @code{INTEGER} of the default
5210 @item @emph{Example}:
5211 See @code{GETPID} for an example.
5213 @item @emph{See also}:
5214 @ref{GETPID}, @ref{GETLOG}
5220 @section @code{GMTIME} --- Convert time to GMT info
5222 @cindex time, conversion to GMT info
5225 @item @emph{Description}:
5226 Given a system time value @var{TIME} (as provided by the @code{TIME8()}
5227 intrinsic), fills @var{VALUES} with values extracted from it appropriate
5228 to the UTC time zone (Universal Coordinated Time, also known in some
5229 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5231 @item @emph{Standard}:
5237 @item @emph{Syntax}:
5238 @code{CALL GMTIME(TIME, VALUES)}
5240 @item @emph{Arguments}:
5241 @multitable @columnfractions .15 .70
5242 @item @var{TIME} @tab An @code{INTEGER} scalar expression
5243 corresponding to a system time, with @code{INTENT(IN)}.
5244 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
5245 with @code{INTENT(OUT)}.
5248 @item @emph{Return value}:
5249 The elements of @var{VALUES} are assigned as follows:
5251 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5253 @item Minutes after the hour, range 0--59
5254 @item Hours past midnight, range 0--23
5255 @item Day of month, range 0--31
5256 @item Number of months since January, range 0--12
5257 @item Years since 1900
5258 @item Number of days since Sunday, range 0--6
5259 @item Days since January 1
5260 @item Daylight savings indicator: positive if daylight savings is in
5261 effect, zero if not, and negative if the information is not available.
5264 @item @emph{See also}:
5265 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5272 @section @code{HOSTNM} --- Get system host name
5274 @cindex system, host name
5277 @item @emph{Description}:
5278 Retrieves the host name of the system on which the program is running.
5280 This intrinsic is provided in both subroutine and function forms; however,
5281 only one form can be used in any given program unit.
5283 @item @emph{Standard}:
5287 Subroutine, function
5289 @item @emph{Syntax}:
5290 @multitable @columnfractions .80
5291 @item @code{CALL HOSTNM(C [, STATUS])}
5292 @item @code{STATUS = HOSTNM(NAME)}
5295 @item @emph{Arguments}:
5296 @multitable @columnfractions .15 .70
5297 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
5298 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5299 Returns 0 on success, or a system specific error code otherwise.
5302 @item @emph{Return value}:
5303 In either syntax, @var{NAME} is set to the current hostname if it can
5304 be obtained, or to a blank string otherwise.
5311 @section @code{HUGE} --- Largest number of a kind
5313 @cindex limits, largest number
5314 @cindex model representation, largest number
5317 @item @emph{Description}:
5318 @code{HUGE(X)} returns the largest number that is not an infinity in
5319 the model of the type of @code{X}.
5321 @item @emph{Standard}:
5322 Fortran 95 and later
5327 @item @emph{Syntax}:
5328 @code{RESULT = HUGE(X)}
5330 @item @emph{Arguments}:
5331 @multitable @columnfractions .15 .70
5332 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5335 @item @emph{Return value}:
5336 The return value is of the same type and kind as @var{X}
5338 @item @emph{Example}:
5340 program test_huge_tiny
5341 print *, huge(0), huge(0.0), huge(0.0d0)
5342 print *, tiny(0.0), tiny(0.0d0)
5343 end program test_huge_tiny
5350 @section @code{HYPOT} --- Euclidean distance function
5352 @cindex Euclidean distance
5355 @item @emph{Description}:
5356 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
5357 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
5359 @item @emph{Standard}:
5360 Fortran 2008 and later
5365 @item @emph{Syntax}:
5366 @code{RESULT = HYPOT(X, Y)}
5368 @item @emph{Arguments}:
5369 @multitable @columnfractions .15 .70
5370 @item @var{X} @tab The type shall be @code{REAL}.
5371 @item @var{Y} @tab The type and kind type parameter shall be the same as
5375 @item @emph{Return value}:
5376 The return value has the same type and kind type parameter as @var{X}.
5378 @item @emph{Example}:
5381 real(4) :: x = 1.e0_4, y = 0.5e0_4
5383 end program test_hypot
5390 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
5392 @cindex @acronym{ASCII} collating sequence
5393 @cindex collating sequence, @acronym{ASCII}
5394 @cindex conversion, to integer
5397 @item @emph{Description}:
5398 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
5399 in the first character position of @code{C}.
5401 @item @emph{Standard}:
5402 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
5407 @item @emph{Syntax}:
5408 @code{RESULT = IACHAR(C [, KIND])}
5410 @item @emph{Arguments}:
5411 @multitable @columnfractions .15 .70
5412 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5413 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5414 expression indicating the kind parameter of the result.
5417 @item @emph{Return value}:
5418 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5419 @var{KIND} is absent, the return value is of default integer kind.
5421 @item @emph{Example}:
5426 end program test_iachar
5430 See @ref{ICHAR} for a discussion of converting between numerical values
5431 and formatted string representations.
5433 @item @emph{See also}:
5434 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
5441 @section @code{IAND} --- Bitwise logical and
5443 @cindex bitwise logical and
5444 @cindex logical and, bitwise
5447 @item @emph{Description}:
5448 Bitwise logical @code{AND}.
5450 @item @emph{Standard}:
5451 Fortran 95 and later
5456 @item @emph{Syntax}:
5457 @code{RESULT = IAND(I, J)}
5459 @item @emph{Arguments}:
5460 @multitable @columnfractions .15 .70
5461 @item @var{I} @tab The type shall be @code{INTEGER}.
5462 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
5463 kind as @var{I}. (As a GNU extension, different kinds are also
5467 @item @emph{Return value}:
5468 The return type is @code{INTEGER}, of the same kind as the
5469 arguments. (If the argument kinds differ, it is of the same kind as
5470 the larger argument.)
5472 @item @emph{Example}:
5476 DATA a / Z'F' /, b / Z'3' /
5477 WRITE (*,*) IAND(a, b)
5481 @item @emph{See also}:
5482 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5489 @section @code{IARGC} --- Get the number of command line arguments
5491 @cindex command-line arguments
5492 @cindex command-line arguments, number of
5493 @cindex arguments, to program
5496 @item @emph{Description}:
5497 @code{IARGC()} returns the number of arguments passed on the
5498 command line when the containing program was invoked.
5500 This intrinsic routine is provided for backwards compatibility with
5501 GNU Fortran 77. In new code, programmers should consider the use of
5502 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
5505 @item @emph{Standard}:
5511 @item @emph{Syntax}:
5512 @code{RESULT = IARGC()}
5514 @item @emph{Arguments}:
5517 @item @emph{Return value}:
5518 The number of command line arguments, type @code{INTEGER(4)}.
5520 @item @emph{Example}:
5523 @item @emph{See also}:
5524 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
5526 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
5527 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5533 @section @code{IBCLR} --- Clear bit
5539 @item @emph{Description}:
5540 @code{IBCLR} returns the value of @var{I} with the bit at position
5541 @var{POS} set to zero.
5543 @item @emph{Standard}:
5544 Fortran 95 and later
5549 @item @emph{Syntax}:
5550 @code{RESULT = IBCLR(I, POS)}
5552 @item @emph{Arguments}:
5553 @multitable @columnfractions .15 .70
5554 @item @var{I} @tab The type shall be @code{INTEGER}.
5555 @item @var{POS} @tab The type shall be @code{INTEGER}.
5558 @item @emph{Return value}:
5559 The return value is of type @code{INTEGER} and of the same kind as
5562 @item @emph{See also}:
5563 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5570 @section @code{IBITS} --- Bit extraction
5573 @cindex bits, extract
5576 @item @emph{Description}:
5577 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
5578 starting from bit position @var{POS} and extending left for @var{LEN}
5579 bits. The result is right-justified and the remaining bits are
5580 zeroed. The value of @code{POS+LEN} must be less than or equal to the
5581 value @code{BIT_SIZE(I)}.
5583 @item @emph{Standard}:
5584 Fortran 95 and later
5589 @item @emph{Syntax}:
5590 @code{RESULT = IBITS(I, POS, LEN)}
5592 @item @emph{Arguments}:
5593 @multitable @columnfractions .15 .70
5594 @item @var{I} @tab The type shall be @code{INTEGER}.
5595 @item @var{POS} @tab The type shall be @code{INTEGER}.
5596 @item @var{LEN} @tab The type shall be @code{INTEGER}.
5599 @item @emph{Return value}:
5600 The return value is of type @code{INTEGER} and of the same kind as
5603 @item @emph{See also}:
5604 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
5610 @section @code{IBSET} --- Set bit
5615 @item @emph{Description}:
5616 @code{IBSET} returns the value of @var{I} with the bit at position
5617 @var{POS} set to one.
5619 @item @emph{Standard}:
5620 Fortran 95 and later
5625 @item @emph{Syntax}:
5626 @code{RESULT = IBSET(I, POS)}
5628 @item @emph{Arguments}:
5629 @multitable @columnfractions .15 .70
5630 @item @var{I} @tab The type shall be @code{INTEGER}.
5631 @item @var{POS} @tab The type shall be @code{INTEGER}.
5634 @item @emph{Return value}:
5635 The return value is of type @code{INTEGER} and of the same kind as
5638 @item @emph{See also}:
5639 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5646 @section @code{ICHAR} --- Character-to-integer conversion function
5648 @cindex conversion, to integer
5651 @item @emph{Description}:
5652 @code{ICHAR(C)} returns the code for the character in the first character
5653 position of @code{C} in the system's native character set.
5654 The correspondence between characters and their codes is not necessarily
5655 the same across different GNU Fortran implementations.
5657 @item @emph{Standard}:
5658 Fortan 95 and later, with @var{KIND} argument Fortran 2003 and later
5663 @item @emph{Syntax}:
5664 @code{RESULT = ICHAR(C [, KIND])}
5666 @item @emph{Arguments}:
5667 @multitable @columnfractions .15 .70
5668 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5669 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5670 expression indicating the kind parameter of the result.
5673 @item @emph{Return value}:
5674 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5675 @var{KIND} is absent, the return value is of default integer kind.
5677 @item @emph{Example}:
5682 end program test_ichar
5686 No intrinsic exists to convert between a numeric value and a formatted
5687 character string representation -- for instance, given the
5688 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
5689 @code{REAL} value with the value 154, or vice versa. Instead, this
5690 functionality is provided by internal-file I/O, as in the following
5695 character(len=10) string, string2
5698 ! Convert a string to a numeric value
5699 read (string,'(I10)') value
5702 ! Convert a value to a formatted string
5703 write (string2,'(I10)') value
5705 end program read_val
5708 @item @emph{See also}:
5709 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
5716 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
5718 @cindex date, current
5719 @cindex current date
5722 @item @emph{Description}:
5723 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
5724 current local time. The day (in the range 1-31), month (in the range 1-12),
5725 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
5726 The year has four significant digits.
5728 @item @emph{Standard}:
5734 @item @emph{Syntax}:
5735 @code{CALL IDATE(VALUES)}
5737 @item @emph{Arguments}:
5738 @multitable @columnfractions .15 .70
5739 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
5740 the kind shall be the default integer kind.
5743 @item @emph{Return value}:
5744 Does not return anything.
5746 @item @emph{Example}:
5749 integer, dimension(3) :: tarray
5754 end program test_idate
5761 @section @code{IEOR} --- Bitwise logical exclusive or
5763 @cindex bitwise logical exclusive or
5764 @cindex logical exclusive or, bitwise
5767 @item @emph{Description}:
5768 @code{IEOR} returns the bitwise boolean exclusive-OR of @var{I} and
5771 @item @emph{Standard}:
5772 Fortran 95 and later
5777 @item @emph{Syntax}:
5778 @code{RESULT = IEOR(I, J)}
5780 @item @emph{Arguments}:
5781 @multitable @columnfractions .15 .70
5782 @item @var{I} @tab The type shall be @code{INTEGER}.
5783 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
5784 kind as @var{I}. (As a GNU extension, different kinds are also
5788 @item @emph{Return value}:
5789 The return type is @code{INTEGER}, of the same kind as the
5790 arguments. (If the argument kinds differ, it is of the same kind as
5791 the larger argument.)
5793 @item @emph{See also}:
5794 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5800 @section @code{IERRNO} --- Get the last system error number
5802 @cindex system, error handling
5805 @item @emph{Description}:
5806 Returns the last system error number, as given by the C @code{errno()}
5809 @item @emph{Standard}:
5815 @item @emph{Syntax}:
5816 @code{RESULT = IERRNO()}
5818 @item @emph{Arguments}:
5821 @item @emph{Return value}:
5822 The return value is of type @code{INTEGER} and of the default integer
5825 @item @emph{See also}:
5831 @node INDEX intrinsic
5832 @section @code{INDEX} --- Position of a substring within a string
5834 @cindex substring position
5835 @cindex string, find substring
5838 @item @emph{Description}:
5839 Returns the position of the start of the first occurrence of string
5840 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
5841 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
5842 the @var{BACK} argument is present and true, the return value is the
5843 start of the last occurrence rather than the first.
5845 @item @emph{Standard}:
5846 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
5851 @item @emph{Syntax}:
5852 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
5854 @item @emph{Arguments}:
5855 @multitable @columnfractions .15 .70
5856 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
5858 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
5860 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
5862 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5863 expression indicating the kind parameter of the result.
5866 @item @emph{Return value}:
5867 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5868 @var{KIND} is absent, the return value is of default integer kind.
5870 @item @emph{See also}:
5871 @ref{SCAN}, @ref{VERIFY}
5877 @section @code{INT} --- Convert to integer type
5881 @cindex conversion, to integer
5884 @item @emph{Description}:
5885 Convert to integer type
5887 @item @emph{Standard}:
5888 Fortran 77 and later
5893 @item @emph{Syntax}:
5894 @code{RESULT = INT(A [, KIND))}
5896 @item @emph{Arguments}:
5897 @multitable @columnfractions .15 .70
5898 @item @var{A} @tab Shall be of type @code{INTEGER},
5899 @code{REAL}, or @code{COMPLEX}.
5900 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5901 expression indicating the kind parameter of the result.
5904 @item @emph{Return value}:
5905 These functions return a @code{INTEGER} variable or array under
5906 the following rules:
5910 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
5912 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
5913 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
5914 the range of @var{A} and whose sign is the same as the sign of @var{A}.
5916 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
5919 @item @emph{Example}:
5923 complex :: z = (-3.7, 1.0)
5925 print *, int(z), int(z,8)
5929 @item @emph{Specific names}:
5930 @multitable @columnfractions .20 .20 .20 .25
5931 @item Name @tab Argument @tab Return type @tab Standard
5932 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
5933 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
5941 @section @code{INT2} --- Convert to 16-bit integer type
5944 @cindex conversion, to integer
5947 @item @emph{Description}:
5948 Convert to a @code{KIND=2} integer type. This is equivalent to the
5949 standard @code{INT} intrinsic with an optional argument of
5950 @code{KIND=2}, and is only included for backwards compatibility.
5952 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
5954 @item @emph{Standard}:
5960 @item @emph{Syntax}:
5961 @code{RESULT = INT2(A)}
5963 @item @emph{Arguments}:
5964 @multitable @columnfractions .15 .70
5965 @item @var{A} @tab Shall be of type @code{INTEGER},
5966 @code{REAL}, or @code{COMPLEX}.
5969 @item @emph{Return value}:
5970 The return value is a @code{INTEGER(2)} variable.
5972 @item @emph{See also}:
5973 @ref{INT}, @ref{INT8}, @ref{LONG}
5979 @section @code{INT8} --- Convert to 64-bit integer type
5981 @cindex conversion, to integer
5984 @item @emph{Description}:
5985 Convert to a @code{KIND=8} integer type. This is equivalent to the
5986 standard @code{INT} intrinsic with an optional argument of
5987 @code{KIND=8}, and is only included for backwards compatibility.
5989 @item @emph{Standard}:
5995 @item @emph{Syntax}:
5996 @code{RESULT = INT8(A)}
5998 @item @emph{Arguments}:
5999 @multitable @columnfractions .15 .70
6000 @item @var{A} @tab Shall be of type @code{INTEGER},
6001 @code{REAL}, or @code{COMPLEX}.
6004 @item @emph{Return value}:
6005 The return value is a @code{INTEGER(8)} variable.
6007 @item @emph{See also}:
6008 @ref{INT}, @ref{INT2}, @ref{LONG}
6014 @section @code{IOR} --- Bitwise logical or
6016 @cindex bitwise logical or
6017 @cindex logical or, bitwise
6020 @item @emph{Description}:
6021 @code{IOR} returns the bitwise boolean inclusive-OR of @var{I} and
6024 @item @emph{Standard}:
6025 Fortran 95 and later
6030 @item @emph{Syntax}:
6031 @code{RESULT = IOR(I, J)}
6033 @item @emph{Arguments}:
6034 @multitable @columnfractions .15 .70
6035 @item @var{I} @tab The type shall be @code{INTEGER}.
6036 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6037 kind as @var{I}. (As a GNU extension, different kinds are also
6041 @item @emph{Return value}:
6042 The return type is @code{INTEGER}, of the same kind as the
6043 arguments. (If the argument kinds differ, it is of the same kind as
6044 the larger argument.)
6046 @item @emph{See also}:
6047 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6053 @section @code{IRAND} --- Integer pseudo-random number
6055 @cindex random number generation
6058 @item @emph{Description}:
6059 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
6060 distribution between 0 and a system-dependent limit (which is in most
6061 cases 2147483647). If @var{FLAG} is 0, the next number
6062 in the current sequence is returned; if @var{FLAG} is 1, the generator
6063 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
6064 it is used as a new seed with @code{SRAND}.
6066 This intrinsic routine is provided for backwards compatibility with
6067 GNU Fortran 77. It implements a simple modulo generator as provided
6068 by @command{g77}. For new code, one should consider the use of
6069 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
6071 @item @emph{Standard}:
6077 @item @emph{Syntax}:
6078 @code{RESULT = IRAND(I)}
6080 @item @emph{Arguments}:
6081 @multitable @columnfractions .15 .70
6082 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
6085 @item @emph{Return value}:
6086 The return value is of @code{INTEGER(kind=4)} type.
6088 @item @emph{Example}:
6091 integer,parameter :: seed = 86456
6094 print *, irand(), irand(), irand(), irand()
6095 print *, irand(seed), irand(), irand(), irand()
6096 end program test_irand
6104 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
6105 @fnindex IS_IOSTAT_END
6106 @cindex IOSTAT, end of file
6109 @item @emph{Description}:
6110 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
6111 status ``end of file''. The function is equivalent to comparing the variable
6112 with the @code{IOSTAT_END} parameter of the intrinsic module
6113 @code{ISO_FORTRAN_ENV}.
6115 @item @emph{Standard}:
6116 Fortran 2003 and later
6121 @item @emph{Syntax}:
6122 @code{RESULT = IS_IOSTAT_END(I)}
6124 @item @emph{Arguments}:
6125 @multitable @columnfractions .15 .70
6126 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6129 @item @emph{Return value}:
6130 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6131 @var{I} has the value which indicates an end of file condition for
6132 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6134 @item @emph{Example}:
6139 OPEN(88, FILE='test.dat')
6140 READ(88, *, IOSTAT=stat) i
6141 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
6149 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
6150 @fnindex IS_IOSTAT_EOR
6151 @cindex IOSTAT, end of record
6154 @item @emph{Description}:
6155 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
6156 status ``end of record''. The function is equivalent to comparing the
6157 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
6158 @code{ISO_FORTRAN_ENV}.
6160 @item @emph{Standard}:
6161 Fortran 2003 and later
6166 @item @emph{Syntax}:
6167 @code{RESULT = IS_IOSTAT_EOR(I)}
6169 @item @emph{Arguments}:
6170 @multitable @columnfractions .15 .70
6171 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6174 @item @emph{Return value}:
6175 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6176 @var{I} has the value which indicates an end of file condition for
6177 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6179 @item @emph{Example}:
6183 INTEGER :: stat, i(50)
6184 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
6185 READ(88, IOSTAT=stat) i
6186 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
6194 @section @code{ISATTY} --- Whether a unit is a terminal device.
6196 @cindex system, terminal
6199 @item @emph{Description}:
6200 Determine whether a unit is connected to a terminal device.
6202 @item @emph{Standard}:
6208 @item @emph{Syntax}:
6209 @code{RESULT = ISATTY(UNIT)}
6211 @item @emph{Arguments}:
6212 @multitable @columnfractions .15 .70
6213 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
6216 @item @emph{Return value}:
6217 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
6218 device, @code{.FALSE.} otherwise.
6220 @item @emph{Example}:
6223 INTEGER(kind=1) :: unit
6225 write(*,*) isatty(unit=unit)
6229 @item @emph{See also}:
6236 @section @code{ISHFT} --- Shift bits
6241 @item @emph{Description}:
6242 @code{ISHFT} returns a value corresponding to @var{I} with all of the
6243 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
6244 zero corresponds to a left shift, a value of zero corresponds to no
6245 shift, and a value less than zero corresponds to a right shift. If the
6246 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
6247 value is undefined. Bits shifted out from the left end or right end are
6248 lost; zeros are shifted in from the opposite end.
6250 @item @emph{Standard}:
6251 Fortran 95 and later
6256 @item @emph{Syntax}:
6257 @code{RESULT = ISHFT(I, SHIFT)}
6259 @item @emph{Arguments}:
6260 @multitable @columnfractions .15 .70
6261 @item @var{I} @tab The type shall be @code{INTEGER}.
6262 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6265 @item @emph{Return value}:
6266 The return value is of type @code{INTEGER} and of the same kind as
6269 @item @emph{See also}:
6276 @section @code{ISHFTC} --- Shift bits circularly
6278 @cindex bits, shift circular
6281 @item @emph{Description}:
6282 @code{ISHFTC} returns a value corresponding to @var{I} with the
6283 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
6284 is, bits shifted out one end are shifted into the opposite end. A value
6285 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
6286 zero corresponds to no shift, and a value less than zero corresponds to
6287 a right shift. The absolute value of @var{SHIFT} must be less than
6288 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
6289 equivalent to @code{BIT_SIZE(I)}.
6291 @item @emph{Standard}:
6292 Fortran 95 and later
6297 @item @emph{Syntax}:
6298 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
6300 @item @emph{Arguments}:
6301 @multitable @columnfractions .15 .70
6302 @item @var{I} @tab The type shall be @code{INTEGER}.
6303 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6304 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
6305 the value must be greater than zero and less than or equal to
6309 @item @emph{Return value}:
6310 The return value is of type @code{INTEGER} and of the same kind as
6313 @item @emph{See also}:
6320 @section @code{ISNAN} --- Test for a NaN
6325 @item @emph{Description}:
6326 @code{ISNAN} tests whether a floating-point value is an IEEE
6328 @item @emph{Standard}:
6334 @item @emph{Syntax}:
6337 @item @emph{Arguments}:
6338 @multitable @columnfractions .15 .70
6339 @item @var{X} @tab Variable of the type @code{REAL}.
6343 @item @emph{Return value}:
6344 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
6345 if @var{X} is a NaN and @code{FALSE} otherwise.
6347 @item @emph{Example}:
6354 if (isnan(x)) stop '"x" is a NaN'
6355 end program test_nan
6362 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
6364 @cindex time, current
6365 @cindex current time
6368 @item @emph{Description}:
6369 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
6370 current local time. The hour (in the range 1-24), minute (in the range 1-60),
6371 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
6374 @item @emph{Standard}:
6380 @item @emph{Syntax}:
6381 @code{CALL ITIME(VALUES)}
6383 @item @emph{Arguments}:
6384 @multitable @columnfractions .15 .70
6385 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
6386 and the kind shall be the default integer kind.
6389 @item @emph{Return value}:
6390 Does not return anything.
6393 @item @emph{Example}:
6396 integer, dimension(3) :: tarray
6401 end program test_itime
6408 @section @code{KILL} --- Send a signal to a process
6412 @item @emph{Description}:
6413 @item @emph{Standard}:
6414 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
6417 This intrinsic is provided in both subroutine and function forms; however,
6418 only one form can be used in any given program unit.
6421 Subroutine, function
6423 @item @emph{Syntax}:
6424 @code{CALL KILL(C, VALUE [, STATUS])}
6426 @item @emph{Arguments}:
6427 @multitable @columnfractions .15 .70
6428 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
6430 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
6432 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
6433 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
6437 @item @emph{See also}:
6438 @ref{ABORT}, @ref{EXIT}
6444 @section @code{KIND} --- Kind of an entity
6449 @item @emph{Description}:
6450 @code{KIND(X)} returns the kind value of the entity @var{X}.
6452 @item @emph{Standard}:
6453 Fortran 95 and later
6458 @item @emph{Syntax}:
6461 @item @emph{Arguments}:
6462 @multitable @columnfractions .15 .70
6463 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
6464 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
6467 @item @emph{Return value}:
6468 The return value is a scalar of type @code{INTEGER} and of the default
6471 @item @emph{Example}:
6474 integer,parameter :: kc = kind(' ')
6475 integer,parameter :: kl = kind(.true.)
6477 print *, "The default character kind is ", kc
6478 print *, "The default logical kind is ", kl
6479 end program test_kind
6487 @section @code{LBOUND} --- Lower dimension bounds of an array
6489 @cindex array, lower bound
6492 @item @emph{Description}:
6493 Returns the lower bounds of an array, or a single lower bound
6494 along the @var{DIM} dimension.
6495 @item @emph{Standard}:
6496 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6501 @item @emph{Syntax}:
6502 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
6504 @item @emph{Arguments}:
6505 @multitable @columnfractions .15 .70
6506 @item @var{ARRAY} @tab Shall be an array, of any type.
6507 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
6508 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6509 expression indicating the kind parameter of the result.
6512 @item @emph{Return value}:
6513 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6514 @var{KIND} is absent, the return value is of default integer kind.
6515 If @var{DIM} is absent, the result is an array of the lower bounds of
6516 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
6517 corresponding to the lower bound of the array along that dimension. If
6518 @var{ARRAY} is an expression rather than a whole array or array
6519 structure component, or if it has a zero extent along the relevant
6520 dimension, the lower bound is taken to be 1.
6522 @item @emph{See also}:
6529 @section @code{LEADZ} --- Number of leading zero bits of an integer
6534 @item @emph{Description}:
6535 @code{LEADZ} returns the number of leading zero bits of an integer.
6537 @item @emph{Standard}:
6538 Fortran 2008 and later
6543 @item @emph{Syntax}:
6544 @code{RESULT = LEADZ(I)}
6546 @item @emph{Arguments}:
6547 @multitable @columnfractions .15 .70
6548 @item @var{I} @tab Shall be of type @code{INTEGER}.
6551 @item @emph{Return value}:
6552 The type of the return value is the default @code{INTEGER}.
6553 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
6555 @item @emph{Example}:
6558 WRITE (*,*) LEADZ(1) ! prints 8 if BITSIZE(I) has the value 32
6562 @item @emph{See also}:
6563 @ref{BIT_SIZE}, @ref{TRAILZ}
6569 @section @code{LEN} --- Length of a character entity
6571 @cindex string, length
6574 @item @emph{Description}:
6575 Returns the length of a character string. If @var{STRING} is an array,
6576 the length of an element of @var{STRING} is returned. Note that
6577 @var{STRING} need not be defined when this intrinsic is invoked, since
6578 only the length, not the content, of @var{STRING} is needed.
6580 @item @emph{Standard}:
6581 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
6586 @item @emph{Syntax}:
6587 @code{L = LEN(STRING [, KIND])}
6589 @item @emph{Arguments}:
6590 @multitable @columnfractions .15 .70
6591 @item @var{STRING} @tab Shall be a scalar or array of type
6592 @code{CHARACTER}, with @code{INTENT(IN)}
6593 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6594 expression indicating the kind parameter of the result.
6597 @item @emph{Return value}:
6598 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6599 @var{KIND} is absent, the return value is of default integer kind.
6601 @item @emph{See also}:
6602 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
6608 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
6610 @cindex string, length, without trailing whitespace
6613 @item @emph{Description}:
6614 Returns the length of a character string, ignoring any trailing blanks.
6616 @item @emph{Standard}:
6617 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6622 @item @emph{Syntax}:
6623 @code{RESULT = LEN_TRIM(STRING [, KIND])}
6625 @item @emph{Arguments}:
6626 @multitable @columnfractions .15 .70
6627 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
6628 with @code{INTENT(IN)}
6629 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6630 expression indicating the kind parameter of the result.
6633 @item @emph{Return value}:
6634 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6635 @var{KIND} is absent, the return value is of default integer kind.
6637 @item @emph{See also}:
6638 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
6644 @section @code{LGE} --- Lexical greater than or equal
6646 @cindex lexical comparison of strings
6647 @cindex string, comparison
6650 @item @emph{Description}:
6651 Determines whether one string is lexically greater than or equal to
6652 another string, where the two strings are interpreted as containing
6653 ASCII character codes. If the String A and String B are not the same
6654 length, the shorter is compared as if spaces were appended to it to form
6655 a value that has the same length as the longer.
6657 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6658 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6659 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6660 that the latter use the processor's character ordering (which is not
6661 ASCII on some targets), whereas the former always use the ASCII
6664 @item @emph{Standard}:
6665 Fortran 77 and later
6670 @item @emph{Syntax}:
6671 @code{RESULT = LGE(STRING_A, STRING_B)}
6673 @item @emph{Arguments}:
6674 @multitable @columnfractions .15 .70
6675 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6676 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6679 @item @emph{Return value}:
6680 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
6681 otherwise, based on the ASCII ordering.
6683 @item @emph{See also}:
6684 @ref{LGT}, @ref{LLE}, @ref{LLT}
6690 @section @code{LGT} --- Lexical greater than
6692 @cindex lexical comparison of strings
6693 @cindex string, comparison
6696 @item @emph{Description}:
6697 Determines whether one string is lexically greater than another string,
6698 where the two strings are interpreted as containing ASCII character
6699 codes. If the String A and String B are not the same length, the
6700 shorter is compared as if spaces were appended to it to form a value
6701 that has the same length as the longer.
6703 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6704 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6705 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6706 that the latter use the processor's character ordering (which is not
6707 ASCII on some targets), whereas the former always use the ASCII
6710 @item @emph{Standard}:
6711 Fortran 77 and later
6716 @item @emph{Syntax}:
6717 @code{RESULT = LGT(STRING_A, STRING_B)}
6719 @item @emph{Arguments}:
6720 @multitable @columnfractions .15 .70
6721 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6722 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6725 @item @emph{Return value}:
6726 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
6727 otherwise, based on the ASCII ordering.
6729 @item @emph{See also}:
6730 @ref{LGE}, @ref{LLE}, @ref{LLT}
6736 @section @code{LINK} --- Create a hard link
6738 @cindex file system, create link
6739 @cindex file system, hard link
6742 @item @emph{Description}:
6743 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
6744 character (@code{CHAR(0)}) can be used to mark the end of the names in
6745 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
6746 names are ignored. If the @var{STATUS} argument is supplied, it
6747 contains 0 on success or a nonzero error code upon return; see
6750 This intrinsic is provided in both subroutine and function forms;
6751 however, only one form can be used in any given program unit.
6753 @item @emph{Standard}:
6757 Subroutine, function
6759 @item @emph{Syntax}:
6760 @multitable @columnfractions .80
6761 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
6762 @item @code{STATUS = LINK(PATH1, PATH2)}
6765 @item @emph{Arguments}:
6766 @multitable @columnfractions .15 .70
6767 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
6768 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
6769 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
6772 @item @emph{See also}:
6773 @ref{SYMLNK}, @ref{UNLINK}
6779 @section @code{LLE} --- Lexical less than or equal
6781 @cindex lexical comparison of strings
6782 @cindex string, comparison
6785 @item @emph{Description}:
6786 Determines whether one string is lexically less than or equal to another
6787 string, where the two strings are interpreted as containing ASCII
6788 character codes. If the String A and String B are not the same length,
6789 the shorter is compared as if spaces were appended to it to form a value
6790 that has the same length as the longer.
6792 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6793 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6794 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6795 that the latter use the processor's character ordering (which is not
6796 ASCII on some targets), whereas the former always use the ASCII
6799 @item @emph{Standard}:
6800 Fortran 77 and later
6805 @item @emph{Syntax}:
6806 @code{RESULT = LLE(STRING_A, STRING_B)}
6808 @item @emph{Arguments}:
6809 @multitable @columnfractions .15 .70
6810 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6811 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6814 @item @emph{Return value}:
6815 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
6816 otherwise, based on the ASCII ordering.
6818 @item @emph{See also}:
6819 @ref{LGE}, @ref{LGT}, @ref{LLT}
6825 @section @code{LLT} --- Lexical less than
6827 @cindex lexical comparison of strings
6828 @cindex string, comparison
6831 @item @emph{Description}:
6832 Determines whether one string is lexically less than another string,
6833 where the two strings are interpreted as containing ASCII character
6834 codes. If the String A and String B are not the same length, the
6835 shorter is compared as if spaces were appended to it to form a value
6836 that has the same length as the longer.
6838 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6839 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6840 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6841 that the latter use the processor's character ordering (which is not
6842 ASCII on some targets), whereas the former always use the ASCII
6845 @item @emph{Standard}:
6846 Fortran 77 and later
6851 @item @emph{Syntax}:
6852 @code{RESULT = LLT(STRING_A, STRING_B)}
6854 @item @emph{Arguments}:
6855 @multitable @columnfractions .15 .70
6856 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6857 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6860 @item @emph{Return value}:
6861 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
6862 otherwise, based on the ASCII ordering.
6864 @item @emph{See also}:
6865 @ref{LGE}, @ref{LGT}, @ref{LLE}
6871 @section @code{LNBLNK} --- Index of the last non-blank character in a string
6873 @cindex string, find non-blank character
6876 @item @emph{Description}:
6877 Returns the length of a character string, ignoring any trailing blanks.
6878 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
6879 included for backwards compatibility.
6881 @item @emph{Standard}:
6887 @item @emph{Syntax}:
6888 @code{RESULT = LNBLNK(STRING)}
6890 @item @emph{Arguments}:
6891 @multitable @columnfractions .15 .70
6892 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
6893 with @code{INTENT(IN)}
6896 @item @emph{Return value}:
6897 The return value is of @code{INTEGER(kind=4)} type.
6899 @item @emph{See also}:
6900 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
6906 @section @code{LOC} --- Returns the address of a variable
6908 @cindex location of a variable in memory
6911 @item @emph{Description}:
6912 @code{LOC(X)} returns the address of @var{X} as an integer.
6914 @item @emph{Standard}:
6920 @item @emph{Syntax}:
6921 @code{RESULT = LOC(X)}
6923 @item @emph{Arguments}:
6924 @multitable @columnfractions .15 .70
6925 @item @var{X} @tab Variable of any type.
6928 @item @emph{Return value}:
6929 The return value is of type @code{INTEGER}, with a @code{KIND}
6930 corresponding to the size (in bytes) of a memory address on the target
6933 @item @emph{Example}:
6940 end program test_loc
6947 @section @code{LOG} --- Logarithm function
6954 @cindex exponential function, inverse
6955 @cindex logarithmic function
6958 @item @emph{Description}:
6959 @code{LOG(X)} computes the logarithm of @var{X}.
6961 @item @emph{Standard}:
6962 Fortran 77 and later
6967 @item @emph{Syntax}:
6968 @code{RESULT = LOG(X)}
6970 @item @emph{Arguments}:
6971 @multitable @columnfractions .15 .70
6972 @item @var{X} @tab The type shall be @code{REAL} or
6976 @item @emph{Return value}:
6977 The return value is of type @code{REAL} or @code{COMPLEX}.
6978 The kind type parameter is the same as @var{X}.
6979 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
6980 @math{-\pi \leq \omega \leq \pi}.
6982 @item @emph{Example}:
6985 real(8) :: x = 1.0_8
6986 complex :: z = (1.0, 2.0)
6989 end program test_log
6992 @item @emph{Specific names}:
6993 @multitable @columnfractions .20 .20 .20 .25
6994 @item Name @tab Argument @tab Return type @tab Standard
6995 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
6996 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
6997 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
6998 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
6999 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7006 @section @code{LOG10} --- Base 10 logarithm function
7010 @cindex exponential function, inverse
7011 @cindex logarithmic function
7014 @item @emph{Description}:
7015 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
7017 @item @emph{Standard}:
7018 Fortran 77 and later
7023 @item @emph{Syntax}:
7024 @code{RESULT = LOG10(X)}
7026 @item @emph{Arguments}:
7027 @multitable @columnfractions .15 .70
7028 @item @var{X} @tab The type shall be @code{REAL}.
7031 @item @emph{Return value}:
7032 The return value is of type @code{REAL} or @code{COMPLEX}.
7033 The kind type parameter is the same as @var{X}.
7035 @item @emph{Example}:
7038 real(8) :: x = 10.0_8
7040 end program test_log10
7043 @item @emph{Specific names}:
7044 @multitable @columnfractions .20 .20 .20 .25
7045 @item Name @tab Argument @tab Return type @tab Standard
7046 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
7047 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
7054 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
7059 @cindex Gamma function, logarithm of
7062 @item @emph{Description}:
7063 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
7064 of the Gamma (@math{\Gamma}) function.
7066 @item @emph{Standard}:
7067 Fortran 2008 and later
7072 @item @emph{Syntax}:
7073 @code{X = LOG_GAMMA(X)}
7075 @item @emph{Arguments}:
7076 @multitable @columnfractions .15 .70
7077 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
7078 nor a negative integer.
7081 @item @emph{Return value}:
7082 The return value is of type @code{REAL} of the same kind as @var{X}.
7084 @item @emph{Example}:
7086 program test_log_gamma
7088 x = lgamma(x) ! returns 0.0
7089 end program test_log_gamma
7092 @item @emph{Specific names}:
7093 @multitable @columnfractions .20 .20 .20 .25
7094 @item Name @tab Argument @tab Return type @tab Standard
7095 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
7096 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
7097 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
7100 @item @emph{See also}:
7101 Gamma function: @ref{GAMMA}
7108 @section @code{LOGICAL} --- Convert to logical type
7110 @cindex conversion, to logical
7113 @item @emph{Description}:
7114 Converts one kind of @code{LOGICAL} variable to another.
7116 @item @emph{Standard}:
7117 Fortran 95 and later
7122 @item @emph{Syntax}:
7123 @code{RESULT = LOGICAL(L [, KIND])}
7125 @item @emph{Arguments}:
7126 @multitable @columnfractions .15 .70
7127 @item @var{L} @tab The type shall be @code{LOGICAL}.
7128 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7129 expression indicating the kind parameter of the result.
7132 @item @emph{Return value}:
7133 The return value is a @code{LOGICAL} value equal to @var{L}, with a
7134 kind corresponding to @var{KIND}, or of the default logical kind if
7135 @var{KIND} is not given.
7137 @item @emph{See also}:
7138 @ref{INT}, @ref{REAL}, @ref{CMPLX}
7144 @section @code{LONG} --- Convert to integer type
7146 @cindex conversion, to integer
7149 @item @emph{Description}:
7150 Convert to a @code{KIND=4} integer type, which is the same size as a C
7151 @code{long} integer. This is equivalent to the standard @code{INT}
7152 intrinsic with an optional argument of @code{KIND=4}, and is only
7153 included for backwards compatibility.
7155 @item @emph{Standard}:
7161 @item @emph{Syntax}:
7162 @code{RESULT = LONG(A)}
7164 @item @emph{Arguments}:
7165 @multitable @columnfractions .15 .70
7166 @item @var{A} @tab Shall be of type @code{INTEGER},
7167 @code{REAL}, or @code{COMPLEX}.
7170 @item @emph{Return value}:
7171 The return value is a @code{INTEGER(4)} variable.
7173 @item @emph{See also}:
7174 @ref{INT}, @ref{INT2}, @ref{INT8}
7180 @section @code{LSHIFT} --- Left shift bits
7182 @cindex bits, shift left
7185 @item @emph{Description}:
7186 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
7187 bits shifted left by @var{SHIFT} places. If the absolute value of
7188 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
7189 Bits shifted out from the left end are lost; zeros are shifted in from
7192 This function has been superseded by the @code{ISHFT} intrinsic, which
7193 is standard in Fortran 95 and later.
7195 @item @emph{Standard}:
7201 @item @emph{Syntax}:
7202 @code{RESULT = LSHIFT(I, SHIFT)}
7204 @item @emph{Arguments}:
7205 @multitable @columnfractions .15 .70
7206 @item @var{I} @tab The type shall be @code{INTEGER}.
7207 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7210 @item @emph{Return value}:
7211 The return value is of type @code{INTEGER} and of the same kind as
7214 @item @emph{See also}:
7215 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}
7222 @section @code{LSTAT} --- Get file status
7224 @cindex file system, file status
7227 @item @emph{Description}:
7228 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
7229 symbolic link, then the link itself is statted, not the file that it
7232 The elements in @code{VALUES} are the same as described by @ref{STAT}.
7234 This intrinsic is provided in both subroutine and function forms;
7235 however, only one form can be used in any given program unit.
7237 @item @emph{Standard}:
7241 Subroutine, function
7243 @item @emph{Syntax}:
7244 @code{CALL LSTAT(NAME, VALUES [, STATUS])}
7246 @item @emph{Arguments}:
7247 @multitable @columnfractions .15 .70
7248 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
7249 kind, a valid path within the file system.
7250 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
7251 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
7252 Returns 0 on success and a system specific error code otherwise.
7255 @item @emph{Example}:
7256 See @ref{STAT} for an example.
7258 @item @emph{See also}:
7259 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
7265 @section @code{LTIME} --- Convert time to local time info
7267 @cindex time, conversion to local time info
7270 @item @emph{Description}:
7271 Given a system time value @var{TIME} (as provided by the @code{TIME8()}
7272 intrinsic), fills @var{VALUES} with values extracted from it appropriate
7273 to the local time zone using @code{localtime(3)}.
7275 @item @emph{Standard}:
7281 @item @emph{Syntax}:
7282 @code{CALL LTIME(TIME, VALUES)}
7284 @item @emph{Arguments}:
7285 @multitable @columnfractions .15 .70
7286 @item @var{TIME} @tab An @code{INTEGER} scalar expression
7287 corresponding to a system time, with @code{INTENT(IN)}.
7288 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
7289 with @code{INTENT(OUT)}.
7292 @item @emph{Return value}:
7293 The elements of @var{VALUES} are assigned as follows:
7295 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
7297 @item Minutes after the hour, range 0--59
7298 @item Hours past midnight, range 0--23
7299 @item Day of month, range 0--31
7300 @item Number of months since January, range 0--12
7301 @item Years since 1900
7302 @item Number of days since Sunday, range 0--6
7303 @item Days since January 1
7304 @item Daylight savings indicator: positive if daylight savings is in
7305 effect, zero if not, and negative if the information is not available.
7308 @item @emph{See also}:
7309 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
7316 @section @code{MALLOC} --- Allocate dynamic memory
7318 @cindex pointer, cray
7321 @item @emph{Description}:
7322 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
7323 returns the address of the allocated memory. The @code{MALLOC} intrinsic
7324 is an extension intended to be used with Cray pointers, and is provided
7325 in GNU Fortran to allow the user to compile legacy code. For new code
7326 using Fortran 95 pointers, the memory allocation intrinsic is
7329 @item @emph{Standard}:
7335 @item @emph{Syntax}:
7336 @code{PTR = MALLOC(SIZE)}
7338 @item @emph{Arguments}:
7339 @multitable @columnfractions .15 .70
7340 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
7343 @item @emph{Return value}:
7344 The return value is of type @code{INTEGER(K)}, with @var{K} such that
7345 variables of type @code{INTEGER(K)} have the same size as
7346 C pointers (@code{sizeof(void *)}).
7348 @item @emph{Example}:
7349 The following example demonstrates the use of @code{MALLOC} and
7350 @code{FREE} with Cray pointers.
7359 ptr_x = malloc(20*8)
7361 x(i) = sqrt(1.0d0 / i)
7369 end program test_malloc
7372 @item @emph{See also}:
7379 @section @code{MATMUL} --- matrix multiplication
7381 @cindex matrix multiplication
7382 @cindex product, matrix
7385 @item @emph{Description}:
7386 Performs a matrix multiplication on numeric or logical arguments.
7388 @item @emph{Standard}:
7389 Fortran 95 and later
7392 Transformational function
7394 @item @emph{Syntax}:
7395 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
7397 @item @emph{Arguments}:
7398 @multitable @columnfractions .15 .70
7399 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
7400 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
7402 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
7403 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
7404 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
7405 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
7406 equal to the last (or only) dimension of @var{MATRIX_A}.
7409 @item @emph{Return value}:
7410 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
7411 kind of the result follow the usual type and kind promotion rules, as
7412 for the @code{*} or @code{.AND.} operators.
7414 @item @emph{See also}:
7420 @section @code{MAX} --- Maximum value of an argument list
7427 @cindex maximum value
7430 @item @emph{Description}:
7431 Returns the argument with the largest (most positive) value.
7433 @item @emph{Standard}:
7434 Fortran 77 and later
7439 @item @emph{Syntax}:
7440 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
7442 @item @emph{Arguments}:
7443 @multitable @columnfractions .15 .70
7444 @item @var{A1} @tab The type shall be @code{INTEGER} or
7446 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7447 as @var{A1}. (As a GNU extension, arguments of different kinds are
7451 @item @emph{Return value}:
7452 The return value corresponds to the maximum value among the arguments,
7453 and has the same type and kind as the first argument.
7455 @item @emph{Specific names}:
7456 @multitable @columnfractions .20 .20 .20 .25
7457 @item Name @tab Argument @tab Return type @tab Standard
7458 @item @code{MAX0(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7459 @item @code{AMAX0(I)} @tab @code{INTEGER(4) I} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
7460 @item @code{MAX1(X)} @tab @code{REAL X} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
7461 @item @code{AMAX1(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
7462 @item @code{DMAX1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
7465 @item @emph{See also}:
7466 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
7473 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
7474 @fnindex MAXEXPONENT
7475 @cindex model representation, maximum exponent
7478 @item @emph{Description}:
7479 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
7482 @item @emph{Standard}:
7483 Fortran 95 and later
7488 @item @emph{Syntax}:
7489 @code{RESULT = MAXEXPONENT(X)}
7491 @item @emph{Arguments}:
7492 @multitable @columnfractions .15 .70
7493 @item @var{X} @tab Shall be of type @code{REAL}.
7496 @item @emph{Return value}:
7497 The return value is of type @code{INTEGER} and of the default integer
7500 @item @emph{Example}:
7506 print *, minexponent(x), maxexponent(x)
7507 print *, minexponent(y), maxexponent(y)
7508 end program exponents
7515 @section @code{MAXLOC} --- Location of the maximum value within an array
7517 @cindex array, location of maximum element
7520 @item @emph{Description}:
7521 Determines the location of the element in the array with the maximum
7522 value, or, if the @var{DIM} argument is supplied, determines the
7523 locations of the maximum element along each row of the array in the
7524 @var{DIM} direction. If @var{MASK} is present, only the elements for
7525 which @var{MASK} is @code{.TRUE.} are considered. If more than one
7526 element in the array has the maximum value, the location returned is
7527 that of the first such element in array element order. If the array has
7528 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7529 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
7530 and all of the elements of @var{MASK} along a given row are zero, the
7531 result value for that row is zero.
7533 @item @emph{Standard}:
7534 Fortran 95 and later
7537 Transformational function
7539 @item @emph{Syntax}:
7540 @multitable @columnfractions .80
7541 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
7542 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
7545 @item @emph{Arguments}:
7546 @multitable @columnfractions .15 .70
7547 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
7548 @code{REAL}, or @code{CHARACTER}.
7549 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7550 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7551 inclusive. It may not be an optional dummy argument.
7552 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7553 and conformable with @var{ARRAY}.
7556 @item @emph{Return value}:
7557 If @var{DIM} is absent, the result is a rank-one array with a length
7558 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
7559 is an array with a rank one less than the rank of @var{ARRAY}, and a
7560 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7561 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
7562 of one, the result is a scalar. In all cases, the result is of default
7563 @code{INTEGER} type.
7565 @item @emph{See also}:
7566 @ref{MAX}, @ref{MAXVAL}
7573 @section @code{MAXVAL} --- Maximum value of an array
7575 @cindex array, maximum value
7576 @cindex maximum value
7579 @item @emph{Description}:
7580 Determines the maximum value of the elements in an array value, or, if
7581 the @var{DIM} argument is supplied, determines the maximum value along
7582 each row of the array in the @var{DIM} direction. If @var{MASK} is
7583 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7584 considered. If the array has zero size, or all of the elements of
7585 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
7586 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
7589 @item @emph{Standard}:
7590 Fortran 95 and later
7593 Transformational function
7595 @item @emph{Syntax}:
7596 @multitable @columnfractions .80
7597 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
7598 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
7601 @item @emph{Arguments}:
7602 @multitable @columnfractions .15 .70
7603 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
7604 @code{REAL}, or @code{CHARACTER}.
7605 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7606 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7607 inclusive. It may not be an optional dummy argument.
7608 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7609 and conformable with @var{ARRAY}.
7612 @item @emph{Return value}:
7613 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7614 is a scalar. If @var{DIM} is present, the result is an array with a
7615 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7616 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
7617 cases, the result is of the same type and kind as @var{ARRAY}.
7619 @item @emph{See also}:
7620 @ref{MAX}, @ref{MAXLOC}
7626 @section @code{MCLOCK} --- Time function
7628 @cindex time, clock ticks
7632 @item @emph{Description}:
7633 Returns the number of clock ticks since the start of the process, based
7634 on the UNIX function @code{clock(3)}.
7636 This intrinsic is not fully portable, such as to systems with 32-bit
7637 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
7638 the values returned by this intrinsic might be, or become, negative, or
7639 numerically less than previous values, during a single run of the
7642 @item @emph{Standard}:
7648 @item @emph{Syntax}:
7649 @code{RESULT = MCLOCK()}
7651 @item @emph{Return value}:
7652 The return value is a scalar of type @code{INTEGER(4)}, equal to the
7653 number of clock ticks since the start of the process, or @code{-1} if
7654 the system does not support @code{clock(3)}.
7656 @item @emph{See also}:
7657 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
7664 @section @code{MCLOCK8} --- Time function (64-bit)
7666 @cindex time, clock ticks
7670 @item @emph{Description}:
7671 Returns the number of clock ticks since the start of the process, based
7672 on the UNIX function @code{clock(3)}.
7674 @emph{Warning:} this intrinsic does not increase the range of the timing
7675 values over that returned by @code{clock(3)}. On a system with a 32-bit
7676 @code{clock(3)}, @code{MCLOCK8()} will return a 32-bit value, even though
7677 it is converted to a 64-bit @code{INTEGER(8)} value. That means
7678 overflows of the 32-bit value can still occur. Therefore, the values
7679 returned by this intrinsic might be or become negative or numerically
7680 less than previous values during a single run of the compiled program.
7682 @item @emph{Standard}:
7688 @item @emph{Syntax}:
7689 @code{RESULT = MCLOCK8()}
7691 @item @emph{Return value}:
7692 The return value is a scalar of type @code{INTEGER(8)}, equal to the
7693 number of clock ticks since the start of the process, or @code{-1} if
7694 the system does not support @code{clock(3)}.
7696 @item @emph{See also}:
7697 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
7704 @section @code{MERGE} --- Merge variables
7706 @cindex array, merge arrays
7707 @cindex array, combine arrays
7710 @item @emph{Description}:
7711 Select values from two arrays according to a logical mask. The result
7712 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
7713 @var{FSOURCE} if it is @code{.FALSE.}.
7715 @item @emph{Standard}:
7716 Fortran 95 and later
7721 @item @emph{Syntax}:
7722 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
7724 @item @emph{Arguments}:
7725 @multitable @columnfractions .15 .70
7726 @item @var{TSOURCE} @tab May be of any type.
7727 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
7729 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
7732 @item @emph{Return value}:
7733 The result is of the same type and type parameters as @var{TSOURCE}.
7740 @section @code{MIN} --- Minimum value of an argument list
7747 @cindex minimum value
7750 @item @emph{Description}:
7751 Returns the argument with the smallest (most negative) value.
7753 @item @emph{Standard}:
7754 Fortran 77 and later
7759 @item @emph{Syntax}:
7760 @code{RESULT = MIN(A1, A2 [, A3, ...])}
7762 @item @emph{Arguments}:
7763 @multitable @columnfractions .15 .70
7764 @item @var{A1} @tab The type shall be @code{INTEGER} or
7766 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7767 as @var{A1}. (As a GNU extension, arguments of different kinds are
7771 @item @emph{Return value}:
7772 The return value corresponds to the maximum value among the arguments,
7773 and has the same type and kind as the first argument.
7775 @item @emph{Specific names}:
7776 @multitable @columnfractions .20 .20 .20 .25
7777 @item Name @tab Argument @tab Return type @tab Standard
7778 @item @code{MIN0(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7779 @item @code{AMIN0(I)} @tab @code{INTEGER(4) I} @tab @code{REAL(MIN(X))} @tab Fortran 77 and later
7780 @item @code{MIN1(X)} @tab @code{REAL X} @tab @code{INT(MIN(X))} @tab Fortran 77 and later
7781 @item @code{AMIN1(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
7782 @item @code{DMIN1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
7785 @item @emph{See also}:
7786 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
7792 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
7793 @fnindex MINEXPONENT
7794 @cindex model representation, minimum exponent
7797 @item @emph{Description}:
7798 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
7801 @item @emph{Standard}:
7802 Fortran 95 and later
7807 @item @emph{Syntax}:
7808 @code{RESULT = MINEXPONENT(X)}
7810 @item @emph{Arguments}:
7811 @multitable @columnfractions .15 .70
7812 @item @var{X} @tab Shall be of type @code{REAL}.
7815 @item @emph{Return value}:
7816 The return value is of type @code{INTEGER} and of the default integer
7819 @item @emph{Example}:
7820 See @code{MAXEXPONENT} for an example.
7826 @section @code{MINLOC} --- Location of the minimum value within an array
7828 @cindex array, location of minimum element
7831 @item @emph{Description}:
7832 Determines the location of the element in the array with the minimum
7833 value, or, if the @var{DIM} argument is supplied, determines the
7834 locations of the minimum element along each row of the array in the
7835 @var{DIM} direction. If @var{MASK} is present, only the elements for
7836 which @var{MASK} is @code{.TRUE.} are considered. If more than one
7837 element in the array has the minimum value, the location returned is
7838 that of the first such element in array element order. If the array has
7839 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7840 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
7841 and all of the elements of @var{MASK} along a given row are zero, the
7842 result value for that row is zero.
7844 @item @emph{Standard}:
7845 Fortran 95 and later
7848 Transformational function
7850 @item @emph{Syntax}:
7851 @multitable @columnfractions .80
7852 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
7853 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
7856 @item @emph{Arguments}:
7857 @multitable @columnfractions .15 .70
7858 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
7859 @code{REAL}, or @code{CHARACTER}.
7860 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7861 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7862 inclusive. It may not be an optional dummy argument.
7863 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7864 and conformable with @var{ARRAY}.
7867 @item @emph{Return value}:
7868 If @var{DIM} is absent, the result is a rank-one array with a length
7869 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
7870 is an array with a rank one less than the rank of @var{ARRAY}, and a
7871 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7872 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
7873 of one, the result is a scalar. In all cases, the result is of default
7874 @code{INTEGER} type.
7876 @item @emph{See also}:
7877 @ref{MIN}, @ref{MINVAL}
7884 @section @code{MINVAL} --- Minimum value of an array
7886 @cindex array, minimum value
7887 @cindex minimum value
7890 @item @emph{Description}:
7891 Determines the minimum value of the elements in an array value, or, if
7892 the @var{DIM} argument is supplied, determines the minimum value along
7893 each row of the array in the @var{DIM} direction. If @var{MASK} is
7894 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7895 considered. If the array has zero size, or all of the elements of
7896 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
7897 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
7898 @var{ARRAY} is of character type.
7900 @item @emph{Standard}:
7901 Fortran 95 and later
7904 Transformational function
7906 @item @emph{Syntax}:
7907 @multitable @columnfractions .80
7908 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
7909 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
7912 @item @emph{Arguments}:
7913 @multitable @columnfractions .15 .70
7914 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
7915 @code{REAL}, or @code{CHARACTER}.
7916 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7917 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7918 inclusive. It may not be an optional dummy argument.
7919 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7920 and conformable with @var{ARRAY}.
7923 @item @emph{Return value}:
7924 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7925 is a scalar. If @var{DIM} is present, the result is an array with a
7926 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7927 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
7928 cases, the result is of the same type and kind as @var{ARRAY}.
7930 @item @emph{See also}:
7931 @ref{MIN}, @ref{MINLOC}
7938 @section @code{MOD} --- Remainder function
7943 @cindex division, remainder
7946 @item @emph{Description}:
7947 @code{MOD(A,P)} computes the remainder of the division of A by P@. It is
7948 calculated as @code{A - (INT(A/P) * P)}.
7950 @item @emph{Standard}:
7951 Fortran 77 and later
7956 @item @emph{Syntax}:
7957 @code{RESULT = MOD(A, P)}
7959 @item @emph{Arguments}:
7960 @multitable @columnfractions .15 .70
7961 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
7962 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
7966 @item @emph{Return value}:
7967 The kind of the return value is the result of cross-promoting
7968 the kinds of the arguments.
7970 @item @emph{Example}:
7974 print *, mod(17.5,5.5)
7975 print *, mod(17.5d0,5.5)
7976 print *, mod(17.5,5.5d0)
7979 print *, mod(-17.5,5.5)
7980 print *, mod(-17.5d0,5.5)
7981 print *, mod(-17.5,5.5d0)
7984 print *, mod(17.5,-5.5)
7985 print *, mod(17.5d0,-5.5)
7986 print *, mod(17.5,-5.5d0)
7987 end program test_mod
7990 @item @emph{Specific names}:
7991 @multitable @columnfractions .20 .20 .20 .25
7992 @item Name @tab Arguments @tab Return type @tab Standard
7993 @item @code{AMOD(A,P)} @tab @code{REAL(4)} @tab @code{REAL(4)} @tab Fortran 95 and later
7994 @item @code{DMOD(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab Fortran 95 and later
8001 @section @code{MODULO} --- Modulo function
8004 @cindex division, modulo
8007 @item @emph{Description}:
8008 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
8010 @item @emph{Standard}:
8011 Fortran 95 and later
8016 @item @emph{Syntax}:
8017 @code{RESULT = MODULO(A, P)}
8019 @item @emph{Arguments}:
8020 @multitable @columnfractions .15 .70
8021 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8022 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
8025 @item @emph{Return value}:
8026 The type and kind of the result are those of the arguments.
8028 @item If @var{A} and @var{P} are of type @code{INTEGER}:
8029 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
8030 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
8032 @item If @var{A} and @var{P} are of type @code{REAL}:
8033 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
8035 In all cases, if @var{P} is zero the result is processor-dependent.
8037 @item @emph{Example}:
8040 print *, modulo(17,3)
8041 print *, modulo(17.5,5.5)
8043 print *, modulo(-17,3)
8044 print *, modulo(-17.5,5.5)
8046 print *, modulo(17,-3)
8047 print *, modulo(17.5,-5.5)
8056 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
8058 @cindex moving allocation
8059 @cindex allocation, moving
8062 @item @emph{Description}:
8063 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
8064 @var{TO}. @var{FROM} will become deallocated in the process.
8066 @item @emph{Standard}:
8067 Fortran 2003 and later
8072 @item @emph{Syntax}:
8073 @code{CALL MOVE_ALLOC(FROM, TO)}
8075 @item @emph{Arguments}:
8076 @multitable @columnfractions .15 .70
8077 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
8078 of any type and kind.
8079 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
8080 of the same type, kind and rank as @var{FROM}.
8083 @item @emph{Return value}:
8086 @item @emph{Example}:
8088 program test_move_alloc
8089 integer, allocatable :: a(:), b(:)
8093 call move_alloc(a, b)
8094 print *, allocated(a), allocated(b)
8096 end program test_move_alloc
8103 @section @code{MVBITS} --- Move bits from one integer to another
8108 @item @emph{Description}:
8109 Moves @var{LEN} bits from positions @var{FROMPOS} through
8110 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
8111 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
8112 affected by the movement of bits is unchanged. The values of
8113 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
8114 @code{BIT_SIZE(FROM)}.
8116 @item @emph{Standard}:
8117 Fortran 95 and later
8120 Elemental subroutine
8122 @item @emph{Syntax}:
8123 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
8125 @item @emph{Arguments}:
8126 @multitable @columnfractions .15 .70
8127 @item @var{FROM} @tab The type shall be @code{INTEGER}.
8128 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
8129 @item @var{LEN} @tab The type shall be @code{INTEGER}.
8130 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
8131 same kind as @var{FROM}.
8132 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
8135 @item @emph{See also}:
8136 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
8142 @section @code{NEAREST} --- Nearest representable number
8144 @cindex real number, nearest different
8145 @cindex floating point, nearest different
8148 @item @emph{Description}:
8149 @code{NEAREST(X, S)} returns the processor-representable number nearest
8150 to @code{X} in the direction indicated by the sign of @code{S}.
8152 @item @emph{Standard}:
8153 Fortran 95 and later
8158 @item @emph{Syntax}:
8159 @code{RESULT = NEAREST(X, S)}
8161 @item @emph{Arguments}:
8162 @multitable @columnfractions .15 .70
8163 @item @var{X} @tab Shall be of type @code{REAL}.
8164 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
8168 @item @emph{Return value}:
8169 The return value is of the same type as @code{X}. If @code{S} is
8170 positive, @code{NEAREST} returns the processor-representable number
8171 greater than @code{X} and nearest to it. If @code{S} is negative,
8172 @code{NEAREST} returns the processor-representable number smaller than
8173 @code{X} and nearest to it.
8175 @item @emph{Example}:
8177 program test_nearest
8179 x = nearest(42.0, 1.0)
8180 y = nearest(42.0, -1.0)
8181 write (*,"(3(G20.15))") x, y, x - y
8182 end program test_nearest
8189 @section @code{NEW_LINE} --- New line character
8192 @cindex output, newline
8195 @item @emph{Description}:
8196 @code{NEW_LINE(C)} returns the new-line character.
8198 @item @emph{Standard}:
8199 Fortran 2003 and later
8204 @item @emph{Syntax}:
8205 @code{RESULT = NEW_LINE(C)}
8207 @item @emph{Arguments}:
8208 @multitable @columnfractions .15 .70
8209 @item @var{C} @tab The argument shall be a scalar or array of the
8210 type @code{CHARACTER}.
8213 @item @emph{Return value}:
8214 Returns a @var{CHARACTER} scalar of length one with the new-line character of
8215 the same kind as parameter @var{C}.
8217 @item @emph{Example}:
8221 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
8229 @section @code{NINT} --- Nearest whole number
8232 @cindex rounding, nearest whole number
8235 @item @emph{Description}:
8236 @code{NINT(A)} rounds its argument to the nearest whole number.
8238 @item @emph{Standard}:
8239 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
8244 @item @emph{Syntax}:
8245 @code{RESULT = NINT(A [, KIND])}
8247 @item @emph{Arguments}:
8248 @multitable @columnfractions .15 .70
8249 @item @var{A} @tab The type of the argument shall be @code{REAL}.
8250 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8251 expression indicating the kind parameter of the result.
8254 @item @emph{Return value}:
8255 Returns @var{A} with the fractional portion of its magnitude eliminated by
8256 rounding to the nearest whole number and with its sign preserved,
8257 converted to an @code{INTEGER} of the default kind.
8259 @item @emph{Example}:
8266 print *, nint(x4), idnint(x8)
8267 end program test_nint
8270 @item @emph{Specific names}:
8271 @multitable @columnfractions .25 .25 .25
8272 @item Name @tab Argument @tab Standard
8273 @item @code{IDNINT(X)} @tab @code{REAL(8)} @tab Fortran 95 and later
8276 @item @emph{See also}:
8277 @ref{CEILING}, @ref{FLOOR}
8284 @section @code{NOT} --- Logical negation
8286 @cindex bits, negate
8287 @cindex bitwise logical not
8288 @cindex logical not, bitwise
8291 @item @emph{Description}:
8292 @code{NOT} returns the bitwise boolean inverse of @var{I}.
8294 @item @emph{Standard}:
8295 Fortran 95 and later
8300 @item @emph{Syntax}:
8301 @code{RESULT = NOT(I)}
8303 @item @emph{Arguments}:
8304 @multitable @columnfractions .15 .70
8305 @item @var{I} @tab The type shall be @code{INTEGER}.
8308 @item @emph{Return value}:
8309 The return type is @code{INTEGER}, of the same kind as the
8312 @item @emph{See also}:
8313 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
8320 @section @code{NULL} --- Function that returns an disassociated pointer
8322 @cindex pointer, status
8323 @cindex pointer, disassociated
8326 @item @emph{Description}:
8327 Returns a disassociated pointer.
8329 If @var{MOLD} is present, a dissassociated pointer of the same type is
8330 returned, otherwise the type is determined by context.
8332 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
8333 includes cases where it is required.
8335 @item @emph{Standard}:
8336 Fortran 95 and later
8339 Transformational function
8341 @item @emph{Syntax}:
8342 @code{PTR => NULL([MOLD])}
8344 @item @emph{Arguments}:
8345 @multitable @columnfractions .15 .70
8346 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
8347 status and of any type.
8350 @item @emph{Return value}:
8351 A disassociated pointer.
8353 @item @emph{Example}:
8355 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
8358 @item @emph{See also}:
8365 @section @code{OR} --- Bitwise logical OR
8367 @cindex bitwise logical or
8368 @cindex logical or, bitwise
8371 @item @emph{Description}:
8372 Bitwise logical @code{OR}.
8374 This intrinsic routine is provided for backwards compatibility with
8375 GNU Fortran 77. For integer arguments, programmers should consider
8376 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
8378 @item @emph{Standard}:
8384 @item @emph{Syntax}:
8385 @code{RESULT = OR(I, J)}
8387 @item @emph{Arguments}:
8388 @multitable @columnfractions .15 .70
8389 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
8390 type or a scalar @code{LOGICAL} type.
8391 @item @var{J} @tab The type shall be the same as the type of @var{J}.
8394 @item @emph{Return value}:
8395 The return type is either a scalar @code{INTEGER} or a scalar
8396 @code{LOGICAL}. If the kind type parameters differ, then the
8397 smaller kind type is implicitly converted to larger kind, and the
8398 return has the larger kind.
8400 @item @emph{Example}:
8403 LOGICAL :: T = .TRUE., F = .FALSE.
8405 DATA a / Z'F' /, b / Z'3' /
8407 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
8408 WRITE (*,*) OR(a, b)
8412 @item @emph{See also}:
8413 Fortran 95 elemental function: @ref{IOR}
8419 @section @code{PACK} --- Pack an array into an array of rank one
8421 @cindex array, packing
8422 @cindex array, reduce dimension
8423 @cindex array, gather elements
8426 @item @emph{Description}:
8427 Stores the elements of @var{ARRAY} in an array of rank one.
8429 The beginning of the resulting array is made up of elements whose @var{MASK}
8430 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
8433 @item @emph{Standard}:
8434 Fortran 95 and later
8437 Transformational function
8439 @item @emph{Syntax}:
8440 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
8442 @item @emph{Arguments}:
8443 @multitable @columnfractions .15 .70
8444 @item @var{ARRAY} @tab Shall be an array of any type.
8445 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
8446 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
8448 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
8449 as @var{ARRAY} and of rank one. If present, the number of elements in
8450 @var{VECTOR} shall be equal to or greater than the number of true elements
8451 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
8452 @var{VECTOR} shall be equal to or greater than the number of elements in
8456 @item @emph{Return value}:
8457 The result is an array of rank one and the same type as that of @var{ARRAY}.
8458 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
8459 number of @code{TRUE} values in @var{MASK} otherwise.
8461 @item @emph{Example}:
8462 Gathering nonzero elements from an array:
8466 m = (/ 1, 0, 0, 0, 5, 0 /)
8467 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
8471 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
8475 m = (/ 1, 0, 0, 2 /)
8476 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
8480 @item @emph{See also}:
8487 @section @code{PERROR} --- Print system error message
8489 @cindex system, error handling
8492 @item @emph{Description}:
8493 Prints (on the C @code{stderr} stream) a newline-terminated error
8494 message corresponding to the last system error. This is prefixed by
8495 @var{STRING}, a colon and a space. See @code{perror(3)}.
8497 @item @emph{Standard}:
8503 @item @emph{Syntax}:
8504 @code{CALL PERROR(STRING)}
8506 @item @emph{Arguments}:
8507 @multitable @columnfractions .15 .70
8508 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
8512 @item @emph{See also}:
8519 @section @code{PRECISION} --- Decimal precision of a real kind
8521 @cindex model representation, precision
8524 @item @emph{Description}:
8525 @code{PRECISION(X)} returns the decimal precision in the model of the
8528 @item @emph{Standard}:
8529 Fortran 95 and later
8534 @item @emph{Syntax}:
8535 @code{RESULT = PRECISION(X)}
8537 @item @emph{Arguments}:
8538 @multitable @columnfractions .15 .70
8539 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8542 @item @emph{Return value}:
8543 The return value is of type @code{INTEGER} and of the default integer
8546 @item @emph{Example}:
8548 program prec_and_range
8549 real(kind=4) :: x(2)
8550 complex(kind=8) :: y
8552 print *, precision(x), range(x)
8553 print *, precision(y), range(y)
8554 end program prec_and_range
8561 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
8565 @item @emph{Description}:
8566 Determines whether an optional dummy argument is present.
8568 @item @emph{Standard}:
8569 Fortran 95 and later
8574 @item @emph{Syntax}:
8575 @code{RESULT = PRESENT(A)}
8577 @item @emph{Arguments}:
8578 @multitable @columnfractions .15 .70
8579 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
8580 value, or a dummy procedure. It shall be the name of an optional dummy argument
8581 accessible within the current subroutine or function.
8584 @item @emph{Return value}:
8585 Returns either @code{TRUE} if the optional argument @var{A} is present, or
8586 @code{FALSE} otherwise.
8588 @item @emph{Example}:
8590 PROGRAM test_present
8591 WRITE(*,*) f(), f(42) ! "F T"
8593 LOGICAL FUNCTION f(x)
8594 INTEGER, INTENT(IN), OPTIONAL :: x
8604 @section @code{PRODUCT} --- Product of array elements
8606 @cindex array, product
8607 @cindex array, multiply elements
8608 @cindex array, conditionally multiply elements
8609 @cindex multiply array elements
8612 @item @emph{Description}:
8613 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
8614 the corresponding element in @var{MASK} is @code{TRUE}.
8616 @item @emph{Standard}:
8617 Fortran 95 and later
8620 Transformational function
8622 @item @emph{Syntax}:
8623 @multitable @columnfractions .80
8624 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
8625 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
8628 @item @emph{Arguments}:
8629 @multitable @columnfractions .15 .70
8630 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
8631 @code{REAL} or @code{COMPLEX}.
8632 @item @var{DIM} @tab (Optional) shall be a scalar of type
8633 @code{INTEGER} with a value in the range from 1 to n, where n
8634 equals the rank of @var{ARRAY}.
8635 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
8636 and either be a scalar or an array of the same shape as @var{ARRAY}.
8639 @item @emph{Return value}:
8640 The result is of the same type as @var{ARRAY}.
8642 If @var{DIM} is absent, a scalar with the product of all elements in
8643 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
8644 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
8645 dimension @var{DIM} dropped is returned.
8648 @item @emph{Example}:
8650 PROGRAM test_product
8651 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
8652 print *, PRODUCT(x) ! all elements, product = 120
8653 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
8657 @item @emph{See also}:
8664 @section @code{RADIX} --- Base of a model number
8666 @cindex model representation, base
8667 @cindex model representation, radix
8670 @item @emph{Description}:
8671 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
8673 @item @emph{Standard}:
8674 Fortran 95 and later
8679 @item @emph{Syntax}:
8680 @code{RESULT = RADIX(X)}
8682 @item @emph{Arguments}:
8683 @multitable @columnfractions .15 .70
8684 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
8687 @item @emph{Return value}:
8688 The return value is a scalar of type @code{INTEGER} and of the default
8691 @item @emph{Example}:
8694 print *, "The radix for the default integer kind is", radix(0)
8695 print *, "The radix for the default real kind is", radix(0.0)
8696 end program test_radix
8704 @section @code{RAN} --- Real pseudo-random number
8706 @cindex random number generation
8709 @item @emph{Description}:
8710 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
8711 provided as an alias for @code{RAND}. See @ref{RAND} for complete
8714 @item @emph{Standard}:
8720 @item @emph{See also}:
8721 @ref{RAND}, @ref{RANDOM_NUMBER}
8727 @section @code{RAND} --- Real pseudo-random number
8729 @cindex random number generation
8732 @item @emph{Description}:
8733 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
8734 distribution between 0 and 1. If @var{FLAG} is 0, the next number
8735 in the current sequence is returned; if @var{FLAG} is 1, the generator
8736 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
8737 it is used as a new seed with @code{SRAND}.
8739 This intrinsic routine is provided for backwards compatibility with
8740 GNU Fortran 77. It implements a simple modulo generator as provided
8741 by @command{g77}. For new code, one should consider the use of
8742 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
8744 @item @emph{Standard}:
8750 @item @emph{Syntax}:
8751 @code{RESULT = RAND(I)}
8753 @item @emph{Arguments}:
8754 @multitable @columnfractions .15 .70
8755 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
8758 @item @emph{Return value}:
8759 The return value is of @code{REAL} type and the default kind.
8761 @item @emph{Example}:
8764 integer,parameter :: seed = 86456
8767 print *, rand(), rand(), rand(), rand()
8768 print *, rand(seed), rand(), rand(), rand()
8769 end program test_rand
8772 @item @emph{See also}:
8773 @ref{SRAND}, @ref{RANDOM_NUMBER}
8780 @section @code{RANDOM_NUMBER} --- Pseudo-random number
8781 @fnindex RANDOM_NUMBER
8782 @cindex random number generation
8785 @item @emph{Description}:
8786 Returns a single pseudorandom number or an array of pseudorandom numbers
8787 from the uniform distribution over the range @math{ 0 \leq x < 1}.
8789 The runtime-library implements George Marsaglia's KISS (Keep It Simple
8790 Stupid) random number generator (RNG). This RNG combines:
8792 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
8793 with a period of @math{2^{32}},
8794 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
8795 @item Two 16-bit multiply-with-carry generators with a period of
8796 @math{597273182964842497 > 2^{59}}.
8798 The overall period exceeds @math{2^{123}}.
8800 Please note, this RNG is thread safe if used within OpenMP directives,
8801 i.e., its state will be consistent while called from multiple threads.
8802 However, the KISS generator does not create random numbers in parallel
8803 from multiple sources, but in sequence from a single source. If an
8804 OpenMP-enabled application heavily relies on random numbers, one should
8805 consider employing a dedicated parallel random number generator instead.
8807 @item @emph{Standard}:
8808 Fortran 95 and later
8813 @item @emph{Syntax}:
8814 @code{RANDOM_NUMBER(HARVEST)}
8816 @item @emph{Arguments}:
8817 @multitable @columnfractions .15 .70
8818 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
8821 @item @emph{Example}:
8823 program test_random_number
8825 CALL init_random_seed() ! see example of RANDOM_SEED
8826 CALL RANDOM_NUMBER(r)
8830 @item @emph{See also}:
8837 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
8838 @fnindex RANDOM_SEED
8839 @cindex random number generation, seeding
8840 @cindex seeding a random number generator
8843 @item @emph{Description}:
8844 Restarts or queries the state of the pseudorandom number generator used by
8845 @code{RANDOM_NUMBER}.
8847 If @code{RANDOM_SEED} is called without arguments, it is initialized to
8848 a default state. The example below shows how to initialize the random
8849 seed based on the system's time.
8851 @item @emph{Standard}:
8852 Fortran 95 and later
8857 @item @emph{Syntax}:
8858 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
8860 @item @emph{Arguments}:
8861 @multitable @columnfractions .15 .70
8862 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
8863 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
8864 of the arrays used with the @var{PUT} and @var{GET} arguments.
8865 @item @var{PUT} @tab (Optional) Shall be an array of type default
8866 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
8867 the array must be larger than or equal to the number returned by the
8868 @var{SIZE} argument.
8869 @item @var{GET} @tab (Optional) Shall be an array of type default
8870 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
8871 of the array must be larger than or equal to the number returned by
8872 the @var{SIZE} argument.
8875 @item @emph{Example}:
8877 SUBROUTINE init_random_seed()
8878 INTEGER :: i, n, clock
8879 INTEGER, DIMENSION(:), ALLOCATABLE :: seed
8881 CALL RANDOM_SEED(size = n)
8884 CALL SYSTEM_CLOCK(COUNT=clock)
8886 seed = clock + 37 * (/ (i - 1, i = 1, n) /)
8887 CALL RANDOM_SEED(PUT = seed)
8893 @item @emph{See also}:
8900 @section @code{RANGE} --- Decimal exponent range
8902 @cindex model representation, range
8905 @item @emph{Description}:
8906 @code{RANGE(X)} returns the decimal exponent range in the model of the
8909 @item @emph{Standard}:
8910 Fortran 95 and later
8915 @item @emph{Syntax}:
8916 @code{RESULT = RANGE(X)}
8918 @item @emph{Arguments}:
8919 @multitable @columnfractions .15 .70
8920 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
8924 @item @emph{Return value}:
8925 The return value is of type @code{INTEGER} and of the default integer
8928 @item @emph{Example}:
8929 See @code{PRECISION} for an example.
8935 @section @code{REAL} --- Convert to real type
8938 @cindex conversion, to real
8939 @cindex complex numbers, real part
8942 @item @emph{Description}:
8943 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
8944 @code{REALPART} function is provided for compatibility with @command{g77},
8945 and its use is strongly discouraged.
8947 @item @emph{Standard}:
8948 Fortran 77 and later
8953 @item @emph{Syntax}:
8954 @multitable @columnfractions .80
8955 @item @code{RESULT = REAL(A [, KIND])}
8956 @item @code{RESULT = REALPART(Z)}
8959 @item @emph{Arguments}:
8960 @multitable @columnfractions .15 .70
8961 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
8963 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8964 expression indicating the kind parameter of the result.
8967 @item @emph{Return value}:
8968 These functions return a @code{REAL} variable or array under
8969 the following rules:
8973 @code{REAL(A)} is converted to a default real type if @var{A} is an
8974 integer or real variable.
8976 @code{REAL(A)} is converted to a real type with the kind type parameter
8977 of @var{A} if @var{A} is a complex variable.
8979 @code{REAL(A, KIND)} is converted to a real type with kind type
8980 parameter @var{KIND} if @var{A} is a complex, integer, or real
8984 @item @emph{Example}:
8987 complex :: x = (1.0, 2.0)
8988 print *, real(x), real(x,8), realpart(x)
8989 end program test_real
8992 @item @emph{See also}:
8993 @ref{DBLE}, @ref{DFLOAT}, @ref{FLOAT}
9000 @section @code{RENAME} --- Rename a file
9002 @cindex file system, rename file
9005 @item @emph{Description}:
9006 Renames a file from file @var{PATH1} to @var{PATH2}. A null
9007 character (@code{CHAR(0)}) can be used to mark the end of the names in
9008 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
9009 names are ignored. If the @var{STATUS} argument is supplied, it
9010 contains 0 on success or a nonzero error code upon return; see
9013 This intrinsic is provided in both subroutine and function forms;
9014 however, only one form can be used in any given program unit.
9016 @item @emph{Standard}:
9020 Subroutine, function
9022 @item @emph{Syntax}:
9023 @multitable @columnfractions .80
9024 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
9025 @item @code{STATUS = RENAME(PATH1, PATH2)}
9028 @item @emph{Arguments}:
9029 @multitable @columnfractions .15 .70
9030 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
9031 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
9032 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9035 @item @emph{See also}:
9043 @section @code{REPEAT} --- Repeated string concatenation
9045 @cindex string, repeat
9046 @cindex string, concatenate
9049 @item @emph{Description}:
9050 Concatenates @var{NCOPIES} copies of a string.
9052 @item @emph{Standard}:
9053 Fortran 95 and later
9056 Transformational function
9058 @item @emph{Syntax}:
9059 @code{RESULT = REPEAT(STRING, NCOPIES)}
9061 @item @emph{Arguments}:
9062 @multitable @columnfractions .15 .70
9063 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
9064 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
9067 @item @emph{Return value}:
9068 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
9071 @item @emph{Example}:
9074 write(*,*) repeat("x", 5) ! "xxxxx"
9082 @section @code{RESHAPE} --- Function to reshape an array
9084 @cindex array, change dimensions
9085 @cindex array, transmogrify
9088 @item @emph{Description}:
9089 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
9090 the new array may be padded with elements from @var{PAD} or permuted
9091 as defined by @var{ORDER}.
9093 @item @emph{Standard}:
9094 Fortran 95 and later
9097 Transformational function
9099 @item @emph{Syntax}:
9100 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
9102 @item @emph{Arguments}:
9103 @multitable @columnfractions .15 .70
9104 @item @var{SOURCE} @tab Shall be an array of any type.
9105 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
9106 array of rank one. Its values must be positive or zero.
9107 @item @var{PAD} @tab (Optional) shall be an array of the same
9108 type as @var{SOURCE}.
9109 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
9110 and an array of the same shape as @var{SHAPE}. Its values shall
9111 be a permutation of the numbers from 1 to n, where n is the size of
9112 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
9116 @item @emph{Return value}:
9117 The result is an array of shape @var{SHAPE} with the same type as
9120 @item @emph{Example}:
9122 PROGRAM test_reshape
9123 INTEGER, DIMENSION(4) :: x
9124 WRITE(*,*) SHAPE(x) ! prints "4"
9125 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
9129 @item @emph{See also}:
9136 @section @code{RRSPACING} --- Reciprocal of the relative spacing
9138 @cindex real number, relative spacing
9139 @cindex floating point, relative spacing
9143 @item @emph{Description}:
9144 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
9145 model numbers near @var{X}.
9147 @item @emph{Standard}:
9148 Fortran 95 and later
9153 @item @emph{Syntax}:
9154 @code{RESULT = RRSPACING(X)}
9156 @item @emph{Arguments}:
9157 @multitable @columnfractions .15 .70
9158 @item @var{X} @tab Shall be of type @code{REAL}.
9161 @item @emph{Return value}:
9162 The return value is of the same type and kind as @var{X}.
9163 The value returned is equal to
9164 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
9166 @item @emph{See also}:
9173 @section @code{RSHIFT} --- Right shift bits
9175 @cindex bits, shift right
9178 @item @emph{Description}:
9179 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
9180 bits shifted right by @var{SHIFT} places. If the absolute value of
9181 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
9182 Bits shifted out from the left end are lost; zeros are shifted in from
9185 This function has been superseded by the @code{ISHFT} intrinsic, which
9186 is standard in Fortran 95 and later.
9188 @item @emph{Standard}:
9194 @item @emph{Syntax}:
9195 @code{RESULT = RSHIFT(I, SHIFT)}
9197 @item @emph{Arguments}:
9198 @multitable @columnfractions .15 .70
9199 @item @var{I} @tab The type shall be @code{INTEGER}.
9200 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
9203 @item @emph{Return value}:
9204 The return value is of type @code{INTEGER} and of the same kind as
9207 @item @emph{See also}:
9208 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}
9215 @section @code{SCALE} --- Scale a real value
9217 @cindex real number, scale
9218 @cindex floating point, scale
9221 @item @emph{Description}:
9222 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
9224 @item @emph{Standard}:
9225 Fortran 95 and later
9230 @item @emph{Syntax}:
9231 @code{RESULT = SCALE(X, I)}
9233 @item @emph{Arguments}:
9234 @multitable @columnfractions .15 .70
9235 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
9236 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
9239 @item @emph{Return value}:
9240 The return value is of the same type and kind as @var{X}.
9241 Its value is @code{X * RADIX(X)**I}.
9243 @item @emph{Example}:
9246 real :: x = 178.1387e-4
9248 print *, scale(x,i), x*radix(x)**i
9249 end program test_scale
9257 @section @code{SCAN} --- Scan a string for the presence of a set of characters
9259 @cindex string, find subset
9262 @item @emph{Description}:
9263 Scans a @var{STRING} for any of the characters in a @var{SET}
9266 If @var{BACK} is either absent or equals @code{FALSE}, this function
9267 returns the position of the leftmost character of @var{STRING} that is
9268 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
9269 is returned. If no character of @var{SET} is found in @var{STRING}, the
9272 @item @emph{Standard}:
9273 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
9278 @item @emph{Syntax}:
9279 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
9281 @item @emph{Arguments}:
9282 @multitable @columnfractions .15 .70
9283 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
9284 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
9285 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
9286 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9287 expression indicating the kind parameter of the result.
9290 @item @emph{Return value}:
9291 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9292 @var{KIND} is absent, the return value is of default integer kind.
9294 @item @emph{Example}:
9297 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
9298 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
9299 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
9303 @item @emph{See also}:
9304 @ref{INDEX intrinsic}, @ref{VERIFY}
9310 @section @code{SECNDS} --- Time function
9312 @cindex time, elapsed
9313 @cindex elapsed time
9316 @item @emph{Description}:
9317 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
9318 @var{X} is a reference time, also in seconds. If this is zero, the time in
9319 seconds from midnight is returned. This function is non-standard and its
9322 @item @emph{Standard}:
9328 @item @emph{Syntax}:
9329 @code{RESULT = SECNDS (X)}
9331 @item @emph{Arguments}:
9332 @multitable @columnfractions .15 .70
9333 @item @var{T} @tab Shall be of type @code{REAL(4)}.
9334 @item @var{X} @tab Shall be of type @code{REAL(4)}.
9337 @item @emph{Return value}:
9340 @item @emph{Example}:
9345 print *, secnds (0.0) ! seconds since midnight
9346 t1 = secnds (0.0) ! reference time
9347 do i = 1, 10000000 ! do something
9349 t2 = secnds (t1) ! elapsed time
9350 print *, "Something took ", t2, " seconds."
9351 end program test_secnds
9358 @section @code{SECOND} --- CPU time function
9360 @cindex time, elapsed
9361 @cindex elapsed time
9364 @item @emph{Description}:
9365 Returns a @code{REAL(4)} value representing the elapsed CPU time in
9366 seconds. This provides the same functionality as the standard
9367 @code{CPU_TIME} intrinsic, and is only included for backwards
9370 This intrinsic is provided in both subroutine and function forms;
9371 however, only one form can be used in any given program unit.
9373 @item @emph{Standard}:
9377 Subroutine, function
9379 @item @emph{Syntax}:
9380 @multitable @columnfractions .80
9381 @item @code{CALL SECOND(TIME)}
9382 @item @code{TIME = SECOND()}
9385 @item @emph{Arguments}:
9386 @multitable @columnfractions .15 .70
9387 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
9390 @item @emph{Return value}:
9391 In either syntax, @var{TIME} is set to the process's current runtime in
9394 @item @emph{See also}:
9401 @node SELECTED_CHAR_KIND
9402 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
9403 @fnindex SELECTED_CHAR_KIND
9404 @cindex character kind
9405 @cindex kind, character
9408 @item @emph{Description}:
9410 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
9411 set named @var{NAME}, if a character set with such a name is supported,
9412 or @math{-1} otherwise. Currently, supported character sets include
9413 ``ASCII'' and ``DEFAULT'', which are equivalent.
9415 @item @emph{Standard}:
9416 Fortran 2003 and later
9419 Transformational function
9421 @item @emph{Syntax}:
9422 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
9424 @item @emph{Arguments}:
9425 @multitable @columnfractions .15 .70
9426 @item @var{NAME} @tab Shall be a scalar and of the default character type.
9429 @item @emph{Example}:
9432 integer,parameter :: ascii = selected_char_kind("ascii")
9433 character(kind=ascii, len=26) :: s
9435 s = ascii_"abcdefghijklmnopqrstuvwxyz"
9437 end program ascii_kind
9443 @node SELECTED_INT_KIND
9444 @section @code{SELECTED_INT_KIND} --- Choose integer kind
9445 @fnindex SELECTED_INT_KIND
9446 @cindex integer kind
9447 @cindex kind, integer
9450 @item @emph{Description}:
9451 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
9452 type that can represent all values ranging from @math{-10^R} (exclusive)
9453 to @math{10^R} (exclusive). If there is no integer kind that accommodates
9454 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
9456 @item @emph{Standard}:
9457 Fortran 95 and later
9460 Transformational function
9462 @item @emph{Syntax}:
9463 @code{RESULT = SELECTED_INT_KIND(R)}
9465 @item @emph{Arguments}:
9466 @multitable @columnfractions .15 .70
9467 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
9470 @item @emph{Example}:
9472 program large_integers
9473 integer,parameter :: k5 = selected_int_kind(5)
9474 integer,parameter :: k15 = selected_int_kind(15)
9475 integer(kind=k5) :: i5
9476 integer(kind=k15) :: i15
9478 print *, huge(i5), huge(i15)
9480 ! The following inequalities are always true
9481 print *, huge(i5) >= 10_k5**5-1
9482 print *, huge(i15) >= 10_k15**15-1
9483 end program large_integers
9489 @node SELECTED_REAL_KIND
9490 @section @code{SELECTED_REAL_KIND} --- Choose real kind
9491 @fnindex SELECTED_REAL_KIND
9496 @item @emph{Description}:
9497 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
9498 with decimal precision of at least @code{P} digits and exponent
9499 range greater at least @code{R}.
9501 @item @emph{Standard}:
9502 Fortran 95 and later
9505 Transformational function
9507 @item @emph{Syntax}:
9508 @code{RESULT = SELECTED_REAL_KIND([P, R])}
9510 @item @emph{Arguments}:
9511 @multitable @columnfractions .15 .70
9512 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9513 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9515 At least one argument shall be present.
9517 @item @emph{Return value}:
9519 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
9520 a real data type with decimal precision of at least @code{P} digits and a
9521 decimal exponent range of at least @code{R}. If more than one real data
9522 type meet the criteria, the kind of the data type with the smallest
9523 decimal precision is returned. If no real data type matches the criteria,
9526 @item -1 if the processor does not support a real data type with a
9527 precision greater than or equal to @code{P}
9528 @item -2 if the processor does not support a real type with an exponent
9529 range greater than or equal to @code{R}
9530 @item -3 if neither is supported.
9533 @item @emph{Example}:
9536 integer,parameter :: p6 = selected_real_kind(6)
9537 integer,parameter :: p10r100 = selected_real_kind(10,100)
9538 integer,parameter :: r400 = selected_real_kind(r=400)
9540 real(kind=p10r100) :: y
9541 real(kind=r400) :: z
9543 print *, precision(x), range(x)
9544 print *, precision(y), range(y)
9545 print *, precision(z), range(z)
9546 end program real_kinds
9553 @section @code{SET_EXPONENT} --- Set the exponent of the model
9554 @fnindex SET_EXPONENT
9555 @cindex real number, set exponent
9556 @cindex floating point, set exponent
9559 @item @emph{Description}:
9560 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
9561 is that that of @var{X} and whose exponent part is @var{I}.
9563 @item @emph{Standard}:
9564 Fortran 95 and later
9569 @item @emph{Syntax}:
9570 @code{RESULT = SET_EXPONENT(X, I)}
9572 @item @emph{Arguments}:
9573 @multitable @columnfractions .15 .70
9574 @item @var{X} @tab Shall be of type @code{REAL}.
9575 @item @var{I} @tab Shall be of type @code{INTEGER}.
9578 @item @emph{Return value}:
9579 The return value is of the same type and kind as @var{X}.
9580 The real number whose fractional part
9581 is that that of @var{X} and whose exponent part if @var{I} is returned;
9582 it is @code{FRACTION(X) * RADIX(X)**I}.
9584 @item @emph{Example}:
9587 REAL :: x = 178.1387e-4
9589 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
9598 @section @code{SHAPE} --- Determine the shape of an array
9600 @cindex array, shape
9603 @item @emph{Description}:
9604 Determines the shape of an array.
9606 @item @emph{Standard}:
9607 Fortran 95 and later
9612 @item @emph{Syntax}:
9613 @code{RESULT = SHAPE(SOURCE)}
9615 @item @emph{Arguments}:
9616 @multitable @columnfractions .15 .70
9617 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
9618 If @var{SOURCE} is a pointer it must be associated and allocatable
9619 arrays must be allocated.
9622 @item @emph{Return value}:
9623 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
9624 has dimensions. The elements of the resulting array correspond to the extend
9625 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
9626 the result is the rank one array of size zero.
9628 @item @emph{Example}:
9631 INTEGER, DIMENSION(-1:1, -1:2) :: A
9632 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
9633 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
9637 @item @emph{See also}:
9638 @ref{RESHAPE}, @ref{SIZE}
9644 @section @code{SIGN} --- Sign copying function
9648 @cindex sign copying
9651 @item @emph{Description}:
9652 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
9654 @item @emph{Standard}:
9655 Fortran 77 and later
9660 @item @emph{Syntax}:
9661 @code{RESULT = SIGN(A, B)}
9663 @item @emph{Arguments}:
9664 @multitable @columnfractions .15 .70
9665 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
9666 @item @var{B} @tab Shall be of the same type and kind as @var{A}
9669 @item @emph{Return value}:
9670 The kind of the return value is that of @var{A} and @var{B}.
9671 If @math{B\ge 0} then the result is @code{ABS(A)}, else
9672 it is @code{-ABS(A)}.
9674 @item @emph{Example}:
9677 print *, sign(-12,1)
9678 print *, sign(-12,0)
9679 print *, sign(-12,-1)
9681 print *, sign(-12.,1.)
9682 print *, sign(-12.,0.)
9683 print *, sign(-12.,-1.)
9684 end program test_sign
9687 @item @emph{Specific names}:
9688 @multitable @columnfractions .20 .20 .20 .25
9689 @item Name @tab Arguments @tab Return type @tab Standard
9690 @item @code{ISIGN(A,P)} @tab @code{INTEGER(4)} @tab @code{INTEGER(4)} @tab f95, gnu
9691 @item @code{DSIGN(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab f95, gnu
9698 @section @code{SIGNAL} --- Signal handling subroutine (or function)
9700 @cindex system, signal handling
9703 @item @emph{Description}:
9704 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
9705 @var{HANDLER} to be executed with a single integer argument when signal
9706 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
9707 turn off handling of signal @var{NUMBER} or revert to its default
9708 action. See @code{signal(2)}.
9710 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
9711 is supplied, it is set to the value returned by @code{signal(2)}.
9713 @item @emph{Standard}:
9717 Subroutine, function
9719 @item @emph{Syntax}:
9720 @multitable @columnfractions .80
9721 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
9722 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
9725 @item @emph{Arguments}:
9726 @multitable @columnfractions .15 .70
9727 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
9728 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
9729 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
9730 @code{INTEGER}. It is @code{INTENT(IN)}.
9731 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
9732 integer. It has @code{INTENT(OUT)}.
9734 @c TODO: What should the interface of the handler be? Does it take arguments?
9736 @item @emph{Return value}:
9737 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
9739 @item @emph{Example}:
9743 external handler_print
9745 call signal (12, handler_print)
9749 end program test_signal
9756 @section @code{SIN} --- Sine function
9762 @cindex trigonometric function, sine
9766 @item @emph{Description}:
9767 @code{SIN(X)} computes the sine of @var{X}.
9769 @item @emph{Standard}:
9770 Fortran 77 and later
9775 @item @emph{Syntax}:
9776 @code{RESULT = SIN(X)}
9778 @item @emph{Arguments}:
9779 @multitable @columnfractions .15 .70
9780 @item @var{X} @tab The type shall be @code{REAL} or
9784 @item @emph{Return value}:
9785 The return value has same type and kind as @var{X}.
9787 @item @emph{Example}:
9792 end program test_sin
9795 @item @emph{Specific names}:
9796 @multitable @columnfractions .20 .20 .20 .25
9797 @item Name @tab Argument @tab Return type @tab Standard
9798 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
9799 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
9800 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9801 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9804 @item @emph{See also}:
9811 @section @code{SINH} --- Hyperbolic sine function
9814 @cindex hyperbolic sine
9815 @cindex hyperbolic function, sine
9816 @cindex sine, hyperbolic
9819 @item @emph{Description}:
9820 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
9822 @item @emph{Standard}:
9823 Fortran 95 and later
9828 @item @emph{Syntax}:
9829 @code{RESULT = SINH(X)}
9831 @item @emph{Arguments}:
9832 @multitable @columnfractions .15 .70
9833 @item @var{X} @tab The type shall be @code{REAL}.
9836 @item @emph{Return value}:
9837 The return value is of type @code{REAL}.
9839 @item @emph{Example}:
9842 real(8) :: x = - 1.0_8
9844 end program test_sinh
9847 @item @emph{Specific names}:
9848 @multitable @columnfractions .20 .20 .20 .25
9849 @item Name @tab Argument @tab Return type @tab Standard
9850 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
9853 @item @emph{See also}:
9860 @section @code{SIZE} --- Determine the size of an array
9863 @cindex array, number of elements
9864 @cindex array, count elements
9867 @item @emph{Description}:
9868 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
9869 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
9871 @item @emph{Standard}:
9872 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
9877 @item @emph{Syntax}:
9878 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
9880 @item @emph{Arguments}:
9881 @multitable @columnfractions .15 .70
9882 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
9883 a pointer it must be associated and allocatable arrays must be allocated.
9884 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
9885 and its value shall be in the range from 1 to n, where n equals the rank
9887 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9888 expression indicating the kind parameter of the result.
9891 @item @emph{Return value}:
9892 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9893 @var{KIND} is absent, the return value is of default integer kind.
9895 @item @emph{Example}:
9898 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
9902 @item @emph{See also}:
9903 @ref{SHAPE}, @ref{RESHAPE}
9908 @section @code{SIZEOF} --- Size in bytes of an expression
9910 @cindex expression size
9911 @cindex size of an expression
9914 @item @emph{Description}:
9915 @code{SIZEOF(X)} calculates the number of bytes of storage the
9916 expression @code{X} occupies.
9918 @item @emph{Standard}:
9924 @item @emph{Syntax}:
9925 @code{N = SIZEOF(X)}
9927 @item @emph{Arguments}:
9928 @multitable @columnfractions .15 .70
9929 @item @var{X} @tab The argument shall be of any type, rank or shape.
9932 @item @emph{Return value}:
9933 The return value is of type integer and of the system-dependent kind
9934 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
9935 number of bytes occupied by the argument. If the argument has the
9936 @code{POINTER} attribute, the number of bytes of the storage area pointed
9937 to is returned. If the argument is of a derived type with @code{POINTER}
9938 or @code{ALLOCATABLE} components, the return value doesn't account for
9939 the sizes of the data pointed to by these components.
9941 @item @emph{Example}:
9945 print *, (sizeof(s)/sizeof(r) == 5)
9948 The example will print @code{.TRUE.} unless you are using a platform
9949 where default @code{REAL} variables are unusually padded.
9951 @item @emph{See also}:
9957 @section @code{SLEEP} --- Sleep for the specified number of seconds
9959 @cindex delayed execution
9962 @item @emph{Description}:
9963 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
9965 @item @emph{Standard}:
9971 @item @emph{Syntax}:
9972 @code{CALL SLEEP(SECONDS)}
9974 @item @emph{Arguments}:
9975 @multitable @columnfractions .15 .70
9976 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
9979 @item @emph{Example}:
9990 @section @code{SNGL} --- Convert double precision real to default real
9992 @cindex conversion, to real
9995 @item @emph{Description}:
9996 @code{SNGL(A)} converts the double precision real @var{A}
9997 to a default real value. This is an archaic form of @code{REAL}
9998 that is specific to one type for @var{A}.
10000 @item @emph{Standard}:
10001 Fortran 77 and later
10003 @item @emph{Class}:
10006 @item @emph{Syntax}:
10007 @code{RESULT = SNGL(A)}
10009 @item @emph{Arguments}:
10010 @multitable @columnfractions .15 .70
10011 @item @var{A} @tab The type shall be a double precision @code{REAL}.
10014 @item @emph{Return value}:
10015 The return value is of type default @code{REAL}.
10017 @item @emph{See also}:
10024 @section @code{SPACING} --- Smallest distance between two numbers of a given type
10026 @cindex real number, relative spacing
10027 @cindex floating point, relative spacing
10030 @item @emph{Description}:
10031 Determines the distance between the argument @var{X} and the nearest
10032 adjacent number of the same type.
10034 @item @emph{Standard}:
10035 Fortran 95 and later
10037 @item @emph{Class}:
10040 @item @emph{Syntax}:
10041 @code{RESULT = SPACING(X)}
10043 @item @emph{Arguments}:
10044 @multitable @columnfractions .15 .70
10045 @item @var{X} @tab Shall be of type @code{REAL}.
10048 @item @emph{Return value}:
10049 The result is of the same type as the input argument @var{X}.
10051 @item @emph{Example}:
10053 PROGRAM test_spacing
10054 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
10055 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
10057 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
10058 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
10062 @item @emph{See also}:
10069 @section @code{SPREAD} --- Add a dimension to an array
10071 @cindex array, increase dimension
10072 @cindex array, duplicate elements
10073 @cindex array, duplicate dimensions
10076 @item @emph{Description}:
10077 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
10078 dimension @var{DIM}.
10080 @item @emph{Standard}:
10081 Fortran 95 and later
10083 @item @emph{Class}:
10084 Transformational function
10086 @item @emph{Syntax}:
10087 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
10089 @item @emph{Arguments}:
10090 @multitable @columnfractions .15 .70
10091 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
10092 a rank less than seven.
10093 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
10094 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
10095 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
10098 @item @emph{Return value}:
10099 The result is an array of the same type as @var{SOURCE} and has rank n+1
10100 where n equals the rank of @var{SOURCE}.
10102 @item @emph{Example}:
10104 PROGRAM test_spread
10105 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
10106 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
10107 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
10111 @item @emph{See also}:
10118 @section @code{SQRT} --- Square-root function
10125 @cindex square-root
10128 @item @emph{Description}:
10129 @code{SQRT(X)} computes the square root of @var{X}.
10131 @item @emph{Standard}:
10132 Fortran 77 and later
10134 @item @emph{Class}:
10137 @item @emph{Syntax}:
10138 @code{RESULT = SQRT(X)}
10140 @item @emph{Arguments}:
10141 @multitable @columnfractions .15 .70
10142 @item @var{X} @tab The type shall be @code{REAL} or
10146 @item @emph{Return value}:
10147 The return value is of type @code{REAL} or @code{COMPLEX}.
10148 The kind type parameter is the same as @var{X}.
10150 @item @emph{Example}:
10153 real(8) :: x = 2.0_8
10154 complex :: z = (1.0, 2.0)
10157 end program test_sqrt
10160 @item @emph{Specific names}:
10161 @multitable @columnfractions .20 .20 .20 .25
10162 @item Name @tab Argument @tab Return type @tab Standard
10163 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10164 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
10165 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
10166 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
10173 @section @code{SRAND} --- Reinitialize the random number generator
10175 @cindex random number generation, seeding
10176 @cindex seeding a random number generator
10179 @item @emph{Description}:
10180 @code{SRAND} reinitializes the pseudo-random number generator
10181 called by @code{RAND} and @code{IRAND}. The new seed used by the
10182 generator is specified by the required argument @var{SEED}.
10184 @item @emph{Standard}:
10187 @item @emph{Class}:
10190 @item @emph{Syntax}:
10191 @code{CALL SRAND(SEED)}
10193 @item @emph{Arguments}:
10194 @multitable @columnfractions .15 .70
10195 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
10198 @item @emph{Return value}:
10199 Does not return anything.
10201 @item @emph{Example}:
10202 See @code{RAND} and @code{IRAND} for examples.
10204 @item @emph{Notes}:
10205 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
10206 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
10207 to generate pseudo-random numbers. Please note that in
10208 GNU Fortran, these two sets of intrinsics (@code{RAND},
10209 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
10210 @code{RANDOM_SEED} on the other hand) access two independent
10211 pseudo-random number generators.
10213 @item @emph{See also}:
10214 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
10221 @section @code{STAT} --- Get file status
10223 @cindex file system, file status
10226 @item @emph{Description}:
10227 This function returns information about a file. No permissions are required on
10228 the file itself, but execute (search) permission is required on all of the
10229 directories in path that lead to the file.
10231 The elements that are obtained and stored in the array @code{VALUES}:
10232 @multitable @columnfractions .15 .70
10233 @item @code{VALUES(1)} @tab Device ID
10234 @item @code{VALUES(2)} @tab Inode number
10235 @item @code{VALUES(3)} @tab File mode
10236 @item @code{VALUES(4)} @tab Number of links
10237 @item @code{VALUES(5)} @tab Owner's uid
10238 @item @code{VALUES(6)} @tab Owner's gid
10239 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
10240 @item @code{VALUES(8)} @tab File size (bytes)
10241 @item @code{VALUES(9)} @tab Last access time
10242 @item @code{VALUES(10)} @tab Last modification time
10243 @item @code{VALUES(11)} @tab Last file status change time
10244 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
10245 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
10248 Not all these elements are relevant on all systems.
10249 If an element is not relevant, it is returned as 0.
10251 This intrinsic is provided in both subroutine and function forms; however,
10252 only one form can be used in any given program unit.
10254 @item @emph{Standard}:
10257 @item @emph{Class}:
10258 Subroutine, function
10260 @item @emph{Syntax}:
10261 @code{CALL STAT(NAME, VALUES [, STATUS])}
10263 @item @emph{Arguments}:
10264 @multitable @columnfractions .15 .70
10265 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
10266 default kind and a valid path within the file system.
10267 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
10268 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
10269 on success and a system specific error code otherwise.
10272 @item @emph{Example}:
10275 INTEGER, DIMENSION(13) :: buff
10278 CALL STAT("/etc/passwd", buff, status)
10280 IF (status == 0) THEN
10281 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
10282 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
10283 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
10284 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
10285 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
10286 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
10287 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
10288 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
10289 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
10290 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
10291 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
10292 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
10293 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
10298 @item @emph{See also}:
10299 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
10305 @section @code{SUM} --- Sum of array elements
10308 @cindex array, add elements
10309 @cindex array, conditionally add elements
10310 @cindex sum array elements
10313 @item @emph{Description}:
10314 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
10315 the corresponding element in @var{MASK} is @code{TRUE}.
10317 @item @emph{Standard}:
10318 Fortran 95 and later
10320 @item @emph{Class}:
10321 Transformational function
10323 @item @emph{Syntax}:
10324 @multitable @columnfractions .80
10325 @item @code{RESULT = SUM(ARRAY[, MASK])}
10326 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
10329 @item @emph{Arguments}:
10330 @multitable @columnfractions .15 .70
10331 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
10332 @code{REAL} or @code{COMPLEX}.
10333 @item @var{DIM} @tab (Optional) shall be a scalar of type
10334 @code{INTEGER} with a value in the range from 1 to n, where n
10335 equals the rank of @var{ARRAY}.
10336 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
10337 and either be a scalar or an array of the same shape as @var{ARRAY}.
10340 @item @emph{Return value}:
10341 The result is of the same type as @var{ARRAY}.
10343 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
10344 is returned. Otherwise, an array of rank n-1, where n equals the rank of
10345 @var{ARRAY},and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
10346 dropped is returned.
10348 @item @emph{Example}:
10351 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
10352 print *, SUM(x) ! all elements, sum = 15
10353 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
10357 @item @emph{See also}:
10364 @section @code{SYMLNK} --- Create a symbolic link
10366 @cindex file system, create link
10367 @cindex file system, soft link
10370 @item @emph{Description}:
10371 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
10372 character (@code{CHAR(0)}) can be used to mark the end of the names in
10373 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10374 names are ignored. If the @var{STATUS} argument is supplied, it
10375 contains 0 on success or a nonzero error code upon return; see
10376 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
10377 @code{ENOSYS} is returned.
10379 This intrinsic is provided in both subroutine and function forms;
10380 however, only one form can be used in any given program unit.
10382 @item @emph{Standard}:
10385 @item @emph{Class}:
10386 Subroutine, function
10388 @item @emph{Syntax}:
10389 @multitable @columnfractions .80
10390 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
10391 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
10394 @item @emph{Arguments}:
10395 @multitable @columnfractions .15 .70
10396 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10397 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10398 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10401 @item @emph{See also}:
10402 @ref{LINK}, @ref{UNLINK}
10409 @section @code{SYSTEM} --- Execute a shell command
10411 @cindex system, system call
10414 @item @emph{Description}:
10415 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
10416 argument @var{STATUS} is present, it contains the value returned by
10417 @code{system(3)}, which is presumably 0 if the shell command succeeded.
10418 Note that which shell is used to invoke the command is system-dependent
10419 and environment-dependent.
10421 This intrinsic is provided in both subroutine and function forms;
10422 however, only one form can be used in any given program unit.
10424 @item @emph{Standard}:
10427 @item @emph{Class}:
10428 Subroutine, function
10430 @item @emph{Syntax}:
10431 @multitable @columnfractions .80
10432 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
10433 @item @code{STATUS = SYSTEM(COMMAND)}
10436 @item @emph{Arguments}:
10437 @multitable @columnfractions .15 .70
10438 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
10439 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10442 @item @emph{See also}:
10448 @section @code{SYSTEM_CLOCK} --- Time function
10449 @fnindex SYSTEM_CLOCK
10450 @cindex time, clock ticks
10451 @cindex clock ticks
10454 @item @emph{Description}:
10455 Determines the @var{COUNT} of milliseconds of wall clock time since
10456 the Epoch (00:00:00 UTC, January 1, 1970) modulo @var{COUNT_MAX},
10457 @var{COUNT_RATE} determines the number of clock ticks per second.
10458 @var{COUNT_RATE} and @var{COUNT_MAX} are constant and specific to
10459 @command{gfortran}.
10461 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
10462 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero
10464 @item @emph{Standard}:
10465 Fortran 95 and later
10467 @item @emph{Class}:
10470 @item @emph{Syntax}:
10471 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
10473 @item @emph{Arguments}:
10474 @item @emph{Arguments}:
10475 @multitable @columnfractions .15 .70
10476 @item @var{COUNT} @tab (Optional) shall be a scalar of type default
10477 @code{INTEGER} with @code{INTENT(OUT)}.
10478 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type default
10479 @code{INTEGER} with @code{INTENT(OUT)}.
10480 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type default
10481 @code{INTEGER} with @code{INTENT(OUT)}.
10484 @item @emph{Example}:
10486 PROGRAM test_system_clock
10487 INTEGER :: count, count_rate, count_max
10488 CALL SYSTEM_CLOCK(count, count_rate, count_max)
10489 WRITE(*,*) count, count_rate, count_max
10493 @item @emph{See also}:
10494 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
10500 @section @code{TAN} --- Tangent function
10503 @cindex trigonometric function, tangent
10507 @item @emph{Description}:
10508 @code{TAN(X)} computes the tangent of @var{X}.
10510 @item @emph{Standard}:
10511 Fortran 77 and later
10513 @item @emph{Class}:
10516 @item @emph{Syntax}:
10517 @code{RESULT = TAN(X)}
10519 @item @emph{Arguments}:
10520 @multitable @columnfractions .15 .70
10521 @item @var{X} @tab The type shall be @code{REAL}.
10524 @item @emph{Return value}:
10525 The return value is of type @code{REAL}. The kind type parameter is
10526 the same as @var{X}.
10528 @item @emph{Example}:
10531 real(8) :: x = 0.165_8
10533 end program test_tan
10536 @item @emph{Specific names}:
10537 @multitable @columnfractions .20 .20 .20 .25
10538 @item Name @tab Argument @tab Return type @tab Standard
10539 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10542 @item @emph{See also}:
10549 @section @code{TANH} --- Hyperbolic tangent function
10552 @cindex hyperbolic tangent
10553 @cindex hyperbolic function, tangent
10554 @cindex tangent, hyperbolic
10557 @item @emph{Description}:
10558 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
10560 @item @emph{Standard}:
10561 Fortran 77 and later
10563 @item @emph{Class}:
10566 @item @emph{Syntax}:
10569 @item @emph{Arguments}:
10570 @multitable @columnfractions .15 .70
10571 @item @var{X} @tab The type shall be @code{REAL}.
10574 @item @emph{Return value}:
10575 The return value is of type @code{REAL} and lies in the range
10576 @math{ - 1 \leq tanh(x) \leq 1 }.
10578 @item @emph{Example}:
10581 real(8) :: x = 2.1_8
10583 end program test_tanh
10586 @item @emph{Specific names}:
10587 @multitable @columnfractions .20 .20 .20 .25
10588 @item Name @tab Argument @tab Return type @tab Standard
10589 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10592 @item @emph{See also}:
10599 @section @code{TIME} --- Time function
10601 @cindex time, current
10602 @cindex current time
10605 @item @emph{Description}:
10606 Returns the current time encoded as an integer (in the manner of the
10607 UNIX function @code{time(3)}). This value is suitable for passing to
10608 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10610 This intrinsic is not fully portable, such as to systems with 32-bit
10611 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
10612 the values returned by this intrinsic might be, or become, negative, or
10613 numerically less than previous values, during a single run of the
10616 See @ref{TIME8}, for information on a similar intrinsic that might be
10617 portable to more GNU Fortran implementations, though to fewer Fortran
10620 @item @emph{Standard}:
10623 @item @emph{Class}:
10626 @item @emph{Syntax}:
10627 @code{RESULT = TIME()}
10629 @item @emph{Return value}:
10630 The return value is a scalar of type @code{INTEGER(4)}.
10632 @item @emph{See also}:
10633 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
10640 @section @code{TIME8} --- Time function (64-bit)
10642 @cindex time, current
10643 @cindex current time
10646 @item @emph{Description}:
10647 Returns the current time encoded as an integer (in the manner of the
10648 UNIX function @code{time(3)}). This value is suitable for passing to
10649 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10651 @emph{Warning:} this intrinsic does not increase the range of the timing
10652 values over that returned by @code{time(3)}. On a system with a 32-bit
10653 @code{time(3)}, @code{TIME8()} will return a 32-bit value, even though
10654 it is converted to a 64-bit @code{INTEGER(8)} value. That means
10655 overflows of the 32-bit value can still occur. Therefore, the values
10656 returned by this intrinsic might be or become negative or numerically
10657 less than previous values during a single run of the compiled program.
10659 @item @emph{Standard}:
10662 @item @emph{Class}:
10665 @item @emph{Syntax}:
10666 @code{RESULT = TIME8()}
10668 @item @emph{Return value}:
10669 The return value is a scalar of type @code{INTEGER(8)}.
10671 @item @emph{See also}:
10672 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
10679 @section @code{TINY} --- Smallest positive number of a real kind
10681 @cindex limits, smallest number
10682 @cindex model representation, smallest number
10685 @item @emph{Description}:
10686 @code{TINY(X)} returns the smallest positive (non zero) number
10687 in the model of the type of @code{X}.
10689 @item @emph{Standard}:
10690 Fortran 95 and later
10692 @item @emph{Class}:
10695 @item @emph{Syntax}:
10696 @code{RESULT = TINY(X)}
10698 @item @emph{Arguments}:
10699 @multitable @columnfractions .15 .70
10700 @item @var{X} @tab Shall be of type @code{REAL}.
10703 @item @emph{Return value}:
10704 The return value is of the same type and kind as @var{X}
10706 @item @emph{Example}:
10707 See @code{HUGE} for an example.
10713 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
10718 @item @emph{Description}:
10719 @code{TRAILZ} returns the number of trailing zero bits of an integer.
10721 @item @emph{Standard}:
10722 Fortran 2008 and later
10724 @item @emph{Class}:
10727 @item @emph{Syntax}:
10728 @code{RESULT = TRAILZ(I)}
10730 @item @emph{Arguments}:
10731 @multitable @columnfractions .15 .70
10732 @item @var{I} @tab Shall be of type @code{INTEGER}.
10735 @item @emph{Return value}:
10736 The type of the return value is the default @code{INTEGER}.
10737 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
10739 @item @emph{Example}:
10741 PROGRAM test_trailz
10742 WRITE (*,*) TRAILZ(8) ! prints 3
10746 @item @emph{See also}:
10747 @ref{BIT_SIZE}, @ref{LEADZ}
10753 @section @code{TRANSFER} --- Transfer bit patterns
10759 @item @emph{Description}:
10760 Interprets the bitwise representation of @var{SOURCE} in memory as if it
10761 is the representation of a variable or array of the same type and type
10762 parameters as @var{MOLD}.
10764 This is approximately equivalent to the C concept of @emph{casting} one
10767 @item @emph{Standard}:
10768 Fortran 95 and later
10770 @item @emph{Class}:
10771 Transformational function
10773 @item @emph{Syntax}:
10774 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
10776 @item @emph{Arguments}:
10777 @multitable @columnfractions .15 .70
10778 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
10779 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
10780 @item @var{SIZE} @tab (Optional) shall be a scalar of type
10784 @item @emph{Return value}:
10785 The result has the same type as @var{MOLD}, with the bit level
10786 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
10787 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
10788 but @var{MOLD} is an array (of any size or shape), the result is a one-
10789 dimensional array of the minimum length needed to contain the entirety
10790 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
10791 and @var{MOLD} is a scalar, the result is a scalar.
10793 If the bitwise representation of the result is longer than that of
10794 @var{SOURCE}, then the leading bits of the result correspond to those of
10795 @var{SOURCE} and any trailing bits are filled arbitrarily.
10797 When the resulting bit representation does not correspond to a valid
10798 representation of a variable of the same type as @var{MOLD}, the results
10799 are undefined, and subsequent operations on the result cannot be
10800 guaranteed to produce sensible behavior. For example, it is possible to
10801 create @code{LOGICAL} variables for which @code{@var{VAR}} and
10802 @code{.NOT.@var{VAR}} both appear to be true.
10804 @item @emph{Example}:
10806 PROGRAM test_transfer
10807 integer :: x = 2143289344
10808 print *, transfer(x, 1.0) ! prints "NaN" on i686
10816 @section @code{TRANSPOSE} --- Transpose an array of rank two
10818 @cindex array, transpose
10819 @cindex matrix, transpose
10823 @item @emph{Description}:
10824 Transpose an array of rank two. Element (i, j) of the result has the value
10825 @code{MATRIX(j, i)}, for all i, j.
10827 @item @emph{Standard}:
10828 Fortran 95 and later
10830 @item @emph{Class}:
10831 Transformational function
10833 @item @emph{Syntax}:
10834 @code{RESULT = TRANSPOSE(MATRIX)}
10836 @item @emph{Arguments}:
10837 @multitable @columnfractions .15 .70
10838 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
10841 @item @emph{Return value}:
10842 The result has the same type as @var{MATRIX}, and has shape
10843 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
10849 @section @code{TRIM} --- Remove trailing blank characters of a string
10851 @cindex string, remove trailing whitespace
10854 @item @emph{Description}:
10855 Removes trailing blank characters of a string.
10857 @item @emph{Standard}:
10858 Fortran 95 and later
10860 @item @emph{Class}:
10861 Transformational function
10863 @item @emph{Syntax}:
10864 @code{RESULT = TRIM(STRING)}
10866 @item @emph{Arguments}:
10867 @multitable @columnfractions .15 .70
10868 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
10871 @item @emph{Return value}:
10872 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
10873 less the number of trailing blanks.
10875 @item @emph{Example}:
10878 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
10879 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
10883 @item @emph{See also}:
10884 @ref{ADJUSTL}, @ref{ADJUSTR}
10890 @section @code{TTYNAM} --- Get the name of a terminal device.
10892 @cindex system, terminal
10895 @item @emph{Description}:
10896 Get the name of a terminal device. For more information,
10897 see @code{ttyname(3)}.
10899 This intrinsic is provided in both subroutine and function forms;
10900 however, only one form can be used in any given program unit.
10902 @item @emph{Standard}:
10905 @item @emph{Class}:
10906 Subroutine, function
10908 @item @emph{Syntax}:
10909 @multitable @columnfractions .80
10910 @item @code{CALL TTYNAM(UNIT, NAME)}
10911 @item @code{NAME = TTYNAM(UNIT)}
10914 @item @emph{Arguments}:
10915 @multitable @columnfractions .15 .70
10916 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
10917 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
10920 @item @emph{Example}:
10922 PROGRAM test_ttynam
10925 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
10930 @item @emph{See also}:
10937 @section @code{UBOUND} --- Upper dimension bounds of an array
10939 @cindex array, upper bound
10942 @item @emph{Description}:
10943 Returns the upper bounds of an array, or a single upper bound
10944 along the @var{DIM} dimension.
10945 @item @emph{Standard}:
10946 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10948 @item @emph{Class}:
10951 @item @emph{Syntax}:
10952 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
10954 @item @emph{Arguments}:
10955 @multitable @columnfractions .15 .70
10956 @item @var{ARRAY} @tab Shall be an array, of any type.
10957 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
10958 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
10959 expression indicating the kind parameter of the result.
10962 @item @emph{Return value}:
10963 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10964 @var{KIND} is absent, the return value is of default integer kind.
10965 If @var{DIM} is absent, the result is an array of the upper bounds of
10966 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
10967 corresponding to the upper bound of the array along that dimension. If
10968 @var{ARRAY} is an expression rather than a whole array or array
10969 structure component, or if it has a zero extent along the relevant
10970 dimension, the upper bound is taken to be the number of elements along
10971 the relevant dimension.
10973 @item @emph{See also}:
10980 @section @code{UMASK} --- Set the file creation mask
10982 @cindex file system, file creation mask
10985 @item @emph{Description}:
10986 Sets the file creation mask to @var{MASK}. If called as a function, it
10987 returns the old value. If called as a subroutine and argument @var{OLD}
10988 if it is supplied, it is set to the old value. See @code{umask(2)}.
10990 @item @emph{Standard}:
10993 @item @emph{Class}:
10994 Subroutine, function
10996 @item @emph{Syntax}:
10997 @code{CALL UMASK(MASK [, OLD])}
10998 @code{OLD = UMASK(MASK)}
11000 @item @emph{Arguments}:
11001 @multitable @columnfractions .15 .70
11002 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
11003 @item @var{OLD} @tab (Optional) Shall be a scalar of type
11012 @section @code{UNLINK} --- Remove a file from the file system
11014 @cindex file system, remove file
11017 @item @emph{Description}:
11018 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
11019 used to mark the end of the name in @var{PATH}; otherwise, trailing
11020 blanks in the file name are ignored. If the @var{STATUS} argument is
11021 supplied, it contains 0 on success or a nonzero error code upon return;
11022 see @code{unlink(2)}.
11024 This intrinsic is provided in both subroutine and function forms;
11025 however, only one form can be used in any given program unit.
11027 @item @emph{Standard}:
11030 @item @emph{Class}:
11031 Subroutine, function
11033 @item @emph{Syntax}:
11034 @multitable @columnfractions .80
11035 @item @code{CALL UNLINK(PATH [, STATUS])}
11036 @item @code{STATUS = UNLINK(PATH)}
11039 @item @emph{Arguments}:
11040 @multitable @columnfractions .15 .70
11041 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
11042 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11045 @item @emph{See also}:
11046 @ref{LINK}, @ref{SYMLNK}
11052 @section @code{UNPACK} --- Unpack an array of rank one into an array
11054 @cindex array, unpacking
11055 @cindex array, increase dimension
11056 @cindex array, scatter elements
11059 @item @emph{Description}:
11060 Store the elements of @var{VECTOR} in an array of higher rank.
11062 @item @emph{Standard}:
11063 Fortran 95 and later
11065 @item @emph{Class}:
11066 Transformational function
11068 @item @emph{Syntax}:
11069 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
11071 @item @emph{Arguments}:
11072 @multitable @columnfractions .15 .70
11073 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
11074 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
11075 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
11076 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
11077 the same shape as @var{MASK}.
11080 @item @emph{Return value}:
11081 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
11082 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
11084 @item @emph{Example}:
11086 PROGRAM test_unpack
11087 integer :: vector(2) = (/1,1/)
11088 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
11089 integer :: field(2,2) = 0, unity(2,2)
11091 ! result: unity matrix
11092 unity = unpack(vector, reshape(mask, (/2,2/)), field)
11096 @item @emph{See also}:
11097 @ref{PACK}, @ref{SPREAD}
11103 @section @code{VERIFY} --- Scan a string for the absence of a set of characters
11105 @cindex string, find missing set
11108 @item @emph{Description}:
11109 Verifies that all the characters in a @var{SET} are present in a @var{STRING}.
11111 If @var{BACK} is either absent or equals @code{FALSE}, this function
11112 returns the position of the leftmost character of @var{STRING} that is
11113 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
11114 is returned. If all characters of @var{SET} are found in @var{STRING}, the
11117 @item @emph{Standard}:
11118 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11120 @item @emph{Class}:
11123 @item @emph{Syntax}:
11124 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
11126 @item @emph{Arguments}:
11127 @multitable @columnfractions .15 .70
11128 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
11129 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
11130 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
11131 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11132 expression indicating the kind parameter of the result.
11135 @item @emph{Return value}:
11136 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11137 @var{KIND} is absent, the return value is of default integer kind.
11139 @item @emph{Example}:
11141 PROGRAM test_verify
11142 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
11143 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
11144 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
11145 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
11146 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
11150 @item @emph{See also}:
11151 @ref{SCAN}, @ref{INDEX intrinsic}
11157 @section @code{XOR} --- Bitwise logical exclusive OR
11159 @cindex bitwise logical exclusive or
11160 @cindex logical exclusive or, bitwise
11163 @item @emph{Description}:
11164 Bitwise logical exclusive or.
11166 This intrinsic routine is provided for backwards compatibility with
11167 GNU Fortran 77. For integer arguments, programmers should consider
11168 the use of the @ref{IEOR} intrinsic defined by the Fortran standard.
11170 @item @emph{Standard}:
11173 @item @emph{Class}:
11176 @item @emph{Syntax}:
11177 @code{RESULT = XOR(I, J)}
11179 @item @emph{Arguments}:
11180 @multitable @columnfractions .15 .70
11181 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
11182 type or a scalar @code{LOGICAL} type.
11183 @item @var{J} @tab The type shall be the same as the type of @var{I}.
11186 @item @emph{Return value}:
11187 The return type is either a scalar @code{INTEGER} or a scalar
11188 @code{LOGICAL}. If the kind type parameters differ, then the
11189 smaller kind type is implicitly converted to larger kind, and the
11190 return has the larger kind.
11192 @item @emph{Example}:
11195 LOGICAL :: T = .TRUE., F = .FALSE.
11197 DATA a / Z'F' /, b / Z'3' /
11199 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
11200 WRITE (*,*) XOR(a, b)
11204 @item @emph{See also}:
11205 Fortran 95 elemental function: @ref{IEOR}
11210 @node Intrinsic Modules
11211 @chapter Intrinsic Modules
11212 @cindex intrinsic Modules
11215 * ISO_FORTRAN_ENV::
11217 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
11220 @node ISO_FORTRAN_ENV
11221 @section @code{ISO_FORTRAN_ENV}
11223 @item @emph{Standard}:
11224 Fortran 2003 and later
11227 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
11231 @item @code{CHARACTER_STORAGE_SIZE}:
11232 Size in bits of the character storage unit.
11234 @item @code{ERROR_UNIT}:
11235 Identifies the preconnected unit used for error reporting.
11237 @item @code{FILE_STORAGE_SIZE}:
11238 Size in bits of the file-storage unit.
11240 @item @code{INPUT_UNIT}:
11241 Identifies the preconnected unit identified by the asterisk
11242 (@code{*}) in @code{READ} statement.
11244 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}
11245 Kind type parameters to specify an INTEGER type with a storage
11246 size of 16, 32, and 64 bits. It is negative if a target platform
11247 does not support the particular kind.
11249 @item @code{IOSTAT_END}:
11250 The value assigned to the variable passed to the IOSTAT= specifier of
11251 an input/output statement if an end-of-file condition occurred.
11253 @item @code{IOSTAT_EOR}:
11254 The value assigned to the variable passed to the IOSTAT= specifier of
11255 an input/output statement if an end-of-record condition occurred.
11257 @item @code{NUMERIC_STORAGE_SIZE}:
11258 The size in bits of the numeric storage unit.
11260 @item @code{OUTPUT_UNIT}:
11261 Identifies the preconnected unit identified by the asterisk
11262 (@code{*}) in @code{WRITE} statement.
11264 @item @code{REAL32}, @code{REAL64}, @code{REAL128}
11265 Kind type parameters to specify a REAL type with a storage
11266 size of 32, 64, and 128 bits. It is negative if a target platform
11267 does not support the particular kind.
11272 @node ISO_C_BINDING
11273 @section @code{ISO_C_BINDING}
11275 @item @emph{Standard}:
11276 Fortran 2003 and later, GNU extensions
11279 The following intrinsic procedures are provided by the module; their
11280 definition can be found in the section Intrinsic Procedures of this
11284 @item @code{C_ASSOCIATED}
11285 @item @code{C_F_POINTER}
11286 @item @code{C_F_PROCPOINTER}
11287 @item @code{C_FUNLOC}
11290 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
11291 @c don't really know why.
11293 The @code{ISO_C_BINDING} module provides the following named constants of
11294 type default integer, which can be used as KIND type parameters.
11296 In addition to the integer named constants required by the Fortran 2003
11297 standard, GNU Fortran provides as an extension named constants for the
11298 128-bit integer types supported by the C compiler: @code{C_INT128_T,
11299 C_INT_LEAST128_T, C_INT_FAST128_T}.
11301 @multitable @columnfractions .15 .35 .35 .35
11302 @item Fortran Type @tab Named constant @tab C type @tab Extension
11303 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
11304 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
11305 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
11306 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
11307 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
11308 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
11309 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
11310 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
11311 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
11312 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
11313 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
11314 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
11315 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
11316 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
11317 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
11318 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
11319 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
11320 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
11321 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
11322 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
11323 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
11324 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
11325 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
11326 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
11327 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
11328 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
11329 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
11330 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
11331 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
11332 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
11333 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
11336 Additionally, the following @code{(CHARACTER(KIND=C_CHAR))} are
11339 @multitable @columnfractions .20 .45 .15
11340 @item Name @tab C definition @tab Value
11341 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
11342 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
11343 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
11344 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
11345 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
11346 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
11347 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
11348 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
11351 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
11352 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
11354 @item @emph{Standard}:
11355 OpenMP Application Program Interface v3.0
11359 The OpenMP Fortran runtime library routines are provided both in
11360 a form of two Fortran 90 modules, named @code{OMP_LIB} and
11361 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
11362 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
11363 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
11364 the named constants defined in the @code{OMP_LIB_KINDS} module are listed
11367 For details refer to the actual
11368 @uref{http://www.openmp.org/mp-documents/spec30.pdf,
11369 OpenMP Application Program Interface v3.0}.
11371 @code{OMP_LIB_KINDS} provides the following scalar default-integer
11375 @item @code{omp_integer_kind}
11376 @item @code{omp_logical_kind}
11377 @item @code{omp_lock_kind}
11378 @item @code{omp_nest_lock_kind}
11379 @item @code{omp_sched_kind}