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\acosd{\mathop{\rm acosd}\nolimits}
27 \gdef\asind{\mathop{\rm asind}\nolimits}
28 \gdef\atand{\mathop{\rm atand}\nolimits}
29 \gdef\acos{\mathop{\rm acos}\nolimits}
30 \gdef\asin{\mathop{\rm asin}\nolimits}
31 \gdef\atan{\mathop{\rm atan}\nolimits}
32 \gdef\acosh{\mathop{\rm acosh}\nolimits}
33 \gdef\asinh{\mathop{\rm asinh}\nolimits}
34 \gdef\atanh{\mathop{\rm atanh}\nolimits}
35 \gdef\cosd{\mathop{\rm cosd}\nolimits}
39 @node Intrinsic Procedures
40 @chapter Intrinsic Procedures
41 @cindex intrinsic procedures
44 * Introduction: Introduction to Intrinsics
45 * @code{ABORT}: ABORT, Abort the program
46 * @code{ABS}: ABS, Absolute value
47 * @code{ACCESS}: ACCESS, Checks file access modes
48 * @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence
49 * @code{ACOS}: ACOS, Arccosine function
50 * @code{ACOSD}: ACOSD, Arccosine function, degrees
51 * @code{ACOSH}: ACOSH, Inverse hyperbolic cosine function
52 * @code{ADJUSTL}: ADJUSTL, Left adjust a string
53 * @code{ADJUSTR}: ADJUSTR, Right adjust a string
54 * @code{AIMAG}: AIMAG, Imaginary part of complex number
55 * @code{AINT}: AINT, Truncate to a whole number
56 * @code{ALARM}: ALARM, Set an alarm clock
57 * @code{ALL}: ALL, Determine if all values are true
58 * @code{ALLOCATED}: ALLOCATED, Status of allocatable entity
59 * @code{AND}: AND, Bitwise logical AND
60 * @code{ANINT}: ANINT, Nearest whole number
61 * @code{ANY}: ANY, Determine if any values are true
62 * @code{ASIN}: ASIN, Arcsine function
63 * @code{ASIND}: ASIND, Arcsine function, degrees
64 * @code{ASINH}: ASINH, Inverse hyperbolic sine function
65 * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair
66 * @code{ATAN}: ATAN, Arctangent function
67 * @code{ATAND}: ATAND, Arctangent function, degrees
68 * @code{ATAN2}: ATAN2, Arctangent function
69 * @code{ATAN2D}: ATAN2D, Arctangent function, degrees
70 * @code{ATANH}: ATANH, Inverse hyperbolic tangent function
71 * @code{ATOMIC_ADD}: ATOMIC_ADD, Atomic ADD operation
72 * @code{ATOMIC_AND}: ATOMIC_AND, Atomic bitwise AND operation
73 * @code{ATOMIC_CAS}: ATOMIC_CAS, Atomic compare and swap
74 * @code{ATOMIC_DEFINE}: ATOMIC_DEFINE, Setting a variable atomically
75 * @code{ATOMIC_FETCH_ADD}: ATOMIC_FETCH_ADD, Atomic ADD operation with prior fetch
76 * @code{ATOMIC_FETCH_AND}: ATOMIC_FETCH_AND, Atomic bitwise AND operation with prior fetch
77 * @code{ATOMIC_FETCH_OR}: ATOMIC_FETCH_OR, Atomic bitwise OR operation with prior fetch
78 * @code{ATOMIC_FETCH_XOR}: ATOMIC_FETCH_XOR, Atomic bitwise XOR operation with prior fetch
79 * @code{ATOMIC_OR}: ATOMIC_OR, Atomic bitwise OR operation
80 * @code{ATOMIC_REF}: ATOMIC_REF, Obtaining the value of a variable atomically
81 * @code{ATOMIC_XOR}: ATOMIC_XOR, Atomic bitwise OR operation
82 * @code{BACKTRACE}: BACKTRACE, Show a backtrace
83 * @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0
84 * @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1
85 * @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind
86 * @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0
87 * @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1
88 * @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind
89 * @code{BGE}: BGE, Bitwise greater than or equal to
90 * @code{BGT}: BGT, Bitwise greater than
91 * @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function
92 * @code{BLE}: BLE, Bitwise less than or equal to
93 * @code{BLT}: BLT, Bitwise less than
94 * @code{BTEST}: BTEST, Bit test function
95 * @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer
96 * @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer
97 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
98 * @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure
99 * @code{C_LOC}: C_LOC, Obtain the C address of an object
100 * @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression
101 * @code{CEILING}: CEILING, Integer ceiling function
102 * @code{CHAR}: CHAR, Integer-to-character conversion function
103 * @code{CHDIR}: CHDIR, Change working directory
104 * @code{CHMOD}: CHMOD, Change access permissions of files
105 * @code{CMPLX}: CMPLX, Complex conversion function
106 * @code{CO_BROADCAST}: CO_BROADCAST, Copy a value to all images the current set of images
107 * @code{CO_MAX}: CO_MAX, Maximal value on the current set of images
108 * @code{CO_MIN}: CO_MIN, Minimal value on the current set of images
109 * @code{CO_REDUCE}: CO_REDUCE, Reduction of values on the current set of images
110 * @code{CO_SUM}: CO_SUM, Sum of values on the current set of images
111 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
112 * @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler
113 * @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string
114 * @code{COMPLEX}: COMPLEX, Complex conversion function
115 * @code{CONJG}: CONJG, Complex conjugate function
116 * @code{COS}: COS, Cosine function
117 * @code{COSD}: COSD, Cosine function, degrees
118 * @code{COSH}: COSH, Hyperbolic cosine function
119 * @code{COTAN}: COTAN, Cotangent function
120 * @code{COTAND}: COTAND, Cotangent function, degrees
121 * @code{COUNT}: COUNT, Count occurrences of TRUE in an array
122 * @code{CPU_TIME}: CPU_TIME, CPU time subroutine
123 * @code{CSHIFT}: CSHIFT, Circular shift elements of an array
124 * @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string
125 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
126 * @code{DBLE}: DBLE, Double precision conversion function
127 * @code{DCMPLX}: DCMPLX, Double complex conversion function
128 * @code{DIGITS}: DIGITS, Significant digits function
129 * @code{DIM}: DIM, Positive difference
130 * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
131 * @code{DPROD}: DPROD, Double product function
132 * @code{DREAL}: DREAL, Double real part function
133 * @code{DSHIFTL}: DSHIFTL, Combined left shift
134 * @code{DSHIFTR}: DSHIFTR, Combined right shift
135 * @code{DTIME}: DTIME, Execution time subroutine (or function)
136 * @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array
137 * @code{EPSILON}: EPSILON, Epsilon function
138 * @code{ERF}: ERF, Error function
139 * @code{ERFC}: ERFC, Complementary error function
140 * @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function
141 * @code{ETIME}: ETIME, Execution time subroutine (or function)
142 * @code{EVENT_QUERY}: EVENT_QUERY, Query whether a coarray event has occurred
143 * @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command
144 * @code{EXIT}: EXIT, Exit the program with status.
145 * @code{EXP}: EXP, Exponential function
146 * @code{EXPONENT}: EXPONENT, Exponent function
147 * @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF, Query dynamic type for extension
148 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
149 * @code{FGET}: FGET, Read a single character in stream mode from stdin
150 * @code{FGETC}: FGETC, Read a single character in stream mode
151 * @code{FLOOR}: FLOOR, Integer floor function
152 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
153 * @code{FNUM}: FNUM, File number function
154 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
155 * @code{FPUTC}: FPUTC, Write a single character in stream mode
156 * @code{FRACTION}: FRACTION, Fractional part of the model representation
157 * @code{FREE}: FREE, Memory de-allocation subroutine
158 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
159 * @code{FSTAT}: FSTAT, Get file status
160 * @code{FTELL}: FTELL, Current stream position
161 * @code{GAMMA}: GAMMA, Gamma function
162 * @code{GERROR}: GERROR, Get last system error message
163 * @code{GETARG}: GETARG, Get command line arguments
164 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
165 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
166 * @code{GETCWD}: GETCWD, Get current working directory
167 * @code{GETENV}: GETENV, Get an environmental variable
168 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
169 * @code{GETGID}: GETGID, Group ID function
170 * @code{GETLOG}: GETLOG, Get login name
171 * @code{GETPID}: GETPID, Process ID function
172 * @code{GETUID}: GETUID, User ID function
173 * @code{GMTIME}: GMTIME, Convert time to GMT info
174 * @code{HOSTNM}: HOSTNM, Get system host name
175 * @code{HUGE}: HUGE, Largest number of a kind
176 * @code{HYPOT}: HYPOT, Euclidean distance function
177 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
178 * @code{IALL}: IALL, Bitwise AND of array elements
179 * @code{IAND}: IAND, Bitwise logical and
180 * @code{IANY}: IANY, Bitwise OR of array elements
181 * @code{IARGC}: IARGC, Get the number of command line arguments
182 * @code{IBCLR}: IBCLR, Clear bit
183 * @code{IBITS}: IBITS, Bit extraction
184 * @code{IBSET}: IBSET, Set bit
185 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
186 * @code{IDATE}: IDATE, Current local time (day/month/year)
187 * @code{IEOR}: IEOR, Bitwise logical exclusive or
188 * @code{IERRNO}: IERRNO, Function to get the last system error number
189 * @code{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index conversion
190 * @code{INDEX}: INDEX intrinsic, Position of a substring within a string
191 * @code{INT}: INT, Convert to integer type
192 * @code{INT2}: INT2, Convert to 16-bit integer type
193 * @code{INT8}: INT8, Convert to 64-bit integer type
194 * @code{IOR}: IOR, Bitwise logical or
195 * @code{IPARITY}: IPARITY, Bitwise XOR of array elements
196 * @code{IRAND}: IRAND, Integer pseudo-random number
197 * @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value
198 * @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value
199 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
200 * @code{ISHFT}: ISHFT, Shift bits
201 * @code{ISHFTC}: ISHFTC, Shift bits circularly
202 * @code{ISNAN}: ISNAN, Tests for a NaN
203 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
204 * @code{KILL}: KILL, Send a signal to a process
205 * @code{KIND}: KIND, Kind of an entity
206 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
207 * @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array
208 * @code{LEADZ}: LEADZ, Number of leading zero bits of an integer
209 * @code{LEN}: LEN, Length of a character entity
210 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
211 * @code{LGE}: LGE, Lexical greater than or equal
212 * @code{LGT}: LGT, Lexical greater than
213 * @code{LINK}: LINK, Create a hard link
214 * @code{LLE}: LLE, Lexical less than or equal
215 * @code{LLT}: LLT, Lexical less than
216 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
217 * @code{LOC}: LOC, Returns the address of a variable
218 * @code{LOG}: LOG, Logarithm function
219 * @code{LOG10}: LOG10, Base 10 logarithm function
220 * @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
221 * @code{LOGICAL}: LOGICAL, Convert to logical type
222 * @code{LONG}: LONG, Convert to integer type
223 * @code{LSHIFT}: LSHIFT, Left shift bits
224 * @code{LSTAT}: LSTAT, Get file status
225 * @code{LTIME}: LTIME, Convert time to local time info
226 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
227 * @code{MASKL}: MASKL, Left justified mask
228 * @code{MASKR}: MASKR, Right justified mask
229 * @code{MATMUL}: MATMUL, matrix multiplication
230 * @code{MAX}: MAX, Maximum value of an argument list
231 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
232 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
233 * @code{MAXVAL}: MAXVAL, Maximum value of an array
234 * @code{MCLOCK}: MCLOCK, Time function
235 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
236 * @code{MERGE}: MERGE, Merge arrays
237 * @code{MERGE_BITS}: MERGE_BITS, Merge of bits under mask
238 * @code{MIN}: MIN, Minimum value of an argument list
239 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
240 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
241 * @code{MINVAL}: MINVAL, Minimum value of an array
242 * @code{MOD}: MOD, Remainder function
243 * @code{MODULO}: MODULO, Modulo function
244 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
245 * @code{MVBITS}: MVBITS, Move bits from one integer to another
246 * @code{NEAREST}: NEAREST, Nearest representable number
247 * @code{NEW_LINE}: NEW_LINE, New line character
248 * @code{NINT}: NINT, Nearest whole number
249 * @code{NORM2}: NORM2, Euclidean vector norm
250 * @code{NOT}: NOT, Logical negation
251 * @code{NULL}: NULL, Function that returns an disassociated pointer
252 * @code{NUM_IMAGES}: NUM_IMAGES, Number of images
253 * @code{OR}: OR, Bitwise logical OR
254 * @code{PACK}: PACK, Pack an array into an array of rank one
255 * @code{PARITY}: PARITY, Reduction with exclusive OR
256 * @code{PERROR}: PERROR, Print system error message
257 * @code{POPCNT}: POPCNT, Number of bits set
258 * @code{POPPAR}: POPPAR, Parity of the number of bits set
259 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
260 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
261 * @code{PRODUCT}: PRODUCT, Product of array elements
262 * @code{RADIX}: RADIX, Base of a data model
263 * @code{RAN}: RAN, Real pseudo-random number
264 * @code{RAND}: RAND, Real pseudo-random number
265 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
266 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
267 * @code{RANGE}: RANGE, Decimal exponent range
268 * @code{RANK} : RANK, Rank of a data object
269 * @code{REAL}: REAL, Convert to real type
270 * @code{RENAME}: RENAME, Rename a file
271 * @code{REPEAT}: REPEAT, Repeated string concatenation
272 * @code{RESHAPE}: RESHAPE, Function to reshape an array
273 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
274 * @code{RSHIFT}: RSHIFT, Right shift bits
275 * @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality
276 * @code{SCALE}: SCALE, Scale a real value
277 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
278 * @code{SECNDS}: SECNDS, Time function
279 * @code{SECOND}: SECOND, CPU time function
280 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind
281 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
282 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
283 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
284 * @code{SHAPE}: SHAPE, Determine the shape of an array
285 * @code{SHIFTA}: SHIFTA, Right shift with fill
286 * @code{SHIFTL}: SHIFTL, Left shift
287 * @code{SHIFTR}: SHIFTR, Right shift
288 * @code{SIGN}: SIGN, Sign copying function
289 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
290 * @code{SIN}: SIN, Sine function
291 * @code{SIND}: SIND, Sine function, degrees
292 * @code{SINH}: SINH, Hyperbolic sine function
293 * @code{SIZE}: SIZE, Function to determine the size of an array
294 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
295 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
296 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
297 * @code{SPREAD}: SPREAD, Add a dimension to an array
298 * @code{SQRT}: SQRT, Square-root function
299 * @code{SRAND}: SRAND, Reinitialize the random number generator
300 * @code{STAT}: STAT, Get file status
301 * @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits
302 * @code{SUM}: SUM, Sum of array elements
303 * @code{SYMLNK}: SYMLNK, Create a symbolic link
304 * @code{SYSTEM}: SYSTEM, Execute a shell command
305 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
306 * @code{TAN}: TAN, Tangent function
307 * @code{TAND}: TAND, Tangent function, degrees
308 * @code{TANH}: TANH, Hyperbolic tangent function
309 * @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image
310 * @code{TIME}: TIME, Time function
311 * @code{TIME8}: TIME8, Time function (64-bit)
312 * @code{TINY}: TINY, Smallest positive number of a real kind
313 * @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer
314 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
315 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
316 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
317 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
318 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
319 * @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array
320 * @code{UMASK}: UMASK, Set the file creation mask
321 * @code{UNLINK}: UNLINK, Remove a file from the file system
322 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
323 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
324 * @code{XOR}: XOR, Bitwise logical exclusive or
327 @node Introduction to Intrinsics
328 @section Introduction to intrinsic procedures
330 The intrinsic procedures provided by GNU Fortran include all of the
331 intrinsic procedures required by the Fortran 95 standard, a set of
332 intrinsic procedures for backwards compatibility with G77, and a
333 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
334 standards. Any conflict between a description here and a description in
335 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
336 2008 standard is unintentional, and the standard(s) should be considered
339 The enumeration of the @code{KIND} type parameter is processor defined in
340 the Fortran 95 standard. GNU Fortran defines the default integer type and
341 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
342 respectively. The standard mandates that both data types shall have
343 another kind, which have more precision. On typical target architectures
344 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
345 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
346 In the description of generic intrinsic procedures, the kind type parameter
347 will be specified by @code{KIND=*}, and in the description of specific
348 names for an intrinsic procedure the kind type parameter will be explicitly
349 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
350 brevity the optional @code{KIND=} syntax will be omitted.
352 Many of the intrinsic procedures take one or more optional arguments.
353 This document follows the convention used in the Fortran 95 standard,
354 and denotes such arguments by square brackets.
356 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
357 which can be used to restrict the set of intrinsic procedures to a
358 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
359 option, and so all intrinsic procedures described here are accepted. There
360 is one caveat. For a select group of intrinsic procedures, @command{g77}
361 implemented both a function and a subroutine. Both classes
362 have been implemented in @command{gfortran} for backwards compatibility
363 with @command{g77}. It is noted here that these functions and subroutines
364 cannot be intermixed in a given subprogram. In the descriptions that follow,
365 the applicable standard for each intrinsic procedure is noted.
370 @section @code{ABORT} --- Abort the program
372 @cindex program termination, with core dump
373 @cindex terminate program, with core dump
377 @item @emph{Description}:
378 @code{ABORT} causes immediate termination of the program. On operating
379 systems that support a core dump, @code{ABORT} will produce a core dump.
380 It will also print a backtrace, unless @code{-fno-backtrace} is given.
382 @item @emph{Standard}:
391 @item @emph{Return value}:
394 @item @emph{Example}:
397 integer :: i = 1, j = 2
398 if (i /= j) call abort
399 end program test_abort
402 @item @emph{See also}:
403 @ref{EXIT}, @ref{KILL}, @ref{BACKTRACE}
410 @section @code{ABS} --- Absolute value
421 @cindex absolute value
424 @item @emph{Description}:
425 @code{ABS(A)} computes the absolute value of @code{A}.
427 @item @emph{Standard}:
428 Fortran 77 and later, has overloads that are GNU extensions
434 @code{RESULT = ABS(A)}
436 @item @emph{Arguments}:
437 @multitable @columnfractions .15 .70
438 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
439 @code{REAL}, or @code{COMPLEX}.
442 @item @emph{Return value}:
443 The return value is of the same type and
444 kind as the argument except the return value is @code{REAL} for a
445 @code{COMPLEX} argument.
447 @item @emph{Example}:
452 complex :: z = (-1.e0,0.e0)
459 @item @emph{Specific names}:
460 @multitable @columnfractions .20 .20 .20 .25
461 @item Name @tab Argument @tab Return type @tab Standard
462 @item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
463 @item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
464 @item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
465 @item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
466 @item @code{BABS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
467 @item @code{IIABS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
468 @item @code{JIABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
469 @item @code{KIABS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
470 @item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
471 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
478 @section @code{ACCESS} --- Checks file access modes
480 @cindex file system, access mode
483 @item @emph{Description}:
484 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
485 exists, is readable, writable or executable. Except for the
486 executable check, @code{ACCESS} can be replaced by
487 Fortran 95's @code{INQUIRE}.
489 @item @emph{Standard}:
496 @code{RESULT = ACCESS(NAME, MODE)}
498 @item @emph{Arguments}:
499 @multitable @columnfractions .15 .70
500 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
501 file name. Tailing blank are ignored unless the character @code{achar(0)}
502 is present, then all characters up to and excluding @code{achar(0)} are
504 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
505 file access mode, may be any concatenation of @code{"r"} (readable),
506 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
510 @item @emph{Return value}:
511 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
512 accessible in the given mode; otherwise or if an invalid argument
513 has been given for @code{MODE} the value @code{1} is returned.
515 @item @emph{Example}:
519 character(len=*), parameter :: file = 'test.dat'
520 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
521 if(access(file,' ') == 0) print *, trim(file),' is exists'
522 if(access(file,'r') == 0) print *, trim(file),' is readable'
523 if(access(file,'w') == 0) print *, trim(file),' is writable'
524 if(access(file,'x') == 0) print *, trim(file),' is executable'
525 if(access(file2,'rwx') == 0) &
526 print *, trim(file2),' is readable, writable and executable'
527 end program access_test
529 @item @emph{Specific names}:
530 @item @emph{See also}:
537 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
539 @cindex @acronym{ASCII} collating sequence
540 @cindex collating sequence, @acronym{ASCII}
543 @item @emph{Description}:
544 @code{ACHAR(I)} returns the character located at position @code{I}
545 in the @acronym{ASCII} collating sequence.
547 @item @emph{Standard}:
548 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
554 @code{RESULT = ACHAR(I [, KIND])}
556 @item @emph{Arguments}:
557 @multitable @columnfractions .15 .70
558 @item @var{I} @tab The type shall be @code{INTEGER}.
559 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
560 expression indicating the kind parameter of the result.
563 @item @emph{Return value}:
564 The return value is of type @code{CHARACTER} with a length of one.
565 If the @var{KIND} argument is present, the return value is of the
566 specified kind and of the default kind otherwise.
568 @item @emph{Example}:
573 end program test_achar
577 See @ref{ICHAR} for a discussion of converting between numerical values
578 and formatted string representations.
580 @item @emph{See also}:
581 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
588 @section @code{ACOS} --- Arccosine function
591 @cindex trigonometric function, cosine, inverse
592 @cindex cosine, inverse
595 @item @emph{Description}:
596 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
598 @item @emph{Standard}:
599 Fortran 77 and later, for a complex argument Fortran 2008 or later
605 @code{RESULT = ACOS(X)}
607 @item @emph{Arguments}:
608 @multitable @columnfractions .15 .70
609 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
610 less than or equal to one - or the type shall be @code{COMPLEX}.
613 @item @emph{Return value}:
614 The return value is of the same type and kind as @var{X}.
615 The real part of the result is in radians and lies in the range
616 @math{0 \leq \Re \acos(x) \leq \pi}.
618 @item @emph{Example}:
621 real(8) :: x = 0.866_8
623 end program test_acos
626 @item @emph{Specific names}:
627 @multitable @columnfractions .20 .20 .20 .25
628 @item Name @tab Argument @tab Return type @tab Standard
629 @item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
630 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
633 @item @emph{See also}:
634 Inverse function: @ref{COS}
635 Degrees function: @ref{ACOSD}
642 @section @code{ACOSD} --- Arccosine function, degrees
645 @cindex trigonometric function, cosine, inverse, degrees
646 @cindex cosine, inverse, degrees
649 @item @emph{Description}:
650 @code{ACOSD(X)} computes the arccosine of @var{X} in degrees (inverse of
653 This function is for compatibility only and should be avoided in favor of
654 standard constructs wherever possible.
656 @item @emph{Standard}:
657 GNU Extension, enabled with @option{-fdec-math}
663 @code{RESULT = ACOSD(X)}
665 @item @emph{Arguments}:
666 @multitable @columnfractions .15 .70
667 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
668 less than or equal to one - or the type shall be @code{COMPLEX}.
671 @item @emph{Return value}:
672 The return value is of the same type and kind as @var{X}.
673 The real part of the result is in degrees and lies in the range
674 @math{0 \leq \Re \acos(x) \leq 180}.
676 @item @emph{Example}:
679 real(8) :: x = 0.866_8
681 end program test_acosd
684 @item @emph{Specific names}:
685 @multitable @columnfractions .20 .20 .20 .25
686 @item Name @tab Argument @tab Return type @tab Standard
687 @item @code{ACOSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
688 @item @code{DACOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
691 @item @emph{See also}:
692 Inverse function: @ref{COSD}
693 Radians function: @ref{ACOS}
700 @section @code{ACOSH} --- Inverse hyperbolic cosine function
703 @cindex area hyperbolic cosine
704 @cindex inverse hyperbolic cosine
705 @cindex hyperbolic function, cosine, inverse
706 @cindex cosine, hyperbolic, inverse
709 @item @emph{Description}:
710 @code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
712 @item @emph{Standard}:
713 Fortran 2008 and later
719 @code{RESULT = ACOSH(X)}
721 @item @emph{Arguments}:
722 @multitable @columnfractions .15 .70
723 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
726 @item @emph{Return value}:
727 The return value has the same type and kind as @var{X}. If @var{X} is
728 complex, the imaginary part of the result is in radians and lies between
729 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
731 @item @emph{Example}:
734 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
739 @item @emph{Specific names}:
740 @multitable @columnfractions .20 .20 .20 .25
741 @item Name @tab Argument @tab Return type @tab Standard
742 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
745 @item @emph{See also}:
746 Inverse function: @ref{COSH}
752 @section @code{ADJUSTL} --- Left adjust a string
754 @cindex string, adjust left
755 @cindex adjust string
758 @item @emph{Description}:
759 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
760 Spaces are inserted at the end of the string as needed.
762 @item @emph{Standard}:
769 @code{RESULT = ADJUSTL(STRING)}
771 @item @emph{Arguments}:
772 @multitable @columnfractions .15 .70
773 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
776 @item @emph{Return value}:
777 The return value is of type @code{CHARACTER} and of the same kind as
778 @var{STRING} where leading spaces are removed and the same number of
779 spaces are inserted on the end of @var{STRING}.
781 @item @emph{Example}:
784 character(len=20) :: str = ' gfortran'
787 end program test_adjustl
790 @item @emph{See also}:
791 @ref{ADJUSTR}, @ref{TRIM}
797 @section @code{ADJUSTR} --- Right adjust a string
799 @cindex string, adjust right
800 @cindex adjust string
803 @item @emph{Description}:
804 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
805 Spaces are inserted at the start of the string as needed.
807 @item @emph{Standard}:
814 @code{RESULT = ADJUSTR(STRING)}
816 @item @emph{Arguments}:
817 @multitable @columnfractions .15 .70
818 @item @var{STR} @tab The type shall be @code{CHARACTER}.
821 @item @emph{Return value}:
822 The return value is of type @code{CHARACTER} and of the same kind as
823 @var{STRING} where trailing spaces are removed and the same number of
824 spaces are inserted at the start of @var{STRING}.
826 @item @emph{Example}:
829 character(len=20) :: str = 'gfortran'
832 end program test_adjustr
835 @item @emph{See also}:
836 @ref{ADJUSTL}, @ref{TRIM}
842 @section @code{AIMAG} --- Imaginary part of complex number
847 @cindex complex numbers, imaginary part
850 @item @emph{Description}:
851 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
852 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
853 for compatibility with @command{g77}, and their use in new code is
854 strongly discouraged.
856 @item @emph{Standard}:
857 Fortran 77 and later, has overloads that are GNU extensions
863 @code{RESULT = AIMAG(Z)}
865 @item @emph{Arguments}:
866 @multitable @columnfractions .15 .70
867 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
870 @item @emph{Return value}:
871 The return value is of type @code{REAL} with the
872 kind type parameter of the argument.
874 @item @emph{Example}:
879 z4 = cmplx(1.e0_4, 0.e0_4)
880 z8 = cmplx(0.e0_8, 1.e0_8)
881 print *, aimag(z4), dimag(z8)
882 end program test_aimag
885 @item @emph{Specific names}:
886 @multitable @columnfractions .20 .20 .20 .25
887 @item Name @tab Argument @tab Return type @tab Standard
888 @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
889 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
890 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
891 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
898 @section @code{AINT} --- Truncate to a whole number
902 @cindex rounding, floor
905 @item @emph{Description}:
906 @code{AINT(A [, KIND])} truncates its argument to a whole number.
908 @item @emph{Standard}:
915 @code{RESULT = AINT(A [, KIND])}
917 @item @emph{Arguments}:
918 @multitable @columnfractions .15 .70
919 @item @var{A} @tab The type of the argument shall be @code{REAL}.
920 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
921 expression indicating the kind parameter of the result.
924 @item @emph{Return value}:
925 The return value is of type @code{REAL} with the kind type parameter of the
926 argument if the optional @var{KIND} is absent; otherwise, the kind
927 type parameter will be given by @var{KIND}. If the magnitude of
928 @var{X} is less than one, @code{AINT(X)} returns zero. If the
929 magnitude is equal to or greater than one then it returns the largest
930 whole number that does not exceed its magnitude. The sign is the same
931 as the sign of @var{X}.
933 @item @emph{Example}:
940 print *, aint(x4), dint(x8)
942 end program test_aint
945 @item @emph{Specific names}:
946 @multitable @columnfractions .20 .20 .20 .25
947 @item Name @tab Argument @tab Return type @tab Standard
948 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
949 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
956 @section @code{ALARM} --- Execute a routine after a given delay
958 @cindex delayed execution
961 @item @emph{Description}:
962 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
963 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
964 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
965 supplied, it will be returned with the number of seconds remaining until
966 any previously scheduled alarm was due to be delivered, or zero if there
967 was no previously scheduled alarm.
969 @item @emph{Standard}:
976 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
978 @item @emph{Arguments}:
979 @multitable @columnfractions .15 .70
980 @item @var{SECONDS} @tab The type of the argument shall be a scalar
981 @code{INTEGER}. It is @code{INTENT(IN)}.
982 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
983 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
984 values may be either @code{SIG_IGN=1} to ignore the alarm generated
985 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
986 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
987 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
990 @item @emph{Example}:
993 external handler_print
995 call alarm (3, handler_print, i)
998 end program test_alarm
1000 This will cause the external routine @var{handler_print} to be called
1007 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
1009 @cindex array, apply condition
1010 @cindex array, condition testing
1013 @item @emph{Description}:
1014 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
1015 in the array along dimension @var{DIM}.
1017 @item @emph{Standard}:
1018 Fortran 95 and later
1021 Transformational function
1023 @item @emph{Syntax}:
1024 @code{RESULT = ALL(MASK [, DIM])}
1026 @item @emph{Arguments}:
1027 @multitable @columnfractions .15 .70
1028 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1029 it shall not be scalar.
1030 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1031 with a value that lies between one and the rank of @var{MASK}.
1034 @item @emph{Return value}:
1035 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
1036 the kind type parameter is the same as the kind type parameter of
1037 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
1038 an array with the rank of @var{MASK} minus 1. The shape is determined from
1039 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1043 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
1044 It also is true if @var{MASK} has zero size; otherwise, it is false.
1046 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
1047 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
1048 is determined by applying @code{ALL} to the array sections.
1051 @item @emph{Example}:
1055 l = all((/.true., .true., .true./))
1060 integer a(2,3), b(2,3)
1064 print *, all(a .eq. b, 1)
1065 print *, all(a .eq. b, 2)
1066 end subroutine section
1067 end program test_all
1074 @section @code{ALLOCATED} --- Status of an allocatable entity
1076 @cindex allocation, status
1079 @item @emph{Description}:
1080 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
1081 status of @var{ARRAY} and @var{SCALAR}, respectively.
1083 @item @emph{Standard}:
1084 Fortran 95 and later. Note, the @code{SCALAR=} keyword and allocatable
1085 scalar entities are available in Fortran 2003 and later.
1090 @item @emph{Syntax}:
1091 @multitable @columnfractions .80
1092 @item @code{RESULT = ALLOCATED(ARRAY)}
1093 @item @code{RESULT = ALLOCATED(SCALAR)}
1096 @item @emph{Arguments}:
1097 @multitable @columnfractions .15 .70
1098 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
1099 @item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar.
1102 @item @emph{Return value}:
1103 The return value is a scalar @code{LOGICAL} with the default logical
1104 kind type parameter. If the argument is allocated, then the result is
1105 @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
1107 @item @emph{Example}:
1109 program test_allocated
1111 real(4), allocatable :: x(:)
1112 if (.not. allocated(x)) allocate(x(i))
1113 end program test_allocated
1120 @section @code{AND} --- Bitwise logical AND
1122 @cindex bitwise logical and
1123 @cindex logical and, bitwise
1126 @item @emph{Description}:
1127 Bitwise logical @code{AND}.
1129 This intrinsic routine is provided for backwards compatibility with
1130 GNU Fortran 77. For integer arguments, programmers should consider
1131 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1133 @item @emph{Standard}:
1139 @item @emph{Syntax}:
1140 @code{RESULT = AND(I, J)}
1142 @item @emph{Arguments}:
1143 @multitable @columnfractions .15 .70
1144 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1145 type or a scalar @code{LOGICAL} type.
1146 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1149 @item @emph{Return value}:
1150 The return type is either a scalar @code{INTEGER} or a scalar
1151 @code{LOGICAL}. If the kind type parameters differ, then the
1152 smaller kind type is implicitly converted to larger kind, and the
1153 return has the larger kind.
1155 @item @emph{Example}:
1158 LOGICAL :: T = .TRUE., F = .FALSE.
1160 DATA a / Z'F' /, b / Z'3' /
1162 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1163 WRITE (*,*) AND(a, b)
1167 @item @emph{See also}:
1168 Fortran 95 elemental function: @ref{IAND}
1174 @section @code{ANINT} --- Nearest whole number
1178 @cindex rounding, ceiling
1181 @item @emph{Description}:
1182 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1184 @item @emph{Standard}:
1185 Fortran 77 and later
1190 @item @emph{Syntax}:
1191 @code{RESULT = ANINT(A [, KIND])}
1193 @item @emph{Arguments}:
1194 @multitable @columnfractions .15 .70
1195 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1196 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1197 expression indicating the kind parameter of the result.
1200 @item @emph{Return value}:
1201 The return value is of type real with the kind type parameter of the
1202 argument if the optional @var{KIND} is absent; otherwise, the kind
1203 type parameter will be given by @var{KIND}. If @var{A} is greater than
1204 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1205 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1207 @item @emph{Example}:
1214 print *, anint(x4), dnint(x8)
1216 end program test_anint
1219 @item @emph{Specific names}:
1220 @multitable @columnfractions .20 .20 .20 .25
1221 @item Name @tab Argument @tab Return type @tab Standard
1222 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
1223 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1230 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1232 @cindex array, apply condition
1233 @cindex array, condition testing
1236 @item @emph{Description}:
1237 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1238 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1240 @item @emph{Standard}:
1241 Fortran 95 and later
1244 Transformational function
1246 @item @emph{Syntax}:
1247 @code{RESULT = ANY(MASK [, DIM])}
1249 @item @emph{Arguments}:
1250 @multitable @columnfractions .15 .70
1251 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1252 it shall not be scalar.
1253 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1254 with a value that lies between one and the rank of @var{MASK}.
1257 @item @emph{Return value}:
1258 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1259 the kind type parameter is the same as the kind type parameter of
1260 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1261 an array with the rank of @var{MASK} minus 1. The shape is determined from
1262 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1266 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1267 otherwise, it is false. It also is false if @var{MASK} has zero size.
1269 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1270 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1271 is determined by applying @code{ANY} to the array sections.
1274 @item @emph{Example}:
1278 l = any((/.true., .true., .true./))
1283 integer a(2,3), b(2,3)
1287 print *, any(a .eq. b, 1)
1288 print *, any(a .eq. b, 2)
1289 end subroutine section
1290 end program test_any
1297 @section @code{ASIN} --- Arcsine function
1300 @cindex trigonometric function, sine, inverse
1301 @cindex sine, inverse
1304 @item @emph{Description}:
1305 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1307 @item @emph{Standard}:
1308 Fortran 77 and later, for a complex argument Fortran 2008 or later
1313 @item @emph{Syntax}:
1314 @code{RESULT = ASIN(X)}
1316 @item @emph{Arguments}:
1317 @multitable @columnfractions .15 .70
1318 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1319 less than or equal to one - or be @code{COMPLEX}.
1322 @item @emph{Return value}:
1323 The return value is of the same type and kind as @var{X}.
1324 The real part of the result is in radians and lies in the range
1325 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1327 @item @emph{Example}:
1330 real(8) :: x = 0.866_8
1332 end program test_asin
1335 @item @emph{Specific names}:
1336 @multitable @columnfractions .20 .20 .20 .25
1337 @item Name @tab Argument @tab Return type @tab Standard
1338 @item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1339 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1342 @item @emph{See also}:
1343 Inverse function: @ref{SIN}
1344 Degrees function: @ref{ASIND}
1351 @section @code{ASIND} --- Arcsine function, degrees
1354 @cindex trigonometric function, sine, inverse, degrees
1355 @cindex sine, inverse, degrees
1358 @item @emph{Description}:
1359 @code{ASIND(X)} computes the arcsine of its @var{X} in degrees (inverse of
1362 This function is for compatibility only and should be avoided in favor of
1363 standard constructs wherever possible.
1365 @item @emph{Standard}:
1366 GNU Extension, enabled with @option{-fdec-math}.
1371 @item @emph{Syntax}:
1372 @code{RESULT = ASIND(X)}
1374 @item @emph{Arguments}:
1375 @multitable @columnfractions .15 .70
1376 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1377 less than or equal to one - or be @code{COMPLEX}.
1380 @item @emph{Return value}:
1381 The return value is of the same type and kind as @var{X}.
1382 The real part of the result is in degrees and lies in the range
1383 @math{-90 \leq \Re \asin(x) \leq 90}.
1385 @item @emph{Example}:
1388 real(8) :: x = 0.866_8
1390 end program test_asind
1393 @item @emph{Specific names}:
1394 @multitable @columnfractions .20 .20 .20 .25
1395 @item Name @tab Argument @tab Return type @tab Standard
1396 @item @code{ASIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
1397 @item @code{DASIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
1400 @item @emph{See also}:
1401 Inverse function: @ref{SIND}
1402 Radians function: @ref{ASIN}
1409 @section @code{ASINH} --- Inverse hyperbolic sine function
1412 @cindex area hyperbolic sine
1413 @cindex inverse hyperbolic sine
1414 @cindex hyperbolic function, sine, inverse
1415 @cindex sine, hyperbolic, inverse
1418 @item @emph{Description}:
1419 @code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
1421 @item @emph{Standard}:
1422 Fortran 2008 and later
1427 @item @emph{Syntax}:
1428 @code{RESULT = ASINH(X)}
1430 @item @emph{Arguments}:
1431 @multitable @columnfractions .15 .70
1432 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1435 @item @emph{Return value}:
1436 The return value is of the same type and kind as @var{X}. If @var{X} is
1437 complex, the imaginary part of the result is in radians and lies between
1438 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1440 @item @emph{Example}:
1443 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1444 WRITE (*,*) ASINH(x)
1448 @item @emph{Specific names}:
1449 @multitable @columnfractions .20 .20 .20 .25
1450 @item Name @tab Argument @tab Return type @tab Standard
1451 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1454 @item @emph{See also}:
1455 Inverse function: @ref{SINH}
1461 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1463 @cindex pointer, status
1464 @cindex association status
1467 @item @emph{Description}:
1468 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1469 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1471 @item @emph{Standard}:
1472 Fortran 95 and later
1477 @item @emph{Syntax}:
1478 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1480 @item @emph{Arguments}:
1481 @multitable @columnfractions .15 .70
1482 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1483 and it can be of any type.
1484 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1485 a target. It must have the same type, kind type parameter, and
1486 array rank as @var{POINTER}.
1488 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1491 @item @emph{Return value}:
1492 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1493 There are several cases:
1495 @item (A) When the optional @var{TARGET} is not present then
1496 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1497 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1498 @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
1499 disassociated, the result is false.
1500 @item (C) If @var{TARGET} is present and an array target, the result is true if
1501 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1502 are arrays whose elements are not zero-sized storage sequences, and
1503 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1505 As in case(B), the result is false, if @var{POINTER} is disassociated.
1506 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1507 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1508 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1510 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1511 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1512 target associated with @var{POINTER} and the target associated with @var{TARGET}
1513 have the same shape, are not zero-sized arrays, are arrays whose elements are
1514 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1515 the same storage units in array element order.
1516 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1519 @item @emph{Example}:
1521 program test_associated
1523 real, target :: tgt(2) = (/1., 2./)
1524 real, pointer :: ptr(:)
1526 if (associated(ptr) .eqv. .false.) call abort
1527 if (associated(ptr,tgt) .eqv. .false.) call abort
1528 end program test_associated
1531 @item @emph{See also}:
1538 @section @code{ATAN} --- Arctangent function
1541 @cindex trigonometric function, tangent, inverse
1542 @cindex tangent, inverse
1545 @item @emph{Description}:
1546 @code{ATAN(X)} computes the arctangent of @var{X}.
1548 @item @emph{Standard}:
1549 Fortran 77 and later, for a complex argument and for two arguments
1550 Fortran 2008 or later
1555 @item @emph{Syntax}:
1556 @multitable @columnfractions .80
1557 @item @code{RESULT = ATAN(X)}
1558 @item @code{RESULT = ATAN(Y, X)}
1561 @item @emph{Arguments}:
1562 @multitable @columnfractions .15 .70
1563 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1564 if @var{Y} is present, @var{X} shall be REAL.
1565 @item @var{Y} shall be of the same type and kind as @var{X}.
1568 @item @emph{Return value}:
1569 The return value is of the same type and kind as @var{X}.
1570 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1571 Otherwise, it the arcus tangent of @var{X}, where the real part of
1572 the result is in radians and lies in the range
1573 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1575 @item @emph{Example}:
1578 real(8) :: x = 2.866_8
1580 end program test_atan
1583 @item @emph{Specific names}:
1584 @multitable @columnfractions .20 .20 .20 .25
1585 @item Name @tab Argument @tab Return type @tab Standard
1586 @item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1587 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1590 @item @emph{See also}:
1591 Inverse function: @ref{TAN}
1592 Degrees function: @ref{ATAND}
1599 @section @code{ATAND} --- Arctangent function, degrees
1602 @cindex trigonometric function, tangent, inverse, degrees
1603 @cindex tangent, inverse, degrees
1606 @item @emph{Description}:
1607 @code{ATAND(X)} computes the arctangent of @var{X} in degrees (inverse of
1610 This function is for compatibility only and should be avoided in favor of
1611 standard constructs wherever possible.
1613 @item @emph{Standard}:
1614 GNU Extension, enabled with @option{-fdec-math}.
1619 @item @emph{Syntax}:
1620 @multitable @columnfractions .80
1621 @item @code{RESULT = ATAND(X)}
1622 @item @code{RESULT = ATAND(Y, X)}
1625 @item @emph{Arguments}:
1626 @multitable @columnfractions .15 .70
1627 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1628 if @var{Y} is present, @var{X} shall be REAL.
1629 @item @var{Y} shall be of the same type and kind as @var{X}.
1632 @item @emph{Return value}:
1633 The return value is of the same type and kind as @var{X}.
1634 If @var{Y} is present, the result is identical to @code{ATAND2(Y,X)}.
1635 Otherwise, it is the arcus tangent of @var{X}, where the real part of
1636 the result is in degrees and lies in the range
1637 @math{-90 \leq \Re \atand(x) \leq 90}.
1639 @item @emph{Example}:
1642 real(8) :: x = 2.866_8
1644 end program test_atand
1647 @item @emph{Specific names}:
1648 @multitable @columnfractions .20 .20 .20 .25
1649 @item Name @tab Argument @tab Return type @tab Standard
1650 @item @code{ATAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
1651 @item @code{DATAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
1654 @item @emph{See also}:
1655 Inverse function: @ref{TAND}
1656 Radians function: @ref{ATAN}
1663 @section @code{ATAN2} --- Arctangent function
1666 @cindex trigonometric function, tangent, inverse
1667 @cindex tangent, inverse
1670 @item @emph{Description}:
1671 @code{ATAN2(Y, X)} computes the principal value of the argument
1672 function of the complex number @math{X + i Y}. This function can
1673 be used to transform from Cartesian into polar coordinates and
1674 allows to determine the angle in the correct quadrant.
1676 @item @emph{Standard}:
1677 Fortran 77 and later
1682 @item @emph{Syntax}:
1683 @code{RESULT = ATAN2(Y, X)}
1685 @item @emph{Arguments}:
1686 @multitable @columnfractions .15 .70
1687 @item @var{Y} @tab The type shall be @code{REAL}.
1688 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1689 If @var{Y} is zero, then @var{X} must be nonzero.
1692 @item @emph{Return value}:
1693 The return value has the same type and kind type parameter as @var{Y}. It
1694 is the principal value of the complex number @math{X + i Y}. If @var{X}
1695 is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1696 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1697 the return value is zero if @var{X} is strictly positive, @math{\pi} if
1698 @var{X} is negative and @var{Y} is positive zero (or the processor does
1699 not handle signed zeros), and @math{-\pi} if @var{X} is negative and
1700 @var{Y} is negative zero. Finally, if @var{X} is zero, then the
1701 magnitude of the result is @math{\pi/2}.
1703 @item @emph{Example}:
1706 real(4) :: x = 1.e0_4, y = 0.5e0_4
1708 end program test_atan2
1711 @item @emph{Specific names}:
1712 @multitable @columnfractions .20 .20 .20 .25
1713 @item Name @tab Argument @tab Return type @tab Standard
1714 @item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1715 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1718 @item @emph{See also}:
1720 Degrees function: @ref{ATAN2D}
1727 @section @code{ATAN2D} --- Arctangent function, degrees
1730 @cindex trigonometric function, tangent, inverse, degrees
1731 @cindex tangent, inverse, degrees
1734 @item @emph{Description}:
1735 @code{ATAN2D(Y, X)} computes the principal value of the argument
1736 function of the complex number @math{X + i Y} in degrees. This function can
1737 be used to transform from Cartesian into polar coordinates and
1738 allows to determine the angle in the correct quadrant.
1740 This function is for compatibility only and should be avoided in favor of
1741 standard constructs wherever possible.
1743 @item @emph{Standard}:
1744 GNU Extension, enabled with @option{-fdec-math}.
1749 @item @emph{Syntax}:
1750 @code{RESULT = ATAN2D(Y, X)}
1752 @item @emph{Arguments}:
1753 @multitable @columnfractions .15 .70
1754 @item @var{Y} @tab The type shall be @code{REAL}.
1755 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1756 If @var{Y} is zero, then @var{X} must be nonzero.
1759 @item @emph{Return value}:
1760 The return value has the same type and kind type parameter as @var{Y}. It
1761 is the principal value of the complex number @math{X + i Y}. If @var{X}
1762 is nonzero, then it lies in the range @math{-180 \le \atan (x) \leq 180}.
1763 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1764 the return value is zero if @var{X} is strictly positive, @math{180} if
1765 @var{X} is negative and @var{Y} is positive zero (or the processor does
1766 not handle signed zeros), and @math{-180} if @var{X} is negative and
1767 @var{Y} is negative zero. Finally, if @var{X} is zero, then the
1768 magnitude of the result is @math{90}.
1770 @item @emph{Example}:
1773 real(4) :: x = 1.e0_4, y = 0.5e0_4
1775 end program test_atan2d
1778 @item @emph{Specific names}:
1779 @multitable @columnfractions .20 .20 .20 .25
1780 @item Name @tab Argument @tab Return type @tab Standard
1781 @item @code{ATAN2D(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab GNU Extension
1782 @item @code{DATAN2D(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab GNU Extension
1785 @item @emph{See also}:
1787 Radians function: @ref{ATAN2}
1794 @section @code{ATANH} --- Inverse hyperbolic tangent function
1797 @cindex area hyperbolic tangent
1798 @cindex inverse hyperbolic tangent
1799 @cindex hyperbolic function, tangent, inverse
1800 @cindex tangent, hyperbolic, inverse
1803 @item @emph{Description}:
1804 @code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
1806 @item @emph{Standard}:
1807 Fortran 2008 and later
1812 @item @emph{Syntax}:
1813 @code{RESULT = ATANH(X)}
1815 @item @emph{Arguments}:
1816 @multitable @columnfractions .15 .70
1817 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1820 @item @emph{Return value}:
1821 The return value has same type and kind as @var{X}. If @var{X} is
1822 complex, the imaginary part of the result is in radians and lies between
1823 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1825 @item @emph{Example}:
1828 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1829 WRITE (*,*) ATANH(x)
1833 @item @emph{Specific names}:
1834 @multitable @columnfractions .20 .20 .20 .25
1835 @item Name @tab Argument @tab Return type @tab Standard
1836 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1839 @item @emph{See also}:
1840 Inverse function: @ref{TANH}
1846 @section @code{ATOMIC_ADD} --- Atomic ADD operation
1848 @cindex Atomic subroutine, add
1851 @item @emph{Description}:
1852 @code{ATOMIC_ADD(ATOM, VALUE)} atomically adds the value of @var{VAR} to the
1853 variable @var{ATOM}. When @var{STAT} is present and the invokation was
1854 successful, it is assigned the value 0. If it is present and the invokation
1855 has failed, it is assigned a positive value; in particular, for a coindexed
1856 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1857 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1858 failed, the value @code{STAT_FAILED_IMAGE}.
1860 @item @emph{Standard}:
1866 @item @emph{Syntax}:
1867 @code{CALL ATOMIC_ADD (ATOM, VALUE [, STAT])}
1869 @item @emph{Arguments}:
1870 @multitable @columnfractions .15 .70
1871 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1872 type with @code{ATOMIC_INT_KIND} kind.
1873 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1874 is different, the value is converted to the kind of @var{ATOM}.
1875 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1878 @item @emph{Example}:
1882 integer(atomic_int_kind) :: atom[*]
1883 call atomic_add (atom[1], this_image())
1887 @item @emph{See also}:
1888 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_ADD}, @ref{ISO_FORTRAN_ENV},
1889 @ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
1896 @section @code{ATOMIC_AND} --- Atomic bitwise AND operation
1898 @cindex Atomic subroutine, AND
1901 @item @emph{Description}:
1902 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
1903 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
1904 and the invokation was successful, it is assigned the value 0. If it is present
1905 and the invokation has failed, it is assigned a positive value; in particular,
1906 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
1907 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
1908 image has failed, the value @code{STAT_FAILED_IMAGE}.
1910 @item @emph{Standard}:
1916 @item @emph{Syntax}:
1917 @code{CALL ATOMIC_AND (ATOM, VALUE [, STAT])}
1919 @item @emph{Arguments}:
1920 @multitable @columnfractions .15 .70
1921 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1922 type with @code{ATOMIC_INT_KIND} kind.
1923 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1924 is different, the value is converted to the kind of @var{ATOM}.
1925 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1928 @item @emph{Example}:
1932 integer(atomic_int_kind) :: atom[*]
1933 call atomic_and (atom[1], int(b'10100011101'))
1937 @item @emph{See also}:
1938 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_AND}, @ref{ISO_FORTRAN_ENV},
1939 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
1945 @section @code{ATOMIC_CAS} --- Atomic compare and swap
1946 @fnindex ATOMIC_DEFINE
1947 @cindex Atomic subroutine, compare and swap
1950 @item @emph{Description}:
1951 @code{ATOMIC_CAS} compares the variable @var{ATOM} with the value of
1952 @var{COMPARE}; if the value is the same, @var{ATOM} is set to the value
1953 of @var{NEW}. Additionally, @var{OLD} is set to the value of @var{ATOM}
1954 that was used for the comparison. When @var{STAT} is present and the invokation
1955 was successful, it is assigned the value 0. If it is present and the invokation
1956 has failed, it is assigned a positive value; in particular, for a coindexed
1957 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1958 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1959 failed, the value @code{STAT_FAILED_IMAGE}.
1961 @item @emph{Standard}:
1967 @item @emph{Syntax}:
1968 @code{CALL ATOMIC_CAS (ATOM, OLD, COMPARE, NEW [, STAT])}
1970 @item @emph{Arguments}:
1971 @multitable @columnfractions .15 .70
1972 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
1973 type with @code{ATOMIC_INT_KIND} kind or logical type with
1974 @code{ATOMIC_LOGICAL_KIND} kind.
1975 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1976 @item @var{COMPARE} @tab Scalar variable of the same type and kind as
1978 @item @var{NEW} @tab Scalar variable of the same type as @var{ATOM}. If kind
1979 is different, the value is converted to the kind of @var{ATOM}.
1980 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1983 @item @emph{Example}:
1987 logical(atomic_logical_kind) :: atom[*], prev
1988 call atomic_cas (atom[1], prev, .false., .true.))
1992 @item @emph{See also}:
1993 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_REF}, @ref{ISO_FORTRAN_ENV}
1999 @section @code{ATOMIC_DEFINE} --- Setting a variable atomically
2000 @fnindex ATOMIC_DEFINE
2001 @cindex Atomic subroutine, define
2004 @item @emph{Description}:
2005 @code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value
2006 @var{VALUE} atomically. When @var{STAT} is present and the invokation was
2007 successful, it is assigned the value 0. If it is present and the invokation
2008 has failed, it is assigned a positive value; in particular, for a coindexed
2009 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2010 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2011 failed, the value @code{STAT_FAILED_IMAGE}.
2013 @item @emph{Standard}:
2014 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
2019 @item @emph{Syntax}:
2020 @code{CALL ATOMIC_DEFINE (ATOM, VALUE [, STAT])}
2022 @item @emph{Arguments}:
2023 @multitable @columnfractions .15 .70
2024 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
2025 type with @code{ATOMIC_INT_KIND} kind or logical type with
2026 @code{ATOMIC_LOGICAL_KIND} kind.
2028 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2029 is different, the value is converted to the kind of @var{ATOM}.
2030 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2033 @item @emph{Example}:
2037 integer(atomic_int_kind) :: atom[*]
2038 call atomic_define (atom[1], this_image())
2042 @item @emph{See also}:
2043 @ref{ATOMIC_REF}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV},
2044 @ref{ATOMIC_ADD}, @ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
2049 @node ATOMIC_FETCH_ADD
2050 @section @code{ATOMIC_FETCH_ADD} --- Atomic ADD operation with prior fetch
2051 @fnindex ATOMIC_FETCH_ADD
2052 @cindex Atomic subroutine, ADD with fetch
2055 @item @emph{Description}:
2056 @code{ATOMIC_FETCH_ADD(ATOM, VALUE, OLD)} atomically stores the value of
2057 @var{ATOM} in @var{OLD} and adds the value of @var{VAR} to the
2058 variable @var{ATOM}. When @var{STAT} is present and the invokation was
2059 successful, it is assigned the value 0. If it is present and the invokation
2060 has failed, it is assigned a positive value; in particular, for a coindexed
2061 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2062 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2063 failed, the value @code{STAT_FAILED_IMAGE}.
2065 @item @emph{Standard}:
2071 @item @emph{Syntax}:
2072 @code{CALL ATOMIC_FETCH_ADD (ATOM, VALUE, old [, STAT])}
2074 @item @emph{Arguments}:
2075 @multitable @columnfractions .15 .70
2076 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2077 type with @code{ATOMIC_INT_KIND} kind.
2078 @code{ATOMIC_LOGICAL_KIND} kind.
2080 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2081 is different, the value is converted to the kind of @var{ATOM}.
2082 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2083 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2086 @item @emph{Example}:
2090 integer(atomic_int_kind) :: atom[*], old
2091 call atomic_add (atom[1], this_image(), old)
2095 @item @emph{See also}:
2096 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_ADD}, @ref{ISO_FORTRAN_ENV},
2097 @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR}
2102 @node ATOMIC_FETCH_AND
2103 @section @code{ATOMIC_FETCH_AND} --- Atomic bitwise AND operation with prior fetch
2104 @fnindex ATOMIC_FETCH_AND
2105 @cindex Atomic subroutine, AND with fetch
2108 @item @emph{Description}:
2109 @code{ATOMIC_AND(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2110 @var{OLD} and defines @var{ATOM} with the bitwise AND between the values of
2111 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was
2112 successful, it is assigned the value 0. If it is present and the invokation has
2113 failed, it is assigned a positive value; in particular, for a coindexed
2114 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2115 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2116 failed, the value @code{STAT_FAILED_IMAGE}.
2118 @item @emph{Standard}:
2124 @item @emph{Syntax}:
2125 @code{CALL ATOMIC_FETCH_AND (ATOM, VALUE, OLD [, STAT])}
2127 @item @emph{Arguments}:
2128 @multitable @columnfractions .15 .70
2129 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2130 type with @code{ATOMIC_INT_KIND} kind.
2131 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2132 is different, the value is converted to the kind of @var{ATOM}.
2133 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2134 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2137 @item @emph{Example}:
2141 integer(atomic_int_kind) :: atom[*], old
2142 call atomic_fetch_and (atom[1], int(b'10100011101'), old)
2146 @item @emph{See also}:
2147 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_AND}, @ref{ISO_FORTRAN_ENV},
2148 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR}
2153 @node ATOMIC_FETCH_OR
2154 @section @code{ATOMIC_FETCH_OR} --- Atomic bitwise OR operation with prior fetch
2155 @fnindex ATOMIC_FETCH_OR
2156 @cindex Atomic subroutine, OR with fetch
2159 @item @emph{Description}:
2160 @code{ATOMIC_OR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2161 @var{OLD} and defines @var{ATOM} with the bitwise OR between the values of
2162 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was
2163 successful, it is assigned the value 0. If it is present and the invokation has
2164 failed, it is assigned a positive value; in particular, for a coindexed
2165 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2166 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2167 failed, the value @code{STAT_FAILED_IMAGE}.
2169 @item @emph{Standard}:
2175 @item @emph{Syntax}:
2176 @code{CALL ATOMIC_FETCH_OR (ATOM, VALUE, OLD [, STAT])}
2178 @item @emph{Arguments}:
2179 @multitable @columnfractions .15 .70
2180 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2181 type with @code{ATOMIC_INT_KIND} kind.
2182 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2183 is different, the value is converted to the kind of @var{ATOM}.
2184 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2185 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2188 @item @emph{Example}:
2192 integer(atomic_int_kind) :: atom[*], old
2193 call atomic_fetch_or (atom[1], int(b'10100011101'), old)
2197 @item @emph{See also}:
2198 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_OR}, @ref{ISO_FORTRAN_ENV},
2199 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_XOR}
2204 @node ATOMIC_FETCH_XOR
2205 @section @code{ATOMIC_FETCH_XOR} --- Atomic bitwise XOR operation with prior fetch
2206 @fnindex ATOMIC_FETCH_XOR
2207 @cindex Atomic subroutine, XOR with fetch
2210 @item @emph{Description}:
2211 @code{ATOMIC_XOR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2212 @var{OLD} and defines @var{ATOM} with the bitwise XOR between the values of
2213 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was
2214 successful, it is assigned the value 0. If it is present and the invokation has
2215 failed, it is assigned a positive value; in particular, for a coindexed
2216 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2217 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2218 failed, the value @code{STAT_FAILED_IMAGE}.
2220 @item @emph{Standard}:
2226 @item @emph{Syntax}:
2227 @code{CALL ATOMIC_FETCH_XOR (ATOM, VALUE, OLD [, STAT])}
2229 @item @emph{Arguments}:
2230 @multitable @columnfractions .15 .70
2231 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2232 type with @code{ATOMIC_INT_KIND} kind.
2233 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2234 is different, the value is converted to the kind of @var{ATOM}.
2235 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2236 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2239 @item @emph{Example}:
2243 integer(atomic_int_kind) :: atom[*], old
2244 call atomic_fetch_xor (atom[1], int(b'10100011101'), old)
2248 @item @emph{See also}:
2249 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_XOR}, @ref{ISO_FORTRAN_ENV},
2250 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}
2256 @section @code{ATOMIC_OR} --- Atomic bitwise OR operation
2258 @cindex Atomic subroutine, OR
2261 @item @emph{Description}:
2262 @code{ATOMIC_OR(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
2263 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
2264 and the invokation was successful, it is assigned the value 0. If it is present
2265 and the invokation has failed, it is assigned a positive value; in particular,
2266 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
2267 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
2268 image has failed, the value @code{STAT_FAILED_IMAGE}.
2270 @item @emph{Standard}:
2276 @item @emph{Syntax}:
2277 @code{CALL ATOMIC_OR (ATOM, VALUE [, STAT])}
2279 @item @emph{Arguments}:
2280 @multitable @columnfractions .15 .70
2281 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2282 type with @code{ATOMIC_INT_KIND} kind.
2283 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2284 is different, the value is converted to the kind of @var{ATOM}.
2285 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2288 @item @emph{Example}:
2292 integer(atomic_int_kind) :: atom[*]
2293 call atomic_or (atom[1], int(b'10100011101'))
2297 @item @emph{See also}:
2298 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_OR}, @ref{ISO_FORTRAN_ENV},
2299 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
2305 @section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically
2307 @cindex Atomic subroutine, reference
2310 @item @emph{Description}:
2311 @code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the
2312 variable @var{ATOM} to @var{VALUE}. When @var{STAT} is present and the
2313 invokation was successful, it is assigned the value 0. If it is present and the
2314 invokation has failed, it is assigned a positive value; in particular, for a
2315 coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value
2316 of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image
2317 has failed, the value @code{STAT_FAILED_IMAGE}.
2320 @item @emph{Standard}:
2321 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
2326 @item @emph{Syntax}:
2327 @code{CALL ATOMIC_REF(VALUE, ATOM [, STAT])}
2329 @item @emph{Arguments}:
2330 @multitable @columnfractions .15 .70
2331 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2332 is different, the value is converted to the kind of @var{ATOM}.
2333 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
2334 type with @code{ATOMIC_INT_KIND} kind or logical type with
2335 @code{ATOMIC_LOGICAL_KIND} kind.
2336 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2339 @item @emph{Example}:
2343 logical(atomic_logical_kind) :: atom[*]
2345 call atomic_ref (atom, .false.)
2347 call atomic_ref (atom, val)
2354 @item @emph{See also}:
2355 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV},
2356 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR},
2357 @ref{ATOMIC_FETCH_XOR}
2362 @section @code{ATOMIC_XOR} --- Atomic bitwise OR operation
2364 @cindex Atomic subroutine, XOR
2367 @item @emph{Description}:
2368 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
2369 XOR between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
2370 and the invokation was successful, it is assigned the value 0. If it is present
2371 and the invokation has failed, it is assigned a positive value; in particular,
2372 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
2373 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
2374 image has failed, the value @code{STAT_FAILED_IMAGE}.
2376 @item @emph{Standard}:
2382 @item @emph{Syntax}:
2383 @code{CALL ATOMIC_XOR (ATOM, VALUE [, STAT])}
2385 @item @emph{Arguments}:
2386 @multitable @columnfractions .15 .70
2387 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2388 type with @code{ATOMIC_INT_KIND} kind.
2389 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2390 is different, the value is converted to the kind of @var{ATOM}.
2391 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2394 @item @emph{Example}:
2398 integer(atomic_int_kind) :: atom[*]
2399 call atomic_xor (atom[1], int(b'10100011101'))
2403 @item @emph{See also}:
2404 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_XOR}, @ref{ISO_FORTRAN_ENV},
2405 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
2410 @section @code{BACKTRACE} --- Show a backtrace
2415 @item @emph{Description}:
2416 @code{BACKTRACE} shows a backtrace at an arbitrary place in user code. Program
2417 execution continues normally afterwards. The backtrace information is printed
2418 to the unit corresponding to @code{ERROR_UNIT} in @code{ISO_FORTRAN_ENV}.
2420 @item @emph{Standard}:
2426 @item @emph{Syntax}:
2427 @code{CALL BACKTRACE}
2429 @item @emph{Arguments}:
2432 @item @emph{See also}:
2439 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
2443 @cindex Bessel function, first kind
2446 @item @emph{Description}:
2447 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
2448 order 0 of @var{X}. This function is available under the name
2449 @code{BESJ0} as a GNU extension.
2451 @item @emph{Standard}:
2452 Fortran 2008 and later
2457 @item @emph{Syntax}:
2458 @code{RESULT = BESSEL_J0(X)}
2460 @item @emph{Arguments}:
2461 @multitable @columnfractions .15 .70
2462 @item @var{X} @tab The type shall be @code{REAL}.
2465 @item @emph{Return value}:
2466 The return value is of type @code{REAL} and lies in the
2467 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
2470 @item @emph{Example}:
2473 real(8) :: x = 0.0_8
2475 end program test_besj0
2478 @item @emph{Specific names}:
2479 @multitable @columnfractions .20 .20 .20 .25
2480 @item Name @tab Argument @tab Return type @tab Standard
2481 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2488 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
2492 @cindex Bessel function, first kind
2495 @item @emph{Description}:
2496 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
2497 order 1 of @var{X}. This function is available under the name
2498 @code{BESJ1} as a GNU extension.
2500 @item @emph{Standard}:
2506 @item @emph{Syntax}:
2507 @code{RESULT = BESSEL_J1(X)}
2509 @item @emph{Arguments}:
2510 @multitable @columnfractions .15 .70
2511 @item @var{X} @tab The type shall be @code{REAL}.
2514 @item @emph{Return value}:
2515 The return value is of type @code{REAL} and lies in the
2516 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
2519 @item @emph{Example}:
2522 real(8) :: x = 1.0_8
2524 end program test_besj1
2527 @item @emph{Specific names}:
2528 @multitable @columnfractions .20 .20 .20 .25
2529 @item Name @tab Argument @tab Return type @tab Standard
2530 @item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2537 @section @code{BESSEL_JN} --- Bessel function of the first kind
2541 @cindex Bessel function, first kind
2544 @item @emph{Description}:
2545 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
2546 order @var{N} of @var{X}. This function is available under the name
2547 @code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays,
2548 their ranks and shapes shall conform.
2550 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
2551 of the first kind of the orders @var{N1} to @var{N2}.
2553 @item @emph{Standard}:
2554 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2557 Elemental function, except for the transformational function
2558 @code{BESSEL_JN(N1, N2, X)}
2560 @item @emph{Syntax}:
2561 @multitable @columnfractions .80
2562 @item @code{RESULT = BESSEL_JN(N, X)}
2563 @item @code{RESULT = BESSEL_JN(N1, N2, X)}
2566 @item @emph{Arguments}:
2567 @multitable @columnfractions .15 .70
2568 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
2569 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2570 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2571 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2572 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
2575 @item @emph{Return value}:
2576 The return value is a scalar of type @code{REAL}. It has the same
2580 The transformational function uses a recurrence algorithm which might,
2581 for some values of @var{X}, lead to different results than calls to
2582 the elemental function.
2584 @item @emph{Example}:
2587 real(8) :: x = 1.0_8
2589 end program test_besjn
2592 @item @emph{Specific names}:
2593 @multitable @columnfractions .20 .20 .20 .25
2594 @item Name @tab Argument @tab Return type @tab Standard
2595 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2596 @item @tab @code{REAL(8) X} @tab @tab
2603 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
2607 @cindex Bessel function, second kind
2610 @item @emph{Description}:
2611 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
2612 order 0 of @var{X}. This function is available under the name
2613 @code{BESY0} as a GNU extension.
2615 @item @emph{Standard}:
2616 Fortran 2008 and later
2621 @item @emph{Syntax}:
2622 @code{RESULT = BESSEL_Y0(X)}
2624 @item @emph{Arguments}:
2625 @multitable @columnfractions .15 .70
2626 @item @var{X} @tab The type shall be @code{REAL}.
2629 @item @emph{Return value}:
2630 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2632 @item @emph{Example}:
2635 real(8) :: x = 0.0_8
2637 end program test_besy0
2640 @item @emph{Specific names}:
2641 @multitable @columnfractions .20 .20 .20 .25
2642 @item Name @tab Argument @tab Return type @tab Standard
2643 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2650 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
2654 @cindex Bessel function, second kind
2657 @item @emph{Description}:
2658 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
2659 order 1 of @var{X}. This function is available under the name
2660 @code{BESY1} as a GNU extension.
2662 @item @emph{Standard}:
2663 Fortran 2008 and later
2668 @item @emph{Syntax}:
2669 @code{RESULT = BESSEL_Y1(X)}
2671 @item @emph{Arguments}:
2672 @multitable @columnfractions .15 .70
2673 @item @var{X} @tab The type shall be @code{REAL}.
2676 @item @emph{Return value}:
2677 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2679 @item @emph{Example}:
2682 real(8) :: x = 1.0_8
2684 end program test_besy1
2687 @item @emph{Specific names}:
2688 @multitable @columnfractions .20 .20 .20 .25
2689 @item Name @tab Argument @tab Return type @tab Standard
2690 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2697 @section @code{BESSEL_YN} --- Bessel function of the second kind
2701 @cindex Bessel function, second kind
2704 @item @emph{Description}:
2705 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
2706 order @var{N} of @var{X}. This function is available under the name
2707 @code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays,
2708 their ranks and shapes shall conform.
2710 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
2711 of the first kind of the orders @var{N1} to @var{N2}.
2713 @item @emph{Standard}:
2714 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2717 Elemental function, except for the transformational function
2718 @code{BESSEL_YN(N1, N2, X)}
2720 @item @emph{Syntax}:
2721 @multitable @columnfractions .80
2722 @item @code{RESULT = BESSEL_YN(N, X)}
2723 @item @code{RESULT = BESSEL_YN(N1, N2, X)}
2726 @item @emph{Arguments}:
2727 @multitable @columnfractions .15 .70
2728 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} .
2729 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2730 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2731 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2732 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
2735 @item @emph{Return value}:
2736 The return value is a scalar of type @code{REAL}. It has the same
2740 The transformational function uses a recurrence algorithm which might,
2741 for some values of @var{X}, lead to different results than calls to
2742 the elemental function.
2744 @item @emph{Example}:
2747 real(8) :: x = 1.0_8
2749 end program test_besyn
2752 @item @emph{Specific names}:
2753 @multitable @columnfractions .20 .20 .20 .25
2754 @item Name @tab Argument @tab Return type @tab Standard
2755 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2756 @item @tab @code{REAL(8) X} @tab @tab
2763 @section @code{BGE} --- Bitwise greater than or equal to
2765 @cindex bitwise comparison
2768 @item @emph{Description}:
2769 Determines whether an integral is a bitwise greater than or equal to
2772 @item @emph{Standard}:
2773 Fortran 2008 and later
2778 @item @emph{Syntax}:
2779 @code{RESULT = BGE(I, J)}
2781 @item @emph{Arguments}:
2782 @multitable @columnfractions .15 .70
2783 @item @var{I} @tab Shall be of @code{INTEGER} type.
2784 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2788 @item @emph{Return value}:
2789 The return value is of type @code{LOGICAL} and of the default kind.
2791 @item @emph{See also}:
2792 @ref{BGT}, @ref{BLE}, @ref{BLT}
2798 @section @code{BGT} --- Bitwise greater than
2800 @cindex bitwise comparison
2803 @item @emph{Description}:
2804 Determines whether an integral is a bitwise greater than another.
2806 @item @emph{Standard}:
2807 Fortran 2008 and later
2812 @item @emph{Syntax}:
2813 @code{RESULT = BGT(I, J)}
2815 @item @emph{Arguments}:
2816 @multitable @columnfractions .15 .70
2817 @item @var{I} @tab Shall be of @code{INTEGER} type.
2818 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2822 @item @emph{Return value}:
2823 The return value is of type @code{LOGICAL} and of the default kind.
2825 @item @emph{See also}:
2826 @ref{BGE}, @ref{BLE}, @ref{BLT}
2832 @section @code{BIT_SIZE} --- Bit size inquiry function
2834 @cindex bits, number of
2835 @cindex size of a variable, in bits
2838 @item @emph{Description}:
2839 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
2840 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
2841 independent of the actual value of @var{I}.
2843 @item @emph{Standard}:
2844 Fortran 95 and later
2849 @item @emph{Syntax}:
2850 @code{RESULT = BIT_SIZE(I)}
2852 @item @emph{Arguments}:
2853 @multitable @columnfractions .15 .70
2854 @item @var{I} @tab The type shall be @code{INTEGER}.
2857 @item @emph{Return value}:
2858 The return value is of type @code{INTEGER}
2860 @item @emph{Example}:
2862 program test_bit_size
2867 end program test_bit_size
2874 @section @code{BLE} --- Bitwise less than or equal to
2876 @cindex bitwise comparison
2879 @item @emph{Description}:
2880 Determines whether an integral is a bitwise less than or equal to
2883 @item @emph{Standard}:
2884 Fortran 2008 and later
2889 @item @emph{Syntax}:
2890 @code{RESULT = BLE(I, J)}
2892 @item @emph{Arguments}:
2893 @multitable @columnfractions .15 .70
2894 @item @var{I} @tab Shall be of @code{INTEGER} type.
2895 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2899 @item @emph{Return value}:
2900 The return value is of type @code{LOGICAL} and of the default kind.
2902 @item @emph{See also}:
2903 @ref{BGT}, @ref{BGE}, @ref{BLT}
2909 @section @code{BLT} --- Bitwise less than
2911 @cindex bitwise comparison
2914 @item @emph{Description}:
2915 Determines whether an integral is a bitwise less than another.
2917 @item @emph{Standard}:
2918 Fortran 2008 and later
2923 @item @emph{Syntax}:
2924 @code{RESULT = BLT(I, J)}
2926 @item @emph{Arguments}:
2927 @multitable @columnfractions .15 .70
2928 @item @var{I} @tab Shall be of @code{INTEGER} type.
2929 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2933 @item @emph{Return value}:
2934 The return value is of type @code{LOGICAL} and of the default kind.
2936 @item @emph{See also}:
2937 @ref{BGE}, @ref{BGT}, @ref{BLE}
2943 @section @code{BTEST} --- Bit test function
2949 @cindex bits, testing
2952 @item @emph{Description}:
2953 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
2954 in @var{I} is set. The counting of the bits starts at 0.
2956 @item @emph{Standard}:
2957 Fortran 95 and later, has overloads that are GNU extensions
2962 @item @emph{Syntax}:
2963 @code{RESULT = BTEST(I, POS)}
2965 @item @emph{Arguments}:
2966 @multitable @columnfractions .15 .70
2967 @item @var{I} @tab The type shall be @code{INTEGER}.
2968 @item @var{POS} @tab The type shall be @code{INTEGER}.
2971 @item @emph{Return value}:
2972 The return value is of type @code{LOGICAL}
2974 @item @emph{Example}:
2977 integer :: i = 32768 + 1024 + 64
2981 bool = btest(i, pos)
2984 end program test_btest
2987 @item @emph{Specific names}:
2988 @multitable @columnfractions .20 .20 .20 .25
2989 @item Name @tab Argument @tab Return type @tab Standard
2990 @item @code{BTEST(I,POS)} @tab @code{INTEGER I,POS} @tab @code{LOGICAL} @tab F95 and later
2991 @item @code{BBTEST(I,POS)} @tab @code{INTEGER(1) I,POS} @tab @code{LOGICAL(1)} @tab GNU extension
2992 @item @code{BITEST(I,POS)} @tab @code{INTEGER(2) I,POS} @tab @code{LOGICAL(2)} @tab GNU extension
2993 @item @code{BJTEST(I,POS)} @tab @code{INTEGER(4) I,POS} @tab @code{LOGICAL(4)} @tab GNU extension
2994 @item @code{BKTEST(I,POS)} @tab @code{INTEGER(8) I,POS} @tab @code{LOGICAL(8)} @tab GNU extension
2999 @section @code{C_ASSOCIATED} --- Status of a C pointer
3000 @fnindex C_ASSOCIATED
3001 @cindex association status, C pointer
3002 @cindex pointer, C association status
3005 @item @emph{Description}:
3006 @code{C_ASSOCIATED(c_ptr_1[, c_ptr_2])} determines the status of the C pointer
3007 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
3009 @item @emph{Standard}:
3010 Fortran 2003 and later
3015 @item @emph{Syntax}:
3016 @code{RESULT = C_ASSOCIATED(c_ptr_1[, c_ptr_2])}
3018 @item @emph{Arguments}:
3019 @multitable @columnfractions .15 .70
3020 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
3021 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
3024 @item @emph{Return value}:
3025 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
3026 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
3027 point to different addresses.
3029 @item @emph{Example}:
3031 subroutine association_test(a,b)
3032 use iso_c_binding, only: c_associated, c_loc, c_ptr
3036 if(c_associated(b, c_loc(a))) &
3037 stop 'b and a do not point to same target'
3038 end subroutine association_test
3041 @item @emph{See also}:
3042 @ref{C_LOC}, @ref{C_FUNLOC}
3047 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
3048 @fnindex C_F_POINTER
3049 @cindex pointer, convert C to Fortran
3052 @item @emph{Description}:
3053 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} assigns the target of the C pointer
3054 @var{CPTR} to the Fortran pointer @var{FPTR} and specifies its shape.
3056 @item @emph{Standard}:
3057 Fortran 2003 and later
3062 @item @emph{Syntax}:
3063 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
3065 @item @emph{Arguments}:
3066 @multitable @columnfractions .15 .70
3067 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
3069 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
3071 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
3072 with @code{INTENT(IN)}. It shall be present
3073 if and only if @var{fptr} is an array. The size
3074 must be equal to the rank of @var{fptr}.
3077 @item @emph{Example}:
3083 subroutine my_routine(p) bind(c,name='myC_func')
3085 type(c_ptr), intent(out) :: p
3089 real,pointer :: a(:)
3090 call my_routine(cptr)
3091 call c_f_pointer(cptr, a, [12])
3095 @item @emph{See also}:
3096 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
3100 @node C_F_PROCPOINTER
3101 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
3102 @fnindex C_F_PROCPOINTER
3103 @cindex pointer, C address of pointers
3106 @item @emph{Description}:
3107 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
3108 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
3110 @item @emph{Standard}:
3111 Fortran 2003 and later
3116 @item @emph{Syntax}:
3117 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
3119 @item @emph{Arguments}:
3120 @multitable @columnfractions .15 .70
3121 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
3123 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
3127 @item @emph{Example}:
3135 real(c_float), intent(in) :: a
3136 real(c_float) :: func
3140 function getIterFunc() bind(c,name="getIterFunc")
3142 type(c_funptr) :: getIterFunc
3145 type(c_funptr) :: cfunptr
3146 procedure(func), pointer :: myFunc
3147 cfunptr = getIterFunc()
3148 call c_f_procpointer(cfunptr, myFunc)
3152 @item @emph{See also}:
3153 @ref{C_LOC}, @ref{C_F_POINTER}
3158 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
3160 @cindex pointer, C address of procedures
3163 @item @emph{Description}:
3164 @code{C_FUNLOC(x)} determines the C address of the argument.
3166 @item @emph{Standard}:
3167 Fortran 2003 and later
3172 @item @emph{Syntax}:
3173 @code{RESULT = C_FUNLOC(x)}
3175 @item @emph{Arguments}:
3176 @multitable @columnfractions .15 .70
3177 @item @var{x} @tab Interoperable function or pointer to such function.
3180 @item @emph{Return value}:
3181 The return value is of type @code{C_FUNPTR} and contains the C address
3184 @item @emph{Example}:
3190 subroutine sub(a) bind(c)
3200 subroutine my_routine(p) bind(c,name='myC_func')
3202 type(c_funptr), intent(in) :: p
3205 call my_routine(c_funloc(sub))
3209 @item @emph{See also}:
3210 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
3215 @section @code{C_LOC} --- Obtain the C address of an object
3217 @cindex procedure pointer, convert C to Fortran
3220 @item @emph{Description}:
3221 @code{C_LOC(X)} determines the C address of the argument.
3223 @item @emph{Standard}:
3224 Fortran 2003 and later
3229 @item @emph{Syntax}:
3230 @code{RESULT = C_LOC(X)}
3232 @item @emph{Arguments}:
3233 @multitable @columnfractions .10 .75
3234 @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.
3238 @item @emph{Return value}:
3239 The return value is of type @code{C_PTR} and contains the C address
3242 @item @emph{Example}:
3244 subroutine association_test(a,b)
3245 use iso_c_binding, only: c_associated, c_loc, c_ptr
3249 if(c_associated(b, c_loc(a))) &
3250 stop 'b and a do not point to same target'
3251 end subroutine association_test
3254 @item @emph{See also}:
3255 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
3260 @section @code{C_SIZEOF} --- Size in bytes of an expression
3262 @cindex expression size
3263 @cindex size of an expression
3266 @item @emph{Description}:
3267 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
3268 expression @code{X} occupies.
3270 @item @emph{Standard}:
3274 Inquiry function of the module @code{ISO_C_BINDING}
3276 @item @emph{Syntax}:
3277 @code{N = C_SIZEOF(X)}
3279 @item @emph{Arguments}:
3280 @multitable @columnfractions .15 .70
3281 @item @var{X} @tab The argument shall be an interoperable data entity.
3284 @item @emph{Return value}:
3285 The return value is of type integer and of the system-dependent kind
3286 @code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the
3287 number of bytes occupied by the argument. If the argument has the
3288 @code{POINTER} attribute, the number of bytes of the storage area pointed
3289 to is returned. If the argument is of a derived type with @code{POINTER}
3290 or @code{ALLOCATABLE} components, the return value does not account for
3291 the sizes of the data pointed to by these components.
3293 @item @emph{Example}:
3297 real(c_float) :: r, s(5)
3298 print *, (c_sizeof(s)/c_sizeof(r) == 5)
3301 The example will print @code{.TRUE.} unless you are using a platform
3302 where default @code{REAL} variables are unusually padded.
3304 @item @emph{See also}:
3305 @ref{SIZEOF}, @ref{STORAGE_SIZE}
3310 @section @code{CEILING} --- Integer ceiling function
3313 @cindex rounding, ceiling
3316 @item @emph{Description}:
3317 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
3319 @item @emph{Standard}:
3320 Fortran 95 and later
3325 @item @emph{Syntax}:
3326 @code{RESULT = CEILING(A [, KIND])}
3328 @item @emph{Arguments}:
3329 @multitable @columnfractions .15 .70
3330 @item @var{A} @tab The type shall be @code{REAL}.
3331 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3332 expression indicating the kind parameter of the result.
3335 @item @emph{Return value}:
3336 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
3337 and a default-kind @code{INTEGER} otherwise.
3339 @item @emph{Example}:
3341 program test_ceiling
3344 print *, ceiling(x) ! returns 64
3345 print *, ceiling(y) ! returns -63
3346 end program test_ceiling
3349 @item @emph{See also}:
3350 @ref{FLOOR}, @ref{NINT}
3357 @section @code{CHAR} --- Character conversion function
3359 @cindex conversion, to character
3362 @item @emph{Description}:
3363 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
3365 @item @emph{Standard}:
3366 Fortran 77 and later
3371 @item @emph{Syntax}:
3372 @code{RESULT = CHAR(I [, KIND])}
3374 @item @emph{Arguments}:
3375 @multitable @columnfractions .15 .70
3376 @item @var{I} @tab The type shall be @code{INTEGER}.
3377 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3378 expression indicating the kind parameter of the result.
3381 @item @emph{Return value}:
3382 The return value is of type @code{CHARACTER(1)}
3384 @item @emph{Example}:
3390 print *, i, c ! returns 'J'
3391 end program test_char
3394 @item @emph{Specific names}:
3395 @multitable @columnfractions .20 .20 .20 .25
3396 @item Name @tab Argument @tab Return type @tab Standard
3397 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
3401 See @ref{ICHAR} for a discussion of converting between numerical values
3402 and formatted string representations.
3404 @item @emph{See also}:
3405 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
3412 @section @code{CHDIR} --- Change working directory
3414 @cindex system, working directory
3417 @item @emph{Description}:
3418 Change current working directory to a specified path.
3420 This intrinsic is provided in both subroutine and function forms; however,
3421 only one form can be used in any given program unit.
3423 @item @emph{Standard}:
3427 Subroutine, function
3429 @item @emph{Syntax}:
3430 @multitable @columnfractions .80
3431 @item @code{CALL CHDIR(NAME [, STATUS])}
3432 @item @code{STATUS = CHDIR(NAME)}
3435 @item @emph{Arguments}:
3436 @multitable @columnfractions .15 .70
3437 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
3438 kind and shall specify a valid path within the file system.
3439 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
3440 kind. Returns 0 on success, and a system specific and nonzero error code
3444 @item @emph{Example}:
3447 CHARACTER(len=255) :: path
3449 WRITE(*,*) TRIM(path)
3452 WRITE(*,*) TRIM(path)
3456 @item @emph{See also}:
3463 @section @code{CHMOD} --- Change access permissions of files
3465 @cindex file system, change access mode
3468 @item @emph{Description}:
3469 @code{CHMOD} changes the permissions of a file.
3471 This intrinsic is provided in both subroutine and function forms; however,
3472 only one form can be used in any given program unit.
3474 @item @emph{Standard}:
3478 Subroutine, function
3480 @item @emph{Syntax}:
3481 @multitable @columnfractions .80
3482 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
3483 @item @code{STATUS = CHMOD(NAME, MODE)}
3486 @item @emph{Arguments}:
3487 @multitable @columnfractions .15 .70
3489 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
3490 file name. Trailing blanks are ignored unless the character
3491 @code{achar(0)} is present, then all characters up to and excluding
3492 @code{achar(0)} are used as the file name.
3494 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
3495 file permission. @var{MODE} uses the same syntax as the @code{chmod} utility
3496 as defined by the POSIX standard. The argument shall either be a string of
3497 a nonnegative octal number or a symbolic mode.
3499 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
3500 @code{0} on success and nonzero otherwise.
3503 @item @emph{Return value}:
3504 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
3507 @item @emph{Example}:
3508 @code{CHMOD} as subroutine
3513 call chmod('test.dat','u+x',status)
3514 print *, 'Status: ', status
3515 end program chmod_test
3517 @code{CHMOD} as function:
3522 status = chmod('test.dat','u+x')
3523 print *, 'Status: ', status
3524 end program chmod_test
3532 @section @code{CMPLX} --- Complex conversion function
3534 @cindex complex numbers, conversion to
3535 @cindex conversion, to complex
3538 @item @emph{Description}:
3539 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
3540 the real component. If @var{Y} is present it is converted to the imaginary
3541 component. If @var{Y} is not present then the imaginary component is set to
3542 0.0. If @var{X} is complex then @var{Y} must not be present.
3544 @item @emph{Standard}:
3545 Fortran 77 and later
3550 @item @emph{Syntax}:
3551 @code{RESULT = CMPLX(X [, Y [, KIND]])}
3553 @item @emph{Arguments}:
3554 @multitable @columnfractions .15 .70
3555 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3557 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
3558 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
3559 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3560 expression indicating the kind parameter of the result.
3563 @item @emph{Return value}:
3564 The return value is of @code{COMPLEX} type, with a kind equal to
3565 @var{KIND} if it is specified. If @var{KIND} is not specified, the
3566 result is of the default @code{COMPLEX} kind, regardless of the kinds of
3567 @var{X} and @var{Y}.
3569 @item @emph{Example}:
3576 print *, z, cmplx(x)
3577 end program test_cmplx
3580 @item @emph{See also}:
3587 @section @code{CO_BROADCAST} --- Copy a value to all images the current set of images
3588 @fnindex CO_BROADCAST
3589 @cindex Collectives, value broadcasting
3592 @item @emph{Description}:
3593 @code{CO_BROADCAST} copies the value of argument @var{A} on the image with
3594 image index @code{SOURCE_IMAGE} to all images in the current team. @var{A}
3595 becomes defined as if by intrinsic assignment. If the execution was
3596 successful and @var{STAT} is present, it is assigned the value zero. If the
3597 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3598 @var{ERRMSG} gets assigned a value describing the occurred error.
3600 @item @emph{Standard}:
3601 Technical Specification (TS) 18508 or later
3604 Collective subroutine
3606 @item @emph{Syntax}:
3607 @code{CALL CO_BROADCAST(A, SOURCE_IMAGE [, STAT, ERRMSG])}
3609 @item @emph{Arguments}:
3610 @multitable @columnfractions .15 .70
3611 @item @var{A} @tab INTENT(INOUT) argument; shall have the same
3612 dynamic type and type paramters on all images of the current team. If it
3613 is an array, it shall have the same shape on all images.
3614 @item @var{SOURCE_IMAGE} @tab a scalar integer expression.
3615 It shall have the same the same value on all images and refer to an
3616 image of the current team.
3617 @item @var{STAT} @tab (optional) a scalar integer variable
3618 @item @var{ERRMSG} @tab (optional) a scalar character variable
3621 @item @emph{Example}:
3625 if (this_image() == 1) then
3628 call co_broadcast (val, source_image=1)
3629 print *, this_image, ":", val
3633 @item @emph{See also}:
3634 @ref{CO_MAX}, @ref{CO_MIN}, @ref{CO_SUM}, @ref{CO_REDUCE}
3640 @section @code{CO_MAX} --- Maximal value on the current set of images
3642 @cindex Collectives, maximal value
3645 @item @emph{Description}:
3646 @code{CO_MAX} determines element-wise the maximal value of @var{A} on all
3647 images of the current team. If @var{RESULT_IMAGE} is present, the maximum
3648 values are returned in @var{A} on the specified image only and the value
3649 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3650 not present, the value is returned on all images. If the execution was
3651 successful and @var{STAT} is present, it is assigned the value zero. If the
3652 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3653 @var{ERRMSG} gets assigned a value describing the occurred error.
3655 @item @emph{Standard}:
3656 Technical Specification (TS) 18508 or later
3659 Collective subroutine
3661 @item @emph{Syntax}:
3662 @code{CALL CO_MAX(A [, RESULT_IMAGE, STAT, ERRMSG])}
3664 @item @emph{Arguments}:
3665 @multitable @columnfractions .15 .70
3666 @item @var{A} @tab shall be an integer, real or character variable,
3667 which has the same type and type parameters on all images of the team.
3668 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3669 present, it shall have the same the same value on all images and refer to an
3670 image of the current team.
3671 @item @var{STAT} @tab (optional) a scalar integer variable
3672 @item @var{ERRMSG} @tab (optional) a scalar character variable
3675 @item @emph{Example}:
3680 call co_max (val, result_image=1)
3681 if (this_image() == 1) then
3682 write(*,*) "Maximal value", val ! prints num_images()
3687 @item @emph{See also}:
3688 @ref{CO_MIN}, @ref{CO_SUM}, @ref{CO_REDUCE}, @ref{CO_BROADCAST}
3694 @section @code{CO_MIN} --- Minimal value on the current set of images
3696 @cindex Collectives, minimal value
3699 @item @emph{Description}:
3700 @code{CO_MIN} determines element-wise the minimal value of @var{A} on all
3701 images of the current team. If @var{RESULT_IMAGE} is present, the minimal
3702 values are returned in @var{A} on the specified image only and the value
3703 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3704 not present, the value is returned on all images. If the execution was
3705 successful and @var{STAT} is present, it is assigned the value zero. If the
3706 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3707 @var{ERRMSG} gets assigned a value describing the occurred error.
3709 @item @emph{Standard}:
3710 Technical Specification (TS) 18508 or later
3713 Collective subroutine
3715 @item @emph{Syntax}:
3716 @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3718 @item @emph{Arguments}:
3719 @multitable @columnfractions .15 .70
3720 @item @var{A} @tab shall be an integer, real or character variable,
3721 which has the same type and type parameters on all images of the team.
3722 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3723 present, it shall have the same the same value on all images and refer to an
3724 image of the current team.
3725 @item @var{STAT} @tab (optional) a scalar integer variable
3726 @item @var{ERRMSG} @tab (optional) a scalar character variable
3729 @item @emph{Example}:
3734 call co_min (val, result_image=1)
3735 if (this_image() == 1) then
3736 write(*,*) "Minimal value", val ! prints 1
3741 @item @emph{See also}:
3742 @ref{CO_MAX}, @ref{CO_SUM}, @ref{CO_REDUCE}, @ref{CO_BROADCAST}
3748 @section @code{CO_REDUCE} --- Reduction of values on the current set of images
3750 @cindex Collectives, generic reduction
3753 @item @emph{Description}:
3754 @code{CO_REDUCE} determines element-wise the reduction of the value of @var{A}
3755 on all images of the current team. The pure function passed as @var{OPERATOR}
3756 is used to pairwise reduce the values of @var{A} by passing either the value
3757 of @var{A} of different images or the result values of such a reduction as
3758 argument. If @var{A} is an array, the deduction is done element wise. If
3759 @var{RESULT_IMAGE} is present, the result values are returned in @var{A} on
3760 the specified image only and the value of @var{A} on the other images become
3761 undefined. If @var{RESULT_IMAGE} is not present, the value is returned on all
3762 images. If the execution was successful and @var{STAT} is present, it is
3763 assigned the value zero. If the execution failed, @var{STAT} gets assigned
3764 a nonzero value and, if present, @var{ERRMSG} gets assigned a value describing
3767 @item @emph{Standard}:
3768 Technical Specification (TS) 18508 or later
3771 Collective subroutine
3773 @item @emph{Syntax}:
3774 @code{CALL CO_REDUCE(A, OPERATOR, [, RESULT_IMAGE, STAT, ERRMSG])}
3776 @item @emph{Arguments}:
3777 @multitable @columnfractions .15 .70
3778 @item @var{A} @tab is an @code{INTENT(INOUT)} argument and shall be
3779 nonpolymorphic. If it is allocatable, it shall be allocated; if it is a pointer,
3780 it shall be associated. @var{A} shall have the same type and type parameters on
3781 all images of the team; if it is an array, it shall have the same shape on all
3783 @item @var{OPERATOR} @tab pure function with two scalar nonallocatable
3784 arguments, which shall be nonpolymorphic and have the same type and type
3785 parameters as @var{A}. The function shall return a nonallocatable scalar of
3786 the same type and type parameters as @var{A}. The function shall be the same on
3787 all images and with regards to the arguments mathematically commutative and
3788 associative. Note that @var{OPERATOR} may not be an elemental function, unless
3789 it is an intrisic function.
3790 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3791 present, it shall have the same the same value on all images and refer to an
3792 image of the current team.
3793 @item @var{STAT} @tab (optional) a scalar integer variable
3794 @item @var{ERRMSG} @tab (optional) a scalar character variable
3797 @item @emph{Example}:
3802 call co_reduce (val, result_image=1, operator=myprod)
3803 if (this_image() == 1) then
3804 write(*,*) "Product value", val ! prints num_images() factorial
3807 pure function myprod(a, b)
3808 integer, value :: a, b
3816 While the rules permit in principle an intrinsic function, none of the
3817 intrinsics in the standard fulfill the criteria of having a specific
3818 function, which takes two arguments of the same type and returning that
3821 @item @emph{See also}:
3822 @ref{CO_MIN}, @ref{CO_MAX}, @ref{CO_SUM}, @ref{CO_BROADCAST}
3828 @section @code{CO_SUM} --- Sum of values on the current set of images
3830 @cindex Collectives, sum of values
3833 @item @emph{Description}:
3834 @code{CO_SUM} sums up the values of each element of @var{A} on all
3835 images of the current team. If @var{RESULT_IMAGE} is present, the summed-up
3836 values are returned in @var{A} on the specified image only and the value
3837 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3838 not present, the value is returned on all images. If the execution was
3839 successful and @var{STAT} is present, it is assigned the value zero. If the
3840 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3841 @var{ERRMSG} gets assigned a value describing the occurred error.
3843 @item @emph{Standard}:
3844 Technical Specification (TS) 18508 or later
3847 Collective subroutine
3849 @item @emph{Syntax}:
3850 @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3852 @item @emph{Arguments}:
3853 @multitable @columnfractions .15 .70
3854 @item @var{A} @tab shall be an integer, real or complex variable,
3855 which has the same type and type parameters on all images of the team.
3856 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3857 present, it shall have the same the same value on all images and refer to an
3858 image of the current team.
3859 @item @var{STAT} @tab (optional) a scalar integer variable
3860 @item @var{ERRMSG} @tab (optional) a scalar character variable
3863 @item @emph{Example}:
3868 call co_sum (val, result_image=1)
3869 if (this_image() == 1) then
3870 write(*,*) "The sum is ", val ! prints (n**2 + n)/2, with n = num_images()
3875 @item @emph{See also}:
3876 @ref{CO_MAX}, @ref{CO_MIN}, @ref{CO_REDUCE}, @ref{CO_BROADCAST}
3881 @node COMMAND_ARGUMENT_COUNT
3882 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
3883 @fnindex COMMAND_ARGUMENT_COUNT
3884 @cindex command-line arguments
3885 @cindex command-line arguments, number of
3886 @cindex arguments, to program
3889 @item @emph{Description}:
3890 @code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the
3891 command line when the containing program was invoked.
3893 @item @emph{Standard}:
3894 Fortran 2003 and later
3899 @item @emph{Syntax}:
3900 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
3902 @item @emph{Arguments}:
3903 @multitable @columnfractions .15 .70
3907 @item @emph{Return value}:
3908 The return value is an @code{INTEGER} of default kind.
3910 @item @emph{Example}:
3912 program test_command_argument_count
3914 count = command_argument_count()
3916 end program test_command_argument_count
3919 @item @emph{See also}:
3920 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
3925 @node COMPILER_OPTIONS
3926 @section @code{COMPILER_OPTIONS} --- Options passed to the compiler
3927 @fnindex COMPILER_OPTIONS
3928 @cindex flags inquiry function
3929 @cindex options inquiry function
3930 @cindex compiler flags inquiry function
3933 @item @emph{Description}:
3934 @code{COMPILER_OPTIONS} returns a string with the options used for
3937 @item @emph{Standard}:
3941 Inquiry function of the module @code{ISO_FORTRAN_ENV}
3943 @item @emph{Syntax}:
3944 @code{STR = COMPILER_OPTIONS()}
3946 @item @emph{Arguments}:
3949 @item @emph{Return value}:
3950 The return value is a default-kind string with system-dependent length.
3951 It contains the compiler flags used to compile the file, which called
3952 the @code{COMPILER_OPTIONS} intrinsic.
3954 @item @emph{Example}:
3957 print '(4a)', 'This file was compiled by ', &
3958 compiler_version(), ' using the options ', &
3963 @item @emph{See also}:
3964 @ref{COMPILER_VERSION}, @ref{ISO_FORTRAN_ENV}
3969 @node COMPILER_VERSION
3970 @section @code{COMPILER_VERSION} --- Compiler version string
3971 @fnindex COMPILER_VERSION
3972 @cindex compiler, name and version
3973 @cindex version of the compiler
3976 @item @emph{Description}:
3977 @code{COMPILER_VERSION} returns a string with the name and the
3978 version of the compiler.
3980 @item @emph{Standard}:
3984 Inquiry function of the module @code{ISO_FORTRAN_ENV}
3986 @item @emph{Syntax}:
3987 @code{STR = COMPILER_VERSION()}
3989 @item @emph{Arguments}:
3992 @item @emph{Return value}:
3993 The return value is a default-kind string with system-dependent length.
3994 It contains the name of the compiler and its version number.
3996 @item @emph{Example}:
3999 print '(4a)', 'This file was compiled by ', &
4000 compiler_version(), ' using the options ', &
4005 @item @emph{See also}:
4006 @ref{COMPILER_OPTIONS}, @ref{ISO_FORTRAN_ENV}
4012 @section @code{COMPLEX} --- Complex conversion function
4014 @cindex complex numbers, conversion to
4015 @cindex conversion, to complex
4018 @item @emph{Description}:
4019 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
4020 to the real component and @var{Y} is converted to the imaginary
4023 @item @emph{Standard}:
4029 @item @emph{Syntax}:
4030 @code{RESULT = COMPLEX(X, Y)}
4032 @item @emph{Arguments}:
4033 @multitable @columnfractions .15 .70
4034 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
4035 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
4038 @item @emph{Return value}:
4039 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
4040 value is of default @code{COMPLEX} type.
4042 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
4043 type and one is of @code{INTEGER} type, then the return value is of
4044 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
4045 argument with the highest precision.
4047 @item @emph{Example}:
4049 program test_complex
4052 print *, complex(i, x)
4053 end program test_complex
4056 @item @emph{See also}:
4063 @section @code{CONJG} --- Complex conjugate function
4066 @cindex complex conjugate
4069 @item @emph{Description}:
4070 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
4071 then the result is @code{(x, -y)}
4073 @item @emph{Standard}:
4074 Fortran 77 and later, has overloads that are GNU extensions
4079 @item @emph{Syntax}:
4082 @item @emph{Arguments}:
4083 @multitable @columnfractions .15 .70
4084 @item @var{Z} @tab The type shall be @code{COMPLEX}.
4087 @item @emph{Return value}:
4088 The return value is of type @code{COMPLEX}.
4090 @item @emph{Example}:
4093 complex :: z = (2.0, 3.0)
4094 complex(8) :: dz = (2.71_8, -3.14_8)
4099 end program test_conjg
4102 @item @emph{Specific names}:
4103 @multitable @columnfractions .20 .20 .20 .25
4104 @item Name @tab Argument @tab Return type @tab Standard
4105 @item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension
4106 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
4113 @section @code{COS} --- Cosine function
4119 @cindex trigonometric function, cosine
4123 @item @emph{Description}:
4124 @code{COS(X)} computes the cosine of @var{X}.
4126 @item @emph{Standard}:
4127 Fortran 77 and later, has overloads that are GNU extensions
4132 @item @emph{Syntax}:
4133 @code{RESULT = COS(X)}
4135 @item @emph{Arguments}:
4136 @multitable @columnfractions .15 .70
4137 @item @var{X} @tab The type shall be @code{REAL} or
4141 @item @emph{Return value}:
4142 The return value is of the same type and kind as @var{X}. The real part
4143 of the result is in radians. If @var{X} is of the type @code{REAL},
4144 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
4146 @item @emph{Example}:
4151 end program test_cos
4154 @item @emph{Specific names}:
4155 @multitable @columnfractions .20 .20 .20 .25
4156 @item Name @tab Argument @tab Return type @tab Standard
4157 @item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
4158 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
4159 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
4160 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4161 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4164 @item @emph{See also}:
4165 Inverse function: @ref{ACOS}
4166 Degrees function: @ref{COSD}
4173 @section @code{COSD} --- Cosine function, degrees
4179 @cindex trigonometric function, cosine, degrees
4180 @cindex cosine, degrees
4183 @item @emph{Description}:
4184 @code{COSD(X)} computes the cosine of @var{X} in degrees.
4186 This function is for compatibility only and should be avoided in favor of
4187 standard constructs wherever possible.
4189 @item @emph{Standard}:
4190 GNU Extension, enabled with @option{-fdec-math}.
4195 @item @emph{Syntax}:
4196 @code{RESULT = COSD(X)}
4198 @item @emph{Arguments}:
4199 @multitable @columnfractions .15 .70
4200 @item @var{X} @tab The type shall be @code{REAL} or
4204 @item @emph{Return value}:
4205 The return value is of the same type and kind as @var{X}. The real part
4206 of the result is in degrees. If @var{X} is of the type @code{REAL},
4207 the return value lies in the range @math{ -1 \leq \cosd (x) \leq 1}.
4209 @item @emph{Example}:
4214 end program test_cosd
4217 @item @emph{Specific names}:
4218 @multitable @columnfractions .20 .20 .20 .25
4219 @item Name @tab Argument @tab Return type @tab Standard
4220 @item @code{COSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4221 @item @code{DCOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4222 @item @code{CCOSD(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU Extension
4223 @item @code{ZCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4224 @item @code{CDCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4227 @item @emph{See also}:
4228 Inverse function: @ref{ACOSD}
4229 Radians function: @ref{COS}
4236 @section @code{COSH} --- Hyperbolic cosine function
4239 @cindex hyperbolic cosine
4240 @cindex hyperbolic function, cosine
4241 @cindex cosine, hyperbolic
4244 @item @emph{Description}:
4245 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
4247 @item @emph{Standard}:
4248 Fortran 77 and later, for a complex argument Fortran 2008 or later
4253 @item @emph{Syntax}:
4256 @item @emph{Arguments}:
4257 @multitable @columnfractions .15 .70
4258 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4261 @item @emph{Return value}:
4262 The return value has same type and kind as @var{X}. If @var{X} is
4263 complex, the imaginary part of the result is in radians. If @var{X}
4264 is @code{REAL}, the return value has a lower bound of one,
4265 @math{\cosh (x) \geq 1}.
4267 @item @emph{Example}:
4270 real(8) :: x = 1.0_8
4272 end program test_cosh
4275 @item @emph{Specific names}:
4276 @multitable @columnfractions .20 .20 .20 .25
4277 @item Name @tab Argument @tab Return type @tab Standard
4278 @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
4279 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
4282 @item @emph{See also}:
4283 Inverse function: @ref{ACOSH}
4290 @section @code{COTAN} --- Cotangent function
4293 @cindex trigonometric function, cotangent
4297 @item @emph{Description}:
4298 @code{COTAN(X)} computes the cotangent of @var{X}. Equivalent to @code{COS(x)}
4299 divided by @code{SIN(x)}, or @code{1 / TAN(x)}.
4301 This function is for compatibility only and should be avoided in favor of
4302 standard constructs wherever possible.
4304 @item @emph{Standard}:
4305 GNU Extension, enabled with @option{-fdec-math}.
4310 @item @emph{Syntax}:
4311 @code{RESULT = COTAN(X)}
4313 @item @emph{Arguments}:
4314 @multitable @columnfractions .15 .70
4315 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4318 @item @emph{Return value}:
4319 The return value has same type and kind as @var{X}, and its value is in radians.
4321 @item @emph{Example}:
4324 real(8) :: x = 0.165_8
4326 end program test_cotan
4329 @item @emph{Specific names}:
4330 @multitable @columnfractions .20 .20 .20 .25
4331 @item Name @tab Argument @tab Return type @tab Standard
4332 @item @code{COTAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4333 @item @code{DCOTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4336 @item @emph{See also}:
4337 Converse function: @ref{TAN}
4338 Degrees function: @ref{COTAND}
4344 @section @code{COTAND} --- Cotangent function, degrees
4347 @cindex trigonometric function, cotangent, degrees
4348 @cindex cotangent, degrees
4351 @item @emph{Description}:
4352 @code{COTAND(X)} computes the cotangent of @var{X} in degrees. Equivalent to
4353 @code{COSD(x)} divided by @code{SIND(x)}, or @code{1 / TAND(x)}.
4355 @item @emph{Standard}:
4356 GNU Extension, enabled with @option{-fdec-math}.
4358 This function is for compatibility only and should be avoided in favor of
4359 standard constructs wherever possible.
4364 @item @emph{Syntax}:
4365 @code{RESULT = COTAND(X)}
4367 @item @emph{Arguments}:
4368 @multitable @columnfractions .15 .70
4369 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4372 @item @emph{Return value}:
4373 The return value has same type and kind as @var{X}, and its value is in degrees.
4375 @item @emph{Example}:
4378 real(8) :: x = 0.165_8
4380 end program test_cotand
4383 @item @emph{Specific names}:
4384 @multitable @columnfractions .20 .20 .20 .25
4385 @item Name @tab Argument @tab Return type @tab Standard
4386 @item @code{COTAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4387 @item @code{DCOTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4390 @item @emph{See also}:
4391 Converse function: @ref{TAND}
4392 Radians function: @ref{COTAN}
4399 @section @code{COUNT} --- Count function
4401 @cindex array, conditionally count elements
4402 @cindex array, element counting
4403 @cindex array, number of elements
4406 @item @emph{Description}:
4408 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
4409 or, if the @var{DIM} argument is supplied, counts the number of
4410 elements along each row of the array in the @var{DIM} direction.
4411 If the array has zero size, or all of the elements of @var{MASK} are
4412 @code{.FALSE.}, then the result is @code{0}.
4414 @item @emph{Standard}:
4415 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
4418 Transformational function
4420 @item @emph{Syntax}:
4421 @code{RESULT = COUNT(MASK [, DIM, KIND])}
4423 @item @emph{Arguments}:
4424 @multitable @columnfractions .15 .70
4425 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
4426 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
4427 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4428 expression indicating the kind parameter of the result.
4431 @item @emph{Return value}:
4432 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
4433 @var{KIND} is absent, the return value is of default integer kind.
4434 If @var{DIM} is present, the result is an array with a rank one less
4435 than the rank of @var{ARRAY}, and a size corresponding to the shape
4436 of @var{ARRAY} with the @var{DIM} dimension removed.
4438 @item @emph{Example}:
4441 integer, dimension(2,3) :: a, b
4442 logical, dimension(2,3) :: mask
4443 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
4444 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
4445 print '(3i3)', a(1,:)
4446 print '(3i3)', a(2,:)
4448 print '(3i3)', b(1,:)
4449 print '(3i3)', b(2,:)
4452 print '(3l3)', mask(1,:)
4453 print '(3l3)', mask(2,:)
4455 print '(3i3)', count(mask)
4457 print '(3i3)', count(mask, 1)
4459 print '(3i3)', count(mask, 2)
4460 end program test_count
4467 @section @code{CPU_TIME} --- CPU elapsed time in seconds
4469 @cindex time, elapsed
4472 @item @emph{Description}:
4473 Returns a @code{REAL} value representing the elapsed CPU time in
4474 seconds. This is useful for testing segments of code to determine
4477 If a time source is available, time will be reported with microsecond
4478 resolution. If no time source is available, @var{TIME} is set to
4481 Note that @var{TIME} may contain a, system dependent, arbitrary offset
4482 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
4483 value is meaningless, only differences between subsequent calls to
4484 this subroutine, as shown in the example below, should be used.
4487 @item @emph{Standard}:
4488 Fortran 95 and later
4493 @item @emph{Syntax}:
4494 @code{CALL CPU_TIME(TIME)}
4496 @item @emph{Arguments}:
4497 @multitable @columnfractions .15 .70
4498 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
4501 @item @emph{Return value}:
4504 @item @emph{Example}:
4506 program test_cpu_time
4507 real :: start, finish
4508 call cpu_time(start)
4509 ! put code to test here
4510 call cpu_time(finish)
4511 print '("Time = ",f6.3," seconds.")',finish-start
4512 end program test_cpu_time
4515 @item @emph{See also}:
4516 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
4522 @section @code{CSHIFT} --- Circular shift elements of an array
4524 @cindex array, shift circularly
4525 @cindex array, permutation
4526 @cindex array, rotate
4529 @item @emph{Description}:
4530 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
4531 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
4532 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
4533 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
4534 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
4535 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
4536 sections of @var{ARRAY} along the given dimension are shifted. Elements
4537 shifted out one end of each rank one section are shifted back in the other end.
4539 @item @emph{Standard}:
4540 Fortran 95 and later
4543 Transformational function
4545 @item @emph{Syntax}:
4546 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
4548 @item @emph{Arguments}:
4549 @multitable @columnfractions .15 .70
4550 @item @var{ARRAY} @tab Shall be an array of any type.
4551 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
4552 @item @var{DIM} @tab The type shall be @code{INTEGER}.
4555 @item @emph{Return value}:
4556 Returns an array of same type and rank as the @var{ARRAY} argument.
4558 @item @emph{Example}:
4561 integer, dimension(3,3) :: a
4562 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
4563 print '(3i3)', a(1,:)
4564 print '(3i3)', a(2,:)
4565 print '(3i3)', a(3,:)
4566 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
4568 print '(3i3)', a(1,:)
4569 print '(3i3)', a(2,:)
4570 print '(3i3)', a(3,:)
4571 end program test_cshift
4578 @section @code{CTIME} --- Convert a time into a string
4580 @cindex time, conversion to string
4581 @cindex conversion, to string
4584 @item @emph{Description}:
4585 @code{CTIME} converts a system time value, such as returned by
4586 @code{TIME8}, to a string. The output will be of the form @samp{Sat
4587 Aug 19 18:13:14 1995}.
4589 This intrinsic is provided in both subroutine and function forms; however,
4590 only one form can be used in any given program unit.
4592 @item @emph{Standard}:
4596 Subroutine, function
4598 @item @emph{Syntax}:
4599 @multitable @columnfractions .80
4600 @item @code{CALL CTIME(TIME, RESULT)}.
4601 @item @code{RESULT = CTIME(TIME)}.
4604 @item @emph{Arguments}:
4605 @multitable @columnfractions .15 .70
4606 @item @var{TIME} @tab The type shall be of type @code{INTEGER}.
4607 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
4608 of default kind. It is an @code{INTENT(OUT)} argument. If the length
4609 of this variable is too short for the time and date string to fit
4610 completely, it will be blank on procedure return.
4613 @item @emph{Return value}:
4614 The converted date and time as a string.
4616 @item @emph{Example}:
4620 character(len=30) :: date
4623 ! Do something, main part of the program
4626 print *, 'Program was started on ', date
4627 end program test_ctime
4630 @item @emph{See Also}:
4631 @ref{DATE_AND_TIME}, @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
4637 @section @code{DATE_AND_TIME} --- Date and time subroutine
4638 @fnindex DATE_AND_TIME
4639 @cindex date, current
4640 @cindex current date
4641 @cindex time, current
4642 @cindex current time
4645 @item @emph{Description}:
4646 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
4647 time information from the real-time system clock. @var{DATE} is
4648 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
4649 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
4650 representing the difference with respect to Coordinated Universal Time (UTC).
4651 Unavailable time and date parameters return blanks.
4653 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
4655 @multitable @columnfractions .15 .30 .40
4656 @item @tab @code{VALUE(1)}: @tab The year
4657 @item @tab @code{VALUE(2)}: @tab The month
4658 @item @tab @code{VALUE(3)}: @tab The day of the month
4659 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
4660 @item @tab @code{VALUE(5)}: @tab The hour of the day
4661 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
4662 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
4663 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
4666 @item @emph{Standard}:
4667 Fortran 95 and later
4672 @item @emph{Syntax}:
4673 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
4675 @item @emph{Arguments}:
4676 @multitable @columnfractions .15 .70
4677 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
4678 or larger, and of default kind.
4679 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
4680 or larger, and of default kind.
4681 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
4682 or larger, and of default kind.
4683 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
4686 @item @emph{Return value}:
4689 @item @emph{Example}:
4691 program test_time_and_date
4692 character(8) :: date
4693 character(10) :: time
4694 character(5) :: zone
4695 integer,dimension(8) :: values
4696 ! using keyword arguments
4697 call date_and_time(date,time,zone,values)
4698 call date_and_time(DATE=date,ZONE=zone)
4699 call date_and_time(TIME=time)
4700 call date_and_time(VALUES=values)
4701 print '(a,2x,a,2x,a)', date, time, zone
4702 print '(8i5)', values
4703 end program test_time_and_date
4706 @item @emph{See also}:
4707 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
4713 @section @code{DBLE} --- Double conversion function
4715 @cindex conversion, to real
4718 @item @emph{Description}:
4719 @code{DBLE(A)} Converts @var{A} to double precision real type.
4721 @item @emph{Standard}:
4722 Fortran 77 and later
4727 @item @emph{Syntax}:
4728 @code{RESULT = DBLE(A)}
4730 @item @emph{Arguments}:
4731 @multitable @columnfractions .15 .70
4732 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
4736 @item @emph{Return value}:
4737 The return value is of type double precision real.
4739 @item @emph{Example}:
4744 complex :: z = (2.3,1.14)
4745 print *, dble(x), dble(i), dble(z)
4746 end program test_dble
4749 @item @emph{See also}:
4756 @section @code{DCMPLX} --- Double complex conversion function
4758 @cindex complex numbers, conversion to
4759 @cindex conversion, to complex
4762 @item @emph{Description}:
4763 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
4764 converted to the real component. If @var{Y} is present it is converted to the
4765 imaginary component. If @var{Y} is not present then the imaginary component is
4766 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
4768 @item @emph{Standard}:
4774 @item @emph{Syntax}:
4775 @code{RESULT = DCMPLX(X [, Y])}
4777 @item @emph{Arguments}:
4778 @multitable @columnfractions .15 .70
4779 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
4781 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
4782 @code{INTEGER} or @code{REAL}.
4785 @item @emph{Return value}:
4786 The return value is of type @code{COMPLEX(8)}
4788 @item @emph{Example}:
4798 print *, dcmplx(x,i)
4799 end program test_dcmplx
4805 @section @code{DIGITS} --- Significant binary digits function
4807 @cindex model representation, significant digits
4810 @item @emph{Description}:
4811 @code{DIGITS(X)} returns the number of significant binary digits of the internal
4812 model representation of @var{X}. For example, on a system using a 32-bit
4813 floating point representation, a default real number would likely return 24.
4815 @item @emph{Standard}:
4816 Fortran 95 and later
4821 @item @emph{Syntax}:
4822 @code{RESULT = DIGITS(X)}
4824 @item @emph{Arguments}:
4825 @multitable @columnfractions .15 .70
4826 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
4829 @item @emph{Return value}:
4830 The return value is of type @code{INTEGER}.
4832 @item @emph{Example}:
4835 integer :: i = 12345
4841 end program test_digits
4848 @section @code{DIM} --- Positive difference
4852 @cindex positive difference
4855 @item @emph{Description}:
4856 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
4857 otherwise returns zero.
4859 @item @emph{Standard}:
4860 Fortran 77 and later
4865 @item @emph{Syntax}:
4866 @code{RESULT = DIM(X, Y)}
4868 @item @emph{Arguments}:
4869 @multitable @columnfractions .15 .70
4870 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
4871 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
4874 @item @emph{Return value}:
4875 The return value is of type @code{INTEGER} or @code{REAL}.
4877 @item @emph{Example}:
4883 x = dim(4.345_8, 2.111_8)
4886 end program test_dim
4889 @item @emph{Specific names}:
4890 @multitable @columnfractions .20 .20 .20 .25
4891 @item Name @tab Argument @tab Return type @tab Standard
4892 @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
4893 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
4894 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
4901 @section @code{DOT_PRODUCT} --- Dot product function
4902 @fnindex DOT_PRODUCT
4904 @cindex vector product
4905 @cindex product, vector
4908 @item @emph{Description}:
4909 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
4910 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
4911 either numeric or logical and must be arrays of rank one and of equal size. If
4912 the vectors are @code{INTEGER} or @code{REAL}, the result is
4913 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
4914 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
4915 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
4917 @item @emph{Standard}:
4918 Fortran 95 and later
4921 Transformational function
4923 @item @emph{Syntax}:
4924 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
4926 @item @emph{Arguments}:
4927 @multitable @columnfractions .15 .70
4928 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
4929 @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.
4932 @item @emph{Return value}:
4933 If the arguments are numeric, the return value is a scalar of numeric type,
4934 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
4935 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
4937 @item @emph{Example}:
4939 program test_dot_prod
4940 integer, dimension(3) :: a, b
4947 print *, dot_product(a,b)
4948 end program test_dot_prod
4955 @section @code{DPROD} --- Double product function
4957 @cindex product, double-precision
4960 @item @emph{Description}:
4961 @code{DPROD(X,Y)} returns the product @code{X*Y}.
4963 @item @emph{Standard}:
4964 Fortran 77 and later
4969 @item @emph{Syntax}:
4970 @code{RESULT = DPROD(X, Y)}
4972 @item @emph{Arguments}:
4973 @multitable @columnfractions .15 .70
4974 @item @var{X} @tab The type shall be @code{REAL}.
4975 @item @var{Y} @tab The type shall be @code{REAL}.
4978 @item @emph{Return value}:
4979 The return value is of type @code{REAL(8)}.
4981 @item @emph{Example}:
4989 end program test_dprod
4992 @item @emph{Specific names}:
4993 @multitable @columnfractions .20 .20 .20 .25
4994 @item Name @tab Argument @tab Return type @tab Standard
4995 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
5002 @section @code{DREAL} --- Double real part function
5004 @cindex complex numbers, real part
5007 @item @emph{Description}:
5008 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
5010 @item @emph{Standard}:
5016 @item @emph{Syntax}:
5017 @code{RESULT = DREAL(A)}
5019 @item @emph{Arguments}:
5020 @multitable @columnfractions .15 .70
5021 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
5024 @item @emph{Return value}:
5025 The return value is of type @code{REAL(8)}.
5027 @item @emph{Example}:
5030 complex(8) :: z = (1.3_8,7.2_8)
5032 end program test_dreal
5035 @item @emph{See also}:
5043 @section @code{DSHIFTL} --- Combined left shift
5045 @cindex left shift, combined
5049 @item @emph{Description}:
5050 @code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
5051 rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
5052 bits of @var{J}, and the remaining bits are the rightmost bits of
5055 @item @emph{Standard}:
5056 Fortran 2008 and later
5061 @item @emph{Syntax}:
5062 @code{RESULT = DSHIFTL(I, J, SHIFT)}
5064 @item @emph{Arguments}:
5065 @multitable @columnfractions .15 .70
5066 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5067 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5068 If both @var{I} and @var{J} have integer type, then they shall have
5069 the same kind type parameter. @var{I} and @var{J} shall not both be
5071 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
5072 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
5073 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
5074 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
5077 @item @emph{Return value}:
5078 If either @var{I} or @var{J} is a BOZ constant, it is first converted
5079 as if by the intrinsic function @code{INT} to an integer type with the
5080 kind type parameter of the other.
5082 @item @emph{See also}:
5088 @section @code{DSHIFTR} --- Combined right shift
5090 @cindex right shift, combined
5091 @cindex shift, right
5094 @item @emph{Description}:
5095 @code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
5096 leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
5097 bits of @var{I}, and the remaining bits are the leftmost bits of
5100 @item @emph{Standard}:
5101 Fortran 2008 and later
5106 @item @emph{Syntax}:
5107 @code{RESULT = DSHIFTR(I, J, SHIFT)}
5109 @item @emph{Arguments}:
5110 @multitable @columnfractions .15 .70
5111 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5112 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5113 If both @var{I} and @var{J} have integer type, then they shall have
5114 the same kind type parameter. @var{I} and @var{J} shall not both be
5116 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
5117 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
5118 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
5119 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
5122 @item @emph{Return value}:
5123 If either @var{I} or @var{J} is a BOZ constant, it is first converted
5124 as if by the intrinsic function @code{INT} to an integer type with the
5125 kind type parameter of the other.
5127 @item @emph{See also}:
5133 @section @code{DTIME} --- Execution time subroutine (or function)
5135 @cindex time, elapsed
5136 @cindex elapsed time
5139 @item @emph{Description}:
5140 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
5141 since the start of the process's execution in @var{TIME}. @var{VALUES}
5142 returns the user and system components of this time in @code{VALUES(1)} and
5143 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
5146 Subsequent invocations of @code{DTIME} return values accumulated since the
5147 previous invocation.
5149 On some systems, the underlying timings are represented using types with
5150 sufficiently small limits that overflows (wrap around) are possible, such as
5151 32-bit types. Therefore, the values returned by this intrinsic might be, or
5152 become, negative, or numerically less than previous values, during a single
5153 run of the compiled program.
5155 Please note, that this implementation is thread safe if used within OpenMP
5156 directives, i.e., its state will be consistent while called from multiple
5157 threads. However, if @code{DTIME} is called from multiple threads, the result
5158 is still the time since the last invocation. This may not give the intended
5159 results. If possible, use @code{CPU_TIME} instead.
5161 This intrinsic is provided in both subroutine and function forms; however,
5162 only one form can be used in any given program unit.
5164 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
5166 @multitable @columnfractions .15 .30 .40
5167 @item @tab @code{VALUES(1)}: @tab User time in seconds.
5168 @item @tab @code{VALUES(2)}: @tab System time in seconds.
5169 @item @tab @code{TIME}: @tab Run time since start in seconds.
5172 @item @emph{Standard}:
5176 Subroutine, function
5178 @item @emph{Syntax}:
5179 @multitable @columnfractions .80
5180 @item @code{CALL DTIME(VALUES, TIME)}.
5181 @item @code{TIME = DTIME(VALUES)}, (not recommended).
5184 @item @emph{Arguments}:
5185 @multitable @columnfractions .15 .70
5186 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
5187 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
5190 @item @emph{Return value}:
5191 Elapsed time in seconds since the last invocation or since the start of program
5192 execution if not called before.
5194 @item @emph{Example}:
5198 real, dimension(2) :: tarray
5200 call dtime(tarray, result)
5204 do i=1,100000000 ! Just a delay
5207 call dtime(tarray, result)
5211 end program test_dtime
5214 @item @emph{See also}:
5222 @section @code{EOSHIFT} --- End-off shift elements of an array
5224 @cindex array, shift
5227 @item @emph{Description}:
5228 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
5229 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
5230 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
5231 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
5232 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
5233 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
5234 then all complete rank one sections of @var{ARRAY} along the given dimension are
5235 shifted. Elements shifted out one end of each rank one section are dropped. If
5236 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
5237 is copied back in the other end. If @var{BOUNDARY} is not present then the
5238 following are copied in depending on the type of @var{ARRAY}.
5240 @multitable @columnfractions .15 .80
5241 @item @emph{Array Type} @tab @emph{Boundary Value}
5242 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
5243 @item Logical @tab @code{.FALSE.}.
5244 @item Character(@var{len}) @tab @var{len} blanks.
5247 @item @emph{Standard}:
5248 Fortran 95 and later
5251 Transformational function
5253 @item @emph{Syntax}:
5254 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
5256 @item @emph{Arguments}:
5257 @multitable @columnfractions .15 .70
5258 @item @var{ARRAY} @tab May be any type, not scalar.
5259 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
5260 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
5261 @item @var{DIM} @tab The type shall be @code{INTEGER}.
5264 @item @emph{Return value}:
5265 Returns an array of same type and rank as the @var{ARRAY} argument.
5267 @item @emph{Example}:
5269 program test_eoshift
5270 integer, dimension(3,3) :: a
5271 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
5272 print '(3i3)', a(1,:)
5273 print '(3i3)', a(2,:)
5274 print '(3i3)', a(3,:)
5275 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
5277 print '(3i3)', a(1,:)
5278 print '(3i3)', a(2,:)
5279 print '(3i3)', a(3,:)
5280 end program test_eoshift
5287 @section @code{EPSILON} --- Epsilon function
5289 @cindex model representation, epsilon
5292 @item @emph{Description}:
5293 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
5294 as @var{X} such that @math{1 + E > 1}.
5296 @item @emph{Standard}:
5297 Fortran 95 and later
5302 @item @emph{Syntax}:
5303 @code{RESULT = EPSILON(X)}
5305 @item @emph{Arguments}:
5306 @multitable @columnfractions .15 .70
5307 @item @var{X} @tab The type shall be @code{REAL}.
5310 @item @emph{Return value}:
5311 The return value is of same type as the argument.
5313 @item @emph{Example}:
5315 program test_epsilon
5320 end program test_epsilon
5327 @section @code{ERF} --- Error function
5329 @cindex error function
5332 @item @emph{Description}:
5333 @code{ERF(X)} computes the error function of @var{X}.
5335 @item @emph{Standard}:
5336 Fortran 2008 and later
5341 @item @emph{Syntax}:
5342 @code{RESULT = ERF(X)}
5344 @item @emph{Arguments}:
5345 @multitable @columnfractions .15 .70
5346 @item @var{X} @tab The type shall be @code{REAL}.
5349 @item @emph{Return value}:
5350 The return value is of type @code{REAL}, of the same kind as
5351 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
5353 @item @emph{Example}:
5356 real(8) :: x = 0.17_8
5358 end program test_erf
5361 @item @emph{Specific names}:
5362 @multitable @columnfractions .20 .20 .20 .25
5363 @item Name @tab Argument @tab Return type @tab Standard
5364 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
5371 @section @code{ERFC} --- Error function
5373 @cindex error function, complementary
5376 @item @emph{Description}:
5377 @code{ERFC(X)} computes the complementary error function of @var{X}.
5379 @item @emph{Standard}:
5380 Fortran 2008 and later
5385 @item @emph{Syntax}:
5386 @code{RESULT = ERFC(X)}
5388 @item @emph{Arguments}:
5389 @multitable @columnfractions .15 .70
5390 @item @var{X} @tab The type shall be @code{REAL}.
5393 @item @emph{Return value}:
5394 The return value is of type @code{REAL} and of the same kind as @var{X}.
5395 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
5397 @item @emph{Example}:
5400 real(8) :: x = 0.17_8
5402 end program test_erfc
5405 @item @emph{Specific names}:
5406 @multitable @columnfractions .20 .20 .20 .25
5407 @item Name @tab Argument @tab Return type @tab Standard
5408 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
5415 @section @code{ERFC_SCALED} --- Error function
5416 @fnindex ERFC_SCALED
5417 @cindex error function, complementary, exponentially-scaled
5420 @item @emph{Description}:
5421 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
5422 error function of @var{X}.
5424 @item @emph{Standard}:
5425 Fortran 2008 and later
5430 @item @emph{Syntax}:
5431 @code{RESULT = ERFC_SCALED(X)}
5433 @item @emph{Arguments}:
5434 @multitable @columnfractions .15 .70
5435 @item @var{X} @tab The type shall be @code{REAL}.
5438 @item @emph{Return value}:
5439 The return value is of type @code{REAL} and of the same kind as @var{X}.
5441 @item @emph{Example}:
5443 program test_erfc_scaled
5444 real(8) :: x = 0.17_8
5446 end program test_erfc_scaled
5453 @section @code{ETIME} --- Execution time subroutine (or function)
5455 @cindex time, elapsed
5458 @item @emph{Description}:
5459 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
5460 since the start of the process's execution in @var{TIME}. @var{VALUES}
5461 returns the user and system components of this time in @code{VALUES(1)} and
5462 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
5464 On some systems, the underlying timings are represented using types with
5465 sufficiently small limits that overflows (wrap around) are possible, such as
5466 32-bit types. Therefore, the values returned by this intrinsic might be, or
5467 become, negative, or numerically less than previous values, during a single
5468 run of the compiled program.
5470 This intrinsic is provided in both subroutine and function forms; however,
5471 only one form can be used in any given program unit.
5473 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
5475 @multitable @columnfractions .15 .30 .60
5476 @item @tab @code{VALUES(1)}: @tab User time in seconds.
5477 @item @tab @code{VALUES(2)}: @tab System time in seconds.
5478 @item @tab @code{TIME}: @tab Run time since start in seconds.
5481 @item @emph{Standard}:
5485 Subroutine, function
5487 @item @emph{Syntax}:
5488 @multitable @columnfractions .80
5489 @item @code{CALL ETIME(VALUES, TIME)}.
5490 @item @code{TIME = ETIME(VALUES)}, (not recommended).
5493 @item @emph{Arguments}:
5494 @multitable @columnfractions .15 .70
5495 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
5496 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
5499 @item @emph{Return value}:
5500 Elapsed time in seconds since the start of program execution.
5502 @item @emph{Example}:
5506 real, dimension(2) :: tarray
5508 call ETIME(tarray, result)
5512 do i=1,100000000 ! Just a delay
5515 call ETIME(tarray, result)
5519 end program test_etime
5522 @item @emph{See also}:
5530 @section @code{EVENT_QUERY} --- Query whether a coarray event has occurred
5531 @fnindex EVENT_QUERY
5532 @cindex Events, EVENT_QUERY
5535 @item @emph{Description}:
5536 @code{EVENT_QUERY} assignes the number of events to @var{COUNT} which have been
5537 posted to the @var{EVENT} variable and not yet been removed by calling
5538 @code{EVENT WAIT}. When @var{STAT} is present and the invokation was successful,
5539 it is assigned the value 0. If it is present and the invokation has failed,
5540 it is assigned a positive value and @var{COUNT} is assigned the value @math{-1}.
5542 @item @emph{Standard}:
5548 @item @emph{Syntax}:
5549 @code{CALL EVENT_QUERY (EVENT, COUNT [, STAT])}
5551 @item @emph{Arguments}:
5552 @multitable @columnfractions .15 .70
5553 @item @var{EVENT} @tab (intent(IN)) Scalar of type @code{EVENT_TYPE},
5554 defined in @code{ISO_FORTRAN_ENV}; shall not be coindexed.
5555 @item @var{COUNT} @tab (intent(out))Scalar integer with at least the
5556 precision of default integer.
5557 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
5560 @item @emph{Example}:
5565 type(event_type) :: event_value_has_been_set[*]
5567 if (this_image() == 1) then
5568 call event_query (event_value_has_been_set, cnt)
5569 if (cnt > 0) write(*,*) "Value has been set"
5570 elseif (this_image() == 2) then
5571 event post (event_value_has_been_set[1])
5580 @node EXECUTE_COMMAND_LINE
5581 @section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
5582 @fnindex EXECUTE_COMMAND_LINE
5583 @cindex system, system call
5584 @cindex command line
5587 @item @emph{Description}:
5588 @code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
5591 The @code{COMMAND} argument is passed to the shell and executed, using
5592 the C library's @code{system} call. (The shell is @code{sh} on Unix
5593 systems, and @code{cmd.exe} on Windows.) If @code{WAIT} is present
5594 and has the value false, the execution of the command is asynchronous
5595 if the system supports it; otherwise, the command is executed
5598 The three last arguments allow the user to get status information. After
5599 synchronous execution, @code{EXITSTAT} contains the integer exit code of
5600 the command, as returned by @code{system}. @code{CMDSTAT} is set to zero
5601 if the command line was executed (whatever its exit status was).
5602 @code{CMDMSG} is assigned an error message if an error has occurred.
5604 Note that the @code{system} function need not be thread-safe. It is
5605 the responsibility of the user to ensure that @code{system} is not
5606 called concurrently.
5608 @item @emph{Standard}:
5609 Fortran 2008 and later
5614 @item @emph{Syntax}:
5615 @code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
5617 @item @emph{Arguments}:
5618 @multitable @columnfractions .15 .70
5619 @item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
5620 @item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
5621 @item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5623 @item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5625 @item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
5629 @item @emph{Example}:
5634 call execute_command_line ("external_prog.exe", exitstat=i)
5635 print *, "Exit status of external_prog.exe was ", i
5637 call execute_command_line ("reindex_files.exe", wait=.false.)
5638 print *, "Now reindexing files in the background"
5640 end program test_exec
5646 Because this intrinsic is implemented in terms of the @code{system}
5647 function call, its behavior with respect to signaling is processor
5648 dependent. In particular, on POSIX-compliant systems, the SIGINT and
5649 SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
5650 such, if the parent process is terminated, the child process might not be
5651 terminated alongside.
5654 @item @emph{See also}:
5661 @section @code{EXIT} --- Exit the program with status.
5663 @cindex program termination
5664 @cindex terminate program
5667 @item @emph{Description}:
5668 @code{EXIT} causes immediate termination of the program with status. If status
5669 is omitted it returns the canonical @emph{success} for the system. All Fortran
5670 I/O units are closed.
5672 @item @emph{Standard}:
5678 @item @emph{Syntax}:
5679 @code{CALL EXIT([STATUS])}
5681 @item @emph{Arguments}:
5682 @multitable @columnfractions .15 .70
5683 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
5686 @item @emph{Return value}:
5687 @code{STATUS} is passed to the parent process on exit.
5689 @item @emph{Example}:
5692 integer :: STATUS = 0
5693 print *, 'This program is going to exit.'
5695 end program test_exit
5698 @item @emph{See also}:
5699 @ref{ABORT}, @ref{KILL}
5705 @section @code{EXP} --- Exponential function
5711 @cindex exponential function
5712 @cindex logarithm function, inverse
5715 @item @emph{Description}:
5716 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
5718 @item @emph{Standard}:
5719 Fortran 77 and later, has overloads that are GNU extensions
5724 @item @emph{Syntax}:
5725 @code{RESULT = EXP(X)}
5727 @item @emph{Arguments}:
5728 @multitable @columnfractions .15 .70
5729 @item @var{X} @tab The type shall be @code{REAL} or
5733 @item @emph{Return value}:
5734 The return value has same type and kind as @var{X}.
5736 @item @emph{Example}:
5741 end program test_exp
5744 @item @emph{Specific names}:
5745 @multitable @columnfractions .20 .20 .20 .25
5746 @item Name @tab Argument @tab Return type @tab Standard
5747 @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
5748 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
5749 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
5750 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5751 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5758 @section @code{EXPONENT} --- Exponent function
5760 @cindex real number, exponent
5761 @cindex floating point, exponent
5764 @item @emph{Description}:
5765 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
5766 is zero the value returned is zero.
5768 @item @emph{Standard}:
5769 Fortran 95 and later
5774 @item @emph{Syntax}:
5775 @code{RESULT = EXPONENT(X)}
5777 @item @emph{Arguments}:
5778 @multitable @columnfractions .15 .70
5779 @item @var{X} @tab The type shall be @code{REAL}.
5782 @item @emph{Return value}:
5783 The return value is of type default @code{INTEGER}.
5785 @item @emph{Example}:
5787 program test_exponent
5792 print *, exponent(0.0)
5793 end program test_exponent
5799 @node EXTENDS_TYPE_OF
5800 @section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension
5801 @fnindex EXTENDS_TYPE_OF
5804 @item @emph{Description}:
5805 Query dynamic type for extension.
5807 @item @emph{Standard}:
5808 Fortran 2003 and later
5813 @item @emph{Syntax}:
5814 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
5816 @item @emph{Arguments}:
5817 @multitable @columnfractions .15 .70
5818 @item @var{A} @tab Shall be an object of extensible declared type or
5819 unlimited polymorphic.
5820 @item @var{MOLD} @tab Shall be an object of extensible declared type or
5821 unlimited polymorphic.
5824 @item @emph{Return value}:
5825 The return value is a scalar of type default logical. It is true if and only if
5826 the dynamic type of A is an extension type of the dynamic type of MOLD.
5829 @item @emph{See also}:
5836 @section @code{FDATE} --- Get the current time as a string
5838 @cindex time, current
5839 @cindex current time
5840 @cindex date, current
5841 @cindex current date
5844 @item @emph{Description}:
5845 @code{FDATE(DATE)} returns the current date (using the same format as
5846 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
5849 This intrinsic is provided in both subroutine and function forms; however,
5850 only one form can be used in any given program unit.
5852 @item @emph{Standard}:
5856 Subroutine, function
5858 @item @emph{Syntax}:
5859 @multitable @columnfractions .80
5860 @item @code{CALL FDATE(DATE)}.
5861 @item @code{DATE = FDATE()}.
5864 @item @emph{Arguments}:
5865 @multitable @columnfractions .15 .70
5866 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
5867 default kind. It is an @code{INTENT(OUT)} argument. If the length of
5868 this variable is too short for the date and time string to fit
5869 completely, it will be blank on procedure return.
5872 @item @emph{Return value}:
5873 The current date and time as a string.
5875 @item @emph{Example}:
5879 character(len=30) :: date
5881 print *, 'Program started on ', date
5882 do i = 1, 100000000 ! Just a delay
5886 print *, 'Program ended on ', date
5887 end program test_fdate
5890 @item @emph{See also}:
5891 @ref{DATE_AND_TIME}, @ref{CTIME}
5896 @section @code{FGET} --- Read a single character in stream mode from stdin
5898 @cindex read character, stream mode
5899 @cindex stream mode, read character
5900 @cindex file operation, read character
5903 @item @emph{Description}:
5904 Read a single character in stream mode from stdin by bypassing normal
5905 formatted output. Stream I/O should not be mixed with normal record-oriented
5906 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
5908 This intrinsic is provided in both subroutine and function forms; however,
5909 only one form can be used in any given program unit.
5911 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
5912 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5913 Programmers should consider the use of new stream IO feature in new code
5914 for future portability. See also @ref{Fortran 2003 status}.
5916 @item @emph{Standard}:
5920 Subroutine, function
5922 @item @emph{Syntax}:
5923 @multitable @columnfractions .80
5924 @item @code{CALL FGET(C [, STATUS])}
5925 @item @code{STATUS = FGET(C)}
5928 @item @emph{Arguments}:
5929 @multitable @columnfractions .15 .70
5930 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5932 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5933 Returns 0 on success, -1 on end-of-file, and a system specific positive
5934 error code otherwise.
5937 @item @emph{Example}:
5940 INTEGER, PARAMETER :: strlen = 100
5941 INTEGER :: status, i = 1
5942 CHARACTER(len=strlen) :: str = ""
5944 WRITE (*,*) 'Enter text:'
5946 CALL fget(str(i:i), status)
5947 if (status /= 0 .OR. i > strlen) exit
5950 WRITE (*,*) TRIM(str)
5954 @item @emph{See also}:
5955 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
5961 @section @code{FGETC} --- Read a single character in stream mode
5963 @cindex read character, stream mode
5964 @cindex stream mode, read character
5965 @cindex file operation, read character
5968 @item @emph{Description}:
5969 Read a single character in stream mode by bypassing normal formatted output.
5970 Stream I/O should not be mixed with normal record-oriented (formatted or
5971 unformatted) I/O on the same unit; the results are unpredictable.
5973 This intrinsic is provided in both subroutine and function forms; however,
5974 only one form can be used in any given program unit.
5976 Note that the @code{FGET} intrinsic is provided for backwards compatibility
5977 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5978 Programmers should consider the use of new stream IO feature in new code
5979 for future portability. See also @ref{Fortran 2003 status}.
5981 @item @emph{Standard}:
5985 Subroutine, function
5987 @item @emph{Syntax}:
5988 @multitable @columnfractions .80
5989 @item @code{CALL FGETC(UNIT, C [, STATUS])}
5990 @item @code{STATUS = FGETC(UNIT, C)}
5993 @item @emph{Arguments}:
5994 @multitable @columnfractions .15 .70
5995 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
5996 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5998 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5999 Returns 0 on success, -1 on end-of-file and a system specific positive
6000 error code otherwise.
6003 @item @emph{Example}:
6006 INTEGER :: fd = 42, status
6009 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
6011 CALL fgetc(fd, c, status)
6012 IF (status /= 0) EXIT
6019 @item @emph{See also}:
6020 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
6026 @section @code{FLOOR} --- Integer floor function
6029 @cindex rounding, floor
6032 @item @emph{Description}:
6033 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
6035 @item @emph{Standard}:
6036 Fortran 95 and later
6041 @item @emph{Syntax}:
6042 @code{RESULT = FLOOR(A [, KIND])}
6044 @item @emph{Arguments}:
6045 @multitable @columnfractions .15 .70
6046 @item @var{A} @tab The type shall be @code{REAL}.
6047 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6048 expression indicating the kind parameter of the result.
6051 @item @emph{Return value}:
6052 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
6053 and of default-kind @code{INTEGER} otherwise.
6055 @item @emph{Example}:
6060 print *, floor(x) ! returns 63
6061 print *, floor(y) ! returns -64
6062 end program test_floor
6065 @item @emph{See also}:
6066 @ref{CEILING}, @ref{NINT}
6073 @section @code{FLUSH} --- Flush I/O unit(s)
6075 @cindex file operation, flush
6078 @item @emph{Description}:
6079 Flushes Fortran unit(s) currently open for output. Without the optional
6080 argument, all units are flushed, otherwise just the unit specified.
6082 @item @emph{Standard}:
6088 @item @emph{Syntax}:
6089 @code{CALL FLUSH(UNIT)}
6091 @item @emph{Arguments}:
6092 @multitable @columnfractions .15 .70
6093 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
6097 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
6098 statement that should be preferred over the @code{FLUSH} intrinsic.
6100 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
6101 have identical effect: they flush the runtime library's I/O buffer so
6102 that the data becomes visible to other processes. This does not guarantee
6103 that the data is committed to disk.
6105 On POSIX systems, you can request that all data is transferred to the
6106 storage device by calling the @code{fsync} function, with the POSIX file
6107 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
6108 @code{FNUM}). The following example shows how:
6111 ! Declare the interface for POSIX fsync function
6113 function fsync (fd) bind(c,name="fsync")
6114 use iso_c_binding, only: c_int
6115 integer(c_int), value :: fd
6116 integer(c_int) :: fsync
6120 ! Variable declaration
6124 open (10,file="foo")
6127 ! Perform I/O on unit 10
6132 ret = fsync(fnum(10))
6134 ! Handle possible error
6135 if (ret /= 0) stop "Error calling FSYNC"
6143 @section @code{FNUM} --- File number function
6145 @cindex file operation, file number
6148 @item @emph{Description}:
6149 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
6150 open Fortran I/O unit @code{UNIT}.
6152 @item @emph{Standard}:
6158 @item @emph{Syntax}:
6159 @code{RESULT = FNUM(UNIT)}
6161 @item @emph{Arguments}:
6162 @multitable @columnfractions .15 .70
6163 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
6166 @item @emph{Return value}:
6167 The return value is of type @code{INTEGER}
6169 @item @emph{Example}:
6173 open (unit=10, status = "scratch")
6177 end program test_fnum
6184 @section @code{FPUT} --- Write a single character in stream mode to stdout
6186 @cindex write character, stream mode
6187 @cindex stream mode, write character
6188 @cindex file operation, write character
6191 @item @emph{Description}:
6192 Write a single character in stream mode to stdout by bypassing normal
6193 formatted output. Stream I/O should not be mixed with normal record-oriented
6194 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
6196 This intrinsic is provided in both subroutine and function forms; however,
6197 only one form can be used in any given program unit.
6199 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
6200 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
6201 Programmers should consider the use of new stream IO feature in new code
6202 for future portability. See also @ref{Fortran 2003 status}.
6204 @item @emph{Standard}:
6208 Subroutine, function
6210 @item @emph{Syntax}:
6211 @multitable @columnfractions .80
6212 @item @code{CALL FPUT(C [, STATUS])}
6213 @item @code{STATUS = FPUT(C)}
6216 @item @emph{Arguments}:
6217 @multitable @columnfractions .15 .70
6218 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6220 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6221 Returns 0 on success, -1 on end-of-file and a system specific positive
6222 error code otherwise.
6225 @item @emph{Example}:
6228 CHARACTER(len=10) :: str = "gfortran"
6230 DO i = 1, len_trim(str)
6236 @item @emph{See also}:
6237 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
6243 @section @code{FPUTC} --- Write a single character in stream mode
6245 @cindex write character, stream mode
6246 @cindex stream mode, write character
6247 @cindex file operation, write character
6250 @item @emph{Description}:
6251 Write a single character in stream mode by bypassing normal formatted
6252 output. Stream I/O should not be mixed with normal record-oriented
6253 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
6255 This intrinsic is provided in both subroutine and function forms; however,
6256 only one form can be used in any given program unit.
6258 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
6259 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
6260 Programmers should consider the use of new stream IO feature in new code
6261 for future portability. See also @ref{Fortran 2003 status}.
6263 @item @emph{Standard}:
6267 Subroutine, function
6269 @item @emph{Syntax}:
6270 @multitable @columnfractions .80
6271 @item @code{CALL FPUTC(UNIT, C [, STATUS])}
6272 @item @code{STATUS = FPUTC(UNIT, C)}
6275 @item @emph{Arguments}:
6276 @multitable @columnfractions .15 .70
6277 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
6278 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6280 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6281 Returns 0 on success, -1 on end-of-file and a system specific positive
6282 error code otherwise.
6285 @item @emph{Example}:
6288 CHARACTER(len=10) :: str = "gfortran"
6289 INTEGER :: fd = 42, i
6291 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
6292 DO i = 1, len_trim(str)
6293 CALL fputc(fd, str(i:i))
6299 @item @emph{See also}:
6300 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
6306 @section @code{FRACTION} --- Fractional part of the model representation
6308 @cindex real number, fraction
6309 @cindex floating point, fraction
6312 @item @emph{Description}:
6313 @code{FRACTION(X)} returns the fractional part of the model
6314 representation of @code{X}.
6316 @item @emph{Standard}:
6317 Fortran 95 and later
6322 @item @emph{Syntax}:
6323 @code{Y = FRACTION(X)}
6325 @item @emph{Arguments}:
6326 @multitable @columnfractions .15 .70
6327 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
6330 @item @emph{Return value}:
6331 The return value is of the same type and kind as the argument.
6332 The fractional part of the model representation of @code{X} is returned;
6333 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
6335 @item @emph{Example}:
6337 program test_fraction
6340 print *, fraction(x), x * radix(x)**(-exponent(x))
6341 end program test_fraction
6349 @section @code{FREE} --- Frees memory
6351 @cindex pointer, cray
6354 @item @emph{Description}:
6355 Frees memory previously allocated by @code{MALLOC}. The @code{FREE}
6356 intrinsic is an extension intended to be used with Cray pointers, and is
6357 provided in GNU Fortran to allow user to compile legacy code. For
6358 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
6361 @item @emph{Standard}:
6367 @item @emph{Syntax}:
6368 @code{CALL FREE(PTR)}
6370 @item @emph{Arguments}:
6371 @multitable @columnfractions .15 .70
6372 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
6373 location of the memory that should be de-allocated.
6376 @item @emph{Return value}:
6379 @item @emph{Example}:
6380 See @code{MALLOC} for an example.
6382 @item @emph{See also}:
6389 @section @code{FSEEK} --- Low level file positioning subroutine
6391 @cindex file operation, seek
6392 @cindex file operation, position
6395 @item @emph{Description}:
6396 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
6397 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
6398 if set to 1, @var{OFFSET} is taken to be relative to the current position
6399 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
6400 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
6403 This intrinsic routine is not fully backwards compatible with @command{g77}.
6404 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
6405 @var{STATUS} variable. If FSEEK is used in old code, change
6407 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
6412 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
6413 IF (status /= 0) GOTO label
6416 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
6417 Programmers should consider the use of new stream IO feature in new code
6418 for future portability. See also @ref{Fortran 2003 status}.
6420 @item @emph{Standard}:
6426 @item @emph{Syntax}:
6427 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
6429 @item @emph{Arguments}:
6430 @multitable @columnfractions .15 .70
6431 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
6432 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
6433 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
6434 Its value shall be either 0, 1 or 2.
6435 @item @var{STATUS} @tab (Optional) shall be a scalar of type
6439 @item @emph{Example}:
6442 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
6443 INTEGER :: fd, offset, ierr
6449 OPEN(UNIT=fd, FILE="fseek.test")
6450 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
6451 print *, FTELL(fd), ierr
6453 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
6454 print *, FTELL(fd), ierr
6456 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
6457 print *, FTELL(fd), ierr
6463 @item @emph{See also}:
6470 @section @code{FSTAT} --- Get file status
6472 @cindex file system, file status
6475 @item @emph{Description}:
6476 @code{FSTAT} is identical to @ref{STAT}, except that information about an
6477 already opened file is obtained.
6479 The elements in @code{VALUES} are the same as described by @ref{STAT}.
6481 This intrinsic is provided in both subroutine and function forms; however,
6482 only one form can be used in any given program unit.
6484 @item @emph{Standard}:
6488 Subroutine, function
6490 @item @emph{Syntax}:
6491 @multitable @columnfractions .80
6492 @item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
6493 @item @code{STATUS = FSTAT(UNIT, VALUES)}
6496 @item @emph{Arguments}:
6497 @multitable @columnfractions .15 .70
6498 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
6499 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
6500 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
6501 on success and a system specific error code otherwise.
6504 @item @emph{Example}:
6505 See @ref{STAT} for an example.
6507 @item @emph{See also}:
6508 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
6514 @section @code{FTELL} --- Current stream position
6516 @cindex file operation, position
6519 @item @emph{Description}:
6520 Retrieves the current position within an open file.
6522 This intrinsic is provided in both subroutine and function forms; however,
6523 only one form can be used in any given program unit.
6525 @item @emph{Standard}:
6529 Subroutine, function
6531 @item @emph{Syntax}:
6532 @multitable @columnfractions .80
6533 @item @code{CALL FTELL(UNIT, OFFSET)}
6534 @item @code{OFFSET = FTELL(UNIT)}
6537 @item @emph{Arguments}:
6538 @multitable @columnfractions .15 .70
6539 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
6540 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
6543 @item @emph{Return value}:
6544 In either syntax, @var{OFFSET} is set to the current offset of unit
6545 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
6547 @item @emph{Example}:
6551 OPEN(10, FILE="temp.dat")
6557 @item @emph{See also}:
6564 @section @code{GAMMA} --- Gamma function
6567 @cindex Gamma function
6568 @cindex Factorial function
6571 @item @emph{Description}:
6572 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
6573 integer values of @var{X} the Gamma function simplifies to the factorial
6574 function @math{\Gamma(x)=(x-1)!}.
6578 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
6582 @item @emph{Standard}:
6583 Fortran 2008 and later
6588 @item @emph{Syntax}:
6591 @item @emph{Arguments}:
6592 @multitable @columnfractions .15 .70
6593 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
6594 nor a negative integer.
6597 @item @emph{Return value}:
6598 The return value is of type @code{REAL} of the same kind as @var{X}.
6600 @item @emph{Example}:
6604 x = gamma(x) ! returns 1.0
6605 end program test_gamma
6608 @item @emph{Specific names}:
6609 @multitable @columnfractions .20 .20 .20 .25
6610 @item Name @tab Argument @tab Return type @tab Standard
6611 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
6612 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
6615 @item @emph{See also}:
6616 Logarithm of the Gamma function: @ref{LOG_GAMMA}
6623 @section @code{GERROR} --- Get last system error message
6625 @cindex system, error handling
6628 @item @emph{Description}:
6629 Returns the system error message corresponding to the last system error.
6630 This resembles the functionality of @code{strerror(3)} in C.
6632 @item @emph{Standard}:
6638 @item @emph{Syntax}:
6639 @code{CALL GERROR(RESULT)}
6641 @item @emph{Arguments}:
6642 @multitable @columnfractions .15 .70
6643 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
6646 @item @emph{Example}:
6649 CHARACTER(len=100) :: msg
6655 @item @emph{See also}:
6656 @ref{IERRNO}, @ref{PERROR}
6662 @section @code{GETARG} --- Get command line arguments
6664 @cindex command-line arguments
6665 @cindex arguments, to program
6668 @item @emph{Description}:
6669 Retrieve the @var{POS}-th argument that was passed on the
6670 command line when the containing program was invoked.
6672 This intrinsic routine is provided for backwards compatibility with
6673 GNU Fortran 77. In new code, programmers should consider the use of
6674 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
6677 @item @emph{Standard}:
6683 @item @emph{Syntax}:
6684 @code{CALL GETARG(POS, VALUE)}
6686 @item @emph{Arguments}:
6687 @multitable @columnfractions .15 .70
6688 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
6689 the default integer kind; @math{@var{POS} \geq 0}
6690 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
6692 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
6695 @item @emph{Return value}:
6696 After @code{GETARG} returns, the @var{VALUE} argument holds the
6697 @var{POS}th command line argument. If @var{VALUE} can not hold the
6698 argument, it is truncated to fit the length of @var{VALUE}. If there are
6699 less than @var{POS} arguments specified at the command line, @var{VALUE}
6700 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
6701 to the name of the program (on systems that support this feature).
6703 @item @emph{Example}:
6707 CHARACTER(len=32) :: arg
6716 @item @emph{See also}:
6717 GNU Fortran 77 compatibility function: @ref{IARGC}
6719 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
6720 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6726 @section @code{GET_COMMAND} --- Get the entire command line
6727 @fnindex GET_COMMAND
6728 @cindex command-line arguments
6729 @cindex arguments, to program
6732 @item @emph{Description}:
6733 Retrieve the entire command line that was used to invoke the program.
6735 @item @emph{Standard}:
6736 Fortran 2003 and later
6741 @item @emph{Syntax}:
6742 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
6744 @item @emph{Arguments}:
6745 @multitable @columnfractions .15 .70
6746 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
6748 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
6750 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
6754 @item @emph{Return value}:
6755 If @var{COMMAND} is present, stores the entire command line that was used
6756 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
6757 assigned the length of the command line. If @var{STATUS} is present, it
6758 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
6759 short to store the command line, or a positive value in case of an error.
6761 @item @emph{Example}:
6763 PROGRAM test_get_command
6764 CHARACTER(len=255) :: cmd
6765 CALL get_command(cmd)
6766 WRITE (*,*) TRIM(cmd)
6770 @item @emph{See also}:
6771 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6776 @node GET_COMMAND_ARGUMENT
6777 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
6778 @fnindex GET_COMMAND_ARGUMENT
6779 @cindex command-line arguments
6780 @cindex arguments, to program
6783 @item @emph{Description}:
6784 Retrieve the @var{NUMBER}-th argument that was passed on the
6785 command line when the containing program was invoked.
6787 @item @emph{Standard}:
6788 Fortran 2003 and later
6793 @item @emph{Syntax}:
6794 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
6796 @item @emph{Arguments}:
6797 @multitable @columnfractions .15 .70
6798 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
6799 default kind, @math{@var{NUMBER} \geq 0}
6800 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
6801 and of default kind.
6802 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6803 and of default kind.
6804 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6805 and of default kind.
6808 @item @emph{Return value}:
6809 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
6810 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
6811 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
6812 arguments specified at the command line, @var{VALUE} will be filled with blanks.
6813 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
6814 systems that support this feature). The @var{LENGTH} argument contains the
6815 length of the @var{NUMBER}-th command line argument. If the argument retrieval
6816 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
6817 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
6820 @item @emph{Example}:
6822 PROGRAM test_get_command_argument
6824 CHARACTER(len=32) :: arg
6828 CALL get_command_argument(i, arg)
6829 IF (LEN_TRIM(arg) == 0) EXIT
6831 WRITE (*,*) TRIM(arg)
6837 @item @emph{See also}:
6838 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
6844 @section @code{GETCWD} --- Get current working directory
6846 @cindex system, working directory
6849 @item @emph{Description}:
6850 Get current working directory.
6852 This intrinsic is provided in both subroutine and function forms; however,
6853 only one form can be used in any given program unit.
6855 @item @emph{Standard}:
6859 Subroutine, function
6861 @item @emph{Syntax}:
6862 @multitable @columnfractions .80
6863 @item @code{CALL GETCWD(C [, STATUS])}
6864 @item @code{STATUS = GETCWD(C)}
6867 @item @emph{Arguments}:
6868 @multitable @columnfractions .15 .70
6869 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
6870 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
6871 a system specific and nonzero error code otherwise.
6874 @item @emph{Example}:
6877 CHARACTER(len=255) :: cwd
6879 WRITE(*,*) TRIM(cwd)
6883 @item @emph{See also}:
6890 @section @code{GETENV} --- Get an environmental variable
6892 @cindex environment variable
6895 @item @emph{Description}:
6896 Get the @var{VALUE} of the environmental variable @var{NAME}.
6898 This intrinsic routine is provided for backwards compatibility with
6899 GNU Fortran 77. In new code, programmers should consider the use of
6900 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
6903 Note that @code{GETENV} need not be thread-safe. It is the
6904 responsibility of the user to ensure that the environment is not being
6905 updated concurrently with a call to the @code{GETENV} intrinsic.
6907 @item @emph{Standard}:
6913 @item @emph{Syntax}:
6914 @code{CALL GETENV(NAME, VALUE)}
6916 @item @emph{Arguments}:
6917 @multitable @columnfractions .15 .70
6918 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
6919 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
6922 @item @emph{Return value}:
6923 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
6924 not large enough to hold the data, it is truncated. If @var{NAME}
6925 is not set, @var{VALUE} will be filled with blanks.
6927 @item @emph{Example}:
6930 CHARACTER(len=255) :: homedir
6931 CALL getenv("HOME", homedir)
6932 WRITE (*,*) TRIM(homedir)
6936 @item @emph{See also}:
6937 @ref{GET_ENVIRONMENT_VARIABLE}
6942 @node GET_ENVIRONMENT_VARIABLE
6943 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
6944 @fnindex GET_ENVIRONMENT_VARIABLE
6945 @cindex environment variable
6948 @item @emph{Description}:
6949 Get the @var{VALUE} of the environmental variable @var{NAME}.
6951 Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It
6952 is the responsibility of the user to ensure that the environment is
6953 not being updated concurrently with a call to the
6954 @code{GET_ENVIRONMENT_VARIABLE} intrinsic.
6956 @item @emph{Standard}:
6957 Fortran 2003 and later
6962 @item @emph{Syntax}:
6963 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
6965 @item @emph{Arguments}:
6966 @multitable @columnfractions .15 .70
6967 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
6968 and of default kind.
6969 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
6970 and of default kind.
6971 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6972 and of default kind.
6973 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6974 and of default kind.
6975 @item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL}
6976 and of default kind.
6979 @item @emph{Return value}:
6980 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
6981 not large enough to hold the data, it is truncated. If @var{NAME}
6982 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
6983 contains the length needed for storing the environment variable @var{NAME}
6984 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
6985 but too short for the environment variable; it is 1 if the environment
6986 variable does not exist and 2 if the processor does not support environment
6987 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
6988 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
6989 are significant; otherwise they are not part of the environment variable
6992 @item @emph{Example}:
6995 CHARACTER(len=255) :: homedir
6996 CALL get_environment_variable("HOME", homedir)
6997 WRITE (*,*) TRIM(homedir)
7005 @section @code{GETGID} --- Group ID function
7007 @cindex system, group ID
7010 @item @emph{Description}:
7011 Returns the numerical group ID of the current process.
7013 @item @emph{Standard}:
7019 @item @emph{Syntax}:
7020 @code{RESULT = GETGID()}
7022 @item @emph{Return value}:
7023 The return value of @code{GETGID} is an @code{INTEGER} of the default
7027 @item @emph{Example}:
7028 See @code{GETPID} for an example.
7030 @item @emph{See also}:
7031 @ref{GETPID}, @ref{GETUID}
7037 @section @code{GETLOG} --- Get login name
7039 @cindex system, login name
7043 @item @emph{Description}:
7044 Gets the username under which the program is running.
7046 @item @emph{Standard}:
7052 @item @emph{Syntax}:
7053 @code{CALL GETLOG(C)}
7055 @item @emph{Arguments}:
7056 @multitable @columnfractions .15 .70
7057 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
7060 @item @emph{Return value}:
7061 Stores the current user name in @var{LOGIN}. (On systems where POSIX
7062 functions @code{geteuid} and @code{getpwuid} are not available, and
7063 the @code{getlogin} function is not implemented either, this will
7064 return a blank string.)
7066 @item @emph{Example}:
7069 CHARACTER(32) :: login
7075 @item @emph{See also}:
7082 @section @code{GETPID} --- Process ID function
7084 @cindex system, process ID
7088 @item @emph{Description}:
7089 Returns the numerical process identifier of the current process.
7091 @item @emph{Standard}:
7097 @item @emph{Syntax}:
7098 @code{RESULT = GETPID()}
7100 @item @emph{Return value}:
7101 The return value of @code{GETPID} is an @code{INTEGER} of the default
7105 @item @emph{Example}:
7108 print *, "The current process ID is ", getpid()
7109 print *, "Your numerical user ID is ", getuid()
7110 print *, "Your numerical group ID is ", getgid()
7114 @item @emph{See also}:
7115 @ref{GETGID}, @ref{GETUID}
7121 @section @code{GETUID} --- User ID function
7123 @cindex system, user ID
7127 @item @emph{Description}:
7128 Returns the numerical user ID of the current process.
7130 @item @emph{Standard}:
7136 @item @emph{Syntax}:
7137 @code{RESULT = GETUID()}
7139 @item @emph{Return value}:
7140 The return value of @code{GETUID} is an @code{INTEGER} of the default
7144 @item @emph{Example}:
7145 See @code{GETPID} for an example.
7147 @item @emph{See also}:
7148 @ref{GETPID}, @ref{GETLOG}
7154 @section @code{GMTIME} --- Convert time to GMT info
7156 @cindex time, conversion to GMT info
7159 @item @emph{Description}:
7160 Given a system time value @var{TIME} (as provided by the @code{TIME8}
7161 intrinsic), fills @var{VALUES} with values extracted from it appropriate
7162 to the UTC time zone (Universal Coordinated Time, also known in some
7163 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
7165 @item @emph{Standard}:
7171 @item @emph{Syntax}:
7172 @code{CALL GMTIME(TIME, VALUES)}
7174 @item @emph{Arguments}:
7175 @multitable @columnfractions .15 .70
7176 @item @var{TIME} @tab An @code{INTEGER} scalar expression
7177 corresponding to a system time, with @code{INTENT(IN)}.
7178 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
7179 with @code{INTENT(OUT)}.
7182 @item @emph{Return value}:
7183 The elements of @var{VALUES} are assigned as follows:
7185 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
7187 @item Minutes after the hour, range 0--59
7188 @item Hours past midnight, range 0--23
7189 @item Day of month, range 0--31
7190 @item Number of months since January, range 0--12
7191 @item Years since 1900
7192 @item Number of days since Sunday, range 0--6
7193 @item Days since January 1
7194 @item Daylight savings indicator: positive if daylight savings is in
7195 effect, zero if not, and negative if the information is not available.
7198 @item @emph{See also}:
7199 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
7206 @section @code{HOSTNM} --- Get system host name
7208 @cindex system, host name
7211 @item @emph{Description}:
7212 Retrieves the host name of the system on which the program is running.
7214 This intrinsic is provided in both subroutine and function forms; however,
7215 only one form can be used in any given program unit.
7217 @item @emph{Standard}:
7221 Subroutine, function
7223 @item @emph{Syntax}:
7224 @multitable @columnfractions .80
7225 @item @code{CALL HOSTNM(C [, STATUS])}
7226 @item @code{STATUS = HOSTNM(NAME)}
7229 @item @emph{Arguments}:
7230 @multitable @columnfractions .15 .70
7231 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
7232 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
7233 Returns 0 on success, or a system specific error code otherwise.
7236 @item @emph{Return value}:
7237 In either syntax, @var{NAME} is set to the current hostname if it can
7238 be obtained, or to a blank string otherwise.
7245 @section @code{HUGE} --- Largest number of a kind
7247 @cindex limits, largest number
7248 @cindex model representation, largest number
7251 @item @emph{Description}:
7252 @code{HUGE(X)} returns the largest number that is not an infinity in
7253 the model of the type of @code{X}.
7255 @item @emph{Standard}:
7256 Fortran 95 and later
7261 @item @emph{Syntax}:
7262 @code{RESULT = HUGE(X)}
7264 @item @emph{Arguments}:
7265 @multitable @columnfractions .15 .70
7266 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
7269 @item @emph{Return value}:
7270 The return value is of the same type and kind as @var{X}
7272 @item @emph{Example}:
7274 program test_huge_tiny
7275 print *, huge(0), huge(0.0), huge(0.0d0)
7276 print *, tiny(0.0), tiny(0.0d0)
7277 end program test_huge_tiny
7284 @section @code{HYPOT} --- Euclidean distance function
7286 @cindex Euclidean distance
7289 @item @emph{Description}:
7290 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
7291 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
7293 @item @emph{Standard}:
7294 Fortran 2008 and later
7299 @item @emph{Syntax}:
7300 @code{RESULT = HYPOT(X, Y)}
7302 @item @emph{Arguments}:
7303 @multitable @columnfractions .15 .70
7304 @item @var{X} @tab The type shall be @code{REAL}.
7305 @item @var{Y} @tab The type and kind type parameter shall be the same as
7309 @item @emph{Return value}:
7310 The return value has the same type and kind type parameter as @var{X}.
7312 @item @emph{Example}:
7315 real(4) :: x = 1.e0_4, y = 0.5e0_4
7317 end program test_hypot
7324 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
7326 @cindex @acronym{ASCII} collating sequence
7327 @cindex collating sequence, @acronym{ASCII}
7328 @cindex conversion, to integer
7331 @item @emph{Description}:
7332 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
7333 in the first character position of @code{C}.
7335 @item @emph{Standard}:
7336 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7341 @item @emph{Syntax}:
7342 @code{RESULT = IACHAR(C [, KIND])}
7344 @item @emph{Arguments}:
7345 @multitable @columnfractions .15 .70
7346 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
7347 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7348 expression indicating the kind parameter of the result.
7351 @item @emph{Return value}:
7352 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7353 @var{KIND} is absent, the return value is of default integer kind.
7355 @item @emph{Example}:
7360 end program test_iachar
7364 See @ref{ICHAR} for a discussion of converting between numerical values
7365 and formatted string representations.
7367 @item @emph{See also}:
7368 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
7375 @section @code{IALL} --- Bitwise AND of array elements
7378 @cindex bits, AND of array elements
7381 @item @emph{Description}:
7382 Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
7383 if the corresponding element in @var{MASK} is @code{TRUE}.
7385 @item @emph{Standard}:
7386 Fortran 2008 and later
7389 Transformational function
7391 @item @emph{Syntax}:
7392 @multitable @columnfractions .80
7393 @item @code{RESULT = IALL(ARRAY[, MASK])}
7394 @item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
7397 @item @emph{Arguments}:
7398 @multitable @columnfractions .15 .70
7399 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7400 @item @var{DIM} @tab (Optional) shall be a scalar of type
7401 @code{INTEGER} with a value in the range from 1 to n, where n
7402 equals the rank of @var{ARRAY}.
7403 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
7404 and either be a scalar or an array of the same shape as @var{ARRAY}.
7407 @item @emph{Return value}:
7408 The result is of the same type as @var{ARRAY}.
7410 If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
7411 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7412 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7413 dimension @var{DIM} dropped is returned.
7415 @item @emph{Example}:
7424 PRINT '(b8.8)', IALL(a)
7428 @item @emph{See also}:
7429 @ref{IANY}, @ref{IPARITY}, @ref{IAND}
7435 @section @code{IAND} --- Bitwise logical and
7441 @cindex bitwise logical and
7442 @cindex logical and, bitwise
7445 @item @emph{Description}:
7446 Bitwise logical @code{AND}.
7448 @item @emph{Standard}:
7449 Fortran 95 and later, has overloads that are GNU extensions
7454 @item @emph{Syntax}:
7455 @code{RESULT = IAND(I, J)}
7457 @item @emph{Arguments}:
7458 @multitable @columnfractions .15 .70
7459 @item @var{I} @tab The type shall be @code{INTEGER}.
7460 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
7461 kind as @var{I}. (As a GNU extension, different kinds are also
7465 @item @emph{Return value}:
7466 The return type is @code{INTEGER}, of the same kind as the
7467 arguments. (If the argument kinds differ, it is of the same kind as
7468 the larger argument.)
7470 @item @emph{Example}:
7474 DATA a / Z'F' /, b / Z'3' /
7475 WRITE (*,*) IAND(a, b)
7479 @item @emph{Specific names}:
7480 @multitable @columnfractions .20 .20 .20 .25
7481 @item Name @tab Argument @tab Return type @tab Standard
7482 @item @code{IAND(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7483 @item @code{BIAND(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7484 @item @code{IIAND(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7485 @item @code{JIAND(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7486 @item @code{KIAND(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7489 @item @emph{See also}:
7490 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
7497 @section @code{IANY} --- Bitwise OR of array elements
7500 @cindex bits, OR of array elements
7503 @item @emph{Description}:
7504 Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
7505 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
7507 @item @emph{Standard}:
7508 Fortran 2008 and later
7511 Transformational function
7513 @item @emph{Syntax}:
7514 @multitable @columnfractions .80
7515 @item @code{RESULT = IANY(ARRAY[, MASK])}
7516 @item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
7519 @item @emph{Arguments}:
7520 @multitable @columnfractions .15 .70
7521 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7522 @item @var{DIM} @tab (Optional) shall be a scalar of type
7523 @code{INTEGER} with a value in the range from 1 to n, where n
7524 equals the rank of @var{ARRAY}.
7525 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
7526 and either be a scalar or an array of the same shape as @var{ARRAY}.
7529 @item @emph{Return value}:
7530 The result is of the same type as @var{ARRAY}.
7532 If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
7533 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7534 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7535 dimension @var{DIM} dropped is returned.
7537 @item @emph{Example}:
7546 PRINT '(b8.8)', IANY(a)
7550 @item @emph{See also}:
7551 @ref{IPARITY}, @ref{IALL}, @ref{IOR}
7557 @section @code{IARGC} --- Get the number of command line arguments
7559 @cindex command-line arguments
7560 @cindex command-line arguments, number of
7561 @cindex arguments, to program
7564 @item @emph{Description}:
7565 @code{IARGC} returns the number of arguments passed on the
7566 command line when the containing program was invoked.
7568 This intrinsic routine is provided for backwards compatibility with
7569 GNU Fortran 77. In new code, programmers should consider the use of
7570 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
7573 @item @emph{Standard}:
7579 @item @emph{Syntax}:
7580 @code{RESULT = IARGC()}
7582 @item @emph{Arguments}:
7585 @item @emph{Return value}:
7586 The number of command line arguments, type @code{INTEGER(4)}.
7588 @item @emph{Example}:
7591 @item @emph{See also}:
7592 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
7594 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
7595 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
7601 @section @code{IBCLR} --- Clear bit
7611 @item @emph{Description}:
7612 @code{IBCLR} returns the value of @var{I} with the bit at position
7613 @var{POS} set to zero.
7615 @item @emph{Standard}:
7616 Fortran 95 and later, has overloads that are GNU extensions
7621 @item @emph{Syntax}:
7622 @code{RESULT = IBCLR(I, POS)}
7624 @item @emph{Arguments}:
7625 @multitable @columnfractions .15 .70
7626 @item @var{I} @tab The type shall be @code{INTEGER}.
7627 @item @var{POS} @tab The type shall be @code{INTEGER}.
7630 @item @emph{Return value}:
7631 The return value is of type @code{INTEGER} and of the same kind as
7634 @item @emph{Specific names}:
7635 @multitable @columnfractions .20 .20 .20 .25
7636 @item Name @tab Argument @tab Return type @tab Standard
7637 @item @code{IBCLR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7638 @item @code{BBCLR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7639 @item @code{IIBCLR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7640 @item @code{JIBCLR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7641 @item @code{KIBCLR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7644 @item @emph{See also}:
7645 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
7652 @section @code{IBITS} --- Bit extraction
7659 @cindex bits, extract
7662 @item @emph{Description}:
7663 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
7664 starting from bit position @var{POS} and extending left for @var{LEN}
7665 bits. The result is right-justified and the remaining bits are
7666 zeroed. The value of @code{POS+LEN} must be less than or equal to the
7667 value @code{BIT_SIZE(I)}.
7669 @item @emph{Standard}:
7670 Fortran 95 and later, has overloads that are GNU extensions
7675 @item @emph{Syntax}:
7676 @code{RESULT = IBITS(I, POS, LEN)}
7678 @item @emph{Arguments}:
7679 @multitable @columnfractions .15 .70
7680 @item @var{I} @tab The type shall be @code{INTEGER}.
7681 @item @var{POS} @tab The type shall be @code{INTEGER}.
7682 @item @var{LEN} @tab The type shall be @code{INTEGER}.
7685 @item @emph{Return value}:
7686 The return value is of type @code{INTEGER} and of the same kind as
7689 @item @emph{Specific names}:
7690 @multitable @columnfractions .20 .20 .20 .25
7691 @item Name @tab Argument @tab Return type @tab Standard
7692 @item @code{IBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7693 @item @code{BBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7694 @item @code{IIBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7695 @item @code{JIBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7696 @item @code{KIBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7699 @item @emph{See also}:
7700 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
7706 @section @code{IBSET} --- Set bit
7715 @item @emph{Description}:
7716 @code{IBSET} returns the value of @var{I} with the bit at position
7717 @var{POS} set to one.
7719 @item @emph{Standard}:
7720 Fortran 95 and later, has overloads that are GNU extensions
7725 @item @emph{Syntax}:
7726 @code{RESULT = IBSET(I, POS)}
7728 @item @emph{Arguments}:
7729 @multitable @columnfractions .15 .70
7730 @item @var{I} @tab The type shall be @code{INTEGER}.
7731 @item @var{POS} @tab The type shall be @code{INTEGER}.
7734 @item @emph{Return value}:
7735 The return value is of type @code{INTEGER} and of the same kind as
7738 @item @emph{Specific names}:
7739 @multitable @columnfractions .20 .20 .20 .25
7740 @item Name @tab Argument @tab Return type @tab Standard
7741 @item @code{IBSET(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7742 @item @code{BBSET(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7743 @item @code{IIBSET(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7744 @item @code{JIBSET(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7745 @item @code{KIBSET(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7748 @item @emph{See also}:
7749 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
7756 @section @code{ICHAR} --- Character-to-integer conversion function
7758 @cindex conversion, to integer
7761 @item @emph{Description}:
7762 @code{ICHAR(C)} returns the code for the character in the first character
7763 position of @code{C} in the system's native character set.
7764 The correspondence between characters and their codes is not necessarily
7765 the same across different GNU Fortran implementations.
7767 @item @emph{Standard}:
7768 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7773 @item @emph{Syntax}:
7774 @code{RESULT = ICHAR(C [, KIND])}
7776 @item @emph{Arguments}:
7777 @multitable @columnfractions .15 .70
7778 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
7779 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7780 expression indicating the kind parameter of the result.
7783 @item @emph{Return value}:
7784 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7785 @var{KIND} is absent, the return value is of default integer kind.
7787 @item @emph{Example}:
7792 end program test_ichar
7795 @item @emph{Specific names}:
7796 @multitable @columnfractions .20 .20 .20 .25
7797 @item Name @tab Argument @tab Return type @tab Standard
7798 @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7802 No intrinsic exists to convert between a numeric value and a formatted
7803 character string representation -- for instance, given the
7804 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
7805 @code{REAL} value with the value 154, or vice versa. Instead, this
7806 functionality is provided by internal-file I/O, as in the following
7811 character(len=10) string, string2
7814 ! Convert a string to a numeric value
7815 read (string,'(I10)') value
7818 ! Convert a value to a formatted string
7819 write (string2,'(I10)') value
7821 end program read_val
7824 @item @emph{See also}:
7825 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
7832 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
7834 @cindex date, current
7835 @cindex current date
7838 @item @emph{Description}:
7839 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
7840 current local time. The day (in the range 1-31), month (in the range 1-12),
7841 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
7842 The year has four significant digits.
7844 @item @emph{Standard}:
7850 @item @emph{Syntax}:
7851 @code{CALL IDATE(VALUES)}
7853 @item @emph{Arguments}:
7854 @multitable @columnfractions .15 .70
7855 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
7856 the kind shall be the default integer kind.
7859 @item @emph{Return value}:
7860 Does not return anything.
7862 @item @emph{Example}:
7865 integer, dimension(3) :: tarray
7870 end program test_idate
7877 @section @code{IEOR} --- Bitwise logical exclusive or
7883 @cindex bitwise logical exclusive or
7884 @cindex logical exclusive or, bitwise
7887 @item @emph{Description}:
7888 @code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
7891 @item @emph{Standard}:
7892 Fortran 95 and later, has overloads that are GNU extensions
7897 @item @emph{Syntax}:
7898 @code{RESULT = IEOR(I, J)}
7900 @item @emph{Arguments}:
7901 @multitable @columnfractions .15 .70
7902 @item @var{I} @tab The type shall be @code{INTEGER}.
7903 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
7904 kind as @var{I}. (As a GNU extension, different kinds are also
7908 @item @emph{Return value}:
7909 The return type is @code{INTEGER}, of the same kind as the
7910 arguments. (If the argument kinds differ, it is of the same kind as
7911 the larger argument.)
7913 @item @emph{Specific names}:
7914 @multitable @columnfractions .20 .20 .20 .25
7915 @item Name @tab Argument @tab Return type @tab Standard
7916 @item @code{IEOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7917 @item @code{BIEOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7918 @item @code{IIEOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7919 @item @code{JIEOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7920 @item @code{KIEOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7923 @item @emph{See also}:
7924 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
7930 @section @code{IERRNO} --- Get the last system error number
7932 @cindex system, error handling
7935 @item @emph{Description}:
7936 Returns the last system error number, as given by the C @code{errno}
7939 @item @emph{Standard}:
7945 @item @emph{Syntax}:
7946 @code{RESULT = IERRNO()}
7948 @item @emph{Arguments}:
7951 @item @emph{Return value}:
7952 The return value is of type @code{INTEGER} and of the default integer
7955 @item @emph{See also}:
7962 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
7963 @fnindex IMAGE_INDEX
7964 @cindex coarray, @code{IMAGE_INDEX}
7965 @cindex images, cosubscript to image index conversion
7968 @item @emph{Description}:
7969 Returns the image index belonging to a cosubscript.
7971 @item @emph{Standard}:
7972 Fortran 2008 and later
7977 @item @emph{Syntax}:
7978 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
7980 @item @emph{Arguments}: None.
7981 @multitable @columnfractions .15 .70
7982 @item @var{COARRAY} @tab Coarray of any type.
7983 @item @var{SUB} @tab default integer rank-1 array of a size equal to
7984 the corank of @var{COARRAY}.
7988 @item @emph{Return value}:
7989 Scalar default integer with the value of the image index which corresponds
7990 to the cosubscripts. For invalid cosubscripts the result is zero.
7992 @item @emph{Example}:
7994 INTEGER :: array[2,-1:4,8,*]
7995 ! Writes 28 (or 0 if there are fewer than 28 images)
7996 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
7999 @item @emph{See also}:
8000 @ref{THIS_IMAGE}, @ref{NUM_IMAGES}
8005 @node INDEX intrinsic
8006 @section @code{INDEX} --- Position of a substring within a string
8008 @cindex substring position
8009 @cindex string, find substring
8012 @item @emph{Description}:
8013 Returns the position of the start of the first occurrence of string
8014 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
8015 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
8016 the @var{BACK} argument is present and true, the return value is the
8017 start of the last occurrence rather than the first.
8019 @item @emph{Standard}:
8020 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
8025 @item @emph{Syntax}:
8026 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
8028 @item @emph{Arguments}:
8029 @multitable @columnfractions .15 .70
8030 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
8032 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
8034 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
8036 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8037 expression indicating the kind parameter of the result.
8040 @item @emph{Return value}:
8041 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8042 @var{KIND} is absent, the return value is of default integer kind.
8044 @item @emph{Specific names}:
8045 @multitable @columnfractions .20 .20 .20 .25
8046 @item Name @tab Argument @tab Return type @tab Standard
8047 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8050 @item @emph{See also}:
8051 @ref{SCAN}, @ref{VERIFY}
8057 @section @code{INT} --- Convert to integer type
8061 @cindex conversion, to integer
8064 @item @emph{Description}:
8065 Convert to integer type
8067 @item @emph{Standard}:
8068 Fortran 77 and later
8073 @item @emph{Syntax}:
8074 @code{RESULT = INT(A [, KIND))}
8076 @item @emph{Arguments}:
8077 @multitable @columnfractions .15 .70
8078 @item @var{A} @tab Shall be of type @code{INTEGER},
8079 @code{REAL}, or @code{COMPLEX}.
8080 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8081 expression indicating the kind parameter of the result.
8084 @item @emph{Return value}:
8085 These functions return a @code{INTEGER} variable or array under
8086 the following rules:
8090 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
8092 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)}
8093 equals @code{0}. If @math{|A| \geq 1}, then @code{INT(A)} is the integer
8094 whose magnitude is the largest integer that does not exceed the magnitude
8095 of @var{A} and whose sign is the same as the sign of @var{A}.
8097 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
8100 @item @emph{Example}:
8104 complex :: z = (-3.7, 1.0)
8106 print *, int(z), int(z,8)
8110 @item @emph{Specific names}:
8111 @multitable @columnfractions .20 .20 .20 .25
8112 @item Name @tab Argument @tab Return type @tab Standard
8113 @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
8114 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
8115 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
8122 @section @code{INT2} --- Convert to 16-bit integer type
8125 @cindex conversion, to integer
8128 @item @emph{Description}:
8129 Convert to a @code{KIND=2} integer type. This is equivalent to the
8130 standard @code{INT} intrinsic with an optional argument of
8131 @code{KIND=2}, and is only included for backwards compatibility.
8133 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
8135 @item @emph{Standard}:
8141 @item @emph{Syntax}:
8142 @code{RESULT = INT2(A)}
8144 @item @emph{Arguments}:
8145 @multitable @columnfractions .15 .70
8146 @item @var{A} @tab Shall be of type @code{INTEGER},
8147 @code{REAL}, or @code{COMPLEX}.
8150 @item @emph{Return value}:
8151 The return value is a @code{INTEGER(2)} variable.
8153 @item @emph{See also}:
8154 @ref{INT}, @ref{INT8}, @ref{LONG}
8160 @section @code{INT8} --- Convert to 64-bit integer type
8162 @cindex conversion, to integer
8165 @item @emph{Description}:
8166 Convert to a @code{KIND=8} integer type. This is equivalent to the
8167 standard @code{INT} intrinsic with an optional argument of
8168 @code{KIND=8}, and is only included for backwards compatibility.
8170 @item @emph{Standard}:
8176 @item @emph{Syntax}:
8177 @code{RESULT = INT8(A)}
8179 @item @emph{Arguments}:
8180 @multitable @columnfractions .15 .70
8181 @item @var{A} @tab Shall be of type @code{INTEGER},
8182 @code{REAL}, or @code{COMPLEX}.
8185 @item @emph{Return value}:
8186 The return value is a @code{INTEGER(8)} variable.
8188 @item @emph{See also}:
8189 @ref{INT}, @ref{INT2}, @ref{LONG}
8195 @section @code{IOR} --- Bitwise logical or
8201 @cindex bitwise logical or
8202 @cindex logical or, bitwise
8205 @item @emph{Description}:
8206 @code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
8209 @item @emph{Standard}:
8210 Fortran 95 and later, has overloads that are GNU extensions
8215 @item @emph{Syntax}:
8216 @code{RESULT = IOR(I, J)}
8218 @item @emph{Arguments}:
8219 @multitable @columnfractions .15 .70
8220 @item @var{I} @tab The type shall be @code{INTEGER}.
8221 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
8222 kind as @var{I}. (As a GNU extension, different kinds are also
8226 @item @emph{Return value}:
8227 The return type is @code{INTEGER}, of the same kind as the
8228 arguments. (If the argument kinds differ, it is of the same kind as
8229 the larger argument.)
8231 @item @emph{Specific names}:
8232 @multitable @columnfractions .20 .20 .20 .25
8233 @item Name @tab Argument @tab Return type @tab Standard
8234 @item @code{IOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
8235 @item @code{BIOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8236 @item @code{IIOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8237 @item @code{JIOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8238 @item @code{KIOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8241 @item @emph{See also}:
8242 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
8248 @section @code{IPARITY} --- Bitwise XOR of array elements
8250 @cindex array, parity
8252 @cindex bits, XOR of array elements
8255 @item @emph{Description}:
8256 Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
8257 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
8259 @item @emph{Standard}:
8260 Fortran 2008 and later
8263 Transformational function
8265 @item @emph{Syntax}:
8266 @multitable @columnfractions .80
8267 @item @code{RESULT = IPARITY(ARRAY[, MASK])}
8268 @item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
8271 @item @emph{Arguments}:
8272 @multitable @columnfractions .15 .70
8273 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
8274 @item @var{DIM} @tab (Optional) shall be a scalar of type
8275 @code{INTEGER} with a value in the range from 1 to n, where n
8276 equals the rank of @var{ARRAY}.
8277 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
8278 and either be a scalar or an array of the same shape as @var{ARRAY}.
8281 @item @emph{Return value}:
8282 The result is of the same type as @var{ARRAY}.
8284 If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
8285 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
8286 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
8287 dimension @var{DIM} dropped is returned.
8289 @item @emph{Example}:
8291 PROGRAM test_iparity
8298 PRINT '(b8.8)', IPARITY(a)
8302 @item @emph{See also}:
8303 @ref{IANY}, @ref{IALL}, @ref{IEOR}, @ref{PARITY}
8309 @section @code{IRAND} --- Integer pseudo-random number
8311 @cindex random number generation
8314 @item @emph{Description}:
8315 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
8316 distribution between 0 and a system-dependent limit (which is in most
8317 cases 2147483647). If @var{FLAG} is 0, the next number
8318 in the current sequence is returned; if @var{FLAG} is 1, the generator
8319 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
8320 it is used as a new seed with @code{SRAND}.
8322 This intrinsic routine is provided for backwards compatibility with
8323 GNU Fortran 77. It implements a simple modulo generator as provided
8324 by @command{g77}. For new code, one should consider the use of
8325 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
8327 @item @emph{Standard}:
8333 @item @emph{Syntax}:
8334 @code{RESULT = IRAND(I)}
8336 @item @emph{Arguments}:
8337 @multitable @columnfractions .15 .70
8338 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
8341 @item @emph{Return value}:
8342 The return value is of @code{INTEGER(kind=4)} type.
8344 @item @emph{Example}:
8347 integer,parameter :: seed = 86456
8350 print *, irand(), irand(), irand(), irand()
8351 print *, irand(seed), irand(), irand(), irand()
8352 end program test_irand
8360 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
8361 @fnindex IS_IOSTAT_END
8362 @cindex @code{IOSTAT}, end of file
8365 @item @emph{Description}:
8366 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
8367 status ``end of file''. The function is equivalent to comparing the variable
8368 with the @code{IOSTAT_END} parameter of the intrinsic module
8369 @code{ISO_FORTRAN_ENV}.
8371 @item @emph{Standard}:
8372 Fortran 2003 and later
8377 @item @emph{Syntax}:
8378 @code{RESULT = IS_IOSTAT_END(I)}
8380 @item @emph{Arguments}:
8381 @multitable @columnfractions .15 .70
8382 @item @var{I} @tab Shall be of the type @code{INTEGER}.
8385 @item @emph{Return value}:
8386 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
8387 @var{I} has the value which indicates an end of file condition for
8388 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
8390 @item @emph{Example}:
8395 OPEN(88, FILE='test.dat')
8396 READ(88, *, IOSTAT=stat) i
8397 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
8405 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
8406 @fnindex IS_IOSTAT_EOR
8407 @cindex @code{IOSTAT}, end of record
8410 @item @emph{Description}:
8411 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
8412 status ``end of record''. The function is equivalent to comparing the
8413 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
8414 @code{ISO_FORTRAN_ENV}.
8416 @item @emph{Standard}:
8417 Fortran 2003 and later
8422 @item @emph{Syntax}:
8423 @code{RESULT = IS_IOSTAT_EOR(I)}
8425 @item @emph{Arguments}:
8426 @multitable @columnfractions .15 .70
8427 @item @var{I} @tab Shall be of the type @code{INTEGER}.
8430 @item @emph{Return value}:
8431 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
8432 @var{I} has the value which indicates an end of file condition for
8433 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
8435 @item @emph{Example}:
8439 INTEGER :: stat, i(50)
8440 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
8441 READ(88, IOSTAT=stat) i
8442 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
8450 @section @code{ISATTY} --- Whether a unit is a terminal device.
8452 @cindex system, terminal
8455 @item @emph{Description}:
8456 Determine whether a unit is connected to a terminal device.
8458 @item @emph{Standard}:
8464 @item @emph{Syntax}:
8465 @code{RESULT = ISATTY(UNIT)}
8467 @item @emph{Arguments}:
8468 @multitable @columnfractions .15 .70
8469 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
8472 @item @emph{Return value}:
8473 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
8474 device, @code{.FALSE.} otherwise.
8476 @item @emph{Example}:
8479 INTEGER(kind=1) :: unit
8481 write(*,*) isatty(unit=unit)
8485 @item @emph{See also}:
8492 @section @code{ISHFT} --- Shift bits
8501 @item @emph{Description}:
8502 @code{ISHFT} returns a value corresponding to @var{I} with all of the
8503 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
8504 zero corresponds to a left shift, a value of zero corresponds to no
8505 shift, and a value less than zero corresponds to a right shift. If the
8506 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
8507 value is undefined. Bits shifted out from the left end or right end are
8508 lost; zeros are shifted in from the opposite end.
8510 @item @emph{Standard}:
8511 Fortran 95 and later, has overloads that are GNU extensions
8516 @item @emph{Syntax}:
8517 @code{RESULT = ISHFT(I, SHIFT)}
8519 @item @emph{Arguments}:
8520 @multitable @columnfractions .15 .70
8521 @item @var{I} @tab The type shall be @code{INTEGER}.
8522 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8525 @item @emph{Return value}:
8526 The return value is of type @code{INTEGER} and of the same kind as
8529 @item @emph{Specific names}:
8530 @multitable @columnfractions .20 .20 .20 .25
8531 @item Name @tab Argument @tab Return type @tab Standard
8532 @item @code{ISHFT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
8533 @item @code{BSHFT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8534 @item @code{IISHFT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8535 @item @code{JISHFT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8536 @item @code{KISHFT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8539 @item @emph{See also}:
8546 @section @code{ISHFTC} --- Shift bits circularly
8552 @cindex bits, shift circular
8555 @item @emph{Description}:
8556 @code{ISHFTC} returns a value corresponding to @var{I} with the
8557 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
8558 is, bits shifted out one end are shifted into the opposite end. A value
8559 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
8560 zero corresponds to no shift, and a value less than zero corresponds to
8561 a right shift. The absolute value of @var{SHIFT} must be less than
8562 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
8563 equivalent to @code{BIT_SIZE(I)}.
8565 @item @emph{Standard}:
8566 Fortran 95 and later, has overloads that are GNU extensions
8571 @item @emph{Syntax}:
8572 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
8574 @item @emph{Arguments}:
8575 @multitable @columnfractions .15 .70
8576 @item @var{I} @tab The type shall be @code{INTEGER}.
8577 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8578 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
8579 the value must be greater than zero and less than or equal to
8583 @item @emph{Return value}:
8584 The return value is of type @code{INTEGER} and of the same kind as
8587 @item @emph{Specific names}:
8588 @multitable @columnfractions .20 .20 .20 .25
8589 @item Name @tab Argument @tab Return type @tab Standard
8590 @item @code{ISHFTC(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
8591 @item @code{BSHFTC(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8592 @item @code{IISHFTC(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8593 @item @code{JISHFTC(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8594 @item @code{KISHFTC(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8597 @item @emph{See also}:
8604 @section @code{ISNAN} --- Test for a NaN
8609 @item @emph{Description}:
8610 @code{ISNAN} tests whether a floating-point value is an IEEE
8612 @item @emph{Standard}:
8618 @item @emph{Syntax}:
8621 @item @emph{Arguments}:
8622 @multitable @columnfractions .15 .70
8623 @item @var{X} @tab Variable of the type @code{REAL}.
8627 @item @emph{Return value}:
8628 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
8629 if @var{X} is a NaN and @code{FALSE} otherwise.
8631 @item @emph{Example}:
8638 if (isnan(x)) stop '"x" is a NaN'
8639 end program test_nan
8646 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
8648 @cindex time, current
8649 @cindex current time
8652 @item @emph{Description}:
8653 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
8654 current local time. The hour (in the range 1-24), minute (in the range 1-60),
8655 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
8658 @item @emph{Standard}:
8664 @item @emph{Syntax}:
8665 @code{CALL ITIME(VALUES)}
8667 @item @emph{Arguments}:
8668 @multitable @columnfractions .15 .70
8669 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
8670 and the kind shall be the default integer kind.
8673 @item @emph{Return value}:
8674 Does not return anything.
8677 @item @emph{Example}:
8680 integer, dimension(3) :: tarray
8685 end program test_itime
8692 @section @code{KILL} --- Send a signal to a process
8696 @item @emph{Description}:
8697 @item @emph{Standard}:
8698 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
8701 This intrinsic is provided in both subroutine and function forms; however,
8702 only one form can be used in any given program unit.
8705 Subroutine, function
8707 @item @emph{Syntax}:
8708 @multitable @columnfractions .80
8709 @item @code{CALL KILL(C, VALUE [, STATUS])}
8710 @item @code{STATUS = KILL(C, VALUE)}
8713 @item @emph{Arguments}:
8714 @multitable @columnfractions .15 .70
8715 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
8717 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
8719 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
8720 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
8724 @item @emph{See also}:
8725 @ref{ABORT}, @ref{EXIT}
8731 @section @code{KIND} --- Kind of an entity
8736 @item @emph{Description}:
8737 @code{KIND(X)} returns the kind value of the entity @var{X}.
8739 @item @emph{Standard}:
8740 Fortran 95 and later
8745 @item @emph{Syntax}:
8748 @item @emph{Arguments}:
8749 @multitable @columnfractions .15 .70
8750 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
8751 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
8754 @item @emph{Return value}:
8755 The return value is a scalar of type @code{INTEGER} and of the default
8758 @item @emph{Example}:
8761 integer,parameter :: kc = kind(' ')
8762 integer,parameter :: kl = kind(.true.)
8764 print *, "The default character kind is ", kc
8765 print *, "The default logical kind is ", kl
8766 end program test_kind
8774 @section @code{LBOUND} --- Lower dimension bounds of an array
8776 @cindex array, lower bound
8779 @item @emph{Description}:
8780 Returns the lower bounds of an array, or a single lower bound
8781 along the @var{DIM} dimension.
8782 @item @emph{Standard}:
8783 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
8788 @item @emph{Syntax}:
8789 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
8791 @item @emph{Arguments}:
8792 @multitable @columnfractions .15 .70
8793 @item @var{ARRAY} @tab Shall be an array, of any type.
8794 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
8795 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8796 expression indicating the kind parameter of the result.
8799 @item @emph{Return value}:
8800 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8801 @var{KIND} is absent, the return value is of default integer kind.
8802 If @var{DIM} is absent, the result is an array of the lower bounds of
8803 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
8804 corresponding to the lower bound of the array along that dimension. If
8805 @var{ARRAY} is an expression rather than a whole array or array
8806 structure component, or if it has a zero extent along the relevant
8807 dimension, the lower bound is taken to be 1.
8809 @item @emph{See also}:
8810 @ref{UBOUND}, @ref{LCOBOUND}
8816 @section @code{LCOBOUND} --- Lower codimension bounds of an array
8818 @cindex coarray, lower bound
8821 @item @emph{Description}:
8822 Returns the lower bounds of a coarray, or a single lower cobound
8823 along the @var{DIM} codimension.
8824 @item @emph{Standard}:
8825 Fortran 2008 and later
8830 @item @emph{Syntax}:
8831 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
8833 @item @emph{Arguments}:
8834 @multitable @columnfractions .15 .70
8835 @item @var{ARRAY} @tab Shall be an coarray, of any type.
8836 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
8837 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8838 expression indicating the kind parameter of the result.
8841 @item @emph{Return value}:
8842 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8843 @var{KIND} is absent, the return value is of default integer kind.
8844 If @var{DIM} is absent, the result is an array of the lower cobounds of
8845 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
8846 corresponding to the lower cobound of the array along that codimension.
8848 @item @emph{See also}:
8849 @ref{UCOBOUND}, @ref{LBOUND}
8855 @section @code{LEADZ} --- Number of leading zero bits of an integer
8860 @item @emph{Description}:
8861 @code{LEADZ} returns the number of leading zero bits of an integer.
8863 @item @emph{Standard}:
8864 Fortran 2008 and later
8869 @item @emph{Syntax}:
8870 @code{RESULT = LEADZ(I)}
8872 @item @emph{Arguments}:
8873 @multitable @columnfractions .15 .70
8874 @item @var{I} @tab Shall be of type @code{INTEGER}.
8877 @item @emph{Return value}:
8878 The type of the return value is the default @code{INTEGER}.
8879 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
8881 @item @emph{Example}:
8884 WRITE (*,*) BIT_SIZE(1) ! prints 32
8885 WRITE (*,*) LEADZ(1) ! prints 31
8889 @item @emph{See also}:
8890 @ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR}
8896 @section @code{LEN} --- Length of a character entity
8898 @cindex string, length
8901 @item @emph{Description}:
8902 Returns the length of a character string. If @var{STRING} is an array,
8903 the length of an element of @var{STRING} is returned. Note that
8904 @var{STRING} need not be defined when this intrinsic is invoked, since
8905 only the length, not the content, of @var{STRING} is needed.
8907 @item @emph{Standard}:
8908 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
8913 @item @emph{Syntax}:
8914 @code{L = LEN(STRING [, KIND])}
8916 @item @emph{Arguments}:
8917 @multitable @columnfractions .15 .70
8918 @item @var{STRING} @tab Shall be a scalar or array of type
8919 @code{CHARACTER}, with @code{INTENT(IN)}
8920 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8921 expression indicating the kind parameter of the result.
8924 @item @emph{Return value}:
8925 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8926 @var{KIND} is absent, the return value is of default integer kind.
8929 @item @emph{Specific names}:
8930 @multitable @columnfractions .20 .20 .20 .25
8931 @item Name @tab Argument @tab Return type @tab Standard
8932 @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
8936 @item @emph{See also}:
8937 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
8943 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
8945 @cindex string, length, without trailing whitespace
8948 @item @emph{Description}:
8949 Returns the length of a character string, ignoring any trailing blanks.
8951 @item @emph{Standard}:
8952 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
8957 @item @emph{Syntax}:
8958 @code{RESULT = LEN_TRIM(STRING [, KIND])}
8960 @item @emph{Arguments}:
8961 @multitable @columnfractions .15 .70
8962 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
8963 with @code{INTENT(IN)}
8964 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8965 expression indicating the kind parameter of the result.
8968 @item @emph{Return value}:
8969 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8970 @var{KIND} is absent, the return value is of default integer kind.
8972 @item @emph{See also}:
8973 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
8979 @section @code{LGE} --- Lexical greater than or equal
8981 @cindex lexical comparison of strings
8982 @cindex string, comparison
8985 @item @emph{Description}:
8986 Determines whether one string is lexically greater than or equal to
8987 another string, where the two strings are interpreted as containing
8988 ASCII character codes. If the String A and String B are not the same
8989 length, the shorter is compared as if spaces were appended to it to form
8990 a value that has the same length as the longer.
8992 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
8993 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
8994 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
8995 that the latter use the processor's character ordering (which is not
8996 ASCII on some targets), whereas the former always use the ASCII
8999 @item @emph{Standard}:
9000 Fortran 77 and later
9005 @item @emph{Syntax}:
9006 @code{RESULT = LGE(STRING_A, STRING_B)}
9008 @item @emph{Arguments}:
9009 @multitable @columnfractions .15 .70
9010 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9011 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9014 @item @emph{Return value}:
9015 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
9016 otherwise, based on the ASCII ordering.
9018 @item @emph{Specific names}:
9019 @multitable @columnfractions .20 .20 .20 .25
9020 @item Name @tab Argument @tab Return type @tab Standard
9021 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9024 @item @emph{See also}:
9025 @ref{LGT}, @ref{LLE}, @ref{LLT}
9031 @section @code{LGT} --- Lexical greater than
9033 @cindex lexical comparison of strings
9034 @cindex string, comparison
9037 @item @emph{Description}:
9038 Determines whether one string is lexically greater than another string,
9039 where the two strings are interpreted as containing ASCII character
9040 codes. If the String A and String B are not the same length, the
9041 shorter is compared as if spaces were appended to it to form a value
9042 that has the same length as the longer.
9044 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9045 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9046 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9047 that the latter use the processor's character ordering (which is not
9048 ASCII on some targets), whereas the former always use the ASCII
9051 @item @emph{Standard}:
9052 Fortran 77 and later
9057 @item @emph{Syntax}:
9058 @code{RESULT = LGT(STRING_A, STRING_B)}
9060 @item @emph{Arguments}:
9061 @multitable @columnfractions .15 .70
9062 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9063 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9066 @item @emph{Return value}:
9067 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
9068 otherwise, based on the ASCII ordering.
9070 @item @emph{Specific names}:
9071 @multitable @columnfractions .20 .20 .20 .25
9072 @item Name @tab Argument @tab Return type @tab Standard
9073 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9076 @item @emph{See also}:
9077 @ref{LGE}, @ref{LLE}, @ref{LLT}
9083 @section @code{LINK} --- Create a hard link
9085 @cindex file system, create link
9086 @cindex file system, hard link
9089 @item @emph{Description}:
9090 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
9091 character (@code{CHAR(0)}) can be used to mark the end of the names in
9092 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
9093 names are ignored. If the @var{STATUS} argument is supplied, it
9094 contains 0 on success or a nonzero error code upon return; see
9097 This intrinsic is provided in both subroutine and function forms;
9098 however, only one form can be used in any given program unit.
9100 @item @emph{Standard}:
9104 Subroutine, function
9106 @item @emph{Syntax}:
9107 @multitable @columnfractions .80
9108 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
9109 @item @code{STATUS = LINK(PATH1, PATH2)}
9112 @item @emph{Arguments}:
9113 @multitable @columnfractions .15 .70
9114 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
9115 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
9116 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9119 @item @emph{See also}:
9120 @ref{SYMLNK}, @ref{UNLINK}
9126 @section @code{LLE} --- Lexical less than or equal
9128 @cindex lexical comparison of strings
9129 @cindex string, comparison
9132 @item @emph{Description}:
9133 Determines whether one string is lexically less than or equal to another
9134 string, where the two strings are interpreted as containing ASCII
9135 character codes. If the String A and String B are not the same length,
9136 the shorter is compared as if spaces were appended to it to form a value
9137 that has the same length as the longer.
9139 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9140 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9141 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9142 that the latter use the processor's character ordering (which is not
9143 ASCII on some targets), whereas the former always use the ASCII
9146 @item @emph{Standard}:
9147 Fortran 77 and later
9152 @item @emph{Syntax}:
9153 @code{RESULT = LLE(STRING_A, STRING_B)}
9155 @item @emph{Arguments}:
9156 @multitable @columnfractions .15 .70
9157 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9158 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9161 @item @emph{Return value}:
9162 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
9163 otherwise, based on the ASCII ordering.
9165 @item @emph{Specific names}:
9166 @multitable @columnfractions .20 .20 .20 .25
9167 @item Name @tab Argument @tab Return type @tab Standard
9168 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9171 @item @emph{See also}:
9172 @ref{LGE}, @ref{LGT}, @ref{LLT}
9178 @section @code{LLT} --- Lexical less than
9180 @cindex lexical comparison of strings
9181 @cindex string, comparison
9184 @item @emph{Description}:
9185 Determines whether one string is lexically less than another string,
9186 where the two strings are interpreted as containing ASCII character
9187 codes. If the String A and String B are not the same length, the
9188 shorter is compared as if spaces were appended to it to form a value
9189 that has the same length as the longer.
9191 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9192 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9193 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9194 that the latter use the processor's character ordering (which is not
9195 ASCII on some targets), whereas the former always use the ASCII
9198 @item @emph{Standard}:
9199 Fortran 77 and later
9204 @item @emph{Syntax}:
9205 @code{RESULT = LLT(STRING_A, STRING_B)}
9207 @item @emph{Arguments}:
9208 @multitable @columnfractions .15 .70
9209 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9210 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9213 @item @emph{Return value}:
9214 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
9215 otherwise, based on the ASCII ordering.
9217 @item @emph{Specific names}:
9218 @multitable @columnfractions .20 .20 .20 .25
9219 @item Name @tab Argument @tab Return type @tab Standard
9220 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9223 @item @emph{See also}:
9224 @ref{LGE}, @ref{LGT}, @ref{LLE}
9230 @section @code{LNBLNK} --- Index of the last non-blank character in a string
9232 @cindex string, find non-blank character
9235 @item @emph{Description}:
9236 Returns the length of a character string, ignoring any trailing blanks.
9237 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
9238 included for backwards compatibility.
9240 @item @emph{Standard}:
9246 @item @emph{Syntax}:
9247 @code{RESULT = LNBLNK(STRING)}
9249 @item @emph{Arguments}:
9250 @multitable @columnfractions .15 .70
9251 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
9252 with @code{INTENT(IN)}
9255 @item @emph{Return value}:
9256 The return value is of @code{INTEGER(kind=4)} type.
9258 @item @emph{See also}:
9259 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
9265 @section @code{LOC} --- Returns the address of a variable
9267 @cindex location of a variable in memory
9270 @item @emph{Description}:
9271 @code{LOC(X)} returns the address of @var{X} as an integer.
9273 @item @emph{Standard}:
9279 @item @emph{Syntax}:
9280 @code{RESULT = LOC(X)}
9282 @item @emph{Arguments}:
9283 @multitable @columnfractions .15 .70
9284 @item @var{X} @tab Variable of any type.
9287 @item @emph{Return value}:
9288 The return value is of type @code{INTEGER}, with a @code{KIND}
9289 corresponding to the size (in bytes) of a memory address on the target
9292 @item @emph{Example}:
9299 end program test_loc
9306 @section @code{LOG} --- Natural logarithm function
9313 @cindex exponential function, inverse
9314 @cindex logarithm function
9315 @cindex natural logarithm function
9318 @item @emph{Description}:
9319 @code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the
9320 logarithm to the base @math{e}.
9322 @item @emph{Standard}:
9323 Fortran 77 and later
9328 @item @emph{Syntax}:
9329 @code{RESULT = LOG(X)}
9331 @item @emph{Arguments}:
9332 @multitable @columnfractions .15 .70
9333 @item @var{X} @tab The type shall be @code{REAL} or
9337 @item @emph{Return value}:
9338 The return value is of type @code{REAL} or @code{COMPLEX}.
9339 The kind type parameter is the same as @var{X}.
9340 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
9341 @math{-\pi < \omega \leq \pi}.
9343 @item @emph{Example}:
9346 real(8) :: x = 2.7182818284590451_8
9347 complex :: z = (1.0, 2.0)
9348 x = log(x) ! will yield (approximately) 1
9350 end program test_log
9353 @item @emph{Specific names}:
9354 @multitable @columnfractions .20 .20 .20 .25
9355 @item Name @tab Argument @tab Return type @tab Standard
9356 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
9357 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
9358 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
9359 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9360 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9367 @section @code{LOG10} --- Base 10 logarithm function
9371 @cindex exponential function, inverse
9372 @cindex logarithm function with base 10
9373 @cindex base 10 logarithm function
9376 @item @emph{Description}:
9377 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
9379 @item @emph{Standard}:
9380 Fortran 77 and later
9385 @item @emph{Syntax}:
9386 @code{RESULT = LOG10(X)}
9388 @item @emph{Arguments}:
9389 @multitable @columnfractions .15 .70
9390 @item @var{X} @tab The type shall be @code{REAL}.
9393 @item @emph{Return value}:
9394 The return value is of type @code{REAL} or @code{COMPLEX}.
9395 The kind type parameter is the same as @var{X}.
9397 @item @emph{Example}:
9400 real(8) :: x = 10.0_8
9402 end program test_log10
9405 @item @emph{Specific names}:
9406 @multitable @columnfractions .20 .20 .20 .25
9407 @item Name @tab Argument @tab Return type @tab Standard
9408 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
9409 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
9416 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
9421 @cindex Gamma function, logarithm of
9424 @item @emph{Description}:
9425 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
9426 of the Gamma (@math{\Gamma}) function.
9428 @item @emph{Standard}:
9429 Fortran 2008 and later
9434 @item @emph{Syntax}:
9435 @code{X = LOG_GAMMA(X)}
9437 @item @emph{Arguments}:
9438 @multitable @columnfractions .15 .70
9439 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
9440 nor a negative integer.
9443 @item @emph{Return value}:
9444 The return value is of type @code{REAL} of the same kind as @var{X}.
9446 @item @emph{Example}:
9448 program test_log_gamma
9450 x = lgamma(x) ! returns 0.0
9451 end program test_log_gamma
9454 @item @emph{Specific names}:
9455 @multitable @columnfractions .20 .20 .20 .25
9456 @item Name @tab Argument @tab Return type @tab Standard
9457 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
9458 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
9459 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
9462 @item @emph{See also}:
9463 Gamma function: @ref{GAMMA}
9470 @section @code{LOGICAL} --- Convert to logical type
9472 @cindex conversion, to logical
9475 @item @emph{Description}:
9476 Converts one kind of @code{LOGICAL} variable to another.
9478 @item @emph{Standard}:
9479 Fortran 95 and later
9484 @item @emph{Syntax}:
9485 @code{RESULT = LOGICAL(L [, KIND])}
9487 @item @emph{Arguments}:
9488 @multitable @columnfractions .15 .70
9489 @item @var{L} @tab The type shall be @code{LOGICAL}.
9490 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9491 expression indicating the kind parameter of the result.
9494 @item @emph{Return value}:
9495 The return value is a @code{LOGICAL} value equal to @var{L}, with a
9496 kind corresponding to @var{KIND}, or of the default logical kind if
9497 @var{KIND} is not given.
9499 @item @emph{See also}:
9500 @ref{INT}, @ref{REAL}, @ref{CMPLX}
9506 @section @code{LONG} --- Convert to integer type
9508 @cindex conversion, to integer
9511 @item @emph{Description}:
9512 Convert to a @code{KIND=4} integer type, which is the same size as a C
9513 @code{long} integer. This is equivalent to the standard @code{INT}
9514 intrinsic with an optional argument of @code{KIND=4}, and is only
9515 included for backwards compatibility.
9517 @item @emph{Standard}:
9523 @item @emph{Syntax}:
9524 @code{RESULT = LONG(A)}
9526 @item @emph{Arguments}:
9527 @multitable @columnfractions .15 .70
9528 @item @var{A} @tab Shall be of type @code{INTEGER},
9529 @code{REAL}, or @code{COMPLEX}.
9532 @item @emph{Return value}:
9533 The return value is a @code{INTEGER(4)} variable.
9535 @item @emph{See also}:
9536 @ref{INT}, @ref{INT2}, @ref{INT8}
9542 @section @code{LSHIFT} --- Left shift bits
9544 @cindex bits, shift left
9547 @item @emph{Description}:
9548 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
9549 bits shifted left by @var{SHIFT} places. If the absolute value of
9550 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
9551 Bits shifted out from the left end are lost; zeros are shifted in from
9554 This function has been superseded by the @code{ISHFT} intrinsic, which
9555 is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
9556 which is standard in Fortran 2008 and later.
9558 @item @emph{Standard}:
9564 @item @emph{Syntax}:
9565 @code{RESULT = LSHIFT(I, SHIFT)}
9567 @item @emph{Arguments}:
9568 @multitable @columnfractions .15 .70
9569 @item @var{I} @tab The type shall be @code{INTEGER}.
9570 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
9573 @item @emph{Return value}:
9574 The return value is of type @code{INTEGER} and of the same kind as
9577 @item @emph{See also}:
9578 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}, @ref{SHIFTA}, @ref{SHIFTL},
9586 @section @code{LSTAT} --- Get file status
9588 @cindex file system, file status
9591 @item @emph{Description}:
9592 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
9593 symbolic link, then the link itself is statted, not the file that it
9596 The elements in @code{VALUES} are the same as described by @ref{STAT}.
9598 This intrinsic is provided in both subroutine and function forms;
9599 however, only one form can be used in any given program unit.
9601 @item @emph{Standard}:
9605 Subroutine, function
9607 @item @emph{Syntax}:
9608 @multitable @columnfractions .80
9609 @item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
9610 @item @code{STATUS = LSTAT(NAME, VALUES)}
9613 @item @emph{Arguments}:
9614 @multitable @columnfractions .15 .70
9615 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
9616 kind, a valid path within the file system.
9617 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
9618 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
9619 Returns 0 on success and a system specific error code otherwise.
9622 @item @emph{Example}:
9623 See @ref{STAT} for an example.
9625 @item @emph{See also}:
9626 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
9632 @section @code{LTIME} --- Convert time to local time info
9634 @cindex time, conversion to local time info
9637 @item @emph{Description}:
9638 Given a system time value @var{TIME} (as provided by the @code{TIME8}
9639 intrinsic), fills @var{VALUES} with values extracted from it appropriate
9640 to the local time zone using @code{localtime(3)}.
9642 @item @emph{Standard}:
9648 @item @emph{Syntax}:
9649 @code{CALL LTIME(TIME, VALUES)}
9651 @item @emph{Arguments}:
9652 @multitable @columnfractions .15 .70
9653 @item @var{TIME} @tab An @code{INTEGER} scalar expression
9654 corresponding to a system time, with @code{INTENT(IN)}.
9655 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
9656 with @code{INTENT(OUT)}.
9659 @item @emph{Return value}:
9660 The elements of @var{VALUES} are assigned as follows:
9662 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
9664 @item Minutes after the hour, range 0--59
9665 @item Hours past midnight, range 0--23
9666 @item Day of month, range 0--31
9667 @item Number of months since January, range 0--12
9668 @item Years since 1900
9669 @item Number of days since Sunday, range 0--6
9670 @item Days since January 1
9671 @item Daylight savings indicator: positive if daylight savings is in
9672 effect, zero if not, and negative if the information is not available.
9675 @item @emph{See also}:
9676 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
9683 @section @code{MALLOC} --- Allocate dynamic memory
9685 @cindex pointer, cray
9688 @item @emph{Description}:
9689 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
9690 returns the address of the allocated memory. The @code{MALLOC} intrinsic
9691 is an extension intended to be used with Cray pointers, and is provided
9692 in GNU Fortran to allow the user to compile legacy code. For new code
9693 using Fortran 95 pointers, the memory allocation intrinsic is
9696 @item @emph{Standard}:
9702 @item @emph{Syntax}:
9703 @code{PTR = MALLOC(SIZE)}
9705 @item @emph{Arguments}:
9706 @multitable @columnfractions .15 .70
9707 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
9710 @item @emph{Return value}:
9711 The return value is of type @code{INTEGER(K)}, with @var{K} such that
9712 variables of type @code{INTEGER(K)} have the same size as
9713 C pointers (@code{sizeof(void *)}).
9715 @item @emph{Example}:
9716 The following example demonstrates the use of @code{MALLOC} and
9717 @code{FREE} with Cray pointers.
9726 ptr_x = malloc(20*8)
9728 x(i) = sqrt(1.0d0 / i)
9736 end program test_malloc
9739 @item @emph{See also}:
9746 @section @code{MASKL} --- Left justified mask
9748 @cindex mask, left justified
9751 @item @emph{Description}:
9752 @code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
9753 remaining bits set to 0.
9755 @item @emph{Standard}:
9756 Fortran 2008 and later
9761 @item @emph{Syntax}:
9762 @code{RESULT = MASKL(I[, KIND])}
9764 @item @emph{Arguments}:
9765 @multitable @columnfractions .15 .70
9766 @item @var{I} @tab Shall be of type @code{INTEGER}.
9767 @item @var{KIND} @tab Shall be a scalar constant expression of type
9771 @item @emph{Return value}:
9772 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
9773 specifies the kind value of the return type; otherwise, it is of the
9774 default integer kind.
9776 @item @emph{See also}:
9783 @section @code{MASKR} --- Right justified mask
9785 @cindex mask, right justified
9788 @item @emph{Description}:
9789 @code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
9790 remaining bits set to 0.
9792 @item @emph{Standard}:
9793 Fortran 2008 and later
9798 @item @emph{Syntax}:
9799 @code{RESULT = MASKR(I[, KIND])}
9801 @item @emph{Arguments}:
9802 @multitable @columnfractions .15 .70
9803 @item @var{I} @tab Shall be of type @code{INTEGER}.
9804 @item @var{KIND} @tab Shall be a scalar constant expression of type
9808 @item @emph{Return value}:
9809 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
9810 specifies the kind value of the return type; otherwise, it is of the
9811 default integer kind.
9813 @item @emph{See also}:
9820 @section @code{MATMUL} --- matrix multiplication
9822 @cindex matrix multiplication
9823 @cindex product, matrix
9826 @item @emph{Description}:
9827 Performs a matrix multiplication on numeric or logical arguments.
9829 @item @emph{Standard}:
9830 Fortran 95 and later
9833 Transformational function
9835 @item @emph{Syntax}:
9836 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
9838 @item @emph{Arguments}:
9839 @multitable @columnfractions .15 .70
9840 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
9841 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
9843 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
9844 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
9845 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
9846 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
9847 equal to the last (or only) dimension of @var{MATRIX_A}.
9850 @item @emph{Return value}:
9851 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
9852 kind of the result follow the usual type and kind promotion rules, as
9853 for the @code{*} or @code{.AND.} operators.
9855 @item @emph{See also}:
9861 @section @code{MAX} --- Maximum value of an argument list
9868 @cindex maximum value
9871 @item @emph{Description}:
9872 Returns the argument with the largest (most positive) value.
9874 @item @emph{Standard}:
9875 Fortran 77 and later
9880 @item @emph{Syntax}:
9881 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
9883 @item @emph{Arguments}:
9884 @multitable @columnfractions .15 .70
9885 @item @var{A1} @tab The type shall be @code{INTEGER} or
9887 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
9888 as @var{A1}. (As a GNU extension, arguments of different kinds are
9892 @item @emph{Return value}:
9893 The return value corresponds to the maximum value among the arguments,
9894 and has the same type and kind as the first argument.
9896 @item @emph{Specific names}:
9897 @multitable @columnfractions .20 .20 .20 .25
9898 @item Name @tab Argument @tab Return type @tab Standard
9899 @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
9900 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
9901 @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
9902 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
9903 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
9906 @item @emph{See also}:
9907 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
9914 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
9915 @fnindex MAXEXPONENT
9916 @cindex model representation, maximum exponent
9919 @item @emph{Description}:
9920 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
9923 @item @emph{Standard}:
9924 Fortran 95 and later
9929 @item @emph{Syntax}:
9930 @code{RESULT = MAXEXPONENT(X)}
9932 @item @emph{Arguments}:
9933 @multitable @columnfractions .15 .70
9934 @item @var{X} @tab Shall be of type @code{REAL}.
9937 @item @emph{Return value}:
9938 The return value is of type @code{INTEGER} and of the default integer
9941 @item @emph{Example}:
9947 print *, minexponent(x), maxexponent(x)
9948 print *, minexponent(y), maxexponent(y)
9949 end program exponents
9956 @section @code{MAXLOC} --- Location of the maximum value within an array
9958 @cindex array, location of maximum element
9961 @item @emph{Description}:
9962 Determines the location of the element in the array with the maximum
9963 value, or, if the @var{DIM} argument is supplied, determines the
9964 locations of the maximum element along each row of the array in the
9965 @var{DIM} direction. If @var{MASK} is present, only the elements for
9966 which @var{MASK} is @code{.TRUE.} are considered. If more than one
9967 element in the array has the maximum value, the location returned is
9968 that of the first such element in array element order. If the array has
9969 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
9970 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
9971 and all of the elements of @var{MASK} along a given row are zero, the
9972 result value for that row is zero.
9974 @item @emph{Standard}:
9975 Fortran 95 and later
9978 Transformational function
9980 @item @emph{Syntax}:
9981 @multitable @columnfractions .80
9982 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
9983 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
9986 @item @emph{Arguments}:
9987 @multitable @columnfractions .15 .70
9988 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
9990 @item @var{DIM} @tab (Optional) Shall be a scalar of type
9991 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
9992 inclusive. It may not be an optional dummy argument.
9993 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
9994 and conformable with @var{ARRAY}.
9997 @item @emph{Return value}:
9998 If @var{DIM} is absent, the result is a rank-one array with a length
9999 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
10000 is an array with a rank one less than the rank of @var{ARRAY}, and a
10001 size corresponding to the size of @var{ARRAY} with the @var{DIM}
10002 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
10003 of one, the result is a scalar. In all cases, the result is of default
10004 @code{INTEGER} type.
10006 @item @emph{See also}:
10007 @ref{MAX}, @ref{MAXVAL}
10014 @section @code{MAXVAL} --- Maximum value of an array
10016 @cindex array, maximum value
10017 @cindex maximum value
10020 @item @emph{Description}:
10021 Determines the maximum value of the elements in an array value, or, if
10022 the @var{DIM} argument is supplied, determines the maximum value along
10023 each row of the array in the @var{DIM} direction. If @var{MASK} is
10024 present, only the elements for which @var{MASK} is @code{.TRUE.} are
10025 considered. If the array has zero size, or all of the elements of
10026 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
10027 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
10030 @item @emph{Standard}:
10031 Fortran 95 and later
10033 @item @emph{Class}:
10034 Transformational function
10036 @item @emph{Syntax}:
10037 @multitable @columnfractions .80
10038 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
10039 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
10042 @item @emph{Arguments}:
10043 @multitable @columnfractions .15 .70
10044 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10046 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10047 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10048 inclusive. It may not be an optional dummy argument.
10049 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
10050 and conformable with @var{ARRAY}.
10053 @item @emph{Return value}:
10054 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
10055 is a scalar. If @var{DIM} is present, the result is an array with a
10056 rank one less than the rank of @var{ARRAY}, and a size corresponding to
10057 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
10058 cases, the result is of the same type and kind as @var{ARRAY}.
10060 @item @emph{See also}:
10061 @ref{MAX}, @ref{MAXLOC}
10067 @section @code{MCLOCK} --- Time function
10069 @cindex time, clock ticks
10070 @cindex clock ticks
10073 @item @emph{Description}:
10074 Returns the number of clock ticks since the start of the process, based
10075 on the function @code{clock(3)} in the C standard library.
10077 This intrinsic is not fully portable, such as to systems with 32-bit
10078 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
10079 the values returned by this intrinsic might be, or become, negative, or
10080 numerically less than previous values, during a single run of the
10083 @item @emph{Standard}:
10086 @item @emph{Class}:
10089 @item @emph{Syntax}:
10090 @code{RESULT = MCLOCK()}
10092 @item @emph{Return value}:
10093 The return value is a scalar of type @code{INTEGER(4)}, equal to the
10094 number of clock ticks since the start of the process, or @code{-1} if
10095 the system does not support @code{clock(3)}.
10097 @item @emph{See also}:
10098 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
10105 @section @code{MCLOCK8} --- Time function (64-bit)
10107 @cindex time, clock ticks
10108 @cindex clock ticks
10111 @item @emph{Description}:
10112 Returns the number of clock ticks since the start of the process, based
10113 on the function @code{clock(3)} in the C standard library.
10115 @emph{Warning:} this intrinsic does not increase the range of the timing
10116 values over that returned by @code{clock(3)}. On a system with a 32-bit
10117 @code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though
10118 it is converted to a 64-bit @code{INTEGER(8)} value. That means
10119 overflows of the 32-bit value can still occur. Therefore, the values
10120 returned by this intrinsic might be or become negative or numerically
10121 less than previous values during a single run of the compiled program.
10123 @item @emph{Standard}:
10126 @item @emph{Class}:
10129 @item @emph{Syntax}:
10130 @code{RESULT = MCLOCK8()}
10132 @item @emph{Return value}:
10133 The return value is a scalar of type @code{INTEGER(8)}, equal to the
10134 number of clock ticks since the start of the process, or @code{-1} if
10135 the system does not support @code{clock(3)}.
10137 @item @emph{See also}:
10138 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
10145 @section @code{MERGE} --- Merge variables
10147 @cindex array, merge arrays
10148 @cindex array, combine arrays
10151 @item @emph{Description}:
10152 Select values from two arrays according to a logical mask. The result
10153 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
10154 @var{FSOURCE} if it is @code{.FALSE.}.
10156 @item @emph{Standard}:
10157 Fortran 95 and later
10159 @item @emph{Class}:
10162 @item @emph{Syntax}:
10163 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
10165 @item @emph{Arguments}:
10166 @multitable @columnfractions .15 .70
10167 @item @var{TSOURCE} @tab May be of any type.
10168 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
10170 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
10173 @item @emph{Return value}:
10174 The result is of the same type and type parameters as @var{TSOURCE}.
10181 @section @code{MERGE_BITS} --- Merge of bits under mask
10182 @fnindex MERGE_BITS
10183 @cindex bits, merge
10186 @item @emph{Description}:
10187 @code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
10188 as determined by the mask. The i-th bit of the result is equal to the
10189 i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
10190 the i-th bit of @var{J} otherwise.
10192 @item @emph{Standard}:
10193 Fortran 2008 and later
10195 @item @emph{Class}:
10198 @item @emph{Syntax}:
10199 @code{RESULT = MERGE_BITS(I, J, MASK)}
10201 @item @emph{Arguments}:
10202 @multitable @columnfractions .15 .70
10203 @item @var{I} @tab Shall be of type @code{INTEGER}.
10204 @item @var{J} @tab Shall be of type @code{INTEGER} and of the same
10206 @item @var{MASK} @tab Shall be of type @code{INTEGER} and of the same
10210 @item @emph{Return value}:
10211 The result is of the same type and kind as @var{I}.
10218 @section @code{MIN} --- Minimum value of an argument list
10225 @cindex minimum value
10228 @item @emph{Description}:
10229 Returns the argument with the smallest (most negative) value.
10231 @item @emph{Standard}:
10232 Fortran 77 and later
10234 @item @emph{Class}:
10237 @item @emph{Syntax}:
10238 @code{RESULT = MIN(A1, A2 [, A3, ...])}
10240 @item @emph{Arguments}:
10241 @multitable @columnfractions .15 .70
10242 @item @var{A1} @tab The type shall be @code{INTEGER} or
10244 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
10245 as @var{A1}. (As a GNU extension, arguments of different kinds are
10249 @item @emph{Return value}:
10250 The return value corresponds to the maximum value among the arguments,
10251 and has the same type and kind as the first argument.
10253 @item @emph{Specific names}:
10254 @multitable @columnfractions .20 .20 .20 .25
10255 @item Name @tab Argument @tab Return type @tab Standard
10256 @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
10257 @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
10258 @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
10259 @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
10260 @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
10263 @item @emph{See also}:
10264 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
10270 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
10271 @fnindex MINEXPONENT
10272 @cindex model representation, minimum exponent
10275 @item @emph{Description}:
10276 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
10279 @item @emph{Standard}:
10280 Fortran 95 and later
10282 @item @emph{Class}:
10285 @item @emph{Syntax}:
10286 @code{RESULT = MINEXPONENT(X)}
10288 @item @emph{Arguments}:
10289 @multitable @columnfractions .15 .70
10290 @item @var{X} @tab Shall be of type @code{REAL}.
10293 @item @emph{Return value}:
10294 The return value is of type @code{INTEGER} and of the default integer
10297 @item @emph{Example}:
10298 See @code{MAXEXPONENT} for an example.
10304 @section @code{MINLOC} --- Location of the minimum value within an array
10306 @cindex array, location of minimum element
10309 @item @emph{Description}:
10310 Determines the location of the element in the array with the minimum
10311 value, or, if the @var{DIM} argument is supplied, determines the
10312 locations of the minimum element along each row of the array in the
10313 @var{DIM} direction. If @var{MASK} is present, only the elements for
10314 which @var{MASK} is @code{.TRUE.} are considered. If more than one
10315 element in the array has the minimum value, the location returned is
10316 that of the first such element in array element order. If the array has
10317 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
10318 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
10319 and all of the elements of @var{MASK} along a given row are zero, the
10320 result value for that row is zero.
10322 @item @emph{Standard}:
10323 Fortran 95 and later
10325 @item @emph{Class}:
10326 Transformational function
10328 @item @emph{Syntax}:
10329 @multitable @columnfractions .80
10330 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
10331 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
10334 @item @emph{Arguments}:
10335 @multitable @columnfractions .15 .70
10336 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10338 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10339 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10340 inclusive. It may not be an optional dummy argument.
10341 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
10342 and conformable with @var{ARRAY}.
10345 @item @emph{Return value}:
10346 If @var{DIM} is absent, the result is a rank-one array with a length
10347 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
10348 is an array with a rank one less than the rank of @var{ARRAY}, and a
10349 size corresponding to the size of @var{ARRAY} with the @var{DIM}
10350 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
10351 of one, the result is a scalar. In all cases, the result is of default
10352 @code{INTEGER} type.
10354 @item @emph{See also}:
10355 @ref{MIN}, @ref{MINVAL}
10362 @section @code{MINVAL} --- Minimum value of an array
10364 @cindex array, minimum value
10365 @cindex minimum value
10368 @item @emph{Description}:
10369 Determines the minimum value of the elements in an array value, or, if
10370 the @var{DIM} argument is supplied, determines the minimum value along
10371 each row of the array in the @var{DIM} direction. If @var{MASK} is
10372 present, only the elements for which @var{MASK} is @code{.TRUE.} are
10373 considered. If the array has zero size, or all of the elements of
10374 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
10375 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
10376 @var{ARRAY} is of character type.
10378 @item @emph{Standard}:
10379 Fortran 95 and later
10381 @item @emph{Class}:
10382 Transformational function
10384 @item @emph{Syntax}:
10385 @multitable @columnfractions .80
10386 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
10387 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
10390 @item @emph{Arguments}:
10391 @multitable @columnfractions .15 .70
10392 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10394 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10395 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10396 inclusive. It may not be an optional dummy argument.
10397 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
10398 and conformable with @var{ARRAY}.
10401 @item @emph{Return value}:
10402 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
10403 is a scalar. If @var{DIM} is present, the result is an array with a
10404 rank one less than the rank of @var{ARRAY}, and a size corresponding to
10405 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
10406 cases, the result is of the same type and kind as @var{ARRAY}.
10408 @item @emph{See also}:
10409 @ref{MIN}, @ref{MINLOC}
10416 @section @code{MOD} --- Remainder function
10425 @cindex division, remainder
10428 @item @emph{Description}:
10429 @code{MOD(A,P)} computes the remainder of the division of A by P@.
10431 @item @emph{Standard}:
10432 Fortran 77 and later, has overloads that are GNU extensions
10434 @item @emph{Class}:
10437 @item @emph{Syntax}:
10438 @code{RESULT = MOD(A, P)}
10440 @item @emph{Arguments}:
10441 @multitable @columnfractions .15 .70
10442 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
10443 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
10444 and not equal to zero.
10447 @item @emph{Return value}:
10448 The return value is the result of @code{A - (INT(A/P) * P)}. The type
10449 and kind of the return value is the same as that of the arguments. The
10450 returned value has the same sign as A and a magnitude less than the
10453 @item @emph{Example}:
10457 print *, mod(17.5,5.5)
10458 print *, mod(17.5d0,5.5)
10459 print *, mod(17.5,5.5d0)
10461 print *, mod(-17,3)
10462 print *, mod(-17.5,5.5)
10463 print *, mod(-17.5d0,5.5)
10464 print *, mod(-17.5,5.5d0)
10466 print *, mod(17,-3)
10467 print *, mod(17.5,-5.5)
10468 print *, mod(17.5d0,-5.5)
10469 print *, mod(17.5,-5.5d0)
10470 end program test_mod
10473 @item @emph{Specific names}:
10474 @multitable @columnfractions .20 .20 .20 .25
10475 @item Name @tab Arguments @tab Return type @tab Standard
10476 @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
10477 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
10478 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
10479 @item @code{BMOD(A,P)} @tab @code{INTEGER(1) A,P} @tab @code{INTEGER(1)} @tab GNU extension
10480 @item @code{IMOD(A,P)} @tab @code{INTEGER(2) A,P} @tab @code{INTEGER(2)} @tab GNU extension
10481 @item @code{JMOD(A,P)} @tab @code{INTEGER(4) A,P} @tab @code{INTEGER(4)} @tab GNU extension
10482 @item @code{KMOD(A,P)} @tab @code{INTEGER(8) A,P} @tab @code{INTEGER(8)} @tab GNU extension
10485 @item @emph{See also}:
10493 @section @code{MODULO} --- Modulo function
10496 @cindex division, modulo
10499 @item @emph{Description}:
10500 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
10502 @item @emph{Standard}:
10503 Fortran 95 and later
10505 @item @emph{Class}:
10508 @item @emph{Syntax}:
10509 @code{RESULT = MODULO(A, P)}
10511 @item @emph{Arguments}:
10512 @multitable @columnfractions .15 .70
10513 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
10514 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}.
10515 It shall not be zero.
10518 @item @emph{Return value}:
10519 The type and kind of the result are those of the arguments.
10521 @item If @var{A} and @var{P} are of type @code{INTEGER}:
10522 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
10523 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
10525 @item If @var{A} and @var{P} are of type @code{REAL}:
10526 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
10528 The returned value has the same sign as P and a magnitude less than
10529 the magnitude of P.
10531 @item @emph{Example}:
10533 program test_modulo
10534 print *, modulo(17,3)
10535 print *, modulo(17.5,5.5)
10537 print *, modulo(-17,3)
10538 print *, modulo(-17.5,5.5)
10540 print *, modulo(17,-3)
10541 print *, modulo(17.5,-5.5)
10545 @item @emph{See also}:
10553 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
10554 @fnindex MOVE_ALLOC
10555 @cindex moving allocation
10556 @cindex allocation, moving
10559 @item @emph{Description}:
10560 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
10561 @var{TO}. @var{FROM} will become deallocated in the process.
10563 @item @emph{Standard}:
10564 Fortran 2003 and later
10566 @item @emph{Class}:
10569 @item @emph{Syntax}:
10570 @code{CALL MOVE_ALLOC(FROM, TO)}
10572 @item @emph{Arguments}:
10573 @multitable @columnfractions .15 .70
10574 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
10575 of any type and kind.
10576 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
10577 of the same type, kind and rank as @var{FROM}.
10580 @item @emph{Return value}:
10583 @item @emph{Example}:
10585 program test_move_alloc
10586 integer, allocatable :: a(:), b(:)
10590 call move_alloc(a, b)
10591 print *, allocated(a), allocated(b)
10593 end program test_move_alloc
10600 @section @code{MVBITS} --- Move bits from one integer to another
10609 @item @emph{Description}:
10610 Moves @var{LEN} bits from positions @var{FROMPOS} through
10611 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
10612 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
10613 affected by the movement of bits is unchanged. The values of
10614 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
10615 @code{BIT_SIZE(FROM)}.
10617 @item @emph{Standard}:
10618 Fortran 95 and later, has overloads that are GNU extensions
10620 @item @emph{Class}:
10621 Elemental subroutine
10623 @item @emph{Syntax}:
10624 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
10626 @item @emph{Arguments}:
10627 @multitable @columnfractions .15 .70
10628 @item @var{FROM} @tab The type shall be @code{INTEGER}.
10629 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
10630 @item @var{LEN} @tab The type shall be @code{INTEGER}.
10631 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
10632 same kind as @var{FROM}.
10633 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
10636 @item @emph{Specific names}:
10637 @multitable @columnfractions .20 .20 .20 .25
10638 @item Name @tab Argument @tab Return type @tab Standard
10639 @item @code{MVBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
10640 @item @code{BMVBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
10641 @item @code{IMVBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
10642 @item @code{JMVBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
10643 @item @code{KMVBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
10646 @item @emph{See also}:
10647 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
10653 @section @code{NEAREST} --- Nearest representable number
10655 @cindex real number, nearest different
10656 @cindex floating point, nearest different
10659 @item @emph{Description}:
10660 @code{NEAREST(X, S)} returns the processor-representable number nearest
10661 to @code{X} in the direction indicated by the sign of @code{S}.
10663 @item @emph{Standard}:
10664 Fortran 95 and later
10666 @item @emph{Class}:
10669 @item @emph{Syntax}:
10670 @code{RESULT = NEAREST(X, S)}
10672 @item @emph{Arguments}:
10673 @multitable @columnfractions .15 .70
10674 @item @var{X} @tab Shall be of type @code{REAL}.
10675 @item @var{S} @tab Shall be of type @code{REAL} and
10679 @item @emph{Return value}:
10680 The return value is of the same type as @code{X}. If @code{S} is
10681 positive, @code{NEAREST} returns the processor-representable number
10682 greater than @code{X} and nearest to it. If @code{S} is negative,
10683 @code{NEAREST} returns the processor-representable number smaller than
10684 @code{X} and nearest to it.
10686 @item @emph{Example}:
10688 program test_nearest
10690 x = nearest(42.0, 1.0)
10691 y = nearest(42.0, -1.0)
10692 write (*,"(3(G20.15))") x, y, x - y
10693 end program test_nearest
10700 @section @code{NEW_LINE} --- New line character
10703 @cindex output, newline
10706 @item @emph{Description}:
10707 @code{NEW_LINE(C)} returns the new-line character.
10709 @item @emph{Standard}:
10710 Fortran 2003 and later
10712 @item @emph{Class}:
10715 @item @emph{Syntax}:
10716 @code{RESULT = NEW_LINE(C)}
10718 @item @emph{Arguments}:
10719 @multitable @columnfractions .15 .70
10720 @item @var{C} @tab The argument shall be a scalar or array of the
10721 type @code{CHARACTER}.
10724 @item @emph{Return value}:
10725 Returns a @var{CHARACTER} scalar of length one with the new-line character of
10726 the same kind as parameter @var{C}.
10728 @item @emph{Example}:
10732 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
10733 end program newline
10740 @section @code{NINT} --- Nearest whole number
10743 @cindex rounding, nearest whole number
10746 @item @emph{Description}:
10747 @code{NINT(A)} rounds its argument to the nearest whole number.
10749 @item @emph{Standard}:
10750 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
10752 @item @emph{Class}:
10755 @item @emph{Syntax}:
10756 @code{RESULT = NINT(A [, KIND])}
10758 @item @emph{Arguments}:
10759 @multitable @columnfractions .15 .70
10760 @item @var{A} @tab The type of the argument shall be @code{REAL}.
10761 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10762 expression indicating the kind parameter of the result.
10765 @item @emph{Return value}:
10766 Returns @var{A} with the fractional portion of its magnitude eliminated by
10767 rounding to the nearest whole number and with its sign preserved,
10768 converted to an @code{INTEGER} of the default kind.
10770 @item @emph{Example}:
10777 print *, nint(x4), idnint(x8)
10778 end program test_nint
10781 @item @emph{Specific names}:
10782 @multitable @columnfractions .20 .20 .20 .25
10783 @item Name @tab Argument @tab Return Type @tab Standard
10784 @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later
10785 @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later
10788 @item @emph{See also}:
10789 @ref{CEILING}, @ref{FLOOR}
10796 @section @code{NORM2} --- Euclidean vector norms
10798 @cindex Euclidean vector norm
10799 @cindex L2 vector norm
10800 @cindex norm, Euclidean
10803 @item @emph{Description}:
10804 Calculates the Euclidean vector norm (@math{L_2} norm) of
10805 of @var{ARRAY} along dimension @var{DIM}.
10807 @item @emph{Standard}:
10808 Fortran 2008 and later
10810 @item @emph{Class}:
10811 Transformational function
10813 @item @emph{Syntax}:
10814 @multitable @columnfractions .80
10815 @item @code{RESULT = NORM2(ARRAY[, DIM])}
10818 @item @emph{Arguments}:
10819 @multitable @columnfractions .15 .70
10820 @item @var{ARRAY} @tab Shall be an array of type @code{REAL}
10821 @item @var{DIM} @tab (Optional) shall be a scalar of type
10822 @code{INTEGER} with a value in the range from 1 to n, where n
10823 equals the rank of @var{ARRAY}.
10826 @item @emph{Return value}:
10827 The result is of the same type as @var{ARRAY}.
10829 If @var{DIM} is absent, a scalar with the square root of the sum of all
10830 elements in @var{ARRAY} squared is returned. Otherwise, an array of
10831 rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
10832 shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
10835 @item @emph{Example}:
10838 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
10839 print *, NORM2(x) ! = sqrt(55.) ~ 7.416
10847 @section @code{NOT} --- Logical negation
10853 @cindex bits, negate
10854 @cindex bitwise logical not
10855 @cindex logical not, bitwise
10858 @item @emph{Description}:
10859 @code{NOT} returns the bitwise Boolean inverse of @var{I}.
10861 @item @emph{Standard}:
10862 Fortran 95 and later, has overloads that are GNU extensions
10864 @item @emph{Class}:
10867 @item @emph{Syntax}:
10868 @code{RESULT = NOT(I)}
10870 @item @emph{Arguments}:
10871 @multitable @columnfractions .15 .70
10872 @item @var{I} @tab The type shall be @code{INTEGER}.
10875 @item @emph{Return value}:
10876 The return type is @code{INTEGER}, of the same kind as the
10879 @item @emph{Specific names}:
10880 @multitable @columnfractions .20 .20 .20 .25
10881 @item Name @tab Argument @tab Return type @tab Standard
10882 @item @code{NOT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
10883 @item @code{BNOT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
10884 @item @code{INOT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
10885 @item @code{JNOT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
10886 @item @code{KNOT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
10889 @item @emph{See also}:
10890 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
10897 @section @code{NULL} --- Function that returns an disassociated pointer
10899 @cindex pointer, status
10900 @cindex pointer, disassociated
10903 @item @emph{Description}:
10904 Returns a disassociated pointer.
10906 If @var{MOLD} is present, a disassociated pointer of the same type is
10907 returned, otherwise the type is determined by context.
10909 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
10910 includes cases where it is required.
10912 @item @emph{Standard}:
10913 Fortran 95 and later
10915 @item @emph{Class}:
10916 Transformational function
10918 @item @emph{Syntax}:
10919 @code{PTR => NULL([MOLD])}
10921 @item @emph{Arguments}:
10922 @multitable @columnfractions .15 .70
10923 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
10924 status and of any type.
10927 @item @emph{Return value}:
10928 A disassociated pointer.
10930 @item @emph{Example}:
10932 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
10935 @item @emph{See also}:
10942 @section @code{NUM_IMAGES} --- Function that returns the number of images
10943 @fnindex NUM_IMAGES
10944 @cindex coarray, @code{NUM_IMAGES}
10945 @cindex images, number of
10948 @item @emph{Description}:
10949 Returns the number of images.
10951 @item @emph{Standard}:
10952 Fortran 2008 and later. With @var{DISTANCE} or @var{FAILED} argument,
10953 Technical Specification (TS) 18508 or later
10956 @item @emph{Class}:
10957 Transformational function
10959 @item @emph{Syntax}:
10960 @code{RESULT = NUM_IMAGES(DISTANCE, FAILED)}
10962 @item @emph{Arguments}:
10963 @multitable @columnfractions .15 .70
10964 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
10965 @item @var{FAILED} @tab (optional, intent(in)) Scalar logical expression
10968 @item @emph{Return value}:
10969 Scalar default-kind integer. If @var{DISTANCE} is not present or has value 0,
10970 the number of images in the current team is returned. For values smaller or
10971 equal distance to the initial team, it returns the number of images index
10972 on the ancestor team which has a distance of @var{DISTANCE} from the invoking
10973 team. If @var{DISTANCE} is larger than the distance to the initial team, the
10974 number of images of the initial team is returned. If @var{FAILED} is not present
10975 the total number of images is returned; if it has the value @code{.TRUE.},
10976 the number of failed images is returned, otherwise, the number of images which
10977 do have not the failed status.
10979 @item @emph{Example}:
10981 INTEGER :: value[*]
10983 value = THIS_IMAGE()
10985 IF (THIS_IMAGE() == 1) THEN
10986 DO i = 1, NUM_IMAGES()
10987 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
10992 @item @emph{See also}:
10993 @ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
10999 @section @code{OR} --- Bitwise logical OR
11001 @cindex bitwise logical or
11002 @cindex logical or, bitwise
11005 @item @emph{Description}:
11006 Bitwise logical @code{OR}.
11008 This intrinsic routine is provided for backwards compatibility with
11009 GNU Fortran 77. For integer arguments, programmers should consider
11010 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
11012 @item @emph{Standard}:
11015 @item @emph{Class}:
11018 @item @emph{Syntax}:
11019 @code{RESULT = OR(I, J)}
11021 @item @emph{Arguments}:
11022 @multitable @columnfractions .15 .70
11023 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
11024 type or a scalar @code{LOGICAL} type.
11025 @item @var{J} @tab The type shall be the same as the type of @var{J}.
11028 @item @emph{Return value}:
11029 The return type is either a scalar @code{INTEGER} or a scalar
11030 @code{LOGICAL}. If the kind type parameters differ, then the
11031 smaller kind type is implicitly converted to larger kind, and the
11032 return has the larger kind.
11034 @item @emph{Example}:
11037 LOGICAL :: T = .TRUE., F = .FALSE.
11039 DATA a / Z'F' /, b / Z'3' /
11041 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
11042 WRITE (*,*) OR(a, b)
11046 @item @emph{See also}:
11047 Fortran 95 elemental function: @ref{IOR}
11053 @section @code{PACK} --- Pack an array into an array of rank one
11055 @cindex array, packing
11056 @cindex array, reduce dimension
11057 @cindex array, gather elements
11060 @item @emph{Description}:
11061 Stores the elements of @var{ARRAY} in an array of rank one.
11063 The beginning of the resulting array is made up of elements whose @var{MASK}
11064 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
11067 @item @emph{Standard}:
11068 Fortran 95 and later
11070 @item @emph{Class}:
11071 Transformational function
11073 @item @emph{Syntax}:
11074 @code{RESULT = PACK(ARRAY, MASK[,VECTOR])}
11076 @item @emph{Arguments}:
11077 @multitable @columnfractions .15 .70
11078 @item @var{ARRAY} @tab Shall be an array of any type.
11079 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
11080 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
11082 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
11083 as @var{ARRAY} and of rank one. If present, the number of elements in
11084 @var{VECTOR} shall be equal to or greater than the number of true elements
11085 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
11086 @var{VECTOR} shall be equal to or greater than the number of elements in
11090 @item @emph{Return value}:
11091 The result is an array of rank one and the same type as that of @var{ARRAY}.
11092 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
11093 number of @code{TRUE} values in @var{MASK} otherwise.
11095 @item @emph{Example}:
11096 Gathering nonzero elements from an array:
11098 PROGRAM test_pack_1
11100 m = (/ 1, 0, 0, 0, 5, 0 /)
11101 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
11105 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
11107 PROGRAM test_pack_2
11109 m = (/ 1, 0, 0, 2 /)
11110 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
11114 @item @emph{See also}:
11121 @section @code{PARITY} --- Reduction with exclusive OR
11124 @cindex Reduction, XOR
11125 @cindex XOR reduction
11128 @item @emph{Description}:
11129 Calculates the parity, i.e. the reduction using @code{.XOR.},
11130 of @var{MASK} along dimension @var{DIM}.
11132 @item @emph{Standard}:
11133 Fortran 2008 and later
11135 @item @emph{Class}:
11136 Transformational function
11138 @item @emph{Syntax}:
11139 @multitable @columnfractions .80
11140 @item @code{RESULT = PARITY(MASK[, DIM])}
11143 @item @emph{Arguments}:
11144 @multitable @columnfractions .15 .70
11145 @item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL}
11146 @item @var{DIM} @tab (Optional) shall be a scalar of type
11147 @code{INTEGER} with a value in the range from 1 to n, where n
11148 equals the rank of @var{MASK}.
11151 @item @emph{Return value}:
11152 The result is of the same type as @var{MASK}.
11154 If @var{DIM} is absent, a scalar with the parity of all elements in
11155 @var{MASK} is returned, i.e. true if an odd number of elements is
11156 @code{.true.} and false otherwise. If @var{DIM} is present, an array
11157 of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
11158 and a shape similar to that of @var{MASK} with dimension @var{DIM}
11159 dropped is returned.
11161 @item @emph{Example}:
11164 LOGICAL :: x(2) = [ .true., .false. ]
11165 print *, PARITY(x) ! prints "T" (true).
11173 @section @code{PERROR} --- Print system error message
11175 @cindex system, error handling
11178 @item @emph{Description}:
11179 Prints (on the C @code{stderr} stream) a newline-terminated error
11180 message corresponding to the last system error. This is prefixed by
11181 @var{STRING}, a colon and a space. See @code{perror(3)}.
11183 @item @emph{Standard}:
11186 @item @emph{Class}:
11189 @item @emph{Syntax}:
11190 @code{CALL PERROR(STRING)}
11192 @item @emph{Arguments}:
11193 @multitable @columnfractions .15 .70
11194 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
11198 @item @emph{See also}:
11205 @section @code{POPCNT} --- Number of bits set
11207 @cindex binary representation
11211 @item @emph{Description}:
11212 @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
11213 representation of @code{I}.
11215 @item @emph{Standard}:
11216 Fortran 2008 and later
11218 @item @emph{Class}:
11221 @item @emph{Syntax}:
11222 @code{RESULT = POPCNT(I)}
11224 @item @emph{Arguments}:
11225 @multitable @columnfractions .15 .70
11226 @item @var{I} @tab Shall be of type @code{INTEGER}.
11229 @item @emph{Return value}:
11230 The return value is of type @code{INTEGER} and of the default integer
11233 @item @emph{See also}:
11234 @ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ}
11236 @item @emph{Example}:
11238 program test_population
11239 print *, popcnt(127), poppar(127)
11240 print *, popcnt(huge(0_4)), poppar(huge(0_4))
11241 print *, popcnt(huge(0_8)), poppar(huge(0_8))
11242 end program test_population
11248 @section @code{POPPAR} --- Parity of the number of bits set
11250 @cindex binary representation
11254 @item @emph{Description}:
11255 @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
11256 of the number of bits set ('1' bits) in the binary representation of
11257 @code{I}. It is equal to 0 if @code{I} has an even number of bits set,
11258 and 1 for an odd number of '1' bits.
11260 @item @emph{Standard}:
11261 Fortran 2008 and later
11263 @item @emph{Class}:
11266 @item @emph{Syntax}:
11267 @code{RESULT = POPPAR(I)}
11269 @item @emph{Arguments}:
11270 @multitable @columnfractions .15 .70
11271 @item @var{I} @tab Shall be of type @code{INTEGER}.
11274 @item @emph{Return value}:
11275 The return value is of type @code{INTEGER} and of the default integer
11278 @item @emph{See also}:
11279 @ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ}
11281 @item @emph{Example}:
11283 program test_population
11284 print *, popcnt(127), poppar(127)
11285 print *, popcnt(huge(0_4)), poppar(huge(0_4))
11286 print *, popcnt(huge(0_8)), poppar(huge(0_8))
11287 end program test_population
11294 @section @code{PRECISION} --- Decimal precision of a real kind
11296 @cindex model representation, precision
11299 @item @emph{Description}:
11300 @code{PRECISION(X)} returns the decimal precision in the model of the
11303 @item @emph{Standard}:
11304 Fortran 95 and later
11306 @item @emph{Class}:
11309 @item @emph{Syntax}:
11310 @code{RESULT = PRECISION(X)}
11312 @item @emph{Arguments}:
11313 @multitable @columnfractions .15 .70
11314 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
11317 @item @emph{Return value}:
11318 The return value is of type @code{INTEGER} and of the default integer
11321 @item @emph{See also}:
11322 @ref{SELECTED_REAL_KIND}, @ref{RANGE}
11324 @item @emph{Example}:
11326 program prec_and_range
11327 real(kind=4) :: x(2)
11328 complex(kind=8) :: y
11330 print *, precision(x), range(x)
11331 print *, precision(y), range(y)
11332 end program prec_and_range
11339 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
11343 @item @emph{Description}:
11344 Determines whether an optional dummy argument is present.
11346 @item @emph{Standard}:
11347 Fortran 95 and later
11349 @item @emph{Class}:
11352 @item @emph{Syntax}:
11353 @code{RESULT = PRESENT(A)}
11355 @item @emph{Arguments}:
11356 @multitable @columnfractions .15 .70
11357 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
11358 value, or a dummy procedure. It shall be the name of an optional dummy argument
11359 accessible within the current subroutine or function.
11362 @item @emph{Return value}:
11363 Returns either @code{TRUE} if the optional argument @var{A} is present, or
11364 @code{FALSE} otherwise.
11366 @item @emph{Example}:
11368 PROGRAM test_present
11369 WRITE(*,*) f(), f(42) ! "F T"
11371 LOGICAL FUNCTION f(x)
11372 INTEGER, INTENT(IN), OPTIONAL :: x
11382 @section @code{PRODUCT} --- Product of array elements
11384 @cindex array, product
11385 @cindex array, multiply elements
11386 @cindex array, conditionally multiply elements
11387 @cindex multiply array elements
11390 @item @emph{Description}:
11391 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
11392 the corresponding element in @var{MASK} is @code{TRUE}.
11394 @item @emph{Standard}:
11395 Fortran 95 and later
11397 @item @emph{Class}:
11398 Transformational function
11400 @item @emph{Syntax}:
11401 @multitable @columnfractions .80
11402 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
11403 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
11406 @item @emph{Arguments}:
11407 @multitable @columnfractions .15 .70
11408 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
11409 @code{REAL} or @code{COMPLEX}.
11410 @item @var{DIM} @tab (Optional) shall be a scalar of type
11411 @code{INTEGER} with a value in the range from 1 to n, where n
11412 equals the rank of @var{ARRAY}.
11413 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
11414 and either be a scalar or an array of the same shape as @var{ARRAY}.
11417 @item @emph{Return value}:
11418 The result is of the same type as @var{ARRAY}.
11420 If @var{DIM} is absent, a scalar with the product of all elements in
11421 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
11422 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
11423 dimension @var{DIM} dropped is returned.
11426 @item @emph{Example}:
11428 PROGRAM test_product
11429 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
11430 print *, PRODUCT(x) ! all elements, product = 120
11431 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
11435 @item @emph{See also}:
11442 @section @code{RADIX} --- Base of a model number
11444 @cindex model representation, base
11445 @cindex model representation, radix
11448 @item @emph{Description}:
11449 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
11451 @item @emph{Standard}:
11452 Fortran 95 and later
11454 @item @emph{Class}:
11457 @item @emph{Syntax}:
11458 @code{RESULT = RADIX(X)}
11460 @item @emph{Arguments}:
11461 @multitable @columnfractions .15 .70
11462 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
11465 @item @emph{Return value}:
11466 The return value is a scalar of type @code{INTEGER} and of the default
11469 @item @emph{See also}:
11470 @ref{SELECTED_REAL_KIND}
11472 @item @emph{Example}:
11475 print *, "The radix for the default integer kind is", radix(0)
11476 print *, "The radix for the default real kind is", radix(0.0)
11477 end program test_radix
11485 @section @code{RAN} --- Real pseudo-random number
11487 @cindex random number generation
11490 @item @emph{Description}:
11491 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
11492 provided as an alias for @code{RAND}. See @ref{RAND} for complete
11495 @item @emph{Standard}:
11498 @item @emph{Class}:
11501 @item @emph{See also}:
11502 @ref{RAND}, @ref{RANDOM_NUMBER}
11508 @section @code{RAND} --- Real pseudo-random number
11510 @cindex random number generation
11513 @item @emph{Description}:
11514 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
11515 distribution between 0 and 1. If @var{FLAG} is 0, the next number
11516 in the current sequence is returned; if @var{FLAG} is 1, the generator
11517 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
11518 it is used as a new seed with @code{SRAND}.
11520 This intrinsic routine is provided for backwards compatibility with
11521 GNU Fortran 77. It implements a simple modulo generator as provided
11522 by @command{g77}. For new code, one should consider the use of
11523 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
11525 @item @emph{Standard}:
11528 @item @emph{Class}:
11531 @item @emph{Syntax}:
11532 @code{RESULT = RAND(I)}
11534 @item @emph{Arguments}:
11535 @multitable @columnfractions .15 .70
11536 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
11539 @item @emph{Return value}:
11540 The return value is of @code{REAL} type and the default kind.
11542 @item @emph{Example}:
11545 integer,parameter :: seed = 86456
11548 print *, rand(), rand(), rand(), rand()
11549 print *, rand(seed), rand(), rand(), rand()
11550 end program test_rand
11553 @item @emph{See also}:
11554 @ref{SRAND}, @ref{RANDOM_NUMBER}
11560 @node RANDOM_NUMBER
11561 @section @code{RANDOM_NUMBER} --- Pseudo-random number
11562 @fnindex RANDOM_NUMBER
11563 @cindex random number generation
11566 @item @emph{Description}:
11567 Returns a single pseudorandom number or an array of pseudorandom numbers
11568 from the uniform distribution over the range @math{ 0 \leq x < 1}.
11570 The runtime-library implements the xorshift1024* random number
11571 generator (RNG). This generator has a period of @math{2^{1024} - 1},
11572 and when using multiple threads up to @math{2^{512}} threads can each
11573 generate @math{2^{512}} random numbers before any aliasing occurs.
11575 Note that in a multi-threaded program (e.g. using OpenMP directives),
11576 each thread will have its own random number state. For details of the
11577 seeding procedure, see the documentation for the @code{RANDOM_SEED}
11581 @item @emph{Standard}:
11582 Fortran 95 and later
11584 @item @emph{Class}:
11587 @item @emph{Syntax}:
11588 @code{RANDOM_NUMBER(HARVEST)}
11590 @item @emph{Arguments}:
11591 @multitable @columnfractions .15 .70
11592 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
11595 @item @emph{Example}:
11597 program test_random_number
11599 CALL RANDOM_NUMBER(r)
11603 @item @emph{See also}:
11610 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
11611 @fnindex RANDOM_SEED
11612 @cindex random number generation, seeding
11613 @cindex seeding a random number generator
11616 @item @emph{Description}:
11617 Restarts or queries the state of the pseudorandom number generator used by
11618 @code{RANDOM_NUMBER}.
11620 If @code{RANDOM_SEED} is called without arguments, it is seeded with
11621 random data retrieved from the operating system.
11623 As an extension to the Fortran standard, the GFortran
11624 @code{RANDOM_NUMBER} supports multiple threads. Each thread in a
11625 multi-threaded program has its own seed. When @code{RANDOM_SEED} is
11626 called either without arguments or with the @var{PUT} argument, the
11627 given seed is copied into a master seed as well as the seed of the
11628 current thread. When a new thread uses @code{RANDOM_NUMBER} for the
11629 first time, the seed is copied from the master seed, and forwarded
11630 @math{N * 2^{512}} steps to guarantee that the random stream does not
11631 alias any other stream in the system, where @var{N} is the number of
11632 threads that have used @code{RANDOM_NUMBER} so far during the program
11635 @item @emph{Standard}:
11636 Fortran 95 and later
11638 @item @emph{Class}:
11641 @item @emph{Syntax}:
11642 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
11644 @item @emph{Arguments}:
11645 @multitable @columnfractions .15 .70
11646 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
11647 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
11648 of the arrays used with the @var{PUT} and @var{GET} arguments.
11649 @item @var{PUT} @tab (Optional) Shall be an array of type default
11650 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
11651 the array must be larger than or equal to the number returned by the
11652 @var{SIZE} argument.
11653 @item @var{GET} @tab (Optional) Shall be an array of type default
11654 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
11655 of the array must be larger than or equal to the number returned by
11656 the @var{SIZE} argument.
11659 @item @emph{Example}:
11661 program test_random_seed
11663 integer, allocatable :: seed(:)
11666 call random_seed(size = n)
11668 call random_seed(get=seed)
11670 end program test_random_seed
11673 @item @emph{See also}:
11674 @ref{RANDOM_NUMBER}
11680 @section @code{RANGE} --- Decimal exponent range
11682 @cindex model representation, range
11685 @item @emph{Description}:
11686 @code{RANGE(X)} returns the decimal exponent range in the model of the
11689 @item @emph{Standard}:
11690 Fortran 95 and later
11692 @item @emph{Class}:
11695 @item @emph{Syntax}:
11696 @code{RESULT = RANGE(X)}
11698 @item @emph{Arguments}:
11699 @multitable @columnfractions .15 .70
11700 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
11704 @item @emph{Return value}:
11705 The return value is of type @code{INTEGER} and of the default integer
11708 @item @emph{See also}:
11709 @ref{SELECTED_REAL_KIND}, @ref{PRECISION}
11711 @item @emph{Example}:
11712 See @code{PRECISION} for an example.
11718 @section @code{RANK} --- Rank of a data object
11723 @item @emph{Description}:
11724 @code{RANK(A)} returns the rank of a scalar or array data object.
11726 @item @emph{Standard}:
11727 Technical Specification (TS) 29113
11729 @item @emph{Class}:
11732 @item @emph{Syntax}:
11733 @code{RESULT = RANK(A)}
11735 @item @emph{Arguments}:
11736 @multitable @columnfractions .15 .70
11737 @item @var{A} @tab can be of any type
11740 @item @emph{Return value}:
11741 The return value is of type @code{INTEGER} and of the default integer
11742 kind. For arrays, their rank is returned; for scalars zero is returned.
11744 @item @emph{Example}:
11748 real, allocatable :: b(:,:)
11750 print *, rank(a), rank(b) ! Prints: 0 2
11751 end program test_rank
11759 @section @code{REAL} --- Convert to real type
11768 @cindex conversion, to real
11769 @cindex complex numbers, real part
11772 @item @emph{Description}:
11773 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
11774 @code{REALPART} function is provided for compatibility with @command{g77},
11775 and its use is strongly discouraged.
11777 @item @emph{Standard}:
11778 Fortran 77 and later
11780 @item @emph{Class}:
11783 @item @emph{Syntax}:
11784 @multitable @columnfractions .80
11785 @item @code{RESULT = REAL(A [, KIND])}
11786 @item @code{RESULT = REALPART(Z)}
11789 @item @emph{Arguments}:
11790 @multitable @columnfractions .15 .70
11791 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
11793 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11794 expression indicating the kind parameter of the result.
11797 @item @emph{Return value}:
11798 These functions return a @code{REAL} variable or array under
11799 the following rules:
11803 @code{REAL(A)} is converted to a default real type if @var{A} is an
11804 integer or real variable.
11806 @code{REAL(A)} is converted to a real type with the kind type parameter
11807 of @var{A} if @var{A} is a complex variable.
11809 @code{REAL(A, KIND)} is converted to a real type with kind type
11810 parameter @var{KIND} if @var{A} is a complex, integer, or real
11814 @item @emph{Example}:
11817 complex :: x = (1.0, 2.0)
11818 print *, real(x), real(x,8), realpart(x)
11819 end program test_real
11822 @item @emph{Specific names}:
11823 @multitable @columnfractions .20 .20 .20 .25
11824 @item Name @tab Argument @tab Return type @tab Standard
11825 @item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later
11826 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension
11827 @item @code{FLOATI(A)} @tab @code{INTEGER(2)} @tab @code{REAL(4)} @tab GNU extension
11828 @item @code{FLOATJ(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab GNU extension
11829 @item @code{FLOATK(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab GNU extension
11830 @item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab Fortran 77 and later
11834 @item @emph{See also}:
11842 @section @code{RENAME} --- Rename a file
11844 @cindex file system, rename file
11847 @item @emph{Description}:
11848 Renames a file from file @var{PATH1} to @var{PATH2}. A null
11849 character (@code{CHAR(0)}) can be used to mark the end of the names in
11850 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
11851 names are ignored. If the @var{STATUS} argument is supplied, it
11852 contains 0 on success or a nonzero error code upon return; see
11855 This intrinsic is provided in both subroutine and function forms;
11856 however, only one form can be used in any given program unit.
11858 @item @emph{Standard}:
11861 @item @emph{Class}:
11862 Subroutine, function
11864 @item @emph{Syntax}:
11865 @multitable @columnfractions .80
11866 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
11867 @item @code{STATUS = RENAME(PATH1, PATH2)}
11870 @item @emph{Arguments}:
11871 @multitable @columnfractions .15 .70
11872 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
11873 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
11874 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11877 @item @emph{See also}:
11885 @section @code{REPEAT} --- Repeated string concatenation
11887 @cindex string, repeat
11888 @cindex string, concatenate
11891 @item @emph{Description}:
11892 Concatenates @var{NCOPIES} copies of a string.
11894 @item @emph{Standard}:
11895 Fortran 95 and later
11897 @item @emph{Class}:
11898 Transformational function
11900 @item @emph{Syntax}:
11901 @code{RESULT = REPEAT(STRING, NCOPIES)}
11903 @item @emph{Arguments}:
11904 @multitable @columnfractions .15 .70
11905 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
11906 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
11909 @item @emph{Return value}:
11910 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
11913 @item @emph{Example}:
11915 program test_repeat
11916 write(*,*) repeat("x", 5) ! "xxxxx"
11924 @section @code{RESHAPE} --- Function to reshape an array
11926 @cindex array, change dimensions
11927 @cindex array, transmogrify
11930 @item @emph{Description}:
11931 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
11932 the new array may be padded with elements from @var{PAD} or permuted
11933 as defined by @var{ORDER}.
11935 @item @emph{Standard}:
11936 Fortran 95 and later
11938 @item @emph{Class}:
11939 Transformational function
11941 @item @emph{Syntax}:
11942 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
11944 @item @emph{Arguments}:
11945 @multitable @columnfractions .15 .70
11946 @item @var{SOURCE} @tab Shall be an array of any type.
11947 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
11948 array of rank one. Its values must be positive or zero.
11949 @item @var{PAD} @tab (Optional) shall be an array of the same
11950 type as @var{SOURCE}.
11951 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
11952 and an array of the same shape as @var{SHAPE}. Its values shall
11953 be a permutation of the numbers from 1 to n, where n is the size of
11954 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
11958 @item @emph{Return value}:
11959 The result is an array of shape @var{SHAPE} with the same type as
11962 @item @emph{Example}:
11964 PROGRAM test_reshape
11965 INTEGER, DIMENSION(4) :: x
11966 WRITE(*,*) SHAPE(x) ! prints "4"
11967 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
11971 @item @emph{See also}:
11978 @section @code{RRSPACING} --- Reciprocal of the relative spacing
11980 @cindex real number, relative spacing
11981 @cindex floating point, relative spacing
11985 @item @emph{Description}:
11986 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
11987 model numbers near @var{X}.
11989 @item @emph{Standard}:
11990 Fortran 95 and later
11992 @item @emph{Class}:
11995 @item @emph{Syntax}:
11996 @code{RESULT = RRSPACING(X)}
11998 @item @emph{Arguments}:
11999 @multitable @columnfractions .15 .70
12000 @item @var{X} @tab Shall be of type @code{REAL}.
12003 @item @emph{Return value}:
12004 The return value is of the same type and kind as @var{X}.
12005 The value returned is equal to
12006 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
12008 @item @emph{See also}:
12015 @section @code{RSHIFT} --- Right shift bits
12017 @cindex bits, shift right
12020 @item @emph{Description}:
12021 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
12022 bits shifted right by @var{SHIFT} places. If the absolute value of
12023 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12024 Bits shifted out from the right end are lost. The fill is arithmetic: the
12025 bits shifted in from the left end are equal to the leftmost bit, which in
12026 two's complement representation is the sign bit.
12028 This function has been superseded by the @code{SHIFTA} intrinsic, which
12029 is standard in Fortran 2008 and later.
12031 @item @emph{Standard}:
12034 @item @emph{Class}:
12037 @item @emph{Syntax}:
12038 @code{RESULT = RSHIFT(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{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}, @ref{SHIFTA}, @ref{SHIFTR},
12059 @section @code{SAME_TYPE_AS} --- Query dynamic types for equality
12060 @fnindex SAME_TYPE_AS
12063 @item @emph{Description}:
12064 Query dynamic types for equality.
12066 @item @emph{Standard}:
12067 Fortran 2003 and later
12069 @item @emph{Class}:
12072 @item @emph{Syntax}:
12073 @code{RESULT = SAME_TYPE_AS(A, B)}
12075 @item @emph{Arguments}:
12076 @multitable @columnfractions .15 .70
12077 @item @var{A} @tab Shall be an object of extensible declared type or
12078 unlimited polymorphic.
12079 @item @var{B} @tab Shall be an object of extensible declared type or
12080 unlimited polymorphic.
12083 @item @emph{Return value}:
12084 The return value is a scalar of type default logical. It is true if and
12085 only if the dynamic type of A is the same as the dynamic type of B.
12087 @item @emph{See also}:
12088 @ref{EXTENDS_TYPE_OF}
12095 @section @code{SCALE} --- Scale a real value
12097 @cindex real number, scale
12098 @cindex floating point, scale
12101 @item @emph{Description}:
12102 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
12104 @item @emph{Standard}:
12105 Fortran 95 and later
12107 @item @emph{Class}:
12110 @item @emph{Syntax}:
12111 @code{RESULT = SCALE(X, I)}
12113 @item @emph{Arguments}:
12114 @multitable @columnfractions .15 .70
12115 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
12116 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
12119 @item @emph{Return value}:
12120 The return value is of the same type and kind as @var{X}.
12121 Its value is @code{X * RADIX(X)**I}.
12123 @item @emph{Example}:
12126 real :: x = 178.1387e-4
12128 print *, scale(x,i), x*radix(x)**i
12129 end program test_scale
12137 @section @code{SCAN} --- Scan a string for the presence of a set of characters
12139 @cindex string, find subset
12142 @item @emph{Description}:
12143 Scans a @var{STRING} for any of the characters in a @var{SET}
12146 If @var{BACK} is either absent or equals @code{FALSE}, this function
12147 returns the position of the leftmost character of @var{STRING} that is
12148 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
12149 is returned. If no character of @var{SET} is found in @var{STRING}, the
12152 @item @emph{Standard}:
12153 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12155 @item @emph{Class}:
12158 @item @emph{Syntax}:
12159 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
12161 @item @emph{Arguments}:
12162 @multitable @columnfractions .15 .70
12163 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
12164 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
12165 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
12166 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12167 expression indicating the kind parameter of the result.
12170 @item @emph{Return value}:
12171 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12172 @var{KIND} is absent, the return value is of default integer kind.
12174 @item @emph{Example}:
12177 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
12178 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
12179 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
12183 @item @emph{See also}:
12184 @ref{INDEX intrinsic}, @ref{VERIFY}
12190 @section @code{SECNDS} --- Time function
12192 @cindex time, elapsed
12193 @cindex elapsed time
12196 @item @emph{Description}:
12197 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
12198 @var{X} is a reference time, also in seconds. If this is zero, the time in
12199 seconds from midnight is returned. This function is non-standard and its
12200 use is discouraged.
12202 @item @emph{Standard}:
12205 @item @emph{Class}:
12208 @item @emph{Syntax}:
12209 @code{RESULT = SECNDS (X)}
12211 @item @emph{Arguments}:
12212 @multitable @columnfractions .15 .70
12213 @item @var{T} @tab Shall be of type @code{REAL(4)}.
12214 @item @var{X} @tab Shall be of type @code{REAL(4)}.
12217 @item @emph{Return value}:
12220 @item @emph{Example}:
12222 program test_secnds
12225 print *, secnds (0.0) ! seconds since midnight
12226 t1 = secnds (0.0) ! reference time
12227 do i = 1, 10000000 ! do something
12229 t2 = secnds (t1) ! elapsed time
12230 print *, "Something took ", t2, " seconds."
12231 end program test_secnds
12238 @section @code{SECOND} --- CPU time function
12240 @cindex time, elapsed
12241 @cindex elapsed time
12244 @item @emph{Description}:
12245 Returns a @code{REAL(4)} value representing the elapsed CPU time in
12246 seconds. This provides the same functionality as the standard
12247 @code{CPU_TIME} intrinsic, and is only included for backwards
12250 This intrinsic is provided in both subroutine and function forms;
12251 however, only one form can be used in any given program unit.
12253 @item @emph{Standard}:
12256 @item @emph{Class}:
12257 Subroutine, function
12259 @item @emph{Syntax}:
12260 @multitable @columnfractions .80
12261 @item @code{CALL SECOND(TIME)}
12262 @item @code{TIME = SECOND()}
12265 @item @emph{Arguments}:
12266 @multitable @columnfractions .15 .70
12267 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
12270 @item @emph{Return value}:
12271 In either syntax, @var{TIME} is set to the process's current runtime in
12274 @item @emph{See also}:
12281 @node SELECTED_CHAR_KIND
12282 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
12283 @fnindex SELECTED_CHAR_KIND
12284 @cindex character kind
12285 @cindex kind, character
12288 @item @emph{Description}:
12290 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
12291 set named @var{NAME}, if a character set with such a name is supported,
12292 or @math{-1} otherwise. Currently, supported character sets include
12293 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
12294 (Universal Character Set, UCS-4) which is commonly known as Unicode.
12296 @item @emph{Standard}:
12297 Fortran 2003 and later
12299 @item @emph{Class}:
12300 Transformational function
12302 @item @emph{Syntax}:
12303 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
12305 @item @emph{Arguments}:
12306 @multitable @columnfractions .15 .70
12307 @item @var{NAME} @tab Shall be a scalar and of the default character type.
12310 @item @emph{Example}:
12312 program character_kind
12313 use iso_fortran_env
12315 integer, parameter :: ascii = selected_char_kind ("ascii")
12316 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646')
12318 character(kind=ascii, len=26) :: alphabet
12319 character(kind=ucs4, len=30) :: hello_world
12321 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
12322 hello_world = ucs4_'Hello World and Ni Hao -- ' &
12323 // char (int (z'4F60'), ucs4) &
12324 // char (int (z'597D'), ucs4)
12326 write (*,*) alphabet
12328 open (output_unit, encoding='UTF-8')
12329 write (*,*) trim (hello_world)
12330 end program character_kind
12336 @node SELECTED_INT_KIND
12337 @section @code{SELECTED_INT_KIND} --- Choose integer kind
12338 @fnindex SELECTED_INT_KIND
12339 @cindex integer kind
12340 @cindex kind, integer
12343 @item @emph{Description}:
12344 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
12345 type that can represent all values ranging from @math{-10^R} (exclusive)
12346 to @math{10^R} (exclusive). If there is no integer kind that accommodates
12347 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
12349 @item @emph{Standard}:
12350 Fortran 95 and later
12352 @item @emph{Class}:
12353 Transformational function
12355 @item @emph{Syntax}:
12356 @code{RESULT = SELECTED_INT_KIND(R)}
12358 @item @emph{Arguments}:
12359 @multitable @columnfractions .15 .70
12360 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
12363 @item @emph{Example}:
12365 program large_integers
12366 integer,parameter :: k5 = selected_int_kind(5)
12367 integer,parameter :: k15 = selected_int_kind(15)
12368 integer(kind=k5) :: i5
12369 integer(kind=k15) :: i15
12371 print *, huge(i5), huge(i15)
12373 ! The following inequalities are always true
12374 print *, huge(i5) >= 10_k5**5-1
12375 print *, huge(i15) >= 10_k15**15-1
12376 end program large_integers
12382 @node SELECTED_REAL_KIND
12383 @section @code{SELECTED_REAL_KIND} --- Choose real kind
12384 @fnindex SELECTED_REAL_KIND
12387 @cindex radix, real
12390 @item @emph{Description}:
12391 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
12392 with decimal precision of at least @code{P} digits, exponent range of
12393 at least @code{R}, and with a radix of @code{RADIX}.
12395 @item @emph{Standard}:
12396 Fortran 95 and later, with @code{RADIX} Fortran 2008 or later
12398 @item @emph{Class}:
12399 Transformational function
12401 @item @emph{Syntax}:
12402 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
12404 @item @emph{Arguments}:
12405 @multitable @columnfractions .15 .70
12406 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12407 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12408 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12410 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
12411 be present; since Fortran 2008, they are assumed to be zero if absent.
12413 @item @emph{Return value}:
12415 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
12416 a real data type with decimal precision of at least @code{P} digits, a
12417 decimal exponent range of at least @code{R}, and with the requested
12418 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
12419 any radix can be returned. If more than one real data type meet the
12420 criteria, the kind of the data type with the smallest decimal precision
12421 is returned. If no real data type matches the criteria, the result is
12423 @item -1 if the processor does not support a real data type with a
12424 precision greater than or equal to @code{P}, but the @code{R} and
12425 @code{RADIX} requirements can be fulfilled
12426 @item -2 if the processor does not support a real type with an exponent
12427 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
12429 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
12431 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
12433 @item -5 if there is no real type with the given @code{RADIX}
12436 @item @emph{See also}:
12437 @ref{PRECISION}, @ref{RANGE}, @ref{RADIX}
12439 @item @emph{Example}:
12442 integer,parameter :: p6 = selected_real_kind(6)
12443 integer,parameter :: p10r100 = selected_real_kind(10,100)
12444 integer,parameter :: r400 = selected_real_kind(r=400)
12446 real(kind=p10r100) :: y
12447 real(kind=r400) :: z
12449 print *, precision(x), range(x)
12450 print *, precision(y), range(y)
12451 print *, precision(z), range(z)
12452 end program real_kinds
12459 @section @code{SET_EXPONENT} --- Set the exponent of the model
12460 @fnindex SET_EXPONENT
12461 @cindex real number, set exponent
12462 @cindex floating point, set exponent
12465 @item @emph{Description}:
12466 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
12467 is that that of @var{X} and whose exponent part is @var{I}.
12469 @item @emph{Standard}:
12470 Fortran 95 and later
12472 @item @emph{Class}:
12475 @item @emph{Syntax}:
12476 @code{RESULT = SET_EXPONENT(X, I)}
12478 @item @emph{Arguments}:
12479 @multitable @columnfractions .15 .70
12480 @item @var{X} @tab Shall be of type @code{REAL}.
12481 @item @var{I} @tab Shall be of type @code{INTEGER}.
12484 @item @emph{Return value}:
12485 The return value is of the same type and kind as @var{X}.
12486 The real number whose fractional part
12487 is that that of @var{X} and whose exponent part if @var{I} is returned;
12488 it is @code{FRACTION(X) * RADIX(X)**I}.
12490 @item @emph{Example}:
12492 PROGRAM test_setexp
12493 REAL :: x = 178.1387e-4
12495 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
12504 @section @code{SHAPE} --- Determine the shape of an array
12506 @cindex array, shape
12509 @item @emph{Description}:
12510 Determines the shape of an array.
12512 @item @emph{Standard}:
12513 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12515 @item @emph{Class}:
12518 @item @emph{Syntax}:
12519 @code{RESULT = SHAPE(SOURCE [, KIND])}
12521 @item @emph{Arguments}:
12522 @multitable @columnfractions .15 .70
12523 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
12524 If @var{SOURCE} is a pointer it must be associated and allocatable
12525 arrays must be allocated.
12526 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12527 expression indicating the kind parameter of the result.
12530 @item @emph{Return value}:
12531 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
12532 has dimensions. The elements of the resulting array correspond to the extend
12533 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
12534 the result is the rank one array of size zero. If @var{KIND} is absent, the
12535 return value has the default integer kind otherwise the specified kind.
12537 @item @emph{Example}:
12540 INTEGER, DIMENSION(-1:1, -1:2) :: A
12541 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
12542 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
12546 @item @emph{See also}:
12547 @ref{RESHAPE}, @ref{SIZE}
12553 @section @code{SHIFTA} --- Right shift with fill
12555 @cindex bits, shift right
12556 @cindex shift, right with fill
12559 @item @emph{Description}:
12560 @code{SHIFTA} returns a value corresponding to @var{I} with all of the
12561 bits shifted right by @var{SHIFT} places. If the absolute value of
12562 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12563 Bits shifted out from the right end are lost. The fill is arithmetic: the
12564 bits shifted in from the left end are equal to the leftmost bit, which in
12565 two's complement representation is the sign bit.
12567 @item @emph{Standard}:
12568 Fortran 2008 and later
12570 @item @emph{Class}:
12573 @item @emph{Syntax}:
12574 @code{RESULT = SHIFTA(I, SHIFT)}
12576 @item @emph{Arguments}:
12577 @multitable @columnfractions .15 .70
12578 @item @var{I} @tab The type shall be @code{INTEGER}.
12579 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12582 @item @emph{Return value}:
12583 The return value is of type @code{INTEGER} and of the same kind as
12586 @item @emph{See also}:
12587 @ref{SHIFTL}, @ref{SHIFTR}
12593 @section @code{SHIFTL} --- Left shift
12595 @cindex bits, shift left
12596 @cindex shift, left
12599 @item @emph{Description}:
12600 @code{SHIFTL} returns a value corresponding to @var{I} with all of the
12601 bits shifted left by @var{SHIFT} places. If the absolute value of
12602 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12603 Bits shifted out from the left end are lost, and bits shifted in from
12604 the right end are set to 0.
12606 @item @emph{Standard}:
12607 Fortran 2008 and later
12609 @item @emph{Class}:
12612 @item @emph{Syntax}:
12613 @code{RESULT = SHIFTL(I, SHIFT)}
12615 @item @emph{Arguments}:
12616 @multitable @columnfractions .15 .70
12617 @item @var{I} @tab The type shall be @code{INTEGER}.
12618 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12621 @item @emph{Return value}:
12622 The return value is of type @code{INTEGER} and of the same kind as
12625 @item @emph{See also}:
12626 @ref{SHIFTA}, @ref{SHIFTR}
12632 @section @code{SHIFTR} --- Right shift
12634 @cindex bits, shift right
12635 @cindex shift, right
12638 @item @emph{Description}:
12639 @code{SHIFTR} returns a value corresponding to @var{I} with all of the
12640 bits shifted right by @var{SHIFT} places. If the absolute value of
12641 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12642 Bits shifted out from the right end are lost, and bits shifted in from
12643 the left end are set to 0.
12645 @item @emph{Standard}:
12646 Fortran 2008 and later
12648 @item @emph{Class}:
12651 @item @emph{Syntax}:
12652 @code{RESULT = SHIFTR(I, SHIFT)}
12654 @item @emph{Arguments}:
12655 @multitable @columnfractions .15 .70
12656 @item @var{I} @tab The type shall be @code{INTEGER}.
12657 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12660 @item @emph{Return value}:
12661 The return value is of type @code{INTEGER} and of the same kind as
12664 @item @emph{See also}:
12665 @ref{SHIFTA}, @ref{SHIFTL}
12671 @section @code{SIGN} --- Sign copying function
12675 @cindex sign copying
12678 @item @emph{Description}:
12679 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
12681 @item @emph{Standard}:
12682 Fortran 77 and later
12684 @item @emph{Class}:
12687 @item @emph{Syntax}:
12688 @code{RESULT = SIGN(A, B)}
12690 @item @emph{Arguments}:
12691 @multitable @columnfractions .15 .70
12692 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
12693 @item @var{B} @tab Shall be of the same type and kind as @var{A}
12696 @item @emph{Return value}:
12697 The kind of the return value is that of @var{A} and @var{B}.
12698 If @math{B\ge 0} then the result is @code{ABS(A)}, else
12699 it is @code{-ABS(A)}.
12701 @item @emph{Example}:
12704 print *, sign(-12,1)
12705 print *, sign(-12,0)
12706 print *, sign(-12,-1)
12708 print *, sign(-12.,1.)
12709 print *, sign(-12.,0.)
12710 print *, sign(-12.,-1.)
12711 end program test_sign
12714 @item @emph{Specific names}:
12715 @multitable @columnfractions .20 .20 .20 .25
12716 @item Name @tab Arguments @tab Return type @tab Standard
12717 @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu
12718 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
12719 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu
12726 @section @code{SIGNAL} --- Signal handling subroutine (or function)
12728 @cindex system, signal handling
12731 @item @emph{Description}:
12732 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
12733 @var{HANDLER} to be executed with a single integer argument when signal
12734 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
12735 turn off handling of signal @var{NUMBER} or revert to its default
12736 action. See @code{signal(2)}.
12738 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
12739 is supplied, it is set to the value returned by @code{signal(2)}.
12741 @item @emph{Standard}:
12744 @item @emph{Class}:
12745 Subroutine, function
12747 @item @emph{Syntax}:
12748 @multitable @columnfractions .80
12749 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
12750 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
12753 @item @emph{Arguments}:
12754 @multitable @columnfractions .15 .70
12755 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
12756 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
12757 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
12758 @code{INTEGER}. It is @code{INTENT(IN)}.
12759 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
12760 integer. It has @code{INTENT(OUT)}.
12762 @c TODO: What should the interface of the handler be? Does it take arguments?
12764 @item @emph{Return value}:
12765 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
12767 @item @emph{Example}:
12769 program test_signal
12771 external handler_print
12773 call signal (12, handler_print)
12774 call signal (10, 1)
12777 end program test_signal
12784 @section @code{SIN} --- Sine function
12790 @cindex trigonometric function, sine
12794 @item @emph{Description}:
12795 @code{SIN(X)} computes the sine of @var{X}.
12797 @item @emph{Standard}:
12798 Fortran 77 and later
12800 @item @emph{Class}:
12803 @item @emph{Syntax}:
12804 @code{RESULT = SIN(X)}
12806 @item @emph{Arguments}:
12807 @multitable @columnfractions .15 .70
12808 @item @var{X} @tab The type shall be @code{REAL} or
12812 @item @emph{Return value}:
12813 The return value has same type and kind as @var{X}.
12815 @item @emph{Example}:
12820 end program test_sin
12823 @item @emph{Specific names}:
12824 @multitable @columnfractions .20 .20 .20 .25
12825 @item Name @tab Argument @tab Return type @tab Standard
12826 @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu
12827 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
12828 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
12829 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
12830 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
12833 @item @emph{See also}:
12834 Inverse function: @ref{ASIN}
12835 Degrees function: @ref{SIND}
12841 @section @code{SIND} --- Sine function, degrees
12847 @cindex trigonometric function, sine, degrees
12848 @cindex sine, degrees
12851 @item @emph{Description}:
12852 @code{SIND(X)} computes the sine of @var{X} in degrees.
12854 This function is for compatibility only and should be avoided in favor of
12855 standard constructs wherever possible.
12857 @item @emph{Standard}:
12858 GNU Extension, enabled with @option{-fdec-math}.
12860 @item @emph{Class}:
12863 @item @emph{Syntax}:
12864 @code{RESULT = SIND(X)}
12866 @item @emph{Arguments}:
12867 @multitable @columnfractions .15 .70
12868 @item @var{X} @tab The type shall be @code{REAL} or
12872 @item @emph{Return value}:
12873 The return value has same type and kind as @var{X}, and its value is in degrees.
12875 @item @emph{Example}:
12880 end program test_sind
12883 @item @emph{Specific names}:
12884 @multitable @columnfractions .20 .20 .20 .25
12885 @item Name @tab Argument @tab Return type @tab Standard
12886 @item @code{SIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
12887 @item @code{DSIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
12888 @item @code{CSIND(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU Extension
12889 @item @code{ZSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU Extension
12890 @item @code{CDSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU Extension
12893 @item @emph{See also}:
12894 Inverse function: @ref{ASIND}
12895 Radians function: @ref{SIN}
12902 @section @code{SINH} --- Hyperbolic sine function
12905 @cindex hyperbolic sine
12906 @cindex hyperbolic function, sine
12907 @cindex sine, hyperbolic
12910 @item @emph{Description}:
12911 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
12913 @item @emph{Standard}:
12914 Fortran 95 and later, for a complex argument Fortran 2008 or later
12916 @item @emph{Class}:
12919 @item @emph{Syntax}:
12920 @code{RESULT = SINH(X)}
12922 @item @emph{Arguments}:
12923 @multitable @columnfractions .15 .70
12924 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
12927 @item @emph{Return value}:
12928 The return value has same type and kind as @var{X}.
12930 @item @emph{Example}:
12933 real(8) :: x = - 1.0_8
12935 end program test_sinh
12938 @item @emph{Specific names}:
12939 @multitable @columnfractions .20 .20 .20 .25
12940 @item Name @tab Argument @tab Return type @tab Standard
12941 @item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
12942 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
12945 @item @emph{See also}:
12952 @section @code{SIZE} --- Determine the size of an array
12954 @cindex array, size
12955 @cindex array, number of elements
12956 @cindex array, count elements
12959 @item @emph{Description}:
12960 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
12961 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
12963 @item @emph{Standard}:
12964 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12966 @item @emph{Class}:
12969 @item @emph{Syntax}:
12970 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
12972 @item @emph{Arguments}:
12973 @multitable @columnfractions .15 .70
12974 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
12975 a pointer it must be associated and allocatable arrays must be allocated.
12976 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
12977 and its value shall be in the range from 1 to n, where n equals the rank
12979 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12980 expression indicating the kind parameter of the result.
12983 @item @emph{Return value}:
12984 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12985 @var{KIND} is absent, the return value is of default integer kind.
12987 @item @emph{Example}:
12990 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
12994 @item @emph{See also}:
12995 @ref{SHAPE}, @ref{RESHAPE}
13000 @section @code{SIZEOF} --- Size in bytes of an expression
13002 @cindex expression size
13003 @cindex size of an expression
13006 @item @emph{Description}:
13007 @code{SIZEOF(X)} calculates the number of bytes of storage the
13008 expression @code{X} occupies.
13010 @item @emph{Standard}:
13013 @item @emph{Class}:
13016 @item @emph{Syntax}:
13017 @code{N = SIZEOF(X)}
13019 @item @emph{Arguments}:
13020 @multitable @columnfractions .15 .70
13021 @item @var{X} @tab The argument shall be of any type, rank or shape.
13024 @item @emph{Return value}:
13025 The return value is of type integer and of the system-dependent kind
13026 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
13027 number of bytes occupied by the argument. If the argument has the
13028 @code{POINTER} attribute, the number of bytes of the storage area pointed
13029 to is returned. If the argument is of a derived type with @code{POINTER}
13030 or @code{ALLOCATABLE} components, the return value does not account for
13031 the sizes of the data pointed to by these components. If the argument is
13032 polymorphic, the size according to the dynamic type is returned. The argument
13033 may not be a procedure or procedure pointer. Note that the code assumes for
13034 arrays that those are contiguous; for contiguous arrays, it returns the
13035 storage or an array element multiplied by the size of the array.
13037 @item @emph{Example}:
13041 print *, (sizeof(s)/sizeof(r) == 5)
13044 The example will print @code{.TRUE.} unless you are using a platform
13045 where default @code{REAL} variables are unusually padded.
13047 @item @emph{See also}:
13048 @ref{C_SIZEOF}, @ref{STORAGE_SIZE}
13053 @section @code{SLEEP} --- Sleep for the specified number of seconds
13055 @cindex delayed execution
13058 @item @emph{Description}:
13059 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
13061 @item @emph{Standard}:
13064 @item @emph{Class}:
13067 @item @emph{Syntax}:
13068 @code{CALL SLEEP(SECONDS)}
13070 @item @emph{Arguments}:
13071 @multitable @columnfractions .15 .70
13072 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
13075 @item @emph{Example}:
13086 @section @code{SPACING} --- Smallest distance between two numbers of a given type
13088 @cindex real number, relative spacing
13089 @cindex floating point, relative spacing
13092 @item @emph{Description}:
13093 Determines the distance between the argument @var{X} and the nearest
13094 adjacent number of the same type.
13096 @item @emph{Standard}:
13097 Fortran 95 and later
13099 @item @emph{Class}:
13102 @item @emph{Syntax}:
13103 @code{RESULT = SPACING(X)}
13105 @item @emph{Arguments}:
13106 @multitable @columnfractions .15 .70
13107 @item @var{X} @tab Shall be of type @code{REAL}.
13110 @item @emph{Return value}:
13111 The result is of the same type as the input argument @var{X}.
13113 @item @emph{Example}:
13115 PROGRAM test_spacing
13116 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
13117 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
13119 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
13120 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
13124 @item @emph{See also}:
13131 @section @code{SPREAD} --- Add a dimension to an array
13133 @cindex array, increase dimension
13134 @cindex array, duplicate elements
13135 @cindex array, duplicate dimensions
13138 @item @emph{Description}:
13139 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
13140 dimension @var{DIM}.
13142 @item @emph{Standard}:
13143 Fortran 95 and later
13145 @item @emph{Class}:
13146 Transformational function
13148 @item @emph{Syntax}:
13149 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
13151 @item @emph{Arguments}:
13152 @multitable @columnfractions .15 .70
13153 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
13154 a rank less than seven.
13155 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
13156 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
13157 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
13160 @item @emph{Return value}:
13161 The result is an array of the same type as @var{SOURCE} and has rank n+1
13162 where n equals the rank of @var{SOURCE}.
13164 @item @emph{Example}:
13166 PROGRAM test_spread
13167 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
13168 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
13169 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
13173 @item @emph{See also}:
13180 @section @code{SQRT} --- Square-root function
13187 @cindex square-root
13190 @item @emph{Description}:
13191 @code{SQRT(X)} computes the square root of @var{X}.
13193 @item @emph{Standard}:
13194 Fortran 77 and later
13196 @item @emph{Class}:
13199 @item @emph{Syntax}:
13200 @code{RESULT = SQRT(X)}
13202 @item @emph{Arguments}:
13203 @multitable @columnfractions .15 .70
13204 @item @var{X} @tab The type shall be @code{REAL} or
13208 @item @emph{Return value}:
13209 The return value is of type @code{REAL} or @code{COMPLEX}.
13210 The kind type parameter is the same as @var{X}.
13212 @item @emph{Example}:
13215 real(8) :: x = 2.0_8
13216 complex :: z = (1.0, 2.0)
13219 end program test_sqrt
13222 @item @emph{Specific names}:
13223 @multitable @columnfractions .20 .20 .20 .25
13224 @item Name @tab Argument @tab Return type @tab Standard
13225 @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
13226 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
13227 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
13228 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13229 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13236 @section @code{SRAND} --- Reinitialize the random number generator
13238 @cindex random number generation, seeding
13239 @cindex seeding a random number generator
13242 @item @emph{Description}:
13243 @code{SRAND} reinitializes the pseudo-random number generator
13244 called by @code{RAND} and @code{IRAND}. The new seed used by the
13245 generator is specified by the required argument @var{SEED}.
13247 @item @emph{Standard}:
13250 @item @emph{Class}:
13253 @item @emph{Syntax}:
13254 @code{CALL SRAND(SEED)}
13256 @item @emph{Arguments}:
13257 @multitable @columnfractions .15 .70
13258 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
13261 @item @emph{Return value}:
13262 Does not return anything.
13264 @item @emph{Example}:
13265 See @code{RAND} and @code{IRAND} for examples.
13267 @item @emph{Notes}:
13268 The Fortran standard specifies the intrinsic subroutines
13269 @code{RANDOM_SEED} to initialize the pseudo-random number
13270 generator and @code{RANDOM_NUMBER} to generate pseudo-random numbers.
13271 These subroutines should be used in new codes.
13273 Please note that in GNU Fortran, these two sets of intrinsics (@code{RAND},
13274 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
13275 @code{RANDOM_SEED} on the other hand) access two independent
13276 pseudo-random number generators.
13278 @item @emph{See also}:
13279 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
13286 @section @code{STAT} --- Get file status
13288 @cindex file system, file status
13291 @item @emph{Description}:
13292 This function returns information about a file. No permissions are required on
13293 the file itself, but execute (search) permission is required on all of the
13294 directories in path that lead to the file.
13296 The elements that are obtained and stored in the array @code{VALUES}:
13297 @multitable @columnfractions .15 .70
13298 @item @code{VALUES(1)} @tab Device ID
13299 @item @code{VALUES(2)} @tab Inode number
13300 @item @code{VALUES(3)} @tab File mode
13301 @item @code{VALUES(4)} @tab Number of links
13302 @item @code{VALUES(5)} @tab Owner's uid
13303 @item @code{VALUES(6)} @tab Owner's gid
13304 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
13305 @item @code{VALUES(8)} @tab File size (bytes)
13306 @item @code{VALUES(9)} @tab Last access time
13307 @item @code{VALUES(10)} @tab Last modification time
13308 @item @code{VALUES(11)} @tab Last file status change time
13309 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
13310 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
13313 Not all these elements are relevant on all systems.
13314 If an element is not relevant, it is returned as 0.
13316 This intrinsic is provided in both subroutine and function forms; however,
13317 only one form can be used in any given program unit.
13319 @item @emph{Standard}:
13322 @item @emph{Class}:
13323 Subroutine, function
13325 @item @emph{Syntax}:
13326 @multitable @columnfractions .80
13327 @item @code{CALL STAT(NAME, VALUES [, STATUS])}
13328 @item @code{STATUS = STAT(NAME, VALUES)}
13331 @item @emph{Arguments}:
13332 @multitable @columnfractions .15 .70
13333 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
13334 default kind and a valid path within the file system.
13335 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
13336 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
13337 on success and a system specific error code otherwise.
13340 @item @emph{Example}:
13343 INTEGER, DIMENSION(13) :: buff
13346 CALL STAT("/etc/passwd", buff, status)
13348 IF (status == 0) THEN
13349 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
13350 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
13351 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
13352 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
13353 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
13354 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
13355 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
13356 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
13357 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
13358 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
13359 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
13360 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
13361 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
13366 @item @emph{See also}:
13367 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
13373 @section @code{STORAGE_SIZE} --- Storage size in bits
13374 @fnindex STORAGE_SIZE
13375 @cindex storage size
13378 @item @emph{Description}:
13379 Returns the storage size of argument @var{A} in bits.
13380 @item @emph{Standard}:
13381 Fortran 2008 and later
13382 @item @emph{Class}:
13384 @item @emph{Syntax}:
13385 @code{RESULT = STORAGE_SIZE(A [, KIND])}
13387 @item @emph{Arguments}:
13388 @multitable @columnfractions .15 .70
13389 @item @var{A} @tab Shall be a scalar or array of any type.
13390 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
13393 @item @emph{Return Value}:
13394 The result is a scalar integer with the kind type parameter specified by KIND
13395 (or default integer type if KIND is missing). The result value is the size
13396 expressed in bits for an element of an array that has the dynamic type and type
13399 @item @emph{See also}:
13400 @ref{C_SIZEOF}, @ref{SIZEOF}
13406 @section @code{SUM} --- Sum of array elements
13409 @cindex array, add elements
13410 @cindex array, conditionally add elements
13411 @cindex sum array elements
13414 @item @emph{Description}:
13415 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
13416 the corresponding element in @var{MASK} is @code{TRUE}.
13418 @item @emph{Standard}:
13419 Fortran 95 and later
13421 @item @emph{Class}:
13422 Transformational function
13424 @item @emph{Syntax}:
13425 @multitable @columnfractions .80
13426 @item @code{RESULT = SUM(ARRAY[, MASK])}
13427 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
13430 @item @emph{Arguments}:
13431 @multitable @columnfractions .15 .70
13432 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
13433 @code{REAL} or @code{COMPLEX}.
13434 @item @var{DIM} @tab (Optional) shall be a scalar of type
13435 @code{INTEGER} with a value in the range from 1 to n, where n
13436 equals the rank of @var{ARRAY}.
13437 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
13438 and either be a scalar or an array of the same shape as @var{ARRAY}.
13441 @item @emph{Return value}:
13442 The result is of the same type as @var{ARRAY}.
13444 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
13445 is returned. Otherwise, an array of rank n-1, where n equals the rank of
13446 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
13447 dropped is returned.
13449 @item @emph{Example}:
13452 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
13453 print *, SUM(x) ! all elements, sum = 15
13454 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
13458 @item @emph{See also}:
13465 @section @code{SYMLNK} --- Create a symbolic link
13467 @cindex file system, create link
13468 @cindex file system, soft link
13471 @item @emph{Description}:
13472 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
13473 character (@code{CHAR(0)}) can be used to mark the end of the names in
13474 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
13475 names are ignored. If the @var{STATUS} argument is supplied, it
13476 contains 0 on success or a nonzero error code upon return; see
13477 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
13478 @code{ENOSYS} is returned.
13480 This intrinsic is provided in both subroutine and function forms;
13481 however, only one form can be used in any given program unit.
13483 @item @emph{Standard}:
13486 @item @emph{Class}:
13487 Subroutine, function
13489 @item @emph{Syntax}:
13490 @multitable @columnfractions .80
13491 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
13492 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
13495 @item @emph{Arguments}:
13496 @multitable @columnfractions .15 .70
13497 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
13498 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
13499 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
13502 @item @emph{See also}:
13503 @ref{LINK}, @ref{UNLINK}
13510 @section @code{SYSTEM} --- Execute a shell command
13512 @cindex system, system call
13515 @item @emph{Description}:
13516 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
13517 argument @var{STATUS} is present, it contains the value returned by
13518 @code{system(3)}, which is presumably 0 if the shell command succeeded.
13519 Note that which shell is used to invoke the command is system-dependent
13520 and environment-dependent.
13522 This intrinsic is provided in both subroutine and function forms;
13523 however, only one form can be used in any given program unit.
13525 Note that the @code{system} function need not be thread-safe. It is
13526 the responsibility of the user to ensure that @code{system} is not
13527 called concurrently.
13529 @item @emph{Standard}:
13532 @item @emph{Class}:
13533 Subroutine, function
13535 @item @emph{Syntax}:
13536 @multitable @columnfractions .80
13537 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
13538 @item @code{STATUS = SYSTEM(COMMAND)}
13541 @item @emph{Arguments}:
13542 @multitable @columnfractions .15 .70
13543 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
13544 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
13547 @item @emph{See also}:
13548 @ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
13549 and should considered in new code for future portability.
13555 @section @code{SYSTEM_CLOCK} --- Time function
13556 @fnindex SYSTEM_CLOCK
13557 @cindex time, clock ticks
13558 @cindex clock ticks
13561 @item @emph{Description}:
13562 Determines the @var{COUNT} of a processor clock since an unspecified
13563 time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines
13564 the number of clock ticks per second. If the platform supports a
13565 monotonic clock, that clock is used and can, depending on the platform
13566 clock implementation, provide up to nanosecond resolution. If a
13567 monotonic clock is not available, the implementation falls back to a
13570 @var{COUNT_RATE} is system dependent and can vary depending on the kind of
13571 the arguments. For @var{kind=4} arguments (and smaller integer kinds),
13572 @var{COUNT} represents milliseconds, while for @var{kind=8} arguments (and
13573 larger integer kinds), @var{COUNT} typically represents micro- or
13574 nanoseconds depending on resolution of the underlying platform clock.
13575 @var{COUNT_MAX} usually equals @code{HUGE(COUNT_MAX)}. Note that the
13576 millisecond resolution of the @var{kind=4} version implies that the
13577 @var{COUNT} will wrap around in roughly 25 days. In order to avoid issues
13578 with the wrap around and for more precise timing, please use the
13579 @var{kind=8} version.
13581 If there is no clock, or querying the clock fails, @var{COUNT} is set
13582 to @code{-HUGE(COUNT)}, and @var{COUNT_RATE} and @var{COUNT_MAX} are
13585 When running on a platform using the GNU C library (glibc) version
13586 2.16 or older, or a derivative thereof, the high resolution monotonic
13587 clock is available only when linking with the @var{rt} library. This
13588 can be done explicitly by adding the @code{-lrt} flag when linking the
13589 application, but is also done implicitly when using OpenMP.
13591 On the Windows platform, the version with @var{kind=4} arguments uses
13592 the @code{GetTickCount} function, whereas the @var{kind=8} version
13593 uses @code{QueryPerformanceCounter} and
13594 @code{QueryPerformanceCounterFrequency}. For more information, and
13595 potential caveats, please see the platform documentation.
13597 @item @emph{Standard}:
13598 Fortran 95 and later
13600 @item @emph{Class}:
13603 @item @emph{Syntax}:
13604 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
13606 @item @emph{Arguments}:
13607 @multitable @columnfractions .15 .70
13608 @item @var{COUNT} @tab (Optional) shall be a scalar of type
13609 @code{INTEGER} with @code{INTENT(OUT)}.
13610 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type
13611 @code{INTEGER} or @code{REAL}, with @code{INTENT(OUT)}.
13612 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type
13613 @code{INTEGER} with @code{INTENT(OUT)}.
13616 @item @emph{Example}:
13618 PROGRAM test_system_clock
13619 INTEGER :: count, count_rate, count_max
13620 CALL SYSTEM_CLOCK(count, count_rate, count_max)
13621 WRITE(*,*) count, count_rate, count_max
13625 @item @emph{See also}:
13626 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
13632 @section @code{TAN} --- Tangent function
13635 @cindex trigonometric function, tangent
13639 @item @emph{Description}:
13640 @code{TAN(X)} computes the tangent of @var{X}.
13642 @item @emph{Standard}:
13643 Fortran 77 and later, for a complex argument Fortran 2008 or later
13645 @item @emph{Class}:
13648 @item @emph{Syntax}:
13649 @code{RESULT = TAN(X)}
13651 @item @emph{Arguments}:
13652 @multitable @columnfractions .15 .70
13653 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13656 @item @emph{Return value}:
13657 The return value has same type and kind as @var{X}, and its value is in radians.
13659 @item @emph{Example}:
13662 real(8) :: x = 0.165_8
13664 end program test_tan
13667 @item @emph{Specific names}:
13668 @multitable @columnfractions .20 .20 .20 .25
13669 @item Name @tab Argument @tab Return type @tab Standard
13670 @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
13671 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
13674 @item @emph{See also}:
13675 Inverse function: @ref{ATAN}
13676 Degrees function: @ref{TAND}
13682 @section @code{TAND} --- Tangent function, degrees
13685 @cindex trigonometric function, tangent, degrees
13686 @cindex tangent, degrees
13689 @item @emph{Description}:
13690 @code{TAND(X)} computes the tangent of @var{X} in degrees.
13692 This function is for compatibility only and should be avoided in favor of
13693 standard constructs wherever possible.
13695 @item @emph{Standard}:
13696 GNU Extension, enabled with @option{-fdec-math}.
13698 @item @emph{Class}:
13701 @item @emph{Syntax}:
13702 @code{RESULT = TAND(X)}
13704 @item @emph{Arguments}:
13705 @multitable @columnfractions .15 .70
13706 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13709 @item @emph{Return value}:
13710 The return value has same type and kind as @var{X}, and its value is in degrees.
13712 @item @emph{Example}:
13715 real(8) :: x = 0.165_8
13717 end program test_tand
13720 @item @emph{Specific names}:
13721 @multitable @columnfractions .20 .20 .20 .25
13722 @item Name @tab Argument @tab Return type @tab Standard
13723 @item @code{TAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
13724 @item @code{DTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
13727 @item @emph{See also}:
13728 Inverse function: @ref{ATAND}
13729 Radians function: @ref{TAN}
13735 @section @code{TANH} --- Hyperbolic tangent function
13738 @cindex hyperbolic tangent
13739 @cindex hyperbolic function, tangent
13740 @cindex tangent, hyperbolic
13743 @item @emph{Description}:
13744 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
13746 @item @emph{Standard}:
13747 Fortran 77 and later, for a complex argument Fortran 2008 or later
13749 @item @emph{Class}:
13752 @item @emph{Syntax}:
13755 @item @emph{Arguments}:
13756 @multitable @columnfractions .15 .70
13757 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13760 @item @emph{Return value}:
13761 The return value has same type and kind as @var{X}. If @var{X} is
13762 complex, the imaginary part of the result is in radians. If @var{X}
13763 is @code{REAL}, the return value lies in the range
13764 @math{ - 1 \leq tanh(x) \leq 1 }.
13766 @item @emph{Example}:
13769 real(8) :: x = 2.1_8
13771 end program test_tanh
13774 @item @emph{Specific names}:
13775 @multitable @columnfractions .20 .20 .20 .25
13776 @item Name @tab Argument @tab Return type @tab Standard
13777 @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
13778 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
13781 @item @emph{See also}:
13788 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
13789 @fnindex THIS_IMAGE
13790 @cindex coarray, @code{THIS_IMAGE}
13791 @cindex images, index of this image
13794 @item @emph{Description}:
13795 Returns the cosubscript for this image.
13797 @item @emph{Standard}:
13798 Fortran 2008 and later. With @var{DISTANCE} argument,
13799 Technical Specification (TS) 18508 or later
13801 @item @emph{Class}:
13802 Transformational function
13804 @item @emph{Syntax}:
13805 @multitable @columnfractions .80
13806 @item @code{RESULT = THIS_IMAGE()}
13807 @item @code{RESULT = THIS_IMAGE(DISTANCE)}
13808 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
13811 @item @emph{Arguments}:
13812 @multitable @columnfractions .15 .70
13813 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
13814 (not permitted together with @var{COARRAY}).
13815 @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
13816 present, required).
13817 @item @var{DIM} @tab default integer scalar (optional). If present,
13818 @var{DIM} shall be between one and the corank of @var{COARRAY}.
13822 @item @emph{Return value}:
13823 Default integer. If @var{COARRAY} is not present, it is scalar; if
13824 @var{DISTANCE} is not present or has value 0, its value is the image index on
13825 the invoking image for the current team, for values smaller or equal
13826 distance to the initial team, it returns the image index on the ancestor team
13827 which has a distance of @var{DISTANCE} from the invoking team. If
13828 @var{DISTANCE} is larger than the distance to the initial team, the image
13829 index of the initial team is returned. Otherwise when the @var{COARRAY} is
13830 present, if @var{DIM} is not present, a rank-1 array with corank elements is
13831 returned, containing the cosubscripts for @var{COARRAY} specifying the invoking
13832 image. If @var{DIM} is present, a scalar is returned, with the value of
13833 the @var{DIM} element of @code{THIS_IMAGE(COARRAY)}.
13835 @item @emph{Example}:
13837 INTEGER :: value[*]
13839 value = THIS_IMAGE()
13841 IF (THIS_IMAGE() == 1) THEN
13842 DO i = 1, NUM_IMAGES()
13843 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
13847 ! Check whether the current image is the initial image
13848 IF (THIS_IMAGE(HUGE(1)) /= THIS_IMAGE())
13849 error stop "something is rotten here"
13852 @item @emph{See also}:
13853 @ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
13859 @section @code{TIME} --- Time function
13861 @cindex time, current
13862 @cindex current time
13865 @item @emph{Description}:
13866 Returns the current time encoded as an integer (in the manner of the
13867 function @code{time(3)} in the C standard library). This value is
13868 suitable for passing to @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
13870 This intrinsic is not fully portable, such as to systems with 32-bit
13871 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
13872 the values returned by this intrinsic might be, or become, negative, or
13873 numerically less than previous values, during a single run of the
13876 See @ref{TIME8}, for information on a similar intrinsic that might be
13877 portable to more GNU Fortran implementations, though to fewer Fortran
13880 @item @emph{Standard}:
13883 @item @emph{Class}:
13886 @item @emph{Syntax}:
13887 @code{RESULT = TIME()}
13889 @item @emph{Return value}:
13890 The return value is a scalar of type @code{INTEGER(4)}.
13892 @item @emph{See also}:
13893 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
13900 @section @code{TIME8} --- Time function (64-bit)
13902 @cindex time, current
13903 @cindex current time
13906 @item @emph{Description}:
13907 Returns the current time encoded as an integer (in the manner of the
13908 function @code{time(3)} in the C standard library). This value is
13909 suitable for passing to @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
13911 @emph{Warning:} this intrinsic does not increase the range of the timing
13912 values over that returned by @code{time(3)}. On a system with a 32-bit
13913 @code{time(3)}, @code{TIME8} will return a 32-bit value, even though
13914 it is converted to a 64-bit @code{INTEGER(8)} value. That means
13915 overflows of the 32-bit value can still occur. Therefore, the values
13916 returned by this intrinsic might be or become negative or numerically
13917 less than previous values during a single run of the compiled program.
13919 @item @emph{Standard}:
13922 @item @emph{Class}:
13925 @item @emph{Syntax}:
13926 @code{RESULT = TIME8()}
13928 @item @emph{Return value}:
13929 The return value is a scalar of type @code{INTEGER(8)}.
13931 @item @emph{See also}:
13932 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
13939 @section @code{TINY} --- Smallest positive number of a real kind
13941 @cindex limits, smallest number
13942 @cindex model representation, smallest number
13945 @item @emph{Description}:
13946 @code{TINY(X)} returns the smallest positive (non zero) number
13947 in the model of the type of @code{X}.
13949 @item @emph{Standard}:
13950 Fortran 95 and later
13952 @item @emph{Class}:
13955 @item @emph{Syntax}:
13956 @code{RESULT = TINY(X)}
13958 @item @emph{Arguments}:
13959 @multitable @columnfractions .15 .70
13960 @item @var{X} @tab Shall be of type @code{REAL}.
13963 @item @emph{Return value}:
13964 The return value is of the same type and kind as @var{X}
13966 @item @emph{Example}:
13967 See @code{HUGE} for an example.
13973 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
13978 @item @emph{Description}:
13979 @code{TRAILZ} returns the number of trailing zero bits of an integer.
13981 @item @emph{Standard}:
13982 Fortran 2008 and later
13984 @item @emph{Class}:
13987 @item @emph{Syntax}:
13988 @code{RESULT = TRAILZ(I)}
13990 @item @emph{Arguments}:
13991 @multitable @columnfractions .15 .70
13992 @item @var{I} @tab Shall be of type @code{INTEGER}.
13995 @item @emph{Return value}:
13996 The type of the return value is the default @code{INTEGER}.
13997 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
13999 @item @emph{Example}:
14001 PROGRAM test_trailz
14002 WRITE (*,*) TRAILZ(8) ! prints 3
14006 @item @emph{See also}:
14007 @ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT}
14013 @section @code{TRANSFER} --- Transfer bit patterns
14019 @item @emph{Description}:
14020 Interprets the bitwise representation of @var{SOURCE} in memory as if it
14021 is the representation of a variable or array of the same type and type
14022 parameters as @var{MOLD}.
14024 This is approximately equivalent to the C concept of @emph{casting} one
14027 @item @emph{Standard}:
14028 Fortran 95 and later
14030 @item @emph{Class}:
14031 Transformational function
14033 @item @emph{Syntax}:
14034 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
14036 @item @emph{Arguments}:
14037 @multitable @columnfractions .15 .70
14038 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
14039 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
14040 @item @var{SIZE} @tab (Optional) shall be a scalar of type
14044 @item @emph{Return value}:
14045 The result has the same type as @var{MOLD}, with the bit level
14046 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
14047 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
14048 but @var{MOLD} is an array (of any size or shape), the result is a one-
14049 dimensional array of the minimum length needed to contain the entirety
14050 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
14051 and @var{MOLD} is a scalar, the result is a scalar.
14053 If the bitwise representation of the result is longer than that of
14054 @var{SOURCE}, then the leading bits of the result correspond to those of
14055 @var{SOURCE} and any trailing bits are filled arbitrarily.
14057 When the resulting bit representation does not correspond to a valid
14058 representation of a variable of the same type as @var{MOLD}, the results
14059 are undefined, and subsequent operations on the result cannot be
14060 guaranteed to produce sensible behavior. For example, it is possible to
14061 create @code{LOGICAL} variables for which @code{@var{VAR}} and
14062 @code{.NOT.@var{VAR}} both appear to be true.
14064 @item @emph{Example}:
14066 PROGRAM test_transfer
14067 integer :: x = 2143289344
14068 print *, transfer(x, 1.0) ! prints "NaN" on i686
14076 @section @code{TRANSPOSE} --- Transpose an array of rank two
14078 @cindex array, transpose
14079 @cindex matrix, transpose
14083 @item @emph{Description}:
14084 Transpose an array of rank two. Element (i, j) of the result has the value
14085 @code{MATRIX(j, i)}, for all i, j.
14087 @item @emph{Standard}:
14088 Fortran 95 and later
14090 @item @emph{Class}:
14091 Transformational function
14093 @item @emph{Syntax}:
14094 @code{RESULT = TRANSPOSE(MATRIX)}
14096 @item @emph{Arguments}:
14097 @multitable @columnfractions .15 .70
14098 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
14101 @item @emph{Return value}:
14102 The result has the same type as @var{MATRIX}, and has shape
14103 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
14109 @section @code{TRIM} --- Remove trailing blank characters of a string
14111 @cindex string, remove trailing whitespace
14114 @item @emph{Description}:
14115 Removes trailing blank characters of a string.
14117 @item @emph{Standard}:
14118 Fortran 95 and later
14120 @item @emph{Class}:
14121 Transformational function
14123 @item @emph{Syntax}:
14124 @code{RESULT = TRIM(STRING)}
14126 @item @emph{Arguments}:
14127 @multitable @columnfractions .15 .70
14128 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
14131 @item @emph{Return value}:
14132 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
14133 less the number of trailing blanks.
14135 @item @emph{Example}:
14138 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
14139 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
14143 @item @emph{See also}:
14144 @ref{ADJUSTL}, @ref{ADJUSTR}
14150 @section @code{TTYNAM} --- Get the name of a terminal device.
14152 @cindex system, terminal
14155 @item @emph{Description}:
14156 Get the name of a terminal device. For more information,
14157 see @code{ttyname(3)}.
14159 This intrinsic is provided in both subroutine and function forms;
14160 however, only one form can be used in any given program unit.
14162 @item @emph{Standard}:
14165 @item @emph{Class}:
14166 Subroutine, function
14168 @item @emph{Syntax}:
14169 @multitable @columnfractions .80
14170 @item @code{CALL TTYNAM(UNIT, NAME)}
14171 @item @code{NAME = TTYNAM(UNIT)}
14174 @item @emph{Arguments}:
14175 @multitable @columnfractions .15 .70
14176 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
14177 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
14180 @item @emph{Example}:
14182 PROGRAM test_ttynam
14185 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
14190 @item @emph{See also}:
14197 @section @code{UBOUND} --- Upper dimension bounds of an array
14199 @cindex array, upper bound
14202 @item @emph{Description}:
14203 Returns the upper bounds of an array, or a single upper bound
14204 along the @var{DIM} dimension.
14205 @item @emph{Standard}:
14206 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
14208 @item @emph{Class}:
14211 @item @emph{Syntax}:
14212 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
14214 @item @emph{Arguments}:
14215 @multitable @columnfractions .15 .70
14216 @item @var{ARRAY} @tab Shall be an array, of any type.
14217 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
14218 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
14219 expression indicating the kind parameter of the result.
14222 @item @emph{Return value}:
14223 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14224 @var{KIND} is absent, the return value is of default integer kind.
14225 If @var{DIM} is absent, the result is an array of the upper bounds of
14226 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
14227 corresponding to the upper bound of the array along that dimension. If
14228 @var{ARRAY} is an expression rather than a whole array or array
14229 structure component, or if it has a zero extent along the relevant
14230 dimension, the upper bound is taken to be the number of elements along
14231 the relevant dimension.
14233 @item @emph{See also}:
14234 @ref{LBOUND}, @ref{LCOBOUND}
14240 @section @code{UCOBOUND} --- Upper codimension bounds of an array
14242 @cindex coarray, upper bound
14245 @item @emph{Description}:
14246 Returns the upper cobounds of a coarray, or a single upper cobound
14247 along the @var{DIM} codimension.
14248 @item @emph{Standard}:
14249 Fortran 2008 and later
14251 @item @emph{Class}:
14254 @item @emph{Syntax}:
14255 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
14257 @item @emph{Arguments}:
14258 @multitable @columnfractions .15 .70
14259 @item @var{ARRAY} @tab Shall be an coarray, of any type.
14260 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
14261 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
14262 expression indicating the kind parameter of the result.
14265 @item @emph{Return value}:
14266 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14267 @var{KIND} is absent, the return value is of default integer kind.
14268 If @var{DIM} is absent, the result is an array of the lower cobounds of
14269 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
14270 corresponding to the lower cobound of the array along that codimension.
14272 @item @emph{See also}:
14273 @ref{LCOBOUND}, @ref{LBOUND}
14279 @section @code{UMASK} --- Set the file creation mask
14281 @cindex file system, file creation mask
14284 @item @emph{Description}:
14285 Sets the file creation mask to @var{MASK}. If called as a function, it
14286 returns the old value. If called as a subroutine and argument @var{OLD}
14287 if it is supplied, it is set to the old value. See @code{umask(2)}.
14289 @item @emph{Standard}:
14292 @item @emph{Class}:
14293 Subroutine, function
14295 @item @emph{Syntax}:
14296 @multitable @columnfractions .80
14297 @item @code{CALL UMASK(MASK [, OLD])}
14298 @item @code{OLD = UMASK(MASK)}
14301 @item @emph{Arguments}:
14302 @multitable @columnfractions .15 .70
14303 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
14304 @item @var{OLD} @tab (Optional) Shall be a scalar of type
14313 @section @code{UNLINK} --- Remove a file from the file system
14315 @cindex file system, remove file
14318 @item @emph{Description}:
14319 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
14320 used to mark the end of the name in @var{PATH}; otherwise, trailing
14321 blanks in the file name are ignored. If the @var{STATUS} argument is
14322 supplied, it contains 0 on success or a nonzero error code upon return;
14323 see @code{unlink(2)}.
14325 This intrinsic is provided in both subroutine and function forms;
14326 however, only one form can be used in any given program unit.
14328 @item @emph{Standard}:
14331 @item @emph{Class}:
14332 Subroutine, function
14334 @item @emph{Syntax}:
14335 @multitable @columnfractions .80
14336 @item @code{CALL UNLINK(PATH [, STATUS])}
14337 @item @code{STATUS = UNLINK(PATH)}
14340 @item @emph{Arguments}:
14341 @multitable @columnfractions .15 .70
14342 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
14343 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
14346 @item @emph{See also}:
14347 @ref{LINK}, @ref{SYMLNK}
14353 @section @code{UNPACK} --- Unpack an array of rank one into an array
14355 @cindex array, unpacking
14356 @cindex array, increase dimension
14357 @cindex array, scatter elements
14360 @item @emph{Description}:
14361 Store the elements of @var{VECTOR} in an array of higher rank.
14363 @item @emph{Standard}:
14364 Fortran 95 and later
14366 @item @emph{Class}:
14367 Transformational function
14369 @item @emph{Syntax}:
14370 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
14372 @item @emph{Arguments}:
14373 @multitable @columnfractions .15 .70
14374 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
14375 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
14376 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
14377 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
14378 the same shape as @var{MASK}.
14381 @item @emph{Return value}:
14382 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
14383 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
14385 @item @emph{Example}:
14387 PROGRAM test_unpack
14388 integer :: vector(2) = (/1,1/)
14389 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
14390 integer :: field(2,2) = 0, unity(2,2)
14392 ! result: unity matrix
14393 unity = unpack(vector, reshape(mask, (/2,2/)), field)
14397 @item @emph{See also}:
14398 @ref{PACK}, @ref{SPREAD}
14404 @section @code{VERIFY} --- Scan a string for characters not a given set
14406 @cindex string, find missing set
14409 @item @emph{Description}:
14410 Verifies that all the characters in @var{STRING} belong to the set of
14411 characters in @var{SET}.
14413 If @var{BACK} is either absent or equals @code{FALSE}, this function
14414 returns the position of the leftmost character of @var{STRING} that is
14415 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost
14416 position is returned. If all characters of @var{STRING} are found in
14417 @var{SET}, the result is zero.
14419 @item @emph{Standard}:
14420 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
14422 @item @emph{Class}:
14425 @item @emph{Syntax}:
14426 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
14428 @item @emph{Arguments}:
14429 @multitable @columnfractions .15 .70
14430 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
14431 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
14432 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
14433 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
14434 expression indicating the kind parameter of the result.
14437 @item @emph{Return value}:
14438 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14439 @var{KIND} is absent, the return value is of default integer kind.
14441 @item @emph{Example}:
14443 PROGRAM test_verify
14444 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
14445 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
14446 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
14447 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
14448 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
14452 @item @emph{See also}:
14453 @ref{SCAN}, @ref{INDEX intrinsic}
14459 @section @code{XOR} --- Bitwise logical exclusive OR
14461 @cindex bitwise logical exclusive or
14462 @cindex logical exclusive or, bitwise
14465 @item @emph{Description}:
14466 Bitwise logical exclusive or.
14468 This intrinsic routine is provided for backwards compatibility with
14469 GNU Fortran 77. For integer arguments, programmers should consider
14470 the use of the @ref{IEOR} intrinsic and for logical arguments the
14471 @code{.NEQV.} operator, which are both defined by the Fortran standard.
14473 @item @emph{Standard}:
14476 @item @emph{Class}:
14479 @item @emph{Syntax}:
14480 @code{RESULT = XOR(I, J)}
14482 @item @emph{Arguments}:
14483 @multitable @columnfractions .15 .70
14484 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
14485 type or a scalar @code{LOGICAL} type.
14486 @item @var{J} @tab The type shall be the same as the type of @var{I}.
14489 @item @emph{Return value}:
14490 The return type is either a scalar @code{INTEGER} or a scalar
14491 @code{LOGICAL}. If the kind type parameters differ, then the
14492 smaller kind type is implicitly converted to larger kind, and the
14493 return has the larger kind.
14495 @item @emph{Example}:
14498 LOGICAL :: T = .TRUE., F = .FALSE.
14500 DATA a / Z'F' /, b / Z'3' /
14502 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
14503 WRITE (*,*) XOR(a, b)
14507 @item @emph{See also}:
14508 Fortran 95 elemental function: @ref{IEOR}
14513 @node Intrinsic Modules
14514 @chapter Intrinsic Modules
14515 @cindex intrinsic Modules
14518 * ISO_FORTRAN_ENV::
14521 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
14522 * OpenACC Module OPENACC::
14525 @node ISO_FORTRAN_ENV
14526 @section @code{ISO_FORTRAN_ENV}
14528 @item @emph{Standard}:
14529 Fortran 2003 and later, except when otherwise noted
14532 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
14536 @item @code{ATOMIC_INT_KIND}:
14537 Default-kind integer constant to be used as kind parameter when defining
14538 integer variables used in atomic operations. (Fortran 2008 or later.)
14540 @item @code{ATOMIC_LOGICAL_KIND}:
14541 Default-kind integer constant to be used as kind parameter when defining
14542 logical variables used in atomic operations. (Fortran 2008 or later.)
14544 @item @code{CHARACTER_KINDS}:
14545 Default-kind integer constant array of rank one containing the supported kind
14546 parameters of the @code{CHARACTER} type. (Fortran 2008 or later.)
14548 @item @code{CHARACTER_STORAGE_SIZE}:
14549 Size in bits of the character storage unit.
14551 @item @code{ERROR_UNIT}:
14552 Identifies the preconnected unit used for error reporting.
14554 @item @code{FILE_STORAGE_SIZE}:
14555 Size in bits of the file-storage unit.
14557 @item @code{INPUT_UNIT}:
14558 Identifies the preconnected unit identified by the asterisk
14559 (@code{*}) in @code{READ} statement.
14561 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
14562 Kind type parameters to specify an INTEGER type with a storage
14563 size of 16, 32, and 64 bits. It is negative if a target platform
14564 does not support the particular kind. (Fortran 2008 or later.)
14566 @item @code{INTEGER_KINDS}:
14567 Default-kind integer constant array of rank one containing the supported kind
14568 parameters of the @code{INTEGER} type. (Fortran 2008 or later.)
14570 @item @code{IOSTAT_END}:
14571 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
14572 an input/output statement if an end-of-file condition occurred.
14574 @item @code{IOSTAT_EOR}:
14575 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
14576 an input/output statement if an end-of-record condition occurred.
14578 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
14579 Scalar default-integer constant, used by @code{INQUIRE} for the
14580 @code{IOSTAT=} specifier to denote an that a unit number identifies an
14581 internal unit. (Fortran 2008 or later.)
14583 @item @code{NUMERIC_STORAGE_SIZE}:
14584 The size in bits of the numeric storage unit.
14586 @item @code{LOGICAL_KINDS}:
14587 Default-kind integer constant array of rank one containing the supported kind
14588 parameters of the @code{LOGICAL} type. (Fortran 2008 or later.)
14590 @item @code{OUTPUT_UNIT}:
14591 Identifies the preconnected unit identified by the asterisk
14592 (@code{*}) in @code{WRITE} statement.
14594 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
14595 Kind type parameters to specify a REAL type with a storage
14596 size of 32, 64, and 128 bits. It is negative if a target platform
14597 does not support the particular kind. (Fortran 2008 or later.)
14599 @item @code{REAL_KINDS}:
14600 Default-kind integer constant array of rank one containing the supported kind
14601 parameters of the @code{REAL} type. (Fortran 2008 or later.)
14603 @item @code{STAT_LOCKED}:
14604 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
14605 denote that the lock variable is locked by the executing image. (Fortran 2008
14608 @item @code{STAT_LOCKED_OTHER_IMAGE}:
14609 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
14610 denote that the lock variable is locked by another image. (Fortran 2008 or
14613 @item @code{STAT_STOPPED_IMAGE}:
14614 Positive, scalar default-integer constant used as STAT= return value if the
14615 argument in the statement requires synchronisation with an image, which has
14616 initiated the termination of the execution. (Fortran 2008 or later.)
14618 @item @code{STAT_FAILED_IMAGE}:
14619 Positive, scalar default-integer constant used as STAT= return value if the
14620 argument in the statement requires communication with an image, which has
14621 is in the failed state. (TS 18508 or later.)
14623 @item @code{STAT_UNLOCKED}:
14624 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
14625 denote that the lock variable is unlocked. (Fortran 2008 or later.)
14628 The module provides the following derived type:
14631 @item @code{LOCK_TYPE}:
14632 Derived type with private components to be use with the @code{LOCK} and
14633 @code{UNLOCK} statement. A variable of its type has to be always declared
14634 as coarray and may not appear in a variable-definition context.
14635 (Fortran 2008 or later.)
14638 The module also provides the following intrinsic procedures:
14639 @ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}.
14643 @node ISO_C_BINDING
14644 @section @code{ISO_C_BINDING}
14646 @item @emph{Standard}:
14647 Fortran 2003 and later, GNU extensions
14650 The following intrinsic procedures are provided by the module; their
14651 definition can be found in the section Intrinsic Procedures of this
14655 @item @code{C_ASSOCIATED}
14656 @item @code{C_F_POINTER}
14657 @item @code{C_F_PROCPOINTER}
14658 @item @code{C_FUNLOC}
14660 @item @code{C_SIZEOF}
14662 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
14663 @c don't really know why.
14665 The @code{ISO_C_BINDING} module provides the following named constants of
14666 type default integer, which can be used as KIND type parameters.
14668 In addition to the integer named constants required by the Fortran 2003
14669 standard and @code{C_PTRDIFF_T} of TS 29113, GNU Fortran provides as an
14670 extension named constants for the 128-bit integer types supported by the
14671 C compiler: @code{C_INT128_T, C_INT_LEAST128_T, C_INT_FAST128_T}.
14672 Furthermore, if @code{__float128} is supported in C, the named constants
14673 @code{C_FLOAT128, C_FLOAT128_COMPLEX} are defined.
14675 @multitable @columnfractions .15 .35 .35 .35
14676 @item Fortran Type @tab Named constant @tab C type @tab Extension
14677 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
14678 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
14679 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
14680 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
14681 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
14682 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
14683 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
14684 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
14685 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
14686 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
14687 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
14688 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
14689 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
14690 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
14691 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
14692 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
14693 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
14694 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
14695 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
14696 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
14697 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
14698 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
14699 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
14700 @item @code{INTEGER}@tab @code{C_PTRDIFF_T} @tab @code{intptr_t} @tab TS 29113
14701 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
14702 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
14703 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
14704 @item @code{REAL} @tab @code{C_FLOAT128} @tab @code{__float128} @tab Ext.
14705 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
14706 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
14707 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
14708 @item @code{REAL} @tab @code{C_FLOAT128_COMPLEX} @tab @code{__float128 _Complex} @tab Ext.
14709 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
14710 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
14713 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
14716 @multitable @columnfractions .20 .45 .15
14717 @item Name @tab C definition @tab Value
14718 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
14719 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
14720 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
14721 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
14722 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
14723 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
14724 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
14725 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
14728 Moreover, the following two named constants are defined:
14730 @multitable @columnfractions .20 .80
14731 @item Name @tab Type
14732 @item @code{C_NULL_PTR} @tab @code{C_PTR}
14733 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
14736 Both are equivalent to the value @code{NULL} in C.
14741 @section IEEE modules: @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
14743 @item @emph{Standard}:
14744 Fortran 2003 and later
14747 The @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
14748 intrinsic modules provide support for exceptions and IEEE arithmetic, as
14749 defined in Fortran 2003 and later standards, and the IEC 60559:1989 standard
14750 (@emph{Binary floating-point arithmetic for microprocessor systems}). These
14751 modules are only provided on the following supported platforms:
14754 @item i386 and x86_64 processors
14755 @item platforms which use the GNU C Library (glibc)
14756 @item platforms with support for SysV/386 routines for floating point
14757 interface (including Solaris and BSDs)
14758 @item platforms with the AIX OS
14761 For full compliance with the Fortran standards, code using the
14762 @code{IEEE_EXCEPTIONS} or @code{IEEE_ARITHMETIC} modules should be compiled
14763 with the following options: @code{-fno-unsafe-math-optimizations
14764 -frounding-math -fsignaling-nans}.
14768 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
14769 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
14771 @item @emph{Standard}:
14772 OpenMP Application Program Interface v4.0
14776 The OpenMP Fortran runtime library routines are provided both in
14777 a form of two Fortran 90 modules, named @code{OMP_LIB} and
14778 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
14779 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
14780 in the @ref{Top,,Introduction,libgomp,GNU Offloading and Multi
14781 Processing Runtime Library} manual,
14782 the named constants defined in the modules are listed
14785 For details refer to the actual
14786 @uref{http://www.openmp.org/mp-documents/OpenMP4.0.0.pdf,
14787 OpenMP Application Program Interface v4.0}.
14789 @code{OMP_LIB_KINDS} provides the following scalar default-integer
14793 @item @code{omp_lock_kind}
14794 @item @code{omp_nest_lock_kind}
14795 @item @code{omp_proc_bind_kind}
14796 @item @code{omp_sched_kind}
14799 @code{OMP_LIB} provides the scalar default-integer
14800 named constant @code{openmp_version} with a value of the form
14801 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
14802 of the OpenMP version; for OpenMP v4.0 the value is @code{201307}.
14804 The following scalar integer named constants of the
14805 kind @code{omp_sched_kind}:
14808 @item @code{omp_sched_static}
14809 @item @code{omp_sched_dynamic}
14810 @item @code{omp_sched_guided}
14811 @item @code{omp_sched_auto}
14814 And the following scalar integer named constants of the
14815 kind @code{omp_proc_bind_kind}:
14818 @item @code{omp_proc_bind_false}
14819 @item @code{omp_proc_bind_true}
14820 @item @code{omp_proc_bind_master}
14821 @item @code{omp_proc_bind_close}
14822 @item @code{omp_proc_bind_spread}
14827 @node OpenACC Module OPENACC
14828 @section OpenACC Module @code{OPENACC}
14830 @item @emph{Standard}:
14831 OpenACC Application Programming Interface v2.0
14835 The OpenACC Fortran runtime library routines are provided both in a
14836 form of a Fortran 90 module, named @code{OPENACC}, and in form of a
14837 Fortran @code{include} file named @file{openacc_lib.h}. The
14838 procedures provided by @code{OPENACC} can be found in the
14839 @ref{Top,,Introduction,libgomp,GNU Offloading and Multi Processing
14840 Runtime Library} manual, the named constants defined in the modules
14843 For details refer to the actual
14844 @uref{http://www.openacc.org/,
14845 OpenACC Application Programming Interface v2.0}.
14847 @code{OPENACC} provides the scalar default-integer
14848 named constant @code{openacc_version} with a value of the form
14849 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
14850 of the OpenACC version; for OpenACC v2.0 the value is @code{201306}.