2 Copyright (C) 2005-2014 Free Software Foundation, Inc.
3 This is part of the GNU Fortran manual.
4 For copying conditions, see the file gfortran.texi.
6 Permission is granted to copy, distribute and/or modify this document
7 under the terms of the GNU Free Documentation License, Version 1.3 or
8 any later version published by the Free Software Foundation; with the
9 Invariant Sections being ``Funding Free Software'', the Front-Cover
10 Texts being (a) (see below), and with the Back-Cover Texts being (b)
11 (see below). A copy of the license is included in the gfdl(7) man page.
14 Some basic guidelines for editing this document:
16 (1) The intrinsic procedures are to be listed in alphabetical order.
17 (2) The generic name is to be used.
18 (3) The specific names are included in the function index and in a
19 table at the end of the node (See ABS entry).
20 (4) Try to maintain the same style for each entry.
26 \gdef\acos{\mathop{\rm acos}\nolimits}
27 \gdef\asin{\mathop{\rm asin}\nolimits}
28 \gdef\atan{\mathop{\rm atan}\nolimits}
29 \gdef\acosh{\mathop{\rm acosh}\nolimits}
30 \gdef\asinh{\mathop{\rm asinh}\nolimits}
31 \gdef\atanh{\mathop{\rm atanh}\nolimits}
35 @node Intrinsic Procedures
36 @chapter Intrinsic Procedures
37 @cindex intrinsic procedures
40 * Introduction: Introduction to Intrinsics
41 * @code{ABORT}: ABORT, Abort the program
42 * @code{ABS}: ABS, Absolute value
43 * @code{ACCESS}: ACCESS, Checks file access modes
44 * @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence
45 * @code{ACOS}: ACOS, Arccosine function
46 * @code{ACOSH}: ACOSH, Inverse hyperbolic cosine function
47 * @code{ADJUSTL}: ADJUSTL, Left adjust a string
48 * @code{ADJUSTR}: ADJUSTR, Right adjust a string
49 * @code{AIMAG}: AIMAG, Imaginary part of complex number
50 * @code{AINT}: AINT, Truncate to a whole number
51 * @code{ALARM}: ALARM, Set an alarm clock
52 * @code{ALL}: ALL, Determine if all values are true
53 * @code{ALLOCATED}: ALLOCATED, Status of allocatable entity
54 * @code{AND}: AND, Bitwise logical AND
55 * @code{ANINT}: ANINT, Nearest whole number
56 * @code{ANY}: ANY, Determine if any values are true
57 * @code{ASIN}: ASIN, Arcsine function
58 * @code{ASINH}: ASINH, Inverse hyperbolic sine function
59 * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair
60 * @code{ATAN}: ATAN, Arctangent function
61 * @code{ATAN2}: ATAN2, Arctangent function
62 * @code{ATANH}: ATANH, Inverse hyperbolic tangent function
63 * @code{ATOMIC_ADD}: ATOMIC_ADD, Atomic ADD operation
64 * @code{ATOMIC_AND}: ATOMIC_AND, Atomic bitwise AND operation
65 * @code{ATOMIC_CAS}: ATOMIC_CAS, Atomic compare and swap
66 * @code{ATOMIC_FETCH_ADD}: ATOMIC_FETCH_ADD, Atomic ADD operation with prior fetch
67 * @code{ATOMIC_FETCH_AND}: ATOMIC_FETCH_AND, Atomic bitwise AND operation with prior fetch
68 * @code{ATOMIC_FETCH_OR}: ATOMIC_FETCH_OR, Atomic bitwise OR operation with prior fetch
69 * @code{ATOMIC_FETCH_XOR}: ATOMIC_FETCH_XOR, Atomic bitwise XOR operation with prior fetch
70 * @code{ATOMIC_OR}: ATOMIC_OR, Atomic bitwise OR operation
71 * @code{ATOMIC_DEFINE}: ATOMIC_DEFINE, Setting a variable atomically
72 * @code{ATOMIC_REF}: ATOMIC_REF, Obtaining the value of a variable atomically
73 * @code{ATOMIC_XOR}: ATOMIC_XOR, Atomic bitwise OR operation
74 * @code{BACKTRACE}: BACKTRACE, Show a backtrace
75 * @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0
76 * @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1
77 * @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind
78 * @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0
79 * @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1
80 * @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind
81 * @code{BGE}: BGE, Bitwise greater than or equal to
82 * @code{BGT}: BGT, Bitwise greater than
83 * @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function
84 * @code{BLE}: BLE, Bitwise less than or equal to
85 * @code{BLT}: BLT, Bitwise less than
86 * @code{BTEST}: BTEST, Bit test function
87 * @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer
88 * @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer
89 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
90 * @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure
91 * @code{C_LOC}: C_LOC, Obtain the C address of an object
92 * @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression
93 * @code{CEILING}: CEILING, Integer ceiling function
94 * @code{CHAR}: CHAR, Integer-to-character conversion function
95 * @code{CHDIR}: CHDIR, Change working directory
96 * @code{CHMOD}: CHMOD, Change access permissions of files
97 * @code{CMPLX}: CMPLX, Complex conversion function
98 * @code{CO_MAX}: CO_MAX, Maximal value on the current set of images
99 * @code{CO_MIN}: CO_MIN, Minimal value on the current set of images
100 * @code{CO_SUM}: CO_SUM, Sum of values on the current set of images
101 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
102 * @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler
103 * @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string
104 * @code{COMPLEX}: COMPLEX, Complex conversion function
105 * @code{CONJG}: CONJG, Complex conjugate function
106 * @code{COS}: COS, Cosine function
107 * @code{COSH}: COSH, Hyperbolic cosine function
108 * @code{COUNT}: COUNT, Count occurrences of TRUE in an array
109 * @code{CPU_TIME}: CPU_TIME, CPU time subroutine
110 * @code{CSHIFT}: CSHIFT, Circular shift elements of an array
111 * @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string
112 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
113 * @code{DBLE}: DBLE, Double precision conversion function
114 * @code{DCMPLX}: DCMPLX, Double complex conversion function
115 * @code{DIGITS}: DIGITS, Significant digits function
116 * @code{DIM}: DIM, Positive difference
117 * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
118 * @code{DPROD}: DPROD, Double product function
119 * @code{DREAL}: DREAL, Double real part function
120 * @code{DSHIFTL}: DSHIFTL, Combined left shift
121 * @code{DSHIFTR}: DSHIFTR, Combined right shift
122 * @code{DTIME}: DTIME, Execution time subroutine (or function)
123 * @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array
124 * @code{EPSILON}: EPSILON, Epsilon function
125 * @code{ERF}: ERF, Error function
126 * @code{ERFC}: ERFC, Complementary error function
127 * @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function
128 * @code{ETIME}: ETIME, Execution time subroutine (or function)
129 * @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command
130 * @code{EXIT}: EXIT, Exit the program with status.
131 * @code{EXP}: EXP, Exponential function
132 * @code{EXPONENT}: EXPONENT, Exponent function
133 * @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF, Query dynamic type for extension
134 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
135 * @code{FGET}: FGET, Read a single character in stream mode from stdin
136 * @code{FGETC}: FGETC, Read a single character in stream mode
137 * @code{FLOOR}: FLOOR, Integer floor function
138 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
139 * @code{FNUM}: FNUM, File number function
140 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
141 * @code{FPUTC}: FPUTC, Write a single character in stream mode
142 * @code{FRACTION}: FRACTION, Fractional part of the model representation
143 * @code{FREE}: FREE, Memory de-allocation subroutine
144 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
145 * @code{FSTAT}: FSTAT, Get file status
146 * @code{FTELL}: FTELL, Current stream position
147 * @code{GAMMA}: GAMMA, Gamma function
148 * @code{GERROR}: GERROR, Get last system error message
149 * @code{GETARG}: GETARG, Get command line arguments
150 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
151 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
152 * @code{GETCWD}: GETCWD, Get current working directory
153 * @code{GETENV}: GETENV, Get an environmental variable
154 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
155 * @code{GETGID}: GETGID, Group ID function
156 * @code{GETLOG}: GETLOG, Get login name
157 * @code{GETPID}: GETPID, Process ID function
158 * @code{GETUID}: GETUID, User ID function
159 * @code{GMTIME}: GMTIME, Convert time to GMT info
160 * @code{HOSTNM}: HOSTNM, Get system host name
161 * @code{HUGE}: HUGE, Largest number of a kind
162 * @code{HYPOT}: HYPOT, Euclidean distance function
163 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
164 * @code{IALL}: IALL, Bitwise AND of array elements
165 * @code{IAND}: IAND, Bitwise logical and
166 * @code{IANY}: IANY, Bitwise OR of array elements
167 * @code{IARGC}: IARGC, Get the number of command line arguments
168 * @code{IBCLR}: IBCLR, Clear bit
169 * @code{IBITS}: IBITS, Bit extraction
170 * @code{IBSET}: IBSET, Set bit
171 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
172 * @code{IDATE}: IDATE, Current local time (day/month/year)
173 * @code{IEOR}: IEOR, Bitwise logical exclusive or
174 * @code{IERRNO}: IERRNO, Function to get the last system error number
175 * @code{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index conversion
176 * @code{INDEX}: INDEX intrinsic, Position of a substring within a string
177 * @code{INT}: INT, Convert to integer type
178 * @code{INT2}: INT2, Convert to 16-bit integer type
179 * @code{INT8}: INT8, Convert to 64-bit integer type
180 * @code{IOR}: IOR, Bitwise logical or
181 * @code{IPARITY}: IPARITY, Bitwise XOR of array elements
182 * @code{IRAND}: IRAND, Integer pseudo-random number
183 * @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value
184 * @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value
185 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
186 * @code{ISHFT}: ISHFT, Shift bits
187 * @code{ISHFTC}: ISHFTC, Shift bits circularly
188 * @code{ISNAN}: ISNAN, Tests for a NaN
189 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
190 * @code{KILL}: KILL, Send a signal to a process
191 * @code{KIND}: KIND, Kind of an entity
192 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
193 * @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array
194 * @code{LEADZ}: LEADZ, Number of leading zero bits of an integer
195 * @code{LEN}: LEN, Length of a character entity
196 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
197 * @code{LGE}: LGE, Lexical greater than or equal
198 * @code{LGT}: LGT, Lexical greater than
199 * @code{LINK}: LINK, Create a hard link
200 * @code{LLE}: LLE, Lexical less than or equal
201 * @code{LLT}: LLT, Lexical less than
202 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
203 * @code{LOC}: LOC, Returns the address of a variable
204 * @code{LOG}: LOG, Logarithm function
205 * @code{LOG10}: LOG10, Base 10 logarithm function
206 * @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
207 * @code{LOGICAL}: LOGICAL, Convert to logical type
208 * @code{LONG}: LONG, Convert to integer type
209 * @code{LSHIFT}: LSHIFT, Left shift bits
210 * @code{LSTAT}: LSTAT, Get file status
211 * @code{LTIME}: LTIME, Convert time to local time info
212 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
213 * @code{MASKL}: MASKL, Left justified mask
214 * @code{MASKR}: MASKR, Right justified mask
215 * @code{MATMUL}: MATMUL, matrix multiplication
216 * @code{MAX}: MAX, Maximum value of an argument list
217 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
218 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
219 * @code{MAXVAL}: MAXVAL, Maximum value of an array
220 * @code{MCLOCK}: MCLOCK, Time function
221 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
222 * @code{MERGE}: MERGE, Merge arrays
223 * @code{MERGE_BITS}: MERGE_BITS, Merge of bits under mask
224 * @code{MIN}: MIN, Minimum value of an argument list
225 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
226 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
227 * @code{MINVAL}: MINVAL, Minimum value of an array
228 * @code{MOD}: MOD, Remainder function
229 * @code{MODULO}: MODULO, Modulo function
230 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
231 * @code{MVBITS}: MVBITS, Move bits from one integer to another
232 * @code{NEAREST}: NEAREST, Nearest representable number
233 * @code{NEW_LINE}: NEW_LINE, New line character
234 * @code{NINT}: NINT, Nearest whole number
235 * @code{NORM2}: NORM2, Euclidean vector norm
236 * @code{NOT}: NOT, Logical negation
237 * @code{NULL}: NULL, Function that returns an disassociated pointer
238 * @code{NUM_IMAGES}: NUM_IMAGES, Number of images
239 * @code{OR}: OR, Bitwise logical OR
240 * @code{PACK}: PACK, Pack an array into an array of rank one
241 * @code{PARITY}: PARITY, Reduction with exclusive OR
242 * @code{PERROR}: PERROR, Print system error message
243 * @code{POPCNT}: POPCNT, Number of bits set
244 * @code{POPPAR}: POPPAR, Parity of the number of bits set
245 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
246 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
247 * @code{PRODUCT}: PRODUCT, Product of array elements
248 * @code{RADIX}: RADIX, Base of a data model
249 * @code{RAN}: RAN, Real pseudo-random number
250 * @code{RAND}: RAND, Real pseudo-random number
251 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
252 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
253 * @code{RANGE}: RANGE, Decimal exponent range
254 * @code{RANK} : RANK, Rank of a data object
255 * @code{REAL}: REAL, Convert to real type
256 * @code{RENAME}: RENAME, Rename a file
257 * @code{REPEAT}: REPEAT, Repeated string concatenation
258 * @code{RESHAPE}: RESHAPE, Function to reshape an array
259 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
260 * @code{RSHIFT}: RSHIFT, Right shift bits
261 * @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality
262 * @code{SCALE}: SCALE, Scale a real value
263 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
264 * @code{SECNDS}: SECNDS, Time function
265 * @code{SECOND}: SECOND, CPU time function
266 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind
267 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
268 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
269 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
270 * @code{SHAPE}: SHAPE, Determine the shape of an array
271 * @code{SHIFTA}: SHIFTA, Right shift with fill
272 * @code{SHIFTL}: SHIFTL, Left shift
273 * @code{SHIFTR}: SHIFTR, Right shift
274 * @code{SIGN}: SIGN, Sign copying function
275 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
276 * @code{SIN}: SIN, Sine function
277 * @code{SINH}: SINH, Hyperbolic sine function
278 * @code{SIZE}: SIZE, Function to determine the size of an array
279 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
280 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
281 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
282 * @code{SPREAD}: SPREAD, Add a dimension to an array
283 * @code{SQRT}: SQRT, Square-root function
284 * @code{SRAND}: SRAND, Reinitialize the random number generator
285 * @code{STAT}: STAT, Get file status
286 * @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits
287 * @code{SUM}: SUM, Sum of array elements
288 * @code{SYMLNK}: SYMLNK, Create a symbolic link
289 * @code{SYSTEM}: SYSTEM, Execute a shell command
290 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
291 * @code{TAN}: TAN, Tangent function
292 * @code{TANH}: TANH, Hyperbolic tangent function
293 * @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image
294 * @code{TIME}: TIME, Time function
295 * @code{TIME8}: TIME8, Time function (64-bit)
296 * @code{TINY}: TINY, Smallest positive number of a real kind
297 * @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer
298 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
299 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
300 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
301 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
302 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
303 * @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array
304 * @code{UMASK}: UMASK, Set the file creation mask
305 * @code{UNLINK}: UNLINK, Remove a file from the file system
306 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
307 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
308 * @code{XOR}: XOR, Bitwise logical exclusive or
311 @node Introduction to Intrinsics
312 @section Introduction to intrinsic procedures
314 The intrinsic procedures provided by GNU Fortran include all of the
315 intrinsic procedures required by the Fortran 95 standard, a set of
316 intrinsic procedures for backwards compatibility with G77, and a
317 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
318 standards. Any conflict between a description here and a description in
319 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
320 2008 standard is unintentional, and the standard(s) should be considered
323 The enumeration of the @code{KIND} type parameter is processor defined in
324 the Fortran 95 standard. GNU Fortran defines the default integer type and
325 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
326 respectively. The standard mandates that both data types shall have
327 another kind, which have more precision. On typical target architectures
328 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
329 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
330 In the description of generic intrinsic procedures, the kind type parameter
331 will be specified by @code{KIND=*}, and in the description of specific
332 names for an intrinsic procedure the kind type parameter will be explicitly
333 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
334 brevity the optional @code{KIND=} syntax will be omitted.
336 Many of the intrinsic procedures take one or more optional arguments.
337 This document follows the convention used in the Fortran 95 standard,
338 and denotes such arguments by square brackets.
340 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
341 which can be used to restrict the set of intrinsic procedures to a
342 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
343 option, and so all intrinsic procedures described here are accepted. There
344 is one caveat. For a select group of intrinsic procedures, @command{g77}
345 implemented both a function and a subroutine. Both classes
346 have been implemented in @command{gfortran} for backwards compatibility
347 with @command{g77}. It is noted here that these functions and subroutines
348 cannot be intermixed in a given subprogram. In the descriptions that follow,
349 the applicable standard for each intrinsic procedure is noted.
354 @section @code{ABORT} --- Abort the program
356 @cindex program termination, with core dump
357 @cindex terminate program, with core dump
361 @item @emph{Description}:
362 @code{ABORT} causes immediate termination of the program. On operating
363 systems that support a core dump, @code{ABORT} will produce a core dump.
364 It will also print a backtrace, unless @code{-fno-backtrace} is given.
366 @item @emph{Standard}:
375 @item @emph{Return value}:
378 @item @emph{Example}:
381 integer :: i = 1, j = 2
382 if (i /= j) call abort
383 end program test_abort
386 @item @emph{See also}:
387 @ref{EXIT}, @ref{KILL}, @ref{BACKTRACE}
394 @section @code{ABS} --- Absolute value
401 @cindex absolute value
404 @item @emph{Description}:
405 @code{ABS(A)} computes the absolute value of @code{A}.
407 @item @emph{Standard}:
408 Fortran 77 and later, has overloads that are GNU extensions
414 @code{RESULT = ABS(A)}
416 @item @emph{Arguments}:
417 @multitable @columnfractions .15 .70
418 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
419 @code{REAL}, or @code{COMPLEX}.
422 @item @emph{Return value}:
423 The return value is of the same type and
424 kind as the argument except the return value is @code{REAL} for a
425 @code{COMPLEX} argument.
427 @item @emph{Example}:
432 complex :: z = (-1.e0,0.e0)
439 @item @emph{Specific names}:
440 @multitable @columnfractions .20 .20 .20 .25
441 @item Name @tab Argument @tab Return type @tab Standard
442 @item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
443 @item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
444 @item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
445 @item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
446 @item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
447 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
454 @section @code{ACCESS} --- Checks file access modes
456 @cindex file system, access mode
459 @item @emph{Description}:
460 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
461 exists, is readable, writable or executable. Except for the
462 executable check, @code{ACCESS} can be replaced by
463 Fortran 95's @code{INQUIRE}.
465 @item @emph{Standard}:
472 @code{RESULT = ACCESS(NAME, MODE)}
474 @item @emph{Arguments}:
475 @multitable @columnfractions .15 .70
476 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
477 file name. Tailing blank are ignored unless the character @code{achar(0)}
478 is present, then all characters up to and excluding @code{achar(0)} are
480 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
481 file access mode, may be any concatenation of @code{"r"} (readable),
482 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
486 @item @emph{Return value}:
487 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
488 accessible in the given mode; otherwise or if an invalid argument
489 has been given for @code{MODE} the value @code{1} is returned.
491 @item @emph{Example}:
495 character(len=*), parameter :: file = 'test.dat'
496 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
497 if(access(file,' ') == 0) print *, trim(file),' is exists'
498 if(access(file,'r') == 0) print *, trim(file),' is readable'
499 if(access(file,'w') == 0) print *, trim(file),' is writable'
500 if(access(file,'x') == 0) print *, trim(file),' is executable'
501 if(access(file2,'rwx') == 0) &
502 print *, trim(file2),' is readable, writable and executable'
503 end program access_test
505 @item @emph{Specific names}:
506 @item @emph{See also}:
513 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
515 @cindex @acronym{ASCII} collating sequence
516 @cindex collating sequence, @acronym{ASCII}
519 @item @emph{Description}:
520 @code{ACHAR(I)} returns the character located at position @code{I}
521 in the @acronym{ASCII} collating sequence.
523 @item @emph{Standard}:
524 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
530 @code{RESULT = ACHAR(I [, KIND])}
532 @item @emph{Arguments}:
533 @multitable @columnfractions .15 .70
534 @item @var{I} @tab The type shall be @code{INTEGER}.
535 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
536 expression indicating the kind parameter of the result.
539 @item @emph{Return value}:
540 The return value is of type @code{CHARACTER} with a length of one.
541 If the @var{KIND} argument is present, the return value is of the
542 specified kind and of the default kind otherwise.
544 @item @emph{Example}:
549 end program test_achar
553 See @ref{ICHAR} for a discussion of converting between numerical values
554 and formatted string representations.
556 @item @emph{See also}:
557 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
564 @section @code{ACOS} --- Arccosine function
567 @cindex trigonometric function, cosine, inverse
568 @cindex cosine, inverse
571 @item @emph{Description}:
572 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
574 @item @emph{Standard}:
575 Fortran 77 and later, for a complex argument Fortran 2008 or later
581 @code{RESULT = ACOS(X)}
583 @item @emph{Arguments}:
584 @multitable @columnfractions .15 .70
585 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
586 less than or equal to one - or the type shall be @code{COMPLEX}.
589 @item @emph{Return value}:
590 The return value is of the same type and kind as @var{X}.
591 The real part of the result is in radians and lies in the range
592 @math{0 \leq \Re \acos(x) \leq \pi}.
594 @item @emph{Example}:
597 real(8) :: x = 0.866_8
599 end program test_acos
602 @item @emph{Specific names}:
603 @multitable @columnfractions .20 .20 .20 .25
604 @item Name @tab Argument @tab Return type @tab Standard
605 @item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
606 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
609 @item @emph{See also}:
610 Inverse function: @ref{COS}
617 @section @code{ACOSH} --- Inverse hyperbolic cosine function
620 @cindex area hyperbolic cosine
621 @cindex inverse hyperbolic cosine
622 @cindex hyperbolic function, cosine, inverse
623 @cindex cosine, hyperbolic, inverse
626 @item @emph{Description}:
627 @code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
629 @item @emph{Standard}:
630 Fortran 2008 and later
636 @code{RESULT = ACOSH(X)}
638 @item @emph{Arguments}:
639 @multitable @columnfractions .15 .70
640 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
643 @item @emph{Return value}:
644 The return value has the same type and kind as @var{X}. If @var{X} is
645 complex, the imaginary part of the result is in radians and lies between
646 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
648 @item @emph{Example}:
651 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
656 @item @emph{Specific names}:
657 @multitable @columnfractions .20 .20 .20 .25
658 @item Name @tab Argument @tab Return type @tab Standard
659 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
662 @item @emph{See also}:
663 Inverse function: @ref{COSH}
669 @section @code{ADJUSTL} --- Left adjust a string
671 @cindex string, adjust left
672 @cindex adjust string
675 @item @emph{Description}:
676 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
677 Spaces are inserted at the end of the string as needed.
679 @item @emph{Standard}:
686 @code{RESULT = ADJUSTL(STRING)}
688 @item @emph{Arguments}:
689 @multitable @columnfractions .15 .70
690 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
693 @item @emph{Return value}:
694 The return value is of type @code{CHARACTER} and of the same kind as
695 @var{STRING} where leading spaces are removed and the same number of
696 spaces are inserted on the end of @var{STRING}.
698 @item @emph{Example}:
701 character(len=20) :: str = ' gfortran'
704 end program test_adjustl
707 @item @emph{See also}:
708 @ref{ADJUSTR}, @ref{TRIM}
714 @section @code{ADJUSTR} --- Right adjust a string
716 @cindex string, adjust right
717 @cindex adjust string
720 @item @emph{Description}:
721 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
722 Spaces are inserted at the start of the string as needed.
724 @item @emph{Standard}:
731 @code{RESULT = ADJUSTR(STRING)}
733 @item @emph{Arguments}:
734 @multitable @columnfractions .15 .70
735 @item @var{STR} @tab The type shall be @code{CHARACTER}.
738 @item @emph{Return value}:
739 The return value is of type @code{CHARACTER} and of the same kind as
740 @var{STRING} where trailing spaces are removed and the same number of
741 spaces are inserted at the start of @var{STRING}.
743 @item @emph{Example}:
746 character(len=20) :: str = 'gfortran'
749 end program test_adjustr
752 @item @emph{See also}:
753 @ref{ADJUSTL}, @ref{TRIM}
759 @section @code{AIMAG} --- Imaginary part of complex number
764 @cindex complex numbers, imaginary part
767 @item @emph{Description}:
768 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
769 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
770 for compatibility with @command{g77}, and their use in new code is
771 strongly discouraged.
773 @item @emph{Standard}:
774 Fortran 77 and later, has overloads that are GNU extensions
780 @code{RESULT = AIMAG(Z)}
782 @item @emph{Arguments}:
783 @multitable @columnfractions .15 .70
784 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
787 @item @emph{Return value}:
788 The return value is of type @code{REAL} with the
789 kind type parameter of the argument.
791 @item @emph{Example}:
796 z4 = cmplx(1.e0_4, 0.e0_4)
797 z8 = cmplx(0.e0_8, 1.e0_8)
798 print *, aimag(z4), dimag(z8)
799 end program test_aimag
802 @item @emph{Specific names}:
803 @multitable @columnfractions .20 .20 .20 .25
804 @item Name @tab Argument @tab Return type @tab Standard
805 @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
806 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
807 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
808 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
815 @section @code{AINT} --- Truncate to a whole number
819 @cindex rounding, floor
822 @item @emph{Description}:
823 @code{AINT(A [, KIND])} truncates its argument to a whole number.
825 @item @emph{Standard}:
832 @code{RESULT = AINT(A [, KIND])}
834 @item @emph{Arguments}:
835 @multitable @columnfractions .15 .70
836 @item @var{A} @tab The type of the argument shall be @code{REAL}.
837 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
838 expression indicating the kind parameter of the result.
841 @item @emph{Return value}:
842 The return value is of type @code{REAL} with the kind type parameter of the
843 argument if the optional @var{KIND} is absent; otherwise, the kind
844 type parameter will be given by @var{KIND}. If the magnitude of
845 @var{X} is less than one, @code{AINT(X)} returns zero. If the
846 magnitude is equal to or greater than one then it returns the largest
847 whole number that does not exceed its magnitude. The sign is the same
848 as the sign of @var{X}.
850 @item @emph{Example}:
857 print *, aint(x4), dint(x8)
859 end program test_aint
862 @item @emph{Specific names}:
863 @multitable @columnfractions .20 .20 .20 .25
864 @item Name @tab Argument @tab Return type @tab Standard
865 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
866 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
873 @section @code{ALARM} --- Execute a routine after a given delay
875 @cindex delayed execution
878 @item @emph{Description}:
879 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
880 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
881 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
882 supplied, it will be returned with the number of seconds remaining until
883 any previously scheduled alarm was due to be delivered, or zero if there
884 was no previously scheduled alarm.
886 @item @emph{Standard}:
893 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
895 @item @emph{Arguments}:
896 @multitable @columnfractions .15 .70
897 @item @var{SECONDS} @tab The type of the argument shall be a scalar
898 @code{INTEGER}. It is @code{INTENT(IN)}.
899 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
900 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
901 values may be either @code{SIG_IGN=1} to ignore the alarm generated
902 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
903 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
904 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
907 @item @emph{Example}:
910 external handler_print
912 call alarm (3, handler_print, i)
915 end program test_alarm
917 This will cause the external routine @var{handler_print} to be called
924 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
926 @cindex array, apply condition
927 @cindex array, condition testing
930 @item @emph{Description}:
931 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
932 in the array along dimension @var{DIM}.
934 @item @emph{Standard}:
938 Transformational function
941 @code{RESULT = ALL(MASK [, DIM])}
943 @item @emph{Arguments}:
944 @multitable @columnfractions .15 .70
945 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
946 it shall not be scalar.
947 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
948 with a value that lies between one and the rank of @var{MASK}.
951 @item @emph{Return value}:
952 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
953 the kind type parameter is the same as the kind type parameter of
954 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
955 an array with the rank of @var{MASK} minus 1. The shape is determined from
956 the shape of @var{MASK} where the @var{DIM} dimension is elided.
960 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
961 It also is true if @var{MASK} has zero size; otherwise, it is false.
963 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
964 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
965 is determined by applying @code{ALL} to the array sections.
968 @item @emph{Example}:
972 l = all((/.true., .true., .true./))
977 integer a(2,3), b(2,3)
981 print *, all(a .eq. b, 1)
982 print *, all(a .eq. b, 2)
983 end subroutine section
991 @section @code{ALLOCATED} --- Status of an allocatable entity
993 @cindex allocation, status
996 @item @emph{Description}:
997 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
998 status of @var{ARRAY} and @var{SCALAR}, respectively.
1000 @item @emph{Standard}:
1001 Fortran 95 and later. Note, the @code{SCALAR=} keyword and allocatable
1002 scalar entities are available in Fortran 2003 and later.
1007 @item @emph{Syntax}:
1008 @multitable @columnfractions .80
1009 @item @code{RESULT = ALLOCATED(ARRAY)}
1010 @item @code{RESULT = ALLOCATED(SCALAR)}
1013 @item @emph{Arguments}:
1014 @multitable @columnfractions .15 .70
1015 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
1016 @item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar.
1019 @item @emph{Return value}:
1020 The return value is a scalar @code{LOGICAL} with the default logical
1021 kind type parameter. If the argument is allocated, then the result is
1022 @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
1024 @item @emph{Example}:
1026 program test_allocated
1028 real(4), allocatable :: x(:)
1029 if (.not. allocated(x)) allocate(x(i))
1030 end program test_allocated
1037 @section @code{AND} --- Bitwise logical AND
1039 @cindex bitwise logical and
1040 @cindex logical and, bitwise
1043 @item @emph{Description}:
1044 Bitwise logical @code{AND}.
1046 This intrinsic routine is provided for backwards compatibility with
1047 GNU Fortran 77. For integer arguments, programmers should consider
1048 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1050 @item @emph{Standard}:
1056 @item @emph{Syntax}:
1057 @code{RESULT = AND(I, J)}
1059 @item @emph{Arguments}:
1060 @multitable @columnfractions .15 .70
1061 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1062 type or a scalar @code{LOGICAL} type.
1063 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1066 @item @emph{Return value}:
1067 The return type is either a scalar @code{INTEGER} or a scalar
1068 @code{LOGICAL}. If the kind type parameters differ, then the
1069 smaller kind type is implicitly converted to larger kind, and the
1070 return has the larger kind.
1072 @item @emph{Example}:
1075 LOGICAL :: T = .TRUE., F = .FALSE.
1077 DATA a / Z'F' /, b / Z'3' /
1079 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1080 WRITE (*,*) AND(a, b)
1084 @item @emph{See also}:
1085 Fortran 95 elemental function: @ref{IAND}
1091 @section @code{ANINT} --- Nearest whole number
1095 @cindex rounding, ceiling
1098 @item @emph{Description}:
1099 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1101 @item @emph{Standard}:
1102 Fortran 77 and later
1107 @item @emph{Syntax}:
1108 @code{RESULT = ANINT(A [, KIND])}
1110 @item @emph{Arguments}:
1111 @multitable @columnfractions .15 .70
1112 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1113 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1114 expression indicating the kind parameter of the result.
1117 @item @emph{Return value}:
1118 The return value is of type real with the kind type parameter of the
1119 argument if the optional @var{KIND} is absent; otherwise, the kind
1120 type parameter will be given by @var{KIND}. If @var{A} is greater than
1121 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1122 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1124 @item @emph{Example}:
1131 print *, anint(x4), dnint(x8)
1133 end program test_anint
1136 @item @emph{Specific names}:
1137 @multitable @columnfractions .20 .20 .20 .25
1138 @item Name @tab Argument @tab Return type @tab Standard
1139 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
1140 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1147 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1149 @cindex array, apply condition
1150 @cindex array, condition testing
1153 @item @emph{Description}:
1154 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1155 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1157 @item @emph{Standard}:
1158 Fortran 95 and later
1161 Transformational function
1163 @item @emph{Syntax}:
1164 @code{RESULT = ANY(MASK [, DIM])}
1166 @item @emph{Arguments}:
1167 @multitable @columnfractions .15 .70
1168 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1169 it shall not be scalar.
1170 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1171 with a value that lies between one and the rank of @var{MASK}.
1174 @item @emph{Return value}:
1175 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1176 the kind type parameter is the same as the kind type parameter of
1177 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1178 an array with the rank of @var{MASK} minus 1. The shape is determined from
1179 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1183 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1184 otherwise, it is false. It also is false if @var{MASK} has zero size.
1186 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1187 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1188 is determined by applying @code{ANY} to the array sections.
1191 @item @emph{Example}:
1195 l = any((/.true., .true., .true./))
1200 integer a(2,3), b(2,3)
1204 print *, any(a .eq. b, 1)
1205 print *, any(a .eq. b, 2)
1206 end subroutine section
1207 end program test_any
1214 @section @code{ASIN} --- Arcsine function
1217 @cindex trigonometric function, sine, inverse
1218 @cindex sine, inverse
1221 @item @emph{Description}:
1222 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1224 @item @emph{Standard}:
1225 Fortran 77 and later, for a complex argument Fortran 2008 or later
1230 @item @emph{Syntax}:
1231 @code{RESULT = ASIN(X)}
1233 @item @emph{Arguments}:
1234 @multitable @columnfractions .15 .70
1235 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1236 less than or equal to one - or be @code{COMPLEX}.
1239 @item @emph{Return value}:
1240 The return value is of the same type and kind as @var{X}.
1241 The real part of the result is in radians and lies in the range
1242 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1244 @item @emph{Example}:
1247 real(8) :: x = 0.866_8
1249 end program test_asin
1252 @item @emph{Specific names}:
1253 @multitable @columnfractions .20 .20 .20 .25
1254 @item Name @tab Argument @tab Return type @tab Standard
1255 @item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1256 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1259 @item @emph{See also}:
1260 Inverse function: @ref{SIN}
1267 @section @code{ASINH} --- Inverse hyperbolic sine function
1270 @cindex area hyperbolic sine
1271 @cindex inverse hyperbolic sine
1272 @cindex hyperbolic function, sine, inverse
1273 @cindex sine, hyperbolic, inverse
1276 @item @emph{Description}:
1277 @code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
1279 @item @emph{Standard}:
1280 Fortran 2008 and later
1285 @item @emph{Syntax}:
1286 @code{RESULT = ASINH(X)}
1288 @item @emph{Arguments}:
1289 @multitable @columnfractions .15 .70
1290 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1293 @item @emph{Return value}:
1294 The return value is of the same type and kind as @var{X}. If @var{X} is
1295 complex, the imaginary part of the result is in radians and lies between
1296 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1298 @item @emph{Example}:
1301 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1302 WRITE (*,*) ASINH(x)
1306 @item @emph{Specific names}:
1307 @multitable @columnfractions .20 .20 .20 .25
1308 @item Name @tab Argument @tab Return type @tab Standard
1309 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1312 @item @emph{See also}:
1313 Inverse function: @ref{SINH}
1319 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1321 @cindex pointer, status
1322 @cindex association status
1325 @item @emph{Description}:
1326 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1327 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1329 @item @emph{Standard}:
1330 Fortran 95 and later
1335 @item @emph{Syntax}:
1336 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1338 @item @emph{Arguments}:
1339 @multitable @columnfractions .15 .70
1340 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1341 and it can be of any type.
1342 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1343 a target. It must have the same type, kind type parameter, and
1344 array rank as @var{POINTER}.
1346 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1349 @item @emph{Return value}:
1350 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1351 There are several cases:
1353 @item (A) When the optional @var{TARGET} is not present then
1354 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1355 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1356 @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
1357 disassociated, the result is false.
1358 @item (C) If @var{TARGET} is present and an array target, the result is true if
1359 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1360 are arrays whose elements are not zero-sized storage sequences, and
1361 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1363 As in case(B), the result is false, if @var{POINTER} is disassociated.
1364 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1365 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1366 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1368 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1369 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1370 target associated with @var{POINTER} and the target associated with @var{TARGET}
1371 have the same shape, are not zero-sized arrays, are arrays whose elements are
1372 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1373 the same storage units in array element order.
1374 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1377 @item @emph{Example}:
1379 program test_associated
1381 real, target :: tgt(2) = (/1., 2./)
1382 real, pointer :: ptr(:)
1384 if (associated(ptr) .eqv. .false.) call abort
1385 if (associated(ptr,tgt) .eqv. .false.) call abort
1386 end program test_associated
1389 @item @emph{See also}:
1396 @section @code{ATAN} --- Arctangent function
1399 @cindex trigonometric function, tangent, inverse
1400 @cindex tangent, inverse
1403 @item @emph{Description}:
1404 @code{ATAN(X)} computes the arctangent of @var{X}.
1406 @item @emph{Standard}:
1407 Fortran 77 and later, for a complex argument and for two arguments
1408 Fortran 2008 or later
1413 @item @emph{Syntax}:
1414 @multitable @columnfractions .80
1415 @item @code{RESULT = ATAN(X)}
1416 @item @code{RESULT = ATAN(Y, X)}
1419 @item @emph{Arguments}:
1420 @multitable @columnfractions .15 .70
1421 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1422 if @var{Y} is present, @var{X} shall be REAL.
1423 @item @var{Y} shall be of the same type and kind as @var{X}.
1426 @item @emph{Return value}:
1427 The return value is of the same type and kind as @var{X}.
1428 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1429 Otherwise, it the arcus tangent of @var{X}, where the real part of
1430 the result is in radians and lies in the range
1431 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1433 @item @emph{Example}:
1436 real(8) :: x = 2.866_8
1438 end program test_atan
1441 @item @emph{Specific names}:
1442 @multitable @columnfractions .20 .20 .20 .25
1443 @item Name @tab Argument @tab Return type @tab Standard
1444 @item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1445 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1448 @item @emph{See also}:
1449 Inverse function: @ref{TAN}
1456 @section @code{ATAN2} --- Arctangent function
1459 @cindex trigonometric function, tangent, inverse
1460 @cindex tangent, inverse
1463 @item @emph{Description}:
1464 @code{ATAN2(Y, X)} computes the principal value of the argument
1465 function of the complex number @math{X + i Y}. This function can
1466 be used to transform from Cartesian into polar coordinates and
1467 allows to determine the angle in the correct quadrant.
1469 @item @emph{Standard}:
1470 Fortran 77 and later
1475 @item @emph{Syntax}:
1476 @code{RESULT = ATAN2(Y, X)}
1478 @item @emph{Arguments}:
1479 @multitable @columnfractions .15 .70
1480 @item @var{Y} @tab The type shall be @code{REAL}.
1481 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1482 If @var{Y} is zero, then @var{X} must be nonzero.
1485 @item @emph{Return value}:
1486 The return value has the same type and kind type parameter as @var{Y}. It
1487 is the principal value of the complex number @math{X + i Y}. If @var{X}
1488 is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1489 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1490 the return value is zero if @var{X} is strictly positive, @math{\pi} if
1491 @var{X} is negative and @var{Y} is positive zero (or the processor does
1492 not handle signed zeros), and @math{-\pi} if @var{X} is negative and
1493 @var{Y} is negative zero. Finally, if @var{X} is zero, then the
1494 magnitude of the result is @math{\pi/2}.
1496 @item @emph{Example}:
1499 real(4) :: x = 1.e0_4, y = 0.5e0_4
1501 end program test_atan2
1504 @item @emph{Specific names}:
1505 @multitable @columnfractions .20 .20 .20 .25
1506 @item Name @tab Argument @tab Return type @tab Standard
1507 @item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1508 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1515 @section @code{ATANH} --- Inverse hyperbolic tangent function
1518 @cindex area hyperbolic tangent
1519 @cindex inverse hyperbolic tangent
1520 @cindex hyperbolic function, tangent, inverse
1521 @cindex tangent, hyperbolic, inverse
1524 @item @emph{Description}:
1525 @code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
1527 @item @emph{Standard}:
1528 Fortran 2008 and later
1533 @item @emph{Syntax}:
1534 @code{RESULT = ATANH(X)}
1536 @item @emph{Arguments}:
1537 @multitable @columnfractions .15 .70
1538 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1541 @item @emph{Return value}:
1542 The return value has same type and kind as @var{X}. If @var{X} is
1543 complex, the imaginary part of the result is in radians and lies between
1544 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1546 @item @emph{Example}:
1549 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1550 WRITE (*,*) ATANH(x)
1554 @item @emph{Specific names}:
1555 @multitable @columnfractions .20 .20 .20 .25
1556 @item Name @tab Argument @tab Return type @tab Standard
1557 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1560 @item @emph{See also}:
1561 Inverse function: @ref{TANH}
1567 @section @code{ATOMIC_ADD} --- Atomic ADD operation
1569 @cindex Atomic subroutine, add
1572 @item @emph{Description}:
1573 @code{ATOMIC_ADD(ATOM, VALUE)} atomically adds the value of @var{VAR} to the
1574 variable @var{ATOM}. When @var{STAT} is present and the invokation was
1575 successful, it is assigned the value 0. If it is present and the invokation
1576 has failed, it is assigned a positive value; in particular, for a coindexed
1577 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1578 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1579 failed, the value @code{STAT_FAILED_IMAGE}.
1581 @item @emph{Standard}:
1587 @item @emph{Syntax}:
1588 @code{CALL ATOMIC_ADD (ATOM, VALUE [, STAT])}
1590 @item @emph{Arguments}:
1591 @multitable @columnfractions .15 .70
1592 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1593 type with @code{ATOMIC_INT_KIND} kind.
1594 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1595 is different, the value is converted to the kind of @var{ATOM}.
1596 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1599 @item @emph{Example}:
1603 integer(atomic_int_kind) :: atom[*]
1604 call atomic_add (atom[1], this_image())
1608 @item @emph{See also}:
1609 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_ADD}, @ref{ISO_FORTRAN_ENV},
1610 @ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
1617 @section @code{ATOMIC_AND} --- Atomic bitwise AND operation
1619 @cindex Atomic subroutine, AND
1622 @item @emph{Description}:
1623 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
1624 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
1625 and the invokation was successful, it is assigned the value 0. If it is present
1626 and the invokation has failed, it is assigned a positive value; in particular,
1627 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
1628 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
1629 image has failed, the value @code{STAT_FAILED_IMAGE}.
1631 @item @emph{Standard}:
1637 @item @emph{Syntax}:
1638 @code{CALL ATOMIC_AND (ATOM, VALUE [, STAT])}
1640 @item @emph{Arguments}:
1641 @multitable @columnfractions .15 .70
1642 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1643 type with @code{ATOMIC_INT_KIND} kind.
1644 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1645 is different, the value is converted to the kind of @var{ATOM}.
1646 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1649 @item @emph{Example}:
1653 integer(atomic_int_kind) :: atom[*]
1654 call atomic_and (atom[1], int(b'10100011101'))
1658 @item @emph{See also}:
1659 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_AND}, @ref{ISO_FORTRAN_ENV},
1660 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
1666 @section @code{ATOMIC_CAS} --- Atomic compare and swap
1667 @fnindex ATOMIC_DEFINE
1668 @cindex Atomic subroutine, compare and swap
1671 @item @emph{Description}:
1672 @code{ATOMIC_CAS} compares the variable @var{ATOM} with the value of
1673 @var{COMPARE}; if the value is the same, @var{ATOM} is set to the value
1674 of @var{NEW}. Additionally, @var{OLD} is set to the value of @var{ATOM}
1675 that was used for the comparison. When @var{STAT} is present and the invokation
1676 was successful, it is assigned the value 0. If it is present and the invokation
1677 has failed, it is assigned a positive value; in particular, for a coindexed
1678 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1679 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1680 failed, the value @code{STAT_FAILED_IMAGE}.
1682 @item @emph{Standard}:
1688 @item @emph{Syntax}:
1689 @code{CALL ATOMIC_CAS (ATOM, OLD, COMPARE, NEW [, STAT])}
1691 @item @emph{Arguments}:
1692 @multitable @columnfractions .15 .70
1693 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
1694 type with @code{ATOMIC_INT_KIND} kind or logical type with
1695 @code{ATOMIC_LOGICAL_KIND} kind.
1696 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1697 @item @var{COMPARE} @tab Scalar variable of the same type and kind as
1699 @item @var{NEW} @tab Scalar variable of the same type as @var{ATOM}. If kind
1700 is different, the value is converted to the kind of @var{ATOM}.
1701 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1704 @item @emph{Example}:
1708 logical(atomic_logical_kind) :: atom[*], prev
1709 call atomic_cas (atom[1], prev, .false., .true.))
1713 @item @emph{See also}:
1714 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_REF}, @ref{ISO_FORTRAN_ENV}
1720 @section @code{ATOMIC_DEFINE} --- Setting a variable atomically
1721 @fnindex ATOMIC_DEFINE
1722 @cindex Atomic subroutine, define
1725 @item @emph{Description}:
1726 @code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value
1727 @var{VALUE} atomically. When @var{STAT} is present and the invokation was
1728 successful, it is assigned the value 0. If it is present and the invokation
1729 has failed, it is assigned a positive value; in particular, for a coindexed
1730 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1731 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1732 failed, the value @code{STAT_FAILED_IMAGE}.
1734 @item @emph{Standard}:
1735 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
1740 @item @emph{Syntax}:
1741 @code{CALL ATOMIC_DEFINE (ATOM, VALUE [, STAT])}
1743 @item @emph{Arguments}:
1744 @multitable @columnfractions .15 .70
1745 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
1746 type with @code{ATOMIC_INT_KIND} kind or logical type with
1747 @code{ATOMIC_LOGICAL_KIND} kind.
1749 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1750 is different, the value is converted to the kind of @var{ATOM}.
1751 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1754 @item @emph{Example}:
1758 integer(atomic_int_kind) :: atom[*]
1759 call atomic_define (atom[1], this_image())
1763 @item @emph{See also}:
1764 @ref{ATOMIC_REF}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV},
1765 @ref{ATOMIC_ADD}, @ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
1770 @node ATOMIC_FETCH_ADD
1771 @section @code{ATOMIC_FETCH_ADD} --- Atomic ADD operation with prior fetch
1772 @fnindex ATOMIC_FETCH_ADD
1773 @cindex Atomic subroutine, ADD with fetch
1776 @item @emph{Description}:
1777 @code{ATOMIC_FETCH_ADD(ATOM, VALUE, OLD)} atomically stores the value of
1778 @var{ATOM} in @var{OLD} and adds the value of @var{VAR} to the
1779 variable @var{ATOM}. When @var{STAT} is present and the invokation was
1780 successful, it is assigned the value 0. If it is present and the invokation
1781 has failed, it is assigned a positive value; in particular, for a coindexed
1782 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1783 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1784 failed, the value @code{STAT_FAILED_IMAGE}.
1786 @item @emph{Standard}:
1792 @item @emph{Syntax}:
1793 @code{CALL ATOMIC_FETCH_ADD (ATOM, VALUE, old [, STAT])}
1795 @item @emph{Arguments}:
1796 @multitable @columnfractions .15 .70
1797 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1798 type with @code{ATOMIC_INT_KIND} kind.
1799 @code{ATOMIC_LOGICAL_KIND} kind.
1801 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1802 is different, the value is converted to the kind of @var{ATOM}.
1803 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1804 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1807 @item @emph{Example}:
1811 integer(atomic_int_kind) :: atom[*], old
1812 call atomic_add (atom[1], this_image(), old)
1816 @item @emph{See also}:
1817 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_ADD}, @ref{ISO_FORTRAN_ENV},
1818 @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR}
1823 @node ATOMIC_FETCH_AND
1824 @section @code{ATOMIC_FETCH_AND} --- Atomic bitwise AND operation with prior fetch
1825 @fnindex ATOMIC_FETCH_AND
1826 @cindex Atomic subroutine, AND with fetch
1829 @item @emph{Description}:
1830 @code{ATOMIC_AND(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
1831 @var{OLD} and defines @var{ATOM} with the bitwise AND between the values of
1832 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was
1833 successful, it is assigned the value 0. If it is present and the invokation has
1834 failed, it is assigned a positive value; in particular, for a coindexed
1835 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1836 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1837 failed, the value @code{STAT_FAILED_IMAGE}.
1839 @item @emph{Standard}:
1845 @item @emph{Syntax}:
1846 @code{CALL ATOMIC_FETCH_AND (ATOM, VALUE, OLD [, STAT])}
1848 @item @emph{Arguments}:
1849 @multitable @columnfractions .15 .70
1850 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1851 type with @code{ATOMIC_INT_KIND} kind.
1852 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1853 is different, the value is converted to the kind of @var{ATOM}.
1854 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1855 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1858 @item @emph{Example}:
1862 integer(atomic_int_kind) :: atom[*], old
1863 call atomic_fetch_and (atom[1], int(b'10100011101'), old)
1867 @item @emph{See also}:
1868 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_AND}, @ref{ISO_FORTRAN_ENV},
1869 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR}
1874 @node ATOMIC_FETCH_OR
1875 @section @code{ATOMIC_FETCH_OR} --- Atomic bitwise OR operation with prior fetch
1876 @fnindex ATOMIC_FETCH_OR
1877 @cindex Atomic subroutine, OR with fetch
1880 @item @emph{Description}:
1881 @code{ATOMIC_OR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
1882 @var{OLD} and defines @var{ATOM} with the bitwise OR between the values of
1883 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was
1884 successful, it is assigned the value 0. If it is present and the invokation has
1885 failed, it is assigned a positive value; in particular, for a coindexed
1886 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1887 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1888 failed, the value @code{STAT_FAILED_IMAGE}.
1890 @item @emph{Standard}:
1896 @item @emph{Syntax}:
1897 @code{CALL ATOMIC_FETCH_OR (ATOM, VALUE, OLD [, STAT])}
1899 @item @emph{Arguments}:
1900 @multitable @columnfractions .15 .70
1901 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1902 type with @code{ATOMIC_INT_KIND} kind.
1903 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1904 is different, the value is converted to the kind of @var{ATOM}.
1905 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1906 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1909 @item @emph{Example}:
1913 integer(atomic_int_kind) :: atom[*], old
1914 call atomic_fetch_or (atom[1], int(b'10100011101'), old)
1918 @item @emph{See also}:
1919 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_OR}, @ref{ISO_FORTRAN_ENV},
1920 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_XOR}
1925 @node ATOMIC_FETCH_XOR
1926 @section @code{ATOMIC_FETCH_XOR} --- Atomic bitwise XOR operation with prior fetch
1927 @fnindex ATOMIC_FETCH_XOR
1928 @cindex Atomic subroutine, XOR with fetch
1931 @item @emph{Description}:
1932 @code{ATOMIC_XOR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
1933 @var{OLD} and defines @var{ATOM} with the bitwise XOR between the values of
1934 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was
1935 successful, it is assigned the value 0. If it is present and the invokation has
1936 failed, it is assigned a positive value; in particular, for a coindexed
1937 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1938 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1939 failed, the value @code{STAT_FAILED_IMAGE}.
1941 @item @emph{Standard}:
1947 @item @emph{Syntax}:
1948 @code{CALL ATOMIC_FETCH_XOR (ATOM, VALUE, OLD [, STAT])}
1950 @item @emph{Arguments}:
1951 @multitable @columnfractions .15 .70
1952 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1953 type with @code{ATOMIC_INT_KIND} kind.
1954 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1955 is different, the value is converted to the kind of @var{ATOM}.
1956 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1957 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1960 @item @emph{Example}:
1964 integer(atomic_int_kind) :: atom[*], old
1965 call atomic_fetch_xor (atom[1], int(b'10100011101'), old)
1969 @item @emph{See also}:
1970 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_XOR}, @ref{ISO_FORTRAN_ENV},
1971 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}
1977 @section @code{ATOMIC_OR} --- Atomic bitwise OR operation
1979 @cindex Atomic subroutine, OR
1982 @item @emph{Description}:
1983 @code{ATOMIC_OR(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
1984 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
1985 and the invokation was successful, it is assigned the value 0. If it is present
1986 and the invokation has failed, it is assigned a positive value; in particular,
1987 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
1988 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
1989 image has failed, the value @code{STAT_FAILED_IMAGE}.
1991 @item @emph{Standard}:
1997 @item @emph{Syntax}:
1998 @code{CALL ATOMIC_OR (ATOM, VALUE [, STAT])}
2000 @item @emph{Arguments}:
2001 @multitable @columnfractions .15 .70
2002 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2003 type with @code{ATOMIC_INT_KIND} kind.
2004 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2005 is different, the value is converted to the kind of @var{ATOM}.
2006 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2009 @item @emph{Example}:
2013 integer(atomic_int_kind) :: atom[*]
2014 call atomic_or (atom[1], int(b'10100011101'))
2018 @item @emph{See also}:
2019 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_OR}, @ref{ISO_FORTRAN_ENV},
2020 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
2026 @section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically
2028 @cindex Atomic subroutine, reference
2031 @item @emph{Description}:
2032 @code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the
2033 variable @var{ATOM} to @var{VALUE}. When @var{STAT} is present and the
2034 invokation was successful, it is assigned the value 0. If it is present and the
2035 invokation has failed, it is assigned a positive value; in particular, for a
2036 coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value
2037 of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image
2038 has failed, the value @code{STAT_FAILED_IMAGE}.
2041 @item @emph{Standard}:
2042 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
2047 @item @emph{Syntax}:
2048 @code{CALL ATOMIC_REF(VALUE, ATOM [, STAT])}
2050 @item @emph{Arguments}:
2051 @multitable @columnfractions .15 .70
2052 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2053 is different, the value is converted to the kind of @var{ATOM}.
2054 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
2055 type with @code{ATOMIC_INT_KIND} kind or logical type with
2056 @code{ATOMIC_LOGICAL_KIND} kind.
2057 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2060 @item @emph{Example}:
2064 logical(atomic_logical_kind) :: atom[*]
2066 call atomic_ref (atom, .false.)
2068 call atomic_ref (atom, val)
2075 @item @emph{See also}:
2076 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV},
2077 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR},
2078 @ref{ATOMIC_FETCH_XOR}
2083 @section @code{ATOMIC_XOR} --- Atomic bitwise OR operation
2085 @cindex Atomic subroutine, XOR
2088 @item @emph{Description}:
2089 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
2090 XOR between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
2091 and the invokation was successful, it is assigned the value 0. If it is present
2092 and the invokation has failed, it is assigned a positive value; in particular,
2093 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
2094 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
2095 image has failed, the value @code{STAT_FAILED_IMAGE}.
2097 @item @emph{Standard}:
2103 @item @emph{Syntax}:
2104 @code{CALL ATOMIC_XOR (ATOM, VALUE [, STAT])}
2106 @item @emph{Arguments}:
2107 @multitable @columnfractions .15 .70
2108 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2109 type with @code{ATOMIC_INT_KIND} kind.
2110 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2111 is different, the value is converted to the kind of @var{ATOM}.
2112 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2115 @item @emph{Example}:
2119 integer(atomic_int_kind) :: atom[*]
2120 call atomic_xor (atom[1], int(b'10100011101'))
2124 @item @emph{See also}:
2125 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_XOR}, @ref{ISO_FORTRAN_ENV},
2126 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
2131 @section @code{BACKTRACE} --- Show a backtrace
2136 @item @emph{Description}:
2137 @code{BACKTRACE} shows a backtrace at an arbitrary place in user code. Program
2138 execution continues normally afterwards. The backtrace information is printed
2139 to the unit corresponding to @code{ERROR_UNIT} in @code{ISO_FORTRAN_ENV}.
2141 @item @emph{Standard}:
2147 @item @emph{Syntax}:
2148 @code{CALL BACKTRACE}
2150 @item @emph{Arguments}:
2153 @item @emph{See also}:
2160 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
2164 @cindex Bessel function, first kind
2167 @item @emph{Description}:
2168 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
2169 order 0 of @var{X}. This function is available under the name
2170 @code{BESJ0} as a GNU extension.
2172 @item @emph{Standard}:
2173 Fortran 2008 and later
2178 @item @emph{Syntax}:
2179 @code{RESULT = BESSEL_J0(X)}
2181 @item @emph{Arguments}:
2182 @multitable @columnfractions .15 .70
2183 @item @var{X} @tab The type shall be @code{REAL}.
2186 @item @emph{Return value}:
2187 The return value is of type @code{REAL} and lies in the
2188 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
2191 @item @emph{Example}:
2194 real(8) :: x = 0.0_8
2196 end program test_besj0
2199 @item @emph{Specific names}:
2200 @multitable @columnfractions .20 .20 .20 .25
2201 @item Name @tab Argument @tab Return type @tab Standard
2202 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2209 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
2213 @cindex Bessel function, first kind
2216 @item @emph{Description}:
2217 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
2218 order 1 of @var{X}. This function is available under the name
2219 @code{BESJ1} as a GNU extension.
2221 @item @emph{Standard}:
2227 @item @emph{Syntax}:
2228 @code{RESULT = BESSEL_J1(X)}
2230 @item @emph{Arguments}:
2231 @multitable @columnfractions .15 .70
2232 @item @var{X} @tab The type shall be @code{REAL}.
2235 @item @emph{Return value}:
2236 The return value is of type @code{REAL} and lies in the
2237 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
2240 @item @emph{Example}:
2243 real(8) :: x = 1.0_8
2245 end program test_besj1
2248 @item @emph{Specific names}:
2249 @multitable @columnfractions .20 .20 .20 .25
2250 @item Name @tab Argument @tab Return type @tab Standard
2251 @item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2258 @section @code{BESSEL_JN} --- Bessel function of the first kind
2262 @cindex Bessel function, first kind
2265 @item @emph{Description}:
2266 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
2267 order @var{N} of @var{X}. This function is available under the name
2268 @code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays,
2269 their ranks and shapes shall conform.
2271 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
2272 of the first kind of the orders @var{N1} to @var{N2}.
2274 @item @emph{Standard}:
2275 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2278 Elemental function, except for the transformational function
2279 @code{BESSEL_JN(N1, N2, X)}
2281 @item @emph{Syntax}:
2282 @multitable @columnfractions .80
2283 @item @code{RESULT = BESSEL_JN(N, X)}
2284 @item @code{RESULT = BESSEL_JN(N1, N2, X)}
2287 @item @emph{Arguments}:
2288 @multitable @columnfractions .15 .70
2289 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
2290 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2291 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2292 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2293 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
2296 @item @emph{Return value}:
2297 The return value is a scalar of type @code{REAL}. It has the same
2301 The transformational function uses a recurrence algorithm which might,
2302 for some values of @var{X}, lead to different results than calls to
2303 the elemental function.
2305 @item @emph{Example}:
2308 real(8) :: x = 1.0_8
2310 end program test_besjn
2313 @item @emph{Specific names}:
2314 @multitable @columnfractions .20 .20 .20 .25
2315 @item Name @tab Argument @tab Return type @tab Standard
2316 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2317 @item @tab @code{REAL(8) X} @tab @tab
2324 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
2328 @cindex Bessel function, second kind
2331 @item @emph{Description}:
2332 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
2333 order 0 of @var{X}. This function is available under the name
2334 @code{BESY0} as a GNU extension.
2336 @item @emph{Standard}:
2337 Fortran 2008 and later
2342 @item @emph{Syntax}:
2343 @code{RESULT = BESSEL_Y0(X)}
2345 @item @emph{Arguments}:
2346 @multitable @columnfractions .15 .70
2347 @item @var{X} @tab The type shall be @code{REAL}.
2350 @item @emph{Return value}:
2351 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2353 @item @emph{Example}:
2356 real(8) :: x = 0.0_8
2358 end program test_besy0
2361 @item @emph{Specific names}:
2362 @multitable @columnfractions .20 .20 .20 .25
2363 @item Name @tab Argument @tab Return type @tab Standard
2364 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2371 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
2375 @cindex Bessel function, second kind
2378 @item @emph{Description}:
2379 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
2380 order 1 of @var{X}. This function is available under the name
2381 @code{BESY1} as a GNU extension.
2383 @item @emph{Standard}:
2384 Fortran 2008 and later
2389 @item @emph{Syntax}:
2390 @code{RESULT = BESSEL_Y1(X)}
2392 @item @emph{Arguments}:
2393 @multitable @columnfractions .15 .70
2394 @item @var{X} @tab The type shall be @code{REAL}.
2397 @item @emph{Return value}:
2398 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2400 @item @emph{Example}:
2403 real(8) :: x = 1.0_8
2405 end program test_besy1
2408 @item @emph{Specific names}:
2409 @multitable @columnfractions .20 .20 .20 .25
2410 @item Name @tab Argument @tab Return type @tab Standard
2411 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2418 @section @code{BESSEL_YN} --- Bessel function of the second kind
2422 @cindex Bessel function, second kind
2425 @item @emph{Description}:
2426 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
2427 order @var{N} of @var{X}. This function is available under the name
2428 @code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays,
2429 their ranks and shapes shall conform.
2431 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
2432 of the first kind of the orders @var{N1} to @var{N2}.
2434 @item @emph{Standard}:
2435 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2438 Elemental function, except for the transformational function
2439 @code{BESSEL_YN(N1, N2, X)}
2441 @item @emph{Syntax}:
2442 @multitable @columnfractions .80
2443 @item @code{RESULT = BESSEL_YN(N, X)}
2444 @item @code{RESULT = BESSEL_YN(N1, N2, X)}
2447 @item @emph{Arguments}:
2448 @multitable @columnfractions .15 .70
2449 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} .
2450 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2451 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2452 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2453 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
2456 @item @emph{Return value}:
2457 The return value is a scalar of type @code{REAL}. It has the same
2461 The transformational function uses a recurrence algorithm which might,
2462 for some values of @var{X}, lead to different results than calls to
2463 the elemental function.
2465 @item @emph{Example}:
2468 real(8) :: x = 1.0_8
2470 end program test_besyn
2473 @item @emph{Specific names}:
2474 @multitable @columnfractions .20 .20 .20 .25
2475 @item Name @tab Argument @tab Return type @tab Standard
2476 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2477 @item @tab @code{REAL(8) X} @tab @tab
2484 @section @code{BGE} --- Bitwise greater than or equal to
2486 @cindex bitwise comparison
2489 @item @emph{Description}:
2490 Determines whether an integral is a bitwise greater than or equal to
2493 @item @emph{Standard}:
2494 Fortran 2008 and later
2499 @item @emph{Syntax}:
2500 @code{RESULT = BGE(I, J)}
2502 @item @emph{Arguments}:
2503 @multitable @columnfractions .15 .70
2504 @item @var{I} @tab Shall be of @code{INTEGER} type.
2505 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2509 @item @emph{Return value}:
2510 The return value is of type @code{LOGICAL} and of the default kind.
2512 @item @emph{See also}:
2513 @ref{BGT}, @ref{BLE}, @ref{BLT}
2519 @section @code{BGT} --- Bitwise greater than
2521 @cindex bitwise comparison
2524 @item @emph{Description}:
2525 Determines whether an integral is a bitwise greater than another.
2527 @item @emph{Standard}:
2528 Fortran 2008 and later
2533 @item @emph{Syntax}:
2534 @code{RESULT = BGT(I, J)}
2536 @item @emph{Arguments}:
2537 @multitable @columnfractions .15 .70
2538 @item @var{I} @tab Shall be of @code{INTEGER} type.
2539 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2543 @item @emph{Return value}:
2544 The return value is of type @code{LOGICAL} and of the default kind.
2546 @item @emph{See also}:
2547 @ref{BGE}, @ref{BLE}, @ref{BLT}
2553 @section @code{BIT_SIZE} --- Bit size inquiry function
2555 @cindex bits, number of
2556 @cindex size of a variable, in bits
2559 @item @emph{Description}:
2560 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
2561 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
2562 independent of the actual value of @var{I}.
2564 @item @emph{Standard}:
2565 Fortran 95 and later
2570 @item @emph{Syntax}:
2571 @code{RESULT = BIT_SIZE(I)}
2573 @item @emph{Arguments}:
2574 @multitable @columnfractions .15 .70
2575 @item @var{I} @tab The type shall be @code{INTEGER}.
2578 @item @emph{Return value}:
2579 The return value is of type @code{INTEGER}
2581 @item @emph{Example}:
2583 program test_bit_size
2588 end program test_bit_size
2595 @section @code{BLE} --- Bitwise less than or equal to
2597 @cindex bitwise comparison
2600 @item @emph{Description}:
2601 Determines whether an integral is a bitwise less than or equal to
2604 @item @emph{Standard}:
2605 Fortran 2008 and later
2610 @item @emph{Syntax}:
2611 @code{RESULT = BLE(I, J)}
2613 @item @emph{Arguments}:
2614 @multitable @columnfractions .15 .70
2615 @item @var{I} @tab Shall be of @code{INTEGER} type.
2616 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2620 @item @emph{Return value}:
2621 The return value is of type @code{LOGICAL} and of the default kind.
2623 @item @emph{See also}:
2624 @ref{BGT}, @ref{BGE}, @ref{BLT}
2630 @section @code{BLT} --- Bitwise less than
2632 @cindex bitwise comparison
2635 @item @emph{Description}:
2636 Determines whether an integral is a bitwise less than another.
2638 @item @emph{Standard}:
2639 Fortran 2008 and later
2644 @item @emph{Syntax}:
2645 @code{RESULT = BLT(I, J)}
2647 @item @emph{Arguments}:
2648 @multitable @columnfractions .15 .70
2649 @item @var{I} @tab Shall be of @code{INTEGER} type.
2650 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2654 @item @emph{Return value}:
2655 The return value is of type @code{LOGICAL} and of the default kind.
2657 @item @emph{See also}:
2658 @ref{BGE}, @ref{BGT}, @ref{BLE}
2664 @section @code{BTEST} --- Bit test function
2666 @cindex bits, testing
2669 @item @emph{Description}:
2670 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
2671 in @var{I} is set. The counting of the bits starts at 0.
2673 @item @emph{Standard}:
2674 Fortran 95 and later
2679 @item @emph{Syntax}:
2680 @code{RESULT = BTEST(I, POS)}
2682 @item @emph{Arguments}:
2683 @multitable @columnfractions .15 .70
2684 @item @var{I} @tab The type shall be @code{INTEGER}.
2685 @item @var{POS} @tab The type shall be @code{INTEGER}.
2688 @item @emph{Return value}:
2689 The return value is of type @code{LOGICAL}
2691 @item @emph{Example}:
2694 integer :: i = 32768 + 1024 + 64
2698 bool = btest(i, pos)
2701 end program test_btest
2707 @section @code{C_ASSOCIATED} --- Status of a C pointer
2708 @fnindex C_ASSOCIATED
2709 @cindex association status, C pointer
2710 @cindex pointer, C association status
2713 @item @emph{Description}:
2714 @code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
2715 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
2717 @item @emph{Standard}:
2718 Fortran 2003 and later
2723 @item @emph{Syntax}:
2724 @code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
2726 @item @emph{Arguments}:
2727 @multitable @columnfractions .15 .70
2728 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
2729 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
2732 @item @emph{Return value}:
2733 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
2734 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
2735 point to different addresses.
2737 @item @emph{Example}:
2739 subroutine association_test(a,b)
2740 use iso_c_binding, only: c_associated, c_loc, c_ptr
2744 if(c_associated(b, c_loc(a))) &
2745 stop 'b and a do not point to same target'
2746 end subroutine association_test
2749 @item @emph{See also}:
2750 @ref{C_LOC}, @ref{C_FUNLOC}
2755 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2756 @fnindex C_F_POINTER
2757 @cindex pointer, convert C to Fortran
2760 @item @emph{Description}:
2761 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} assigns the target of the C pointer
2762 @var{CPTR} to the Fortran pointer @var{FPTR} and specifies its shape.
2764 @item @emph{Standard}:
2765 Fortran 2003 and later
2770 @item @emph{Syntax}:
2771 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2773 @item @emph{Arguments}:
2774 @multitable @columnfractions .15 .70
2775 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
2777 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
2779 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2780 with @code{INTENT(IN)}. It shall be present
2781 if and only if @var{fptr} is an array. The size
2782 must be equal to the rank of @var{fptr}.
2785 @item @emph{Example}:
2791 subroutine my_routine(p) bind(c,name='myC_func')
2793 type(c_ptr), intent(out) :: p
2797 real,pointer :: a(:)
2798 call my_routine(cptr)
2799 call c_f_pointer(cptr, a, [12])
2803 @item @emph{See also}:
2804 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2808 @node C_F_PROCPOINTER
2809 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
2810 @fnindex C_F_PROCPOINTER
2811 @cindex pointer, C address of pointers
2814 @item @emph{Description}:
2815 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
2816 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
2818 @item @emph{Standard}:
2819 Fortran 2003 and later
2824 @item @emph{Syntax}:
2825 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2827 @item @emph{Arguments}:
2828 @multitable @columnfractions .15 .70
2829 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
2831 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
2835 @item @emph{Example}:
2843 real(c_float), intent(in) :: a
2844 real(c_float) :: func
2848 function getIterFunc() bind(c,name="getIterFunc")
2850 type(c_funptr) :: getIterFunc
2853 type(c_funptr) :: cfunptr
2854 procedure(func), pointer :: myFunc
2855 cfunptr = getIterFunc()
2856 call c_f_procpointer(cfunptr, myFunc)
2860 @item @emph{See also}:
2861 @ref{C_LOC}, @ref{C_F_POINTER}
2866 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
2868 @cindex pointer, C address of procedures
2871 @item @emph{Description}:
2872 @code{C_FUNLOC(x)} determines the C address of the argument.
2874 @item @emph{Standard}:
2875 Fortran 2003 and later
2880 @item @emph{Syntax}:
2881 @code{RESULT = C_FUNLOC(x)}
2883 @item @emph{Arguments}:
2884 @multitable @columnfractions .15 .70
2885 @item @var{x} @tab Interoperable function or pointer to such function.
2888 @item @emph{Return value}:
2889 The return value is of type @code{C_FUNPTR} and contains the C address
2892 @item @emph{Example}:
2898 subroutine sub(a) bind(c)
2908 subroutine my_routine(p) bind(c,name='myC_func')
2910 type(c_funptr), intent(in) :: p
2913 call my_routine(c_funloc(sub))
2917 @item @emph{See also}:
2918 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2923 @section @code{C_LOC} --- Obtain the C address of an object
2925 @cindex procedure pointer, convert C to Fortran
2928 @item @emph{Description}:
2929 @code{C_LOC(X)} determines the C address of the argument.
2931 @item @emph{Standard}:
2932 Fortran 2003 and later
2937 @item @emph{Syntax}:
2938 @code{RESULT = C_LOC(X)}
2940 @item @emph{Arguments}:
2941 @multitable @columnfractions .10 .75
2942 @item @var{X} @tab Shall have either the POINTER or TARGET attribute. It shall not be a coindexed object. It shall either be a variable with interoperable type and kind type parameters, or be a scalar, nonpolymorphic variable with no length type parameters.
2946 @item @emph{Return value}:
2947 The return value is of type @code{C_PTR} and contains the C address
2950 @item @emph{Example}:
2952 subroutine association_test(a,b)
2953 use iso_c_binding, only: c_associated, c_loc, c_ptr
2957 if(c_associated(b, c_loc(a))) &
2958 stop 'b and a do not point to same target'
2959 end subroutine association_test
2962 @item @emph{See also}:
2963 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2968 @section @code{C_SIZEOF} --- Size in bytes of an expression
2970 @cindex expression size
2971 @cindex size of an expression
2974 @item @emph{Description}:
2975 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
2976 expression @code{X} occupies.
2978 @item @emph{Standard}:
2982 Inquiry function of the module @code{ISO_C_BINDING}
2984 @item @emph{Syntax}:
2985 @code{N = C_SIZEOF(X)}
2987 @item @emph{Arguments}:
2988 @multitable @columnfractions .15 .70
2989 @item @var{X} @tab The argument shall be an interoperable data entity.
2992 @item @emph{Return value}:
2993 The return value is of type integer and of the system-dependent kind
2994 @code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the
2995 number of bytes occupied by the argument. If the argument has the
2996 @code{POINTER} attribute, the number of bytes of the storage area pointed
2997 to is returned. If the argument is of a derived type with @code{POINTER}
2998 or @code{ALLOCATABLE} components, the return value does not account for
2999 the sizes of the data pointed to by these components.
3001 @item @emph{Example}:
3005 real(c_float) :: r, s(5)
3006 print *, (c_sizeof(s)/c_sizeof(r) == 5)
3009 The example will print @code{.TRUE.} unless you are using a platform
3010 where default @code{REAL} variables are unusually padded.
3012 @item @emph{See also}:
3013 @ref{SIZEOF}, @ref{STORAGE_SIZE}
3018 @section @code{CEILING} --- Integer ceiling function
3021 @cindex rounding, ceiling
3024 @item @emph{Description}:
3025 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
3027 @item @emph{Standard}:
3028 Fortran 95 and later
3033 @item @emph{Syntax}:
3034 @code{RESULT = CEILING(A [, KIND])}
3036 @item @emph{Arguments}:
3037 @multitable @columnfractions .15 .70
3038 @item @var{A} @tab The type shall be @code{REAL}.
3039 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3040 expression indicating the kind parameter of the result.
3043 @item @emph{Return value}:
3044 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
3045 and a default-kind @code{INTEGER} otherwise.
3047 @item @emph{Example}:
3049 program test_ceiling
3052 print *, ceiling(x) ! returns 64
3053 print *, ceiling(y) ! returns -63
3054 end program test_ceiling
3057 @item @emph{See also}:
3058 @ref{FLOOR}, @ref{NINT}
3065 @section @code{CHAR} --- Character conversion function
3067 @cindex conversion, to character
3070 @item @emph{Description}:
3071 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
3073 @item @emph{Standard}:
3074 Fortran 77 and later
3079 @item @emph{Syntax}:
3080 @code{RESULT = CHAR(I [, KIND])}
3082 @item @emph{Arguments}:
3083 @multitable @columnfractions .15 .70
3084 @item @var{I} @tab The type shall be @code{INTEGER}.
3085 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3086 expression indicating the kind parameter of the result.
3089 @item @emph{Return value}:
3090 The return value is of type @code{CHARACTER(1)}
3092 @item @emph{Example}:
3098 print *, i, c ! returns 'J'
3099 end program test_char
3102 @item @emph{Specific names}:
3103 @multitable @columnfractions .20 .20 .20 .25
3104 @item Name @tab Argument @tab Return type @tab Standard
3105 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
3109 See @ref{ICHAR} for a discussion of converting between numerical values
3110 and formatted string representations.
3112 @item @emph{See also}:
3113 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
3120 @section @code{CHDIR} --- Change working directory
3122 @cindex system, working directory
3125 @item @emph{Description}:
3126 Change current working directory to a specified path.
3128 This intrinsic is provided in both subroutine and function forms; however,
3129 only one form can be used in any given program unit.
3131 @item @emph{Standard}:
3135 Subroutine, function
3137 @item @emph{Syntax}:
3138 @multitable @columnfractions .80
3139 @item @code{CALL CHDIR(NAME [, STATUS])}
3140 @item @code{STATUS = CHDIR(NAME)}
3143 @item @emph{Arguments}:
3144 @multitable @columnfractions .15 .70
3145 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
3146 kind and shall specify a valid path within the file system.
3147 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
3148 kind. Returns 0 on success, and a system specific and nonzero error code
3152 @item @emph{Example}:
3155 CHARACTER(len=255) :: path
3157 WRITE(*,*) TRIM(path)
3160 WRITE(*,*) TRIM(path)
3164 @item @emph{See also}:
3171 @section @code{CHMOD} --- Change access permissions of files
3173 @cindex file system, change access mode
3176 @item @emph{Description}:
3177 @code{CHMOD} changes the permissions of a file.
3179 This intrinsic is provided in both subroutine and function forms; however,
3180 only one form can be used in any given program unit.
3182 @item @emph{Standard}:
3186 Subroutine, function
3188 @item @emph{Syntax}:
3189 @multitable @columnfractions .80
3190 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
3191 @item @code{STATUS = CHMOD(NAME, MODE)}
3194 @item @emph{Arguments}:
3195 @multitable @columnfractions .15 .70
3197 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
3198 file name. Trailing blanks are ignored unless the character
3199 @code{achar(0)} is present, then all characters up to and excluding
3200 @code{achar(0)} are used as the file name.
3202 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
3203 file permission. @var{MODE} uses the same syntax as the @code{chmod} utility
3204 as defined by the POSIX standard. The argument shall either be a string of
3205 a nonnegative octal number or a symbolic mode.
3207 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
3208 @code{0} on success and nonzero otherwise.
3211 @item @emph{Return value}:
3212 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
3215 @item @emph{Example}:
3216 @code{CHMOD} as subroutine
3221 call chmod('test.dat','u+x',status)
3222 print *, 'Status: ', status
3223 end program chmod_test
3225 @code{CHMOD} as function:
3230 status = chmod('test.dat','u+x')
3231 print *, 'Status: ', status
3232 end program chmod_test
3240 @section @code{CMPLX} --- Complex conversion function
3242 @cindex complex numbers, conversion to
3243 @cindex conversion, to complex
3246 @item @emph{Description}:
3247 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
3248 the real component. If @var{Y} is present it is converted to the imaginary
3249 component. If @var{Y} is not present then the imaginary component is set to
3250 0.0. If @var{X} is complex then @var{Y} must not be present.
3252 @item @emph{Standard}:
3253 Fortran 77 and later
3258 @item @emph{Syntax}:
3259 @code{RESULT = CMPLX(X [, Y [, KIND]])}
3261 @item @emph{Arguments}:
3262 @multitable @columnfractions .15 .70
3263 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3265 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
3266 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
3267 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3268 expression indicating the kind parameter of the result.
3271 @item @emph{Return value}:
3272 The return value is of @code{COMPLEX} type, with a kind equal to
3273 @var{KIND} if it is specified. If @var{KIND} is not specified, the
3274 result is of the default @code{COMPLEX} kind, regardless of the kinds of
3275 @var{X} and @var{Y}.
3277 @item @emph{Example}:
3284 print *, z, cmplx(x)
3285 end program test_cmplx
3288 @item @emph{See also}:
3295 @section @code{CO_MAX} --- Maximal value on the current set of images
3297 @cindex Collectives, maximal value
3300 @item @emph{Description}:
3301 @code{CO_MAX} determines element-wise the maximal value of @var{A} on all
3302 images of the current team. If @var{RESULT_IMAGE} is present, the maximum
3303 values are returned on in @var{A} on the specified image only and the value
3304 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3305 not present, the value is returned on all images. If the execution was
3306 successful and @var{STAT} is present, it is assigned the value zero. If the
3307 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3308 @var{ERRMSG} gets assigned a value describing the occurred error.
3310 @item @emph{Standard}:
3311 Technical Specification (TS) 18508 or later
3314 Collective subroutine
3316 @item @emph{Syntax}:
3317 @code{CALL CO_MAX(A [, RESULT_IMAGE, STAT, ERRMSG])}
3319 @item @emph{Arguments}:
3320 @multitable @columnfractions .15 .70
3321 @item @var{A} @tab shall be an integer, real or character variable,
3322 which has the same type and type parameters on all images of the team.
3323 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3324 present, it shall have the same the same value on all images and refer to an
3325 image of the current team.
3326 @item @var{STAT} @tab (optional) a scalar integer variable
3327 @item @var{ERRMSG} @tab (optional) a scalar character variable
3330 @item @emph{Example}:
3335 call co_max (val, result_image=1)
3336 if (this_image() == 1) then
3337 write(*,*) "Maximal value", val ! prints num_images()
3342 @item @emph{See also}:
3343 @ref{CO_MIN}, @ref{CO_SUM}
3349 @section @code{CO_MIN} --- Minimal value on the current set of images
3351 @cindex Collectives, minimal value
3354 @item @emph{Description}:
3355 @code{CO_MIN} determines element-wise the minimal value of @var{A} on all
3356 images of the current team. If @var{RESULT_IMAGE} is present, the minimal
3357 values are returned on in @var{A} on the specified image only and the value
3358 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3359 not present, the value is returned on all images. If the execution was
3360 successful and @var{STAT} is present, it is assigned the value zero. If the
3361 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3362 @var{ERRMSG} gets assigned a value describing the occurred error.
3364 @item @emph{Standard}:
3365 Technical Specification (TS) 18508 or later
3368 Collective subroutine
3370 @item @emph{Syntax}:
3371 @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3373 @item @emph{Arguments}:
3374 @multitable @columnfractions .15 .70
3375 @item @var{A} @tab shall be an integer, real or character variable,
3376 which has the same type and type parameters on all images of the team.
3377 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3378 present, it shall have the same the same value on all images and refer to an
3379 image of the current team.
3380 @item @var{STAT} @tab (optional) a scalar integer variable
3381 @item @var{ERRMSG} @tab (optional) a scalar character variable
3384 @item @emph{Example}:
3389 call co_min (val, result_image=1)
3390 if (this_image() == 1) then
3391 write(*,*) "Minimal value", val ! prints 1
3396 @item @emph{See also}:
3397 @ref{CO_MAX}, @ref{CO_SUM}
3403 @section @code{CO_SUM} --- Sum of values on the current set of images
3405 @cindex Collectives, sum of values
3408 @item @emph{Description}:
3409 @code{CO_SUM} sums up the values of each element of @var{A} on all
3410 images of the current team. If @var{RESULT_IMAGE} is present, the summed-up
3411 values are returned on in @var{A} on the specified image only and the value
3412 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3413 not present, the value is returned on all images. If the execution was
3414 successful and @var{STAT} is present, it is assigned the value zero. If the
3415 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3416 @var{ERRMSG} gets assigned a value describing the occurred error.
3418 @item @emph{Standard}:
3419 Technical Specification (TS) 18508 or later
3422 Collective subroutine
3424 @item @emph{Syntax}:
3425 @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3427 @item @emph{Arguments}:
3428 @multitable @columnfractions .15 .70
3429 @item @var{A} @tab shall be an integer, real or complex variable,
3430 which has the same type and type parameters on all images of the team.
3431 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3432 present, it shall have the same the same value on all images and refer to an
3433 image of the current team.
3434 @item @var{STAT} @tab (optional) a scalar integer variable
3435 @item @var{ERRMSG} @tab (optional) a scalar character variable
3438 @item @emph{Example}:
3443 call co_sum (val, result_image=1)
3444 if (this_image() == 1) then
3445 write(*,*) "The sum is ", val ! prints (n**2 + n)/2, with n = num_images()
3450 @item @emph{See also}:
3451 @ref{CO_MAX}, @ref{CO_MIN}
3456 @node COMMAND_ARGUMENT_COUNT
3457 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
3458 @fnindex COMMAND_ARGUMENT_COUNT
3459 @cindex command-line arguments
3460 @cindex command-line arguments, number of
3461 @cindex arguments, to program
3464 @item @emph{Description}:
3465 @code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the
3466 command line when the containing program was invoked.
3468 @item @emph{Standard}:
3469 Fortran 2003 and later
3474 @item @emph{Syntax}:
3475 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
3477 @item @emph{Arguments}:
3478 @multitable @columnfractions .15 .70
3482 @item @emph{Return value}:
3483 The return value is an @code{INTEGER} of default kind.
3485 @item @emph{Example}:
3487 program test_command_argument_count
3489 count = command_argument_count()
3491 end program test_command_argument_count
3494 @item @emph{See also}:
3495 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
3500 @node COMPILER_OPTIONS
3501 @section @code{COMPILER_OPTIONS} --- Options passed to the compiler
3502 @fnindex COMPILER_OPTIONS
3503 @cindex flags inquiry function
3504 @cindex options inquiry function
3505 @cindex compiler flags inquiry function
3508 @item @emph{Description}:
3509 @code{COMPILER_OPTIONS} returns a string with the options used for
3512 @item @emph{Standard}:
3516 Inquiry function of the module @code{ISO_FORTRAN_ENV}
3518 @item @emph{Syntax}:
3519 @code{STR = COMPILER_OPTIONS()}
3521 @item @emph{Arguments}:
3524 @item @emph{Return value}:
3525 The return value is a default-kind string with system-dependent length.
3526 It contains the compiler flags used to compile the file, which called
3527 the @code{COMPILER_OPTIONS} intrinsic.
3529 @item @emph{Example}:
3532 print '(4a)', 'This file was compiled by ', &
3533 compiler_version(), ' using the options ', &
3538 @item @emph{See also}:
3539 @ref{COMPILER_VERSION}, @ref{ISO_FORTRAN_ENV}
3544 @node COMPILER_VERSION
3545 @section @code{COMPILER_VERSION} --- Compiler version string
3546 @fnindex COMPILER_VERSION
3547 @cindex compiler, name and version
3548 @cindex version of the compiler
3551 @item @emph{Description}:
3552 @code{COMPILER_VERSION} returns a string with the name and the
3553 version of the compiler.
3555 @item @emph{Standard}:
3559 Inquiry function of the module @code{ISO_FORTRAN_ENV}
3561 @item @emph{Syntax}:
3562 @code{STR = COMPILER_VERSION()}
3564 @item @emph{Arguments}:
3567 @item @emph{Return value}:
3568 The return value is a default-kind string with system-dependent length.
3569 It contains the name of the compiler and its version number.
3571 @item @emph{Example}:
3574 print '(4a)', 'This file was compiled by ', &
3575 compiler_version(), ' using the options ', &
3580 @item @emph{See also}:
3581 @ref{COMPILER_OPTIONS}, @ref{ISO_FORTRAN_ENV}
3587 @section @code{COMPLEX} --- Complex conversion function
3589 @cindex complex numbers, conversion to
3590 @cindex conversion, to complex
3593 @item @emph{Description}:
3594 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
3595 to the real component and @var{Y} is converted to the imaginary
3598 @item @emph{Standard}:
3604 @item @emph{Syntax}:
3605 @code{RESULT = COMPLEX(X, Y)}
3607 @item @emph{Arguments}:
3608 @multitable @columnfractions .15 .70
3609 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3610 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
3613 @item @emph{Return value}:
3614 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
3615 value is of default @code{COMPLEX} type.
3617 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
3618 type and one is of @code{INTEGER} type, then the return value is of
3619 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
3620 argument with the highest precision.
3622 @item @emph{Example}:
3624 program test_complex
3627 print *, complex(i, x)
3628 end program test_complex
3631 @item @emph{See also}:
3638 @section @code{CONJG} --- Complex conjugate function
3641 @cindex complex conjugate
3644 @item @emph{Description}:
3645 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
3646 then the result is @code{(x, -y)}
3648 @item @emph{Standard}:
3649 Fortran 77 and later, has overloads that are GNU extensions
3654 @item @emph{Syntax}:
3657 @item @emph{Arguments}:
3658 @multitable @columnfractions .15 .70
3659 @item @var{Z} @tab The type shall be @code{COMPLEX}.
3662 @item @emph{Return value}:
3663 The return value is of type @code{COMPLEX}.
3665 @item @emph{Example}:
3668 complex :: z = (2.0, 3.0)
3669 complex(8) :: dz = (2.71_8, -3.14_8)
3674 end program test_conjg
3677 @item @emph{Specific names}:
3678 @multitable @columnfractions .20 .20 .20 .25
3679 @item Name @tab Argument @tab Return type @tab Standard
3680 @item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension
3681 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
3688 @section @code{COS} --- Cosine function
3694 @cindex trigonometric function, cosine
3698 @item @emph{Description}:
3699 @code{COS(X)} computes the cosine of @var{X}.
3701 @item @emph{Standard}:
3702 Fortran 77 and later, has overloads that are GNU extensions
3707 @item @emph{Syntax}:
3708 @code{RESULT = COS(X)}
3710 @item @emph{Arguments}:
3711 @multitable @columnfractions .15 .70
3712 @item @var{X} @tab The type shall be @code{REAL} or
3716 @item @emph{Return value}:
3717 The return value is of the same type and kind as @var{X}. The real part
3718 of the result is in radians. If @var{X} is of the type @code{REAL},
3719 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
3721 @item @emph{Example}:
3726 end program test_cos
3729 @item @emph{Specific names}:
3730 @multitable @columnfractions .20 .20 .20 .25
3731 @item Name @tab Argument @tab Return type @tab Standard
3732 @item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
3733 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3734 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
3735 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3736 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3739 @item @emph{See also}:
3740 Inverse function: @ref{ACOS}
3747 @section @code{COSH} --- Hyperbolic cosine function
3750 @cindex hyperbolic cosine
3751 @cindex hyperbolic function, cosine
3752 @cindex cosine, hyperbolic
3755 @item @emph{Description}:
3756 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
3758 @item @emph{Standard}:
3759 Fortran 77 and later, for a complex argument Fortran 2008 or later
3764 @item @emph{Syntax}:
3767 @item @emph{Arguments}:
3768 @multitable @columnfractions .15 .70
3769 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
3772 @item @emph{Return value}:
3773 The return value has same type and kind as @var{X}. If @var{X} is
3774 complex, the imaginary part of the result is in radians. If @var{X}
3775 is @code{REAL}, the return value has a lower bound of one,
3776 @math{\cosh (x) \geq 1}.
3778 @item @emph{Example}:
3781 real(8) :: x = 1.0_8
3783 end program test_cosh
3786 @item @emph{Specific names}:
3787 @multitable @columnfractions .20 .20 .20 .25
3788 @item Name @tab Argument @tab Return type @tab Standard
3789 @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
3790 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3793 @item @emph{See also}:
3794 Inverse function: @ref{ACOSH}
3801 @section @code{COUNT} --- Count function
3803 @cindex array, conditionally count elements
3804 @cindex array, element counting
3805 @cindex array, number of elements
3808 @item @emph{Description}:
3810 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
3811 or, if the @var{DIM} argument is supplied, counts the number of
3812 elements along each row of the array in the @var{DIM} direction.
3813 If the array has zero size, or all of the elements of @var{MASK} are
3814 @code{.FALSE.}, then the result is @code{0}.
3816 @item @emph{Standard}:
3817 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
3820 Transformational function
3822 @item @emph{Syntax}:
3823 @code{RESULT = COUNT(MASK [, DIM, KIND])}
3825 @item @emph{Arguments}:
3826 @multitable @columnfractions .15 .70
3827 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
3828 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
3829 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3830 expression indicating the kind parameter of the result.
3833 @item @emph{Return value}:
3834 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
3835 @var{KIND} is absent, the return value is of default integer kind.
3836 If @var{DIM} is present, the result is an array with a rank one less
3837 than the rank of @var{ARRAY}, and a size corresponding to the shape
3838 of @var{ARRAY} with the @var{DIM} dimension removed.
3840 @item @emph{Example}:
3843 integer, dimension(2,3) :: a, b
3844 logical, dimension(2,3) :: mask
3845 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
3846 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
3847 print '(3i3)', a(1,:)
3848 print '(3i3)', a(2,:)
3850 print '(3i3)', b(1,:)
3851 print '(3i3)', b(2,:)
3854 print '(3l3)', mask(1,:)
3855 print '(3l3)', mask(2,:)
3857 print '(3i3)', count(mask)
3859 print '(3i3)', count(mask, 1)
3861 print '(3i3)', count(mask, 2)
3862 end program test_count
3869 @section @code{CPU_TIME} --- CPU elapsed time in seconds
3871 @cindex time, elapsed
3874 @item @emph{Description}:
3875 Returns a @code{REAL} value representing the elapsed CPU time in
3876 seconds. This is useful for testing segments of code to determine
3879 If a time source is available, time will be reported with microsecond
3880 resolution. If no time source is available, @var{TIME} is set to
3883 Note that @var{TIME} may contain a, system dependent, arbitrary offset
3884 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
3885 value is meaningless, only differences between subsequent calls to
3886 this subroutine, as shown in the example below, should be used.
3889 @item @emph{Standard}:
3890 Fortran 95 and later
3895 @item @emph{Syntax}:
3896 @code{CALL CPU_TIME(TIME)}
3898 @item @emph{Arguments}:
3899 @multitable @columnfractions .15 .70
3900 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
3903 @item @emph{Return value}:
3906 @item @emph{Example}:
3908 program test_cpu_time
3909 real :: start, finish
3910 call cpu_time(start)
3911 ! put code to test here
3912 call cpu_time(finish)
3913 print '("Time = ",f6.3," seconds.")',finish-start
3914 end program test_cpu_time
3917 @item @emph{See also}:
3918 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
3924 @section @code{CSHIFT} --- Circular shift elements of an array
3926 @cindex array, shift circularly
3927 @cindex array, permutation
3928 @cindex array, rotate
3931 @item @emph{Description}:
3932 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
3933 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
3934 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
3935 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
3936 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
3937 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
3938 sections of @var{ARRAY} along the given dimension are shifted. Elements
3939 shifted out one end of each rank one section are shifted back in the other end.
3941 @item @emph{Standard}:
3942 Fortran 95 and later
3945 Transformational function
3947 @item @emph{Syntax}:
3948 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
3950 @item @emph{Arguments}:
3951 @multitable @columnfractions .15 .70
3952 @item @var{ARRAY} @tab Shall be an array of any type.
3953 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3954 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3957 @item @emph{Return value}:
3958 Returns an array of same type and rank as the @var{ARRAY} argument.
3960 @item @emph{Example}:
3963 integer, dimension(3,3) :: a
3964 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3965 print '(3i3)', a(1,:)
3966 print '(3i3)', a(2,:)
3967 print '(3i3)', a(3,:)
3968 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
3970 print '(3i3)', a(1,:)
3971 print '(3i3)', a(2,:)
3972 print '(3i3)', a(3,:)
3973 end program test_cshift
3980 @section @code{CTIME} --- Convert a time into a string
3982 @cindex time, conversion to string
3983 @cindex conversion, to string
3986 @item @emph{Description}:
3987 @code{CTIME} converts a system time value, such as returned by
3988 @code{TIME8}, to a string. The output will be of the form @samp{Sat
3989 Aug 19 18:13:14 1995}.
3991 This intrinsic is provided in both subroutine and function forms; however,
3992 only one form can be used in any given program unit.
3994 @item @emph{Standard}:
3998 Subroutine, function
4000 @item @emph{Syntax}:
4001 @multitable @columnfractions .80
4002 @item @code{CALL CTIME(TIME, RESULT)}.
4003 @item @code{RESULT = CTIME(TIME)}.
4006 @item @emph{Arguments}:
4007 @multitable @columnfractions .15 .70
4008 @item @var{TIME} @tab The type shall be of type @code{INTEGER}.
4009 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
4010 of default kind. It is an @code{INTENT(OUT)} argument. If the length
4011 of this variable is too short for the time and date string to fit
4012 completely, it will be blank on procedure return.
4015 @item @emph{Return value}:
4016 The converted date and time as a string.
4018 @item @emph{Example}:
4022 character(len=30) :: date
4025 ! Do something, main part of the program
4028 print *, 'Program was started on ', date
4029 end program test_ctime
4032 @item @emph{See Also}:
4033 @ref{DATE_AND_TIME}, @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
4039 @section @code{DATE_AND_TIME} --- Date and time subroutine
4040 @fnindex DATE_AND_TIME
4041 @cindex date, current
4042 @cindex current date
4043 @cindex time, current
4044 @cindex current time
4047 @item @emph{Description}:
4048 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
4049 time information from the real-time system clock. @var{DATE} is
4050 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
4051 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
4052 representing the difference with respect to Coordinated Universal Time (UTC).
4053 Unavailable time and date parameters return blanks.
4055 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
4057 @multitable @columnfractions .15 .30 .40
4058 @item @tab @code{VALUE(1)}: @tab The year
4059 @item @tab @code{VALUE(2)}: @tab The month
4060 @item @tab @code{VALUE(3)}: @tab The day of the month
4061 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
4062 @item @tab @code{VALUE(5)}: @tab The hour of the day
4063 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
4064 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
4065 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
4068 @item @emph{Standard}:
4069 Fortran 95 and later
4074 @item @emph{Syntax}:
4075 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
4077 @item @emph{Arguments}:
4078 @multitable @columnfractions .15 .70
4079 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
4080 or larger, and of default kind.
4081 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
4082 or larger, and of default kind.
4083 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
4084 or larger, and of default kind.
4085 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
4088 @item @emph{Return value}:
4091 @item @emph{Example}:
4093 program test_time_and_date
4094 character(8) :: date
4095 character(10) :: time
4096 character(5) :: zone
4097 integer,dimension(8) :: values
4098 ! using keyword arguments
4099 call date_and_time(date,time,zone,values)
4100 call date_and_time(DATE=date,ZONE=zone)
4101 call date_and_time(TIME=time)
4102 call date_and_time(VALUES=values)
4103 print '(a,2x,a,2x,a)', date, time, zone
4104 print '(8i5)', values
4105 end program test_time_and_date
4108 @item @emph{See also}:
4109 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
4115 @section @code{DBLE} --- Double conversion function
4117 @cindex conversion, to real
4120 @item @emph{Description}:
4121 @code{DBLE(A)} Converts @var{A} to double precision real type.
4123 @item @emph{Standard}:
4124 Fortran 77 and later
4129 @item @emph{Syntax}:
4130 @code{RESULT = DBLE(A)}
4132 @item @emph{Arguments}:
4133 @multitable @columnfractions .15 .70
4134 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
4138 @item @emph{Return value}:
4139 The return value is of type double precision real.
4141 @item @emph{Example}:
4146 complex :: z = (2.3,1.14)
4147 print *, dble(x), dble(i), dble(z)
4148 end program test_dble
4151 @item @emph{See also}:
4158 @section @code{DCMPLX} --- Double complex conversion function
4160 @cindex complex numbers, conversion to
4161 @cindex conversion, to complex
4164 @item @emph{Description}:
4165 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
4166 converted to the real component. If @var{Y} is present it is converted to the
4167 imaginary component. If @var{Y} is not present then the imaginary component is
4168 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
4170 @item @emph{Standard}:
4176 @item @emph{Syntax}:
4177 @code{RESULT = DCMPLX(X [, Y])}
4179 @item @emph{Arguments}:
4180 @multitable @columnfractions .15 .70
4181 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
4183 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
4184 @code{INTEGER} or @code{REAL}.
4187 @item @emph{Return value}:
4188 The return value is of type @code{COMPLEX(8)}
4190 @item @emph{Example}:
4200 print *, dcmplx(x,i)
4201 end program test_dcmplx
4207 @section @code{DIGITS} --- Significant binary digits function
4209 @cindex model representation, significant digits
4212 @item @emph{Description}:
4213 @code{DIGITS(X)} returns the number of significant binary digits of the internal
4214 model representation of @var{X}. For example, on a system using a 32-bit
4215 floating point representation, a default real number would likely return 24.
4217 @item @emph{Standard}:
4218 Fortran 95 and later
4223 @item @emph{Syntax}:
4224 @code{RESULT = DIGITS(X)}
4226 @item @emph{Arguments}:
4227 @multitable @columnfractions .15 .70
4228 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
4231 @item @emph{Return value}:
4232 The return value is of type @code{INTEGER}.
4234 @item @emph{Example}:
4237 integer :: i = 12345
4243 end program test_digits
4250 @section @code{DIM} --- Positive difference
4254 @cindex positive difference
4257 @item @emph{Description}:
4258 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
4259 otherwise returns zero.
4261 @item @emph{Standard}:
4262 Fortran 77 and later
4267 @item @emph{Syntax}:
4268 @code{RESULT = DIM(X, Y)}
4270 @item @emph{Arguments}:
4271 @multitable @columnfractions .15 .70
4272 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
4273 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
4276 @item @emph{Return value}:
4277 The return value is of type @code{INTEGER} or @code{REAL}.
4279 @item @emph{Example}:
4285 x = dim(4.345_8, 2.111_8)
4288 end program test_dim
4291 @item @emph{Specific names}:
4292 @multitable @columnfractions .20 .20 .20 .25
4293 @item Name @tab Argument @tab Return type @tab Standard
4294 @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
4295 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
4296 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
4303 @section @code{DOT_PRODUCT} --- Dot product function
4304 @fnindex DOT_PRODUCT
4306 @cindex vector product
4307 @cindex product, vector
4310 @item @emph{Description}:
4311 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
4312 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
4313 either numeric or logical and must be arrays of rank one and of equal size. If
4314 the vectors are @code{INTEGER} or @code{REAL}, the result is
4315 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
4316 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
4317 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
4319 @item @emph{Standard}:
4320 Fortran 95 and later
4323 Transformational function
4325 @item @emph{Syntax}:
4326 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
4328 @item @emph{Arguments}:
4329 @multitable @columnfractions .15 .70
4330 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
4331 @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.
4334 @item @emph{Return value}:
4335 If the arguments are numeric, the return value is a scalar of numeric type,
4336 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
4337 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
4339 @item @emph{Example}:
4341 program test_dot_prod
4342 integer, dimension(3) :: a, b
4349 print *, dot_product(a,b)
4350 end program test_dot_prod
4357 @section @code{DPROD} --- Double product function
4359 @cindex product, double-precision
4362 @item @emph{Description}:
4363 @code{DPROD(X,Y)} returns the product @code{X*Y}.
4365 @item @emph{Standard}:
4366 Fortran 77 and later
4371 @item @emph{Syntax}:
4372 @code{RESULT = DPROD(X, Y)}
4374 @item @emph{Arguments}:
4375 @multitable @columnfractions .15 .70
4376 @item @var{X} @tab The type shall be @code{REAL}.
4377 @item @var{Y} @tab The type shall be @code{REAL}.
4380 @item @emph{Return value}:
4381 The return value is of type @code{REAL(8)}.
4383 @item @emph{Example}:
4391 end program test_dprod
4394 @item @emph{Specific names}:
4395 @multitable @columnfractions .20 .20 .20 .25
4396 @item Name @tab Argument @tab Return type @tab Standard
4397 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
4404 @section @code{DREAL} --- Double real part function
4406 @cindex complex numbers, real part
4409 @item @emph{Description}:
4410 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
4412 @item @emph{Standard}:
4418 @item @emph{Syntax}:
4419 @code{RESULT = DREAL(A)}
4421 @item @emph{Arguments}:
4422 @multitable @columnfractions .15 .70
4423 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
4426 @item @emph{Return value}:
4427 The return value is of type @code{REAL(8)}.
4429 @item @emph{Example}:
4432 complex(8) :: z = (1.3_8,7.2_8)
4434 end program test_dreal
4437 @item @emph{See also}:
4445 @section @code{DSHIFTL} --- Combined left shift
4447 @cindex left shift, combined
4451 @item @emph{Description}:
4452 @code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
4453 rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
4454 bits of @var{J}, and the remaining bits are the rightmost bits of
4457 @item @emph{Standard}:
4458 Fortran 2008 and later
4463 @item @emph{Syntax}:
4464 @code{RESULT = DSHIFTL(I, J, SHIFT)}
4466 @item @emph{Arguments}:
4467 @multitable @columnfractions .15 .70
4468 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
4469 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
4470 If both @var{I} and @var{J} have integer type, then they shall have
4471 the same kind type parameter. @var{I} and @var{J} shall not both be
4473 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
4474 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
4475 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
4476 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
4479 @item @emph{Return value}:
4480 If either @var{I} or @var{J} is a BOZ constant, it is first converted
4481 as if by the intrinsic function @code{INT} to an integer type with the
4482 kind type parameter of the other.
4484 @item @emph{See also}:
4490 @section @code{DSHIFTR} --- Combined right shift
4492 @cindex right shift, combined
4493 @cindex shift, right
4496 @item @emph{Description}:
4497 @code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
4498 leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
4499 bits of @var{I}, and the remaining bits are the leftmost bits of
4502 @item @emph{Standard}:
4503 Fortran 2008 and later
4508 @item @emph{Syntax}:
4509 @code{RESULT = DSHIFTR(I, J, SHIFT)}
4511 @item @emph{Arguments}:
4512 @multitable @columnfractions .15 .70
4513 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
4514 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
4515 If both @var{I} and @var{J} have integer type, then they shall have
4516 the same kind type parameter. @var{I} and @var{J} shall not both be
4518 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
4519 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
4520 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
4521 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
4524 @item @emph{Return value}:
4525 If either @var{I} or @var{J} is a BOZ constant, it is first converted
4526 as if by the intrinsic function @code{INT} to an integer type with the
4527 kind type parameter of the other.
4529 @item @emph{See also}:
4535 @section @code{DTIME} --- Execution time subroutine (or function)
4537 @cindex time, elapsed
4538 @cindex elapsed time
4541 @item @emph{Description}:
4542 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
4543 since the start of the process's execution in @var{TIME}. @var{VALUES}
4544 returns the user and system components of this time in @code{VALUES(1)} and
4545 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
4548 Subsequent invocations of @code{DTIME} return values accumulated since the
4549 previous invocation.
4551 On some systems, the underlying timings are represented using types with
4552 sufficiently small limits that overflows (wrap around) are possible, such as
4553 32-bit types. Therefore, the values returned by this intrinsic might be, or
4554 become, negative, or numerically less than previous values, during a single
4555 run of the compiled program.
4557 Please note, that this implementation is thread safe if used within OpenMP
4558 directives, i.e., its state will be consistent while called from multiple
4559 threads. However, if @code{DTIME} is called from multiple threads, the result
4560 is still the time since the last invocation. This may not give the intended
4561 results. If possible, use @code{CPU_TIME} instead.
4563 This intrinsic is provided in both subroutine and function forms; however,
4564 only one form can be used in any given program unit.
4566 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
4568 @multitable @columnfractions .15 .30 .40
4569 @item @tab @code{VALUES(1)}: @tab User time in seconds.
4570 @item @tab @code{VALUES(2)}: @tab System time in seconds.
4571 @item @tab @code{TIME}: @tab Run time since start in seconds.
4574 @item @emph{Standard}:
4578 Subroutine, function
4580 @item @emph{Syntax}:
4581 @multitable @columnfractions .80
4582 @item @code{CALL DTIME(VALUES, TIME)}.
4583 @item @code{TIME = DTIME(VALUES)}, (not recommended).
4586 @item @emph{Arguments}:
4587 @multitable @columnfractions .15 .70
4588 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
4589 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
4592 @item @emph{Return value}:
4593 Elapsed time in seconds since the last invocation or since the start of program
4594 execution if not called before.
4596 @item @emph{Example}:
4600 real, dimension(2) :: tarray
4602 call dtime(tarray, result)
4606 do i=1,100000000 ! Just a delay
4609 call dtime(tarray, result)
4613 end program test_dtime
4616 @item @emph{See also}:
4624 @section @code{EOSHIFT} --- End-off shift elements of an array
4626 @cindex array, shift
4629 @item @emph{Description}:
4630 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
4631 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
4632 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
4633 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
4634 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
4635 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
4636 then all complete rank one sections of @var{ARRAY} along the given dimension are
4637 shifted. Elements shifted out one end of each rank one section are dropped. If
4638 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
4639 is copied back in the other end. If @var{BOUNDARY} is not present then the
4640 following are copied in depending on the type of @var{ARRAY}.
4642 @multitable @columnfractions .15 .80
4643 @item @emph{Array Type} @tab @emph{Boundary Value}
4644 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
4645 @item Logical @tab @code{.FALSE.}.
4646 @item Character(@var{len}) @tab @var{len} blanks.
4649 @item @emph{Standard}:
4650 Fortran 95 and later
4653 Transformational function
4655 @item @emph{Syntax}:
4656 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
4658 @item @emph{Arguments}:
4659 @multitable @columnfractions .15 .70
4660 @item @var{ARRAY} @tab May be any type, not scalar.
4661 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
4662 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
4663 @item @var{DIM} @tab The type shall be @code{INTEGER}.
4666 @item @emph{Return value}:
4667 Returns an array of same type and rank as the @var{ARRAY} argument.
4669 @item @emph{Example}:
4671 program test_eoshift
4672 integer, dimension(3,3) :: a
4673 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
4674 print '(3i3)', a(1,:)
4675 print '(3i3)', a(2,:)
4676 print '(3i3)', a(3,:)
4677 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
4679 print '(3i3)', a(1,:)
4680 print '(3i3)', a(2,:)
4681 print '(3i3)', a(3,:)
4682 end program test_eoshift
4689 @section @code{EPSILON} --- Epsilon function
4691 @cindex model representation, epsilon
4694 @item @emph{Description}:
4695 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
4696 as @var{X} such that @math{1 + E > 1}.
4698 @item @emph{Standard}:
4699 Fortran 95 and later
4704 @item @emph{Syntax}:
4705 @code{RESULT = EPSILON(X)}
4707 @item @emph{Arguments}:
4708 @multitable @columnfractions .15 .70
4709 @item @var{X} @tab The type shall be @code{REAL}.
4712 @item @emph{Return value}:
4713 The return value is of same type as the argument.
4715 @item @emph{Example}:
4717 program test_epsilon
4722 end program test_epsilon
4729 @section @code{ERF} --- Error function
4731 @cindex error function
4734 @item @emph{Description}:
4735 @code{ERF(X)} computes the error function of @var{X}.
4737 @item @emph{Standard}:
4738 Fortran 2008 and later
4743 @item @emph{Syntax}:
4744 @code{RESULT = ERF(X)}
4746 @item @emph{Arguments}:
4747 @multitable @columnfractions .15 .70
4748 @item @var{X} @tab The type shall be @code{REAL}.
4751 @item @emph{Return value}:
4752 The return value is of type @code{REAL}, of the same kind as
4753 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
4755 @item @emph{Example}:
4758 real(8) :: x = 0.17_8
4760 end program test_erf
4763 @item @emph{Specific names}:
4764 @multitable @columnfractions .20 .20 .20 .25
4765 @item Name @tab Argument @tab Return type @tab Standard
4766 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4773 @section @code{ERFC} --- Error function
4775 @cindex error function, complementary
4778 @item @emph{Description}:
4779 @code{ERFC(X)} computes the complementary error function of @var{X}.
4781 @item @emph{Standard}:
4782 Fortran 2008 and later
4787 @item @emph{Syntax}:
4788 @code{RESULT = ERFC(X)}
4790 @item @emph{Arguments}:
4791 @multitable @columnfractions .15 .70
4792 @item @var{X} @tab The type shall be @code{REAL}.
4795 @item @emph{Return value}:
4796 The return value is of type @code{REAL} and of the same kind as @var{X}.
4797 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
4799 @item @emph{Example}:
4802 real(8) :: x = 0.17_8
4804 end program test_erfc
4807 @item @emph{Specific names}:
4808 @multitable @columnfractions .20 .20 .20 .25
4809 @item Name @tab Argument @tab Return type @tab Standard
4810 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4817 @section @code{ERFC_SCALED} --- Error function
4818 @fnindex ERFC_SCALED
4819 @cindex error function, complementary, exponentially-scaled
4822 @item @emph{Description}:
4823 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
4824 error function of @var{X}.
4826 @item @emph{Standard}:
4827 Fortran 2008 and later
4832 @item @emph{Syntax}:
4833 @code{RESULT = ERFC_SCALED(X)}
4835 @item @emph{Arguments}:
4836 @multitable @columnfractions .15 .70
4837 @item @var{X} @tab The type shall be @code{REAL}.
4840 @item @emph{Return value}:
4841 The return value is of type @code{REAL} and of the same kind as @var{X}.
4843 @item @emph{Example}:
4845 program test_erfc_scaled
4846 real(8) :: x = 0.17_8
4848 end program test_erfc_scaled
4855 @section @code{ETIME} --- Execution time subroutine (or function)
4857 @cindex time, elapsed
4860 @item @emph{Description}:
4861 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
4862 since the start of the process's execution in @var{TIME}. @var{VALUES}
4863 returns the user and system components of this time in @code{VALUES(1)} and
4864 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
4866 On some systems, the underlying timings are represented using types with
4867 sufficiently small limits that overflows (wrap around) are possible, such as
4868 32-bit types. Therefore, the values returned by this intrinsic might be, or
4869 become, negative, or numerically less than previous values, during a single
4870 run of the compiled program.
4872 This intrinsic is provided in both subroutine and function forms; however,
4873 only one form can be used in any given program unit.
4875 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
4877 @multitable @columnfractions .15 .30 .60
4878 @item @tab @code{VALUES(1)}: @tab User time in seconds.
4879 @item @tab @code{VALUES(2)}: @tab System time in seconds.
4880 @item @tab @code{TIME}: @tab Run time since start in seconds.
4883 @item @emph{Standard}:
4887 Subroutine, function
4889 @item @emph{Syntax}:
4890 @multitable @columnfractions .80
4891 @item @code{CALL ETIME(VALUES, TIME)}.
4892 @item @code{TIME = ETIME(VALUES)}, (not recommended).
4895 @item @emph{Arguments}:
4896 @multitable @columnfractions .15 .70
4897 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
4898 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
4901 @item @emph{Return value}:
4902 Elapsed time in seconds since the start of program execution.
4904 @item @emph{Example}:
4908 real, dimension(2) :: tarray
4910 call ETIME(tarray, result)
4914 do i=1,100000000 ! Just a delay
4917 call ETIME(tarray, result)
4921 end program test_etime
4924 @item @emph{See also}:
4931 @node EXECUTE_COMMAND_LINE
4932 @section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
4933 @fnindex EXECUTE_COMMAND_LINE
4934 @cindex system, system call
4935 @cindex command line
4938 @item @emph{Description}:
4939 @code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
4942 The @code{COMMAND} argument is passed to the shell and executed, using
4943 the C library's @code{system} call. (The shell is @code{sh} on Unix
4944 systems, and @code{cmd.exe} on Windows.) If @code{WAIT} is present
4945 and has the value false, the execution of the command is asynchronous
4946 if the system supports it; otherwise, the command is executed
4949 The three last arguments allow the user to get status information. After
4950 synchronous execution, @code{EXITSTAT} contains the integer exit code of
4951 the command, as returned by @code{system}. @code{CMDSTAT} is set to zero
4952 if the command line was executed (whatever its exit status was).
4953 @code{CMDMSG} is assigned an error message if an error has occurred.
4955 Note that the @code{system} function need not be thread-safe. It is
4956 the responsibility of the user to ensure that @code{system} is not
4957 called concurrently.
4959 @item @emph{Standard}:
4960 Fortran 2008 and later
4965 @item @emph{Syntax}:
4966 @code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
4968 @item @emph{Arguments}:
4969 @multitable @columnfractions .15 .70
4970 @item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
4971 @item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
4972 @item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
4974 @item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
4976 @item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
4980 @item @emph{Example}:
4985 call execute_command_line ("external_prog.exe", exitstat=i)
4986 print *, "Exit status of external_prog.exe was ", i
4988 call execute_command_line ("reindex_files.exe", wait=.false.)
4989 print *, "Now reindexing files in the background"
4991 end program test_exec
4997 Because this intrinsic is implemented in terms of the @code{system}
4998 function call, its behavior with respect to signaling is processor
4999 dependent. In particular, on POSIX-compliant systems, the SIGINT and
5000 SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
5001 such, if the parent process is terminated, the child process might not be
5002 terminated alongside.
5005 @item @emph{See also}:
5012 @section @code{EXIT} --- Exit the program with status.
5014 @cindex program termination
5015 @cindex terminate program
5018 @item @emph{Description}:
5019 @code{EXIT} causes immediate termination of the program with status. If status
5020 is omitted it returns the canonical @emph{success} for the system. All Fortran
5021 I/O units are closed.
5023 @item @emph{Standard}:
5029 @item @emph{Syntax}:
5030 @code{CALL EXIT([STATUS])}
5032 @item @emph{Arguments}:
5033 @multitable @columnfractions .15 .70
5034 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
5037 @item @emph{Return value}:
5038 @code{STATUS} is passed to the parent process on exit.
5040 @item @emph{Example}:
5043 integer :: STATUS = 0
5044 print *, 'This program is going to exit.'
5046 end program test_exit
5049 @item @emph{See also}:
5050 @ref{ABORT}, @ref{KILL}
5056 @section @code{EXP} --- Exponential function
5062 @cindex exponential function
5063 @cindex logarithm function, inverse
5066 @item @emph{Description}:
5067 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
5069 @item @emph{Standard}:
5070 Fortran 77 and later, has overloads that are GNU extensions
5075 @item @emph{Syntax}:
5076 @code{RESULT = EXP(X)}
5078 @item @emph{Arguments}:
5079 @multitable @columnfractions .15 .70
5080 @item @var{X} @tab The type shall be @code{REAL} or
5084 @item @emph{Return value}:
5085 The return value has same type and kind as @var{X}.
5087 @item @emph{Example}:
5092 end program test_exp
5095 @item @emph{Specific names}:
5096 @multitable @columnfractions .20 .20 .20 .25
5097 @item Name @tab Argument @tab Return type @tab Standard
5098 @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
5099 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
5100 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
5101 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5102 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5109 @section @code{EXPONENT} --- Exponent function
5111 @cindex real number, exponent
5112 @cindex floating point, exponent
5115 @item @emph{Description}:
5116 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
5117 is zero the value returned is zero.
5119 @item @emph{Standard}:
5120 Fortran 95 and later
5125 @item @emph{Syntax}:
5126 @code{RESULT = EXPONENT(X)}
5128 @item @emph{Arguments}:
5129 @multitable @columnfractions .15 .70
5130 @item @var{X} @tab The type shall be @code{REAL}.
5133 @item @emph{Return value}:
5134 The return value is of type default @code{INTEGER}.
5136 @item @emph{Example}:
5138 program test_exponent
5143 print *, exponent(0.0)
5144 end program test_exponent
5150 @node EXTENDS_TYPE_OF
5151 @section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension
5152 @fnindex EXTENDS_TYPE_OF
5155 @item @emph{Description}:
5156 Query dynamic type for extension.
5158 @item @emph{Standard}:
5159 Fortran 2003 and later
5164 @item @emph{Syntax}:
5165 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
5167 @item @emph{Arguments}:
5168 @multitable @columnfractions .15 .70
5169 @item @var{A} @tab Shall be an object of extensible declared type or
5170 unlimited polymorphic.
5171 @item @var{MOLD} @tab Shall be an object of extensible declared type or
5172 unlimited polymorphic.
5175 @item @emph{Return value}:
5176 The return value is a scalar of type default logical. It is true if and only if
5177 the dynamic type of A is an extension type of the dynamic type of MOLD.
5180 @item @emph{See also}:
5187 @section @code{FDATE} --- Get the current time as a string
5189 @cindex time, current
5190 @cindex current time
5191 @cindex date, current
5192 @cindex current date
5195 @item @emph{Description}:
5196 @code{FDATE(DATE)} returns the current date (using the same format as
5197 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
5200 This intrinsic is provided in both subroutine and function forms; however,
5201 only one form can be used in any given program unit.
5203 @item @emph{Standard}:
5207 Subroutine, function
5209 @item @emph{Syntax}:
5210 @multitable @columnfractions .80
5211 @item @code{CALL FDATE(DATE)}.
5212 @item @code{DATE = FDATE()}.
5215 @item @emph{Arguments}:
5216 @multitable @columnfractions .15 .70
5217 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
5218 default kind. It is an @code{INTENT(OUT)} argument. If the length of
5219 this variable is too short for the date and time string to fit
5220 completely, it will be blank on procedure return.
5223 @item @emph{Return value}:
5224 The current date and time as a string.
5226 @item @emph{Example}:
5230 character(len=30) :: date
5232 print *, 'Program started on ', date
5233 do i = 1, 100000000 ! Just a delay
5237 print *, 'Program ended on ', date
5238 end program test_fdate
5241 @item @emph{See also}:
5242 @ref{DATE_AND_TIME}, @ref{CTIME}
5247 @section @code{FGET} --- Read a single character in stream mode from stdin
5249 @cindex read character, stream mode
5250 @cindex stream mode, read character
5251 @cindex file operation, read character
5254 @item @emph{Description}:
5255 Read a single character in stream mode from stdin by bypassing normal
5256 formatted output. Stream I/O should not be mixed with normal record-oriented
5257 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
5259 This intrinsic is provided in both subroutine and function forms; however,
5260 only one form can be used in any given program unit.
5262 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
5263 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5264 Programmers should consider the use of new stream IO feature in new code
5265 for future portability. See also @ref{Fortran 2003 status}.
5267 @item @emph{Standard}:
5271 Subroutine, function
5273 @item @emph{Syntax}:
5274 @multitable @columnfractions .80
5275 @item @code{CALL FGET(C [, STATUS])}
5276 @item @code{STATUS = FGET(C)}
5279 @item @emph{Arguments}:
5280 @multitable @columnfractions .15 .70
5281 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5283 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5284 Returns 0 on success, -1 on end-of-file, and a system specific positive
5285 error code otherwise.
5288 @item @emph{Example}:
5291 INTEGER, PARAMETER :: strlen = 100
5292 INTEGER :: status, i = 1
5293 CHARACTER(len=strlen) :: str = ""
5295 WRITE (*,*) 'Enter text:'
5297 CALL fget(str(i:i), status)
5298 if (status /= 0 .OR. i > strlen) exit
5301 WRITE (*,*) TRIM(str)
5305 @item @emph{See also}:
5306 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
5312 @section @code{FGETC} --- Read a single character in stream mode
5314 @cindex read character, stream mode
5315 @cindex stream mode, read character
5316 @cindex file operation, read character
5319 @item @emph{Description}:
5320 Read a single character in stream mode by bypassing normal formatted output.
5321 Stream I/O should not be mixed with normal record-oriented (formatted or
5322 unformatted) I/O on the same unit; the results are unpredictable.
5324 This intrinsic is provided in both subroutine and function forms; however,
5325 only one form can be used in any given program unit.
5327 Note that the @code{FGET} intrinsic is provided for backwards compatibility
5328 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5329 Programmers should consider the use of new stream IO feature in new code
5330 for future portability. See also @ref{Fortran 2003 status}.
5332 @item @emph{Standard}:
5336 Subroutine, function
5338 @item @emph{Syntax}:
5339 @multitable @columnfractions .80
5340 @item @code{CALL FGETC(UNIT, C [, STATUS])}
5341 @item @code{STATUS = FGETC(UNIT, C)}
5344 @item @emph{Arguments}:
5345 @multitable @columnfractions .15 .70
5346 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
5347 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5349 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5350 Returns 0 on success, -1 on end-of-file and a system specific positive
5351 error code otherwise.
5354 @item @emph{Example}:
5357 INTEGER :: fd = 42, status
5360 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
5362 CALL fgetc(fd, c, status)
5363 IF (status /= 0) EXIT
5370 @item @emph{See also}:
5371 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
5377 @section @code{FLOOR} --- Integer floor function
5380 @cindex rounding, floor
5383 @item @emph{Description}:
5384 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
5386 @item @emph{Standard}:
5387 Fortran 95 and later
5392 @item @emph{Syntax}:
5393 @code{RESULT = FLOOR(A [, KIND])}
5395 @item @emph{Arguments}:
5396 @multitable @columnfractions .15 .70
5397 @item @var{A} @tab The type shall be @code{REAL}.
5398 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5399 expression indicating the kind parameter of the result.
5402 @item @emph{Return value}:
5403 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
5404 and of default-kind @code{INTEGER} otherwise.
5406 @item @emph{Example}:
5411 print *, floor(x) ! returns 63
5412 print *, floor(y) ! returns -64
5413 end program test_floor
5416 @item @emph{See also}:
5417 @ref{CEILING}, @ref{NINT}
5424 @section @code{FLUSH} --- Flush I/O unit(s)
5426 @cindex file operation, flush
5429 @item @emph{Description}:
5430 Flushes Fortran unit(s) currently open for output. Without the optional
5431 argument, all units are flushed, otherwise just the unit specified.
5433 @item @emph{Standard}:
5439 @item @emph{Syntax}:
5440 @code{CALL FLUSH(UNIT)}
5442 @item @emph{Arguments}:
5443 @multitable @columnfractions .15 .70
5444 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
5448 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
5449 statement that should be preferred over the @code{FLUSH} intrinsic.
5451 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
5452 have identical effect: they flush the runtime library's I/O buffer so
5453 that the data becomes visible to other processes. This does not guarantee
5454 that the data is committed to disk.
5456 On POSIX systems, you can request that all data is transferred to the
5457 storage device by calling the @code{fsync} function, with the POSIX file
5458 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
5459 @code{FNUM}). The following example shows how:
5462 ! Declare the interface for POSIX fsync function
5464 function fsync (fd) bind(c,name="fsync")
5465 use iso_c_binding, only: c_int
5466 integer(c_int), value :: fd
5467 integer(c_int) :: fsync
5471 ! Variable declaration
5475 open (10,file="foo")
5478 ! Perform I/O on unit 10
5483 ret = fsync(fnum(10))
5485 ! Handle possible error
5486 if (ret /= 0) stop "Error calling FSYNC"
5494 @section @code{FNUM} --- File number function
5496 @cindex file operation, file number
5499 @item @emph{Description}:
5500 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
5501 open Fortran I/O unit @code{UNIT}.
5503 @item @emph{Standard}:
5509 @item @emph{Syntax}:
5510 @code{RESULT = FNUM(UNIT)}
5512 @item @emph{Arguments}:
5513 @multitable @columnfractions .15 .70
5514 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
5517 @item @emph{Return value}:
5518 The return value is of type @code{INTEGER}
5520 @item @emph{Example}:
5524 open (unit=10, status = "scratch")
5528 end program test_fnum
5535 @section @code{FPUT} --- Write a single character in stream mode to stdout
5537 @cindex write character, stream mode
5538 @cindex stream mode, write character
5539 @cindex file operation, write character
5542 @item @emph{Description}:
5543 Write a single character in stream mode to stdout by bypassing normal
5544 formatted output. Stream I/O should not be mixed with normal record-oriented
5545 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
5547 This intrinsic is provided in both subroutine and function forms; however,
5548 only one form can be used in any given program unit.
5550 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
5551 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5552 Programmers should consider the use of new stream IO feature in new code
5553 for future portability. See also @ref{Fortran 2003 status}.
5555 @item @emph{Standard}:
5559 Subroutine, function
5561 @item @emph{Syntax}:
5562 @multitable @columnfractions .80
5563 @item @code{CALL FPUT(C [, STATUS])}
5564 @item @code{STATUS = FPUT(C)}
5567 @item @emph{Arguments}:
5568 @multitable @columnfractions .15 .70
5569 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5571 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5572 Returns 0 on success, -1 on end-of-file and a system specific positive
5573 error code otherwise.
5576 @item @emph{Example}:
5579 CHARACTER(len=10) :: str = "gfortran"
5581 DO i = 1, len_trim(str)
5587 @item @emph{See also}:
5588 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
5594 @section @code{FPUTC} --- Write a single character in stream mode
5596 @cindex write character, stream mode
5597 @cindex stream mode, write character
5598 @cindex file operation, write character
5601 @item @emph{Description}:
5602 Write a single character in stream mode by bypassing normal formatted
5603 output. Stream I/O should not be mixed with normal record-oriented
5604 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
5606 This intrinsic is provided in both subroutine and function forms; however,
5607 only one form can be used in any given program unit.
5609 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
5610 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5611 Programmers should consider the use of new stream IO feature in new code
5612 for future portability. See also @ref{Fortran 2003 status}.
5614 @item @emph{Standard}:
5618 Subroutine, function
5620 @item @emph{Syntax}:
5621 @multitable @columnfractions .80
5622 @item @code{CALL FPUTC(UNIT, C [, STATUS])}
5623 @item @code{STATUS = FPUTC(UNIT, C)}
5626 @item @emph{Arguments}:
5627 @multitable @columnfractions .15 .70
5628 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
5629 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5631 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5632 Returns 0 on success, -1 on end-of-file and a system specific positive
5633 error code otherwise.
5636 @item @emph{Example}:
5639 CHARACTER(len=10) :: str = "gfortran"
5640 INTEGER :: fd = 42, i
5642 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
5643 DO i = 1, len_trim(str)
5644 CALL fputc(fd, str(i:i))
5650 @item @emph{See also}:
5651 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
5657 @section @code{FRACTION} --- Fractional part of the model representation
5659 @cindex real number, fraction
5660 @cindex floating point, fraction
5663 @item @emph{Description}:
5664 @code{FRACTION(X)} returns the fractional part of the model
5665 representation of @code{X}.
5667 @item @emph{Standard}:
5668 Fortran 95 and later
5673 @item @emph{Syntax}:
5674 @code{Y = FRACTION(X)}
5676 @item @emph{Arguments}:
5677 @multitable @columnfractions .15 .70
5678 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
5681 @item @emph{Return value}:
5682 The return value is of the same type and kind as the argument.
5683 The fractional part of the model representation of @code{X} is returned;
5684 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
5686 @item @emph{Example}:
5688 program test_fraction
5691 print *, fraction(x), x * radix(x)**(-exponent(x))
5692 end program test_fraction
5700 @section @code{FREE} --- Frees memory
5702 @cindex pointer, cray
5705 @item @emph{Description}:
5706 Frees memory previously allocated by @code{MALLOC}. The @code{FREE}
5707 intrinsic is an extension intended to be used with Cray pointers, and is
5708 provided in GNU Fortran to allow user to compile legacy code. For
5709 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
5712 @item @emph{Standard}:
5718 @item @emph{Syntax}:
5719 @code{CALL FREE(PTR)}
5721 @item @emph{Arguments}:
5722 @multitable @columnfractions .15 .70
5723 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
5724 location of the memory that should be de-allocated.
5727 @item @emph{Return value}:
5730 @item @emph{Example}:
5731 See @code{MALLOC} for an example.
5733 @item @emph{See also}:
5740 @section @code{FSEEK} --- Low level file positioning subroutine
5742 @cindex file operation, seek
5743 @cindex file operation, position
5746 @item @emph{Description}:
5747 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
5748 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
5749 if set to 1, @var{OFFSET} is taken to be relative to the current position
5750 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
5751 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
5754 This intrinsic routine is not fully backwards compatible with @command{g77}.
5755 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
5756 @var{STATUS} variable. If FSEEK is used in old code, change
5758 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
5763 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
5764 IF (status /= 0) GOTO label
5767 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
5768 Programmers should consider the use of new stream IO feature in new code
5769 for future portability. See also @ref{Fortran 2003 status}.
5771 @item @emph{Standard}:
5777 @item @emph{Syntax}:
5778 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
5780 @item @emph{Arguments}:
5781 @multitable @columnfractions .15 .70
5782 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
5783 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
5784 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
5785 Its value shall be either 0, 1 or 2.
5786 @item @var{STATUS} @tab (Optional) shall be a scalar of type
5790 @item @emph{Example}:
5793 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
5794 INTEGER :: fd, offset, ierr
5800 OPEN(UNIT=fd, FILE="fseek.test")
5801 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
5802 print *, FTELL(fd), ierr
5804 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
5805 print *, FTELL(fd), ierr
5807 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
5808 print *, FTELL(fd), ierr
5814 @item @emph{See also}:
5821 @section @code{FSTAT} --- Get file status
5823 @cindex file system, file status
5826 @item @emph{Description}:
5827 @code{FSTAT} is identical to @ref{STAT}, except that information about an
5828 already opened file is obtained.
5830 The elements in @code{VALUES} are the same as described by @ref{STAT}.
5832 This intrinsic is provided in both subroutine and function forms; however,
5833 only one form can be used in any given program unit.
5835 @item @emph{Standard}:
5839 Subroutine, function
5841 @item @emph{Syntax}:
5842 @multitable @columnfractions .80
5843 @item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
5844 @item @code{STATUS = FSTAT(UNIT, VALUES)}
5847 @item @emph{Arguments}:
5848 @multitable @columnfractions .15 .70
5849 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
5850 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
5851 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
5852 on success and a system specific error code otherwise.
5855 @item @emph{Example}:
5856 See @ref{STAT} for an example.
5858 @item @emph{See also}:
5859 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
5865 @section @code{FTELL} --- Current stream position
5867 @cindex file operation, position
5870 @item @emph{Description}:
5871 Retrieves the current position within an open file.
5873 This intrinsic is provided in both subroutine and function forms; however,
5874 only one form can be used in any given program unit.
5876 @item @emph{Standard}:
5880 Subroutine, function
5882 @item @emph{Syntax}:
5883 @multitable @columnfractions .80
5884 @item @code{CALL FTELL(UNIT, OFFSET)}
5885 @item @code{OFFSET = FTELL(UNIT)}
5888 @item @emph{Arguments}:
5889 @multitable @columnfractions .15 .70
5890 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
5891 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
5894 @item @emph{Return value}:
5895 In either syntax, @var{OFFSET} is set to the current offset of unit
5896 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
5898 @item @emph{Example}:
5902 OPEN(10, FILE="temp.dat")
5908 @item @emph{See also}:
5915 @section @code{GAMMA} --- Gamma function
5918 @cindex Gamma function
5919 @cindex Factorial function
5922 @item @emph{Description}:
5923 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
5924 integer values of @var{X} the Gamma function simplifies to the factorial
5925 function @math{\Gamma(x)=(x-1)!}.
5929 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
5933 @item @emph{Standard}:
5934 Fortran 2008 and later
5939 @item @emph{Syntax}:
5942 @item @emph{Arguments}:
5943 @multitable @columnfractions .15 .70
5944 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
5945 nor a negative integer.
5948 @item @emph{Return value}:
5949 The return value is of type @code{REAL} of the same kind as @var{X}.
5951 @item @emph{Example}:
5955 x = gamma(x) ! returns 1.0
5956 end program test_gamma
5959 @item @emph{Specific names}:
5960 @multitable @columnfractions .20 .20 .20 .25
5961 @item Name @tab Argument @tab Return type @tab Standard
5962 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
5963 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
5966 @item @emph{See also}:
5967 Logarithm of the Gamma function: @ref{LOG_GAMMA}
5974 @section @code{GERROR} --- Get last system error message
5976 @cindex system, error handling
5979 @item @emph{Description}:
5980 Returns the system error message corresponding to the last system error.
5981 This resembles the functionality of @code{strerror(3)} in C.
5983 @item @emph{Standard}:
5989 @item @emph{Syntax}:
5990 @code{CALL GERROR(RESULT)}
5992 @item @emph{Arguments}:
5993 @multitable @columnfractions .15 .70
5994 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
5997 @item @emph{Example}:
6000 CHARACTER(len=100) :: msg
6006 @item @emph{See also}:
6007 @ref{IERRNO}, @ref{PERROR}
6013 @section @code{GETARG} --- Get command line arguments
6015 @cindex command-line arguments
6016 @cindex arguments, to program
6019 @item @emph{Description}:
6020 Retrieve the @var{POS}-th argument that was passed on the
6021 command line when the containing program was invoked.
6023 This intrinsic routine is provided for backwards compatibility with
6024 GNU Fortran 77. In new code, programmers should consider the use of
6025 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
6028 @item @emph{Standard}:
6034 @item @emph{Syntax}:
6035 @code{CALL GETARG(POS, VALUE)}
6037 @item @emph{Arguments}:
6038 @multitable @columnfractions .15 .70
6039 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
6040 the default integer kind; @math{@var{POS} \geq 0}
6041 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
6043 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
6046 @item @emph{Return value}:
6047 After @code{GETARG} returns, the @var{VALUE} argument holds the
6048 @var{POS}th command line argument. If @var{VALUE} can not hold the
6049 argument, it is truncated to fit the length of @var{VALUE}. If there are
6050 less than @var{POS} arguments specified at the command line, @var{VALUE}
6051 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
6052 to the name of the program (on systems that support this feature).
6054 @item @emph{Example}:
6058 CHARACTER(len=32) :: arg
6067 @item @emph{See also}:
6068 GNU Fortran 77 compatibility function: @ref{IARGC}
6070 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
6071 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6077 @section @code{GET_COMMAND} --- Get the entire command line
6078 @fnindex GET_COMMAND
6079 @cindex command-line arguments
6080 @cindex arguments, to program
6083 @item @emph{Description}:
6084 Retrieve the entire command line that was used to invoke the program.
6086 @item @emph{Standard}:
6087 Fortran 2003 and later
6092 @item @emph{Syntax}:
6093 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
6095 @item @emph{Arguments}:
6096 @multitable @columnfractions .15 .70
6097 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
6099 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
6101 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
6105 @item @emph{Return value}:
6106 If @var{COMMAND} is present, stores the entire command line that was used
6107 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
6108 assigned the length of the command line. If @var{STATUS} is present, it
6109 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
6110 short to store the command line, or a positive value in case of an error.
6112 @item @emph{Example}:
6114 PROGRAM test_get_command
6115 CHARACTER(len=255) :: cmd
6116 CALL get_command(cmd)
6117 WRITE (*,*) TRIM(cmd)
6121 @item @emph{See also}:
6122 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6127 @node GET_COMMAND_ARGUMENT
6128 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
6129 @fnindex GET_COMMAND_ARGUMENT
6130 @cindex command-line arguments
6131 @cindex arguments, to program
6134 @item @emph{Description}:
6135 Retrieve the @var{NUMBER}-th argument that was passed on the
6136 command line when the containing program was invoked.
6138 @item @emph{Standard}:
6139 Fortran 2003 and later
6144 @item @emph{Syntax}:
6145 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
6147 @item @emph{Arguments}:
6148 @multitable @columnfractions .15 .70
6149 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
6150 default kind, @math{@var{NUMBER} \geq 0}
6151 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
6152 and of default kind.
6153 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6154 and of default kind.
6155 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6156 and of default kind.
6159 @item @emph{Return value}:
6160 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
6161 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
6162 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
6163 arguments specified at the command line, @var{VALUE} will be filled with blanks.
6164 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
6165 systems that support this feature). The @var{LENGTH} argument contains the
6166 length of the @var{NUMBER}-th command line argument. If the argument retrieval
6167 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
6168 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
6171 @item @emph{Example}:
6173 PROGRAM test_get_command_argument
6175 CHARACTER(len=32) :: arg
6179 CALL get_command_argument(i, arg)
6180 IF (LEN_TRIM(arg) == 0) EXIT
6182 WRITE (*,*) TRIM(arg)
6188 @item @emph{See also}:
6189 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
6195 @section @code{GETCWD} --- Get current working directory
6197 @cindex system, working directory
6200 @item @emph{Description}:
6201 Get current working directory.
6203 This intrinsic is provided in both subroutine and function forms; however,
6204 only one form can be used in any given program unit.
6206 @item @emph{Standard}:
6210 Subroutine, function
6212 @item @emph{Syntax}:
6213 @multitable @columnfractions .80
6214 @item @code{CALL GETCWD(C [, STATUS])}
6215 @item @code{STATUS = GETCWD(C)}
6218 @item @emph{Arguments}:
6219 @multitable @columnfractions .15 .70
6220 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
6221 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
6222 a system specific and nonzero error code otherwise.
6225 @item @emph{Example}:
6228 CHARACTER(len=255) :: cwd
6230 WRITE(*,*) TRIM(cwd)
6234 @item @emph{See also}:
6241 @section @code{GETENV} --- Get an environmental variable
6243 @cindex environment variable
6246 @item @emph{Description}:
6247 Get the @var{VALUE} of the environmental variable @var{NAME}.
6249 This intrinsic routine is provided for backwards compatibility with
6250 GNU Fortran 77. In new code, programmers should consider the use of
6251 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
6254 Note that @code{GETENV} need not be thread-safe. It is the
6255 responsibility of the user to ensure that the environment is not being
6256 updated concurrently with a call to the @code{GETENV} intrinsic.
6258 @item @emph{Standard}:
6264 @item @emph{Syntax}:
6265 @code{CALL GETENV(NAME, VALUE)}
6267 @item @emph{Arguments}:
6268 @multitable @columnfractions .15 .70
6269 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
6270 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
6273 @item @emph{Return value}:
6274 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
6275 not large enough to hold the data, it is truncated. If @var{NAME}
6276 is not set, @var{VALUE} will be filled with blanks.
6278 @item @emph{Example}:
6281 CHARACTER(len=255) :: homedir
6282 CALL getenv("HOME", homedir)
6283 WRITE (*,*) TRIM(homedir)
6287 @item @emph{See also}:
6288 @ref{GET_ENVIRONMENT_VARIABLE}
6293 @node GET_ENVIRONMENT_VARIABLE
6294 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
6295 @fnindex GET_ENVIRONMENT_VARIABLE
6296 @cindex environment variable
6299 @item @emph{Description}:
6300 Get the @var{VALUE} of the environmental variable @var{NAME}.
6302 Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It
6303 is the responsibility of the user to ensure that the environment is
6304 not being updated concurrently with a call to the
6305 @code{GET_ENVIRONMENT_VARIABLE} intrinsic.
6307 @item @emph{Standard}:
6308 Fortran 2003 and later
6313 @item @emph{Syntax}:
6314 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
6316 @item @emph{Arguments}:
6317 @multitable @columnfractions .15 .70
6318 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
6319 and of default kind.
6320 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
6321 and of default kind.
6322 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6323 and of default kind.
6324 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6325 and of default kind.
6326 @item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL}
6327 and of default kind.
6330 @item @emph{Return value}:
6331 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
6332 not large enough to hold the data, it is truncated. If @var{NAME}
6333 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
6334 contains the length needed for storing the environment variable @var{NAME}
6335 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
6336 but too short for the environment variable; it is 1 if the environment
6337 variable does not exist and 2 if the processor does not support environment
6338 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
6339 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
6340 are significant; otherwise they are not part of the environment variable
6343 @item @emph{Example}:
6346 CHARACTER(len=255) :: homedir
6347 CALL get_environment_variable("HOME", homedir)
6348 WRITE (*,*) TRIM(homedir)
6356 @section @code{GETGID} --- Group ID function
6358 @cindex system, group ID
6361 @item @emph{Description}:
6362 Returns the numerical group ID of the current process.
6364 @item @emph{Standard}:
6370 @item @emph{Syntax}:
6371 @code{RESULT = GETGID()}
6373 @item @emph{Return value}:
6374 The return value of @code{GETGID} is an @code{INTEGER} of the default
6378 @item @emph{Example}:
6379 See @code{GETPID} for an example.
6381 @item @emph{See also}:
6382 @ref{GETPID}, @ref{GETUID}
6388 @section @code{GETLOG} --- Get login name
6390 @cindex system, login name
6394 @item @emph{Description}:
6395 Gets the username under which the program is running.
6397 @item @emph{Standard}:
6403 @item @emph{Syntax}:
6404 @code{CALL GETLOG(C)}
6406 @item @emph{Arguments}:
6407 @multitable @columnfractions .15 .70
6408 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
6411 @item @emph{Return value}:
6412 Stores the current user name in @var{LOGIN}. (On systems where POSIX
6413 functions @code{geteuid} and @code{getpwuid} are not available, and
6414 the @code{getlogin} function is not implemented either, this will
6415 return a blank string.)
6417 @item @emph{Example}:
6420 CHARACTER(32) :: login
6426 @item @emph{See also}:
6433 @section @code{GETPID} --- Process ID function
6435 @cindex system, process ID
6439 @item @emph{Description}:
6440 Returns the numerical process identifier of the current process.
6442 @item @emph{Standard}:
6448 @item @emph{Syntax}:
6449 @code{RESULT = GETPID()}
6451 @item @emph{Return value}:
6452 The return value of @code{GETPID} is an @code{INTEGER} of the default
6456 @item @emph{Example}:
6459 print *, "The current process ID is ", getpid()
6460 print *, "Your numerical user ID is ", getuid()
6461 print *, "Your numerical group ID is ", getgid()
6465 @item @emph{See also}:
6466 @ref{GETGID}, @ref{GETUID}
6472 @section @code{GETUID} --- User ID function
6474 @cindex system, user ID
6478 @item @emph{Description}:
6479 Returns the numerical user ID of the current process.
6481 @item @emph{Standard}:
6487 @item @emph{Syntax}:
6488 @code{RESULT = GETUID()}
6490 @item @emph{Return value}:
6491 The return value of @code{GETUID} is an @code{INTEGER} of the default
6495 @item @emph{Example}:
6496 See @code{GETPID} for an example.
6498 @item @emph{See also}:
6499 @ref{GETPID}, @ref{GETLOG}
6505 @section @code{GMTIME} --- Convert time to GMT info
6507 @cindex time, conversion to GMT info
6510 @item @emph{Description}:
6511 Given a system time value @var{TIME} (as provided by the @code{TIME8}
6512 intrinsic), fills @var{VALUES} with values extracted from it appropriate
6513 to the UTC time zone (Universal Coordinated Time, also known in some
6514 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
6516 @item @emph{Standard}:
6522 @item @emph{Syntax}:
6523 @code{CALL GMTIME(TIME, VALUES)}
6525 @item @emph{Arguments}:
6526 @multitable @columnfractions .15 .70
6527 @item @var{TIME} @tab An @code{INTEGER} scalar expression
6528 corresponding to a system time, with @code{INTENT(IN)}.
6529 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
6530 with @code{INTENT(OUT)}.
6533 @item @emph{Return value}:
6534 The elements of @var{VALUES} are assigned as follows:
6536 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
6538 @item Minutes after the hour, range 0--59
6539 @item Hours past midnight, range 0--23
6540 @item Day of month, range 0--31
6541 @item Number of months since January, range 0--12
6542 @item Years since 1900
6543 @item Number of days since Sunday, range 0--6
6544 @item Days since January 1
6545 @item Daylight savings indicator: positive if daylight savings is in
6546 effect, zero if not, and negative if the information is not available.
6549 @item @emph{See also}:
6550 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
6557 @section @code{HOSTNM} --- Get system host name
6559 @cindex system, host name
6562 @item @emph{Description}:
6563 Retrieves the host name of the system on which the program is running.
6565 This intrinsic is provided in both subroutine and function forms; however,
6566 only one form can be used in any given program unit.
6568 @item @emph{Standard}:
6572 Subroutine, function
6574 @item @emph{Syntax}:
6575 @multitable @columnfractions .80
6576 @item @code{CALL HOSTNM(C [, STATUS])}
6577 @item @code{STATUS = HOSTNM(NAME)}
6580 @item @emph{Arguments}:
6581 @multitable @columnfractions .15 .70
6582 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
6583 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6584 Returns 0 on success, or a system specific error code otherwise.
6587 @item @emph{Return value}:
6588 In either syntax, @var{NAME} is set to the current hostname if it can
6589 be obtained, or to a blank string otherwise.
6596 @section @code{HUGE} --- Largest number of a kind
6598 @cindex limits, largest number
6599 @cindex model representation, largest number
6602 @item @emph{Description}:
6603 @code{HUGE(X)} returns the largest number that is not an infinity in
6604 the model of the type of @code{X}.
6606 @item @emph{Standard}:
6607 Fortran 95 and later
6612 @item @emph{Syntax}:
6613 @code{RESULT = HUGE(X)}
6615 @item @emph{Arguments}:
6616 @multitable @columnfractions .15 .70
6617 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
6620 @item @emph{Return value}:
6621 The return value is of the same type and kind as @var{X}
6623 @item @emph{Example}:
6625 program test_huge_tiny
6626 print *, huge(0), huge(0.0), huge(0.0d0)
6627 print *, tiny(0.0), tiny(0.0d0)
6628 end program test_huge_tiny
6635 @section @code{HYPOT} --- Euclidean distance function
6637 @cindex Euclidean distance
6640 @item @emph{Description}:
6641 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
6642 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
6644 @item @emph{Standard}:
6645 Fortran 2008 and later
6650 @item @emph{Syntax}:
6651 @code{RESULT = HYPOT(X, Y)}
6653 @item @emph{Arguments}:
6654 @multitable @columnfractions .15 .70
6655 @item @var{X} @tab The type shall be @code{REAL}.
6656 @item @var{Y} @tab The type and kind type parameter shall be the same as
6660 @item @emph{Return value}:
6661 The return value has the same type and kind type parameter as @var{X}.
6663 @item @emph{Example}:
6666 real(4) :: x = 1.e0_4, y = 0.5e0_4
6668 end program test_hypot
6675 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
6677 @cindex @acronym{ASCII} collating sequence
6678 @cindex collating sequence, @acronym{ASCII}
6679 @cindex conversion, to integer
6682 @item @emph{Description}:
6683 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
6684 in the first character position of @code{C}.
6686 @item @emph{Standard}:
6687 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6692 @item @emph{Syntax}:
6693 @code{RESULT = IACHAR(C [, KIND])}
6695 @item @emph{Arguments}:
6696 @multitable @columnfractions .15 .70
6697 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
6698 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6699 expression indicating the kind parameter of the result.
6702 @item @emph{Return value}:
6703 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6704 @var{KIND} is absent, the return value is of default integer kind.
6706 @item @emph{Example}:
6711 end program test_iachar
6715 See @ref{ICHAR} for a discussion of converting between numerical values
6716 and formatted string representations.
6718 @item @emph{See also}:
6719 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
6726 @section @code{IALL} --- Bitwise AND of array elements
6729 @cindex bits, AND of array elements
6732 @item @emph{Description}:
6733 Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
6734 if the corresponding element in @var{MASK} is @code{TRUE}.
6736 @item @emph{Standard}:
6737 Fortran 2008 and later
6740 Transformational function
6742 @item @emph{Syntax}:
6743 @multitable @columnfractions .80
6744 @item @code{RESULT = IALL(ARRAY[, MASK])}
6745 @item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
6748 @item @emph{Arguments}:
6749 @multitable @columnfractions .15 .70
6750 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6751 @item @var{DIM} @tab (Optional) shall be a scalar of type
6752 @code{INTEGER} with a value in the range from 1 to n, where n
6753 equals the rank of @var{ARRAY}.
6754 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
6755 and either be a scalar or an array of the same shape as @var{ARRAY}.
6758 @item @emph{Return value}:
6759 The result is of the same type as @var{ARRAY}.
6761 If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
6762 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6763 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6764 dimension @var{DIM} dropped is returned.
6766 @item @emph{Example}:
6775 PRINT '(b8.8)', IALL(a)
6779 @item @emph{See also}:
6780 @ref{IANY}, @ref{IPARITY}, @ref{IAND}
6786 @section @code{IAND} --- Bitwise logical and
6788 @cindex bitwise logical and
6789 @cindex logical and, bitwise
6792 @item @emph{Description}:
6793 Bitwise logical @code{AND}.
6795 @item @emph{Standard}:
6796 Fortran 95 and later
6801 @item @emph{Syntax}:
6802 @code{RESULT = IAND(I, J)}
6804 @item @emph{Arguments}:
6805 @multitable @columnfractions .15 .70
6806 @item @var{I} @tab The type shall be @code{INTEGER}.
6807 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6808 kind as @var{I}. (As a GNU extension, different kinds are also
6812 @item @emph{Return value}:
6813 The return type is @code{INTEGER}, of the same kind as the
6814 arguments. (If the argument kinds differ, it is of the same kind as
6815 the larger argument.)
6817 @item @emph{Example}:
6821 DATA a / Z'F' /, b / Z'3' /
6822 WRITE (*,*) IAND(a, b)
6826 @item @emph{See also}:
6827 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6834 @section @code{IANY} --- Bitwise OR of array elements
6837 @cindex bits, OR of array elements
6840 @item @emph{Description}:
6841 Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
6842 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
6844 @item @emph{Standard}:
6845 Fortran 2008 and later
6848 Transformational function
6850 @item @emph{Syntax}:
6851 @multitable @columnfractions .80
6852 @item @code{RESULT = IANY(ARRAY[, MASK])}
6853 @item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
6856 @item @emph{Arguments}:
6857 @multitable @columnfractions .15 .70
6858 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6859 @item @var{DIM} @tab (Optional) shall be a scalar of type
6860 @code{INTEGER} with a value in the range from 1 to n, where n
6861 equals the rank of @var{ARRAY}.
6862 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
6863 and either be a scalar or an array of the same shape as @var{ARRAY}.
6866 @item @emph{Return value}:
6867 The result is of the same type as @var{ARRAY}.
6869 If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
6870 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6871 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6872 dimension @var{DIM} dropped is returned.
6874 @item @emph{Example}:
6883 PRINT '(b8.8)', IANY(a)
6887 @item @emph{See also}:
6888 @ref{IPARITY}, @ref{IALL}, @ref{IOR}
6894 @section @code{IARGC} --- Get the number of command line arguments
6896 @cindex command-line arguments
6897 @cindex command-line arguments, number of
6898 @cindex arguments, to program
6901 @item @emph{Description}:
6902 @code{IARGC} returns the number of arguments passed on the
6903 command line when the containing program was invoked.
6905 This intrinsic routine is provided for backwards compatibility with
6906 GNU Fortran 77. In new code, programmers should consider the use of
6907 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
6910 @item @emph{Standard}:
6916 @item @emph{Syntax}:
6917 @code{RESULT = IARGC()}
6919 @item @emph{Arguments}:
6922 @item @emph{Return value}:
6923 The number of command line arguments, type @code{INTEGER(4)}.
6925 @item @emph{Example}:
6928 @item @emph{See also}:
6929 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
6931 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
6932 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6938 @section @code{IBCLR} --- Clear bit
6944 @item @emph{Description}:
6945 @code{IBCLR} returns the value of @var{I} with the bit at position
6946 @var{POS} set to zero.
6948 @item @emph{Standard}:
6949 Fortran 95 and later
6954 @item @emph{Syntax}:
6955 @code{RESULT = IBCLR(I, POS)}
6957 @item @emph{Arguments}:
6958 @multitable @columnfractions .15 .70
6959 @item @var{I} @tab The type shall be @code{INTEGER}.
6960 @item @var{POS} @tab The type shall be @code{INTEGER}.
6963 @item @emph{Return value}:
6964 The return value is of type @code{INTEGER} and of the same kind as
6967 @item @emph{See also}:
6968 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
6975 @section @code{IBITS} --- Bit extraction
6978 @cindex bits, extract
6981 @item @emph{Description}:
6982 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
6983 starting from bit position @var{POS} and extending left for @var{LEN}
6984 bits. The result is right-justified and the remaining bits are
6985 zeroed. The value of @code{POS+LEN} must be less than or equal to the
6986 value @code{BIT_SIZE(I)}.
6988 @item @emph{Standard}:
6989 Fortran 95 and later
6994 @item @emph{Syntax}:
6995 @code{RESULT = IBITS(I, POS, LEN)}
6997 @item @emph{Arguments}:
6998 @multitable @columnfractions .15 .70
6999 @item @var{I} @tab The type shall be @code{INTEGER}.
7000 @item @var{POS} @tab The type shall be @code{INTEGER}.
7001 @item @var{LEN} @tab The type shall be @code{INTEGER}.
7004 @item @emph{Return value}:
7005 The return value is of type @code{INTEGER} and of the same kind as
7008 @item @emph{See also}:
7009 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
7015 @section @code{IBSET} --- Set bit
7020 @item @emph{Description}:
7021 @code{IBSET} returns the value of @var{I} with the bit at position
7022 @var{POS} set to one.
7024 @item @emph{Standard}:
7025 Fortran 95 and later
7030 @item @emph{Syntax}:
7031 @code{RESULT = IBSET(I, POS)}
7033 @item @emph{Arguments}:
7034 @multitable @columnfractions .15 .70
7035 @item @var{I} @tab The type shall be @code{INTEGER}.
7036 @item @var{POS} @tab The type shall be @code{INTEGER}.
7039 @item @emph{Return value}:
7040 The return value is of type @code{INTEGER} and of the same kind as
7043 @item @emph{See also}:
7044 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
7051 @section @code{ICHAR} --- Character-to-integer conversion function
7053 @cindex conversion, to integer
7056 @item @emph{Description}:
7057 @code{ICHAR(C)} returns the code for the character in the first character
7058 position of @code{C} in the system's native character set.
7059 The correspondence between characters and their codes is not necessarily
7060 the same across different GNU Fortran implementations.
7062 @item @emph{Standard}:
7063 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7068 @item @emph{Syntax}:
7069 @code{RESULT = ICHAR(C [, KIND])}
7071 @item @emph{Arguments}:
7072 @multitable @columnfractions .15 .70
7073 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
7074 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7075 expression indicating the kind parameter of the result.
7078 @item @emph{Return value}:
7079 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7080 @var{KIND} is absent, the return value is of default integer kind.
7082 @item @emph{Example}:
7087 end program test_ichar
7090 @item @emph{Specific names}:
7091 @multitable @columnfractions .20 .20 .20 .25
7092 @item Name @tab Argument @tab Return type @tab Standard
7093 @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7097 No intrinsic exists to convert between a numeric value and a formatted
7098 character string representation -- for instance, given the
7099 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
7100 @code{REAL} value with the value 154, or vice versa. Instead, this
7101 functionality is provided by internal-file I/O, as in the following
7106 character(len=10) string, string2
7109 ! Convert a string to a numeric value
7110 read (string,'(I10)') value
7113 ! Convert a value to a formatted string
7114 write (string2,'(I10)') value
7116 end program read_val
7119 @item @emph{See also}:
7120 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
7127 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
7129 @cindex date, current
7130 @cindex current date
7133 @item @emph{Description}:
7134 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
7135 current local time. The day (in the range 1-31), month (in the range 1-12),
7136 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
7137 The year has four significant digits.
7139 @item @emph{Standard}:
7145 @item @emph{Syntax}:
7146 @code{CALL IDATE(VALUES)}
7148 @item @emph{Arguments}:
7149 @multitable @columnfractions .15 .70
7150 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
7151 the kind shall be the default integer kind.
7154 @item @emph{Return value}:
7155 Does not return anything.
7157 @item @emph{Example}:
7160 integer, dimension(3) :: tarray
7165 end program test_idate
7172 @section @code{IEOR} --- Bitwise logical exclusive or
7174 @cindex bitwise logical exclusive or
7175 @cindex logical exclusive or, bitwise
7178 @item @emph{Description}:
7179 @code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
7182 @item @emph{Standard}:
7183 Fortran 95 and later
7188 @item @emph{Syntax}:
7189 @code{RESULT = IEOR(I, J)}
7191 @item @emph{Arguments}:
7192 @multitable @columnfractions .15 .70
7193 @item @var{I} @tab The type shall be @code{INTEGER}.
7194 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
7195 kind as @var{I}. (As a GNU extension, different kinds are also
7199 @item @emph{Return value}:
7200 The return type is @code{INTEGER}, of the same kind as the
7201 arguments. (If the argument kinds differ, it is of the same kind as
7202 the larger argument.)
7204 @item @emph{See also}:
7205 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
7211 @section @code{IERRNO} --- Get the last system error number
7213 @cindex system, error handling
7216 @item @emph{Description}:
7217 Returns the last system error number, as given by the C @code{errno}
7220 @item @emph{Standard}:
7226 @item @emph{Syntax}:
7227 @code{RESULT = IERRNO()}
7229 @item @emph{Arguments}:
7232 @item @emph{Return value}:
7233 The return value is of type @code{INTEGER} and of the default integer
7236 @item @emph{See also}:
7243 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
7244 @fnindex IMAGE_INDEX
7245 @cindex coarray, @code{IMAGE_INDEX}
7246 @cindex images, cosubscript to image index conversion
7249 @item @emph{Description}:
7250 Returns the image index belonging to a cosubscript.
7252 @item @emph{Standard}:
7253 Fortran 2008 and later
7258 @item @emph{Syntax}:
7259 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
7261 @item @emph{Arguments}: None.
7262 @multitable @columnfractions .15 .70
7263 @item @var{COARRAY} @tab Coarray of any type.
7264 @item @var{SUB} @tab default integer rank-1 array of a size equal to
7265 the corank of @var{COARRAY}.
7269 @item @emph{Return value}:
7270 Scalar default integer with the value of the image index which corresponds
7271 to the cosubscripts. For invalid cosubscripts the result is zero.
7273 @item @emph{Example}:
7275 INTEGER :: array[2,-1:4,8,*]
7276 ! Writes 28 (or 0 if there are fewer than 28 images)
7277 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
7280 @item @emph{See also}:
7281 @ref{THIS_IMAGE}, @ref{NUM_IMAGES}
7286 @node INDEX intrinsic
7287 @section @code{INDEX} --- Position of a substring within a string
7289 @cindex substring position
7290 @cindex string, find substring
7293 @item @emph{Description}:
7294 Returns the position of the start of the first occurrence of string
7295 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
7296 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
7297 the @var{BACK} argument is present and true, the return value is the
7298 start of the last occurrence rather than the first.
7300 @item @emph{Standard}:
7301 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
7306 @item @emph{Syntax}:
7307 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
7309 @item @emph{Arguments}:
7310 @multitable @columnfractions .15 .70
7311 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
7313 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
7315 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
7317 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7318 expression indicating the kind parameter of the result.
7321 @item @emph{Return value}:
7322 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7323 @var{KIND} is absent, the return value is of default integer kind.
7325 @item @emph{Specific names}:
7326 @multitable @columnfractions .20 .20 .20 .25
7327 @item Name @tab Argument @tab Return type @tab Standard
7328 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7331 @item @emph{See also}:
7332 @ref{SCAN}, @ref{VERIFY}
7338 @section @code{INT} --- Convert to integer type
7342 @cindex conversion, to integer
7345 @item @emph{Description}:
7346 Convert to integer type
7348 @item @emph{Standard}:
7349 Fortran 77 and later
7354 @item @emph{Syntax}:
7355 @code{RESULT = INT(A [, KIND))}
7357 @item @emph{Arguments}:
7358 @multitable @columnfractions .15 .70
7359 @item @var{A} @tab Shall be of type @code{INTEGER},
7360 @code{REAL}, or @code{COMPLEX}.
7361 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7362 expression indicating the kind parameter of the result.
7365 @item @emph{Return value}:
7366 These functions return a @code{INTEGER} variable or array under
7367 the following rules:
7371 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
7373 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
7374 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
7375 the range of @var{A} and whose sign is the same as the sign of @var{A}.
7377 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
7380 @item @emph{Example}:
7384 complex :: z = (-3.7, 1.0)
7386 print *, int(z), int(z,8)
7390 @item @emph{Specific names}:
7391 @multitable @columnfractions .20 .20 .20 .25
7392 @item Name @tab Argument @tab Return type @tab Standard
7393 @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
7394 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
7395 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
7402 @section @code{INT2} --- Convert to 16-bit integer type
7405 @cindex conversion, to integer
7408 @item @emph{Description}:
7409 Convert to a @code{KIND=2} integer type. This is equivalent to the
7410 standard @code{INT} intrinsic with an optional argument of
7411 @code{KIND=2}, and is only included for backwards compatibility.
7413 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
7415 @item @emph{Standard}:
7421 @item @emph{Syntax}:
7422 @code{RESULT = INT2(A)}
7424 @item @emph{Arguments}:
7425 @multitable @columnfractions .15 .70
7426 @item @var{A} @tab Shall be of type @code{INTEGER},
7427 @code{REAL}, or @code{COMPLEX}.
7430 @item @emph{Return value}:
7431 The return value is a @code{INTEGER(2)} variable.
7433 @item @emph{See also}:
7434 @ref{INT}, @ref{INT8}, @ref{LONG}
7440 @section @code{INT8} --- Convert to 64-bit integer type
7442 @cindex conversion, to integer
7445 @item @emph{Description}:
7446 Convert to a @code{KIND=8} integer type. This is equivalent to the
7447 standard @code{INT} intrinsic with an optional argument of
7448 @code{KIND=8}, and is only included for backwards compatibility.
7450 @item @emph{Standard}:
7456 @item @emph{Syntax}:
7457 @code{RESULT = INT8(A)}
7459 @item @emph{Arguments}:
7460 @multitable @columnfractions .15 .70
7461 @item @var{A} @tab Shall be of type @code{INTEGER},
7462 @code{REAL}, or @code{COMPLEX}.
7465 @item @emph{Return value}:
7466 The return value is a @code{INTEGER(8)} variable.
7468 @item @emph{See also}:
7469 @ref{INT}, @ref{INT2}, @ref{LONG}
7475 @section @code{IOR} --- Bitwise logical or
7477 @cindex bitwise logical or
7478 @cindex logical or, bitwise
7481 @item @emph{Description}:
7482 @code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
7485 @item @emph{Standard}:
7486 Fortran 95 and later
7491 @item @emph{Syntax}:
7492 @code{RESULT = IOR(I, J)}
7494 @item @emph{Arguments}:
7495 @multitable @columnfractions .15 .70
7496 @item @var{I} @tab The type shall be @code{INTEGER}.
7497 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
7498 kind as @var{I}. (As a GNU extension, different kinds are also
7502 @item @emph{Return value}:
7503 The return type is @code{INTEGER}, of the same kind as the
7504 arguments. (If the argument kinds differ, it is of the same kind as
7505 the larger argument.)
7507 @item @emph{See also}:
7508 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
7514 @section @code{IPARITY} --- Bitwise XOR of array elements
7516 @cindex array, parity
7518 @cindex bits, XOR of array elements
7521 @item @emph{Description}:
7522 Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
7523 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
7525 @item @emph{Standard}:
7526 Fortran 2008 and later
7529 Transformational function
7531 @item @emph{Syntax}:
7532 @multitable @columnfractions .80
7533 @item @code{RESULT = IPARITY(ARRAY[, MASK])}
7534 @item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
7537 @item @emph{Arguments}:
7538 @multitable @columnfractions .15 .70
7539 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7540 @item @var{DIM} @tab (Optional) shall be a scalar of type
7541 @code{INTEGER} with a value in the range from 1 to n, where n
7542 equals the rank of @var{ARRAY}.
7543 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
7544 and either be a scalar or an array of the same shape as @var{ARRAY}.
7547 @item @emph{Return value}:
7548 The result is of the same type as @var{ARRAY}.
7550 If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
7551 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7552 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7553 dimension @var{DIM} dropped is returned.
7555 @item @emph{Example}:
7557 PROGRAM test_iparity
7564 PRINT '(b8.8)', IPARITY(a)
7568 @item @emph{See also}:
7569 @ref{IANY}, @ref{IALL}, @ref{IEOR}, @ref{PARITY}
7575 @section @code{IRAND} --- Integer pseudo-random number
7577 @cindex random number generation
7580 @item @emph{Description}:
7581 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
7582 distribution between 0 and a system-dependent limit (which is in most
7583 cases 2147483647). If @var{FLAG} is 0, the next number
7584 in the current sequence is returned; if @var{FLAG} is 1, the generator
7585 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
7586 it is used as a new seed with @code{SRAND}.
7588 This intrinsic routine is provided for backwards compatibility with
7589 GNU Fortran 77. It implements a simple modulo generator as provided
7590 by @command{g77}. For new code, one should consider the use of
7591 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
7593 @item @emph{Standard}:
7599 @item @emph{Syntax}:
7600 @code{RESULT = IRAND(I)}
7602 @item @emph{Arguments}:
7603 @multitable @columnfractions .15 .70
7604 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
7607 @item @emph{Return value}:
7608 The return value is of @code{INTEGER(kind=4)} type.
7610 @item @emph{Example}:
7613 integer,parameter :: seed = 86456
7616 print *, irand(), irand(), irand(), irand()
7617 print *, irand(seed), irand(), irand(), irand()
7618 end program test_irand
7626 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
7627 @fnindex IS_IOSTAT_END
7628 @cindex @code{IOSTAT}, end of file
7631 @item @emph{Description}:
7632 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
7633 status ``end of file''. The function is equivalent to comparing the variable
7634 with the @code{IOSTAT_END} parameter of the intrinsic module
7635 @code{ISO_FORTRAN_ENV}.
7637 @item @emph{Standard}:
7638 Fortran 2003 and later
7643 @item @emph{Syntax}:
7644 @code{RESULT = IS_IOSTAT_END(I)}
7646 @item @emph{Arguments}:
7647 @multitable @columnfractions .15 .70
7648 @item @var{I} @tab Shall be of the type @code{INTEGER}.
7651 @item @emph{Return value}:
7652 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
7653 @var{I} has the value which indicates an end of file condition for
7654 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
7656 @item @emph{Example}:
7661 OPEN(88, FILE='test.dat')
7662 READ(88, *, IOSTAT=stat) i
7663 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
7671 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
7672 @fnindex IS_IOSTAT_EOR
7673 @cindex @code{IOSTAT}, end of record
7676 @item @emph{Description}:
7677 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
7678 status ``end of record''. The function is equivalent to comparing the
7679 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
7680 @code{ISO_FORTRAN_ENV}.
7682 @item @emph{Standard}:
7683 Fortran 2003 and later
7688 @item @emph{Syntax}:
7689 @code{RESULT = IS_IOSTAT_EOR(I)}
7691 @item @emph{Arguments}:
7692 @multitable @columnfractions .15 .70
7693 @item @var{I} @tab Shall be of the type @code{INTEGER}.
7696 @item @emph{Return value}:
7697 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
7698 @var{I} has the value which indicates an end of file condition for
7699 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
7701 @item @emph{Example}:
7705 INTEGER :: stat, i(50)
7706 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
7707 READ(88, IOSTAT=stat) i
7708 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
7716 @section @code{ISATTY} --- Whether a unit is a terminal device.
7718 @cindex system, terminal
7721 @item @emph{Description}:
7722 Determine whether a unit is connected to a terminal device.
7724 @item @emph{Standard}:
7730 @item @emph{Syntax}:
7731 @code{RESULT = ISATTY(UNIT)}
7733 @item @emph{Arguments}:
7734 @multitable @columnfractions .15 .70
7735 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
7738 @item @emph{Return value}:
7739 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
7740 device, @code{.FALSE.} otherwise.
7742 @item @emph{Example}:
7745 INTEGER(kind=1) :: unit
7747 write(*,*) isatty(unit=unit)
7751 @item @emph{See also}:
7758 @section @code{ISHFT} --- Shift bits
7763 @item @emph{Description}:
7764 @code{ISHFT} returns a value corresponding to @var{I} with all of the
7765 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
7766 zero corresponds to a left shift, a value of zero corresponds to no
7767 shift, and a value less than zero corresponds to a right shift. If the
7768 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
7769 value is undefined. Bits shifted out from the left end or right end are
7770 lost; zeros are shifted in from the opposite end.
7772 @item @emph{Standard}:
7773 Fortran 95 and later
7778 @item @emph{Syntax}:
7779 @code{RESULT = ISHFT(I, SHIFT)}
7781 @item @emph{Arguments}:
7782 @multitable @columnfractions .15 .70
7783 @item @var{I} @tab The type shall be @code{INTEGER}.
7784 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7787 @item @emph{Return value}:
7788 The return value is of type @code{INTEGER} and of the same kind as
7791 @item @emph{See also}:
7798 @section @code{ISHFTC} --- Shift bits circularly
7800 @cindex bits, shift circular
7803 @item @emph{Description}:
7804 @code{ISHFTC} returns a value corresponding to @var{I} with the
7805 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
7806 is, bits shifted out one end are shifted into the opposite end. A value
7807 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
7808 zero corresponds to no shift, and a value less than zero corresponds to
7809 a right shift. The absolute value of @var{SHIFT} must be less than
7810 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
7811 equivalent to @code{BIT_SIZE(I)}.
7813 @item @emph{Standard}:
7814 Fortran 95 and later
7819 @item @emph{Syntax}:
7820 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
7822 @item @emph{Arguments}:
7823 @multitable @columnfractions .15 .70
7824 @item @var{I} @tab The type shall be @code{INTEGER}.
7825 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7826 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
7827 the value must be greater than zero and less than or equal to
7831 @item @emph{Return value}:
7832 The return value is of type @code{INTEGER} and of the same kind as
7835 @item @emph{See also}:
7842 @section @code{ISNAN} --- Test for a NaN
7847 @item @emph{Description}:
7848 @code{ISNAN} tests whether a floating-point value is an IEEE
7850 @item @emph{Standard}:
7856 @item @emph{Syntax}:
7859 @item @emph{Arguments}:
7860 @multitable @columnfractions .15 .70
7861 @item @var{X} @tab Variable of the type @code{REAL}.
7865 @item @emph{Return value}:
7866 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
7867 if @var{X} is a NaN and @code{FALSE} otherwise.
7869 @item @emph{Example}:
7876 if (isnan(x)) stop '"x" is a NaN'
7877 end program test_nan
7884 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
7886 @cindex time, current
7887 @cindex current time
7890 @item @emph{Description}:
7891 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
7892 current local time. The hour (in the range 1-24), minute (in the range 1-60),
7893 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
7896 @item @emph{Standard}:
7902 @item @emph{Syntax}:
7903 @code{CALL ITIME(VALUES)}
7905 @item @emph{Arguments}:
7906 @multitable @columnfractions .15 .70
7907 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
7908 and the kind shall be the default integer kind.
7911 @item @emph{Return value}:
7912 Does not return anything.
7915 @item @emph{Example}:
7918 integer, dimension(3) :: tarray
7923 end program test_itime
7930 @section @code{KILL} --- Send a signal to a process
7934 @item @emph{Description}:
7935 @item @emph{Standard}:
7936 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
7939 This intrinsic is provided in both subroutine and function forms; however,
7940 only one form can be used in any given program unit.
7943 Subroutine, function
7945 @item @emph{Syntax}:
7946 @multitable @columnfractions .80
7947 @item @code{CALL KILL(C, VALUE [, STATUS])}
7948 @item @code{STATUS = KILL(C, VALUE)}
7951 @item @emph{Arguments}:
7952 @multitable @columnfractions .15 .70
7953 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
7955 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
7957 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
7958 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
7962 @item @emph{See also}:
7963 @ref{ABORT}, @ref{EXIT}
7969 @section @code{KIND} --- Kind of an entity
7974 @item @emph{Description}:
7975 @code{KIND(X)} returns the kind value of the entity @var{X}.
7977 @item @emph{Standard}:
7978 Fortran 95 and later
7983 @item @emph{Syntax}:
7986 @item @emph{Arguments}:
7987 @multitable @columnfractions .15 .70
7988 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
7989 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
7992 @item @emph{Return value}:
7993 The return value is a scalar of type @code{INTEGER} and of the default
7996 @item @emph{Example}:
7999 integer,parameter :: kc = kind(' ')
8000 integer,parameter :: kl = kind(.true.)
8002 print *, "The default character kind is ", kc
8003 print *, "The default logical kind is ", kl
8004 end program test_kind
8012 @section @code{LBOUND} --- Lower dimension bounds of an array
8014 @cindex array, lower bound
8017 @item @emph{Description}:
8018 Returns the lower bounds of an array, or a single lower bound
8019 along the @var{DIM} dimension.
8020 @item @emph{Standard}:
8021 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
8026 @item @emph{Syntax}:
8027 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
8029 @item @emph{Arguments}:
8030 @multitable @columnfractions .15 .70
8031 @item @var{ARRAY} @tab Shall be an array, of any type.
8032 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
8033 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8034 expression indicating the kind parameter of the result.
8037 @item @emph{Return value}:
8038 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8039 @var{KIND} is absent, the return value is of default integer kind.
8040 If @var{DIM} is absent, the result is an array of the lower bounds of
8041 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
8042 corresponding to the lower bound of the array along that dimension. If
8043 @var{ARRAY} is an expression rather than a whole array or array
8044 structure component, or if it has a zero extent along the relevant
8045 dimension, the lower bound is taken to be 1.
8047 @item @emph{See also}:
8048 @ref{UBOUND}, @ref{LCOBOUND}
8054 @section @code{LCOBOUND} --- Lower codimension bounds of an array
8056 @cindex coarray, lower bound
8059 @item @emph{Description}:
8060 Returns the lower bounds of a coarray, or a single lower cobound
8061 along the @var{DIM} codimension.
8062 @item @emph{Standard}:
8063 Fortran 2008 and later
8068 @item @emph{Syntax}:
8069 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
8071 @item @emph{Arguments}:
8072 @multitable @columnfractions .15 .70
8073 @item @var{ARRAY} @tab Shall be an coarray, of any type.
8074 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
8075 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8076 expression indicating the kind parameter of the result.
8079 @item @emph{Return value}:
8080 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8081 @var{KIND} is absent, the return value is of default integer kind.
8082 If @var{DIM} is absent, the result is an array of the lower cobounds of
8083 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
8084 corresponding to the lower cobound of the array along that codimension.
8086 @item @emph{See also}:
8087 @ref{UCOBOUND}, @ref{LBOUND}
8093 @section @code{LEADZ} --- Number of leading zero bits of an integer
8098 @item @emph{Description}:
8099 @code{LEADZ} returns the number of leading zero bits of an integer.
8101 @item @emph{Standard}:
8102 Fortran 2008 and later
8107 @item @emph{Syntax}:
8108 @code{RESULT = LEADZ(I)}
8110 @item @emph{Arguments}:
8111 @multitable @columnfractions .15 .70
8112 @item @var{I} @tab Shall be of type @code{INTEGER}.
8115 @item @emph{Return value}:
8116 The type of the return value is the default @code{INTEGER}.
8117 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
8119 @item @emph{Example}:
8122 WRITE (*,*) BIT_SIZE(1) ! prints 32
8123 WRITE (*,*) LEADZ(1) ! prints 31
8127 @item @emph{See also}:
8128 @ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR}
8134 @section @code{LEN} --- Length of a character entity
8136 @cindex string, length
8139 @item @emph{Description}:
8140 Returns the length of a character string. If @var{STRING} is an array,
8141 the length of an element of @var{STRING} is returned. Note that
8142 @var{STRING} need not be defined when this intrinsic is invoked, since
8143 only the length, not the content, of @var{STRING} is needed.
8145 @item @emph{Standard}:
8146 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
8151 @item @emph{Syntax}:
8152 @code{L = LEN(STRING [, KIND])}
8154 @item @emph{Arguments}:
8155 @multitable @columnfractions .15 .70
8156 @item @var{STRING} @tab Shall be a scalar or array of type
8157 @code{CHARACTER}, with @code{INTENT(IN)}
8158 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8159 expression indicating the kind parameter of the result.
8162 @item @emph{Return value}:
8163 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8164 @var{KIND} is absent, the return value is of default integer kind.
8167 @item @emph{Specific names}:
8168 @multitable @columnfractions .20 .20 .20 .25
8169 @item Name @tab Argument @tab Return type @tab Standard
8170 @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
8174 @item @emph{See also}:
8175 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
8181 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
8183 @cindex string, length, without trailing whitespace
8186 @item @emph{Description}:
8187 Returns the length of a character string, ignoring any trailing blanks.
8189 @item @emph{Standard}:
8190 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
8195 @item @emph{Syntax}:
8196 @code{RESULT = LEN_TRIM(STRING [, KIND])}
8198 @item @emph{Arguments}:
8199 @multitable @columnfractions .15 .70
8200 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
8201 with @code{INTENT(IN)}
8202 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8203 expression indicating the kind parameter of the result.
8206 @item @emph{Return value}:
8207 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8208 @var{KIND} is absent, the return value is of default integer kind.
8210 @item @emph{See also}:
8211 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
8217 @section @code{LGE} --- Lexical greater than or equal
8219 @cindex lexical comparison of strings
8220 @cindex string, comparison
8223 @item @emph{Description}:
8224 Determines whether one string is lexically greater than or equal to
8225 another string, where the two strings are interpreted as containing
8226 ASCII character codes. If the String A and String B are not the same
8227 length, the shorter is compared as if spaces were appended to it to form
8228 a value that has the same length as the longer.
8230 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
8231 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
8232 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
8233 that the latter use the processor's character ordering (which is not
8234 ASCII on some targets), whereas the former always use the ASCII
8237 @item @emph{Standard}:
8238 Fortran 77 and later
8243 @item @emph{Syntax}:
8244 @code{RESULT = LGE(STRING_A, STRING_B)}
8246 @item @emph{Arguments}:
8247 @multitable @columnfractions .15 .70
8248 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
8249 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
8252 @item @emph{Return value}:
8253 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
8254 otherwise, based on the ASCII ordering.
8256 @item @emph{Specific names}:
8257 @multitable @columnfractions .20 .20 .20 .25
8258 @item Name @tab Argument @tab Return type @tab Standard
8259 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
8262 @item @emph{See also}:
8263 @ref{LGT}, @ref{LLE}, @ref{LLT}
8269 @section @code{LGT} --- Lexical greater than
8271 @cindex lexical comparison of strings
8272 @cindex string, comparison
8275 @item @emph{Description}:
8276 Determines whether one string is lexically greater than another string,
8277 where the two strings are interpreted as containing ASCII character
8278 codes. If the String A and String B are not the same length, the
8279 shorter is compared as if spaces were appended to it to form a value
8280 that has the same length as the longer.
8282 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
8283 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
8284 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
8285 that the latter use the processor's character ordering (which is not
8286 ASCII on some targets), whereas the former always use the ASCII
8289 @item @emph{Standard}:
8290 Fortran 77 and later
8295 @item @emph{Syntax}:
8296 @code{RESULT = LGT(STRING_A, STRING_B)}
8298 @item @emph{Arguments}:
8299 @multitable @columnfractions .15 .70
8300 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
8301 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
8304 @item @emph{Return value}:
8305 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
8306 otherwise, based on the ASCII ordering.
8308 @item @emph{Specific names}:
8309 @multitable @columnfractions .20 .20 .20 .25
8310 @item Name @tab Argument @tab Return type @tab Standard
8311 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
8314 @item @emph{See also}:
8315 @ref{LGE}, @ref{LLE}, @ref{LLT}
8321 @section @code{LINK} --- Create a hard link
8323 @cindex file system, create link
8324 @cindex file system, hard link
8327 @item @emph{Description}:
8328 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
8329 character (@code{CHAR(0)}) can be used to mark the end of the names in
8330 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
8331 names are ignored. If the @var{STATUS} argument is supplied, it
8332 contains 0 on success or a nonzero error code upon return; see
8335 This intrinsic is provided in both subroutine and function forms;
8336 however, only one form can be used in any given program unit.
8338 @item @emph{Standard}:
8342 Subroutine, function
8344 @item @emph{Syntax}:
8345 @multitable @columnfractions .80
8346 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
8347 @item @code{STATUS = LINK(PATH1, PATH2)}
8350 @item @emph{Arguments}:
8351 @multitable @columnfractions .15 .70
8352 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
8353 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
8354 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
8357 @item @emph{See also}:
8358 @ref{SYMLNK}, @ref{UNLINK}
8364 @section @code{LLE} --- Lexical less than or equal
8366 @cindex lexical comparison of strings
8367 @cindex string, comparison
8370 @item @emph{Description}:
8371 Determines whether one string is lexically less than or equal to another
8372 string, where the two strings are interpreted as containing ASCII
8373 character codes. If the String A and String B are not the same length,
8374 the shorter is compared as if spaces were appended to it to form a value
8375 that has the same length as the longer.
8377 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
8378 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
8379 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
8380 that the latter use the processor's character ordering (which is not
8381 ASCII on some targets), whereas the former always use the ASCII
8384 @item @emph{Standard}:
8385 Fortran 77 and later
8390 @item @emph{Syntax}:
8391 @code{RESULT = LLE(STRING_A, STRING_B)}
8393 @item @emph{Arguments}:
8394 @multitable @columnfractions .15 .70
8395 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
8396 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
8399 @item @emph{Return value}:
8400 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
8401 otherwise, based on the ASCII ordering.
8403 @item @emph{Specific names}:
8404 @multitable @columnfractions .20 .20 .20 .25
8405 @item Name @tab Argument @tab Return type @tab Standard
8406 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
8409 @item @emph{See also}:
8410 @ref{LGE}, @ref{LGT}, @ref{LLT}
8416 @section @code{LLT} --- Lexical less than
8418 @cindex lexical comparison of strings
8419 @cindex string, comparison
8422 @item @emph{Description}:
8423 Determines whether one string is lexically less than another string,
8424 where the two strings are interpreted as containing ASCII character
8425 codes. If the String A and String B are not the same length, the
8426 shorter is compared as if spaces were appended to it to form a value
8427 that has the same length as the longer.
8429 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
8430 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
8431 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
8432 that the latter use the processor's character ordering (which is not
8433 ASCII on some targets), whereas the former always use the ASCII
8436 @item @emph{Standard}:
8437 Fortran 77 and later
8442 @item @emph{Syntax}:
8443 @code{RESULT = LLT(STRING_A, STRING_B)}
8445 @item @emph{Arguments}:
8446 @multitable @columnfractions .15 .70
8447 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
8448 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
8451 @item @emph{Return value}:
8452 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
8453 otherwise, based on the ASCII ordering.
8455 @item @emph{Specific names}:
8456 @multitable @columnfractions .20 .20 .20 .25
8457 @item Name @tab Argument @tab Return type @tab Standard
8458 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
8461 @item @emph{See also}:
8462 @ref{LGE}, @ref{LGT}, @ref{LLE}
8468 @section @code{LNBLNK} --- Index of the last non-blank character in a string
8470 @cindex string, find non-blank character
8473 @item @emph{Description}:
8474 Returns the length of a character string, ignoring any trailing blanks.
8475 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
8476 included for backwards compatibility.
8478 @item @emph{Standard}:
8484 @item @emph{Syntax}:
8485 @code{RESULT = LNBLNK(STRING)}
8487 @item @emph{Arguments}:
8488 @multitable @columnfractions .15 .70
8489 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
8490 with @code{INTENT(IN)}
8493 @item @emph{Return value}:
8494 The return value is of @code{INTEGER(kind=4)} type.
8496 @item @emph{See also}:
8497 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
8503 @section @code{LOC} --- Returns the address of a variable
8505 @cindex location of a variable in memory
8508 @item @emph{Description}:
8509 @code{LOC(X)} returns the address of @var{X} as an integer.
8511 @item @emph{Standard}:
8517 @item @emph{Syntax}:
8518 @code{RESULT = LOC(X)}
8520 @item @emph{Arguments}:
8521 @multitable @columnfractions .15 .70
8522 @item @var{X} @tab Variable of any type.
8525 @item @emph{Return value}:
8526 The return value is of type @code{INTEGER}, with a @code{KIND}
8527 corresponding to the size (in bytes) of a memory address on the target
8530 @item @emph{Example}:
8537 end program test_loc
8544 @section @code{LOG} --- Natural logarithm function
8551 @cindex exponential function, inverse
8552 @cindex logarithm function
8553 @cindex natural logarithm function
8556 @item @emph{Description}:
8557 @code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the
8558 logarithm to the base @math{e}.
8560 @item @emph{Standard}:
8561 Fortran 77 and later
8566 @item @emph{Syntax}:
8567 @code{RESULT = LOG(X)}
8569 @item @emph{Arguments}:
8570 @multitable @columnfractions .15 .70
8571 @item @var{X} @tab The type shall be @code{REAL} or
8575 @item @emph{Return value}:
8576 The return value is of type @code{REAL} or @code{COMPLEX}.
8577 The kind type parameter is the same as @var{X}.
8578 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
8579 @math{-\pi \leq \omega \leq \pi}.
8581 @item @emph{Example}:
8584 real(8) :: x = 2.7182818284590451_8
8585 complex :: z = (1.0, 2.0)
8586 x = log(x) ! will yield (approximately) 1
8588 end program test_log
8591 @item @emph{Specific names}:
8592 @multitable @columnfractions .20 .20 .20 .25
8593 @item Name @tab Argument @tab Return type @tab Standard
8594 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
8595 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
8596 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
8597 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
8598 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
8605 @section @code{LOG10} --- Base 10 logarithm function
8609 @cindex exponential function, inverse
8610 @cindex logarithm function with base 10
8611 @cindex base 10 logarithm function
8614 @item @emph{Description}:
8615 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
8617 @item @emph{Standard}:
8618 Fortran 77 and later
8623 @item @emph{Syntax}:
8624 @code{RESULT = LOG10(X)}
8626 @item @emph{Arguments}:
8627 @multitable @columnfractions .15 .70
8628 @item @var{X} @tab The type shall be @code{REAL}.
8631 @item @emph{Return value}:
8632 The return value is of type @code{REAL} or @code{COMPLEX}.
8633 The kind type parameter is the same as @var{X}.
8635 @item @emph{Example}:
8638 real(8) :: x = 10.0_8
8640 end program test_log10
8643 @item @emph{Specific names}:
8644 @multitable @columnfractions .20 .20 .20 .25
8645 @item Name @tab Argument @tab Return type @tab Standard
8646 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
8647 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
8654 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
8659 @cindex Gamma function, logarithm of
8662 @item @emph{Description}:
8663 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
8664 of the Gamma (@math{\Gamma}) function.
8666 @item @emph{Standard}:
8667 Fortran 2008 and later
8672 @item @emph{Syntax}:
8673 @code{X = LOG_GAMMA(X)}
8675 @item @emph{Arguments}:
8676 @multitable @columnfractions .15 .70
8677 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
8678 nor a negative integer.
8681 @item @emph{Return value}:
8682 The return value is of type @code{REAL} of the same kind as @var{X}.
8684 @item @emph{Example}:
8686 program test_log_gamma
8688 x = lgamma(x) ! returns 0.0
8689 end program test_log_gamma
8692 @item @emph{Specific names}:
8693 @multitable @columnfractions .20 .20 .20 .25
8694 @item Name @tab Argument @tab Return type @tab Standard
8695 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
8696 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
8697 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
8700 @item @emph{See also}:
8701 Gamma function: @ref{GAMMA}
8708 @section @code{LOGICAL} --- Convert to logical type
8710 @cindex conversion, to logical
8713 @item @emph{Description}:
8714 Converts one kind of @code{LOGICAL} variable to another.
8716 @item @emph{Standard}:
8717 Fortran 95 and later
8722 @item @emph{Syntax}:
8723 @code{RESULT = LOGICAL(L [, KIND])}
8725 @item @emph{Arguments}:
8726 @multitable @columnfractions .15 .70
8727 @item @var{L} @tab The type shall be @code{LOGICAL}.
8728 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8729 expression indicating the kind parameter of the result.
8732 @item @emph{Return value}:
8733 The return value is a @code{LOGICAL} value equal to @var{L}, with a
8734 kind corresponding to @var{KIND}, or of the default logical kind if
8735 @var{KIND} is not given.
8737 @item @emph{See also}:
8738 @ref{INT}, @ref{REAL}, @ref{CMPLX}
8744 @section @code{LONG} --- Convert to integer type
8746 @cindex conversion, to integer
8749 @item @emph{Description}:
8750 Convert to a @code{KIND=4} integer type, which is the same size as a C
8751 @code{long} integer. This is equivalent to the standard @code{INT}
8752 intrinsic with an optional argument of @code{KIND=4}, and is only
8753 included for backwards compatibility.
8755 @item @emph{Standard}:
8761 @item @emph{Syntax}:
8762 @code{RESULT = LONG(A)}
8764 @item @emph{Arguments}:
8765 @multitable @columnfractions .15 .70
8766 @item @var{A} @tab Shall be of type @code{INTEGER},
8767 @code{REAL}, or @code{COMPLEX}.
8770 @item @emph{Return value}:
8771 The return value is a @code{INTEGER(4)} variable.
8773 @item @emph{See also}:
8774 @ref{INT}, @ref{INT2}, @ref{INT8}
8780 @section @code{LSHIFT} --- Left shift bits
8782 @cindex bits, shift left
8785 @item @emph{Description}:
8786 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
8787 bits shifted left by @var{SHIFT} places. If the absolute value of
8788 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
8789 Bits shifted out from the left end are lost; zeros are shifted in from
8792 This function has been superseded by the @code{ISHFT} intrinsic, which
8793 is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
8794 which is standard in Fortran 2008 and later.
8796 @item @emph{Standard}:
8802 @item @emph{Syntax}:
8803 @code{RESULT = LSHIFT(I, SHIFT)}
8805 @item @emph{Arguments}:
8806 @multitable @columnfractions .15 .70
8807 @item @var{I} @tab The type shall be @code{INTEGER}.
8808 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8811 @item @emph{Return value}:
8812 The return value is of type @code{INTEGER} and of the same kind as
8815 @item @emph{See also}:
8816 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}, @ref{SHIFTA}, @ref{SHIFTL},
8824 @section @code{LSTAT} --- Get file status
8826 @cindex file system, file status
8829 @item @emph{Description}:
8830 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
8831 symbolic link, then the link itself is statted, not the file that it
8834 The elements in @code{VALUES} are the same as described by @ref{STAT}.
8836 This intrinsic is provided in both subroutine and function forms;
8837 however, only one form can be used in any given program unit.
8839 @item @emph{Standard}:
8843 Subroutine, function
8845 @item @emph{Syntax}:
8846 @multitable @columnfractions .80
8847 @item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
8848 @item @code{STATUS = LSTAT(NAME, VALUES)}
8851 @item @emph{Arguments}:
8852 @multitable @columnfractions .15 .70
8853 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
8854 kind, a valid path within the file system.
8855 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
8856 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
8857 Returns 0 on success and a system specific error code otherwise.
8860 @item @emph{Example}:
8861 See @ref{STAT} for an example.
8863 @item @emph{See also}:
8864 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
8870 @section @code{LTIME} --- Convert time to local time info
8872 @cindex time, conversion to local time info
8875 @item @emph{Description}:
8876 Given a system time value @var{TIME} (as provided by the @code{TIME8}
8877 intrinsic), fills @var{VALUES} with values extracted from it appropriate
8878 to the local time zone using @code{localtime(3)}.
8880 @item @emph{Standard}:
8886 @item @emph{Syntax}:
8887 @code{CALL LTIME(TIME, VALUES)}
8889 @item @emph{Arguments}:
8890 @multitable @columnfractions .15 .70
8891 @item @var{TIME} @tab An @code{INTEGER} scalar expression
8892 corresponding to a system time, with @code{INTENT(IN)}.
8893 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
8894 with @code{INTENT(OUT)}.
8897 @item @emph{Return value}:
8898 The elements of @var{VALUES} are assigned as follows:
8900 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
8902 @item Minutes after the hour, range 0--59
8903 @item Hours past midnight, range 0--23
8904 @item Day of month, range 0--31
8905 @item Number of months since January, range 0--12
8906 @item Years since 1900
8907 @item Number of days since Sunday, range 0--6
8908 @item Days since January 1
8909 @item Daylight savings indicator: positive if daylight savings is in
8910 effect, zero if not, and negative if the information is not available.
8913 @item @emph{See also}:
8914 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
8921 @section @code{MALLOC} --- Allocate dynamic memory
8923 @cindex pointer, cray
8926 @item @emph{Description}:
8927 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
8928 returns the address of the allocated memory. The @code{MALLOC} intrinsic
8929 is an extension intended to be used with Cray pointers, and is provided
8930 in GNU Fortran to allow the user to compile legacy code. For new code
8931 using Fortran 95 pointers, the memory allocation intrinsic is
8934 @item @emph{Standard}:
8940 @item @emph{Syntax}:
8941 @code{PTR = MALLOC(SIZE)}
8943 @item @emph{Arguments}:
8944 @multitable @columnfractions .15 .70
8945 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
8948 @item @emph{Return value}:
8949 The return value is of type @code{INTEGER(K)}, with @var{K} such that
8950 variables of type @code{INTEGER(K)} have the same size as
8951 C pointers (@code{sizeof(void *)}).
8953 @item @emph{Example}:
8954 The following example demonstrates the use of @code{MALLOC} and
8955 @code{FREE} with Cray pointers.
8964 ptr_x = malloc(20*8)
8966 x(i) = sqrt(1.0d0 / i)
8974 end program test_malloc
8977 @item @emph{See also}:
8984 @section @code{MASKL} --- Left justified mask
8986 @cindex mask, left justified
8989 @item @emph{Description}:
8990 @code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
8991 remaining bits set to 0.
8993 @item @emph{Standard}:
8994 Fortran 2008 and later
8999 @item @emph{Syntax}:
9000 @code{RESULT = MASKL(I[, KIND])}
9002 @item @emph{Arguments}:
9003 @multitable @columnfractions .15 .70
9004 @item @var{I} @tab Shall be of type @code{INTEGER}.
9005 @item @var{KIND} @tab Shall be a scalar constant expression of type
9009 @item @emph{Return value}:
9010 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
9011 specifies the kind value of the return type; otherwise, it is of the
9012 default integer kind.
9014 @item @emph{See also}:
9021 @section @code{MASKR} --- Right justified mask
9023 @cindex mask, right justified
9026 @item @emph{Description}:
9027 @code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
9028 remaining bits set to 0.
9030 @item @emph{Standard}:
9031 Fortran 2008 and later
9036 @item @emph{Syntax}:
9037 @code{RESULT = MASKR(I[, KIND])}
9039 @item @emph{Arguments}:
9040 @multitable @columnfractions .15 .70
9041 @item @var{I} @tab Shall be of type @code{INTEGER}.
9042 @item @var{KIND} @tab Shall be a scalar constant expression of type
9046 @item @emph{Return value}:
9047 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
9048 specifies the kind value of the return type; otherwise, it is of the
9049 default integer kind.
9051 @item @emph{See also}:
9058 @section @code{MATMUL} --- matrix multiplication
9060 @cindex matrix multiplication
9061 @cindex product, matrix
9064 @item @emph{Description}:
9065 Performs a matrix multiplication on numeric or logical arguments.
9067 @item @emph{Standard}:
9068 Fortran 95 and later
9071 Transformational function
9073 @item @emph{Syntax}:
9074 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
9076 @item @emph{Arguments}:
9077 @multitable @columnfractions .15 .70
9078 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
9079 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
9081 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
9082 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
9083 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
9084 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
9085 equal to the last (or only) dimension of @var{MATRIX_A}.
9088 @item @emph{Return value}:
9089 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
9090 kind of the result follow the usual type and kind promotion rules, as
9091 for the @code{*} or @code{.AND.} operators.
9093 @item @emph{See also}:
9099 @section @code{MAX} --- Maximum value of an argument list
9106 @cindex maximum value
9109 @item @emph{Description}:
9110 Returns the argument with the largest (most positive) value.
9112 @item @emph{Standard}:
9113 Fortran 77 and later
9118 @item @emph{Syntax}:
9119 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
9121 @item @emph{Arguments}:
9122 @multitable @columnfractions .15 .70
9123 @item @var{A1} @tab The type shall be @code{INTEGER} or
9125 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
9126 as @var{A1}. (As a GNU extension, arguments of different kinds are
9130 @item @emph{Return value}:
9131 The return value corresponds to the maximum value among the arguments,
9132 and has the same type and kind as the first argument.
9134 @item @emph{Specific names}:
9135 @multitable @columnfractions .20 .20 .20 .25
9136 @item Name @tab Argument @tab Return type @tab Standard
9137 @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
9138 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
9139 @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
9140 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
9141 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
9144 @item @emph{See also}:
9145 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
9152 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
9153 @fnindex MAXEXPONENT
9154 @cindex model representation, maximum exponent
9157 @item @emph{Description}:
9158 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
9161 @item @emph{Standard}:
9162 Fortran 95 and later
9167 @item @emph{Syntax}:
9168 @code{RESULT = MAXEXPONENT(X)}
9170 @item @emph{Arguments}:
9171 @multitable @columnfractions .15 .70
9172 @item @var{X} @tab Shall be of type @code{REAL}.
9175 @item @emph{Return value}:
9176 The return value is of type @code{INTEGER} and of the default integer
9179 @item @emph{Example}:
9185 print *, minexponent(x), maxexponent(x)
9186 print *, minexponent(y), maxexponent(y)
9187 end program exponents
9194 @section @code{MAXLOC} --- Location of the maximum value within an array
9196 @cindex array, location of maximum element
9199 @item @emph{Description}:
9200 Determines the location of the element in the array with the maximum
9201 value, or, if the @var{DIM} argument is supplied, determines the
9202 locations of the maximum element along each row of the array in the
9203 @var{DIM} direction. If @var{MASK} is present, only the elements for
9204 which @var{MASK} is @code{.TRUE.} are considered. If more than one
9205 element in the array has the maximum value, the location returned is
9206 that of the first such element in array element order. If the array has
9207 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
9208 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
9209 and all of the elements of @var{MASK} along a given row are zero, the
9210 result value for that row is zero.
9212 @item @emph{Standard}:
9213 Fortran 95 and later
9216 Transformational function
9218 @item @emph{Syntax}:
9219 @multitable @columnfractions .80
9220 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
9221 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
9224 @item @emph{Arguments}:
9225 @multitable @columnfractions .15 .70
9226 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
9228 @item @var{DIM} @tab (Optional) Shall be a scalar of type
9229 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
9230 inclusive. It may not be an optional dummy argument.
9231 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
9232 and conformable with @var{ARRAY}.
9235 @item @emph{Return value}:
9236 If @var{DIM} is absent, the result is a rank-one array with a length
9237 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
9238 is an array with a rank one less than the rank of @var{ARRAY}, and a
9239 size corresponding to the size of @var{ARRAY} with the @var{DIM}
9240 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
9241 of one, the result is a scalar. In all cases, the result is of default
9242 @code{INTEGER} type.
9244 @item @emph{See also}:
9245 @ref{MAX}, @ref{MAXVAL}
9252 @section @code{MAXVAL} --- Maximum value of an array
9254 @cindex array, maximum value
9255 @cindex maximum value
9258 @item @emph{Description}:
9259 Determines the maximum value of the elements in an array value, or, if
9260 the @var{DIM} argument is supplied, determines the maximum value along
9261 each row of the array in the @var{DIM} direction. If @var{MASK} is
9262 present, only the elements for which @var{MASK} is @code{.TRUE.} are
9263 considered. If the array has zero size, or all of the elements of
9264 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
9265 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
9268 @item @emph{Standard}:
9269 Fortran 95 and later
9272 Transformational function
9274 @item @emph{Syntax}:
9275 @multitable @columnfractions .80
9276 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
9277 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
9280 @item @emph{Arguments}:
9281 @multitable @columnfractions .15 .70
9282 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
9284 @item @var{DIM} @tab (Optional) Shall be a scalar of type
9285 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
9286 inclusive. It may not be an optional dummy argument.
9287 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
9288 and conformable with @var{ARRAY}.
9291 @item @emph{Return value}:
9292 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
9293 is a scalar. If @var{DIM} is present, the result is an array with a
9294 rank one less than the rank of @var{ARRAY}, and a size corresponding to
9295 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
9296 cases, the result is of the same type and kind as @var{ARRAY}.
9298 @item @emph{See also}:
9299 @ref{MAX}, @ref{MAXLOC}
9305 @section @code{MCLOCK} --- Time function
9307 @cindex time, clock ticks
9311 @item @emph{Description}:
9312 Returns the number of clock ticks since the start of the process, based
9313 on the function @code{clock(3)} in the C standard library.
9315 This intrinsic is not fully portable, such as to systems with 32-bit
9316 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
9317 the values returned by this intrinsic might be, or become, negative, or
9318 numerically less than previous values, during a single run of the
9321 @item @emph{Standard}:
9327 @item @emph{Syntax}:
9328 @code{RESULT = MCLOCK()}
9330 @item @emph{Return value}:
9331 The return value is a scalar of type @code{INTEGER(4)}, equal to the
9332 number of clock ticks since the start of the process, or @code{-1} if
9333 the system does not support @code{clock(3)}.
9335 @item @emph{See also}:
9336 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
9343 @section @code{MCLOCK8} --- Time function (64-bit)
9345 @cindex time, clock ticks
9349 @item @emph{Description}:
9350 Returns the number of clock ticks since the start of the process, based
9351 on the function @code{clock(3)} in the C standard library.
9353 @emph{Warning:} this intrinsic does not increase the range of the timing
9354 values over that returned by @code{clock(3)}. On a system with a 32-bit
9355 @code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though
9356 it is converted to a 64-bit @code{INTEGER(8)} value. That means
9357 overflows of the 32-bit value can still occur. Therefore, the values
9358 returned by this intrinsic might be or become negative or numerically
9359 less than previous values during a single run of the compiled program.
9361 @item @emph{Standard}:
9367 @item @emph{Syntax}:
9368 @code{RESULT = MCLOCK8()}
9370 @item @emph{Return value}:
9371 The return value is a scalar of type @code{INTEGER(8)}, equal to the
9372 number of clock ticks since the start of the process, or @code{-1} if
9373 the system does not support @code{clock(3)}.
9375 @item @emph{See also}:
9376 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
9383 @section @code{MERGE} --- Merge variables
9385 @cindex array, merge arrays
9386 @cindex array, combine arrays
9389 @item @emph{Description}:
9390 Select values from two arrays according to a logical mask. The result
9391 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
9392 @var{FSOURCE} if it is @code{.FALSE.}.
9394 @item @emph{Standard}:
9395 Fortran 95 and later
9400 @item @emph{Syntax}:
9401 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
9403 @item @emph{Arguments}:
9404 @multitable @columnfractions .15 .70
9405 @item @var{TSOURCE} @tab May be of any type.
9406 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
9408 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
9411 @item @emph{Return value}:
9412 The result is of the same type and type parameters as @var{TSOURCE}.
9419 @section @code{MERGE_BITS} --- Merge of bits under mask
9424 @item @emph{Description}:
9425 @code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
9426 as determined by the mask. The i-th bit of the result is equal to the
9427 i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
9428 the i-th bit of @var{J} otherwise.
9430 @item @emph{Standard}:
9431 Fortran 2008 and later
9436 @item @emph{Syntax}:
9437 @code{RESULT = MERGE_BITS(I, J, MASK)}
9439 @item @emph{Arguments}:
9440 @multitable @columnfractions .15 .70
9441 @item @var{I} @tab Shall be of type @code{INTEGER}.
9442 @item @var{J} @tab Shall be of type @code{INTEGER} and of the same
9444 @item @var{MASK} @tab Shall be of type @code{INTEGER} and of the same
9448 @item @emph{Return value}:
9449 The result is of the same type and kind as @var{I}.
9456 @section @code{MIN} --- Minimum value of an argument list
9463 @cindex minimum value
9466 @item @emph{Description}:
9467 Returns the argument with the smallest (most negative) value.
9469 @item @emph{Standard}:
9470 Fortran 77 and later
9475 @item @emph{Syntax}:
9476 @code{RESULT = MIN(A1, A2 [, A3, ...])}
9478 @item @emph{Arguments}:
9479 @multitable @columnfractions .15 .70
9480 @item @var{A1} @tab The type shall be @code{INTEGER} or
9482 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
9483 as @var{A1}. (As a GNU extension, arguments of different kinds are
9487 @item @emph{Return value}:
9488 The return value corresponds to the maximum value among the arguments,
9489 and has the same type and kind as the first argument.
9491 @item @emph{Specific names}:
9492 @multitable @columnfractions .20 .20 .20 .25
9493 @item Name @tab Argument @tab Return type @tab Standard
9494 @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
9495 @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
9496 @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
9497 @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
9498 @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
9501 @item @emph{See also}:
9502 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
9508 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
9509 @fnindex MINEXPONENT
9510 @cindex model representation, minimum exponent
9513 @item @emph{Description}:
9514 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
9517 @item @emph{Standard}:
9518 Fortran 95 and later
9523 @item @emph{Syntax}:
9524 @code{RESULT = MINEXPONENT(X)}
9526 @item @emph{Arguments}:
9527 @multitable @columnfractions .15 .70
9528 @item @var{X} @tab Shall be of type @code{REAL}.
9531 @item @emph{Return value}:
9532 The return value is of type @code{INTEGER} and of the default integer
9535 @item @emph{Example}:
9536 See @code{MAXEXPONENT} for an example.
9542 @section @code{MINLOC} --- Location of the minimum value within an array
9544 @cindex array, location of minimum element
9547 @item @emph{Description}:
9548 Determines the location of the element in the array with the minimum
9549 value, or, if the @var{DIM} argument is supplied, determines the
9550 locations of the minimum element along each row of the array in the
9551 @var{DIM} direction. If @var{MASK} is present, only the elements for
9552 which @var{MASK} is @code{.TRUE.} are considered. If more than one
9553 element in the array has the minimum value, the location returned is
9554 that of the first such element in array element order. If the array has
9555 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
9556 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
9557 and all of the elements of @var{MASK} along a given row are zero, the
9558 result value for that row is zero.
9560 @item @emph{Standard}:
9561 Fortran 95 and later
9564 Transformational function
9566 @item @emph{Syntax}:
9567 @multitable @columnfractions .80
9568 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
9569 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
9572 @item @emph{Arguments}:
9573 @multitable @columnfractions .15 .70
9574 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
9576 @item @var{DIM} @tab (Optional) Shall be a scalar of type
9577 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
9578 inclusive. It may not be an optional dummy argument.
9579 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
9580 and conformable with @var{ARRAY}.
9583 @item @emph{Return value}:
9584 If @var{DIM} is absent, the result is a rank-one array with a length
9585 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
9586 is an array with a rank one less than the rank of @var{ARRAY}, and a
9587 size corresponding to the size of @var{ARRAY} with the @var{DIM}
9588 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
9589 of one, the result is a scalar. In all cases, the result is of default
9590 @code{INTEGER} type.
9592 @item @emph{See also}:
9593 @ref{MIN}, @ref{MINVAL}
9600 @section @code{MINVAL} --- Minimum value of an array
9602 @cindex array, minimum value
9603 @cindex minimum value
9606 @item @emph{Description}:
9607 Determines the minimum value of the elements in an array value, or, if
9608 the @var{DIM} argument is supplied, determines the minimum value along
9609 each row of the array in the @var{DIM} direction. If @var{MASK} is
9610 present, only the elements for which @var{MASK} is @code{.TRUE.} are
9611 considered. If the array has zero size, or all of the elements of
9612 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
9613 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
9614 @var{ARRAY} is of character type.
9616 @item @emph{Standard}:
9617 Fortran 95 and later
9620 Transformational function
9622 @item @emph{Syntax}:
9623 @multitable @columnfractions .80
9624 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
9625 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
9628 @item @emph{Arguments}:
9629 @multitable @columnfractions .15 .70
9630 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
9632 @item @var{DIM} @tab (Optional) Shall be a scalar of type
9633 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
9634 inclusive. It may not be an optional dummy argument.
9635 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
9636 and conformable with @var{ARRAY}.
9639 @item @emph{Return value}:
9640 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
9641 is a scalar. If @var{DIM} is present, the result is an array with a
9642 rank one less than the rank of @var{ARRAY}, and a size corresponding to
9643 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
9644 cases, the result is of the same type and kind as @var{ARRAY}.
9646 @item @emph{See also}:
9647 @ref{MIN}, @ref{MINLOC}
9654 @section @code{MOD} --- Remainder function
9659 @cindex division, remainder
9662 @item @emph{Description}:
9663 @code{MOD(A,P)} computes the remainder of the division of A by P@.
9665 @item @emph{Standard}:
9666 Fortran 77 and later
9671 @item @emph{Syntax}:
9672 @code{RESULT = MOD(A, P)}
9674 @item @emph{Arguments}:
9675 @multitable @columnfractions .15 .70
9676 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
9677 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
9678 and not equal to zero.
9681 @item @emph{Return value}:
9682 The return value is the result of @code{A - (INT(A/P) * P)}. The type
9683 and kind of the return value is the same as that of the arguments. The
9684 returned value has the same sign as A and a magnitude less than the
9687 @item @emph{Example}:
9691 print *, mod(17.5,5.5)
9692 print *, mod(17.5d0,5.5)
9693 print *, mod(17.5,5.5d0)
9696 print *, mod(-17.5,5.5)
9697 print *, mod(-17.5d0,5.5)
9698 print *, mod(-17.5,5.5d0)
9701 print *, mod(17.5,-5.5)
9702 print *, mod(17.5d0,-5.5)
9703 print *, mod(17.5,-5.5d0)
9704 end program test_mod
9707 @item @emph{Specific names}:
9708 @multitable @columnfractions .20 .20 .20 .25
9709 @item Name @tab Arguments @tab Return type @tab Standard
9710 @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
9711 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
9712 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
9715 @item @emph{See also}:
9723 @section @code{MODULO} --- Modulo function
9726 @cindex division, modulo
9729 @item @emph{Description}:
9730 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
9732 @item @emph{Standard}:
9733 Fortran 95 and later
9738 @item @emph{Syntax}:
9739 @code{RESULT = MODULO(A, P)}
9741 @item @emph{Arguments}:
9742 @multitable @columnfractions .15 .70
9743 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
9744 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}.
9745 It shall not be zero.
9748 @item @emph{Return value}:
9749 The type and kind of the result are those of the arguments.
9751 @item If @var{A} and @var{P} are of type @code{INTEGER}:
9752 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
9753 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
9755 @item If @var{A} and @var{P} are of type @code{REAL}:
9756 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
9758 The returned value has the same sign as P and a magnitude less than
9761 @item @emph{Example}:
9764 print *, modulo(17,3)
9765 print *, modulo(17.5,5.5)
9767 print *, modulo(-17,3)
9768 print *, modulo(-17.5,5.5)
9770 print *, modulo(17,-3)
9771 print *, modulo(17.5,-5.5)
9775 @item @emph{See also}:
9783 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
9785 @cindex moving allocation
9786 @cindex allocation, moving
9789 @item @emph{Description}:
9790 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
9791 @var{TO}. @var{FROM} will become deallocated in the process.
9793 @item @emph{Standard}:
9794 Fortran 2003 and later
9799 @item @emph{Syntax}:
9800 @code{CALL MOVE_ALLOC(FROM, TO)}
9802 @item @emph{Arguments}:
9803 @multitable @columnfractions .15 .70
9804 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
9805 of any type and kind.
9806 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
9807 of the same type, kind and rank as @var{FROM}.
9810 @item @emph{Return value}:
9813 @item @emph{Example}:
9815 program test_move_alloc
9816 integer, allocatable :: a(:), b(:)
9820 call move_alloc(a, b)
9821 print *, allocated(a), allocated(b)
9823 end program test_move_alloc
9830 @section @code{MVBITS} --- Move bits from one integer to another
9835 @item @emph{Description}:
9836 Moves @var{LEN} bits from positions @var{FROMPOS} through
9837 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
9838 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
9839 affected by the movement of bits is unchanged. The values of
9840 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
9841 @code{BIT_SIZE(FROM)}.
9843 @item @emph{Standard}:
9844 Fortran 95 and later
9847 Elemental subroutine
9849 @item @emph{Syntax}:
9850 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
9852 @item @emph{Arguments}:
9853 @multitable @columnfractions .15 .70
9854 @item @var{FROM} @tab The type shall be @code{INTEGER}.
9855 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
9856 @item @var{LEN} @tab The type shall be @code{INTEGER}.
9857 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
9858 same kind as @var{FROM}.
9859 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
9862 @item @emph{See also}:
9863 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
9869 @section @code{NEAREST} --- Nearest representable number
9871 @cindex real number, nearest different
9872 @cindex floating point, nearest different
9875 @item @emph{Description}:
9876 @code{NEAREST(X, S)} returns the processor-representable number nearest
9877 to @code{X} in the direction indicated by the sign of @code{S}.
9879 @item @emph{Standard}:
9880 Fortran 95 and later
9885 @item @emph{Syntax}:
9886 @code{RESULT = NEAREST(X, S)}
9888 @item @emph{Arguments}:
9889 @multitable @columnfractions .15 .70
9890 @item @var{X} @tab Shall be of type @code{REAL}.
9891 @item @var{S} @tab Shall be of type @code{REAL} and
9895 @item @emph{Return value}:
9896 The return value is of the same type as @code{X}. If @code{S} is
9897 positive, @code{NEAREST} returns the processor-representable number
9898 greater than @code{X} and nearest to it. If @code{S} is negative,
9899 @code{NEAREST} returns the processor-representable number smaller than
9900 @code{X} and nearest to it.
9902 @item @emph{Example}:
9904 program test_nearest
9906 x = nearest(42.0, 1.0)
9907 y = nearest(42.0, -1.0)
9908 write (*,"(3(G20.15))") x, y, x - y
9909 end program test_nearest
9916 @section @code{NEW_LINE} --- New line character
9919 @cindex output, newline
9922 @item @emph{Description}:
9923 @code{NEW_LINE(C)} returns the new-line character.
9925 @item @emph{Standard}:
9926 Fortran 2003 and later
9931 @item @emph{Syntax}:
9932 @code{RESULT = NEW_LINE(C)}
9934 @item @emph{Arguments}:
9935 @multitable @columnfractions .15 .70
9936 @item @var{C} @tab The argument shall be a scalar or array of the
9937 type @code{CHARACTER}.
9940 @item @emph{Return value}:
9941 Returns a @var{CHARACTER} scalar of length one with the new-line character of
9942 the same kind as parameter @var{C}.
9944 @item @emph{Example}:
9948 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
9956 @section @code{NINT} --- Nearest whole number
9959 @cindex rounding, nearest whole number
9962 @item @emph{Description}:
9963 @code{NINT(A)} rounds its argument to the nearest whole number.
9965 @item @emph{Standard}:
9966 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
9971 @item @emph{Syntax}:
9972 @code{RESULT = NINT(A [, KIND])}
9974 @item @emph{Arguments}:
9975 @multitable @columnfractions .15 .70
9976 @item @var{A} @tab The type of the argument shall be @code{REAL}.
9977 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9978 expression indicating the kind parameter of the result.
9981 @item @emph{Return value}:
9982 Returns @var{A} with the fractional portion of its magnitude eliminated by
9983 rounding to the nearest whole number and with its sign preserved,
9984 converted to an @code{INTEGER} of the default kind.
9986 @item @emph{Example}:
9993 print *, nint(x4), idnint(x8)
9994 end program test_nint
9997 @item @emph{Specific names}:
9998 @multitable @columnfractions .20 .20 .20 .25
9999 @item Name @tab Argument @tab Return Type @tab Standard
10000 @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later
10001 @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later
10004 @item @emph{See also}:
10005 @ref{CEILING}, @ref{FLOOR}
10012 @section @code{NORM2} --- Euclidean vector norms
10014 @cindex Euclidean vector norm
10015 @cindex L2 vector norm
10016 @cindex norm, Euclidean
10019 @item @emph{Description}:
10020 Calculates the Euclidean vector norm (@math{L_2} norm) of
10021 of @var{ARRAY} along dimension @var{DIM}.
10023 @item @emph{Standard}:
10024 Fortran 2008 and later
10026 @item @emph{Class}:
10027 Transformational function
10029 @item @emph{Syntax}:
10030 @multitable @columnfractions .80
10031 @item @code{RESULT = NORM2(ARRAY[, DIM])}
10034 @item @emph{Arguments}:
10035 @multitable @columnfractions .15 .70
10036 @item @var{ARRAY} @tab Shall be an array of type @code{REAL}
10037 @item @var{DIM} @tab (Optional) shall be a scalar of type
10038 @code{INTEGER} with a value in the range from 1 to n, where n
10039 equals the rank of @var{ARRAY}.
10042 @item @emph{Return value}:
10043 The result is of the same type as @var{ARRAY}.
10045 If @var{DIM} is absent, a scalar with the square root of the sum of all
10046 elements in @var{ARRAY} squared is returned. Otherwise, an array of
10047 rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
10048 shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
10051 @item @emph{Example}:
10054 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
10055 print *, NORM2(x) ! = sqrt(55.) ~ 7.416
10063 @section @code{NOT} --- Logical negation
10065 @cindex bits, negate
10066 @cindex bitwise logical not
10067 @cindex logical not, bitwise
10070 @item @emph{Description}:
10071 @code{NOT} returns the bitwise Boolean inverse of @var{I}.
10073 @item @emph{Standard}:
10074 Fortran 95 and later
10076 @item @emph{Class}:
10079 @item @emph{Syntax}:
10080 @code{RESULT = NOT(I)}
10082 @item @emph{Arguments}:
10083 @multitable @columnfractions .15 .70
10084 @item @var{I} @tab The type shall be @code{INTEGER}.
10087 @item @emph{Return value}:
10088 The return type is @code{INTEGER}, of the same kind as the
10091 @item @emph{See also}:
10092 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
10099 @section @code{NULL} --- Function that returns an disassociated pointer
10101 @cindex pointer, status
10102 @cindex pointer, disassociated
10105 @item @emph{Description}:
10106 Returns a disassociated pointer.
10108 If @var{MOLD} is present, a disassociated pointer of the same type is
10109 returned, otherwise the type is determined by context.
10111 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
10112 includes cases where it is required.
10114 @item @emph{Standard}:
10115 Fortran 95 and later
10117 @item @emph{Class}:
10118 Transformational function
10120 @item @emph{Syntax}:
10121 @code{PTR => NULL([MOLD])}
10123 @item @emph{Arguments}:
10124 @multitable @columnfractions .15 .70
10125 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
10126 status and of any type.
10129 @item @emph{Return value}:
10130 A disassociated pointer.
10132 @item @emph{Example}:
10134 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
10137 @item @emph{See also}:
10144 @section @code{NUM_IMAGES} --- Function that returns the number of images
10145 @fnindex NUM_IMAGES
10146 @cindex coarray, @code{NUM_IMAGES}
10147 @cindex images, number of
10150 @item @emph{Description}:
10151 Returns the number of images.
10153 @item @emph{Standard}:
10154 Fortran 2008 and later. With @var{DISTANCE} or @var{FAILED} argument,
10155 Technical Specification (TS) 18508 or later
10158 @item @emph{Class}:
10159 Transformational function
10161 @item @emph{Syntax}:
10162 @code{RESULT = NUM_IMAGES(DISTANCE, FAILED)}
10164 @item @emph{Arguments}:
10165 @multitable @columnfractions .15 .70
10166 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
10167 @item @var{FAILED} @tab (optional, intent(in)) Scalar logical expression
10170 @item @emph{Return value}:
10171 Scalar default-kind integer. If @var{DISTANCE} is not present or has value 0,
10172 the number of images in the current team is returned. For values smaller or
10173 equal distance to the initial team, it returns the number of images index
10174 on the ancestor team which has a distance of @var{DISTANCE} from the invoking
10175 team. If @var{DISTANCE} is larger than the distance to the initial team, the
10176 number of images of the initial team is returned. If @var{FAILED} is not present
10177 the total number of images is returned; if it has the value @code{.TRUE.},
10178 the number of failed images is returned, otherwise, the number of images which
10179 do have not the failed status.
10181 @item @emph{Example}:
10183 INTEGER :: value[*]
10185 value = THIS_IMAGE()
10187 IF (THIS_IMAGE() == 1) THEN
10188 DO i = 1, NUM_IMAGES()
10189 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
10194 @item @emph{See also}:
10195 @ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
10201 @section @code{OR} --- Bitwise logical OR
10203 @cindex bitwise logical or
10204 @cindex logical or, bitwise
10207 @item @emph{Description}:
10208 Bitwise logical @code{OR}.
10210 This intrinsic routine is provided for backwards compatibility with
10211 GNU Fortran 77. For integer arguments, programmers should consider
10212 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
10214 @item @emph{Standard}:
10217 @item @emph{Class}:
10220 @item @emph{Syntax}:
10221 @code{RESULT = OR(I, J)}
10223 @item @emph{Arguments}:
10224 @multitable @columnfractions .15 .70
10225 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
10226 type or a scalar @code{LOGICAL} type.
10227 @item @var{J} @tab The type shall be the same as the type of @var{J}.
10230 @item @emph{Return value}:
10231 The return type is either a scalar @code{INTEGER} or a scalar
10232 @code{LOGICAL}. If the kind type parameters differ, then the
10233 smaller kind type is implicitly converted to larger kind, and the
10234 return has the larger kind.
10236 @item @emph{Example}:
10239 LOGICAL :: T = .TRUE., F = .FALSE.
10241 DATA a / Z'F' /, b / Z'3' /
10243 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
10244 WRITE (*,*) OR(a, b)
10248 @item @emph{See also}:
10249 Fortran 95 elemental function: @ref{IOR}
10255 @section @code{PACK} --- Pack an array into an array of rank one
10257 @cindex array, packing
10258 @cindex array, reduce dimension
10259 @cindex array, gather elements
10262 @item @emph{Description}:
10263 Stores the elements of @var{ARRAY} in an array of rank one.
10265 The beginning of the resulting array is made up of elements whose @var{MASK}
10266 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
10269 @item @emph{Standard}:
10270 Fortran 95 and later
10272 @item @emph{Class}:
10273 Transformational function
10275 @item @emph{Syntax}:
10276 @code{RESULT = PACK(ARRAY, MASK[,VECTOR])}
10278 @item @emph{Arguments}:
10279 @multitable @columnfractions .15 .70
10280 @item @var{ARRAY} @tab Shall be an array of any type.
10281 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
10282 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
10284 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
10285 as @var{ARRAY} and of rank one. If present, the number of elements in
10286 @var{VECTOR} shall be equal to or greater than the number of true elements
10287 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
10288 @var{VECTOR} shall be equal to or greater than the number of elements in
10292 @item @emph{Return value}:
10293 The result is an array of rank one and the same type as that of @var{ARRAY}.
10294 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
10295 number of @code{TRUE} values in @var{MASK} otherwise.
10297 @item @emph{Example}:
10298 Gathering nonzero elements from an array:
10300 PROGRAM test_pack_1
10302 m = (/ 1, 0, 0, 0, 5, 0 /)
10303 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
10307 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
10309 PROGRAM test_pack_2
10311 m = (/ 1, 0, 0, 2 /)
10312 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
10316 @item @emph{See also}:
10323 @section @code{PARITY} --- Reduction with exclusive OR
10326 @cindex Reduction, XOR
10327 @cindex XOR reduction
10330 @item @emph{Description}:
10331 Calculates the parity, i.e. the reduction using @code{.XOR.},
10332 of @var{MASK} along dimension @var{DIM}.
10334 @item @emph{Standard}:
10335 Fortran 2008 and later
10337 @item @emph{Class}:
10338 Transformational function
10340 @item @emph{Syntax}:
10341 @multitable @columnfractions .80
10342 @item @code{RESULT = PARITY(MASK[, DIM])}
10345 @item @emph{Arguments}:
10346 @multitable @columnfractions .15 .70
10347 @item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL}
10348 @item @var{DIM} @tab (Optional) shall be a scalar of type
10349 @code{INTEGER} with a value in the range from 1 to n, where n
10350 equals the rank of @var{MASK}.
10353 @item @emph{Return value}:
10354 The result is of the same type as @var{MASK}.
10356 If @var{DIM} is absent, a scalar with the parity of all elements in
10357 @var{MASK} is returned, i.e. true if an odd number of elements is
10358 @code{.true.} and false otherwise. If @var{DIM} is present, an array
10359 of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
10360 and a shape similar to that of @var{MASK} with dimension @var{DIM}
10361 dropped is returned.
10363 @item @emph{Example}:
10366 LOGICAL :: x(2) = [ .true., .false. ]
10367 print *, PARITY(x) ! prints "T" (true).
10375 @section @code{PERROR} --- Print system error message
10377 @cindex system, error handling
10380 @item @emph{Description}:
10381 Prints (on the C @code{stderr} stream) a newline-terminated error
10382 message corresponding to the last system error. This is prefixed by
10383 @var{STRING}, a colon and a space. See @code{perror(3)}.
10385 @item @emph{Standard}:
10388 @item @emph{Class}:
10391 @item @emph{Syntax}:
10392 @code{CALL PERROR(STRING)}
10394 @item @emph{Arguments}:
10395 @multitable @columnfractions .15 .70
10396 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
10400 @item @emph{See also}:
10407 @section @code{POPCNT} --- Number of bits set
10409 @cindex binary representation
10413 @item @emph{Description}:
10414 @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
10415 representation of @code{I}.
10417 @item @emph{Standard}:
10418 Fortran 2008 and later
10420 @item @emph{Class}:
10423 @item @emph{Syntax}:
10424 @code{RESULT = POPCNT(I)}
10426 @item @emph{Arguments}:
10427 @multitable @columnfractions .15 .70
10428 @item @var{I} @tab Shall be of type @code{INTEGER}.
10431 @item @emph{Return value}:
10432 The return value is of type @code{INTEGER} and of the default integer
10435 @item @emph{See also}:
10436 @ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ}
10438 @item @emph{Example}:
10440 program test_population
10441 print *, popcnt(127), poppar(127)
10442 print *, popcnt(huge(0_4)), poppar(huge(0_4))
10443 print *, popcnt(huge(0_8)), poppar(huge(0_8))
10444 end program test_population
10450 @section @code{POPPAR} --- Parity of the number of bits set
10452 @cindex binary representation
10456 @item @emph{Description}:
10457 @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
10458 of the number of bits set ('1' bits) in the binary representation of
10459 @code{I}. It is equal to 0 if @code{I} has an even number of bits set,
10460 and 1 for an odd number of '1' bits.
10462 @item @emph{Standard}:
10463 Fortran 2008 and later
10465 @item @emph{Class}:
10468 @item @emph{Syntax}:
10469 @code{RESULT = POPPAR(I)}
10471 @item @emph{Arguments}:
10472 @multitable @columnfractions .15 .70
10473 @item @var{I} @tab Shall be of type @code{INTEGER}.
10476 @item @emph{Return value}:
10477 The return value is of type @code{INTEGER} and of the default integer
10480 @item @emph{See also}:
10481 @ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ}
10483 @item @emph{Example}:
10485 program test_population
10486 print *, popcnt(127), poppar(127)
10487 print *, popcnt(huge(0_4)), poppar(huge(0_4))
10488 print *, popcnt(huge(0_8)), poppar(huge(0_8))
10489 end program test_population
10496 @section @code{PRECISION} --- Decimal precision of a real kind
10498 @cindex model representation, precision
10501 @item @emph{Description}:
10502 @code{PRECISION(X)} returns the decimal precision in the model of the
10505 @item @emph{Standard}:
10506 Fortran 95 and later
10508 @item @emph{Class}:
10511 @item @emph{Syntax}:
10512 @code{RESULT = PRECISION(X)}
10514 @item @emph{Arguments}:
10515 @multitable @columnfractions .15 .70
10516 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
10519 @item @emph{Return value}:
10520 The return value is of type @code{INTEGER} and of the default integer
10523 @item @emph{See also}:
10524 @ref{SELECTED_REAL_KIND}, @ref{RANGE}
10526 @item @emph{Example}:
10528 program prec_and_range
10529 real(kind=4) :: x(2)
10530 complex(kind=8) :: y
10532 print *, precision(x), range(x)
10533 print *, precision(y), range(y)
10534 end program prec_and_range
10541 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
10545 @item @emph{Description}:
10546 Determines whether an optional dummy argument is present.
10548 @item @emph{Standard}:
10549 Fortran 95 and later
10551 @item @emph{Class}:
10554 @item @emph{Syntax}:
10555 @code{RESULT = PRESENT(A)}
10557 @item @emph{Arguments}:
10558 @multitable @columnfractions .15 .70
10559 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
10560 value, or a dummy procedure. It shall be the name of an optional dummy argument
10561 accessible within the current subroutine or function.
10564 @item @emph{Return value}:
10565 Returns either @code{TRUE} if the optional argument @var{A} is present, or
10566 @code{FALSE} otherwise.
10568 @item @emph{Example}:
10570 PROGRAM test_present
10571 WRITE(*,*) f(), f(42) ! "F T"
10573 LOGICAL FUNCTION f(x)
10574 INTEGER, INTENT(IN), OPTIONAL :: x
10584 @section @code{PRODUCT} --- Product of array elements
10586 @cindex array, product
10587 @cindex array, multiply elements
10588 @cindex array, conditionally multiply elements
10589 @cindex multiply array elements
10592 @item @emph{Description}:
10593 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
10594 the corresponding element in @var{MASK} is @code{TRUE}.
10596 @item @emph{Standard}:
10597 Fortran 95 and later
10599 @item @emph{Class}:
10600 Transformational function
10602 @item @emph{Syntax}:
10603 @multitable @columnfractions .80
10604 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
10605 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
10608 @item @emph{Arguments}:
10609 @multitable @columnfractions .15 .70
10610 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
10611 @code{REAL} or @code{COMPLEX}.
10612 @item @var{DIM} @tab (Optional) shall be a scalar of type
10613 @code{INTEGER} with a value in the range from 1 to n, where n
10614 equals the rank of @var{ARRAY}.
10615 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
10616 and either be a scalar or an array of the same shape as @var{ARRAY}.
10619 @item @emph{Return value}:
10620 The result is of the same type as @var{ARRAY}.
10622 If @var{DIM} is absent, a scalar with the product of all elements in
10623 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
10624 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
10625 dimension @var{DIM} dropped is returned.
10628 @item @emph{Example}:
10630 PROGRAM test_product
10631 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
10632 print *, PRODUCT(x) ! all elements, product = 120
10633 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
10637 @item @emph{See also}:
10644 @section @code{RADIX} --- Base of a model number
10646 @cindex model representation, base
10647 @cindex model representation, radix
10650 @item @emph{Description}:
10651 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
10653 @item @emph{Standard}:
10654 Fortran 95 and later
10656 @item @emph{Class}:
10659 @item @emph{Syntax}:
10660 @code{RESULT = RADIX(X)}
10662 @item @emph{Arguments}:
10663 @multitable @columnfractions .15 .70
10664 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
10667 @item @emph{Return value}:
10668 The return value is a scalar of type @code{INTEGER} and of the default
10671 @item @emph{See also}:
10672 @ref{SELECTED_REAL_KIND}
10674 @item @emph{Example}:
10677 print *, "The radix for the default integer kind is", radix(0)
10678 print *, "The radix for the default real kind is", radix(0.0)
10679 end program test_radix
10687 @section @code{RAN} --- Real pseudo-random number
10689 @cindex random number generation
10692 @item @emph{Description}:
10693 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
10694 provided as an alias for @code{RAND}. See @ref{RAND} for complete
10697 @item @emph{Standard}:
10700 @item @emph{Class}:
10703 @item @emph{See also}:
10704 @ref{RAND}, @ref{RANDOM_NUMBER}
10710 @section @code{RAND} --- Real pseudo-random number
10712 @cindex random number generation
10715 @item @emph{Description}:
10716 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
10717 distribution between 0 and 1. If @var{FLAG} is 0, the next number
10718 in the current sequence is returned; if @var{FLAG} is 1, the generator
10719 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
10720 it is used as a new seed with @code{SRAND}.
10722 This intrinsic routine is provided for backwards compatibility with
10723 GNU Fortran 77. It implements a simple modulo generator as provided
10724 by @command{g77}. For new code, one should consider the use of
10725 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
10727 @item @emph{Standard}:
10730 @item @emph{Class}:
10733 @item @emph{Syntax}:
10734 @code{RESULT = RAND(I)}
10736 @item @emph{Arguments}:
10737 @multitable @columnfractions .15 .70
10738 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
10741 @item @emph{Return value}:
10742 The return value is of @code{REAL} type and the default kind.
10744 @item @emph{Example}:
10747 integer,parameter :: seed = 86456
10750 print *, rand(), rand(), rand(), rand()
10751 print *, rand(seed), rand(), rand(), rand()
10752 end program test_rand
10755 @item @emph{See also}:
10756 @ref{SRAND}, @ref{RANDOM_NUMBER}
10762 @node RANDOM_NUMBER
10763 @section @code{RANDOM_NUMBER} --- Pseudo-random number
10764 @fnindex RANDOM_NUMBER
10765 @cindex random number generation
10768 @item @emph{Description}:
10769 Returns a single pseudorandom number or an array of pseudorandom numbers
10770 from the uniform distribution over the range @math{ 0 \leq x < 1}.
10772 The runtime-library implements George Marsaglia's KISS (Keep It Simple
10773 Stupid) random number generator (RNG). This RNG combines:
10775 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
10776 with a period of @math{2^{32}},
10777 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
10778 @item Two 16-bit multiply-with-carry generators with a period of
10779 @math{597273182964842497 > 2^{59}}.
10781 The overall period exceeds @math{2^{123}}.
10783 Please note, this RNG is thread safe if used within OpenMP directives,
10784 i.e., its state will be consistent while called from multiple threads.
10785 However, the KISS generator does not create random numbers in parallel
10786 from multiple sources, but in sequence from a single source. If an
10787 OpenMP-enabled application heavily relies on random numbers, one should
10788 consider employing a dedicated parallel random number generator instead.
10790 @item @emph{Standard}:
10791 Fortran 95 and later
10793 @item @emph{Class}:
10796 @item @emph{Syntax}:
10797 @code{RANDOM_NUMBER(HARVEST)}
10799 @item @emph{Arguments}:
10800 @multitable @columnfractions .15 .70
10801 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
10804 @item @emph{Example}:
10806 program test_random_number
10808 CALL init_random_seed() ! see example of RANDOM_SEED
10809 CALL RANDOM_NUMBER(r)
10813 @item @emph{See also}:
10820 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
10821 @fnindex RANDOM_SEED
10822 @cindex random number generation, seeding
10823 @cindex seeding a random number generator
10826 @item @emph{Description}:
10827 Restarts or queries the state of the pseudorandom number generator used by
10828 @code{RANDOM_NUMBER}.
10830 If @code{RANDOM_SEED} is called without arguments, it is initialized
10831 to a default state. The example below shows how to initialize the
10832 random seed with a varying seed in order to ensure a different random
10833 number sequence for each invocation of the program. Note that setting
10834 any of the seed values to zero should be avoided as it can result in
10835 poor quality random numbers being generated.
10837 @item @emph{Standard}:
10838 Fortran 95 and later
10840 @item @emph{Class}:
10843 @item @emph{Syntax}:
10844 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
10846 @item @emph{Arguments}:
10847 @multitable @columnfractions .15 .70
10848 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
10849 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
10850 of the arrays used with the @var{PUT} and @var{GET} arguments.
10851 @item @var{PUT} @tab (Optional) Shall be an array of type default
10852 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
10853 the array must be larger than or equal to the number returned by the
10854 @var{SIZE} argument.
10855 @item @var{GET} @tab (Optional) Shall be an array of type default
10856 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
10857 of the array must be larger than or equal to the number returned by
10858 the @var{SIZE} argument.
10861 @item @emph{Example}:
10863 subroutine init_random_seed()
10864 use iso_fortran_env, only: int64
10866 integer, allocatable :: seed(:)
10867 integer :: i, n, un, istat, dt(8), pid
10868 integer(int64) :: t
10870 call random_seed(size = n)
10872 ! First try if the OS provides a random number generator
10873 open(newunit=un, file="/dev/urandom", access="stream", &
10874 form="unformatted", action="read", status="old", iostat=istat)
10875 if (istat == 0) then
10879 ! Fallback to XOR:ing the current time and pid. The PID is
10880 ! useful in case one launches multiple instances of the same
10881 ! program in parallel.
10882 call system_clock(t)
10884 call date_and_time(values=dt)
10885 t = (dt(1) - 1970) * 365_int64 * 24 * 60 * 60 * 1000 &
10886 + dt(2) * 31_int64 * 24 * 60 * 60 * 1000 &
10887 + dt(3) * 24_int64 * 60 * 60 * 1000 &
10888 + dt(5) * 60 * 60 * 1000 &
10889 + dt(6) * 60 * 1000 + dt(7) * 1000 &
10893 t = ieor(t, int(pid, kind(t)))
10898 call random_seed(put=seed)
10900 ! This simple PRNG might not be good enough for real work, but is
10901 ! sufficient for seeding a better PRNG.
10904 integer(int64) :: s
10908 s = mod(s, 4294967296_int64)
10910 s = mod(s * 279470273_int64, 4294967291_int64)
10911 lcg = int(mod(s, int(huge(0), int64)), kind(0))
10913 end subroutine init_random_seed
10916 @item @emph{See also}:
10917 @ref{RANDOM_NUMBER}
10923 @section @code{RANGE} --- Decimal exponent range
10925 @cindex model representation, range
10928 @item @emph{Description}:
10929 @code{RANGE(X)} returns the decimal exponent range in the model of the
10932 @item @emph{Standard}:
10933 Fortran 95 and later
10935 @item @emph{Class}:
10938 @item @emph{Syntax}:
10939 @code{RESULT = RANGE(X)}
10941 @item @emph{Arguments}:
10942 @multitable @columnfractions .15 .70
10943 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
10947 @item @emph{Return value}:
10948 The return value is of type @code{INTEGER} and of the default integer
10951 @item @emph{See also}:
10952 @ref{SELECTED_REAL_KIND}, @ref{PRECISION}
10954 @item @emph{Example}:
10955 See @code{PRECISION} for an example.
10961 @section @code{RANK} --- Rank of a data object
10966 @item @emph{Description}:
10967 @code{RANK(A)} returns the rank of a scalar or array data object.
10969 @item @emph{Standard}:
10970 Technical Specification (TS) 29113
10972 @item @emph{Class}:
10975 @item @emph{Syntax}:
10976 @code{RESULT = RANK(A)}
10978 @item @emph{Arguments}:
10979 @multitable @columnfractions .15 .70
10980 @item @var{A} @tab can be of any type
10983 @item @emph{Return value}:
10984 The return value is of type @code{INTEGER} and of the default integer
10985 kind. For arrays, their rank is returned; for scalars zero is returned.
10987 @item @emph{Example}:
10991 real, allocatable :: b(:,:)
10993 print *, rank(a), rank(b) ! Prints: 0 2
10994 end program test_rank
11002 @section @code{REAL} --- Convert to real type
11008 @cindex conversion, to real
11009 @cindex complex numbers, real part
11012 @item @emph{Description}:
11013 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
11014 @code{REALPART} function is provided for compatibility with @command{g77},
11015 and its use is strongly discouraged.
11017 @item @emph{Standard}:
11018 Fortran 77 and later
11020 @item @emph{Class}:
11023 @item @emph{Syntax}:
11024 @multitable @columnfractions .80
11025 @item @code{RESULT = REAL(A [, KIND])}
11026 @item @code{RESULT = REALPART(Z)}
11029 @item @emph{Arguments}:
11030 @multitable @columnfractions .15 .70
11031 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
11033 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11034 expression indicating the kind parameter of the result.
11037 @item @emph{Return value}:
11038 These functions return a @code{REAL} variable or array under
11039 the following rules:
11043 @code{REAL(A)} is converted to a default real type if @var{A} is an
11044 integer or real variable.
11046 @code{REAL(A)} is converted to a real type with the kind type parameter
11047 of @var{A} if @var{A} is a complex variable.
11049 @code{REAL(A, KIND)} is converted to a real type with kind type
11050 parameter @var{KIND} if @var{A} is a complex, integer, or real
11054 @item @emph{Example}:
11057 complex :: x = (1.0, 2.0)
11058 print *, real(x), real(x,8), realpart(x)
11059 end program test_real
11062 @item @emph{Specific names}:
11063 @multitable @columnfractions .20 .20 .20 .25
11064 @item Name @tab Argument @tab Return type @tab Standard
11065 @item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later
11066 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension
11067 @item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab Fortran 77 and later
11071 @item @emph{See also}:
11079 @section @code{RENAME} --- Rename a file
11081 @cindex file system, rename file
11084 @item @emph{Description}:
11085 Renames a file from file @var{PATH1} to @var{PATH2}. A null
11086 character (@code{CHAR(0)}) can be used to mark the end of the names in
11087 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
11088 names are ignored. If the @var{STATUS} argument is supplied, it
11089 contains 0 on success or a nonzero error code upon return; see
11092 This intrinsic is provided in both subroutine and function forms;
11093 however, only one form can be used in any given program unit.
11095 @item @emph{Standard}:
11098 @item @emph{Class}:
11099 Subroutine, function
11101 @item @emph{Syntax}:
11102 @multitable @columnfractions .80
11103 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
11104 @item @code{STATUS = RENAME(PATH1, PATH2)}
11107 @item @emph{Arguments}:
11108 @multitable @columnfractions .15 .70
11109 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
11110 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
11111 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11114 @item @emph{See also}:
11122 @section @code{REPEAT} --- Repeated string concatenation
11124 @cindex string, repeat
11125 @cindex string, concatenate
11128 @item @emph{Description}:
11129 Concatenates @var{NCOPIES} copies of a string.
11131 @item @emph{Standard}:
11132 Fortran 95 and later
11134 @item @emph{Class}:
11135 Transformational function
11137 @item @emph{Syntax}:
11138 @code{RESULT = REPEAT(STRING, NCOPIES)}
11140 @item @emph{Arguments}:
11141 @multitable @columnfractions .15 .70
11142 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
11143 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
11146 @item @emph{Return value}:
11147 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
11150 @item @emph{Example}:
11152 program test_repeat
11153 write(*,*) repeat("x", 5) ! "xxxxx"
11161 @section @code{RESHAPE} --- Function to reshape an array
11163 @cindex array, change dimensions
11164 @cindex array, transmogrify
11167 @item @emph{Description}:
11168 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
11169 the new array may be padded with elements from @var{PAD} or permuted
11170 as defined by @var{ORDER}.
11172 @item @emph{Standard}:
11173 Fortran 95 and later
11175 @item @emph{Class}:
11176 Transformational function
11178 @item @emph{Syntax}:
11179 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
11181 @item @emph{Arguments}:
11182 @multitable @columnfractions .15 .70
11183 @item @var{SOURCE} @tab Shall be an array of any type.
11184 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
11185 array of rank one. Its values must be positive or zero.
11186 @item @var{PAD} @tab (Optional) shall be an array of the same
11187 type as @var{SOURCE}.
11188 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
11189 and an array of the same shape as @var{SHAPE}. Its values shall
11190 be a permutation of the numbers from 1 to n, where n is the size of
11191 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
11195 @item @emph{Return value}:
11196 The result is an array of shape @var{SHAPE} with the same type as
11199 @item @emph{Example}:
11201 PROGRAM test_reshape
11202 INTEGER, DIMENSION(4) :: x
11203 WRITE(*,*) SHAPE(x) ! prints "4"
11204 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
11208 @item @emph{See also}:
11215 @section @code{RRSPACING} --- Reciprocal of the relative spacing
11217 @cindex real number, relative spacing
11218 @cindex floating point, relative spacing
11222 @item @emph{Description}:
11223 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
11224 model numbers near @var{X}.
11226 @item @emph{Standard}:
11227 Fortran 95 and later
11229 @item @emph{Class}:
11232 @item @emph{Syntax}:
11233 @code{RESULT = RRSPACING(X)}
11235 @item @emph{Arguments}:
11236 @multitable @columnfractions .15 .70
11237 @item @var{X} @tab Shall be of type @code{REAL}.
11240 @item @emph{Return value}:
11241 The return value is of the same type and kind as @var{X}.
11242 The value returned is equal to
11243 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
11245 @item @emph{See also}:
11252 @section @code{RSHIFT} --- Right shift bits
11254 @cindex bits, shift right
11257 @item @emph{Description}:
11258 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
11259 bits shifted right by @var{SHIFT} places. If the absolute value of
11260 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11261 Bits shifted out from the right end are lost. The fill is arithmetic: the
11262 bits shifted in from the left end are equal to the leftmost bit, which in
11263 two's complement representation is the sign bit.
11265 This function has been superseded by the @code{SHIFTA} intrinsic, which
11266 is standard in Fortran 2008 and later.
11268 @item @emph{Standard}:
11271 @item @emph{Class}:
11274 @item @emph{Syntax}:
11275 @code{RESULT = RSHIFT(I, SHIFT)}
11277 @item @emph{Arguments}:
11278 @multitable @columnfractions .15 .70
11279 @item @var{I} @tab The type shall be @code{INTEGER}.
11280 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11283 @item @emph{Return value}:
11284 The return value is of type @code{INTEGER} and of the same kind as
11287 @item @emph{See also}:
11288 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}, @ref{SHIFTA}, @ref{SHIFTR},
11296 @section @code{SAME_TYPE_AS} --- Query dynamic types for equality
11297 @fnindex SAME_TYPE_AS
11300 @item @emph{Description}:
11301 Query dynamic types for equality.
11303 @item @emph{Standard}:
11304 Fortran 2003 and later
11306 @item @emph{Class}:
11309 @item @emph{Syntax}:
11310 @code{RESULT = SAME_TYPE_AS(A, B)}
11312 @item @emph{Arguments}:
11313 @multitable @columnfractions .15 .70
11314 @item @var{A} @tab Shall be an object of extensible declared type or
11315 unlimited polymorphic.
11316 @item @var{B} @tab Shall be an object of extensible declared type or
11317 unlimited polymorphic.
11320 @item @emph{Return value}:
11321 The return value is a scalar of type default logical. It is true if and
11322 only if the dynamic type of A is the same as the dynamic type of B.
11324 @item @emph{See also}:
11325 @ref{EXTENDS_TYPE_OF}
11332 @section @code{SCALE} --- Scale a real value
11334 @cindex real number, scale
11335 @cindex floating point, scale
11338 @item @emph{Description}:
11339 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
11341 @item @emph{Standard}:
11342 Fortran 95 and later
11344 @item @emph{Class}:
11347 @item @emph{Syntax}:
11348 @code{RESULT = SCALE(X, I)}
11350 @item @emph{Arguments}:
11351 @multitable @columnfractions .15 .70
11352 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
11353 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
11356 @item @emph{Return value}:
11357 The return value is of the same type and kind as @var{X}.
11358 Its value is @code{X * RADIX(X)**I}.
11360 @item @emph{Example}:
11363 real :: x = 178.1387e-4
11365 print *, scale(x,i), x*radix(x)**i
11366 end program test_scale
11374 @section @code{SCAN} --- Scan a string for the presence of a set of characters
11376 @cindex string, find subset
11379 @item @emph{Description}:
11380 Scans a @var{STRING} for any of the characters in a @var{SET}
11383 If @var{BACK} is either absent or equals @code{FALSE}, this function
11384 returns the position of the leftmost character of @var{STRING} that is
11385 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
11386 is returned. If no character of @var{SET} is found in @var{STRING}, the
11389 @item @emph{Standard}:
11390 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11392 @item @emph{Class}:
11395 @item @emph{Syntax}:
11396 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
11398 @item @emph{Arguments}:
11399 @multitable @columnfractions .15 .70
11400 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
11401 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
11402 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
11403 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11404 expression indicating the kind parameter of the result.
11407 @item @emph{Return value}:
11408 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11409 @var{KIND} is absent, the return value is of default integer kind.
11411 @item @emph{Example}:
11414 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
11415 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
11416 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
11420 @item @emph{See also}:
11421 @ref{INDEX intrinsic}, @ref{VERIFY}
11427 @section @code{SECNDS} --- Time function
11429 @cindex time, elapsed
11430 @cindex elapsed time
11433 @item @emph{Description}:
11434 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
11435 @var{X} is a reference time, also in seconds. If this is zero, the time in
11436 seconds from midnight is returned. This function is non-standard and its
11437 use is discouraged.
11439 @item @emph{Standard}:
11442 @item @emph{Class}:
11445 @item @emph{Syntax}:
11446 @code{RESULT = SECNDS (X)}
11448 @item @emph{Arguments}:
11449 @multitable @columnfractions .15 .70
11450 @item @var{T} @tab Shall be of type @code{REAL(4)}.
11451 @item @var{X} @tab Shall be of type @code{REAL(4)}.
11454 @item @emph{Return value}:
11457 @item @emph{Example}:
11459 program test_secnds
11462 print *, secnds (0.0) ! seconds since midnight
11463 t1 = secnds (0.0) ! reference time
11464 do i = 1, 10000000 ! do something
11466 t2 = secnds (t1) ! elapsed time
11467 print *, "Something took ", t2, " seconds."
11468 end program test_secnds
11475 @section @code{SECOND} --- CPU time function
11477 @cindex time, elapsed
11478 @cindex elapsed time
11481 @item @emph{Description}:
11482 Returns a @code{REAL(4)} value representing the elapsed CPU time in
11483 seconds. This provides the same functionality as the standard
11484 @code{CPU_TIME} intrinsic, and is only included for backwards
11487 This intrinsic is provided in both subroutine and function forms;
11488 however, only one form can be used in any given program unit.
11490 @item @emph{Standard}:
11493 @item @emph{Class}:
11494 Subroutine, function
11496 @item @emph{Syntax}:
11497 @multitable @columnfractions .80
11498 @item @code{CALL SECOND(TIME)}
11499 @item @code{TIME = SECOND()}
11502 @item @emph{Arguments}:
11503 @multitable @columnfractions .15 .70
11504 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
11507 @item @emph{Return value}:
11508 In either syntax, @var{TIME} is set to the process's current runtime in
11511 @item @emph{See also}:
11518 @node SELECTED_CHAR_KIND
11519 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
11520 @fnindex SELECTED_CHAR_KIND
11521 @cindex character kind
11522 @cindex kind, character
11525 @item @emph{Description}:
11527 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
11528 set named @var{NAME}, if a character set with such a name is supported,
11529 or @math{-1} otherwise. Currently, supported character sets include
11530 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
11531 (Universal Character Set, UCS-4) which is commonly known as Unicode.
11533 @item @emph{Standard}:
11534 Fortran 2003 and later
11536 @item @emph{Class}:
11537 Transformational function
11539 @item @emph{Syntax}:
11540 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
11542 @item @emph{Arguments}:
11543 @multitable @columnfractions .15 .70
11544 @item @var{NAME} @tab Shall be a scalar and of the default character type.
11547 @item @emph{Example}:
11549 program character_kind
11550 use iso_fortran_env
11552 integer, parameter :: ascii = selected_char_kind ("ascii")
11553 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646')
11555 character(kind=ascii, len=26) :: alphabet
11556 character(kind=ucs4, len=30) :: hello_world
11558 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
11559 hello_world = ucs4_'Hello World and Ni Hao -- ' &
11560 // char (int (z'4F60'), ucs4) &
11561 // char (int (z'597D'), ucs4)
11563 write (*,*) alphabet
11565 open (output_unit, encoding='UTF-8')
11566 write (*,*) trim (hello_world)
11567 end program character_kind
11573 @node SELECTED_INT_KIND
11574 @section @code{SELECTED_INT_KIND} --- Choose integer kind
11575 @fnindex SELECTED_INT_KIND
11576 @cindex integer kind
11577 @cindex kind, integer
11580 @item @emph{Description}:
11581 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
11582 type that can represent all values ranging from @math{-10^R} (exclusive)
11583 to @math{10^R} (exclusive). If there is no integer kind that accommodates
11584 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
11586 @item @emph{Standard}:
11587 Fortran 95 and later
11589 @item @emph{Class}:
11590 Transformational function
11592 @item @emph{Syntax}:
11593 @code{RESULT = SELECTED_INT_KIND(R)}
11595 @item @emph{Arguments}:
11596 @multitable @columnfractions .15 .70
11597 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
11600 @item @emph{Example}:
11602 program large_integers
11603 integer,parameter :: k5 = selected_int_kind(5)
11604 integer,parameter :: k15 = selected_int_kind(15)
11605 integer(kind=k5) :: i5
11606 integer(kind=k15) :: i15
11608 print *, huge(i5), huge(i15)
11610 ! The following inequalities are always true
11611 print *, huge(i5) >= 10_k5**5-1
11612 print *, huge(i15) >= 10_k15**15-1
11613 end program large_integers
11619 @node SELECTED_REAL_KIND
11620 @section @code{SELECTED_REAL_KIND} --- Choose real kind
11621 @fnindex SELECTED_REAL_KIND
11624 @cindex radix, real
11627 @item @emph{Description}:
11628 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
11629 with decimal precision of at least @code{P} digits, exponent range of
11630 at least @code{R}, and with a radix of @code{RADIX}.
11632 @item @emph{Standard}:
11633 Fortran 95 and later, with @code{RADIX} Fortran 2008 or later
11635 @item @emph{Class}:
11636 Transformational function
11638 @item @emph{Syntax}:
11639 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
11641 @item @emph{Arguments}:
11642 @multitable @columnfractions .15 .70
11643 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
11644 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
11645 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
11647 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
11648 be present; since Fortran 2008, they are assumed to be zero if absent.
11650 @item @emph{Return value}:
11652 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
11653 a real data type with decimal precision of at least @code{P} digits, a
11654 decimal exponent range of at least @code{R}, and with the requested
11655 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
11656 any radix can be returned. If more than one real data type meet the
11657 criteria, the kind of the data type with the smallest decimal precision
11658 is returned. If no real data type matches the criteria, the result is
11660 @item -1 if the processor does not support a real data type with a
11661 precision greater than or equal to @code{P}, but the @code{R} and
11662 @code{RADIX} requirements can be fulfilled
11663 @item -2 if the processor does not support a real type with an exponent
11664 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
11666 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
11668 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
11670 @item -5 if there is no real type with the given @code{RADIX}
11673 @item @emph{See also}:
11674 @ref{PRECISION}, @ref{RANGE}, @ref{RADIX}
11676 @item @emph{Example}:
11679 integer,parameter :: p6 = selected_real_kind(6)
11680 integer,parameter :: p10r100 = selected_real_kind(10,100)
11681 integer,parameter :: r400 = selected_real_kind(r=400)
11683 real(kind=p10r100) :: y
11684 real(kind=r400) :: z
11686 print *, precision(x), range(x)
11687 print *, precision(y), range(y)
11688 print *, precision(z), range(z)
11689 end program real_kinds
11696 @section @code{SET_EXPONENT} --- Set the exponent of the model
11697 @fnindex SET_EXPONENT
11698 @cindex real number, set exponent
11699 @cindex floating point, set exponent
11702 @item @emph{Description}:
11703 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
11704 is that that of @var{X} and whose exponent part is @var{I}.
11706 @item @emph{Standard}:
11707 Fortran 95 and later
11709 @item @emph{Class}:
11712 @item @emph{Syntax}:
11713 @code{RESULT = SET_EXPONENT(X, I)}
11715 @item @emph{Arguments}:
11716 @multitable @columnfractions .15 .70
11717 @item @var{X} @tab Shall be of type @code{REAL}.
11718 @item @var{I} @tab Shall be of type @code{INTEGER}.
11721 @item @emph{Return value}:
11722 The return value is of the same type and kind as @var{X}.
11723 The real number whose fractional part
11724 is that that of @var{X} and whose exponent part if @var{I} is returned;
11725 it is @code{FRACTION(X) * RADIX(X)**I}.
11727 @item @emph{Example}:
11729 PROGRAM test_setexp
11730 REAL :: x = 178.1387e-4
11732 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
11741 @section @code{SHAPE} --- Determine the shape of an array
11743 @cindex array, shape
11746 @item @emph{Description}:
11747 Determines the shape of an array.
11749 @item @emph{Standard}:
11750 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11752 @item @emph{Class}:
11755 @item @emph{Syntax}:
11756 @code{RESULT = SHAPE(SOURCE [, KIND])}
11758 @item @emph{Arguments}:
11759 @multitable @columnfractions .15 .70
11760 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
11761 If @var{SOURCE} is a pointer it must be associated and allocatable
11762 arrays must be allocated.
11763 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11764 expression indicating the kind parameter of the result.
11767 @item @emph{Return value}:
11768 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
11769 has dimensions. The elements of the resulting array correspond to the extend
11770 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
11771 the result is the rank one array of size zero. If @var{KIND} is absent, the
11772 return value has the default integer kind otherwise the specified kind.
11774 @item @emph{Example}:
11777 INTEGER, DIMENSION(-1:1, -1:2) :: A
11778 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
11779 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
11783 @item @emph{See also}:
11784 @ref{RESHAPE}, @ref{SIZE}
11790 @section @code{SHIFTA} --- Right shift with fill
11792 @cindex bits, shift right
11793 @cindex shift, right with fill
11796 @item @emph{Description}:
11797 @code{SHIFTA} returns a value corresponding to @var{I} with all of the
11798 bits shifted right by @var{SHIFT} places. If the absolute value of
11799 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11800 Bits shifted out from the right end are lost. The fill is arithmetic: the
11801 bits shifted in from the left end are equal to the leftmost bit, which in
11802 two's complement representation is the sign bit.
11804 @item @emph{Standard}:
11805 Fortran 2008 and later
11807 @item @emph{Class}:
11810 @item @emph{Syntax}:
11811 @code{RESULT = SHIFTA(I, SHIFT)}
11813 @item @emph{Arguments}:
11814 @multitable @columnfractions .15 .70
11815 @item @var{I} @tab The type shall be @code{INTEGER}.
11816 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11819 @item @emph{Return value}:
11820 The return value is of type @code{INTEGER} and of the same kind as
11823 @item @emph{See also}:
11824 @ref{SHIFTL}, @ref{SHIFTR}
11830 @section @code{SHIFTL} --- Left shift
11832 @cindex bits, shift left
11833 @cindex shift, left
11836 @item @emph{Description}:
11837 @code{SHIFTL} returns a value corresponding to @var{I} with all of the
11838 bits shifted left by @var{SHIFT} places. If the absolute value of
11839 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11840 Bits shifted out from the left end are lost, and bits shifted in from
11841 the right end are set to 0.
11843 @item @emph{Standard}:
11844 Fortran 2008 and later
11846 @item @emph{Class}:
11849 @item @emph{Syntax}:
11850 @code{RESULT = SHIFTL(I, SHIFT)}
11852 @item @emph{Arguments}:
11853 @multitable @columnfractions .15 .70
11854 @item @var{I} @tab The type shall be @code{INTEGER}.
11855 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11858 @item @emph{Return value}:
11859 The return value is of type @code{INTEGER} and of the same kind as
11862 @item @emph{See also}:
11863 @ref{SHIFTA}, @ref{SHIFTR}
11869 @section @code{SHIFTR} --- Right shift
11871 @cindex bits, shift right
11872 @cindex shift, right
11875 @item @emph{Description}:
11876 @code{SHIFTR} returns a value corresponding to @var{I} with all of the
11877 bits shifted right by @var{SHIFT} places. If the absolute value of
11878 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11879 Bits shifted out from the right end are lost, and bits shifted in from
11880 the left end are set to 0.
11882 @item @emph{Standard}:
11883 Fortran 2008 and later
11885 @item @emph{Class}:
11888 @item @emph{Syntax}:
11889 @code{RESULT = SHIFTR(I, SHIFT)}
11891 @item @emph{Arguments}:
11892 @multitable @columnfractions .15 .70
11893 @item @var{I} @tab The type shall be @code{INTEGER}.
11894 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11897 @item @emph{Return value}:
11898 The return value is of type @code{INTEGER} and of the same kind as
11901 @item @emph{See also}:
11902 @ref{SHIFTA}, @ref{SHIFTL}
11908 @section @code{SIGN} --- Sign copying function
11912 @cindex sign copying
11915 @item @emph{Description}:
11916 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
11918 @item @emph{Standard}:
11919 Fortran 77 and later
11921 @item @emph{Class}:
11924 @item @emph{Syntax}:
11925 @code{RESULT = SIGN(A, B)}
11927 @item @emph{Arguments}:
11928 @multitable @columnfractions .15 .70
11929 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
11930 @item @var{B} @tab Shall be of the same type and kind as @var{A}
11933 @item @emph{Return value}:
11934 The kind of the return value is that of @var{A} and @var{B}.
11935 If @math{B\ge 0} then the result is @code{ABS(A)}, else
11936 it is @code{-ABS(A)}.
11938 @item @emph{Example}:
11941 print *, sign(-12,1)
11942 print *, sign(-12,0)
11943 print *, sign(-12,-1)
11945 print *, sign(-12.,1.)
11946 print *, sign(-12.,0.)
11947 print *, sign(-12.,-1.)
11948 end program test_sign
11951 @item @emph{Specific names}:
11952 @multitable @columnfractions .20 .20 .20 .25
11953 @item Name @tab Arguments @tab Return type @tab Standard
11954 @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu
11955 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
11956 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu
11963 @section @code{SIGNAL} --- Signal handling subroutine (or function)
11965 @cindex system, signal handling
11968 @item @emph{Description}:
11969 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
11970 @var{HANDLER} to be executed with a single integer argument when signal
11971 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
11972 turn off handling of signal @var{NUMBER} or revert to its default
11973 action. See @code{signal(2)}.
11975 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
11976 is supplied, it is set to the value returned by @code{signal(2)}.
11978 @item @emph{Standard}:
11981 @item @emph{Class}:
11982 Subroutine, function
11984 @item @emph{Syntax}:
11985 @multitable @columnfractions .80
11986 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
11987 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
11990 @item @emph{Arguments}:
11991 @multitable @columnfractions .15 .70
11992 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
11993 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
11994 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
11995 @code{INTEGER}. It is @code{INTENT(IN)}.
11996 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
11997 integer. It has @code{INTENT(OUT)}.
11999 @c TODO: What should the interface of the handler be? Does it take arguments?
12001 @item @emph{Return value}:
12002 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
12004 @item @emph{Example}:
12006 program test_signal
12008 external handler_print
12010 call signal (12, handler_print)
12011 call signal (10, 1)
12014 end program test_signal
12021 @section @code{SIN} --- Sine function
12027 @cindex trigonometric function, sine
12031 @item @emph{Description}:
12032 @code{SIN(X)} computes the sine of @var{X}.
12034 @item @emph{Standard}:
12035 Fortran 77 and later
12037 @item @emph{Class}:
12040 @item @emph{Syntax}:
12041 @code{RESULT = SIN(X)}
12043 @item @emph{Arguments}:
12044 @multitable @columnfractions .15 .70
12045 @item @var{X} @tab The type shall be @code{REAL} or
12049 @item @emph{Return value}:
12050 The return value has same type and kind as @var{X}.
12052 @item @emph{Example}:
12057 end program test_sin
12060 @item @emph{Specific names}:
12061 @multitable @columnfractions .20 .20 .20 .25
12062 @item Name @tab Argument @tab Return type @tab Standard
12063 @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu
12064 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
12065 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
12066 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
12067 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
12070 @item @emph{See also}:
12077 @section @code{SINH} --- Hyperbolic sine function
12080 @cindex hyperbolic sine
12081 @cindex hyperbolic function, sine
12082 @cindex sine, hyperbolic
12085 @item @emph{Description}:
12086 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
12088 @item @emph{Standard}:
12089 Fortran 95 and later, for a complex argument Fortran 2008 or later
12091 @item @emph{Class}:
12094 @item @emph{Syntax}:
12095 @code{RESULT = SINH(X)}
12097 @item @emph{Arguments}:
12098 @multitable @columnfractions .15 .70
12099 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
12102 @item @emph{Return value}:
12103 The return value has same type and kind as @var{X}.
12105 @item @emph{Example}:
12108 real(8) :: x = - 1.0_8
12110 end program test_sinh
12113 @item @emph{Specific names}:
12114 @multitable @columnfractions .20 .20 .20 .25
12115 @item Name @tab Argument @tab Return type @tab Standard
12116 @item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
12117 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
12120 @item @emph{See also}:
12127 @section @code{SIZE} --- Determine the size of an array
12129 @cindex array, size
12130 @cindex array, number of elements
12131 @cindex array, count elements
12134 @item @emph{Description}:
12135 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
12136 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
12138 @item @emph{Standard}:
12139 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12141 @item @emph{Class}:
12144 @item @emph{Syntax}:
12145 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
12147 @item @emph{Arguments}:
12148 @multitable @columnfractions .15 .70
12149 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
12150 a pointer it must be associated and allocatable arrays must be allocated.
12151 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
12152 and its value shall be in the range from 1 to n, where n equals the rank
12154 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12155 expression indicating the kind parameter of the result.
12158 @item @emph{Return value}:
12159 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12160 @var{KIND} is absent, the return value is of default integer kind.
12162 @item @emph{Example}:
12165 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
12169 @item @emph{See also}:
12170 @ref{SHAPE}, @ref{RESHAPE}
12175 @section @code{SIZEOF} --- Size in bytes of an expression
12177 @cindex expression size
12178 @cindex size of an expression
12181 @item @emph{Description}:
12182 @code{SIZEOF(X)} calculates the number of bytes of storage the
12183 expression @code{X} occupies.
12185 @item @emph{Standard}:
12188 @item @emph{Class}:
12191 @item @emph{Syntax}:
12192 @code{N = SIZEOF(X)}
12194 @item @emph{Arguments}:
12195 @multitable @columnfractions .15 .70
12196 @item @var{X} @tab The argument shall be of any type, rank or shape.
12199 @item @emph{Return value}:
12200 The return value is of type integer and of the system-dependent kind
12201 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
12202 number of bytes occupied by the argument. If the argument has the
12203 @code{POINTER} attribute, the number of bytes of the storage area pointed
12204 to is returned. If the argument is of a derived type with @code{POINTER}
12205 or @code{ALLOCATABLE} components, the return value does not account for
12206 the sizes of the data pointed to by these components. If the argument is
12207 polymorphic, the size according to the declared type is returned. The argument
12208 may not be a procedure or procedure pointer.
12210 @item @emph{Example}:
12214 print *, (sizeof(s)/sizeof(r) == 5)
12217 The example will print @code{.TRUE.} unless you are using a platform
12218 where default @code{REAL} variables are unusually padded.
12220 @item @emph{See also}:
12221 @ref{C_SIZEOF}, @ref{STORAGE_SIZE}
12226 @section @code{SLEEP} --- Sleep for the specified number of seconds
12228 @cindex delayed execution
12231 @item @emph{Description}:
12232 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
12234 @item @emph{Standard}:
12237 @item @emph{Class}:
12240 @item @emph{Syntax}:
12241 @code{CALL SLEEP(SECONDS)}
12243 @item @emph{Arguments}:
12244 @multitable @columnfractions .15 .70
12245 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
12248 @item @emph{Example}:
12259 @section @code{SPACING} --- Smallest distance between two numbers of a given type
12261 @cindex real number, relative spacing
12262 @cindex floating point, relative spacing
12265 @item @emph{Description}:
12266 Determines the distance between the argument @var{X} and the nearest
12267 adjacent number of the same type.
12269 @item @emph{Standard}:
12270 Fortran 95 and later
12272 @item @emph{Class}:
12275 @item @emph{Syntax}:
12276 @code{RESULT = SPACING(X)}
12278 @item @emph{Arguments}:
12279 @multitable @columnfractions .15 .70
12280 @item @var{X} @tab Shall be of type @code{REAL}.
12283 @item @emph{Return value}:
12284 The result is of the same type as the input argument @var{X}.
12286 @item @emph{Example}:
12288 PROGRAM test_spacing
12289 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
12290 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
12292 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
12293 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
12297 @item @emph{See also}:
12304 @section @code{SPREAD} --- Add a dimension to an array
12306 @cindex array, increase dimension
12307 @cindex array, duplicate elements
12308 @cindex array, duplicate dimensions
12311 @item @emph{Description}:
12312 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
12313 dimension @var{DIM}.
12315 @item @emph{Standard}:
12316 Fortran 95 and later
12318 @item @emph{Class}:
12319 Transformational function
12321 @item @emph{Syntax}:
12322 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
12324 @item @emph{Arguments}:
12325 @multitable @columnfractions .15 .70
12326 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
12327 a rank less than seven.
12328 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
12329 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
12330 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
12333 @item @emph{Return value}:
12334 The result is an array of the same type as @var{SOURCE} and has rank n+1
12335 where n equals the rank of @var{SOURCE}.
12337 @item @emph{Example}:
12339 PROGRAM test_spread
12340 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
12341 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
12342 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
12346 @item @emph{See also}:
12353 @section @code{SQRT} --- Square-root function
12360 @cindex square-root
12363 @item @emph{Description}:
12364 @code{SQRT(X)} computes the square root of @var{X}.
12366 @item @emph{Standard}:
12367 Fortran 77 and later
12369 @item @emph{Class}:
12372 @item @emph{Syntax}:
12373 @code{RESULT = SQRT(X)}
12375 @item @emph{Arguments}:
12376 @multitable @columnfractions .15 .70
12377 @item @var{X} @tab The type shall be @code{REAL} or
12381 @item @emph{Return value}:
12382 The return value is of type @code{REAL} or @code{COMPLEX}.
12383 The kind type parameter is the same as @var{X}.
12385 @item @emph{Example}:
12388 real(8) :: x = 2.0_8
12389 complex :: z = (1.0, 2.0)
12392 end program test_sqrt
12395 @item @emph{Specific names}:
12396 @multitable @columnfractions .20 .20 .20 .25
12397 @item Name @tab Argument @tab Return type @tab Standard
12398 @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
12399 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
12400 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
12401 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
12402 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
12409 @section @code{SRAND} --- Reinitialize the random number generator
12411 @cindex random number generation, seeding
12412 @cindex seeding a random number generator
12415 @item @emph{Description}:
12416 @code{SRAND} reinitializes the pseudo-random number generator
12417 called by @code{RAND} and @code{IRAND}. The new seed used by the
12418 generator is specified by the required argument @var{SEED}.
12420 @item @emph{Standard}:
12423 @item @emph{Class}:
12426 @item @emph{Syntax}:
12427 @code{CALL SRAND(SEED)}
12429 @item @emph{Arguments}:
12430 @multitable @columnfractions .15 .70
12431 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
12434 @item @emph{Return value}:
12435 Does not return anything.
12437 @item @emph{Example}:
12438 See @code{RAND} and @code{IRAND} for examples.
12440 @item @emph{Notes}:
12441 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
12442 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
12443 to generate pseudo-random numbers. Please note that in
12444 GNU Fortran, these two sets of intrinsics (@code{RAND},
12445 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
12446 @code{RANDOM_SEED} on the other hand) access two independent
12447 pseudo-random number generators.
12449 @item @emph{See also}:
12450 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
12457 @section @code{STAT} --- Get file status
12459 @cindex file system, file status
12462 @item @emph{Description}:
12463 This function returns information about a file. No permissions are required on
12464 the file itself, but execute (search) permission is required on all of the
12465 directories in path that lead to the file.
12467 The elements that are obtained and stored in the array @code{VALUES}:
12468 @multitable @columnfractions .15 .70
12469 @item @code{VALUES(1)} @tab Device ID
12470 @item @code{VALUES(2)} @tab Inode number
12471 @item @code{VALUES(3)} @tab File mode
12472 @item @code{VALUES(4)} @tab Number of links
12473 @item @code{VALUES(5)} @tab Owner's uid
12474 @item @code{VALUES(6)} @tab Owner's gid
12475 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
12476 @item @code{VALUES(8)} @tab File size (bytes)
12477 @item @code{VALUES(9)} @tab Last access time
12478 @item @code{VALUES(10)} @tab Last modification time
12479 @item @code{VALUES(11)} @tab Last file status change time
12480 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
12481 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
12484 Not all these elements are relevant on all systems.
12485 If an element is not relevant, it is returned as 0.
12487 This intrinsic is provided in both subroutine and function forms; however,
12488 only one form can be used in any given program unit.
12490 @item @emph{Standard}:
12493 @item @emph{Class}:
12494 Subroutine, function
12496 @item @emph{Syntax}:
12497 @multitable @columnfractions .80
12498 @item @code{CALL STAT(NAME, VALUES [, STATUS])}
12499 @item @code{STATUS = STAT(NAME, VALUES)}
12502 @item @emph{Arguments}:
12503 @multitable @columnfractions .15 .70
12504 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
12505 default kind and a valid path within the file system.
12506 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
12507 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
12508 on success and a system specific error code otherwise.
12511 @item @emph{Example}:
12514 INTEGER, DIMENSION(13) :: buff
12517 CALL STAT("/etc/passwd", buff, status)
12519 IF (status == 0) THEN
12520 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
12521 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
12522 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
12523 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
12524 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
12525 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
12526 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
12527 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
12528 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
12529 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
12530 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
12531 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
12532 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
12537 @item @emph{See also}:
12538 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
12544 @section @code{STORAGE_SIZE} --- Storage size in bits
12545 @fnindex STORAGE_SIZE
12546 @cindex storage size
12549 @item @emph{Description}:
12550 Returns the storage size of argument @var{A} in bits.
12551 @item @emph{Standard}:
12552 Fortran 2008 and later
12553 @item @emph{Class}:
12555 @item @emph{Syntax}:
12556 @code{RESULT = STORAGE_SIZE(A [, KIND])}
12558 @item @emph{Arguments}:
12559 @multitable @columnfractions .15 .70
12560 @item @var{A} @tab Shall be a scalar or array of any type.
12561 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
12564 @item @emph{Return Value}:
12565 The result is a scalar integer with the kind type parameter specified by KIND
12566 (or default integer type if KIND is missing). The result value is the size
12567 expressed in bits for an element of an array that has the dynamic type and type
12570 @item @emph{See also}:
12571 @ref{C_SIZEOF}, @ref{SIZEOF}
12577 @section @code{SUM} --- Sum of array elements
12580 @cindex array, add elements
12581 @cindex array, conditionally add elements
12582 @cindex sum array elements
12585 @item @emph{Description}:
12586 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
12587 the corresponding element in @var{MASK} is @code{TRUE}.
12589 @item @emph{Standard}:
12590 Fortran 95 and later
12592 @item @emph{Class}:
12593 Transformational function
12595 @item @emph{Syntax}:
12596 @multitable @columnfractions .80
12597 @item @code{RESULT = SUM(ARRAY[, MASK])}
12598 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
12601 @item @emph{Arguments}:
12602 @multitable @columnfractions .15 .70
12603 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
12604 @code{REAL} or @code{COMPLEX}.
12605 @item @var{DIM} @tab (Optional) shall be a scalar of type
12606 @code{INTEGER} with a value in the range from 1 to n, where n
12607 equals the rank of @var{ARRAY}.
12608 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
12609 and either be a scalar or an array of the same shape as @var{ARRAY}.
12612 @item @emph{Return value}:
12613 The result is of the same type as @var{ARRAY}.
12615 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
12616 is returned. Otherwise, an array of rank n-1, where n equals the rank of
12617 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
12618 dropped is returned.
12620 @item @emph{Example}:
12623 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
12624 print *, SUM(x) ! all elements, sum = 15
12625 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
12629 @item @emph{See also}:
12636 @section @code{SYMLNK} --- Create a symbolic link
12638 @cindex file system, create link
12639 @cindex file system, soft link
12642 @item @emph{Description}:
12643 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
12644 character (@code{CHAR(0)}) can be used to mark the end of the names in
12645 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
12646 names are ignored. If the @var{STATUS} argument is supplied, it
12647 contains 0 on success or a nonzero error code upon return; see
12648 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
12649 @code{ENOSYS} is returned.
12651 This intrinsic is provided in both subroutine and function forms;
12652 however, only one form can be used in any given program unit.
12654 @item @emph{Standard}:
12657 @item @emph{Class}:
12658 Subroutine, function
12660 @item @emph{Syntax}:
12661 @multitable @columnfractions .80
12662 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
12663 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
12666 @item @emph{Arguments}:
12667 @multitable @columnfractions .15 .70
12668 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
12669 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
12670 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12673 @item @emph{See also}:
12674 @ref{LINK}, @ref{UNLINK}
12681 @section @code{SYSTEM} --- Execute a shell command
12683 @cindex system, system call
12686 @item @emph{Description}:
12687 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
12688 argument @var{STATUS} is present, it contains the value returned by
12689 @code{system(3)}, which is presumably 0 if the shell command succeeded.
12690 Note that which shell is used to invoke the command is system-dependent
12691 and environment-dependent.
12693 This intrinsic is provided in both subroutine and function forms;
12694 however, only one form can be used in any given program unit.
12696 Note that the @code{system} function need not be thread-safe. It is
12697 the responsibility of the user to ensure that @code{system} is not
12698 called concurrently.
12700 @item @emph{Standard}:
12703 @item @emph{Class}:
12704 Subroutine, function
12706 @item @emph{Syntax}:
12707 @multitable @columnfractions .80
12708 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
12709 @item @code{STATUS = SYSTEM(COMMAND)}
12712 @item @emph{Arguments}:
12713 @multitable @columnfractions .15 .70
12714 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
12715 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12718 @item @emph{See also}:
12719 @ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
12720 and should considered in new code for future portability.
12726 @section @code{SYSTEM_CLOCK} --- Time function
12727 @fnindex SYSTEM_CLOCK
12728 @cindex time, clock ticks
12729 @cindex clock ticks
12732 @item @emph{Description}:
12733 Determines the @var{COUNT} of a processor clock since an unspecified
12734 time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines
12735 the number of clock ticks per second. If the platform supports a
12736 monotonic clock, that clock is used and can, depending on the platform
12737 clock implementation, provide up to nanosecond resolution. If a
12738 monotonic clock is not available, the implementation falls back to a
12741 @var{COUNT_RATE} is system dependent and can vary depending on the kind of
12742 the arguments. For @var{kind=4} arguments (and smaller integer kinds),
12743 @var{COUNT} represents milliseconds, while for @var{kind=8} arguments (and
12744 larger integer kinds), @var{COUNT} typically represents micro- or
12745 nanoseconds depending on resolution of the underlying platform clock.
12746 @var{COUNT_MAX} usually equals @code{HUGE(COUNT_MAX)}. Note that the
12747 millisecond resolution of the @var{kind=4} version implies that the
12748 @var{COUNT} will wrap around in roughly 25 days. In order to avoid issues
12749 with the wrap around and for more precise timing, please use the
12750 @var{kind=8} version.
12752 If there is no clock, or querying the clock fails, @var{COUNT} is set
12753 to @code{-HUGE(COUNT)}, and @var{COUNT_RATE} and @var{COUNT_MAX} are
12756 When running on a platform using the GNU C library (glibc) version
12757 2.16 or older, or a derivative thereof, the high resolution monotonic
12758 clock is available only when linking with the @var{rt} library. This
12759 can be done explicitly by adding the @code{-lrt} flag when linking the
12760 application, but is also done implicitly when using OpenMP.
12762 On the Windows platform, the version with @var{kind=4} arguments uses
12763 the @code{GetTickCount} function, whereas the @var{kind=8} version
12764 uses @code{QueryPerformanceCounter} and
12765 @code{QueryPerformanceCounterFrequency}. For more information, and
12766 potential caveats, please see the platform documentation.
12768 @item @emph{Standard}:
12769 Fortran 95 and later
12771 @item @emph{Class}:
12774 @item @emph{Syntax}:
12775 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
12777 @item @emph{Arguments}:
12778 @multitable @columnfractions .15 .70
12779 @item @var{COUNT} @tab (Optional) shall be a scalar of type
12780 @code{INTEGER} with @code{INTENT(OUT)}.
12781 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type
12782 @code{INTEGER} or @code{REAL}, with @code{INTENT(OUT)}.
12783 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type
12784 @code{INTEGER} with @code{INTENT(OUT)}.
12787 @item @emph{Example}:
12789 PROGRAM test_system_clock
12790 INTEGER :: count, count_rate, count_max
12791 CALL SYSTEM_CLOCK(count, count_rate, count_max)
12792 WRITE(*,*) count, count_rate, count_max
12796 @item @emph{See also}:
12797 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
12803 @section @code{TAN} --- Tangent function
12806 @cindex trigonometric function, tangent
12810 @item @emph{Description}:
12811 @code{TAN(X)} computes the tangent of @var{X}.
12813 @item @emph{Standard}:
12814 Fortran 77 and later, for a complex argument Fortran 2008 or later
12816 @item @emph{Class}:
12819 @item @emph{Syntax}:
12820 @code{RESULT = TAN(X)}
12822 @item @emph{Arguments}:
12823 @multitable @columnfractions .15 .70
12824 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
12827 @item @emph{Return value}:
12828 The return value has same type and kind as @var{X}.
12830 @item @emph{Example}:
12833 real(8) :: x = 0.165_8
12835 end program test_tan
12838 @item @emph{Specific names}:
12839 @multitable @columnfractions .20 .20 .20 .25
12840 @item Name @tab Argument @tab Return type @tab Standard
12841 @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
12842 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
12845 @item @emph{See also}:
12852 @section @code{TANH} --- Hyperbolic tangent function
12855 @cindex hyperbolic tangent
12856 @cindex hyperbolic function, tangent
12857 @cindex tangent, hyperbolic
12860 @item @emph{Description}:
12861 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
12863 @item @emph{Standard}:
12864 Fortran 77 and later, for a complex argument Fortran 2008 or later
12866 @item @emph{Class}:
12869 @item @emph{Syntax}:
12872 @item @emph{Arguments}:
12873 @multitable @columnfractions .15 .70
12874 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
12877 @item @emph{Return value}:
12878 The return value has same type and kind as @var{X}. If @var{X} is
12879 complex, the imaginary part of the result is in radians. If @var{X}
12880 is @code{REAL}, the return value lies in the range
12881 @math{ - 1 \leq tanh(x) \leq 1 }.
12883 @item @emph{Example}:
12886 real(8) :: x = 2.1_8
12888 end program test_tanh
12891 @item @emph{Specific names}:
12892 @multitable @columnfractions .20 .20 .20 .25
12893 @item Name @tab Argument @tab Return type @tab Standard
12894 @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
12895 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
12898 @item @emph{See also}:
12905 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
12906 @fnindex THIS_IMAGE
12907 @cindex coarray, @code{THIS_IMAGE}
12908 @cindex images, index of this image
12911 @item @emph{Description}:
12912 Returns the cosubscript for this image.
12914 @item @emph{Standard}:
12915 Fortran 2008 and later. With @var{DISTANCE} argument,
12916 Technical Specification (TS) 18508 or later
12918 @item @emph{Class}:
12919 Transformational function
12921 @item @emph{Syntax}:
12922 @multitable @columnfractions .80
12923 @item @code{RESULT = THIS_IMAGE()}
12924 @item @code{RESULT = THIS_IMAGE(DISTANCE)}
12925 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
12928 @item @emph{Arguments}:
12929 @multitable @columnfractions .15 .70
12930 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
12931 (not permitted together with @var{COARRAY}).
12932 @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
12933 present, required).
12934 @item @var{DIM} @tab default integer scalar (optional). If present,
12935 @var{DIM} shall be between one and the corank of @var{COARRAY}.
12939 @item @emph{Return value}:
12940 Default integer. If @var{COARRAY} is not present, it is scalar; if
12941 @var{DISTANCE} is not present or has value 0, its value is the image index on
12942 the invoking image for the current team, for values smaller or equal
12943 distance to the initial team, it returns the image index on the ancestor team
12944 which has a distance of @var{DISTANCE} from the invoking team. If
12945 @var{DISTANCE} is larger than the distance to the initial team, the image
12946 index of the initial team is returned. Otherwise when the @var{COARRAY} is
12947 present, if @var{DIM} is not present, a rank-1 array with corank elements is
12948 returned, containing the cosubscripts for @var{COARRAY} specifying the invoking
12949 image. If @var{DIM} is present, a scalar is returned, with the value of
12950 the @var{DIM} element of @code{THIS_IMAGE(COARRAY)}.
12952 @item @emph{Example}:
12954 INTEGER :: value[*]
12956 value = THIS_IMAGE()
12958 IF (THIS_IMAGE() == 1) THEN
12959 DO i = 1, NUM_IMAGES()
12960 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
12964 ! Check whether the current image is the initial image
12965 IF (THIS_IMAGE(HUGE(1)) /= THIS_IMAGE())
12966 error stop "something is rotten here"
12969 @item @emph{See also}:
12970 @ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
12976 @section @code{TIME} --- Time function
12978 @cindex time, current
12979 @cindex current time
12982 @item @emph{Description}:
12983 Returns the current time encoded as an integer (in the manner of the
12984 function @code{time(3)} in the C standard library). This value is
12985 suitable for passing to @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
12987 This intrinsic is not fully portable, such as to systems with 32-bit
12988 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
12989 the values returned by this intrinsic might be, or become, negative, or
12990 numerically less than previous values, during a single run of the
12993 See @ref{TIME8}, for information on a similar intrinsic that might be
12994 portable to more GNU Fortran implementations, though to fewer Fortran
12997 @item @emph{Standard}:
13000 @item @emph{Class}:
13003 @item @emph{Syntax}:
13004 @code{RESULT = TIME()}
13006 @item @emph{Return value}:
13007 The return value is a scalar of type @code{INTEGER(4)}.
13009 @item @emph{See also}:
13010 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
13017 @section @code{TIME8} --- Time function (64-bit)
13019 @cindex time, current
13020 @cindex current time
13023 @item @emph{Description}:
13024 Returns the current time encoded as an integer (in the manner of the
13025 function @code{time(3)} in the C standard library). This value is
13026 suitable for passing to @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
13028 @emph{Warning:} this intrinsic does not increase the range of the timing
13029 values over that returned by @code{time(3)}. On a system with a 32-bit
13030 @code{time(3)}, @code{TIME8} will return a 32-bit value, even though
13031 it is converted to a 64-bit @code{INTEGER(8)} value. That means
13032 overflows of the 32-bit value can still occur. Therefore, the values
13033 returned by this intrinsic might be or become negative or numerically
13034 less than previous values during a single run of the compiled program.
13036 @item @emph{Standard}:
13039 @item @emph{Class}:
13042 @item @emph{Syntax}:
13043 @code{RESULT = TIME8()}
13045 @item @emph{Return value}:
13046 The return value is a scalar of type @code{INTEGER(8)}.
13048 @item @emph{See also}:
13049 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
13056 @section @code{TINY} --- Smallest positive number of a real kind
13058 @cindex limits, smallest number
13059 @cindex model representation, smallest number
13062 @item @emph{Description}:
13063 @code{TINY(X)} returns the smallest positive (non zero) number
13064 in the model of the type of @code{X}.
13066 @item @emph{Standard}:
13067 Fortran 95 and later
13069 @item @emph{Class}:
13072 @item @emph{Syntax}:
13073 @code{RESULT = TINY(X)}
13075 @item @emph{Arguments}:
13076 @multitable @columnfractions .15 .70
13077 @item @var{X} @tab Shall be of type @code{REAL}.
13080 @item @emph{Return value}:
13081 The return value is of the same type and kind as @var{X}
13083 @item @emph{Example}:
13084 See @code{HUGE} for an example.
13090 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
13095 @item @emph{Description}:
13096 @code{TRAILZ} returns the number of trailing zero bits of an integer.
13098 @item @emph{Standard}:
13099 Fortran 2008 and later
13101 @item @emph{Class}:
13104 @item @emph{Syntax}:
13105 @code{RESULT = TRAILZ(I)}
13107 @item @emph{Arguments}:
13108 @multitable @columnfractions .15 .70
13109 @item @var{I} @tab Shall be of type @code{INTEGER}.
13112 @item @emph{Return value}:
13113 The type of the return value is the default @code{INTEGER}.
13114 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
13116 @item @emph{Example}:
13118 PROGRAM test_trailz
13119 WRITE (*,*) TRAILZ(8) ! prints 3
13123 @item @emph{See also}:
13124 @ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT}
13130 @section @code{TRANSFER} --- Transfer bit patterns
13136 @item @emph{Description}:
13137 Interprets the bitwise representation of @var{SOURCE} in memory as if it
13138 is the representation of a variable or array of the same type and type
13139 parameters as @var{MOLD}.
13141 This is approximately equivalent to the C concept of @emph{casting} one
13144 @item @emph{Standard}:
13145 Fortran 95 and later
13147 @item @emph{Class}:
13148 Transformational function
13150 @item @emph{Syntax}:
13151 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
13153 @item @emph{Arguments}:
13154 @multitable @columnfractions .15 .70
13155 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
13156 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
13157 @item @var{SIZE} @tab (Optional) shall be a scalar of type
13161 @item @emph{Return value}:
13162 The result has the same type as @var{MOLD}, with the bit level
13163 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
13164 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
13165 but @var{MOLD} is an array (of any size or shape), the result is a one-
13166 dimensional array of the minimum length needed to contain the entirety
13167 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
13168 and @var{MOLD} is a scalar, the result is a scalar.
13170 If the bitwise representation of the result is longer than that of
13171 @var{SOURCE}, then the leading bits of the result correspond to those of
13172 @var{SOURCE} and any trailing bits are filled arbitrarily.
13174 When the resulting bit representation does not correspond to a valid
13175 representation of a variable of the same type as @var{MOLD}, the results
13176 are undefined, and subsequent operations on the result cannot be
13177 guaranteed to produce sensible behavior. For example, it is possible to
13178 create @code{LOGICAL} variables for which @code{@var{VAR}} and
13179 @code{.NOT.@var{VAR}} both appear to be true.
13181 @item @emph{Example}:
13183 PROGRAM test_transfer
13184 integer :: x = 2143289344
13185 print *, transfer(x, 1.0) ! prints "NaN" on i686
13193 @section @code{TRANSPOSE} --- Transpose an array of rank two
13195 @cindex array, transpose
13196 @cindex matrix, transpose
13200 @item @emph{Description}:
13201 Transpose an array of rank two. Element (i, j) of the result has the value
13202 @code{MATRIX(j, i)}, for all i, j.
13204 @item @emph{Standard}:
13205 Fortran 95 and later
13207 @item @emph{Class}:
13208 Transformational function
13210 @item @emph{Syntax}:
13211 @code{RESULT = TRANSPOSE(MATRIX)}
13213 @item @emph{Arguments}:
13214 @multitable @columnfractions .15 .70
13215 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
13218 @item @emph{Return value}:
13219 The result has the same type as @var{MATRIX}, and has shape
13220 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
13226 @section @code{TRIM} --- Remove trailing blank characters of a string
13228 @cindex string, remove trailing whitespace
13231 @item @emph{Description}:
13232 Removes trailing blank characters of a string.
13234 @item @emph{Standard}:
13235 Fortran 95 and later
13237 @item @emph{Class}:
13238 Transformational function
13240 @item @emph{Syntax}:
13241 @code{RESULT = TRIM(STRING)}
13243 @item @emph{Arguments}:
13244 @multitable @columnfractions .15 .70
13245 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
13248 @item @emph{Return value}:
13249 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
13250 less the number of trailing blanks.
13252 @item @emph{Example}:
13255 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
13256 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
13260 @item @emph{See also}:
13261 @ref{ADJUSTL}, @ref{ADJUSTR}
13267 @section @code{TTYNAM} --- Get the name of a terminal device.
13269 @cindex system, terminal
13272 @item @emph{Description}:
13273 Get the name of a terminal device. For more information,
13274 see @code{ttyname(3)}.
13276 This intrinsic is provided in both subroutine and function forms;
13277 however, only one form can be used in any given program unit.
13279 @item @emph{Standard}:
13282 @item @emph{Class}:
13283 Subroutine, function
13285 @item @emph{Syntax}:
13286 @multitable @columnfractions .80
13287 @item @code{CALL TTYNAM(UNIT, NAME)}
13288 @item @code{NAME = TTYNAM(UNIT)}
13291 @item @emph{Arguments}:
13292 @multitable @columnfractions .15 .70
13293 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
13294 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
13297 @item @emph{Example}:
13299 PROGRAM test_ttynam
13302 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
13307 @item @emph{See also}:
13314 @section @code{UBOUND} --- Upper dimension bounds of an array
13316 @cindex array, upper bound
13319 @item @emph{Description}:
13320 Returns the upper bounds of an array, or a single upper bound
13321 along the @var{DIM} dimension.
13322 @item @emph{Standard}:
13323 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
13325 @item @emph{Class}:
13328 @item @emph{Syntax}:
13329 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
13331 @item @emph{Arguments}:
13332 @multitable @columnfractions .15 .70
13333 @item @var{ARRAY} @tab Shall be an array, of any type.
13334 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
13335 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
13336 expression indicating the kind parameter of the result.
13339 @item @emph{Return value}:
13340 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
13341 @var{KIND} is absent, the return value is of default integer kind.
13342 If @var{DIM} is absent, the result is an array of the upper bounds of
13343 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
13344 corresponding to the upper bound of the array along that dimension. If
13345 @var{ARRAY} is an expression rather than a whole array or array
13346 structure component, or if it has a zero extent along the relevant
13347 dimension, the upper bound is taken to be the number of elements along
13348 the relevant dimension.
13350 @item @emph{See also}:
13351 @ref{LBOUND}, @ref{LCOBOUND}
13357 @section @code{UCOBOUND} --- Upper codimension bounds of an array
13359 @cindex coarray, upper bound
13362 @item @emph{Description}:
13363 Returns the upper cobounds of a coarray, or a single upper cobound
13364 along the @var{DIM} codimension.
13365 @item @emph{Standard}:
13366 Fortran 2008 and later
13368 @item @emph{Class}:
13371 @item @emph{Syntax}:
13372 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
13374 @item @emph{Arguments}:
13375 @multitable @columnfractions .15 .70
13376 @item @var{ARRAY} @tab Shall be an coarray, of any type.
13377 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
13378 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
13379 expression indicating the kind parameter of the result.
13382 @item @emph{Return value}:
13383 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
13384 @var{KIND} is absent, the return value is of default integer kind.
13385 If @var{DIM} is absent, the result is an array of the lower cobounds of
13386 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
13387 corresponding to the lower cobound of the array along that codimension.
13389 @item @emph{See also}:
13390 @ref{LCOBOUND}, @ref{LBOUND}
13396 @section @code{UMASK} --- Set the file creation mask
13398 @cindex file system, file creation mask
13401 @item @emph{Description}:
13402 Sets the file creation mask to @var{MASK}. If called as a function, it
13403 returns the old value. If called as a subroutine and argument @var{OLD}
13404 if it is supplied, it is set to the old value. See @code{umask(2)}.
13406 @item @emph{Standard}:
13409 @item @emph{Class}:
13410 Subroutine, function
13412 @item @emph{Syntax}:
13413 @multitable @columnfractions .80
13414 @item @code{CALL UMASK(MASK [, OLD])}
13415 @item @code{OLD = UMASK(MASK)}
13418 @item @emph{Arguments}:
13419 @multitable @columnfractions .15 .70
13420 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
13421 @item @var{OLD} @tab (Optional) Shall be a scalar of type
13430 @section @code{UNLINK} --- Remove a file from the file system
13432 @cindex file system, remove file
13435 @item @emph{Description}:
13436 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
13437 used to mark the end of the name in @var{PATH}; otherwise, trailing
13438 blanks in the file name are ignored. If the @var{STATUS} argument is
13439 supplied, it contains 0 on success or a nonzero error code upon return;
13440 see @code{unlink(2)}.
13442 This intrinsic is provided in both subroutine and function forms;
13443 however, only one form can be used in any given program unit.
13445 @item @emph{Standard}:
13448 @item @emph{Class}:
13449 Subroutine, function
13451 @item @emph{Syntax}:
13452 @multitable @columnfractions .80
13453 @item @code{CALL UNLINK(PATH [, STATUS])}
13454 @item @code{STATUS = UNLINK(PATH)}
13457 @item @emph{Arguments}:
13458 @multitable @columnfractions .15 .70
13459 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
13460 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
13463 @item @emph{See also}:
13464 @ref{LINK}, @ref{SYMLNK}
13470 @section @code{UNPACK} --- Unpack an array of rank one into an array
13472 @cindex array, unpacking
13473 @cindex array, increase dimension
13474 @cindex array, scatter elements
13477 @item @emph{Description}:
13478 Store the elements of @var{VECTOR} in an array of higher rank.
13480 @item @emph{Standard}:
13481 Fortran 95 and later
13483 @item @emph{Class}:
13484 Transformational function
13486 @item @emph{Syntax}:
13487 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
13489 @item @emph{Arguments}:
13490 @multitable @columnfractions .15 .70
13491 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
13492 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
13493 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
13494 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
13495 the same shape as @var{MASK}.
13498 @item @emph{Return value}:
13499 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
13500 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
13502 @item @emph{Example}:
13504 PROGRAM test_unpack
13505 integer :: vector(2) = (/1,1/)
13506 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
13507 integer :: field(2,2) = 0, unity(2,2)
13509 ! result: unity matrix
13510 unity = unpack(vector, reshape(mask, (/2,2/)), field)
13514 @item @emph{See also}:
13515 @ref{PACK}, @ref{SPREAD}
13521 @section @code{VERIFY} --- Scan a string for characters not a given set
13523 @cindex string, find missing set
13526 @item @emph{Description}:
13527 Verifies that all the characters in @var{STRING} belong to the set of
13528 characters in @var{SET}.
13530 If @var{BACK} is either absent or equals @code{FALSE}, this function
13531 returns the position of the leftmost character of @var{STRING} that is
13532 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost
13533 position is returned. If all characters of @var{STRING} are found in
13534 @var{SET}, the result is zero.
13536 @item @emph{Standard}:
13537 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
13539 @item @emph{Class}:
13542 @item @emph{Syntax}:
13543 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
13545 @item @emph{Arguments}:
13546 @multitable @columnfractions .15 .70
13547 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
13548 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
13549 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
13550 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
13551 expression indicating the kind parameter of the result.
13554 @item @emph{Return value}:
13555 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
13556 @var{KIND} is absent, the return value is of default integer kind.
13558 @item @emph{Example}:
13560 PROGRAM test_verify
13561 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
13562 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
13563 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
13564 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
13565 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
13569 @item @emph{See also}:
13570 @ref{SCAN}, @ref{INDEX intrinsic}
13576 @section @code{XOR} --- Bitwise logical exclusive OR
13578 @cindex bitwise logical exclusive or
13579 @cindex logical exclusive or, bitwise
13582 @item @emph{Description}:
13583 Bitwise logical exclusive or.
13585 This intrinsic routine is provided for backwards compatibility with
13586 GNU Fortran 77. For integer arguments, programmers should consider
13587 the use of the @ref{IEOR} intrinsic and for logical arguments the
13588 @code{.NEQV.} operator, which are both defined by the Fortran standard.
13590 @item @emph{Standard}:
13593 @item @emph{Class}:
13596 @item @emph{Syntax}:
13597 @code{RESULT = XOR(I, J)}
13599 @item @emph{Arguments}:
13600 @multitable @columnfractions .15 .70
13601 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
13602 type or a scalar @code{LOGICAL} type.
13603 @item @var{J} @tab The type shall be the same as the type of @var{I}.
13606 @item @emph{Return value}:
13607 The return type is either a scalar @code{INTEGER} or a scalar
13608 @code{LOGICAL}. If the kind type parameters differ, then the
13609 smaller kind type is implicitly converted to larger kind, and the
13610 return has the larger kind.
13612 @item @emph{Example}:
13615 LOGICAL :: T = .TRUE., F = .FALSE.
13617 DATA a / Z'F' /, b / Z'3' /
13619 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
13620 WRITE (*,*) XOR(a, b)
13624 @item @emph{See also}:
13625 Fortran 95 elemental function: @ref{IEOR}
13630 @node Intrinsic Modules
13631 @chapter Intrinsic Modules
13632 @cindex intrinsic Modules
13635 * ISO_FORTRAN_ENV::
13638 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
13641 @node ISO_FORTRAN_ENV
13642 @section @code{ISO_FORTRAN_ENV}
13644 @item @emph{Standard}:
13645 Fortran 2003 and later, except when otherwise noted
13648 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
13652 @item @code{ATOMIC_INT_KIND}:
13653 Default-kind integer constant to be used as kind parameter when defining
13654 integer variables used in atomic operations. (Fortran 2008 or later.)
13656 @item @code{ATOMIC_LOGICAL_KIND}:
13657 Default-kind integer constant to be used as kind parameter when defining
13658 logical variables used in atomic operations. (Fortran 2008 or later.)
13660 @item @code{CHARACTER_KINDS}:
13661 Default-kind integer constant array of rank one containing the supported kind
13662 parameters of the @code{CHARACTER} type. (Fortran 2008 or later.)
13664 @item @code{CHARACTER_STORAGE_SIZE}:
13665 Size in bits of the character storage unit.
13667 @item @code{ERROR_UNIT}:
13668 Identifies the preconnected unit used for error reporting.
13670 @item @code{FILE_STORAGE_SIZE}:
13671 Size in bits of the file-storage unit.
13673 @item @code{INPUT_UNIT}:
13674 Identifies the preconnected unit identified by the asterisk
13675 (@code{*}) in @code{READ} statement.
13677 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
13678 Kind type parameters to specify an INTEGER type with a storage
13679 size of 16, 32, and 64 bits. It is negative if a target platform
13680 does not support the particular kind. (Fortran 2008 or later.)
13682 @item @code{INTEGER_KINDS}:
13683 Default-kind integer constant array of rank one containing the supported kind
13684 parameters of the @code{INTEGER} type. (Fortran 2008 or later.)
13686 @item @code{IOSTAT_END}:
13687 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
13688 an input/output statement if an end-of-file condition occurred.
13690 @item @code{IOSTAT_EOR}:
13691 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
13692 an input/output statement if an end-of-record condition occurred.
13694 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
13695 Scalar default-integer constant, used by @code{INQUIRE} for the
13696 @code{IOSTAT=} specifier to denote an that a unit number identifies an
13697 internal unit. (Fortran 2008 or later.)
13699 @item @code{NUMERIC_STORAGE_SIZE}:
13700 The size in bits of the numeric storage unit.
13702 @item @code{LOGICAL_KINDS}:
13703 Default-kind integer constant array of rank one containing the supported kind
13704 parameters of the @code{LOGICAL} type. (Fortran 2008 or later.)
13706 @item @code{OUTPUT_UNIT}:
13707 Identifies the preconnected unit identified by the asterisk
13708 (@code{*}) in @code{WRITE} statement.
13710 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
13711 Kind type parameters to specify a REAL type with a storage
13712 size of 32, 64, and 128 bits. It is negative if a target platform
13713 does not support the particular kind. (Fortran 2008 or later.)
13715 @item @code{REAL_KINDS}:
13716 Default-kind integer constant array of rank one containing the supported kind
13717 parameters of the @code{REAL} type. (Fortran 2008 or later.)
13719 @item @code{STAT_LOCKED}:
13720 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
13721 denote that the lock variable is locked by the executing image. (Fortran 2008
13724 @item @code{STAT_LOCKED_OTHER_IMAGE}:
13725 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
13726 denote that the lock variable is locked by another image. (Fortran 2008 or
13729 @item @code{STAT_STOPPED_IMAGE}:
13730 Positive, scalar default-integer constant used as STAT= return value if the
13731 argument in the statement requires synchronisation with an image, which has
13732 initiated the termination of the execution. (Fortran 2008 or later.)
13734 @item @code{STAT_FAILED_IMAGE}:
13735 Positive, scalar default-integer constant used as STAT= return value if the
13736 argument in the statement requires communication with an image, which has
13737 is in the failed state. (TS 18508 or later.)
13739 @item @code{STAT_UNLOCKED}:
13740 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
13741 denote that the lock variable is unlocked. (Fortran 2008 or later.)
13744 The module provides the following derived type:
13747 @item @code{LOCK_TYPE}:
13748 Derived type with private components to be use with the @code{LOCK} and
13749 @code{UNLOCK} statement. A variable of its type has to be always declared
13750 as coarray and may not appear in a variable-definition context.
13751 (Fortran 2008 or later.)
13754 The module also provides the following intrinsic procedures:
13755 @ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}.
13759 @node ISO_C_BINDING
13760 @section @code{ISO_C_BINDING}
13762 @item @emph{Standard}:
13763 Fortran 2003 and later, GNU extensions
13766 The following intrinsic procedures are provided by the module; their
13767 definition can be found in the section Intrinsic Procedures of this
13771 @item @code{C_ASSOCIATED}
13772 @item @code{C_F_POINTER}
13773 @item @code{C_F_PROCPOINTER}
13774 @item @code{C_FUNLOC}
13776 @item @code{C_SIZEOF}
13778 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
13779 @c don't really know why.
13781 The @code{ISO_C_BINDING} module provides the following named constants of
13782 type default integer, which can be used as KIND type parameters.
13784 In addition to the integer named constants required by the Fortran 2003
13785 standard and @code{C_PTRDIFF_T} of TS 29113, GNU Fortran provides as an
13786 extension named constants for the 128-bit integer types supported by the
13787 C compiler: @code{C_INT128_T, C_INT_LEAST128_T, C_INT_FAST128_T}.
13788 Furthermore, if @code{__float128} is supported in C, the named constants
13789 @code{C_FLOAT128, C_FLOAT128_COMPLEX} are defined.
13791 @multitable @columnfractions .15 .35 .35 .35
13792 @item Fortran Type @tab Named constant @tab C type @tab Extension
13793 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
13794 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
13795 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
13796 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
13797 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
13798 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
13799 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
13800 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
13801 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
13802 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
13803 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
13804 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
13805 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
13806 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
13807 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
13808 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
13809 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
13810 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
13811 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
13812 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
13813 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
13814 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
13815 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
13816 @item @code{INTEGER}@tab @code{C_PTRDIFF_T} @tab @code{intptr_t} @tab TS 29113
13817 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
13818 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
13819 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
13820 @item @code{REAL} @tab @code{C_FLOAT128} @tab @code{__float128} @tab Ext.
13821 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
13822 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
13823 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
13824 @item @code{REAL} @tab @code{C_FLOAT128_COMPLEX} @tab @code{__float128 _Complex} @tab Ext.
13825 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
13826 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
13829 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
13832 @multitable @columnfractions .20 .45 .15
13833 @item Name @tab C definition @tab Value
13834 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
13835 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
13836 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
13837 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
13838 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
13839 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
13840 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
13841 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
13844 Moreover, the following two named constants are defined:
13846 @multitable @columnfractions .20 .80
13847 @item Name @tab Type
13848 @item @code{C_NULL_PTR} @tab @code{C_PTR}
13849 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
13852 Both are equivalent to the value @code{NULL} in C.
13857 @section IEEE modules: @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
13859 @item @emph{Standard}:
13860 Fortran 2003 and later
13863 The @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
13864 intrinsic modules provide support for exceptions and IEEE arithmetic, as
13865 defined in Fortran 2003 and later standards, and the IEC 60559:1989 standard
13866 (@emph{Binary floating-point arithmetic for microprocessor systems}). These
13867 modules are only provided on the following supported platforms:
13870 @item i386 and x86_64 processors
13871 @item platforms which use the GNU C Library (glibc)
13872 @item platforms with support for SysV/386 routines for floating point
13873 interface (including Solaris and BSDs)
13874 @item platforms with the AIX OS
13877 For full compliance with the Fortran standards, code using the
13878 @code{IEEE_EXCEPTIONS} or @code{IEEE_ARITHMETIC} modules should be compiled
13879 with the following options: @code{-fno-unsafe-math-optimizations
13880 -frounding-math -fsignaling-nans}.
13883 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
13884 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
13886 @item @emph{Standard}:
13887 OpenMP Application Program Interface v4.0
13891 The OpenMP Fortran runtime library routines are provided both in
13892 a form of two Fortran 90 modules, named @code{OMP_LIB} and
13893 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
13894 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
13895 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
13896 the named constants defined in the modules are listed
13899 For details refer to the actual
13900 @uref{http://www.openmp.org/mp-documents/OpenMP4.0.0.pdf,
13901 OpenMP Application Program Interface v4.0}.
13903 @code{OMP_LIB_KINDS} provides the following scalar default-integer
13907 @item @code{omp_lock_kind}
13908 @item @code{omp_nest_lock_kind}
13909 @item @code{omp_proc_bind_kind}
13910 @item @code{omp_sched_kind}
13913 @code{OMP_LIB} provides the scalar default-integer
13914 named constant @code{openmp_version} with a value of the form
13915 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
13916 of the OpenMP version; for OpenMP v4.0 the value is @code{201307}.
13918 The following scalar integer named constants of the
13919 kind @code{omp_sched_kind}:
13922 @item @code{omp_sched_static}
13923 @item @code{omp_sched_dynamic}
13924 @item @code{omp_sched_guided}
13925 @item @code{omp_sched_auto}
13928 And the following scalar integer named constants of the
13929 kind @code{omp_proc_bind_kind}:
13932 @item @code{omp_proc_bind_false}
13933 @item @code{omp_proc_bind_true}
13934 @item @code{omp_proc_bind_master}
13935 @item @code{omp_proc_bind_close}
13936 @item @code{omp_proc_bind_spread}