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}
38 @node Intrinsic Procedures
39 @chapter Intrinsic Procedures
40 @cindex intrinsic procedures
43 * Introduction: Introduction to Intrinsics
44 * @code{ABORT}: ABORT, Abort the program
45 * @code{ABS}: ABS, Absolute value
46 * @code{ACCESS}: ACCESS, Checks file access modes
47 * @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence
48 * @code{ACOS}: ACOS, Arccosine function
49 * @code{ACOSD}: ACOSD, Arccosine function, degrees
50 * @code{ACOSH}: ACOSH, Inverse hyperbolic cosine function
51 * @code{ADJUSTL}: ADJUSTL, Left adjust a string
52 * @code{ADJUSTR}: ADJUSTR, Right adjust a string
53 * @code{AIMAG}: AIMAG, Imaginary part of complex number
54 * @code{AINT}: AINT, Truncate to a whole number
55 * @code{ALARM}: ALARM, Set an alarm clock
56 * @code{ALL}: ALL, Determine if all values are true
57 * @code{ALLOCATED}: ALLOCATED, Status of allocatable entity
58 * @code{AND}: AND, Bitwise logical AND
59 * @code{ANINT}: ANINT, Nearest whole number
60 * @code{ANY}: ANY, Determine if any values are true
61 * @code{ASIN}: ASIN, Arcsine function
62 * @code{ASIND}: ASIND, Arcsine function, degrees
63 * @code{ASINH}: ASINH, Inverse hyperbolic sine function
64 * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair
65 * @code{ATAN}: ATAN, Arctangent function
66 * @code{ATAND}: ATAND, Arctangent function, degrees
67 * @code{ATAN2}: ATAN2, Arctangent function
68 * @code{ATAN2D}: ATAN2D, Arctangent function, degrees
69 * @code{ATANH}: ATANH, Inverse hyperbolic tangent function
70 * @code{ATOMIC_ADD}: ATOMIC_ADD, Atomic ADD operation
71 * @code{ATOMIC_AND}: ATOMIC_AND, Atomic bitwise AND operation
72 * @code{ATOMIC_CAS}: ATOMIC_CAS, Atomic compare and swap
73 * @code{ATOMIC_DEFINE}: ATOMIC_DEFINE, Setting a variable atomically
74 * @code{ATOMIC_FETCH_ADD}: ATOMIC_FETCH_ADD, Atomic ADD operation with prior fetch
75 * @code{ATOMIC_FETCH_AND}: ATOMIC_FETCH_AND, Atomic bitwise AND operation with prior fetch
76 * @code{ATOMIC_FETCH_OR}: ATOMIC_FETCH_OR, Atomic bitwise OR operation with prior fetch
77 * @code{ATOMIC_FETCH_XOR}: ATOMIC_FETCH_XOR, Atomic bitwise XOR operation with prior fetch
78 * @code{ATOMIC_OR}: ATOMIC_OR, Atomic bitwise OR operation
79 * @code{ATOMIC_REF}: ATOMIC_REF, Obtaining the value of a variable atomically
80 * @code{ATOMIC_XOR}: ATOMIC_XOR, Atomic bitwise OR operation
81 * @code{BACKTRACE}: BACKTRACE, Show a backtrace
82 * @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0
83 * @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1
84 * @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind
85 * @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0
86 * @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1
87 * @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind
88 * @code{BGE}: BGE, Bitwise greater than or equal to
89 * @code{BGT}: BGT, Bitwise greater than
90 * @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function
91 * @code{BLE}: BLE, Bitwise less than or equal to
92 * @code{BLT}: BLT, Bitwise less than
93 * @code{BTEST}: BTEST, Bit test function
94 * @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer
95 * @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer
96 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
97 * @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure
98 * @code{C_LOC}: C_LOC, Obtain the C address of an object
99 * @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression
100 * @code{CEILING}: CEILING, Integer ceiling function
101 * @code{CHAR}: CHAR, Integer-to-character conversion function
102 * @code{CHDIR}: CHDIR, Change working directory
103 * @code{CHMOD}: CHMOD, Change access permissions of files
104 * @code{CMPLX}: CMPLX, Complex conversion function
105 * @code{CO_BROADCAST}: CO_BROADCAST, Copy a value to all images the current set of images
106 * @code{CO_MAX}: CO_MAX, Maximal value on the current set of images
107 * @code{CO_MIN}: CO_MIN, Minimal value on the current set of images
108 * @code{CO_REDUCE}: CO_REDUCE, Reduction of values on the current set of images
109 * @code{CO_SUM}: CO_SUM, Sum of values on the current set of images
110 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
111 * @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler
112 * @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string
113 * @code{COMPLEX}: COMPLEX, Complex conversion function
114 * @code{CONJG}: CONJG, Complex conjugate function
115 * @code{COS}: COS, Cosine function
116 * @code{COSD}: COSD, Cosine function, degrees
117 * @code{COSH}: COSH, Hyperbolic cosine function
118 * @code{COTAN}: COTAN, Cotangent function
119 * @code{COTAND}: COTAND, Cotangent function, degrees
120 * @code{COUNT}: COUNT, Count occurrences of TRUE in an array
121 * @code{CPU_TIME}: CPU_TIME, CPU time subroutine
122 * @code{CSHIFT}: CSHIFT, Circular shift elements of an array
123 * @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string
124 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
125 * @code{DBLE}: DBLE, Double precision conversion function
126 * @code{DCMPLX}: DCMPLX, Double complex conversion function
127 * @code{DIGITS}: DIGITS, Significant digits function
128 * @code{DIM}: DIM, Positive difference
129 * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
130 * @code{DPROD}: DPROD, Double product function
131 * @code{DREAL}: DREAL, Double real part function
132 * @code{DSHIFTL}: DSHIFTL, Combined left shift
133 * @code{DSHIFTR}: DSHIFTR, Combined right shift
134 * @code{DTIME}: DTIME, Execution time subroutine (or function)
135 * @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array
136 * @code{EPSILON}: EPSILON, Epsilon function
137 * @code{ERF}: ERF, Error function
138 * @code{ERFC}: ERFC, Complementary error function
139 * @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function
140 * @code{ETIME}: ETIME, Execution time subroutine (or function)
141 * @code{EVENT_QUERY}: EVENT_QUERY, Query whether a coarray event has occurred
142 * @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command
143 * @code{EXIT}: EXIT, Exit the program with status.
144 * @code{EXP}: EXP, Exponential function
145 * @code{EXPONENT}: EXPONENT, Exponent function
146 * @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF, Query dynamic type for extension
147 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
148 * @code{FGET}: FGET, Read a single character in stream mode from stdin
149 * @code{FGETC}: FGETC, Read a single character in stream mode
150 * @code{FLOOR}: FLOOR, Integer floor function
151 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
152 * @code{FNUM}: FNUM, File number function
153 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
154 * @code{FPUTC}: FPUTC, Write a single character in stream mode
155 * @code{FRACTION}: FRACTION, Fractional part of the model representation
156 * @code{FREE}: FREE, Memory de-allocation subroutine
157 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
158 * @code{FSTAT}: FSTAT, Get file status
159 * @code{FTELL}: FTELL, Current stream position
160 * @code{GAMMA}: GAMMA, Gamma function
161 * @code{GERROR}: GERROR, Get last system error message
162 * @code{GETARG}: GETARG, Get command line arguments
163 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
164 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
165 * @code{GETCWD}: GETCWD, Get current working directory
166 * @code{GETENV}: GETENV, Get an environmental variable
167 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
168 * @code{GETGID}: GETGID, Group ID function
169 * @code{GETLOG}: GETLOG, Get login name
170 * @code{GETPID}: GETPID, Process ID function
171 * @code{GETUID}: GETUID, User ID function
172 * @code{GMTIME}: GMTIME, Convert time to GMT info
173 * @code{HOSTNM}: HOSTNM, Get system host name
174 * @code{HUGE}: HUGE, Largest number of a kind
175 * @code{HYPOT}: HYPOT, Euclidean distance function
176 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
177 * @code{IALL}: IALL, Bitwise AND of array elements
178 * @code{IAND}: IAND, Bitwise logical and
179 * @code{IANY}: IANY, Bitwise OR of array elements
180 * @code{IARGC}: IARGC, Get the number of command line arguments
181 * @code{IBCLR}: IBCLR, Clear bit
182 * @code{IBITS}: IBITS, Bit extraction
183 * @code{IBSET}: IBSET, Set bit
184 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
185 * @code{IDATE}: IDATE, Current local time (day/month/year)
186 * @code{IEOR}: IEOR, Bitwise logical exclusive or
187 * @code{IERRNO}: IERRNO, Function to get the last system error number
188 * @code{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index conversion
189 * @code{INDEX}: INDEX intrinsic, Position of a substring within a string
190 * @code{INT}: INT, Convert to integer type
191 * @code{INT2}: INT2, Convert to 16-bit integer type
192 * @code{INT8}: INT8, Convert to 64-bit integer type
193 * @code{IOR}: IOR, Bitwise logical or
194 * @code{IPARITY}: IPARITY, Bitwise XOR of array elements
195 * @code{IRAND}: IRAND, Integer pseudo-random number
196 * @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value
197 * @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value
198 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
199 * @code{ISHFT}: ISHFT, Shift bits
200 * @code{ISHFTC}: ISHFTC, Shift bits circularly
201 * @code{ISNAN}: ISNAN, Tests for a NaN
202 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
203 * @code{KILL}: KILL, Send a signal to a process
204 * @code{KIND}: KIND, Kind of an entity
205 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
206 * @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array
207 * @code{LEADZ}: LEADZ, Number of leading zero bits of an integer
208 * @code{LEN}: LEN, Length of a character entity
209 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
210 * @code{LGE}: LGE, Lexical greater than or equal
211 * @code{LGT}: LGT, Lexical greater than
212 * @code{LINK}: LINK, Create a hard link
213 * @code{LLE}: LLE, Lexical less than or equal
214 * @code{LLT}: LLT, Lexical less than
215 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
216 * @code{LOC}: LOC, Returns the address of a variable
217 * @code{LOG}: LOG, Logarithm function
218 * @code{LOG10}: LOG10, Base 10 logarithm function
219 * @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
220 * @code{LOGICAL}: LOGICAL, Convert to logical type
221 * @code{LONG}: LONG, Convert to integer type
222 * @code{LSHIFT}: LSHIFT, Left shift bits
223 * @code{LSTAT}: LSTAT, Get file status
224 * @code{LTIME}: LTIME, Convert time to local time info
225 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
226 * @code{MASKL}: MASKL, Left justified mask
227 * @code{MASKR}: MASKR, Right justified mask
228 * @code{MATMUL}: MATMUL, matrix multiplication
229 * @code{MAX}: MAX, Maximum value of an argument list
230 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
231 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
232 * @code{MAXVAL}: MAXVAL, Maximum value of an array
233 * @code{MCLOCK}: MCLOCK, Time function
234 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
235 * @code{MERGE}: MERGE, Merge arrays
236 * @code{MERGE_BITS}: MERGE_BITS, Merge of bits under mask
237 * @code{MIN}: MIN, Minimum value of an argument list
238 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
239 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
240 * @code{MINVAL}: MINVAL, Minimum value of an array
241 * @code{MOD}: MOD, Remainder function
242 * @code{MODULO}: MODULO, Modulo function
243 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
244 * @code{MVBITS}: MVBITS, Move bits from one integer to another
245 * @code{NEAREST}: NEAREST, Nearest representable number
246 * @code{NEW_LINE}: NEW_LINE, New line character
247 * @code{NINT}: NINT, Nearest whole number
248 * @code{NORM2}: NORM2, Euclidean vector norm
249 * @code{NOT}: NOT, Logical negation
250 * @code{NULL}: NULL, Function that returns an disassociated pointer
251 * @code{NUM_IMAGES}: NUM_IMAGES, Number of images
252 * @code{OR}: OR, Bitwise logical OR
253 * @code{PACK}: PACK, Pack an array into an array of rank one
254 * @code{PARITY}: PARITY, Reduction with exclusive OR
255 * @code{PERROR}: PERROR, Print system error message
256 * @code{POPCNT}: POPCNT, Number of bits set
257 * @code{POPPAR}: POPPAR, Parity of the number of bits set
258 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
259 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
260 * @code{PRODUCT}: PRODUCT, Product of array elements
261 * @code{RADIX}: RADIX, Base of a data model
262 * @code{RAN}: RAN, Real pseudo-random number
263 * @code{RAND}: RAND, Real pseudo-random number
264 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
265 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
266 * @code{RANGE}: RANGE, Decimal exponent range
267 * @code{RANK} : RANK, Rank of a data object
268 * @code{REAL}: REAL, Convert to real type
269 * @code{RENAME}: RENAME, Rename a file
270 * @code{REPEAT}: REPEAT, Repeated string concatenation
271 * @code{RESHAPE}: RESHAPE, Function to reshape an array
272 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
273 * @code{RSHIFT}: RSHIFT, Right shift bits
274 * @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality
275 * @code{SCALE}: SCALE, Scale a real value
276 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
277 * @code{SECNDS}: SECNDS, Time function
278 * @code{SECOND}: SECOND, CPU time function
279 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind
280 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
281 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
282 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
283 * @code{SHAPE}: SHAPE, Determine the shape of an array
284 * @code{SHIFTA}: SHIFTA, Right shift with fill
285 * @code{SHIFTL}: SHIFTL, Left shift
286 * @code{SHIFTR}: SHIFTR, Right shift
287 * @code{SIGN}: SIGN, Sign copying function
288 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
289 * @code{SIN}: SIN, Sine function
290 * @code{SIND}: SIND, Sine function, degrees
291 * @code{SINH}: SINH, Hyperbolic sine function
292 * @code{SIZE}: SIZE, Function to determine the size of an array
293 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
294 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
295 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
296 * @code{SPREAD}: SPREAD, Add a dimension to an array
297 * @code{SQRT}: SQRT, Square-root function
298 * @code{SRAND}: SRAND, Reinitialize the random number generator
299 * @code{STAT}: STAT, Get file status
300 * @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits
301 * @code{SUM}: SUM, Sum of array elements
302 * @code{SYMLNK}: SYMLNK, Create a symbolic link
303 * @code{SYSTEM}: SYSTEM, Execute a shell command
304 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
305 * @code{TAN}: TAN, Tangent function
306 * @code{TAND}: TAND, Tangent function, degrees
307 * @code{TANH}: TANH, Hyperbolic tangent function
308 * @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image
309 * @code{TIME}: TIME, Time function
310 * @code{TIME8}: TIME8, Time function (64-bit)
311 * @code{TINY}: TINY, Smallest positive number of a real kind
312 * @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer
313 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
314 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
315 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
316 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
317 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
318 * @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array
319 * @code{UMASK}: UMASK, Set the file creation mask
320 * @code{UNLINK}: UNLINK, Remove a file from the file system
321 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
322 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
323 * @code{XOR}: XOR, Bitwise logical exclusive or
326 @node Introduction to Intrinsics
327 @section Introduction to intrinsic procedures
329 The intrinsic procedures provided by GNU Fortran include all of the
330 intrinsic procedures required by the Fortran 95 standard, a set of
331 intrinsic procedures for backwards compatibility with G77, and a
332 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
333 standards. Any conflict between a description here and a description in
334 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
335 2008 standard is unintentional, and the standard(s) should be considered
338 The enumeration of the @code{KIND} type parameter is processor defined in
339 the Fortran 95 standard. GNU Fortran defines the default integer type and
340 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
341 respectively. The standard mandates that both data types shall have
342 another kind, which have more precision. On typical target architectures
343 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
344 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
345 In the description of generic intrinsic procedures, the kind type parameter
346 will be specified by @code{KIND=*}, and in the description of specific
347 names for an intrinsic procedure the kind type parameter will be explicitly
348 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
349 brevity the optional @code{KIND=} syntax will be omitted.
351 Many of the intrinsic procedures take one or more optional arguments.
352 This document follows the convention used in the Fortran 95 standard,
353 and denotes such arguments by square brackets.
355 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
356 which can be used to restrict the set of intrinsic procedures to a
357 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
358 option, and so all intrinsic procedures described here are accepted. There
359 is one caveat. For a select group of intrinsic procedures, @command{g77}
360 implemented both a function and a subroutine. Both classes
361 have been implemented in @command{gfortran} for backwards compatibility
362 with @command{g77}. It is noted here that these functions and subroutines
363 cannot be intermixed in a given subprogram. In the descriptions that follow,
364 the applicable standard for each intrinsic procedure is noted.
369 @section @code{ABORT} --- Abort the program
371 @cindex program termination, with core dump
372 @cindex terminate program, with core dump
376 @item @emph{Description}:
377 @code{ABORT} causes immediate termination of the program. On operating
378 systems that support a core dump, @code{ABORT} will produce a core dump.
379 It will also print a backtrace, unless @code{-fno-backtrace} is given.
381 @item @emph{Standard}:
390 @item @emph{Return value}:
393 @item @emph{Example}:
396 integer :: i = 1, j = 2
397 if (i /= j) call abort
398 end program test_abort
401 @item @emph{See also}:
402 @ref{EXIT}, @ref{KILL}, @ref{BACKTRACE}
409 @section @code{ABS} --- Absolute value
420 @cindex absolute value
423 @item @emph{Description}:
424 @code{ABS(A)} computes the absolute value of @code{A}.
426 @item @emph{Standard}:
427 Fortran 77 and later, has overloads that are GNU extensions
433 @code{RESULT = ABS(A)}
435 @item @emph{Arguments}:
436 @multitable @columnfractions .15 .70
437 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
438 @code{REAL}, or @code{COMPLEX}.
441 @item @emph{Return value}:
442 The return value is of the same type and
443 kind as the argument except the return value is @code{REAL} for a
444 @code{COMPLEX} argument.
446 @item @emph{Example}:
451 complex :: z = (-1.e0,0.e0)
458 @item @emph{Specific names}:
459 @multitable @columnfractions .20 .20 .20 .25
460 @item Name @tab Argument @tab Return type @tab Standard
461 @item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
462 @item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
463 @item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
464 @item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
465 @item @code{BABS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
466 @item @code{IIABS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
467 @item @code{JIABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
468 @item @code{KIABS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
469 @item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
470 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
477 @section @code{ACCESS} --- Checks file access modes
479 @cindex file system, access mode
482 @item @emph{Description}:
483 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
484 exists, is readable, writable or executable. Except for the
485 executable check, @code{ACCESS} can be replaced by
486 Fortran 95's @code{INQUIRE}.
488 @item @emph{Standard}:
495 @code{RESULT = ACCESS(NAME, MODE)}
497 @item @emph{Arguments}:
498 @multitable @columnfractions .15 .70
499 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
500 file name. Tailing blank are ignored unless the character @code{achar(0)}
501 is present, then all characters up to and excluding @code{achar(0)} are
503 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
504 file access mode, may be any concatenation of @code{"r"} (readable),
505 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
509 @item @emph{Return value}:
510 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
511 accessible in the given mode; otherwise or if an invalid argument
512 has been given for @code{MODE} the value @code{1} is returned.
514 @item @emph{Example}:
518 character(len=*), parameter :: file = 'test.dat'
519 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
520 if(access(file,' ') == 0) print *, trim(file),' is exists'
521 if(access(file,'r') == 0) print *, trim(file),' is readable'
522 if(access(file,'w') == 0) print *, trim(file),' is writable'
523 if(access(file,'x') == 0) print *, trim(file),' is executable'
524 if(access(file2,'rwx') == 0) &
525 print *, trim(file2),' is readable, writable and executable'
526 end program access_test
528 @item @emph{Specific names}:
529 @item @emph{See also}:
536 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
538 @cindex @acronym{ASCII} collating sequence
539 @cindex collating sequence, @acronym{ASCII}
542 @item @emph{Description}:
543 @code{ACHAR(I)} returns the character located at position @code{I}
544 in the @acronym{ASCII} collating sequence.
546 @item @emph{Standard}:
547 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
553 @code{RESULT = ACHAR(I [, KIND])}
555 @item @emph{Arguments}:
556 @multitable @columnfractions .15 .70
557 @item @var{I} @tab The type shall be @code{INTEGER}.
558 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
559 expression indicating the kind parameter of the result.
562 @item @emph{Return value}:
563 The return value is of type @code{CHARACTER} with a length of one.
564 If the @var{KIND} argument is present, the return value is of the
565 specified kind and of the default kind otherwise.
567 @item @emph{Example}:
572 end program test_achar
576 See @ref{ICHAR} for a discussion of converting between numerical values
577 and formatted string representations.
579 @item @emph{See also}:
580 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
587 @section @code{ACOS} --- Arccosine function
590 @cindex trigonometric function, cosine, inverse
591 @cindex cosine, inverse
594 @item @emph{Description}:
595 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
597 @item @emph{Standard}:
598 Fortran 77 and later, for a complex argument Fortran 2008 or later
604 @code{RESULT = ACOS(X)}
606 @item @emph{Arguments}:
607 @multitable @columnfractions .15 .70
608 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
609 less than or equal to one - or the type shall be @code{COMPLEX}.
612 @item @emph{Return value}:
613 The return value is of the same type and kind as @var{X}.
614 The real part of the result is in radians and lies in the range
615 @math{0 \leq \Re \acos(x) \leq \pi}.
617 @item @emph{Example}:
620 real(8) :: x = 0.866_8
622 end program test_acos
625 @item @emph{Specific names}:
626 @multitable @columnfractions .20 .20 .20 .25
627 @item Name @tab Argument @tab Return type @tab Standard
628 @item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
629 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
632 @item @emph{See also}:
633 Inverse function: @ref{COS}
634 Degrees function: @ref{ACOSD}
641 @section @code{ACOSD} --- Arccosine function, degrees
644 @cindex trigonometric function, cosine, inverse, degrees
645 @cindex cosine, inverse, degrees
648 @item @emph{Description}:
649 @code{ACOSD(X)} computes the arccosine of @var{X} in degrees (inverse of
652 This function is for compatibility only and should be avoided in favor of
653 standard constructs wherever possible.
655 @item @emph{Standard}:
656 GNU Extension, enabled with @option{-fdec-math}
662 @code{RESULT = ACOSD(X)}
664 @item @emph{Arguments}:
665 @multitable @columnfractions .15 .70
666 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
667 less than or equal to one - or the type shall be @code{COMPLEX}.
670 @item @emph{Return value}:
671 The return value is of the same type and kind as @var{X}.
672 The real part of the result is in degrees and lies in the range
673 @math{0 \leq \Re \acos(x) \leq 180}.
675 @item @emph{Example}:
678 real(8) :: x = 0.866_8
680 end program test_acosd
683 @item @emph{Specific names}:
684 @multitable @columnfractions .20 .20 .20 .25
685 @item Name @tab Argument @tab Return type @tab Standard
686 @item @code{ACOSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
687 @item @code{DACOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
690 @item @emph{See also}:
691 Inverse function: @ref{COSD}
692 Radians function: @ref{ACOS}
699 @section @code{ACOSH} --- Inverse hyperbolic cosine function
702 @cindex area hyperbolic cosine
703 @cindex inverse hyperbolic cosine
704 @cindex hyperbolic function, cosine, inverse
705 @cindex cosine, hyperbolic, inverse
708 @item @emph{Description}:
709 @code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
711 @item @emph{Standard}:
712 Fortran 2008 and later
718 @code{RESULT = ACOSH(X)}
720 @item @emph{Arguments}:
721 @multitable @columnfractions .15 .70
722 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
725 @item @emph{Return value}:
726 The return value has the same type and kind as @var{X}. If @var{X} is
727 complex, the imaginary part of the result is in radians and lies between
728 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
730 @item @emph{Example}:
733 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
738 @item @emph{Specific names}:
739 @multitable @columnfractions .20 .20 .20 .25
740 @item Name @tab Argument @tab Return type @tab Standard
741 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
744 @item @emph{See also}:
745 Inverse function: @ref{COSH}
751 @section @code{ADJUSTL} --- Left adjust a string
753 @cindex string, adjust left
754 @cindex adjust string
757 @item @emph{Description}:
758 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
759 Spaces are inserted at the end of the string as needed.
761 @item @emph{Standard}:
768 @code{RESULT = ADJUSTL(STRING)}
770 @item @emph{Arguments}:
771 @multitable @columnfractions .15 .70
772 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
775 @item @emph{Return value}:
776 The return value is of type @code{CHARACTER} and of the same kind as
777 @var{STRING} where leading spaces are removed and the same number of
778 spaces are inserted on the end of @var{STRING}.
780 @item @emph{Example}:
783 character(len=20) :: str = ' gfortran'
786 end program test_adjustl
789 @item @emph{See also}:
790 @ref{ADJUSTR}, @ref{TRIM}
796 @section @code{ADJUSTR} --- Right adjust a string
798 @cindex string, adjust right
799 @cindex adjust string
802 @item @emph{Description}:
803 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
804 Spaces are inserted at the start of the string as needed.
806 @item @emph{Standard}:
813 @code{RESULT = ADJUSTR(STRING)}
815 @item @emph{Arguments}:
816 @multitable @columnfractions .15 .70
817 @item @var{STR} @tab The type shall be @code{CHARACTER}.
820 @item @emph{Return value}:
821 The return value is of type @code{CHARACTER} and of the same kind as
822 @var{STRING} where trailing spaces are removed and the same number of
823 spaces are inserted at the start of @var{STRING}.
825 @item @emph{Example}:
828 character(len=20) :: str = 'gfortran'
831 end program test_adjustr
834 @item @emph{See also}:
835 @ref{ADJUSTL}, @ref{TRIM}
841 @section @code{AIMAG} --- Imaginary part of complex number
846 @cindex complex numbers, imaginary part
849 @item @emph{Description}:
850 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
851 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
852 for compatibility with @command{g77}, and their use in new code is
853 strongly discouraged.
855 @item @emph{Standard}:
856 Fortran 77 and later, has overloads that are GNU extensions
862 @code{RESULT = AIMAG(Z)}
864 @item @emph{Arguments}:
865 @multitable @columnfractions .15 .70
866 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
869 @item @emph{Return value}:
870 The return value is of type @code{REAL} with the
871 kind type parameter of the argument.
873 @item @emph{Example}:
878 z4 = cmplx(1.e0_4, 0.e0_4)
879 z8 = cmplx(0.e0_8, 1.e0_8)
880 print *, aimag(z4), dimag(z8)
881 end program test_aimag
884 @item @emph{Specific names}:
885 @multitable @columnfractions .20 .20 .20 .25
886 @item Name @tab Argument @tab Return type @tab Standard
887 @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
888 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
889 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
890 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
897 @section @code{AINT} --- Truncate to a whole number
901 @cindex rounding, floor
904 @item @emph{Description}:
905 @code{AINT(A [, KIND])} truncates its argument to a whole number.
907 @item @emph{Standard}:
914 @code{RESULT = AINT(A [, KIND])}
916 @item @emph{Arguments}:
917 @multitable @columnfractions .15 .70
918 @item @var{A} @tab The type of the argument shall be @code{REAL}.
919 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
920 expression indicating the kind parameter of the result.
923 @item @emph{Return value}:
924 The return value is of type @code{REAL} with the kind type parameter of the
925 argument if the optional @var{KIND} is absent; otherwise, the kind
926 type parameter will be given by @var{KIND}. If the magnitude of
927 @var{X} is less than one, @code{AINT(X)} returns zero. If the
928 magnitude is equal to or greater than one then it returns the largest
929 whole number that does not exceed its magnitude. The sign is the same
930 as the sign of @var{X}.
932 @item @emph{Example}:
939 print *, aint(x4), dint(x8)
941 end program test_aint
944 @item @emph{Specific names}:
945 @multitable @columnfractions .20 .20 .20 .25
946 @item Name @tab Argument @tab Return type @tab Standard
947 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
948 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
955 @section @code{ALARM} --- Execute a routine after a given delay
957 @cindex delayed execution
960 @item @emph{Description}:
961 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
962 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
963 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
964 supplied, it will be returned with the number of seconds remaining until
965 any previously scheduled alarm was due to be delivered, or zero if there
966 was no previously scheduled alarm.
968 @item @emph{Standard}:
975 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
977 @item @emph{Arguments}:
978 @multitable @columnfractions .15 .70
979 @item @var{SECONDS} @tab The type of the argument shall be a scalar
980 @code{INTEGER}. It is @code{INTENT(IN)}.
981 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
982 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
983 values may be either @code{SIG_IGN=1} to ignore the alarm generated
984 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
985 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
986 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
989 @item @emph{Example}:
992 external handler_print
994 call alarm (3, handler_print, i)
997 end program test_alarm
999 This will cause the external routine @var{handler_print} to be called
1006 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
1008 @cindex array, apply condition
1009 @cindex array, condition testing
1012 @item @emph{Description}:
1013 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
1014 in the array along dimension @var{DIM}.
1016 @item @emph{Standard}:
1017 Fortran 95 and later
1020 Transformational function
1022 @item @emph{Syntax}:
1023 @code{RESULT = ALL(MASK [, DIM])}
1025 @item @emph{Arguments}:
1026 @multitable @columnfractions .15 .70
1027 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1028 it shall not be scalar.
1029 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1030 with a value that lies between one and the rank of @var{MASK}.
1033 @item @emph{Return value}:
1034 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
1035 the kind type parameter is the same as the kind type parameter of
1036 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
1037 an array with the rank of @var{MASK} minus 1. The shape is determined from
1038 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1042 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
1043 It also is true if @var{MASK} has zero size; otherwise, it is false.
1045 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
1046 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
1047 is determined by applying @code{ALL} to the array sections.
1050 @item @emph{Example}:
1054 l = all((/.true., .true., .true./))
1059 integer a(2,3), b(2,3)
1063 print *, all(a .eq. b, 1)
1064 print *, all(a .eq. b, 2)
1065 end subroutine section
1066 end program test_all
1073 @section @code{ALLOCATED} --- Status of an allocatable entity
1075 @cindex allocation, status
1078 @item @emph{Description}:
1079 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
1080 status of @var{ARRAY} and @var{SCALAR}, respectively.
1082 @item @emph{Standard}:
1083 Fortran 95 and later. Note, the @code{SCALAR=} keyword and allocatable
1084 scalar entities are available in Fortran 2003 and later.
1089 @item @emph{Syntax}:
1090 @multitable @columnfractions .80
1091 @item @code{RESULT = ALLOCATED(ARRAY)}
1092 @item @code{RESULT = ALLOCATED(SCALAR)}
1095 @item @emph{Arguments}:
1096 @multitable @columnfractions .15 .70
1097 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
1098 @item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar.
1101 @item @emph{Return value}:
1102 The return value is a scalar @code{LOGICAL} with the default logical
1103 kind type parameter. If the argument is allocated, then the result is
1104 @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
1106 @item @emph{Example}:
1108 program test_allocated
1110 real(4), allocatable :: x(:)
1111 if (.not. allocated(x)) allocate(x(i))
1112 end program test_allocated
1119 @section @code{AND} --- Bitwise logical AND
1121 @cindex bitwise logical and
1122 @cindex logical and, bitwise
1125 @item @emph{Description}:
1126 Bitwise logical @code{AND}.
1128 This intrinsic routine is provided for backwards compatibility with
1129 GNU Fortran 77. For integer arguments, programmers should consider
1130 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1132 @item @emph{Standard}:
1138 @item @emph{Syntax}:
1139 @code{RESULT = AND(I, J)}
1141 @item @emph{Arguments}:
1142 @multitable @columnfractions .15 .70
1143 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1144 type or a scalar @code{LOGICAL} type.
1145 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1148 @item @emph{Return value}:
1149 The return type is either a scalar @code{INTEGER} or a scalar
1150 @code{LOGICAL}. If the kind type parameters differ, then the
1151 smaller kind type is implicitly converted to larger kind, and the
1152 return has the larger kind.
1154 @item @emph{Example}:
1157 LOGICAL :: T = .TRUE., F = .FALSE.
1159 DATA a / Z'F' /, b / Z'3' /
1161 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1162 WRITE (*,*) AND(a, b)
1166 @item @emph{See also}:
1167 Fortran 95 elemental function: @ref{IAND}
1173 @section @code{ANINT} --- Nearest whole number
1177 @cindex rounding, ceiling
1180 @item @emph{Description}:
1181 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1183 @item @emph{Standard}:
1184 Fortran 77 and later
1189 @item @emph{Syntax}:
1190 @code{RESULT = ANINT(A [, KIND])}
1192 @item @emph{Arguments}:
1193 @multitable @columnfractions .15 .70
1194 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1195 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1196 expression indicating the kind parameter of the result.
1199 @item @emph{Return value}:
1200 The return value is of type real with the kind type parameter of the
1201 argument if the optional @var{KIND} is absent; otherwise, the kind
1202 type parameter will be given by @var{KIND}. If @var{A} is greater than
1203 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1204 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1206 @item @emph{Example}:
1213 print *, anint(x4), dnint(x8)
1215 end program test_anint
1218 @item @emph{Specific names}:
1219 @multitable @columnfractions .20 .20 .20 .25
1220 @item Name @tab Argument @tab Return type @tab Standard
1221 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
1222 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1229 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1231 @cindex array, apply condition
1232 @cindex array, condition testing
1235 @item @emph{Description}:
1236 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1237 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1239 @item @emph{Standard}:
1240 Fortran 95 and later
1243 Transformational function
1245 @item @emph{Syntax}:
1246 @code{RESULT = ANY(MASK [, DIM])}
1248 @item @emph{Arguments}:
1249 @multitable @columnfractions .15 .70
1250 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1251 it shall not be scalar.
1252 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1253 with a value that lies between one and the rank of @var{MASK}.
1256 @item @emph{Return value}:
1257 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1258 the kind type parameter is the same as the kind type parameter of
1259 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1260 an array with the rank of @var{MASK} minus 1. The shape is determined from
1261 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1265 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1266 otherwise, it is false. It also is false if @var{MASK} has zero size.
1268 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1269 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1270 is determined by applying @code{ANY} to the array sections.
1273 @item @emph{Example}:
1277 l = any((/.true., .true., .true./))
1282 integer a(2,3), b(2,3)
1286 print *, any(a .eq. b, 1)
1287 print *, any(a .eq. b, 2)
1288 end subroutine section
1289 end program test_any
1296 @section @code{ASIN} --- Arcsine function
1299 @cindex trigonometric function, sine, inverse
1300 @cindex sine, inverse
1303 @item @emph{Description}:
1304 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1306 @item @emph{Standard}:
1307 Fortran 77 and later, for a complex argument Fortran 2008 or later
1312 @item @emph{Syntax}:
1313 @code{RESULT = ASIN(X)}
1315 @item @emph{Arguments}:
1316 @multitable @columnfractions .15 .70
1317 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1318 less than or equal to one - or be @code{COMPLEX}.
1321 @item @emph{Return value}:
1322 The return value is of the same type and kind as @var{X}.
1323 The real part of the result is in radians and lies in the range
1324 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1326 @item @emph{Example}:
1329 real(8) :: x = 0.866_8
1331 end program test_asin
1334 @item @emph{Specific names}:
1335 @multitable @columnfractions .20 .20 .20 .25
1336 @item Name @tab Argument @tab Return type @tab Standard
1337 @item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1338 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1341 @item @emph{See also}:
1342 Inverse function: @ref{SIN}
1343 Degrees function: @ref{ASIND}
1350 @section @code{ASIND} --- Arcsine function, degrees
1353 @cindex trigonometric function, sine, inverse, degrees
1354 @cindex sine, inverse, degrees
1357 @item @emph{Description}:
1358 @code{ASIND(X)} computes the arcsine of its @var{X} in degrees (inverse of
1361 This function is for compatibility only and should be avoided in favor of
1362 standard constructs wherever possible.
1364 @item @emph{Standard}:
1365 GNU Extension, enabled with @option{-fdec-math}.
1370 @item @emph{Syntax}:
1371 @code{RESULT = ASIND(X)}
1373 @item @emph{Arguments}:
1374 @multitable @columnfractions .15 .70
1375 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1376 less than or equal to one - or be @code{COMPLEX}.
1379 @item @emph{Return value}:
1380 The return value is of the same type and kind as @var{X}.
1381 The real part of the result is in degrees and lies in the range
1382 @math{-90 \leq \Re \asin(x) \leq 90}.
1384 @item @emph{Example}:
1387 real(8) :: x = 0.866_8
1389 end program test_asind
1392 @item @emph{Specific names}:
1393 @multitable @columnfractions .20 .20 .20 .25
1394 @item Name @tab Argument @tab Return type @tab Standard
1395 @item @code{ASIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
1396 @item @code{DASIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
1399 @item @emph{See also}:
1400 Inverse function: @ref{SIND}
1401 Radians function: @ref{ASIN}
1408 @section @code{ASINH} --- Inverse hyperbolic sine function
1411 @cindex area hyperbolic sine
1412 @cindex inverse hyperbolic sine
1413 @cindex hyperbolic function, sine, inverse
1414 @cindex sine, hyperbolic, inverse
1417 @item @emph{Description}:
1418 @code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
1420 @item @emph{Standard}:
1421 Fortran 2008 and later
1426 @item @emph{Syntax}:
1427 @code{RESULT = ASINH(X)}
1429 @item @emph{Arguments}:
1430 @multitable @columnfractions .15 .70
1431 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1434 @item @emph{Return value}:
1435 The return value is of the same type and kind as @var{X}. If @var{X} is
1436 complex, the imaginary part of the result is in radians and lies between
1437 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1439 @item @emph{Example}:
1442 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1443 WRITE (*,*) ASINH(x)
1447 @item @emph{Specific names}:
1448 @multitable @columnfractions .20 .20 .20 .25
1449 @item Name @tab Argument @tab Return type @tab Standard
1450 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1453 @item @emph{See also}:
1454 Inverse function: @ref{SINH}
1460 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1462 @cindex pointer, status
1463 @cindex association status
1466 @item @emph{Description}:
1467 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1468 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1470 @item @emph{Standard}:
1471 Fortran 95 and later
1476 @item @emph{Syntax}:
1477 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1479 @item @emph{Arguments}:
1480 @multitable @columnfractions .15 .70
1481 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1482 and it can be of any type.
1483 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1484 a target. It must have the same type, kind type parameter, and
1485 array rank as @var{POINTER}.
1487 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1490 @item @emph{Return value}:
1491 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1492 There are several cases:
1494 @item (A) When the optional @var{TARGET} is not present then
1495 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1496 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1497 @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
1498 disassociated, the result is false.
1499 @item (C) If @var{TARGET} is present and an array target, the result is true if
1500 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1501 are arrays whose elements are not zero-sized storage sequences, and
1502 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1504 As in case(B), the result is false, if @var{POINTER} is disassociated.
1505 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1506 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1507 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1509 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1510 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1511 target associated with @var{POINTER} and the target associated with @var{TARGET}
1512 have the same shape, are not zero-sized arrays, are arrays whose elements are
1513 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1514 the same storage units in array element order.
1515 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1518 @item @emph{Example}:
1520 program test_associated
1522 real, target :: tgt(2) = (/1., 2./)
1523 real, pointer :: ptr(:)
1525 if (associated(ptr) .eqv. .false.) call abort
1526 if (associated(ptr,tgt) .eqv. .false.) call abort
1527 end program test_associated
1530 @item @emph{See also}:
1537 @section @code{ATAN} --- Arctangent function
1540 @cindex trigonometric function, tangent, inverse
1541 @cindex tangent, inverse
1544 @item @emph{Description}:
1545 @code{ATAN(X)} computes the arctangent of @var{X}.
1547 @item @emph{Standard}:
1548 Fortran 77 and later, for a complex argument and for two arguments
1549 Fortran 2008 or later
1554 @item @emph{Syntax}:
1555 @multitable @columnfractions .80
1556 @item @code{RESULT = ATAN(X)}
1557 @item @code{RESULT = ATAN(Y, X)}
1560 @item @emph{Arguments}:
1561 @multitable @columnfractions .15 .70
1562 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1563 if @var{Y} is present, @var{X} shall be REAL.
1564 @item @var{Y} shall be of the same type and kind as @var{X}.
1567 @item @emph{Return value}:
1568 The return value is of the same type and kind as @var{X}.
1569 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1570 Otherwise, it the arcus tangent of @var{X}, where the real part of
1571 the result is in radians and lies in the range
1572 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1574 @item @emph{Example}:
1577 real(8) :: x = 2.866_8
1579 end program test_atan
1582 @item @emph{Specific names}:
1583 @multitable @columnfractions .20 .20 .20 .25
1584 @item Name @tab Argument @tab Return type @tab Standard
1585 @item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1586 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1589 @item @emph{See also}:
1590 Inverse function: @ref{TAN}
1591 Degrees function: @ref{ATAND}
1598 @section @code{ATAND} --- Arctangent function, degrees
1601 @cindex trigonometric function, tangent, inverse, degrees
1602 @cindex tangent, inverse, degrees
1605 @item @emph{Description}:
1606 @code{ATAND(X)} computes the arctangent of @var{X} in degrees (inverse of
1609 This function is for compatibility only and should be avoided in favor of
1610 standard constructs wherever possible.
1612 @item @emph{Standard}:
1613 GNU Extension, enabled with @option{-fdec-math}.
1618 @item @emph{Syntax}:
1619 @multitable @columnfractions .80
1620 @item @code{RESULT = ATAND(X)}
1621 @item @code{RESULT = ATAND(Y, X)}
1624 @item @emph{Arguments}:
1625 @multitable @columnfractions .15 .70
1626 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1627 if @var{Y} is present, @var{X} shall be REAL.
1628 @item @var{Y} shall be of the same type and kind as @var{X}.
1631 @item @emph{Return value}:
1632 The return value is of the same type and kind as @var{X}.
1633 If @var{Y} is present, the result is identical to @code{ATAND2(Y,X)}.
1634 Otherwise, it is the arcus tangent of @var{X}, where the real part of
1635 the result is in degrees and lies in the range
1636 @math{-90 \leq \Re \atand(x) \leq 90}.
1638 @item @emph{Example}:
1641 real(8) :: x = 2.866_8
1643 end program test_atand
1646 @item @emph{Specific names}:
1647 @multitable @columnfractions .20 .20 .20 .25
1648 @item Name @tab Argument @tab Return type @tab Standard
1649 @item @code{ATAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
1650 @item @code{DATAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
1653 @item @emph{See also}:
1654 Inverse function: @ref{TAND}
1655 Radians function: @ref{ATAN}
1662 @section @code{ATAN2} --- Arctangent function
1665 @cindex trigonometric function, tangent, inverse
1666 @cindex tangent, inverse
1669 @item @emph{Description}:
1670 @code{ATAN2(Y, X)} computes the principal value of the argument
1671 function of the complex number @math{X + i Y}. This function can
1672 be used to transform from Cartesian into polar coordinates and
1673 allows to determine the angle in the correct quadrant.
1675 @item @emph{Standard}:
1676 Fortran 77 and later
1681 @item @emph{Syntax}:
1682 @code{RESULT = ATAN2(Y, X)}
1684 @item @emph{Arguments}:
1685 @multitable @columnfractions .15 .70
1686 @item @var{Y} @tab The type shall be @code{REAL}.
1687 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1688 If @var{Y} is zero, then @var{X} must be nonzero.
1691 @item @emph{Return value}:
1692 The return value has the same type and kind type parameter as @var{Y}. It
1693 is the principal value of the complex number @math{X + i Y}. If @var{X}
1694 is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1695 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1696 the return value is zero if @var{X} is strictly positive, @math{\pi} if
1697 @var{X} is negative and @var{Y} is positive zero (or the processor does
1698 not handle signed zeros), and @math{-\pi} if @var{X} is negative and
1699 @var{Y} is negative zero. Finally, if @var{X} is zero, then the
1700 magnitude of the result is @math{\pi/2}.
1702 @item @emph{Example}:
1705 real(4) :: x = 1.e0_4, y = 0.5e0_4
1707 end program test_atan2
1710 @item @emph{Specific names}:
1711 @multitable @columnfractions .20 .20 .20 .25
1712 @item Name @tab Argument @tab Return type @tab Standard
1713 @item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1714 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1717 @item @emph{See also}:
1719 Degrees function: @ref{ATAN2D}
1726 @section @code{ATAN2D} --- Arctangent function, degrees
1729 @cindex trigonometric function, tangent, inverse, degrees
1730 @cindex tangent, inverse, degrees
1733 @item @emph{Description}:
1734 @code{ATAN2D(Y, X)} computes the principal value of the argument
1735 function of the complex number @math{X + i Y} in degrees. This function can
1736 be used to transform from Cartesian into polar coordinates and
1737 allows to determine the angle in the correct quadrant.
1739 This function is for compatibility only and should be avoided in favor of
1740 standard constructs wherever possible.
1742 @item @emph{Standard}:
1743 GNU Extension, enabled with @option{-fdec-math}.
1748 @item @emph{Syntax}:
1749 @code{RESULT = ATAN2D(Y, X)}
1751 @item @emph{Arguments}:
1752 @multitable @columnfractions .15 .70
1753 @item @var{Y} @tab The type shall be @code{REAL}.
1754 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1755 If @var{Y} is zero, then @var{X} must be nonzero.
1758 @item @emph{Return value}:
1759 The return value has the same type and kind type parameter as @var{Y}. It
1760 is the principal value of the complex number @math{X + i Y}. If @var{X}
1761 is nonzero, then it lies in the range @math{-180 \le \atan (x) \leq 180}.
1762 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1763 the return value is zero if @var{X} is strictly positive, @math{180} if
1764 @var{X} is negative and @var{Y} is positive zero (or the processor does
1765 not handle signed zeros), and @math{-180} if @var{X} is negative and
1766 @var{Y} is negative zero. Finally, if @var{X} is zero, then the
1767 magnitude of the result is @math{90}.
1769 @item @emph{Example}:
1772 real(4) :: x = 1.e0_4, y = 0.5e0_4
1774 end program test_atan2d
1777 @item @emph{Specific names}:
1778 @multitable @columnfractions .20 .20 .20 .25
1779 @item Name @tab Argument @tab Return type @tab Standard
1780 @item @code{ATAN2D(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab GNU Extension
1781 @item @code{DATAN2D(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab GNU Extension
1784 @item @emph{See also}:
1786 Radians function: @ref{ATAN2}
1793 @section @code{ATANH} --- Inverse hyperbolic tangent function
1796 @cindex area hyperbolic tangent
1797 @cindex inverse hyperbolic tangent
1798 @cindex hyperbolic function, tangent, inverse
1799 @cindex tangent, hyperbolic, inverse
1802 @item @emph{Description}:
1803 @code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
1805 @item @emph{Standard}:
1806 Fortran 2008 and later
1811 @item @emph{Syntax}:
1812 @code{RESULT = ATANH(X)}
1814 @item @emph{Arguments}:
1815 @multitable @columnfractions .15 .70
1816 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1819 @item @emph{Return value}:
1820 The return value has same type and kind as @var{X}. If @var{X} is
1821 complex, the imaginary part of the result is in radians and lies between
1822 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1824 @item @emph{Example}:
1827 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1828 WRITE (*,*) ATANH(x)
1832 @item @emph{Specific names}:
1833 @multitable @columnfractions .20 .20 .20 .25
1834 @item Name @tab Argument @tab Return type @tab Standard
1835 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1838 @item @emph{See also}:
1839 Inverse function: @ref{TANH}
1845 @section @code{ATOMIC_ADD} --- Atomic ADD operation
1847 @cindex Atomic subroutine, add
1850 @item @emph{Description}:
1851 @code{ATOMIC_ADD(ATOM, VALUE)} atomically adds the value of @var{VAR} to the
1852 variable @var{ATOM}. When @var{STAT} is present and the invokation was
1853 successful, it is assigned the value 0. If it is present and the invokation
1854 has failed, it is assigned a positive value; in particular, for a coindexed
1855 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1856 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1857 failed, the value @code{STAT_FAILED_IMAGE}.
1859 @item @emph{Standard}:
1865 @item @emph{Syntax}:
1866 @code{CALL ATOMIC_ADD (ATOM, VALUE [, STAT])}
1868 @item @emph{Arguments}:
1869 @multitable @columnfractions .15 .70
1870 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1871 type with @code{ATOMIC_INT_KIND} kind.
1872 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1873 is different, the value is converted to the kind of @var{ATOM}.
1874 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1877 @item @emph{Example}:
1881 integer(atomic_int_kind) :: atom[*]
1882 call atomic_add (atom[1], this_image())
1886 @item @emph{See also}:
1887 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_ADD}, @ref{ISO_FORTRAN_ENV},
1888 @ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
1895 @section @code{ATOMIC_AND} --- Atomic bitwise AND operation
1897 @cindex Atomic subroutine, AND
1900 @item @emph{Description}:
1901 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
1902 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
1903 and the invokation was successful, it is assigned the value 0. If it is present
1904 and the invokation has failed, it is assigned a positive value; in particular,
1905 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
1906 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
1907 image has failed, the value @code{STAT_FAILED_IMAGE}.
1909 @item @emph{Standard}:
1915 @item @emph{Syntax}:
1916 @code{CALL ATOMIC_AND (ATOM, VALUE [, STAT])}
1918 @item @emph{Arguments}:
1919 @multitable @columnfractions .15 .70
1920 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1921 type with @code{ATOMIC_INT_KIND} kind.
1922 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1923 is different, the value is converted to the kind of @var{ATOM}.
1924 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1927 @item @emph{Example}:
1931 integer(atomic_int_kind) :: atom[*]
1932 call atomic_and (atom[1], int(b'10100011101'))
1936 @item @emph{See also}:
1937 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_AND}, @ref{ISO_FORTRAN_ENV},
1938 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
1944 @section @code{ATOMIC_CAS} --- Atomic compare and swap
1945 @fnindex ATOMIC_DEFINE
1946 @cindex Atomic subroutine, compare and swap
1949 @item @emph{Description}:
1950 @code{ATOMIC_CAS} compares the variable @var{ATOM} with the value of
1951 @var{COMPARE}; if the value is the same, @var{ATOM} is set to the value
1952 of @var{NEW}. Additionally, @var{OLD} is set to the value of @var{ATOM}
1953 that was used for the comparison. When @var{STAT} is present and the invokation
1954 was successful, it is assigned the value 0. If it is present and the invokation
1955 has failed, it is assigned a positive value; in particular, for a coindexed
1956 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1957 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1958 failed, the value @code{STAT_FAILED_IMAGE}.
1960 @item @emph{Standard}:
1966 @item @emph{Syntax}:
1967 @code{CALL ATOMIC_CAS (ATOM, OLD, COMPARE, NEW [, STAT])}
1969 @item @emph{Arguments}:
1970 @multitable @columnfractions .15 .70
1971 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
1972 type with @code{ATOMIC_INT_KIND} kind or logical type with
1973 @code{ATOMIC_LOGICAL_KIND} kind.
1974 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1975 @item @var{COMPARE} @tab Scalar variable of the same type and kind as
1977 @item @var{NEW} @tab Scalar variable of the same type as @var{ATOM}. If kind
1978 is different, the value is converted to the kind of @var{ATOM}.
1979 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1982 @item @emph{Example}:
1986 logical(atomic_logical_kind) :: atom[*], prev
1987 call atomic_cas (atom[1], prev, .false., .true.))
1991 @item @emph{See also}:
1992 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_REF}, @ref{ISO_FORTRAN_ENV}
1998 @section @code{ATOMIC_DEFINE} --- Setting a variable atomically
1999 @fnindex ATOMIC_DEFINE
2000 @cindex Atomic subroutine, define
2003 @item @emph{Description}:
2004 @code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value
2005 @var{VALUE} atomically. When @var{STAT} is present and the invokation was
2006 successful, it is assigned the value 0. If it is present and the invokation
2007 has failed, it is assigned a positive value; in particular, for a coindexed
2008 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2009 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2010 failed, the value @code{STAT_FAILED_IMAGE}.
2012 @item @emph{Standard}:
2013 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
2018 @item @emph{Syntax}:
2019 @code{CALL ATOMIC_DEFINE (ATOM, VALUE [, STAT])}
2021 @item @emph{Arguments}:
2022 @multitable @columnfractions .15 .70
2023 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
2024 type with @code{ATOMIC_INT_KIND} kind or logical type with
2025 @code{ATOMIC_LOGICAL_KIND} kind.
2027 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2028 is different, the value is converted to the kind of @var{ATOM}.
2029 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2032 @item @emph{Example}:
2036 integer(atomic_int_kind) :: atom[*]
2037 call atomic_define (atom[1], this_image())
2041 @item @emph{See also}:
2042 @ref{ATOMIC_REF}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV},
2043 @ref{ATOMIC_ADD}, @ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
2048 @node ATOMIC_FETCH_ADD
2049 @section @code{ATOMIC_FETCH_ADD} --- Atomic ADD operation with prior fetch
2050 @fnindex ATOMIC_FETCH_ADD
2051 @cindex Atomic subroutine, ADD with fetch
2054 @item @emph{Description}:
2055 @code{ATOMIC_FETCH_ADD(ATOM, VALUE, OLD)} atomically stores the value of
2056 @var{ATOM} in @var{OLD} and adds the value of @var{VAR} to the
2057 variable @var{ATOM}. When @var{STAT} is present and the invokation was
2058 successful, it is assigned the value 0. If it is present and the invokation
2059 has failed, it is assigned a positive value; in particular, for a coindexed
2060 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2061 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2062 failed, the value @code{STAT_FAILED_IMAGE}.
2064 @item @emph{Standard}:
2070 @item @emph{Syntax}:
2071 @code{CALL ATOMIC_FETCH_ADD (ATOM, VALUE, old [, STAT])}
2073 @item @emph{Arguments}:
2074 @multitable @columnfractions .15 .70
2075 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2076 type with @code{ATOMIC_INT_KIND} kind.
2077 @code{ATOMIC_LOGICAL_KIND} kind.
2079 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2080 is different, the value is converted to the kind of @var{ATOM}.
2081 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2082 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2085 @item @emph{Example}:
2089 integer(atomic_int_kind) :: atom[*], old
2090 call atomic_add (atom[1], this_image(), old)
2094 @item @emph{See also}:
2095 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_ADD}, @ref{ISO_FORTRAN_ENV},
2096 @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR}
2101 @node ATOMIC_FETCH_AND
2102 @section @code{ATOMIC_FETCH_AND} --- Atomic bitwise AND operation with prior fetch
2103 @fnindex ATOMIC_FETCH_AND
2104 @cindex Atomic subroutine, AND with fetch
2107 @item @emph{Description}:
2108 @code{ATOMIC_AND(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2109 @var{OLD} and defines @var{ATOM} with the bitwise AND between the values of
2110 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was
2111 successful, it is assigned the value 0. If it is present and the invokation has
2112 failed, it is assigned a positive value; in particular, for a coindexed
2113 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2114 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2115 failed, the value @code{STAT_FAILED_IMAGE}.
2117 @item @emph{Standard}:
2123 @item @emph{Syntax}:
2124 @code{CALL ATOMIC_FETCH_AND (ATOM, VALUE, OLD [, STAT])}
2126 @item @emph{Arguments}:
2127 @multitable @columnfractions .15 .70
2128 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2129 type with @code{ATOMIC_INT_KIND} kind.
2130 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2131 is different, the value is converted to the kind of @var{ATOM}.
2132 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2133 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2136 @item @emph{Example}:
2140 integer(atomic_int_kind) :: atom[*], old
2141 call atomic_fetch_and (atom[1], int(b'10100011101'), old)
2145 @item @emph{See also}:
2146 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_AND}, @ref{ISO_FORTRAN_ENV},
2147 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR}
2152 @node ATOMIC_FETCH_OR
2153 @section @code{ATOMIC_FETCH_OR} --- Atomic bitwise OR operation with prior fetch
2154 @fnindex ATOMIC_FETCH_OR
2155 @cindex Atomic subroutine, OR with fetch
2158 @item @emph{Description}:
2159 @code{ATOMIC_OR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2160 @var{OLD} and defines @var{ATOM} with the bitwise OR between the values of
2161 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was
2162 successful, it is assigned the value 0. If it is present and the invokation has
2163 failed, it is assigned a positive value; in particular, for a coindexed
2164 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2165 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2166 failed, the value @code{STAT_FAILED_IMAGE}.
2168 @item @emph{Standard}:
2174 @item @emph{Syntax}:
2175 @code{CALL ATOMIC_FETCH_OR (ATOM, VALUE, OLD [, STAT])}
2177 @item @emph{Arguments}:
2178 @multitable @columnfractions .15 .70
2179 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2180 type with @code{ATOMIC_INT_KIND} kind.
2181 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2182 is different, the value is converted to the kind of @var{ATOM}.
2183 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2184 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2187 @item @emph{Example}:
2191 integer(atomic_int_kind) :: atom[*], old
2192 call atomic_fetch_or (atom[1], int(b'10100011101'), old)
2196 @item @emph{See also}:
2197 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_OR}, @ref{ISO_FORTRAN_ENV},
2198 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_XOR}
2203 @node ATOMIC_FETCH_XOR
2204 @section @code{ATOMIC_FETCH_XOR} --- Atomic bitwise XOR operation with prior fetch
2205 @fnindex ATOMIC_FETCH_XOR
2206 @cindex Atomic subroutine, XOR with fetch
2209 @item @emph{Description}:
2210 @code{ATOMIC_XOR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2211 @var{OLD} and defines @var{ATOM} with the bitwise XOR between the values of
2212 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was
2213 successful, it is assigned the value 0. If it is present and the invokation has
2214 failed, it is assigned a positive value; in particular, for a coindexed
2215 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2216 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2217 failed, the value @code{STAT_FAILED_IMAGE}.
2219 @item @emph{Standard}:
2225 @item @emph{Syntax}:
2226 @code{CALL ATOMIC_FETCH_XOR (ATOM, VALUE, OLD [, STAT])}
2228 @item @emph{Arguments}:
2229 @multitable @columnfractions .15 .70
2230 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2231 type with @code{ATOMIC_INT_KIND} kind.
2232 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2233 is different, the value is converted to the kind of @var{ATOM}.
2234 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2235 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2238 @item @emph{Example}:
2242 integer(atomic_int_kind) :: atom[*], old
2243 call atomic_fetch_xor (atom[1], int(b'10100011101'), old)
2247 @item @emph{See also}:
2248 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_XOR}, @ref{ISO_FORTRAN_ENV},
2249 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}
2255 @section @code{ATOMIC_OR} --- Atomic bitwise OR operation
2257 @cindex Atomic subroutine, OR
2260 @item @emph{Description}:
2261 @code{ATOMIC_OR(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
2262 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
2263 and the invokation was successful, it is assigned the value 0. If it is present
2264 and the invokation has failed, it is assigned a positive value; in particular,
2265 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
2266 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
2267 image has failed, the value @code{STAT_FAILED_IMAGE}.
2269 @item @emph{Standard}:
2275 @item @emph{Syntax}:
2276 @code{CALL ATOMIC_OR (ATOM, VALUE [, STAT])}
2278 @item @emph{Arguments}:
2279 @multitable @columnfractions .15 .70
2280 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2281 type with @code{ATOMIC_INT_KIND} kind.
2282 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2283 is different, the value is converted to the kind of @var{ATOM}.
2284 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2287 @item @emph{Example}:
2291 integer(atomic_int_kind) :: atom[*]
2292 call atomic_or (atom[1], int(b'10100011101'))
2296 @item @emph{See also}:
2297 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_OR}, @ref{ISO_FORTRAN_ENV},
2298 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
2304 @section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically
2306 @cindex Atomic subroutine, reference
2309 @item @emph{Description}:
2310 @code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the
2311 variable @var{ATOM} to @var{VALUE}. When @var{STAT} is present and the
2312 invokation was successful, it is assigned the value 0. If it is present and the
2313 invokation has failed, it is assigned a positive value; in particular, for a
2314 coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value
2315 of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image
2316 has failed, the value @code{STAT_FAILED_IMAGE}.
2319 @item @emph{Standard}:
2320 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
2325 @item @emph{Syntax}:
2326 @code{CALL ATOMIC_REF(VALUE, ATOM [, STAT])}
2328 @item @emph{Arguments}:
2329 @multitable @columnfractions .15 .70
2330 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2331 is different, the value is converted to the kind of @var{ATOM}.
2332 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
2333 type with @code{ATOMIC_INT_KIND} kind or logical type with
2334 @code{ATOMIC_LOGICAL_KIND} kind.
2335 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2338 @item @emph{Example}:
2342 logical(atomic_logical_kind) :: atom[*]
2344 call atomic_ref (atom, .false.)
2346 call atomic_ref (atom, val)
2353 @item @emph{See also}:
2354 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV},
2355 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR},
2356 @ref{ATOMIC_FETCH_XOR}
2361 @section @code{ATOMIC_XOR} --- Atomic bitwise OR operation
2363 @cindex Atomic subroutine, XOR
2366 @item @emph{Description}:
2367 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
2368 XOR between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
2369 and the invokation was successful, it is assigned the value 0. If it is present
2370 and the invokation has failed, it is assigned a positive value; in particular,
2371 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
2372 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
2373 image has failed, the value @code{STAT_FAILED_IMAGE}.
2375 @item @emph{Standard}:
2381 @item @emph{Syntax}:
2382 @code{CALL ATOMIC_XOR (ATOM, VALUE [, STAT])}
2384 @item @emph{Arguments}:
2385 @multitable @columnfractions .15 .70
2386 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2387 type with @code{ATOMIC_INT_KIND} kind.
2388 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2389 is different, the value is converted to the kind of @var{ATOM}.
2390 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2393 @item @emph{Example}:
2397 integer(atomic_int_kind) :: atom[*]
2398 call atomic_xor (atom[1], int(b'10100011101'))
2402 @item @emph{See also}:
2403 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_XOR}, @ref{ISO_FORTRAN_ENV},
2404 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
2409 @section @code{BACKTRACE} --- Show a backtrace
2414 @item @emph{Description}:
2415 @code{BACKTRACE} shows a backtrace at an arbitrary place in user code. Program
2416 execution continues normally afterwards. The backtrace information is printed
2417 to the unit corresponding to @code{ERROR_UNIT} in @code{ISO_FORTRAN_ENV}.
2419 @item @emph{Standard}:
2425 @item @emph{Syntax}:
2426 @code{CALL BACKTRACE}
2428 @item @emph{Arguments}:
2431 @item @emph{See also}:
2438 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
2442 @cindex Bessel function, first kind
2445 @item @emph{Description}:
2446 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
2447 order 0 of @var{X}. This function is available under the name
2448 @code{BESJ0} as a GNU extension.
2450 @item @emph{Standard}:
2451 Fortran 2008 and later
2456 @item @emph{Syntax}:
2457 @code{RESULT = BESSEL_J0(X)}
2459 @item @emph{Arguments}:
2460 @multitable @columnfractions .15 .70
2461 @item @var{X} @tab The type shall be @code{REAL}.
2464 @item @emph{Return value}:
2465 The return value is of type @code{REAL} and lies in the
2466 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
2469 @item @emph{Example}:
2472 real(8) :: x = 0.0_8
2474 end program test_besj0
2477 @item @emph{Specific names}:
2478 @multitable @columnfractions .20 .20 .20 .25
2479 @item Name @tab Argument @tab Return type @tab Standard
2480 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2487 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
2491 @cindex Bessel function, first kind
2494 @item @emph{Description}:
2495 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
2496 order 1 of @var{X}. This function is available under the name
2497 @code{BESJ1} as a GNU extension.
2499 @item @emph{Standard}:
2505 @item @emph{Syntax}:
2506 @code{RESULT = BESSEL_J1(X)}
2508 @item @emph{Arguments}:
2509 @multitable @columnfractions .15 .70
2510 @item @var{X} @tab The type shall be @code{REAL}.
2513 @item @emph{Return value}:
2514 The return value is of type @code{REAL} and lies in the
2515 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
2518 @item @emph{Example}:
2521 real(8) :: x = 1.0_8
2523 end program test_besj1
2526 @item @emph{Specific names}:
2527 @multitable @columnfractions .20 .20 .20 .25
2528 @item Name @tab Argument @tab Return type @tab Standard
2529 @item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2536 @section @code{BESSEL_JN} --- Bessel function of the first kind
2540 @cindex Bessel function, first kind
2543 @item @emph{Description}:
2544 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
2545 order @var{N} of @var{X}. This function is available under the name
2546 @code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays,
2547 their ranks and shapes shall conform.
2549 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
2550 of the first kind of the orders @var{N1} to @var{N2}.
2552 @item @emph{Standard}:
2553 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2556 Elemental function, except for the transformational function
2557 @code{BESSEL_JN(N1, N2, X)}
2559 @item @emph{Syntax}:
2560 @multitable @columnfractions .80
2561 @item @code{RESULT = BESSEL_JN(N, X)}
2562 @item @code{RESULT = BESSEL_JN(N1, N2, X)}
2565 @item @emph{Arguments}:
2566 @multitable @columnfractions .15 .70
2567 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
2568 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2569 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2570 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2571 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
2574 @item @emph{Return value}:
2575 The return value is a scalar of type @code{REAL}. It has the same
2579 The transformational function uses a recurrence algorithm which might,
2580 for some values of @var{X}, lead to different results than calls to
2581 the elemental function.
2583 @item @emph{Example}:
2586 real(8) :: x = 1.0_8
2588 end program test_besjn
2591 @item @emph{Specific names}:
2592 @multitable @columnfractions .20 .20 .20 .25
2593 @item Name @tab Argument @tab Return type @tab Standard
2594 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2595 @item @tab @code{REAL(8) X} @tab @tab
2602 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
2606 @cindex Bessel function, second kind
2609 @item @emph{Description}:
2610 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
2611 order 0 of @var{X}. This function is available under the name
2612 @code{BESY0} as a GNU extension.
2614 @item @emph{Standard}:
2615 Fortran 2008 and later
2620 @item @emph{Syntax}:
2621 @code{RESULT = BESSEL_Y0(X)}
2623 @item @emph{Arguments}:
2624 @multitable @columnfractions .15 .70
2625 @item @var{X} @tab The type shall be @code{REAL}.
2628 @item @emph{Return value}:
2629 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2631 @item @emph{Example}:
2634 real(8) :: x = 0.0_8
2636 end program test_besy0
2639 @item @emph{Specific names}:
2640 @multitable @columnfractions .20 .20 .20 .25
2641 @item Name @tab Argument @tab Return type @tab Standard
2642 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2649 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
2653 @cindex Bessel function, second kind
2656 @item @emph{Description}:
2657 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
2658 order 1 of @var{X}. This function is available under the name
2659 @code{BESY1} as a GNU extension.
2661 @item @emph{Standard}:
2662 Fortran 2008 and later
2667 @item @emph{Syntax}:
2668 @code{RESULT = BESSEL_Y1(X)}
2670 @item @emph{Arguments}:
2671 @multitable @columnfractions .15 .70
2672 @item @var{X} @tab The type shall be @code{REAL}.
2675 @item @emph{Return value}:
2676 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2678 @item @emph{Example}:
2681 real(8) :: x = 1.0_8
2683 end program test_besy1
2686 @item @emph{Specific names}:
2687 @multitable @columnfractions .20 .20 .20 .25
2688 @item Name @tab Argument @tab Return type @tab Standard
2689 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2696 @section @code{BESSEL_YN} --- Bessel function of the second kind
2700 @cindex Bessel function, second kind
2703 @item @emph{Description}:
2704 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
2705 order @var{N} of @var{X}. This function is available under the name
2706 @code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays,
2707 their ranks and shapes shall conform.
2709 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
2710 of the first kind of the orders @var{N1} to @var{N2}.
2712 @item @emph{Standard}:
2713 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2716 Elemental function, except for the transformational function
2717 @code{BESSEL_YN(N1, N2, X)}
2719 @item @emph{Syntax}:
2720 @multitable @columnfractions .80
2721 @item @code{RESULT = BESSEL_YN(N, X)}
2722 @item @code{RESULT = BESSEL_YN(N1, N2, X)}
2725 @item @emph{Arguments}:
2726 @multitable @columnfractions .15 .70
2727 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} .
2728 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2729 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2730 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2731 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
2734 @item @emph{Return value}:
2735 The return value is a scalar of type @code{REAL}. It has the same
2739 The transformational function uses a recurrence algorithm which might,
2740 for some values of @var{X}, lead to different results than calls to
2741 the elemental function.
2743 @item @emph{Example}:
2746 real(8) :: x = 1.0_8
2748 end program test_besyn
2751 @item @emph{Specific names}:
2752 @multitable @columnfractions .20 .20 .20 .25
2753 @item Name @tab Argument @tab Return type @tab Standard
2754 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2755 @item @tab @code{REAL(8) X} @tab @tab
2762 @section @code{BGE} --- Bitwise greater than or equal to
2764 @cindex bitwise comparison
2767 @item @emph{Description}:
2768 Determines whether an integral is a bitwise greater than or equal to
2771 @item @emph{Standard}:
2772 Fortran 2008 and later
2777 @item @emph{Syntax}:
2778 @code{RESULT = BGE(I, J)}
2780 @item @emph{Arguments}:
2781 @multitable @columnfractions .15 .70
2782 @item @var{I} @tab Shall be of @code{INTEGER} type.
2783 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2787 @item @emph{Return value}:
2788 The return value is of type @code{LOGICAL} and of the default kind.
2790 @item @emph{See also}:
2791 @ref{BGT}, @ref{BLE}, @ref{BLT}
2797 @section @code{BGT} --- Bitwise greater than
2799 @cindex bitwise comparison
2802 @item @emph{Description}:
2803 Determines whether an integral is a bitwise greater than another.
2805 @item @emph{Standard}:
2806 Fortran 2008 and later
2811 @item @emph{Syntax}:
2812 @code{RESULT = BGT(I, J)}
2814 @item @emph{Arguments}:
2815 @multitable @columnfractions .15 .70
2816 @item @var{I} @tab Shall be of @code{INTEGER} type.
2817 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2821 @item @emph{Return value}:
2822 The return value is of type @code{LOGICAL} and of the default kind.
2824 @item @emph{See also}:
2825 @ref{BGE}, @ref{BLE}, @ref{BLT}
2831 @section @code{BIT_SIZE} --- Bit size inquiry function
2833 @cindex bits, number of
2834 @cindex size of a variable, in bits
2837 @item @emph{Description}:
2838 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
2839 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
2840 independent of the actual value of @var{I}.
2842 @item @emph{Standard}:
2843 Fortran 95 and later
2848 @item @emph{Syntax}:
2849 @code{RESULT = BIT_SIZE(I)}
2851 @item @emph{Arguments}:
2852 @multitable @columnfractions .15 .70
2853 @item @var{I} @tab The type shall be @code{INTEGER}.
2856 @item @emph{Return value}:
2857 The return value is of type @code{INTEGER}
2859 @item @emph{Example}:
2861 program test_bit_size
2866 end program test_bit_size
2873 @section @code{BLE} --- Bitwise less than or equal to
2875 @cindex bitwise comparison
2878 @item @emph{Description}:
2879 Determines whether an integral is a bitwise less than or equal to
2882 @item @emph{Standard}:
2883 Fortran 2008 and later
2888 @item @emph{Syntax}:
2889 @code{RESULT = BLE(I, J)}
2891 @item @emph{Arguments}:
2892 @multitable @columnfractions .15 .70
2893 @item @var{I} @tab Shall be of @code{INTEGER} type.
2894 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2898 @item @emph{Return value}:
2899 The return value is of type @code{LOGICAL} and of the default kind.
2901 @item @emph{See also}:
2902 @ref{BGT}, @ref{BGE}, @ref{BLT}
2908 @section @code{BLT} --- Bitwise less than
2910 @cindex bitwise comparison
2913 @item @emph{Description}:
2914 Determines whether an integral is a bitwise less than another.
2916 @item @emph{Standard}:
2917 Fortran 2008 and later
2922 @item @emph{Syntax}:
2923 @code{RESULT = BLT(I, J)}
2925 @item @emph{Arguments}:
2926 @multitable @columnfractions .15 .70
2927 @item @var{I} @tab Shall be of @code{INTEGER} type.
2928 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2932 @item @emph{Return value}:
2933 The return value is of type @code{LOGICAL} and of the default kind.
2935 @item @emph{See also}:
2936 @ref{BGE}, @ref{BGT}, @ref{BLE}
2942 @section @code{BTEST} --- Bit test function
2948 @cindex bits, testing
2951 @item @emph{Description}:
2952 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
2953 in @var{I} is set. The counting of the bits starts at 0.
2955 @item @emph{Standard}:
2956 Fortran 95 and later, has overloads that are GNU extensions
2961 @item @emph{Syntax}:
2962 @code{RESULT = BTEST(I, POS)}
2964 @item @emph{Arguments}:
2965 @multitable @columnfractions .15 .70
2966 @item @var{I} @tab The type shall be @code{INTEGER}.
2967 @item @var{POS} @tab The type shall be @code{INTEGER}.
2970 @item @emph{Return value}:
2971 The return value is of type @code{LOGICAL}
2973 @item @emph{Example}:
2976 integer :: i = 32768 + 1024 + 64
2980 bool = btest(i, pos)
2983 end program test_btest
2986 @item @emph{Specific names}:
2987 @multitable @columnfractions .20 .20 .20 .25
2988 @item Name @tab Argument @tab Return type @tab Standard
2989 @item @code{BTEST(I,POS)} @tab @code{INTEGER I,POS} @tab @code{LOGICAL} @tab F95 and later
2990 @item @code{BBTEST(I,POS)} @tab @code{INTEGER(1) I,POS} @tab @code{LOGICAL(1)} @tab GNU extension
2991 @item @code{BITEST(I,POS)} @tab @code{INTEGER(2) I,POS} @tab @code{LOGICAL(2)} @tab GNU extension
2992 @item @code{BJTEST(I,POS)} @tab @code{INTEGER(4) I,POS} @tab @code{LOGICAL(4)} @tab GNU extension
2993 @item @code{BKTEST(I,POS)} @tab @code{INTEGER(8) I,POS} @tab @code{LOGICAL(8)} @tab GNU extension
2998 @section @code{C_ASSOCIATED} --- Status of a C pointer
2999 @fnindex C_ASSOCIATED
3000 @cindex association status, C pointer
3001 @cindex pointer, C association status
3004 @item @emph{Description}:
3005 @code{C_ASSOCIATED(c_ptr_1[, c_ptr_2])} determines the status of the C pointer
3006 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
3008 @item @emph{Standard}:
3009 Fortran 2003 and later
3014 @item @emph{Syntax}:
3015 @code{RESULT = C_ASSOCIATED(c_ptr_1[, c_ptr_2])}
3017 @item @emph{Arguments}:
3018 @multitable @columnfractions .15 .70
3019 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
3020 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
3023 @item @emph{Return value}:
3024 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
3025 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
3026 point to different addresses.
3028 @item @emph{Example}:
3030 subroutine association_test(a,b)
3031 use iso_c_binding, only: c_associated, c_loc, c_ptr
3035 if(c_associated(b, c_loc(a))) &
3036 stop 'b and a do not point to same target'
3037 end subroutine association_test
3040 @item @emph{See also}:
3041 @ref{C_LOC}, @ref{C_FUNLOC}
3046 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
3047 @fnindex C_F_POINTER
3048 @cindex pointer, convert C to Fortran
3051 @item @emph{Description}:
3052 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} assigns the target of the C pointer
3053 @var{CPTR} to the Fortran pointer @var{FPTR} and specifies its shape.
3055 @item @emph{Standard}:
3056 Fortran 2003 and later
3061 @item @emph{Syntax}:
3062 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
3064 @item @emph{Arguments}:
3065 @multitable @columnfractions .15 .70
3066 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
3068 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
3070 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
3071 with @code{INTENT(IN)}. It shall be present
3072 if and only if @var{fptr} is an array. The size
3073 must be equal to the rank of @var{fptr}.
3076 @item @emph{Example}:
3082 subroutine my_routine(p) bind(c,name='myC_func')
3084 type(c_ptr), intent(out) :: p
3088 real,pointer :: a(:)
3089 call my_routine(cptr)
3090 call c_f_pointer(cptr, a, [12])
3094 @item @emph{See also}:
3095 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
3099 @node C_F_PROCPOINTER
3100 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
3101 @fnindex C_F_PROCPOINTER
3102 @cindex pointer, C address of pointers
3105 @item @emph{Description}:
3106 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
3107 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
3109 @item @emph{Standard}:
3110 Fortran 2003 and later
3115 @item @emph{Syntax}:
3116 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
3118 @item @emph{Arguments}:
3119 @multitable @columnfractions .15 .70
3120 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
3122 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
3126 @item @emph{Example}:
3134 real(c_float), intent(in) :: a
3135 real(c_float) :: func
3139 function getIterFunc() bind(c,name="getIterFunc")
3141 type(c_funptr) :: getIterFunc
3144 type(c_funptr) :: cfunptr
3145 procedure(func), pointer :: myFunc
3146 cfunptr = getIterFunc()
3147 call c_f_procpointer(cfunptr, myFunc)
3151 @item @emph{See also}:
3152 @ref{C_LOC}, @ref{C_F_POINTER}
3157 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
3159 @cindex pointer, C address of procedures
3162 @item @emph{Description}:
3163 @code{C_FUNLOC(x)} determines the C address of the argument.
3165 @item @emph{Standard}:
3166 Fortran 2003 and later
3171 @item @emph{Syntax}:
3172 @code{RESULT = C_FUNLOC(x)}
3174 @item @emph{Arguments}:
3175 @multitable @columnfractions .15 .70
3176 @item @var{x} @tab Interoperable function or pointer to such function.
3179 @item @emph{Return value}:
3180 The return value is of type @code{C_FUNPTR} and contains the C address
3183 @item @emph{Example}:
3189 subroutine sub(a) bind(c)
3199 subroutine my_routine(p) bind(c,name='myC_func')
3201 type(c_funptr), intent(in) :: p
3204 call my_routine(c_funloc(sub))
3208 @item @emph{See also}:
3209 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
3214 @section @code{C_LOC} --- Obtain the C address of an object
3216 @cindex procedure pointer, convert C to Fortran
3219 @item @emph{Description}:
3220 @code{C_LOC(X)} determines the C address of the argument.
3222 @item @emph{Standard}:
3223 Fortran 2003 and later
3228 @item @emph{Syntax}:
3229 @code{RESULT = C_LOC(X)}
3231 @item @emph{Arguments}:
3232 @multitable @columnfractions .10 .75
3233 @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.
3237 @item @emph{Return value}:
3238 The return value is of type @code{C_PTR} and contains the C address
3241 @item @emph{Example}:
3243 subroutine association_test(a,b)
3244 use iso_c_binding, only: c_associated, c_loc, c_ptr
3248 if(c_associated(b, c_loc(a))) &
3249 stop 'b and a do not point to same target'
3250 end subroutine association_test
3253 @item @emph{See also}:
3254 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
3259 @section @code{C_SIZEOF} --- Size in bytes of an expression
3261 @cindex expression size
3262 @cindex size of an expression
3265 @item @emph{Description}:
3266 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
3267 expression @code{X} occupies.
3269 @item @emph{Standard}:
3273 Inquiry function of the module @code{ISO_C_BINDING}
3275 @item @emph{Syntax}:
3276 @code{N = C_SIZEOF(X)}
3278 @item @emph{Arguments}:
3279 @multitable @columnfractions .15 .70
3280 @item @var{X} @tab The argument shall be an interoperable data entity.
3283 @item @emph{Return value}:
3284 The return value is of type integer and of the system-dependent kind
3285 @code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the
3286 number of bytes occupied by the argument. If the argument has the
3287 @code{POINTER} attribute, the number of bytes of the storage area pointed
3288 to is returned. If the argument is of a derived type with @code{POINTER}
3289 or @code{ALLOCATABLE} components, the return value does not account for
3290 the sizes of the data pointed to by these components.
3292 @item @emph{Example}:
3296 real(c_float) :: r, s(5)
3297 print *, (c_sizeof(s)/c_sizeof(r) == 5)
3300 The example will print @code{.TRUE.} unless you are using a platform
3301 where default @code{REAL} variables are unusually padded.
3303 @item @emph{See also}:
3304 @ref{SIZEOF}, @ref{STORAGE_SIZE}
3309 @section @code{CEILING} --- Integer ceiling function
3312 @cindex rounding, ceiling
3315 @item @emph{Description}:
3316 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
3318 @item @emph{Standard}:
3319 Fortran 95 and later
3324 @item @emph{Syntax}:
3325 @code{RESULT = CEILING(A [, KIND])}
3327 @item @emph{Arguments}:
3328 @multitable @columnfractions .15 .70
3329 @item @var{A} @tab The type shall be @code{REAL}.
3330 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3331 expression indicating the kind parameter of the result.
3334 @item @emph{Return value}:
3335 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
3336 and a default-kind @code{INTEGER} otherwise.
3338 @item @emph{Example}:
3340 program test_ceiling
3343 print *, ceiling(x) ! returns 64
3344 print *, ceiling(y) ! returns -63
3345 end program test_ceiling
3348 @item @emph{See also}:
3349 @ref{FLOOR}, @ref{NINT}
3356 @section @code{CHAR} --- Character conversion function
3358 @cindex conversion, to character
3361 @item @emph{Description}:
3362 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
3364 @item @emph{Standard}:
3365 Fortran 77 and later
3370 @item @emph{Syntax}:
3371 @code{RESULT = CHAR(I [, KIND])}
3373 @item @emph{Arguments}:
3374 @multitable @columnfractions .15 .70
3375 @item @var{I} @tab The type shall be @code{INTEGER}.
3376 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3377 expression indicating the kind parameter of the result.
3380 @item @emph{Return value}:
3381 The return value is of type @code{CHARACTER(1)}
3383 @item @emph{Example}:
3389 print *, i, c ! returns 'J'
3390 end program test_char
3393 @item @emph{Specific names}:
3394 @multitable @columnfractions .20 .20 .20 .25
3395 @item Name @tab Argument @tab Return type @tab Standard
3396 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
3400 See @ref{ICHAR} for a discussion of converting between numerical values
3401 and formatted string representations.
3403 @item @emph{See also}:
3404 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
3411 @section @code{CHDIR} --- Change working directory
3413 @cindex system, working directory
3416 @item @emph{Description}:
3417 Change current working directory to a specified path.
3419 This intrinsic is provided in both subroutine and function forms; however,
3420 only one form can be used in any given program unit.
3422 @item @emph{Standard}:
3426 Subroutine, function
3428 @item @emph{Syntax}:
3429 @multitable @columnfractions .80
3430 @item @code{CALL CHDIR(NAME [, STATUS])}
3431 @item @code{STATUS = CHDIR(NAME)}
3434 @item @emph{Arguments}:
3435 @multitable @columnfractions .15 .70
3436 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
3437 kind and shall specify a valid path within the file system.
3438 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
3439 kind. Returns 0 on success, and a system specific and nonzero error code
3443 @item @emph{Example}:
3446 CHARACTER(len=255) :: path
3448 WRITE(*,*) TRIM(path)
3451 WRITE(*,*) TRIM(path)
3455 @item @emph{See also}:
3462 @section @code{CHMOD} --- Change access permissions of files
3464 @cindex file system, change access mode
3467 @item @emph{Description}:
3468 @code{CHMOD} changes the permissions of a file.
3470 This intrinsic is provided in both subroutine and function forms; however,
3471 only one form can be used in any given program unit.
3473 @item @emph{Standard}:
3477 Subroutine, function
3479 @item @emph{Syntax}:
3480 @multitable @columnfractions .80
3481 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
3482 @item @code{STATUS = CHMOD(NAME, MODE)}
3485 @item @emph{Arguments}:
3486 @multitable @columnfractions .15 .70
3488 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
3489 file name. Trailing blanks are ignored unless the character
3490 @code{achar(0)} is present, then all characters up to and excluding
3491 @code{achar(0)} are used as the file name.
3493 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
3494 file permission. @var{MODE} uses the same syntax as the @code{chmod} utility
3495 as defined by the POSIX standard. The argument shall either be a string of
3496 a nonnegative octal number or a symbolic mode.
3498 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
3499 @code{0} on success and nonzero otherwise.
3502 @item @emph{Return value}:
3503 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
3506 @item @emph{Example}:
3507 @code{CHMOD} as subroutine
3512 call chmod('test.dat','u+x',status)
3513 print *, 'Status: ', status
3514 end program chmod_test
3516 @code{CHMOD} as function:
3521 status = chmod('test.dat','u+x')
3522 print *, 'Status: ', status
3523 end program chmod_test
3531 @section @code{CMPLX} --- Complex conversion function
3533 @cindex complex numbers, conversion to
3534 @cindex conversion, to complex
3537 @item @emph{Description}:
3538 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
3539 the real component. If @var{Y} is present it is converted to the imaginary
3540 component. If @var{Y} is not present then the imaginary component is set to
3541 0.0. If @var{X} is complex then @var{Y} must not be present.
3543 @item @emph{Standard}:
3544 Fortran 77 and later
3549 @item @emph{Syntax}:
3550 @code{RESULT = CMPLX(X [, Y [, KIND]])}
3552 @item @emph{Arguments}:
3553 @multitable @columnfractions .15 .70
3554 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3556 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
3557 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
3558 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3559 expression indicating the kind parameter of the result.
3562 @item @emph{Return value}:
3563 The return value is of @code{COMPLEX} type, with a kind equal to
3564 @var{KIND} if it is specified. If @var{KIND} is not specified, the
3565 result is of the default @code{COMPLEX} kind, regardless of the kinds of
3566 @var{X} and @var{Y}.
3568 @item @emph{Example}:
3575 print *, z, cmplx(x)
3576 end program test_cmplx
3579 @item @emph{See also}:
3586 @section @code{CO_BROADCAST} --- Copy a value to all images the current set of images
3587 @fnindex CO_BROADCAST
3588 @cindex Collectives, value broadcasting
3591 @item @emph{Description}:
3592 @code{CO_BROADCAST} copies the value of argument @var{A} on the image with
3593 image index @code{SOURCE_IMAGE} to all images in the current team. @var{A}
3594 becomes defined as if by intrinsic assignment. If the execution was
3595 successful and @var{STAT} is present, it is assigned the value zero. If the
3596 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3597 @var{ERRMSG} gets assigned a value describing the occurred error.
3599 @item @emph{Standard}:
3600 Technical Specification (TS) 18508 or later
3603 Collective subroutine
3605 @item @emph{Syntax}:
3606 @code{CALL CO_BROADCAST(A, SOURCE_IMAGE [, STAT, ERRMSG])}
3608 @item @emph{Arguments}:
3609 @multitable @columnfractions .15 .70
3610 @item @var{A} @tab INTENT(INOUT) argument; shall have the same
3611 dynamic type and type paramters on all images of the current team. If it
3612 is an array, it shall have the same shape on all images.
3613 @item @var{SOURCE_IMAGE} @tab a scalar integer expression.
3614 It shall have the same the same value on all images and refer to an
3615 image of the current team.
3616 @item @var{STAT} @tab (optional) a scalar integer variable
3617 @item @var{ERRMSG} @tab (optional) a scalar character variable
3620 @item @emph{Example}:
3624 if (this_image() == 1) then
3627 call co_broadcast (val, source_image=1)
3628 print *, this_image, ":", val
3632 @item @emph{See also}:
3633 @ref{CO_MAX}, @ref{CO_MIN}, @ref{CO_SUM}, @ref{CO_REDUCE}
3639 @section @code{CO_MAX} --- Maximal value on the current set of images
3641 @cindex Collectives, maximal value
3644 @item @emph{Description}:
3645 @code{CO_MAX} determines element-wise the maximal value of @var{A} on all
3646 images of the current team. If @var{RESULT_IMAGE} is present, the maximum
3647 values are returned in @var{A} on the specified image only and the value
3648 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3649 not present, the value is returned on all images. If the execution was
3650 successful and @var{STAT} is present, it is assigned the value zero. If the
3651 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3652 @var{ERRMSG} gets assigned a value describing the occurred error.
3654 @item @emph{Standard}:
3655 Technical Specification (TS) 18508 or later
3658 Collective subroutine
3660 @item @emph{Syntax}:
3661 @code{CALL CO_MAX(A [, RESULT_IMAGE, STAT, ERRMSG])}
3663 @item @emph{Arguments}:
3664 @multitable @columnfractions .15 .70
3665 @item @var{A} @tab shall be an integer, real or character variable,
3666 which has the same type and type parameters on all images of the team.
3667 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3668 present, it shall have the same the same value on all images and refer to an
3669 image of the current team.
3670 @item @var{STAT} @tab (optional) a scalar integer variable
3671 @item @var{ERRMSG} @tab (optional) a scalar character variable
3674 @item @emph{Example}:
3679 call co_max (val, result_image=1)
3680 if (this_image() == 1) then
3681 write(*,*) "Maximal value", val ! prints num_images()
3686 @item @emph{See also}:
3687 @ref{CO_MIN}, @ref{CO_SUM}, @ref{CO_REDUCE}, @ref{CO_BROADCAST}
3693 @section @code{CO_MIN} --- Minimal value on the current set of images
3695 @cindex Collectives, minimal value
3698 @item @emph{Description}:
3699 @code{CO_MIN} determines element-wise the minimal value of @var{A} on all
3700 images of the current team. If @var{RESULT_IMAGE} is present, the minimal
3701 values are returned in @var{A} on the specified image only and the value
3702 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3703 not present, the value is returned on all images. If the execution was
3704 successful and @var{STAT} is present, it is assigned the value zero. If the
3705 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3706 @var{ERRMSG} gets assigned a value describing the occurred error.
3708 @item @emph{Standard}:
3709 Technical Specification (TS) 18508 or later
3712 Collective subroutine
3714 @item @emph{Syntax}:
3715 @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3717 @item @emph{Arguments}:
3718 @multitable @columnfractions .15 .70
3719 @item @var{A} @tab shall be an integer, real or character variable,
3720 which has the same type and type parameters on all images of the team.
3721 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3722 present, it shall have the same the same value on all images and refer to an
3723 image of the current team.
3724 @item @var{STAT} @tab (optional) a scalar integer variable
3725 @item @var{ERRMSG} @tab (optional) a scalar character variable
3728 @item @emph{Example}:
3733 call co_min (val, result_image=1)
3734 if (this_image() == 1) then
3735 write(*,*) "Minimal value", val ! prints 1
3740 @item @emph{See also}:
3741 @ref{CO_MAX}, @ref{CO_SUM}, @ref{CO_REDUCE}, @ref{CO_BROADCAST}
3747 @section @code{CO_REDUCE} --- Reduction of values on the current set of images
3749 @cindex Collectives, generic reduction
3752 @item @emph{Description}:
3753 @code{CO_REDUCE} determines element-wise the reduction of the value of @var{A}
3754 on all images of the current team. The pure function passed as @var{OPERATOR}
3755 is used to pairwise reduce the values of @var{A} by passing either the value
3756 of @var{A} of different images or the result values of such a reduction as
3757 argument. If @var{A} is an array, the deduction is done element wise. If
3758 @var{RESULT_IMAGE} is present, the result values are returned in @var{A} on
3759 the specified image only and the value of @var{A} on the other images become
3760 undefined. If @var{RESULT_IMAGE} is not present, the value is returned on all
3761 images. If the execution was successful and @var{STAT} is present, it is
3762 assigned the value zero. If the execution failed, @var{STAT} gets assigned
3763 a nonzero value and, if present, @var{ERRMSG} gets assigned a value describing
3766 @item @emph{Standard}:
3767 Technical Specification (TS) 18508 or later
3770 Collective subroutine
3772 @item @emph{Syntax}:
3773 @code{CALL CO_REDUCE(A, OPERATOR, [, RESULT_IMAGE, STAT, ERRMSG])}
3775 @item @emph{Arguments}:
3776 @multitable @columnfractions .15 .70
3777 @item @var{A} @tab is an @code{INTENT(INOUT)} argument and shall be
3778 nonpolymorphic. If it is allocatable, it shall be allocated; if it is a pointer,
3779 it shall be associated. @var{A} shall have the same type and type parameters on
3780 all images of the team; if it is an array, it shall have the same shape on all
3782 @item @var{OPERATOR} @tab pure function with two scalar nonallocatable
3783 arguments, which shall be nonpolymorphic and have the same type and type
3784 parameters as @var{A}. The function shall return a nonallocatable scalar of
3785 the same type and type parameters as @var{A}. The function shall be the same on
3786 all images and with regards to the arguments mathematically commutative and
3787 associative. Note that @var{OPERATOR} may not be an elemental function, unless
3788 it is an intrisic function.
3789 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3790 present, it shall have the same the same value on all images and refer to an
3791 image of the current team.
3792 @item @var{STAT} @tab (optional) a scalar integer variable
3793 @item @var{ERRMSG} @tab (optional) a scalar character variable
3796 @item @emph{Example}:
3801 call co_reduce (val, result_image=1, operator=myprod)
3802 if (this_image() == 1) then
3803 write(*,*) "Product value", val ! prints num_images() factorial
3806 pure function myprod(a, b)
3807 integer, value :: a, b
3815 While the rules permit in principle an intrinsic function, none of the
3816 intrinsics in the standard fulfill the criteria of having a specific
3817 function, which takes two arguments of the same type and returning that
3820 @item @emph{See also}:
3821 @ref{CO_MIN}, @ref{CO_MAX}, @ref{CO_SUM}, @ref{CO_BROADCAST}
3827 @section @code{CO_SUM} --- Sum of values on the current set of images
3829 @cindex Collectives, sum of values
3832 @item @emph{Description}:
3833 @code{CO_SUM} sums up the values of each element of @var{A} on all
3834 images of the current team. If @var{RESULT_IMAGE} is present, the summed-up
3835 values are returned in @var{A} on the specified image only and the value
3836 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3837 not present, the value is returned on all images. If the execution was
3838 successful and @var{STAT} is present, it is assigned the value zero. If the
3839 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3840 @var{ERRMSG} gets assigned a value describing the occurred error.
3842 @item @emph{Standard}:
3843 Technical Specification (TS) 18508 or later
3846 Collective subroutine
3848 @item @emph{Syntax}:
3849 @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3851 @item @emph{Arguments}:
3852 @multitable @columnfractions .15 .70
3853 @item @var{A} @tab shall be an integer, real or complex variable,
3854 which has the same type and type parameters on all images of the team.
3855 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3856 present, it shall have the same the same value on all images and refer to an
3857 image of the current team.
3858 @item @var{STAT} @tab (optional) a scalar integer variable
3859 @item @var{ERRMSG} @tab (optional) a scalar character variable
3862 @item @emph{Example}:
3867 call co_sum (val, result_image=1)
3868 if (this_image() == 1) then
3869 write(*,*) "The sum is ", val ! prints (n**2 + n)/2, with n = num_images()
3874 @item @emph{See also}:
3875 @ref{CO_MAX}, @ref{CO_MIN}, @ref{CO_REDUCE}, @ref{CO_BROADCAST}
3880 @node COMMAND_ARGUMENT_COUNT
3881 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
3882 @fnindex COMMAND_ARGUMENT_COUNT
3883 @cindex command-line arguments
3884 @cindex command-line arguments, number of
3885 @cindex arguments, to program
3888 @item @emph{Description}:
3889 @code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the
3890 command line when the containing program was invoked.
3892 @item @emph{Standard}:
3893 Fortran 2003 and later
3898 @item @emph{Syntax}:
3899 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
3901 @item @emph{Arguments}:
3902 @multitable @columnfractions .15 .70
3906 @item @emph{Return value}:
3907 The return value is an @code{INTEGER} of default kind.
3909 @item @emph{Example}:
3911 program test_command_argument_count
3913 count = command_argument_count()
3915 end program test_command_argument_count
3918 @item @emph{See also}:
3919 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
3924 @node COMPILER_OPTIONS
3925 @section @code{COMPILER_OPTIONS} --- Options passed to the compiler
3926 @fnindex COMPILER_OPTIONS
3927 @cindex flags inquiry function
3928 @cindex options inquiry function
3929 @cindex compiler flags inquiry function
3932 @item @emph{Description}:
3933 @code{COMPILER_OPTIONS} returns a string with the options used for
3936 @item @emph{Standard}:
3940 Inquiry function of the module @code{ISO_FORTRAN_ENV}
3942 @item @emph{Syntax}:
3943 @code{STR = COMPILER_OPTIONS()}
3945 @item @emph{Arguments}:
3948 @item @emph{Return value}:
3949 The return value is a default-kind string with system-dependent length.
3950 It contains the compiler flags used to compile the file, which called
3951 the @code{COMPILER_OPTIONS} intrinsic.
3953 @item @emph{Example}:
3956 print '(4a)', 'This file was compiled by ', &
3957 compiler_version(), ' using the options ', &
3962 @item @emph{See also}:
3963 @ref{COMPILER_VERSION}, @ref{ISO_FORTRAN_ENV}
3968 @node COMPILER_VERSION
3969 @section @code{COMPILER_VERSION} --- Compiler version string
3970 @fnindex COMPILER_VERSION
3971 @cindex compiler, name and version
3972 @cindex version of the compiler
3975 @item @emph{Description}:
3976 @code{COMPILER_VERSION} returns a string with the name and the
3977 version of the compiler.
3979 @item @emph{Standard}:
3983 Inquiry function of the module @code{ISO_FORTRAN_ENV}
3985 @item @emph{Syntax}:
3986 @code{STR = COMPILER_VERSION()}
3988 @item @emph{Arguments}:
3991 @item @emph{Return value}:
3992 The return value is a default-kind string with system-dependent length.
3993 It contains the name of the compiler and its version number.
3995 @item @emph{Example}:
3998 print '(4a)', 'This file was compiled by ', &
3999 compiler_version(), ' using the options ', &
4004 @item @emph{See also}:
4005 @ref{COMPILER_OPTIONS}, @ref{ISO_FORTRAN_ENV}
4011 @section @code{COMPLEX} --- Complex conversion function
4013 @cindex complex numbers, conversion to
4014 @cindex conversion, to complex
4017 @item @emph{Description}:
4018 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
4019 to the real component and @var{Y} is converted to the imaginary
4022 @item @emph{Standard}:
4028 @item @emph{Syntax}:
4029 @code{RESULT = COMPLEX(X, Y)}
4031 @item @emph{Arguments}:
4032 @multitable @columnfractions .15 .70
4033 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
4034 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
4037 @item @emph{Return value}:
4038 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
4039 value is of default @code{COMPLEX} type.
4041 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
4042 type and one is of @code{INTEGER} type, then the return value is of
4043 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
4044 argument with the highest precision.
4046 @item @emph{Example}:
4048 program test_complex
4051 print *, complex(i, x)
4052 end program test_complex
4055 @item @emph{See also}:
4062 @section @code{CONJG} --- Complex conjugate function
4065 @cindex complex conjugate
4068 @item @emph{Description}:
4069 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
4070 then the result is @code{(x, -y)}
4072 @item @emph{Standard}:
4073 Fortran 77 and later, has overloads that are GNU extensions
4078 @item @emph{Syntax}:
4081 @item @emph{Arguments}:
4082 @multitable @columnfractions .15 .70
4083 @item @var{Z} @tab The type shall be @code{COMPLEX}.
4086 @item @emph{Return value}:
4087 The return value is of type @code{COMPLEX}.
4089 @item @emph{Example}:
4092 complex :: z = (2.0, 3.0)
4093 complex(8) :: dz = (2.71_8, -3.14_8)
4098 end program test_conjg
4101 @item @emph{Specific names}:
4102 @multitable @columnfractions .20 .20 .20 .25
4103 @item Name @tab Argument @tab Return type @tab Standard
4104 @item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension
4105 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
4112 @section @code{COS} --- Cosine function
4118 @cindex trigonometric function, cosine
4122 @item @emph{Description}:
4123 @code{COS(X)} computes the cosine of @var{X}.
4125 @item @emph{Standard}:
4126 Fortran 77 and later, has overloads that are GNU extensions
4131 @item @emph{Syntax}:
4132 @code{RESULT = COS(X)}
4134 @item @emph{Arguments}:
4135 @multitable @columnfractions .15 .70
4136 @item @var{X} @tab The type shall be @code{REAL} or
4140 @item @emph{Return value}:
4141 The return value is of the same type and kind as @var{X}. The real part
4142 of the result is in radians. If @var{X} is of the type @code{REAL},
4143 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
4145 @item @emph{Example}:
4150 end program test_cos
4153 @item @emph{Specific names}:
4154 @multitable @columnfractions .20 .20 .20 .25
4155 @item Name @tab Argument @tab Return type @tab Standard
4156 @item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
4157 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
4158 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
4159 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4160 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4163 @item @emph{See also}:
4164 Inverse function: @ref{ACOS}
4165 Degrees function: @ref{COSD}
4172 @section @code{COSD} --- Cosine function, degrees
4178 @cindex trigonometric function, cosine, degrees
4179 @cindex cosine, degrees
4182 @item @emph{Description}:
4183 @code{COSD(X)} computes the cosine of @var{X} in degrees.
4185 This function is for compatibility only and should be avoided in favor of
4186 standard constructs wherever possible.
4188 @item @emph{Standard}:
4189 GNU Extension, enabled with @option{-fdec-math}.
4194 @item @emph{Syntax}:
4195 @code{RESULT = COSD(X)}
4197 @item @emph{Arguments}:
4198 @multitable @columnfractions .15 .70
4199 @item @var{X} @tab The type shall be @code{REAL} or
4203 @item @emph{Return value}:
4204 The return value is of the same type and kind as @var{X}. The real part
4205 of the result is in degrees. If @var{X} is of the type @code{REAL},
4206 the return value lies in the range @math{ -1 \leq \cosd (x) \leq 1}.
4208 @item @emph{Example}:
4213 end program test_cosd
4216 @item @emph{Specific names}:
4217 @multitable @columnfractions .20 .20 .20 .25
4218 @item Name @tab Argument @tab Return type @tab Standard
4219 @item @code{COSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4220 @item @code{DCOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4221 @item @code{CCOSD(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU Extension
4222 @item @code{ZCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4223 @item @code{CDCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4226 @item @emph{See also}:
4227 Inverse function: @ref{ACOSD}
4228 Radians function: @ref{COS}
4235 @section @code{COSH} --- Hyperbolic cosine function
4238 @cindex hyperbolic cosine
4239 @cindex hyperbolic function, cosine
4240 @cindex cosine, hyperbolic
4243 @item @emph{Description}:
4244 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
4246 @item @emph{Standard}:
4247 Fortran 77 and later, for a complex argument Fortran 2008 or later
4252 @item @emph{Syntax}:
4255 @item @emph{Arguments}:
4256 @multitable @columnfractions .15 .70
4257 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4260 @item @emph{Return value}:
4261 The return value has same type and kind as @var{X}. If @var{X} is
4262 complex, the imaginary part of the result is in radians. If @var{X}
4263 is @code{REAL}, the return value has a lower bound of one,
4264 @math{\cosh (x) \geq 1}.
4266 @item @emph{Example}:
4269 real(8) :: x = 1.0_8
4271 end program test_cosh
4274 @item @emph{Specific names}:
4275 @multitable @columnfractions .20 .20 .20 .25
4276 @item Name @tab Argument @tab Return type @tab Standard
4277 @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
4278 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
4281 @item @emph{See also}:
4282 Inverse function: @ref{ACOSH}
4289 @section @code{COTAN} --- Cotangent function
4292 @cindex trigonometric function, cotangent
4296 @item @emph{Description}:
4297 @code{COTAN(X)} computes the cotangent of @var{X}. Equivalent to @code{COS(x)}
4298 divided by @code{SIN(x)}, or @code{1 / TAN(x)}.
4300 This function is for compatibility only and should be avoided in favor of
4301 standard constructs wherever possible.
4303 @item @emph{Standard}:
4304 GNU Extension, enabled with @option{-fdec-math}.
4309 @item @emph{Syntax}:
4310 @code{RESULT = COTAN(X)}
4312 @item @emph{Arguments}:
4313 @multitable @columnfractions .15 .70
4314 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4317 @item @emph{Return value}:
4318 The return value has same type and kind as @var{X}, and its value is in radians.
4320 @item @emph{Example}:
4323 real(8) :: x = 0.165_8
4325 end program test_cotan
4328 @item @emph{Specific names}:
4329 @multitable @columnfractions .20 .20 .20 .25
4330 @item Name @tab Argument @tab Return type @tab Standard
4331 @item @code{COTAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4332 @item @code{DCOTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4335 @item @emph{See also}:
4336 Converse function: @ref{TAN}
4337 Degrees function: @ref{COTAND}
4343 @section @code{COTAND} --- Cotangent function, degrees
4346 @cindex trigonometric function, cotangent, degrees
4347 @cindex cotangent, degrees
4350 @item @emph{Description}:
4351 @code{COTAND(X)} computes the cotangent of @var{X} in degrees. Equivalent to
4352 @code{COSD(x)} divided by @code{SIND(x)}, or @code{1 / TAND(x)}.
4354 @item @emph{Standard}:
4355 GNU Extension, enabled with @option{-fdec-math}.
4357 This function is for compatibility only and should be avoided in favor of
4358 standard constructs wherever possible.
4363 @item @emph{Syntax}:
4364 @code{RESULT = COTAND(X)}
4366 @item @emph{Arguments}:
4367 @multitable @columnfractions .15 .70
4368 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4371 @item @emph{Return value}:
4372 The return value has same type and kind as @var{X}, and its value is in degrees.
4374 @item @emph{Example}:
4377 real(8) :: x = 0.165_8
4379 end program test_cotand
4382 @item @emph{Specific names}:
4383 @multitable @columnfractions .20 .20 .20 .25
4384 @item Name @tab Argument @tab Return type @tab Standard
4385 @item @code{COTAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4386 @item @code{DCOTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4389 @item @emph{See also}:
4390 Converse function: @ref{TAND}
4391 Radians function: @ref{COTAN}
4398 @section @code{COUNT} --- Count function
4400 @cindex array, conditionally count elements
4401 @cindex array, element counting
4402 @cindex array, number of elements
4405 @item @emph{Description}:
4407 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
4408 or, if the @var{DIM} argument is supplied, counts the number of
4409 elements along each row of the array in the @var{DIM} direction.
4410 If the array has zero size, or all of the elements of @var{MASK} are
4411 @code{.FALSE.}, then the result is @code{0}.
4413 @item @emph{Standard}:
4414 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
4417 Transformational function
4419 @item @emph{Syntax}:
4420 @code{RESULT = COUNT(MASK [, DIM, KIND])}
4422 @item @emph{Arguments}:
4423 @multitable @columnfractions .15 .70
4424 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
4425 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
4426 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4427 expression indicating the kind parameter of the result.
4430 @item @emph{Return value}:
4431 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
4432 @var{KIND} is absent, the return value is of default integer kind.
4433 If @var{DIM} is present, the result is an array with a rank one less
4434 than the rank of @var{ARRAY}, and a size corresponding to the shape
4435 of @var{ARRAY} with the @var{DIM} dimension removed.
4437 @item @emph{Example}:
4440 integer, dimension(2,3) :: a, b
4441 logical, dimension(2,3) :: mask
4442 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
4443 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
4444 print '(3i3)', a(1,:)
4445 print '(3i3)', a(2,:)
4447 print '(3i3)', b(1,:)
4448 print '(3i3)', b(2,:)
4451 print '(3l3)', mask(1,:)
4452 print '(3l3)', mask(2,:)
4454 print '(3i3)', count(mask)
4456 print '(3i3)', count(mask, 1)
4458 print '(3i3)', count(mask, 2)
4459 end program test_count
4466 @section @code{CPU_TIME} --- CPU elapsed time in seconds
4468 @cindex time, elapsed
4471 @item @emph{Description}:
4472 Returns a @code{REAL} value representing the elapsed CPU time in
4473 seconds. This is useful for testing segments of code to determine
4476 If a time source is available, time will be reported with microsecond
4477 resolution. If no time source is available, @var{TIME} is set to
4480 Note that @var{TIME} may contain a, system dependent, arbitrary offset
4481 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
4482 value is meaningless, only differences between subsequent calls to
4483 this subroutine, as shown in the example below, should be used.
4486 @item @emph{Standard}:
4487 Fortran 95 and later
4492 @item @emph{Syntax}:
4493 @code{CALL CPU_TIME(TIME)}
4495 @item @emph{Arguments}:
4496 @multitable @columnfractions .15 .70
4497 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
4500 @item @emph{Return value}:
4503 @item @emph{Example}:
4505 program test_cpu_time
4506 real :: start, finish
4507 call cpu_time(start)
4508 ! put code to test here
4509 call cpu_time(finish)
4510 print '("Time = ",f6.3," seconds.")',finish-start
4511 end program test_cpu_time
4514 @item @emph{See also}:
4515 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
4521 @section @code{CSHIFT} --- Circular shift elements of an array
4523 @cindex array, shift circularly
4524 @cindex array, permutation
4525 @cindex array, rotate
4528 @item @emph{Description}:
4529 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
4530 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
4531 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
4532 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
4533 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
4534 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
4535 sections of @var{ARRAY} along the given dimension are shifted. Elements
4536 shifted out one end of each rank one section are shifted back in the other end.
4538 @item @emph{Standard}:
4539 Fortran 95 and later
4542 Transformational function
4544 @item @emph{Syntax}:
4545 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
4547 @item @emph{Arguments}:
4548 @multitable @columnfractions .15 .70
4549 @item @var{ARRAY} @tab Shall be an array of any type.
4550 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
4551 @item @var{DIM} @tab The type shall be @code{INTEGER}.
4554 @item @emph{Return value}:
4555 Returns an array of same type and rank as the @var{ARRAY} argument.
4557 @item @emph{Example}:
4560 integer, dimension(3,3) :: a
4561 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
4562 print '(3i3)', a(1,:)
4563 print '(3i3)', a(2,:)
4564 print '(3i3)', a(3,:)
4565 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
4567 print '(3i3)', a(1,:)
4568 print '(3i3)', a(2,:)
4569 print '(3i3)', a(3,:)
4570 end program test_cshift
4577 @section @code{CTIME} --- Convert a time into a string
4579 @cindex time, conversion to string
4580 @cindex conversion, to string
4583 @item @emph{Description}:
4584 @code{CTIME} converts a system time value, such as returned by
4585 @code{TIME8}, to a string. The output will be of the form @samp{Sat
4586 Aug 19 18:13:14 1995}.
4588 This intrinsic is provided in both subroutine and function forms; however,
4589 only one form can be used in any given program unit.
4591 @item @emph{Standard}:
4595 Subroutine, function
4597 @item @emph{Syntax}:
4598 @multitable @columnfractions .80
4599 @item @code{CALL CTIME(TIME, RESULT)}.
4600 @item @code{RESULT = CTIME(TIME)}.
4603 @item @emph{Arguments}:
4604 @multitable @columnfractions .15 .70
4605 @item @var{TIME} @tab The type shall be of type @code{INTEGER}.
4606 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
4607 of default kind. It is an @code{INTENT(OUT)} argument. If the length
4608 of this variable is too short for the time and date string to fit
4609 completely, it will be blank on procedure return.
4612 @item @emph{Return value}:
4613 The converted date and time as a string.
4615 @item @emph{Example}:
4619 character(len=30) :: date
4622 ! Do something, main part of the program
4625 print *, 'Program was started on ', date
4626 end program test_ctime
4629 @item @emph{See Also}:
4630 @ref{DATE_AND_TIME}, @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
4636 @section @code{DATE_AND_TIME} --- Date and time subroutine
4637 @fnindex DATE_AND_TIME
4638 @cindex date, current
4639 @cindex current date
4640 @cindex time, current
4641 @cindex current time
4644 @item @emph{Description}:
4645 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
4646 time information from the real-time system clock. @var{DATE} is
4647 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
4648 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
4649 representing the difference with respect to Coordinated Universal Time (UTC).
4650 Unavailable time and date parameters return blanks.
4652 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
4654 @multitable @columnfractions .15 .30 .40
4655 @item @tab @code{VALUE(1)}: @tab The year
4656 @item @tab @code{VALUE(2)}: @tab The month
4657 @item @tab @code{VALUE(3)}: @tab The day of the month
4658 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
4659 @item @tab @code{VALUE(5)}: @tab The hour of the day
4660 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
4661 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
4662 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
4665 @item @emph{Standard}:
4666 Fortran 95 and later
4671 @item @emph{Syntax}:
4672 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
4674 @item @emph{Arguments}:
4675 @multitable @columnfractions .15 .70
4676 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
4677 or larger, and of default kind.
4678 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
4679 or larger, and of default kind.
4680 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
4681 or larger, and of default kind.
4682 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
4685 @item @emph{Return value}:
4688 @item @emph{Example}:
4690 program test_time_and_date
4691 character(8) :: date
4692 character(10) :: time
4693 character(5) :: zone
4694 integer,dimension(8) :: values
4695 ! using keyword arguments
4696 call date_and_time(date,time,zone,values)
4697 call date_and_time(DATE=date,ZONE=zone)
4698 call date_and_time(TIME=time)
4699 call date_and_time(VALUES=values)
4700 print '(a,2x,a,2x,a)', date, time, zone
4701 print '(8i5)', values
4702 end program test_time_and_date
4705 @item @emph{See also}:
4706 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
4712 @section @code{DBLE} --- Double conversion function
4714 @cindex conversion, to real
4717 @item @emph{Description}:
4718 @code{DBLE(A)} Converts @var{A} to double precision real type.
4720 @item @emph{Standard}:
4721 Fortran 77 and later
4726 @item @emph{Syntax}:
4727 @code{RESULT = DBLE(A)}
4729 @item @emph{Arguments}:
4730 @multitable @columnfractions .15 .70
4731 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
4735 @item @emph{Return value}:
4736 The return value is of type double precision real.
4738 @item @emph{Example}:
4743 complex :: z = (2.3,1.14)
4744 print *, dble(x), dble(i), dble(z)
4745 end program test_dble
4748 @item @emph{See also}:
4755 @section @code{DCMPLX} --- Double complex conversion function
4757 @cindex complex numbers, conversion to
4758 @cindex conversion, to complex
4761 @item @emph{Description}:
4762 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
4763 converted to the real component. If @var{Y} is present it is converted to the
4764 imaginary component. If @var{Y} is not present then the imaginary component is
4765 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
4767 @item @emph{Standard}:
4773 @item @emph{Syntax}:
4774 @code{RESULT = DCMPLX(X [, Y])}
4776 @item @emph{Arguments}:
4777 @multitable @columnfractions .15 .70
4778 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
4780 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
4781 @code{INTEGER} or @code{REAL}.
4784 @item @emph{Return value}:
4785 The return value is of type @code{COMPLEX(8)}
4787 @item @emph{Example}:
4797 print *, dcmplx(x,i)
4798 end program test_dcmplx
4804 @section @code{DIGITS} --- Significant binary digits function
4806 @cindex model representation, significant digits
4809 @item @emph{Description}:
4810 @code{DIGITS(X)} returns the number of significant binary digits of the internal
4811 model representation of @var{X}. For example, on a system using a 32-bit
4812 floating point representation, a default real number would likely return 24.
4814 @item @emph{Standard}:
4815 Fortran 95 and later
4820 @item @emph{Syntax}:
4821 @code{RESULT = DIGITS(X)}
4823 @item @emph{Arguments}:
4824 @multitable @columnfractions .15 .70
4825 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
4828 @item @emph{Return value}:
4829 The return value is of type @code{INTEGER}.
4831 @item @emph{Example}:
4834 integer :: i = 12345
4840 end program test_digits
4847 @section @code{DIM} --- Positive difference
4851 @cindex positive difference
4854 @item @emph{Description}:
4855 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
4856 otherwise returns zero.
4858 @item @emph{Standard}:
4859 Fortran 77 and later
4864 @item @emph{Syntax}:
4865 @code{RESULT = DIM(X, Y)}
4867 @item @emph{Arguments}:
4868 @multitable @columnfractions .15 .70
4869 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
4870 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
4873 @item @emph{Return value}:
4874 The return value is of type @code{INTEGER} or @code{REAL}.
4876 @item @emph{Example}:
4882 x = dim(4.345_8, 2.111_8)
4885 end program test_dim
4888 @item @emph{Specific names}:
4889 @multitable @columnfractions .20 .20 .20 .25
4890 @item Name @tab Argument @tab Return type @tab Standard
4891 @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
4892 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
4893 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
4900 @section @code{DOT_PRODUCT} --- Dot product function
4901 @fnindex DOT_PRODUCT
4903 @cindex vector product
4904 @cindex product, vector
4907 @item @emph{Description}:
4908 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
4909 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
4910 either numeric or logical and must be arrays of rank one and of equal size. If
4911 the vectors are @code{INTEGER} or @code{REAL}, the result is
4912 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
4913 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
4914 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
4916 @item @emph{Standard}:
4917 Fortran 95 and later
4920 Transformational function
4922 @item @emph{Syntax}:
4923 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
4925 @item @emph{Arguments}:
4926 @multitable @columnfractions .15 .70
4927 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
4928 @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.
4931 @item @emph{Return value}:
4932 If the arguments are numeric, the return value is a scalar of numeric type,
4933 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
4934 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
4936 @item @emph{Example}:
4938 program test_dot_prod
4939 integer, dimension(3) :: a, b
4946 print *, dot_product(a,b)
4947 end program test_dot_prod
4954 @section @code{DPROD} --- Double product function
4956 @cindex product, double-precision
4959 @item @emph{Description}:
4960 @code{DPROD(X,Y)} returns the product @code{X*Y}.
4962 @item @emph{Standard}:
4963 Fortran 77 and later
4968 @item @emph{Syntax}:
4969 @code{RESULT = DPROD(X, Y)}
4971 @item @emph{Arguments}:
4972 @multitable @columnfractions .15 .70
4973 @item @var{X} @tab The type shall be @code{REAL}.
4974 @item @var{Y} @tab The type shall be @code{REAL}.
4977 @item @emph{Return value}:
4978 The return value is of type @code{REAL(8)}.
4980 @item @emph{Example}:
4988 end program test_dprod
4991 @item @emph{Specific names}:
4992 @multitable @columnfractions .20 .20 .20 .25
4993 @item Name @tab Argument @tab Return type @tab Standard
4994 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
5001 @section @code{DREAL} --- Double real part function
5003 @cindex complex numbers, real part
5006 @item @emph{Description}:
5007 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
5009 @item @emph{Standard}:
5015 @item @emph{Syntax}:
5016 @code{RESULT = DREAL(A)}
5018 @item @emph{Arguments}:
5019 @multitable @columnfractions .15 .70
5020 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
5023 @item @emph{Return value}:
5024 The return value is of type @code{REAL(8)}.
5026 @item @emph{Example}:
5029 complex(8) :: z = (1.3_8,7.2_8)
5031 end program test_dreal
5034 @item @emph{See also}:
5042 @section @code{DSHIFTL} --- Combined left shift
5044 @cindex left shift, combined
5048 @item @emph{Description}:
5049 @code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
5050 rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
5051 bits of @var{J}, and the remaining bits are the rightmost bits of
5054 @item @emph{Standard}:
5055 Fortran 2008 and later
5060 @item @emph{Syntax}:
5061 @code{RESULT = DSHIFTL(I, J, SHIFT)}
5063 @item @emph{Arguments}:
5064 @multitable @columnfractions .15 .70
5065 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5066 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5067 If both @var{I} and @var{J} have integer type, then they shall have
5068 the same kind type parameter. @var{I} and @var{J} shall not both be
5070 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
5071 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
5072 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
5073 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
5076 @item @emph{Return value}:
5077 If either @var{I} or @var{J} is a BOZ constant, it is first converted
5078 as if by the intrinsic function @code{INT} to an integer type with the
5079 kind type parameter of the other.
5081 @item @emph{See also}:
5087 @section @code{DSHIFTR} --- Combined right shift
5089 @cindex right shift, combined
5090 @cindex shift, right
5093 @item @emph{Description}:
5094 @code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
5095 leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
5096 bits of @var{I}, and the remaining bits are the leftmost bits of
5099 @item @emph{Standard}:
5100 Fortran 2008 and later
5105 @item @emph{Syntax}:
5106 @code{RESULT = DSHIFTR(I, J, SHIFT)}
5108 @item @emph{Arguments}:
5109 @multitable @columnfractions .15 .70
5110 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5111 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5112 If both @var{I} and @var{J} have integer type, then they shall have
5113 the same kind type parameter. @var{I} and @var{J} shall not both be
5115 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
5116 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
5117 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
5118 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
5121 @item @emph{Return value}:
5122 If either @var{I} or @var{J} is a BOZ constant, it is first converted
5123 as if by the intrinsic function @code{INT} to an integer type with the
5124 kind type parameter of the other.
5126 @item @emph{See also}:
5132 @section @code{DTIME} --- Execution time subroutine (or function)
5134 @cindex time, elapsed
5135 @cindex elapsed time
5138 @item @emph{Description}:
5139 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
5140 since the start of the process's execution in @var{TIME}. @var{VALUES}
5141 returns the user and system components of this time in @code{VALUES(1)} and
5142 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
5145 Subsequent invocations of @code{DTIME} return values accumulated since the
5146 previous invocation.
5148 On some systems, the underlying timings are represented using types with
5149 sufficiently small limits that overflows (wrap around) are possible, such as
5150 32-bit types. Therefore, the values returned by this intrinsic might be, or
5151 become, negative, or numerically less than previous values, during a single
5152 run of the compiled program.
5154 Please note, that this implementation is thread safe if used within OpenMP
5155 directives, i.e., its state will be consistent while called from multiple
5156 threads. However, if @code{DTIME} is called from multiple threads, the result
5157 is still the time since the last invocation. This may not give the intended
5158 results. If possible, use @code{CPU_TIME} instead.
5160 This intrinsic is provided in both subroutine and function forms; however,
5161 only one form can be used in any given program unit.
5163 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
5165 @multitable @columnfractions .15 .30 .40
5166 @item @tab @code{VALUES(1)}: @tab User time in seconds.
5167 @item @tab @code{VALUES(2)}: @tab System time in seconds.
5168 @item @tab @code{TIME}: @tab Run time since start in seconds.
5171 @item @emph{Standard}:
5175 Subroutine, function
5177 @item @emph{Syntax}:
5178 @multitable @columnfractions .80
5179 @item @code{CALL DTIME(VALUES, TIME)}.
5180 @item @code{TIME = DTIME(VALUES)}, (not recommended).
5183 @item @emph{Arguments}:
5184 @multitable @columnfractions .15 .70
5185 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
5186 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
5189 @item @emph{Return value}:
5190 Elapsed time in seconds since the last invocation or since the start of program
5191 execution if not called before.
5193 @item @emph{Example}:
5197 real, dimension(2) :: tarray
5199 call dtime(tarray, result)
5203 do i=1,100000000 ! Just a delay
5206 call dtime(tarray, result)
5210 end program test_dtime
5213 @item @emph{See also}:
5221 @section @code{EOSHIFT} --- End-off shift elements of an array
5223 @cindex array, shift
5226 @item @emph{Description}:
5227 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
5228 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
5229 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
5230 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
5231 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
5232 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
5233 then all complete rank one sections of @var{ARRAY} along the given dimension are
5234 shifted. Elements shifted out one end of each rank one section are dropped. If
5235 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
5236 is copied back in the other end. If @var{BOUNDARY} is not present then the
5237 following are copied in depending on the type of @var{ARRAY}.
5239 @multitable @columnfractions .15 .80
5240 @item @emph{Array Type} @tab @emph{Boundary Value}
5241 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
5242 @item Logical @tab @code{.FALSE.}.
5243 @item Character(@var{len}) @tab @var{len} blanks.
5246 @item @emph{Standard}:
5247 Fortran 95 and later
5250 Transformational function
5252 @item @emph{Syntax}:
5253 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
5255 @item @emph{Arguments}:
5256 @multitable @columnfractions .15 .70
5257 @item @var{ARRAY} @tab May be any type, not scalar.
5258 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
5259 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
5260 @item @var{DIM} @tab The type shall be @code{INTEGER}.
5263 @item @emph{Return value}:
5264 Returns an array of same type and rank as the @var{ARRAY} argument.
5266 @item @emph{Example}:
5268 program test_eoshift
5269 integer, dimension(3,3) :: a
5270 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
5271 print '(3i3)', a(1,:)
5272 print '(3i3)', a(2,:)
5273 print '(3i3)', a(3,:)
5274 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
5276 print '(3i3)', a(1,:)
5277 print '(3i3)', a(2,:)
5278 print '(3i3)', a(3,:)
5279 end program test_eoshift
5286 @section @code{EPSILON} --- Epsilon function
5288 @cindex model representation, epsilon
5291 @item @emph{Description}:
5292 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
5293 as @var{X} such that @math{1 + E > 1}.
5295 @item @emph{Standard}:
5296 Fortran 95 and later
5301 @item @emph{Syntax}:
5302 @code{RESULT = EPSILON(X)}
5304 @item @emph{Arguments}:
5305 @multitable @columnfractions .15 .70
5306 @item @var{X} @tab The type shall be @code{REAL}.
5309 @item @emph{Return value}:
5310 The return value is of same type as the argument.
5312 @item @emph{Example}:
5314 program test_epsilon
5319 end program test_epsilon
5326 @section @code{ERF} --- Error function
5328 @cindex error function
5331 @item @emph{Description}:
5332 @code{ERF(X)} computes the error function of @var{X}.
5334 @item @emph{Standard}:
5335 Fortran 2008 and later
5340 @item @emph{Syntax}:
5341 @code{RESULT = ERF(X)}
5343 @item @emph{Arguments}:
5344 @multitable @columnfractions .15 .70
5345 @item @var{X} @tab The type shall be @code{REAL}.
5348 @item @emph{Return value}:
5349 The return value is of type @code{REAL}, of the same kind as
5350 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
5352 @item @emph{Example}:
5355 real(8) :: x = 0.17_8
5357 end program test_erf
5360 @item @emph{Specific names}:
5361 @multitable @columnfractions .20 .20 .20 .25
5362 @item Name @tab Argument @tab Return type @tab Standard
5363 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
5370 @section @code{ERFC} --- Error function
5372 @cindex error function, complementary
5375 @item @emph{Description}:
5376 @code{ERFC(X)} computes the complementary error function of @var{X}.
5378 @item @emph{Standard}:
5379 Fortran 2008 and later
5384 @item @emph{Syntax}:
5385 @code{RESULT = ERFC(X)}
5387 @item @emph{Arguments}:
5388 @multitable @columnfractions .15 .70
5389 @item @var{X} @tab The type shall be @code{REAL}.
5392 @item @emph{Return value}:
5393 The return value is of type @code{REAL} and of the same kind as @var{X}.
5394 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
5396 @item @emph{Example}:
5399 real(8) :: x = 0.17_8
5401 end program test_erfc
5404 @item @emph{Specific names}:
5405 @multitable @columnfractions .20 .20 .20 .25
5406 @item Name @tab Argument @tab Return type @tab Standard
5407 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
5414 @section @code{ERFC_SCALED} --- Error function
5415 @fnindex ERFC_SCALED
5416 @cindex error function, complementary, exponentially-scaled
5419 @item @emph{Description}:
5420 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
5421 error function of @var{X}.
5423 @item @emph{Standard}:
5424 Fortran 2008 and later
5429 @item @emph{Syntax}:
5430 @code{RESULT = ERFC_SCALED(X)}
5432 @item @emph{Arguments}:
5433 @multitable @columnfractions .15 .70
5434 @item @var{X} @tab The type shall be @code{REAL}.
5437 @item @emph{Return value}:
5438 The return value is of type @code{REAL} and of the same kind as @var{X}.
5440 @item @emph{Example}:
5442 program test_erfc_scaled
5443 real(8) :: x = 0.17_8
5445 end program test_erfc_scaled
5452 @section @code{ETIME} --- Execution time subroutine (or function)
5454 @cindex time, elapsed
5457 @item @emph{Description}:
5458 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
5459 since the start of the process's execution in @var{TIME}. @var{VALUES}
5460 returns the user and system components of this time in @code{VALUES(1)} and
5461 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
5463 On some systems, the underlying timings are represented using types with
5464 sufficiently small limits that overflows (wrap around) are possible, such as
5465 32-bit types. Therefore, the values returned by this intrinsic might be, or
5466 become, negative, or numerically less than previous values, during a single
5467 run of the compiled program.
5469 This intrinsic is provided in both subroutine and function forms; however,
5470 only one form can be used in any given program unit.
5472 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
5474 @multitable @columnfractions .15 .30 .60
5475 @item @tab @code{VALUES(1)}: @tab User time in seconds.
5476 @item @tab @code{VALUES(2)}: @tab System time in seconds.
5477 @item @tab @code{TIME}: @tab Run time since start in seconds.
5480 @item @emph{Standard}:
5484 Subroutine, function
5486 @item @emph{Syntax}:
5487 @multitable @columnfractions .80
5488 @item @code{CALL ETIME(VALUES, TIME)}.
5489 @item @code{TIME = ETIME(VALUES)}, (not recommended).
5492 @item @emph{Arguments}:
5493 @multitable @columnfractions .15 .70
5494 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
5495 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
5498 @item @emph{Return value}:
5499 Elapsed time in seconds since the start of program execution.
5501 @item @emph{Example}:
5505 real, dimension(2) :: tarray
5507 call ETIME(tarray, result)
5511 do i=1,100000000 ! Just a delay
5514 call ETIME(tarray, result)
5518 end program test_etime
5521 @item @emph{See also}:
5529 @section @code{EVENT_QUERY} --- Query whether a coarray event has occurred
5530 @fnindex EVENT_QUERY
5531 @cindex Events, EVENT_QUERY
5534 @item @emph{Description}:
5535 @code{EVENT_QUERY} assignes the number of events to @var{COUNT} which have been
5536 posted to the @var{EVENT} variable and not yet been removed by calling
5537 @code{EVENT WAIT}. When @var{STAT} is present and the invokation was successful,
5538 it is assigned the value 0. If it is present and the invokation has failed,
5539 it is assigned a positive value and @var{COUNT} is assigned the value @math{-1}.
5541 @item @emph{Standard}:
5547 @item @emph{Syntax}:
5548 @code{CALL EVENT_QUERY (EVENT, COUNT [, STAT])}
5550 @item @emph{Arguments}:
5551 @multitable @columnfractions .15 .70
5552 @item @var{EVENT} @tab (intent(IN)) Scalar of type @code{EVENT_TYPE},
5553 defined in @code{ISO_FORTRAN_ENV}; shall not be coindexed.
5554 @item @var{COUNT} @tab (intent(out))Scalar integer with at least the
5555 precision of default integer.
5556 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
5559 @item @emph{Example}:
5564 type(event_type) :: event_value_has_been_set[*]
5566 if (this_image() == 1) then
5567 call event_query (event_value_has_been_set, cnt)
5568 if (cnt > 0) write(*,*) "Value has been set"
5569 elseif (this_image() == 2) then
5570 event post (event_value_has_been_set[1])
5579 @node EXECUTE_COMMAND_LINE
5580 @section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
5581 @fnindex EXECUTE_COMMAND_LINE
5582 @cindex system, system call
5583 @cindex command line
5586 @item @emph{Description}:
5587 @code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
5590 The @code{COMMAND} argument is passed to the shell and executed, using
5591 the C library's @code{system} call. (The shell is @code{sh} on Unix
5592 systems, and @code{cmd.exe} on Windows.) If @code{WAIT} is present
5593 and has the value false, the execution of the command is asynchronous
5594 if the system supports it; otherwise, the command is executed
5597 The three last arguments allow the user to get status information. After
5598 synchronous execution, @code{EXITSTAT} contains the integer exit code of
5599 the command, as returned by @code{system}. @code{CMDSTAT} is set to zero
5600 if the command line was executed (whatever its exit status was).
5601 @code{CMDMSG} is assigned an error message if an error has occurred.
5603 Note that the @code{system} function need not be thread-safe. It is
5604 the responsibility of the user to ensure that @code{system} is not
5605 called concurrently.
5607 @item @emph{Standard}:
5608 Fortran 2008 and later
5613 @item @emph{Syntax}:
5614 @code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
5616 @item @emph{Arguments}:
5617 @multitable @columnfractions .15 .70
5618 @item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
5619 @item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
5620 @item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5622 @item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5624 @item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
5628 @item @emph{Example}:
5633 call execute_command_line ("external_prog.exe", exitstat=i)
5634 print *, "Exit status of external_prog.exe was ", i
5636 call execute_command_line ("reindex_files.exe", wait=.false.)
5637 print *, "Now reindexing files in the background"
5639 end program test_exec
5645 Because this intrinsic is implemented in terms of the @code{system}
5646 function call, its behavior with respect to signaling is processor
5647 dependent. In particular, on POSIX-compliant systems, the SIGINT and
5648 SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
5649 such, if the parent process is terminated, the child process might not be
5650 terminated alongside.
5653 @item @emph{See also}:
5660 @section @code{EXIT} --- Exit the program with status.
5662 @cindex program termination
5663 @cindex terminate program
5666 @item @emph{Description}:
5667 @code{EXIT} causes immediate termination of the program with status. If status
5668 is omitted it returns the canonical @emph{success} for the system. All Fortran
5669 I/O units are closed.
5671 @item @emph{Standard}:
5677 @item @emph{Syntax}:
5678 @code{CALL EXIT([STATUS])}
5680 @item @emph{Arguments}:
5681 @multitable @columnfractions .15 .70
5682 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
5685 @item @emph{Return value}:
5686 @code{STATUS} is passed to the parent process on exit.
5688 @item @emph{Example}:
5691 integer :: STATUS = 0
5692 print *, 'This program is going to exit.'
5694 end program test_exit
5697 @item @emph{See also}:
5698 @ref{ABORT}, @ref{KILL}
5704 @section @code{EXP} --- Exponential function
5710 @cindex exponential function
5711 @cindex logarithm function, inverse
5714 @item @emph{Description}:
5715 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
5717 @item @emph{Standard}:
5718 Fortran 77 and later, has overloads that are GNU extensions
5723 @item @emph{Syntax}:
5724 @code{RESULT = EXP(X)}
5726 @item @emph{Arguments}:
5727 @multitable @columnfractions .15 .70
5728 @item @var{X} @tab The type shall be @code{REAL} or
5732 @item @emph{Return value}:
5733 The return value has same type and kind as @var{X}.
5735 @item @emph{Example}:
5740 end program test_exp
5743 @item @emph{Specific names}:
5744 @multitable @columnfractions .20 .20 .20 .25
5745 @item Name @tab Argument @tab Return type @tab Standard
5746 @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
5747 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
5748 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
5749 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5750 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5757 @section @code{EXPONENT} --- Exponent function
5759 @cindex real number, exponent
5760 @cindex floating point, exponent
5763 @item @emph{Description}:
5764 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
5765 is zero the value returned is zero.
5767 @item @emph{Standard}:
5768 Fortran 95 and later
5773 @item @emph{Syntax}:
5774 @code{RESULT = EXPONENT(X)}
5776 @item @emph{Arguments}:
5777 @multitable @columnfractions .15 .70
5778 @item @var{X} @tab The type shall be @code{REAL}.
5781 @item @emph{Return value}:
5782 The return value is of type default @code{INTEGER}.
5784 @item @emph{Example}:
5786 program test_exponent
5791 print *, exponent(0.0)
5792 end program test_exponent
5798 @node EXTENDS_TYPE_OF
5799 @section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension
5800 @fnindex EXTENDS_TYPE_OF
5803 @item @emph{Description}:
5804 Query dynamic type for extension.
5806 @item @emph{Standard}:
5807 Fortran 2003 and later
5812 @item @emph{Syntax}:
5813 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
5815 @item @emph{Arguments}:
5816 @multitable @columnfractions .15 .70
5817 @item @var{A} @tab Shall be an object of extensible declared type or
5818 unlimited polymorphic.
5819 @item @var{MOLD} @tab Shall be an object of extensible declared type or
5820 unlimited polymorphic.
5823 @item @emph{Return value}:
5824 The return value is a scalar of type default logical. It is true if and only if
5825 the dynamic type of A is an extension type of the dynamic type of MOLD.
5828 @item @emph{See also}:
5835 @section @code{FDATE} --- Get the current time as a string
5837 @cindex time, current
5838 @cindex current time
5839 @cindex date, current
5840 @cindex current date
5843 @item @emph{Description}:
5844 @code{FDATE(DATE)} returns the current date (using the same format as
5845 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
5848 This intrinsic is provided in both subroutine and function forms; however,
5849 only one form can be used in any given program unit.
5851 @item @emph{Standard}:
5855 Subroutine, function
5857 @item @emph{Syntax}:
5858 @multitable @columnfractions .80
5859 @item @code{CALL FDATE(DATE)}.
5860 @item @code{DATE = FDATE()}.
5863 @item @emph{Arguments}:
5864 @multitable @columnfractions .15 .70
5865 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
5866 default kind. It is an @code{INTENT(OUT)} argument. If the length of
5867 this variable is too short for the date and time string to fit
5868 completely, it will be blank on procedure return.
5871 @item @emph{Return value}:
5872 The current date and time as a string.
5874 @item @emph{Example}:
5878 character(len=30) :: date
5880 print *, 'Program started on ', date
5881 do i = 1, 100000000 ! Just a delay
5885 print *, 'Program ended on ', date
5886 end program test_fdate
5889 @item @emph{See also}:
5890 @ref{DATE_AND_TIME}, @ref{CTIME}
5895 @section @code{FGET} --- Read a single character in stream mode from stdin
5897 @cindex read character, stream mode
5898 @cindex stream mode, read character
5899 @cindex file operation, read character
5902 @item @emph{Description}:
5903 Read a single character in stream mode from stdin by bypassing normal
5904 formatted output. Stream I/O should not be mixed with normal record-oriented
5905 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
5907 This intrinsic is provided in both subroutine and function forms; however,
5908 only one form can be used in any given program unit.
5910 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
5911 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5912 Programmers should consider the use of new stream IO feature in new code
5913 for future portability. See also @ref{Fortran 2003 status}.
5915 @item @emph{Standard}:
5919 Subroutine, function
5921 @item @emph{Syntax}:
5922 @multitable @columnfractions .80
5923 @item @code{CALL FGET(C [, STATUS])}
5924 @item @code{STATUS = FGET(C)}
5927 @item @emph{Arguments}:
5928 @multitable @columnfractions .15 .70
5929 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5931 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5932 Returns 0 on success, -1 on end-of-file, and a system specific positive
5933 error code otherwise.
5936 @item @emph{Example}:
5939 INTEGER, PARAMETER :: strlen = 100
5940 INTEGER :: status, i = 1
5941 CHARACTER(len=strlen) :: str = ""
5943 WRITE (*,*) 'Enter text:'
5945 CALL fget(str(i:i), status)
5946 if (status /= 0 .OR. i > strlen) exit
5949 WRITE (*,*) TRIM(str)
5953 @item @emph{See also}:
5954 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
5960 @section @code{FGETC} --- Read a single character in stream mode
5962 @cindex read character, stream mode
5963 @cindex stream mode, read character
5964 @cindex file operation, read character
5967 @item @emph{Description}:
5968 Read a single character in stream mode by bypassing normal formatted output.
5969 Stream I/O should not be mixed with normal record-oriented (formatted or
5970 unformatted) I/O on the same unit; the results are unpredictable.
5972 This intrinsic is provided in both subroutine and function forms; however,
5973 only one form can be used in any given program unit.
5975 Note that the @code{FGET} intrinsic is provided for backwards compatibility
5976 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5977 Programmers should consider the use of new stream IO feature in new code
5978 for future portability. See also @ref{Fortran 2003 status}.
5980 @item @emph{Standard}:
5984 Subroutine, function
5986 @item @emph{Syntax}:
5987 @multitable @columnfractions .80
5988 @item @code{CALL FGETC(UNIT, C [, STATUS])}
5989 @item @code{STATUS = FGETC(UNIT, C)}
5992 @item @emph{Arguments}:
5993 @multitable @columnfractions .15 .70
5994 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
5995 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5997 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5998 Returns 0 on success, -1 on end-of-file and a system specific positive
5999 error code otherwise.
6002 @item @emph{Example}:
6005 INTEGER :: fd = 42, status
6008 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
6010 CALL fgetc(fd, c, status)
6011 IF (status /= 0) EXIT
6018 @item @emph{See also}:
6019 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
6025 @section @code{FLOOR} --- Integer floor function
6028 @cindex rounding, floor
6031 @item @emph{Description}:
6032 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
6034 @item @emph{Standard}:
6035 Fortran 95 and later
6040 @item @emph{Syntax}:
6041 @code{RESULT = FLOOR(A [, KIND])}
6043 @item @emph{Arguments}:
6044 @multitable @columnfractions .15 .70
6045 @item @var{A} @tab The type shall be @code{REAL}.
6046 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6047 expression indicating the kind parameter of the result.
6050 @item @emph{Return value}:
6051 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
6052 and of default-kind @code{INTEGER} otherwise.
6054 @item @emph{Example}:
6059 print *, floor(x) ! returns 63
6060 print *, floor(y) ! returns -64
6061 end program test_floor
6064 @item @emph{See also}:
6065 @ref{CEILING}, @ref{NINT}
6072 @section @code{FLUSH} --- Flush I/O unit(s)
6074 @cindex file operation, flush
6077 @item @emph{Description}:
6078 Flushes Fortran unit(s) currently open for output. Without the optional
6079 argument, all units are flushed, otherwise just the unit specified.
6081 @item @emph{Standard}:
6087 @item @emph{Syntax}:
6088 @code{CALL FLUSH(UNIT)}
6090 @item @emph{Arguments}:
6091 @multitable @columnfractions .15 .70
6092 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
6096 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
6097 statement that should be preferred over the @code{FLUSH} intrinsic.
6099 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
6100 have identical effect: they flush the runtime library's I/O buffer so
6101 that the data becomes visible to other processes. This does not guarantee
6102 that the data is committed to disk.
6104 On POSIX systems, you can request that all data is transferred to the
6105 storage device by calling the @code{fsync} function, with the POSIX file
6106 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
6107 @code{FNUM}). The following example shows how:
6110 ! Declare the interface for POSIX fsync function
6112 function fsync (fd) bind(c,name="fsync")
6113 use iso_c_binding, only: c_int
6114 integer(c_int), value :: fd
6115 integer(c_int) :: fsync
6119 ! Variable declaration
6123 open (10,file="foo")
6126 ! Perform I/O on unit 10
6131 ret = fsync(fnum(10))
6133 ! Handle possible error
6134 if (ret /= 0) stop "Error calling FSYNC"
6142 @section @code{FNUM} --- File number function
6144 @cindex file operation, file number
6147 @item @emph{Description}:
6148 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
6149 open Fortran I/O unit @code{UNIT}.
6151 @item @emph{Standard}:
6157 @item @emph{Syntax}:
6158 @code{RESULT = FNUM(UNIT)}
6160 @item @emph{Arguments}:
6161 @multitable @columnfractions .15 .70
6162 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
6165 @item @emph{Return value}:
6166 The return value is of type @code{INTEGER}
6168 @item @emph{Example}:
6172 open (unit=10, status = "scratch")
6176 end program test_fnum
6183 @section @code{FPUT} --- Write a single character in stream mode to stdout
6185 @cindex write character, stream mode
6186 @cindex stream mode, write character
6187 @cindex file operation, write character
6190 @item @emph{Description}:
6191 Write a single character in stream mode to stdout by bypassing normal
6192 formatted output. Stream I/O should not be mixed with normal record-oriented
6193 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
6195 This intrinsic is provided in both subroutine and function forms; however,
6196 only one form can be used in any given program unit.
6198 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
6199 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
6200 Programmers should consider the use of new stream IO feature in new code
6201 for future portability. See also @ref{Fortran 2003 status}.
6203 @item @emph{Standard}:
6207 Subroutine, function
6209 @item @emph{Syntax}:
6210 @multitable @columnfractions .80
6211 @item @code{CALL FPUT(C [, STATUS])}
6212 @item @code{STATUS = FPUT(C)}
6215 @item @emph{Arguments}:
6216 @multitable @columnfractions .15 .70
6217 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6219 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6220 Returns 0 on success, -1 on end-of-file and a system specific positive
6221 error code otherwise.
6224 @item @emph{Example}:
6227 CHARACTER(len=10) :: str = "gfortran"
6229 DO i = 1, len_trim(str)
6235 @item @emph{See also}:
6236 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
6242 @section @code{FPUTC} --- Write a single character in stream mode
6244 @cindex write character, stream mode
6245 @cindex stream mode, write character
6246 @cindex file operation, write character
6249 @item @emph{Description}:
6250 Write a single character in stream mode by bypassing normal formatted
6251 output. Stream I/O should not be mixed with normal record-oriented
6252 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
6254 This intrinsic is provided in both subroutine and function forms; however,
6255 only one form can be used in any given program unit.
6257 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
6258 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
6259 Programmers should consider the use of new stream IO feature in new code
6260 for future portability. See also @ref{Fortran 2003 status}.
6262 @item @emph{Standard}:
6266 Subroutine, function
6268 @item @emph{Syntax}:
6269 @multitable @columnfractions .80
6270 @item @code{CALL FPUTC(UNIT, C [, STATUS])}
6271 @item @code{STATUS = FPUTC(UNIT, C)}
6274 @item @emph{Arguments}:
6275 @multitable @columnfractions .15 .70
6276 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
6277 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6279 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6280 Returns 0 on success, -1 on end-of-file and a system specific positive
6281 error code otherwise.
6284 @item @emph{Example}:
6287 CHARACTER(len=10) :: str = "gfortran"
6288 INTEGER :: fd = 42, i
6290 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
6291 DO i = 1, len_trim(str)
6292 CALL fputc(fd, str(i:i))
6298 @item @emph{See also}:
6299 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
6305 @section @code{FRACTION} --- Fractional part of the model representation
6307 @cindex real number, fraction
6308 @cindex floating point, fraction
6311 @item @emph{Description}:
6312 @code{FRACTION(X)} returns the fractional part of the model
6313 representation of @code{X}.
6315 @item @emph{Standard}:
6316 Fortran 95 and later
6321 @item @emph{Syntax}:
6322 @code{Y = FRACTION(X)}
6324 @item @emph{Arguments}:
6325 @multitable @columnfractions .15 .70
6326 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
6329 @item @emph{Return value}:
6330 The return value is of the same type and kind as the argument.
6331 The fractional part of the model representation of @code{X} is returned;
6332 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
6334 @item @emph{Example}:
6336 program test_fraction
6339 print *, fraction(x), x * radix(x)**(-exponent(x))
6340 end program test_fraction
6348 @section @code{FREE} --- Frees memory
6350 @cindex pointer, cray
6353 @item @emph{Description}:
6354 Frees memory previously allocated by @code{MALLOC}. The @code{FREE}
6355 intrinsic is an extension intended to be used with Cray pointers, and is
6356 provided in GNU Fortran to allow user to compile legacy code. For
6357 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
6360 @item @emph{Standard}:
6366 @item @emph{Syntax}:
6367 @code{CALL FREE(PTR)}
6369 @item @emph{Arguments}:
6370 @multitable @columnfractions .15 .70
6371 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
6372 location of the memory that should be de-allocated.
6375 @item @emph{Return value}:
6378 @item @emph{Example}:
6379 See @code{MALLOC} for an example.
6381 @item @emph{See also}:
6388 @section @code{FSEEK} --- Low level file positioning subroutine
6390 @cindex file operation, seek
6391 @cindex file operation, position
6394 @item @emph{Description}:
6395 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
6396 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
6397 if set to 1, @var{OFFSET} is taken to be relative to the current position
6398 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
6399 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
6402 This intrinsic routine is not fully backwards compatible with @command{g77}.
6403 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
6404 @var{STATUS} variable. If FSEEK is used in old code, change
6406 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
6411 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
6412 IF (status /= 0) GOTO label
6415 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
6416 Programmers should consider the use of new stream IO feature in new code
6417 for future portability. See also @ref{Fortran 2003 status}.
6419 @item @emph{Standard}:
6425 @item @emph{Syntax}:
6426 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
6428 @item @emph{Arguments}:
6429 @multitable @columnfractions .15 .70
6430 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
6431 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
6432 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
6433 Its value shall be either 0, 1 or 2.
6434 @item @var{STATUS} @tab (Optional) shall be a scalar of type
6438 @item @emph{Example}:
6441 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
6442 INTEGER :: fd, offset, ierr
6448 OPEN(UNIT=fd, FILE="fseek.test")
6449 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
6450 print *, FTELL(fd), ierr
6452 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
6453 print *, FTELL(fd), ierr
6455 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
6456 print *, FTELL(fd), ierr
6462 @item @emph{See also}:
6469 @section @code{FSTAT} --- Get file status
6471 @cindex file system, file status
6474 @item @emph{Description}:
6475 @code{FSTAT} is identical to @ref{STAT}, except that information about an
6476 already opened file is obtained.
6478 The elements in @code{VALUES} are the same as described by @ref{STAT}.
6480 This intrinsic is provided in both subroutine and function forms; however,
6481 only one form can be used in any given program unit.
6483 @item @emph{Standard}:
6487 Subroutine, function
6489 @item @emph{Syntax}:
6490 @multitable @columnfractions .80
6491 @item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
6492 @item @code{STATUS = FSTAT(UNIT, VALUES)}
6495 @item @emph{Arguments}:
6496 @multitable @columnfractions .15 .70
6497 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
6498 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
6499 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
6500 on success and a system specific error code otherwise.
6503 @item @emph{Example}:
6504 See @ref{STAT} for an example.
6506 @item @emph{See also}:
6507 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
6513 @section @code{FTELL} --- Current stream position
6515 @cindex file operation, position
6518 @item @emph{Description}:
6519 Retrieves the current position within an open file.
6521 This intrinsic is provided in both subroutine and function forms; however,
6522 only one form can be used in any given program unit.
6524 @item @emph{Standard}:
6528 Subroutine, function
6530 @item @emph{Syntax}:
6531 @multitable @columnfractions .80
6532 @item @code{CALL FTELL(UNIT, OFFSET)}
6533 @item @code{OFFSET = FTELL(UNIT)}
6536 @item @emph{Arguments}:
6537 @multitable @columnfractions .15 .70
6538 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
6539 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
6542 @item @emph{Return value}:
6543 In either syntax, @var{OFFSET} is set to the current offset of unit
6544 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
6546 @item @emph{Example}:
6550 OPEN(10, FILE="temp.dat")
6556 @item @emph{See also}:
6563 @section @code{GAMMA} --- Gamma function
6566 @cindex Gamma function
6567 @cindex Factorial function
6570 @item @emph{Description}:
6571 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
6572 integer values of @var{X} the Gamma function simplifies to the factorial
6573 function @math{\Gamma(x)=(x-1)!}.
6577 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
6581 @item @emph{Standard}:
6582 Fortran 2008 and later
6587 @item @emph{Syntax}:
6590 @item @emph{Arguments}:
6591 @multitable @columnfractions .15 .70
6592 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
6593 nor a negative integer.
6596 @item @emph{Return value}:
6597 The return value is of type @code{REAL} of the same kind as @var{X}.
6599 @item @emph{Example}:
6603 x = gamma(x) ! returns 1.0
6604 end program test_gamma
6607 @item @emph{Specific names}:
6608 @multitable @columnfractions .20 .20 .20 .25
6609 @item Name @tab Argument @tab Return type @tab Standard
6610 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
6611 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
6614 @item @emph{See also}:
6615 Logarithm of the Gamma function: @ref{LOG_GAMMA}
6622 @section @code{GERROR} --- Get last system error message
6624 @cindex system, error handling
6627 @item @emph{Description}:
6628 Returns the system error message corresponding to the last system error.
6629 This resembles the functionality of @code{strerror(3)} in C.
6631 @item @emph{Standard}:
6637 @item @emph{Syntax}:
6638 @code{CALL GERROR(RESULT)}
6640 @item @emph{Arguments}:
6641 @multitable @columnfractions .15 .70
6642 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
6645 @item @emph{Example}:
6648 CHARACTER(len=100) :: msg
6654 @item @emph{See also}:
6655 @ref{IERRNO}, @ref{PERROR}
6661 @section @code{GETARG} --- Get command line arguments
6663 @cindex command-line arguments
6664 @cindex arguments, to program
6667 @item @emph{Description}:
6668 Retrieve the @var{POS}-th argument that was passed on the
6669 command line when the containing program was invoked.
6671 This intrinsic routine is provided for backwards compatibility with
6672 GNU Fortran 77. In new code, programmers should consider the use of
6673 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
6676 @item @emph{Standard}:
6682 @item @emph{Syntax}:
6683 @code{CALL GETARG(POS, VALUE)}
6685 @item @emph{Arguments}:
6686 @multitable @columnfractions .15 .70
6687 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
6688 the default integer kind; @math{@var{POS} \geq 0}
6689 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
6691 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
6694 @item @emph{Return value}:
6695 After @code{GETARG} returns, the @var{VALUE} argument holds the
6696 @var{POS}th command line argument. If @var{VALUE} can not hold the
6697 argument, it is truncated to fit the length of @var{VALUE}. If there are
6698 less than @var{POS} arguments specified at the command line, @var{VALUE}
6699 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
6700 to the name of the program (on systems that support this feature).
6702 @item @emph{Example}:
6706 CHARACTER(len=32) :: arg
6715 @item @emph{See also}:
6716 GNU Fortran 77 compatibility function: @ref{IARGC}
6718 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
6719 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6725 @section @code{GET_COMMAND} --- Get the entire command line
6726 @fnindex GET_COMMAND
6727 @cindex command-line arguments
6728 @cindex arguments, to program
6731 @item @emph{Description}:
6732 Retrieve the entire command line that was used to invoke the program.
6734 @item @emph{Standard}:
6735 Fortran 2003 and later
6740 @item @emph{Syntax}:
6741 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
6743 @item @emph{Arguments}:
6744 @multitable @columnfractions .15 .70
6745 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
6747 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
6749 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
6753 @item @emph{Return value}:
6754 If @var{COMMAND} is present, stores the entire command line that was used
6755 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
6756 assigned the length of the command line. If @var{STATUS} is present, it
6757 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
6758 short to store the command line, or a positive value in case of an error.
6760 @item @emph{Example}:
6762 PROGRAM test_get_command
6763 CHARACTER(len=255) :: cmd
6764 CALL get_command(cmd)
6765 WRITE (*,*) TRIM(cmd)
6769 @item @emph{See also}:
6770 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6775 @node GET_COMMAND_ARGUMENT
6776 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
6777 @fnindex GET_COMMAND_ARGUMENT
6778 @cindex command-line arguments
6779 @cindex arguments, to program
6782 @item @emph{Description}:
6783 Retrieve the @var{NUMBER}-th argument that was passed on the
6784 command line when the containing program was invoked.
6786 @item @emph{Standard}:
6787 Fortran 2003 and later
6792 @item @emph{Syntax}:
6793 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
6795 @item @emph{Arguments}:
6796 @multitable @columnfractions .15 .70
6797 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
6798 default kind, @math{@var{NUMBER} \geq 0}
6799 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
6800 and of default kind.
6801 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6802 and of default kind.
6803 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6804 and of default kind.
6807 @item @emph{Return value}:
6808 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
6809 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
6810 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
6811 arguments specified at the command line, @var{VALUE} will be filled with blanks.
6812 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
6813 systems that support this feature). The @var{LENGTH} argument contains the
6814 length of the @var{NUMBER}-th command line argument. If the argument retrieval
6815 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
6816 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
6819 @item @emph{Example}:
6821 PROGRAM test_get_command_argument
6823 CHARACTER(len=32) :: arg
6827 CALL get_command_argument(i, arg)
6828 IF (LEN_TRIM(arg) == 0) EXIT
6830 WRITE (*,*) TRIM(arg)
6836 @item @emph{See also}:
6837 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
6843 @section @code{GETCWD} --- Get current working directory
6845 @cindex system, working directory
6848 @item @emph{Description}:
6849 Get current working directory.
6851 This intrinsic is provided in both subroutine and function forms; however,
6852 only one form can be used in any given program unit.
6854 @item @emph{Standard}:
6858 Subroutine, function
6860 @item @emph{Syntax}:
6861 @multitable @columnfractions .80
6862 @item @code{CALL GETCWD(C [, STATUS])}
6863 @item @code{STATUS = GETCWD(C)}
6866 @item @emph{Arguments}:
6867 @multitable @columnfractions .15 .70
6868 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
6869 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
6870 a system specific and nonzero error code otherwise.
6873 @item @emph{Example}:
6876 CHARACTER(len=255) :: cwd
6878 WRITE(*,*) TRIM(cwd)
6882 @item @emph{See also}:
6889 @section @code{GETENV} --- Get an environmental variable
6891 @cindex environment variable
6894 @item @emph{Description}:
6895 Get the @var{VALUE} of the environmental variable @var{NAME}.
6897 This intrinsic routine is provided for backwards compatibility with
6898 GNU Fortran 77. In new code, programmers should consider the use of
6899 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
6902 Note that @code{GETENV} need not be thread-safe. It is the
6903 responsibility of the user to ensure that the environment is not being
6904 updated concurrently with a call to the @code{GETENV} intrinsic.
6906 @item @emph{Standard}:
6912 @item @emph{Syntax}:
6913 @code{CALL GETENV(NAME, VALUE)}
6915 @item @emph{Arguments}:
6916 @multitable @columnfractions .15 .70
6917 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
6918 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
6921 @item @emph{Return value}:
6922 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
6923 not large enough to hold the data, it is truncated. If @var{NAME}
6924 is not set, @var{VALUE} will be filled with blanks.
6926 @item @emph{Example}:
6929 CHARACTER(len=255) :: homedir
6930 CALL getenv("HOME", homedir)
6931 WRITE (*,*) TRIM(homedir)
6935 @item @emph{See also}:
6936 @ref{GET_ENVIRONMENT_VARIABLE}
6941 @node GET_ENVIRONMENT_VARIABLE
6942 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
6943 @fnindex GET_ENVIRONMENT_VARIABLE
6944 @cindex environment variable
6947 @item @emph{Description}:
6948 Get the @var{VALUE} of the environmental variable @var{NAME}.
6950 Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It
6951 is the responsibility of the user to ensure that the environment is
6952 not being updated concurrently with a call to the
6953 @code{GET_ENVIRONMENT_VARIABLE} intrinsic.
6955 @item @emph{Standard}:
6956 Fortran 2003 and later
6961 @item @emph{Syntax}:
6962 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
6964 @item @emph{Arguments}:
6965 @multitable @columnfractions .15 .70
6966 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
6967 and of default kind.
6968 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
6969 and of default kind.
6970 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6971 and of default kind.
6972 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6973 and of default kind.
6974 @item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL}
6975 and of default kind.
6978 @item @emph{Return value}:
6979 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
6980 not large enough to hold the data, it is truncated. If @var{NAME}
6981 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
6982 contains the length needed for storing the environment variable @var{NAME}
6983 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
6984 but too short for the environment variable; it is 1 if the environment
6985 variable does not exist and 2 if the processor does not support environment
6986 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
6987 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
6988 are significant; otherwise they are not part of the environment variable
6991 @item @emph{Example}:
6994 CHARACTER(len=255) :: homedir
6995 CALL get_environment_variable("HOME", homedir)
6996 WRITE (*,*) TRIM(homedir)
7004 @section @code{GETGID} --- Group ID function
7006 @cindex system, group ID
7009 @item @emph{Description}:
7010 Returns the numerical group ID of the current process.
7012 @item @emph{Standard}:
7018 @item @emph{Syntax}:
7019 @code{RESULT = GETGID()}
7021 @item @emph{Return value}:
7022 The return value of @code{GETGID} is an @code{INTEGER} of the default
7026 @item @emph{Example}:
7027 See @code{GETPID} for an example.
7029 @item @emph{See also}:
7030 @ref{GETPID}, @ref{GETUID}
7036 @section @code{GETLOG} --- Get login name
7038 @cindex system, login name
7042 @item @emph{Description}:
7043 Gets the username under which the program is running.
7045 @item @emph{Standard}:
7051 @item @emph{Syntax}:
7052 @code{CALL GETLOG(C)}
7054 @item @emph{Arguments}:
7055 @multitable @columnfractions .15 .70
7056 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
7059 @item @emph{Return value}:
7060 Stores the current user name in @var{LOGIN}. (On systems where POSIX
7061 functions @code{geteuid} and @code{getpwuid} are not available, and
7062 the @code{getlogin} function is not implemented either, this will
7063 return a blank string.)
7065 @item @emph{Example}:
7068 CHARACTER(32) :: login
7074 @item @emph{See also}:
7081 @section @code{GETPID} --- Process ID function
7083 @cindex system, process ID
7087 @item @emph{Description}:
7088 Returns the numerical process identifier of the current process.
7090 @item @emph{Standard}:
7096 @item @emph{Syntax}:
7097 @code{RESULT = GETPID()}
7099 @item @emph{Return value}:
7100 The return value of @code{GETPID} is an @code{INTEGER} of the default
7104 @item @emph{Example}:
7107 print *, "The current process ID is ", getpid()
7108 print *, "Your numerical user ID is ", getuid()
7109 print *, "Your numerical group ID is ", getgid()
7113 @item @emph{See also}:
7114 @ref{GETGID}, @ref{GETUID}
7120 @section @code{GETUID} --- User ID function
7122 @cindex system, user ID
7126 @item @emph{Description}:
7127 Returns the numerical user ID of the current process.
7129 @item @emph{Standard}:
7135 @item @emph{Syntax}:
7136 @code{RESULT = GETUID()}
7138 @item @emph{Return value}:
7139 The return value of @code{GETUID} is an @code{INTEGER} of the default
7143 @item @emph{Example}:
7144 See @code{GETPID} for an example.
7146 @item @emph{See also}:
7147 @ref{GETPID}, @ref{GETLOG}
7153 @section @code{GMTIME} --- Convert time to GMT info
7155 @cindex time, conversion to GMT info
7158 @item @emph{Description}:
7159 Given a system time value @var{TIME} (as provided by the @code{TIME8}
7160 intrinsic), fills @var{VALUES} with values extracted from it appropriate
7161 to the UTC time zone (Universal Coordinated Time, also known in some
7162 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
7164 @item @emph{Standard}:
7170 @item @emph{Syntax}:
7171 @code{CALL GMTIME(TIME, VALUES)}
7173 @item @emph{Arguments}:
7174 @multitable @columnfractions .15 .70
7175 @item @var{TIME} @tab An @code{INTEGER} scalar expression
7176 corresponding to a system time, with @code{INTENT(IN)}.
7177 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
7178 with @code{INTENT(OUT)}.
7181 @item @emph{Return value}:
7182 The elements of @var{VALUES} are assigned as follows:
7184 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
7186 @item Minutes after the hour, range 0--59
7187 @item Hours past midnight, range 0--23
7188 @item Day of month, range 0--31
7189 @item Number of months since January, range 0--12
7190 @item Years since 1900
7191 @item Number of days since Sunday, range 0--6
7192 @item Days since January 1
7193 @item Daylight savings indicator: positive if daylight savings is in
7194 effect, zero if not, and negative if the information is not available.
7197 @item @emph{See also}:
7198 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
7205 @section @code{HOSTNM} --- Get system host name
7207 @cindex system, host name
7210 @item @emph{Description}:
7211 Retrieves the host name of the system on which the program is running.
7213 This intrinsic is provided in both subroutine and function forms; however,
7214 only one form can be used in any given program unit.
7216 @item @emph{Standard}:
7220 Subroutine, function
7222 @item @emph{Syntax}:
7223 @multitable @columnfractions .80
7224 @item @code{CALL HOSTNM(C [, STATUS])}
7225 @item @code{STATUS = HOSTNM(NAME)}
7228 @item @emph{Arguments}:
7229 @multitable @columnfractions .15 .70
7230 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
7231 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
7232 Returns 0 on success, or a system specific error code otherwise.
7235 @item @emph{Return value}:
7236 In either syntax, @var{NAME} is set to the current hostname if it can
7237 be obtained, or to a blank string otherwise.
7244 @section @code{HUGE} --- Largest number of a kind
7246 @cindex limits, largest number
7247 @cindex model representation, largest number
7250 @item @emph{Description}:
7251 @code{HUGE(X)} returns the largest number that is not an infinity in
7252 the model of the type of @code{X}.
7254 @item @emph{Standard}:
7255 Fortran 95 and later
7260 @item @emph{Syntax}:
7261 @code{RESULT = HUGE(X)}
7263 @item @emph{Arguments}:
7264 @multitable @columnfractions .15 .70
7265 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
7268 @item @emph{Return value}:
7269 The return value is of the same type and kind as @var{X}
7271 @item @emph{Example}:
7273 program test_huge_tiny
7274 print *, huge(0), huge(0.0), huge(0.0d0)
7275 print *, tiny(0.0), tiny(0.0d0)
7276 end program test_huge_tiny
7283 @section @code{HYPOT} --- Euclidean distance function
7285 @cindex Euclidean distance
7288 @item @emph{Description}:
7289 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
7290 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
7292 @item @emph{Standard}:
7293 Fortran 2008 and later
7298 @item @emph{Syntax}:
7299 @code{RESULT = HYPOT(X, Y)}
7301 @item @emph{Arguments}:
7302 @multitable @columnfractions .15 .70
7303 @item @var{X} @tab The type shall be @code{REAL}.
7304 @item @var{Y} @tab The type and kind type parameter shall be the same as
7308 @item @emph{Return value}:
7309 The return value has the same type and kind type parameter as @var{X}.
7311 @item @emph{Example}:
7314 real(4) :: x = 1.e0_4, y = 0.5e0_4
7316 end program test_hypot
7323 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
7325 @cindex @acronym{ASCII} collating sequence
7326 @cindex collating sequence, @acronym{ASCII}
7327 @cindex conversion, to integer
7330 @item @emph{Description}:
7331 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
7332 in the first character position of @code{C}.
7334 @item @emph{Standard}:
7335 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7340 @item @emph{Syntax}:
7341 @code{RESULT = IACHAR(C [, KIND])}
7343 @item @emph{Arguments}:
7344 @multitable @columnfractions .15 .70
7345 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
7346 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7347 expression indicating the kind parameter of the result.
7350 @item @emph{Return value}:
7351 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7352 @var{KIND} is absent, the return value is of default integer kind.
7354 @item @emph{Example}:
7359 end program test_iachar
7363 See @ref{ICHAR} for a discussion of converting between numerical values
7364 and formatted string representations.
7366 @item @emph{See also}:
7367 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
7374 @section @code{IALL} --- Bitwise AND of array elements
7377 @cindex bits, AND of array elements
7380 @item @emph{Description}:
7381 Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
7382 if the corresponding element in @var{MASK} is @code{TRUE}.
7384 @item @emph{Standard}:
7385 Fortran 2008 and later
7388 Transformational function
7390 @item @emph{Syntax}:
7391 @multitable @columnfractions .80
7392 @item @code{RESULT = IALL(ARRAY[, MASK])}
7393 @item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
7396 @item @emph{Arguments}:
7397 @multitable @columnfractions .15 .70
7398 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7399 @item @var{DIM} @tab (Optional) shall be a scalar of type
7400 @code{INTEGER} with a value in the range from 1 to n, where n
7401 equals the rank of @var{ARRAY}.
7402 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
7403 and either be a scalar or an array of the same shape as @var{ARRAY}.
7406 @item @emph{Return value}:
7407 The result is of the same type as @var{ARRAY}.
7409 If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
7410 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7411 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7412 dimension @var{DIM} dropped is returned.
7414 @item @emph{Example}:
7423 PRINT '(b8.8)', IALL(a)
7427 @item @emph{See also}:
7428 @ref{IANY}, @ref{IPARITY}, @ref{IAND}
7434 @section @code{IAND} --- Bitwise logical and
7440 @cindex bitwise logical and
7441 @cindex logical and, bitwise
7444 @item @emph{Description}:
7445 Bitwise logical @code{AND}.
7447 @item @emph{Standard}:
7448 Fortran 95 and later, has overloads that are GNU extensions
7453 @item @emph{Syntax}:
7454 @code{RESULT = IAND(I, J)}
7456 @item @emph{Arguments}:
7457 @multitable @columnfractions .15 .70
7458 @item @var{I} @tab The type shall be @code{INTEGER}.
7459 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
7460 kind as @var{I}. (As a GNU extension, different kinds are also
7464 @item @emph{Return value}:
7465 The return type is @code{INTEGER}, of the same kind as the
7466 arguments. (If the argument kinds differ, it is of the same kind as
7467 the larger argument.)
7469 @item @emph{Example}:
7473 DATA a / Z'F' /, b / Z'3' /
7474 WRITE (*,*) IAND(a, b)
7478 @item @emph{Specific names}:
7479 @multitable @columnfractions .20 .20 .20 .25
7480 @item Name @tab Argument @tab Return type @tab Standard
7481 @item @code{IAND(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7482 @item @code{BIAND(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7483 @item @code{IIAND(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7484 @item @code{JIAND(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7485 @item @code{KIAND(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7488 @item @emph{See also}:
7489 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
7496 @section @code{IANY} --- Bitwise OR of array elements
7499 @cindex bits, OR of array elements
7502 @item @emph{Description}:
7503 Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
7504 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
7506 @item @emph{Standard}:
7507 Fortran 2008 and later
7510 Transformational function
7512 @item @emph{Syntax}:
7513 @multitable @columnfractions .80
7514 @item @code{RESULT = IANY(ARRAY[, MASK])}
7515 @item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
7518 @item @emph{Arguments}:
7519 @multitable @columnfractions .15 .70
7520 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7521 @item @var{DIM} @tab (Optional) shall be a scalar of type
7522 @code{INTEGER} with a value in the range from 1 to n, where n
7523 equals the rank of @var{ARRAY}.
7524 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
7525 and either be a scalar or an array of the same shape as @var{ARRAY}.
7528 @item @emph{Return value}:
7529 The result is of the same type as @var{ARRAY}.
7531 If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
7532 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7533 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7534 dimension @var{DIM} dropped is returned.
7536 @item @emph{Example}:
7545 PRINT '(b8.8)', IANY(a)
7549 @item @emph{See also}:
7550 @ref{IPARITY}, @ref{IALL}, @ref{IOR}
7556 @section @code{IARGC} --- Get the number of command line arguments
7558 @cindex command-line arguments
7559 @cindex command-line arguments, number of
7560 @cindex arguments, to program
7563 @item @emph{Description}:
7564 @code{IARGC} returns the number of arguments passed on the
7565 command line when the containing program was invoked.
7567 This intrinsic routine is provided for backwards compatibility with
7568 GNU Fortran 77. In new code, programmers should consider the use of
7569 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
7572 @item @emph{Standard}:
7578 @item @emph{Syntax}:
7579 @code{RESULT = IARGC()}
7581 @item @emph{Arguments}:
7584 @item @emph{Return value}:
7585 The number of command line arguments, type @code{INTEGER(4)}.
7587 @item @emph{Example}:
7590 @item @emph{See also}:
7591 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
7593 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
7594 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
7600 @section @code{IBCLR} --- Clear bit
7610 @item @emph{Description}:
7611 @code{IBCLR} returns the value of @var{I} with the bit at position
7612 @var{POS} set to zero.
7614 @item @emph{Standard}:
7615 Fortran 95 and later, has overloads that are GNU extensions
7620 @item @emph{Syntax}:
7621 @code{RESULT = IBCLR(I, POS)}
7623 @item @emph{Arguments}:
7624 @multitable @columnfractions .15 .70
7625 @item @var{I} @tab The type shall be @code{INTEGER}.
7626 @item @var{POS} @tab The type shall be @code{INTEGER}.
7629 @item @emph{Return value}:
7630 The return value is of type @code{INTEGER} and of the same kind as
7633 @item @emph{Specific names}:
7634 @multitable @columnfractions .20 .20 .20 .25
7635 @item Name @tab Argument @tab Return type @tab Standard
7636 @item @code{IBCLR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7637 @item @code{BBCLR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7638 @item @code{IIBCLR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7639 @item @code{JIBCLR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7640 @item @code{KIBCLR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7643 @item @emph{See also}:
7644 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
7651 @section @code{IBITS} --- Bit extraction
7658 @cindex bits, extract
7661 @item @emph{Description}:
7662 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
7663 starting from bit position @var{POS} and extending left for @var{LEN}
7664 bits. The result is right-justified and the remaining bits are
7665 zeroed. The value of @code{POS+LEN} must be less than or equal to the
7666 value @code{BIT_SIZE(I)}.
7668 @item @emph{Standard}:
7669 Fortran 95 and later, has overloads that are GNU extensions
7674 @item @emph{Syntax}:
7675 @code{RESULT = IBITS(I, POS, LEN)}
7677 @item @emph{Arguments}:
7678 @multitable @columnfractions .15 .70
7679 @item @var{I} @tab The type shall be @code{INTEGER}.
7680 @item @var{POS} @tab The type shall be @code{INTEGER}.
7681 @item @var{LEN} @tab The type shall be @code{INTEGER}.
7684 @item @emph{Return value}:
7685 The return value is of type @code{INTEGER} and of the same kind as
7688 @item @emph{Specific names}:
7689 @multitable @columnfractions .20 .20 .20 .25
7690 @item Name @tab Argument @tab Return type @tab Standard
7691 @item @code{IBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7692 @item @code{BBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7693 @item @code{IIBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7694 @item @code{JIBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7695 @item @code{KIBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7698 @item @emph{See also}:
7699 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
7705 @section @code{IBSET} --- Set bit
7714 @item @emph{Description}:
7715 @code{IBSET} returns the value of @var{I} with the bit at position
7716 @var{POS} set to one.
7718 @item @emph{Standard}:
7719 Fortran 95 and later, has overloads that are GNU extensions
7724 @item @emph{Syntax}:
7725 @code{RESULT = IBSET(I, POS)}
7727 @item @emph{Arguments}:
7728 @multitable @columnfractions .15 .70
7729 @item @var{I} @tab The type shall be @code{INTEGER}.
7730 @item @var{POS} @tab The type shall be @code{INTEGER}.
7733 @item @emph{Return value}:
7734 The return value is of type @code{INTEGER} and of the same kind as
7737 @item @emph{Specific names}:
7738 @multitable @columnfractions .20 .20 .20 .25
7739 @item Name @tab Argument @tab Return type @tab Standard
7740 @item @code{IBSET(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7741 @item @code{BBSET(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7742 @item @code{IIBSET(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7743 @item @code{JIBSET(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7744 @item @code{KIBSET(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7747 @item @emph{See also}:
7748 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
7755 @section @code{ICHAR} --- Character-to-integer conversion function
7757 @cindex conversion, to integer
7760 @item @emph{Description}:
7761 @code{ICHAR(C)} returns the code for the character in the first character
7762 position of @code{C} in the system's native character set.
7763 The correspondence between characters and their codes is not necessarily
7764 the same across different GNU Fortran implementations.
7766 @item @emph{Standard}:
7767 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7772 @item @emph{Syntax}:
7773 @code{RESULT = ICHAR(C [, KIND])}
7775 @item @emph{Arguments}:
7776 @multitable @columnfractions .15 .70
7777 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
7778 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7779 expression indicating the kind parameter of the result.
7782 @item @emph{Return value}:
7783 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7784 @var{KIND} is absent, the return value is of default integer kind.
7786 @item @emph{Example}:
7791 end program test_ichar
7794 @item @emph{Specific names}:
7795 @multitable @columnfractions .20 .20 .20 .25
7796 @item Name @tab Argument @tab Return type @tab Standard
7797 @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7801 No intrinsic exists to convert between a numeric value and a formatted
7802 character string representation -- for instance, given the
7803 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
7804 @code{REAL} value with the value 154, or vice versa. Instead, this
7805 functionality is provided by internal-file I/O, as in the following
7810 character(len=10) string, string2
7813 ! Convert a string to a numeric value
7814 read (string,'(I10)') value
7817 ! Convert a value to a formatted string
7818 write (string2,'(I10)') value
7820 end program read_val
7823 @item @emph{See also}:
7824 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
7831 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
7833 @cindex date, current
7834 @cindex current date
7837 @item @emph{Description}:
7838 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
7839 current local time. The day (in the range 1-31), month (in the range 1-12),
7840 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
7841 The year has four significant digits.
7843 @item @emph{Standard}:
7849 @item @emph{Syntax}:
7850 @code{CALL IDATE(VALUES)}
7852 @item @emph{Arguments}:
7853 @multitable @columnfractions .15 .70
7854 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
7855 the kind shall be the default integer kind.
7858 @item @emph{Return value}:
7859 Does not return anything.
7861 @item @emph{Example}:
7864 integer, dimension(3) :: tarray
7869 end program test_idate
7876 @section @code{IEOR} --- Bitwise logical exclusive or
7882 @cindex bitwise logical exclusive or
7883 @cindex logical exclusive or, bitwise
7886 @item @emph{Description}:
7887 @code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
7890 @item @emph{Standard}:
7891 Fortran 95 and later, has overloads that are GNU extensions
7896 @item @emph{Syntax}:
7897 @code{RESULT = IEOR(I, J)}
7899 @item @emph{Arguments}:
7900 @multitable @columnfractions .15 .70
7901 @item @var{I} @tab The type shall be @code{INTEGER}.
7902 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
7903 kind as @var{I}. (As a GNU extension, different kinds are also
7907 @item @emph{Return value}:
7908 The return type is @code{INTEGER}, of the same kind as the
7909 arguments. (If the argument kinds differ, it is of the same kind as
7910 the larger argument.)
7912 @item @emph{Specific names}:
7913 @multitable @columnfractions .20 .20 .20 .25
7914 @item Name @tab Argument @tab Return type @tab Standard
7915 @item @code{IEOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7916 @item @code{BIEOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7917 @item @code{IIEOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7918 @item @code{JIEOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7919 @item @code{KIEOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7922 @item @emph{See also}:
7923 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
7929 @section @code{IERRNO} --- Get the last system error number
7931 @cindex system, error handling
7934 @item @emph{Description}:
7935 Returns the last system error number, as given by the C @code{errno}
7938 @item @emph{Standard}:
7944 @item @emph{Syntax}:
7945 @code{RESULT = IERRNO()}
7947 @item @emph{Arguments}:
7950 @item @emph{Return value}:
7951 The return value is of type @code{INTEGER} and of the default integer
7954 @item @emph{See also}:
7961 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
7962 @fnindex IMAGE_INDEX
7963 @cindex coarray, @code{IMAGE_INDEX}
7964 @cindex images, cosubscript to image index conversion
7967 @item @emph{Description}:
7968 Returns the image index belonging to a cosubscript.
7970 @item @emph{Standard}:
7971 Fortran 2008 and later
7976 @item @emph{Syntax}:
7977 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
7979 @item @emph{Arguments}: None.
7980 @multitable @columnfractions .15 .70
7981 @item @var{COARRAY} @tab Coarray of any type.
7982 @item @var{SUB} @tab default integer rank-1 array of a size equal to
7983 the corank of @var{COARRAY}.
7987 @item @emph{Return value}:
7988 Scalar default integer with the value of the image index which corresponds
7989 to the cosubscripts. For invalid cosubscripts the result is zero.
7991 @item @emph{Example}:
7993 INTEGER :: array[2,-1:4,8,*]
7994 ! Writes 28 (or 0 if there are fewer than 28 images)
7995 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
7998 @item @emph{See also}:
7999 @ref{THIS_IMAGE}, @ref{NUM_IMAGES}
8004 @node INDEX intrinsic
8005 @section @code{INDEX} --- Position of a substring within a string
8007 @cindex substring position
8008 @cindex string, find substring
8011 @item @emph{Description}:
8012 Returns the position of the start of the first occurrence of string
8013 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
8014 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
8015 the @var{BACK} argument is present and true, the return value is the
8016 start of the last occurrence rather than the first.
8018 @item @emph{Standard}:
8019 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
8024 @item @emph{Syntax}:
8025 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
8027 @item @emph{Arguments}:
8028 @multitable @columnfractions .15 .70
8029 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
8031 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
8033 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
8035 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8036 expression indicating the kind parameter of the result.
8039 @item @emph{Return value}:
8040 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8041 @var{KIND} is absent, the return value is of default integer kind.
8043 @item @emph{Specific names}:
8044 @multitable @columnfractions .20 .20 .20 .25
8045 @item Name @tab Argument @tab Return type @tab Standard
8046 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8049 @item @emph{See also}:
8050 @ref{SCAN}, @ref{VERIFY}
8056 @section @code{INT} --- Convert to integer type
8060 @cindex conversion, to integer
8063 @item @emph{Description}:
8064 Convert to integer type
8066 @item @emph{Standard}:
8067 Fortran 77 and later
8072 @item @emph{Syntax}:
8073 @code{RESULT = INT(A [, KIND))}
8075 @item @emph{Arguments}:
8076 @multitable @columnfractions .15 .70
8077 @item @var{A} @tab Shall be of type @code{INTEGER},
8078 @code{REAL}, or @code{COMPLEX}.
8079 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8080 expression indicating the kind parameter of the result.
8083 @item @emph{Return value}:
8084 These functions return a @code{INTEGER} variable or array under
8085 the following rules:
8089 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
8091 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)}
8092 equals @code{0}. If @math{|A| \geq 1}, then @code{INT(A)} is the integer
8093 whose magnitude is the largest integer that does not exceed the magnitude
8094 of @var{A} and whose sign is the same as the sign of @var{A}.
8096 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
8099 @item @emph{Example}:
8103 complex :: z = (-3.7, 1.0)
8105 print *, int(z), int(z,8)
8109 @item @emph{Specific names}:
8110 @multitable @columnfractions .20 .20 .20 .25
8111 @item Name @tab Argument @tab Return type @tab Standard
8112 @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
8113 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
8114 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
8121 @section @code{INT2} --- Convert to 16-bit integer type
8124 @cindex conversion, to integer
8127 @item @emph{Description}:
8128 Convert to a @code{KIND=2} integer type. This is equivalent to the
8129 standard @code{INT} intrinsic with an optional argument of
8130 @code{KIND=2}, and is only included for backwards compatibility.
8132 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
8134 @item @emph{Standard}:
8140 @item @emph{Syntax}:
8141 @code{RESULT = INT2(A)}
8143 @item @emph{Arguments}:
8144 @multitable @columnfractions .15 .70
8145 @item @var{A} @tab Shall be of type @code{INTEGER},
8146 @code{REAL}, or @code{COMPLEX}.
8149 @item @emph{Return value}:
8150 The return value is a @code{INTEGER(2)} variable.
8152 @item @emph{See also}:
8153 @ref{INT}, @ref{INT8}, @ref{LONG}
8159 @section @code{INT8} --- Convert to 64-bit integer type
8161 @cindex conversion, to integer
8164 @item @emph{Description}:
8165 Convert to a @code{KIND=8} integer type. This is equivalent to the
8166 standard @code{INT} intrinsic with an optional argument of
8167 @code{KIND=8}, and is only included for backwards compatibility.
8169 @item @emph{Standard}:
8175 @item @emph{Syntax}:
8176 @code{RESULT = INT8(A)}
8178 @item @emph{Arguments}:
8179 @multitable @columnfractions .15 .70
8180 @item @var{A} @tab Shall be of type @code{INTEGER},
8181 @code{REAL}, or @code{COMPLEX}.
8184 @item @emph{Return value}:
8185 The return value is a @code{INTEGER(8)} variable.
8187 @item @emph{See also}:
8188 @ref{INT}, @ref{INT2}, @ref{LONG}
8194 @section @code{IOR} --- Bitwise logical or
8200 @cindex bitwise logical or
8201 @cindex logical or, bitwise
8204 @item @emph{Description}:
8205 @code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
8208 @item @emph{Standard}:
8209 Fortran 95 and later, has overloads that are GNU extensions
8214 @item @emph{Syntax}:
8215 @code{RESULT = IOR(I, J)}
8217 @item @emph{Arguments}:
8218 @multitable @columnfractions .15 .70
8219 @item @var{I} @tab The type shall be @code{INTEGER}.
8220 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
8221 kind as @var{I}. (As a GNU extension, different kinds are also
8225 @item @emph{Return value}:
8226 The return type is @code{INTEGER}, of the same kind as the
8227 arguments. (If the argument kinds differ, it is of the same kind as
8228 the larger argument.)
8230 @item @emph{Specific names}:
8231 @multitable @columnfractions .20 .20 .20 .25
8232 @item Name @tab Argument @tab Return type @tab Standard
8233 @item @code{IOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
8234 @item @code{BIOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8235 @item @code{IIOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8236 @item @code{JIOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8237 @item @code{KIOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8240 @item @emph{See also}:
8241 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
8247 @section @code{IPARITY} --- Bitwise XOR of array elements
8249 @cindex array, parity
8251 @cindex bits, XOR of array elements
8254 @item @emph{Description}:
8255 Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
8256 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
8258 @item @emph{Standard}:
8259 Fortran 2008 and later
8262 Transformational function
8264 @item @emph{Syntax}:
8265 @multitable @columnfractions .80
8266 @item @code{RESULT = IPARITY(ARRAY[, MASK])}
8267 @item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
8270 @item @emph{Arguments}:
8271 @multitable @columnfractions .15 .70
8272 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
8273 @item @var{DIM} @tab (Optional) shall be a scalar of type
8274 @code{INTEGER} with a value in the range from 1 to n, where n
8275 equals the rank of @var{ARRAY}.
8276 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
8277 and either be a scalar or an array of the same shape as @var{ARRAY}.
8280 @item @emph{Return value}:
8281 The result is of the same type as @var{ARRAY}.
8283 If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
8284 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
8285 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
8286 dimension @var{DIM} dropped is returned.
8288 @item @emph{Example}:
8290 PROGRAM test_iparity
8297 PRINT '(b8.8)', IPARITY(a)
8301 @item @emph{See also}:
8302 @ref{IANY}, @ref{IALL}, @ref{IEOR}, @ref{PARITY}
8308 @section @code{IRAND} --- Integer pseudo-random number
8310 @cindex random number generation
8313 @item @emph{Description}:
8314 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
8315 distribution between 0 and a system-dependent limit (which is in most
8316 cases 2147483647). If @var{FLAG} is 0, the next number
8317 in the current sequence is returned; if @var{FLAG} is 1, the generator
8318 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
8319 it is used as a new seed with @code{SRAND}.
8321 This intrinsic routine is provided for backwards compatibility with
8322 GNU Fortran 77. It implements a simple modulo generator as provided
8323 by @command{g77}. For new code, one should consider the use of
8324 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
8326 @item @emph{Standard}:
8332 @item @emph{Syntax}:
8333 @code{RESULT = IRAND(I)}
8335 @item @emph{Arguments}:
8336 @multitable @columnfractions .15 .70
8337 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
8340 @item @emph{Return value}:
8341 The return value is of @code{INTEGER(kind=4)} type.
8343 @item @emph{Example}:
8346 integer,parameter :: seed = 86456
8349 print *, irand(), irand(), irand(), irand()
8350 print *, irand(seed), irand(), irand(), irand()
8351 end program test_irand
8359 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
8360 @fnindex IS_IOSTAT_END
8361 @cindex @code{IOSTAT}, end of file
8364 @item @emph{Description}:
8365 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
8366 status ``end of file''. The function is equivalent to comparing the variable
8367 with the @code{IOSTAT_END} parameter of the intrinsic module
8368 @code{ISO_FORTRAN_ENV}.
8370 @item @emph{Standard}:
8371 Fortran 2003 and later
8376 @item @emph{Syntax}:
8377 @code{RESULT = IS_IOSTAT_END(I)}
8379 @item @emph{Arguments}:
8380 @multitable @columnfractions .15 .70
8381 @item @var{I} @tab Shall be of the type @code{INTEGER}.
8384 @item @emph{Return value}:
8385 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
8386 @var{I} has the value which indicates an end of file condition for
8387 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
8389 @item @emph{Example}:
8394 OPEN(88, FILE='test.dat')
8395 READ(88, *, IOSTAT=stat) i
8396 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
8404 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
8405 @fnindex IS_IOSTAT_EOR
8406 @cindex @code{IOSTAT}, end of record
8409 @item @emph{Description}:
8410 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
8411 status ``end of record''. The function is equivalent to comparing the
8412 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
8413 @code{ISO_FORTRAN_ENV}.
8415 @item @emph{Standard}:
8416 Fortran 2003 and later
8421 @item @emph{Syntax}:
8422 @code{RESULT = IS_IOSTAT_EOR(I)}
8424 @item @emph{Arguments}:
8425 @multitable @columnfractions .15 .70
8426 @item @var{I} @tab Shall be of the type @code{INTEGER}.
8429 @item @emph{Return value}:
8430 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
8431 @var{I} has the value which indicates an end of file condition for
8432 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
8434 @item @emph{Example}:
8438 INTEGER :: stat, i(50)
8439 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
8440 READ(88, IOSTAT=stat) i
8441 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
8449 @section @code{ISATTY} --- Whether a unit is a terminal device.
8451 @cindex system, terminal
8454 @item @emph{Description}:
8455 Determine whether a unit is connected to a terminal device.
8457 @item @emph{Standard}:
8463 @item @emph{Syntax}:
8464 @code{RESULT = ISATTY(UNIT)}
8466 @item @emph{Arguments}:
8467 @multitable @columnfractions .15 .70
8468 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
8471 @item @emph{Return value}:
8472 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
8473 device, @code{.FALSE.} otherwise.
8475 @item @emph{Example}:
8478 INTEGER(kind=1) :: unit
8480 write(*,*) isatty(unit=unit)
8484 @item @emph{See also}:
8491 @section @code{ISHFT} --- Shift bits
8500 @item @emph{Description}:
8501 @code{ISHFT} returns a value corresponding to @var{I} with all of the
8502 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
8503 zero corresponds to a left shift, a value of zero corresponds to no
8504 shift, and a value less than zero corresponds to a right shift. If the
8505 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
8506 value is undefined. Bits shifted out from the left end or right end are
8507 lost; zeros are shifted in from the opposite end.
8509 @item @emph{Standard}:
8510 Fortran 95 and later, has overloads that are GNU extensions
8515 @item @emph{Syntax}:
8516 @code{RESULT = ISHFT(I, SHIFT)}
8518 @item @emph{Arguments}:
8519 @multitable @columnfractions .15 .70
8520 @item @var{I} @tab The type shall be @code{INTEGER}.
8521 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8524 @item @emph{Return value}:
8525 The return value is of type @code{INTEGER} and of the same kind as
8528 @item @emph{Specific names}:
8529 @multitable @columnfractions .20 .20 .20 .25
8530 @item Name @tab Argument @tab Return type @tab Standard
8531 @item @code{ISHFT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
8532 @item @code{BSHFT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8533 @item @code{IISHFT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8534 @item @code{JISHFT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8535 @item @code{KISHFT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8538 @item @emph{See also}:
8545 @section @code{ISHFTC} --- Shift bits circularly
8551 @cindex bits, shift circular
8554 @item @emph{Description}:
8555 @code{ISHFTC} returns a value corresponding to @var{I} with the
8556 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
8557 is, bits shifted out one end are shifted into the opposite end. A value
8558 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
8559 zero corresponds to no shift, and a value less than zero corresponds to
8560 a right shift. The absolute value of @var{SHIFT} must be less than
8561 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
8562 equivalent to @code{BIT_SIZE(I)}.
8564 @item @emph{Standard}:
8565 Fortran 95 and later, has overloads that are GNU extensions
8570 @item @emph{Syntax}:
8571 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
8573 @item @emph{Arguments}:
8574 @multitable @columnfractions .15 .70
8575 @item @var{I} @tab The type shall be @code{INTEGER}.
8576 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8577 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
8578 the value must be greater than zero and less than or equal to
8582 @item @emph{Return value}:
8583 The return value is of type @code{INTEGER} and of the same kind as
8586 @item @emph{Specific names}:
8587 @multitable @columnfractions .20 .20 .20 .25
8588 @item Name @tab Argument @tab Return type @tab Standard
8589 @item @code{ISHFTC(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
8590 @item @code{BSHFTC(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8591 @item @code{IISHFTC(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8592 @item @code{JISHFTC(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8593 @item @code{KISHFTC(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8596 @item @emph{See also}:
8603 @section @code{ISNAN} --- Test for a NaN
8608 @item @emph{Description}:
8609 @code{ISNAN} tests whether a floating-point value is an IEEE
8611 @item @emph{Standard}:
8617 @item @emph{Syntax}:
8620 @item @emph{Arguments}:
8621 @multitable @columnfractions .15 .70
8622 @item @var{X} @tab Variable of the type @code{REAL}.
8626 @item @emph{Return value}:
8627 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
8628 if @var{X} is a NaN and @code{FALSE} otherwise.
8630 @item @emph{Example}:
8637 if (isnan(x)) stop '"x" is a NaN'
8638 end program test_nan
8645 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
8647 @cindex time, current
8648 @cindex current time
8651 @item @emph{Description}:
8652 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
8653 current local time. The hour (in the range 1-24), minute (in the range 1-60),
8654 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
8657 @item @emph{Standard}:
8663 @item @emph{Syntax}:
8664 @code{CALL ITIME(VALUES)}
8666 @item @emph{Arguments}:
8667 @multitable @columnfractions .15 .70
8668 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
8669 and the kind shall be the default integer kind.
8672 @item @emph{Return value}:
8673 Does not return anything.
8676 @item @emph{Example}:
8679 integer, dimension(3) :: tarray
8684 end program test_itime
8691 @section @code{KILL} --- Send a signal to a process
8695 @item @emph{Description}:
8696 @item @emph{Standard}:
8697 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
8700 This intrinsic is provided in both subroutine and function forms; however,
8701 only one form can be used in any given program unit.
8704 Subroutine, function
8706 @item @emph{Syntax}:
8707 @multitable @columnfractions .80
8708 @item @code{CALL KILL(C, VALUE [, STATUS])}
8709 @item @code{STATUS = KILL(C, VALUE)}
8712 @item @emph{Arguments}:
8713 @multitable @columnfractions .15 .70
8714 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
8716 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
8718 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
8719 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
8723 @item @emph{See also}:
8724 @ref{ABORT}, @ref{EXIT}
8730 @section @code{KIND} --- Kind of an entity
8735 @item @emph{Description}:
8736 @code{KIND(X)} returns the kind value of the entity @var{X}.
8738 @item @emph{Standard}:
8739 Fortran 95 and later
8744 @item @emph{Syntax}:
8747 @item @emph{Arguments}:
8748 @multitable @columnfractions .15 .70
8749 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
8750 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
8753 @item @emph{Return value}:
8754 The return value is a scalar of type @code{INTEGER} and of the default
8757 @item @emph{Example}:
8760 integer,parameter :: kc = kind(' ')
8761 integer,parameter :: kl = kind(.true.)
8763 print *, "The default character kind is ", kc
8764 print *, "The default logical kind is ", kl
8765 end program test_kind
8773 @section @code{LBOUND} --- Lower dimension bounds of an array
8775 @cindex array, lower bound
8778 @item @emph{Description}:
8779 Returns the lower bounds of an array, or a single lower bound
8780 along the @var{DIM} dimension.
8781 @item @emph{Standard}:
8782 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
8787 @item @emph{Syntax}:
8788 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
8790 @item @emph{Arguments}:
8791 @multitable @columnfractions .15 .70
8792 @item @var{ARRAY} @tab Shall be an array, of any type.
8793 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
8794 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8795 expression indicating the kind parameter of the result.
8798 @item @emph{Return value}:
8799 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8800 @var{KIND} is absent, the return value is of default integer kind.
8801 If @var{DIM} is absent, the result is an array of the lower bounds of
8802 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
8803 corresponding to the lower bound of the array along that dimension. If
8804 @var{ARRAY} is an expression rather than a whole array or array
8805 structure component, or if it has a zero extent along the relevant
8806 dimension, the lower bound is taken to be 1.
8808 @item @emph{See also}:
8809 @ref{UBOUND}, @ref{LCOBOUND}
8815 @section @code{LCOBOUND} --- Lower codimension bounds of an array
8817 @cindex coarray, lower bound
8820 @item @emph{Description}:
8821 Returns the lower bounds of a coarray, or a single lower cobound
8822 along the @var{DIM} codimension.
8823 @item @emph{Standard}:
8824 Fortran 2008 and later
8829 @item @emph{Syntax}:
8830 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
8832 @item @emph{Arguments}:
8833 @multitable @columnfractions .15 .70
8834 @item @var{ARRAY} @tab Shall be an coarray, of any type.
8835 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
8836 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8837 expression indicating the kind parameter of the result.
8840 @item @emph{Return value}:
8841 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8842 @var{KIND} is absent, the return value is of default integer kind.
8843 If @var{DIM} is absent, the result is an array of the lower cobounds of
8844 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
8845 corresponding to the lower cobound of the array along that codimension.
8847 @item @emph{See also}:
8848 @ref{UCOBOUND}, @ref{LBOUND}
8854 @section @code{LEADZ} --- Number of leading zero bits of an integer
8859 @item @emph{Description}:
8860 @code{LEADZ} returns the number of leading zero bits of an integer.
8862 @item @emph{Standard}:
8863 Fortran 2008 and later
8868 @item @emph{Syntax}:
8869 @code{RESULT = LEADZ(I)}
8871 @item @emph{Arguments}:
8872 @multitable @columnfractions .15 .70
8873 @item @var{I} @tab Shall be of type @code{INTEGER}.
8876 @item @emph{Return value}:
8877 The type of the return value is the default @code{INTEGER}.
8878 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
8880 @item @emph{Example}:
8883 WRITE (*,*) BIT_SIZE(1) ! prints 32
8884 WRITE (*,*) LEADZ(1) ! prints 31
8888 @item @emph{See also}:
8889 @ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR}
8895 @section @code{LEN} --- Length of a character entity
8897 @cindex string, length
8900 @item @emph{Description}:
8901 Returns the length of a character string. If @var{STRING} is an array,
8902 the length of an element of @var{STRING} is returned. Note that
8903 @var{STRING} need not be defined when this intrinsic is invoked, since
8904 only the length, not the content, of @var{STRING} is needed.
8906 @item @emph{Standard}:
8907 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
8912 @item @emph{Syntax}:
8913 @code{L = LEN(STRING [, KIND])}
8915 @item @emph{Arguments}:
8916 @multitable @columnfractions .15 .70
8917 @item @var{STRING} @tab Shall be a scalar or array of type
8918 @code{CHARACTER}, with @code{INTENT(IN)}
8919 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8920 expression indicating the kind parameter of the result.
8923 @item @emph{Return value}:
8924 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8925 @var{KIND} is absent, the return value is of default integer kind.
8928 @item @emph{Specific names}:
8929 @multitable @columnfractions .20 .20 .20 .25
8930 @item Name @tab Argument @tab Return type @tab Standard
8931 @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
8935 @item @emph{See also}:
8936 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
8942 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
8944 @cindex string, length, without trailing whitespace
8947 @item @emph{Description}:
8948 Returns the length of a character string, ignoring any trailing blanks.
8950 @item @emph{Standard}:
8951 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
8956 @item @emph{Syntax}:
8957 @code{RESULT = LEN_TRIM(STRING [, KIND])}
8959 @item @emph{Arguments}:
8960 @multitable @columnfractions .15 .70
8961 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
8962 with @code{INTENT(IN)}
8963 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8964 expression indicating the kind parameter of the result.
8967 @item @emph{Return value}:
8968 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8969 @var{KIND} is absent, the return value is of default integer kind.
8971 @item @emph{See also}:
8972 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
8978 @section @code{LGE} --- Lexical greater than or equal
8980 @cindex lexical comparison of strings
8981 @cindex string, comparison
8984 @item @emph{Description}:
8985 Determines whether one string is lexically greater than or equal to
8986 another string, where the two strings are interpreted as containing
8987 ASCII character codes. If the String A and String B are not the same
8988 length, the shorter is compared as if spaces were appended to it to form
8989 a value that has the same length as the longer.
8991 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
8992 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
8993 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
8994 that the latter use the processor's character ordering (which is not
8995 ASCII on some targets), whereas the former always use the ASCII
8998 @item @emph{Standard}:
8999 Fortran 77 and later
9004 @item @emph{Syntax}:
9005 @code{RESULT = LGE(STRING_A, STRING_B)}
9007 @item @emph{Arguments}:
9008 @multitable @columnfractions .15 .70
9009 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9010 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9013 @item @emph{Return value}:
9014 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
9015 otherwise, based on the ASCII ordering.
9017 @item @emph{Specific names}:
9018 @multitable @columnfractions .20 .20 .20 .25
9019 @item Name @tab Argument @tab Return type @tab Standard
9020 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9023 @item @emph{See also}:
9024 @ref{LGT}, @ref{LLE}, @ref{LLT}
9030 @section @code{LGT} --- Lexical greater than
9032 @cindex lexical comparison of strings
9033 @cindex string, comparison
9036 @item @emph{Description}:
9037 Determines whether one string is lexically greater than another string,
9038 where the two strings are interpreted as containing ASCII character
9039 codes. If the String A and String B are not the same length, the
9040 shorter is compared as if spaces were appended to it to form a value
9041 that has the same length as the longer.
9043 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9044 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9045 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9046 that the latter use the processor's character ordering (which is not
9047 ASCII on some targets), whereas the former always use the ASCII
9050 @item @emph{Standard}:
9051 Fortran 77 and later
9056 @item @emph{Syntax}:
9057 @code{RESULT = LGT(STRING_A, STRING_B)}
9059 @item @emph{Arguments}:
9060 @multitable @columnfractions .15 .70
9061 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9062 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9065 @item @emph{Return value}:
9066 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
9067 otherwise, based on the ASCII ordering.
9069 @item @emph{Specific names}:
9070 @multitable @columnfractions .20 .20 .20 .25
9071 @item Name @tab Argument @tab Return type @tab Standard
9072 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9075 @item @emph{See also}:
9076 @ref{LGE}, @ref{LLE}, @ref{LLT}
9082 @section @code{LINK} --- Create a hard link
9084 @cindex file system, create link
9085 @cindex file system, hard link
9088 @item @emph{Description}:
9089 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
9090 character (@code{CHAR(0)}) can be used to mark the end of the names in
9091 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
9092 names are ignored. If the @var{STATUS} argument is supplied, it
9093 contains 0 on success or a nonzero error code upon return; see
9096 This intrinsic is provided in both subroutine and function forms;
9097 however, only one form can be used in any given program unit.
9099 @item @emph{Standard}:
9103 Subroutine, function
9105 @item @emph{Syntax}:
9106 @multitable @columnfractions .80
9107 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
9108 @item @code{STATUS = LINK(PATH1, PATH2)}
9111 @item @emph{Arguments}:
9112 @multitable @columnfractions .15 .70
9113 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
9114 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
9115 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9118 @item @emph{See also}:
9119 @ref{SYMLNK}, @ref{UNLINK}
9125 @section @code{LLE} --- Lexical less than or equal
9127 @cindex lexical comparison of strings
9128 @cindex string, comparison
9131 @item @emph{Description}:
9132 Determines whether one string is lexically less than or equal to another
9133 string, where the two strings are interpreted as containing ASCII
9134 character codes. If the String A and String B are not the same length,
9135 the shorter is compared as if spaces were appended to it to form a value
9136 that has the same length as the longer.
9138 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9139 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9140 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9141 that the latter use the processor's character ordering (which is not
9142 ASCII on some targets), whereas the former always use the ASCII
9145 @item @emph{Standard}:
9146 Fortran 77 and later
9151 @item @emph{Syntax}:
9152 @code{RESULT = LLE(STRING_A, STRING_B)}
9154 @item @emph{Arguments}:
9155 @multitable @columnfractions .15 .70
9156 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9157 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9160 @item @emph{Return value}:
9161 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
9162 otherwise, based on the ASCII ordering.
9164 @item @emph{Specific names}:
9165 @multitable @columnfractions .20 .20 .20 .25
9166 @item Name @tab Argument @tab Return type @tab Standard
9167 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9170 @item @emph{See also}:
9171 @ref{LGE}, @ref{LGT}, @ref{LLT}
9177 @section @code{LLT} --- Lexical less than
9179 @cindex lexical comparison of strings
9180 @cindex string, comparison
9183 @item @emph{Description}:
9184 Determines whether one string is lexically less than another string,
9185 where the two strings are interpreted as containing ASCII character
9186 codes. If the String A and String B are not the same length, the
9187 shorter is compared as if spaces were appended to it to form a value
9188 that has the same length as the longer.
9190 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9191 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9192 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9193 that the latter use the processor's character ordering (which is not
9194 ASCII on some targets), whereas the former always use the ASCII
9197 @item @emph{Standard}:
9198 Fortran 77 and later
9203 @item @emph{Syntax}:
9204 @code{RESULT = LLT(STRING_A, STRING_B)}
9206 @item @emph{Arguments}:
9207 @multitable @columnfractions .15 .70
9208 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9209 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9212 @item @emph{Return value}:
9213 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
9214 otherwise, based on the ASCII ordering.
9216 @item @emph{Specific names}:
9217 @multitable @columnfractions .20 .20 .20 .25
9218 @item Name @tab Argument @tab Return type @tab Standard
9219 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9222 @item @emph{See also}:
9223 @ref{LGE}, @ref{LGT}, @ref{LLE}
9229 @section @code{LNBLNK} --- Index of the last non-blank character in a string
9231 @cindex string, find non-blank character
9234 @item @emph{Description}:
9235 Returns the length of a character string, ignoring any trailing blanks.
9236 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
9237 included for backwards compatibility.
9239 @item @emph{Standard}:
9245 @item @emph{Syntax}:
9246 @code{RESULT = LNBLNK(STRING)}
9248 @item @emph{Arguments}:
9249 @multitable @columnfractions .15 .70
9250 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
9251 with @code{INTENT(IN)}
9254 @item @emph{Return value}:
9255 The return value is of @code{INTEGER(kind=4)} type.
9257 @item @emph{See also}:
9258 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
9264 @section @code{LOC} --- Returns the address of a variable
9266 @cindex location of a variable in memory
9269 @item @emph{Description}:
9270 @code{LOC(X)} returns the address of @var{X} as an integer.
9272 @item @emph{Standard}:
9278 @item @emph{Syntax}:
9279 @code{RESULT = LOC(X)}
9281 @item @emph{Arguments}:
9282 @multitable @columnfractions .15 .70
9283 @item @var{X} @tab Variable of any type.
9286 @item @emph{Return value}:
9287 The return value is of type @code{INTEGER}, with a @code{KIND}
9288 corresponding to the size (in bytes) of a memory address on the target
9291 @item @emph{Example}:
9298 end program test_loc
9305 @section @code{LOG} --- Natural logarithm function
9312 @cindex exponential function, inverse
9313 @cindex logarithm function
9314 @cindex natural logarithm function
9317 @item @emph{Description}:
9318 @code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the
9319 logarithm to the base @math{e}.
9321 @item @emph{Standard}:
9322 Fortran 77 and later
9327 @item @emph{Syntax}:
9328 @code{RESULT = LOG(X)}
9330 @item @emph{Arguments}:
9331 @multitable @columnfractions .15 .70
9332 @item @var{X} @tab The type shall be @code{REAL} or
9336 @item @emph{Return value}:
9337 The return value is of type @code{REAL} or @code{COMPLEX}.
9338 The kind type parameter is the same as @var{X}.
9339 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
9340 @math{-\pi < \omega \leq \pi}.
9342 @item @emph{Example}:
9345 real(8) :: x = 2.7182818284590451_8
9346 complex :: z = (1.0, 2.0)
9347 x = log(x) ! will yield (approximately) 1
9349 end program test_log
9352 @item @emph{Specific names}:
9353 @multitable @columnfractions .20 .20 .20 .25
9354 @item Name @tab Argument @tab Return type @tab Standard
9355 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
9356 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
9357 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
9358 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9359 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9366 @section @code{LOG10} --- Base 10 logarithm function
9370 @cindex exponential function, inverse
9371 @cindex logarithm function with base 10
9372 @cindex base 10 logarithm function
9375 @item @emph{Description}:
9376 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
9378 @item @emph{Standard}:
9379 Fortran 77 and later
9384 @item @emph{Syntax}:
9385 @code{RESULT = LOG10(X)}
9387 @item @emph{Arguments}:
9388 @multitable @columnfractions .15 .70
9389 @item @var{X} @tab The type shall be @code{REAL}.
9392 @item @emph{Return value}:
9393 The return value is of type @code{REAL} or @code{COMPLEX}.
9394 The kind type parameter is the same as @var{X}.
9396 @item @emph{Example}:
9399 real(8) :: x = 10.0_8
9401 end program test_log10
9404 @item @emph{Specific names}:
9405 @multitable @columnfractions .20 .20 .20 .25
9406 @item Name @tab Argument @tab Return type @tab Standard
9407 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
9408 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
9415 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
9420 @cindex Gamma function, logarithm of
9423 @item @emph{Description}:
9424 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
9425 of the Gamma (@math{\Gamma}) function.
9427 @item @emph{Standard}:
9428 Fortran 2008 and later
9433 @item @emph{Syntax}:
9434 @code{X = LOG_GAMMA(X)}
9436 @item @emph{Arguments}:
9437 @multitable @columnfractions .15 .70
9438 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
9439 nor a negative integer.
9442 @item @emph{Return value}:
9443 The return value is of type @code{REAL} of the same kind as @var{X}.
9445 @item @emph{Example}:
9447 program test_log_gamma
9449 x = lgamma(x) ! returns 0.0
9450 end program test_log_gamma
9453 @item @emph{Specific names}:
9454 @multitable @columnfractions .20 .20 .20 .25
9455 @item Name @tab Argument @tab Return type @tab Standard
9456 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
9457 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
9458 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
9461 @item @emph{See also}:
9462 Gamma function: @ref{GAMMA}
9469 @section @code{LOGICAL} --- Convert to logical type
9471 @cindex conversion, to logical
9474 @item @emph{Description}:
9475 Converts one kind of @code{LOGICAL} variable to another.
9477 @item @emph{Standard}:
9478 Fortran 95 and later
9483 @item @emph{Syntax}:
9484 @code{RESULT = LOGICAL(L [, KIND])}
9486 @item @emph{Arguments}:
9487 @multitable @columnfractions .15 .70
9488 @item @var{L} @tab The type shall be @code{LOGICAL}.
9489 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9490 expression indicating the kind parameter of the result.
9493 @item @emph{Return value}:
9494 The return value is a @code{LOGICAL} value equal to @var{L}, with a
9495 kind corresponding to @var{KIND}, or of the default logical kind if
9496 @var{KIND} is not given.
9498 @item @emph{See also}:
9499 @ref{INT}, @ref{REAL}, @ref{CMPLX}
9505 @section @code{LONG} --- Convert to integer type
9507 @cindex conversion, to integer
9510 @item @emph{Description}:
9511 Convert to a @code{KIND=4} integer type, which is the same size as a C
9512 @code{long} integer. This is equivalent to the standard @code{INT}
9513 intrinsic with an optional argument of @code{KIND=4}, and is only
9514 included for backwards compatibility.
9516 @item @emph{Standard}:
9522 @item @emph{Syntax}:
9523 @code{RESULT = LONG(A)}
9525 @item @emph{Arguments}:
9526 @multitable @columnfractions .15 .70
9527 @item @var{A} @tab Shall be of type @code{INTEGER},
9528 @code{REAL}, or @code{COMPLEX}.
9531 @item @emph{Return value}:
9532 The return value is a @code{INTEGER(4)} variable.
9534 @item @emph{See also}:
9535 @ref{INT}, @ref{INT2}, @ref{INT8}
9541 @section @code{LSHIFT} --- Left shift bits
9543 @cindex bits, shift left
9546 @item @emph{Description}:
9547 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
9548 bits shifted left by @var{SHIFT} places. If the absolute value of
9549 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
9550 Bits shifted out from the left end are lost; zeros are shifted in from
9553 This function has been superseded by the @code{ISHFT} intrinsic, which
9554 is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
9555 which is standard in Fortran 2008 and later.
9557 @item @emph{Standard}:
9563 @item @emph{Syntax}:
9564 @code{RESULT = LSHIFT(I, SHIFT)}
9566 @item @emph{Arguments}:
9567 @multitable @columnfractions .15 .70
9568 @item @var{I} @tab The type shall be @code{INTEGER}.
9569 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
9572 @item @emph{Return value}:
9573 The return value is of type @code{INTEGER} and of the same kind as
9576 @item @emph{See also}:
9577 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}, @ref{SHIFTA}, @ref{SHIFTL},
9585 @section @code{LSTAT} --- Get file status
9587 @cindex file system, file status
9590 @item @emph{Description}:
9591 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
9592 symbolic link, then the link itself is statted, not the file that it
9595 The elements in @code{VALUES} are the same as described by @ref{STAT}.
9597 This intrinsic is provided in both subroutine and function forms;
9598 however, only one form can be used in any given program unit.
9600 @item @emph{Standard}:
9604 Subroutine, function
9606 @item @emph{Syntax}:
9607 @multitable @columnfractions .80
9608 @item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
9609 @item @code{STATUS = LSTAT(NAME, VALUES)}
9612 @item @emph{Arguments}:
9613 @multitable @columnfractions .15 .70
9614 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
9615 kind, a valid path within the file system.
9616 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
9617 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
9618 Returns 0 on success and a system specific error code otherwise.
9621 @item @emph{Example}:
9622 See @ref{STAT} for an example.
9624 @item @emph{See also}:
9625 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
9631 @section @code{LTIME} --- Convert time to local time info
9633 @cindex time, conversion to local time info
9636 @item @emph{Description}:
9637 Given a system time value @var{TIME} (as provided by the @code{TIME8}
9638 intrinsic), fills @var{VALUES} with values extracted from it appropriate
9639 to the local time zone using @code{localtime(3)}.
9641 @item @emph{Standard}:
9647 @item @emph{Syntax}:
9648 @code{CALL LTIME(TIME, VALUES)}
9650 @item @emph{Arguments}:
9651 @multitable @columnfractions .15 .70
9652 @item @var{TIME} @tab An @code{INTEGER} scalar expression
9653 corresponding to a system time, with @code{INTENT(IN)}.
9654 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
9655 with @code{INTENT(OUT)}.
9658 @item @emph{Return value}:
9659 The elements of @var{VALUES} are assigned as follows:
9661 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
9663 @item Minutes after the hour, range 0--59
9664 @item Hours past midnight, range 0--23
9665 @item Day of month, range 0--31
9666 @item Number of months since January, range 0--12
9667 @item Years since 1900
9668 @item Number of days since Sunday, range 0--6
9669 @item Days since January 1
9670 @item Daylight savings indicator: positive if daylight savings is in
9671 effect, zero if not, and negative if the information is not available.
9674 @item @emph{See also}:
9675 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
9682 @section @code{MALLOC} --- Allocate dynamic memory
9684 @cindex pointer, cray
9687 @item @emph{Description}:
9688 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
9689 returns the address of the allocated memory. The @code{MALLOC} intrinsic
9690 is an extension intended to be used with Cray pointers, and is provided
9691 in GNU Fortran to allow the user to compile legacy code. For new code
9692 using Fortran 95 pointers, the memory allocation intrinsic is
9695 @item @emph{Standard}:
9701 @item @emph{Syntax}:
9702 @code{PTR = MALLOC(SIZE)}
9704 @item @emph{Arguments}:
9705 @multitable @columnfractions .15 .70
9706 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
9709 @item @emph{Return value}:
9710 The return value is of type @code{INTEGER(K)}, with @var{K} such that
9711 variables of type @code{INTEGER(K)} have the same size as
9712 C pointers (@code{sizeof(void *)}).
9714 @item @emph{Example}:
9715 The following example demonstrates the use of @code{MALLOC} and
9716 @code{FREE} with Cray pointers.
9725 ptr_x = malloc(20*8)
9727 x(i) = sqrt(1.0d0 / i)
9735 end program test_malloc
9738 @item @emph{See also}:
9745 @section @code{MASKL} --- Left justified mask
9747 @cindex mask, left justified
9750 @item @emph{Description}:
9751 @code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
9752 remaining bits set to 0.
9754 @item @emph{Standard}:
9755 Fortran 2008 and later
9760 @item @emph{Syntax}:
9761 @code{RESULT = MASKL(I[, KIND])}
9763 @item @emph{Arguments}:
9764 @multitable @columnfractions .15 .70
9765 @item @var{I} @tab Shall be of type @code{INTEGER}.
9766 @item @var{KIND} @tab Shall be a scalar constant expression of type
9770 @item @emph{Return value}:
9771 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
9772 specifies the kind value of the return type; otherwise, it is of the
9773 default integer kind.
9775 @item @emph{See also}:
9782 @section @code{MASKR} --- Right justified mask
9784 @cindex mask, right justified
9787 @item @emph{Description}:
9788 @code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
9789 remaining bits set to 0.
9791 @item @emph{Standard}:
9792 Fortran 2008 and later
9797 @item @emph{Syntax}:
9798 @code{RESULT = MASKR(I[, KIND])}
9800 @item @emph{Arguments}:
9801 @multitable @columnfractions .15 .70
9802 @item @var{I} @tab Shall be of type @code{INTEGER}.
9803 @item @var{KIND} @tab Shall be a scalar constant expression of type
9807 @item @emph{Return value}:
9808 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
9809 specifies the kind value of the return type; otherwise, it is of the
9810 default integer kind.
9812 @item @emph{See also}:
9819 @section @code{MATMUL} --- matrix multiplication
9821 @cindex matrix multiplication
9822 @cindex product, matrix
9825 @item @emph{Description}:
9826 Performs a matrix multiplication on numeric or logical arguments.
9828 @item @emph{Standard}:
9829 Fortran 95 and later
9832 Transformational function
9834 @item @emph{Syntax}:
9835 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
9837 @item @emph{Arguments}:
9838 @multitable @columnfractions .15 .70
9839 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
9840 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
9842 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
9843 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
9844 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
9845 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
9846 equal to the last (or only) dimension of @var{MATRIX_A}.
9849 @item @emph{Return value}:
9850 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
9851 kind of the result follow the usual type and kind promotion rules, as
9852 for the @code{*} or @code{.AND.} operators.
9854 @item @emph{See also}:
9860 @section @code{MAX} --- Maximum value of an argument list
9867 @cindex maximum value
9870 @item @emph{Description}:
9871 Returns the argument with the largest (most positive) value.
9873 @item @emph{Standard}:
9874 Fortran 77 and later
9879 @item @emph{Syntax}:
9880 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
9882 @item @emph{Arguments}:
9883 @multitable @columnfractions .15 .70
9884 @item @var{A1} @tab The type shall be @code{INTEGER} or
9886 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
9887 as @var{A1}. (As a GNU extension, arguments of different kinds are
9891 @item @emph{Return value}:
9892 The return value corresponds to the maximum value among the arguments,
9893 and has the same type and kind as the first argument.
9895 @item @emph{Specific names}:
9896 @multitable @columnfractions .20 .20 .20 .25
9897 @item Name @tab Argument @tab Return type @tab Standard
9898 @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
9899 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
9900 @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
9901 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
9902 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
9905 @item @emph{See also}:
9906 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
9913 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
9914 @fnindex MAXEXPONENT
9915 @cindex model representation, maximum exponent
9918 @item @emph{Description}:
9919 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
9922 @item @emph{Standard}:
9923 Fortran 95 and later
9928 @item @emph{Syntax}:
9929 @code{RESULT = MAXEXPONENT(X)}
9931 @item @emph{Arguments}:
9932 @multitable @columnfractions .15 .70
9933 @item @var{X} @tab Shall be of type @code{REAL}.
9936 @item @emph{Return value}:
9937 The return value is of type @code{INTEGER} and of the default integer
9940 @item @emph{Example}:
9946 print *, minexponent(x), maxexponent(x)
9947 print *, minexponent(y), maxexponent(y)
9948 end program exponents
9955 @section @code{MAXLOC} --- Location of the maximum value within an array
9957 @cindex array, location of maximum element
9960 @item @emph{Description}:
9961 Determines the location of the element in the array with the maximum
9962 value, or, if the @var{DIM} argument is supplied, determines the
9963 locations of the maximum element along each row of the array in the
9964 @var{DIM} direction. If @var{MASK} is present, only the elements for
9965 which @var{MASK} is @code{.TRUE.} are considered. If more than one
9966 element in the array has the maximum value, the location returned is
9967 that of the first such element in array element order. If the array has
9968 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
9969 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
9970 and all of the elements of @var{MASK} along a given row are zero, the
9971 result value for that row is zero.
9973 @item @emph{Standard}:
9974 Fortran 95 and later
9977 Transformational function
9979 @item @emph{Syntax}:
9980 @multitable @columnfractions .80
9981 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
9982 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
9985 @item @emph{Arguments}:
9986 @multitable @columnfractions .15 .70
9987 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
9989 @item @var{DIM} @tab (Optional) Shall be a scalar of type
9990 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
9991 inclusive. It may not be an optional dummy argument.
9992 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
9993 and conformable with @var{ARRAY}.
9996 @item @emph{Return value}:
9997 If @var{DIM} is absent, the result is a rank-one array with a length
9998 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
9999 is an array with a rank one less than the rank of @var{ARRAY}, and a
10000 size corresponding to the size of @var{ARRAY} with the @var{DIM}
10001 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
10002 of one, the result is a scalar. In all cases, the result is of default
10003 @code{INTEGER} type.
10005 @item @emph{See also}:
10006 @ref{MAX}, @ref{MAXVAL}
10013 @section @code{MAXVAL} --- Maximum value of an array
10015 @cindex array, maximum value
10016 @cindex maximum value
10019 @item @emph{Description}:
10020 Determines the maximum value of the elements in an array value, or, if
10021 the @var{DIM} argument is supplied, determines the maximum value along
10022 each row of the array in the @var{DIM} direction. If @var{MASK} is
10023 present, only the elements for which @var{MASK} is @code{.TRUE.} are
10024 considered. If the array has zero size, or all of the elements of
10025 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
10026 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
10029 @item @emph{Standard}:
10030 Fortran 95 and later
10032 @item @emph{Class}:
10033 Transformational function
10035 @item @emph{Syntax}:
10036 @multitable @columnfractions .80
10037 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
10038 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
10041 @item @emph{Arguments}:
10042 @multitable @columnfractions .15 .70
10043 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10045 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10046 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10047 inclusive. It may not be an optional dummy argument.
10048 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
10049 and conformable with @var{ARRAY}.
10052 @item @emph{Return value}:
10053 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
10054 is a scalar. If @var{DIM} is present, the result is an array with a
10055 rank one less than the rank of @var{ARRAY}, and a size corresponding to
10056 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
10057 cases, the result is of the same type and kind as @var{ARRAY}.
10059 @item @emph{See also}:
10060 @ref{MAX}, @ref{MAXLOC}
10066 @section @code{MCLOCK} --- Time function
10068 @cindex time, clock ticks
10069 @cindex clock ticks
10072 @item @emph{Description}:
10073 Returns the number of clock ticks since the start of the process, based
10074 on the function @code{clock(3)} in the C standard library.
10076 This intrinsic is not fully portable, such as to systems with 32-bit
10077 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
10078 the values returned by this intrinsic might be, or become, negative, or
10079 numerically less than previous values, during a single run of the
10082 @item @emph{Standard}:
10085 @item @emph{Class}:
10088 @item @emph{Syntax}:
10089 @code{RESULT = MCLOCK()}
10091 @item @emph{Return value}:
10092 The return value is a scalar of type @code{INTEGER(4)}, equal to the
10093 number of clock ticks since the start of the process, or @code{-1} if
10094 the system does not support @code{clock(3)}.
10096 @item @emph{See also}:
10097 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
10104 @section @code{MCLOCK8} --- Time function (64-bit)
10106 @cindex time, clock ticks
10107 @cindex clock ticks
10110 @item @emph{Description}:
10111 Returns the number of clock ticks since the start of the process, based
10112 on the function @code{clock(3)} in the C standard library.
10114 @emph{Warning:} this intrinsic does not increase the range of the timing
10115 values over that returned by @code{clock(3)}. On a system with a 32-bit
10116 @code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though
10117 it is converted to a 64-bit @code{INTEGER(8)} value. That means
10118 overflows of the 32-bit value can still occur. Therefore, the values
10119 returned by this intrinsic might be or become negative or numerically
10120 less than previous values during a single run of the compiled program.
10122 @item @emph{Standard}:
10125 @item @emph{Class}:
10128 @item @emph{Syntax}:
10129 @code{RESULT = MCLOCK8()}
10131 @item @emph{Return value}:
10132 The return value is a scalar of type @code{INTEGER(8)}, equal to the
10133 number of clock ticks since the start of the process, or @code{-1} if
10134 the system does not support @code{clock(3)}.
10136 @item @emph{See also}:
10137 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
10144 @section @code{MERGE} --- Merge variables
10146 @cindex array, merge arrays
10147 @cindex array, combine arrays
10150 @item @emph{Description}:
10151 Select values from two arrays according to a logical mask. The result
10152 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
10153 @var{FSOURCE} if it is @code{.FALSE.}.
10155 @item @emph{Standard}:
10156 Fortran 95 and later
10158 @item @emph{Class}:
10161 @item @emph{Syntax}:
10162 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
10164 @item @emph{Arguments}:
10165 @multitable @columnfractions .15 .70
10166 @item @var{TSOURCE} @tab May be of any type.
10167 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
10169 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
10172 @item @emph{Return value}:
10173 The result is of the same type and type parameters as @var{TSOURCE}.
10180 @section @code{MERGE_BITS} --- Merge of bits under mask
10181 @fnindex MERGE_BITS
10182 @cindex bits, merge
10185 @item @emph{Description}:
10186 @code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
10187 as determined by the mask. The i-th bit of the result is equal to the
10188 i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
10189 the i-th bit of @var{J} otherwise.
10191 @item @emph{Standard}:
10192 Fortran 2008 and later
10194 @item @emph{Class}:
10197 @item @emph{Syntax}:
10198 @code{RESULT = MERGE_BITS(I, J, MASK)}
10200 @item @emph{Arguments}:
10201 @multitable @columnfractions .15 .70
10202 @item @var{I} @tab Shall be of type @code{INTEGER}.
10203 @item @var{J} @tab Shall be of type @code{INTEGER} and of the same
10205 @item @var{MASK} @tab Shall be of type @code{INTEGER} and of the same
10209 @item @emph{Return value}:
10210 The result is of the same type and kind as @var{I}.
10217 @section @code{MIN} --- Minimum value of an argument list
10224 @cindex minimum value
10227 @item @emph{Description}:
10228 Returns the argument with the smallest (most negative) value.
10230 @item @emph{Standard}:
10231 Fortran 77 and later
10233 @item @emph{Class}:
10236 @item @emph{Syntax}:
10237 @code{RESULT = MIN(A1, A2 [, A3, ...])}
10239 @item @emph{Arguments}:
10240 @multitable @columnfractions .15 .70
10241 @item @var{A1} @tab The type shall be @code{INTEGER} or
10243 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
10244 as @var{A1}. (As a GNU extension, arguments of different kinds are
10248 @item @emph{Return value}:
10249 The return value corresponds to the maximum value among the arguments,
10250 and has the same type and kind as the first argument.
10252 @item @emph{Specific names}:
10253 @multitable @columnfractions .20 .20 .20 .25
10254 @item Name @tab Argument @tab Return type @tab Standard
10255 @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
10256 @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
10257 @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
10258 @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
10259 @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
10262 @item @emph{See also}:
10263 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
10269 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
10270 @fnindex MINEXPONENT
10271 @cindex model representation, minimum exponent
10274 @item @emph{Description}:
10275 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
10278 @item @emph{Standard}:
10279 Fortran 95 and later
10281 @item @emph{Class}:
10284 @item @emph{Syntax}:
10285 @code{RESULT = MINEXPONENT(X)}
10287 @item @emph{Arguments}:
10288 @multitable @columnfractions .15 .70
10289 @item @var{X} @tab Shall be of type @code{REAL}.
10292 @item @emph{Return value}:
10293 The return value is of type @code{INTEGER} and of the default integer
10296 @item @emph{Example}:
10297 See @code{MAXEXPONENT} for an example.
10303 @section @code{MINLOC} --- Location of the minimum value within an array
10305 @cindex array, location of minimum element
10308 @item @emph{Description}:
10309 Determines the location of the element in the array with the minimum
10310 value, or, if the @var{DIM} argument is supplied, determines the
10311 locations of the minimum element along each row of the array in the
10312 @var{DIM} direction. If @var{MASK} is present, only the elements for
10313 which @var{MASK} is @code{.TRUE.} are considered. If more than one
10314 element in the array has the minimum value, the location returned is
10315 that of the first such element in array element order. If the array has
10316 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
10317 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
10318 and all of the elements of @var{MASK} along a given row are zero, the
10319 result value for that row is zero.
10321 @item @emph{Standard}:
10322 Fortran 95 and later
10324 @item @emph{Class}:
10325 Transformational function
10327 @item @emph{Syntax}:
10328 @multitable @columnfractions .80
10329 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
10330 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
10333 @item @emph{Arguments}:
10334 @multitable @columnfractions .15 .70
10335 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10337 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10338 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10339 inclusive. It may not be an optional dummy argument.
10340 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
10341 and conformable with @var{ARRAY}.
10344 @item @emph{Return value}:
10345 If @var{DIM} is absent, the result is a rank-one array with a length
10346 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
10347 is an array with a rank one less than the rank of @var{ARRAY}, and a
10348 size corresponding to the size of @var{ARRAY} with the @var{DIM}
10349 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
10350 of one, the result is a scalar. In all cases, the result is of default
10351 @code{INTEGER} type.
10353 @item @emph{See also}:
10354 @ref{MIN}, @ref{MINVAL}
10361 @section @code{MINVAL} --- Minimum value of an array
10363 @cindex array, minimum value
10364 @cindex minimum value
10367 @item @emph{Description}:
10368 Determines the minimum value of the elements in an array value, or, if
10369 the @var{DIM} argument is supplied, determines the minimum value along
10370 each row of the array in the @var{DIM} direction. If @var{MASK} is
10371 present, only the elements for which @var{MASK} is @code{.TRUE.} are
10372 considered. If the array has zero size, or all of the elements of
10373 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
10374 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
10375 @var{ARRAY} is of character type.
10377 @item @emph{Standard}:
10378 Fortran 95 and later
10380 @item @emph{Class}:
10381 Transformational function
10383 @item @emph{Syntax}:
10384 @multitable @columnfractions .80
10385 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
10386 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
10389 @item @emph{Arguments}:
10390 @multitable @columnfractions .15 .70
10391 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10393 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10394 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10395 inclusive. It may not be an optional dummy argument.
10396 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
10397 and conformable with @var{ARRAY}.
10400 @item @emph{Return value}:
10401 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
10402 is a scalar. If @var{DIM} is present, the result is an array with a
10403 rank one less than the rank of @var{ARRAY}, and a size corresponding to
10404 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
10405 cases, the result is of the same type and kind as @var{ARRAY}.
10407 @item @emph{See also}:
10408 @ref{MIN}, @ref{MINLOC}
10415 @section @code{MOD} --- Remainder function
10424 @cindex division, remainder
10427 @item @emph{Description}:
10428 @code{MOD(A,P)} computes the remainder of the division of A by P@.
10430 @item @emph{Standard}:
10431 Fortran 77 and later, has overloads that are GNU extensions
10433 @item @emph{Class}:
10436 @item @emph{Syntax}:
10437 @code{RESULT = MOD(A, P)}
10439 @item @emph{Arguments}:
10440 @multitable @columnfractions .15 .70
10441 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
10442 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
10443 and not equal to zero.
10446 @item @emph{Return value}:
10447 The return value is the result of @code{A - (INT(A/P) * P)}. The type
10448 and kind of the return value is the same as that of the arguments. The
10449 returned value has the same sign as A and a magnitude less than the
10452 @item @emph{Example}:
10456 print *, mod(17.5,5.5)
10457 print *, mod(17.5d0,5.5)
10458 print *, mod(17.5,5.5d0)
10460 print *, mod(-17,3)
10461 print *, mod(-17.5,5.5)
10462 print *, mod(-17.5d0,5.5)
10463 print *, mod(-17.5,5.5d0)
10465 print *, mod(17,-3)
10466 print *, mod(17.5,-5.5)
10467 print *, mod(17.5d0,-5.5)
10468 print *, mod(17.5,-5.5d0)
10469 end program test_mod
10472 @item @emph{Specific names}:
10473 @multitable @columnfractions .20 .20 .20 .25
10474 @item Name @tab Arguments @tab Return type @tab Standard
10475 @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
10476 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
10477 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
10478 @item @code{BMOD(A,P)} @tab @code{INTEGER(1) A,P} @tab @code{INTEGER(1)} @tab GNU extension
10479 @item @code{IMOD(A,P)} @tab @code{INTEGER(2) A,P} @tab @code{INTEGER(2)} @tab GNU extension
10480 @item @code{JMOD(A,P)} @tab @code{INTEGER(4) A,P} @tab @code{INTEGER(4)} @tab GNU extension
10481 @item @code{KMOD(A,P)} @tab @code{INTEGER(8) A,P} @tab @code{INTEGER(8)} @tab GNU extension
10484 @item @emph{See also}:
10492 @section @code{MODULO} --- Modulo function
10495 @cindex division, modulo
10498 @item @emph{Description}:
10499 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
10501 @item @emph{Standard}:
10502 Fortran 95 and later
10504 @item @emph{Class}:
10507 @item @emph{Syntax}:
10508 @code{RESULT = MODULO(A, P)}
10510 @item @emph{Arguments}:
10511 @multitable @columnfractions .15 .70
10512 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
10513 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}.
10514 It shall not be zero.
10517 @item @emph{Return value}:
10518 The type and kind of the result are those of the arguments.
10520 @item If @var{A} and @var{P} are of type @code{INTEGER}:
10521 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
10522 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
10524 @item If @var{A} and @var{P} are of type @code{REAL}:
10525 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
10527 The returned value has the same sign as P and a magnitude less than
10528 the magnitude of P.
10530 @item @emph{Example}:
10532 program test_modulo
10533 print *, modulo(17,3)
10534 print *, modulo(17.5,5.5)
10536 print *, modulo(-17,3)
10537 print *, modulo(-17.5,5.5)
10539 print *, modulo(17,-3)
10540 print *, modulo(17.5,-5.5)
10544 @item @emph{See also}:
10552 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
10553 @fnindex MOVE_ALLOC
10554 @cindex moving allocation
10555 @cindex allocation, moving
10558 @item @emph{Description}:
10559 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
10560 @var{TO}. @var{FROM} will become deallocated in the process.
10562 @item @emph{Standard}:
10563 Fortran 2003 and later
10565 @item @emph{Class}:
10568 @item @emph{Syntax}:
10569 @code{CALL MOVE_ALLOC(FROM, TO)}
10571 @item @emph{Arguments}:
10572 @multitable @columnfractions .15 .70
10573 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
10574 of any type and kind.
10575 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
10576 of the same type, kind and rank as @var{FROM}.
10579 @item @emph{Return value}:
10582 @item @emph{Example}:
10584 program test_move_alloc
10585 integer, allocatable :: a(:), b(:)
10589 call move_alloc(a, b)
10590 print *, allocated(a), allocated(b)
10592 end program test_move_alloc
10599 @section @code{MVBITS} --- Move bits from one integer to another
10608 @item @emph{Description}:
10609 Moves @var{LEN} bits from positions @var{FROMPOS} through
10610 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
10611 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
10612 affected by the movement of bits is unchanged. The values of
10613 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
10614 @code{BIT_SIZE(FROM)}.
10616 @item @emph{Standard}:
10617 Fortran 95 and later, has overloads that are GNU extensions
10619 @item @emph{Class}:
10620 Elemental subroutine
10622 @item @emph{Syntax}:
10623 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
10625 @item @emph{Arguments}:
10626 @multitable @columnfractions .15 .70
10627 @item @var{FROM} @tab The type shall be @code{INTEGER}.
10628 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
10629 @item @var{LEN} @tab The type shall be @code{INTEGER}.
10630 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
10631 same kind as @var{FROM}.
10632 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
10635 @item @emph{Specific names}:
10636 @multitable @columnfractions .20 .20 .20 .25
10637 @item Name @tab Argument @tab Return type @tab Standard
10638 @item @code{MVBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
10639 @item @code{BMVBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
10640 @item @code{IMVBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
10641 @item @code{JMVBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
10642 @item @code{KMVBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
10645 @item @emph{See also}:
10646 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
10652 @section @code{NEAREST} --- Nearest representable number
10654 @cindex real number, nearest different
10655 @cindex floating point, nearest different
10658 @item @emph{Description}:
10659 @code{NEAREST(X, S)} returns the processor-representable number nearest
10660 to @code{X} in the direction indicated by the sign of @code{S}.
10662 @item @emph{Standard}:
10663 Fortran 95 and later
10665 @item @emph{Class}:
10668 @item @emph{Syntax}:
10669 @code{RESULT = NEAREST(X, S)}
10671 @item @emph{Arguments}:
10672 @multitable @columnfractions .15 .70
10673 @item @var{X} @tab Shall be of type @code{REAL}.
10674 @item @var{S} @tab Shall be of type @code{REAL} and
10678 @item @emph{Return value}:
10679 The return value is of the same type as @code{X}. If @code{S} is
10680 positive, @code{NEAREST} returns the processor-representable number
10681 greater than @code{X} and nearest to it. If @code{S} is negative,
10682 @code{NEAREST} returns the processor-representable number smaller than
10683 @code{X} and nearest to it.
10685 @item @emph{Example}:
10687 program test_nearest
10689 x = nearest(42.0, 1.0)
10690 y = nearest(42.0, -1.0)
10691 write (*,"(3(G20.15))") x, y, x - y
10692 end program test_nearest
10699 @section @code{NEW_LINE} --- New line character
10702 @cindex output, newline
10705 @item @emph{Description}:
10706 @code{NEW_LINE(C)} returns the new-line character.
10708 @item @emph{Standard}:
10709 Fortran 2003 and later
10711 @item @emph{Class}:
10714 @item @emph{Syntax}:
10715 @code{RESULT = NEW_LINE(C)}
10717 @item @emph{Arguments}:
10718 @multitable @columnfractions .15 .70
10719 @item @var{C} @tab The argument shall be a scalar or array of the
10720 type @code{CHARACTER}.
10723 @item @emph{Return value}:
10724 Returns a @var{CHARACTER} scalar of length one with the new-line character of
10725 the same kind as parameter @var{C}.
10727 @item @emph{Example}:
10731 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
10732 end program newline
10739 @section @code{NINT} --- Nearest whole number
10742 @cindex rounding, nearest whole number
10745 @item @emph{Description}:
10746 @code{NINT(A)} rounds its argument to the nearest whole number.
10748 @item @emph{Standard}:
10749 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
10751 @item @emph{Class}:
10754 @item @emph{Syntax}:
10755 @code{RESULT = NINT(A [, KIND])}
10757 @item @emph{Arguments}:
10758 @multitable @columnfractions .15 .70
10759 @item @var{A} @tab The type of the argument shall be @code{REAL}.
10760 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10761 expression indicating the kind parameter of the result.
10764 @item @emph{Return value}:
10765 Returns @var{A} with the fractional portion of its magnitude eliminated by
10766 rounding to the nearest whole number and with its sign preserved,
10767 converted to an @code{INTEGER} of the default kind.
10769 @item @emph{Example}:
10776 print *, nint(x4), idnint(x8)
10777 end program test_nint
10780 @item @emph{Specific names}:
10781 @multitable @columnfractions .20 .20 .20 .25
10782 @item Name @tab Argument @tab Return Type @tab Standard
10783 @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later
10784 @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later
10787 @item @emph{See also}:
10788 @ref{CEILING}, @ref{FLOOR}
10795 @section @code{NORM2} --- Euclidean vector norms
10797 @cindex Euclidean vector norm
10798 @cindex L2 vector norm
10799 @cindex norm, Euclidean
10802 @item @emph{Description}:
10803 Calculates the Euclidean vector norm (@math{L_2} norm) of
10804 of @var{ARRAY} along dimension @var{DIM}.
10806 @item @emph{Standard}:
10807 Fortran 2008 and later
10809 @item @emph{Class}:
10810 Transformational function
10812 @item @emph{Syntax}:
10813 @multitable @columnfractions .80
10814 @item @code{RESULT = NORM2(ARRAY[, DIM])}
10817 @item @emph{Arguments}:
10818 @multitable @columnfractions .15 .70
10819 @item @var{ARRAY} @tab Shall be an array of type @code{REAL}
10820 @item @var{DIM} @tab (Optional) shall be a scalar of type
10821 @code{INTEGER} with a value in the range from 1 to n, where n
10822 equals the rank of @var{ARRAY}.
10825 @item @emph{Return value}:
10826 The result is of the same type as @var{ARRAY}.
10828 If @var{DIM} is absent, a scalar with the square root of the sum of all
10829 elements in @var{ARRAY} squared is returned. Otherwise, an array of
10830 rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
10831 shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
10834 @item @emph{Example}:
10837 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
10838 print *, NORM2(x) ! = sqrt(55.) ~ 7.416
10846 @section @code{NOT} --- Logical negation
10852 @cindex bits, negate
10853 @cindex bitwise logical not
10854 @cindex logical not, bitwise
10857 @item @emph{Description}:
10858 @code{NOT} returns the bitwise Boolean inverse of @var{I}.
10860 @item @emph{Standard}:
10861 Fortran 95 and later, has overloads that are GNU extensions
10863 @item @emph{Class}:
10866 @item @emph{Syntax}:
10867 @code{RESULT = NOT(I)}
10869 @item @emph{Arguments}:
10870 @multitable @columnfractions .15 .70
10871 @item @var{I} @tab The type shall be @code{INTEGER}.
10874 @item @emph{Return value}:
10875 The return type is @code{INTEGER}, of the same kind as the
10878 @item @emph{Specific names}:
10879 @multitable @columnfractions .20 .20 .20 .25
10880 @item Name @tab Argument @tab Return type @tab Standard
10881 @item @code{NOT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
10882 @item @code{BNOT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
10883 @item @code{INOT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
10884 @item @code{JNOT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
10885 @item @code{KNOT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
10888 @item @emph{See also}:
10889 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
10896 @section @code{NULL} --- Function that returns an disassociated pointer
10898 @cindex pointer, status
10899 @cindex pointer, disassociated
10902 @item @emph{Description}:
10903 Returns a disassociated pointer.
10905 If @var{MOLD} is present, a disassociated pointer of the same type is
10906 returned, otherwise the type is determined by context.
10908 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
10909 includes cases where it is required.
10911 @item @emph{Standard}:
10912 Fortran 95 and later
10914 @item @emph{Class}:
10915 Transformational function
10917 @item @emph{Syntax}:
10918 @code{PTR => NULL([MOLD])}
10920 @item @emph{Arguments}:
10921 @multitable @columnfractions .15 .70
10922 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
10923 status and of any type.
10926 @item @emph{Return value}:
10927 A disassociated pointer.
10929 @item @emph{Example}:
10931 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
10934 @item @emph{See also}:
10941 @section @code{NUM_IMAGES} --- Function that returns the number of images
10942 @fnindex NUM_IMAGES
10943 @cindex coarray, @code{NUM_IMAGES}
10944 @cindex images, number of
10947 @item @emph{Description}:
10948 Returns the number of images.
10950 @item @emph{Standard}:
10951 Fortran 2008 and later. With @var{DISTANCE} or @var{FAILED} argument,
10952 Technical Specification (TS) 18508 or later
10955 @item @emph{Class}:
10956 Transformational function
10958 @item @emph{Syntax}:
10959 @code{RESULT = NUM_IMAGES(DISTANCE, FAILED)}
10961 @item @emph{Arguments}:
10962 @multitable @columnfractions .15 .70
10963 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
10964 @item @var{FAILED} @tab (optional, intent(in)) Scalar logical expression
10967 @item @emph{Return value}:
10968 Scalar default-kind integer. If @var{DISTANCE} is not present or has value 0,
10969 the number of images in the current team is returned. For values smaller or
10970 equal distance to the initial team, it returns the number of images index
10971 on the ancestor team which has a distance of @var{DISTANCE} from the invoking
10972 team. If @var{DISTANCE} is larger than the distance to the initial team, the
10973 number of images of the initial team is returned. If @var{FAILED} is not present
10974 the total number of images is returned; if it has the value @code{.TRUE.},
10975 the number of failed images is returned, otherwise, the number of images which
10976 do have not the failed status.
10978 @item @emph{Example}:
10980 INTEGER :: value[*]
10982 value = THIS_IMAGE()
10984 IF (THIS_IMAGE() == 1) THEN
10985 DO i = 1, NUM_IMAGES()
10986 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
10991 @item @emph{See also}:
10992 @ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
10998 @section @code{OR} --- Bitwise logical OR
11000 @cindex bitwise logical or
11001 @cindex logical or, bitwise
11004 @item @emph{Description}:
11005 Bitwise logical @code{OR}.
11007 This intrinsic routine is provided for backwards compatibility with
11008 GNU Fortran 77. For integer arguments, programmers should consider
11009 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
11011 @item @emph{Standard}:
11014 @item @emph{Class}:
11017 @item @emph{Syntax}:
11018 @code{RESULT = OR(I, J)}
11020 @item @emph{Arguments}:
11021 @multitable @columnfractions .15 .70
11022 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
11023 type or a scalar @code{LOGICAL} type.
11024 @item @var{J} @tab The type shall be the same as the type of @var{J}.
11027 @item @emph{Return value}:
11028 The return type is either a scalar @code{INTEGER} or a scalar
11029 @code{LOGICAL}. If the kind type parameters differ, then the
11030 smaller kind type is implicitly converted to larger kind, and the
11031 return has the larger kind.
11033 @item @emph{Example}:
11036 LOGICAL :: T = .TRUE., F = .FALSE.
11038 DATA a / Z'F' /, b / Z'3' /
11040 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
11041 WRITE (*,*) OR(a, b)
11045 @item @emph{See also}:
11046 Fortran 95 elemental function: @ref{IOR}
11052 @section @code{PACK} --- Pack an array into an array of rank one
11054 @cindex array, packing
11055 @cindex array, reduce dimension
11056 @cindex array, gather elements
11059 @item @emph{Description}:
11060 Stores the elements of @var{ARRAY} in an array of rank one.
11062 The beginning of the resulting array is made up of elements whose @var{MASK}
11063 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
11066 @item @emph{Standard}:
11067 Fortran 95 and later
11069 @item @emph{Class}:
11070 Transformational function
11072 @item @emph{Syntax}:
11073 @code{RESULT = PACK(ARRAY, MASK[,VECTOR])}
11075 @item @emph{Arguments}:
11076 @multitable @columnfractions .15 .70
11077 @item @var{ARRAY} @tab Shall be an array of any type.
11078 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
11079 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
11081 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
11082 as @var{ARRAY} and of rank one. If present, the number of elements in
11083 @var{VECTOR} shall be equal to or greater than the number of true elements
11084 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
11085 @var{VECTOR} shall be equal to or greater than the number of elements in
11089 @item @emph{Return value}:
11090 The result is an array of rank one and the same type as that of @var{ARRAY}.
11091 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
11092 number of @code{TRUE} values in @var{MASK} otherwise.
11094 @item @emph{Example}:
11095 Gathering nonzero elements from an array:
11097 PROGRAM test_pack_1
11099 m = (/ 1, 0, 0, 0, 5, 0 /)
11100 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
11104 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
11106 PROGRAM test_pack_2
11108 m = (/ 1, 0, 0, 2 /)
11109 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
11113 @item @emph{See also}:
11120 @section @code{PARITY} --- Reduction with exclusive OR
11123 @cindex Reduction, XOR
11124 @cindex XOR reduction
11127 @item @emph{Description}:
11128 Calculates the parity, i.e. the reduction using @code{.XOR.},
11129 of @var{MASK} along dimension @var{DIM}.
11131 @item @emph{Standard}:
11132 Fortran 2008 and later
11134 @item @emph{Class}:
11135 Transformational function
11137 @item @emph{Syntax}:
11138 @multitable @columnfractions .80
11139 @item @code{RESULT = PARITY(MASK[, DIM])}
11142 @item @emph{Arguments}:
11143 @multitable @columnfractions .15 .70
11144 @item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL}
11145 @item @var{DIM} @tab (Optional) shall be a scalar of type
11146 @code{INTEGER} with a value in the range from 1 to n, where n
11147 equals the rank of @var{MASK}.
11150 @item @emph{Return value}:
11151 The result is of the same type as @var{MASK}.
11153 If @var{DIM} is absent, a scalar with the parity of all elements in
11154 @var{MASK} is returned, i.e. true if an odd number of elements is
11155 @code{.true.} and false otherwise. If @var{DIM} is present, an array
11156 of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
11157 and a shape similar to that of @var{MASK} with dimension @var{DIM}
11158 dropped is returned.
11160 @item @emph{Example}:
11163 LOGICAL :: x(2) = [ .true., .false. ]
11164 print *, PARITY(x) ! prints "T" (true).
11172 @section @code{PERROR} --- Print system error message
11174 @cindex system, error handling
11177 @item @emph{Description}:
11178 Prints (on the C @code{stderr} stream) a newline-terminated error
11179 message corresponding to the last system error. This is prefixed by
11180 @var{STRING}, a colon and a space. See @code{perror(3)}.
11182 @item @emph{Standard}:
11185 @item @emph{Class}:
11188 @item @emph{Syntax}:
11189 @code{CALL PERROR(STRING)}
11191 @item @emph{Arguments}:
11192 @multitable @columnfractions .15 .70
11193 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
11197 @item @emph{See also}:
11204 @section @code{POPCNT} --- Number of bits set
11206 @cindex binary representation
11210 @item @emph{Description}:
11211 @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
11212 representation of @code{I}.
11214 @item @emph{Standard}:
11215 Fortran 2008 and later
11217 @item @emph{Class}:
11220 @item @emph{Syntax}:
11221 @code{RESULT = POPCNT(I)}
11223 @item @emph{Arguments}:
11224 @multitable @columnfractions .15 .70
11225 @item @var{I} @tab Shall be of type @code{INTEGER}.
11228 @item @emph{Return value}:
11229 The return value is of type @code{INTEGER} and of the default integer
11232 @item @emph{See also}:
11233 @ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ}
11235 @item @emph{Example}:
11237 program test_population
11238 print *, popcnt(127), poppar(127)
11239 print *, popcnt(huge(0_4)), poppar(huge(0_4))
11240 print *, popcnt(huge(0_8)), poppar(huge(0_8))
11241 end program test_population
11247 @section @code{POPPAR} --- Parity of the number of bits set
11249 @cindex binary representation
11253 @item @emph{Description}:
11254 @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
11255 of the number of bits set ('1' bits) in the binary representation of
11256 @code{I}. It is equal to 0 if @code{I} has an even number of bits set,
11257 and 1 for an odd number of '1' bits.
11259 @item @emph{Standard}:
11260 Fortran 2008 and later
11262 @item @emph{Class}:
11265 @item @emph{Syntax}:
11266 @code{RESULT = POPPAR(I)}
11268 @item @emph{Arguments}:
11269 @multitable @columnfractions .15 .70
11270 @item @var{I} @tab Shall be of type @code{INTEGER}.
11273 @item @emph{Return value}:
11274 The return value is of type @code{INTEGER} and of the default integer
11277 @item @emph{See also}:
11278 @ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ}
11280 @item @emph{Example}:
11282 program test_population
11283 print *, popcnt(127), poppar(127)
11284 print *, popcnt(huge(0_4)), poppar(huge(0_4))
11285 print *, popcnt(huge(0_8)), poppar(huge(0_8))
11286 end program test_population
11293 @section @code{PRECISION} --- Decimal precision of a real kind
11295 @cindex model representation, precision
11298 @item @emph{Description}:
11299 @code{PRECISION(X)} returns the decimal precision in the model of the
11302 @item @emph{Standard}:
11303 Fortran 95 and later
11305 @item @emph{Class}:
11308 @item @emph{Syntax}:
11309 @code{RESULT = PRECISION(X)}
11311 @item @emph{Arguments}:
11312 @multitable @columnfractions .15 .70
11313 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
11316 @item @emph{Return value}:
11317 The return value is of type @code{INTEGER} and of the default integer
11320 @item @emph{See also}:
11321 @ref{SELECTED_REAL_KIND}, @ref{RANGE}
11323 @item @emph{Example}:
11325 program prec_and_range
11326 real(kind=4) :: x(2)
11327 complex(kind=8) :: y
11329 print *, precision(x), range(x)
11330 print *, precision(y), range(y)
11331 end program prec_and_range
11338 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
11342 @item @emph{Description}:
11343 Determines whether an optional dummy argument is present.
11345 @item @emph{Standard}:
11346 Fortran 95 and later
11348 @item @emph{Class}:
11351 @item @emph{Syntax}:
11352 @code{RESULT = PRESENT(A)}
11354 @item @emph{Arguments}:
11355 @multitable @columnfractions .15 .70
11356 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
11357 value, or a dummy procedure. It shall be the name of an optional dummy argument
11358 accessible within the current subroutine or function.
11361 @item @emph{Return value}:
11362 Returns either @code{TRUE} if the optional argument @var{A} is present, or
11363 @code{FALSE} otherwise.
11365 @item @emph{Example}:
11367 PROGRAM test_present
11368 WRITE(*,*) f(), f(42) ! "F T"
11370 LOGICAL FUNCTION f(x)
11371 INTEGER, INTENT(IN), OPTIONAL :: x
11381 @section @code{PRODUCT} --- Product of array elements
11383 @cindex array, product
11384 @cindex array, multiply elements
11385 @cindex array, conditionally multiply elements
11386 @cindex multiply array elements
11389 @item @emph{Description}:
11390 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
11391 the corresponding element in @var{MASK} is @code{TRUE}.
11393 @item @emph{Standard}:
11394 Fortran 95 and later
11396 @item @emph{Class}:
11397 Transformational function
11399 @item @emph{Syntax}:
11400 @multitable @columnfractions .80
11401 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
11402 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
11405 @item @emph{Arguments}:
11406 @multitable @columnfractions .15 .70
11407 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
11408 @code{REAL} or @code{COMPLEX}.
11409 @item @var{DIM} @tab (Optional) shall be a scalar of type
11410 @code{INTEGER} with a value in the range from 1 to n, where n
11411 equals the rank of @var{ARRAY}.
11412 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
11413 and either be a scalar or an array of the same shape as @var{ARRAY}.
11416 @item @emph{Return value}:
11417 The result is of the same type as @var{ARRAY}.
11419 If @var{DIM} is absent, a scalar with the product of all elements in
11420 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
11421 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
11422 dimension @var{DIM} dropped is returned.
11425 @item @emph{Example}:
11427 PROGRAM test_product
11428 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
11429 print *, PRODUCT(x) ! all elements, product = 120
11430 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
11434 @item @emph{See also}:
11441 @section @code{RADIX} --- Base of a model number
11443 @cindex model representation, base
11444 @cindex model representation, radix
11447 @item @emph{Description}:
11448 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
11450 @item @emph{Standard}:
11451 Fortran 95 and later
11453 @item @emph{Class}:
11456 @item @emph{Syntax}:
11457 @code{RESULT = RADIX(X)}
11459 @item @emph{Arguments}:
11460 @multitable @columnfractions .15 .70
11461 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
11464 @item @emph{Return value}:
11465 The return value is a scalar of type @code{INTEGER} and of the default
11468 @item @emph{See also}:
11469 @ref{SELECTED_REAL_KIND}
11471 @item @emph{Example}:
11474 print *, "The radix for the default integer kind is", radix(0)
11475 print *, "The radix for the default real kind is", radix(0.0)
11476 end program test_radix
11484 @section @code{RAN} --- Real pseudo-random number
11486 @cindex random number generation
11489 @item @emph{Description}:
11490 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
11491 provided as an alias for @code{RAND}. See @ref{RAND} for complete
11494 @item @emph{Standard}:
11497 @item @emph{Class}:
11500 @item @emph{See also}:
11501 @ref{RAND}, @ref{RANDOM_NUMBER}
11507 @section @code{RAND} --- Real pseudo-random number
11509 @cindex random number generation
11512 @item @emph{Description}:
11513 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
11514 distribution between 0 and 1. If @var{FLAG} is 0, the next number
11515 in the current sequence is returned; if @var{FLAG} is 1, the generator
11516 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
11517 it is used as a new seed with @code{SRAND}.
11519 This intrinsic routine is provided for backwards compatibility with
11520 GNU Fortran 77. It implements a simple modulo generator as provided
11521 by @command{g77}. For new code, one should consider the use of
11522 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
11524 @item @emph{Standard}:
11527 @item @emph{Class}:
11530 @item @emph{Syntax}:
11531 @code{RESULT = RAND(I)}
11533 @item @emph{Arguments}:
11534 @multitable @columnfractions .15 .70
11535 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
11538 @item @emph{Return value}:
11539 The return value is of @code{REAL} type and the default kind.
11541 @item @emph{Example}:
11544 integer,parameter :: seed = 86456
11547 print *, rand(), rand(), rand(), rand()
11548 print *, rand(seed), rand(), rand(), rand()
11549 end program test_rand
11552 @item @emph{See also}:
11553 @ref{SRAND}, @ref{RANDOM_NUMBER}
11559 @node RANDOM_NUMBER
11560 @section @code{RANDOM_NUMBER} --- Pseudo-random number
11561 @fnindex RANDOM_NUMBER
11562 @cindex random number generation
11565 @item @emph{Description}:
11566 Returns a single pseudorandom number or an array of pseudorandom numbers
11567 from the uniform distribution over the range @math{ 0 \leq x < 1}.
11569 The runtime-library implements the xorshift1024* random number
11570 generator (RNG). This generator has a period of @math{2^{1024} - 1},
11571 and when using multiple threads up to @math{2^{512}} threads can each
11572 generate @math{2^{512}} random numbers before any aliasing occurs.
11574 Note that in a multi-threaded program (e.g. using OpenMP directives),
11575 each thread will have its own random number state. For details of the
11576 seeding procedure, see the documentation for the @code{RANDOM_SEED}
11580 @item @emph{Standard}:
11581 Fortran 95 and later
11583 @item @emph{Class}:
11586 @item @emph{Syntax}:
11587 @code{RANDOM_NUMBER(HARVEST)}
11589 @item @emph{Arguments}:
11590 @multitable @columnfractions .15 .70
11591 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
11594 @item @emph{Example}:
11596 program test_random_number
11598 CALL RANDOM_NUMBER(r)
11602 @item @emph{See also}:
11609 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
11610 @fnindex RANDOM_SEED
11611 @cindex random number generation, seeding
11612 @cindex seeding a random number generator
11615 @item @emph{Description}:
11616 Restarts or queries the state of the pseudorandom number generator used by
11617 @code{RANDOM_NUMBER}.
11619 If @code{RANDOM_SEED} is called without arguments, it is seeded with
11620 random data retrieved from the operating system.
11622 As an extension to the Fortran standard, the GFortran
11623 @code{RANDOM_NUMBER} supports multiple threads. Each thread in a
11624 multi-threaded program has its own seed. When @code{RANDOM_SEED} is
11625 called either without arguments or with the @var{PUT} argument, the
11626 given seed is copied into a master seed as well as the seed of the
11627 current thread. When a new thread uses @code{RANDOM_NUMBER} for the
11628 first time, the seed is copied from the master seed, and forwarded
11629 @math{N * 2^{512}} steps to guarantee that the random stream does not
11630 alias any other stream in the system, where @var{N} is the number of
11631 threads that have used @code{RANDOM_NUMBER} so far during the program
11634 @item @emph{Standard}:
11635 Fortran 95 and later
11637 @item @emph{Class}:
11640 @item @emph{Syntax}:
11641 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
11643 @item @emph{Arguments}:
11644 @multitable @columnfractions .15 .70
11645 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
11646 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
11647 of the arrays used with the @var{PUT} and @var{GET} arguments.
11648 @item @var{PUT} @tab (Optional) Shall be an array of type default
11649 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
11650 the array must be larger than or equal to the number returned by the
11651 @var{SIZE} argument.
11652 @item @var{GET} @tab (Optional) Shall be an array of type default
11653 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
11654 of the array must be larger than or equal to the number returned by
11655 the @var{SIZE} argument.
11658 @item @emph{Example}:
11660 program test_random_seed
11662 integer, allocatable :: seed(:)
11665 call random_seed(size = n)
11667 call random_seed(get=seed)
11669 end program test_random_seed
11672 @item @emph{See also}:
11673 @ref{RANDOM_NUMBER}
11679 @section @code{RANGE} --- Decimal exponent range
11681 @cindex model representation, range
11684 @item @emph{Description}:
11685 @code{RANGE(X)} returns the decimal exponent range in the model of the
11688 @item @emph{Standard}:
11689 Fortran 95 and later
11691 @item @emph{Class}:
11694 @item @emph{Syntax}:
11695 @code{RESULT = RANGE(X)}
11697 @item @emph{Arguments}:
11698 @multitable @columnfractions .15 .70
11699 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
11703 @item @emph{Return value}:
11704 The return value is of type @code{INTEGER} and of the default integer
11707 @item @emph{See also}:
11708 @ref{SELECTED_REAL_KIND}, @ref{PRECISION}
11710 @item @emph{Example}:
11711 See @code{PRECISION} for an example.
11717 @section @code{RANK} --- Rank of a data object
11722 @item @emph{Description}:
11723 @code{RANK(A)} returns the rank of a scalar or array data object.
11725 @item @emph{Standard}:
11726 Technical Specification (TS) 29113
11728 @item @emph{Class}:
11731 @item @emph{Syntax}:
11732 @code{RESULT = RANK(A)}
11734 @item @emph{Arguments}:
11735 @multitable @columnfractions .15 .70
11736 @item @var{A} @tab can be of any type
11739 @item @emph{Return value}:
11740 The return value is of type @code{INTEGER} and of the default integer
11741 kind. For arrays, their rank is returned; for scalars zero is returned.
11743 @item @emph{Example}:
11747 real, allocatable :: b(:,:)
11749 print *, rank(a), rank(b) ! Prints: 0 2
11750 end program test_rank
11758 @section @code{REAL} --- Convert to real type
11767 @cindex conversion, to real
11768 @cindex complex numbers, real part
11771 @item @emph{Description}:
11772 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
11773 @code{REALPART} function is provided for compatibility with @command{g77},
11774 and its use is strongly discouraged.
11776 @item @emph{Standard}:
11777 Fortran 77 and later
11779 @item @emph{Class}:
11782 @item @emph{Syntax}:
11783 @multitable @columnfractions .80
11784 @item @code{RESULT = REAL(A [, KIND])}
11785 @item @code{RESULT = REALPART(Z)}
11788 @item @emph{Arguments}:
11789 @multitable @columnfractions .15 .70
11790 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
11792 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11793 expression indicating the kind parameter of the result.
11796 @item @emph{Return value}:
11797 These functions return a @code{REAL} variable or array under
11798 the following rules:
11802 @code{REAL(A)} is converted to a default real type if @var{A} is an
11803 integer or real variable.
11805 @code{REAL(A)} is converted to a real type with the kind type parameter
11806 of @var{A} if @var{A} is a complex variable.
11808 @code{REAL(A, KIND)} is converted to a real type with kind type
11809 parameter @var{KIND} if @var{A} is a complex, integer, or real
11813 @item @emph{Example}:
11816 complex :: x = (1.0, 2.0)
11817 print *, real(x), real(x,8), realpart(x)
11818 end program test_real
11821 @item @emph{Specific names}:
11822 @multitable @columnfractions .20 .20 .20 .25
11823 @item Name @tab Argument @tab Return type @tab Standard
11824 @item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later
11825 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension
11826 @item @code{FLOATI(A)} @tab @code{INTEGER(2)} @tab @code{REAL(4)} @tab GNU extension
11827 @item @code{FLOATJ(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab GNU extension
11828 @item @code{FLOATK(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab GNU extension
11829 @item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab Fortran 77 and later
11833 @item @emph{See also}:
11841 @section @code{RENAME} --- Rename a file
11843 @cindex file system, rename file
11846 @item @emph{Description}:
11847 Renames a file from file @var{PATH1} to @var{PATH2}. A null
11848 character (@code{CHAR(0)}) can be used to mark the end of the names in
11849 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
11850 names are ignored. If the @var{STATUS} argument is supplied, it
11851 contains 0 on success or a nonzero error code upon return; see
11854 This intrinsic is provided in both subroutine and function forms;
11855 however, only one form can be used in any given program unit.
11857 @item @emph{Standard}:
11860 @item @emph{Class}:
11861 Subroutine, function
11863 @item @emph{Syntax}:
11864 @multitable @columnfractions .80
11865 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
11866 @item @code{STATUS = RENAME(PATH1, PATH2)}
11869 @item @emph{Arguments}:
11870 @multitable @columnfractions .15 .70
11871 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
11872 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
11873 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11876 @item @emph{See also}:
11884 @section @code{REPEAT} --- Repeated string concatenation
11886 @cindex string, repeat
11887 @cindex string, concatenate
11890 @item @emph{Description}:
11891 Concatenates @var{NCOPIES} copies of a string.
11893 @item @emph{Standard}:
11894 Fortran 95 and later
11896 @item @emph{Class}:
11897 Transformational function
11899 @item @emph{Syntax}:
11900 @code{RESULT = REPEAT(STRING, NCOPIES)}
11902 @item @emph{Arguments}:
11903 @multitable @columnfractions .15 .70
11904 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
11905 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
11908 @item @emph{Return value}:
11909 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
11912 @item @emph{Example}:
11914 program test_repeat
11915 write(*,*) repeat("x", 5) ! "xxxxx"
11923 @section @code{RESHAPE} --- Function to reshape an array
11925 @cindex array, change dimensions
11926 @cindex array, transmogrify
11929 @item @emph{Description}:
11930 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
11931 the new array may be padded with elements from @var{PAD} or permuted
11932 as defined by @var{ORDER}.
11934 @item @emph{Standard}:
11935 Fortran 95 and later
11937 @item @emph{Class}:
11938 Transformational function
11940 @item @emph{Syntax}:
11941 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
11943 @item @emph{Arguments}:
11944 @multitable @columnfractions .15 .70
11945 @item @var{SOURCE} @tab Shall be an array of any type.
11946 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
11947 array of rank one. Its values must be positive or zero.
11948 @item @var{PAD} @tab (Optional) shall be an array of the same
11949 type as @var{SOURCE}.
11950 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
11951 and an array of the same shape as @var{SHAPE}. Its values shall
11952 be a permutation of the numbers from 1 to n, where n is the size of
11953 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
11957 @item @emph{Return value}:
11958 The result is an array of shape @var{SHAPE} with the same type as
11961 @item @emph{Example}:
11963 PROGRAM test_reshape
11964 INTEGER, DIMENSION(4) :: x
11965 WRITE(*,*) SHAPE(x) ! prints "4"
11966 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
11970 @item @emph{See also}:
11977 @section @code{RRSPACING} --- Reciprocal of the relative spacing
11979 @cindex real number, relative spacing
11980 @cindex floating point, relative spacing
11984 @item @emph{Description}:
11985 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
11986 model numbers near @var{X}.
11988 @item @emph{Standard}:
11989 Fortran 95 and later
11991 @item @emph{Class}:
11994 @item @emph{Syntax}:
11995 @code{RESULT = RRSPACING(X)}
11997 @item @emph{Arguments}:
11998 @multitable @columnfractions .15 .70
11999 @item @var{X} @tab Shall be of type @code{REAL}.
12002 @item @emph{Return value}:
12003 The return value is of the same type and kind as @var{X}.
12004 The value returned is equal to
12005 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
12007 @item @emph{See also}:
12014 @section @code{RSHIFT} --- Right shift bits
12016 @cindex bits, shift right
12019 @item @emph{Description}:
12020 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
12021 bits shifted right by @var{SHIFT} places. If the absolute value of
12022 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12023 Bits shifted out from the right end are lost. The fill is arithmetic: the
12024 bits shifted in from the left end are equal to the leftmost bit, which in
12025 two's complement representation is the sign bit.
12027 This function has been superseded by the @code{SHIFTA} intrinsic, which
12028 is standard in Fortran 2008 and later.
12030 @item @emph{Standard}:
12033 @item @emph{Class}:
12036 @item @emph{Syntax}:
12037 @code{RESULT = RSHIFT(I, SHIFT)}
12039 @item @emph{Arguments}:
12040 @multitable @columnfractions .15 .70
12041 @item @var{I} @tab The type shall be @code{INTEGER}.
12042 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12045 @item @emph{Return value}:
12046 The return value is of type @code{INTEGER} and of the same kind as
12049 @item @emph{See also}:
12050 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}, @ref{SHIFTA}, @ref{SHIFTR},
12058 @section @code{SAME_TYPE_AS} --- Query dynamic types for equality
12059 @fnindex SAME_TYPE_AS
12062 @item @emph{Description}:
12063 Query dynamic types for equality.
12065 @item @emph{Standard}:
12066 Fortran 2003 and later
12068 @item @emph{Class}:
12071 @item @emph{Syntax}:
12072 @code{RESULT = SAME_TYPE_AS(A, B)}
12074 @item @emph{Arguments}:
12075 @multitable @columnfractions .15 .70
12076 @item @var{A} @tab Shall be an object of extensible declared type or
12077 unlimited polymorphic.
12078 @item @var{B} @tab Shall be an object of extensible declared type or
12079 unlimited polymorphic.
12082 @item @emph{Return value}:
12083 The return value is a scalar of type default logical. It is true if and
12084 only if the dynamic type of A is the same as the dynamic type of B.
12086 @item @emph{See also}:
12087 @ref{EXTENDS_TYPE_OF}
12094 @section @code{SCALE} --- Scale a real value
12096 @cindex real number, scale
12097 @cindex floating point, scale
12100 @item @emph{Description}:
12101 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
12103 @item @emph{Standard}:
12104 Fortran 95 and later
12106 @item @emph{Class}:
12109 @item @emph{Syntax}:
12110 @code{RESULT = SCALE(X, I)}
12112 @item @emph{Arguments}:
12113 @multitable @columnfractions .15 .70
12114 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
12115 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
12118 @item @emph{Return value}:
12119 The return value is of the same type and kind as @var{X}.
12120 Its value is @code{X * RADIX(X)**I}.
12122 @item @emph{Example}:
12125 real :: x = 178.1387e-4
12127 print *, scale(x,i), x*radix(x)**i
12128 end program test_scale
12136 @section @code{SCAN} --- Scan a string for the presence of a set of characters
12138 @cindex string, find subset
12141 @item @emph{Description}:
12142 Scans a @var{STRING} for any of the characters in a @var{SET}
12145 If @var{BACK} is either absent or equals @code{FALSE}, this function
12146 returns the position of the leftmost character of @var{STRING} that is
12147 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
12148 is returned. If no character of @var{SET} is found in @var{STRING}, the
12151 @item @emph{Standard}:
12152 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12154 @item @emph{Class}:
12157 @item @emph{Syntax}:
12158 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
12160 @item @emph{Arguments}:
12161 @multitable @columnfractions .15 .70
12162 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
12163 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
12164 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
12165 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12166 expression indicating the kind parameter of the result.
12169 @item @emph{Return value}:
12170 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12171 @var{KIND} is absent, the return value is of default integer kind.
12173 @item @emph{Example}:
12176 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
12177 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
12178 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
12182 @item @emph{See also}:
12183 @ref{INDEX intrinsic}, @ref{VERIFY}
12189 @section @code{SECNDS} --- Time function
12191 @cindex time, elapsed
12192 @cindex elapsed time
12195 @item @emph{Description}:
12196 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
12197 @var{X} is a reference time, also in seconds. If this is zero, the time in
12198 seconds from midnight is returned. This function is non-standard and its
12199 use is discouraged.
12201 @item @emph{Standard}:
12204 @item @emph{Class}:
12207 @item @emph{Syntax}:
12208 @code{RESULT = SECNDS (X)}
12210 @item @emph{Arguments}:
12211 @multitable @columnfractions .15 .70
12212 @item @var{T} @tab Shall be of type @code{REAL(4)}.
12213 @item @var{X} @tab Shall be of type @code{REAL(4)}.
12216 @item @emph{Return value}:
12219 @item @emph{Example}:
12221 program test_secnds
12224 print *, secnds (0.0) ! seconds since midnight
12225 t1 = secnds (0.0) ! reference time
12226 do i = 1, 10000000 ! do something
12228 t2 = secnds (t1) ! elapsed time
12229 print *, "Something took ", t2, " seconds."
12230 end program test_secnds
12237 @section @code{SECOND} --- CPU time function
12239 @cindex time, elapsed
12240 @cindex elapsed time
12243 @item @emph{Description}:
12244 Returns a @code{REAL(4)} value representing the elapsed CPU time in
12245 seconds. This provides the same functionality as the standard
12246 @code{CPU_TIME} intrinsic, and is only included for backwards
12249 This intrinsic is provided in both subroutine and function forms;
12250 however, only one form can be used in any given program unit.
12252 @item @emph{Standard}:
12255 @item @emph{Class}:
12256 Subroutine, function
12258 @item @emph{Syntax}:
12259 @multitable @columnfractions .80
12260 @item @code{CALL SECOND(TIME)}
12261 @item @code{TIME = SECOND()}
12264 @item @emph{Arguments}:
12265 @multitable @columnfractions .15 .70
12266 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
12269 @item @emph{Return value}:
12270 In either syntax, @var{TIME} is set to the process's current runtime in
12273 @item @emph{See also}:
12280 @node SELECTED_CHAR_KIND
12281 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
12282 @fnindex SELECTED_CHAR_KIND
12283 @cindex character kind
12284 @cindex kind, character
12287 @item @emph{Description}:
12289 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
12290 set named @var{NAME}, if a character set with such a name is supported,
12291 or @math{-1} otherwise. Currently, supported character sets include
12292 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
12293 (Universal Character Set, UCS-4) which is commonly known as Unicode.
12295 @item @emph{Standard}:
12296 Fortran 2003 and later
12298 @item @emph{Class}:
12299 Transformational function
12301 @item @emph{Syntax}:
12302 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
12304 @item @emph{Arguments}:
12305 @multitable @columnfractions .15 .70
12306 @item @var{NAME} @tab Shall be a scalar and of the default character type.
12309 @item @emph{Example}:
12311 program character_kind
12312 use iso_fortran_env
12314 integer, parameter :: ascii = selected_char_kind ("ascii")
12315 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646')
12317 character(kind=ascii, len=26) :: alphabet
12318 character(kind=ucs4, len=30) :: hello_world
12320 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
12321 hello_world = ucs4_'Hello World and Ni Hao -- ' &
12322 // char (int (z'4F60'), ucs4) &
12323 // char (int (z'597D'), ucs4)
12325 write (*,*) alphabet
12327 open (output_unit, encoding='UTF-8')
12328 write (*,*) trim (hello_world)
12329 end program character_kind
12335 @node SELECTED_INT_KIND
12336 @section @code{SELECTED_INT_KIND} --- Choose integer kind
12337 @fnindex SELECTED_INT_KIND
12338 @cindex integer kind
12339 @cindex kind, integer
12342 @item @emph{Description}:
12343 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
12344 type that can represent all values ranging from @math{-10^R} (exclusive)
12345 to @math{10^R} (exclusive). If there is no integer kind that accommodates
12346 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
12348 @item @emph{Standard}:
12349 Fortran 95 and later
12351 @item @emph{Class}:
12352 Transformational function
12354 @item @emph{Syntax}:
12355 @code{RESULT = SELECTED_INT_KIND(R)}
12357 @item @emph{Arguments}:
12358 @multitable @columnfractions .15 .70
12359 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
12362 @item @emph{Example}:
12364 program large_integers
12365 integer,parameter :: k5 = selected_int_kind(5)
12366 integer,parameter :: k15 = selected_int_kind(15)
12367 integer(kind=k5) :: i5
12368 integer(kind=k15) :: i15
12370 print *, huge(i5), huge(i15)
12372 ! The following inequalities are always true
12373 print *, huge(i5) >= 10_k5**5-1
12374 print *, huge(i15) >= 10_k15**15-1
12375 end program large_integers
12381 @node SELECTED_REAL_KIND
12382 @section @code{SELECTED_REAL_KIND} --- Choose real kind
12383 @fnindex SELECTED_REAL_KIND
12386 @cindex radix, real
12389 @item @emph{Description}:
12390 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
12391 with decimal precision of at least @code{P} digits, exponent range of
12392 at least @code{R}, and with a radix of @code{RADIX}.
12394 @item @emph{Standard}:
12395 Fortran 95 and later, with @code{RADIX} Fortran 2008 or later
12397 @item @emph{Class}:
12398 Transformational function
12400 @item @emph{Syntax}:
12401 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
12403 @item @emph{Arguments}:
12404 @multitable @columnfractions .15 .70
12405 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12406 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12407 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12409 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
12410 be present; since Fortran 2008, they are assumed to be zero if absent.
12412 @item @emph{Return value}:
12414 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
12415 a real data type with decimal precision of at least @code{P} digits, a
12416 decimal exponent range of at least @code{R}, and with the requested
12417 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
12418 any radix can be returned. If more than one real data type meet the
12419 criteria, the kind of the data type with the smallest decimal precision
12420 is returned. If no real data type matches the criteria, the result is
12422 @item -1 if the processor does not support a real data type with a
12423 precision greater than or equal to @code{P}, but the @code{R} and
12424 @code{RADIX} requirements can be fulfilled
12425 @item -2 if the processor does not support a real type with an exponent
12426 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
12428 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
12430 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
12432 @item -5 if there is no real type with the given @code{RADIX}
12435 @item @emph{See also}:
12436 @ref{PRECISION}, @ref{RANGE}, @ref{RADIX}
12438 @item @emph{Example}:
12441 integer,parameter :: p6 = selected_real_kind(6)
12442 integer,parameter :: p10r100 = selected_real_kind(10,100)
12443 integer,parameter :: r400 = selected_real_kind(r=400)
12445 real(kind=p10r100) :: y
12446 real(kind=r400) :: z
12448 print *, precision(x), range(x)
12449 print *, precision(y), range(y)
12450 print *, precision(z), range(z)
12451 end program real_kinds
12458 @section @code{SET_EXPONENT} --- Set the exponent of the model
12459 @fnindex SET_EXPONENT
12460 @cindex real number, set exponent
12461 @cindex floating point, set exponent
12464 @item @emph{Description}:
12465 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
12466 is that that of @var{X} and whose exponent part is @var{I}.
12468 @item @emph{Standard}:
12469 Fortran 95 and later
12471 @item @emph{Class}:
12474 @item @emph{Syntax}:
12475 @code{RESULT = SET_EXPONENT(X, I)}
12477 @item @emph{Arguments}:
12478 @multitable @columnfractions .15 .70
12479 @item @var{X} @tab Shall be of type @code{REAL}.
12480 @item @var{I} @tab Shall be of type @code{INTEGER}.
12483 @item @emph{Return value}:
12484 The return value is of the same type and kind as @var{X}.
12485 The real number whose fractional part
12486 is that that of @var{X} and whose exponent part if @var{I} is returned;
12487 it is @code{FRACTION(X) * RADIX(X)**I}.
12489 @item @emph{Example}:
12491 PROGRAM test_setexp
12492 REAL :: x = 178.1387e-4
12494 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
12503 @section @code{SHAPE} --- Determine the shape of an array
12505 @cindex array, shape
12508 @item @emph{Description}:
12509 Determines the shape of an array.
12511 @item @emph{Standard}:
12512 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12514 @item @emph{Class}:
12517 @item @emph{Syntax}:
12518 @code{RESULT = SHAPE(SOURCE [, KIND])}
12520 @item @emph{Arguments}:
12521 @multitable @columnfractions .15 .70
12522 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
12523 If @var{SOURCE} is a pointer it must be associated and allocatable
12524 arrays must be allocated.
12525 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12526 expression indicating the kind parameter of the result.
12529 @item @emph{Return value}:
12530 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
12531 has dimensions. The elements of the resulting array correspond to the extend
12532 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
12533 the result is the rank one array of size zero. If @var{KIND} is absent, the
12534 return value has the default integer kind otherwise the specified kind.
12536 @item @emph{Example}:
12539 INTEGER, DIMENSION(-1:1, -1:2) :: A
12540 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
12541 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
12545 @item @emph{See also}:
12546 @ref{RESHAPE}, @ref{SIZE}
12552 @section @code{SHIFTA} --- Right shift with fill
12554 @cindex bits, shift right
12555 @cindex shift, right with fill
12558 @item @emph{Description}:
12559 @code{SHIFTA} returns a value corresponding to @var{I} with all of the
12560 bits shifted right by @var{SHIFT} places. If the absolute value of
12561 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12562 Bits shifted out from the right end are lost. The fill is arithmetic: the
12563 bits shifted in from the left end are equal to the leftmost bit, which in
12564 two's complement representation is the sign bit.
12566 @item @emph{Standard}:
12567 Fortran 2008 and later
12569 @item @emph{Class}:
12572 @item @emph{Syntax}:
12573 @code{RESULT = SHIFTA(I, SHIFT)}
12575 @item @emph{Arguments}:
12576 @multitable @columnfractions .15 .70
12577 @item @var{I} @tab The type shall be @code{INTEGER}.
12578 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12581 @item @emph{Return value}:
12582 The return value is of type @code{INTEGER} and of the same kind as
12585 @item @emph{See also}:
12586 @ref{SHIFTL}, @ref{SHIFTR}
12592 @section @code{SHIFTL} --- Left shift
12594 @cindex bits, shift left
12595 @cindex shift, left
12598 @item @emph{Description}:
12599 @code{SHIFTL} returns a value corresponding to @var{I} with all of the
12600 bits shifted left by @var{SHIFT} places. If the absolute value of
12601 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12602 Bits shifted out from the left end are lost, and bits shifted in from
12603 the right end are set to 0.
12605 @item @emph{Standard}:
12606 Fortran 2008 and later
12608 @item @emph{Class}:
12611 @item @emph{Syntax}:
12612 @code{RESULT = SHIFTL(I, SHIFT)}
12614 @item @emph{Arguments}:
12615 @multitable @columnfractions .15 .70
12616 @item @var{I} @tab The type shall be @code{INTEGER}.
12617 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12620 @item @emph{Return value}:
12621 The return value is of type @code{INTEGER} and of the same kind as
12624 @item @emph{See also}:
12625 @ref{SHIFTA}, @ref{SHIFTR}
12631 @section @code{SHIFTR} --- Right shift
12633 @cindex bits, shift right
12634 @cindex shift, right
12637 @item @emph{Description}:
12638 @code{SHIFTR} returns a value corresponding to @var{I} with all of the
12639 bits shifted right by @var{SHIFT} places. If the absolute value of
12640 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12641 Bits shifted out from the right end are lost, and bits shifted in from
12642 the left end are set to 0.
12644 @item @emph{Standard}:
12645 Fortran 2008 and later
12647 @item @emph{Class}:
12650 @item @emph{Syntax}:
12651 @code{RESULT = SHIFTR(I, SHIFT)}
12653 @item @emph{Arguments}:
12654 @multitable @columnfractions .15 .70
12655 @item @var{I} @tab The type shall be @code{INTEGER}.
12656 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12659 @item @emph{Return value}:
12660 The return value is of type @code{INTEGER} and of the same kind as
12663 @item @emph{See also}:
12664 @ref{SHIFTA}, @ref{SHIFTL}
12670 @section @code{SIGN} --- Sign copying function
12674 @cindex sign copying
12677 @item @emph{Description}:
12678 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
12680 @item @emph{Standard}:
12681 Fortran 77 and later
12683 @item @emph{Class}:
12686 @item @emph{Syntax}:
12687 @code{RESULT = SIGN(A, B)}
12689 @item @emph{Arguments}:
12690 @multitable @columnfractions .15 .70
12691 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
12692 @item @var{B} @tab Shall be of the same type and kind as @var{A}
12695 @item @emph{Return value}:
12696 The kind of the return value is that of @var{A} and @var{B}.
12697 If @math{B\ge 0} then the result is @code{ABS(A)}, else
12698 it is @code{-ABS(A)}.
12700 @item @emph{Example}:
12703 print *, sign(-12,1)
12704 print *, sign(-12,0)
12705 print *, sign(-12,-1)
12707 print *, sign(-12.,1.)
12708 print *, sign(-12.,0.)
12709 print *, sign(-12.,-1.)
12710 end program test_sign
12713 @item @emph{Specific names}:
12714 @multitable @columnfractions .20 .20 .20 .25
12715 @item Name @tab Arguments @tab Return type @tab Standard
12716 @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu
12717 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
12718 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu
12725 @section @code{SIGNAL} --- Signal handling subroutine (or function)
12727 @cindex system, signal handling
12730 @item @emph{Description}:
12731 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
12732 @var{HANDLER} to be executed with a single integer argument when signal
12733 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
12734 turn off handling of signal @var{NUMBER} or revert to its default
12735 action. See @code{signal(2)}.
12737 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
12738 is supplied, it is set to the value returned by @code{signal(2)}.
12740 @item @emph{Standard}:
12743 @item @emph{Class}:
12744 Subroutine, function
12746 @item @emph{Syntax}:
12747 @multitable @columnfractions .80
12748 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
12749 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
12752 @item @emph{Arguments}:
12753 @multitable @columnfractions .15 .70
12754 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
12755 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
12756 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
12757 @code{INTEGER}. It is @code{INTENT(IN)}.
12758 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
12759 integer. It has @code{INTENT(OUT)}.
12761 @c TODO: What should the interface of the handler be? Does it take arguments?
12763 @item @emph{Return value}:
12764 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
12766 @item @emph{Example}:
12768 program test_signal
12770 external handler_print
12772 call signal (12, handler_print)
12773 call signal (10, 1)
12776 end program test_signal
12783 @section @code{SIN} --- Sine function
12789 @cindex trigonometric function, sine
12793 @item @emph{Description}:
12794 @code{SIN(X)} computes the sine of @var{X}.
12796 @item @emph{Standard}:
12797 Fortran 77 and later
12799 @item @emph{Class}:
12802 @item @emph{Syntax}:
12803 @code{RESULT = SIN(X)}
12805 @item @emph{Arguments}:
12806 @multitable @columnfractions .15 .70
12807 @item @var{X} @tab The type shall be @code{REAL} or
12811 @item @emph{Return value}:
12812 The return value has same type and kind as @var{X}.
12814 @item @emph{Example}:
12819 end program test_sin
12822 @item @emph{Specific names}:
12823 @multitable @columnfractions .20 .20 .20 .25
12824 @item Name @tab Argument @tab Return type @tab Standard
12825 @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu
12826 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
12827 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
12828 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
12829 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
12832 @item @emph{See also}:
12833 Inverse function: @ref{ASIN}
12834 Degrees function: @ref{SIND}
12840 @section @code{SIND} --- Sine function, degrees
12846 @cindex trigonometric function, sine, degrees
12847 @cindex sine, degrees
12850 @item @emph{Description}:
12851 @code{SIND(X)} computes the sine of @var{X} in degrees.
12853 This function is for compatibility only and should be avoided in favor of
12854 standard constructs wherever possible.
12856 @item @emph{Standard}:
12857 GNU Extension, enabled with @option{-fdec-math}.
12859 @item @emph{Class}:
12862 @item @emph{Syntax}:
12863 @code{RESULT = SIND(X)}
12865 @item @emph{Arguments}:
12866 @multitable @columnfractions .15 .70
12867 @item @var{X} @tab The type shall be @code{REAL} or
12871 @item @emph{Return value}:
12872 The return value has same type and kind as @var{X}, and its value is in degrees.
12874 @item @emph{Example}:
12879 end program test_sind
12882 @item @emph{Specific names}:
12883 @multitable @columnfractions .20 .20 .20 .25
12884 @item Name @tab Argument @tab Return type @tab Standard
12885 @item @code{SIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
12886 @item @code{DSIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
12887 @item @code{CSIND(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU Extension
12888 @item @code{ZSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU Extension
12889 @item @code{CDSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU Extension
12892 @item @emph{See also}:
12893 Inverse function: @ref{ASIND}
12894 Radians function: @ref{SIN}
12901 @section @code{SINH} --- Hyperbolic sine function
12904 @cindex hyperbolic sine
12905 @cindex hyperbolic function, sine
12906 @cindex sine, hyperbolic
12909 @item @emph{Description}:
12910 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
12912 @item @emph{Standard}:
12913 Fortran 95 and later, for a complex argument Fortran 2008 or later
12915 @item @emph{Class}:
12918 @item @emph{Syntax}:
12919 @code{RESULT = SINH(X)}
12921 @item @emph{Arguments}:
12922 @multitable @columnfractions .15 .70
12923 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
12926 @item @emph{Return value}:
12927 The return value has same type and kind as @var{X}.
12929 @item @emph{Example}:
12932 real(8) :: x = - 1.0_8
12934 end program test_sinh
12937 @item @emph{Specific names}:
12938 @multitable @columnfractions .20 .20 .20 .25
12939 @item Name @tab Argument @tab Return type @tab Standard
12940 @item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
12941 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
12944 @item @emph{See also}:
12951 @section @code{SIZE} --- Determine the size of an array
12953 @cindex array, size
12954 @cindex array, number of elements
12955 @cindex array, count elements
12958 @item @emph{Description}:
12959 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
12960 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
12962 @item @emph{Standard}:
12963 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12965 @item @emph{Class}:
12968 @item @emph{Syntax}:
12969 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
12971 @item @emph{Arguments}:
12972 @multitable @columnfractions .15 .70
12973 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
12974 a pointer it must be associated and allocatable arrays must be allocated.
12975 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
12976 and its value shall be in the range from 1 to n, where n equals the rank
12978 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12979 expression indicating the kind parameter of the result.
12982 @item @emph{Return value}:
12983 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12984 @var{KIND} is absent, the return value is of default integer kind.
12986 @item @emph{Example}:
12989 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
12993 @item @emph{See also}:
12994 @ref{SHAPE}, @ref{RESHAPE}
12999 @section @code{SIZEOF} --- Size in bytes of an expression
13001 @cindex expression size
13002 @cindex size of an expression
13005 @item @emph{Description}:
13006 @code{SIZEOF(X)} calculates the number of bytes of storage the
13007 expression @code{X} occupies.
13009 @item @emph{Standard}:
13012 @item @emph{Class}:
13015 @item @emph{Syntax}:
13016 @code{N = SIZEOF(X)}
13018 @item @emph{Arguments}:
13019 @multitable @columnfractions .15 .70
13020 @item @var{X} @tab The argument shall be of any type, rank or shape.
13023 @item @emph{Return value}:
13024 The return value is of type integer and of the system-dependent kind
13025 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
13026 number of bytes occupied by the argument. If the argument has the
13027 @code{POINTER} attribute, the number of bytes of the storage area pointed
13028 to is returned. If the argument is of a derived type with @code{POINTER}
13029 or @code{ALLOCATABLE} components, the return value does not account for
13030 the sizes of the data pointed to by these components. If the argument is
13031 polymorphic, the size according to the dynamic type is returned. The argument
13032 may not be a procedure or procedure pointer. Note that the code assumes for
13033 arrays that those are contiguous; for contiguous arrays, it returns the
13034 storage or an array element multiplied by the size of the array.
13036 @item @emph{Example}:
13040 print *, (sizeof(s)/sizeof(r) == 5)
13043 The example will print @code{.TRUE.} unless you are using a platform
13044 where default @code{REAL} variables are unusually padded.
13046 @item @emph{See also}:
13047 @ref{C_SIZEOF}, @ref{STORAGE_SIZE}
13052 @section @code{SLEEP} --- Sleep for the specified number of seconds
13054 @cindex delayed execution
13057 @item @emph{Description}:
13058 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
13060 @item @emph{Standard}:
13063 @item @emph{Class}:
13066 @item @emph{Syntax}:
13067 @code{CALL SLEEP(SECONDS)}
13069 @item @emph{Arguments}:
13070 @multitable @columnfractions .15 .70
13071 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
13074 @item @emph{Example}:
13085 @section @code{SPACING} --- Smallest distance between two numbers of a given type
13087 @cindex real number, relative spacing
13088 @cindex floating point, relative spacing
13091 @item @emph{Description}:
13092 Determines the distance between the argument @var{X} and the nearest
13093 adjacent number of the same type.
13095 @item @emph{Standard}:
13096 Fortran 95 and later
13098 @item @emph{Class}:
13101 @item @emph{Syntax}:
13102 @code{RESULT = SPACING(X)}
13104 @item @emph{Arguments}:
13105 @multitable @columnfractions .15 .70
13106 @item @var{X} @tab Shall be of type @code{REAL}.
13109 @item @emph{Return value}:
13110 The result is of the same type as the input argument @var{X}.
13112 @item @emph{Example}:
13114 PROGRAM test_spacing
13115 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
13116 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
13118 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
13119 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
13123 @item @emph{See also}:
13130 @section @code{SPREAD} --- Add a dimension to an array
13132 @cindex array, increase dimension
13133 @cindex array, duplicate elements
13134 @cindex array, duplicate dimensions
13137 @item @emph{Description}:
13138 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
13139 dimension @var{DIM}.
13141 @item @emph{Standard}:
13142 Fortran 95 and later
13144 @item @emph{Class}:
13145 Transformational function
13147 @item @emph{Syntax}:
13148 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
13150 @item @emph{Arguments}:
13151 @multitable @columnfractions .15 .70
13152 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
13153 a rank less than seven.
13154 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
13155 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
13156 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
13159 @item @emph{Return value}:
13160 The result is an array of the same type as @var{SOURCE} and has rank n+1
13161 where n equals the rank of @var{SOURCE}.
13163 @item @emph{Example}:
13165 PROGRAM test_spread
13166 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
13167 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
13168 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
13172 @item @emph{See also}:
13179 @section @code{SQRT} --- Square-root function
13186 @cindex square-root
13189 @item @emph{Description}:
13190 @code{SQRT(X)} computes the square root of @var{X}.
13192 @item @emph{Standard}:
13193 Fortran 77 and later
13195 @item @emph{Class}:
13198 @item @emph{Syntax}:
13199 @code{RESULT = SQRT(X)}
13201 @item @emph{Arguments}:
13202 @multitable @columnfractions .15 .70
13203 @item @var{X} @tab The type shall be @code{REAL} or
13207 @item @emph{Return value}:
13208 The return value is of type @code{REAL} or @code{COMPLEX}.
13209 The kind type parameter is the same as @var{X}.
13211 @item @emph{Example}:
13214 real(8) :: x = 2.0_8
13215 complex :: z = (1.0, 2.0)
13218 end program test_sqrt
13221 @item @emph{Specific names}:
13222 @multitable @columnfractions .20 .20 .20 .25
13223 @item Name @tab Argument @tab Return type @tab Standard
13224 @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
13225 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
13226 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
13227 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13228 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13235 @section @code{SRAND} --- Reinitialize the random number generator
13237 @cindex random number generation, seeding
13238 @cindex seeding a random number generator
13241 @item @emph{Description}:
13242 @code{SRAND} reinitializes the pseudo-random number generator
13243 called by @code{RAND} and @code{IRAND}. The new seed used by the
13244 generator is specified by the required argument @var{SEED}.
13246 @item @emph{Standard}:
13249 @item @emph{Class}:
13252 @item @emph{Syntax}:
13253 @code{CALL SRAND(SEED)}
13255 @item @emph{Arguments}:
13256 @multitable @columnfractions .15 .70
13257 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
13260 @item @emph{Return value}:
13261 Does not return anything.
13263 @item @emph{Example}:
13264 See @code{RAND} and @code{IRAND} for examples.
13266 @item @emph{Notes}:
13267 The Fortran standard specifies the intrinsic subroutines
13268 @code{RANDOM_SEED} to initialize the pseudo-random number
13269 generator and @code{RANDOM_NUMBER} to generate pseudo-random numbers.
13270 These subroutines should be used in new codes.
13272 Please note that in GNU Fortran, these two sets of intrinsics (@code{RAND},
13273 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
13274 @code{RANDOM_SEED} on the other hand) access two independent
13275 pseudo-random number generators.
13277 @item @emph{See also}:
13278 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
13285 @section @code{STAT} --- Get file status
13287 @cindex file system, file status
13290 @item @emph{Description}:
13291 This function returns information about a file. No permissions are required on
13292 the file itself, but execute (search) permission is required on all of the
13293 directories in path that lead to the file.
13295 The elements that are obtained and stored in the array @code{VALUES}:
13296 @multitable @columnfractions .15 .70
13297 @item @code{VALUES(1)} @tab Device ID
13298 @item @code{VALUES(2)} @tab Inode number
13299 @item @code{VALUES(3)} @tab File mode
13300 @item @code{VALUES(4)} @tab Number of links
13301 @item @code{VALUES(5)} @tab Owner's uid
13302 @item @code{VALUES(6)} @tab Owner's gid
13303 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
13304 @item @code{VALUES(8)} @tab File size (bytes)
13305 @item @code{VALUES(9)} @tab Last access time
13306 @item @code{VALUES(10)} @tab Last modification time
13307 @item @code{VALUES(11)} @tab Last file status change time
13308 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
13309 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
13312 Not all these elements are relevant on all systems.
13313 If an element is not relevant, it is returned as 0.
13315 This intrinsic is provided in both subroutine and function forms; however,
13316 only one form can be used in any given program unit.
13318 @item @emph{Standard}:
13321 @item @emph{Class}:
13322 Subroutine, function
13324 @item @emph{Syntax}:
13325 @multitable @columnfractions .80
13326 @item @code{CALL STAT(NAME, VALUES [, STATUS])}
13327 @item @code{STATUS = STAT(NAME, VALUES)}
13330 @item @emph{Arguments}:
13331 @multitable @columnfractions .15 .70
13332 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
13333 default kind and a valid path within the file system.
13334 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
13335 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
13336 on success and a system specific error code otherwise.
13339 @item @emph{Example}:
13342 INTEGER, DIMENSION(13) :: buff
13345 CALL STAT("/etc/passwd", buff, status)
13347 IF (status == 0) THEN
13348 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
13349 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
13350 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
13351 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
13352 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
13353 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
13354 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
13355 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
13356 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
13357 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
13358 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
13359 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
13360 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
13365 @item @emph{See also}:
13366 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
13372 @section @code{STORAGE_SIZE} --- Storage size in bits
13373 @fnindex STORAGE_SIZE
13374 @cindex storage size
13377 @item @emph{Description}:
13378 Returns the storage size of argument @var{A} in bits.
13379 @item @emph{Standard}:
13380 Fortran 2008 and later
13381 @item @emph{Class}:
13383 @item @emph{Syntax}:
13384 @code{RESULT = STORAGE_SIZE(A [, KIND])}
13386 @item @emph{Arguments}:
13387 @multitable @columnfractions .15 .70
13388 @item @var{A} @tab Shall be a scalar or array of any type.
13389 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
13392 @item @emph{Return Value}:
13393 The result is a scalar integer with the kind type parameter specified by KIND
13394 (or default integer type if KIND is missing). The result value is the size
13395 expressed in bits for an element of an array that has the dynamic type and type
13398 @item @emph{See also}:
13399 @ref{C_SIZEOF}, @ref{SIZEOF}
13405 @section @code{SUM} --- Sum of array elements
13408 @cindex array, add elements
13409 @cindex array, conditionally add elements
13410 @cindex sum array elements
13413 @item @emph{Description}:
13414 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
13415 the corresponding element in @var{MASK} is @code{TRUE}.
13417 @item @emph{Standard}:
13418 Fortran 95 and later
13420 @item @emph{Class}:
13421 Transformational function
13423 @item @emph{Syntax}:
13424 @multitable @columnfractions .80
13425 @item @code{RESULT = SUM(ARRAY[, MASK])}
13426 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
13429 @item @emph{Arguments}:
13430 @multitable @columnfractions .15 .70
13431 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
13432 @code{REAL} or @code{COMPLEX}.
13433 @item @var{DIM} @tab (Optional) shall be a scalar of type
13434 @code{INTEGER} with a value in the range from 1 to n, where n
13435 equals the rank of @var{ARRAY}.
13436 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
13437 and either be a scalar or an array of the same shape as @var{ARRAY}.
13440 @item @emph{Return value}:
13441 The result is of the same type as @var{ARRAY}.
13443 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
13444 is returned. Otherwise, an array of rank n-1, where n equals the rank of
13445 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
13446 dropped is returned.
13448 @item @emph{Example}:
13451 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
13452 print *, SUM(x) ! all elements, sum = 15
13453 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
13457 @item @emph{See also}:
13464 @section @code{SYMLNK} --- Create a symbolic link
13466 @cindex file system, create link
13467 @cindex file system, soft link
13470 @item @emph{Description}:
13471 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
13472 character (@code{CHAR(0)}) can be used to mark the end of the names in
13473 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
13474 names are ignored. If the @var{STATUS} argument is supplied, it
13475 contains 0 on success or a nonzero error code upon return; see
13476 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
13477 @code{ENOSYS} is returned.
13479 This intrinsic is provided in both subroutine and function forms;
13480 however, only one form can be used in any given program unit.
13482 @item @emph{Standard}:
13485 @item @emph{Class}:
13486 Subroutine, function
13488 @item @emph{Syntax}:
13489 @multitable @columnfractions .80
13490 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
13491 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
13494 @item @emph{Arguments}:
13495 @multitable @columnfractions .15 .70
13496 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
13497 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
13498 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
13501 @item @emph{See also}:
13502 @ref{LINK}, @ref{UNLINK}
13509 @section @code{SYSTEM} --- Execute a shell command
13511 @cindex system, system call
13514 @item @emph{Description}:
13515 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
13516 argument @var{STATUS} is present, it contains the value returned by
13517 @code{system(3)}, which is presumably 0 if the shell command succeeded.
13518 Note that which shell is used to invoke the command is system-dependent
13519 and environment-dependent.
13521 This intrinsic is provided in both subroutine and function forms;
13522 however, only one form can be used in any given program unit.
13524 Note that the @code{system} function need not be thread-safe. It is
13525 the responsibility of the user to ensure that @code{system} is not
13526 called concurrently.
13528 @item @emph{Standard}:
13531 @item @emph{Class}:
13532 Subroutine, function
13534 @item @emph{Syntax}:
13535 @multitable @columnfractions .80
13536 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
13537 @item @code{STATUS = SYSTEM(COMMAND)}
13540 @item @emph{Arguments}:
13541 @multitable @columnfractions .15 .70
13542 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
13543 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
13546 @item @emph{See also}:
13547 @ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
13548 and should considered in new code for future portability.
13554 @section @code{SYSTEM_CLOCK} --- Time function
13555 @fnindex SYSTEM_CLOCK
13556 @cindex time, clock ticks
13557 @cindex clock ticks
13560 @item @emph{Description}:
13561 Determines the @var{COUNT} of a processor clock since an unspecified
13562 time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines
13563 the number of clock ticks per second. If the platform supports a
13564 monotonic clock, that clock is used and can, depending on the platform
13565 clock implementation, provide up to nanosecond resolution. If a
13566 monotonic clock is not available, the implementation falls back to a
13569 @var{COUNT_RATE} is system dependent and can vary depending on the kind of
13570 the arguments. For @var{kind=4} arguments (and smaller integer kinds),
13571 @var{COUNT} represents milliseconds, while for @var{kind=8} arguments (and
13572 larger integer kinds), @var{COUNT} typically represents micro- or
13573 nanoseconds depending on resolution of the underlying platform clock.
13574 @var{COUNT_MAX} usually equals @code{HUGE(COUNT_MAX)}. Note that the
13575 millisecond resolution of the @var{kind=4} version implies that the
13576 @var{COUNT} will wrap around in roughly 25 days. In order to avoid issues
13577 with the wrap around and for more precise timing, please use the
13578 @var{kind=8} version.
13580 If there is no clock, or querying the clock fails, @var{COUNT} is set
13581 to @code{-HUGE(COUNT)}, and @var{COUNT_RATE} and @var{COUNT_MAX} are
13584 When running on a platform using the GNU C library (glibc) version
13585 2.16 or older, or a derivative thereof, the high resolution monotonic
13586 clock is available only when linking with the @var{rt} library. This
13587 can be done explicitly by adding the @code{-lrt} flag when linking the
13588 application, but is also done implicitly when using OpenMP.
13590 On the Windows platform, the version with @var{kind=4} arguments uses
13591 the @code{GetTickCount} function, whereas the @var{kind=8} version
13592 uses @code{QueryPerformanceCounter} and
13593 @code{QueryPerformanceCounterFrequency}. For more information, and
13594 potential caveats, please see the platform documentation.
13596 @item @emph{Standard}:
13597 Fortran 95 and later
13599 @item @emph{Class}:
13602 @item @emph{Syntax}:
13603 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
13605 @item @emph{Arguments}:
13606 @multitable @columnfractions .15 .70
13607 @item @var{COUNT} @tab (Optional) shall be a scalar of type
13608 @code{INTEGER} with @code{INTENT(OUT)}.
13609 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type
13610 @code{INTEGER} or @code{REAL}, with @code{INTENT(OUT)}.
13611 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type
13612 @code{INTEGER} with @code{INTENT(OUT)}.
13615 @item @emph{Example}:
13617 PROGRAM test_system_clock
13618 INTEGER :: count, count_rate, count_max
13619 CALL SYSTEM_CLOCK(count, count_rate, count_max)
13620 WRITE(*,*) count, count_rate, count_max
13624 @item @emph{See also}:
13625 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
13631 @section @code{TAN} --- Tangent function
13634 @cindex trigonometric function, tangent
13638 @item @emph{Description}:
13639 @code{TAN(X)} computes the tangent of @var{X}.
13641 @item @emph{Standard}:
13642 Fortran 77 and later, for a complex argument Fortran 2008 or later
13644 @item @emph{Class}:
13647 @item @emph{Syntax}:
13648 @code{RESULT = TAN(X)}
13650 @item @emph{Arguments}:
13651 @multitable @columnfractions .15 .70
13652 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13655 @item @emph{Return value}:
13656 The return value has same type and kind as @var{X}, and its value is in radians.
13658 @item @emph{Example}:
13661 real(8) :: x = 0.165_8
13663 end program test_tan
13666 @item @emph{Specific names}:
13667 @multitable @columnfractions .20 .20 .20 .25
13668 @item Name @tab Argument @tab Return type @tab Standard
13669 @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
13670 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
13673 @item @emph{See also}:
13674 Inverse function: @ref{ATAN}
13675 Degrees function: @ref{TAND}
13681 @section @code{TAND} --- Tangent function, degrees
13684 @cindex trigonometric function, tangent, degrees
13685 @cindex tangent, degrees
13688 @item @emph{Description}:
13689 @code{TAND(X)} computes the tangent of @var{X} in degrees.
13691 This function is for compatibility only and should be avoided in favor of
13692 standard constructs wherever possible.
13694 @item @emph{Standard}:
13695 GNU Extension, enabled with @option{-fdec-math}.
13697 @item @emph{Class}:
13700 @item @emph{Syntax}:
13701 @code{RESULT = TAND(X)}
13703 @item @emph{Arguments}:
13704 @multitable @columnfractions .15 .70
13705 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13708 @item @emph{Return value}:
13709 The return value has same type and kind as @var{X}, and its value is in degrees.
13711 @item @emph{Example}:
13714 real(8) :: x = 0.165_8
13716 end program test_tand
13719 @item @emph{Specific names}:
13720 @multitable @columnfractions .20 .20 .20 .25
13721 @item Name @tab Argument @tab Return type @tab Standard
13722 @item @code{TAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
13723 @item @code{DTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
13726 @item @emph{See also}:
13727 Inverse function: @ref{ATAND}
13728 Radians function: @ref{TAN}
13734 @section @code{TANH} --- Hyperbolic tangent function
13737 @cindex hyperbolic tangent
13738 @cindex hyperbolic function, tangent
13739 @cindex tangent, hyperbolic
13742 @item @emph{Description}:
13743 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
13745 @item @emph{Standard}:
13746 Fortran 77 and later, for a complex argument Fortran 2008 or later
13748 @item @emph{Class}:
13751 @item @emph{Syntax}:
13754 @item @emph{Arguments}:
13755 @multitable @columnfractions .15 .70
13756 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13759 @item @emph{Return value}:
13760 The return value has same type and kind as @var{X}. If @var{X} is
13761 complex, the imaginary part of the result is in radians. If @var{X}
13762 is @code{REAL}, the return value lies in the range
13763 @math{ - 1 \leq tanh(x) \leq 1 }.
13765 @item @emph{Example}:
13768 real(8) :: x = 2.1_8
13770 end program test_tanh
13773 @item @emph{Specific names}:
13774 @multitable @columnfractions .20 .20 .20 .25
13775 @item Name @tab Argument @tab Return type @tab Standard
13776 @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
13777 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
13780 @item @emph{See also}:
13787 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
13788 @fnindex THIS_IMAGE
13789 @cindex coarray, @code{THIS_IMAGE}
13790 @cindex images, index of this image
13793 @item @emph{Description}:
13794 Returns the cosubscript for this image.
13796 @item @emph{Standard}:
13797 Fortran 2008 and later. With @var{DISTANCE} argument,
13798 Technical Specification (TS) 18508 or later
13800 @item @emph{Class}:
13801 Transformational function
13803 @item @emph{Syntax}:
13804 @multitable @columnfractions .80
13805 @item @code{RESULT = THIS_IMAGE()}
13806 @item @code{RESULT = THIS_IMAGE(DISTANCE)}
13807 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
13810 @item @emph{Arguments}:
13811 @multitable @columnfractions .15 .70
13812 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
13813 (not permitted together with @var{COARRAY}).
13814 @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
13815 present, required).
13816 @item @var{DIM} @tab default integer scalar (optional). If present,
13817 @var{DIM} shall be between one and the corank of @var{COARRAY}.
13821 @item @emph{Return value}:
13822 Default integer. If @var{COARRAY} is not present, it is scalar; if
13823 @var{DISTANCE} is not present or has value 0, its value is the image index on
13824 the invoking image for the current team, for values smaller or equal
13825 distance to the initial team, it returns the image index on the ancestor team
13826 which has a distance of @var{DISTANCE} from the invoking team. If
13827 @var{DISTANCE} is larger than the distance to the initial team, the image
13828 index of the initial team is returned. Otherwise when the @var{COARRAY} is
13829 present, if @var{DIM} is not present, a rank-1 array with corank elements is
13830 returned, containing the cosubscripts for @var{COARRAY} specifying the invoking
13831 image. If @var{DIM} is present, a scalar is returned, with the value of
13832 the @var{DIM} element of @code{THIS_IMAGE(COARRAY)}.
13834 @item @emph{Example}:
13836 INTEGER :: value[*]
13838 value = THIS_IMAGE()
13840 IF (THIS_IMAGE() == 1) THEN
13841 DO i = 1, NUM_IMAGES()
13842 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
13846 ! Check whether the current image is the initial image
13847 IF (THIS_IMAGE(HUGE(1)) /= THIS_IMAGE())
13848 error stop "something is rotten here"
13851 @item @emph{See also}:
13852 @ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
13858 @section @code{TIME} --- Time function
13860 @cindex time, current
13861 @cindex current time
13864 @item @emph{Description}:
13865 Returns the current time encoded as an integer (in the manner of the
13866 function @code{time(3)} in the C standard library). This value is
13867 suitable for passing to @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
13869 This intrinsic is not fully portable, such as to systems with 32-bit
13870 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
13871 the values returned by this intrinsic might be, or become, negative, or
13872 numerically less than previous values, during a single run of the
13875 See @ref{TIME8}, for information on a similar intrinsic that might be
13876 portable to more GNU Fortran implementations, though to fewer Fortran
13879 @item @emph{Standard}:
13882 @item @emph{Class}:
13885 @item @emph{Syntax}:
13886 @code{RESULT = TIME()}
13888 @item @emph{Return value}:
13889 The return value is a scalar of type @code{INTEGER(4)}.
13891 @item @emph{See also}:
13892 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
13899 @section @code{TIME8} --- Time function (64-bit)
13901 @cindex time, current
13902 @cindex current time
13905 @item @emph{Description}:
13906 Returns the current time encoded as an integer (in the manner of the
13907 function @code{time(3)} in the C standard library). This value is
13908 suitable for passing to @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
13910 @emph{Warning:} this intrinsic does not increase the range of the timing
13911 values over that returned by @code{time(3)}. On a system with a 32-bit
13912 @code{time(3)}, @code{TIME8} will return a 32-bit value, even though
13913 it is converted to a 64-bit @code{INTEGER(8)} value. That means
13914 overflows of the 32-bit value can still occur. Therefore, the values
13915 returned by this intrinsic might be or become negative or numerically
13916 less than previous values during a single run of the compiled program.
13918 @item @emph{Standard}:
13921 @item @emph{Class}:
13924 @item @emph{Syntax}:
13925 @code{RESULT = TIME8()}
13927 @item @emph{Return value}:
13928 The return value is a scalar of type @code{INTEGER(8)}.
13930 @item @emph{See also}:
13931 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
13938 @section @code{TINY} --- Smallest positive number of a real kind
13940 @cindex limits, smallest number
13941 @cindex model representation, smallest number
13944 @item @emph{Description}:
13945 @code{TINY(X)} returns the smallest positive (non zero) number
13946 in the model of the type of @code{X}.
13948 @item @emph{Standard}:
13949 Fortran 95 and later
13951 @item @emph{Class}:
13954 @item @emph{Syntax}:
13955 @code{RESULT = TINY(X)}
13957 @item @emph{Arguments}:
13958 @multitable @columnfractions .15 .70
13959 @item @var{X} @tab Shall be of type @code{REAL}.
13962 @item @emph{Return value}:
13963 The return value is of the same type and kind as @var{X}
13965 @item @emph{Example}:
13966 See @code{HUGE} for an example.
13972 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
13977 @item @emph{Description}:
13978 @code{TRAILZ} returns the number of trailing zero bits of an integer.
13980 @item @emph{Standard}:
13981 Fortran 2008 and later
13983 @item @emph{Class}:
13986 @item @emph{Syntax}:
13987 @code{RESULT = TRAILZ(I)}
13989 @item @emph{Arguments}:
13990 @multitable @columnfractions .15 .70
13991 @item @var{I} @tab Shall be of type @code{INTEGER}.
13994 @item @emph{Return value}:
13995 The type of the return value is the default @code{INTEGER}.
13996 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
13998 @item @emph{Example}:
14000 PROGRAM test_trailz
14001 WRITE (*,*) TRAILZ(8) ! prints 3
14005 @item @emph{See also}:
14006 @ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT}
14012 @section @code{TRANSFER} --- Transfer bit patterns
14018 @item @emph{Description}:
14019 Interprets the bitwise representation of @var{SOURCE} in memory as if it
14020 is the representation of a variable or array of the same type and type
14021 parameters as @var{MOLD}.
14023 This is approximately equivalent to the C concept of @emph{casting} one
14026 @item @emph{Standard}:
14027 Fortran 95 and later
14029 @item @emph{Class}:
14030 Transformational function
14032 @item @emph{Syntax}:
14033 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
14035 @item @emph{Arguments}:
14036 @multitable @columnfractions .15 .70
14037 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
14038 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
14039 @item @var{SIZE} @tab (Optional) shall be a scalar of type
14043 @item @emph{Return value}:
14044 The result has the same type as @var{MOLD}, with the bit level
14045 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
14046 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
14047 but @var{MOLD} is an array (of any size or shape), the result is a one-
14048 dimensional array of the minimum length needed to contain the entirety
14049 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
14050 and @var{MOLD} is a scalar, the result is a scalar.
14052 If the bitwise representation of the result is longer than that of
14053 @var{SOURCE}, then the leading bits of the result correspond to those of
14054 @var{SOURCE} and any trailing bits are filled arbitrarily.
14056 When the resulting bit representation does not correspond to a valid
14057 representation of a variable of the same type as @var{MOLD}, the results
14058 are undefined, and subsequent operations on the result cannot be
14059 guaranteed to produce sensible behavior. For example, it is possible to
14060 create @code{LOGICAL} variables for which @code{@var{VAR}} and
14061 @code{.NOT.@var{VAR}} both appear to be true.
14063 @item @emph{Example}:
14065 PROGRAM test_transfer
14066 integer :: x = 2143289344
14067 print *, transfer(x, 1.0) ! prints "NaN" on i686
14075 @section @code{TRANSPOSE} --- Transpose an array of rank two
14077 @cindex array, transpose
14078 @cindex matrix, transpose
14082 @item @emph{Description}:
14083 Transpose an array of rank two. Element (i, j) of the result has the value
14084 @code{MATRIX(j, i)}, for all i, j.
14086 @item @emph{Standard}:
14087 Fortran 95 and later
14089 @item @emph{Class}:
14090 Transformational function
14092 @item @emph{Syntax}:
14093 @code{RESULT = TRANSPOSE(MATRIX)}
14095 @item @emph{Arguments}:
14096 @multitable @columnfractions .15 .70
14097 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
14100 @item @emph{Return value}:
14101 The result has the same type as @var{MATRIX}, and has shape
14102 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
14108 @section @code{TRIM} --- Remove trailing blank characters of a string
14110 @cindex string, remove trailing whitespace
14113 @item @emph{Description}:
14114 Removes trailing blank characters of a string.
14116 @item @emph{Standard}:
14117 Fortran 95 and later
14119 @item @emph{Class}:
14120 Transformational function
14122 @item @emph{Syntax}:
14123 @code{RESULT = TRIM(STRING)}
14125 @item @emph{Arguments}:
14126 @multitable @columnfractions .15 .70
14127 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
14130 @item @emph{Return value}:
14131 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
14132 less the number of trailing blanks.
14134 @item @emph{Example}:
14137 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
14138 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
14142 @item @emph{See also}:
14143 @ref{ADJUSTL}, @ref{ADJUSTR}
14149 @section @code{TTYNAM} --- Get the name of a terminal device.
14151 @cindex system, terminal
14154 @item @emph{Description}:
14155 Get the name of a terminal device. For more information,
14156 see @code{ttyname(3)}.
14158 This intrinsic is provided in both subroutine and function forms;
14159 however, only one form can be used in any given program unit.
14161 @item @emph{Standard}:
14164 @item @emph{Class}:
14165 Subroutine, function
14167 @item @emph{Syntax}:
14168 @multitable @columnfractions .80
14169 @item @code{CALL TTYNAM(UNIT, NAME)}
14170 @item @code{NAME = TTYNAM(UNIT)}
14173 @item @emph{Arguments}:
14174 @multitable @columnfractions .15 .70
14175 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
14176 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
14179 @item @emph{Example}:
14181 PROGRAM test_ttynam
14184 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
14189 @item @emph{See also}:
14196 @section @code{UBOUND} --- Upper dimension bounds of an array
14198 @cindex array, upper bound
14201 @item @emph{Description}:
14202 Returns the upper bounds of an array, or a single upper bound
14203 along the @var{DIM} dimension.
14204 @item @emph{Standard}:
14205 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
14207 @item @emph{Class}:
14210 @item @emph{Syntax}:
14211 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
14213 @item @emph{Arguments}:
14214 @multitable @columnfractions .15 .70
14215 @item @var{ARRAY} @tab Shall be an array, of any type.
14216 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
14217 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
14218 expression indicating the kind parameter of the result.
14221 @item @emph{Return value}:
14222 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14223 @var{KIND} is absent, the return value is of default integer kind.
14224 If @var{DIM} is absent, the result is an array of the upper bounds of
14225 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
14226 corresponding to the upper bound of the array along that dimension. If
14227 @var{ARRAY} is an expression rather than a whole array or array
14228 structure component, or if it has a zero extent along the relevant
14229 dimension, the upper bound is taken to be the number of elements along
14230 the relevant dimension.
14232 @item @emph{See also}:
14233 @ref{LBOUND}, @ref{LCOBOUND}
14239 @section @code{UCOBOUND} --- Upper codimension bounds of an array
14241 @cindex coarray, upper bound
14244 @item @emph{Description}:
14245 Returns the upper cobounds of a coarray, or a single upper cobound
14246 along the @var{DIM} codimension.
14247 @item @emph{Standard}:
14248 Fortran 2008 and later
14250 @item @emph{Class}:
14253 @item @emph{Syntax}:
14254 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
14256 @item @emph{Arguments}:
14257 @multitable @columnfractions .15 .70
14258 @item @var{ARRAY} @tab Shall be an coarray, of any type.
14259 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
14260 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
14261 expression indicating the kind parameter of the result.
14264 @item @emph{Return value}:
14265 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14266 @var{KIND} is absent, the return value is of default integer kind.
14267 If @var{DIM} is absent, the result is an array of the lower cobounds of
14268 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
14269 corresponding to the lower cobound of the array along that codimension.
14271 @item @emph{See also}:
14272 @ref{LCOBOUND}, @ref{LBOUND}
14278 @section @code{UMASK} --- Set the file creation mask
14280 @cindex file system, file creation mask
14283 @item @emph{Description}:
14284 Sets the file creation mask to @var{MASK}. If called as a function, it
14285 returns the old value. If called as a subroutine and argument @var{OLD}
14286 if it is supplied, it is set to the old value. See @code{umask(2)}.
14288 @item @emph{Standard}:
14291 @item @emph{Class}:
14292 Subroutine, function
14294 @item @emph{Syntax}:
14295 @multitable @columnfractions .80
14296 @item @code{CALL UMASK(MASK [, OLD])}
14297 @item @code{OLD = UMASK(MASK)}
14300 @item @emph{Arguments}:
14301 @multitable @columnfractions .15 .70
14302 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
14303 @item @var{OLD} @tab (Optional) Shall be a scalar of type
14312 @section @code{UNLINK} --- Remove a file from the file system
14314 @cindex file system, remove file
14317 @item @emph{Description}:
14318 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
14319 used to mark the end of the name in @var{PATH}; otherwise, trailing
14320 blanks in the file name are ignored. If the @var{STATUS} argument is
14321 supplied, it contains 0 on success or a nonzero error code upon return;
14322 see @code{unlink(2)}.
14324 This intrinsic is provided in both subroutine and function forms;
14325 however, only one form can be used in any given program unit.
14327 @item @emph{Standard}:
14330 @item @emph{Class}:
14331 Subroutine, function
14333 @item @emph{Syntax}:
14334 @multitable @columnfractions .80
14335 @item @code{CALL UNLINK(PATH [, STATUS])}
14336 @item @code{STATUS = UNLINK(PATH)}
14339 @item @emph{Arguments}:
14340 @multitable @columnfractions .15 .70
14341 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
14342 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
14345 @item @emph{See also}:
14346 @ref{LINK}, @ref{SYMLNK}
14352 @section @code{UNPACK} --- Unpack an array of rank one into an array
14354 @cindex array, unpacking
14355 @cindex array, increase dimension
14356 @cindex array, scatter elements
14359 @item @emph{Description}:
14360 Store the elements of @var{VECTOR} in an array of higher rank.
14362 @item @emph{Standard}:
14363 Fortran 95 and later
14365 @item @emph{Class}:
14366 Transformational function
14368 @item @emph{Syntax}:
14369 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
14371 @item @emph{Arguments}:
14372 @multitable @columnfractions .15 .70
14373 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
14374 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
14375 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
14376 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
14377 the same shape as @var{MASK}.
14380 @item @emph{Return value}:
14381 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
14382 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
14384 @item @emph{Example}:
14386 PROGRAM test_unpack
14387 integer :: vector(2) = (/1,1/)
14388 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
14389 integer :: field(2,2) = 0, unity(2,2)
14391 ! result: unity matrix
14392 unity = unpack(vector, reshape(mask, (/2,2/)), field)
14396 @item @emph{See also}:
14397 @ref{PACK}, @ref{SPREAD}
14403 @section @code{VERIFY} --- Scan a string for characters not a given set
14405 @cindex string, find missing set
14408 @item @emph{Description}:
14409 Verifies that all the characters in @var{STRING} belong to the set of
14410 characters in @var{SET}.
14412 If @var{BACK} is either absent or equals @code{FALSE}, this function
14413 returns the position of the leftmost character of @var{STRING} that is
14414 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost
14415 position is returned. If all characters of @var{STRING} are found in
14416 @var{SET}, the result is zero.
14418 @item @emph{Standard}:
14419 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
14421 @item @emph{Class}:
14424 @item @emph{Syntax}:
14425 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
14427 @item @emph{Arguments}:
14428 @multitable @columnfractions .15 .70
14429 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
14430 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
14431 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
14432 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
14433 expression indicating the kind parameter of the result.
14436 @item @emph{Return value}:
14437 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14438 @var{KIND} is absent, the return value is of default integer kind.
14440 @item @emph{Example}:
14442 PROGRAM test_verify
14443 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
14444 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
14445 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
14446 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
14447 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
14451 @item @emph{See also}:
14452 @ref{SCAN}, @ref{INDEX intrinsic}
14458 @section @code{XOR} --- Bitwise logical exclusive OR
14460 @cindex bitwise logical exclusive or
14461 @cindex logical exclusive or, bitwise
14464 @item @emph{Description}:
14465 Bitwise logical exclusive or.
14467 This intrinsic routine is provided for backwards compatibility with
14468 GNU Fortran 77. For integer arguments, programmers should consider
14469 the use of the @ref{IEOR} intrinsic and for logical arguments the
14470 @code{.NEQV.} operator, which are both defined by the Fortran standard.
14472 @item @emph{Standard}:
14475 @item @emph{Class}:
14478 @item @emph{Syntax}:
14479 @code{RESULT = XOR(I, J)}
14481 @item @emph{Arguments}:
14482 @multitable @columnfractions .15 .70
14483 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
14484 type or a scalar @code{LOGICAL} type.
14485 @item @var{J} @tab The type shall be the same as the type of @var{I}.
14488 @item @emph{Return value}:
14489 The return type is either a scalar @code{INTEGER} or a scalar
14490 @code{LOGICAL}. If the kind type parameters differ, then the
14491 smaller kind type is implicitly converted to larger kind, and the
14492 return has the larger kind.
14494 @item @emph{Example}:
14497 LOGICAL :: T = .TRUE., F = .FALSE.
14499 DATA a / Z'F' /, b / Z'3' /
14501 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
14502 WRITE (*,*) XOR(a, b)
14506 @item @emph{See also}:
14507 Fortran 95 elemental function: @ref{IEOR}
14512 @node Intrinsic Modules
14513 @chapter Intrinsic Modules
14514 @cindex intrinsic Modules
14517 * ISO_FORTRAN_ENV::
14520 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
14521 * OpenACC Module OPENACC::
14524 @node ISO_FORTRAN_ENV
14525 @section @code{ISO_FORTRAN_ENV}
14527 @item @emph{Standard}:
14528 Fortran 2003 and later, except when otherwise noted
14531 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
14535 @item @code{ATOMIC_INT_KIND}:
14536 Default-kind integer constant to be used as kind parameter when defining
14537 integer variables used in atomic operations. (Fortran 2008 or later.)
14539 @item @code{ATOMIC_LOGICAL_KIND}:
14540 Default-kind integer constant to be used as kind parameter when defining
14541 logical variables used in atomic operations. (Fortran 2008 or later.)
14543 @item @code{CHARACTER_KINDS}:
14544 Default-kind integer constant array of rank one containing the supported kind
14545 parameters of the @code{CHARACTER} type. (Fortran 2008 or later.)
14547 @item @code{CHARACTER_STORAGE_SIZE}:
14548 Size in bits of the character storage unit.
14550 @item @code{ERROR_UNIT}:
14551 Identifies the preconnected unit used for error reporting.
14553 @item @code{FILE_STORAGE_SIZE}:
14554 Size in bits of the file-storage unit.
14556 @item @code{INPUT_UNIT}:
14557 Identifies the preconnected unit identified by the asterisk
14558 (@code{*}) in @code{READ} statement.
14560 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
14561 Kind type parameters to specify an INTEGER type with a storage
14562 size of 16, 32, and 64 bits. It is negative if a target platform
14563 does not support the particular kind. (Fortran 2008 or later.)
14565 @item @code{INTEGER_KINDS}:
14566 Default-kind integer constant array of rank one containing the supported kind
14567 parameters of the @code{INTEGER} type. (Fortran 2008 or later.)
14569 @item @code{IOSTAT_END}:
14570 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
14571 an input/output statement if an end-of-file condition occurred.
14573 @item @code{IOSTAT_EOR}:
14574 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
14575 an input/output statement if an end-of-record condition occurred.
14577 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
14578 Scalar default-integer constant, used by @code{INQUIRE} for the
14579 @code{IOSTAT=} specifier to denote an that a unit number identifies an
14580 internal unit. (Fortran 2008 or later.)
14582 @item @code{NUMERIC_STORAGE_SIZE}:
14583 The size in bits of the numeric storage unit.
14585 @item @code{LOGICAL_KINDS}:
14586 Default-kind integer constant array of rank one containing the supported kind
14587 parameters of the @code{LOGICAL} type. (Fortran 2008 or later.)
14589 @item @code{OUTPUT_UNIT}:
14590 Identifies the preconnected unit identified by the asterisk
14591 (@code{*}) in @code{WRITE} statement.
14593 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
14594 Kind type parameters to specify a REAL type with a storage
14595 size of 32, 64, and 128 bits. It is negative if a target platform
14596 does not support the particular kind. (Fortran 2008 or later.)
14598 @item @code{REAL_KINDS}:
14599 Default-kind integer constant array of rank one containing the supported kind
14600 parameters of the @code{REAL} type. (Fortran 2008 or later.)
14602 @item @code{STAT_LOCKED}:
14603 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
14604 denote that the lock variable is locked by the executing image. (Fortran 2008
14607 @item @code{STAT_LOCKED_OTHER_IMAGE}:
14608 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
14609 denote that the lock variable is locked by another image. (Fortran 2008 or
14612 @item @code{STAT_STOPPED_IMAGE}:
14613 Positive, scalar default-integer constant used as STAT= return value if the
14614 argument in the statement requires synchronisation with an image, which has
14615 initiated the termination of the execution. (Fortran 2008 or later.)
14617 @item @code{STAT_FAILED_IMAGE}:
14618 Positive, scalar default-integer constant used as STAT= return value if the
14619 argument in the statement requires communication with an image, which has
14620 is in the failed state. (TS 18508 or later.)
14622 @item @code{STAT_UNLOCKED}:
14623 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
14624 denote that the lock variable is unlocked. (Fortran 2008 or later.)
14627 The module provides the following derived type:
14630 @item @code{LOCK_TYPE}:
14631 Derived type with private components to be use with the @code{LOCK} and
14632 @code{UNLOCK} statement. A variable of its type has to be always declared
14633 as coarray and may not appear in a variable-definition context.
14634 (Fortran 2008 or later.)
14637 The module also provides the following intrinsic procedures:
14638 @ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}.
14642 @node ISO_C_BINDING
14643 @section @code{ISO_C_BINDING}
14645 @item @emph{Standard}:
14646 Fortran 2003 and later, GNU extensions
14649 The following intrinsic procedures are provided by the module; their
14650 definition can be found in the section Intrinsic Procedures of this
14654 @item @code{C_ASSOCIATED}
14655 @item @code{C_F_POINTER}
14656 @item @code{C_F_PROCPOINTER}
14657 @item @code{C_FUNLOC}
14659 @item @code{C_SIZEOF}
14661 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
14662 @c don't really know why.
14664 The @code{ISO_C_BINDING} module provides the following named constants of
14665 type default integer, which can be used as KIND type parameters.
14667 In addition to the integer named constants required by the Fortran 2003
14668 standard and @code{C_PTRDIFF_T} of TS 29113, GNU Fortran provides as an
14669 extension named constants for the 128-bit integer types supported by the
14670 C compiler: @code{C_INT128_T, C_INT_LEAST128_T, C_INT_FAST128_T}.
14671 Furthermore, if @code{__float128} is supported in C, the named constants
14672 @code{C_FLOAT128, C_FLOAT128_COMPLEX} are defined.
14674 @multitable @columnfractions .15 .35 .35 .35
14675 @item Fortran Type @tab Named constant @tab C type @tab Extension
14676 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
14677 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
14678 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
14679 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
14680 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
14681 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
14682 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
14683 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
14684 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
14685 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
14686 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
14687 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
14688 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
14689 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
14690 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
14691 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
14692 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
14693 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
14694 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
14695 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
14696 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
14697 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
14698 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
14699 @item @code{INTEGER}@tab @code{C_PTRDIFF_T} @tab @code{intptr_t} @tab TS 29113
14700 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
14701 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
14702 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
14703 @item @code{REAL} @tab @code{C_FLOAT128} @tab @code{__float128} @tab Ext.
14704 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
14705 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
14706 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
14707 @item @code{REAL} @tab @code{C_FLOAT128_COMPLEX} @tab @code{__float128 _Complex} @tab Ext.
14708 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
14709 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
14712 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
14715 @multitable @columnfractions .20 .45 .15
14716 @item Name @tab C definition @tab Value
14717 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
14718 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
14719 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
14720 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
14721 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
14722 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
14723 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
14724 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
14727 Moreover, the following two named constants are defined:
14729 @multitable @columnfractions .20 .80
14730 @item Name @tab Type
14731 @item @code{C_NULL_PTR} @tab @code{C_PTR}
14732 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
14735 Both are equivalent to the value @code{NULL} in C.
14740 @section IEEE modules: @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
14742 @item @emph{Standard}:
14743 Fortran 2003 and later
14746 The @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
14747 intrinsic modules provide support for exceptions and IEEE arithmetic, as
14748 defined in Fortran 2003 and later standards, and the IEC 60559:1989 standard
14749 (@emph{Binary floating-point arithmetic for microprocessor systems}). These
14750 modules are only provided on the following supported platforms:
14753 @item i386 and x86_64 processors
14754 @item platforms which use the GNU C Library (glibc)
14755 @item platforms with support for SysV/386 routines for floating point
14756 interface (including Solaris and BSDs)
14757 @item platforms with the AIX OS
14760 For full compliance with the Fortran standards, code using the
14761 @code{IEEE_EXCEPTIONS} or @code{IEEE_ARITHMETIC} modules should be compiled
14762 with the following options: @code{-fno-unsafe-math-optimizations
14763 -frounding-math -fsignaling-nans}.
14767 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
14768 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
14770 @item @emph{Standard}:
14771 OpenMP Application Program Interface v4.0
14775 The OpenMP Fortran runtime library routines are provided both in
14776 a form of two Fortran 90 modules, named @code{OMP_LIB} and
14777 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
14778 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
14779 in the @ref{Top,,Introduction,libgomp,GNU Offloading and Multi
14780 Processing Runtime Library} manual,
14781 the named constants defined in the modules are listed
14784 For details refer to the actual
14785 @uref{http://www.openmp.org/mp-documents/OpenMP4.0.0.pdf,
14786 OpenMP Application Program Interface v4.0}.
14788 @code{OMP_LIB_KINDS} provides the following scalar default-integer
14792 @item @code{omp_lock_kind}
14793 @item @code{omp_nest_lock_kind}
14794 @item @code{omp_proc_bind_kind}
14795 @item @code{omp_sched_kind}
14798 @code{OMP_LIB} provides the scalar default-integer
14799 named constant @code{openmp_version} with a value of the form
14800 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
14801 of the OpenMP version; for OpenMP v4.0 the value is @code{201307}.
14803 The following scalar integer named constants of the
14804 kind @code{omp_sched_kind}:
14807 @item @code{omp_sched_static}
14808 @item @code{omp_sched_dynamic}
14809 @item @code{omp_sched_guided}
14810 @item @code{omp_sched_auto}
14813 And the following scalar integer named constants of the
14814 kind @code{omp_proc_bind_kind}:
14817 @item @code{omp_proc_bind_false}
14818 @item @code{omp_proc_bind_true}
14819 @item @code{omp_proc_bind_master}
14820 @item @code{omp_proc_bind_close}
14821 @item @code{omp_proc_bind_spread}
14826 @node OpenACC Module OPENACC
14827 @section OpenACC Module @code{OPENACC}
14829 @item @emph{Standard}:
14830 OpenACC Application Programming Interface v2.0
14834 The OpenACC Fortran runtime library routines are provided both in a
14835 form of a Fortran 90 module, named @code{OPENACC}, and in form of a
14836 Fortran @code{include} file named @file{openacc_lib.h}. The
14837 procedures provided by @code{OPENACC} can be found in the
14838 @ref{Top,,Introduction,libgomp,GNU Offloading and Multi Processing
14839 Runtime Library} manual, the named constants defined in the modules
14842 For details refer to the actual
14843 @uref{http://www.openacc.org/,
14844 OpenACC Application Programming Interface v2.0}.
14846 @code{OPENACC} provides the scalar default-integer
14847 named constant @code{openacc_version} with a value of the form
14848 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
14849 of the OpenACC version; for OpenACC v2.0 the value is @code{201306}.