2 Copyright (C) 2005-2016 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_DEFINE}: ATOMIC_DEFINE, Setting a variable atomically
67 * @code{ATOMIC_FETCH_ADD}: ATOMIC_FETCH_ADD, Atomic ADD operation with prior fetch
68 * @code{ATOMIC_FETCH_AND}: ATOMIC_FETCH_AND, Atomic bitwise AND operation with prior fetch
69 * @code{ATOMIC_FETCH_OR}: ATOMIC_FETCH_OR, Atomic bitwise OR operation with prior fetch
70 * @code{ATOMIC_FETCH_XOR}: ATOMIC_FETCH_XOR, Atomic bitwise XOR operation with prior fetch
71 * @code{ATOMIC_OR}: ATOMIC_OR, Atomic bitwise OR operation
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_BROADCAST}: CO_BROADCAST, Copy a value to all images the current set of images
99 * @code{CO_MAX}: CO_MAX, Maximal value on the current set of images
100 * @code{CO_MIN}: CO_MIN, Minimal value on the current set of images
101 * @code{CO_REDUCE}: CO_REDUCE, Reduction of values on the current set of images
102 * @code{CO_SUM}: CO_SUM, Sum of values on the current set of images
103 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
104 * @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler
105 * @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string
106 * @code{COMPLEX}: COMPLEX, Complex conversion function
107 * @code{CONJG}: CONJG, Complex conjugate function
108 * @code{COS}: COS, Cosine function
109 * @code{COSH}: COSH, Hyperbolic cosine function
110 * @code{COUNT}: COUNT, Count occurrences of TRUE in an array
111 * @code{CPU_TIME}: CPU_TIME, CPU time subroutine
112 * @code{CSHIFT}: CSHIFT, Circular shift elements of an array
113 * @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string
114 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
115 * @code{DBLE}: DBLE, Double precision conversion function
116 * @code{DCMPLX}: DCMPLX, Double complex conversion function
117 * @code{DIGITS}: DIGITS, Significant digits function
118 * @code{DIM}: DIM, Positive difference
119 * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
120 * @code{DPROD}: DPROD, Double product function
121 * @code{DREAL}: DREAL, Double real part function
122 * @code{DSHIFTL}: DSHIFTL, Combined left shift
123 * @code{DSHIFTR}: DSHIFTR, Combined right shift
124 * @code{DTIME}: DTIME, Execution time subroutine (or function)
125 * @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array
126 * @code{EPSILON}: EPSILON, Epsilon function
127 * @code{ERF}: ERF, Error function
128 * @code{ERFC}: ERFC, Complementary error function
129 * @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function
130 * @code{ETIME}: ETIME, Execution time subroutine (or function)
131 * @code{EVENT_QUERY}: EVENT_QUERY, Query whether a coarray event has occurred
132 * @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command
133 * @code{EXIT}: EXIT, Exit the program with status.
134 * @code{EXP}: EXP, Exponential function
135 * @code{EXPONENT}: EXPONENT, Exponent function
136 * @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF, Query dynamic type for extension
137 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
138 * @code{FGET}: FGET, Read a single character in stream mode from stdin
139 * @code{FGETC}: FGETC, Read a single character in stream mode
140 * @code{FLOOR}: FLOOR, Integer floor function
141 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
142 * @code{FNUM}: FNUM, File number function
143 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
144 * @code{FPUTC}: FPUTC, Write a single character in stream mode
145 * @code{FRACTION}: FRACTION, Fractional part of the model representation
146 * @code{FREE}: FREE, Memory de-allocation subroutine
147 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
148 * @code{FSTAT}: FSTAT, Get file status
149 * @code{FTELL}: FTELL, Current stream position
150 * @code{GAMMA}: GAMMA, Gamma function
151 * @code{GERROR}: GERROR, Get last system error message
152 * @code{GETARG}: GETARG, Get command line arguments
153 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
154 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
155 * @code{GETCWD}: GETCWD, Get current working directory
156 * @code{GETENV}: GETENV, Get an environmental variable
157 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
158 * @code{GETGID}: GETGID, Group ID function
159 * @code{GETLOG}: GETLOG, Get login name
160 * @code{GETPID}: GETPID, Process ID function
161 * @code{GETUID}: GETUID, User ID function
162 * @code{GMTIME}: GMTIME, Convert time to GMT info
163 * @code{HOSTNM}: HOSTNM, Get system host name
164 * @code{HUGE}: HUGE, Largest number of a kind
165 * @code{HYPOT}: HYPOT, Euclidean distance function
166 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
167 * @code{IALL}: IALL, Bitwise AND of array elements
168 * @code{IAND}: IAND, Bitwise logical and
169 * @code{IANY}: IANY, Bitwise OR of array elements
170 * @code{IARGC}: IARGC, Get the number of command line arguments
171 * @code{IBCLR}: IBCLR, Clear bit
172 * @code{IBITS}: IBITS, Bit extraction
173 * @code{IBSET}: IBSET, Set bit
174 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
175 * @code{IDATE}: IDATE, Current local time (day/month/year)
176 * @code{IEOR}: IEOR, Bitwise logical exclusive or
177 * @code{IERRNO}: IERRNO, Function to get the last system error number
178 * @code{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index conversion
179 * @code{INDEX}: INDEX intrinsic, Position of a substring within a string
180 * @code{INT}: INT, Convert to integer type
181 * @code{INT2}: INT2, Convert to 16-bit integer type
182 * @code{INT8}: INT8, Convert to 64-bit integer type
183 * @code{IOR}: IOR, Bitwise logical or
184 * @code{IPARITY}: IPARITY, Bitwise XOR of array elements
185 * @code{IRAND}: IRAND, Integer pseudo-random number
186 * @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value
187 * @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value
188 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
189 * @code{ISHFT}: ISHFT, Shift bits
190 * @code{ISHFTC}: ISHFTC, Shift bits circularly
191 * @code{ISNAN}: ISNAN, Tests for a NaN
192 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
193 * @code{KILL}: KILL, Send a signal to a process
194 * @code{KIND}: KIND, Kind of an entity
195 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
196 * @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array
197 * @code{LEADZ}: LEADZ, Number of leading zero bits of an integer
198 * @code{LEN}: LEN, Length of a character entity
199 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
200 * @code{LGE}: LGE, Lexical greater than or equal
201 * @code{LGT}: LGT, Lexical greater than
202 * @code{LINK}: LINK, Create a hard link
203 * @code{LLE}: LLE, Lexical less than or equal
204 * @code{LLT}: LLT, Lexical less than
205 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
206 * @code{LOC}: LOC, Returns the address of a variable
207 * @code{LOG}: LOG, Logarithm function
208 * @code{LOG10}: LOG10, Base 10 logarithm function
209 * @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
210 * @code{LOGICAL}: LOGICAL, Convert to logical type
211 * @code{LONG}: LONG, Convert to integer type
212 * @code{LSHIFT}: LSHIFT, Left shift bits
213 * @code{LSTAT}: LSTAT, Get file status
214 * @code{LTIME}: LTIME, Convert time to local time info
215 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
216 * @code{MASKL}: MASKL, Left justified mask
217 * @code{MASKR}: MASKR, Right justified mask
218 * @code{MATMUL}: MATMUL, matrix multiplication
219 * @code{MAX}: MAX, Maximum value of an argument list
220 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
221 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
222 * @code{MAXVAL}: MAXVAL, Maximum value of an array
223 * @code{MCLOCK}: MCLOCK, Time function
224 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
225 * @code{MERGE}: MERGE, Merge arrays
226 * @code{MERGE_BITS}: MERGE_BITS, Merge of bits under mask
227 * @code{MIN}: MIN, Minimum value of an argument list
228 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
229 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
230 * @code{MINVAL}: MINVAL, Minimum value of an array
231 * @code{MOD}: MOD, Remainder function
232 * @code{MODULO}: MODULO, Modulo function
233 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
234 * @code{MVBITS}: MVBITS, Move bits from one integer to another
235 * @code{NEAREST}: NEAREST, Nearest representable number
236 * @code{NEW_LINE}: NEW_LINE, New line character
237 * @code{NINT}: NINT, Nearest whole number
238 * @code{NORM2}: NORM2, Euclidean vector norm
239 * @code{NOT}: NOT, Logical negation
240 * @code{NULL}: NULL, Function that returns an disassociated pointer
241 * @code{NUM_IMAGES}: NUM_IMAGES, Number of images
242 * @code{OR}: OR, Bitwise logical OR
243 * @code{PACK}: PACK, Pack an array into an array of rank one
244 * @code{PARITY}: PARITY, Reduction with exclusive OR
245 * @code{PERROR}: PERROR, Print system error message
246 * @code{POPCNT}: POPCNT, Number of bits set
247 * @code{POPPAR}: POPPAR, Parity of the number of bits set
248 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
249 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
250 * @code{PRODUCT}: PRODUCT, Product of array elements
251 * @code{RADIX}: RADIX, Base of a data model
252 * @code{RAN}: RAN, Real pseudo-random number
253 * @code{RAND}: RAND, Real pseudo-random number
254 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
255 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
256 * @code{RANGE}: RANGE, Decimal exponent range
257 * @code{RANK} : RANK, Rank of a data object
258 * @code{REAL}: REAL, Convert to real type
259 * @code{RENAME}: RENAME, Rename a file
260 * @code{REPEAT}: REPEAT, Repeated string concatenation
261 * @code{RESHAPE}: RESHAPE, Function to reshape an array
262 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
263 * @code{RSHIFT}: RSHIFT, Right shift bits
264 * @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality
265 * @code{SCALE}: SCALE, Scale a real value
266 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
267 * @code{SECNDS}: SECNDS, Time function
268 * @code{SECOND}: SECOND, CPU time function
269 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind
270 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
271 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
272 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
273 * @code{SHAPE}: SHAPE, Determine the shape of an array
274 * @code{SHIFTA}: SHIFTA, Right shift with fill
275 * @code{SHIFTL}: SHIFTL, Left shift
276 * @code{SHIFTR}: SHIFTR, Right shift
277 * @code{SIGN}: SIGN, Sign copying function
278 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
279 * @code{SIN}: SIN, Sine function
280 * @code{SINH}: SINH, Hyperbolic sine function
281 * @code{SIZE}: SIZE, Function to determine the size of an array
282 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
283 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
284 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
285 * @code{SPREAD}: SPREAD, Add a dimension to an array
286 * @code{SQRT}: SQRT, Square-root function
287 * @code{SRAND}: SRAND, Reinitialize the random number generator
288 * @code{STAT}: STAT, Get file status
289 * @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits
290 * @code{SUM}: SUM, Sum of array elements
291 * @code{SYMLNK}: SYMLNK, Create a symbolic link
292 * @code{SYSTEM}: SYSTEM, Execute a shell command
293 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
294 * @code{TAN}: TAN, Tangent function
295 * @code{TANH}: TANH, Hyperbolic tangent function
296 * @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image
297 * @code{TIME}: TIME, Time function
298 * @code{TIME8}: TIME8, Time function (64-bit)
299 * @code{TINY}: TINY, Smallest positive number of a real kind
300 * @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer
301 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
302 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
303 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
304 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
305 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
306 * @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array
307 * @code{UMASK}: UMASK, Set the file creation mask
308 * @code{UNLINK}: UNLINK, Remove a file from the file system
309 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
310 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
311 * @code{XOR}: XOR, Bitwise logical exclusive or
314 @node Introduction to Intrinsics
315 @section Introduction to intrinsic procedures
317 The intrinsic procedures provided by GNU Fortran include all of the
318 intrinsic procedures required by the Fortran 95 standard, a set of
319 intrinsic procedures for backwards compatibility with G77, and a
320 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
321 standards. Any conflict between a description here and a description in
322 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
323 2008 standard is unintentional, and the standard(s) should be considered
326 The enumeration of the @code{KIND} type parameter is processor defined in
327 the Fortran 95 standard. GNU Fortran defines the default integer type and
328 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
329 respectively. The standard mandates that both data types shall have
330 another kind, which have more precision. On typical target architectures
331 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
332 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
333 In the description of generic intrinsic procedures, the kind type parameter
334 will be specified by @code{KIND=*}, and in the description of specific
335 names for an intrinsic procedure the kind type parameter will be explicitly
336 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
337 brevity the optional @code{KIND=} syntax will be omitted.
339 Many of the intrinsic procedures take one or more optional arguments.
340 This document follows the convention used in the Fortran 95 standard,
341 and denotes such arguments by square brackets.
343 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
344 which can be used to restrict the set of intrinsic procedures to a
345 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
346 option, and so all intrinsic procedures described here are accepted. There
347 is one caveat. For a select group of intrinsic procedures, @command{g77}
348 implemented both a function and a subroutine. Both classes
349 have been implemented in @command{gfortran} for backwards compatibility
350 with @command{g77}. It is noted here that these functions and subroutines
351 cannot be intermixed in a given subprogram. In the descriptions that follow,
352 the applicable standard for each intrinsic procedure is noted.
357 @section @code{ABORT} --- Abort the program
359 @cindex program termination, with core dump
360 @cindex terminate program, with core dump
364 @item @emph{Description}:
365 @code{ABORT} causes immediate termination of the program. On operating
366 systems that support a core dump, @code{ABORT} will produce a core dump.
367 It will also print a backtrace, unless @code{-fno-backtrace} is given.
369 @item @emph{Standard}:
378 @item @emph{Return value}:
381 @item @emph{Example}:
384 integer :: i = 1, j = 2
385 if (i /= j) call abort
386 end program test_abort
389 @item @emph{See also}:
390 @ref{EXIT}, @ref{KILL}, @ref{BACKTRACE}
397 @section @code{ABS} --- Absolute value
404 @cindex absolute value
407 @item @emph{Description}:
408 @code{ABS(A)} computes the absolute value of @code{A}.
410 @item @emph{Standard}:
411 Fortran 77 and later, has overloads that are GNU extensions
417 @code{RESULT = ABS(A)}
419 @item @emph{Arguments}:
420 @multitable @columnfractions .15 .70
421 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
422 @code{REAL}, or @code{COMPLEX}.
425 @item @emph{Return value}:
426 The return value is of the same type and
427 kind as the argument except the return value is @code{REAL} for a
428 @code{COMPLEX} argument.
430 @item @emph{Example}:
435 complex :: z = (-1.e0,0.e0)
442 @item @emph{Specific names}:
443 @multitable @columnfractions .20 .20 .20 .25
444 @item Name @tab Argument @tab Return type @tab Standard
445 @item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
446 @item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
447 @item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
448 @item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
449 @item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
450 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
457 @section @code{ACCESS} --- Checks file access modes
459 @cindex file system, access mode
462 @item @emph{Description}:
463 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
464 exists, is readable, writable or executable. Except for the
465 executable check, @code{ACCESS} can be replaced by
466 Fortran 95's @code{INQUIRE}.
468 @item @emph{Standard}:
475 @code{RESULT = ACCESS(NAME, MODE)}
477 @item @emph{Arguments}:
478 @multitable @columnfractions .15 .70
479 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
480 file name. Tailing blank are ignored unless the character @code{achar(0)}
481 is present, then all characters up to and excluding @code{achar(0)} are
483 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
484 file access mode, may be any concatenation of @code{"r"} (readable),
485 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
489 @item @emph{Return value}:
490 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
491 accessible in the given mode; otherwise or if an invalid argument
492 has been given for @code{MODE} the value @code{1} is returned.
494 @item @emph{Example}:
498 character(len=*), parameter :: file = 'test.dat'
499 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
500 if(access(file,' ') == 0) print *, trim(file),' is exists'
501 if(access(file,'r') == 0) print *, trim(file),' is readable'
502 if(access(file,'w') == 0) print *, trim(file),' is writable'
503 if(access(file,'x') == 0) print *, trim(file),' is executable'
504 if(access(file2,'rwx') == 0) &
505 print *, trim(file2),' is readable, writable and executable'
506 end program access_test
508 @item @emph{Specific names}:
509 @item @emph{See also}:
516 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
518 @cindex @acronym{ASCII} collating sequence
519 @cindex collating sequence, @acronym{ASCII}
522 @item @emph{Description}:
523 @code{ACHAR(I)} returns the character located at position @code{I}
524 in the @acronym{ASCII} collating sequence.
526 @item @emph{Standard}:
527 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
533 @code{RESULT = ACHAR(I [, KIND])}
535 @item @emph{Arguments}:
536 @multitable @columnfractions .15 .70
537 @item @var{I} @tab The type shall be @code{INTEGER}.
538 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
539 expression indicating the kind parameter of the result.
542 @item @emph{Return value}:
543 The return value is of type @code{CHARACTER} with a length of one.
544 If the @var{KIND} argument is present, the return value is of the
545 specified kind and of the default kind otherwise.
547 @item @emph{Example}:
552 end program test_achar
556 See @ref{ICHAR} for a discussion of converting between numerical values
557 and formatted string representations.
559 @item @emph{See also}:
560 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
567 @section @code{ACOS} --- Arccosine function
570 @cindex trigonometric function, cosine, inverse
571 @cindex cosine, inverse
574 @item @emph{Description}:
575 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
577 @item @emph{Standard}:
578 Fortran 77 and later, for a complex argument Fortran 2008 or later
584 @code{RESULT = ACOS(X)}
586 @item @emph{Arguments}:
587 @multitable @columnfractions .15 .70
588 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
589 less than or equal to one - or the type shall be @code{COMPLEX}.
592 @item @emph{Return value}:
593 The return value is of the same type and kind as @var{X}.
594 The real part of the result is in radians and lies in the range
595 @math{0 \leq \Re \acos(x) \leq \pi}.
597 @item @emph{Example}:
600 real(8) :: x = 0.866_8
602 end program test_acos
605 @item @emph{Specific names}:
606 @multitable @columnfractions .20 .20 .20 .25
607 @item Name @tab Argument @tab Return type @tab Standard
608 @item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
609 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
612 @item @emph{See also}:
613 Inverse function: @ref{COS}
620 @section @code{ACOSH} --- Inverse hyperbolic cosine function
623 @cindex area hyperbolic cosine
624 @cindex inverse hyperbolic cosine
625 @cindex hyperbolic function, cosine, inverse
626 @cindex cosine, hyperbolic, inverse
629 @item @emph{Description}:
630 @code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
632 @item @emph{Standard}:
633 Fortran 2008 and later
639 @code{RESULT = ACOSH(X)}
641 @item @emph{Arguments}:
642 @multitable @columnfractions .15 .70
643 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
646 @item @emph{Return value}:
647 The return value has the same type and kind as @var{X}. If @var{X} is
648 complex, the imaginary part of the result is in radians and lies between
649 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
651 @item @emph{Example}:
654 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
659 @item @emph{Specific names}:
660 @multitable @columnfractions .20 .20 .20 .25
661 @item Name @tab Argument @tab Return type @tab Standard
662 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
665 @item @emph{See also}:
666 Inverse function: @ref{COSH}
672 @section @code{ADJUSTL} --- Left adjust a string
674 @cindex string, adjust left
675 @cindex adjust string
678 @item @emph{Description}:
679 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
680 Spaces are inserted at the end of the string as needed.
682 @item @emph{Standard}:
689 @code{RESULT = ADJUSTL(STRING)}
691 @item @emph{Arguments}:
692 @multitable @columnfractions .15 .70
693 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
696 @item @emph{Return value}:
697 The return value is of type @code{CHARACTER} and of the same kind as
698 @var{STRING} where leading spaces are removed and the same number of
699 spaces are inserted on the end of @var{STRING}.
701 @item @emph{Example}:
704 character(len=20) :: str = ' gfortran'
707 end program test_adjustl
710 @item @emph{See also}:
711 @ref{ADJUSTR}, @ref{TRIM}
717 @section @code{ADJUSTR} --- Right adjust a string
719 @cindex string, adjust right
720 @cindex adjust string
723 @item @emph{Description}:
724 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
725 Spaces are inserted at the start of the string as needed.
727 @item @emph{Standard}:
734 @code{RESULT = ADJUSTR(STRING)}
736 @item @emph{Arguments}:
737 @multitable @columnfractions .15 .70
738 @item @var{STR} @tab The type shall be @code{CHARACTER}.
741 @item @emph{Return value}:
742 The return value is of type @code{CHARACTER} and of the same kind as
743 @var{STRING} where trailing spaces are removed and the same number of
744 spaces are inserted at the start of @var{STRING}.
746 @item @emph{Example}:
749 character(len=20) :: str = 'gfortran'
752 end program test_adjustr
755 @item @emph{See also}:
756 @ref{ADJUSTL}, @ref{TRIM}
762 @section @code{AIMAG} --- Imaginary part of complex number
767 @cindex complex numbers, imaginary part
770 @item @emph{Description}:
771 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
772 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
773 for compatibility with @command{g77}, and their use in new code is
774 strongly discouraged.
776 @item @emph{Standard}:
777 Fortran 77 and later, has overloads that are GNU extensions
783 @code{RESULT = AIMAG(Z)}
785 @item @emph{Arguments}:
786 @multitable @columnfractions .15 .70
787 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
790 @item @emph{Return value}:
791 The return value is of type @code{REAL} with the
792 kind type parameter of the argument.
794 @item @emph{Example}:
799 z4 = cmplx(1.e0_4, 0.e0_4)
800 z8 = cmplx(0.e0_8, 1.e0_8)
801 print *, aimag(z4), dimag(z8)
802 end program test_aimag
805 @item @emph{Specific names}:
806 @multitable @columnfractions .20 .20 .20 .25
807 @item Name @tab Argument @tab Return type @tab Standard
808 @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
809 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
810 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
811 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
818 @section @code{AINT} --- Truncate to a whole number
822 @cindex rounding, floor
825 @item @emph{Description}:
826 @code{AINT(A [, KIND])} truncates its argument to a whole number.
828 @item @emph{Standard}:
835 @code{RESULT = AINT(A [, KIND])}
837 @item @emph{Arguments}:
838 @multitable @columnfractions .15 .70
839 @item @var{A} @tab The type of the argument shall be @code{REAL}.
840 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
841 expression indicating the kind parameter of the result.
844 @item @emph{Return value}:
845 The return value is of type @code{REAL} with the kind type parameter of the
846 argument if the optional @var{KIND} is absent; otherwise, the kind
847 type parameter will be given by @var{KIND}. If the magnitude of
848 @var{X} is less than one, @code{AINT(X)} returns zero. If the
849 magnitude is equal to or greater than one then it returns the largest
850 whole number that does not exceed its magnitude. The sign is the same
851 as the sign of @var{X}.
853 @item @emph{Example}:
860 print *, aint(x4), dint(x8)
862 end program test_aint
865 @item @emph{Specific names}:
866 @multitable @columnfractions .20 .20 .20 .25
867 @item Name @tab Argument @tab Return type @tab Standard
868 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
869 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
876 @section @code{ALARM} --- Execute a routine after a given delay
878 @cindex delayed execution
881 @item @emph{Description}:
882 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
883 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
884 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
885 supplied, it will be returned with the number of seconds remaining until
886 any previously scheduled alarm was due to be delivered, or zero if there
887 was no previously scheduled alarm.
889 @item @emph{Standard}:
896 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
898 @item @emph{Arguments}:
899 @multitable @columnfractions .15 .70
900 @item @var{SECONDS} @tab The type of the argument shall be a scalar
901 @code{INTEGER}. It is @code{INTENT(IN)}.
902 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
903 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
904 values may be either @code{SIG_IGN=1} to ignore the alarm generated
905 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
906 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
907 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
910 @item @emph{Example}:
913 external handler_print
915 call alarm (3, handler_print, i)
918 end program test_alarm
920 This will cause the external routine @var{handler_print} to be called
927 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
929 @cindex array, apply condition
930 @cindex array, condition testing
933 @item @emph{Description}:
934 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
935 in the array along dimension @var{DIM}.
937 @item @emph{Standard}:
941 Transformational function
944 @code{RESULT = ALL(MASK [, DIM])}
946 @item @emph{Arguments}:
947 @multitable @columnfractions .15 .70
948 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
949 it shall not be scalar.
950 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
951 with a value that lies between one and the rank of @var{MASK}.
954 @item @emph{Return value}:
955 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
956 the kind type parameter is the same as the kind type parameter of
957 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
958 an array with the rank of @var{MASK} minus 1. The shape is determined from
959 the shape of @var{MASK} where the @var{DIM} dimension is elided.
963 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
964 It also is true if @var{MASK} has zero size; otherwise, it is false.
966 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
967 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
968 is determined by applying @code{ALL} to the array sections.
971 @item @emph{Example}:
975 l = all((/.true., .true., .true./))
980 integer a(2,3), b(2,3)
984 print *, all(a .eq. b, 1)
985 print *, all(a .eq. b, 2)
986 end subroutine section
994 @section @code{ALLOCATED} --- Status of an allocatable entity
996 @cindex allocation, status
999 @item @emph{Description}:
1000 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
1001 status of @var{ARRAY} and @var{SCALAR}, respectively.
1003 @item @emph{Standard}:
1004 Fortran 95 and later. Note, the @code{SCALAR=} keyword and allocatable
1005 scalar entities are available in Fortran 2003 and later.
1010 @item @emph{Syntax}:
1011 @multitable @columnfractions .80
1012 @item @code{RESULT = ALLOCATED(ARRAY)}
1013 @item @code{RESULT = ALLOCATED(SCALAR)}
1016 @item @emph{Arguments}:
1017 @multitable @columnfractions .15 .70
1018 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
1019 @item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar.
1022 @item @emph{Return value}:
1023 The return value is a scalar @code{LOGICAL} with the default logical
1024 kind type parameter. If the argument is allocated, then the result is
1025 @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
1027 @item @emph{Example}:
1029 program test_allocated
1031 real(4), allocatable :: x(:)
1032 if (.not. allocated(x)) allocate(x(i))
1033 end program test_allocated
1040 @section @code{AND} --- Bitwise logical AND
1042 @cindex bitwise logical and
1043 @cindex logical and, bitwise
1046 @item @emph{Description}:
1047 Bitwise logical @code{AND}.
1049 This intrinsic routine is provided for backwards compatibility with
1050 GNU Fortran 77. For integer arguments, programmers should consider
1051 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1053 @item @emph{Standard}:
1059 @item @emph{Syntax}:
1060 @code{RESULT = AND(I, J)}
1062 @item @emph{Arguments}:
1063 @multitable @columnfractions .15 .70
1064 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1065 type or a scalar @code{LOGICAL} type.
1066 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1069 @item @emph{Return value}:
1070 The return type is either a scalar @code{INTEGER} or a scalar
1071 @code{LOGICAL}. If the kind type parameters differ, then the
1072 smaller kind type is implicitly converted to larger kind, and the
1073 return has the larger kind.
1075 @item @emph{Example}:
1078 LOGICAL :: T = .TRUE., F = .FALSE.
1080 DATA a / Z'F' /, b / Z'3' /
1082 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1083 WRITE (*,*) AND(a, b)
1087 @item @emph{See also}:
1088 Fortran 95 elemental function: @ref{IAND}
1094 @section @code{ANINT} --- Nearest whole number
1098 @cindex rounding, ceiling
1101 @item @emph{Description}:
1102 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1104 @item @emph{Standard}:
1105 Fortran 77 and later
1110 @item @emph{Syntax}:
1111 @code{RESULT = ANINT(A [, KIND])}
1113 @item @emph{Arguments}:
1114 @multitable @columnfractions .15 .70
1115 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1116 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1117 expression indicating the kind parameter of the result.
1120 @item @emph{Return value}:
1121 The return value is of type real with the kind type parameter of the
1122 argument if the optional @var{KIND} is absent; otherwise, the kind
1123 type parameter will be given by @var{KIND}. If @var{A} is greater than
1124 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1125 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1127 @item @emph{Example}:
1134 print *, anint(x4), dnint(x8)
1136 end program test_anint
1139 @item @emph{Specific names}:
1140 @multitable @columnfractions .20 .20 .20 .25
1141 @item Name @tab Argument @tab Return type @tab Standard
1142 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
1143 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1150 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1152 @cindex array, apply condition
1153 @cindex array, condition testing
1156 @item @emph{Description}:
1157 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1158 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1160 @item @emph{Standard}:
1161 Fortran 95 and later
1164 Transformational function
1166 @item @emph{Syntax}:
1167 @code{RESULT = ANY(MASK [, DIM])}
1169 @item @emph{Arguments}:
1170 @multitable @columnfractions .15 .70
1171 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1172 it shall not be scalar.
1173 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1174 with a value that lies between one and the rank of @var{MASK}.
1177 @item @emph{Return value}:
1178 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1179 the kind type parameter is the same as the kind type parameter of
1180 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1181 an array with the rank of @var{MASK} minus 1. The shape is determined from
1182 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1186 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1187 otherwise, it is false. It also is false if @var{MASK} has zero size.
1189 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1190 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1191 is determined by applying @code{ANY} to the array sections.
1194 @item @emph{Example}:
1198 l = any((/.true., .true., .true./))
1203 integer a(2,3), b(2,3)
1207 print *, any(a .eq. b, 1)
1208 print *, any(a .eq. b, 2)
1209 end subroutine section
1210 end program test_any
1217 @section @code{ASIN} --- Arcsine function
1220 @cindex trigonometric function, sine, inverse
1221 @cindex sine, inverse
1224 @item @emph{Description}:
1225 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1227 @item @emph{Standard}:
1228 Fortran 77 and later, for a complex argument Fortran 2008 or later
1233 @item @emph{Syntax}:
1234 @code{RESULT = ASIN(X)}
1236 @item @emph{Arguments}:
1237 @multitable @columnfractions .15 .70
1238 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1239 less than or equal to one - or be @code{COMPLEX}.
1242 @item @emph{Return value}:
1243 The return value is of the same type and kind as @var{X}.
1244 The real part of the result is in radians and lies in the range
1245 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1247 @item @emph{Example}:
1250 real(8) :: x = 0.866_8
1252 end program test_asin
1255 @item @emph{Specific names}:
1256 @multitable @columnfractions .20 .20 .20 .25
1257 @item Name @tab Argument @tab Return type @tab Standard
1258 @item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1259 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1262 @item @emph{See also}:
1263 Inverse function: @ref{SIN}
1270 @section @code{ASINH} --- Inverse hyperbolic sine function
1273 @cindex area hyperbolic sine
1274 @cindex inverse hyperbolic sine
1275 @cindex hyperbolic function, sine, inverse
1276 @cindex sine, hyperbolic, inverse
1279 @item @emph{Description}:
1280 @code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
1282 @item @emph{Standard}:
1283 Fortran 2008 and later
1288 @item @emph{Syntax}:
1289 @code{RESULT = ASINH(X)}
1291 @item @emph{Arguments}:
1292 @multitable @columnfractions .15 .70
1293 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1296 @item @emph{Return value}:
1297 The return value is of the same type and kind as @var{X}. If @var{X} is
1298 complex, the imaginary part of the result is in radians and lies between
1299 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1301 @item @emph{Example}:
1304 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1305 WRITE (*,*) ASINH(x)
1309 @item @emph{Specific names}:
1310 @multitable @columnfractions .20 .20 .20 .25
1311 @item Name @tab Argument @tab Return type @tab Standard
1312 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1315 @item @emph{See also}:
1316 Inverse function: @ref{SINH}
1322 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1324 @cindex pointer, status
1325 @cindex association status
1328 @item @emph{Description}:
1329 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1330 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1332 @item @emph{Standard}:
1333 Fortran 95 and later
1338 @item @emph{Syntax}:
1339 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1341 @item @emph{Arguments}:
1342 @multitable @columnfractions .15 .70
1343 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1344 and it can be of any type.
1345 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1346 a target. It must have the same type, kind type parameter, and
1347 array rank as @var{POINTER}.
1349 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1352 @item @emph{Return value}:
1353 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1354 There are several cases:
1356 @item (A) When the optional @var{TARGET} is not present then
1357 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1358 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1359 @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
1360 disassociated, the result is false.
1361 @item (C) If @var{TARGET} is present and an array target, the result is true if
1362 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1363 are arrays whose elements are not zero-sized storage sequences, and
1364 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1366 As in case(B), the result is false, if @var{POINTER} is disassociated.
1367 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1368 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1369 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1371 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1372 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1373 target associated with @var{POINTER} and the target associated with @var{TARGET}
1374 have the same shape, are not zero-sized arrays, are arrays whose elements are
1375 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1376 the same storage units in array element order.
1377 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1380 @item @emph{Example}:
1382 program test_associated
1384 real, target :: tgt(2) = (/1., 2./)
1385 real, pointer :: ptr(:)
1387 if (associated(ptr) .eqv. .false.) call abort
1388 if (associated(ptr,tgt) .eqv. .false.) call abort
1389 end program test_associated
1392 @item @emph{See also}:
1399 @section @code{ATAN} --- Arctangent function
1402 @cindex trigonometric function, tangent, inverse
1403 @cindex tangent, inverse
1406 @item @emph{Description}:
1407 @code{ATAN(X)} computes the arctangent of @var{X}.
1409 @item @emph{Standard}:
1410 Fortran 77 and later, for a complex argument and for two arguments
1411 Fortran 2008 or later
1416 @item @emph{Syntax}:
1417 @multitable @columnfractions .80
1418 @item @code{RESULT = ATAN(X)}
1419 @item @code{RESULT = ATAN(Y, X)}
1422 @item @emph{Arguments}:
1423 @multitable @columnfractions .15 .70
1424 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1425 if @var{Y} is present, @var{X} shall be REAL.
1426 @item @var{Y} shall be of the same type and kind as @var{X}.
1429 @item @emph{Return value}:
1430 The return value is of the same type and kind as @var{X}.
1431 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1432 Otherwise, it the arcus tangent of @var{X}, where the real part of
1433 the result is in radians and lies in the range
1434 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1436 @item @emph{Example}:
1439 real(8) :: x = 2.866_8
1441 end program test_atan
1444 @item @emph{Specific names}:
1445 @multitable @columnfractions .20 .20 .20 .25
1446 @item Name @tab Argument @tab Return type @tab Standard
1447 @item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1448 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1451 @item @emph{See also}:
1452 Inverse function: @ref{TAN}
1459 @section @code{ATAN2} --- Arctangent function
1462 @cindex trigonometric function, tangent, inverse
1463 @cindex tangent, inverse
1466 @item @emph{Description}:
1467 @code{ATAN2(Y, X)} computes the principal value of the argument
1468 function of the complex number @math{X + i Y}. This function can
1469 be used to transform from Cartesian into polar coordinates and
1470 allows to determine the angle in the correct quadrant.
1472 @item @emph{Standard}:
1473 Fortran 77 and later
1478 @item @emph{Syntax}:
1479 @code{RESULT = ATAN2(Y, X)}
1481 @item @emph{Arguments}:
1482 @multitable @columnfractions .15 .70
1483 @item @var{Y} @tab The type shall be @code{REAL}.
1484 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1485 If @var{Y} is zero, then @var{X} must be nonzero.
1488 @item @emph{Return value}:
1489 The return value has the same type and kind type parameter as @var{Y}. It
1490 is the principal value of the complex number @math{X + i Y}. If @var{X}
1491 is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1492 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1493 the return value is zero if @var{X} is strictly positive, @math{\pi} if
1494 @var{X} is negative and @var{Y} is positive zero (or the processor does
1495 not handle signed zeros), and @math{-\pi} if @var{X} is negative and
1496 @var{Y} is negative zero. Finally, if @var{X} is zero, then the
1497 magnitude of the result is @math{\pi/2}.
1499 @item @emph{Example}:
1502 real(4) :: x = 1.e0_4, y = 0.5e0_4
1504 end program test_atan2
1507 @item @emph{Specific names}:
1508 @multitable @columnfractions .20 .20 .20 .25
1509 @item Name @tab Argument @tab Return type @tab Standard
1510 @item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1511 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1518 @section @code{ATANH} --- Inverse hyperbolic tangent function
1521 @cindex area hyperbolic tangent
1522 @cindex inverse hyperbolic tangent
1523 @cindex hyperbolic function, tangent, inverse
1524 @cindex tangent, hyperbolic, inverse
1527 @item @emph{Description}:
1528 @code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
1530 @item @emph{Standard}:
1531 Fortran 2008 and later
1536 @item @emph{Syntax}:
1537 @code{RESULT = ATANH(X)}
1539 @item @emph{Arguments}:
1540 @multitable @columnfractions .15 .70
1541 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1544 @item @emph{Return value}:
1545 The return value has same type and kind as @var{X}. If @var{X} is
1546 complex, the imaginary part of the result is in radians and lies between
1547 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1549 @item @emph{Example}:
1552 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1553 WRITE (*,*) ATANH(x)
1557 @item @emph{Specific names}:
1558 @multitable @columnfractions .20 .20 .20 .25
1559 @item Name @tab Argument @tab Return type @tab Standard
1560 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1563 @item @emph{See also}:
1564 Inverse function: @ref{TANH}
1570 @section @code{ATOMIC_ADD} --- Atomic ADD operation
1572 @cindex Atomic subroutine, add
1575 @item @emph{Description}:
1576 @code{ATOMIC_ADD(ATOM, VALUE)} atomically adds the value of @var{VAR} to the
1577 variable @var{ATOM}. When @var{STAT} is present and the invokation was
1578 successful, it is assigned the value 0. If it is present and the invokation
1579 has failed, it is assigned a positive value; in particular, for a coindexed
1580 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1581 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1582 failed, the value @code{STAT_FAILED_IMAGE}.
1584 @item @emph{Standard}:
1590 @item @emph{Syntax}:
1591 @code{CALL ATOMIC_ADD (ATOM, VALUE [, STAT])}
1593 @item @emph{Arguments}:
1594 @multitable @columnfractions .15 .70
1595 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1596 type with @code{ATOMIC_INT_KIND} kind.
1597 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1598 is different, the value is converted to the kind of @var{ATOM}.
1599 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1602 @item @emph{Example}:
1606 integer(atomic_int_kind) :: atom[*]
1607 call atomic_add (atom[1], this_image())
1611 @item @emph{See also}:
1612 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_ADD}, @ref{ISO_FORTRAN_ENV},
1613 @ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
1620 @section @code{ATOMIC_AND} --- Atomic bitwise AND operation
1622 @cindex Atomic subroutine, AND
1625 @item @emph{Description}:
1626 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
1627 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
1628 and the invokation was successful, it is assigned the value 0. If it is present
1629 and the invokation has failed, it is assigned a positive value; in particular,
1630 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
1631 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
1632 image has failed, the value @code{STAT_FAILED_IMAGE}.
1634 @item @emph{Standard}:
1640 @item @emph{Syntax}:
1641 @code{CALL ATOMIC_AND (ATOM, VALUE [, STAT])}
1643 @item @emph{Arguments}:
1644 @multitable @columnfractions .15 .70
1645 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1646 type with @code{ATOMIC_INT_KIND} kind.
1647 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1648 is different, the value is converted to the kind of @var{ATOM}.
1649 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1652 @item @emph{Example}:
1656 integer(atomic_int_kind) :: atom[*]
1657 call atomic_and (atom[1], int(b'10100011101'))
1661 @item @emph{See also}:
1662 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_AND}, @ref{ISO_FORTRAN_ENV},
1663 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
1669 @section @code{ATOMIC_CAS} --- Atomic compare and swap
1670 @fnindex ATOMIC_DEFINE
1671 @cindex Atomic subroutine, compare and swap
1674 @item @emph{Description}:
1675 @code{ATOMIC_CAS} compares the variable @var{ATOM} with the value of
1676 @var{COMPARE}; if the value is the same, @var{ATOM} is set to the value
1677 of @var{NEW}. Additionally, @var{OLD} is set to the value of @var{ATOM}
1678 that was used for the comparison. When @var{STAT} is present and the invokation
1679 was successful, it is assigned the value 0. If it is present and the invokation
1680 has failed, it is assigned a positive value; in particular, for a coindexed
1681 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1682 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1683 failed, the value @code{STAT_FAILED_IMAGE}.
1685 @item @emph{Standard}:
1691 @item @emph{Syntax}:
1692 @code{CALL ATOMIC_CAS (ATOM, OLD, COMPARE, NEW [, STAT])}
1694 @item @emph{Arguments}:
1695 @multitable @columnfractions .15 .70
1696 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
1697 type with @code{ATOMIC_INT_KIND} kind or logical type with
1698 @code{ATOMIC_LOGICAL_KIND} kind.
1699 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1700 @item @var{COMPARE} @tab Scalar variable of the same type and kind as
1702 @item @var{NEW} @tab Scalar variable of the same type as @var{ATOM}. If kind
1703 is different, the value is converted to the kind of @var{ATOM}.
1704 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1707 @item @emph{Example}:
1711 logical(atomic_logical_kind) :: atom[*], prev
1712 call atomic_cas (atom[1], prev, .false., .true.))
1716 @item @emph{See also}:
1717 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_REF}, @ref{ISO_FORTRAN_ENV}
1723 @section @code{ATOMIC_DEFINE} --- Setting a variable atomically
1724 @fnindex ATOMIC_DEFINE
1725 @cindex Atomic subroutine, define
1728 @item @emph{Description}:
1729 @code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value
1730 @var{VALUE} atomically. When @var{STAT} is present and the invokation was
1731 successful, it is assigned the value 0. If it is present and the invokation
1732 has failed, it is assigned a positive value; in particular, for a coindexed
1733 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1734 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1735 failed, the value @code{STAT_FAILED_IMAGE}.
1737 @item @emph{Standard}:
1738 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
1743 @item @emph{Syntax}:
1744 @code{CALL ATOMIC_DEFINE (ATOM, VALUE [, STAT])}
1746 @item @emph{Arguments}:
1747 @multitable @columnfractions .15 .70
1748 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
1749 type with @code{ATOMIC_INT_KIND} kind or logical type with
1750 @code{ATOMIC_LOGICAL_KIND} kind.
1752 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1753 is different, the value is converted to the kind of @var{ATOM}.
1754 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1757 @item @emph{Example}:
1761 integer(atomic_int_kind) :: atom[*]
1762 call atomic_define (atom[1], this_image())
1766 @item @emph{See also}:
1767 @ref{ATOMIC_REF}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV},
1768 @ref{ATOMIC_ADD}, @ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
1773 @node ATOMIC_FETCH_ADD
1774 @section @code{ATOMIC_FETCH_ADD} --- Atomic ADD operation with prior fetch
1775 @fnindex ATOMIC_FETCH_ADD
1776 @cindex Atomic subroutine, ADD with fetch
1779 @item @emph{Description}:
1780 @code{ATOMIC_FETCH_ADD(ATOM, VALUE, OLD)} atomically stores the value of
1781 @var{ATOM} in @var{OLD} and adds the value of @var{VAR} to the
1782 variable @var{ATOM}. When @var{STAT} is present and the invokation was
1783 successful, it is assigned the value 0. If it is present and the invokation
1784 has failed, it is assigned a positive value; in particular, for a coindexed
1785 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1786 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1787 failed, the value @code{STAT_FAILED_IMAGE}.
1789 @item @emph{Standard}:
1795 @item @emph{Syntax}:
1796 @code{CALL ATOMIC_FETCH_ADD (ATOM, VALUE, old [, STAT])}
1798 @item @emph{Arguments}:
1799 @multitable @columnfractions .15 .70
1800 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1801 type with @code{ATOMIC_INT_KIND} kind.
1802 @code{ATOMIC_LOGICAL_KIND} kind.
1804 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1805 is different, the value is converted to the kind of @var{ATOM}.
1806 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1807 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1810 @item @emph{Example}:
1814 integer(atomic_int_kind) :: atom[*], old
1815 call atomic_add (atom[1], this_image(), old)
1819 @item @emph{See also}:
1820 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_ADD}, @ref{ISO_FORTRAN_ENV},
1821 @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR}
1826 @node ATOMIC_FETCH_AND
1827 @section @code{ATOMIC_FETCH_AND} --- Atomic bitwise AND operation with prior fetch
1828 @fnindex ATOMIC_FETCH_AND
1829 @cindex Atomic subroutine, AND with fetch
1832 @item @emph{Description}:
1833 @code{ATOMIC_AND(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
1834 @var{OLD} and defines @var{ATOM} with the bitwise AND between the values of
1835 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was
1836 successful, it is assigned the value 0. If it is present and the invokation has
1837 failed, it is assigned a positive value; in particular, for a coindexed
1838 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1839 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1840 failed, the value @code{STAT_FAILED_IMAGE}.
1842 @item @emph{Standard}:
1848 @item @emph{Syntax}:
1849 @code{CALL ATOMIC_FETCH_AND (ATOM, VALUE, OLD [, STAT])}
1851 @item @emph{Arguments}:
1852 @multitable @columnfractions .15 .70
1853 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1854 type with @code{ATOMIC_INT_KIND} kind.
1855 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1856 is different, the value is converted to the kind of @var{ATOM}.
1857 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1858 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1861 @item @emph{Example}:
1865 integer(atomic_int_kind) :: atom[*], old
1866 call atomic_fetch_and (atom[1], int(b'10100011101'), old)
1870 @item @emph{See also}:
1871 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_AND}, @ref{ISO_FORTRAN_ENV},
1872 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR}
1877 @node ATOMIC_FETCH_OR
1878 @section @code{ATOMIC_FETCH_OR} --- Atomic bitwise OR operation with prior fetch
1879 @fnindex ATOMIC_FETCH_OR
1880 @cindex Atomic subroutine, OR with fetch
1883 @item @emph{Description}:
1884 @code{ATOMIC_OR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
1885 @var{OLD} and defines @var{ATOM} with the bitwise OR between the values of
1886 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was
1887 successful, it is assigned the value 0. If it is present and the invokation has
1888 failed, it is assigned a positive value; in particular, for a coindexed
1889 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1890 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1891 failed, the value @code{STAT_FAILED_IMAGE}.
1893 @item @emph{Standard}:
1899 @item @emph{Syntax}:
1900 @code{CALL ATOMIC_FETCH_OR (ATOM, VALUE, OLD [, STAT])}
1902 @item @emph{Arguments}:
1903 @multitable @columnfractions .15 .70
1904 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1905 type with @code{ATOMIC_INT_KIND} kind.
1906 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1907 is different, the value is converted to the kind of @var{ATOM}.
1908 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1909 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1912 @item @emph{Example}:
1916 integer(atomic_int_kind) :: atom[*], old
1917 call atomic_fetch_or (atom[1], int(b'10100011101'), old)
1921 @item @emph{See also}:
1922 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_OR}, @ref{ISO_FORTRAN_ENV},
1923 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_XOR}
1928 @node ATOMIC_FETCH_XOR
1929 @section @code{ATOMIC_FETCH_XOR} --- Atomic bitwise XOR operation with prior fetch
1930 @fnindex ATOMIC_FETCH_XOR
1931 @cindex Atomic subroutine, XOR with fetch
1934 @item @emph{Description}:
1935 @code{ATOMIC_XOR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
1936 @var{OLD} and defines @var{ATOM} with the bitwise XOR between the values of
1937 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was
1938 successful, it is assigned the value 0. If it is present and the invokation has
1939 failed, it is assigned a positive value; in particular, for a coindexed
1940 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1941 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1942 failed, the value @code{STAT_FAILED_IMAGE}.
1944 @item @emph{Standard}:
1950 @item @emph{Syntax}:
1951 @code{CALL ATOMIC_FETCH_XOR (ATOM, VALUE, OLD [, STAT])}
1953 @item @emph{Arguments}:
1954 @multitable @columnfractions .15 .70
1955 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1956 type with @code{ATOMIC_INT_KIND} kind.
1957 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1958 is different, the value is converted to the kind of @var{ATOM}.
1959 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1960 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1963 @item @emph{Example}:
1967 integer(atomic_int_kind) :: atom[*], old
1968 call atomic_fetch_xor (atom[1], int(b'10100011101'), old)
1972 @item @emph{See also}:
1973 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_XOR}, @ref{ISO_FORTRAN_ENV},
1974 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}
1980 @section @code{ATOMIC_OR} --- Atomic bitwise OR operation
1982 @cindex Atomic subroutine, OR
1985 @item @emph{Description}:
1986 @code{ATOMIC_OR(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
1987 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
1988 and the invokation was successful, it is assigned the value 0. If it is present
1989 and the invokation has failed, it is assigned a positive value; in particular,
1990 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
1991 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
1992 image has failed, the value @code{STAT_FAILED_IMAGE}.
1994 @item @emph{Standard}:
2000 @item @emph{Syntax}:
2001 @code{CALL ATOMIC_OR (ATOM, VALUE [, STAT])}
2003 @item @emph{Arguments}:
2004 @multitable @columnfractions .15 .70
2005 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2006 type with @code{ATOMIC_INT_KIND} kind.
2007 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2008 is different, the value is converted to the kind of @var{ATOM}.
2009 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2012 @item @emph{Example}:
2016 integer(atomic_int_kind) :: atom[*]
2017 call atomic_or (atom[1], int(b'10100011101'))
2021 @item @emph{See also}:
2022 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_OR}, @ref{ISO_FORTRAN_ENV},
2023 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
2029 @section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically
2031 @cindex Atomic subroutine, reference
2034 @item @emph{Description}:
2035 @code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the
2036 variable @var{ATOM} to @var{VALUE}. When @var{STAT} is present and the
2037 invokation was successful, it is assigned the value 0. If it is present and the
2038 invokation has failed, it is assigned a positive value; in particular, for a
2039 coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value
2040 of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image
2041 has failed, the value @code{STAT_FAILED_IMAGE}.
2044 @item @emph{Standard}:
2045 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
2050 @item @emph{Syntax}:
2051 @code{CALL ATOMIC_REF(VALUE, ATOM [, STAT])}
2053 @item @emph{Arguments}:
2054 @multitable @columnfractions .15 .70
2055 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2056 is different, the value is converted to the kind of @var{ATOM}.
2057 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
2058 type with @code{ATOMIC_INT_KIND} kind or logical type with
2059 @code{ATOMIC_LOGICAL_KIND} kind.
2060 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2063 @item @emph{Example}:
2067 logical(atomic_logical_kind) :: atom[*]
2069 call atomic_ref (atom, .false.)
2071 call atomic_ref (atom, val)
2078 @item @emph{See also}:
2079 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV},
2080 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR},
2081 @ref{ATOMIC_FETCH_XOR}
2086 @section @code{ATOMIC_XOR} --- Atomic bitwise OR operation
2088 @cindex Atomic subroutine, XOR
2091 @item @emph{Description}:
2092 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
2093 XOR between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
2094 and the invokation was successful, it is assigned the value 0. If it is present
2095 and the invokation has failed, it is assigned a positive value; in particular,
2096 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
2097 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
2098 image has failed, the value @code{STAT_FAILED_IMAGE}.
2100 @item @emph{Standard}:
2106 @item @emph{Syntax}:
2107 @code{CALL ATOMIC_XOR (ATOM, VALUE [, STAT])}
2109 @item @emph{Arguments}:
2110 @multitable @columnfractions .15 .70
2111 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2112 type with @code{ATOMIC_INT_KIND} kind.
2113 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2114 is different, the value is converted to the kind of @var{ATOM}.
2115 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2118 @item @emph{Example}:
2122 integer(atomic_int_kind) :: atom[*]
2123 call atomic_xor (atom[1], int(b'10100011101'))
2127 @item @emph{See also}:
2128 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_XOR}, @ref{ISO_FORTRAN_ENV},
2129 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
2134 @section @code{BACKTRACE} --- Show a backtrace
2139 @item @emph{Description}:
2140 @code{BACKTRACE} shows a backtrace at an arbitrary place in user code. Program
2141 execution continues normally afterwards. The backtrace information is printed
2142 to the unit corresponding to @code{ERROR_UNIT} in @code{ISO_FORTRAN_ENV}.
2144 @item @emph{Standard}:
2150 @item @emph{Syntax}:
2151 @code{CALL BACKTRACE}
2153 @item @emph{Arguments}:
2156 @item @emph{See also}:
2163 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
2167 @cindex Bessel function, first kind
2170 @item @emph{Description}:
2171 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
2172 order 0 of @var{X}. This function is available under the name
2173 @code{BESJ0} as a GNU extension.
2175 @item @emph{Standard}:
2176 Fortran 2008 and later
2181 @item @emph{Syntax}:
2182 @code{RESULT = BESSEL_J0(X)}
2184 @item @emph{Arguments}:
2185 @multitable @columnfractions .15 .70
2186 @item @var{X} @tab The type shall be @code{REAL}.
2189 @item @emph{Return value}:
2190 The return value is of type @code{REAL} and lies in the
2191 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
2194 @item @emph{Example}:
2197 real(8) :: x = 0.0_8
2199 end program test_besj0
2202 @item @emph{Specific names}:
2203 @multitable @columnfractions .20 .20 .20 .25
2204 @item Name @tab Argument @tab Return type @tab Standard
2205 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2212 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
2216 @cindex Bessel function, first kind
2219 @item @emph{Description}:
2220 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
2221 order 1 of @var{X}. This function is available under the name
2222 @code{BESJ1} as a GNU extension.
2224 @item @emph{Standard}:
2230 @item @emph{Syntax}:
2231 @code{RESULT = BESSEL_J1(X)}
2233 @item @emph{Arguments}:
2234 @multitable @columnfractions .15 .70
2235 @item @var{X} @tab The type shall be @code{REAL}.
2238 @item @emph{Return value}:
2239 The return value is of type @code{REAL} and lies in the
2240 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
2243 @item @emph{Example}:
2246 real(8) :: x = 1.0_8
2248 end program test_besj1
2251 @item @emph{Specific names}:
2252 @multitable @columnfractions .20 .20 .20 .25
2253 @item Name @tab Argument @tab Return type @tab Standard
2254 @item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2261 @section @code{BESSEL_JN} --- Bessel function of the first kind
2265 @cindex Bessel function, first kind
2268 @item @emph{Description}:
2269 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
2270 order @var{N} of @var{X}. This function is available under the name
2271 @code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays,
2272 their ranks and shapes shall conform.
2274 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
2275 of the first kind of the orders @var{N1} to @var{N2}.
2277 @item @emph{Standard}:
2278 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2281 Elemental function, except for the transformational function
2282 @code{BESSEL_JN(N1, N2, X)}
2284 @item @emph{Syntax}:
2285 @multitable @columnfractions .80
2286 @item @code{RESULT = BESSEL_JN(N, X)}
2287 @item @code{RESULT = BESSEL_JN(N1, N2, X)}
2290 @item @emph{Arguments}:
2291 @multitable @columnfractions .15 .70
2292 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
2293 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2294 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2295 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2296 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
2299 @item @emph{Return value}:
2300 The return value is a scalar of type @code{REAL}. It has the same
2304 The transformational function uses a recurrence algorithm which might,
2305 for some values of @var{X}, lead to different results than calls to
2306 the elemental function.
2308 @item @emph{Example}:
2311 real(8) :: x = 1.0_8
2313 end program test_besjn
2316 @item @emph{Specific names}:
2317 @multitable @columnfractions .20 .20 .20 .25
2318 @item Name @tab Argument @tab Return type @tab Standard
2319 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2320 @item @tab @code{REAL(8) X} @tab @tab
2327 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
2331 @cindex Bessel function, second kind
2334 @item @emph{Description}:
2335 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
2336 order 0 of @var{X}. This function is available under the name
2337 @code{BESY0} as a GNU extension.
2339 @item @emph{Standard}:
2340 Fortran 2008 and later
2345 @item @emph{Syntax}:
2346 @code{RESULT = BESSEL_Y0(X)}
2348 @item @emph{Arguments}:
2349 @multitable @columnfractions .15 .70
2350 @item @var{X} @tab The type shall be @code{REAL}.
2353 @item @emph{Return value}:
2354 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2356 @item @emph{Example}:
2359 real(8) :: x = 0.0_8
2361 end program test_besy0
2364 @item @emph{Specific names}:
2365 @multitable @columnfractions .20 .20 .20 .25
2366 @item Name @tab Argument @tab Return type @tab Standard
2367 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2374 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
2378 @cindex Bessel function, second kind
2381 @item @emph{Description}:
2382 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
2383 order 1 of @var{X}. This function is available under the name
2384 @code{BESY1} as a GNU extension.
2386 @item @emph{Standard}:
2387 Fortran 2008 and later
2392 @item @emph{Syntax}:
2393 @code{RESULT = BESSEL_Y1(X)}
2395 @item @emph{Arguments}:
2396 @multitable @columnfractions .15 .70
2397 @item @var{X} @tab The type shall be @code{REAL}.
2400 @item @emph{Return value}:
2401 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2403 @item @emph{Example}:
2406 real(8) :: x = 1.0_8
2408 end program test_besy1
2411 @item @emph{Specific names}:
2412 @multitable @columnfractions .20 .20 .20 .25
2413 @item Name @tab Argument @tab Return type @tab Standard
2414 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2421 @section @code{BESSEL_YN} --- Bessel function of the second kind
2425 @cindex Bessel function, second kind
2428 @item @emph{Description}:
2429 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
2430 order @var{N} of @var{X}. This function is available under the name
2431 @code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays,
2432 their ranks and shapes shall conform.
2434 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
2435 of the first kind of the orders @var{N1} to @var{N2}.
2437 @item @emph{Standard}:
2438 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2441 Elemental function, except for the transformational function
2442 @code{BESSEL_YN(N1, N2, X)}
2444 @item @emph{Syntax}:
2445 @multitable @columnfractions .80
2446 @item @code{RESULT = BESSEL_YN(N, X)}
2447 @item @code{RESULT = BESSEL_YN(N1, N2, X)}
2450 @item @emph{Arguments}:
2451 @multitable @columnfractions .15 .70
2452 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} .
2453 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2454 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2455 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2456 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
2459 @item @emph{Return value}:
2460 The return value is a scalar of type @code{REAL}. It has the same
2464 The transformational function uses a recurrence algorithm which might,
2465 for some values of @var{X}, lead to different results than calls to
2466 the elemental function.
2468 @item @emph{Example}:
2471 real(8) :: x = 1.0_8
2473 end program test_besyn
2476 @item @emph{Specific names}:
2477 @multitable @columnfractions .20 .20 .20 .25
2478 @item Name @tab Argument @tab Return type @tab Standard
2479 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2480 @item @tab @code{REAL(8) X} @tab @tab
2487 @section @code{BGE} --- Bitwise greater than or equal to
2489 @cindex bitwise comparison
2492 @item @emph{Description}:
2493 Determines whether an integral is a bitwise greater than or equal to
2496 @item @emph{Standard}:
2497 Fortran 2008 and later
2502 @item @emph{Syntax}:
2503 @code{RESULT = BGE(I, J)}
2505 @item @emph{Arguments}:
2506 @multitable @columnfractions .15 .70
2507 @item @var{I} @tab Shall be of @code{INTEGER} type.
2508 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2512 @item @emph{Return value}:
2513 The return value is of type @code{LOGICAL} and of the default kind.
2515 @item @emph{See also}:
2516 @ref{BGT}, @ref{BLE}, @ref{BLT}
2522 @section @code{BGT} --- Bitwise greater than
2524 @cindex bitwise comparison
2527 @item @emph{Description}:
2528 Determines whether an integral is a bitwise greater than another.
2530 @item @emph{Standard}:
2531 Fortran 2008 and later
2536 @item @emph{Syntax}:
2537 @code{RESULT = BGT(I, J)}
2539 @item @emph{Arguments}:
2540 @multitable @columnfractions .15 .70
2541 @item @var{I} @tab Shall be of @code{INTEGER} type.
2542 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2546 @item @emph{Return value}:
2547 The return value is of type @code{LOGICAL} and of the default kind.
2549 @item @emph{See also}:
2550 @ref{BGE}, @ref{BLE}, @ref{BLT}
2556 @section @code{BIT_SIZE} --- Bit size inquiry function
2558 @cindex bits, number of
2559 @cindex size of a variable, in bits
2562 @item @emph{Description}:
2563 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
2564 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
2565 independent of the actual value of @var{I}.
2567 @item @emph{Standard}:
2568 Fortran 95 and later
2573 @item @emph{Syntax}:
2574 @code{RESULT = BIT_SIZE(I)}
2576 @item @emph{Arguments}:
2577 @multitable @columnfractions .15 .70
2578 @item @var{I} @tab The type shall be @code{INTEGER}.
2581 @item @emph{Return value}:
2582 The return value is of type @code{INTEGER}
2584 @item @emph{Example}:
2586 program test_bit_size
2591 end program test_bit_size
2598 @section @code{BLE} --- Bitwise less than or equal to
2600 @cindex bitwise comparison
2603 @item @emph{Description}:
2604 Determines whether an integral is a bitwise less than or equal to
2607 @item @emph{Standard}:
2608 Fortran 2008 and later
2613 @item @emph{Syntax}:
2614 @code{RESULT = BLE(I, J)}
2616 @item @emph{Arguments}:
2617 @multitable @columnfractions .15 .70
2618 @item @var{I} @tab Shall be of @code{INTEGER} type.
2619 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2623 @item @emph{Return value}:
2624 The return value is of type @code{LOGICAL} and of the default kind.
2626 @item @emph{See also}:
2627 @ref{BGT}, @ref{BGE}, @ref{BLT}
2633 @section @code{BLT} --- Bitwise less than
2635 @cindex bitwise comparison
2638 @item @emph{Description}:
2639 Determines whether an integral is a bitwise less than another.
2641 @item @emph{Standard}:
2642 Fortran 2008 and later
2647 @item @emph{Syntax}:
2648 @code{RESULT = BLT(I, J)}
2650 @item @emph{Arguments}:
2651 @multitable @columnfractions .15 .70
2652 @item @var{I} @tab Shall be of @code{INTEGER} type.
2653 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2657 @item @emph{Return value}:
2658 The return value is of type @code{LOGICAL} and of the default kind.
2660 @item @emph{See also}:
2661 @ref{BGE}, @ref{BGT}, @ref{BLE}
2667 @section @code{BTEST} --- Bit test function
2669 @cindex bits, testing
2672 @item @emph{Description}:
2673 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
2674 in @var{I} is set. The counting of the bits starts at 0.
2676 @item @emph{Standard}:
2677 Fortran 95 and later
2682 @item @emph{Syntax}:
2683 @code{RESULT = BTEST(I, POS)}
2685 @item @emph{Arguments}:
2686 @multitable @columnfractions .15 .70
2687 @item @var{I} @tab The type shall be @code{INTEGER}.
2688 @item @var{POS} @tab The type shall be @code{INTEGER}.
2691 @item @emph{Return value}:
2692 The return value is of type @code{LOGICAL}
2694 @item @emph{Example}:
2697 integer :: i = 32768 + 1024 + 64
2701 bool = btest(i, pos)
2704 end program test_btest
2710 @section @code{C_ASSOCIATED} --- Status of a C pointer
2711 @fnindex C_ASSOCIATED
2712 @cindex association status, C pointer
2713 @cindex pointer, C association status
2716 @item @emph{Description}:
2717 @code{C_ASSOCIATED(c_ptr_1[, c_ptr_2])} determines the status of the C pointer
2718 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
2720 @item @emph{Standard}:
2721 Fortran 2003 and later
2726 @item @emph{Syntax}:
2727 @code{RESULT = C_ASSOCIATED(c_ptr_1[, c_ptr_2])}
2729 @item @emph{Arguments}:
2730 @multitable @columnfractions .15 .70
2731 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
2732 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
2735 @item @emph{Return value}:
2736 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
2737 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
2738 point to different addresses.
2740 @item @emph{Example}:
2742 subroutine association_test(a,b)
2743 use iso_c_binding, only: c_associated, c_loc, c_ptr
2747 if(c_associated(b, c_loc(a))) &
2748 stop 'b and a do not point to same target'
2749 end subroutine association_test
2752 @item @emph{See also}:
2753 @ref{C_LOC}, @ref{C_FUNLOC}
2758 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2759 @fnindex C_F_POINTER
2760 @cindex pointer, convert C to Fortran
2763 @item @emph{Description}:
2764 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} assigns the target of the C pointer
2765 @var{CPTR} to the Fortran pointer @var{FPTR} and specifies its shape.
2767 @item @emph{Standard}:
2768 Fortran 2003 and later
2773 @item @emph{Syntax}:
2774 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2776 @item @emph{Arguments}:
2777 @multitable @columnfractions .15 .70
2778 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
2780 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
2782 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2783 with @code{INTENT(IN)}. It shall be present
2784 if and only if @var{fptr} is an array. The size
2785 must be equal to the rank of @var{fptr}.
2788 @item @emph{Example}:
2794 subroutine my_routine(p) bind(c,name='myC_func')
2796 type(c_ptr), intent(out) :: p
2800 real,pointer :: a(:)
2801 call my_routine(cptr)
2802 call c_f_pointer(cptr, a, [12])
2806 @item @emph{See also}:
2807 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2811 @node C_F_PROCPOINTER
2812 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
2813 @fnindex C_F_PROCPOINTER
2814 @cindex pointer, C address of pointers
2817 @item @emph{Description}:
2818 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
2819 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
2821 @item @emph{Standard}:
2822 Fortran 2003 and later
2827 @item @emph{Syntax}:
2828 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2830 @item @emph{Arguments}:
2831 @multitable @columnfractions .15 .70
2832 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
2834 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
2838 @item @emph{Example}:
2846 real(c_float), intent(in) :: a
2847 real(c_float) :: func
2851 function getIterFunc() bind(c,name="getIterFunc")
2853 type(c_funptr) :: getIterFunc
2856 type(c_funptr) :: cfunptr
2857 procedure(func), pointer :: myFunc
2858 cfunptr = getIterFunc()
2859 call c_f_procpointer(cfunptr, myFunc)
2863 @item @emph{See also}:
2864 @ref{C_LOC}, @ref{C_F_POINTER}
2869 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
2871 @cindex pointer, C address of procedures
2874 @item @emph{Description}:
2875 @code{C_FUNLOC(x)} determines the C address of the argument.
2877 @item @emph{Standard}:
2878 Fortran 2003 and later
2883 @item @emph{Syntax}:
2884 @code{RESULT = C_FUNLOC(x)}
2886 @item @emph{Arguments}:
2887 @multitable @columnfractions .15 .70
2888 @item @var{x} @tab Interoperable function or pointer to such function.
2891 @item @emph{Return value}:
2892 The return value is of type @code{C_FUNPTR} and contains the C address
2895 @item @emph{Example}:
2901 subroutine sub(a) bind(c)
2911 subroutine my_routine(p) bind(c,name='myC_func')
2913 type(c_funptr), intent(in) :: p
2916 call my_routine(c_funloc(sub))
2920 @item @emph{See also}:
2921 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2926 @section @code{C_LOC} --- Obtain the C address of an object
2928 @cindex procedure pointer, convert C to Fortran
2931 @item @emph{Description}:
2932 @code{C_LOC(X)} determines the C address of the argument.
2934 @item @emph{Standard}:
2935 Fortran 2003 and later
2940 @item @emph{Syntax}:
2941 @code{RESULT = C_LOC(X)}
2943 @item @emph{Arguments}:
2944 @multitable @columnfractions .10 .75
2945 @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.
2949 @item @emph{Return value}:
2950 The return value is of type @code{C_PTR} and contains the C address
2953 @item @emph{Example}:
2955 subroutine association_test(a,b)
2956 use iso_c_binding, only: c_associated, c_loc, c_ptr
2960 if(c_associated(b, c_loc(a))) &
2961 stop 'b and a do not point to same target'
2962 end subroutine association_test
2965 @item @emph{See also}:
2966 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2971 @section @code{C_SIZEOF} --- Size in bytes of an expression
2973 @cindex expression size
2974 @cindex size of an expression
2977 @item @emph{Description}:
2978 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
2979 expression @code{X} occupies.
2981 @item @emph{Standard}:
2985 Inquiry function of the module @code{ISO_C_BINDING}
2987 @item @emph{Syntax}:
2988 @code{N = C_SIZEOF(X)}
2990 @item @emph{Arguments}:
2991 @multitable @columnfractions .15 .70
2992 @item @var{X} @tab The argument shall be an interoperable data entity.
2995 @item @emph{Return value}:
2996 The return value is of type integer and of the system-dependent kind
2997 @code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the
2998 number of bytes occupied by the argument. If the argument has the
2999 @code{POINTER} attribute, the number of bytes of the storage area pointed
3000 to is returned. If the argument is of a derived type with @code{POINTER}
3001 or @code{ALLOCATABLE} components, the return value does not account for
3002 the sizes of the data pointed to by these components.
3004 @item @emph{Example}:
3008 real(c_float) :: r, s(5)
3009 print *, (c_sizeof(s)/c_sizeof(r) == 5)
3012 The example will print @code{.TRUE.} unless you are using a platform
3013 where default @code{REAL} variables are unusually padded.
3015 @item @emph{See also}:
3016 @ref{SIZEOF}, @ref{STORAGE_SIZE}
3021 @section @code{CEILING} --- Integer ceiling function
3024 @cindex rounding, ceiling
3027 @item @emph{Description}:
3028 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
3030 @item @emph{Standard}:
3031 Fortran 95 and later
3036 @item @emph{Syntax}:
3037 @code{RESULT = CEILING(A [, KIND])}
3039 @item @emph{Arguments}:
3040 @multitable @columnfractions .15 .70
3041 @item @var{A} @tab The type shall be @code{REAL}.
3042 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3043 expression indicating the kind parameter of the result.
3046 @item @emph{Return value}:
3047 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
3048 and a default-kind @code{INTEGER} otherwise.
3050 @item @emph{Example}:
3052 program test_ceiling
3055 print *, ceiling(x) ! returns 64
3056 print *, ceiling(y) ! returns -63
3057 end program test_ceiling
3060 @item @emph{See also}:
3061 @ref{FLOOR}, @ref{NINT}
3068 @section @code{CHAR} --- Character conversion function
3070 @cindex conversion, to character
3073 @item @emph{Description}:
3074 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
3076 @item @emph{Standard}:
3077 Fortran 77 and later
3082 @item @emph{Syntax}:
3083 @code{RESULT = CHAR(I [, KIND])}
3085 @item @emph{Arguments}:
3086 @multitable @columnfractions .15 .70
3087 @item @var{I} @tab The type shall be @code{INTEGER}.
3088 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3089 expression indicating the kind parameter of the result.
3092 @item @emph{Return value}:
3093 The return value is of type @code{CHARACTER(1)}
3095 @item @emph{Example}:
3101 print *, i, c ! returns 'J'
3102 end program test_char
3105 @item @emph{Specific names}:
3106 @multitable @columnfractions .20 .20 .20 .25
3107 @item Name @tab Argument @tab Return type @tab Standard
3108 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
3112 See @ref{ICHAR} for a discussion of converting between numerical values
3113 and formatted string representations.
3115 @item @emph{See also}:
3116 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
3123 @section @code{CHDIR} --- Change working directory
3125 @cindex system, working directory
3128 @item @emph{Description}:
3129 Change current working directory to a specified path.
3131 This intrinsic is provided in both subroutine and function forms; however,
3132 only one form can be used in any given program unit.
3134 @item @emph{Standard}:
3138 Subroutine, function
3140 @item @emph{Syntax}:
3141 @multitable @columnfractions .80
3142 @item @code{CALL CHDIR(NAME [, STATUS])}
3143 @item @code{STATUS = CHDIR(NAME)}
3146 @item @emph{Arguments}:
3147 @multitable @columnfractions .15 .70
3148 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
3149 kind and shall specify a valid path within the file system.
3150 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
3151 kind. Returns 0 on success, and a system specific and nonzero error code
3155 @item @emph{Example}:
3158 CHARACTER(len=255) :: path
3160 WRITE(*,*) TRIM(path)
3163 WRITE(*,*) TRIM(path)
3167 @item @emph{See also}:
3174 @section @code{CHMOD} --- Change access permissions of files
3176 @cindex file system, change access mode
3179 @item @emph{Description}:
3180 @code{CHMOD} changes the permissions of a file.
3182 This intrinsic is provided in both subroutine and function forms; however,
3183 only one form can be used in any given program unit.
3185 @item @emph{Standard}:
3189 Subroutine, function
3191 @item @emph{Syntax}:
3192 @multitable @columnfractions .80
3193 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
3194 @item @code{STATUS = CHMOD(NAME, MODE)}
3197 @item @emph{Arguments}:
3198 @multitable @columnfractions .15 .70
3200 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
3201 file name. Trailing blanks are ignored unless the character
3202 @code{achar(0)} is present, then all characters up to and excluding
3203 @code{achar(0)} are used as the file name.
3205 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
3206 file permission. @var{MODE} uses the same syntax as the @code{chmod} utility
3207 as defined by the POSIX standard. The argument shall either be a string of
3208 a nonnegative octal number or a symbolic mode.
3210 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
3211 @code{0} on success and nonzero otherwise.
3214 @item @emph{Return value}:
3215 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
3218 @item @emph{Example}:
3219 @code{CHMOD} as subroutine
3224 call chmod('test.dat','u+x',status)
3225 print *, 'Status: ', status
3226 end program chmod_test
3228 @code{CHMOD} as function:
3233 status = chmod('test.dat','u+x')
3234 print *, 'Status: ', status
3235 end program chmod_test
3243 @section @code{CMPLX} --- Complex conversion function
3245 @cindex complex numbers, conversion to
3246 @cindex conversion, to complex
3249 @item @emph{Description}:
3250 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
3251 the real component. If @var{Y} is present it is converted to the imaginary
3252 component. If @var{Y} is not present then the imaginary component is set to
3253 0.0. If @var{X} is complex then @var{Y} must not be present.
3255 @item @emph{Standard}:
3256 Fortran 77 and later
3261 @item @emph{Syntax}:
3262 @code{RESULT = CMPLX(X [, Y [, KIND]])}
3264 @item @emph{Arguments}:
3265 @multitable @columnfractions .15 .70
3266 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3268 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
3269 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
3270 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3271 expression indicating the kind parameter of the result.
3274 @item @emph{Return value}:
3275 The return value is of @code{COMPLEX} type, with a kind equal to
3276 @var{KIND} if it is specified. If @var{KIND} is not specified, the
3277 result is of the default @code{COMPLEX} kind, regardless of the kinds of
3278 @var{X} and @var{Y}.
3280 @item @emph{Example}:
3287 print *, z, cmplx(x)
3288 end program test_cmplx
3291 @item @emph{See also}:
3298 @section @code{CO_BROADCAST} --- Copy a value to all images the current set of images
3299 @fnindex CO_BROADCAST
3300 @cindex Collectives, value broadcasting
3303 @item @emph{Description}:
3304 @code{CO_BROADCAST} copies the value of argument @var{A} on the image with
3305 image index @code{SOURCE_IMAGE} to all images in the current team. @var{A}
3306 becomes defined as if by intrinsic assignment. If the execution was
3307 successful and @var{STAT} is present, it is assigned the value zero. If the
3308 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3309 @var{ERRMSG} gets assigned a value describing the occurred error.
3311 @item @emph{Standard}:
3312 Technical Specification (TS) 18508 or later
3315 Collective subroutine
3317 @item @emph{Syntax}:
3318 @code{CALL CO_BROADCAST(A, SOURCE_IMAGE [, STAT, ERRMSG])}
3320 @item @emph{Arguments}:
3321 @multitable @columnfractions .15 .70
3322 @item @var{A} @tab INTENT(INOUT) argument; shall have the same
3323 dynamic type and type paramters on all images of the current team. If it
3324 is an array, it shall have the same shape on all images.
3325 @item @var{SOURCE_IMAGE} @tab a scalar integer expression.
3326 It shall have the same the same value on all images and refer to an
3327 image of the current team.
3328 @item @var{STAT} @tab (optional) a scalar integer variable
3329 @item @var{ERRMSG} @tab (optional) a scalar character variable
3332 @item @emph{Example}:
3336 if (this_image() == 1) then
3339 call co_broadcast (val, source_image=1)
3340 print *, this_image, ":", val
3344 @item @emph{See also}:
3345 @ref{CO_MAX}, @ref{CO_MIN}, @ref{CO_SUM}, @ref{CO_REDUCE}
3351 @section @code{CO_MAX} --- Maximal value on the current set of images
3353 @cindex Collectives, maximal value
3356 @item @emph{Description}:
3357 @code{CO_MAX} determines element-wise the maximal value of @var{A} on all
3358 images of the current team. If @var{RESULT_IMAGE} is present, the maximum
3359 values are returned in @var{A} on the specified image only and the value
3360 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3361 not present, the value is returned on all images. If the execution was
3362 successful and @var{STAT} is present, it is assigned the value zero. If the
3363 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3364 @var{ERRMSG} gets assigned a value describing the occurred error.
3366 @item @emph{Standard}:
3367 Technical Specification (TS) 18508 or later
3370 Collective subroutine
3372 @item @emph{Syntax}:
3373 @code{CALL CO_MAX(A [, RESULT_IMAGE, STAT, ERRMSG])}
3375 @item @emph{Arguments}:
3376 @multitable @columnfractions .15 .70
3377 @item @var{A} @tab shall be an integer, real or character variable,
3378 which has the same type and type parameters on all images of the team.
3379 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3380 present, it shall have the same the same value on all images and refer to an
3381 image of the current team.
3382 @item @var{STAT} @tab (optional) a scalar integer variable
3383 @item @var{ERRMSG} @tab (optional) a scalar character variable
3386 @item @emph{Example}:
3391 call co_max (val, result_image=1)
3392 if (this_image() == 1) then
3393 write(*,*) "Maximal value", val ! prints num_images()
3398 @item @emph{See also}:
3399 @ref{CO_MIN}, @ref{CO_SUM}, @ref{CO_REDUCE}, @ref{CO_BROADCAST}
3405 @section @code{CO_MIN} --- Minimal value on the current set of images
3407 @cindex Collectives, minimal value
3410 @item @emph{Description}:
3411 @code{CO_MIN} determines element-wise the minimal value of @var{A} on all
3412 images of the current team. If @var{RESULT_IMAGE} is present, the minimal
3413 values are returned in @var{A} on the specified image only and the value
3414 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3415 not present, the value is returned on all images. If the execution was
3416 successful and @var{STAT} is present, it is assigned the value zero. If the
3417 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3418 @var{ERRMSG} gets assigned a value describing the occurred error.
3420 @item @emph{Standard}:
3421 Technical Specification (TS) 18508 or later
3424 Collective subroutine
3426 @item @emph{Syntax}:
3427 @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3429 @item @emph{Arguments}:
3430 @multitable @columnfractions .15 .70
3431 @item @var{A} @tab shall be an integer, real or character variable,
3432 which has the same type and type parameters on all images of the team.
3433 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3434 present, it shall have the same the same value on all images and refer to an
3435 image of the current team.
3436 @item @var{STAT} @tab (optional) a scalar integer variable
3437 @item @var{ERRMSG} @tab (optional) a scalar character variable
3440 @item @emph{Example}:
3445 call co_min (val, result_image=1)
3446 if (this_image() == 1) then
3447 write(*,*) "Minimal value", val ! prints 1
3452 @item @emph{See also}:
3453 @ref{CO_MAX}, @ref{CO_SUM}, @ref{CO_REDUCE}, @ref{CO_BROADCAST}
3459 @section @code{CO_REDUCE} --- Reduction of values on the current set of images
3461 @cindex Collectives, generic reduction
3464 @item @emph{Description}:
3465 @code{CO_REDUCE} determines element-wise the reduction of the value of @var{A}
3466 on all images of the current team. The pure function passed as @var{OPERATOR}
3467 is used to pairwise reduce the values of @var{A} by passing either the value
3468 of @var{A} of different images or the result values of such a reduction as
3469 argument. If @var{A} is an array, the deduction is done element wise. If
3470 @var{RESULT_IMAGE} is present, the result values are returned in @var{A} on
3471 the specified image only and the value of @var{A} on the other images become
3472 undefined. If @var{RESULT_IMAGE} is not present, the value is returned on all
3473 images. If the execution was successful and @var{STAT} is present, it is
3474 assigned the value zero. If the execution failed, @var{STAT} gets assigned
3475 a nonzero value and, if present, @var{ERRMSG} gets assigned a value describing
3478 @item @emph{Standard}:
3479 Technical Specification (TS) 18508 or later
3482 Collective subroutine
3484 @item @emph{Syntax}:
3485 @code{CALL CO_REDUCE(A, OPERATOR, [, RESULT_IMAGE, STAT, ERRMSG])}
3487 @item @emph{Arguments}:
3488 @multitable @columnfractions .15 .70
3489 @item @var{A} @tab is an @code{INTENT(INOUT)} argument and shall be
3490 nonpolymorphic. If it is allocatable, it shall be allocated; if it is a pointer,
3491 it shall be associated. @var{A} shall have the same type and type parameters on
3492 all images of the team; if it is an array, it shall have the same shape on all
3494 @item @var{OPERATOR} @tab pure function with two scalar nonallocatable
3495 arguments, which shall be nonpolymorphic and have the same type and type
3496 parameters as @var{A}. The function shall return a nonallocatable scalar of
3497 the same type and type parameters as @var{A}. The function shall be the same on
3498 all images and with regards to the arguments mathematically commutative and
3499 associative. Note that @var{OPERATOR} may not be an elemental function, unless
3500 it is an intrisic function.
3501 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3502 present, it shall have the same the same value on all images and refer to an
3503 image of the current team.
3504 @item @var{STAT} @tab (optional) a scalar integer variable
3505 @item @var{ERRMSG} @tab (optional) a scalar character variable
3508 @item @emph{Example}:
3513 call co_reduce (val, result_image=1, operator=myprod)
3514 if (this_image() == 1) then
3515 write(*,*) "Product value", val ! prints num_images() factorial
3518 pure function myprod(a, b)
3519 integer, value :: a, b
3527 While the rules permit in principle an intrinsic function, none of the
3528 intrinsics in the standard fulfill the criteria of having a specific
3529 function, which takes two arguments of the same type and returning that
3532 @item @emph{See also}:
3533 @ref{CO_MIN}, @ref{CO_MAX}, @ref{CO_SUM}, @ref{CO_BROADCAST}
3539 @section @code{CO_SUM} --- Sum of values on the current set of images
3541 @cindex Collectives, sum of values
3544 @item @emph{Description}:
3545 @code{CO_SUM} sums up the values of each element of @var{A} on all
3546 images of the current team. If @var{RESULT_IMAGE} is present, the summed-up
3547 values are returned in @var{A} on the specified image only and the value
3548 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3549 not present, the value is returned on all images. If the execution was
3550 successful and @var{STAT} is present, it is assigned the value zero. If the
3551 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3552 @var{ERRMSG} gets assigned a value describing the occurred error.
3554 @item @emph{Standard}:
3555 Technical Specification (TS) 18508 or later
3558 Collective subroutine
3560 @item @emph{Syntax}:
3561 @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3563 @item @emph{Arguments}:
3564 @multitable @columnfractions .15 .70
3565 @item @var{A} @tab shall be an integer, real or complex variable,
3566 which has the same type and type parameters on all images of the team.
3567 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3568 present, it shall have the same the same value on all images and refer to an
3569 image of the current team.
3570 @item @var{STAT} @tab (optional) a scalar integer variable
3571 @item @var{ERRMSG} @tab (optional) a scalar character variable
3574 @item @emph{Example}:
3579 call co_sum (val, result_image=1)
3580 if (this_image() == 1) then
3581 write(*,*) "The sum is ", val ! prints (n**2 + n)/2, with n = num_images()
3586 @item @emph{See also}:
3587 @ref{CO_MAX}, @ref{CO_MIN}, @ref{CO_REDUCE}, @ref{CO_BROADCAST}
3592 @node COMMAND_ARGUMENT_COUNT
3593 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
3594 @fnindex COMMAND_ARGUMENT_COUNT
3595 @cindex command-line arguments
3596 @cindex command-line arguments, number of
3597 @cindex arguments, to program
3600 @item @emph{Description}:
3601 @code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the
3602 command line when the containing program was invoked.
3604 @item @emph{Standard}:
3605 Fortran 2003 and later
3610 @item @emph{Syntax}:
3611 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
3613 @item @emph{Arguments}:
3614 @multitable @columnfractions .15 .70
3618 @item @emph{Return value}:
3619 The return value is an @code{INTEGER} of default kind.
3621 @item @emph{Example}:
3623 program test_command_argument_count
3625 count = command_argument_count()
3627 end program test_command_argument_count
3630 @item @emph{See also}:
3631 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
3636 @node COMPILER_OPTIONS
3637 @section @code{COMPILER_OPTIONS} --- Options passed to the compiler
3638 @fnindex COMPILER_OPTIONS
3639 @cindex flags inquiry function
3640 @cindex options inquiry function
3641 @cindex compiler flags inquiry function
3644 @item @emph{Description}:
3645 @code{COMPILER_OPTIONS} returns a string with the options used for
3648 @item @emph{Standard}:
3652 Inquiry function of the module @code{ISO_FORTRAN_ENV}
3654 @item @emph{Syntax}:
3655 @code{STR = COMPILER_OPTIONS()}
3657 @item @emph{Arguments}:
3660 @item @emph{Return value}:
3661 The return value is a default-kind string with system-dependent length.
3662 It contains the compiler flags used to compile the file, which called
3663 the @code{COMPILER_OPTIONS} intrinsic.
3665 @item @emph{Example}:
3668 print '(4a)', 'This file was compiled by ', &
3669 compiler_version(), ' using the options ', &
3674 @item @emph{See also}:
3675 @ref{COMPILER_VERSION}, @ref{ISO_FORTRAN_ENV}
3680 @node COMPILER_VERSION
3681 @section @code{COMPILER_VERSION} --- Compiler version string
3682 @fnindex COMPILER_VERSION
3683 @cindex compiler, name and version
3684 @cindex version of the compiler
3687 @item @emph{Description}:
3688 @code{COMPILER_VERSION} returns a string with the name and the
3689 version of the compiler.
3691 @item @emph{Standard}:
3695 Inquiry function of the module @code{ISO_FORTRAN_ENV}
3697 @item @emph{Syntax}:
3698 @code{STR = COMPILER_VERSION()}
3700 @item @emph{Arguments}:
3703 @item @emph{Return value}:
3704 The return value is a default-kind string with system-dependent length.
3705 It contains the name of the compiler and its version number.
3707 @item @emph{Example}:
3710 print '(4a)', 'This file was compiled by ', &
3711 compiler_version(), ' using the options ', &
3716 @item @emph{See also}:
3717 @ref{COMPILER_OPTIONS}, @ref{ISO_FORTRAN_ENV}
3723 @section @code{COMPLEX} --- Complex conversion function
3725 @cindex complex numbers, conversion to
3726 @cindex conversion, to complex
3729 @item @emph{Description}:
3730 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
3731 to the real component and @var{Y} is converted to the imaginary
3734 @item @emph{Standard}:
3740 @item @emph{Syntax}:
3741 @code{RESULT = COMPLEX(X, Y)}
3743 @item @emph{Arguments}:
3744 @multitable @columnfractions .15 .70
3745 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3746 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
3749 @item @emph{Return value}:
3750 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
3751 value is of default @code{COMPLEX} type.
3753 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
3754 type and one is of @code{INTEGER} type, then the return value is of
3755 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
3756 argument with the highest precision.
3758 @item @emph{Example}:
3760 program test_complex
3763 print *, complex(i, x)
3764 end program test_complex
3767 @item @emph{See also}:
3774 @section @code{CONJG} --- Complex conjugate function
3777 @cindex complex conjugate
3780 @item @emph{Description}:
3781 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
3782 then the result is @code{(x, -y)}
3784 @item @emph{Standard}:
3785 Fortran 77 and later, has overloads that are GNU extensions
3790 @item @emph{Syntax}:
3793 @item @emph{Arguments}:
3794 @multitable @columnfractions .15 .70
3795 @item @var{Z} @tab The type shall be @code{COMPLEX}.
3798 @item @emph{Return value}:
3799 The return value is of type @code{COMPLEX}.
3801 @item @emph{Example}:
3804 complex :: z = (2.0, 3.0)
3805 complex(8) :: dz = (2.71_8, -3.14_8)
3810 end program test_conjg
3813 @item @emph{Specific names}:
3814 @multitable @columnfractions .20 .20 .20 .25
3815 @item Name @tab Argument @tab Return type @tab Standard
3816 @item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension
3817 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
3824 @section @code{COS} --- Cosine function
3830 @cindex trigonometric function, cosine
3834 @item @emph{Description}:
3835 @code{COS(X)} computes the cosine of @var{X}.
3837 @item @emph{Standard}:
3838 Fortran 77 and later, has overloads that are GNU extensions
3843 @item @emph{Syntax}:
3844 @code{RESULT = COS(X)}
3846 @item @emph{Arguments}:
3847 @multitable @columnfractions .15 .70
3848 @item @var{X} @tab The type shall be @code{REAL} or
3852 @item @emph{Return value}:
3853 The return value is of the same type and kind as @var{X}. The real part
3854 of the result is in radians. If @var{X} is of the type @code{REAL},
3855 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
3857 @item @emph{Example}:
3862 end program test_cos
3865 @item @emph{Specific names}:
3866 @multitable @columnfractions .20 .20 .20 .25
3867 @item Name @tab Argument @tab Return type @tab Standard
3868 @item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
3869 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3870 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
3871 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3872 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3875 @item @emph{See also}:
3876 Inverse function: @ref{ACOS}
3883 @section @code{COSH} --- Hyperbolic cosine function
3886 @cindex hyperbolic cosine
3887 @cindex hyperbolic function, cosine
3888 @cindex cosine, hyperbolic
3891 @item @emph{Description}:
3892 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
3894 @item @emph{Standard}:
3895 Fortran 77 and later, for a complex argument Fortran 2008 or later
3900 @item @emph{Syntax}:
3903 @item @emph{Arguments}:
3904 @multitable @columnfractions .15 .70
3905 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
3908 @item @emph{Return value}:
3909 The return value has same type and kind as @var{X}. If @var{X} is
3910 complex, the imaginary part of the result is in radians. If @var{X}
3911 is @code{REAL}, the return value has a lower bound of one,
3912 @math{\cosh (x) \geq 1}.
3914 @item @emph{Example}:
3917 real(8) :: x = 1.0_8
3919 end program test_cosh
3922 @item @emph{Specific names}:
3923 @multitable @columnfractions .20 .20 .20 .25
3924 @item Name @tab Argument @tab Return type @tab Standard
3925 @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
3926 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3929 @item @emph{See also}:
3930 Inverse function: @ref{ACOSH}
3937 @section @code{COUNT} --- Count function
3939 @cindex array, conditionally count elements
3940 @cindex array, element counting
3941 @cindex array, number of elements
3944 @item @emph{Description}:
3946 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
3947 or, if the @var{DIM} argument is supplied, counts the number of
3948 elements along each row of the array in the @var{DIM} direction.
3949 If the array has zero size, or all of the elements of @var{MASK} are
3950 @code{.FALSE.}, then the result is @code{0}.
3952 @item @emph{Standard}:
3953 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
3956 Transformational function
3958 @item @emph{Syntax}:
3959 @code{RESULT = COUNT(MASK [, DIM, KIND])}
3961 @item @emph{Arguments}:
3962 @multitable @columnfractions .15 .70
3963 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
3964 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
3965 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3966 expression indicating the kind parameter of the result.
3969 @item @emph{Return value}:
3970 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
3971 @var{KIND} is absent, the return value is of default integer kind.
3972 If @var{DIM} is present, the result is an array with a rank one less
3973 than the rank of @var{ARRAY}, and a size corresponding to the shape
3974 of @var{ARRAY} with the @var{DIM} dimension removed.
3976 @item @emph{Example}:
3979 integer, dimension(2,3) :: a, b
3980 logical, dimension(2,3) :: mask
3981 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
3982 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
3983 print '(3i3)', a(1,:)
3984 print '(3i3)', a(2,:)
3986 print '(3i3)', b(1,:)
3987 print '(3i3)', b(2,:)
3990 print '(3l3)', mask(1,:)
3991 print '(3l3)', mask(2,:)
3993 print '(3i3)', count(mask)
3995 print '(3i3)', count(mask, 1)
3997 print '(3i3)', count(mask, 2)
3998 end program test_count
4005 @section @code{CPU_TIME} --- CPU elapsed time in seconds
4007 @cindex time, elapsed
4010 @item @emph{Description}:
4011 Returns a @code{REAL} value representing the elapsed CPU time in
4012 seconds. This is useful for testing segments of code to determine
4015 If a time source is available, time will be reported with microsecond
4016 resolution. If no time source is available, @var{TIME} is set to
4019 Note that @var{TIME} may contain a, system dependent, arbitrary offset
4020 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
4021 value is meaningless, only differences between subsequent calls to
4022 this subroutine, as shown in the example below, should be used.
4025 @item @emph{Standard}:
4026 Fortran 95 and later
4031 @item @emph{Syntax}:
4032 @code{CALL CPU_TIME(TIME)}
4034 @item @emph{Arguments}:
4035 @multitable @columnfractions .15 .70
4036 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
4039 @item @emph{Return value}:
4042 @item @emph{Example}:
4044 program test_cpu_time
4045 real :: start, finish
4046 call cpu_time(start)
4047 ! put code to test here
4048 call cpu_time(finish)
4049 print '("Time = ",f6.3," seconds.")',finish-start
4050 end program test_cpu_time
4053 @item @emph{See also}:
4054 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
4060 @section @code{CSHIFT} --- Circular shift elements of an array
4062 @cindex array, shift circularly
4063 @cindex array, permutation
4064 @cindex array, rotate
4067 @item @emph{Description}:
4068 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
4069 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
4070 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
4071 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
4072 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
4073 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
4074 sections of @var{ARRAY} along the given dimension are shifted. Elements
4075 shifted out one end of each rank one section are shifted back in the other end.
4077 @item @emph{Standard}:
4078 Fortran 95 and later
4081 Transformational function
4083 @item @emph{Syntax}:
4084 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
4086 @item @emph{Arguments}:
4087 @multitable @columnfractions .15 .70
4088 @item @var{ARRAY} @tab Shall be an array of any type.
4089 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
4090 @item @var{DIM} @tab The type shall be @code{INTEGER}.
4093 @item @emph{Return value}:
4094 Returns an array of same type and rank as the @var{ARRAY} argument.
4096 @item @emph{Example}:
4099 integer, dimension(3,3) :: a
4100 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
4101 print '(3i3)', a(1,:)
4102 print '(3i3)', a(2,:)
4103 print '(3i3)', a(3,:)
4104 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
4106 print '(3i3)', a(1,:)
4107 print '(3i3)', a(2,:)
4108 print '(3i3)', a(3,:)
4109 end program test_cshift
4116 @section @code{CTIME} --- Convert a time into a string
4118 @cindex time, conversion to string
4119 @cindex conversion, to string
4122 @item @emph{Description}:
4123 @code{CTIME} converts a system time value, such as returned by
4124 @code{TIME8}, to a string. The output will be of the form @samp{Sat
4125 Aug 19 18:13:14 1995}.
4127 This intrinsic is provided in both subroutine and function forms; however,
4128 only one form can be used in any given program unit.
4130 @item @emph{Standard}:
4134 Subroutine, function
4136 @item @emph{Syntax}:
4137 @multitable @columnfractions .80
4138 @item @code{CALL CTIME(TIME, RESULT)}.
4139 @item @code{RESULT = CTIME(TIME)}.
4142 @item @emph{Arguments}:
4143 @multitable @columnfractions .15 .70
4144 @item @var{TIME} @tab The type shall be of type @code{INTEGER}.
4145 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
4146 of default kind. It is an @code{INTENT(OUT)} argument. If the length
4147 of this variable is too short for the time and date string to fit
4148 completely, it will be blank on procedure return.
4151 @item @emph{Return value}:
4152 The converted date and time as a string.
4154 @item @emph{Example}:
4158 character(len=30) :: date
4161 ! Do something, main part of the program
4164 print *, 'Program was started on ', date
4165 end program test_ctime
4168 @item @emph{See Also}:
4169 @ref{DATE_AND_TIME}, @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
4175 @section @code{DATE_AND_TIME} --- Date and time subroutine
4176 @fnindex DATE_AND_TIME
4177 @cindex date, current
4178 @cindex current date
4179 @cindex time, current
4180 @cindex current time
4183 @item @emph{Description}:
4184 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
4185 time information from the real-time system clock. @var{DATE} is
4186 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
4187 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
4188 representing the difference with respect to Coordinated Universal Time (UTC).
4189 Unavailable time and date parameters return blanks.
4191 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
4193 @multitable @columnfractions .15 .30 .40
4194 @item @tab @code{VALUE(1)}: @tab The year
4195 @item @tab @code{VALUE(2)}: @tab The month
4196 @item @tab @code{VALUE(3)}: @tab The day of the month
4197 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
4198 @item @tab @code{VALUE(5)}: @tab The hour of the day
4199 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
4200 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
4201 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
4204 @item @emph{Standard}:
4205 Fortran 95 and later
4210 @item @emph{Syntax}:
4211 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
4213 @item @emph{Arguments}:
4214 @multitable @columnfractions .15 .70
4215 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
4216 or larger, and of default kind.
4217 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
4218 or larger, and of default kind.
4219 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
4220 or larger, and of default kind.
4221 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
4224 @item @emph{Return value}:
4227 @item @emph{Example}:
4229 program test_time_and_date
4230 character(8) :: date
4231 character(10) :: time
4232 character(5) :: zone
4233 integer,dimension(8) :: values
4234 ! using keyword arguments
4235 call date_and_time(date,time,zone,values)
4236 call date_and_time(DATE=date,ZONE=zone)
4237 call date_and_time(TIME=time)
4238 call date_and_time(VALUES=values)
4239 print '(a,2x,a,2x,a)', date, time, zone
4240 print '(8i5)', values
4241 end program test_time_and_date
4244 @item @emph{See also}:
4245 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
4251 @section @code{DBLE} --- Double conversion function
4253 @cindex conversion, to real
4256 @item @emph{Description}:
4257 @code{DBLE(A)} Converts @var{A} to double precision real type.
4259 @item @emph{Standard}:
4260 Fortran 77 and later
4265 @item @emph{Syntax}:
4266 @code{RESULT = DBLE(A)}
4268 @item @emph{Arguments}:
4269 @multitable @columnfractions .15 .70
4270 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
4274 @item @emph{Return value}:
4275 The return value is of type double precision real.
4277 @item @emph{Example}:
4282 complex :: z = (2.3,1.14)
4283 print *, dble(x), dble(i), dble(z)
4284 end program test_dble
4287 @item @emph{See also}:
4294 @section @code{DCMPLX} --- Double complex conversion function
4296 @cindex complex numbers, conversion to
4297 @cindex conversion, to complex
4300 @item @emph{Description}:
4301 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
4302 converted to the real component. If @var{Y} is present it is converted to the
4303 imaginary component. If @var{Y} is not present then the imaginary component is
4304 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
4306 @item @emph{Standard}:
4312 @item @emph{Syntax}:
4313 @code{RESULT = DCMPLX(X [, Y])}
4315 @item @emph{Arguments}:
4316 @multitable @columnfractions .15 .70
4317 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
4319 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
4320 @code{INTEGER} or @code{REAL}.
4323 @item @emph{Return value}:
4324 The return value is of type @code{COMPLEX(8)}
4326 @item @emph{Example}:
4336 print *, dcmplx(x,i)
4337 end program test_dcmplx
4343 @section @code{DIGITS} --- Significant binary digits function
4345 @cindex model representation, significant digits
4348 @item @emph{Description}:
4349 @code{DIGITS(X)} returns the number of significant binary digits of the internal
4350 model representation of @var{X}. For example, on a system using a 32-bit
4351 floating point representation, a default real number would likely return 24.
4353 @item @emph{Standard}:
4354 Fortran 95 and later
4359 @item @emph{Syntax}:
4360 @code{RESULT = DIGITS(X)}
4362 @item @emph{Arguments}:
4363 @multitable @columnfractions .15 .70
4364 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
4367 @item @emph{Return value}:
4368 The return value is of type @code{INTEGER}.
4370 @item @emph{Example}:
4373 integer :: i = 12345
4379 end program test_digits
4386 @section @code{DIM} --- Positive difference
4390 @cindex positive difference
4393 @item @emph{Description}:
4394 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
4395 otherwise returns zero.
4397 @item @emph{Standard}:
4398 Fortran 77 and later
4403 @item @emph{Syntax}:
4404 @code{RESULT = DIM(X, Y)}
4406 @item @emph{Arguments}:
4407 @multitable @columnfractions .15 .70
4408 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
4409 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
4412 @item @emph{Return value}:
4413 The return value is of type @code{INTEGER} or @code{REAL}.
4415 @item @emph{Example}:
4421 x = dim(4.345_8, 2.111_8)
4424 end program test_dim
4427 @item @emph{Specific names}:
4428 @multitable @columnfractions .20 .20 .20 .25
4429 @item Name @tab Argument @tab Return type @tab Standard
4430 @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
4431 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
4432 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
4439 @section @code{DOT_PRODUCT} --- Dot product function
4440 @fnindex DOT_PRODUCT
4442 @cindex vector product
4443 @cindex product, vector
4446 @item @emph{Description}:
4447 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
4448 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
4449 either numeric or logical and must be arrays of rank one and of equal size. If
4450 the vectors are @code{INTEGER} or @code{REAL}, the result is
4451 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
4452 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
4453 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
4455 @item @emph{Standard}:
4456 Fortran 95 and later
4459 Transformational function
4461 @item @emph{Syntax}:
4462 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
4464 @item @emph{Arguments}:
4465 @multitable @columnfractions .15 .70
4466 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
4467 @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.
4470 @item @emph{Return value}:
4471 If the arguments are numeric, the return value is a scalar of numeric type,
4472 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
4473 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
4475 @item @emph{Example}:
4477 program test_dot_prod
4478 integer, dimension(3) :: a, b
4485 print *, dot_product(a,b)
4486 end program test_dot_prod
4493 @section @code{DPROD} --- Double product function
4495 @cindex product, double-precision
4498 @item @emph{Description}:
4499 @code{DPROD(X,Y)} returns the product @code{X*Y}.
4501 @item @emph{Standard}:
4502 Fortran 77 and later
4507 @item @emph{Syntax}:
4508 @code{RESULT = DPROD(X, Y)}
4510 @item @emph{Arguments}:
4511 @multitable @columnfractions .15 .70
4512 @item @var{X} @tab The type shall be @code{REAL}.
4513 @item @var{Y} @tab The type shall be @code{REAL}.
4516 @item @emph{Return value}:
4517 The return value is of type @code{REAL(8)}.
4519 @item @emph{Example}:
4527 end program test_dprod
4530 @item @emph{Specific names}:
4531 @multitable @columnfractions .20 .20 .20 .25
4532 @item Name @tab Argument @tab Return type @tab Standard
4533 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
4540 @section @code{DREAL} --- Double real part function
4542 @cindex complex numbers, real part
4545 @item @emph{Description}:
4546 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
4548 @item @emph{Standard}:
4554 @item @emph{Syntax}:
4555 @code{RESULT = DREAL(A)}
4557 @item @emph{Arguments}:
4558 @multitable @columnfractions .15 .70
4559 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
4562 @item @emph{Return value}:
4563 The return value is of type @code{REAL(8)}.
4565 @item @emph{Example}:
4568 complex(8) :: z = (1.3_8,7.2_8)
4570 end program test_dreal
4573 @item @emph{See also}:
4581 @section @code{DSHIFTL} --- Combined left shift
4583 @cindex left shift, combined
4587 @item @emph{Description}:
4588 @code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
4589 rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
4590 bits of @var{J}, and the remaining bits are the rightmost bits of
4593 @item @emph{Standard}:
4594 Fortran 2008 and later
4599 @item @emph{Syntax}:
4600 @code{RESULT = DSHIFTL(I, J, SHIFT)}
4602 @item @emph{Arguments}:
4603 @multitable @columnfractions .15 .70
4604 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
4605 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
4606 If both @var{I} and @var{J} have integer type, then they shall have
4607 the same kind type parameter. @var{I} and @var{J} shall not both be
4609 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
4610 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
4611 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
4612 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
4615 @item @emph{Return value}:
4616 If either @var{I} or @var{J} is a BOZ constant, it is first converted
4617 as if by the intrinsic function @code{INT} to an integer type with the
4618 kind type parameter of the other.
4620 @item @emph{See also}:
4626 @section @code{DSHIFTR} --- Combined right shift
4628 @cindex right shift, combined
4629 @cindex shift, right
4632 @item @emph{Description}:
4633 @code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
4634 leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
4635 bits of @var{I}, and the remaining bits are the leftmost bits of
4638 @item @emph{Standard}:
4639 Fortran 2008 and later
4644 @item @emph{Syntax}:
4645 @code{RESULT = DSHIFTR(I, J, SHIFT)}
4647 @item @emph{Arguments}:
4648 @multitable @columnfractions .15 .70
4649 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
4650 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
4651 If both @var{I} and @var{J} have integer type, then they shall have
4652 the same kind type parameter. @var{I} and @var{J} shall not both be
4654 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
4655 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
4656 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
4657 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
4660 @item @emph{Return value}:
4661 If either @var{I} or @var{J} is a BOZ constant, it is first converted
4662 as if by the intrinsic function @code{INT} to an integer type with the
4663 kind type parameter of the other.
4665 @item @emph{See also}:
4671 @section @code{DTIME} --- Execution time subroutine (or function)
4673 @cindex time, elapsed
4674 @cindex elapsed time
4677 @item @emph{Description}:
4678 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
4679 since the start of the process's execution in @var{TIME}. @var{VALUES}
4680 returns the user and system components of this time in @code{VALUES(1)} and
4681 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
4684 Subsequent invocations of @code{DTIME} return values accumulated since the
4685 previous invocation.
4687 On some systems, the underlying timings are represented using types with
4688 sufficiently small limits that overflows (wrap around) are possible, such as
4689 32-bit types. Therefore, the values returned by this intrinsic might be, or
4690 become, negative, or numerically less than previous values, during a single
4691 run of the compiled program.
4693 Please note, that this implementation is thread safe if used within OpenMP
4694 directives, i.e., its state will be consistent while called from multiple
4695 threads. However, if @code{DTIME} is called from multiple threads, the result
4696 is still the time since the last invocation. This may not give the intended
4697 results. If possible, use @code{CPU_TIME} instead.
4699 This intrinsic is provided in both subroutine and function forms; however,
4700 only one form can be used in any given program unit.
4702 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
4704 @multitable @columnfractions .15 .30 .40
4705 @item @tab @code{VALUES(1)}: @tab User time in seconds.
4706 @item @tab @code{VALUES(2)}: @tab System time in seconds.
4707 @item @tab @code{TIME}: @tab Run time since start in seconds.
4710 @item @emph{Standard}:
4714 Subroutine, function
4716 @item @emph{Syntax}:
4717 @multitable @columnfractions .80
4718 @item @code{CALL DTIME(VALUES, TIME)}.
4719 @item @code{TIME = DTIME(VALUES)}, (not recommended).
4722 @item @emph{Arguments}:
4723 @multitable @columnfractions .15 .70
4724 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
4725 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
4728 @item @emph{Return value}:
4729 Elapsed time in seconds since the last invocation or since the start of program
4730 execution if not called before.
4732 @item @emph{Example}:
4736 real, dimension(2) :: tarray
4738 call dtime(tarray, result)
4742 do i=1,100000000 ! Just a delay
4745 call dtime(tarray, result)
4749 end program test_dtime
4752 @item @emph{See also}:
4760 @section @code{EOSHIFT} --- End-off shift elements of an array
4762 @cindex array, shift
4765 @item @emph{Description}:
4766 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
4767 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
4768 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
4769 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
4770 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
4771 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
4772 then all complete rank one sections of @var{ARRAY} along the given dimension are
4773 shifted. Elements shifted out one end of each rank one section are dropped. If
4774 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
4775 is copied back in the other end. If @var{BOUNDARY} is not present then the
4776 following are copied in depending on the type of @var{ARRAY}.
4778 @multitable @columnfractions .15 .80
4779 @item @emph{Array Type} @tab @emph{Boundary Value}
4780 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
4781 @item Logical @tab @code{.FALSE.}.
4782 @item Character(@var{len}) @tab @var{len} blanks.
4785 @item @emph{Standard}:
4786 Fortran 95 and later
4789 Transformational function
4791 @item @emph{Syntax}:
4792 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
4794 @item @emph{Arguments}:
4795 @multitable @columnfractions .15 .70
4796 @item @var{ARRAY} @tab May be any type, not scalar.
4797 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
4798 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
4799 @item @var{DIM} @tab The type shall be @code{INTEGER}.
4802 @item @emph{Return value}:
4803 Returns an array of same type and rank as the @var{ARRAY} argument.
4805 @item @emph{Example}:
4807 program test_eoshift
4808 integer, dimension(3,3) :: a
4809 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
4810 print '(3i3)', a(1,:)
4811 print '(3i3)', a(2,:)
4812 print '(3i3)', a(3,:)
4813 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
4815 print '(3i3)', a(1,:)
4816 print '(3i3)', a(2,:)
4817 print '(3i3)', a(3,:)
4818 end program test_eoshift
4825 @section @code{EPSILON} --- Epsilon function
4827 @cindex model representation, epsilon
4830 @item @emph{Description}:
4831 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
4832 as @var{X} such that @math{1 + E > 1}.
4834 @item @emph{Standard}:
4835 Fortran 95 and later
4840 @item @emph{Syntax}:
4841 @code{RESULT = EPSILON(X)}
4843 @item @emph{Arguments}:
4844 @multitable @columnfractions .15 .70
4845 @item @var{X} @tab The type shall be @code{REAL}.
4848 @item @emph{Return value}:
4849 The return value is of same type as the argument.
4851 @item @emph{Example}:
4853 program test_epsilon
4858 end program test_epsilon
4865 @section @code{ERF} --- Error function
4867 @cindex error function
4870 @item @emph{Description}:
4871 @code{ERF(X)} computes the error function of @var{X}.
4873 @item @emph{Standard}:
4874 Fortran 2008 and later
4879 @item @emph{Syntax}:
4880 @code{RESULT = ERF(X)}
4882 @item @emph{Arguments}:
4883 @multitable @columnfractions .15 .70
4884 @item @var{X} @tab The type shall be @code{REAL}.
4887 @item @emph{Return value}:
4888 The return value is of type @code{REAL}, of the same kind as
4889 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
4891 @item @emph{Example}:
4894 real(8) :: x = 0.17_8
4896 end program test_erf
4899 @item @emph{Specific names}:
4900 @multitable @columnfractions .20 .20 .20 .25
4901 @item Name @tab Argument @tab Return type @tab Standard
4902 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4909 @section @code{ERFC} --- Error function
4911 @cindex error function, complementary
4914 @item @emph{Description}:
4915 @code{ERFC(X)} computes the complementary error function of @var{X}.
4917 @item @emph{Standard}:
4918 Fortran 2008 and later
4923 @item @emph{Syntax}:
4924 @code{RESULT = ERFC(X)}
4926 @item @emph{Arguments}:
4927 @multitable @columnfractions .15 .70
4928 @item @var{X} @tab The type shall be @code{REAL}.
4931 @item @emph{Return value}:
4932 The return value is of type @code{REAL} and of the same kind as @var{X}.
4933 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
4935 @item @emph{Example}:
4938 real(8) :: x = 0.17_8
4940 end program test_erfc
4943 @item @emph{Specific names}:
4944 @multitable @columnfractions .20 .20 .20 .25
4945 @item Name @tab Argument @tab Return type @tab Standard
4946 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4953 @section @code{ERFC_SCALED} --- Error function
4954 @fnindex ERFC_SCALED
4955 @cindex error function, complementary, exponentially-scaled
4958 @item @emph{Description}:
4959 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
4960 error function of @var{X}.
4962 @item @emph{Standard}:
4963 Fortran 2008 and later
4968 @item @emph{Syntax}:
4969 @code{RESULT = ERFC_SCALED(X)}
4971 @item @emph{Arguments}:
4972 @multitable @columnfractions .15 .70
4973 @item @var{X} @tab The type shall be @code{REAL}.
4976 @item @emph{Return value}:
4977 The return value is of type @code{REAL} and of the same kind as @var{X}.
4979 @item @emph{Example}:
4981 program test_erfc_scaled
4982 real(8) :: x = 0.17_8
4984 end program test_erfc_scaled
4991 @section @code{ETIME} --- Execution time subroutine (or function)
4993 @cindex time, elapsed
4996 @item @emph{Description}:
4997 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
4998 since the start of the process's execution in @var{TIME}. @var{VALUES}
4999 returns the user and system components of this time in @code{VALUES(1)} and
5000 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
5002 On some systems, the underlying timings are represented using types with
5003 sufficiently small limits that overflows (wrap around) are possible, such as
5004 32-bit types. Therefore, the values returned by this intrinsic might be, or
5005 become, negative, or numerically less than previous values, during a single
5006 run of the compiled program.
5008 This intrinsic is provided in both subroutine and function forms; however,
5009 only one form can be used in any given program unit.
5011 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
5013 @multitable @columnfractions .15 .30 .60
5014 @item @tab @code{VALUES(1)}: @tab User time in seconds.
5015 @item @tab @code{VALUES(2)}: @tab System time in seconds.
5016 @item @tab @code{TIME}: @tab Run time since start in seconds.
5019 @item @emph{Standard}:
5023 Subroutine, function
5025 @item @emph{Syntax}:
5026 @multitable @columnfractions .80
5027 @item @code{CALL ETIME(VALUES, TIME)}.
5028 @item @code{TIME = ETIME(VALUES)}, (not recommended).
5031 @item @emph{Arguments}:
5032 @multitable @columnfractions .15 .70
5033 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
5034 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
5037 @item @emph{Return value}:
5038 Elapsed time in seconds since the start of program execution.
5040 @item @emph{Example}:
5044 real, dimension(2) :: tarray
5046 call ETIME(tarray, result)
5050 do i=1,100000000 ! Just a delay
5053 call ETIME(tarray, result)
5057 end program test_etime
5060 @item @emph{See also}:
5068 @section @code{EVENT_QUERY} --- Query whether a coarray event has occurred
5069 @fnindex EVENT_QUERY
5070 @cindex Events, EVENT_QUERY
5073 @item @emph{Description}:
5074 @code{EVENT_QUERY} assignes the number of events to @var{COUNT} which have been
5075 posted to the @var{EVENT} variable and not yet been removed by calling
5076 @code{EVENT WAIT}. When @var{STAT} is present and the invokation was successful,
5077 it is assigned the value 0. If it is present and the invokation has failed,
5078 it is assigned a positive value and @var{COUNT} is assigned the value @math{-1}.
5080 @item @emph{Standard}:
5086 @item @emph{Syntax}:
5087 @code{CALL EVENT_QUERY (EVENT, COUNT [, STAT])}
5089 @item @emph{Arguments}:
5090 @multitable @columnfractions .15 .70
5091 @item @var{EVENT} @tab (intent(IN)) Scalar of type @code{EVENT_TYPE},
5092 defined in @code{ISO_FORTRAN_ENV}; shall not be coindexed.
5093 @item @var{COUNT} @tab (intent(out))Scalar integer with at least the
5094 precision of default integer.
5095 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
5098 @item @emph{Example}:
5103 type(event_type) :: event_value_has_been_set[*]
5105 if (this_image() == 1) then
5106 call event_query (event_value_has_been_set, cnt)
5107 if (cnt > 0) write(*,*) "Value has been set"
5108 elseif (this_image() == 2) then
5109 event post (event_value_has_been_set[1])
5118 @node EXECUTE_COMMAND_LINE
5119 @section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
5120 @fnindex EXECUTE_COMMAND_LINE
5121 @cindex system, system call
5122 @cindex command line
5125 @item @emph{Description}:
5126 @code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
5129 The @code{COMMAND} argument is passed to the shell and executed, using
5130 the C library's @code{system} call. (The shell is @code{sh} on Unix
5131 systems, and @code{cmd.exe} on Windows.) If @code{WAIT} is present
5132 and has the value false, the execution of the command is asynchronous
5133 if the system supports it; otherwise, the command is executed
5136 The three last arguments allow the user to get status information. After
5137 synchronous execution, @code{EXITSTAT} contains the integer exit code of
5138 the command, as returned by @code{system}. @code{CMDSTAT} is set to zero
5139 if the command line was executed (whatever its exit status was).
5140 @code{CMDMSG} is assigned an error message if an error has occurred.
5142 Note that the @code{system} function need not be thread-safe. It is
5143 the responsibility of the user to ensure that @code{system} is not
5144 called concurrently.
5146 @item @emph{Standard}:
5147 Fortran 2008 and later
5152 @item @emph{Syntax}:
5153 @code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
5155 @item @emph{Arguments}:
5156 @multitable @columnfractions .15 .70
5157 @item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
5158 @item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
5159 @item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5161 @item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5163 @item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
5167 @item @emph{Example}:
5172 call execute_command_line ("external_prog.exe", exitstat=i)
5173 print *, "Exit status of external_prog.exe was ", i
5175 call execute_command_line ("reindex_files.exe", wait=.false.)
5176 print *, "Now reindexing files in the background"
5178 end program test_exec
5184 Because this intrinsic is implemented in terms of the @code{system}
5185 function call, its behavior with respect to signaling is processor
5186 dependent. In particular, on POSIX-compliant systems, the SIGINT and
5187 SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
5188 such, if the parent process is terminated, the child process might not be
5189 terminated alongside.
5192 @item @emph{See also}:
5199 @section @code{EXIT} --- Exit the program with status.
5201 @cindex program termination
5202 @cindex terminate program
5205 @item @emph{Description}:
5206 @code{EXIT} causes immediate termination of the program with status. If status
5207 is omitted it returns the canonical @emph{success} for the system. All Fortran
5208 I/O units are closed.
5210 @item @emph{Standard}:
5216 @item @emph{Syntax}:
5217 @code{CALL EXIT([STATUS])}
5219 @item @emph{Arguments}:
5220 @multitable @columnfractions .15 .70
5221 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
5224 @item @emph{Return value}:
5225 @code{STATUS} is passed to the parent process on exit.
5227 @item @emph{Example}:
5230 integer :: STATUS = 0
5231 print *, 'This program is going to exit.'
5233 end program test_exit
5236 @item @emph{See also}:
5237 @ref{ABORT}, @ref{KILL}
5243 @section @code{EXP} --- Exponential function
5249 @cindex exponential function
5250 @cindex logarithm function, inverse
5253 @item @emph{Description}:
5254 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
5256 @item @emph{Standard}:
5257 Fortran 77 and later, has overloads that are GNU extensions
5262 @item @emph{Syntax}:
5263 @code{RESULT = EXP(X)}
5265 @item @emph{Arguments}:
5266 @multitable @columnfractions .15 .70
5267 @item @var{X} @tab The type shall be @code{REAL} or
5271 @item @emph{Return value}:
5272 The return value has same type and kind as @var{X}.
5274 @item @emph{Example}:
5279 end program test_exp
5282 @item @emph{Specific names}:
5283 @multitable @columnfractions .20 .20 .20 .25
5284 @item Name @tab Argument @tab Return type @tab Standard
5285 @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
5286 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
5287 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
5288 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5289 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5296 @section @code{EXPONENT} --- Exponent function
5298 @cindex real number, exponent
5299 @cindex floating point, exponent
5302 @item @emph{Description}:
5303 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
5304 is zero the value returned is zero.
5306 @item @emph{Standard}:
5307 Fortran 95 and later
5312 @item @emph{Syntax}:
5313 @code{RESULT = EXPONENT(X)}
5315 @item @emph{Arguments}:
5316 @multitable @columnfractions .15 .70
5317 @item @var{X} @tab The type shall be @code{REAL}.
5320 @item @emph{Return value}:
5321 The return value is of type default @code{INTEGER}.
5323 @item @emph{Example}:
5325 program test_exponent
5330 print *, exponent(0.0)
5331 end program test_exponent
5337 @node EXTENDS_TYPE_OF
5338 @section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension
5339 @fnindex EXTENDS_TYPE_OF
5342 @item @emph{Description}:
5343 Query dynamic type for extension.
5345 @item @emph{Standard}:
5346 Fortran 2003 and later
5351 @item @emph{Syntax}:
5352 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
5354 @item @emph{Arguments}:
5355 @multitable @columnfractions .15 .70
5356 @item @var{A} @tab Shall be an object of extensible declared type or
5357 unlimited polymorphic.
5358 @item @var{MOLD} @tab Shall be an object of extensible declared type or
5359 unlimited polymorphic.
5362 @item @emph{Return value}:
5363 The return value is a scalar of type default logical. It is true if and only if
5364 the dynamic type of A is an extension type of the dynamic type of MOLD.
5367 @item @emph{See also}:
5374 @section @code{FDATE} --- Get the current time as a string
5376 @cindex time, current
5377 @cindex current time
5378 @cindex date, current
5379 @cindex current date
5382 @item @emph{Description}:
5383 @code{FDATE(DATE)} returns the current date (using the same format as
5384 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
5387 This intrinsic is provided in both subroutine and function forms; however,
5388 only one form can be used in any given program unit.
5390 @item @emph{Standard}:
5394 Subroutine, function
5396 @item @emph{Syntax}:
5397 @multitable @columnfractions .80
5398 @item @code{CALL FDATE(DATE)}.
5399 @item @code{DATE = FDATE()}.
5402 @item @emph{Arguments}:
5403 @multitable @columnfractions .15 .70
5404 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
5405 default kind. It is an @code{INTENT(OUT)} argument. If the length of
5406 this variable is too short for the date and time string to fit
5407 completely, it will be blank on procedure return.
5410 @item @emph{Return value}:
5411 The current date and time as a string.
5413 @item @emph{Example}:
5417 character(len=30) :: date
5419 print *, 'Program started on ', date
5420 do i = 1, 100000000 ! Just a delay
5424 print *, 'Program ended on ', date
5425 end program test_fdate
5428 @item @emph{See also}:
5429 @ref{DATE_AND_TIME}, @ref{CTIME}
5434 @section @code{FGET} --- Read a single character in stream mode from stdin
5436 @cindex read character, stream mode
5437 @cindex stream mode, read character
5438 @cindex file operation, read character
5441 @item @emph{Description}:
5442 Read a single character in stream mode from stdin by bypassing normal
5443 formatted output. Stream I/O should not be mixed with normal record-oriented
5444 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
5446 This intrinsic is provided in both subroutine and function forms; however,
5447 only one form can be used in any given program unit.
5449 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
5450 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5451 Programmers should consider the use of new stream IO feature in new code
5452 for future portability. See also @ref{Fortran 2003 status}.
5454 @item @emph{Standard}:
5458 Subroutine, function
5460 @item @emph{Syntax}:
5461 @multitable @columnfractions .80
5462 @item @code{CALL FGET(C [, STATUS])}
5463 @item @code{STATUS = FGET(C)}
5466 @item @emph{Arguments}:
5467 @multitable @columnfractions .15 .70
5468 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5470 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5471 Returns 0 on success, -1 on end-of-file, and a system specific positive
5472 error code otherwise.
5475 @item @emph{Example}:
5478 INTEGER, PARAMETER :: strlen = 100
5479 INTEGER :: status, i = 1
5480 CHARACTER(len=strlen) :: str = ""
5482 WRITE (*,*) 'Enter text:'
5484 CALL fget(str(i:i), status)
5485 if (status /= 0 .OR. i > strlen) exit
5488 WRITE (*,*) TRIM(str)
5492 @item @emph{See also}:
5493 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
5499 @section @code{FGETC} --- Read a single character in stream mode
5501 @cindex read character, stream mode
5502 @cindex stream mode, read character
5503 @cindex file operation, read character
5506 @item @emph{Description}:
5507 Read a single character in stream mode by bypassing normal formatted output.
5508 Stream I/O should not be mixed with normal record-oriented (formatted or
5509 unformatted) I/O on the same unit; the results are unpredictable.
5511 This intrinsic is provided in both subroutine and function forms; however,
5512 only one form can be used in any given program unit.
5514 Note that the @code{FGET} intrinsic is provided for backwards compatibility
5515 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5516 Programmers should consider the use of new stream IO feature in new code
5517 for future portability. See also @ref{Fortran 2003 status}.
5519 @item @emph{Standard}:
5523 Subroutine, function
5525 @item @emph{Syntax}:
5526 @multitable @columnfractions .80
5527 @item @code{CALL FGETC(UNIT, C [, STATUS])}
5528 @item @code{STATUS = FGETC(UNIT, C)}
5531 @item @emph{Arguments}:
5532 @multitable @columnfractions .15 .70
5533 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
5534 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5536 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5537 Returns 0 on success, -1 on end-of-file and a system specific positive
5538 error code otherwise.
5541 @item @emph{Example}:
5544 INTEGER :: fd = 42, status
5547 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
5549 CALL fgetc(fd, c, status)
5550 IF (status /= 0) EXIT
5557 @item @emph{See also}:
5558 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
5564 @section @code{FLOOR} --- Integer floor function
5567 @cindex rounding, floor
5570 @item @emph{Description}:
5571 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
5573 @item @emph{Standard}:
5574 Fortran 95 and later
5579 @item @emph{Syntax}:
5580 @code{RESULT = FLOOR(A [, KIND])}
5582 @item @emph{Arguments}:
5583 @multitable @columnfractions .15 .70
5584 @item @var{A} @tab The type shall be @code{REAL}.
5585 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5586 expression indicating the kind parameter of the result.
5589 @item @emph{Return value}:
5590 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
5591 and of default-kind @code{INTEGER} otherwise.
5593 @item @emph{Example}:
5598 print *, floor(x) ! returns 63
5599 print *, floor(y) ! returns -64
5600 end program test_floor
5603 @item @emph{See also}:
5604 @ref{CEILING}, @ref{NINT}
5611 @section @code{FLUSH} --- Flush I/O unit(s)
5613 @cindex file operation, flush
5616 @item @emph{Description}:
5617 Flushes Fortran unit(s) currently open for output. Without the optional
5618 argument, all units are flushed, otherwise just the unit specified.
5620 @item @emph{Standard}:
5626 @item @emph{Syntax}:
5627 @code{CALL FLUSH(UNIT)}
5629 @item @emph{Arguments}:
5630 @multitable @columnfractions .15 .70
5631 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
5635 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
5636 statement that should be preferred over the @code{FLUSH} intrinsic.
5638 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
5639 have identical effect: they flush the runtime library's I/O buffer so
5640 that the data becomes visible to other processes. This does not guarantee
5641 that the data is committed to disk.
5643 On POSIX systems, you can request that all data is transferred to the
5644 storage device by calling the @code{fsync} function, with the POSIX file
5645 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
5646 @code{FNUM}). The following example shows how:
5649 ! Declare the interface for POSIX fsync function
5651 function fsync (fd) bind(c,name="fsync")
5652 use iso_c_binding, only: c_int
5653 integer(c_int), value :: fd
5654 integer(c_int) :: fsync
5658 ! Variable declaration
5662 open (10,file="foo")
5665 ! Perform I/O on unit 10
5670 ret = fsync(fnum(10))
5672 ! Handle possible error
5673 if (ret /= 0) stop "Error calling FSYNC"
5681 @section @code{FNUM} --- File number function
5683 @cindex file operation, file number
5686 @item @emph{Description}:
5687 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
5688 open Fortran I/O unit @code{UNIT}.
5690 @item @emph{Standard}:
5696 @item @emph{Syntax}:
5697 @code{RESULT = FNUM(UNIT)}
5699 @item @emph{Arguments}:
5700 @multitable @columnfractions .15 .70
5701 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
5704 @item @emph{Return value}:
5705 The return value is of type @code{INTEGER}
5707 @item @emph{Example}:
5711 open (unit=10, status = "scratch")
5715 end program test_fnum
5722 @section @code{FPUT} --- Write a single character in stream mode to stdout
5724 @cindex write character, stream mode
5725 @cindex stream mode, write character
5726 @cindex file operation, write character
5729 @item @emph{Description}:
5730 Write a single character in stream mode to stdout by bypassing normal
5731 formatted output. Stream I/O should not be mixed with normal record-oriented
5732 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
5734 This intrinsic is provided in both subroutine and function forms; however,
5735 only one form can be used in any given program unit.
5737 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
5738 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5739 Programmers should consider the use of new stream IO feature in new code
5740 for future portability. See also @ref{Fortran 2003 status}.
5742 @item @emph{Standard}:
5746 Subroutine, function
5748 @item @emph{Syntax}:
5749 @multitable @columnfractions .80
5750 @item @code{CALL FPUT(C [, STATUS])}
5751 @item @code{STATUS = FPUT(C)}
5754 @item @emph{Arguments}:
5755 @multitable @columnfractions .15 .70
5756 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5758 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5759 Returns 0 on success, -1 on end-of-file and a system specific positive
5760 error code otherwise.
5763 @item @emph{Example}:
5766 CHARACTER(len=10) :: str = "gfortran"
5768 DO i = 1, len_trim(str)
5774 @item @emph{See also}:
5775 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
5781 @section @code{FPUTC} --- Write a single character in stream mode
5783 @cindex write character, stream mode
5784 @cindex stream mode, write character
5785 @cindex file operation, write character
5788 @item @emph{Description}:
5789 Write a single character in stream mode by bypassing normal formatted
5790 output. Stream I/O should not be mixed with normal record-oriented
5791 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
5793 This intrinsic is provided in both subroutine and function forms; however,
5794 only one form can be used in any given program unit.
5796 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
5797 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5798 Programmers should consider the use of new stream IO feature in new code
5799 for future portability. See also @ref{Fortran 2003 status}.
5801 @item @emph{Standard}:
5805 Subroutine, function
5807 @item @emph{Syntax}:
5808 @multitable @columnfractions .80
5809 @item @code{CALL FPUTC(UNIT, C [, STATUS])}
5810 @item @code{STATUS = FPUTC(UNIT, C)}
5813 @item @emph{Arguments}:
5814 @multitable @columnfractions .15 .70
5815 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
5816 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5818 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5819 Returns 0 on success, -1 on end-of-file and a system specific positive
5820 error code otherwise.
5823 @item @emph{Example}:
5826 CHARACTER(len=10) :: str = "gfortran"
5827 INTEGER :: fd = 42, i
5829 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
5830 DO i = 1, len_trim(str)
5831 CALL fputc(fd, str(i:i))
5837 @item @emph{See also}:
5838 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
5844 @section @code{FRACTION} --- Fractional part of the model representation
5846 @cindex real number, fraction
5847 @cindex floating point, fraction
5850 @item @emph{Description}:
5851 @code{FRACTION(X)} returns the fractional part of the model
5852 representation of @code{X}.
5854 @item @emph{Standard}:
5855 Fortran 95 and later
5860 @item @emph{Syntax}:
5861 @code{Y = FRACTION(X)}
5863 @item @emph{Arguments}:
5864 @multitable @columnfractions .15 .70
5865 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
5868 @item @emph{Return value}:
5869 The return value is of the same type and kind as the argument.
5870 The fractional part of the model representation of @code{X} is returned;
5871 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
5873 @item @emph{Example}:
5875 program test_fraction
5878 print *, fraction(x), x * radix(x)**(-exponent(x))
5879 end program test_fraction
5887 @section @code{FREE} --- Frees memory
5889 @cindex pointer, cray
5892 @item @emph{Description}:
5893 Frees memory previously allocated by @code{MALLOC}. The @code{FREE}
5894 intrinsic is an extension intended to be used with Cray pointers, and is
5895 provided in GNU Fortran to allow user to compile legacy code. For
5896 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
5899 @item @emph{Standard}:
5905 @item @emph{Syntax}:
5906 @code{CALL FREE(PTR)}
5908 @item @emph{Arguments}:
5909 @multitable @columnfractions .15 .70
5910 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
5911 location of the memory that should be de-allocated.
5914 @item @emph{Return value}:
5917 @item @emph{Example}:
5918 See @code{MALLOC} for an example.
5920 @item @emph{See also}:
5927 @section @code{FSEEK} --- Low level file positioning subroutine
5929 @cindex file operation, seek
5930 @cindex file operation, position
5933 @item @emph{Description}:
5934 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
5935 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
5936 if set to 1, @var{OFFSET} is taken to be relative to the current position
5937 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
5938 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
5941 This intrinsic routine is not fully backwards compatible with @command{g77}.
5942 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
5943 @var{STATUS} variable. If FSEEK is used in old code, change
5945 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
5950 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
5951 IF (status /= 0) GOTO label
5954 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
5955 Programmers should consider the use of new stream IO feature in new code
5956 for future portability. See also @ref{Fortran 2003 status}.
5958 @item @emph{Standard}:
5964 @item @emph{Syntax}:
5965 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
5967 @item @emph{Arguments}:
5968 @multitable @columnfractions .15 .70
5969 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
5970 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
5971 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
5972 Its value shall be either 0, 1 or 2.
5973 @item @var{STATUS} @tab (Optional) shall be a scalar of type
5977 @item @emph{Example}:
5980 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
5981 INTEGER :: fd, offset, ierr
5987 OPEN(UNIT=fd, FILE="fseek.test")
5988 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
5989 print *, FTELL(fd), ierr
5991 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
5992 print *, FTELL(fd), ierr
5994 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
5995 print *, FTELL(fd), ierr
6001 @item @emph{See also}:
6008 @section @code{FSTAT} --- Get file status
6010 @cindex file system, file status
6013 @item @emph{Description}:
6014 @code{FSTAT} is identical to @ref{STAT}, except that information about an
6015 already opened file is obtained.
6017 The elements in @code{VALUES} are the same as described by @ref{STAT}.
6019 This intrinsic is provided in both subroutine and function forms; however,
6020 only one form can be used in any given program unit.
6022 @item @emph{Standard}:
6026 Subroutine, function
6028 @item @emph{Syntax}:
6029 @multitable @columnfractions .80
6030 @item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
6031 @item @code{STATUS = FSTAT(UNIT, VALUES)}
6034 @item @emph{Arguments}:
6035 @multitable @columnfractions .15 .70
6036 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
6037 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
6038 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
6039 on success and a system specific error code otherwise.
6042 @item @emph{Example}:
6043 See @ref{STAT} for an example.
6045 @item @emph{See also}:
6046 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
6052 @section @code{FTELL} --- Current stream position
6054 @cindex file operation, position
6057 @item @emph{Description}:
6058 Retrieves the current position within an open file.
6060 This intrinsic is provided in both subroutine and function forms; however,
6061 only one form can be used in any given program unit.
6063 @item @emph{Standard}:
6067 Subroutine, function
6069 @item @emph{Syntax}:
6070 @multitable @columnfractions .80
6071 @item @code{CALL FTELL(UNIT, OFFSET)}
6072 @item @code{OFFSET = FTELL(UNIT)}
6075 @item @emph{Arguments}:
6076 @multitable @columnfractions .15 .70
6077 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
6078 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
6081 @item @emph{Return value}:
6082 In either syntax, @var{OFFSET} is set to the current offset of unit
6083 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
6085 @item @emph{Example}:
6089 OPEN(10, FILE="temp.dat")
6095 @item @emph{See also}:
6102 @section @code{GAMMA} --- Gamma function
6105 @cindex Gamma function
6106 @cindex Factorial function
6109 @item @emph{Description}:
6110 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
6111 integer values of @var{X} the Gamma function simplifies to the factorial
6112 function @math{\Gamma(x)=(x-1)!}.
6116 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
6120 @item @emph{Standard}:
6121 Fortran 2008 and later
6126 @item @emph{Syntax}:
6129 @item @emph{Arguments}:
6130 @multitable @columnfractions .15 .70
6131 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
6132 nor a negative integer.
6135 @item @emph{Return value}:
6136 The return value is of type @code{REAL} of the same kind as @var{X}.
6138 @item @emph{Example}:
6142 x = gamma(x) ! returns 1.0
6143 end program test_gamma
6146 @item @emph{Specific names}:
6147 @multitable @columnfractions .20 .20 .20 .25
6148 @item Name @tab Argument @tab Return type @tab Standard
6149 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
6150 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
6153 @item @emph{See also}:
6154 Logarithm of the Gamma function: @ref{LOG_GAMMA}
6161 @section @code{GERROR} --- Get last system error message
6163 @cindex system, error handling
6166 @item @emph{Description}:
6167 Returns the system error message corresponding to the last system error.
6168 This resembles the functionality of @code{strerror(3)} in C.
6170 @item @emph{Standard}:
6176 @item @emph{Syntax}:
6177 @code{CALL GERROR(RESULT)}
6179 @item @emph{Arguments}:
6180 @multitable @columnfractions .15 .70
6181 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
6184 @item @emph{Example}:
6187 CHARACTER(len=100) :: msg
6193 @item @emph{See also}:
6194 @ref{IERRNO}, @ref{PERROR}
6200 @section @code{GETARG} --- Get command line arguments
6202 @cindex command-line arguments
6203 @cindex arguments, to program
6206 @item @emph{Description}:
6207 Retrieve the @var{POS}-th argument that was passed on the
6208 command line when the containing program was invoked.
6210 This intrinsic routine is provided for backwards compatibility with
6211 GNU Fortran 77. In new code, programmers should consider the use of
6212 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
6215 @item @emph{Standard}:
6221 @item @emph{Syntax}:
6222 @code{CALL GETARG(POS, VALUE)}
6224 @item @emph{Arguments}:
6225 @multitable @columnfractions .15 .70
6226 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
6227 the default integer kind; @math{@var{POS} \geq 0}
6228 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
6230 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
6233 @item @emph{Return value}:
6234 After @code{GETARG} returns, the @var{VALUE} argument holds the
6235 @var{POS}th command line argument. If @var{VALUE} can not hold the
6236 argument, it is truncated to fit the length of @var{VALUE}. If there are
6237 less than @var{POS} arguments specified at the command line, @var{VALUE}
6238 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
6239 to the name of the program (on systems that support this feature).
6241 @item @emph{Example}:
6245 CHARACTER(len=32) :: arg
6254 @item @emph{See also}:
6255 GNU Fortran 77 compatibility function: @ref{IARGC}
6257 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
6258 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6264 @section @code{GET_COMMAND} --- Get the entire command line
6265 @fnindex GET_COMMAND
6266 @cindex command-line arguments
6267 @cindex arguments, to program
6270 @item @emph{Description}:
6271 Retrieve the entire command line that was used to invoke the program.
6273 @item @emph{Standard}:
6274 Fortran 2003 and later
6279 @item @emph{Syntax}:
6280 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
6282 @item @emph{Arguments}:
6283 @multitable @columnfractions .15 .70
6284 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
6286 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
6288 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
6292 @item @emph{Return value}:
6293 If @var{COMMAND} is present, stores the entire command line that was used
6294 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
6295 assigned the length of the command line. If @var{STATUS} is present, it
6296 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
6297 short to store the command line, or a positive value in case of an error.
6299 @item @emph{Example}:
6301 PROGRAM test_get_command
6302 CHARACTER(len=255) :: cmd
6303 CALL get_command(cmd)
6304 WRITE (*,*) TRIM(cmd)
6308 @item @emph{See also}:
6309 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6314 @node GET_COMMAND_ARGUMENT
6315 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
6316 @fnindex GET_COMMAND_ARGUMENT
6317 @cindex command-line arguments
6318 @cindex arguments, to program
6321 @item @emph{Description}:
6322 Retrieve the @var{NUMBER}-th argument that was passed on the
6323 command line when the containing program was invoked.
6325 @item @emph{Standard}:
6326 Fortran 2003 and later
6331 @item @emph{Syntax}:
6332 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
6334 @item @emph{Arguments}:
6335 @multitable @columnfractions .15 .70
6336 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
6337 default kind, @math{@var{NUMBER} \geq 0}
6338 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
6339 and of default kind.
6340 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6341 and of default kind.
6342 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6343 and of default kind.
6346 @item @emph{Return value}:
6347 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
6348 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
6349 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
6350 arguments specified at the command line, @var{VALUE} will be filled with blanks.
6351 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
6352 systems that support this feature). The @var{LENGTH} argument contains the
6353 length of the @var{NUMBER}-th command line argument. If the argument retrieval
6354 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
6355 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
6358 @item @emph{Example}:
6360 PROGRAM test_get_command_argument
6362 CHARACTER(len=32) :: arg
6366 CALL get_command_argument(i, arg)
6367 IF (LEN_TRIM(arg) == 0) EXIT
6369 WRITE (*,*) TRIM(arg)
6375 @item @emph{See also}:
6376 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
6382 @section @code{GETCWD} --- Get current working directory
6384 @cindex system, working directory
6387 @item @emph{Description}:
6388 Get current working directory.
6390 This intrinsic is provided in both subroutine and function forms; however,
6391 only one form can be used in any given program unit.
6393 @item @emph{Standard}:
6397 Subroutine, function
6399 @item @emph{Syntax}:
6400 @multitable @columnfractions .80
6401 @item @code{CALL GETCWD(C [, STATUS])}
6402 @item @code{STATUS = GETCWD(C)}
6405 @item @emph{Arguments}:
6406 @multitable @columnfractions .15 .70
6407 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
6408 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
6409 a system specific and nonzero error code otherwise.
6412 @item @emph{Example}:
6415 CHARACTER(len=255) :: cwd
6417 WRITE(*,*) TRIM(cwd)
6421 @item @emph{See also}:
6428 @section @code{GETENV} --- Get an environmental variable
6430 @cindex environment variable
6433 @item @emph{Description}:
6434 Get the @var{VALUE} of the environmental variable @var{NAME}.
6436 This intrinsic routine is provided for backwards compatibility with
6437 GNU Fortran 77. In new code, programmers should consider the use of
6438 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
6441 Note that @code{GETENV} need not be thread-safe. It is the
6442 responsibility of the user to ensure that the environment is not being
6443 updated concurrently with a call to the @code{GETENV} intrinsic.
6445 @item @emph{Standard}:
6451 @item @emph{Syntax}:
6452 @code{CALL GETENV(NAME, VALUE)}
6454 @item @emph{Arguments}:
6455 @multitable @columnfractions .15 .70
6456 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
6457 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
6460 @item @emph{Return value}:
6461 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
6462 not large enough to hold the data, it is truncated. If @var{NAME}
6463 is not set, @var{VALUE} will be filled with blanks.
6465 @item @emph{Example}:
6468 CHARACTER(len=255) :: homedir
6469 CALL getenv("HOME", homedir)
6470 WRITE (*,*) TRIM(homedir)
6474 @item @emph{See also}:
6475 @ref{GET_ENVIRONMENT_VARIABLE}
6480 @node GET_ENVIRONMENT_VARIABLE
6481 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
6482 @fnindex GET_ENVIRONMENT_VARIABLE
6483 @cindex environment variable
6486 @item @emph{Description}:
6487 Get the @var{VALUE} of the environmental variable @var{NAME}.
6489 Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It
6490 is the responsibility of the user to ensure that the environment is
6491 not being updated concurrently with a call to the
6492 @code{GET_ENVIRONMENT_VARIABLE} intrinsic.
6494 @item @emph{Standard}:
6495 Fortran 2003 and later
6500 @item @emph{Syntax}:
6501 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
6503 @item @emph{Arguments}:
6504 @multitable @columnfractions .15 .70
6505 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
6506 and of default kind.
6507 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
6508 and of default kind.
6509 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6510 and of default kind.
6511 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6512 and of default kind.
6513 @item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL}
6514 and of default kind.
6517 @item @emph{Return value}:
6518 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
6519 not large enough to hold the data, it is truncated. If @var{NAME}
6520 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
6521 contains the length needed for storing the environment variable @var{NAME}
6522 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
6523 but too short for the environment variable; it is 1 if the environment
6524 variable does not exist and 2 if the processor does not support environment
6525 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
6526 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
6527 are significant; otherwise they are not part of the environment variable
6530 @item @emph{Example}:
6533 CHARACTER(len=255) :: homedir
6534 CALL get_environment_variable("HOME", homedir)
6535 WRITE (*,*) TRIM(homedir)
6543 @section @code{GETGID} --- Group ID function
6545 @cindex system, group ID
6548 @item @emph{Description}:
6549 Returns the numerical group ID of the current process.
6551 @item @emph{Standard}:
6557 @item @emph{Syntax}:
6558 @code{RESULT = GETGID()}
6560 @item @emph{Return value}:
6561 The return value of @code{GETGID} is an @code{INTEGER} of the default
6565 @item @emph{Example}:
6566 See @code{GETPID} for an example.
6568 @item @emph{See also}:
6569 @ref{GETPID}, @ref{GETUID}
6575 @section @code{GETLOG} --- Get login name
6577 @cindex system, login name
6581 @item @emph{Description}:
6582 Gets the username under which the program is running.
6584 @item @emph{Standard}:
6590 @item @emph{Syntax}:
6591 @code{CALL GETLOG(C)}
6593 @item @emph{Arguments}:
6594 @multitable @columnfractions .15 .70
6595 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
6598 @item @emph{Return value}:
6599 Stores the current user name in @var{LOGIN}. (On systems where POSIX
6600 functions @code{geteuid} and @code{getpwuid} are not available, and
6601 the @code{getlogin} function is not implemented either, this will
6602 return a blank string.)
6604 @item @emph{Example}:
6607 CHARACTER(32) :: login
6613 @item @emph{See also}:
6620 @section @code{GETPID} --- Process ID function
6622 @cindex system, process ID
6626 @item @emph{Description}:
6627 Returns the numerical process identifier of the current process.
6629 @item @emph{Standard}:
6635 @item @emph{Syntax}:
6636 @code{RESULT = GETPID()}
6638 @item @emph{Return value}:
6639 The return value of @code{GETPID} is an @code{INTEGER} of the default
6643 @item @emph{Example}:
6646 print *, "The current process ID is ", getpid()
6647 print *, "Your numerical user ID is ", getuid()
6648 print *, "Your numerical group ID is ", getgid()
6652 @item @emph{See also}:
6653 @ref{GETGID}, @ref{GETUID}
6659 @section @code{GETUID} --- User ID function
6661 @cindex system, user ID
6665 @item @emph{Description}:
6666 Returns the numerical user ID of the current process.
6668 @item @emph{Standard}:
6674 @item @emph{Syntax}:
6675 @code{RESULT = GETUID()}
6677 @item @emph{Return value}:
6678 The return value of @code{GETUID} is an @code{INTEGER} of the default
6682 @item @emph{Example}:
6683 See @code{GETPID} for an example.
6685 @item @emph{See also}:
6686 @ref{GETPID}, @ref{GETLOG}
6692 @section @code{GMTIME} --- Convert time to GMT info
6694 @cindex time, conversion to GMT info
6697 @item @emph{Description}:
6698 Given a system time value @var{TIME} (as provided by the @code{TIME8}
6699 intrinsic), fills @var{VALUES} with values extracted from it appropriate
6700 to the UTC time zone (Universal Coordinated Time, also known in some
6701 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
6703 @item @emph{Standard}:
6709 @item @emph{Syntax}:
6710 @code{CALL GMTIME(TIME, VALUES)}
6712 @item @emph{Arguments}:
6713 @multitable @columnfractions .15 .70
6714 @item @var{TIME} @tab An @code{INTEGER} scalar expression
6715 corresponding to a system time, with @code{INTENT(IN)}.
6716 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
6717 with @code{INTENT(OUT)}.
6720 @item @emph{Return value}:
6721 The elements of @var{VALUES} are assigned as follows:
6723 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
6725 @item Minutes after the hour, range 0--59
6726 @item Hours past midnight, range 0--23
6727 @item Day of month, range 0--31
6728 @item Number of months since January, range 0--12
6729 @item Years since 1900
6730 @item Number of days since Sunday, range 0--6
6731 @item Days since January 1
6732 @item Daylight savings indicator: positive if daylight savings is in
6733 effect, zero if not, and negative if the information is not available.
6736 @item @emph{See also}:
6737 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
6744 @section @code{HOSTNM} --- Get system host name
6746 @cindex system, host name
6749 @item @emph{Description}:
6750 Retrieves the host name of the system on which the program is running.
6752 This intrinsic is provided in both subroutine and function forms; however,
6753 only one form can be used in any given program unit.
6755 @item @emph{Standard}:
6759 Subroutine, function
6761 @item @emph{Syntax}:
6762 @multitable @columnfractions .80
6763 @item @code{CALL HOSTNM(C [, STATUS])}
6764 @item @code{STATUS = HOSTNM(NAME)}
6767 @item @emph{Arguments}:
6768 @multitable @columnfractions .15 .70
6769 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
6770 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6771 Returns 0 on success, or a system specific error code otherwise.
6774 @item @emph{Return value}:
6775 In either syntax, @var{NAME} is set to the current hostname if it can
6776 be obtained, or to a blank string otherwise.
6783 @section @code{HUGE} --- Largest number of a kind
6785 @cindex limits, largest number
6786 @cindex model representation, largest number
6789 @item @emph{Description}:
6790 @code{HUGE(X)} returns the largest number that is not an infinity in
6791 the model of the type of @code{X}.
6793 @item @emph{Standard}:
6794 Fortran 95 and later
6799 @item @emph{Syntax}:
6800 @code{RESULT = HUGE(X)}
6802 @item @emph{Arguments}:
6803 @multitable @columnfractions .15 .70
6804 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
6807 @item @emph{Return value}:
6808 The return value is of the same type and kind as @var{X}
6810 @item @emph{Example}:
6812 program test_huge_tiny
6813 print *, huge(0), huge(0.0), huge(0.0d0)
6814 print *, tiny(0.0), tiny(0.0d0)
6815 end program test_huge_tiny
6822 @section @code{HYPOT} --- Euclidean distance function
6824 @cindex Euclidean distance
6827 @item @emph{Description}:
6828 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
6829 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
6831 @item @emph{Standard}:
6832 Fortran 2008 and later
6837 @item @emph{Syntax}:
6838 @code{RESULT = HYPOT(X, Y)}
6840 @item @emph{Arguments}:
6841 @multitable @columnfractions .15 .70
6842 @item @var{X} @tab The type shall be @code{REAL}.
6843 @item @var{Y} @tab The type and kind type parameter shall be the same as
6847 @item @emph{Return value}:
6848 The return value has the same type and kind type parameter as @var{X}.
6850 @item @emph{Example}:
6853 real(4) :: x = 1.e0_4, y = 0.5e0_4
6855 end program test_hypot
6862 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
6864 @cindex @acronym{ASCII} collating sequence
6865 @cindex collating sequence, @acronym{ASCII}
6866 @cindex conversion, to integer
6869 @item @emph{Description}:
6870 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
6871 in the first character position of @code{C}.
6873 @item @emph{Standard}:
6874 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6879 @item @emph{Syntax}:
6880 @code{RESULT = IACHAR(C [, KIND])}
6882 @item @emph{Arguments}:
6883 @multitable @columnfractions .15 .70
6884 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
6885 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6886 expression indicating the kind parameter of the result.
6889 @item @emph{Return value}:
6890 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6891 @var{KIND} is absent, the return value is of default integer kind.
6893 @item @emph{Example}:
6898 end program test_iachar
6902 See @ref{ICHAR} for a discussion of converting between numerical values
6903 and formatted string representations.
6905 @item @emph{See also}:
6906 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
6913 @section @code{IALL} --- Bitwise AND of array elements
6916 @cindex bits, AND of array elements
6919 @item @emph{Description}:
6920 Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
6921 if the corresponding element in @var{MASK} is @code{TRUE}.
6923 @item @emph{Standard}:
6924 Fortran 2008 and later
6927 Transformational function
6929 @item @emph{Syntax}:
6930 @multitable @columnfractions .80
6931 @item @code{RESULT = IALL(ARRAY[, MASK])}
6932 @item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
6935 @item @emph{Arguments}:
6936 @multitable @columnfractions .15 .70
6937 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6938 @item @var{DIM} @tab (Optional) shall be a scalar of type
6939 @code{INTEGER} with a value in the range from 1 to n, where n
6940 equals the rank of @var{ARRAY}.
6941 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
6942 and either be a scalar or an array of the same shape as @var{ARRAY}.
6945 @item @emph{Return value}:
6946 The result is of the same type as @var{ARRAY}.
6948 If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
6949 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6950 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6951 dimension @var{DIM} dropped is returned.
6953 @item @emph{Example}:
6962 PRINT '(b8.8)', IALL(a)
6966 @item @emph{See also}:
6967 @ref{IANY}, @ref{IPARITY}, @ref{IAND}
6973 @section @code{IAND} --- Bitwise logical and
6975 @cindex bitwise logical and
6976 @cindex logical and, bitwise
6979 @item @emph{Description}:
6980 Bitwise logical @code{AND}.
6982 @item @emph{Standard}:
6983 Fortran 95 and later
6988 @item @emph{Syntax}:
6989 @code{RESULT = IAND(I, J)}
6991 @item @emph{Arguments}:
6992 @multitable @columnfractions .15 .70
6993 @item @var{I} @tab The type shall be @code{INTEGER}.
6994 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6995 kind as @var{I}. (As a GNU extension, different kinds are also
6999 @item @emph{Return value}:
7000 The return type is @code{INTEGER}, of the same kind as the
7001 arguments. (If the argument kinds differ, it is of the same kind as
7002 the larger argument.)
7004 @item @emph{Example}:
7008 DATA a / Z'F' /, b / Z'3' /
7009 WRITE (*,*) IAND(a, b)
7013 @item @emph{See also}:
7014 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
7021 @section @code{IANY} --- Bitwise OR of array elements
7024 @cindex bits, OR of array elements
7027 @item @emph{Description}:
7028 Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
7029 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
7031 @item @emph{Standard}:
7032 Fortran 2008 and later
7035 Transformational function
7037 @item @emph{Syntax}:
7038 @multitable @columnfractions .80
7039 @item @code{RESULT = IANY(ARRAY[, MASK])}
7040 @item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
7043 @item @emph{Arguments}:
7044 @multitable @columnfractions .15 .70
7045 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7046 @item @var{DIM} @tab (Optional) shall be a scalar of type
7047 @code{INTEGER} with a value in the range from 1 to n, where n
7048 equals the rank of @var{ARRAY}.
7049 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
7050 and either be a scalar or an array of the same shape as @var{ARRAY}.
7053 @item @emph{Return value}:
7054 The result is of the same type as @var{ARRAY}.
7056 If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
7057 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7058 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7059 dimension @var{DIM} dropped is returned.
7061 @item @emph{Example}:
7070 PRINT '(b8.8)', IANY(a)
7074 @item @emph{See also}:
7075 @ref{IPARITY}, @ref{IALL}, @ref{IOR}
7081 @section @code{IARGC} --- Get the number of command line arguments
7083 @cindex command-line arguments
7084 @cindex command-line arguments, number of
7085 @cindex arguments, to program
7088 @item @emph{Description}:
7089 @code{IARGC} returns the number of arguments passed on the
7090 command line when the containing program was invoked.
7092 This intrinsic routine is provided for backwards compatibility with
7093 GNU Fortran 77. In new code, programmers should consider the use of
7094 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
7097 @item @emph{Standard}:
7103 @item @emph{Syntax}:
7104 @code{RESULT = IARGC()}
7106 @item @emph{Arguments}:
7109 @item @emph{Return value}:
7110 The number of command line arguments, type @code{INTEGER(4)}.
7112 @item @emph{Example}:
7115 @item @emph{See also}:
7116 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
7118 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
7119 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
7125 @section @code{IBCLR} --- Clear bit
7131 @item @emph{Description}:
7132 @code{IBCLR} returns the value of @var{I} with the bit at position
7133 @var{POS} set to zero.
7135 @item @emph{Standard}:
7136 Fortran 95 and later
7141 @item @emph{Syntax}:
7142 @code{RESULT = IBCLR(I, POS)}
7144 @item @emph{Arguments}:
7145 @multitable @columnfractions .15 .70
7146 @item @var{I} @tab The type shall be @code{INTEGER}.
7147 @item @var{POS} @tab The type shall be @code{INTEGER}.
7150 @item @emph{Return value}:
7151 The return value is of type @code{INTEGER} and of the same kind as
7154 @item @emph{See also}:
7155 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
7162 @section @code{IBITS} --- Bit extraction
7165 @cindex bits, extract
7168 @item @emph{Description}:
7169 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
7170 starting from bit position @var{POS} and extending left for @var{LEN}
7171 bits. The result is right-justified and the remaining bits are
7172 zeroed. The value of @code{POS+LEN} must be less than or equal to the
7173 value @code{BIT_SIZE(I)}.
7175 @item @emph{Standard}:
7176 Fortran 95 and later
7181 @item @emph{Syntax}:
7182 @code{RESULT = IBITS(I, POS, LEN)}
7184 @item @emph{Arguments}:
7185 @multitable @columnfractions .15 .70
7186 @item @var{I} @tab The type shall be @code{INTEGER}.
7187 @item @var{POS} @tab The type shall be @code{INTEGER}.
7188 @item @var{LEN} @tab The type shall be @code{INTEGER}.
7191 @item @emph{Return value}:
7192 The return value is of type @code{INTEGER} and of the same kind as
7195 @item @emph{See also}:
7196 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
7202 @section @code{IBSET} --- Set bit
7207 @item @emph{Description}:
7208 @code{IBSET} returns the value of @var{I} with the bit at position
7209 @var{POS} set to one.
7211 @item @emph{Standard}:
7212 Fortran 95 and later
7217 @item @emph{Syntax}:
7218 @code{RESULT = IBSET(I, POS)}
7220 @item @emph{Arguments}:
7221 @multitable @columnfractions .15 .70
7222 @item @var{I} @tab The type shall be @code{INTEGER}.
7223 @item @var{POS} @tab The type shall be @code{INTEGER}.
7226 @item @emph{Return value}:
7227 The return value is of type @code{INTEGER} and of the same kind as
7230 @item @emph{See also}:
7231 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
7238 @section @code{ICHAR} --- Character-to-integer conversion function
7240 @cindex conversion, to integer
7243 @item @emph{Description}:
7244 @code{ICHAR(C)} returns the code for the character in the first character
7245 position of @code{C} in the system's native character set.
7246 The correspondence between characters and their codes is not necessarily
7247 the same across different GNU Fortran implementations.
7249 @item @emph{Standard}:
7250 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7255 @item @emph{Syntax}:
7256 @code{RESULT = ICHAR(C [, KIND])}
7258 @item @emph{Arguments}:
7259 @multitable @columnfractions .15 .70
7260 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
7261 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7262 expression indicating the kind parameter of the result.
7265 @item @emph{Return value}:
7266 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7267 @var{KIND} is absent, the return value is of default integer kind.
7269 @item @emph{Example}:
7274 end program test_ichar
7277 @item @emph{Specific names}:
7278 @multitable @columnfractions .20 .20 .20 .25
7279 @item Name @tab Argument @tab Return type @tab Standard
7280 @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7284 No intrinsic exists to convert between a numeric value and a formatted
7285 character string representation -- for instance, given the
7286 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
7287 @code{REAL} value with the value 154, or vice versa. Instead, this
7288 functionality is provided by internal-file I/O, as in the following
7293 character(len=10) string, string2
7296 ! Convert a string to a numeric value
7297 read (string,'(I10)') value
7300 ! Convert a value to a formatted string
7301 write (string2,'(I10)') value
7303 end program read_val
7306 @item @emph{See also}:
7307 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
7314 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
7316 @cindex date, current
7317 @cindex current date
7320 @item @emph{Description}:
7321 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
7322 current local time. The day (in the range 1-31), month (in the range 1-12),
7323 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
7324 The year has four significant digits.
7326 @item @emph{Standard}:
7332 @item @emph{Syntax}:
7333 @code{CALL IDATE(VALUES)}
7335 @item @emph{Arguments}:
7336 @multitable @columnfractions .15 .70
7337 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
7338 the kind shall be the default integer kind.
7341 @item @emph{Return value}:
7342 Does not return anything.
7344 @item @emph{Example}:
7347 integer, dimension(3) :: tarray
7352 end program test_idate
7359 @section @code{IEOR} --- Bitwise logical exclusive or
7361 @cindex bitwise logical exclusive or
7362 @cindex logical exclusive or, bitwise
7365 @item @emph{Description}:
7366 @code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
7369 @item @emph{Standard}:
7370 Fortran 95 and later
7375 @item @emph{Syntax}:
7376 @code{RESULT = IEOR(I, J)}
7378 @item @emph{Arguments}:
7379 @multitable @columnfractions .15 .70
7380 @item @var{I} @tab The type shall be @code{INTEGER}.
7381 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
7382 kind as @var{I}. (As a GNU extension, different kinds are also
7386 @item @emph{Return value}:
7387 The return type is @code{INTEGER}, of the same kind as the
7388 arguments. (If the argument kinds differ, it is of the same kind as
7389 the larger argument.)
7391 @item @emph{See also}:
7392 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
7398 @section @code{IERRNO} --- Get the last system error number
7400 @cindex system, error handling
7403 @item @emph{Description}:
7404 Returns the last system error number, as given by the C @code{errno}
7407 @item @emph{Standard}:
7413 @item @emph{Syntax}:
7414 @code{RESULT = IERRNO()}
7416 @item @emph{Arguments}:
7419 @item @emph{Return value}:
7420 The return value is of type @code{INTEGER} and of the default integer
7423 @item @emph{See also}:
7430 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
7431 @fnindex IMAGE_INDEX
7432 @cindex coarray, @code{IMAGE_INDEX}
7433 @cindex images, cosubscript to image index conversion
7436 @item @emph{Description}:
7437 Returns the image index belonging to a cosubscript.
7439 @item @emph{Standard}:
7440 Fortran 2008 and later
7445 @item @emph{Syntax}:
7446 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
7448 @item @emph{Arguments}: None.
7449 @multitable @columnfractions .15 .70
7450 @item @var{COARRAY} @tab Coarray of any type.
7451 @item @var{SUB} @tab default integer rank-1 array of a size equal to
7452 the corank of @var{COARRAY}.
7456 @item @emph{Return value}:
7457 Scalar default integer with the value of the image index which corresponds
7458 to the cosubscripts. For invalid cosubscripts the result is zero.
7460 @item @emph{Example}:
7462 INTEGER :: array[2,-1:4,8,*]
7463 ! Writes 28 (or 0 if there are fewer than 28 images)
7464 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
7467 @item @emph{See also}:
7468 @ref{THIS_IMAGE}, @ref{NUM_IMAGES}
7473 @node INDEX intrinsic
7474 @section @code{INDEX} --- Position of a substring within a string
7476 @cindex substring position
7477 @cindex string, find substring
7480 @item @emph{Description}:
7481 Returns the position of the start of the first occurrence of string
7482 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
7483 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
7484 the @var{BACK} argument is present and true, the return value is the
7485 start of the last occurrence rather than the first.
7487 @item @emph{Standard}:
7488 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
7493 @item @emph{Syntax}:
7494 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
7496 @item @emph{Arguments}:
7497 @multitable @columnfractions .15 .70
7498 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
7500 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
7502 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
7504 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7505 expression indicating the kind parameter of the result.
7508 @item @emph{Return value}:
7509 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7510 @var{KIND} is absent, the return value is of default integer kind.
7512 @item @emph{Specific names}:
7513 @multitable @columnfractions .20 .20 .20 .25
7514 @item Name @tab Argument @tab Return type @tab Standard
7515 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7518 @item @emph{See also}:
7519 @ref{SCAN}, @ref{VERIFY}
7525 @section @code{INT} --- Convert to integer type
7529 @cindex conversion, to integer
7532 @item @emph{Description}:
7533 Convert to integer type
7535 @item @emph{Standard}:
7536 Fortran 77 and later
7541 @item @emph{Syntax}:
7542 @code{RESULT = INT(A [, KIND))}
7544 @item @emph{Arguments}:
7545 @multitable @columnfractions .15 .70
7546 @item @var{A} @tab Shall be of type @code{INTEGER},
7547 @code{REAL}, or @code{COMPLEX}.
7548 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7549 expression indicating the kind parameter of the result.
7552 @item @emph{Return value}:
7553 These functions return a @code{INTEGER} variable or array under
7554 the following rules:
7558 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
7560 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)}
7561 equals @code{0}. If @math{|A| \geq 1}, then @code{INT(A)} is the integer
7562 whose magnitude is the largest integer that does not exceed the magnitude
7563 of @var{A} and whose sign is the same as the sign of @var{A}.
7565 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
7568 @item @emph{Example}:
7572 complex :: z = (-3.7, 1.0)
7574 print *, int(z), int(z,8)
7578 @item @emph{Specific names}:
7579 @multitable @columnfractions .20 .20 .20 .25
7580 @item Name @tab Argument @tab Return type @tab Standard
7581 @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
7582 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
7583 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
7590 @section @code{INT2} --- Convert to 16-bit integer type
7593 @cindex conversion, to integer
7596 @item @emph{Description}:
7597 Convert to a @code{KIND=2} integer type. This is equivalent to the
7598 standard @code{INT} intrinsic with an optional argument of
7599 @code{KIND=2}, and is only included for backwards compatibility.
7601 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
7603 @item @emph{Standard}:
7609 @item @emph{Syntax}:
7610 @code{RESULT = INT2(A)}
7612 @item @emph{Arguments}:
7613 @multitable @columnfractions .15 .70
7614 @item @var{A} @tab Shall be of type @code{INTEGER},
7615 @code{REAL}, or @code{COMPLEX}.
7618 @item @emph{Return value}:
7619 The return value is a @code{INTEGER(2)} variable.
7621 @item @emph{See also}:
7622 @ref{INT}, @ref{INT8}, @ref{LONG}
7628 @section @code{INT8} --- Convert to 64-bit integer type
7630 @cindex conversion, to integer
7633 @item @emph{Description}:
7634 Convert to a @code{KIND=8} integer type. This is equivalent to the
7635 standard @code{INT} intrinsic with an optional argument of
7636 @code{KIND=8}, and is only included for backwards compatibility.
7638 @item @emph{Standard}:
7644 @item @emph{Syntax}:
7645 @code{RESULT = INT8(A)}
7647 @item @emph{Arguments}:
7648 @multitable @columnfractions .15 .70
7649 @item @var{A} @tab Shall be of type @code{INTEGER},
7650 @code{REAL}, or @code{COMPLEX}.
7653 @item @emph{Return value}:
7654 The return value is a @code{INTEGER(8)} variable.
7656 @item @emph{See also}:
7657 @ref{INT}, @ref{INT2}, @ref{LONG}
7663 @section @code{IOR} --- Bitwise logical or
7665 @cindex bitwise logical or
7666 @cindex logical or, bitwise
7669 @item @emph{Description}:
7670 @code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
7673 @item @emph{Standard}:
7674 Fortran 95 and later
7679 @item @emph{Syntax}:
7680 @code{RESULT = IOR(I, J)}
7682 @item @emph{Arguments}:
7683 @multitable @columnfractions .15 .70
7684 @item @var{I} @tab The type shall be @code{INTEGER}.
7685 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
7686 kind as @var{I}. (As a GNU extension, different kinds are also
7690 @item @emph{Return value}:
7691 The return type is @code{INTEGER}, of the same kind as the
7692 arguments. (If the argument kinds differ, it is of the same kind as
7693 the larger argument.)
7695 @item @emph{See also}:
7696 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
7702 @section @code{IPARITY} --- Bitwise XOR of array elements
7704 @cindex array, parity
7706 @cindex bits, XOR of array elements
7709 @item @emph{Description}:
7710 Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
7711 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
7713 @item @emph{Standard}:
7714 Fortran 2008 and later
7717 Transformational function
7719 @item @emph{Syntax}:
7720 @multitable @columnfractions .80
7721 @item @code{RESULT = IPARITY(ARRAY[, MASK])}
7722 @item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
7725 @item @emph{Arguments}:
7726 @multitable @columnfractions .15 .70
7727 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7728 @item @var{DIM} @tab (Optional) shall be a scalar of type
7729 @code{INTEGER} with a value in the range from 1 to n, where n
7730 equals the rank of @var{ARRAY}.
7731 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
7732 and either be a scalar or an array of the same shape as @var{ARRAY}.
7735 @item @emph{Return value}:
7736 The result is of the same type as @var{ARRAY}.
7738 If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
7739 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7740 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7741 dimension @var{DIM} dropped is returned.
7743 @item @emph{Example}:
7745 PROGRAM test_iparity
7752 PRINT '(b8.8)', IPARITY(a)
7756 @item @emph{See also}:
7757 @ref{IANY}, @ref{IALL}, @ref{IEOR}, @ref{PARITY}
7763 @section @code{IRAND} --- Integer pseudo-random number
7765 @cindex random number generation
7768 @item @emph{Description}:
7769 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
7770 distribution between 0 and a system-dependent limit (which is in most
7771 cases 2147483647). If @var{FLAG} is 0, the next number
7772 in the current sequence is returned; if @var{FLAG} is 1, the generator
7773 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
7774 it is used as a new seed with @code{SRAND}.
7776 This intrinsic routine is provided for backwards compatibility with
7777 GNU Fortran 77. It implements a simple modulo generator as provided
7778 by @command{g77}. For new code, one should consider the use of
7779 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
7781 @item @emph{Standard}:
7787 @item @emph{Syntax}:
7788 @code{RESULT = IRAND(I)}
7790 @item @emph{Arguments}:
7791 @multitable @columnfractions .15 .70
7792 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
7795 @item @emph{Return value}:
7796 The return value is of @code{INTEGER(kind=4)} type.
7798 @item @emph{Example}:
7801 integer,parameter :: seed = 86456
7804 print *, irand(), irand(), irand(), irand()
7805 print *, irand(seed), irand(), irand(), irand()
7806 end program test_irand
7814 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
7815 @fnindex IS_IOSTAT_END
7816 @cindex @code{IOSTAT}, end of file
7819 @item @emph{Description}:
7820 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
7821 status ``end of file''. The function is equivalent to comparing the variable
7822 with the @code{IOSTAT_END} parameter of the intrinsic module
7823 @code{ISO_FORTRAN_ENV}.
7825 @item @emph{Standard}:
7826 Fortran 2003 and later
7831 @item @emph{Syntax}:
7832 @code{RESULT = IS_IOSTAT_END(I)}
7834 @item @emph{Arguments}:
7835 @multitable @columnfractions .15 .70
7836 @item @var{I} @tab Shall be of the type @code{INTEGER}.
7839 @item @emph{Return value}:
7840 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
7841 @var{I} has the value which indicates an end of file condition for
7842 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
7844 @item @emph{Example}:
7849 OPEN(88, FILE='test.dat')
7850 READ(88, *, IOSTAT=stat) i
7851 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
7859 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
7860 @fnindex IS_IOSTAT_EOR
7861 @cindex @code{IOSTAT}, end of record
7864 @item @emph{Description}:
7865 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
7866 status ``end of record''. The function is equivalent to comparing the
7867 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
7868 @code{ISO_FORTRAN_ENV}.
7870 @item @emph{Standard}:
7871 Fortran 2003 and later
7876 @item @emph{Syntax}:
7877 @code{RESULT = IS_IOSTAT_EOR(I)}
7879 @item @emph{Arguments}:
7880 @multitable @columnfractions .15 .70
7881 @item @var{I} @tab Shall be of the type @code{INTEGER}.
7884 @item @emph{Return value}:
7885 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
7886 @var{I} has the value which indicates an end of file condition for
7887 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
7889 @item @emph{Example}:
7893 INTEGER :: stat, i(50)
7894 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
7895 READ(88, IOSTAT=stat) i
7896 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
7904 @section @code{ISATTY} --- Whether a unit is a terminal device.
7906 @cindex system, terminal
7909 @item @emph{Description}:
7910 Determine whether a unit is connected to a terminal device.
7912 @item @emph{Standard}:
7918 @item @emph{Syntax}:
7919 @code{RESULT = ISATTY(UNIT)}
7921 @item @emph{Arguments}:
7922 @multitable @columnfractions .15 .70
7923 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
7926 @item @emph{Return value}:
7927 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
7928 device, @code{.FALSE.} otherwise.
7930 @item @emph{Example}:
7933 INTEGER(kind=1) :: unit
7935 write(*,*) isatty(unit=unit)
7939 @item @emph{See also}:
7946 @section @code{ISHFT} --- Shift bits
7951 @item @emph{Description}:
7952 @code{ISHFT} returns a value corresponding to @var{I} with all of the
7953 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
7954 zero corresponds to a left shift, a value of zero corresponds to no
7955 shift, and a value less than zero corresponds to a right shift. If the
7956 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
7957 value is undefined. Bits shifted out from the left end or right end are
7958 lost; zeros are shifted in from the opposite end.
7960 @item @emph{Standard}:
7961 Fortran 95 and later
7966 @item @emph{Syntax}:
7967 @code{RESULT = ISHFT(I, SHIFT)}
7969 @item @emph{Arguments}:
7970 @multitable @columnfractions .15 .70
7971 @item @var{I} @tab The type shall be @code{INTEGER}.
7972 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7975 @item @emph{Return value}:
7976 The return value is of type @code{INTEGER} and of the same kind as
7979 @item @emph{See also}:
7986 @section @code{ISHFTC} --- Shift bits circularly
7988 @cindex bits, shift circular
7991 @item @emph{Description}:
7992 @code{ISHFTC} returns a value corresponding to @var{I} with the
7993 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
7994 is, bits shifted out one end are shifted into the opposite end. A value
7995 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
7996 zero corresponds to no shift, and a value less than zero corresponds to
7997 a right shift. The absolute value of @var{SHIFT} must be less than
7998 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
7999 equivalent to @code{BIT_SIZE(I)}.
8001 @item @emph{Standard}:
8002 Fortran 95 and later
8007 @item @emph{Syntax}:
8008 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
8010 @item @emph{Arguments}:
8011 @multitable @columnfractions .15 .70
8012 @item @var{I} @tab The type shall be @code{INTEGER}.
8013 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8014 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
8015 the value must be greater than zero and less than or equal to
8019 @item @emph{Return value}:
8020 The return value is of type @code{INTEGER} and of the same kind as
8023 @item @emph{See also}:
8030 @section @code{ISNAN} --- Test for a NaN
8035 @item @emph{Description}:
8036 @code{ISNAN} tests whether a floating-point value is an IEEE
8038 @item @emph{Standard}:
8044 @item @emph{Syntax}:
8047 @item @emph{Arguments}:
8048 @multitable @columnfractions .15 .70
8049 @item @var{X} @tab Variable of the type @code{REAL}.
8053 @item @emph{Return value}:
8054 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
8055 if @var{X} is a NaN and @code{FALSE} otherwise.
8057 @item @emph{Example}:
8064 if (isnan(x)) stop '"x" is a NaN'
8065 end program test_nan
8072 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
8074 @cindex time, current
8075 @cindex current time
8078 @item @emph{Description}:
8079 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
8080 current local time. The hour (in the range 1-24), minute (in the range 1-60),
8081 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
8084 @item @emph{Standard}:
8090 @item @emph{Syntax}:
8091 @code{CALL ITIME(VALUES)}
8093 @item @emph{Arguments}:
8094 @multitable @columnfractions .15 .70
8095 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
8096 and the kind shall be the default integer kind.
8099 @item @emph{Return value}:
8100 Does not return anything.
8103 @item @emph{Example}:
8106 integer, dimension(3) :: tarray
8111 end program test_itime
8118 @section @code{KILL} --- Send a signal to a process
8122 @item @emph{Description}:
8123 @item @emph{Standard}:
8124 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
8127 This intrinsic is provided in both subroutine and function forms; however,
8128 only one form can be used in any given program unit.
8131 Subroutine, function
8133 @item @emph{Syntax}:
8134 @multitable @columnfractions .80
8135 @item @code{CALL KILL(C, VALUE [, STATUS])}
8136 @item @code{STATUS = KILL(C, VALUE)}
8139 @item @emph{Arguments}:
8140 @multitable @columnfractions .15 .70
8141 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
8143 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
8145 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
8146 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
8150 @item @emph{See also}:
8151 @ref{ABORT}, @ref{EXIT}
8157 @section @code{KIND} --- Kind of an entity
8162 @item @emph{Description}:
8163 @code{KIND(X)} returns the kind value of the entity @var{X}.
8165 @item @emph{Standard}:
8166 Fortran 95 and later
8171 @item @emph{Syntax}:
8174 @item @emph{Arguments}:
8175 @multitable @columnfractions .15 .70
8176 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
8177 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
8180 @item @emph{Return value}:
8181 The return value is a scalar of type @code{INTEGER} and of the default
8184 @item @emph{Example}:
8187 integer,parameter :: kc = kind(' ')
8188 integer,parameter :: kl = kind(.true.)
8190 print *, "The default character kind is ", kc
8191 print *, "The default logical kind is ", kl
8192 end program test_kind
8200 @section @code{LBOUND} --- Lower dimension bounds of an array
8202 @cindex array, lower bound
8205 @item @emph{Description}:
8206 Returns the lower bounds of an array, or a single lower bound
8207 along the @var{DIM} dimension.
8208 @item @emph{Standard}:
8209 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
8214 @item @emph{Syntax}:
8215 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
8217 @item @emph{Arguments}:
8218 @multitable @columnfractions .15 .70
8219 @item @var{ARRAY} @tab Shall be an array, of any type.
8220 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
8221 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8222 expression indicating the kind parameter of the result.
8225 @item @emph{Return value}:
8226 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8227 @var{KIND} is absent, the return value is of default integer kind.
8228 If @var{DIM} is absent, the result is an array of the lower bounds of
8229 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
8230 corresponding to the lower bound of the array along that dimension. If
8231 @var{ARRAY} is an expression rather than a whole array or array
8232 structure component, or if it has a zero extent along the relevant
8233 dimension, the lower bound is taken to be 1.
8235 @item @emph{See also}:
8236 @ref{UBOUND}, @ref{LCOBOUND}
8242 @section @code{LCOBOUND} --- Lower codimension bounds of an array
8244 @cindex coarray, lower bound
8247 @item @emph{Description}:
8248 Returns the lower bounds of a coarray, or a single lower cobound
8249 along the @var{DIM} codimension.
8250 @item @emph{Standard}:
8251 Fortran 2008 and later
8256 @item @emph{Syntax}:
8257 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
8259 @item @emph{Arguments}:
8260 @multitable @columnfractions .15 .70
8261 @item @var{ARRAY} @tab Shall be an coarray, of any type.
8262 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
8263 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8264 expression indicating the kind parameter of the result.
8267 @item @emph{Return value}:
8268 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8269 @var{KIND} is absent, the return value is of default integer kind.
8270 If @var{DIM} is absent, the result is an array of the lower cobounds of
8271 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
8272 corresponding to the lower cobound of the array along that codimension.
8274 @item @emph{See also}:
8275 @ref{UCOBOUND}, @ref{LBOUND}
8281 @section @code{LEADZ} --- Number of leading zero bits of an integer
8286 @item @emph{Description}:
8287 @code{LEADZ} returns the number of leading zero bits of an integer.
8289 @item @emph{Standard}:
8290 Fortran 2008 and later
8295 @item @emph{Syntax}:
8296 @code{RESULT = LEADZ(I)}
8298 @item @emph{Arguments}:
8299 @multitable @columnfractions .15 .70
8300 @item @var{I} @tab Shall be of type @code{INTEGER}.
8303 @item @emph{Return value}:
8304 The type of the return value is the default @code{INTEGER}.
8305 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
8307 @item @emph{Example}:
8310 WRITE (*,*) BIT_SIZE(1) ! prints 32
8311 WRITE (*,*) LEADZ(1) ! prints 31
8315 @item @emph{See also}:
8316 @ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR}
8322 @section @code{LEN} --- Length of a character entity
8324 @cindex string, length
8327 @item @emph{Description}:
8328 Returns the length of a character string. If @var{STRING} is an array,
8329 the length of an element of @var{STRING} is returned. Note that
8330 @var{STRING} need not be defined when this intrinsic is invoked, since
8331 only the length, not the content, of @var{STRING} is needed.
8333 @item @emph{Standard}:
8334 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
8339 @item @emph{Syntax}:
8340 @code{L = LEN(STRING [, KIND])}
8342 @item @emph{Arguments}:
8343 @multitable @columnfractions .15 .70
8344 @item @var{STRING} @tab Shall be a scalar or array of type
8345 @code{CHARACTER}, with @code{INTENT(IN)}
8346 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8347 expression indicating the kind parameter of the result.
8350 @item @emph{Return value}:
8351 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8352 @var{KIND} is absent, the return value is of default integer kind.
8355 @item @emph{Specific names}:
8356 @multitable @columnfractions .20 .20 .20 .25
8357 @item Name @tab Argument @tab Return type @tab Standard
8358 @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
8362 @item @emph{See also}:
8363 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
8369 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
8371 @cindex string, length, without trailing whitespace
8374 @item @emph{Description}:
8375 Returns the length of a character string, ignoring any trailing blanks.
8377 @item @emph{Standard}:
8378 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
8383 @item @emph{Syntax}:
8384 @code{RESULT = LEN_TRIM(STRING [, KIND])}
8386 @item @emph{Arguments}:
8387 @multitable @columnfractions .15 .70
8388 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
8389 with @code{INTENT(IN)}
8390 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8391 expression indicating the kind parameter of the result.
8394 @item @emph{Return value}:
8395 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8396 @var{KIND} is absent, the return value is of default integer kind.
8398 @item @emph{See also}:
8399 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
8405 @section @code{LGE} --- Lexical greater than or equal
8407 @cindex lexical comparison of strings
8408 @cindex string, comparison
8411 @item @emph{Description}:
8412 Determines whether one string is lexically greater than or equal to
8413 another string, where the two strings are interpreted as containing
8414 ASCII character codes. If the String A and String B are not the same
8415 length, the shorter is compared as if spaces were appended to it to form
8416 a value that has the same length as the longer.
8418 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
8419 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
8420 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
8421 that the latter use the processor's character ordering (which is not
8422 ASCII on some targets), whereas the former always use the ASCII
8425 @item @emph{Standard}:
8426 Fortran 77 and later
8431 @item @emph{Syntax}:
8432 @code{RESULT = LGE(STRING_A, STRING_B)}
8434 @item @emph{Arguments}:
8435 @multitable @columnfractions .15 .70
8436 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
8437 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
8440 @item @emph{Return value}:
8441 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
8442 otherwise, based on the ASCII ordering.
8444 @item @emph{Specific names}:
8445 @multitable @columnfractions .20 .20 .20 .25
8446 @item Name @tab Argument @tab Return type @tab Standard
8447 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
8450 @item @emph{See also}:
8451 @ref{LGT}, @ref{LLE}, @ref{LLT}
8457 @section @code{LGT} --- Lexical greater than
8459 @cindex lexical comparison of strings
8460 @cindex string, comparison
8463 @item @emph{Description}:
8464 Determines whether one string is lexically greater than another string,
8465 where the two strings are interpreted as containing ASCII character
8466 codes. If the String A and String B are not the same length, the
8467 shorter is compared as if spaces were appended to it to form a value
8468 that has the same length as the longer.
8470 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
8471 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
8472 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
8473 that the latter use the processor's character ordering (which is not
8474 ASCII on some targets), whereas the former always use the ASCII
8477 @item @emph{Standard}:
8478 Fortran 77 and later
8483 @item @emph{Syntax}:
8484 @code{RESULT = LGT(STRING_A, STRING_B)}
8486 @item @emph{Arguments}:
8487 @multitable @columnfractions .15 .70
8488 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
8489 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
8492 @item @emph{Return value}:
8493 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
8494 otherwise, based on the ASCII ordering.
8496 @item @emph{Specific names}:
8497 @multitable @columnfractions .20 .20 .20 .25
8498 @item Name @tab Argument @tab Return type @tab Standard
8499 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
8502 @item @emph{See also}:
8503 @ref{LGE}, @ref{LLE}, @ref{LLT}
8509 @section @code{LINK} --- Create a hard link
8511 @cindex file system, create link
8512 @cindex file system, hard link
8515 @item @emph{Description}:
8516 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
8517 character (@code{CHAR(0)}) can be used to mark the end of the names in
8518 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
8519 names are ignored. If the @var{STATUS} argument is supplied, it
8520 contains 0 on success or a nonzero error code upon return; see
8523 This intrinsic is provided in both subroutine and function forms;
8524 however, only one form can be used in any given program unit.
8526 @item @emph{Standard}:
8530 Subroutine, function
8532 @item @emph{Syntax}:
8533 @multitable @columnfractions .80
8534 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
8535 @item @code{STATUS = LINK(PATH1, PATH2)}
8538 @item @emph{Arguments}:
8539 @multitable @columnfractions .15 .70
8540 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
8541 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
8542 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
8545 @item @emph{See also}:
8546 @ref{SYMLNK}, @ref{UNLINK}
8552 @section @code{LLE} --- Lexical less than or equal
8554 @cindex lexical comparison of strings
8555 @cindex string, comparison
8558 @item @emph{Description}:
8559 Determines whether one string is lexically less than or equal to another
8560 string, where the two strings are interpreted as containing ASCII
8561 character codes. If the String A and String B are not the same length,
8562 the shorter is compared as if spaces were appended to it to form a value
8563 that has the same length as the longer.
8565 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
8566 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
8567 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
8568 that the latter use the processor's character ordering (which is not
8569 ASCII on some targets), whereas the former always use the ASCII
8572 @item @emph{Standard}:
8573 Fortran 77 and later
8578 @item @emph{Syntax}:
8579 @code{RESULT = LLE(STRING_A, STRING_B)}
8581 @item @emph{Arguments}:
8582 @multitable @columnfractions .15 .70
8583 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
8584 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
8587 @item @emph{Return value}:
8588 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
8589 otherwise, based on the ASCII ordering.
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{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
8597 @item @emph{See also}:
8598 @ref{LGE}, @ref{LGT}, @ref{LLT}
8604 @section @code{LLT} --- Lexical less than
8606 @cindex lexical comparison of strings
8607 @cindex string, comparison
8610 @item @emph{Description}:
8611 Determines whether one string is lexically less than another string,
8612 where the two strings are interpreted as containing ASCII character
8613 codes. If the String A and String B are not the same length, the
8614 shorter is compared as if spaces were appended to it to form a value
8615 that has the same length as the longer.
8617 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
8618 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
8619 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
8620 that the latter use the processor's character ordering (which is not
8621 ASCII on some targets), whereas the former always use the ASCII
8624 @item @emph{Standard}:
8625 Fortran 77 and later
8630 @item @emph{Syntax}:
8631 @code{RESULT = LLT(STRING_A, STRING_B)}
8633 @item @emph{Arguments}:
8634 @multitable @columnfractions .15 .70
8635 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
8636 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
8639 @item @emph{Return value}:
8640 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
8641 otherwise, based on the ASCII ordering.
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{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
8649 @item @emph{See also}:
8650 @ref{LGE}, @ref{LGT}, @ref{LLE}
8656 @section @code{LNBLNK} --- Index of the last non-blank character in a string
8658 @cindex string, find non-blank character
8661 @item @emph{Description}:
8662 Returns the length of a character string, ignoring any trailing blanks.
8663 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
8664 included for backwards compatibility.
8666 @item @emph{Standard}:
8672 @item @emph{Syntax}:
8673 @code{RESULT = LNBLNK(STRING)}
8675 @item @emph{Arguments}:
8676 @multitable @columnfractions .15 .70
8677 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
8678 with @code{INTENT(IN)}
8681 @item @emph{Return value}:
8682 The return value is of @code{INTEGER(kind=4)} type.
8684 @item @emph{See also}:
8685 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
8691 @section @code{LOC} --- Returns the address of a variable
8693 @cindex location of a variable in memory
8696 @item @emph{Description}:
8697 @code{LOC(X)} returns the address of @var{X} as an integer.
8699 @item @emph{Standard}:
8705 @item @emph{Syntax}:
8706 @code{RESULT = LOC(X)}
8708 @item @emph{Arguments}:
8709 @multitable @columnfractions .15 .70
8710 @item @var{X} @tab Variable of any type.
8713 @item @emph{Return value}:
8714 The return value is of type @code{INTEGER}, with a @code{KIND}
8715 corresponding to the size (in bytes) of a memory address on the target
8718 @item @emph{Example}:
8725 end program test_loc
8732 @section @code{LOG} --- Natural logarithm function
8739 @cindex exponential function, inverse
8740 @cindex logarithm function
8741 @cindex natural logarithm function
8744 @item @emph{Description}:
8745 @code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the
8746 logarithm to the base @math{e}.
8748 @item @emph{Standard}:
8749 Fortran 77 and later
8754 @item @emph{Syntax}:
8755 @code{RESULT = LOG(X)}
8757 @item @emph{Arguments}:
8758 @multitable @columnfractions .15 .70
8759 @item @var{X} @tab The type shall be @code{REAL} or
8763 @item @emph{Return value}:
8764 The return value is of type @code{REAL} or @code{COMPLEX}.
8765 The kind type parameter is the same as @var{X}.
8766 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
8767 @math{-\pi < \omega \leq \pi}.
8769 @item @emph{Example}:
8772 real(8) :: x = 2.7182818284590451_8
8773 complex :: z = (1.0, 2.0)
8774 x = log(x) ! will yield (approximately) 1
8776 end program test_log
8779 @item @emph{Specific names}:
8780 @multitable @columnfractions .20 .20 .20 .25
8781 @item Name @tab Argument @tab Return type @tab Standard
8782 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
8783 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
8784 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
8785 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
8786 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
8793 @section @code{LOG10} --- Base 10 logarithm function
8797 @cindex exponential function, inverse
8798 @cindex logarithm function with base 10
8799 @cindex base 10 logarithm function
8802 @item @emph{Description}:
8803 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
8805 @item @emph{Standard}:
8806 Fortran 77 and later
8811 @item @emph{Syntax}:
8812 @code{RESULT = LOG10(X)}
8814 @item @emph{Arguments}:
8815 @multitable @columnfractions .15 .70
8816 @item @var{X} @tab The type shall be @code{REAL}.
8819 @item @emph{Return value}:
8820 The return value is of type @code{REAL} or @code{COMPLEX}.
8821 The kind type parameter is the same as @var{X}.
8823 @item @emph{Example}:
8826 real(8) :: x = 10.0_8
8828 end program test_log10
8831 @item @emph{Specific names}:
8832 @multitable @columnfractions .20 .20 .20 .25
8833 @item Name @tab Argument @tab Return type @tab Standard
8834 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
8835 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
8842 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
8847 @cindex Gamma function, logarithm of
8850 @item @emph{Description}:
8851 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
8852 of the Gamma (@math{\Gamma}) function.
8854 @item @emph{Standard}:
8855 Fortran 2008 and later
8860 @item @emph{Syntax}:
8861 @code{X = LOG_GAMMA(X)}
8863 @item @emph{Arguments}:
8864 @multitable @columnfractions .15 .70
8865 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
8866 nor a negative integer.
8869 @item @emph{Return value}:
8870 The return value is of type @code{REAL} of the same kind as @var{X}.
8872 @item @emph{Example}:
8874 program test_log_gamma
8876 x = lgamma(x) ! returns 0.0
8877 end program test_log_gamma
8880 @item @emph{Specific names}:
8881 @multitable @columnfractions .20 .20 .20 .25
8882 @item Name @tab Argument @tab Return type @tab Standard
8883 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
8884 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
8885 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
8888 @item @emph{See also}:
8889 Gamma function: @ref{GAMMA}
8896 @section @code{LOGICAL} --- Convert to logical type
8898 @cindex conversion, to logical
8901 @item @emph{Description}:
8902 Converts one kind of @code{LOGICAL} variable to another.
8904 @item @emph{Standard}:
8905 Fortran 95 and later
8910 @item @emph{Syntax}:
8911 @code{RESULT = LOGICAL(L [, KIND])}
8913 @item @emph{Arguments}:
8914 @multitable @columnfractions .15 .70
8915 @item @var{L} @tab The type shall be @code{LOGICAL}.
8916 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8917 expression indicating the kind parameter of the result.
8920 @item @emph{Return value}:
8921 The return value is a @code{LOGICAL} value equal to @var{L}, with a
8922 kind corresponding to @var{KIND}, or of the default logical kind if
8923 @var{KIND} is not given.
8925 @item @emph{See also}:
8926 @ref{INT}, @ref{REAL}, @ref{CMPLX}
8932 @section @code{LONG} --- Convert to integer type
8934 @cindex conversion, to integer
8937 @item @emph{Description}:
8938 Convert to a @code{KIND=4} integer type, which is the same size as a C
8939 @code{long} integer. This is equivalent to the standard @code{INT}
8940 intrinsic with an optional argument of @code{KIND=4}, and is only
8941 included for backwards compatibility.
8943 @item @emph{Standard}:
8949 @item @emph{Syntax}:
8950 @code{RESULT = LONG(A)}
8952 @item @emph{Arguments}:
8953 @multitable @columnfractions .15 .70
8954 @item @var{A} @tab Shall be of type @code{INTEGER},
8955 @code{REAL}, or @code{COMPLEX}.
8958 @item @emph{Return value}:
8959 The return value is a @code{INTEGER(4)} variable.
8961 @item @emph{See also}:
8962 @ref{INT}, @ref{INT2}, @ref{INT8}
8968 @section @code{LSHIFT} --- Left shift bits
8970 @cindex bits, shift left
8973 @item @emph{Description}:
8974 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
8975 bits shifted left by @var{SHIFT} places. If the absolute value of
8976 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
8977 Bits shifted out from the left end are lost; zeros are shifted in from
8980 This function has been superseded by the @code{ISHFT} intrinsic, which
8981 is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
8982 which is standard in Fortran 2008 and later.
8984 @item @emph{Standard}:
8990 @item @emph{Syntax}:
8991 @code{RESULT = LSHIFT(I, SHIFT)}
8993 @item @emph{Arguments}:
8994 @multitable @columnfractions .15 .70
8995 @item @var{I} @tab The type shall be @code{INTEGER}.
8996 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8999 @item @emph{Return value}:
9000 The return value is of type @code{INTEGER} and of the same kind as
9003 @item @emph{See also}:
9004 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}, @ref{SHIFTA}, @ref{SHIFTL},
9012 @section @code{LSTAT} --- Get file status
9014 @cindex file system, file status
9017 @item @emph{Description}:
9018 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
9019 symbolic link, then the link itself is statted, not the file that it
9022 The elements in @code{VALUES} are the same as described by @ref{STAT}.
9024 This intrinsic is provided in both subroutine and function forms;
9025 however, only one form can be used in any given program unit.
9027 @item @emph{Standard}:
9031 Subroutine, function
9033 @item @emph{Syntax}:
9034 @multitable @columnfractions .80
9035 @item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
9036 @item @code{STATUS = LSTAT(NAME, VALUES)}
9039 @item @emph{Arguments}:
9040 @multitable @columnfractions .15 .70
9041 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
9042 kind, a valid path within the file system.
9043 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
9044 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
9045 Returns 0 on success and a system specific error code otherwise.
9048 @item @emph{Example}:
9049 See @ref{STAT} for an example.
9051 @item @emph{See also}:
9052 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
9058 @section @code{LTIME} --- Convert time to local time info
9060 @cindex time, conversion to local time info
9063 @item @emph{Description}:
9064 Given a system time value @var{TIME} (as provided by the @code{TIME8}
9065 intrinsic), fills @var{VALUES} with values extracted from it appropriate
9066 to the local time zone using @code{localtime(3)}.
9068 @item @emph{Standard}:
9074 @item @emph{Syntax}:
9075 @code{CALL LTIME(TIME, VALUES)}
9077 @item @emph{Arguments}:
9078 @multitable @columnfractions .15 .70
9079 @item @var{TIME} @tab An @code{INTEGER} scalar expression
9080 corresponding to a system time, with @code{INTENT(IN)}.
9081 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
9082 with @code{INTENT(OUT)}.
9085 @item @emph{Return value}:
9086 The elements of @var{VALUES} are assigned as follows:
9088 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
9090 @item Minutes after the hour, range 0--59
9091 @item Hours past midnight, range 0--23
9092 @item Day of month, range 0--31
9093 @item Number of months since January, range 0--12
9094 @item Years since 1900
9095 @item Number of days since Sunday, range 0--6
9096 @item Days since January 1
9097 @item Daylight savings indicator: positive if daylight savings is in
9098 effect, zero if not, and negative if the information is not available.
9101 @item @emph{See also}:
9102 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
9109 @section @code{MALLOC} --- Allocate dynamic memory
9111 @cindex pointer, cray
9114 @item @emph{Description}:
9115 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
9116 returns the address of the allocated memory. The @code{MALLOC} intrinsic
9117 is an extension intended to be used with Cray pointers, and is provided
9118 in GNU Fortran to allow the user to compile legacy code. For new code
9119 using Fortran 95 pointers, the memory allocation intrinsic is
9122 @item @emph{Standard}:
9128 @item @emph{Syntax}:
9129 @code{PTR = MALLOC(SIZE)}
9131 @item @emph{Arguments}:
9132 @multitable @columnfractions .15 .70
9133 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
9136 @item @emph{Return value}:
9137 The return value is of type @code{INTEGER(K)}, with @var{K} such that
9138 variables of type @code{INTEGER(K)} have the same size as
9139 C pointers (@code{sizeof(void *)}).
9141 @item @emph{Example}:
9142 The following example demonstrates the use of @code{MALLOC} and
9143 @code{FREE} with Cray pointers.
9152 ptr_x = malloc(20*8)
9154 x(i) = sqrt(1.0d0 / i)
9162 end program test_malloc
9165 @item @emph{See also}:
9172 @section @code{MASKL} --- Left justified mask
9174 @cindex mask, left justified
9177 @item @emph{Description}:
9178 @code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
9179 remaining bits set to 0.
9181 @item @emph{Standard}:
9182 Fortran 2008 and later
9187 @item @emph{Syntax}:
9188 @code{RESULT = MASKL(I[, KIND])}
9190 @item @emph{Arguments}:
9191 @multitable @columnfractions .15 .70
9192 @item @var{I} @tab Shall be of type @code{INTEGER}.
9193 @item @var{KIND} @tab Shall be a scalar constant expression of type
9197 @item @emph{Return value}:
9198 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
9199 specifies the kind value of the return type; otherwise, it is of the
9200 default integer kind.
9202 @item @emph{See also}:
9209 @section @code{MASKR} --- Right justified mask
9211 @cindex mask, right justified
9214 @item @emph{Description}:
9215 @code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
9216 remaining bits set to 0.
9218 @item @emph{Standard}:
9219 Fortran 2008 and later
9224 @item @emph{Syntax}:
9225 @code{RESULT = MASKR(I[, KIND])}
9227 @item @emph{Arguments}:
9228 @multitable @columnfractions .15 .70
9229 @item @var{I} @tab Shall be of type @code{INTEGER}.
9230 @item @var{KIND} @tab Shall be a scalar constant expression of type
9234 @item @emph{Return value}:
9235 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
9236 specifies the kind value of the return type; otherwise, it is of the
9237 default integer kind.
9239 @item @emph{See also}:
9246 @section @code{MATMUL} --- matrix multiplication
9248 @cindex matrix multiplication
9249 @cindex product, matrix
9252 @item @emph{Description}:
9253 Performs a matrix multiplication on numeric or logical arguments.
9255 @item @emph{Standard}:
9256 Fortran 95 and later
9259 Transformational function
9261 @item @emph{Syntax}:
9262 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
9264 @item @emph{Arguments}:
9265 @multitable @columnfractions .15 .70
9266 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
9267 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
9269 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
9270 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
9271 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
9272 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
9273 equal to the last (or only) dimension of @var{MATRIX_A}.
9276 @item @emph{Return value}:
9277 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
9278 kind of the result follow the usual type and kind promotion rules, as
9279 for the @code{*} or @code{.AND.} operators.
9281 @item @emph{See also}:
9287 @section @code{MAX} --- Maximum value of an argument list
9294 @cindex maximum value
9297 @item @emph{Description}:
9298 Returns the argument with the largest (most positive) value.
9300 @item @emph{Standard}:
9301 Fortran 77 and later
9306 @item @emph{Syntax}:
9307 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
9309 @item @emph{Arguments}:
9310 @multitable @columnfractions .15 .70
9311 @item @var{A1} @tab The type shall be @code{INTEGER} or
9313 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
9314 as @var{A1}. (As a GNU extension, arguments of different kinds are
9318 @item @emph{Return value}:
9319 The return value corresponds to the maximum value among the arguments,
9320 and has the same type and kind as the first argument.
9322 @item @emph{Specific names}:
9323 @multitable @columnfractions .20 .20 .20 .25
9324 @item Name @tab Argument @tab Return type @tab Standard
9325 @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
9326 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
9327 @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
9328 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
9329 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
9332 @item @emph{See also}:
9333 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
9340 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
9341 @fnindex MAXEXPONENT
9342 @cindex model representation, maximum exponent
9345 @item @emph{Description}:
9346 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
9349 @item @emph{Standard}:
9350 Fortran 95 and later
9355 @item @emph{Syntax}:
9356 @code{RESULT = MAXEXPONENT(X)}
9358 @item @emph{Arguments}:
9359 @multitable @columnfractions .15 .70
9360 @item @var{X} @tab Shall be of type @code{REAL}.
9363 @item @emph{Return value}:
9364 The return value is of type @code{INTEGER} and of the default integer
9367 @item @emph{Example}:
9373 print *, minexponent(x), maxexponent(x)
9374 print *, minexponent(y), maxexponent(y)
9375 end program exponents
9382 @section @code{MAXLOC} --- Location of the maximum value within an array
9384 @cindex array, location of maximum element
9387 @item @emph{Description}:
9388 Determines the location of the element in the array with the maximum
9389 value, or, if the @var{DIM} argument is supplied, determines the
9390 locations of the maximum element along each row of the array in the
9391 @var{DIM} direction. If @var{MASK} is present, only the elements for
9392 which @var{MASK} is @code{.TRUE.} are considered. If more than one
9393 element in the array has the maximum value, the location returned is
9394 that of the first such element in array element order. If the array has
9395 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
9396 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
9397 and all of the elements of @var{MASK} along a given row are zero, the
9398 result value for that row is zero.
9400 @item @emph{Standard}:
9401 Fortran 95 and later
9404 Transformational function
9406 @item @emph{Syntax}:
9407 @multitable @columnfractions .80
9408 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
9409 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
9412 @item @emph{Arguments}:
9413 @multitable @columnfractions .15 .70
9414 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
9416 @item @var{DIM} @tab (Optional) Shall be a scalar of type
9417 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
9418 inclusive. It may not be an optional dummy argument.
9419 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
9420 and conformable with @var{ARRAY}.
9423 @item @emph{Return value}:
9424 If @var{DIM} is absent, the result is a rank-one array with a length
9425 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
9426 is an array with a rank one less than the rank of @var{ARRAY}, and a
9427 size corresponding to the size of @var{ARRAY} with the @var{DIM}
9428 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
9429 of one, the result is a scalar. In all cases, the result is of default
9430 @code{INTEGER} type.
9432 @item @emph{See also}:
9433 @ref{MAX}, @ref{MAXVAL}
9440 @section @code{MAXVAL} --- Maximum value of an array
9442 @cindex array, maximum value
9443 @cindex maximum value
9446 @item @emph{Description}:
9447 Determines the maximum value of the elements in an array value, or, if
9448 the @var{DIM} argument is supplied, determines the maximum value along
9449 each row of the array in the @var{DIM} direction. If @var{MASK} is
9450 present, only the elements for which @var{MASK} is @code{.TRUE.} are
9451 considered. If the array has zero size, or all of the elements of
9452 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
9453 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
9456 @item @emph{Standard}:
9457 Fortran 95 and later
9460 Transformational function
9462 @item @emph{Syntax}:
9463 @multitable @columnfractions .80
9464 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
9465 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
9468 @item @emph{Arguments}:
9469 @multitable @columnfractions .15 .70
9470 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
9472 @item @var{DIM} @tab (Optional) Shall be a scalar of type
9473 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
9474 inclusive. It may not be an optional dummy argument.
9475 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
9476 and conformable with @var{ARRAY}.
9479 @item @emph{Return value}:
9480 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
9481 is a scalar. If @var{DIM} is present, the result is an array with a
9482 rank one less than the rank of @var{ARRAY}, and a size corresponding to
9483 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
9484 cases, the result is of the same type and kind as @var{ARRAY}.
9486 @item @emph{See also}:
9487 @ref{MAX}, @ref{MAXLOC}
9493 @section @code{MCLOCK} --- Time function
9495 @cindex time, clock ticks
9499 @item @emph{Description}:
9500 Returns the number of clock ticks since the start of the process, based
9501 on the function @code{clock(3)} in the C standard library.
9503 This intrinsic is not fully portable, such as to systems with 32-bit
9504 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
9505 the values returned by this intrinsic might be, or become, negative, or
9506 numerically less than previous values, during a single run of the
9509 @item @emph{Standard}:
9515 @item @emph{Syntax}:
9516 @code{RESULT = MCLOCK()}
9518 @item @emph{Return value}:
9519 The return value is a scalar of type @code{INTEGER(4)}, equal to the
9520 number of clock ticks since the start of the process, or @code{-1} if
9521 the system does not support @code{clock(3)}.
9523 @item @emph{See also}:
9524 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
9531 @section @code{MCLOCK8} --- Time function (64-bit)
9533 @cindex time, clock ticks
9537 @item @emph{Description}:
9538 Returns the number of clock ticks since the start of the process, based
9539 on the function @code{clock(3)} in the C standard library.
9541 @emph{Warning:} this intrinsic does not increase the range of the timing
9542 values over that returned by @code{clock(3)}. On a system with a 32-bit
9543 @code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though
9544 it is converted to a 64-bit @code{INTEGER(8)} value. That means
9545 overflows of the 32-bit value can still occur. Therefore, the values
9546 returned by this intrinsic might be or become negative or numerically
9547 less than previous values during a single run of the compiled program.
9549 @item @emph{Standard}:
9555 @item @emph{Syntax}:
9556 @code{RESULT = MCLOCK8()}
9558 @item @emph{Return value}:
9559 The return value is a scalar of type @code{INTEGER(8)}, equal to the
9560 number of clock ticks since the start of the process, or @code{-1} if
9561 the system does not support @code{clock(3)}.
9563 @item @emph{See also}:
9564 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
9571 @section @code{MERGE} --- Merge variables
9573 @cindex array, merge arrays
9574 @cindex array, combine arrays
9577 @item @emph{Description}:
9578 Select values from two arrays according to a logical mask. The result
9579 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
9580 @var{FSOURCE} if it is @code{.FALSE.}.
9582 @item @emph{Standard}:
9583 Fortran 95 and later
9588 @item @emph{Syntax}:
9589 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
9591 @item @emph{Arguments}:
9592 @multitable @columnfractions .15 .70
9593 @item @var{TSOURCE} @tab May be of any type.
9594 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
9596 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
9599 @item @emph{Return value}:
9600 The result is of the same type and type parameters as @var{TSOURCE}.
9607 @section @code{MERGE_BITS} --- Merge of bits under mask
9612 @item @emph{Description}:
9613 @code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
9614 as determined by the mask. The i-th bit of the result is equal to the
9615 i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
9616 the i-th bit of @var{J} otherwise.
9618 @item @emph{Standard}:
9619 Fortran 2008 and later
9624 @item @emph{Syntax}:
9625 @code{RESULT = MERGE_BITS(I, J, MASK)}
9627 @item @emph{Arguments}:
9628 @multitable @columnfractions .15 .70
9629 @item @var{I} @tab Shall be of type @code{INTEGER}.
9630 @item @var{J} @tab Shall be of type @code{INTEGER} and of the same
9632 @item @var{MASK} @tab Shall be of type @code{INTEGER} and of the same
9636 @item @emph{Return value}:
9637 The result is of the same type and kind as @var{I}.
9644 @section @code{MIN} --- Minimum value of an argument list
9651 @cindex minimum value
9654 @item @emph{Description}:
9655 Returns the argument with the smallest (most negative) value.
9657 @item @emph{Standard}:
9658 Fortran 77 and later
9663 @item @emph{Syntax}:
9664 @code{RESULT = MIN(A1, A2 [, A3, ...])}
9666 @item @emph{Arguments}:
9667 @multitable @columnfractions .15 .70
9668 @item @var{A1} @tab The type shall be @code{INTEGER} or
9670 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
9671 as @var{A1}. (As a GNU extension, arguments of different kinds are
9675 @item @emph{Return value}:
9676 The return value corresponds to the maximum value among the arguments,
9677 and has the same type and kind as the first argument.
9679 @item @emph{Specific names}:
9680 @multitable @columnfractions .20 .20 .20 .25
9681 @item Name @tab Argument @tab Return type @tab Standard
9682 @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
9683 @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
9684 @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
9685 @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
9686 @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
9689 @item @emph{See also}:
9690 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
9696 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
9697 @fnindex MINEXPONENT
9698 @cindex model representation, minimum exponent
9701 @item @emph{Description}:
9702 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
9705 @item @emph{Standard}:
9706 Fortran 95 and later
9711 @item @emph{Syntax}:
9712 @code{RESULT = MINEXPONENT(X)}
9714 @item @emph{Arguments}:
9715 @multitable @columnfractions .15 .70
9716 @item @var{X} @tab Shall be of type @code{REAL}.
9719 @item @emph{Return value}:
9720 The return value is of type @code{INTEGER} and of the default integer
9723 @item @emph{Example}:
9724 See @code{MAXEXPONENT} for an example.
9730 @section @code{MINLOC} --- Location of the minimum value within an array
9732 @cindex array, location of minimum element
9735 @item @emph{Description}:
9736 Determines the location of the element in the array with the minimum
9737 value, or, if the @var{DIM} argument is supplied, determines the
9738 locations of the minimum element along each row of the array in the
9739 @var{DIM} direction. If @var{MASK} is present, only the elements for
9740 which @var{MASK} is @code{.TRUE.} are considered. If more than one
9741 element in the array has the minimum value, the location returned is
9742 that of the first such element in array element order. If the array has
9743 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
9744 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
9745 and all of the elements of @var{MASK} along a given row are zero, the
9746 result value for that row is zero.
9748 @item @emph{Standard}:
9749 Fortran 95 and later
9752 Transformational function
9754 @item @emph{Syntax}:
9755 @multitable @columnfractions .80
9756 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
9757 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
9760 @item @emph{Arguments}:
9761 @multitable @columnfractions .15 .70
9762 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
9764 @item @var{DIM} @tab (Optional) Shall be a scalar of type
9765 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
9766 inclusive. It may not be an optional dummy argument.
9767 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
9768 and conformable with @var{ARRAY}.
9771 @item @emph{Return value}:
9772 If @var{DIM} is absent, the result is a rank-one array with a length
9773 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
9774 is an array with a rank one less than the rank of @var{ARRAY}, and a
9775 size corresponding to the size of @var{ARRAY} with the @var{DIM}
9776 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
9777 of one, the result is a scalar. In all cases, the result is of default
9778 @code{INTEGER} type.
9780 @item @emph{See also}:
9781 @ref{MIN}, @ref{MINVAL}
9788 @section @code{MINVAL} --- Minimum value of an array
9790 @cindex array, minimum value
9791 @cindex minimum value
9794 @item @emph{Description}:
9795 Determines the minimum value of the elements in an array value, or, if
9796 the @var{DIM} argument is supplied, determines the minimum value along
9797 each row of the array in the @var{DIM} direction. If @var{MASK} is
9798 present, only the elements for which @var{MASK} is @code{.TRUE.} are
9799 considered. If the array has zero size, or all of the elements of
9800 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
9801 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
9802 @var{ARRAY} is of character type.
9804 @item @emph{Standard}:
9805 Fortran 95 and later
9808 Transformational function
9810 @item @emph{Syntax}:
9811 @multitable @columnfractions .80
9812 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
9813 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
9816 @item @emph{Arguments}:
9817 @multitable @columnfractions .15 .70
9818 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
9820 @item @var{DIM} @tab (Optional) Shall be a scalar of type
9821 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
9822 inclusive. It may not be an optional dummy argument.
9823 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
9824 and conformable with @var{ARRAY}.
9827 @item @emph{Return value}:
9828 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
9829 is a scalar. If @var{DIM} is present, the result is an array with a
9830 rank one less than the rank of @var{ARRAY}, and a size corresponding to
9831 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
9832 cases, the result is of the same type and kind as @var{ARRAY}.
9834 @item @emph{See also}:
9835 @ref{MIN}, @ref{MINLOC}
9842 @section @code{MOD} --- Remainder function
9847 @cindex division, remainder
9850 @item @emph{Description}:
9851 @code{MOD(A,P)} computes the remainder of the division of A by P@.
9853 @item @emph{Standard}:
9854 Fortran 77 and later
9859 @item @emph{Syntax}:
9860 @code{RESULT = MOD(A, P)}
9862 @item @emph{Arguments}:
9863 @multitable @columnfractions .15 .70
9864 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
9865 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
9866 and not equal to zero.
9869 @item @emph{Return value}:
9870 The return value is the result of @code{A - (INT(A/P) * P)}. The type
9871 and kind of the return value is the same as that of the arguments. The
9872 returned value has the same sign as A and a magnitude less than the
9875 @item @emph{Example}:
9879 print *, mod(17.5,5.5)
9880 print *, mod(17.5d0,5.5)
9881 print *, mod(17.5,5.5d0)
9884 print *, mod(-17.5,5.5)
9885 print *, mod(-17.5d0,5.5)
9886 print *, mod(-17.5,5.5d0)
9889 print *, mod(17.5,-5.5)
9890 print *, mod(17.5d0,-5.5)
9891 print *, mod(17.5,-5.5d0)
9892 end program test_mod
9895 @item @emph{Specific names}:
9896 @multitable @columnfractions .20 .20 .20 .25
9897 @item Name @tab Arguments @tab Return type @tab Standard
9898 @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
9899 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
9900 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
9903 @item @emph{See also}:
9911 @section @code{MODULO} --- Modulo function
9914 @cindex division, modulo
9917 @item @emph{Description}:
9918 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
9920 @item @emph{Standard}:
9921 Fortran 95 and later
9926 @item @emph{Syntax}:
9927 @code{RESULT = MODULO(A, P)}
9929 @item @emph{Arguments}:
9930 @multitable @columnfractions .15 .70
9931 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
9932 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}.
9933 It shall not be zero.
9936 @item @emph{Return value}:
9937 The type and kind of the result are those of the arguments.
9939 @item If @var{A} and @var{P} are of type @code{INTEGER}:
9940 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
9941 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
9943 @item If @var{A} and @var{P} are of type @code{REAL}:
9944 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
9946 The returned value has the same sign as P and a magnitude less than
9949 @item @emph{Example}:
9952 print *, modulo(17,3)
9953 print *, modulo(17.5,5.5)
9955 print *, modulo(-17,3)
9956 print *, modulo(-17.5,5.5)
9958 print *, modulo(17,-3)
9959 print *, modulo(17.5,-5.5)
9963 @item @emph{See also}:
9971 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
9973 @cindex moving allocation
9974 @cindex allocation, moving
9977 @item @emph{Description}:
9978 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
9979 @var{TO}. @var{FROM} will become deallocated in the process.
9981 @item @emph{Standard}:
9982 Fortran 2003 and later
9987 @item @emph{Syntax}:
9988 @code{CALL MOVE_ALLOC(FROM, TO)}
9990 @item @emph{Arguments}:
9991 @multitable @columnfractions .15 .70
9992 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
9993 of any type and kind.
9994 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
9995 of the same type, kind and rank as @var{FROM}.
9998 @item @emph{Return value}:
10001 @item @emph{Example}:
10003 program test_move_alloc
10004 integer, allocatable :: a(:), b(:)
10008 call move_alloc(a, b)
10009 print *, allocated(a), allocated(b)
10011 end program test_move_alloc
10018 @section @code{MVBITS} --- Move bits from one integer to another
10023 @item @emph{Description}:
10024 Moves @var{LEN} bits from positions @var{FROMPOS} through
10025 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
10026 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
10027 affected by the movement of bits is unchanged. The values of
10028 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
10029 @code{BIT_SIZE(FROM)}.
10031 @item @emph{Standard}:
10032 Fortran 95 and later
10034 @item @emph{Class}:
10035 Elemental subroutine
10037 @item @emph{Syntax}:
10038 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
10040 @item @emph{Arguments}:
10041 @multitable @columnfractions .15 .70
10042 @item @var{FROM} @tab The type shall be @code{INTEGER}.
10043 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
10044 @item @var{LEN} @tab The type shall be @code{INTEGER}.
10045 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
10046 same kind as @var{FROM}.
10047 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
10050 @item @emph{See also}:
10051 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
10057 @section @code{NEAREST} --- Nearest representable number
10059 @cindex real number, nearest different
10060 @cindex floating point, nearest different
10063 @item @emph{Description}:
10064 @code{NEAREST(X, S)} returns the processor-representable number nearest
10065 to @code{X} in the direction indicated by the sign of @code{S}.
10067 @item @emph{Standard}:
10068 Fortran 95 and later
10070 @item @emph{Class}:
10073 @item @emph{Syntax}:
10074 @code{RESULT = NEAREST(X, S)}
10076 @item @emph{Arguments}:
10077 @multitable @columnfractions .15 .70
10078 @item @var{X} @tab Shall be of type @code{REAL}.
10079 @item @var{S} @tab Shall be of type @code{REAL} and
10083 @item @emph{Return value}:
10084 The return value is of the same type as @code{X}. If @code{S} is
10085 positive, @code{NEAREST} returns the processor-representable number
10086 greater than @code{X} and nearest to it. If @code{S} is negative,
10087 @code{NEAREST} returns the processor-representable number smaller than
10088 @code{X} and nearest to it.
10090 @item @emph{Example}:
10092 program test_nearest
10094 x = nearest(42.0, 1.0)
10095 y = nearest(42.0, -1.0)
10096 write (*,"(3(G20.15))") x, y, x - y
10097 end program test_nearest
10104 @section @code{NEW_LINE} --- New line character
10107 @cindex output, newline
10110 @item @emph{Description}:
10111 @code{NEW_LINE(C)} returns the new-line character.
10113 @item @emph{Standard}:
10114 Fortran 2003 and later
10116 @item @emph{Class}:
10119 @item @emph{Syntax}:
10120 @code{RESULT = NEW_LINE(C)}
10122 @item @emph{Arguments}:
10123 @multitable @columnfractions .15 .70
10124 @item @var{C} @tab The argument shall be a scalar or array of the
10125 type @code{CHARACTER}.
10128 @item @emph{Return value}:
10129 Returns a @var{CHARACTER} scalar of length one with the new-line character of
10130 the same kind as parameter @var{C}.
10132 @item @emph{Example}:
10136 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
10137 end program newline
10144 @section @code{NINT} --- Nearest whole number
10147 @cindex rounding, nearest whole number
10150 @item @emph{Description}:
10151 @code{NINT(A)} rounds its argument to the nearest whole number.
10153 @item @emph{Standard}:
10154 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
10156 @item @emph{Class}:
10159 @item @emph{Syntax}:
10160 @code{RESULT = NINT(A [, KIND])}
10162 @item @emph{Arguments}:
10163 @multitable @columnfractions .15 .70
10164 @item @var{A} @tab The type of the argument shall be @code{REAL}.
10165 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10166 expression indicating the kind parameter of the result.
10169 @item @emph{Return value}:
10170 Returns @var{A} with the fractional portion of its magnitude eliminated by
10171 rounding to the nearest whole number and with its sign preserved,
10172 converted to an @code{INTEGER} of the default kind.
10174 @item @emph{Example}:
10181 print *, nint(x4), idnint(x8)
10182 end program test_nint
10185 @item @emph{Specific names}:
10186 @multitable @columnfractions .20 .20 .20 .25
10187 @item Name @tab Argument @tab Return Type @tab Standard
10188 @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later
10189 @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later
10192 @item @emph{See also}:
10193 @ref{CEILING}, @ref{FLOOR}
10200 @section @code{NORM2} --- Euclidean vector norms
10202 @cindex Euclidean vector norm
10203 @cindex L2 vector norm
10204 @cindex norm, Euclidean
10207 @item @emph{Description}:
10208 Calculates the Euclidean vector norm (@math{L_2} norm) of
10209 of @var{ARRAY} along dimension @var{DIM}.
10211 @item @emph{Standard}:
10212 Fortran 2008 and later
10214 @item @emph{Class}:
10215 Transformational function
10217 @item @emph{Syntax}:
10218 @multitable @columnfractions .80
10219 @item @code{RESULT = NORM2(ARRAY[, DIM])}
10222 @item @emph{Arguments}:
10223 @multitable @columnfractions .15 .70
10224 @item @var{ARRAY} @tab Shall be an array of type @code{REAL}
10225 @item @var{DIM} @tab (Optional) shall be a scalar of type
10226 @code{INTEGER} with a value in the range from 1 to n, where n
10227 equals the rank of @var{ARRAY}.
10230 @item @emph{Return value}:
10231 The result is of the same type as @var{ARRAY}.
10233 If @var{DIM} is absent, a scalar with the square root of the sum of all
10234 elements in @var{ARRAY} squared is returned. Otherwise, an array of
10235 rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
10236 shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
10239 @item @emph{Example}:
10242 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
10243 print *, NORM2(x) ! = sqrt(55.) ~ 7.416
10251 @section @code{NOT} --- Logical negation
10253 @cindex bits, negate
10254 @cindex bitwise logical not
10255 @cindex logical not, bitwise
10258 @item @emph{Description}:
10259 @code{NOT} returns the bitwise Boolean inverse of @var{I}.
10261 @item @emph{Standard}:
10262 Fortran 95 and later
10264 @item @emph{Class}:
10267 @item @emph{Syntax}:
10268 @code{RESULT = NOT(I)}
10270 @item @emph{Arguments}:
10271 @multitable @columnfractions .15 .70
10272 @item @var{I} @tab The type shall be @code{INTEGER}.
10275 @item @emph{Return value}:
10276 The return type is @code{INTEGER}, of the same kind as the
10279 @item @emph{See also}:
10280 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
10287 @section @code{NULL} --- Function that returns an disassociated pointer
10289 @cindex pointer, status
10290 @cindex pointer, disassociated
10293 @item @emph{Description}:
10294 Returns a disassociated pointer.
10296 If @var{MOLD} is present, a disassociated pointer of the same type is
10297 returned, otherwise the type is determined by context.
10299 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
10300 includes cases where it is required.
10302 @item @emph{Standard}:
10303 Fortran 95 and later
10305 @item @emph{Class}:
10306 Transformational function
10308 @item @emph{Syntax}:
10309 @code{PTR => NULL([MOLD])}
10311 @item @emph{Arguments}:
10312 @multitable @columnfractions .15 .70
10313 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
10314 status and of any type.
10317 @item @emph{Return value}:
10318 A disassociated pointer.
10320 @item @emph{Example}:
10322 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
10325 @item @emph{See also}:
10332 @section @code{NUM_IMAGES} --- Function that returns the number of images
10333 @fnindex NUM_IMAGES
10334 @cindex coarray, @code{NUM_IMAGES}
10335 @cindex images, number of
10338 @item @emph{Description}:
10339 Returns the number of images.
10341 @item @emph{Standard}:
10342 Fortran 2008 and later. With @var{DISTANCE} or @var{FAILED} argument,
10343 Technical Specification (TS) 18508 or later
10346 @item @emph{Class}:
10347 Transformational function
10349 @item @emph{Syntax}:
10350 @code{RESULT = NUM_IMAGES(DISTANCE, FAILED)}
10352 @item @emph{Arguments}:
10353 @multitable @columnfractions .15 .70
10354 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
10355 @item @var{FAILED} @tab (optional, intent(in)) Scalar logical expression
10358 @item @emph{Return value}:
10359 Scalar default-kind integer. If @var{DISTANCE} is not present or has value 0,
10360 the number of images in the current team is returned. For values smaller or
10361 equal distance to the initial team, it returns the number of images index
10362 on the ancestor team which has a distance of @var{DISTANCE} from the invoking
10363 team. If @var{DISTANCE} is larger than the distance to the initial team, the
10364 number of images of the initial team is returned. If @var{FAILED} is not present
10365 the total number of images is returned; if it has the value @code{.TRUE.},
10366 the number of failed images is returned, otherwise, the number of images which
10367 do have not the failed status.
10369 @item @emph{Example}:
10371 INTEGER :: value[*]
10373 value = THIS_IMAGE()
10375 IF (THIS_IMAGE() == 1) THEN
10376 DO i = 1, NUM_IMAGES()
10377 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
10382 @item @emph{See also}:
10383 @ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
10389 @section @code{OR} --- Bitwise logical OR
10391 @cindex bitwise logical or
10392 @cindex logical or, bitwise
10395 @item @emph{Description}:
10396 Bitwise logical @code{OR}.
10398 This intrinsic routine is provided for backwards compatibility with
10399 GNU Fortran 77. For integer arguments, programmers should consider
10400 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
10402 @item @emph{Standard}:
10405 @item @emph{Class}:
10408 @item @emph{Syntax}:
10409 @code{RESULT = OR(I, J)}
10411 @item @emph{Arguments}:
10412 @multitable @columnfractions .15 .70
10413 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
10414 type or a scalar @code{LOGICAL} type.
10415 @item @var{J} @tab The type shall be the same as the type of @var{J}.
10418 @item @emph{Return value}:
10419 The return type is either a scalar @code{INTEGER} or a scalar
10420 @code{LOGICAL}. If the kind type parameters differ, then the
10421 smaller kind type is implicitly converted to larger kind, and the
10422 return has the larger kind.
10424 @item @emph{Example}:
10427 LOGICAL :: T = .TRUE., F = .FALSE.
10429 DATA a / Z'F' /, b / Z'3' /
10431 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
10432 WRITE (*,*) OR(a, b)
10436 @item @emph{See also}:
10437 Fortran 95 elemental function: @ref{IOR}
10443 @section @code{PACK} --- Pack an array into an array of rank one
10445 @cindex array, packing
10446 @cindex array, reduce dimension
10447 @cindex array, gather elements
10450 @item @emph{Description}:
10451 Stores the elements of @var{ARRAY} in an array of rank one.
10453 The beginning of the resulting array is made up of elements whose @var{MASK}
10454 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
10457 @item @emph{Standard}:
10458 Fortran 95 and later
10460 @item @emph{Class}:
10461 Transformational function
10463 @item @emph{Syntax}:
10464 @code{RESULT = PACK(ARRAY, MASK[,VECTOR])}
10466 @item @emph{Arguments}:
10467 @multitable @columnfractions .15 .70
10468 @item @var{ARRAY} @tab Shall be an array of any type.
10469 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
10470 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
10472 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
10473 as @var{ARRAY} and of rank one. If present, the number of elements in
10474 @var{VECTOR} shall be equal to or greater than the number of true elements
10475 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
10476 @var{VECTOR} shall be equal to or greater than the number of elements in
10480 @item @emph{Return value}:
10481 The result is an array of rank one and the same type as that of @var{ARRAY}.
10482 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
10483 number of @code{TRUE} values in @var{MASK} otherwise.
10485 @item @emph{Example}:
10486 Gathering nonzero elements from an array:
10488 PROGRAM test_pack_1
10490 m = (/ 1, 0, 0, 0, 5, 0 /)
10491 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
10495 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
10497 PROGRAM test_pack_2
10499 m = (/ 1, 0, 0, 2 /)
10500 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
10504 @item @emph{See also}:
10511 @section @code{PARITY} --- Reduction with exclusive OR
10514 @cindex Reduction, XOR
10515 @cindex XOR reduction
10518 @item @emph{Description}:
10519 Calculates the parity, i.e. the reduction using @code{.XOR.},
10520 of @var{MASK} along dimension @var{DIM}.
10522 @item @emph{Standard}:
10523 Fortran 2008 and later
10525 @item @emph{Class}:
10526 Transformational function
10528 @item @emph{Syntax}:
10529 @multitable @columnfractions .80
10530 @item @code{RESULT = PARITY(MASK[, DIM])}
10533 @item @emph{Arguments}:
10534 @multitable @columnfractions .15 .70
10535 @item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL}
10536 @item @var{DIM} @tab (Optional) shall be a scalar of type
10537 @code{INTEGER} with a value in the range from 1 to n, where n
10538 equals the rank of @var{MASK}.
10541 @item @emph{Return value}:
10542 The result is of the same type as @var{MASK}.
10544 If @var{DIM} is absent, a scalar with the parity of all elements in
10545 @var{MASK} is returned, i.e. true if an odd number of elements is
10546 @code{.true.} and false otherwise. If @var{DIM} is present, an array
10547 of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
10548 and a shape similar to that of @var{MASK} with dimension @var{DIM}
10549 dropped is returned.
10551 @item @emph{Example}:
10554 LOGICAL :: x(2) = [ .true., .false. ]
10555 print *, PARITY(x) ! prints "T" (true).
10563 @section @code{PERROR} --- Print system error message
10565 @cindex system, error handling
10568 @item @emph{Description}:
10569 Prints (on the C @code{stderr} stream) a newline-terminated error
10570 message corresponding to the last system error. This is prefixed by
10571 @var{STRING}, a colon and a space. See @code{perror(3)}.
10573 @item @emph{Standard}:
10576 @item @emph{Class}:
10579 @item @emph{Syntax}:
10580 @code{CALL PERROR(STRING)}
10582 @item @emph{Arguments}:
10583 @multitable @columnfractions .15 .70
10584 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
10588 @item @emph{See also}:
10595 @section @code{POPCNT} --- Number of bits set
10597 @cindex binary representation
10601 @item @emph{Description}:
10602 @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
10603 representation of @code{I}.
10605 @item @emph{Standard}:
10606 Fortran 2008 and later
10608 @item @emph{Class}:
10611 @item @emph{Syntax}:
10612 @code{RESULT = POPCNT(I)}
10614 @item @emph{Arguments}:
10615 @multitable @columnfractions .15 .70
10616 @item @var{I} @tab Shall be of type @code{INTEGER}.
10619 @item @emph{Return value}:
10620 The return value is of type @code{INTEGER} and of the default integer
10623 @item @emph{See also}:
10624 @ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ}
10626 @item @emph{Example}:
10628 program test_population
10629 print *, popcnt(127), poppar(127)
10630 print *, popcnt(huge(0_4)), poppar(huge(0_4))
10631 print *, popcnt(huge(0_8)), poppar(huge(0_8))
10632 end program test_population
10638 @section @code{POPPAR} --- Parity of the number of bits set
10640 @cindex binary representation
10644 @item @emph{Description}:
10645 @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
10646 of the number of bits set ('1' bits) in the binary representation of
10647 @code{I}. It is equal to 0 if @code{I} has an even number of bits set,
10648 and 1 for an odd number of '1' bits.
10650 @item @emph{Standard}:
10651 Fortran 2008 and later
10653 @item @emph{Class}:
10656 @item @emph{Syntax}:
10657 @code{RESULT = POPPAR(I)}
10659 @item @emph{Arguments}:
10660 @multitable @columnfractions .15 .70
10661 @item @var{I} @tab Shall be of type @code{INTEGER}.
10664 @item @emph{Return value}:
10665 The return value is of type @code{INTEGER} and of the default integer
10668 @item @emph{See also}:
10669 @ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ}
10671 @item @emph{Example}:
10673 program test_population
10674 print *, popcnt(127), poppar(127)
10675 print *, popcnt(huge(0_4)), poppar(huge(0_4))
10676 print *, popcnt(huge(0_8)), poppar(huge(0_8))
10677 end program test_population
10684 @section @code{PRECISION} --- Decimal precision of a real kind
10686 @cindex model representation, precision
10689 @item @emph{Description}:
10690 @code{PRECISION(X)} returns the decimal precision in the model of the
10693 @item @emph{Standard}:
10694 Fortran 95 and later
10696 @item @emph{Class}:
10699 @item @emph{Syntax}:
10700 @code{RESULT = PRECISION(X)}
10702 @item @emph{Arguments}:
10703 @multitable @columnfractions .15 .70
10704 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
10707 @item @emph{Return value}:
10708 The return value is of type @code{INTEGER} and of the default integer
10711 @item @emph{See also}:
10712 @ref{SELECTED_REAL_KIND}, @ref{RANGE}
10714 @item @emph{Example}:
10716 program prec_and_range
10717 real(kind=4) :: x(2)
10718 complex(kind=8) :: y
10720 print *, precision(x), range(x)
10721 print *, precision(y), range(y)
10722 end program prec_and_range
10729 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
10733 @item @emph{Description}:
10734 Determines whether an optional dummy argument is present.
10736 @item @emph{Standard}:
10737 Fortran 95 and later
10739 @item @emph{Class}:
10742 @item @emph{Syntax}:
10743 @code{RESULT = PRESENT(A)}
10745 @item @emph{Arguments}:
10746 @multitable @columnfractions .15 .70
10747 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
10748 value, or a dummy procedure. It shall be the name of an optional dummy argument
10749 accessible within the current subroutine or function.
10752 @item @emph{Return value}:
10753 Returns either @code{TRUE} if the optional argument @var{A} is present, or
10754 @code{FALSE} otherwise.
10756 @item @emph{Example}:
10758 PROGRAM test_present
10759 WRITE(*,*) f(), f(42) ! "F T"
10761 LOGICAL FUNCTION f(x)
10762 INTEGER, INTENT(IN), OPTIONAL :: x
10772 @section @code{PRODUCT} --- Product of array elements
10774 @cindex array, product
10775 @cindex array, multiply elements
10776 @cindex array, conditionally multiply elements
10777 @cindex multiply array elements
10780 @item @emph{Description}:
10781 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
10782 the corresponding element in @var{MASK} is @code{TRUE}.
10784 @item @emph{Standard}:
10785 Fortran 95 and later
10787 @item @emph{Class}:
10788 Transformational function
10790 @item @emph{Syntax}:
10791 @multitable @columnfractions .80
10792 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
10793 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
10796 @item @emph{Arguments}:
10797 @multitable @columnfractions .15 .70
10798 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
10799 @code{REAL} or @code{COMPLEX}.
10800 @item @var{DIM} @tab (Optional) shall be a scalar of type
10801 @code{INTEGER} with a value in the range from 1 to n, where n
10802 equals the rank of @var{ARRAY}.
10803 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
10804 and either be a scalar or an array of the same shape as @var{ARRAY}.
10807 @item @emph{Return value}:
10808 The result is of the same type as @var{ARRAY}.
10810 If @var{DIM} is absent, a scalar with the product of all elements in
10811 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
10812 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
10813 dimension @var{DIM} dropped is returned.
10816 @item @emph{Example}:
10818 PROGRAM test_product
10819 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
10820 print *, PRODUCT(x) ! all elements, product = 120
10821 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
10825 @item @emph{See also}:
10832 @section @code{RADIX} --- Base of a model number
10834 @cindex model representation, base
10835 @cindex model representation, radix
10838 @item @emph{Description}:
10839 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
10841 @item @emph{Standard}:
10842 Fortran 95 and later
10844 @item @emph{Class}:
10847 @item @emph{Syntax}:
10848 @code{RESULT = RADIX(X)}
10850 @item @emph{Arguments}:
10851 @multitable @columnfractions .15 .70
10852 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
10855 @item @emph{Return value}:
10856 The return value is a scalar of type @code{INTEGER} and of the default
10859 @item @emph{See also}:
10860 @ref{SELECTED_REAL_KIND}
10862 @item @emph{Example}:
10865 print *, "The radix for the default integer kind is", radix(0)
10866 print *, "The radix for the default real kind is", radix(0.0)
10867 end program test_radix
10875 @section @code{RAN} --- Real pseudo-random number
10877 @cindex random number generation
10880 @item @emph{Description}:
10881 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
10882 provided as an alias for @code{RAND}. See @ref{RAND} for complete
10885 @item @emph{Standard}:
10888 @item @emph{Class}:
10891 @item @emph{See also}:
10892 @ref{RAND}, @ref{RANDOM_NUMBER}
10898 @section @code{RAND} --- Real pseudo-random number
10900 @cindex random number generation
10903 @item @emph{Description}:
10904 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
10905 distribution between 0 and 1. If @var{FLAG} is 0, the next number
10906 in the current sequence is returned; if @var{FLAG} is 1, the generator
10907 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
10908 it is used as a new seed with @code{SRAND}.
10910 This intrinsic routine is provided for backwards compatibility with
10911 GNU Fortran 77. It implements a simple modulo generator as provided
10912 by @command{g77}. For new code, one should consider the use of
10913 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
10915 @item @emph{Standard}:
10918 @item @emph{Class}:
10921 @item @emph{Syntax}:
10922 @code{RESULT = RAND(I)}
10924 @item @emph{Arguments}:
10925 @multitable @columnfractions .15 .70
10926 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
10929 @item @emph{Return value}:
10930 The return value is of @code{REAL} type and the default kind.
10932 @item @emph{Example}:
10935 integer,parameter :: seed = 86456
10938 print *, rand(), rand(), rand(), rand()
10939 print *, rand(seed), rand(), rand(), rand()
10940 end program test_rand
10943 @item @emph{See also}:
10944 @ref{SRAND}, @ref{RANDOM_NUMBER}
10950 @node RANDOM_NUMBER
10951 @section @code{RANDOM_NUMBER} --- Pseudo-random number
10952 @fnindex RANDOM_NUMBER
10953 @cindex random number generation
10956 @item @emph{Description}:
10957 Returns a single pseudorandom number or an array of pseudorandom numbers
10958 from the uniform distribution over the range @math{ 0 \leq x < 1}.
10960 The runtime-library implements George Marsaglia's KISS (Keep It Simple
10961 Stupid) random number generator (RNG). This RNG combines:
10963 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
10964 with a period of @math{2^{32}},
10965 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
10966 @item Two 16-bit multiply-with-carry generators with a period of
10967 @math{597273182964842497 > 2^{59}}.
10969 The overall period exceeds @math{2^{123}}.
10971 Please note, this RNG is thread safe if used within OpenMP directives,
10972 i.e., its state will be consistent while called from multiple threads.
10973 However, the KISS generator does not create random numbers in parallel
10974 from multiple sources, but in sequence from a single source. If an
10975 OpenMP-enabled application heavily relies on random numbers, one should
10976 consider employing a dedicated parallel random number generator instead.
10978 @item @emph{Standard}:
10979 Fortran 95 and later
10981 @item @emph{Class}:
10984 @item @emph{Syntax}:
10985 @code{RANDOM_NUMBER(HARVEST)}
10987 @item @emph{Arguments}:
10988 @multitable @columnfractions .15 .70
10989 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
10992 @item @emph{Example}:
10994 program test_random_number
10996 CALL init_random_seed() ! see example of RANDOM_SEED
10997 CALL RANDOM_NUMBER(r)
11001 @item @emph{See also}:
11008 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
11009 @fnindex RANDOM_SEED
11010 @cindex random number generation, seeding
11011 @cindex seeding a random number generator
11014 @item @emph{Description}:
11015 Restarts or queries the state of the pseudorandom number generator used by
11016 @code{RANDOM_NUMBER}.
11018 If @code{RANDOM_SEED} is called without arguments, it is initialized
11019 to a default state. The example below shows how to initialize the
11020 random seed with a varying seed in order to ensure a different random
11021 number sequence for each invocation of the program. Note that setting
11022 any of the seed values to zero should be avoided as it can result in
11023 poor quality random numbers being generated.
11025 @item @emph{Standard}:
11026 Fortran 95 and later
11028 @item @emph{Class}:
11031 @item @emph{Syntax}:
11032 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
11034 @item @emph{Arguments}:
11035 @multitable @columnfractions .15 .70
11036 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
11037 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
11038 of the arrays used with the @var{PUT} and @var{GET} arguments.
11039 @item @var{PUT} @tab (Optional) Shall be an array of type default
11040 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
11041 the array must be larger than or equal to the number returned by the
11042 @var{SIZE} argument.
11043 @item @var{GET} @tab (Optional) Shall be an array of type default
11044 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
11045 of the array must be larger than or equal to the number returned by
11046 the @var{SIZE} argument.
11049 @item @emph{Example}:
11051 subroutine init_random_seed()
11052 use iso_fortran_env, only: int64
11054 integer, allocatable :: seed(:)
11055 integer :: i, n, un, istat, dt(8), pid
11056 integer(int64) :: t
11058 call random_seed(size = n)
11060 ! First try if the OS provides a random number generator
11061 open(newunit=un, file="/dev/urandom", access="stream", &
11062 form="unformatted", action="read", status="old", iostat=istat)
11063 if (istat == 0) then
11067 ! Fallback to XOR:ing the current time and pid. The PID is
11068 ! useful in case one launches multiple instances of the same
11069 ! program in parallel.
11070 call system_clock(t)
11072 call date_and_time(values=dt)
11073 t = (dt(1) - 1970) * 365_int64 * 24 * 60 * 60 * 1000 &
11074 + dt(2) * 31_int64 * 24 * 60 * 60 * 1000 &
11075 + dt(3) * 24_int64 * 60 * 60 * 1000 &
11076 + dt(5) * 60 * 60 * 1000 &
11077 + dt(6) * 60 * 1000 + dt(7) * 1000 &
11081 t = ieor(t, int(pid, kind(t)))
11086 call random_seed(put=seed)
11088 ! This simple PRNG might not be good enough for real work, but is
11089 ! sufficient for seeding a better PRNG.
11092 integer(int64) :: s
11096 s = mod(s, 4294967296_int64)
11098 s = mod(s * 279470273_int64, 4294967291_int64)
11099 lcg = int(mod(s, int(huge(0), int64)), kind(0))
11101 end subroutine init_random_seed
11104 @item @emph{See also}:
11105 @ref{RANDOM_NUMBER}
11111 @section @code{RANGE} --- Decimal exponent range
11113 @cindex model representation, range
11116 @item @emph{Description}:
11117 @code{RANGE(X)} returns the decimal exponent range in the model of the
11120 @item @emph{Standard}:
11121 Fortran 95 and later
11123 @item @emph{Class}:
11126 @item @emph{Syntax}:
11127 @code{RESULT = RANGE(X)}
11129 @item @emph{Arguments}:
11130 @multitable @columnfractions .15 .70
11131 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
11135 @item @emph{Return value}:
11136 The return value is of type @code{INTEGER} and of the default integer
11139 @item @emph{See also}:
11140 @ref{SELECTED_REAL_KIND}, @ref{PRECISION}
11142 @item @emph{Example}:
11143 See @code{PRECISION} for an example.
11149 @section @code{RANK} --- Rank of a data object
11154 @item @emph{Description}:
11155 @code{RANK(A)} returns the rank of a scalar or array data object.
11157 @item @emph{Standard}:
11158 Technical Specification (TS) 29113
11160 @item @emph{Class}:
11163 @item @emph{Syntax}:
11164 @code{RESULT = RANK(A)}
11166 @item @emph{Arguments}:
11167 @multitable @columnfractions .15 .70
11168 @item @var{A} @tab can be of any type
11171 @item @emph{Return value}:
11172 The return value is of type @code{INTEGER} and of the default integer
11173 kind. For arrays, their rank is returned; for scalars zero is returned.
11175 @item @emph{Example}:
11179 real, allocatable :: b(:,:)
11181 print *, rank(a), rank(b) ! Prints: 0 2
11182 end program test_rank
11190 @section @code{REAL} --- Convert to real type
11196 @cindex conversion, to real
11197 @cindex complex numbers, real part
11200 @item @emph{Description}:
11201 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
11202 @code{REALPART} function is provided for compatibility with @command{g77},
11203 and its use is strongly discouraged.
11205 @item @emph{Standard}:
11206 Fortran 77 and later
11208 @item @emph{Class}:
11211 @item @emph{Syntax}:
11212 @multitable @columnfractions .80
11213 @item @code{RESULT = REAL(A [, KIND])}
11214 @item @code{RESULT = REALPART(Z)}
11217 @item @emph{Arguments}:
11218 @multitable @columnfractions .15 .70
11219 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
11221 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11222 expression indicating the kind parameter of the result.
11225 @item @emph{Return value}:
11226 These functions return a @code{REAL} variable or array under
11227 the following rules:
11231 @code{REAL(A)} is converted to a default real type if @var{A} is an
11232 integer or real variable.
11234 @code{REAL(A)} is converted to a real type with the kind type parameter
11235 of @var{A} if @var{A} is a complex variable.
11237 @code{REAL(A, KIND)} is converted to a real type with kind type
11238 parameter @var{KIND} if @var{A} is a complex, integer, or real
11242 @item @emph{Example}:
11245 complex :: x = (1.0, 2.0)
11246 print *, real(x), real(x,8), realpart(x)
11247 end program test_real
11250 @item @emph{Specific names}:
11251 @multitable @columnfractions .20 .20 .20 .25
11252 @item Name @tab Argument @tab Return type @tab Standard
11253 @item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later
11254 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension
11255 @item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab Fortran 77 and later
11259 @item @emph{See also}:
11267 @section @code{RENAME} --- Rename a file
11269 @cindex file system, rename file
11272 @item @emph{Description}:
11273 Renames a file from file @var{PATH1} to @var{PATH2}. A null
11274 character (@code{CHAR(0)}) can be used to mark the end of the names in
11275 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
11276 names are ignored. If the @var{STATUS} argument is supplied, it
11277 contains 0 on success or a nonzero error code upon return; see
11280 This intrinsic is provided in both subroutine and function forms;
11281 however, only one form can be used in any given program unit.
11283 @item @emph{Standard}:
11286 @item @emph{Class}:
11287 Subroutine, function
11289 @item @emph{Syntax}:
11290 @multitable @columnfractions .80
11291 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
11292 @item @code{STATUS = RENAME(PATH1, PATH2)}
11295 @item @emph{Arguments}:
11296 @multitable @columnfractions .15 .70
11297 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
11298 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
11299 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11302 @item @emph{See also}:
11310 @section @code{REPEAT} --- Repeated string concatenation
11312 @cindex string, repeat
11313 @cindex string, concatenate
11316 @item @emph{Description}:
11317 Concatenates @var{NCOPIES} copies of a string.
11319 @item @emph{Standard}:
11320 Fortran 95 and later
11322 @item @emph{Class}:
11323 Transformational function
11325 @item @emph{Syntax}:
11326 @code{RESULT = REPEAT(STRING, NCOPIES)}
11328 @item @emph{Arguments}:
11329 @multitable @columnfractions .15 .70
11330 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
11331 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
11334 @item @emph{Return value}:
11335 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
11338 @item @emph{Example}:
11340 program test_repeat
11341 write(*,*) repeat("x", 5) ! "xxxxx"
11349 @section @code{RESHAPE} --- Function to reshape an array
11351 @cindex array, change dimensions
11352 @cindex array, transmogrify
11355 @item @emph{Description}:
11356 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
11357 the new array may be padded with elements from @var{PAD} or permuted
11358 as defined by @var{ORDER}.
11360 @item @emph{Standard}:
11361 Fortran 95 and later
11363 @item @emph{Class}:
11364 Transformational function
11366 @item @emph{Syntax}:
11367 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
11369 @item @emph{Arguments}:
11370 @multitable @columnfractions .15 .70
11371 @item @var{SOURCE} @tab Shall be an array of any type.
11372 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
11373 array of rank one. Its values must be positive or zero.
11374 @item @var{PAD} @tab (Optional) shall be an array of the same
11375 type as @var{SOURCE}.
11376 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
11377 and an array of the same shape as @var{SHAPE}. Its values shall
11378 be a permutation of the numbers from 1 to n, where n is the size of
11379 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
11383 @item @emph{Return value}:
11384 The result is an array of shape @var{SHAPE} with the same type as
11387 @item @emph{Example}:
11389 PROGRAM test_reshape
11390 INTEGER, DIMENSION(4) :: x
11391 WRITE(*,*) SHAPE(x) ! prints "4"
11392 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
11396 @item @emph{See also}:
11403 @section @code{RRSPACING} --- Reciprocal of the relative spacing
11405 @cindex real number, relative spacing
11406 @cindex floating point, relative spacing
11410 @item @emph{Description}:
11411 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
11412 model numbers near @var{X}.
11414 @item @emph{Standard}:
11415 Fortran 95 and later
11417 @item @emph{Class}:
11420 @item @emph{Syntax}:
11421 @code{RESULT = RRSPACING(X)}
11423 @item @emph{Arguments}:
11424 @multitable @columnfractions .15 .70
11425 @item @var{X} @tab Shall be of type @code{REAL}.
11428 @item @emph{Return value}:
11429 The return value is of the same type and kind as @var{X}.
11430 The value returned is equal to
11431 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
11433 @item @emph{See also}:
11440 @section @code{RSHIFT} --- Right shift bits
11442 @cindex bits, shift right
11445 @item @emph{Description}:
11446 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
11447 bits shifted right by @var{SHIFT} places. If the absolute value of
11448 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11449 Bits shifted out from the right end are lost. The fill is arithmetic: the
11450 bits shifted in from the left end are equal to the leftmost bit, which in
11451 two's complement representation is the sign bit.
11453 This function has been superseded by the @code{SHIFTA} intrinsic, which
11454 is standard in Fortran 2008 and later.
11456 @item @emph{Standard}:
11459 @item @emph{Class}:
11462 @item @emph{Syntax}:
11463 @code{RESULT = RSHIFT(I, SHIFT)}
11465 @item @emph{Arguments}:
11466 @multitable @columnfractions .15 .70
11467 @item @var{I} @tab The type shall be @code{INTEGER}.
11468 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11471 @item @emph{Return value}:
11472 The return value is of type @code{INTEGER} and of the same kind as
11475 @item @emph{See also}:
11476 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}, @ref{SHIFTA}, @ref{SHIFTR},
11484 @section @code{SAME_TYPE_AS} --- Query dynamic types for equality
11485 @fnindex SAME_TYPE_AS
11488 @item @emph{Description}:
11489 Query dynamic types for equality.
11491 @item @emph{Standard}:
11492 Fortran 2003 and later
11494 @item @emph{Class}:
11497 @item @emph{Syntax}:
11498 @code{RESULT = SAME_TYPE_AS(A, B)}
11500 @item @emph{Arguments}:
11501 @multitable @columnfractions .15 .70
11502 @item @var{A} @tab Shall be an object of extensible declared type or
11503 unlimited polymorphic.
11504 @item @var{B} @tab Shall be an object of extensible declared type or
11505 unlimited polymorphic.
11508 @item @emph{Return value}:
11509 The return value is a scalar of type default logical. It is true if and
11510 only if the dynamic type of A is the same as the dynamic type of B.
11512 @item @emph{See also}:
11513 @ref{EXTENDS_TYPE_OF}
11520 @section @code{SCALE} --- Scale a real value
11522 @cindex real number, scale
11523 @cindex floating point, scale
11526 @item @emph{Description}:
11527 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
11529 @item @emph{Standard}:
11530 Fortran 95 and later
11532 @item @emph{Class}:
11535 @item @emph{Syntax}:
11536 @code{RESULT = SCALE(X, I)}
11538 @item @emph{Arguments}:
11539 @multitable @columnfractions .15 .70
11540 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
11541 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
11544 @item @emph{Return value}:
11545 The return value is of the same type and kind as @var{X}.
11546 Its value is @code{X * RADIX(X)**I}.
11548 @item @emph{Example}:
11551 real :: x = 178.1387e-4
11553 print *, scale(x,i), x*radix(x)**i
11554 end program test_scale
11562 @section @code{SCAN} --- Scan a string for the presence of a set of characters
11564 @cindex string, find subset
11567 @item @emph{Description}:
11568 Scans a @var{STRING} for any of the characters in a @var{SET}
11571 If @var{BACK} is either absent or equals @code{FALSE}, this function
11572 returns the position of the leftmost character of @var{STRING} that is
11573 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
11574 is returned. If no character of @var{SET} is found in @var{STRING}, the
11577 @item @emph{Standard}:
11578 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11580 @item @emph{Class}:
11583 @item @emph{Syntax}:
11584 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
11586 @item @emph{Arguments}:
11587 @multitable @columnfractions .15 .70
11588 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
11589 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
11590 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
11591 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11592 expression indicating the kind parameter of the result.
11595 @item @emph{Return value}:
11596 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11597 @var{KIND} is absent, the return value is of default integer kind.
11599 @item @emph{Example}:
11602 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
11603 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
11604 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
11608 @item @emph{See also}:
11609 @ref{INDEX intrinsic}, @ref{VERIFY}
11615 @section @code{SECNDS} --- Time function
11617 @cindex time, elapsed
11618 @cindex elapsed time
11621 @item @emph{Description}:
11622 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
11623 @var{X} is a reference time, also in seconds. If this is zero, the time in
11624 seconds from midnight is returned. This function is non-standard and its
11625 use is discouraged.
11627 @item @emph{Standard}:
11630 @item @emph{Class}:
11633 @item @emph{Syntax}:
11634 @code{RESULT = SECNDS (X)}
11636 @item @emph{Arguments}:
11637 @multitable @columnfractions .15 .70
11638 @item @var{T} @tab Shall be of type @code{REAL(4)}.
11639 @item @var{X} @tab Shall be of type @code{REAL(4)}.
11642 @item @emph{Return value}:
11645 @item @emph{Example}:
11647 program test_secnds
11650 print *, secnds (0.0) ! seconds since midnight
11651 t1 = secnds (0.0) ! reference time
11652 do i = 1, 10000000 ! do something
11654 t2 = secnds (t1) ! elapsed time
11655 print *, "Something took ", t2, " seconds."
11656 end program test_secnds
11663 @section @code{SECOND} --- CPU time function
11665 @cindex time, elapsed
11666 @cindex elapsed time
11669 @item @emph{Description}:
11670 Returns a @code{REAL(4)} value representing the elapsed CPU time in
11671 seconds. This provides the same functionality as the standard
11672 @code{CPU_TIME} intrinsic, and is only included for backwards
11675 This intrinsic is provided in both subroutine and function forms;
11676 however, only one form can be used in any given program unit.
11678 @item @emph{Standard}:
11681 @item @emph{Class}:
11682 Subroutine, function
11684 @item @emph{Syntax}:
11685 @multitable @columnfractions .80
11686 @item @code{CALL SECOND(TIME)}
11687 @item @code{TIME = SECOND()}
11690 @item @emph{Arguments}:
11691 @multitable @columnfractions .15 .70
11692 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
11695 @item @emph{Return value}:
11696 In either syntax, @var{TIME} is set to the process's current runtime in
11699 @item @emph{See also}:
11706 @node SELECTED_CHAR_KIND
11707 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
11708 @fnindex SELECTED_CHAR_KIND
11709 @cindex character kind
11710 @cindex kind, character
11713 @item @emph{Description}:
11715 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
11716 set named @var{NAME}, if a character set with such a name is supported,
11717 or @math{-1} otherwise. Currently, supported character sets include
11718 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
11719 (Universal Character Set, UCS-4) which is commonly known as Unicode.
11721 @item @emph{Standard}:
11722 Fortran 2003 and later
11724 @item @emph{Class}:
11725 Transformational function
11727 @item @emph{Syntax}:
11728 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
11730 @item @emph{Arguments}:
11731 @multitable @columnfractions .15 .70
11732 @item @var{NAME} @tab Shall be a scalar and of the default character type.
11735 @item @emph{Example}:
11737 program character_kind
11738 use iso_fortran_env
11740 integer, parameter :: ascii = selected_char_kind ("ascii")
11741 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646')
11743 character(kind=ascii, len=26) :: alphabet
11744 character(kind=ucs4, len=30) :: hello_world
11746 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
11747 hello_world = ucs4_'Hello World and Ni Hao -- ' &
11748 // char (int (z'4F60'), ucs4) &
11749 // char (int (z'597D'), ucs4)
11751 write (*,*) alphabet
11753 open (output_unit, encoding='UTF-8')
11754 write (*,*) trim (hello_world)
11755 end program character_kind
11761 @node SELECTED_INT_KIND
11762 @section @code{SELECTED_INT_KIND} --- Choose integer kind
11763 @fnindex SELECTED_INT_KIND
11764 @cindex integer kind
11765 @cindex kind, integer
11768 @item @emph{Description}:
11769 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
11770 type that can represent all values ranging from @math{-10^R} (exclusive)
11771 to @math{10^R} (exclusive). If there is no integer kind that accommodates
11772 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
11774 @item @emph{Standard}:
11775 Fortran 95 and later
11777 @item @emph{Class}:
11778 Transformational function
11780 @item @emph{Syntax}:
11781 @code{RESULT = SELECTED_INT_KIND(R)}
11783 @item @emph{Arguments}:
11784 @multitable @columnfractions .15 .70
11785 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
11788 @item @emph{Example}:
11790 program large_integers
11791 integer,parameter :: k5 = selected_int_kind(5)
11792 integer,parameter :: k15 = selected_int_kind(15)
11793 integer(kind=k5) :: i5
11794 integer(kind=k15) :: i15
11796 print *, huge(i5), huge(i15)
11798 ! The following inequalities are always true
11799 print *, huge(i5) >= 10_k5**5-1
11800 print *, huge(i15) >= 10_k15**15-1
11801 end program large_integers
11807 @node SELECTED_REAL_KIND
11808 @section @code{SELECTED_REAL_KIND} --- Choose real kind
11809 @fnindex SELECTED_REAL_KIND
11812 @cindex radix, real
11815 @item @emph{Description}:
11816 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
11817 with decimal precision of at least @code{P} digits, exponent range of
11818 at least @code{R}, and with a radix of @code{RADIX}.
11820 @item @emph{Standard}:
11821 Fortran 95 and later, with @code{RADIX} Fortran 2008 or later
11823 @item @emph{Class}:
11824 Transformational function
11826 @item @emph{Syntax}:
11827 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
11829 @item @emph{Arguments}:
11830 @multitable @columnfractions .15 .70
11831 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
11832 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
11833 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
11835 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
11836 be present; since Fortran 2008, they are assumed to be zero if absent.
11838 @item @emph{Return value}:
11840 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
11841 a real data type with decimal precision of at least @code{P} digits, a
11842 decimal exponent range of at least @code{R}, and with the requested
11843 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
11844 any radix can be returned. If more than one real data type meet the
11845 criteria, the kind of the data type with the smallest decimal precision
11846 is returned. If no real data type matches the criteria, the result is
11848 @item -1 if the processor does not support a real data type with a
11849 precision greater than or equal to @code{P}, but the @code{R} and
11850 @code{RADIX} requirements can be fulfilled
11851 @item -2 if the processor does not support a real type with an exponent
11852 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
11854 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
11856 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
11858 @item -5 if there is no real type with the given @code{RADIX}
11861 @item @emph{See also}:
11862 @ref{PRECISION}, @ref{RANGE}, @ref{RADIX}
11864 @item @emph{Example}:
11867 integer,parameter :: p6 = selected_real_kind(6)
11868 integer,parameter :: p10r100 = selected_real_kind(10,100)
11869 integer,parameter :: r400 = selected_real_kind(r=400)
11871 real(kind=p10r100) :: y
11872 real(kind=r400) :: z
11874 print *, precision(x), range(x)
11875 print *, precision(y), range(y)
11876 print *, precision(z), range(z)
11877 end program real_kinds
11884 @section @code{SET_EXPONENT} --- Set the exponent of the model
11885 @fnindex SET_EXPONENT
11886 @cindex real number, set exponent
11887 @cindex floating point, set exponent
11890 @item @emph{Description}:
11891 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
11892 is that that of @var{X} and whose exponent part is @var{I}.
11894 @item @emph{Standard}:
11895 Fortran 95 and later
11897 @item @emph{Class}:
11900 @item @emph{Syntax}:
11901 @code{RESULT = SET_EXPONENT(X, I)}
11903 @item @emph{Arguments}:
11904 @multitable @columnfractions .15 .70
11905 @item @var{X} @tab Shall be of type @code{REAL}.
11906 @item @var{I} @tab Shall be of type @code{INTEGER}.
11909 @item @emph{Return value}:
11910 The return value is of the same type and kind as @var{X}.
11911 The real number whose fractional part
11912 is that that of @var{X} and whose exponent part if @var{I} is returned;
11913 it is @code{FRACTION(X) * RADIX(X)**I}.
11915 @item @emph{Example}:
11917 PROGRAM test_setexp
11918 REAL :: x = 178.1387e-4
11920 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
11929 @section @code{SHAPE} --- Determine the shape of an array
11931 @cindex array, shape
11934 @item @emph{Description}:
11935 Determines the shape of an array.
11937 @item @emph{Standard}:
11938 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11940 @item @emph{Class}:
11943 @item @emph{Syntax}:
11944 @code{RESULT = SHAPE(SOURCE [, KIND])}
11946 @item @emph{Arguments}:
11947 @multitable @columnfractions .15 .70
11948 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
11949 If @var{SOURCE} is a pointer it must be associated and allocatable
11950 arrays must be allocated.
11951 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11952 expression indicating the kind parameter of the result.
11955 @item @emph{Return value}:
11956 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
11957 has dimensions. The elements of the resulting array correspond to the extend
11958 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
11959 the result is the rank one array of size zero. If @var{KIND} is absent, the
11960 return value has the default integer kind otherwise the specified kind.
11962 @item @emph{Example}:
11965 INTEGER, DIMENSION(-1:1, -1:2) :: A
11966 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
11967 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
11971 @item @emph{See also}:
11972 @ref{RESHAPE}, @ref{SIZE}
11978 @section @code{SHIFTA} --- Right shift with fill
11980 @cindex bits, shift right
11981 @cindex shift, right with fill
11984 @item @emph{Description}:
11985 @code{SHIFTA} returns a value corresponding to @var{I} with all of the
11986 bits shifted right by @var{SHIFT} places. If the absolute value of
11987 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11988 Bits shifted out from the right end are lost. The fill is arithmetic: the
11989 bits shifted in from the left end are equal to the leftmost bit, which in
11990 two's complement representation is the sign bit.
11992 @item @emph{Standard}:
11993 Fortran 2008 and later
11995 @item @emph{Class}:
11998 @item @emph{Syntax}:
11999 @code{RESULT = SHIFTA(I, SHIFT)}
12001 @item @emph{Arguments}:
12002 @multitable @columnfractions .15 .70
12003 @item @var{I} @tab The type shall be @code{INTEGER}.
12004 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12007 @item @emph{Return value}:
12008 The return value is of type @code{INTEGER} and of the same kind as
12011 @item @emph{See also}:
12012 @ref{SHIFTL}, @ref{SHIFTR}
12018 @section @code{SHIFTL} --- Left shift
12020 @cindex bits, shift left
12021 @cindex shift, left
12024 @item @emph{Description}:
12025 @code{SHIFTL} returns a value corresponding to @var{I} with all of the
12026 bits shifted left by @var{SHIFT} places. If the absolute value of
12027 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12028 Bits shifted out from the left end are lost, and bits shifted in from
12029 the right end are set to 0.
12031 @item @emph{Standard}:
12032 Fortran 2008 and later
12034 @item @emph{Class}:
12037 @item @emph{Syntax}:
12038 @code{RESULT = SHIFTL(I, SHIFT)}
12040 @item @emph{Arguments}:
12041 @multitable @columnfractions .15 .70
12042 @item @var{I} @tab The type shall be @code{INTEGER}.
12043 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12046 @item @emph{Return value}:
12047 The return value is of type @code{INTEGER} and of the same kind as
12050 @item @emph{See also}:
12051 @ref{SHIFTA}, @ref{SHIFTR}
12057 @section @code{SHIFTR} --- Right shift
12059 @cindex bits, shift right
12060 @cindex shift, right
12063 @item @emph{Description}:
12064 @code{SHIFTR} returns a value corresponding to @var{I} with all of the
12065 bits shifted right by @var{SHIFT} places. If the absolute value of
12066 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12067 Bits shifted out from the right end are lost, and bits shifted in from
12068 the left end are set to 0.
12070 @item @emph{Standard}:
12071 Fortran 2008 and later
12073 @item @emph{Class}:
12076 @item @emph{Syntax}:
12077 @code{RESULT = SHIFTR(I, SHIFT)}
12079 @item @emph{Arguments}:
12080 @multitable @columnfractions .15 .70
12081 @item @var{I} @tab The type shall be @code{INTEGER}.
12082 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12085 @item @emph{Return value}:
12086 The return value is of type @code{INTEGER} and of the same kind as
12089 @item @emph{See also}:
12090 @ref{SHIFTA}, @ref{SHIFTL}
12096 @section @code{SIGN} --- Sign copying function
12100 @cindex sign copying
12103 @item @emph{Description}:
12104 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
12106 @item @emph{Standard}:
12107 Fortran 77 and later
12109 @item @emph{Class}:
12112 @item @emph{Syntax}:
12113 @code{RESULT = SIGN(A, B)}
12115 @item @emph{Arguments}:
12116 @multitable @columnfractions .15 .70
12117 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
12118 @item @var{B} @tab Shall be of the same type and kind as @var{A}
12121 @item @emph{Return value}:
12122 The kind of the return value is that of @var{A} and @var{B}.
12123 If @math{B\ge 0} then the result is @code{ABS(A)}, else
12124 it is @code{-ABS(A)}.
12126 @item @emph{Example}:
12129 print *, sign(-12,1)
12130 print *, sign(-12,0)
12131 print *, sign(-12,-1)
12133 print *, sign(-12.,1.)
12134 print *, sign(-12.,0.)
12135 print *, sign(-12.,-1.)
12136 end program test_sign
12139 @item @emph{Specific names}:
12140 @multitable @columnfractions .20 .20 .20 .25
12141 @item Name @tab Arguments @tab Return type @tab Standard
12142 @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu
12143 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
12144 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu
12151 @section @code{SIGNAL} --- Signal handling subroutine (or function)
12153 @cindex system, signal handling
12156 @item @emph{Description}:
12157 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
12158 @var{HANDLER} to be executed with a single integer argument when signal
12159 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
12160 turn off handling of signal @var{NUMBER} or revert to its default
12161 action. See @code{signal(2)}.
12163 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
12164 is supplied, it is set to the value returned by @code{signal(2)}.
12166 @item @emph{Standard}:
12169 @item @emph{Class}:
12170 Subroutine, function
12172 @item @emph{Syntax}:
12173 @multitable @columnfractions .80
12174 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
12175 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
12178 @item @emph{Arguments}:
12179 @multitable @columnfractions .15 .70
12180 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
12181 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
12182 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
12183 @code{INTEGER}. It is @code{INTENT(IN)}.
12184 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
12185 integer. It has @code{INTENT(OUT)}.
12187 @c TODO: What should the interface of the handler be? Does it take arguments?
12189 @item @emph{Return value}:
12190 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
12192 @item @emph{Example}:
12194 program test_signal
12196 external handler_print
12198 call signal (12, handler_print)
12199 call signal (10, 1)
12202 end program test_signal
12209 @section @code{SIN} --- Sine function
12215 @cindex trigonometric function, sine
12219 @item @emph{Description}:
12220 @code{SIN(X)} computes the sine of @var{X}.
12222 @item @emph{Standard}:
12223 Fortran 77 and later
12225 @item @emph{Class}:
12228 @item @emph{Syntax}:
12229 @code{RESULT = SIN(X)}
12231 @item @emph{Arguments}:
12232 @multitable @columnfractions .15 .70
12233 @item @var{X} @tab The type shall be @code{REAL} or
12237 @item @emph{Return value}:
12238 The return value has same type and kind as @var{X}.
12240 @item @emph{Example}:
12245 end program test_sin
12248 @item @emph{Specific names}:
12249 @multitable @columnfractions .20 .20 .20 .25
12250 @item Name @tab Argument @tab Return type @tab Standard
12251 @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu
12252 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
12253 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
12254 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
12255 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
12258 @item @emph{See also}:
12265 @section @code{SINH} --- Hyperbolic sine function
12268 @cindex hyperbolic sine
12269 @cindex hyperbolic function, sine
12270 @cindex sine, hyperbolic
12273 @item @emph{Description}:
12274 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
12276 @item @emph{Standard}:
12277 Fortran 95 and later, for a complex argument Fortran 2008 or later
12279 @item @emph{Class}:
12282 @item @emph{Syntax}:
12283 @code{RESULT = SINH(X)}
12285 @item @emph{Arguments}:
12286 @multitable @columnfractions .15 .70
12287 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
12290 @item @emph{Return value}:
12291 The return value has same type and kind as @var{X}.
12293 @item @emph{Example}:
12296 real(8) :: x = - 1.0_8
12298 end program test_sinh
12301 @item @emph{Specific names}:
12302 @multitable @columnfractions .20 .20 .20 .25
12303 @item Name @tab Argument @tab Return type @tab Standard
12304 @item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
12305 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
12308 @item @emph{See also}:
12315 @section @code{SIZE} --- Determine the size of an array
12317 @cindex array, size
12318 @cindex array, number of elements
12319 @cindex array, count elements
12322 @item @emph{Description}:
12323 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
12324 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
12326 @item @emph{Standard}:
12327 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12329 @item @emph{Class}:
12332 @item @emph{Syntax}:
12333 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
12335 @item @emph{Arguments}:
12336 @multitable @columnfractions .15 .70
12337 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
12338 a pointer it must be associated and allocatable arrays must be allocated.
12339 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
12340 and its value shall be in the range from 1 to n, where n equals the rank
12342 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12343 expression indicating the kind parameter of the result.
12346 @item @emph{Return value}:
12347 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12348 @var{KIND} is absent, the return value is of default integer kind.
12350 @item @emph{Example}:
12353 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
12357 @item @emph{See also}:
12358 @ref{SHAPE}, @ref{RESHAPE}
12363 @section @code{SIZEOF} --- Size in bytes of an expression
12365 @cindex expression size
12366 @cindex size of an expression
12369 @item @emph{Description}:
12370 @code{SIZEOF(X)} calculates the number of bytes of storage the
12371 expression @code{X} occupies.
12373 @item @emph{Standard}:
12376 @item @emph{Class}:
12379 @item @emph{Syntax}:
12380 @code{N = SIZEOF(X)}
12382 @item @emph{Arguments}:
12383 @multitable @columnfractions .15 .70
12384 @item @var{X} @tab The argument shall be of any type, rank or shape.
12387 @item @emph{Return value}:
12388 The return value is of type integer and of the system-dependent kind
12389 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
12390 number of bytes occupied by the argument. If the argument has the
12391 @code{POINTER} attribute, the number of bytes of the storage area pointed
12392 to is returned. If the argument is of a derived type with @code{POINTER}
12393 or @code{ALLOCATABLE} components, the return value does not account for
12394 the sizes of the data pointed to by these components. If the argument is
12395 polymorphic, the size according to the dynamic type is returned. The argument
12396 may not be a procedure or procedure pointer. Note that the code assumes for
12397 arrays that those are contiguous; for contiguous arrays, it returns the
12398 storage or an array element multiplied by the size of the array.
12400 @item @emph{Example}:
12404 print *, (sizeof(s)/sizeof(r) == 5)
12407 The example will print @code{.TRUE.} unless you are using a platform
12408 where default @code{REAL} variables are unusually padded.
12410 @item @emph{See also}:
12411 @ref{C_SIZEOF}, @ref{STORAGE_SIZE}
12416 @section @code{SLEEP} --- Sleep for the specified number of seconds
12418 @cindex delayed execution
12421 @item @emph{Description}:
12422 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
12424 @item @emph{Standard}:
12427 @item @emph{Class}:
12430 @item @emph{Syntax}:
12431 @code{CALL SLEEP(SECONDS)}
12433 @item @emph{Arguments}:
12434 @multitable @columnfractions .15 .70
12435 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
12438 @item @emph{Example}:
12449 @section @code{SPACING} --- Smallest distance between two numbers of a given type
12451 @cindex real number, relative spacing
12452 @cindex floating point, relative spacing
12455 @item @emph{Description}:
12456 Determines the distance between the argument @var{X} and the nearest
12457 adjacent number of the same type.
12459 @item @emph{Standard}:
12460 Fortran 95 and later
12462 @item @emph{Class}:
12465 @item @emph{Syntax}:
12466 @code{RESULT = SPACING(X)}
12468 @item @emph{Arguments}:
12469 @multitable @columnfractions .15 .70
12470 @item @var{X} @tab Shall be of type @code{REAL}.
12473 @item @emph{Return value}:
12474 The result is of the same type as the input argument @var{X}.
12476 @item @emph{Example}:
12478 PROGRAM test_spacing
12479 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
12480 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
12482 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
12483 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
12487 @item @emph{See also}:
12494 @section @code{SPREAD} --- Add a dimension to an array
12496 @cindex array, increase dimension
12497 @cindex array, duplicate elements
12498 @cindex array, duplicate dimensions
12501 @item @emph{Description}:
12502 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
12503 dimension @var{DIM}.
12505 @item @emph{Standard}:
12506 Fortran 95 and later
12508 @item @emph{Class}:
12509 Transformational function
12511 @item @emph{Syntax}:
12512 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
12514 @item @emph{Arguments}:
12515 @multitable @columnfractions .15 .70
12516 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
12517 a rank less than seven.
12518 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
12519 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
12520 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
12523 @item @emph{Return value}:
12524 The result is an array of the same type as @var{SOURCE} and has rank n+1
12525 where n equals the rank of @var{SOURCE}.
12527 @item @emph{Example}:
12529 PROGRAM test_spread
12530 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
12531 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
12532 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
12536 @item @emph{See also}:
12543 @section @code{SQRT} --- Square-root function
12550 @cindex square-root
12553 @item @emph{Description}:
12554 @code{SQRT(X)} computes the square root of @var{X}.
12556 @item @emph{Standard}:
12557 Fortran 77 and later
12559 @item @emph{Class}:
12562 @item @emph{Syntax}:
12563 @code{RESULT = SQRT(X)}
12565 @item @emph{Arguments}:
12566 @multitable @columnfractions .15 .70
12567 @item @var{X} @tab The type shall be @code{REAL} or
12571 @item @emph{Return value}:
12572 The return value is of type @code{REAL} or @code{COMPLEX}.
12573 The kind type parameter is the same as @var{X}.
12575 @item @emph{Example}:
12578 real(8) :: x = 2.0_8
12579 complex :: z = (1.0, 2.0)
12582 end program test_sqrt
12585 @item @emph{Specific names}:
12586 @multitable @columnfractions .20 .20 .20 .25
12587 @item Name @tab Argument @tab Return type @tab Standard
12588 @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
12589 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
12590 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
12591 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
12592 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
12599 @section @code{SRAND} --- Reinitialize the random number generator
12601 @cindex random number generation, seeding
12602 @cindex seeding a random number generator
12605 @item @emph{Description}:
12606 @code{SRAND} reinitializes the pseudo-random number generator
12607 called by @code{RAND} and @code{IRAND}. The new seed used by the
12608 generator is specified by the required argument @var{SEED}.
12610 @item @emph{Standard}:
12613 @item @emph{Class}:
12616 @item @emph{Syntax}:
12617 @code{CALL SRAND(SEED)}
12619 @item @emph{Arguments}:
12620 @multitable @columnfractions .15 .70
12621 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
12624 @item @emph{Return value}:
12625 Does not return anything.
12627 @item @emph{Example}:
12628 See @code{RAND} and @code{IRAND} for examples.
12630 @item @emph{Notes}:
12631 The Fortran standard specifies the intrinsic subroutines
12632 @code{RANDOM_SEED} to initialize the pseudo-random number
12633 generator and @code{RANDOM_NUMBER} to generate pseudo-random numbers.
12634 These subroutines should be used in new codes.
12636 Please note that in GNU Fortran, these two sets of intrinsics (@code{RAND},
12637 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
12638 @code{RANDOM_SEED} on the other hand) access two independent
12639 pseudo-random number generators.
12641 @item @emph{See also}:
12642 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
12649 @section @code{STAT} --- Get file status
12651 @cindex file system, file status
12654 @item @emph{Description}:
12655 This function returns information about a file. No permissions are required on
12656 the file itself, but execute (search) permission is required on all of the
12657 directories in path that lead to the file.
12659 The elements that are obtained and stored in the array @code{VALUES}:
12660 @multitable @columnfractions .15 .70
12661 @item @code{VALUES(1)} @tab Device ID
12662 @item @code{VALUES(2)} @tab Inode number
12663 @item @code{VALUES(3)} @tab File mode
12664 @item @code{VALUES(4)} @tab Number of links
12665 @item @code{VALUES(5)} @tab Owner's uid
12666 @item @code{VALUES(6)} @tab Owner's gid
12667 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
12668 @item @code{VALUES(8)} @tab File size (bytes)
12669 @item @code{VALUES(9)} @tab Last access time
12670 @item @code{VALUES(10)} @tab Last modification time
12671 @item @code{VALUES(11)} @tab Last file status change time
12672 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
12673 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
12676 Not all these elements are relevant on all systems.
12677 If an element is not relevant, it is returned as 0.
12679 This intrinsic is provided in both subroutine and function forms; however,
12680 only one form can be used in any given program unit.
12682 @item @emph{Standard}:
12685 @item @emph{Class}:
12686 Subroutine, function
12688 @item @emph{Syntax}:
12689 @multitable @columnfractions .80
12690 @item @code{CALL STAT(NAME, VALUES [, STATUS])}
12691 @item @code{STATUS = STAT(NAME, VALUES)}
12694 @item @emph{Arguments}:
12695 @multitable @columnfractions .15 .70
12696 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
12697 default kind and a valid path within the file system.
12698 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
12699 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
12700 on success and a system specific error code otherwise.
12703 @item @emph{Example}:
12706 INTEGER, DIMENSION(13) :: buff
12709 CALL STAT("/etc/passwd", buff, status)
12711 IF (status == 0) THEN
12712 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
12713 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
12714 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
12715 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
12716 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
12717 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
12718 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
12719 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
12720 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
12721 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
12722 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
12723 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
12724 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
12729 @item @emph{See also}:
12730 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
12736 @section @code{STORAGE_SIZE} --- Storage size in bits
12737 @fnindex STORAGE_SIZE
12738 @cindex storage size
12741 @item @emph{Description}:
12742 Returns the storage size of argument @var{A} in bits.
12743 @item @emph{Standard}:
12744 Fortran 2008 and later
12745 @item @emph{Class}:
12747 @item @emph{Syntax}:
12748 @code{RESULT = STORAGE_SIZE(A [, KIND])}
12750 @item @emph{Arguments}:
12751 @multitable @columnfractions .15 .70
12752 @item @var{A} @tab Shall be a scalar or array of any type.
12753 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
12756 @item @emph{Return Value}:
12757 The result is a scalar integer with the kind type parameter specified by KIND
12758 (or default integer type if KIND is missing). The result value is the size
12759 expressed in bits for an element of an array that has the dynamic type and type
12762 @item @emph{See also}:
12763 @ref{C_SIZEOF}, @ref{SIZEOF}
12769 @section @code{SUM} --- Sum of array elements
12772 @cindex array, add elements
12773 @cindex array, conditionally add elements
12774 @cindex sum array elements
12777 @item @emph{Description}:
12778 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
12779 the corresponding element in @var{MASK} is @code{TRUE}.
12781 @item @emph{Standard}:
12782 Fortran 95 and later
12784 @item @emph{Class}:
12785 Transformational function
12787 @item @emph{Syntax}:
12788 @multitable @columnfractions .80
12789 @item @code{RESULT = SUM(ARRAY[, MASK])}
12790 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
12793 @item @emph{Arguments}:
12794 @multitable @columnfractions .15 .70
12795 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
12796 @code{REAL} or @code{COMPLEX}.
12797 @item @var{DIM} @tab (Optional) shall be a scalar of type
12798 @code{INTEGER} with a value in the range from 1 to n, where n
12799 equals the rank of @var{ARRAY}.
12800 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
12801 and either be a scalar or an array of the same shape as @var{ARRAY}.
12804 @item @emph{Return value}:
12805 The result is of the same type as @var{ARRAY}.
12807 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
12808 is returned. Otherwise, an array of rank n-1, where n equals the rank of
12809 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
12810 dropped is returned.
12812 @item @emph{Example}:
12815 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
12816 print *, SUM(x) ! all elements, sum = 15
12817 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
12821 @item @emph{See also}:
12828 @section @code{SYMLNK} --- Create a symbolic link
12830 @cindex file system, create link
12831 @cindex file system, soft link
12834 @item @emph{Description}:
12835 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
12836 character (@code{CHAR(0)}) can be used to mark the end of the names in
12837 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
12838 names are ignored. If the @var{STATUS} argument is supplied, it
12839 contains 0 on success or a nonzero error code upon return; see
12840 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
12841 @code{ENOSYS} is returned.
12843 This intrinsic is provided in both subroutine and function forms;
12844 however, only one form can be used in any given program unit.
12846 @item @emph{Standard}:
12849 @item @emph{Class}:
12850 Subroutine, function
12852 @item @emph{Syntax}:
12853 @multitable @columnfractions .80
12854 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
12855 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
12858 @item @emph{Arguments}:
12859 @multitable @columnfractions .15 .70
12860 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
12861 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
12862 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12865 @item @emph{See also}:
12866 @ref{LINK}, @ref{UNLINK}
12873 @section @code{SYSTEM} --- Execute a shell command
12875 @cindex system, system call
12878 @item @emph{Description}:
12879 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
12880 argument @var{STATUS} is present, it contains the value returned by
12881 @code{system(3)}, which is presumably 0 if the shell command succeeded.
12882 Note that which shell is used to invoke the command is system-dependent
12883 and environment-dependent.
12885 This intrinsic is provided in both subroutine and function forms;
12886 however, only one form can be used in any given program unit.
12888 Note that the @code{system} function need not be thread-safe. It is
12889 the responsibility of the user to ensure that @code{system} is not
12890 called concurrently.
12892 @item @emph{Standard}:
12895 @item @emph{Class}:
12896 Subroutine, function
12898 @item @emph{Syntax}:
12899 @multitable @columnfractions .80
12900 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
12901 @item @code{STATUS = SYSTEM(COMMAND)}
12904 @item @emph{Arguments}:
12905 @multitable @columnfractions .15 .70
12906 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
12907 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12910 @item @emph{See also}:
12911 @ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
12912 and should considered in new code for future portability.
12918 @section @code{SYSTEM_CLOCK} --- Time function
12919 @fnindex SYSTEM_CLOCK
12920 @cindex time, clock ticks
12921 @cindex clock ticks
12924 @item @emph{Description}:
12925 Determines the @var{COUNT} of a processor clock since an unspecified
12926 time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines
12927 the number of clock ticks per second. If the platform supports a
12928 monotonic clock, that clock is used and can, depending on the platform
12929 clock implementation, provide up to nanosecond resolution. If a
12930 monotonic clock is not available, the implementation falls back to a
12933 @var{COUNT_RATE} is system dependent and can vary depending on the kind of
12934 the arguments. For @var{kind=4} arguments (and smaller integer kinds),
12935 @var{COUNT} represents milliseconds, while for @var{kind=8} arguments (and
12936 larger integer kinds), @var{COUNT} typically represents micro- or
12937 nanoseconds depending on resolution of the underlying platform clock.
12938 @var{COUNT_MAX} usually equals @code{HUGE(COUNT_MAX)}. Note that the
12939 millisecond resolution of the @var{kind=4} version implies that the
12940 @var{COUNT} will wrap around in roughly 25 days. In order to avoid issues
12941 with the wrap around and for more precise timing, please use the
12942 @var{kind=8} version.
12944 If there is no clock, or querying the clock fails, @var{COUNT} is set
12945 to @code{-HUGE(COUNT)}, and @var{COUNT_RATE} and @var{COUNT_MAX} are
12948 When running on a platform using the GNU C library (glibc) version
12949 2.16 or older, or a derivative thereof, the high resolution monotonic
12950 clock is available only when linking with the @var{rt} library. This
12951 can be done explicitly by adding the @code{-lrt} flag when linking the
12952 application, but is also done implicitly when using OpenMP.
12954 On the Windows platform, the version with @var{kind=4} arguments uses
12955 the @code{GetTickCount} function, whereas the @var{kind=8} version
12956 uses @code{QueryPerformanceCounter} and
12957 @code{QueryPerformanceCounterFrequency}. For more information, and
12958 potential caveats, please see the platform documentation.
12960 @item @emph{Standard}:
12961 Fortran 95 and later
12963 @item @emph{Class}:
12966 @item @emph{Syntax}:
12967 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
12969 @item @emph{Arguments}:
12970 @multitable @columnfractions .15 .70
12971 @item @var{COUNT} @tab (Optional) shall be a scalar of type
12972 @code{INTEGER} with @code{INTENT(OUT)}.
12973 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type
12974 @code{INTEGER} or @code{REAL}, with @code{INTENT(OUT)}.
12975 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type
12976 @code{INTEGER} with @code{INTENT(OUT)}.
12979 @item @emph{Example}:
12981 PROGRAM test_system_clock
12982 INTEGER :: count, count_rate, count_max
12983 CALL SYSTEM_CLOCK(count, count_rate, count_max)
12984 WRITE(*,*) count, count_rate, count_max
12988 @item @emph{See also}:
12989 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
12995 @section @code{TAN} --- Tangent function
12998 @cindex trigonometric function, tangent
13002 @item @emph{Description}:
13003 @code{TAN(X)} computes the tangent of @var{X}.
13005 @item @emph{Standard}:
13006 Fortran 77 and later, for a complex argument Fortran 2008 or later
13008 @item @emph{Class}:
13011 @item @emph{Syntax}:
13012 @code{RESULT = TAN(X)}
13014 @item @emph{Arguments}:
13015 @multitable @columnfractions .15 .70
13016 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13019 @item @emph{Return value}:
13020 The return value has same type and kind as @var{X}.
13022 @item @emph{Example}:
13025 real(8) :: x = 0.165_8
13027 end program test_tan
13030 @item @emph{Specific names}:
13031 @multitable @columnfractions .20 .20 .20 .25
13032 @item Name @tab Argument @tab Return type @tab Standard
13033 @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
13034 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
13037 @item @emph{See also}:
13044 @section @code{TANH} --- Hyperbolic tangent function
13047 @cindex hyperbolic tangent
13048 @cindex hyperbolic function, tangent
13049 @cindex tangent, hyperbolic
13052 @item @emph{Description}:
13053 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
13055 @item @emph{Standard}:
13056 Fortran 77 and later, for a complex argument Fortran 2008 or later
13058 @item @emph{Class}:
13061 @item @emph{Syntax}:
13064 @item @emph{Arguments}:
13065 @multitable @columnfractions .15 .70
13066 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13069 @item @emph{Return value}:
13070 The return value has same type and kind as @var{X}. If @var{X} is
13071 complex, the imaginary part of the result is in radians. If @var{X}
13072 is @code{REAL}, the return value lies in the range
13073 @math{ - 1 \leq tanh(x) \leq 1 }.
13075 @item @emph{Example}:
13078 real(8) :: x = 2.1_8
13080 end program test_tanh
13083 @item @emph{Specific names}:
13084 @multitable @columnfractions .20 .20 .20 .25
13085 @item Name @tab Argument @tab Return type @tab Standard
13086 @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
13087 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
13090 @item @emph{See also}:
13097 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
13098 @fnindex THIS_IMAGE
13099 @cindex coarray, @code{THIS_IMAGE}
13100 @cindex images, index of this image
13103 @item @emph{Description}:
13104 Returns the cosubscript for this image.
13106 @item @emph{Standard}:
13107 Fortran 2008 and later. With @var{DISTANCE} argument,
13108 Technical Specification (TS) 18508 or later
13110 @item @emph{Class}:
13111 Transformational function
13113 @item @emph{Syntax}:
13114 @multitable @columnfractions .80
13115 @item @code{RESULT = THIS_IMAGE()}
13116 @item @code{RESULT = THIS_IMAGE(DISTANCE)}
13117 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
13120 @item @emph{Arguments}:
13121 @multitable @columnfractions .15 .70
13122 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
13123 (not permitted together with @var{COARRAY}).
13124 @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
13125 present, required).
13126 @item @var{DIM} @tab default integer scalar (optional). If present,
13127 @var{DIM} shall be between one and the corank of @var{COARRAY}.
13131 @item @emph{Return value}:
13132 Default integer. If @var{COARRAY} is not present, it is scalar; if
13133 @var{DISTANCE} is not present or has value 0, its value is the image index on
13134 the invoking image for the current team, for values smaller or equal
13135 distance to the initial team, it returns the image index on the ancestor team
13136 which has a distance of @var{DISTANCE} from the invoking team. If
13137 @var{DISTANCE} is larger than the distance to the initial team, the image
13138 index of the initial team is returned. Otherwise when the @var{COARRAY} is
13139 present, if @var{DIM} is not present, a rank-1 array with corank elements is
13140 returned, containing the cosubscripts for @var{COARRAY} specifying the invoking
13141 image. If @var{DIM} is present, a scalar is returned, with the value of
13142 the @var{DIM} element of @code{THIS_IMAGE(COARRAY)}.
13144 @item @emph{Example}:
13146 INTEGER :: value[*]
13148 value = THIS_IMAGE()
13150 IF (THIS_IMAGE() == 1) THEN
13151 DO i = 1, NUM_IMAGES()
13152 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
13156 ! Check whether the current image is the initial image
13157 IF (THIS_IMAGE(HUGE(1)) /= THIS_IMAGE())
13158 error stop "something is rotten here"
13161 @item @emph{See also}:
13162 @ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
13168 @section @code{TIME} --- Time function
13170 @cindex time, current
13171 @cindex current time
13174 @item @emph{Description}:
13175 Returns the current time encoded as an integer (in the manner of the
13176 function @code{time(3)} in the C standard library). This value is
13177 suitable for passing to @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
13179 This intrinsic is not fully portable, such as to systems with 32-bit
13180 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
13181 the values returned by this intrinsic might be, or become, negative, or
13182 numerically less than previous values, during a single run of the
13185 See @ref{TIME8}, for information on a similar intrinsic that might be
13186 portable to more GNU Fortran implementations, though to fewer Fortran
13189 @item @emph{Standard}:
13192 @item @emph{Class}:
13195 @item @emph{Syntax}:
13196 @code{RESULT = TIME()}
13198 @item @emph{Return value}:
13199 The return value is a scalar of type @code{INTEGER(4)}.
13201 @item @emph{See also}:
13202 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
13209 @section @code{TIME8} --- Time function (64-bit)
13211 @cindex time, current
13212 @cindex current time
13215 @item @emph{Description}:
13216 Returns the current time encoded as an integer (in the manner of the
13217 function @code{time(3)} in the C standard library). This value is
13218 suitable for passing to @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
13220 @emph{Warning:} this intrinsic does not increase the range of the timing
13221 values over that returned by @code{time(3)}. On a system with a 32-bit
13222 @code{time(3)}, @code{TIME8} will return a 32-bit value, even though
13223 it is converted to a 64-bit @code{INTEGER(8)} value. That means
13224 overflows of the 32-bit value can still occur. Therefore, the values
13225 returned by this intrinsic might be or become negative or numerically
13226 less than previous values during a single run of the compiled program.
13228 @item @emph{Standard}:
13231 @item @emph{Class}:
13234 @item @emph{Syntax}:
13235 @code{RESULT = TIME8()}
13237 @item @emph{Return value}:
13238 The return value is a scalar of type @code{INTEGER(8)}.
13240 @item @emph{See also}:
13241 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
13248 @section @code{TINY} --- Smallest positive number of a real kind
13250 @cindex limits, smallest number
13251 @cindex model representation, smallest number
13254 @item @emph{Description}:
13255 @code{TINY(X)} returns the smallest positive (non zero) number
13256 in the model of the type of @code{X}.
13258 @item @emph{Standard}:
13259 Fortran 95 and later
13261 @item @emph{Class}:
13264 @item @emph{Syntax}:
13265 @code{RESULT = TINY(X)}
13267 @item @emph{Arguments}:
13268 @multitable @columnfractions .15 .70
13269 @item @var{X} @tab Shall be of type @code{REAL}.
13272 @item @emph{Return value}:
13273 The return value is of the same type and kind as @var{X}
13275 @item @emph{Example}:
13276 See @code{HUGE} for an example.
13282 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
13287 @item @emph{Description}:
13288 @code{TRAILZ} returns the number of trailing zero bits of an integer.
13290 @item @emph{Standard}:
13291 Fortran 2008 and later
13293 @item @emph{Class}:
13296 @item @emph{Syntax}:
13297 @code{RESULT = TRAILZ(I)}
13299 @item @emph{Arguments}:
13300 @multitable @columnfractions .15 .70
13301 @item @var{I} @tab Shall be of type @code{INTEGER}.
13304 @item @emph{Return value}:
13305 The type of the return value is the default @code{INTEGER}.
13306 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
13308 @item @emph{Example}:
13310 PROGRAM test_trailz
13311 WRITE (*,*) TRAILZ(8) ! prints 3
13315 @item @emph{See also}:
13316 @ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT}
13322 @section @code{TRANSFER} --- Transfer bit patterns
13328 @item @emph{Description}:
13329 Interprets the bitwise representation of @var{SOURCE} in memory as if it
13330 is the representation of a variable or array of the same type and type
13331 parameters as @var{MOLD}.
13333 This is approximately equivalent to the C concept of @emph{casting} one
13336 @item @emph{Standard}:
13337 Fortran 95 and later
13339 @item @emph{Class}:
13340 Transformational function
13342 @item @emph{Syntax}:
13343 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
13345 @item @emph{Arguments}:
13346 @multitable @columnfractions .15 .70
13347 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
13348 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
13349 @item @var{SIZE} @tab (Optional) shall be a scalar of type
13353 @item @emph{Return value}:
13354 The result has the same type as @var{MOLD}, with the bit level
13355 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
13356 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
13357 but @var{MOLD} is an array (of any size or shape), the result is a one-
13358 dimensional array of the minimum length needed to contain the entirety
13359 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
13360 and @var{MOLD} is a scalar, the result is a scalar.
13362 If the bitwise representation of the result is longer than that of
13363 @var{SOURCE}, then the leading bits of the result correspond to those of
13364 @var{SOURCE} and any trailing bits are filled arbitrarily.
13366 When the resulting bit representation does not correspond to a valid
13367 representation of a variable of the same type as @var{MOLD}, the results
13368 are undefined, and subsequent operations on the result cannot be
13369 guaranteed to produce sensible behavior. For example, it is possible to
13370 create @code{LOGICAL} variables for which @code{@var{VAR}} and
13371 @code{.NOT.@var{VAR}} both appear to be true.
13373 @item @emph{Example}:
13375 PROGRAM test_transfer
13376 integer :: x = 2143289344
13377 print *, transfer(x, 1.0) ! prints "NaN" on i686
13385 @section @code{TRANSPOSE} --- Transpose an array of rank two
13387 @cindex array, transpose
13388 @cindex matrix, transpose
13392 @item @emph{Description}:
13393 Transpose an array of rank two. Element (i, j) of the result has the value
13394 @code{MATRIX(j, i)}, for all i, j.
13396 @item @emph{Standard}:
13397 Fortran 95 and later
13399 @item @emph{Class}:
13400 Transformational function
13402 @item @emph{Syntax}:
13403 @code{RESULT = TRANSPOSE(MATRIX)}
13405 @item @emph{Arguments}:
13406 @multitable @columnfractions .15 .70
13407 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
13410 @item @emph{Return value}:
13411 The result has the same type as @var{MATRIX}, and has shape
13412 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
13418 @section @code{TRIM} --- Remove trailing blank characters of a string
13420 @cindex string, remove trailing whitespace
13423 @item @emph{Description}:
13424 Removes trailing blank characters of a string.
13426 @item @emph{Standard}:
13427 Fortran 95 and later
13429 @item @emph{Class}:
13430 Transformational function
13432 @item @emph{Syntax}:
13433 @code{RESULT = TRIM(STRING)}
13435 @item @emph{Arguments}:
13436 @multitable @columnfractions .15 .70
13437 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
13440 @item @emph{Return value}:
13441 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
13442 less the number of trailing blanks.
13444 @item @emph{Example}:
13447 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
13448 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
13452 @item @emph{See also}:
13453 @ref{ADJUSTL}, @ref{ADJUSTR}
13459 @section @code{TTYNAM} --- Get the name of a terminal device.
13461 @cindex system, terminal
13464 @item @emph{Description}:
13465 Get the name of a terminal device. For more information,
13466 see @code{ttyname(3)}.
13468 This intrinsic is provided in both subroutine and function forms;
13469 however, only one form can be used in any given program unit.
13471 @item @emph{Standard}:
13474 @item @emph{Class}:
13475 Subroutine, function
13477 @item @emph{Syntax}:
13478 @multitable @columnfractions .80
13479 @item @code{CALL TTYNAM(UNIT, NAME)}
13480 @item @code{NAME = TTYNAM(UNIT)}
13483 @item @emph{Arguments}:
13484 @multitable @columnfractions .15 .70
13485 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
13486 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
13489 @item @emph{Example}:
13491 PROGRAM test_ttynam
13494 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
13499 @item @emph{See also}:
13506 @section @code{UBOUND} --- Upper dimension bounds of an array
13508 @cindex array, upper bound
13511 @item @emph{Description}:
13512 Returns the upper bounds of an array, or a single upper bound
13513 along the @var{DIM} dimension.
13514 @item @emph{Standard}:
13515 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
13517 @item @emph{Class}:
13520 @item @emph{Syntax}:
13521 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
13523 @item @emph{Arguments}:
13524 @multitable @columnfractions .15 .70
13525 @item @var{ARRAY} @tab Shall be an array, of any type.
13526 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
13527 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
13528 expression indicating the kind parameter of the result.
13531 @item @emph{Return value}:
13532 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
13533 @var{KIND} is absent, the return value is of default integer kind.
13534 If @var{DIM} is absent, the result is an array of the upper bounds of
13535 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
13536 corresponding to the upper bound of the array along that dimension. If
13537 @var{ARRAY} is an expression rather than a whole array or array
13538 structure component, or if it has a zero extent along the relevant
13539 dimension, the upper bound is taken to be the number of elements along
13540 the relevant dimension.
13542 @item @emph{See also}:
13543 @ref{LBOUND}, @ref{LCOBOUND}
13549 @section @code{UCOBOUND} --- Upper codimension bounds of an array
13551 @cindex coarray, upper bound
13554 @item @emph{Description}:
13555 Returns the upper cobounds of a coarray, or a single upper cobound
13556 along the @var{DIM} codimension.
13557 @item @emph{Standard}:
13558 Fortran 2008 and later
13560 @item @emph{Class}:
13563 @item @emph{Syntax}:
13564 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
13566 @item @emph{Arguments}:
13567 @multitable @columnfractions .15 .70
13568 @item @var{ARRAY} @tab Shall be an coarray, of any type.
13569 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
13570 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
13571 expression indicating the kind parameter of the result.
13574 @item @emph{Return value}:
13575 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
13576 @var{KIND} is absent, the return value is of default integer kind.
13577 If @var{DIM} is absent, the result is an array of the lower cobounds of
13578 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
13579 corresponding to the lower cobound of the array along that codimension.
13581 @item @emph{See also}:
13582 @ref{LCOBOUND}, @ref{LBOUND}
13588 @section @code{UMASK} --- Set the file creation mask
13590 @cindex file system, file creation mask
13593 @item @emph{Description}:
13594 Sets the file creation mask to @var{MASK}. If called as a function, it
13595 returns the old value. If called as a subroutine and argument @var{OLD}
13596 if it is supplied, it is set to the old value. See @code{umask(2)}.
13598 @item @emph{Standard}:
13601 @item @emph{Class}:
13602 Subroutine, function
13604 @item @emph{Syntax}:
13605 @multitable @columnfractions .80
13606 @item @code{CALL UMASK(MASK [, OLD])}
13607 @item @code{OLD = UMASK(MASK)}
13610 @item @emph{Arguments}:
13611 @multitable @columnfractions .15 .70
13612 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
13613 @item @var{OLD} @tab (Optional) Shall be a scalar of type
13622 @section @code{UNLINK} --- Remove a file from the file system
13624 @cindex file system, remove file
13627 @item @emph{Description}:
13628 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
13629 used to mark the end of the name in @var{PATH}; otherwise, trailing
13630 blanks in the file name are ignored. If the @var{STATUS} argument is
13631 supplied, it contains 0 on success or a nonzero error code upon return;
13632 see @code{unlink(2)}.
13634 This intrinsic is provided in both subroutine and function forms;
13635 however, only one form can be used in any given program unit.
13637 @item @emph{Standard}:
13640 @item @emph{Class}:
13641 Subroutine, function
13643 @item @emph{Syntax}:
13644 @multitable @columnfractions .80
13645 @item @code{CALL UNLINK(PATH [, STATUS])}
13646 @item @code{STATUS = UNLINK(PATH)}
13649 @item @emph{Arguments}:
13650 @multitable @columnfractions .15 .70
13651 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
13652 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
13655 @item @emph{See also}:
13656 @ref{LINK}, @ref{SYMLNK}
13662 @section @code{UNPACK} --- Unpack an array of rank one into an array
13664 @cindex array, unpacking
13665 @cindex array, increase dimension
13666 @cindex array, scatter elements
13669 @item @emph{Description}:
13670 Store the elements of @var{VECTOR} in an array of higher rank.
13672 @item @emph{Standard}:
13673 Fortran 95 and later
13675 @item @emph{Class}:
13676 Transformational function
13678 @item @emph{Syntax}:
13679 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
13681 @item @emph{Arguments}:
13682 @multitable @columnfractions .15 .70
13683 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
13684 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
13685 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
13686 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
13687 the same shape as @var{MASK}.
13690 @item @emph{Return value}:
13691 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
13692 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
13694 @item @emph{Example}:
13696 PROGRAM test_unpack
13697 integer :: vector(2) = (/1,1/)
13698 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
13699 integer :: field(2,2) = 0, unity(2,2)
13701 ! result: unity matrix
13702 unity = unpack(vector, reshape(mask, (/2,2/)), field)
13706 @item @emph{See also}:
13707 @ref{PACK}, @ref{SPREAD}
13713 @section @code{VERIFY} --- Scan a string for characters not a given set
13715 @cindex string, find missing set
13718 @item @emph{Description}:
13719 Verifies that all the characters in @var{STRING} belong to the set of
13720 characters in @var{SET}.
13722 If @var{BACK} is either absent or equals @code{FALSE}, this function
13723 returns the position of the leftmost character of @var{STRING} that is
13724 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost
13725 position is returned. If all characters of @var{STRING} are found in
13726 @var{SET}, the result is zero.
13728 @item @emph{Standard}:
13729 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
13731 @item @emph{Class}:
13734 @item @emph{Syntax}:
13735 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
13737 @item @emph{Arguments}:
13738 @multitable @columnfractions .15 .70
13739 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
13740 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
13741 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
13742 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
13743 expression indicating the kind parameter of the result.
13746 @item @emph{Return value}:
13747 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
13748 @var{KIND} is absent, the return value is of default integer kind.
13750 @item @emph{Example}:
13752 PROGRAM test_verify
13753 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
13754 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
13755 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
13756 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
13757 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
13761 @item @emph{See also}:
13762 @ref{SCAN}, @ref{INDEX intrinsic}
13768 @section @code{XOR} --- Bitwise logical exclusive OR
13770 @cindex bitwise logical exclusive or
13771 @cindex logical exclusive or, bitwise
13774 @item @emph{Description}:
13775 Bitwise logical exclusive or.
13777 This intrinsic routine is provided for backwards compatibility with
13778 GNU Fortran 77. For integer arguments, programmers should consider
13779 the use of the @ref{IEOR} intrinsic and for logical arguments the
13780 @code{.NEQV.} operator, which are both defined by the Fortran standard.
13782 @item @emph{Standard}:
13785 @item @emph{Class}:
13788 @item @emph{Syntax}:
13789 @code{RESULT = XOR(I, J)}
13791 @item @emph{Arguments}:
13792 @multitable @columnfractions .15 .70
13793 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
13794 type or a scalar @code{LOGICAL} type.
13795 @item @var{J} @tab The type shall be the same as the type of @var{I}.
13798 @item @emph{Return value}:
13799 The return type is either a scalar @code{INTEGER} or a scalar
13800 @code{LOGICAL}. If the kind type parameters differ, then the
13801 smaller kind type is implicitly converted to larger kind, and the
13802 return has the larger kind.
13804 @item @emph{Example}:
13807 LOGICAL :: T = .TRUE., F = .FALSE.
13809 DATA a / Z'F' /, b / Z'3' /
13811 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
13812 WRITE (*,*) XOR(a, b)
13816 @item @emph{See also}:
13817 Fortran 95 elemental function: @ref{IEOR}
13822 @node Intrinsic Modules
13823 @chapter Intrinsic Modules
13824 @cindex intrinsic Modules
13827 * ISO_FORTRAN_ENV::
13830 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
13831 * OpenACC Module OPENACC::
13834 @node ISO_FORTRAN_ENV
13835 @section @code{ISO_FORTRAN_ENV}
13837 @item @emph{Standard}:
13838 Fortran 2003 and later, except when otherwise noted
13841 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
13845 @item @code{ATOMIC_INT_KIND}:
13846 Default-kind integer constant to be used as kind parameter when defining
13847 integer variables used in atomic operations. (Fortran 2008 or later.)
13849 @item @code{ATOMIC_LOGICAL_KIND}:
13850 Default-kind integer constant to be used as kind parameter when defining
13851 logical variables used in atomic operations. (Fortran 2008 or later.)
13853 @item @code{CHARACTER_KINDS}:
13854 Default-kind integer constant array of rank one containing the supported kind
13855 parameters of the @code{CHARACTER} type. (Fortran 2008 or later.)
13857 @item @code{CHARACTER_STORAGE_SIZE}:
13858 Size in bits of the character storage unit.
13860 @item @code{ERROR_UNIT}:
13861 Identifies the preconnected unit used for error reporting.
13863 @item @code{FILE_STORAGE_SIZE}:
13864 Size in bits of the file-storage unit.
13866 @item @code{INPUT_UNIT}:
13867 Identifies the preconnected unit identified by the asterisk
13868 (@code{*}) in @code{READ} statement.
13870 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
13871 Kind type parameters to specify an INTEGER type with a storage
13872 size of 16, 32, and 64 bits. It is negative if a target platform
13873 does not support the particular kind. (Fortran 2008 or later.)
13875 @item @code{INTEGER_KINDS}:
13876 Default-kind integer constant array of rank one containing the supported kind
13877 parameters of the @code{INTEGER} type. (Fortran 2008 or later.)
13879 @item @code{IOSTAT_END}:
13880 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
13881 an input/output statement if an end-of-file condition occurred.
13883 @item @code{IOSTAT_EOR}:
13884 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
13885 an input/output statement if an end-of-record condition occurred.
13887 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
13888 Scalar default-integer constant, used by @code{INQUIRE} for the
13889 @code{IOSTAT=} specifier to denote an that a unit number identifies an
13890 internal unit. (Fortran 2008 or later.)
13892 @item @code{NUMERIC_STORAGE_SIZE}:
13893 The size in bits of the numeric storage unit.
13895 @item @code{LOGICAL_KINDS}:
13896 Default-kind integer constant array of rank one containing the supported kind
13897 parameters of the @code{LOGICAL} type. (Fortran 2008 or later.)
13899 @item @code{OUTPUT_UNIT}:
13900 Identifies the preconnected unit identified by the asterisk
13901 (@code{*}) in @code{WRITE} statement.
13903 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
13904 Kind type parameters to specify a REAL type with a storage
13905 size of 32, 64, and 128 bits. It is negative if a target platform
13906 does not support the particular kind. (Fortran 2008 or later.)
13908 @item @code{REAL_KINDS}:
13909 Default-kind integer constant array of rank one containing the supported kind
13910 parameters of the @code{REAL} type. (Fortran 2008 or later.)
13912 @item @code{STAT_LOCKED}:
13913 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
13914 denote that the lock variable is locked by the executing image. (Fortran 2008
13917 @item @code{STAT_LOCKED_OTHER_IMAGE}:
13918 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
13919 denote that the lock variable is locked by another image. (Fortran 2008 or
13922 @item @code{STAT_STOPPED_IMAGE}:
13923 Positive, scalar default-integer constant used as STAT= return value if the
13924 argument in the statement requires synchronisation with an image, which has
13925 initiated the termination of the execution. (Fortran 2008 or later.)
13927 @item @code{STAT_FAILED_IMAGE}:
13928 Positive, scalar default-integer constant used as STAT= return value if the
13929 argument in the statement requires communication with an image, which has
13930 is in the failed state. (TS 18508 or later.)
13932 @item @code{STAT_UNLOCKED}:
13933 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
13934 denote that the lock variable is unlocked. (Fortran 2008 or later.)
13937 The module provides the following derived type:
13940 @item @code{LOCK_TYPE}:
13941 Derived type with private components to be use with the @code{LOCK} and
13942 @code{UNLOCK} statement. A variable of its type has to be always declared
13943 as coarray and may not appear in a variable-definition context.
13944 (Fortran 2008 or later.)
13947 The module also provides the following intrinsic procedures:
13948 @ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}.
13952 @node ISO_C_BINDING
13953 @section @code{ISO_C_BINDING}
13955 @item @emph{Standard}:
13956 Fortran 2003 and later, GNU extensions
13959 The following intrinsic procedures are provided by the module; their
13960 definition can be found in the section Intrinsic Procedures of this
13964 @item @code{C_ASSOCIATED}
13965 @item @code{C_F_POINTER}
13966 @item @code{C_F_PROCPOINTER}
13967 @item @code{C_FUNLOC}
13969 @item @code{C_SIZEOF}
13971 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
13972 @c don't really know why.
13974 The @code{ISO_C_BINDING} module provides the following named constants of
13975 type default integer, which can be used as KIND type parameters.
13977 In addition to the integer named constants required by the Fortran 2003
13978 standard and @code{C_PTRDIFF_T} of TS 29113, GNU Fortran provides as an
13979 extension named constants for the 128-bit integer types supported by the
13980 C compiler: @code{C_INT128_T, C_INT_LEAST128_T, C_INT_FAST128_T}.
13981 Furthermore, if @code{__float128} is supported in C, the named constants
13982 @code{C_FLOAT128, C_FLOAT128_COMPLEX} are defined.
13984 @multitable @columnfractions .15 .35 .35 .35
13985 @item Fortran Type @tab Named constant @tab C type @tab Extension
13986 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
13987 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
13988 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
13989 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
13990 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
13991 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
13992 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
13993 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
13994 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
13995 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
13996 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
13997 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
13998 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
13999 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
14000 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
14001 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
14002 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
14003 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
14004 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
14005 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
14006 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
14007 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
14008 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
14009 @item @code{INTEGER}@tab @code{C_PTRDIFF_T} @tab @code{intptr_t} @tab TS 29113
14010 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
14011 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
14012 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
14013 @item @code{REAL} @tab @code{C_FLOAT128} @tab @code{__float128} @tab Ext.
14014 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
14015 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
14016 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
14017 @item @code{REAL} @tab @code{C_FLOAT128_COMPLEX} @tab @code{__float128 _Complex} @tab Ext.
14018 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
14019 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
14022 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
14025 @multitable @columnfractions .20 .45 .15
14026 @item Name @tab C definition @tab Value
14027 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
14028 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
14029 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
14030 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
14031 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
14032 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
14033 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
14034 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
14037 Moreover, the following two named constants are defined:
14039 @multitable @columnfractions .20 .80
14040 @item Name @tab Type
14041 @item @code{C_NULL_PTR} @tab @code{C_PTR}
14042 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
14045 Both are equivalent to the value @code{NULL} in C.
14050 @section IEEE modules: @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
14052 @item @emph{Standard}:
14053 Fortran 2003 and later
14056 The @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
14057 intrinsic modules provide support for exceptions and IEEE arithmetic, as
14058 defined in Fortran 2003 and later standards, and the IEC 60559:1989 standard
14059 (@emph{Binary floating-point arithmetic for microprocessor systems}). These
14060 modules are only provided on the following supported platforms:
14063 @item i386 and x86_64 processors
14064 @item platforms which use the GNU C Library (glibc)
14065 @item platforms with support for SysV/386 routines for floating point
14066 interface (including Solaris and BSDs)
14067 @item platforms with the AIX OS
14070 For full compliance with the Fortran standards, code using the
14071 @code{IEEE_EXCEPTIONS} or @code{IEEE_ARITHMETIC} modules should be compiled
14072 with the following options: @code{-fno-unsafe-math-optimizations
14073 -frounding-math -fsignaling-nans}.
14077 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
14078 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
14080 @item @emph{Standard}:
14081 OpenMP Application Program Interface v4.0
14085 The OpenMP Fortran runtime library routines are provided both in
14086 a form of two Fortran 90 modules, named @code{OMP_LIB} and
14087 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
14088 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
14089 in the @ref{Top,,Introduction,libgomp,GNU Offloading and Multi
14090 Processing Runtime Library} manual,
14091 the named constants defined in the modules are listed
14094 For details refer to the actual
14095 @uref{http://www.openmp.org/mp-documents/OpenMP4.0.0.pdf,
14096 OpenMP Application Program Interface v4.0}.
14098 @code{OMP_LIB_KINDS} provides the following scalar default-integer
14102 @item @code{omp_lock_kind}
14103 @item @code{omp_nest_lock_kind}
14104 @item @code{omp_proc_bind_kind}
14105 @item @code{omp_sched_kind}
14108 @code{OMP_LIB} provides the scalar default-integer
14109 named constant @code{openmp_version} with a value of the form
14110 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
14111 of the OpenMP version; for OpenMP v4.0 the value is @code{201307}.
14113 The following scalar integer named constants of the
14114 kind @code{omp_sched_kind}:
14117 @item @code{omp_sched_static}
14118 @item @code{omp_sched_dynamic}
14119 @item @code{omp_sched_guided}
14120 @item @code{omp_sched_auto}
14123 And the following scalar integer named constants of the
14124 kind @code{omp_proc_bind_kind}:
14127 @item @code{omp_proc_bind_false}
14128 @item @code{omp_proc_bind_true}
14129 @item @code{omp_proc_bind_master}
14130 @item @code{omp_proc_bind_close}
14131 @item @code{omp_proc_bind_spread}
14136 @node OpenACC Module OPENACC
14137 @section OpenACC Module @code{OPENACC}
14139 @item @emph{Standard}:
14140 OpenACC Application Programming Interface v2.0
14144 The OpenACC Fortran runtime library routines are provided both in a
14145 form of a Fortran 90 module, named @code{OPENACC}, and in form of a
14146 Fortran @code{include} file named @file{openacc_lib.h}. The
14147 procedures provided by @code{OPENACC} can be found in the
14148 @ref{Top,,Introduction,libgomp,GNU Offloading and Multi Processing
14149 Runtime Library} manual, the named constants defined in the modules
14152 For details refer to the actual
14153 @uref{http://www.openacc.org/,
14154 OpenACC Application Programming Interface v2.0}.
14156 @code{OPENACC} provides the scalar default-integer
14157 named constant @code{openacc_version} with a value of the form
14158 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
14159 of the OpenACC version; for OpenACC v2.0 the value is @code{201306}.