2 Copyright (C) 2005-2021 Free Software Foundation, Inc.
3 This is part of the GNU Fortran manual.
4 For copying conditions, see the file gfortran.texi.
6 Permission is granted to copy, distribute and/or modify this document
7 under the terms of the GNU Free Documentation License, Version 1.3 or
8 any later version published by the Free Software Foundation; with the
9 Invariant Sections being ``Funding Free Software'', the Front-Cover
10 Texts being (a) (see below), and with the Back-Cover Texts being (b)
11 (see below). A copy of the license is included in the gfdl(7) man page.
14 Some basic guidelines for editing this document:
16 (1) The intrinsic procedures are to be listed in alphabetical order.
17 (2) The generic name is to be used.
18 (3) The specific names are included in the function index and in a
19 table at the end of the node (See ABS entry).
20 (4) Try to maintain the same style for each entry.
26 \gdef\acosd{\mathop{\rm acosd}\nolimits}
27 \gdef\asind{\mathop{\rm asind}\nolimits}
28 \gdef\atand{\mathop{\rm atand}\nolimits}
29 \gdef\acos{\mathop{\rm acos}\nolimits}
30 \gdef\asin{\mathop{\rm asin}\nolimits}
31 \gdef\atan{\mathop{\rm atan}\nolimits}
32 \gdef\acosh{\mathop{\rm acosh}\nolimits}
33 \gdef\asinh{\mathop{\rm asinh}\nolimits}
34 \gdef\atanh{\mathop{\rm atanh}\nolimits}
35 \gdef\cosd{\mathop{\rm cosd}\nolimits}
39 @node Intrinsic Procedures
40 @chapter Intrinsic Procedures
41 @cindex intrinsic procedures
44 * Introduction: Introduction to Intrinsics
45 * @code{ABORT}: ABORT, Abort the program
46 * @code{ABS}: ABS, Absolute value
47 * @code{ACCESS}: ACCESS, Checks file access modes
48 * @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence
49 * @code{ACOS}: ACOS, Arccosine function
50 * @code{ACOSD}: ACOSD, Arccosine function, degrees
51 * @code{ACOSH}: ACOSH, Inverse hyperbolic cosine function
52 * @code{ADJUSTL}: ADJUSTL, Left adjust a string
53 * @code{ADJUSTR}: ADJUSTR, Right adjust a string
54 * @code{AIMAG}: AIMAG, Imaginary part of complex number
55 * @code{AINT}: AINT, Truncate to a whole number
56 * @code{ALARM}: ALARM, Set an alarm clock
57 * @code{ALL}: ALL, Determine if all values are true
58 * @code{ALLOCATED}: ALLOCATED, Status of allocatable entity
59 * @code{AND}: AND, Bitwise logical AND
60 * @code{ANINT}: ANINT, Nearest whole number
61 * @code{ANY}: ANY, Determine if any values are true
62 * @code{ASIN}: ASIN, Arcsine function
63 * @code{ASIND}: ASIND, Arcsine function, degrees
64 * @code{ASINH}: ASINH, Inverse hyperbolic sine function
65 * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair
66 * @code{ATAN}: ATAN, Arctangent function
67 * @code{ATAND}: ATAND, Arctangent function, degrees
68 * @code{ATAN2}: ATAN2, Arctangent function
69 * @code{ATAN2D}: ATAN2D, Arctangent function, degrees
70 * @code{ATANH}: ATANH, Inverse hyperbolic tangent function
71 * @code{ATOMIC_ADD}: ATOMIC_ADD, Atomic ADD operation
72 * @code{ATOMIC_AND}: ATOMIC_AND, Atomic bitwise AND operation
73 * @code{ATOMIC_CAS}: ATOMIC_CAS, Atomic compare and swap
74 * @code{ATOMIC_DEFINE}: ATOMIC_DEFINE, Setting a variable atomically
75 * @code{ATOMIC_FETCH_ADD}: ATOMIC_FETCH_ADD, Atomic ADD operation with prior fetch
76 * @code{ATOMIC_FETCH_AND}: ATOMIC_FETCH_AND, Atomic bitwise AND operation with prior fetch
77 * @code{ATOMIC_FETCH_OR}: ATOMIC_FETCH_OR, Atomic bitwise OR operation with prior fetch
78 * @code{ATOMIC_FETCH_XOR}: ATOMIC_FETCH_XOR, Atomic bitwise XOR operation with prior fetch
79 * @code{ATOMIC_OR}: ATOMIC_OR, Atomic bitwise OR operation
80 * @code{ATOMIC_REF}: ATOMIC_REF, Obtaining the value of a variable atomically
81 * @code{ATOMIC_XOR}: ATOMIC_XOR, Atomic bitwise OR operation
82 * @code{BACKTRACE}: BACKTRACE, Show a backtrace
83 * @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0
84 * @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1
85 * @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind
86 * @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0
87 * @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1
88 * @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind
89 * @code{BGE}: BGE, Bitwise greater than or equal to
90 * @code{BGT}: BGT, Bitwise greater than
91 * @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function
92 * @code{BLE}: BLE, Bitwise less than or equal to
93 * @code{BLT}: BLT, Bitwise less than
94 * @code{BTEST}: BTEST, Bit test function
95 * @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer
96 * @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer
97 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
98 * @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure
99 * @code{C_LOC}: C_LOC, Obtain the C address of an object
100 * @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression
101 * @code{CEILING}: CEILING, Integer ceiling function
102 * @code{CHAR}: CHAR, Integer-to-character conversion function
103 * @code{CHDIR}: CHDIR, Change working directory
104 * @code{CHMOD}: CHMOD, Change access permissions of files
105 * @code{CMPLX}: CMPLX, Complex conversion function
106 * @code{CO_BROADCAST}: CO_BROADCAST, Copy a value to all images the current set of images
107 * @code{CO_MAX}: CO_MAX, Maximal value on the current set of images
108 * @code{CO_MIN}: CO_MIN, Minimal value on the current set of images
109 * @code{CO_REDUCE}: CO_REDUCE, Reduction of values on the current set of images
110 * @code{CO_SUM}: CO_SUM, Sum of values on the current set of images
111 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
112 * @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler
113 * @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string
114 * @code{COMPLEX}: COMPLEX, Complex conversion function
115 * @code{CONJG}: CONJG, Complex conjugate function
116 * @code{COS}: COS, Cosine function
117 * @code{COSD}: COSD, Cosine function, degrees
118 * @code{COSH}: COSH, Hyperbolic cosine function
119 * @code{COTAN}: COTAN, Cotangent function
120 * @code{COTAND}: COTAND, Cotangent function, degrees
121 * @code{COUNT}: COUNT, Count occurrences of TRUE in an array
122 * @code{CPU_TIME}: CPU_TIME, CPU time subroutine
123 * @code{CSHIFT}: CSHIFT, Circular shift elements of an array
124 * @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string
125 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
126 * @code{DBLE}: DBLE, Double precision conversion function
127 * @code{DCMPLX}: DCMPLX, Double complex conversion function
128 * @code{DIGITS}: DIGITS, Significant digits function
129 * @code{DIM}: DIM, Positive difference
130 * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
131 * @code{DPROD}: DPROD, Double product function
132 * @code{DREAL}: DREAL, Double real part function
133 * @code{DSHIFTL}: DSHIFTL, Combined left shift
134 * @code{DSHIFTR}: DSHIFTR, Combined right shift
135 * @code{DTIME}: DTIME, Execution time subroutine (or function)
136 * @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array
137 * @code{EPSILON}: EPSILON, Epsilon function
138 * @code{ERF}: ERF, Error function
139 * @code{ERFC}: ERFC, Complementary error function
140 * @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function
141 * @code{ETIME}: ETIME, Execution time subroutine (or function)
142 * @code{EVENT_QUERY}: EVENT_QUERY, Query whether a coarray event has occurred
143 * @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command
144 * @code{EXIT}: EXIT, Exit the program with status.
145 * @code{EXP}: EXP, Exponential function
146 * @code{EXPONENT}: EXPONENT, Exponent function
147 * @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF, Query dynamic type for extension
148 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
149 * @code{FGET}: FGET, Read a single character in stream mode from stdin
150 * @code{FGETC}: FGETC, Read a single character in stream mode
151 * @code{FINDLOC}: FINDLOC, Search an array for a value
152 * @code{FLOOR}: FLOOR, Integer floor function
153 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
154 * @code{FNUM}: FNUM, File number function
155 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
156 * @code{FPUTC}: FPUTC, Write a single character in stream mode
157 * @code{FRACTION}: FRACTION, Fractional part of the model representation
158 * @code{FREE}: FREE, Memory de-allocation subroutine
159 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
160 * @code{FSTAT}: FSTAT, Get file status
161 * @code{FTELL}: FTELL, Current stream position
162 * @code{GAMMA}: GAMMA, Gamma function
163 * @code{GERROR}: GERROR, Get last system error message
164 * @code{GETARG}: GETARG, Get command line arguments
165 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
166 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
167 * @code{GETCWD}: GETCWD, Get current working directory
168 * @code{GETENV}: GETENV, Get an environmental variable
169 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
170 * @code{GETGID}: GETGID, Group ID function
171 * @code{GETLOG}: GETLOG, Get login name
172 * @code{GETPID}: GETPID, Process ID function
173 * @code{GETUID}: GETUID, User ID function
174 * @code{GMTIME}: GMTIME, Convert time to GMT info
175 * @code{HOSTNM}: HOSTNM, Get system host name
176 * @code{HUGE}: HUGE, Largest number of a kind
177 * @code{HYPOT}: HYPOT, Euclidean distance function
178 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
179 * @code{IALL}: IALL, Bitwise AND of array elements
180 * @code{IAND}: IAND, Bitwise logical and
181 * @code{IANY}: IANY, Bitwise OR of array elements
182 * @code{IARGC}: IARGC, Get the number of command line arguments
183 * @code{IBCLR}: IBCLR, Clear bit
184 * @code{IBITS}: IBITS, Bit extraction
185 * @code{IBSET}: IBSET, Set bit
186 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
187 * @code{IDATE}: IDATE, Current local time (day/month/year)
188 * @code{IEOR}: IEOR, Bitwise logical exclusive or
189 * @code{IERRNO}: IERRNO, Function to get the last system error number
190 * @code{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index conversion
191 * @code{INDEX}: INDEX intrinsic, Position of a substring within a string
192 * @code{INT}: INT, Convert to integer type
193 * @code{INT2}: INT2, Convert to 16-bit integer type
194 * @code{INT8}: INT8, Convert to 64-bit integer type
195 * @code{IOR}: IOR, Bitwise logical or
196 * @code{IPARITY}: IPARITY, Bitwise XOR of array elements
197 * @code{IRAND}: IRAND, Integer pseudo-random number
198 * @code{IS_CONTIGUOUS}: IS_CONTIGUOUS, Test whether an array is contiguous
199 * @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value
200 * @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value
201 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
202 * @code{ISHFT}: ISHFT, Shift bits
203 * @code{ISHFTC}: ISHFTC, Shift bits circularly
204 * @code{ISNAN}: ISNAN, Tests for a NaN
205 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
206 * @code{KILL}: KILL, Send a signal to a process
207 * @code{KIND}: KIND, Kind of an entity
208 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
209 * @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array
210 * @code{LEADZ}: LEADZ, Number of leading zero bits of an integer
211 * @code{LEN}: LEN, Length of a character entity
212 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
213 * @code{LGE}: LGE, Lexical greater than or equal
214 * @code{LGT}: LGT, Lexical greater than
215 * @code{LINK}: LINK, Create a hard link
216 * @code{LLE}: LLE, Lexical less than or equal
217 * @code{LLT}: LLT, Lexical less than
218 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
219 * @code{LOC}: LOC, Returns the address of a variable
220 * @code{LOG}: LOG, Logarithm function
221 * @code{LOG10}: LOG10, Base 10 logarithm function
222 * @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
223 * @code{LOGICAL}: LOGICAL, Convert to logical type
224 * @code{LONG}: LONG, Convert to integer type
225 * @code{LSHIFT}: LSHIFT, Left shift bits
226 * @code{LSTAT}: LSTAT, Get file status
227 * @code{LTIME}: LTIME, Convert time to local time info
228 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
229 * @code{MASKL}: MASKL, Left justified mask
230 * @code{MASKR}: MASKR, Right justified mask
231 * @code{MATMUL}: MATMUL, matrix multiplication
232 * @code{MAX}: MAX, Maximum value of an argument list
233 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
234 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
235 * @code{MAXVAL}: MAXVAL, Maximum value of an array
236 * @code{MCLOCK}: MCLOCK, Time function
237 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
238 * @code{MERGE}: MERGE, Merge arrays
239 * @code{MERGE_BITS}: MERGE_BITS, Merge of bits under mask
240 * @code{MIN}: MIN, Minimum value of an argument list
241 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
242 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
243 * @code{MINVAL}: MINVAL, Minimum value of an array
244 * @code{MOD}: MOD, Remainder function
245 * @code{MODULO}: MODULO, Modulo function
246 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
247 * @code{MVBITS}: MVBITS, Move bits from one integer to another
248 * @code{NEAREST}: NEAREST, Nearest representable number
249 * @code{NEW_LINE}: NEW_LINE, New line character
250 * @code{NINT}: NINT, Nearest whole number
251 * @code{NORM2}: NORM2, Euclidean vector norm
252 * @code{NOT}: NOT, Logical negation
253 * @code{NULL}: NULL, Function that returns an disassociated pointer
254 * @code{NUM_IMAGES}: NUM_IMAGES, Number of images
255 * @code{OR}: OR, Bitwise logical OR
256 * @code{PACK}: PACK, Pack an array into an array of rank one
257 * @code{PARITY}: PARITY, Reduction with exclusive OR
258 * @code{PERROR}: PERROR, Print system error message
259 * @code{POPCNT}: POPCNT, Number of bits set
260 * @code{POPPAR}: POPPAR, Parity of the number of bits set
261 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
262 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
263 * @code{PRODUCT}: PRODUCT, Product of array elements
264 * @code{RADIX}: RADIX, Base of a data model
265 * @code{RAN}: RAN, Real pseudo-random number
266 * @code{RAND}: RAND, Real pseudo-random number
267 * @code{RANDOM_INIT}: RANDOM_INIT, Initialize pseudo-random number generator
268 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
269 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
270 * @code{RANGE}: RANGE, Decimal exponent range
271 * @code{RANK} : RANK, Rank of a data object
272 * @code{REAL}: REAL, Convert to real type
273 * @code{RENAME}: RENAME, Rename a file
274 * @code{REPEAT}: REPEAT, Repeated string concatenation
275 * @code{RESHAPE}: RESHAPE, Function to reshape an array
276 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
277 * @code{RSHIFT}: RSHIFT, Right shift bits
278 * @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality
279 * @code{SCALE}: SCALE, Scale a real value
280 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
281 * @code{SECNDS}: SECNDS, Time function
282 * @code{SECOND}: SECOND, CPU time function
283 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind
284 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
285 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
286 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
287 * @code{SHAPE}: SHAPE, Determine the shape of an array
288 * @code{SHIFTA}: SHIFTA, Right shift with fill
289 * @code{SHIFTL}: SHIFTL, Left shift
290 * @code{SHIFTR}: SHIFTR, Right shift
291 * @code{SIGN}: SIGN, Sign copying function
292 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
293 * @code{SIN}: SIN, Sine function
294 * @code{SIND}: SIND, Sine function, degrees
295 * @code{SINH}: SINH, Hyperbolic sine function
296 * @code{SIZE}: SIZE, Function to determine the size of an array
297 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
298 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
299 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
300 * @code{SPREAD}: SPREAD, Add a dimension to an array
301 * @code{SQRT}: SQRT, Square-root function
302 * @code{SRAND}: SRAND, Reinitialize the random number generator
303 * @code{STAT}: STAT, Get file status
304 * @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits
305 * @code{SUM}: SUM, Sum of array elements
306 * @code{SYMLNK}: SYMLNK, Create a symbolic link
307 * @code{SYSTEM}: SYSTEM, Execute a shell command
308 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
309 * @code{TAN}: TAN, Tangent function
310 * @code{TAND}: TAND, Tangent function, degrees
311 * @code{TANH}: TANH, Hyperbolic tangent function
312 * @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image
313 * @code{TIME}: TIME, Time function
314 * @code{TIME8}: TIME8, Time function (64-bit)
315 * @code{TINY}: TINY, Smallest positive number of a real kind
316 * @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer
317 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
318 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
319 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
320 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
321 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
322 * @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array
323 * @code{UMASK}: UMASK, Set the file creation mask
324 * @code{UNLINK}: UNLINK, Remove a file from the file system
325 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
326 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
327 * @code{XOR}: XOR, Bitwise logical exclusive or
330 @node Introduction to Intrinsics
331 @section Introduction to intrinsic procedures
333 The intrinsic procedures provided by GNU Fortran include all of the
334 intrinsic procedures required by the Fortran 95 standard, a set of
335 intrinsic procedures for backwards compatibility with G77, and a
336 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
337 standards. Any conflict between a description here and a description in
338 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
339 2008 standard is unintentional, and the standard(s) should be considered
342 The enumeration of the @code{KIND} type parameter is processor defined in
343 the Fortran 95 standard. GNU Fortran defines the default integer type and
344 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
345 respectively. The standard mandates that both data types shall have
346 another kind, which have more precision. On typical target architectures
347 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
348 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
349 In the description of generic intrinsic procedures, the kind type parameter
350 will be specified by @code{KIND=*}, and in the description of specific
351 names for an intrinsic procedure the kind type parameter will be explicitly
352 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
353 brevity the optional @code{KIND=} syntax will be omitted.
355 Many of the intrinsic procedures take one or more optional arguments.
356 This document follows the convention used in the Fortran 95 standard,
357 and denotes such arguments by square brackets.
359 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
360 which can be used to restrict the set of intrinsic procedures to a
361 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
362 option, and so all intrinsic procedures described here are accepted. There
363 is one caveat. For a select group of intrinsic procedures, @command{g77}
364 implemented both a function and a subroutine. Both classes
365 have been implemented in @command{gfortran} for backwards compatibility
366 with @command{g77}. It is noted here that these functions and subroutines
367 cannot be intermixed in a given subprogram. In the descriptions that follow,
368 the applicable standard for each intrinsic procedure is noted.
373 @section @code{ABORT} --- Abort the program
375 @cindex program termination, with core dump
376 @cindex terminate program, with core dump
380 @item @emph{Description}:
381 @code{ABORT} causes immediate termination of the program. On operating
382 systems that support a core dump, @code{ABORT} will produce a core dump.
383 It will also print a backtrace, unless @code{-fno-backtrace} is given.
385 @item @emph{Standard}:
394 @item @emph{Return value}:
397 @item @emph{Example}:
400 integer :: i = 1, j = 2
401 if (i /= j) call abort
402 end program test_abort
405 @item @emph{See also}:
414 @section @code{ABS} --- Absolute value
425 @cindex absolute value
428 @item @emph{Description}:
429 @code{ABS(A)} computes the absolute value of @code{A}.
431 @item @emph{Standard}:
432 Fortran 77 and later, has overloads that are GNU extensions
438 @code{RESULT = ABS(A)}
440 @item @emph{Arguments}:
441 @multitable @columnfractions .15 .70
442 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
443 @code{REAL}, or @code{COMPLEX}.
446 @item @emph{Return value}:
447 The return value is of the same type and
448 kind as the argument except the return value is @code{REAL} for a
449 @code{COMPLEX} argument.
451 @item @emph{Example}:
456 complex :: z = (-1.e0,0.e0)
463 @item @emph{Specific names}:
464 @multitable @columnfractions .20 .20 .20 .25
465 @item Name @tab Argument @tab Return type @tab Standard
466 @item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
467 @item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
468 @item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
469 @item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
470 @item @code{BABS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
471 @item @code{IIABS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
472 @item @code{JIABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
473 @item @code{KIABS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
474 @item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{REAL(8)} @tab GNU extension
475 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{REAL(8)} @tab GNU extension
482 @section @code{ACCESS} --- Checks file access modes
484 @cindex file system, access mode
487 @item @emph{Description}:
488 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
489 exists, is readable, writable or executable. Except for the
490 executable check, @code{ACCESS} can be replaced by
491 Fortran 95's @code{INQUIRE}.
493 @item @emph{Standard}:
500 @code{RESULT = ACCESS(NAME, MODE)}
502 @item @emph{Arguments}:
503 @multitable @columnfractions .15 .70
504 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
505 file name. Tailing blank are ignored unless the character @code{achar(0)}
506 is present, then all characters up to and excluding @code{achar(0)} are
508 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
509 file access mode, may be any concatenation of @code{"r"} (readable),
510 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
514 @item @emph{Return value}:
515 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
516 accessible in the given mode; otherwise or if an invalid argument
517 has been given for @code{MODE} the value @code{1} is returned.
519 @item @emph{Example}:
523 character(len=*), parameter :: file = 'test.dat'
524 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
525 if(access(file,' ') == 0) print *, trim(file),' is exists'
526 if(access(file,'r') == 0) print *, trim(file),' is readable'
527 if(access(file,'w') == 0) print *, trim(file),' is writable'
528 if(access(file,'x') == 0) print *, trim(file),' is executable'
529 if(access(file2,'rwx') == 0) &
530 print *, trim(file2),' is readable, writable and executable'
531 end program access_test
538 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
540 @cindex @acronym{ASCII} collating sequence
541 @cindex collating sequence, @acronym{ASCII}
544 @item @emph{Description}:
545 @code{ACHAR(I)} returns the character located at position @code{I}
546 in the @acronym{ASCII} collating sequence.
548 @item @emph{Standard}:
549 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
555 @code{RESULT = ACHAR(I [, KIND])}
557 @item @emph{Arguments}:
558 @multitable @columnfractions .15 .70
559 @item @var{I} @tab The type shall be @code{INTEGER}.
560 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
561 expression indicating the kind parameter of the result.
564 @item @emph{Return value}:
565 The return value is of type @code{CHARACTER} with a length of one.
566 If the @var{KIND} argument is present, the return value is of the
567 specified kind and of the default kind otherwise.
569 @item @emph{Example}:
574 end program test_achar
578 See @ref{ICHAR} for a discussion of converting between numerical values
579 and formatted string representations.
581 @item @emph{See also}:
590 @section @code{ACOS} --- Arccosine function
593 @cindex trigonometric function, cosine, inverse
594 @cindex cosine, inverse
597 @item @emph{Description}:
598 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
600 @item @emph{Standard}:
601 Fortran 77 and later, for a complex argument Fortran 2008 or later
607 @code{RESULT = ACOS(X)}
609 @item @emph{Arguments}:
610 @multitable @columnfractions .15 .70
611 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
612 less than or equal to one - or the type shall be @code{COMPLEX}.
615 @item @emph{Return value}:
616 The return value is of the same type and kind as @var{X}.
617 The real part of the result is in radians and lies in the range
618 @math{0 \leq \Re \acos(x) \leq \pi}.
620 @item @emph{Example}:
623 real(8) :: x = 0.866_8
625 end program test_acos
628 @item @emph{Specific names}:
629 @multitable @columnfractions .20 .20 .20 .25
630 @item Name @tab Argument @tab Return type @tab Standard
631 @item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
632 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
635 @item @emph{See also}:
636 Inverse function: @gol
638 Degrees function: @gol
645 @section @code{ACOSD} --- Arccosine function, degrees
648 @cindex trigonometric function, cosine, inverse, degrees
649 @cindex cosine, inverse, degrees
652 @item @emph{Description}:
653 @code{ACOSD(X)} computes the arccosine of @var{X} in degrees (inverse of
656 This function is for compatibility only and should be avoided in favor of
657 standard constructs wherever possible.
659 @item @emph{Standard}:
660 GNU extension, enabled with @option{-fdec-math}
666 @code{RESULT = ACOSD(X)}
668 @item @emph{Arguments}:
669 @multitable @columnfractions .15 .70
670 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
671 less than or equal to one - or the type shall be @code{COMPLEX}.
674 @item @emph{Return value}:
675 The return value is of the same type and kind as @var{X}.
676 The real part of the result is in degrees and lies in the range
677 @math{0 \leq \Re \acos(x) \leq 180}.
679 @item @emph{Example}:
682 real(8) :: x = 0.866_8
684 end program test_acosd
687 @item @emph{Specific names}:
688 @multitable @columnfractions .20 .20 .20 .25
689 @item Name @tab Argument @tab Return type @tab Standard
690 @item @code{ACOSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
691 @item @code{DACOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
694 @item @emph{See also}:
695 Inverse function: @gol
697 Radians function: @gol
704 @section @code{ACOSH} --- Inverse hyperbolic cosine function
707 @cindex area hyperbolic cosine
708 @cindex inverse hyperbolic cosine
709 @cindex hyperbolic function, cosine, inverse
710 @cindex cosine, hyperbolic, inverse
713 @item @emph{Description}:
714 @code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
716 @item @emph{Standard}:
717 Fortran 2008 and later
723 @code{RESULT = ACOSH(X)}
725 @item @emph{Arguments}:
726 @multitable @columnfractions .15 .70
727 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
730 @item @emph{Return value}:
731 The return value has the same type and kind as @var{X}. If @var{X} is
732 complex, the imaginary part of the result is in radians and lies between
733 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
735 @item @emph{Example}:
738 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
743 @item @emph{Specific names}:
744 @multitable @columnfractions .20 .20 .20 .25
745 @item Name @tab Argument @tab Return type @tab Standard
746 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
749 @item @emph{See also}:
750 Inverse function: @gol
757 @section @code{ADJUSTL} --- Left adjust a string
759 @cindex string, adjust left
760 @cindex adjust string
763 @item @emph{Description}:
764 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
765 Spaces are inserted at the end of the string as needed.
767 @item @emph{Standard}:
774 @code{RESULT = ADJUSTL(STRING)}
776 @item @emph{Arguments}:
777 @multitable @columnfractions .15 .70
778 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
781 @item @emph{Return value}:
782 The return value is of type @code{CHARACTER} and of the same kind as
783 @var{STRING} where leading spaces are removed and the same number of
784 spaces are inserted on the end of @var{STRING}.
786 @item @emph{Example}:
789 character(len=20) :: str = ' gfortran'
792 end program test_adjustl
795 @item @emph{See also}:
803 @section @code{ADJUSTR} --- Right adjust a string
805 @cindex string, adjust right
806 @cindex adjust string
809 @item @emph{Description}:
810 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
811 Spaces are inserted at the start of the string as needed.
813 @item @emph{Standard}:
820 @code{RESULT = ADJUSTR(STRING)}
822 @item @emph{Arguments}:
823 @multitable @columnfractions .15 .70
824 @item @var{STR} @tab The type shall be @code{CHARACTER}.
827 @item @emph{Return value}:
828 The return value is of type @code{CHARACTER} and of the same kind as
829 @var{STRING} where trailing spaces are removed and the same number of
830 spaces are inserted at the start of @var{STRING}.
832 @item @emph{Example}:
835 character(len=20) :: str = 'gfortran'
838 end program test_adjustr
841 @item @emph{See also}:
849 @section @code{AIMAG} --- Imaginary part of complex number
854 @cindex complex numbers, imaginary part
857 @item @emph{Description}:
858 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
859 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
860 for compatibility with @command{g77}, and their use in new code is
861 strongly discouraged.
863 @item @emph{Standard}:
864 Fortran 77 and later, has overloads that are GNU extensions
870 @code{RESULT = AIMAG(Z)}
872 @item @emph{Arguments}:
873 @multitable @columnfractions .15 .70
874 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
877 @item @emph{Return value}:
878 The return value is of type @code{REAL} with the
879 kind type parameter of the argument.
881 @item @emph{Example}:
886 z4 = cmplx(1.e0_4, 0.e0_4)
887 z8 = cmplx(0.e0_8, 1.e0_8)
888 print *, aimag(z4), dimag(z8)
889 end program test_aimag
892 @item @emph{Specific names}:
893 @multitable @columnfractions .20 .20 .20 .25
894 @item Name @tab Argument @tab Return type @tab Standard
895 @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab Fortran 77 and later
896 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
897 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
898 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
905 @section @code{AINT} --- Truncate to a whole number
909 @cindex rounding, floor
912 @item @emph{Description}:
913 @code{AINT(A [, KIND])} truncates its argument to a whole number.
915 @item @emph{Standard}:
922 @code{RESULT = AINT(A [, KIND])}
924 @item @emph{Arguments}:
925 @multitable @columnfractions .15 .70
926 @item @var{A} @tab The type of the argument shall be @code{REAL}.
927 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
928 expression indicating the kind parameter of the result.
931 @item @emph{Return value}:
932 The return value is of type @code{REAL} with the kind type parameter of the
933 argument if the optional @var{KIND} is absent; otherwise, the kind
934 type parameter will be given by @var{KIND}. If the magnitude of
935 @var{X} is less than one, @code{AINT(X)} returns zero. If the
936 magnitude is equal to or greater than one then it returns the largest
937 whole number that does not exceed its magnitude. The sign is the same
938 as the sign of @var{X}.
940 @item @emph{Example}:
947 print *, aint(x4), dint(x8)
949 end program test_aint
952 @item @emph{Specific names}:
953 @multitable @columnfractions .20 .20 .20 .25
954 @item Name @tab Argument @tab Return type @tab Standard
955 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
956 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
963 @section @code{ALARM} --- Execute a routine after a given delay
965 @cindex delayed execution
968 @item @emph{Description}:
969 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
970 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
971 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
972 supplied, it will be returned with the number of seconds remaining until
973 any previously scheduled alarm was due to be delivered, or zero if there
974 was no previously scheduled alarm.
976 @item @emph{Standard}:
983 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
985 @item @emph{Arguments}:
986 @multitable @columnfractions .15 .70
987 @item @var{SECONDS} @tab The type of the argument shall be a scalar
988 @code{INTEGER}. It is @code{INTENT(IN)}.
989 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
990 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
991 values may be either @code{SIG_IGN=1} to ignore the alarm generated
992 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
993 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
994 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
997 @item @emph{Example}:
1000 external handler_print
1002 call alarm (3, handler_print, i)
1005 end program test_alarm
1007 This will cause the external routine @var{handler_print} to be called
1014 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
1016 @cindex array, apply condition
1017 @cindex array, condition testing
1020 @item @emph{Description}:
1021 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
1022 in the array along dimension @var{DIM}.
1024 @item @emph{Standard}:
1025 Fortran 90 and later
1028 Transformational function
1030 @item @emph{Syntax}:
1031 @code{RESULT = ALL(MASK [, DIM])}
1033 @item @emph{Arguments}:
1034 @multitable @columnfractions .15 .70
1035 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1036 it shall not be scalar.
1037 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1038 with a value that lies between one and the rank of @var{MASK}.
1041 @item @emph{Return value}:
1042 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
1043 the kind type parameter is the same as the kind type parameter of
1044 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
1045 an array with the rank of @var{MASK} minus 1. The shape is determined from
1046 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1050 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
1051 It also is true if @var{MASK} has zero size; otherwise, it is false.
1053 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
1054 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
1055 is determined by applying @code{ALL} to the array sections.
1058 @item @emph{Example}:
1062 l = all((/.true., .true., .true./))
1067 integer a(2,3), b(2,3)
1071 print *, all(a .eq. b, 1)
1072 print *, all(a .eq. b, 2)
1073 end subroutine section
1074 end program test_all
1081 @section @code{ALLOCATED} --- Status of an allocatable entity
1083 @cindex allocation, status
1086 @item @emph{Description}:
1087 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
1088 status of @var{ARRAY} and @var{SCALAR}, respectively.
1090 @item @emph{Standard}:
1091 Fortran 90 and later. Note, the @code{SCALAR=} keyword and allocatable
1092 scalar entities are available in Fortran 2003 and later.
1097 @item @emph{Syntax}:
1098 @multitable @columnfractions .80
1099 @item @code{RESULT = ALLOCATED(ARRAY)}
1100 @item @code{RESULT = ALLOCATED(SCALAR)}
1103 @item @emph{Arguments}:
1104 @multitable @columnfractions .15 .70
1105 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
1106 @item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar.
1109 @item @emph{Return value}:
1110 The return value is a scalar @code{LOGICAL} with the default logical
1111 kind type parameter. If the argument is allocated, then the result is
1112 @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
1114 @item @emph{Example}:
1116 program test_allocated
1118 real(4), allocatable :: x(:)
1119 if (.not. allocated(x)) allocate(x(i))
1120 end program test_allocated
1127 @section @code{AND} --- Bitwise logical AND
1129 @cindex bitwise logical and
1130 @cindex logical and, bitwise
1133 @item @emph{Description}:
1134 Bitwise logical @code{AND}.
1136 This intrinsic routine is provided for backwards compatibility with
1137 GNU Fortran 77. For integer arguments, programmers should consider
1138 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1140 @item @emph{Standard}:
1146 @item @emph{Syntax}:
1147 @code{RESULT = AND(I, J)}
1149 @item @emph{Arguments}:
1150 @multitable @columnfractions .15 .70
1151 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1152 type or a scalar @code{LOGICAL} type or a boz-literal-constant.
1153 @item @var{J} @tab The type shall be the same as the type of @var{I} or
1154 a boz-literal-constant. @var{I} and @var{J} shall not both be
1155 boz-literal-constants. If either @var{I} or @var{J} is a
1156 boz-literal-constant, then the other argument must be a scalar @code{INTEGER}.
1159 @item @emph{Return value}:
1160 The return type is either a scalar @code{INTEGER} or a scalar
1161 @code{LOGICAL}. If the kind type parameters differ, then the
1162 smaller kind type is implicitly converted to larger kind, and the
1163 return has the larger kind. A boz-literal-constant is
1164 converted to an @code{INTEGER} with the kind type parameter of
1165 the other argument as-if a call to @ref{INT} occurred.
1167 @item @emph{Example}:
1170 LOGICAL :: T = .TRUE., F = .FALSE.
1172 DATA a / Z'F' /, b / Z'3' /
1174 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1175 WRITE (*,*) AND(a, b)
1179 @item @emph{See also}:
1180 Fortran 95 elemental function: @gol
1187 @section @code{ANINT} --- Nearest whole number
1191 @cindex rounding, ceiling
1194 @item @emph{Description}:
1195 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1197 @item @emph{Standard}:
1198 Fortran 77 and later
1203 @item @emph{Syntax}:
1204 @code{RESULT = ANINT(A [, KIND])}
1206 @item @emph{Arguments}:
1207 @multitable @columnfractions .15 .70
1208 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1209 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1210 expression indicating the kind parameter of the result.
1213 @item @emph{Return value}:
1214 The return value is of type real with the kind type parameter of the
1215 argument if the optional @var{KIND} is absent; otherwise, the kind
1216 type parameter will be given by @var{KIND}. If @var{A} is greater than
1217 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1218 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1220 @item @emph{Example}:
1227 print *, anint(x4), dnint(x8)
1229 end program test_anint
1232 @item @emph{Specific names}:
1233 @multitable @columnfractions .20 .20 .20 .25
1234 @item Name @tab Argument @tab Return type @tab Standard
1235 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
1236 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1243 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1245 @cindex array, apply condition
1246 @cindex array, condition testing
1249 @item @emph{Description}:
1250 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1251 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1253 @item @emph{Standard}:
1254 Fortran 90 and later
1257 Transformational function
1259 @item @emph{Syntax}:
1260 @code{RESULT = ANY(MASK [, DIM])}
1262 @item @emph{Arguments}:
1263 @multitable @columnfractions .15 .70
1264 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1265 it shall not be scalar.
1266 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1267 with a value that lies between one and the rank of @var{MASK}.
1270 @item @emph{Return value}:
1271 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1272 the kind type parameter is the same as the kind type parameter of
1273 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1274 an array with the rank of @var{MASK} minus 1. The shape is determined from
1275 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1279 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1280 otherwise, it is false. It also is false if @var{MASK} has zero size.
1282 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1283 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1284 is determined by applying @code{ANY} to the array sections.
1287 @item @emph{Example}:
1291 l = any((/.true., .true., .true./))
1296 integer a(2,3), b(2,3)
1300 print *, any(a .eq. b, 1)
1301 print *, any(a .eq. b, 2)
1302 end subroutine section
1303 end program test_any
1310 @section @code{ASIN} --- Arcsine function
1313 @cindex trigonometric function, sine, inverse
1314 @cindex sine, inverse
1317 @item @emph{Description}:
1318 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1320 @item @emph{Standard}:
1321 Fortran 77 and later, for a complex argument Fortran 2008 or later
1326 @item @emph{Syntax}:
1327 @code{RESULT = ASIN(X)}
1329 @item @emph{Arguments}:
1330 @multitable @columnfractions .15 .70
1331 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1332 less than or equal to one - or be @code{COMPLEX}.
1335 @item @emph{Return value}:
1336 The return value is of the same type and kind as @var{X}.
1337 The real part of the result is in radians and lies in the range
1338 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1340 @item @emph{Example}:
1343 real(8) :: x = 0.866_8
1345 end program test_asin
1348 @item @emph{Specific names}:
1349 @multitable @columnfractions .20 .20 .20 .25
1350 @item Name @tab Argument @tab Return type @tab Standard
1351 @item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1352 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1355 @item @emph{See also}:
1356 Inverse function: @gol
1358 Degrees function: @gol
1365 @section @code{ASIND} --- Arcsine function, degrees
1368 @cindex trigonometric function, sine, inverse, degrees
1369 @cindex sine, inverse, degrees
1372 @item @emph{Description}:
1373 @code{ASIND(X)} computes the arcsine of its @var{X} in degrees (inverse of
1376 This function is for compatibility only and should be avoided in favor of
1377 standard constructs wherever possible.
1379 @item @emph{Standard}:
1380 GNU extension, enabled with @option{-fdec-math}.
1385 @item @emph{Syntax}:
1386 @code{RESULT = ASIND(X)}
1388 @item @emph{Arguments}:
1389 @multitable @columnfractions .15 .70
1390 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1391 less than or equal to one - or be @code{COMPLEX}.
1394 @item @emph{Return value}:
1395 The return value is of the same type and kind as @var{X}.
1396 The real part of the result is in degrees and lies in the range
1397 @math{-90 \leq \Re \asin(x) \leq 90}.
1399 @item @emph{Example}:
1402 real(8) :: x = 0.866_8
1404 end program test_asind
1407 @item @emph{Specific names}:
1408 @multitable @columnfractions .20 .20 .20 .25
1409 @item Name @tab Argument @tab Return type @tab Standard
1410 @item @code{ASIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
1411 @item @code{DASIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1414 @item @emph{See also}:
1415 Inverse function: @gol
1417 Radians function: @gol
1424 @section @code{ASINH} --- Inverse hyperbolic sine function
1427 @cindex area hyperbolic sine
1428 @cindex inverse hyperbolic sine
1429 @cindex hyperbolic function, sine, inverse
1430 @cindex sine, hyperbolic, inverse
1433 @item @emph{Description}:
1434 @code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
1436 @item @emph{Standard}:
1437 Fortran 2008 and later
1442 @item @emph{Syntax}:
1443 @code{RESULT = ASINH(X)}
1445 @item @emph{Arguments}:
1446 @multitable @columnfractions .15 .70
1447 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1450 @item @emph{Return value}:
1451 The return value is of the same type and kind as @var{X}. If @var{X} is
1452 complex, the imaginary part of the result is in radians and lies between
1453 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1455 @item @emph{Example}:
1458 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1459 WRITE (*,*) ASINH(x)
1463 @item @emph{Specific names}:
1464 @multitable @columnfractions .20 .20 .20 .25
1465 @item Name @tab Argument @tab Return type @tab Standard
1466 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1469 @item @emph{See also}:
1470 Inverse function: @gol
1477 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1479 @cindex pointer, status
1480 @cindex association status
1483 @item @emph{Description}:
1484 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1485 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1487 @item @emph{Standard}:
1488 Fortran 90 and later
1493 @item @emph{Syntax}:
1494 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1496 @item @emph{Arguments}:
1497 @multitable @columnfractions .15 .70
1498 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1499 and it can be of any type.
1500 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1501 a target. It must have the same type, kind type parameter, and
1502 array rank as @var{POINTER}.
1504 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1507 @item @emph{Return value}:
1508 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1509 There are several cases:
1511 @item (A) When the optional @var{TARGET} is not present then
1512 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1513 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1514 @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
1515 disassociated, the result is false.
1516 @item (C) If @var{TARGET} is present and an array target, the result is true if
1517 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1518 are arrays whose elements are not zero-sized storage sequences, and
1519 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1521 As in case(B), the result is false, if @var{POINTER} is disassociated.
1522 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1523 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1524 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1526 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1527 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1528 target associated with @var{POINTER} and the target associated with @var{TARGET}
1529 have the same shape, are not zero-sized arrays, are arrays whose elements are
1530 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1531 the same storage units in array element order.
1532 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1535 @item @emph{Example}:
1537 program test_associated
1539 real, target :: tgt(2) = (/1., 2./)
1540 real, pointer :: ptr(:)
1542 if (associated(ptr) .eqv. .false.) call abort
1543 if (associated(ptr,tgt) .eqv. .false.) call abort
1544 end program test_associated
1547 @item @emph{See also}:
1554 @section @code{ATAN} --- Arctangent function
1557 @cindex trigonometric function, tangent, inverse
1558 @cindex tangent, inverse
1561 @item @emph{Description}:
1562 @code{ATAN(X)} computes the arctangent of @var{X}.
1564 @item @emph{Standard}:
1565 Fortran 77 and later, for a complex argument and for two arguments
1566 Fortran 2008 or later
1571 @item @emph{Syntax}:
1572 @multitable @columnfractions .80
1573 @item @code{RESULT = ATAN(X)}
1574 @item @code{RESULT = ATAN(Y, X)}
1577 @item @emph{Arguments}:
1578 @multitable @columnfractions .15 .70
1579 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1580 if @var{Y} is present, @var{X} shall be REAL.
1581 @item @var{Y} @tab The type and kind type parameter shall be the same as @var{X}.
1584 @item @emph{Return value}:
1585 The return value is of the same type and kind as @var{X}.
1586 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1587 Otherwise, it the arcus tangent of @var{X}, where the real part of
1588 the result is in radians and lies in the range
1589 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1591 @item @emph{Example}:
1594 real(8) :: x = 2.866_8
1596 end program test_atan
1599 @item @emph{Specific names}:
1600 @multitable @columnfractions .20 .20 .20 .25
1601 @item Name @tab Argument @tab Return type @tab Standard
1602 @item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1603 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1606 @item @emph{See also}:
1607 Inverse function: @gol
1609 Degrees function: @gol
1616 @section @code{ATAND} --- Arctangent function, degrees
1619 @cindex trigonometric function, tangent, inverse, degrees
1620 @cindex tangent, inverse, degrees
1623 @item @emph{Description}:
1624 @code{ATAND(X)} computes the arctangent of @var{X} in degrees (inverse of
1627 This function is for compatibility only and should be avoided in favor of
1628 standard constructs wherever possible.
1630 @item @emph{Standard}:
1631 GNU extension, enabled with @option{-fdec-math}.
1636 @item @emph{Syntax}:
1637 @multitable @columnfractions .80
1638 @item @code{RESULT = ATAND(X)}
1639 @item @code{RESULT = ATAND(Y, X)}
1642 @item @emph{Arguments}:
1643 @multitable @columnfractions .15 .70
1644 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1645 if @var{Y} is present, @var{X} shall be REAL.
1646 @item @var{Y} @tab The type and kind type parameter shall be the same as @var{X}.
1649 @item @emph{Return value}:
1650 The return value is of the same type and kind as @var{X}.
1651 If @var{Y} is present, the result is identical to @code{ATAND2(Y,X)}.
1652 Otherwise, it is the arcus tangent of @var{X}, where the real part of
1653 the result is in degrees and lies in the range
1654 @math{-90 \leq \Re \atand(x) \leq 90}.
1656 @item @emph{Example}:
1659 real(8) :: x = 2.866_8
1661 end program test_atand
1664 @item @emph{Specific names}:
1665 @multitable @columnfractions .20 .20 .20 .25
1666 @item Name @tab Argument @tab Return type @tab Standard
1667 @item @code{ATAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
1668 @item @code{DATAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1671 @item @emph{See also}:
1672 Inverse function: @gol
1674 Radians function: @gol
1681 @section @code{ATAN2} --- Arctangent function
1684 @cindex trigonometric function, tangent, inverse
1685 @cindex tangent, inverse
1688 @item @emph{Description}:
1689 @code{ATAN2(Y, X)} computes the principal value of the argument
1690 function of the complex number @math{X + i Y}. This function can
1691 be used to transform from Cartesian into polar coordinates and
1692 allows to determine the angle in the correct quadrant.
1694 @item @emph{Standard}:
1695 Fortran 77 and later
1700 @item @emph{Syntax}:
1701 @code{RESULT = ATAN2(Y, X)}
1703 @item @emph{Arguments}:
1704 @multitable @columnfractions .15 .70
1705 @item @var{Y} @tab The type shall be @code{REAL}.
1706 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1707 If @var{Y} is zero, then @var{X} must be nonzero.
1710 @item @emph{Return value}:
1711 The return value has the same type and kind type parameter as @var{Y}. It
1712 is the principal value of the complex number @math{X + i Y}. If @var{X}
1713 is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1714 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1715 the return value is zero if @var{X} is strictly positive, @math{\pi} if
1716 @var{X} is negative and @var{Y} is positive zero (or the processor does
1717 not handle signed zeros), and @math{-\pi} if @var{X} is negative and
1718 @var{Y} is negative zero. Finally, if @var{X} is zero, then the
1719 magnitude of the result is @math{\pi/2}.
1721 @item @emph{Example}:
1724 real(4) :: x = 1.e0_4, y = 0.5e0_4
1726 end program test_atan2
1729 @item @emph{Specific names}:
1730 @multitable @columnfractions .20 .20 .20 .25
1731 @item Name @tab Argument @tab Return type @tab Standard
1732 @item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1733 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1736 @item @emph{See also}:
1739 Degrees function: @gol
1746 @section @code{ATAN2D} --- Arctangent function, degrees
1749 @cindex trigonometric function, tangent, inverse, degrees
1750 @cindex tangent, inverse, degrees
1753 @item @emph{Description}:
1754 @code{ATAN2D(Y, X)} computes the principal value of the argument
1755 function of the complex number @math{X + i Y} in degrees. This function can
1756 be used to transform from Cartesian into polar coordinates and
1757 allows to determine the angle in the correct quadrant.
1759 This function is for compatibility only and should be avoided in favor of
1760 standard constructs wherever possible.
1762 @item @emph{Standard}:
1763 GNU extension, enabled with @option{-fdec-math}.
1768 @item @emph{Syntax}:
1769 @code{RESULT = ATAN2D(Y, X)}
1771 @item @emph{Arguments}:
1772 @multitable @columnfractions .15 .70
1773 @item @var{Y} @tab The type shall be @code{REAL}.
1774 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1775 If @var{Y} is zero, then @var{X} must be nonzero.
1778 @item @emph{Return value}:
1779 The return value has the same type and kind type parameter as @var{Y}. It
1780 is the principal value of the complex number @math{X + i Y}. If @var{X}
1781 is nonzero, then it lies in the range @math{-180 \le \atan (x) \leq 180}.
1782 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1783 the return value is zero if @var{X} is strictly positive, @math{180} if
1784 @var{X} is negative and @var{Y} is positive zero (or the processor does
1785 not handle signed zeros), and @math{-180} if @var{X} is negative and
1786 @var{Y} is negative zero. Finally, if @var{X} is zero, then the
1787 magnitude of the result is @math{90}.
1789 @item @emph{Example}:
1792 real(4) :: x = 1.e0_4, y = 0.5e0_4
1794 end program test_atan2d
1797 @item @emph{Specific names}:
1798 @multitable @columnfractions .20 .20 .20 .25
1799 @item Name @tab Argument @tab Return type @tab Standard
1800 @item @code{ATAN2D(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab GNU extension
1801 @item @code{DATAN2D(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab GNU extension
1804 @item @emph{See also}:
1807 Radians function: @gol
1814 @section @code{ATANH} --- Inverse hyperbolic tangent function
1817 @cindex area hyperbolic tangent
1818 @cindex inverse hyperbolic tangent
1819 @cindex hyperbolic function, tangent, inverse
1820 @cindex tangent, hyperbolic, inverse
1823 @item @emph{Description}:
1824 @code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
1826 @item @emph{Standard}:
1827 Fortran 2008 and later
1832 @item @emph{Syntax}:
1833 @code{RESULT = ATANH(X)}
1835 @item @emph{Arguments}:
1836 @multitable @columnfractions .15 .70
1837 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1840 @item @emph{Return value}:
1841 The return value has same type and kind as @var{X}. If @var{X} is
1842 complex, the imaginary part of the result is in radians and lies between
1843 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1845 @item @emph{Example}:
1848 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1849 WRITE (*,*) ATANH(x)
1853 @item @emph{Specific names}:
1854 @multitable @columnfractions .20 .20 .20 .25
1855 @item Name @tab Argument @tab Return type @tab Standard
1856 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1859 @item @emph{See also}:
1860 Inverse function: @gol
1867 @section @code{ATOMIC_ADD} --- Atomic ADD operation
1869 @cindex Atomic subroutine, add
1872 @item @emph{Description}:
1873 @code{ATOMIC_ADD(ATOM, VALUE)} atomically adds the value of @var{VAR} to the
1874 variable @var{ATOM}. When @var{STAT} is present and the invocation was
1875 successful, it is assigned the value 0. If it is present and the invocation
1876 has failed, it is assigned a positive value; in particular, for a coindexed
1877 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1878 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1879 failed, the value @code{STAT_FAILED_IMAGE}.
1881 @item @emph{Standard}:
1887 @item @emph{Syntax}:
1888 @code{CALL ATOMIC_ADD (ATOM, VALUE [, STAT])}
1890 @item @emph{Arguments}:
1891 @multitable @columnfractions .15 .70
1892 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1893 type with @code{ATOMIC_INT_KIND} kind.
1894 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1895 is different, the value is converted to the kind of @var{ATOM}.
1896 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1899 @item @emph{Example}:
1903 integer(atomic_int_kind) :: atom[*]
1904 call atomic_add (atom[1], this_image())
1908 @item @emph{See also}:
1909 @ref{ATOMIC_DEFINE}, @gol
1910 @ref{ATOMIC_FETCH_ADD}, @gol
1911 @ref{ISO_FORTRAN_ENV}, @gol
1912 @ref{ATOMIC_AND}, @gol
1913 @ref{ATOMIC_OR}, @gol
1921 @section @code{ATOMIC_AND} --- Atomic bitwise AND operation
1923 @cindex Atomic subroutine, AND
1926 @item @emph{Description}:
1927 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
1928 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
1929 and the invocation was successful, it is assigned the value 0. If it is present
1930 and the invocation has failed, it is assigned a positive value; in particular,
1931 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
1932 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
1933 image has failed, the value @code{STAT_FAILED_IMAGE}.
1935 @item @emph{Standard}:
1941 @item @emph{Syntax}:
1942 @code{CALL ATOMIC_AND (ATOM, VALUE [, STAT])}
1944 @item @emph{Arguments}:
1945 @multitable @columnfractions .15 .70
1946 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1947 type with @code{ATOMIC_INT_KIND} kind.
1948 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1949 is different, the value is converted to the kind of @var{ATOM}.
1950 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1953 @item @emph{Example}:
1957 integer(atomic_int_kind) :: atom[*]
1958 call atomic_and (atom[1], int(b'10100011101'))
1962 @item @emph{See also}:
1963 @ref{ATOMIC_DEFINE}, @gol
1964 @ref{ATOMIC_FETCH_AND}, @gol
1965 @ref{ISO_FORTRAN_ENV}, @gol
1966 @ref{ATOMIC_ADD}, @gol
1967 @ref{ATOMIC_OR}, @gol
1974 @section @code{ATOMIC_CAS} --- Atomic compare and swap
1975 @fnindex ATOMIC_DEFINE
1976 @cindex Atomic subroutine, compare and swap
1979 @item @emph{Description}:
1980 @code{ATOMIC_CAS} compares the variable @var{ATOM} with the value of
1981 @var{COMPARE}; if the value is the same, @var{ATOM} is set to the value
1982 of @var{NEW}. Additionally, @var{OLD} is set to the value of @var{ATOM}
1983 that was used for the comparison. When @var{STAT} is present and the invocation
1984 was successful, it is assigned the value 0. If it is present and the invocation
1985 has failed, it is assigned a positive value; in particular, for a coindexed
1986 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1987 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1988 failed, the value @code{STAT_FAILED_IMAGE}.
1990 @item @emph{Standard}:
1996 @item @emph{Syntax}:
1997 @code{CALL ATOMIC_CAS (ATOM, OLD, COMPARE, NEW [, STAT])}
1999 @item @emph{Arguments}:
2000 @multitable @columnfractions .15 .70
2001 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
2002 type with @code{ATOMIC_INT_KIND} kind or logical type with
2003 @code{ATOMIC_LOGICAL_KIND} kind.
2004 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2005 @item @var{COMPARE} @tab Scalar variable of the same type and kind as
2007 @item @var{NEW} @tab Scalar variable of the same type as @var{ATOM}. If kind
2008 is different, the value is converted to the kind of @var{ATOM}.
2009 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2012 @item @emph{Example}:
2016 logical(atomic_logical_kind) :: atom[*], prev
2017 call atomic_cas (atom[1], prev, .false., .true.))
2021 @item @emph{See also}:
2022 @ref{ATOMIC_DEFINE}, @gol
2023 @ref{ATOMIC_REF}, @gol
2024 @ref{ISO_FORTRAN_ENV}
2030 @section @code{ATOMIC_DEFINE} --- Setting a variable atomically
2031 @fnindex ATOMIC_DEFINE
2032 @cindex Atomic subroutine, define
2035 @item @emph{Description}:
2036 @code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value
2037 @var{VALUE} atomically. When @var{STAT} is present and the invocation was
2038 successful, it is assigned the value 0. If it is present and the invocation
2039 has failed, it is assigned a positive value; in particular, for a coindexed
2040 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2041 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2042 failed, the value @code{STAT_FAILED_IMAGE}.
2044 @item @emph{Standard}:
2045 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
2050 @item @emph{Syntax}:
2051 @code{CALL ATOMIC_DEFINE (ATOM, VALUE [, STAT])}
2053 @item @emph{Arguments}:
2054 @multitable @columnfractions .15 .70
2055 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
2056 type with @code{ATOMIC_INT_KIND} kind or logical type with
2057 @code{ATOMIC_LOGICAL_KIND} kind.
2059 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2060 is different, the value is converted to the kind of @var{ATOM}.
2061 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2064 @item @emph{Example}:
2068 integer(atomic_int_kind) :: atom[*]
2069 call atomic_define (atom[1], this_image())
2073 @item @emph{See also}:
2074 @ref{ATOMIC_REF}, @gol
2075 @ref{ATOMIC_CAS}, @gol
2076 @ref{ISO_FORTRAN_ENV}, @gol
2077 @ref{ATOMIC_ADD}, @gol
2078 @ref{ATOMIC_AND}, @gol
2079 @ref{ATOMIC_OR}, @gol
2085 @node ATOMIC_FETCH_ADD
2086 @section @code{ATOMIC_FETCH_ADD} --- Atomic ADD operation with prior fetch
2087 @fnindex ATOMIC_FETCH_ADD
2088 @cindex Atomic subroutine, ADD with fetch
2091 @item @emph{Description}:
2092 @code{ATOMIC_FETCH_ADD(ATOM, VALUE, OLD)} atomically stores the value of
2093 @var{ATOM} in @var{OLD} and adds the value of @var{VAR} to the
2094 variable @var{ATOM}. When @var{STAT} is present and the invocation was
2095 successful, it is assigned the value 0. If it is present and the invocation
2096 has failed, it is assigned a positive value; in particular, for a coindexed
2097 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2098 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2099 failed, the value @code{STAT_FAILED_IMAGE}.
2101 @item @emph{Standard}:
2107 @item @emph{Syntax}:
2108 @code{CALL ATOMIC_FETCH_ADD (ATOM, VALUE, old [, STAT])}
2110 @item @emph{Arguments}:
2111 @multitable @columnfractions .15 .70
2112 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2113 type with @code{ATOMIC_INT_KIND} kind.
2114 @code{ATOMIC_LOGICAL_KIND} kind.
2116 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2117 is different, the value is converted to the kind of @var{ATOM}.
2118 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2119 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2122 @item @emph{Example}:
2126 integer(atomic_int_kind) :: atom[*], old
2127 call atomic_add (atom[1], this_image(), old)
2131 @item @emph{See also}:
2132 @ref{ATOMIC_DEFINE}, @gol
2133 @ref{ATOMIC_ADD}, @gol
2134 @ref{ISO_FORTRAN_ENV}, @gol
2135 @ref{ATOMIC_FETCH_AND}, @gol
2136 @ref{ATOMIC_FETCH_OR}, @gol
2137 @ref{ATOMIC_FETCH_XOR}
2142 @node ATOMIC_FETCH_AND
2143 @section @code{ATOMIC_FETCH_AND} --- Atomic bitwise AND operation with prior fetch
2144 @fnindex ATOMIC_FETCH_AND
2145 @cindex Atomic subroutine, AND with fetch
2148 @item @emph{Description}:
2149 @code{ATOMIC_AND(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2150 @var{OLD} and defines @var{ATOM} with the bitwise AND between the values of
2151 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
2152 successful, it is assigned the value 0. If it is present and the invocation has
2153 failed, it is assigned a positive value; in particular, for a coindexed
2154 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2155 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2156 failed, the value @code{STAT_FAILED_IMAGE}.
2158 @item @emph{Standard}:
2164 @item @emph{Syntax}:
2165 @code{CALL ATOMIC_FETCH_AND (ATOM, VALUE, OLD [, STAT])}
2167 @item @emph{Arguments}:
2168 @multitable @columnfractions .15 .70
2169 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2170 type with @code{ATOMIC_INT_KIND} kind.
2171 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2172 is different, the value is converted to the kind of @var{ATOM}.
2173 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2174 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2177 @item @emph{Example}:
2181 integer(atomic_int_kind) :: atom[*], old
2182 call atomic_fetch_and (atom[1], int(b'10100011101'), old)
2186 @item @emph{See also}:
2187 @ref{ATOMIC_DEFINE}, @gol
2188 @ref{ATOMIC_AND}, @gol
2189 @ref{ISO_FORTRAN_ENV}, @gol
2190 @ref{ATOMIC_FETCH_ADD}, @gol
2191 @ref{ATOMIC_FETCH_OR}, @gol
2192 @ref{ATOMIC_FETCH_XOR}
2197 @node ATOMIC_FETCH_OR
2198 @section @code{ATOMIC_FETCH_OR} --- Atomic bitwise OR operation with prior fetch
2199 @fnindex ATOMIC_FETCH_OR
2200 @cindex Atomic subroutine, OR with fetch
2203 @item @emph{Description}:
2204 @code{ATOMIC_OR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2205 @var{OLD} and defines @var{ATOM} with the bitwise OR between the values of
2206 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
2207 successful, it is assigned the value 0. If it is present and the invocation has
2208 failed, it is assigned a positive value; in particular, for a coindexed
2209 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2210 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2211 failed, the value @code{STAT_FAILED_IMAGE}.
2213 @item @emph{Standard}:
2219 @item @emph{Syntax}:
2220 @code{CALL ATOMIC_FETCH_OR (ATOM, VALUE, OLD [, STAT])}
2222 @item @emph{Arguments}:
2223 @multitable @columnfractions .15 .70
2224 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2225 type with @code{ATOMIC_INT_KIND} kind.
2226 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2227 is different, the value is converted to the kind of @var{ATOM}.
2228 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2229 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2232 @item @emph{Example}:
2236 integer(atomic_int_kind) :: atom[*], old
2237 call atomic_fetch_or (atom[1], int(b'10100011101'), old)
2241 @item @emph{See also}:
2242 @ref{ATOMIC_DEFINE}, @gol
2243 @ref{ATOMIC_OR}, @gol
2244 @ref{ISO_FORTRAN_ENV}, @gol
2245 @ref{ATOMIC_FETCH_ADD}, @gol
2246 @ref{ATOMIC_FETCH_AND}, @gol
2247 @ref{ATOMIC_FETCH_XOR}
2252 @node ATOMIC_FETCH_XOR
2253 @section @code{ATOMIC_FETCH_XOR} --- Atomic bitwise XOR operation with prior fetch
2254 @fnindex ATOMIC_FETCH_XOR
2255 @cindex Atomic subroutine, XOR with fetch
2258 @item @emph{Description}:
2259 @code{ATOMIC_XOR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2260 @var{OLD} and defines @var{ATOM} with the bitwise XOR between the values of
2261 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
2262 successful, it is assigned the value 0. If it is present and the invocation has
2263 failed, it is assigned a positive value; in particular, for a coindexed
2264 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2265 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2266 failed, the value @code{STAT_FAILED_IMAGE}.
2268 @item @emph{Standard}:
2274 @item @emph{Syntax}:
2275 @code{CALL ATOMIC_FETCH_XOR (ATOM, VALUE, OLD [, STAT])}
2277 @item @emph{Arguments}:
2278 @multitable @columnfractions .15 .70
2279 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2280 type with @code{ATOMIC_INT_KIND} kind.
2281 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2282 is different, the value is converted to the kind of @var{ATOM}.
2283 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2284 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2287 @item @emph{Example}:
2291 integer(atomic_int_kind) :: atom[*], old
2292 call atomic_fetch_xor (atom[1], int(b'10100011101'), old)
2296 @item @emph{See also}:
2297 @ref{ATOMIC_DEFINE}, @gol
2298 @ref{ATOMIC_XOR}, @gol
2299 @ref{ISO_FORTRAN_ENV}, @gol
2300 @ref{ATOMIC_FETCH_ADD}, @gol
2301 @ref{ATOMIC_FETCH_AND}, @gol
2302 @ref{ATOMIC_FETCH_OR}
2308 @section @code{ATOMIC_OR} --- Atomic bitwise OR operation
2310 @cindex Atomic subroutine, OR
2313 @item @emph{Description}:
2314 @code{ATOMIC_OR(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
2315 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
2316 and the invocation was successful, it is assigned the value 0. If it is present
2317 and the invocation has failed, it is assigned a positive value; in particular,
2318 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
2319 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
2320 image has failed, the value @code{STAT_FAILED_IMAGE}.
2322 @item @emph{Standard}:
2328 @item @emph{Syntax}:
2329 @code{CALL ATOMIC_OR (ATOM, VALUE [, STAT])}
2331 @item @emph{Arguments}:
2332 @multitable @columnfractions .15 .70
2333 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2334 type with @code{ATOMIC_INT_KIND} kind.
2335 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2336 is different, the value is converted to the kind of @var{ATOM}.
2337 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2340 @item @emph{Example}:
2344 integer(atomic_int_kind) :: atom[*]
2345 call atomic_or (atom[1], int(b'10100011101'))
2349 @item @emph{See also}:
2350 @ref{ATOMIC_DEFINE}, @gol
2351 @ref{ATOMIC_FETCH_OR}, @gol
2352 @ref{ISO_FORTRAN_ENV}, @gol
2353 @ref{ATOMIC_ADD}, @gol
2354 @ref{ATOMIC_OR}, @gol
2361 @section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically
2363 @cindex Atomic subroutine, reference
2366 @item @emph{Description}:
2367 @code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the
2368 variable @var{ATOM} to @var{VALUE}. When @var{STAT} is present and the
2369 invocation was successful, it is assigned the value 0. If it is present and the
2370 invocation has failed, it is assigned a positive value; in particular, for a
2371 coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value
2372 of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image
2373 has failed, the value @code{STAT_FAILED_IMAGE}.
2376 @item @emph{Standard}:
2377 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
2382 @item @emph{Syntax}:
2383 @code{CALL ATOMIC_REF(VALUE, ATOM [, STAT])}
2385 @item @emph{Arguments}:
2386 @multitable @columnfractions .15 .70
2387 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2388 is different, the value is converted to the kind of @var{ATOM}.
2389 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
2390 type with @code{ATOMIC_INT_KIND} kind or logical type with
2391 @code{ATOMIC_LOGICAL_KIND} kind.
2392 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2395 @item @emph{Example}:
2399 logical(atomic_logical_kind) :: atom[*]
2401 call atomic_ref (atom, .false.)
2403 call atomic_ref (atom, val)
2410 @item @emph{See also}:
2411 @ref{ATOMIC_DEFINE}, @gol
2412 @ref{ATOMIC_CAS}, @gol
2413 @ref{ISO_FORTRAN_ENV}, @gol
2414 @ref{ATOMIC_FETCH_ADD}, @gol
2415 @ref{ATOMIC_FETCH_AND}, @gol
2416 @ref{ATOMIC_FETCH_OR}, @gol
2417 @ref{ATOMIC_FETCH_XOR}
2422 @section @code{ATOMIC_XOR} --- Atomic bitwise OR operation
2424 @cindex Atomic subroutine, XOR
2427 @item @emph{Description}:
2428 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
2429 XOR between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
2430 and the invocation was successful, it is assigned the value 0. If it is present
2431 and the invocation has failed, it is assigned a positive value; in particular,
2432 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
2433 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
2434 image has failed, the value @code{STAT_FAILED_IMAGE}.
2436 @item @emph{Standard}:
2442 @item @emph{Syntax}:
2443 @code{CALL ATOMIC_XOR (ATOM, VALUE [, STAT])}
2445 @item @emph{Arguments}:
2446 @multitable @columnfractions .15 .70
2447 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2448 type with @code{ATOMIC_INT_KIND} kind.
2449 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2450 is different, the value is converted to the kind of @var{ATOM}.
2451 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2454 @item @emph{Example}:
2458 integer(atomic_int_kind) :: atom[*]
2459 call atomic_xor (atom[1], int(b'10100011101'))
2463 @item @emph{See also}:
2464 @ref{ATOMIC_DEFINE}, @gol
2465 @ref{ATOMIC_FETCH_XOR}, @gol
2466 @ref{ISO_FORTRAN_ENV}, @gol
2467 @ref{ATOMIC_ADD}, @gol
2468 @ref{ATOMIC_OR}, @gol
2474 @section @code{BACKTRACE} --- Show a backtrace
2479 @item @emph{Description}:
2480 @code{BACKTRACE} shows a backtrace at an arbitrary place in user code. Program
2481 execution continues normally afterwards. The backtrace information is printed
2482 to the unit corresponding to @code{ERROR_UNIT} in @code{ISO_FORTRAN_ENV}.
2484 @item @emph{Standard}:
2490 @item @emph{Syntax}:
2491 @code{CALL BACKTRACE}
2493 @item @emph{Arguments}:
2496 @item @emph{See also}:
2503 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
2507 @cindex Bessel function, first kind
2510 @item @emph{Description}:
2511 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
2512 order 0 of @var{X}. This function is available under the name
2513 @code{BESJ0} as a GNU extension.
2515 @item @emph{Standard}:
2516 Fortran 2008 and later
2521 @item @emph{Syntax}:
2522 @code{RESULT = BESSEL_J0(X)}
2524 @item @emph{Arguments}:
2525 @multitable @columnfractions .15 .70
2526 @item @var{X} @tab The type shall be @code{REAL}.
2529 @item @emph{Return value}:
2530 The return value is of type @code{REAL} and lies in the
2531 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
2534 @item @emph{Example}:
2537 real(8) :: x = 0.0_8
2539 end program test_besj0
2542 @item @emph{Specific names}:
2543 @multitable @columnfractions .20 .20 .20 .25
2544 @item Name @tab Argument @tab Return type @tab Standard
2545 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2552 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
2556 @cindex Bessel function, first kind
2559 @item @emph{Description}:
2560 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
2561 order 1 of @var{X}. This function is available under the name
2562 @code{BESJ1} as a GNU extension.
2564 @item @emph{Standard}:
2570 @item @emph{Syntax}:
2571 @code{RESULT = BESSEL_J1(X)}
2573 @item @emph{Arguments}:
2574 @multitable @columnfractions .15 .70
2575 @item @var{X} @tab The type shall be @code{REAL}.
2578 @item @emph{Return value}:
2579 The return value is of type @code{REAL} and lies in the
2580 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
2583 @item @emph{Example}:
2586 real(8) :: x = 1.0_8
2588 end program test_besj1
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{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2601 @section @code{BESSEL_JN} --- Bessel function of the first kind
2605 @cindex Bessel function, first kind
2608 @item @emph{Description}:
2609 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
2610 order @var{N} of @var{X}. This function is available under the name
2611 @code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays,
2612 their ranks and shapes shall conform.
2614 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
2615 of the first kind of the orders @var{N1} to @var{N2}.
2617 @item @emph{Standard}:
2618 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2621 Elemental function, except for the transformational function
2622 @code{BESSEL_JN(N1, N2, X)}
2624 @item @emph{Syntax}:
2625 @multitable @columnfractions .80
2626 @item @code{RESULT = BESSEL_JN(N, X)}
2627 @item @code{RESULT = BESSEL_JN(N1, N2, X)}
2630 @item @emph{Arguments}:
2631 @multitable @columnfractions .15 .70
2632 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
2633 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2634 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2635 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2636 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
2639 @item @emph{Return value}:
2640 The return value is a scalar of type @code{REAL}. It has the same
2644 The transformational function uses a recurrence algorithm which might,
2645 for some values of @var{X}, lead to different results than calls to
2646 the elemental function.
2648 @item @emph{Example}:
2651 real(8) :: x = 1.0_8
2653 end program test_besjn
2656 @item @emph{Specific names}:
2657 @multitable @columnfractions .20 .20 .20 .25
2658 @item Name @tab Argument @tab Return type @tab Standard
2659 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2660 @item @tab @code{REAL(8) X} @tab @tab
2667 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
2671 @cindex Bessel function, second kind
2674 @item @emph{Description}:
2675 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
2676 order 0 of @var{X}. This function is available under the name
2677 @code{BESY0} as a GNU extension.
2679 @item @emph{Standard}:
2680 Fortran 2008 and later
2685 @item @emph{Syntax}:
2686 @code{RESULT = BESSEL_Y0(X)}
2688 @item @emph{Arguments}:
2689 @multitable @columnfractions .15 .70
2690 @item @var{X} @tab The type shall be @code{REAL}.
2693 @item @emph{Return value}:
2694 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2696 @item @emph{Example}:
2699 real(8) :: x = 0.0_8
2701 end program test_besy0
2704 @item @emph{Specific names}:
2705 @multitable @columnfractions .20 .20 .20 .25
2706 @item Name @tab Argument @tab Return type @tab Standard
2707 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2714 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
2718 @cindex Bessel function, second kind
2721 @item @emph{Description}:
2722 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
2723 order 1 of @var{X}. This function is available under the name
2724 @code{BESY1} as a GNU extension.
2726 @item @emph{Standard}:
2727 Fortran 2008 and later
2732 @item @emph{Syntax}:
2733 @code{RESULT = BESSEL_Y1(X)}
2735 @item @emph{Arguments}:
2736 @multitable @columnfractions .15 .70
2737 @item @var{X} @tab The type shall be @code{REAL}.
2740 @item @emph{Return value}:
2741 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2743 @item @emph{Example}:
2746 real(8) :: x = 1.0_8
2748 end program test_besy1
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{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2761 @section @code{BESSEL_YN} --- Bessel function of the second kind
2765 @cindex Bessel function, second kind
2768 @item @emph{Description}:
2769 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
2770 order @var{N} of @var{X}. This function is available under the name
2771 @code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays,
2772 their ranks and shapes shall conform.
2774 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
2775 of the first kind of the orders @var{N1} to @var{N2}.
2777 @item @emph{Standard}:
2778 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2781 Elemental function, except for the transformational function
2782 @code{BESSEL_YN(N1, N2, X)}
2784 @item @emph{Syntax}:
2785 @multitable @columnfractions .80
2786 @item @code{RESULT = BESSEL_YN(N, X)}
2787 @item @code{RESULT = BESSEL_YN(N1, N2, X)}
2790 @item @emph{Arguments}:
2791 @multitable @columnfractions .15 .70
2792 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} .
2793 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2794 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2795 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2796 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
2799 @item @emph{Return value}:
2800 The return value is a scalar of type @code{REAL}. It has the same
2804 The transformational function uses a recurrence algorithm which might,
2805 for some values of @var{X}, lead to different results than calls to
2806 the elemental function.
2808 @item @emph{Example}:
2811 real(8) :: x = 1.0_8
2813 end program test_besyn
2816 @item @emph{Specific names}:
2817 @multitable @columnfractions .20 .20 .20 .25
2818 @item Name @tab Argument @tab Return type @tab Standard
2819 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2820 @item @tab @code{REAL(8) X} @tab @tab
2827 @section @code{BGE} --- Bitwise greater than or equal to
2829 @cindex bitwise comparison
2832 @item @emph{Description}:
2833 Determines whether an integral is a bitwise greater than or equal to
2836 @item @emph{Standard}:
2837 Fortran 2008 and later
2842 @item @emph{Syntax}:
2843 @code{RESULT = BGE(I, J)}
2845 @item @emph{Arguments}:
2846 @multitable @columnfractions .15 .70
2847 @item @var{I} @tab Shall be of @code{INTEGER} type.
2848 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2852 @item @emph{Return value}:
2853 The return value is of type @code{LOGICAL} and of the default kind.
2855 @item @emph{See also}:
2864 @section @code{BGT} --- Bitwise greater than
2866 @cindex bitwise comparison
2869 @item @emph{Description}:
2870 Determines whether an integral is a bitwise greater than another.
2872 @item @emph{Standard}:
2873 Fortran 2008 and later
2878 @item @emph{Syntax}:
2879 @code{RESULT = BGT(I, J)}
2881 @item @emph{Arguments}:
2882 @multitable @columnfractions .15 .70
2883 @item @var{I} @tab Shall be of @code{INTEGER} type.
2884 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2888 @item @emph{Return value}:
2889 The return value is of type @code{LOGICAL} and of the default kind.
2891 @item @emph{See also}:
2900 @section @code{BIT_SIZE} --- Bit size inquiry function
2902 @cindex bits, number of
2903 @cindex size of a variable, in bits
2906 @item @emph{Description}:
2907 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
2908 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
2909 independent of the actual value of @var{I}.
2911 @item @emph{Standard}:
2912 Fortran 90 and later
2917 @item @emph{Syntax}:
2918 @code{RESULT = BIT_SIZE(I)}
2920 @item @emph{Arguments}:
2921 @multitable @columnfractions .15 .70
2922 @item @var{I} @tab The type shall be @code{INTEGER}.
2925 @item @emph{Return value}:
2926 The return value is of type @code{INTEGER}
2928 @item @emph{Example}:
2930 program test_bit_size
2935 end program test_bit_size
2942 @section @code{BLE} --- Bitwise less than or equal to
2944 @cindex bitwise comparison
2947 @item @emph{Description}:
2948 Determines whether an integral is a bitwise less than or equal to
2951 @item @emph{Standard}:
2952 Fortran 2008 and later
2957 @item @emph{Syntax}:
2958 @code{RESULT = BLE(I, J)}
2960 @item @emph{Arguments}:
2961 @multitable @columnfractions .15 .70
2962 @item @var{I} @tab Shall be of @code{INTEGER} type.
2963 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2967 @item @emph{Return value}:
2968 The return value is of type @code{LOGICAL} and of the default kind.
2970 @item @emph{See also}:
2979 @section @code{BLT} --- Bitwise less than
2981 @cindex bitwise comparison
2984 @item @emph{Description}:
2985 Determines whether an integral is a bitwise less than another.
2987 @item @emph{Standard}:
2988 Fortran 2008 and later
2993 @item @emph{Syntax}:
2994 @code{RESULT = BLT(I, J)}
2996 @item @emph{Arguments}:
2997 @multitable @columnfractions .15 .70
2998 @item @var{I} @tab Shall be of @code{INTEGER} type.
2999 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
3003 @item @emph{Return value}:
3004 The return value is of type @code{LOGICAL} and of the default kind.
3006 @item @emph{See also}:
3015 @section @code{BTEST} --- Bit test function
3021 @cindex bits, testing
3024 @item @emph{Description}:
3025 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
3026 in @var{I} is set. The counting of the bits starts at 0.
3028 @item @emph{Standard}:
3029 Fortran 90 and later, has overloads that are GNU extensions
3034 @item @emph{Syntax}:
3035 @code{RESULT = BTEST(I, POS)}
3037 @item @emph{Arguments}:
3038 @multitable @columnfractions .15 .70
3039 @item @var{I} @tab The type shall be @code{INTEGER}.
3040 @item @var{POS} @tab The type shall be @code{INTEGER}.
3043 @item @emph{Return value}:
3044 The return value is of type @code{LOGICAL}
3046 @item @emph{Example}:
3049 integer :: i = 32768 + 1024 + 64
3053 bool = btest(i, pos)
3056 end program test_btest
3059 @item @emph{Specific names}:
3060 @multitable @columnfractions .20 .20 .20 .25
3061 @item Name @tab Argument @tab Return type @tab Standard
3062 @item @code{BTEST(I,POS)} @tab @code{INTEGER I,POS} @tab @code{LOGICAL} @tab Fortran 95 and later
3063 @item @code{BBTEST(I,POS)} @tab @code{INTEGER(1) I,POS} @tab @code{LOGICAL(1)} @tab GNU extension
3064 @item @code{BITEST(I,POS)} @tab @code{INTEGER(2) I,POS} @tab @code{LOGICAL(2)} @tab GNU extension
3065 @item @code{BJTEST(I,POS)} @tab @code{INTEGER(4) I,POS} @tab @code{LOGICAL(4)} @tab GNU extension
3066 @item @code{BKTEST(I,POS)} @tab @code{INTEGER(8) I,POS} @tab @code{LOGICAL(8)} @tab GNU extension
3071 @section @code{C_ASSOCIATED} --- Status of a C pointer
3072 @fnindex C_ASSOCIATED
3073 @cindex association status, C pointer
3074 @cindex pointer, C association status
3077 @item @emph{Description}:
3078 @code{C_ASSOCIATED(c_ptr_1[, c_ptr_2])} determines the status of the C pointer
3079 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
3081 @item @emph{Standard}:
3082 Fortran 2003 and later
3087 @item @emph{Syntax}:
3088 @code{RESULT = C_ASSOCIATED(c_ptr_1[, c_ptr_2])}
3090 @item @emph{Arguments}:
3091 @multitable @columnfractions .15 .70
3092 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
3093 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
3096 @item @emph{Return value}:
3097 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
3098 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
3099 point to different addresses.
3101 @item @emph{Example}:
3103 subroutine association_test(a,b)
3104 use iso_c_binding, only: c_associated, c_loc, c_ptr
3108 if(c_associated(b, c_loc(a))) &
3109 stop 'b and a do not point to same target'
3110 end subroutine association_test
3113 @item @emph{See also}:
3120 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
3121 @fnindex C_F_POINTER
3122 @cindex pointer, convert C to Fortran
3125 @item @emph{Description}:
3126 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} assigns the target of the C pointer
3127 @var{CPTR} to the Fortran pointer @var{FPTR} and specifies its shape.
3129 @item @emph{Standard}:
3130 Fortran 2003 and later
3135 @item @emph{Syntax}:
3136 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
3138 @item @emph{Arguments}:
3139 @multitable @columnfractions .15 .70
3140 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
3142 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
3144 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
3145 with @code{INTENT(IN)}. It shall be present
3146 if and only if @var{fptr} is an array. The size
3147 must be equal to the rank of @var{fptr}.
3150 @item @emph{Example}:
3156 subroutine my_routine(p) bind(c,name='myC_func')
3158 type(c_ptr), intent(out) :: p
3162 real,pointer :: a(:)
3163 call my_routine(cptr)
3164 call c_f_pointer(cptr, a, [12])
3168 @item @emph{See also}:
3170 @ref{C_F_PROCPOINTER}
3174 @node C_F_PROCPOINTER
3175 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
3176 @fnindex C_F_PROCPOINTER
3177 @cindex pointer, C address of pointers
3180 @item @emph{Description}:
3181 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
3182 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
3184 @item @emph{Standard}:
3185 Fortran 2003 and later
3190 @item @emph{Syntax}:
3191 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
3193 @item @emph{Arguments}:
3194 @multitable @columnfractions .15 .70
3195 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
3197 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
3201 @item @emph{Example}:
3209 real(c_float), intent(in) :: a
3210 real(c_float) :: func
3214 function getIterFunc() bind(c,name="getIterFunc")
3216 type(c_funptr) :: getIterFunc
3219 type(c_funptr) :: cfunptr
3220 procedure(func), pointer :: myFunc
3221 cfunptr = getIterFunc()
3222 call c_f_procpointer(cfunptr, myFunc)
3226 @item @emph{See also}:
3233 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
3235 @cindex pointer, C address of procedures
3238 @item @emph{Description}:
3239 @code{C_FUNLOC(x)} determines the C address of the argument.
3241 @item @emph{Standard}:
3242 Fortran 2003 and later
3247 @item @emph{Syntax}:
3248 @code{RESULT = C_FUNLOC(x)}
3250 @item @emph{Arguments}:
3251 @multitable @columnfractions .15 .70
3252 @item @var{x} @tab Interoperable function or pointer to such function.
3255 @item @emph{Return value}:
3256 The return value is of type @code{C_FUNPTR} and contains the C address
3259 @item @emph{Example}:
3265 subroutine sub(a) bind(c)
3275 subroutine my_routine(p) bind(c,name='myC_func')
3277 type(c_funptr), intent(in) :: p
3280 call my_routine(c_funloc(sub))
3284 @item @emph{See also}:
3285 @ref{C_ASSOCIATED}, @gol
3287 @ref{C_F_POINTER}, @gol
3288 @ref{C_F_PROCPOINTER}
3293 @section @code{C_LOC} --- Obtain the C address of an object
3295 @cindex procedure pointer, convert C to Fortran
3298 @item @emph{Description}:
3299 @code{C_LOC(X)} determines the C address of the argument.
3301 @item @emph{Standard}:
3302 Fortran 2003 and later
3307 @item @emph{Syntax}:
3308 @code{RESULT = C_LOC(X)}
3310 @item @emph{Arguments}:
3311 @multitable @columnfractions .10 .75
3312 @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.
3316 @item @emph{Return value}:
3317 The return value is of type @code{C_PTR} and contains the C address
3320 @item @emph{Example}:
3322 subroutine association_test(a,b)
3323 use iso_c_binding, only: c_associated, c_loc, c_ptr
3327 if(c_associated(b, c_loc(a))) &
3328 stop 'b and a do not point to same target'
3329 end subroutine association_test
3332 @item @emph{See also}:
3333 @ref{C_ASSOCIATED}, @gol
3334 @ref{C_FUNLOC}, @gol
3335 @ref{C_F_POINTER}, @gol
3336 @ref{C_F_PROCPOINTER}
3341 @section @code{C_SIZEOF} --- Size in bytes of an expression
3343 @cindex expression size
3344 @cindex size of an expression
3347 @item @emph{Description}:
3348 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
3349 expression @code{X} occupies.
3351 @item @emph{Standard}:
3355 Inquiry function of the module @code{ISO_C_BINDING}
3357 @item @emph{Syntax}:
3358 @code{N = C_SIZEOF(X)}
3360 @item @emph{Arguments}:
3361 @multitable @columnfractions .15 .70
3362 @item @var{X} @tab The argument shall be an interoperable data entity.
3365 @item @emph{Return value}:
3366 The return value is of type integer and of the system-dependent kind
3367 @code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the
3368 number of bytes occupied by the argument. If the argument has the
3369 @code{POINTER} attribute, the number of bytes of the storage area pointed
3370 to is returned. If the argument is of a derived type with @code{POINTER}
3371 or @code{ALLOCATABLE} components, the return value does not account for
3372 the sizes of the data pointed to by these components.
3374 @item @emph{Example}:
3378 real(c_float) :: r, s(5)
3379 print *, (c_sizeof(s)/c_sizeof(r) == 5)
3382 The example will print @code{T} unless you are using a platform
3383 where default @code{REAL} variables are unusually padded.
3385 @item @emph{See also}:
3392 @section @code{CEILING} --- Integer ceiling function
3395 @cindex rounding, ceiling
3398 @item @emph{Description}:
3399 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
3401 @item @emph{Standard}:
3402 Fortran 95 and later
3407 @item @emph{Syntax}:
3408 @code{RESULT = CEILING(A [, KIND])}
3410 @item @emph{Arguments}:
3411 @multitable @columnfractions .15 .70
3412 @item @var{A} @tab The type shall be @code{REAL}.
3413 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3414 expression indicating the kind parameter of the result.
3417 @item @emph{Return value}:
3418 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
3419 and a default-kind @code{INTEGER} otherwise.
3421 @item @emph{Example}:
3423 program test_ceiling
3426 print *, ceiling(x) ! returns 64
3427 print *, ceiling(y) ! returns -63
3428 end program test_ceiling
3431 @item @emph{See also}:
3439 @section @code{CHAR} --- Character conversion function
3441 @cindex conversion, to character
3444 @item @emph{Description}:
3445 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
3447 @item @emph{Standard}:
3448 Fortran 77 and later
3453 @item @emph{Syntax}:
3454 @code{RESULT = CHAR(I [, KIND])}
3456 @item @emph{Arguments}:
3457 @multitable @columnfractions .15 .70
3458 @item @var{I} @tab The type shall be @code{INTEGER}.
3459 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3460 expression indicating the kind parameter of the result.
3463 @item @emph{Return value}:
3464 The return value is of type @code{CHARACTER(1)}
3466 @item @emph{Example}:
3472 print *, i, c ! returns 'J'
3473 end program test_char
3476 @item @emph{Specific names}:
3477 @multitable @columnfractions .18 .18 .24 .25
3478 @item Name @tab Argument @tab Return type @tab Standard
3479 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab Fortran 77 and later
3483 See @ref{ICHAR} for a discussion of converting between numerical values
3484 and formatted string representations.
3486 @item @emph{See also}:
3496 @section @code{CHDIR} --- Change working directory
3498 @cindex system, working directory
3501 @item @emph{Description}:
3502 Change current working directory to a specified path.
3504 This intrinsic is provided in both subroutine and function forms; however,
3505 only one form can be used in any given program unit.
3507 @item @emph{Standard}:
3511 Subroutine, function
3513 @item @emph{Syntax}:
3514 @multitable @columnfractions .80
3515 @item @code{CALL CHDIR(NAME [, STATUS])}
3516 @item @code{STATUS = CHDIR(NAME)}
3519 @item @emph{Arguments}:
3520 @multitable @columnfractions .15 .70
3521 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
3522 kind and shall specify a valid path within the file system.
3523 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
3524 kind. Returns 0 on success, and a system specific and nonzero error code
3528 @item @emph{Example}:
3531 CHARACTER(len=255) :: path
3533 WRITE(*,*) TRIM(path)
3536 WRITE(*,*) TRIM(path)
3540 @item @emph{See also}:
3547 @section @code{CHMOD} --- Change access permissions of files
3549 @cindex file system, change access mode
3552 @item @emph{Description}:
3553 @code{CHMOD} changes the permissions of a file.
3555 This intrinsic is provided in both subroutine and function forms; however,
3556 only one form can be used in any given program unit.
3558 @item @emph{Standard}:
3562 Subroutine, function
3564 @item @emph{Syntax}:
3565 @multitable @columnfractions .80
3566 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
3567 @item @code{STATUS = CHMOD(NAME, MODE)}
3570 @item @emph{Arguments}:
3571 @multitable @columnfractions .15 .70
3573 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
3574 file name. Trailing blanks are ignored unless the character
3575 @code{achar(0)} is present, then all characters up to and excluding
3576 @code{achar(0)} are used as the file name.
3578 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
3579 file permission. @var{MODE} uses the same syntax as the @code{chmod} utility
3580 as defined by the POSIX standard. The argument shall either be a string of
3581 a nonnegative octal number or a symbolic mode.
3583 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
3584 @code{0} on success and nonzero otherwise.
3587 @item @emph{Return value}:
3588 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
3591 @item @emph{Example}:
3592 @code{CHMOD} as subroutine
3597 call chmod('test.dat','u+x',status)
3598 print *, 'Status: ', status
3599 end program chmod_test
3601 @code{CHMOD} as function:
3606 status = chmod('test.dat','u+x')
3607 print *, 'Status: ', status
3608 end program chmod_test
3616 @section @code{CMPLX} --- Complex conversion function
3618 @cindex complex numbers, conversion to
3619 @cindex conversion, to complex
3622 @item @emph{Description}:
3623 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
3624 the real component. If @var{Y} is present it is converted to the imaginary
3625 component. If @var{Y} is not present then the imaginary component is set to
3626 0.0. If @var{X} is complex then @var{Y} must not be present.
3628 @item @emph{Standard}:
3629 Fortran 77 and later
3634 @item @emph{Syntax}:
3635 @code{RESULT = CMPLX(X [, Y [, KIND]])}
3637 @item @emph{Arguments}:
3638 @multitable @columnfractions .15 .70
3639 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3641 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
3642 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
3643 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3644 expression indicating the kind parameter of the result.
3647 @item @emph{Return value}:
3648 The return value is of @code{COMPLEX} type, with a kind equal to
3649 @var{KIND} if it is specified. If @var{KIND} is not specified, the
3650 result is of the default @code{COMPLEX} kind, regardless of the kinds of
3651 @var{X} and @var{Y}.
3653 @item @emph{Example}:
3660 print *, z, cmplx(x)
3661 end program test_cmplx
3664 @item @emph{See also}:
3671 @section @code{CO_BROADCAST} --- Copy a value to all images the current set of images
3672 @fnindex CO_BROADCAST
3673 @cindex Collectives, value broadcasting
3676 @item @emph{Description}:
3677 @code{CO_BROADCAST} copies the value of argument @var{A} on the image with
3678 image index @code{SOURCE_IMAGE} to all images in the current team. @var{A}
3679 becomes defined as if by intrinsic assignment. If the execution was
3680 successful and @var{STAT} is present, it is assigned the value zero. If the
3681 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3682 @var{ERRMSG} gets assigned a value describing the occurred error.
3684 @item @emph{Standard}:
3685 Technical Specification (TS) 18508 or later
3688 Collective subroutine
3690 @item @emph{Syntax}:
3691 @code{CALL CO_BROADCAST(A, SOURCE_IMAGE [, STAT, ERRMSG])}
3693 @item @emph{Arguments}:
3694 @multitable @columnfractions .20 .65
3695 @item @var{A} @tab INTENT(INOUT) argument; shall have the same
3696 dynamic type and type parameters on all images of the current team. If it
3697 is an array, it shall have the same shape on all images.
3698 @item @var{SOURCE_IMAGE} @tab a scalar integer expression.
3699 It shall have the same the same value on all images and refer to an
3700 image of the current team.
3701 @item @var{STAT} @tab (optional) a scalar integer variable
3702 @item @var{ERRMSG} @tab (optional) a scalar character variable
3705 @item @emph{Example}:
3709 if (this_image() == 1) then
3712 call co_broadcast (val, source_image=1)
3713 print *, this_image, ":", val
3717 @item @emph{See also}:
3727 @section @code{CO_MAX} --- Maximal value on the current set of images
3729 @cindex Collectives, maximal value
3732 @item @emph{Description}:
3733 @code{CO_MAX} determines element-wise the maximal value of @var{A} on all
3734 images of the current team. If @var{RESULT_IMAGE} is present, the maximum
3735 values are returned in @var{A} on the specified image only and the value
3736 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3737 not present, the value is returned on all images. If the execution was
3738 successful and @var{STAT} is present, it is assigned the value zero. If the
3739 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3740 @var{ERRMSG} gets assigned a value describing the occurred error.
3742 @item @emph{Standard}:
3743 Technical Specification (TS) 18508 or later
3746 Collective subroutine
3748 @item @emph{Syntax}:
3749 @code{CALL CO_MAX(A [, RESULT_IMAGE, STAT, ERRMSG])}
3751 @item @emph{Arguments}:
3752 @multitable @columnfractions .20 .65
3753 @item @var{A} @tab shall be an integer, real or character variable,
3754 which has the same type and type parameters on all images of the team.
3755 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3756 present, it shall have the same value on all images and refer to an
3757 image of the current team.
3758 @item @var{STAT} @tab (optional) a scalar integer variable
3759 @item @var{ERRMSG} @tab (optional) a scalar character variable
3762 @item @emph{Example}:
3767 call co_max (val, result_image=1)
3768 if (this_image() == 1) then
3769 write(*,*) "Maximal value", val ! prints num_images()
3774 @item @emph{See also}:
3777 @ref{CO_REDUCE}, @gol
3784 @section @code{CO_MIN} --- Minimal value on the current set of images
3786 @cindex Collectives, minimal value
3789 @item @emph{Description}:
3790 @code{CO_MIN} determines element-wise the minimal value of @var{A} on all
3791 images of the current team. If @var{RESULT_IMAGE} is present, the minimal
3792 values are returned in @var{A} on the specified image only and the value
3793 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3794 not present, the value is returned on all images. If the execution was
3795 successful and @var{STAT} is present, it is assigned the value zero. If the
3796 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3797 @var{ERRMSG} gets assigned a value describing the occurred error.
3799 @item @emph{Standard}:
3800 Technical Specification (TS) 18508 or later
3803 Collective subroutine
3805 @item @emph{Syntax}:
3806 @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3808 @item @emph{Arguments}:
3809 @multitable @columnfractions .20 .65
3810 @item @var{A} @tab shall be an integer, real or character variable,
3811 which has the same type and type parameters on all images of the team.
3812 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3813 present, it shall have the same the same value on all images and refer to an
3814 image of the current team.
3815 @item @var{STAT} @tab (optional) a scalar integer variable
3816 @item @var{ERRMSG} @tab (optional) a scalar character variable
3819 @item @emph{Example}:
3824 call co_min (val, result_image=1)
3825 if (this_image() == 1) then
3826 write(*,*) "Minimal value", val ! prints 1
3831 @item @emph{See also}:
3834 @ref{CO_REDUCE}, @gol
3841 @section @code{CO_REDUCE} --- Reduction of values on the current set of images
3843 @cindex Collectives, generic reduction
3846 @item @emph{Description}:
3847 @code{CO_REDUCE} determines element-wise the reduction of the value of @var{A}
3848 on all images of the current team. The pure function passed as @var{OPERATOR}
3849 is used to pairwise reduce the values of @var{A} by passing either the value
3850 of @var{A} of different images or the result values of such a reduction as
3851 argument. If @var{A} is an array, the deduction is done element wise. If
3852 @var{RESULT_IMAGE} is present, the result values are returned in @var{A} on
3853 the specified image only and the value of @var{A} on the other images become
3854 undefined. If @var{RESULT_IMAGE} is not present, the value is returned on all
3855 images. If the execution was successful and @var{STAT} is present, it is
3856 assigned the value zero. If the execution failed, @var{STAT} gets assigned
3857 a nonzero value and, if present, @var{ERRMSG} gets assigned a value describing
3860 @item @emph{Standard}:
3861 Technical Specification (TS) 18508 or later
3864 Collective subroutine
3866 @item @emph{Syntax}:
3867 @code{CALL CO_REDUCE(A, OPERATOR, [, RESULT_IMAGE, STAT, ERRMSG])}
3869 @item @emph{Arguments}:
3870 @multitable @columnfractions .20 .65
3871 @item @var{A} @tab is an @code{INTENT(INOUT)} argument and shall be
3872 nonpolymorphic. If it is allocatable, it shall be allocated; if it is a pointer,
3873 it shall be associated. @var{A} shall have the same type and type parameters on
3874 all images of the team; if it is an array, it shall have the same shape on all
3876 @item @var{OPERATOR} @tab pure function with two scalar nonallocatable
3877 arguments, which shall be nonpolymorphic and have the same type and type
3878 parameters as @var{A}. The function shall return a nonallocatable scalar of
3879 the same type and type parameters as @var{A}. The function shall be the same on
3880 all images and with regards to the arguments mathematically commutative and
3881 associative. Note that @var{OPERATOR} may not be an elemental function, unless
3882 it is an intrisic function.
3883 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3884 present, it shall have the same the same value on all images and refer to an
3885 image of the current team.
3886 @item @var{STAT} @tab (optional) a scalar integer variable
3887 @item @var{ERRMSG} @tab (optional) a scalar character variable
3890 @item @emph{Example}:
3895 call co_reduce (val, result_image=1, operator=myprod)
3896 if (this_image() == 1) then
3897 write(*,*) "Product value", val ! prints num_images() factorial
3900 pure function myprod(a, b)
3901 integer, value :: a, b
3909 While the rules permit in principle an intrinsic function, none of the
3910 intrinsics in the standard fulfill the criteria of having a specific
3911 function, which takes two arguments of the same type and returning that
3914 @item @emph{See also}:
3924 @section @code{CO_SUM} --- Sum of values on the current set of images
3926 @cindex Collectives, sum of values
3929 @item @emph{Description}:
3930 @code{CO_SUM} sums up the values of each element of @var{A} on all
3931 images of the current team. If @var{RESULT_IMAGE} is present, the summed-up
3932 values are returned in @var{A} on the specified image only and the value
3933 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3934 not present, the value is returned on all images. If the execution was
3935 successful and @var{STAT} is present, it is assigned the value zero. If the
3936 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3937 @var{ERRMSG} gets assigned a value describing the occurred error.
3939 @item @emph{Standard}:
3940 Technical Specification (TS) 18508 or later
3943 Collective subroutine
3945 @item @emph{Syntax}:
3946 @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3948 @item @emph{Arguments}:
3949 @multitable @columnfractions .20 .65
3950 @item @var{A} @tab shall be an integer, real or complex variable,
3951 which has the same type and type parameters on all images of the team.
3952 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3953 present, it shall have the same the same value on all images and refer to an
3954 image of the current team.
3955 @item @var{STAT} @tab (optional) a scalar integer variable
3956 @item @var{ERRMSG} @tab (optional) a scalar character variable
3959 @item @emph{Example}:
3964 call co_sum (val, result_image=1)
3965 if (this_image() == 1) then
3966 write(*,*) "The sum is ", val ! prints (n**2 + n)/2,
3967 ! with n = num_images()
3972 @item @emph{See also}:
3975 @ref{CO_REDUCE}, @gol
3981 @node COMMAND_ARGUMENT_COUNT
3982 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
3983 @fnindex COMMAND_ARGUMENT_COUNT
3984 @cindex command-line arguments
3985 @cindex command-line arguments, number of
3986 @cindex arguments, to program
3989 @item @emph{Description}:
3990 @code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the
3991 command line when the containing program was invoked.
3993 @item @emph{Standard}:
3994 Fortran 2003 and later
3999 @item @emph{Syntax}:
4000 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
4002 @item @emph{Arguments}:
4003 @multitable @columnfractions .15 .70
4007 @item @emph{Return value}:
4008 The return value is an @code{INTEGER} of default kind.
4010 @item @emph{Example}:
4012 program test_command_argument_count
4014 count = command_argument_count()
4016 end program test_command_argument_count
4019 @item @emph{See also}:
4020 @ref{GET_COMMAND}, @gol
4021 @ref{GET_COMMAND_ARGUMENT}
4026 @node COMPILER_OPTIONS
4027 @section @code{COMPILER_OPTIONS} --- Options passed to the compiler
4028 @fnindex COMPILER_OPTIONS
4029 @cindex flags inquiry function
4030 @cindex options inquiry function
4031 @cindex compiler flags inquiry function
4034 @item @emph{Description}:
4035 @code{COMPILER_OPTIONS} returns a string with the options used for
4038 @item @emph{Standard}:
4042 Inquiry function of the module @code{ISO_FORTRAN_ENV}
4044 @item @emph{Syntax}:
4045 @code{STR = COMPILER_OPTIONS()}
4047 @item @emph{Arguments}:
4050 @item @emph{Return value}:
4051 The return value is a default-kind string with system-dependent length.
4052 It contains the compiler flags used to compile the file, which called
4053 the @code{COMPILER_OPTIONS} intrinsic.
4055 @item @emph{Example}:
4058 print '(4a)', 'This file was compiled by ', &
4059 compiler_version(), ' using the options ', &
4064 @item @emph{See also}:
4065 @ref{COMPILER_VERSION}, @gol
4066 @ref{ISO_FORTRAN_ENV}
4071 @node COMPILER_VERSION
4072 @section @code{COMPILER_VERSION} --- Compiler version string
4073 @fnindex COMPILER_VERSION
4074 @cindex compiler, name and version
4075 @cindex version of the compiler
4078 @item @emph{Description}:
4079 @code{COMPILER_VERSION} returns a string with the name and the
4080 version of the compiler.
4082 @item @emph{Standard}:
4086 Inquiry function of the module @code{ISO_FORTRAN_ENV}
4088 @item @emph{Syntax}:
4089 @code{STR = COMPILER_VERSION()}
4091 @item @emph{Arguments}:
4094 @item @emph{Return value}:
4095 The return value is a default-kind string with system-dependent length.
4096 It contains the name of the compiler and its version number.
4098 @item @emph{Example}:
4101 print '(4a)', 'This file was compiled by ', &
4102 compiler_version(), ' using the options ', &
4107 @item @emph{See also}:
4108 @ref{COMPILER_OPTIONS}, @gol
4109 @ref{ISO_FORTRAN_ENV}
4115 @section @code{COMPLEX} --- Complex conversion function
4117 @cindex complex numbers, conversion to
4118 @cindex conversion, to complex
4121 @item @emph{Description}:
4122 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
4123 to the real component and @var{Y} is converted to the imaginary
4126 @item @emph{Standard}:
4132 @item @emph{Syntax}:
4133 @code{RESULT = COMPLEX(X, Y)}
4135 @item @emph{Arguments}:
4136 @multitable @columnfractions .15 .70
4137 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
4138 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
4141 @item @emph{Return value}:
4142 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
4143 value is of default @code{COMPLEX} type.
4145 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
4146 type and one is of @code{INTEGER} type, then the return value is of
4147 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
4148 argument with the highest precision.
4150 @item @emph{Example}:
4152 program test_complex
4155 print *, complex(i, x)
4156 end program test_complex
4159 @item @emph{See also}:
4166 @section @code{CONJG} --- Complex conjugate function
4169 @cindex complex conjugate
4172 @item @emph{Description}:
4173 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
4174 then the result is @code{(x, -y)}
4176 @item @emph{Standard}:
4177 Fortran 77 and later, has an overload that is a GNU extension
4182 @item @emph{Syntax}:
4185 @item @emph{Arguments}:
4186 @multitable @columnfractions .15 .70
4187 @item @var{Z} @tab The type shall be @code{COMPLEX}.
4190 @item @emph{Return value}:
4191 The return value is of type @code{COMPLEX}.
4193 @item @emph{Example}:
4196 complex :: z = (2.0, 3.0)
4197 complex(8) :: dz = (2.71_8, -3.14_8)
4202 end program test_conjg
4205 @item @emph{Specific names}:
4206 @multitable @columnfractions .20 .20 .20 .25
4207 @item Name @tab Argument @tab Return type @tab Standard
4208 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
4215 @section @code{COS} --- Cosine function
4221 @cindex trigonometric function, cosine
4225 @item @emph{Description}:
4226 @code{COS(X)} computes the cosine of @var{X}.
4228 @item @emph{Standard}:
4229 Fortran 77 and later, has overloads that are GNU extensions
4234 @item @emph{Syntax}:
4235 @code{RESULT = COS(X)}
4237 @item @emph{Arguments}:
4238 @multitable @columnfractions .15 .70
4239 @item @var{X} @tab The type shall be @code{REAL} or
4243 @item @emph{Return value}:
4244 The return value is of the same type and kind as @var{X}. The real part
4245 of the result is in radians. If @var{X} is of the type @code{REAL},
4246 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
4248 @item @emph{Example}:
4253 end program test_cos
4256 @item @emph{Specific names}:
4257 @multitable @columnfractions .20 .20 .20 .25
4258 @item Name @tab Argument @tab Return type @tab Standard
4259 @item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
4260 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
4261 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
4262 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4263 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4266 @item @emph{See also}:
4267 Inverse function: @gol
4269 Degrees function: @gol
4276 @section @code{COSD} --- Cosine function, degrees
4282 @cindex trigonometric function, cosine, degrees
4283 @cindex cosine, degrees
4286 @item @emph{Description}:
4287 @code{COSD(X)} computes the cosine of @var{X} in degrees.
4289 This function is for compatibility only and should be avoided in favor of
4290 standard constructs wherever possible.
4292 @item @emph{Standard}:
4293 GNU extension, enabled with @option{-fdec-math}.
4298 @item @emph{Syntax}:
4299 @code{RESULT = COSD(X)}
4301 @item @emph{Arguments}:
4302 @multitable @columnfractions .15 .70
4303 @item @var{X} @tab The type shall be @code{REAL} or
4307 @item @emph{Return value}:
4308 The return value is of the same type and kind as @var{X}. The real part
4309 of the result is in degrees. If @var{X} is of the type @code{REAL},
4310 the return value lies in the range @math{ -1 \leq \cosd (x) \leq 1}.
4312 @item @emph{Example}:
4317 end program test_cosd
4320 @item @emph{Specific names}:
4321 @multitable @columnfractions .20 .20 .20 .25
4322 @item Name @tab Argument @tab Return type @tab Standard
4323 @item @code{COSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
4324 @item @code{DCOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4325 @item @code{CCOSD(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU extension
4326 @item @code{ZCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4327 @item @code{CDCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4330 @item @emph{See also}:
4331 Inverse function: @gol
4333 Radians function: @gol
4340 @section @code{COSH} --- Hyperbolic cosine function
4343 @cindex hyperbolic cosine
4344 @cindex hyperbolic function, cosine
4345 @cindex cosine, hyperbolic
4348 @item @emph{Description}:
4349 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
4351 @item @emph{Standard}:
4352 Fortran 77 and later, for a complex argument Fortran 2008 or later
4357 @item @emph{Syntax}:
4360 @item @emph{Arguments}:
4361 @multitable @columnfractions .15 .70
4362 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4365 @item @emph{Return value}:
4366 The return value has same type and kind as @var{X}. If @var{X} is
4367 complex, the imaginary part of the result is in radians. If @var{X}
4368 is @code{REAL}, the return value has a lower bound of one,
4369 @math{\cosh (x) \geq 1}.
4371 @item @emph{Example}:
4374 real(8) :: x = 1.0_8
4376 end program test_cosh
4379 @item @emph{Specific names}:
4380 @multitable @columnfractions .20 .20 .20 .25
4381 @item Name @tab Argument @tab Return type @tab Standard
4382 @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
4383 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
4386 @item @emph{See also}:
4387 Inverse function: @gol
4394 @section @code{COTAN} --- Cotangent function
4397 @cindex trigonometric function, cotangent
4401 @item @emph{Description}:
4402 @code{COTAN(X)} computes the cotangent of @var{X}. Equivalent to @code{COS(x)}
4403 divided by @code{SIN(x)}, or @code{1 / TAN(x)}.
4405 This function is for compatibility only and should be avoided in favor of
4406 standard constructs wherever possible.
4408 @item @emph{Standard}:
4409 GNU extension, enabled with @option{-fdec-math}.
4414 @item @emph{Syntax}:
4415 @code{RESULT = COTAN(X)}
4417 @item @emph{Arguments}:
4418 @multitable @columnfractions .15 .70
4419 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4422 @item @emph{Return value}:
4423 The return value has same type and kind as @var{X}, and its value is in radians.
4425 @item @emph{Example}:
4428 real(8) :: x = 0.165_8
4430 end program test_cotan
4433 @item @emph{Specific names}:
4434 @multitable @columnfractions .20 .20 .20 .25
4435 @item Name @tab Argument @tab Return type @tab Standard
4436 @item @code{COTAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
4437 @item @code{DCOTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4440 @item @emph{See also}:
4441 Converse function: @gol
4443 Degrees function: @gol
4450 @section @code{COTAND} --- Cotangent function, degrees
4453 @cindex trigonometric function, cotangent, degrees
4454 @cindex cotangent, degrees
4457 @item @emph{Description}:
4458 @code{COTAND(X)} computes the cotangent of @var{X} in degrees. Equivalent to
4459 @code{COSD(x)} divided by @code{SIND(x)}, or @code{1 / TAND(x)}.
4461 @item @emph{Standard}:
4462 GNU extension, enabled with @option{-fdec-math}.
4464 This function is for compatibility only and should be avoided in favor of
4465 standard constructs wherever possible.
4470 @item @emph{Syntax}:
4471 @code{RESULT = COTAND(X)}
4473 @item @emph{Arguments}:
4474 @multitable @columnfractions .15 .70
4475 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4478 @item @emph{Return value}:
4479 The return value has same type and kind as @var{X}, and its value is in degrees.
4481 @item @emph{Example}:
4484 real(8) :: x = 0.165_8
4486 end program test_cotand
4489 @item @emph{Specific names}:
4490 @multitable @columnfractions .20 .20 .20 .25
4491 @item Name @tab Argument @tab Return type @tab Standard
4492 @item @code{COTAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
4493 @item @code{DCOTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4496 @item @emph{See also}:
4497 Converse function: @gol
4499 Radians function: @gol
4506 @section @code{COUNT} --- Count function
4508 @cindex array, conditionally count elements
4509 @cindex array, element counting
4510 @cindex array, number of elements
4513 @item @emph{Description}:
4515 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
4516 or, if the @var{DIM} argument is supplied, counts the number of
4517 elements along each row of the array in the @var{DIM} direction.
4518 If the array has zero size, or all of the elements of @var{MASK} are
4519 @code{.FALSE.}, then the result is @code{0}.
4521 @item @emph{Standard}:
4522 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
4525 Transformational function
4527 @item @emph{Syntax}:
4528 @code{RESULT = COUNT(MASK [, DIM, KIND])}
4530 @item @emph{Arguments}:
4531 @multitable @columnfractions .15 .70
4532 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
4533 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
4534 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4535 expression indicating the kind parameter of the result.
4538 @item @emph{Return value}:
4539 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
4540 @var{KIND} is absent, the return value is of default integer kind.
4541 If @var{DIM} is present, the result is an array with a rank one less
4542 than the rank of @var{ARRAY}, and a size corresponding to the shape
4543 of @var{ARRAY} with the @var{DIM} dimension removed.
4545 @item @emph{Example}:
4548 integer, dimension(2,3) :: a, b
4549 logical, dimension(2,3) :: mask
4550 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
4551 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
4552 print '(3i3)', a(1,:)
4553 print '(3i3)', a(2,:)
4555 print '(3i3)', b(1,:)
4556 print '(3i3)', b(2,:)
4559 print '(3l3)', mask(1,:)
4560 print '(3l3)', mask(2,:)
4562 print '(3i3)', count(mask)
4564 print '(3i3)', count(mask, 1)
4566 print '(3i3)', count(mask, 2)
4567 end program test_count
4574 @section @code{CPU_TIME} --- CPU elapsed time in seconds
4576 @cindex time, elapsed
4579 @item @emph{Description}:
4580 Returns a @code{REAL} value representing the elapsed CPU time in
4581 seconds. This is useful for testing segments of code to determine
4584 If a time source is available, time will be reported with microsecond
4585 resolution. If no time source is available, @var{TIME} is set to
4588 Note that @var{TIME} may contain a, system dependent, arbitrary offset
4589 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
4590 value is meaningless, only differences between subsequent calls to
4591 this subroutine, as shown in the example below, should be used.
4594 @item @emph{Standard}:
4595 Fortran 95 and later
4600 @item @emph{Syntax}:
4601 @code{CALL CPU_TIME(TIME)}
4603 @item @emph{Arguments}:
4604 @multitable @columnfractions .15 .70
4605 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
4608 @item @emph{Return value}:
4611 @item @emph{Example}:
4613 program test_cpu_time
4614 real :: start, finish
4615 call cpu_time(start)
4616 ! put code to test here
4617 call cpu_time(finish)
4618 print '("Time = ",f6.3," seconds.")',finish-start
4619 end program test_cpu_time
4622 @item @emph{See also}:
4623 @ref{SYSTEM_CLOCK}, @gol
4630 @section @code{CSHIFT} --- Circular shift elements of an array
4632 @cindex array, shift circularly
4633 @cindex array, permutation
4634 @cindex array, rotate
4637 @item @emph{Description}:
4638 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
4639 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
4640 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
4641 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
4642 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
4643 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
4644 sections of @var{ARRAY} along the given dimension are shifted. Elements
4645 shifted out one end of each rank one section are shifted back in the other end.
4647 @item @emph{Standard}:
4648 Fortran 90 and later
4651 Transformational function
4653 @item @emph{Syntax}:
4654 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
4656 @item @emph{Arguments}:
4657 @multitable @columnfractions .15 .70
4658 @item @var{ARRAY} @tab Shall be an array of any type.
4659 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
4660 @item @var{DIM} @tab The type shall be @code{INTEGER}.
4663 @item @emph{Return value}:
4664 Returns an array of same type and rank as the @var{ARRAY} argument.
4666 @item @emph{Example}:
4669 integer, dimension(3,3) :: a
4670 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
4671 print '(3i3)', a(1,:)
4672 print '(3i3)', a(2,:)
4673 print '(3i3)', a(3,:)
4674 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
4676 print '(3i3)', a(1,:)
4677 print '(3i3)', a(2,:)
4678 print '(3i3)', a(3,:)
4679 end program test_cshift
4686 @section @code{CTIME} --- Convert a time into a string
4688 @cindex time, conversion to string
4689 @cindex conversion, to string
4692 @item @emph{Description}:
4693 @code{CTIME} converts a system time value, such as returned by
4694 @ref{TIME8}, to a string. The output will be of the form @samp{Sat
4695 Aug 19 18:13:14 1995}.
4697 This intrinsic is provided in both subroutine and function forms; however,
4698 only one form can be used in any given program unit.
4700 @item @emph{Standard}:
4704 Subroutine, function
4706 @item @emph{Syntax}:
4707 @multitable @columnfractions .80
4708 @item @code{CALL CTIME(TIME, RESULT)}.
4709 @item @code{RESULT = CTIME(TIME)}.
4712 @item @emph{Arguments}:
4713 @multitable @columnfractions .15 .70
4714 @item @var{TIME} @tab The type shall be of type @code{INTEGER}.
4715 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
4716 of default kind. It is an @code{INTENT(OUT)} argument. If the length
4717 of this variable is too short for the time and date string to fit
4718 completely, it will be blank on procedure return.
4721 @item @emph{Return value}:
4722 The converted date and time as a string.
4724 @item @emph{Example}:
4728 character(len=30) :: date
4731 ! Do something, main part of the program
4734 print *, 'Program was started on ', date
4735 end program test_ctime
4738 @item @emph{See Also}:
4739 @ref{DATE_AND_TIME}, @gol
4749 @section @code{DATE_AND_TIME} --- Date and time subroutine
4750 @fnindex DATE_AND_TIME
4751 @cindex date, current
4752 @cindex current date
4753 @cindex time, current
4754 @cindex current time
4757 @item @emph{Description}:
4758 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
4759 time information from the real-time system clock. @var{DATE} is
4760 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
4761 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
4762 representing the difference with respect to Coordinated Universal Time (UTC).
4763 Unavailable time and date parameters return blanks.
4765 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
4767 @multitable @columnfractions .15 .30 .40
4768 @item @tab @code{VALUE(1)}: @tab The year
4769 @item @tab @code{VALUE(2)}: @tab The month
4770 @item @tab @code{VALUE(3)}: @tab The day of the month
4771 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
4772 @item @tab @code{VALUE(5)}: @tab The hour of the day
4773 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
4774 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
4775 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
4778 @item @emph{Standard}:
4779 Fortran 90 and later
4784 @item @emph{Syntax}:
4785 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
4787 @item @emph{Arguments}:
4788 @multitable @columnfractions .15 .70
4789 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
4790 or larger, and of default kind.
4791 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
4792 or larger, and of default kind.
4793 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
4794 or larger, and of default kind.
4795 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
4798 @item @emph{Return value}:
4801 @item @emph{Example}:
4803 program test_time_and_date
4804 character(8) :: date
4805 character(10) :: time
4806 character(5) :: zone
4807 integer,dimension(8) :: values
4808 ! using keyword arguments
4809 call date_and_time(date,time,zone,values)
4810 call date_and_time(DATE=date,ZONE=zone)
4811 call date_and_time(TIME=time)
4812 call date_and_time(VALUES=values)
4813 print '(a,2x,a,2x,a)', date, time, zone
4814 print '(8i5)', values
4815 end program test_time_and_date
4818 @item @emph{See also}:
4819 @ref{CPU_TIME}, @gol
4826 @section @code{DBLE} --- Double conversion function
4828 @cindex conversion, to real
4831 @item @emph{Description}:
4832 @code{DBLE(A)} Converts @var{A} to double precision real type.
4834 @item @emph{Standard}:
4835 Fortran 77 and later
4840 @item @emph{Syntax}:
4841 @code{RESULT = DBLE(A)}
4843 @item @emph{Arguments}:
4844 @multitable @columnfractions .15 .70
4845 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
4849 @item @emph{Return value}:
4850 The return value is of type double precision real.
4852 @item @emph{Example}:
4857 complex :: z = (2.3,1.14)
4858 print *, dble(x), dble(i), dble(z)
4859 end program test_dble
4862 @item @emph{See also}:
4869 @section @code{DCMPLX} --- Double complex conversion function
4871 @cindex complex numbers, conversion to
4872 @cindex conversion, to complex
4875 @item @emph{Description}:
4876 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
4877 converted to the real component. If @var{Y} is present it is converted to the
4878 imaginary component. If @var{Y} is not present then the imaginary component is
4879 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
4881 @item @emph{Standard}:
4887 @item @emph{Syntax}:
4888 @code{RESULT = DCMPLX(X [, Y])}
4890 @item @emph{Arguments}:
4891 @multitable @columnfractions .15 .70
4892 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
4894 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
4895 @code{INTEGER} or @code{REAL}.
4898 @item @emph{Return value}:
4899 The return value is of type @code{COMPLEX(8)}
4901 @item @emph{Example}:
4911 print *, dcmplx(x,i)
4912 end program test_dcmplx
4918 @section @code{DIGITS} --- Significant binary digits function
4920 @cindex model representation, significant digits
4923 @item @emph{Description}:
4924 @code{DIGITS(X)} returns the number of significant binary digits of the internal
4925 model representation of @var{X}. For example, on a system using a 32-bit
4926 floating point representation, a default real number would likely return 24.
4928 @item @emph{Standard}:
4929 Fortran 90 and later
4934 @item @emph{Syntax}:
4935 @code{RESULT = DIGITS(X)}
4937 @item @emph{Arguments}:
4938 @multitable @columnfractions .15 .70
4939 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
4942 @item @emph{Return value}:
4943 The return value is of type @code{INTEGER}.
4945 @item @emph{Example}:
4948 integer :: i = 12345
4954 end program test_digits
4961 @section @code{DIM} --- Positive difference
4965 @cindex positive difference
4968 @item @emph{Description}:
4969 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
4970 otherwise returns zero.
4972 @item @emph{Standard}:
4973 Fortran 77 and later
4978 @item @emph{Syntax}:
4979 @code{RESULT = DIM(X, Y)}
4981 @item @emph{Arguments}:
4982 @multitable @columnfractions .15 .70
4983 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
4984 @item @var{Y} @tab The type shall be the same type and kind as @var{X}. (As
4985 a GNU extension, arguments of different kinds are permitted.)
4988 @item @emph{Return value}:
4989 The return value is of type @code{INTEGER} or @code{REAL}. (As a GNU
4990 extension, kind is the largest kind of the actual arguments.)
4992 @item @emph{Example}:
4998 x = dim(4.345_8, 2.111_8)
5001 end program test_dim
5004 @item @emph{Specific names}:
5005 @multitable @columnfractions .20 .20 .20 .25
5006 @item Name @tab Argument @tab Return type @tab Standard
5007 @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
5008 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
5009 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
5016 @section @code{DOT_PRODUCT} --- Dot product function
5017 @fnindex DOT_PRODUCT
5019 @cindex vector product
5020 @cindex product, vector
5023 @item @emph{Description}:
5024 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
5025 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
5026 either numeric or logical and must be arrays of rank one and of equal size. If
5027 the vectors are @code{INTEGER} or @code{REAL}, the result is
5028 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
5029 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
5030 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
5032 @item @emph{Standard}:
5033 Fortran 90 and later
5036 Transformational function
5038 @item @emph{Syntax}:
5039 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
5041 @item @emph{Arguments}:
5042 @multitable @columnfractions .15 .70
5043 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
5044 @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.
5047 @item @emph{Return value}:
5048 If the arguments are numeric, the return value is a scalar of numeric type,
5049 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
5050 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
5052 @item @emph{Example}:
5054 program test_dot_prod
5055 integer, dimension(3) :: a, b
5062 print *, dot_product(a,b)
5063 end program test_dot_prod
5070 @section @code{DPROD} --- Double product function
5072 @cindex product, double-precision
5075 @item @emph{Description}:
5076 @code{DPROD(X,Y)} returns the product @code{X*Y}.
5078 @item @emph{Standard}:
5079 Fortran 77 and later
5084 @item @emph{Syntax}:
5085 @code{RESULT = DPROD(X, Y)}
5087 @item @emph{Arguments}:
5088 @multitable @columnfractions .15 .70
5089 @item @var{X} @tab The type shall be @code{REAL}.
5090 @item @var{Y} @tab The type shall be @code{REAL}.
5093 @item @emph{Return value}:
5094 The return value is of type @code{REAL(8)}.
5096 @item @emph{Example}:
5104 end program test_dprod
5107 @item @emph{Specific names}:
5108 @multitable @columnfractions .20 .20 .20 .25
5109 @item Name @tab Argument @tab Return type @tab Standard
5110 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
5117 @section @code{DREAL} --- Double real part function
5119 @cindex complex numbers, real part
5122 @item @emph{Description}:
5123 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
5125 @item @emph{Standard}:
5131 @item @emph{Syntax}:
5132 @code{RESULT = DREAL(A)}
5134 @item @emph{Arguments}:
5135 @multitable @columnfractions .15 .70
5136 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
5139 @item @emph{Return value}:
5140 The return value is of type @code{REAL(8)}.
5142 @item @emph{Example}:
5145 complex(8) :: z = (1.3_8,7.2_8)
5147 end program test_dreal
5150 @item @emph{See also}:
5158 @section @code{DSHIFTL} --- Combined left shift
5160 @cindex left shift, combined
5164 @item @emph{Description}:
5165 @code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
5166 rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
5167 bits of @var{J}, and the remaining bits are the rightmost bits of
5170 @item @emph{Standard}:
5171 Fortran 2008 and later
5176 @item @emph{Syntax}:
5177 @code{RESULT = DSHIFTL(I, J, SHIFT)}
5179 @item @emph{Arguments}:
5180 @multitable @columnfractions .15 .70
5181 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5182 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5183 If both @var{I} and @var{J} have integer type, then they shall have
5184 the same kind type parameter. @var{I} and @var{J} shall not both be
5186 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
5187 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
5188 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
5189 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
5192 @item @emph{Return value}:
5193 If either @var{I} or @var{J} is a BOZ constant, it is first converted
5194 as if by the intrinsic function @code{INT} to an integer type with the
5195 kind type parameter of the other.
5197 @item @emph{See also}:
5203 @section @code{DSHIFTR} --- Combined right shift
5205 @cindex right shift, combined
5206 @cindex shift, right
5209 @item @emph{Description}:
5210 @code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
5211 leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
5212 bits of @var{I}, and the remaining bits are the leftmost bits of
5215 @item @emph{Standard}:
5216 Fortran 2008 and later
5221 @item @emph{Syntax}:
5222 @code{RESULT = DSHIFTR(I, J, SHIFT)}
5224 @item @emph{Arguments}:
5225 @multitable @columnfractions .15 .70
5226 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5227 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5228 If both @var{I} and @var{J} have integer type, then they shall have
5229 the same kind type parameter. @var{I} and @var{J} shall not both be
5231 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
5232 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
5233 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
5234 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
5237 @item @emph{Return value}:
5238 If either @var{I} or @var{J} is a BOZ constant, it is first converted
5239 as if by the intrinsic function @code{INT} to an integer type with the
5240 kind type parameter of the other.
5242 @item @emph{See also}:
5248 @section @code{DTIME} --- Execution time subroutine (or function)
5250 @cindex time, elapsed
5251 @cindex elapsed time
5254 @item @emph{Description}:
5255 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
5256 since the start of the process's execution in @var{TIME}. @var{VALUES}
5257 returns the user and system components of this time in @code{VALUES(1)} and
5258 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
5261 Subsequent invocations of @code{DTIME} return values accumulated since the
5262 previous invocation.
5264 On some systems, the underlying timings are represented using types with
5265 sufficiently small limits that overflows (wrap around) are possible, such as
5266 32-bit types. Therefore, the values returned by this intrinsic might be, or
5267 become, negative, or numerically less than previous values, during a single
5268 run of the compiled program.
5270 Please note, that this implementation is thread safe if used within OpenMP
5271 directives, i.e., its state will be consistent while called from multiple
5272 threads. However, if @code{DTIME} is called from multiple threads, the result
5273 is still the time since the last invocation. This may not give the intended
5274 results. If possible, use @code{CPU_TIME} instead.
5276 This intrinsic is provided in both subroutine and function forms; however,
5277 only one form can be used in any given program unit.
5279 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
5281 @multitable @columnfractions .15 .30 .40
5282 @item @tab @code{VALUES(1)}: @tab User time in seconds.
5283 @item @tab @code{VALUES(2)}: @tab System time in seconds.
5284 @item @tab @code{TIME}: @tab Run time since start in seconds.
5287 @item @emph{Standard}:
5291 Subroutine, function
5293 @item @emph{Syntax}:
5294 @multitable @columnfractions .80
5295 @item @code{CALL DTIME(VALUES, TIME)}.
5296 @item @code{TIME = DTIME(VALUES)}, (not recommended).
5299 @item @emph{Arguments}:
5300 @multitable @columnfractions .15 .70
5301 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
5302 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
5305 @item @emph{Return value}:
5306 Elapsed time in seconds since the last invocation or since the start of program
5307 execution if not called before.
5309 @item @emph{Example}:
5313 real, dimension(2) :: tarray
5315 call dtime(tarray, result)
5319 do i=1,100000000 ! Just a delay
5322 call dtime(tarray, result)
5326 end program test_dtime
5329 @item @emph{See also}:
5337 @section @code{EOSHIFT} --- End-off shift elements of an array
5339 @cindex array, shift
5342 @item @emph{Description}:
5343 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
5344 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
5345 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
5346 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
5347 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
5348 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
5349 then all complete rank one sections of @var{ARRAY} along the given dimension are
5350 shifted. Elements shifted out one end of each rank one section are dropped. If
5351 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
5352 is copied back in the other end. If @var{BOUNDARY} is not present then the
5353 following are copied in depending on the type of @var{ARRAY}.
5355 @multitable @columnfractions .15 .80
5356 @item @emph{Array Type} @tab @emph{Boundary Value}
5357 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
5358 @item Logical @tab @code{.FALSE.}.
5359 @item Character(@var{len}) @tab @var{len} blanks.
5362 @item @emph{Standard}:
5363 Fortran 90 and later
5366 Transformational function
5368 @item @emph{Syntax}:
5369 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
5371 @item @emph{Arguments}:
5372 @multitable @columnfractions .15 .70
5373 @item @var{ARRAY} @tab May be any type, not scalar.
5374 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
5375 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
5376 @item @var{DIM} @tab The type shall be @code{INTEGER}.
5379 @item @emph{Return value}:
5380 Returns an array of same type and rank as the @var{ARRAY} argument.
5382 @item @emph{Example}:
5384 program test_eoshift
5385 integer, dimension(3,3) :: a
5386 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
5387 print '(3i3)', a(1,:)
5388 print '(3i3)', a(2,:)
5389 print '(3i3)', a(3,:)
5390 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
5392 print '(3i3)', a(1,:)
5393 print '(3i3)', a(2,:)
5394 print '(3i3)', a(3,:)
5395 end program test_eoshift
5402 @section @code{EPSILON} --- Epsilon function
5404 @cindex model representation, epsilon
5407 @item @emph{Description}:
5408 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
5409 as @var{X} such that @math{1 + E > 1}.
5411 @item @emph{Standard}:
5412 Fortran 90 and later
5417 @item @emph{Syntax}:
5418 @code{RESULT = EPSILON(X)}
5420 @item @emph{Arguments}:
5421 @multitable @columnfractions .15 .70
5422 @item @var{X} @tab The type shall be @code{REAL}.
5425 @item @emph{Return value}:
5426 The return value is of same type as the argument.
5428 @item @emph{Example}:
5430 program test_epsilon
5435 end program test_epsilon
5442 @section @code{ERF} --- Error function
5444 @cindex error function
5447 @item @emph{Description}:
5448 @code{ERF(X)} computes the error function of @var{X}.
5450 @item @emph{Standard}:
5451 Fortran 2008 and later
5456 @item @emph{Syntax}:
5457 @code{RESULT = ERF(X)}
5459 @item @emph{Arguments}:
5460 @multitable @columnfractions .15 .70
5461 @item @var{X} @tab The type shall be @code{REAL}.
5464 @item @emph{Return value}:
5465 The return value is of type @code{REAL}, of the same kind as
5466 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
5468 @item @emph{Example}:
5471 real(8) :: x = 0.17_8
5473 end program test_erf
5476 @item @emph{Specific names}:
5477 @multitable @columnfractions .20 .20 .20 .25
5478 @item Name @tab Argument @tab Return type @tab Standard
5479 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
5486 @section @code{ERFC} --- Error function
5488 @cindex error function, complementary
5491 @item @emph{Description}:
5492 @code{ERFC(X)} computes the complementary error function of @var{X}.
5494 @item @emph{Standard}:
5495 Fortran 2008 and later
5500 @item @emph{Syntax}:
5501 @code{RESULT = ERFC(X)}
5503 @item @emph{Arguments}:
5504 @multitable @columnfractions .15 .70
5505 @item @var{X} @tab The type shall be @code{REAL}.
5508 @item @emph{Return value}:
5509 The return value is of type @code{REAL} and of the same kind as @var{X}.
5510 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
5512 @item @emph{Example}:
5515 real(8) :: x = 0.17_8
5517 end program test_erfc
5520 @item @emph{Specific names}:
5521 @multitable @columnfractions .20 .20 .20 .25
5522 @item Name @tab Argument @tab Return type @tab Standard
5523 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
5530 @section @code{ERFC_SCALED} --- Error function
5531 @fnindex ERFC_SCALED
5532 @cindex error function, complementary, exponentially-scaled
5535 @item @emph{Description}:
5536 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
5537 error function of @var{X}.
5539 @item @emph{Standard}:
5540 Fortran 2008 and later
5545 @item @emph{Syntax}:
5546 @code{RESULT = ERFC_SCALED(X)}
5548 @item @emph{Arguments}:
5549 @multitable @columnfractions .15 .70
5550 @item @var{X} @tab The type shall be @code{REAL}.
5553 @item @emph{Return value}:
5554 The return value is of type @code{REAL} and of the same kind as @var{X}.
5556 @item @emph{Example}:
5558 program test_erfc_scaled
5559 real(8) :: x = 0.17_8
5561 end program test_erfc_scaled
5568 @section @code{ETIME} --- Execution time subroutine (or function)
5570 @cindex time, elapsed
5573 @item @emph{Description}:
5574 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
5575 since the start of the process's execution in @var{TIME}. @var{VALUES}
5576 returns the user and system components of this time in @code{VALUES(1)} and
5577 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
5579 On some systems, the underlying timings are represented using types with
5580 sufficiently small limits that overflows (wrap around) are possible, such as
5581 32-bit types. Therefore, the values returned by this intrinsic might be, or
5582 become, negative, or numerically less than previous values, during a single
5583 run of the compiled program.
5585 This intrinsic is provided in both subroutine and function forms; however,
5586 only one form can be used in any given program unit.
5588 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
5590 @multitable @columnfractions .15 .30 .60
5591 @item @tab @code{VALUES(1)}: @tab User time in seconds.
5592 @item @tab @code{VALUES(2)}: @tab System time in seconds.
5593 @item @tab @code{TIME}: @tab Run time since start in seconds.
5596 @item @emph{Standard}:
5600 Subroutine, function
5602 @item @emph{Syntax}:
5603 @multitable @columnfractions .80
5604 @item @code{CALL ETIME(VALUES, TIME)}.
5605 @item @code{TIME = ETIME(VALUES)}, (not recommended).
5608 @item @emph{Arguments}:
5609 @multitable @columnfractions .15 .70
5610 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
5611 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
5614 @item @emph{Return value}:
5615 Elapsed time in seconds since the start of program execution.
5617 @item @emph{Example}:
5621 real, dimension(2) :: tarray
5623 call ETIME(tarray, result)
5627 do i=1,100000000 ! Just a delay
5630 call ETIME(tarray, result)
5634 end program test_etime
5637 @item @emph{See also}:
5645 @section @code{EVENT_QUERY} --- Query whether a coarray event has occurred
5646 @fnindex EVENT_QUERY
5647 @cindex Events, EVENT_QUERY
5650 @item @emph{Description}:
5651 @code{EVENT_QUERY} assignes the number of events to @var{COUNT} which have been
5652 posted to the @var{EVENT} variable and not yet been removed by calling
5653 @code{EVENT WAIT}. When @var{STAT} is present and the invocation was successful,
5654 it is assigned the value 0. If it is present and the invocation has failed,
5655 it is assigned a positive value and @var{COUNT} is assigned the value @math{-1}.
5657 @item @emph{Standard}:
5663 @item @emph{Syntax}:
5664 @code{CALL EVENT_QUERY (EVENT, COUNT [, STAT])}
5666 @item @emph{Arguments}:
5667 @multitable @columnfractions .15 .70
5668 @item @var{EVENT} @tab (intent(IN)) Scalar of type @code{EVENT_TYPE},
5669 defined in @code{ISO_FORTRAN_ENV}; shall not be coindexed.
5670 @item @var{COUNT} @tab (intent(out))Scalar integer with at least the
5671 precision of default integer.
5672 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
5675 @item @emph{Example}:
5680 type(event_type) :: event_value_has_been_set[*]
5682 if (this_image() == 1) then
5683 call event_query (event_value_has_been_set, cnt)
5684 if (cnt > 0) write(*,*) "Value has been set"
5685 elseif (this_image() == 2) then
5686 event post (event_value_has_been_set[1])
5695 @node EXECUTE_COMMAND_LINE
5696 @section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
5697 @fnindex EXECUTE_COMMAND_LINE
5698 @cindex system, system call
5699 @cindex command line
5702 @item @emph{Description}:
5703 @code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
5706 The @code{COMMAND} argument is passed to the shell and executed (The
5707 shell is @code{sh} on Unix systems, and @code{cmd.exe} on Windows.).
5708 If @code{WAIT} is present and has the value false, the execution of
5709 the command is asynchronous if the system supports it; otherwise, the
5710 command is executed synchronously using the C library's @code{system}
5713 The three last arguments allow the user to get status information. After
5714 synchronous execution, @code{EXITSTAT} contains the integer exit code of
5715 the command, as returned by @code{system}. @code{CMDSTAT} is set to zero
5716 if the command line was executed (whatever its exit status was).
5717 @code{CMDMSG} is assigned an error message if an error has occurred.
5719 Note that the @code{system} function need not be thread-safe. It is
5720 the responsibility of the user to ensure that @code{system} is not
5721 called concurrently.
5723 For asynchronous execution on supported targets, the POSIX
5724 @code{posix_spawn} or @code{fork} functions are used. Also, a signal
5725 handler for the @code{SIGCHLD} signal is installed.
5727 @item @emph{Standard}:
5728 Fortran 2008 and later
5733 @item @emph{Syntax}:
5734 @code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
5736 @item @emph{Arguments}:
5737 @multitable @columnfractions .15 .70
5738 @item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
5739 @item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
5740 @item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5742 @item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5744 @item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
5748 @item @emph{Example}:
5753 call execute_command_line ("external_prog.exe", exitstat=i)
5754 print *, "Exit status of external_prog.exe was ", i
5756 call execute_command_line ("reindex_files.exe", wait=.false.)
5757 print *, "Now reindexing files in the background"
5759 end program test_exec
5765 Because this intrinsic is implemented in terms of the @code{system}
5766 function call, its behavior with respect to signaling is processor
5767 dependent. In particular, on POSIX-compliant systems, the SIGINT and
5768 SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
5769 such, if the parent process is terminated, the child process might not be
5770 terminated alongside.
5773 @item @emph{See also}:
5780 @section @code{EXIT} --- Exit the program with status.
5782 @cindex program termination
5783 @cindex terminate program
5786 @item @emph{Description}:
5787 @code{EXIT} causes immediate termination of the program with status. If status
5788 is omitted it returns the canonical @emph{success} for the system. All Fortran
5789 I/O units are closed.
5791 @item @emph{Standard}:
5797 @item @emph{Syntax}:
5798 @code{CALL EXIT([STATUS])}
5800 @item @emph{Arguments}:
5801 @multitable @columnfractions .15 .70
5802 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
5805 @item @emph{Return value}:
5806 @code{STATUS} is passed to the parent process on exit.
5808 @item @emph{Example}:
5811 integer :: STATUS = 0
5812 print *, 'This program is going to exit.'
5814 end program test_exit
5817 @item @emph{See also}:
5825 @section @code{EXP} --- Exponential function
5831 @cindex exponential function
5832 @cindex logarithm function, inverse
5835 @item @emph{Description}:
5836 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
5838 @item @emph{Standard}:
5839 Fortran 77 and later, has overloads that are GNU extensions
5844 @item @emph{Syntax}:
5845 @code{RESULT = EXP(X)}
5847 @item @emph{Arguments}:
5848 @multitable @columnfractions .15 .70
5849 @item @var{X} @tab The type shall be @code{REAL} or
5853 @item @emph{Return value}:
5854 The return value has same type and kind as @var{X}.
5856 @item @emph{Example}:
5861 end program test_exp
5864 @item @emph{Specific names}:
5865 @multitable @columnfractions .20 .20 .20 .25
5866 @item Name @tab Argument @tab Return type @tab Standard
5867 @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
5868 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
5869 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
5870 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5871 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5878 @section @code{EXPONENT} --- Exponent function
5880 @cindex real number, exponent
5881 @cindex floating point, exponent
5884 @item @emph{Description}:
5885 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
5886 is zero the value returned is zero.
5888 @item @emph{Standard}:
5889 Fortran 90 and later
5894 @item @emph{Syntax}:
5895 @code{RESULT = EXPONENT(X)}
5897 @item @emph{Arguments}:
5898 @multitable @columnfractions .15 .70
5899 @item @var{X} @tab The type shall be @code{REAL}.
5902 @item @emph{Return value}:
5903 The return value is of type default @code{INTEGER}.
5905 @item @emph{Example}:
5907 program test_exponent
5912 print *, exponent(0.0)
5913 end program test_exponent
5919 @node EXTENDS_TYPE_OF
5920 @section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension
5921 @fnindex EXTENDS_TYPE_OF
5924 @item @emph{Description}:
5925 Query dynamic type for extension.
5927 @item @emph{Standard}:
5928 Fortran 2003 and later
5933 @item @emph{Syntax}:
5934 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
5936 @item @emph{Arguments}:
5937 @multitable @columnfractions .15 .70
5938 @item @var{A} @tab Shall be an object of extensible declared type or
5939 unlimited polymorphic.
5940 @item @var{MOLD} @tab Shall be an object of extensible declared type or
5941 unlimited polymorphic.
5944 @item @emph{Return value}:
5945 The return value is a scalar of type default logical. It is true if and only if
5946 the dynamic type of A is an extension type of the dynamic type of MOLD.
5949 @item @emph{See also}:
5956 @section @code{FDATE} --- Get the current time as a string
5958 @cindex time, current
5959 @cindex current time
5960 @cindex date, current
5961 @cindex current date
5964 @item @emph{Description}:
5965 @code{FDATE(DATE)} returns the current date (using the same format as
5966 @ref{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
5969 This intrinsic is provided in both subroutine and function forms; however,
5970 only one form can be used in any given program unit.
5972 @item @emph{Standard}:
5976 Subroutine, function
5978 @item @emph{Syntax}:
5979 @multitable @columnfractions .80
5980 @item @code{CALL FDATE(DATE)}.
5981 @item @code{DATE = FDATE()}.
5984 @item @emph{Arguments}:
5985 @multitable @columnfractions .15 .70
5986 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
5987 default kind. It is an @code{INTENT(OUT)} argument. If the length of
5988 this variable is too short for the date and time string to fit
5989 completely, it will be blank on procedure return.
5992 @item @emph{Return value}:
5993 The current date and time as a string.
5995 @item @emph{Example}:
5999 character(len=30) :: date
6001 print *, 'Program started on ', date
6002 do i = 1, 100000000 ! Just a delay
6006 print *, 'Program ended on ', date
6007 end program test_fdate
6010 @item @emph{See also}:
6011 @ref{DATE_AND_TIME}, @gol
6017 @section @code{FGET} --- Read a single character in stream mode from stdin
6019 @cindex read character, stream mode
6020 @cindex stream mode, read character
6021 @cindex file operation, read character
6024 @item @emph{Description}:
6025 Read a single character in stream mode from stdin by bypassing normal
6026 formatted output. Stream I/O should not be mixed with normal record-oriented
6027 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
6029 This intrinsic is provided in both subroutine and function forms; however,
6030 only one form can be used in any given program unit.
6032 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
6033 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
6034 Programmers should consider the use of new stream IO feature in new code
6035 for future portability. See also @ref{Fortran 2003 status}.
6037 @item @emph{Standard}:
6041 Subroutine, function
6043 @item @emph{Syntax}:
6044 @multitable @columnfractions .80
6045 @item @code{CALL FGET(C [, STATUS])}
6046 @item @code{STATUS = FGET(C)}
6049 @item @emph{Arguments}:
6050 @multitable @columnfractions .15 .70
6051 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6053 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6054 Returns 0 on success, -1 on end-of-file, and a system specific positive
6055 error code otherwise.
6058 @item @emph{Example}:
6061 INTEGER, PARAMETER :: strlen = 100
6062 INTEGER :: status, i = 1
6063 CHARACTER(len=strlen) :: str = ""
6065 WRITE (*,*) 'Enter text:'
6067 CALL fget(str(i:i), status)
6068 if (status /= 0 .OR. i > strlen) exit
6071 WRITE (*,*) TRIM(str)
6075 @item @emph{See also}:
6084 @section @code{FGETC} --- Read a single character in stream mode
6086 @cindex read character, stream mode
6087 @cindex stream mode, read character
6088 @cindex file operation, read character
6091 @item @emph{Description}:
6092 Read a single character in stream mode by bypassing normal formatted output.
6093 Stream I/O should not be mixed with normal record-oriented (formatted or
6094 unformatted) I/O on the same unit; the results are unpredictable.
6096 This intrinsic is provided in both subroutine and function forms; however,
6097 only one form can be used in any given program unit.
6099 Note that the @code{FGET} intrinsic is provided for backwards compatibility
6100 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
6101 Programmers should consider the use of new stream IO feature in new code
6102 for future portability. See also @ref{Fortran 2003 status}.
6104 @item @emph{Standard}:
6108 Subroutine, function
6110 @item @emph{Syntax}:
6111 @multitable @columnfractions .80
6112 @item @code{CALL FGETC(UNIT, C [, STATUS])}
6113 @item @code{STATUS = FGETC(UNIT, C)}
6116 @item @emph{Arguments}:
6117 @multitable @columnfractions .15 .70
6118 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
6119 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6121 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6122 Returns 0 on success, -1 on end-of-file and a system specific positive
6123 error code otherwise.
6126 @item @emph{Example}:
6129 INTEGER :: fd = 42, status
6132 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
6134 CALL fgetc(fd, c, status)
6135 IF (status /= 0) EXIT
6142 @item @emph{See also}:
6149 @section @code{FINDLOC} --- Search an array for a value
6154 @item @emph{Description}:
6155 Determines the location of the element in the array with the value
6156 given in the @var{VALUE} argument, or, if the @var{DIM} argument is
6157 supplied, determines the locations of the elements equal to the
6158 @var{VALUE} argument element along each
6159 row of the array in the @var{DIM} direction. If @var{MASK} is
6160 present, only the elements for which @var{MASK} is @code{.TRUE.} are
6161 considered. If more than one element in the array has the value
6162 @var{VALUE}, the location returned is that of the first such element
6163 in array element order if the @var{BACK} is not present or if it is
6164 @code{.FALSE.}. If @var{BACK} is true, the location returned is that
6165 of the last such element. If the array has zero size, or all of the
6166 elements of @var{MASK} are @code{.FALSE.}, then the result is an array
6167 of zeroes. Similarly, if @var{DIM} is supplied and all of the
6168 elements of @var{MASK} along a given row are zero, the result value
6169 for that row is zero.
6171 @item @emph{Standard}:
6172 Fortran 2008 and later.
6175 Transformational function
6177 @item @emph{Syntax}:
6178 @multitable @columnfractions .80
6179 @item @code{RESULT = FINDLOC(ARRAY, VALUE, DIM [, MASK] [,KIND] [,BACK])}
6180 @item @code{RESULT = FINDLOC(ARRAY, VALUE, [, MASK] [,KIND] [,BACK])}
6183 @item @emph{Arguments}:
6184 @multitable @columnfractions .15 .70
6185 @item @var{ARRAY} @tab Shall be an array of intrinsic type.
6186 @item @var{VALUE} @tab A scalar of intrinsic type which is in type
6187 conformance with @var{ARRAY}.
6188 @item @var{DIM} @tab (Optional) Shall be a scalar of type
6189 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
6190 inclusive. It may not be an optional dummy argument.
6191 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6192 expression indicating the kind parameter of the result.
6193 @item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}.
6196 @item @emph{Return value}:
6197 If @var{DIM} is absent, the result is a rank-one array with a length
6198 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
6199 is an array with a rank one less than the rank of @var{ARRAY}, and a
6200 size corresponding to the size of @var{ARRAY} with the @var{DIM}
6201 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
6202 of one, the result is a scalar. If the optional argument @var{KIND}
6203 is present, the result is an integer of kind @var{KIND}, otherwise it
6206 @item @emph{See also}:
6213 @section @code{FLOOR} --- Integer floor function
6216 @cindex rounding, floor
6219 @item @emph{Description}:
6220 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
6222 @item @emph{Standard}:
6223 Fortran 95 and later
6228 @item @emph{Syntax}:
6229 @code{RESULT = FLOOR(A [, KIND])}
6231 @item @emph{Arguments}:
6232 @multitable @columnfractions .15 .70
6233 @item @var{A} @tab The type shall be @code{REAL}.
6234 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6235 expression indicating the kind parameter of the result.
6238 @item @emph{Return value}:
6239 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
6240 and of default-kind @code{INTEGER} otherwise.
6242 @item @emph{Example}:
6247 print *, floor(x) ! returns 63
6248 print *, floor(y) ! returns -64
6249 end program test_floor
6252 @item @emph{See also}:
6260 @section @code{FLUSH} --- Flush I/O unit(s)
6262 @cindex file operation, flush
6265 @item @emph{Description}:
6266 Flushes Fortran unit(s) currently open for output. Without the optional
6267 argument, all units are flushed, otherwise just the unit specified.
6269 @item @emph{Standard}:
6275 @item @emph{Syntax}:
6276 @code{CALL FLUSH(UNIT)}
6278 @item @emph{Arguments}:
6279 @multitable @columnfractions .15 .70
6280 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
6284 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
6285 statement that should be preferred over the @code{FLUSH} intrinsic.
6287 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
6288 have identical effect: they flush the runtime library's I/O buffer so
6289 that the data becomes visible to other processes. This does not guarantee
6290 that the data is committed to disk.
6292 On POSIX systems, you can request that all data is transferred to the
6293 storage device by calling the @code{fsync} function, with the POSIX file
6294 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
6295 @code{FNUM}). The following example shows how:
6298 ! Declare the interface for POSIX fsync function
6300 function fsync (fd) bind(c,name="fsync")
6301 use iso_c_binding, only: c_int
6302 integer(c_int), value :: fd
6303 integer(c_int) :: fsync
6307 ! Variable declaration
6311 open (10,file="foo")
6314 ! Perform I/O on unit 10
6319 ret = fsync(fnum(10))
6321 ! Handle possible error
6322 if (ret /= 0) stop "Error calling FSYNC"
6330 @section @code{FNUM} --- File number function
6332 @cindex file operation, file number
6335 @item @emph{Description}:
6336 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
6337 open Fortran I/O unit @code{UNIT}.
6339 @item @emph{Standard}:
6345 @item @emph{Syntax}:
6346 @code{RESULT = FNUM(UNIT)}
6348 @item @emph{Arguments}:
6349 @multitable @columnfractions .15 .70
6350 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
6353 @item @emph{Return value}:
6354 The return value is of type @code{INTEGER}
6356 @item @emph{Example}:
6360 open (unit=10, status = "scratch")
6364 end program test_fnum
6371 @section @code{FPUT} --- Write a single character in stream mode to stdout
6373 @cindex write character, stream mode
6374 @cindex stream mode, write character
6375 @cindex file operation, write character
6378 @item @emph{Description}:
6379 Write a single character in stream mode to stdout by bypassing normal
6380 formatted output. Stream I/O should not be mixed with normal record-oriented
6381 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
6383 This intrinsic is provided in both subroutine and function forms; however,
6384 only one form can be used in any given program unit.
6386 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
6387 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
6388 Programmers should consider the use of new stream IO feature in new code
6389 for future portability. See also @ref{Fortran 2003 status}.
6391 @item @emph{Standard}:
6395 Subroutine, function
6397 @item @emph{Syntax}:
6398 @multitable @columnfractions .80
6399 @item @code{CALL FPUT(C [, STATUS])}
6400 @item @code{STATUS = FPUT(C)}
6403 @item @emph{Arguments}:
6404 @multitable @columnfractions .15 .70
6405 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6407 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6408 Returns 0 on success, -1 on end-of-file and a system specific positive
6409 error code otherwise.
6412 @item @emph{Example}:
6415 CHARACTER(len=10) :: str = "gfortran"
6417 DO i = 1, len_trim(str)
6423 @item @emph{See also}:
6432 @section @code{FPUTC} --- Write a single character in stream mode
6434 @cindex write character, stream mode
6435 @cindex stream mode, write character
6436 @cindex file operation, write character
6439 @item @emph{Description}:
6440 Write a single character in stream mode by bypassing normal formatted
6441 output. Stream I/O should not be mixed with normal record-oriented
6442 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
6444 This intrinsic is provided in both subroutine and function forms; however,
6445 only one form can be used in any given program unit.
6447 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
6448 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
6449 Programmers should consider the use of new stream IO feature in new code
6450 for future portability. See also @ref{Fortran 2003 status}.
6452 @item @emph{Standard}:
6456 Subroutine, function
6458 @item @emph{Syntax}:
6459 @multitable @columnfractions .80
6460 @item @code{CALL FPUTC(UNIT, C [, STATUS])}
6461 @item @code{STATUS = FPUTC(UNIT, C)}
6464 @item @emph{Arguments}:
6465 @multitable @columnfractions .15 .70
6466 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
6467 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6469 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6470 Returns 0 on success, -1 on end-of-file and a system specific positive
6471 error code otherwise.
6474 @item @emph{Example}:
6477 CHARACTER(len=10) :: str = "gfortran"
6478 INTEGER :: fd = 42, i
6480 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
6481 DO i = 1, len_trim(str)
6482 CALL fputc(fd, str(i:i))
6488 @item @emph{See also}:
6497 @section @code{FRACTION} --- Fractional part of the model representation
6499 @cindex real number, fraction
6500 @cindex floating point, fraction
6503 @item @emph{Description}:
6504 @code{FRACTION(X)} returns the fractional part of the model
6505 representation of @code{X}.
6507 @item @emph{Standard}:
6508 Fortran 90 and later
6513 @item @emph{Syntax}:
6514 @code{Y = FRACTION(X)}
6516 @item @emph{Arguments}:
6517 @multitable @columnfractions .15 .70
6518 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
6521 @item @emph{Return value}:
6522 The return value is of the same type and kind as the argument.
6523 The fractional part of the model representation of @code{X} is returned;
6524 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
6526 @item @emph{Example}:
6528 program test_fraction
6531 print *, fraction(x), x * radix(x)**(-exponent(x))
6532 end program test_fraction
6540 @section @code{FREE} --- Frees memory
6542 @cindex pointer, cray
6545 @item @emph{Description}:
6546 Frees memory previously allocated by @code{MALLOC}. The @code{FREE}
6547 intrinsic is an extension intended to be used with Cray pointers, and is
6548 provided in GNU Fortran to allow user to compile legacy code. For
6549 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
6552 @item @emph{Standard}:
6558 @item @emph{Syntax}:
6559 @code{CALL FREE(PTR)}
6561 @item @emph{Arguments}:
6562 @multitable @columnfractions .15 .70
6563 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
6564 location of the memory that should be de-allocated.
6567 @item @emph{Return value}:
6570 @item @emph{Example}:
6571 See @code{MALLOC} for an example.
6573 @item @emph{See also}:
6580 @section @code{FSEEK} --- Low level file positioning subroutine
6582 @cindex file operation, seek
6583 @cindex file operation, position
6586 @item @emph{Description}:
6587 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
6588 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
6589 if set to 1, @var{OFFSET} is taken to be relative to the current position
6590 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
6591 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
6594 This intrinsic routine is not fully backwards compatible with @command{g77}.
6595 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
6596 @var{STATUS} variable. If FSEEK is used in old code, change
6598 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
6603 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
6604 IF (status /= 0) GOTO label
6607 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
6608 Programmers should consider the use of new stream IO feature in new code
6609 for future portability. See also @ref{Fortran 2003 status}.
6611 @item @emph{Standard}:
6617 @item @emph{Syntax}:
6618 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
6620 @item @emph{Arguments}:
6621 @multitable @columnfractions .15 .70
6622 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
6623 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
6624 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
6625 Its value shall be either 0, 1 or 2.
6626 @item @var{STATUS} @tab (Optional) shall be a scalar of type
6630 @item @emph{Example}:
6633 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
6634 INTEGER :: fd, offset, ierr
6640 OPEN(UNIT=fd, FILE="fseek.test")
6641 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
6642 print *, FTELL(fd), ierr
6644 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
6645 print *, FTELL(fd), ierr
6647 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
6648 print *, FTELL(fd), ierr
6654 @item @emph{See also}:
6661 @section @code{FSTAT} --- Get file status
6663 @cindex file system, file status
6666 @item @emph{Description}:
6667 @code{FSTAT} is identical to @ref{STAT}, except that information about an
6668 already opened file is obtained.
6670 The elements in @code{VALUES} are the same as described by @ref{STAT}.
6672 This intrinsic is provided in both subroutine and function forms; however,
6673 only one form can be used in any given program unit.
6675 @item @emph{Standard}:
6679 Subroutine, function
6681 @item @emph{Syntax}:
6682 @multitable @columnfractions .80
6683 @item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
6684 @item @code{STATUS = FSTAT(UNIT, VALUES)}
6687 @item @emph{Arguments}:
6688 @multitable @columnfractions .15 .70
6689 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
6690 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
6691 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
6692 on success and a system specific error code otherwise.
6695 @item @emph{Example}:
6696 See @ref{STAT} for an example.
6698 @item @emph{See also}:
6699 To stat a link: @gol
6701 To stat a file: @gol
6708 @section @code{FTELL} --- Current stream position
6710 @cindex file operation, position
6713 @item @emph{Description}:
6714 Retrieves the current position within an open file.
6716 This intrinsic is provided in both subroutine and function forms; however,
6717 only one form can be used in any given program unit.
6719 @item @emph{Standard}:
6723 Subroutine, function
6725 @item @emph{Syntax}:
6726 @multitable @columnfractions .80
6727 @item @code{CALL FTELL(UNIT, OFFSET)}
6728 @item @code{OFFSET = FTELL(UNIT)}
6731 @item @emph{Arguments}:
6732 @multitable @columnfractions .15 .70
6733 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
6734 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
6737 @item @emph{Return value}:
6738 In either syntax, @var{OFFSET} is set to the current offset of unit
6739 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
6741 @item @emph{Example}:
6745 OPEN(10, FILE="temp.dat")
6751 @item @emph{See also}:
6758 @section @code{GAMMA} --- Gamma function
6761 @cindex Gamma function
6762 @cindex Factorial function
6765 @item @emph{Description}:
6766 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
6767 integer values of @var{X} the Gamma function simplifies to the factorial
6768 function @math{\Gamma(x)=(x-1)!}.
6772 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
6776 @item @emph{Standard}:
6777 Fortran 2008 and later
6782 @item @emph{Syntax}:
6785 @item @emph{Arguments}:
6786 @multitable @columnfractions .15 .70
6787 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
6788 nor a negative integer.
6791 @item @emph{Return value}:
6792 The return value is of type @code{REAL} of the same kind as @var{X}.
6794 @item @emph{Example}:
6798 x = gamma(x) ! returns 1.0
6799 end program test_gamma
6802 @item @emph{Specific names}:
6803 @multitable @columnfractions .20 .20 .20 .25
6804 @item Name @tab Argument @tab Return type @tab Standard
6805 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
6808 @item @emph{See also}:
6809 Logarithm of the Gamma function: @gol
6816 @section @code{GERROR} --- Get last system error message
6818 @cindex system, error handling
6821 @item @emph{Description}:
6822 Returns the system error message corresponding to the last system error.
6823 This resembles the functionality of @code{strerror(3)} in C.
6825 @item @emph{Standard}:
6831 @item @emph{Syntax}:
6832 @code{CALL GERROR(RESULT)}
6834 @item @emph{Arguments}:
6835 @multitable @columnfractions .15 .70
6836 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
6839 @item @emph{Example}:
6842 CHARACTER(len=100) :: msg
6848 @item @emph{See also}:
6856 @section @code{GETARG} --- Get command line arguments
6858 @cindex command-line arguments
6859 @cindex arguments, to program
6862 @item @emph{Description}:
6863 Retrieve the @var{POS}-th argument that was passed on the
6864 command line when the containing program was invoked.
6866 This intrinsic routine is provided for backwards compatibility with
6867 GNU Fortran 77. In new code, programmers should consider the use of
6868 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
6871 @item @emph{Standard}:
6877 @item @emph{Syntax}:
6878 @code{CALL GETARG(POS, VALUE)}
6880 @item @emph{Arguments}:
6881 @multitable @columnfractions .15 .70
6882 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
6883 the default integer kind; @math{@var{POS} \geq 0}
6884 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
6886 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
6889 @item @emph{Return value}:
6890 After @code{GETARG} returns, the @var{VALUE} argument holds the
6891 @var{POS}th command line argument. If @var{VALUE} cannot hold the
6892 argument, it is truncated to fit the length of @var{VALUE}. If there are
6893 less than @var{POS} arguments specified at the command line, @var{VALUE}
6894 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
6895 to the name of the program (on systems that support this feature).
6897 @item @emph{Example}:
6901 CHARACTER(len=32) :: arg
6910 @item @emph{See also}:
6911 GNU Fortran 77 compatibility function: @gol
6913 Fortran 2003 functions and subroutines: @gol
6914 @ref{GET_COMMAND}, @gol
6915 @ref{GET_COMMAND_ARGUMENT}, @gol
6916 @ref{COMMAND_ARGUMENT_COUNT}
6922 @section @code{GET_COMMAND} --- Get the entire command line
6923 @fnindex GET_COMMAND
6924 @cindex command-line arguments
6925 @cindex arguments, to program
6928 @item @emph{Description}:
6929 Retrieve the entire command line that was used to invoke the program.
6931 @item @emph{Standard}:
6932 Fortran 2003 and later
6937 @item @emph{Syntax}:
6938 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
6940 @item @emph{Arguments}:
6941 @multitable @columnfractions .15 .70
6942 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
6944 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
6946 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
6950 @item @emph{Return value}:
6951 If @var{COMMAND} is present, stores the entire command line that was used
6952 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
6953 assigned the length of the command line. If @var{STATUS} is present, it
6954 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
6955 short to store the command line, or a positive value in case of an error.
6957 @item @emph{Example}:
6959 PROGRAM test_get_command
6960 CHARACTER(len=255) :: cmd
6961 CALL get_command(cmd)
6962 WRITE (*,*) TRIM(cmd)
6966 @item @emph{See also}:
6967 @ref{GET_COMMAND_ARGUMENT}, @gol
6968 @ref{COMMAND_ARGUMENT_COUNT}
6973 @node GET_COMMAND_ARGUMENT
6974 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
6975 @fnindex GET_COMMAND_ARGUMENT
6976 @cindex command-line arguments
6977 @cindex arguments, to program
6980 @item @emph{Description}:
6981 Retrieve the @var{NUMBER}-th argument that was passed on the
6982 command line when the containing program was invoked.
6984 @item @emph{Standard}:
6985 Fortran 2003 and later
6990 @item @emph{Syntax}:
6991 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
6993 @item @emph{Arguments}:
6994 @multitable @columnfractions .15 .70
6995 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
6996 default kind, @math{@var{NUMBER} \geq 0}
6997 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
6998 and of default kind.
6999 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
7000 and of default kind.
7001 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
7002 and of default kind.
7005 @item @emph{Return value}:
7006 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
7007 @var{NUMBER}-th command line argument. If @var{VALUE} cannot hold the argument, it is
7008 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
7009 arguments specified at the command line, @var{VALUE} will be filled with blanks.
7010 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
7011 systems that support this feature). The @var{LENGTH} argument contains the
7012 length of the @var{NUMBER}-th command line argument. If the argument retrieval
7013 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
7014 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
7017 @item @emph{Example}:
7019 PROGRAM test_get_command_argument
7021 CHARACTER(len=32) :: arg
7025 CALL get_command_argument(i, arg)
7026 IF (LEN_TRIM(arg) == 0) EXIT
7028 WRITE (*,*) TRIM(arg)
7034 @item @emph{See also}:
7035 @ref{GET_COMMAND}, @gol
7036 @ref{COMMAND_ARGUMENT_COUNT}
7042 @section @code{GETCWD} --- Get current working directory
7044 @cindex system, working directory
7047 @item @emph{Description}:
7048 Get current working directory.
7050 This intrinsic is provided in both subroutine and function forms; however,
7051 only one form can be used in any given program unit.
7053 @item @emph{Standard}:
7057 Subroutine, function
7059 @item @emph{Syntax}:
7060 @multitable @columnfractions .80
7061 @item @code{CALL GETCWD(C [, STATUS])}
7062 @item @code{STATUS = GETCWD(C)}
7065 @item @emph{Arguments}:
7066 @multitable @columnfractions .15 .70
7067 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
7068 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
7069 a system specific and nonzero error code otherwise.
7072 @item @emph{Example}:
7075 CHARACTER(len=255) :: cwd
7077 WRITE(*,*) TRIM(cwd)
7081 @item @emph{See also}:
7088 @section @code{GETENV} --- Get an environmental variable
7090 @cindex environment variable
7093 @item @emph{Description}:
7094 Get the @var{VALUE} of the environmental variable @var{NAME}.
7096 This intrinsic routine is provided for backwards compatibility with
7097 GNU Fortran 77. In new code, programmers should consider the use of
7098 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
7101 Note that @code{GETENV} need not be thread-safe. It is the
7102 responsibility of the user to ensure that the environment is not being
7103 updated concurrently with a call to the @code{GETENV} intrinsic.
7105 @item @emph{Standard}:
7111 @item @emph{Syntax}:
7112 @code{CALL GETENV(NAME, VALUE)}
7114 @item @emph{Arguments}:
7115 @multitable @columnfractions .15 .70
7116 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
7117 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
7120 @item @emph{Return value}:
7121 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
7122 not large enough to hold the data, it is truncated. If @var{NAME}
7123 is not set, @var{VALUE} will be filled with blanks.
7125 @item @emph{Example}:
7128 CHARACTER(len=255) :: homedir
7129 CALL getenv("HOME", homedir)
7130 WRITE (*,*) TRIM(homedir)
7134 @item @emph{See also}:
7135 @ref{GET_ENVIRONMENT_VARIABLE}
7140 @node GET_ENVIRONMENT_VARIABLE
7141 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
7142 @fnindex GET_ENVIRONMENT_VARIABLE
7143 @cindex environment variable
7146 @item @emph{Description}:
7147 Get the @var{VALUE} of the environmental variable @var{NAME}.
7149 Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It
7150 is the responsibility of the user to ensure that the environment is
7151 not being updated concurrently with a call to the
7152 @code{GET_ENVIRONMENT_VARIABLE} intrinsic.
7154 @item @emph{Standard}:
7155 Fortran 2003 and later
7160 @item @emph{Syntax}:
7161 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
7163 @item @emph{Arguments}:
7164 @multitable @columnfractions .15 .70
7165 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
7166 and of default kind.
7167 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
7168 and of default kind.
7169 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
7170 and of default kind.
7171 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
7172 and of default kind.
7173 @item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL}
7174 and of default kind.
7177 @item @emph{Return value}:
7178 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
7179 not large enough to hold the data, it is truncated. If @var{NAME}
7180 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
7181 contains the length needed for storing the environment variable @var{NAME}
7182 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
7183 but too short for the environment variable; it is 1 if the environment
7184 variable does not exist and 2 if the processor does not support environment
7185 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
7186 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
7187 are significant; otherwise they are not part of the environment variable
7190 @item @emph{Example}:
7193 CHARACTER(len=255) :: homedir
7194 CALL get_environment_variable("HOME", homedir)
7195 WRITE (*,*) TRIM(homedir)
7203 @section @code{GETGID} --- Group ID function
7205 @cindex system, group ID
7208 @item @emph{Description}:
7209 Returns the numerical group ID of the current process.
7211 @item @emph{Standard}:
7217 @item @emph{Syntax}:
7218 @code{RESULT = GETGID()}
7220 @item @emph{Return value}:
7221 The return value of @code{GETGID} is an @code{INTEGER} of the default
7225 @item @emph{Example}:
7226 See @code{GETPID} for an example.
7228 @item @emph{See also}:
7236 @section @code{GETLOG} --- Get login name
7238 @cindex system, login name
7242 @item @emph{Description}:
7243 Gets the username under which the program is running.
7245 @item @emph{Standard}:
7251 @item @emph{Syntax}:
7252 @code{CALL GETLOG(C)}
7254 @item @emph{Arguments}:
7255 @multitable @columnfractions .15 .70
7256 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
7259 @item @emph{Return value}:
7260 Stores the current user name in @var{LOGIN}. (On systems where POSIX
7261 functions @code{geteuid} and @code{getpwuid} are not available, and
7262 the @code{getlogin} function is not implemented either, this will
7263 return a blank string.)
7265 @item @emph{Example}:
7268 CHARACTER(32) :: login
7274 @item @emph{See also}:
7281 @section @code{GETPID} --- Process ID function
7283 @cindex system, process ID
7287 @item @emph{Description}:
7288 Returns the numerical process identifier of the current process.
7290 @item @emph{Standard}:
7296 @item @emph{Syntax}:
7297 @code{RESULT = GETPID()}
7299 @item @emph{Return value}:
7300 The return value of @code{GETPID} is an @code{INTEGER} of the default
7304 @item @emph{Example}:
7307 print *, "The current process ID is ", getpid()
7308 print *, "Your numerical user ID is ", getuid()
7309 print *, "Your numerical group ID is ", getgid()
7313 @item @emph{See also}:
7321 @section @code{GETUID} --- User ID function
7323 @cindex system, user ID
7327 @item @emph{Description}:
7328 Returns the numerical user ID of the current process.
7330 @item @emph{Standard}:
7336 @item @emph{Syntax}:
7337 @code{RESULT = GETUID()}
7339 @item @emph{Return value}:
7340 The return value of @code{GETUID} is an @code{INTEGER} of the default
7344 @item @emph{Example}:
7345 See @code{GETPID} for an example.
7347 @item @emph{See also}:
7355 @section @code{GMTIME} --- Convert time to GMT info
7357 @cindex time, conversion to GMT info
7360 @item @emph{Description}:
7361 Given a system time value @var{TIME} (as provided by the @ref{TIME}
7362 intrinsic), fills @var{VALUES} with values extracted from it appropriate
7363 to the UTC time zone (Universal Coordinated Time, also known in some
7364 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
7366 This intrinsic routine is provided for backwards compatibility with
7367 GNU Fortran 77. In new code, programmers should consider the use of
7368 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
7371 @item @emph{Standard}:
7377 @item @emph{Syntax}:
7378 @code{CALL GMTIME(TIME, VALUES)}
7380 @item @emph{Arguments}:
7381 @multitable @columnfractions .15 .70
7382 @item @var{TIME} @tab An @code{INTEGER} scalar expression
7383 corresponding to a system time, with @code{INTENT(IN)}.
7384 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
7385 with @code{INTENT(OUT)}.
7388 @item @emph{Return value}:
7389 The elements of @var{VALUES} are assigned as follows:
7391 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
7393 @item Minutes after the hour, range 0--59
7394 @item Hours past midnight, range 0--23
7395 @item Day of month, range 1--31
7396 @item Number of months since January, range 0--11
7397 @item Years since 1900
7398 @item Number of days since Sunday, range 0--6
7399 @item Days since January 1, range 0--365
7400 @item Daylight savings indicator: positive if daylight savings is in
7401 effect, zero if not, and negative if the information is not available.
7404 @item @emph{See also}:
7405 @ref{DATE_AND_TIME}, @gol
7415 @section @code{HOSTNM} --- Get system host name
7417 @cindex system, host name
7420 @item @emph{Description}:
7421 Retrieves the host name of the system on which the program is running.
7423 This intrinsic is provided in both subroutine and function forms; however,
7424 only one form can be used in any given program unit.
7426 @item @emph{Standard}:
7430 Subroutine, function
7432 @item @emph{Syntax}:
7433 @multitable @columnfractions .80
7434 @item @code{CALL HOSTNM(C [, STATUS])}
7435 @item @code{STATUS = HOSTNM(NAME)}
7438 @item @emph{Arguments}:
7439 @multitable @columnfractions .15 .70
7440 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
7441 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
7442 Returns 0 on success, or a system specific error code otherwise.
7445 @item @emph{Return value}:
7446 In either syntax, @var{NAME} is set to the current hostname if it can
7447 be obtained, or to a blank string otherwise.
7454 @section @code{HUGE} --- Largest number of a kind
7456 @cindex limits, largest number
7457 @cindex model representation, largest number
7460 @item @emph{Description}:
7461 @code{HUGE(X)} returns the largest number that is not an infinity in
7462 the model of the type of @code{X}.
7464 @item @emph{Standard}:
7465 Fortran 90 and later
7470 @item @emph{Syntax}:
7471 @code{RESULT = HUGE(X)}
7473 @item @emph{Arguments}:
7474 @multitable @columnfractions .15 .70
7475 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
7478 @item @emph{Return value}:
7479 The return value is of the same type and kind as @var{X}
7481 @item @emph{Example}:
7483 program test_huge_tiny
7484 print *, huge(0), huge(0.0), huge(0.0d0)
7485 print *, tiny(0.0), tiny(0.0d0)
7486 end program test_huge_tiny
7493 @section @code{HYPOT} --- Euclidean distance function
7495 @cindex Euclidean distance
7498 @item @emph{Description}:
7499 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
7500 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
7502 @item @emph{Standard}:
7503 Fortran 2008 and later
7508 @item @emph{Syntax}:
7509 @code{RESULT = HYPOT(X, Y)}
7511 @item @emph{Arguments}:
7512 @multitable @columnfractions .15 .70
7513 @item @var{X} @tab The type shall be @code{REAL}.
7514 @item @var{Y} @tab The type and kind type parameter shall be the same as
7518 @item @emph{Return value}:
7519 The return value has the same type and kind type parameter as @var{X}.
7521 @item @emph{Example}:
7524 real(4) :: x = 1.e0_4, y = 0.5e0_4
7526 end program test_hypot
7533 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
7535 @cindex @acronym{ASCII} collating sequence
7536 @cindex collating sequence, @acronym{ASCII}
7537 @cindex conversion, to integer
7540 @item @emph{Description}:
7541 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
7542 in the first character position of @code{C}.
7544 @item @emph{Standard}:
7545 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7550 @item @emph{Syntax}:
7551 @code{RESULT = IACHAR(C [, KIND])}
7553 @item @emph{Arguments}:
7554 @multitable @columnfractions .15 .70
7555 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
7556 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7557 expression indicating the kind parameter of the result.
7560 @item @emph{Return value}:
7561 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7562 @var{KIND} is absent, the return value is of default integer kind.
7564 @item @emph{Example}:
7569 end program test_iachar
7573 See @ref{ICHAR} for a discussion of converting between numerical values
7574 and formatted string representations.
7576 @item @emph{See also}:
7585 @section @code{IALL} --- Bitwise AND of array elements
7588 @cindex bits, AND of array elements
7591 @item @emph{Description}:
7592 Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
7593 if the corresponding element in @var{MASK} is @code{TRUE}.
7595 @item @emph{Standard}:
7596 Fortran 2008 and later
7599 Transformational function
7601 @item @emph{Syntax}:
7602 @multitable @columnfractions .80
7603 @item @code{RESULT = IALL(ARRAY[, MASK])}
7604 @item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
7607 @item @emph{Arguments}:
7608 @multitable @columnfractions .15 .70
7609 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7610 @item @var{DIM} @tab (Optional) shall be a scalar of type
7611 @code{INTEGER} with a value in the range from 1 to n, where n
7612 equals the rank of @var{ARRAY}.
7613 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
7614 and either be a scalar or an array of the same shape as @var{ARRAY}.
7617 @item @emph{Return value}:
7618 The result is of the same type as @var{ARRAY}.
7620 If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
7621 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7622 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7623 dimension @var{DIM} dropped is returned.
7625 @item @emph{Example}:
7634 PRINT '(b8.8)', IALL(a)
7638 @item @emph{See also}:
7647 @section @code{IAND} --- Bitwise logical and
7653 @cindex bitwise logical and
7654 @cindex logical and, bitwise
7657 @item @emph{Description}:
7658 Bitwise logical @code{AND}.
7660 @item @emph{Standard}:
7661 Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions
7666 @item @emph{Syntax}:
7667 @code{RESULT = IAND(I, J)}
7669 @item @emph{Arguments}:
7670 @multitable @columnfractions .15 .70
7671 @item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant.
7672 @item @var{J} @tab The type shall be @code{INTEGER} with the same
7673 kind type parameter as @var{I} or a boz-literal-constant.
7674 @var{I} and @var{J} shall not both be boz-literal-constants.
7677 @item @emph{Return value}:
7678 The return type is @code{INTEGER} with the kind type parameter of the
7680 A boz-literal-constant is converted to an @code{INTEGER} with the kind
7681 type parameter of the other argument as-if a call to @ref{INT} occurred.
7683 @item @emph{Example}:
7687 DATA a / Z'F' /, b / Z'3' /
7688 WRITE (*,*) IAND(a, b)
7692 @item @emph{Specific names}:
7693 @multitable @columnfractions .20 .20 .20 .25
7694 @item Name @tab Argument @tab Return type @tab Standard
7695 @item @code{IAND(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
7696 @item @code{BIAND(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7697 @item @code{IIAND(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7698 @item @code{JIAND(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7699 @item @code{KIAND(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7702 @item @emph{See also}:
7714 @section @code{IANY} --- Bitwise OR of array elements
7717 @cindex bits, OR of array elements
7720 @item @emph{Description}:
7721 Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
7722 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
7724 @item @emph{Standard}:
7725 Fortran 2008 and later
7728 Transformational function
7730 @item @emph{Syntax}:
7731 @multitable @columnfractions .80
7732 @item @code{RESULT = IANY(ARRAY[, MASK])}
7733 @item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
7736 @item @emph{Arguments}:
7737 @multitable @columnfractions .15 .70
7738 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7739 @item @var{DIM} @tab (Optional) shall be a scalar of type
7740 @code{INTEGER} with a value in the range from 1 to n, where n
7741 equals the rank of @var{ARRAY}.
7742 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
7743 and either be a scalar or an array of the same shape as @var{ARRAY}.
7746 @item @emph{Return value}:
7747 The result is of the same type as @var{ARRAY}.
7749 If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
7750 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7751 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7752 dimension @var{DIM} dropped is returned.
7754 @item @emph{Example}:
7763 PRINT '(b8.8)', IANY(a)
7767 @item @emph{See also}:
7776 @section @code{IARGC} --- Get the number of command line arguments
7778 @cindex command-line arguments
7779 @cindex command-line arguments, number of
7780 @cindex arguments, to program
7783 @item @emph{Description}:
7784 @code{IARGC} returns the number of arguments passed on the
7785 command line when the containing program was invoked.
7787 This intrinsic routine is provided for backwards compatibility with
7788 GNU Fortran 77. In new code, programmers should consider the use of
7789 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
7792 @item @emph{Standard}:
7798 @item @emph{Syntax}:
7799 @code{RESULT = IARGC()}
7801 @item @emph{Arguments}:
7804 @item @emph{Return value}:
7805 The number of command line arguments, type @code{INTEGER(4)}.
7807 @item @emph{Example}:
7810 @item @emph{See also}:
7811 GNU Fortran 77 compatibility subroutine: @gol
7813 Fortran 2003 functions and subroutines: @gol
7814 @ref{GET_COMMAND}, @gol
7815 @ref{GET_COMMAND_ARGUMENT}, @gol
7816 @ref{COMMAND_ARGUMENT_COUNT}
7822 @section @code{IBCLR} --- Clear bit
7832 @item @emph{Description}:
7833 @code{IBCLR} returns the value of @var{I} with the bit at position
7834 @var{POS} set to zero.
7836 @item @emph{Standard}:
7837 Fortran 90 and later, has overloads that are GNU extensions
7842 @item @emph{Syntax}:
7843 @code{RESULT = IBCLR(I, POS)}
7845 @item @emph{Arguments}:
7846 @multitable @columnfractions .15 .70
7847 @item @var{I} @tab The type shall be @code{INTEGER}.
7848 @item @var{POS} @tab The type shall be @code{INTEGER}.
7851 @item @emph{Return value}:
7852 The return value is of type @code{INTEGER} and of the same kind as
7855 @item @emph{Specific names}:
7856 @multitable @columnfractions .20 .20 .20 .25
7857 @item Name @tab Argument @tab Return type @tab Standard
7858 @item @code{IBCLR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
7859 @item @code{BBCLR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7860 @item @code{IIBCLR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7861 @item @code{JIBCLR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7862 @item @code{KIBCLR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7865 @item @emph{See also}:
7877 @section @code{IBITS} --- Bit extraction
7884 @cindex bits, extract
7887 @item @emph{Description}:
7888 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
7889 starting from bit position @var{POS} and extending left for @var{LEN}
7890 bits. The result is right-justified and the remaining bits are
7891 zeroed. The value of @code{POS+LEN} must be less than or equal to the
7892 value @code{BIT_SIZE(I)}.
7894 @item @emph{Standard}:
7895 Fortran 90 and later, has overloads that are GNU extensions
7900 @item @emph{Syntax}:
7901 @code{RESULT = IBITS(I, POS, LEN)}
7903 @item @emph{Arguments}:
7904 @multitable @columnfractions .15 .70
7905 @item @var{I} @tab The type shall be @code{INTEGER}.
7906 @item @var{POS} @tab The type shall be @code{INTEGER}.
7907 @item @var{LEN} @tab The type shall be @code{INTEGER}.
7910 @item @emph{Return value}:
7911 The return value is of type @code{INTEGER} and of the same kind as
7914 @item @emph{Specific names}:
7915 @multitable @columnfractions .20 .20 .20 .25
7916 @item Name @tab Argument @tab Return type @tab Standard
7917 @item @code{IBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
7918 @item @code{BBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7919 @item @code{IIBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7920 @item @code{JIBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7921 @item @code{KIBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7924 @item @emph{See also}:
7925 @ref{BIT_SIZE}, @gol
7936 @section @code{IBSET} --- Set bit
7945 @item @emph{Description}:
7946 @code{IBSET} returns the value of @var{I} with the bit at position
7947 @var{POS} set to one.
7949 @item @emph{Standard}:
7950 Fortran 90 and later, has overloads that are GNU extensions
7955 @item @emph{Syntax}:
7956 @code{RESULT = IBSET(I, POS)}
7958 @item @emph{Arguments}:
7959 @multitable @columnfractions .15 .70
7960 @item @var{I} @tab The type shall be @code{INTEGER}.
7961 @item @var{POS} @tab The type shall be @code{INTEGER}.
7964 @item @emph{Return value}:
7965 The return value is of type @code{INTEGER} and of the same kind as
7968 @item @emph{Specific names}:
7969 @multitable @columnfractions .20 .20 .20 .25
7970 @item Name @tab Argument @tab Return type @tab Standard
7971 @item @code{IBSET(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
7972 @item @code{BBSET(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7973 @item @code{IIBSET(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7974 @item @code{JIBSET(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7975 @item @code{KIBSET(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7978 @item @emph{See also}:
7990 @section @code{ICHAR} --- Character-to-integer conversion function
7992 @cindex conversion, to integer
7995 @item @emph{Description}:
7996 @code{ICHAR(C)} returns the code for the character in the first character
7997 position of @code{C} in the system's native character set.
7998 The correspondence between characters and their codes is not necessarily
7999 the same across different GNU Fortran implementations.
8001 @item @emph{Standard}:
8002 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
8007 @item @emph{Syntax}:
8008 @code{RESULT = ICHAR(C [, KIND])}
8010 @item @emph{Arguments}:
8011 @multitable @columnfractions .15 .70
8012 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
8013 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8014 expression indicating the kind parameter of the result.
8017 @item @emph{Return value}:
8018 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8019 @var{KIND} is absent, the return value is of default integer kind.
8021 @item @emph{Example}:
8026 end program test_ichar
8029 @item @emph{Specific names}:
8030 @multitable @columnfractions .20 .20 .20 .25
8031 @item Name @tab Argument @tab Return type @tab Standard
8032 @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8036 No intrinsic exists to convert between a numeric value and a formatted
8037 character string representation -- for instance, given the
8038 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
8039 @code{REAL} value with the value 154, or vice versa. Instead, this
8040 functionality is provided by internal-file I/O, as in the following
8045 character(len=10) string, string2
8048 ! Convert a string to a numeric value
8049 read (string,'(I10)') value
8052 ! Convert a value to a formatted string
8053 write (string2,'(I10)') value
8055 end program read_val
8058 @item @emph{See also}:
8067 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
8069 @cindex date, current
8070 @cindex current date
8073 @item @emph{Description}:
8074 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
8075 current local time. The day (in the range 1-31), month (in the range 1-12),
8076 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
8077 The year has four significant digits.
8079 This intrinsic routine is provided for backwards compatibility with
8080 GNU Fortran 77. In new code, programmers should consider the use of
8081 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
8084 @item @emph{Standard}:
8090 @item @emph{Syntax}:
8091 @code{CALL IDATE(VALUES)}
8093 @item @emph{Arguments}:
8094 @multitable @columnfractions .15 .70
8095 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
8096 the kind shall be the default integer kind.
8099 @item @emph{Return value}:
8100 Does not return anything.
8102 @item @emph{Example}:
8105 integer, dimension(3) :: tarray
8110 end program test_idate
8113 @item @emph{See also}:
8119 @section @code{IEOR} --- Bitwise logical exclusive or
8125 @cindex bitwise logical exclusive or
8126 @cindex logical exclusive or, bitwise
8129 @item @emph{Description}:
8130 @code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
8133 @item @emph{Standard}:
8134 Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions
8139 @item @emph{Syntax}:
8140 @code{RESULT = IEOR(I, J)}
8142 @item @emph{Arguments}:
8143 @multitable @columnfractions .15 .70
8144 @item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant.
8145 @item @var{J} @tab The type shall be @code{INTEGER} with the same
8146 kind type parameter as @var{I} or a boz-literal-constant.
8147 @var{I} and @var{J} shall not both be boz-literal-constants.
8150 @item @emph{Return value}:
8151 The return type is @code{INTEGER} with the kind type parameter of the
8153 A boz-literal-constant is converted to an @code{INTEGER} with the kind
8154 type parameter of the other argument as-if a call to @ref{INT} occurred.
8156 @item @emph{Specific names}:
8157 @multitable @columnfractions .20 .20 .20 .25
8158 @item Name @tab Argument @tab Return type @tab Standard
8159 @item @code{IEOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
8160 @item @code{BIEOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8161 @item @code{IIEOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8162 @item @code{JIEOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8163 @item @code{KIEOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8166 @item @emph{See also}:
8178 @section @code{IERRNO} --- Get the last system error number
8180 @cindex system, error handling
8183 @item @emph{Description}:
8184 Returns the last system error number, as given by the C @code{errno}
8187 @item @emph{Standard}:
8193 @item @emph{Syntax}:
8194 @code{RESULT = IERRNO()}
8196 @item @emph{Arguments}:
8199 @item @emph{Return value}:
8200 The return value is of type @code{INTEGER} and of the default integer
8203 @item @emph{See also}:
8210 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
8211 @fnindex IMAGE_INDEX
8212 @cindex coarray, @code{IMAGE_INDEX}
8213 @cindex images, cosubscript to image index conversion
8216 @item @emph{Description}:
8217 Returns the image index belonging to a cosubscript.
8219 @item @emph{Standard}:
8220 Fortran 2008 and later
8225 @item @emph{Syntax}:
8226 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
8228 @item @emph{Arguments}:
8229 @multitable @columnfractions .15 .70
8230 @item @var{COARRAY} @tab Coarray of any type.
8231 @item @var{SUB} @tab default integer rank-1 array of a size equal to
8232 the corank of @var{COARRAY}.
8236 @item @emph{Return value}:
8237 Scalar default integer with the value of the image index which corresponds
8238 to the cosubscripts. For invalid cosubscripts the result is zero.
8240 @item @emph{Example}:
8242 INTEGER :: array[2,-1:4,8,*]
8243 ! Writes 28 (or 0 if there are fewer than 28 images)
8244 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
8247 @item @emph{See also}:
8248 @ref{THIS_IMAGE}, @gol
8254 @node INDEX intrinsic
8255 @section @code{INDEX} --- Position of a substring within a string
8257 @cindex substring position
8258 @cindex string, find substring
8261 @item @emph{Description}:
8262 Returns the position of the start of the first occurrence of string
8263 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
8264 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
8265 the @var{BACK} argument is present and true, the return value is the
8266 start of the last occurrence rather than the first.
8268 @item @emph{Standard}:
8269 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
8274 @item @emph{Syntax}:
8275 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
8277 @item @emph{Arguments}:
8278 @multitable @columnfractions .15 .70
8279 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
8281 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
8283 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
8285 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8286 expression indicating the kind parameter of the result.
8289 @item @emph{Return value}:
8290 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8291 @var{KIND} is absent, the return value is of default integer kind.
8293 @item @emph{Specific names}:
8294 @multitable @columnfractions .20 .20 .20 .25
8295 @item Name @tab Argument @tab Return type @tab Standard
8296 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8299 @item @emph{See also}:
8307 @section @code{INT} --- Convert to integer type
8311 @cindex conversion, to integer
8314 @item @emph{Description}:
8315 Convert to integer type
8317 @item @emph{Standard}:
8318 Fortran 77 and later, with boz-literal-constant Fortran 2008 and later.
8323 @item @emph{Syntax}:
8324 @code{RESULT = INT(A [, KIND))}
8326 @item @emph{Arguments}:
8327 @multitable @columnfractions .15 .70
8328 @item @var{A} @tab Shall be of type @code{INTEGER},
8329 @code{REAL}, or @code{COMPLEX} or a boz-literal-constant.
8330 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8331 expression indicating the kind parameter of the result.
8334 @item @emph{Return value}:
8335 These functions return a @code{INTEGER} variable or array under
8336 the following rules:
8340 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
8342 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)}
8343 equals @code{0}. If @math{|A| \geq 1}, then @code{INT(A)} is the integer
8344 whose magnitude is the largest integer that does not exceed the magnitude
8345 of @var{A} and whose sign is the same as the sign of @var{A}.
8347 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
8350 @item @emph{Example}:
8354 complex :: z = (-3.7, 1.0)
8356 print *, int(z), int(z,8)
8360 @item @emph{Specific names}:
8361 @multitable @columnfractions .20 .20 .20 .25
8362 @item Name @tab Argument @tab Return type @tab Standard
8363 @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
8364 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
8365 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
8372 @section @code{INT2} --- Convert to 16-bit integer type
8375 @cindex conversion, to integer
8378 @item @emph{Description}:
8379 Convert to a @code{KIND=2} integer type. This is equivalent to the
8380 standard @code{INT} intrinsic with an optional argument of
8381 @code{KIND=2}, and is only included for backwards compatibility.
8383 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
8385 @item @emph{Standard}:
8391 @item @emph{Syntax}:
8392 @code{RESULT = INT2(A)}
8394 @item @emph{Arguments}:
8395 @multitable @columnfractions .15 .70
8396 @item @var{A} @tab Shall be of type @code{INTEGER},
8397 @code{REAL}, or @code{COMPLEX}.
8400 @item @emph{Return value}:
8401 The return value is a @code{INTEGER(2)} variable.
8403 @item @emph{See also}:
8412 @section @code{INT8} --- Convert to 64-bit integer type
8414 @cindex conversion, to integer
8417 @item @emph{Description}:
8418 Convert to a @code{KIND=8} integer type. This is equivalent to the
8419 standard @code{INT} intrinsic with an optional argument of
8420 @code{KIND=8}, and is only included for backwards compatibility.
8422 @item @emph{Standard}:
8428 @item @emph{Syntax}:
8429 @code{RESULT = INT8(A)}
8431 @item @emph{Arguments}:
8432 @multitable @columnfractions .15 .70
8433 @item @var{A} @tab Shall be of type @code{INTEGER},
8434 @code{REAL}, or @code{COMPLEX}.
8437 @item @emph{Return value}:
8438 The return value is a @code{INTEGER(8)} variable.
8440 @item @emph{See also}:
8449 @section @code{IOR} --- Bitwise logical or
8455 @cindex bitwise logical or
8456 @cindex logical or, bitwise
8459 @item @emph{Description}:
8460 @code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
8463 @item @emph{Standard}:
8464 Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions
8469 @item @emph{Syntax}:
8470 @code{RESULT = IOR(I, J)}
8472 @item @emph{Arguments}:
8473 @multitable @columnfractions .15 .70
8474 @item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant.
8475 @item @var{J} @tab The type shall be @code{INTEGER} with the same
8476 kind type parameter as @var{I} or a boz-literal-constant.
8477 @var{I} and @var{J} shall not both be boz-literal-constants.
8480 @item @emph{Return value}:
8481 The return type is @code{INTEGER} with the kind type parameter of the
8483 A boz-literal-constant is converted to an @code{INTEGER} with the kind
8484 type parameter of the other argument as-if a call to @ref{INT} occurred.
8486 @item @emph{Specific names}:
8487 @multitable @columnfractions .20 .20 .20 .25
8488 @item Name @tab Argument @tab Return type @tab Standard
8489 @item @code{IOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
8490 @item @code{BIOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8491 @item @code{IIOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8492 @item @code{JIOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8493 @item @code{KIOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8496 @item @emph{See also}:
8508 @section @code{IPARITY} --- Bitwise XOR of array elements
8510 @cindex array, parity
8512 @cindex bits, XOR of array elements
8515 @item @emph{Description}:
8516 Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
8517 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
8519 @item @emph{Standard}:
8520 Fortran 2008 and later
8523 Transformational function
8525 @item @emph{Syntax}:
8526 @multitable @columnfractions .80
8527 @item @code{RESULT = IPARITY(ARRAY[, MASK])}
8528 @item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
8531 @item @emph{Arguments}:
8532 @multitable @columnfractions .15 .70
8533 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
8534 @item @var{DIM} @tab (Optional) shall be a scalar of type
8535 @code{INTEGER} with a value in the range from 1 to n, where n
8536 equals the rank of @var{ARRAY}.
8537 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
8538 and either be a scalar or an array of the same shape as @var{ARRAY}.
8541 @item @emph{Return value}:
8542 The result is of the same type as @var{ARRAY}.
8544 If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
8545 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
8546 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
8547 dimension @var{DIM} dropped is returned.
8549 @item @emph{Example}:
8551 PROGRAM test_iparity
8554 a(1) = int(b'00100100', 1)
8555 a(2) = int(b'01101010', 1)
8558 PRINT '(b8.8)', IPARITY(a)
8562 @item @emph{See also}:
8572 @section @code{IRAND} --- Integer pseudo-random number
8574 @cindex random number generation
8577 @item @emph{Description}:
8578 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
8579 distribution between 0 and a system-dependent limit (which is in most
8580 cases 2147483647). If @var{FLAG} is 0, the next number
8581 in the current sequence is returned; if @var{FLAG} is 1, the generator
8582 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
8583 it is used as a new seed with @code{SRAND}.
8585 This intrinsic routine is provided for backwards compatibility with
8586 GNU Fortran 77. It implements a simple modulo generator as provided
8587 by @command{g77}. For new code, one should consider the use of
8588 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
8590 @item @emph{Standard}:
8596 @item @emph{Syntax}:
8597 @code{RESULT = IRAND(I)}
8599 @item @emph{Arguments}:
8600 @multitable @columnfractions .15 .70
8601 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
8604 @item @emph{Return value}:
8605 The return value is of @code{INTEGER(kind=4)} type.
8607 @item @emph{Example}:
8610 integer,parameter :: seed = 86456
8613 print *, irand(), irand(), irand(), irand()
8614 print *, irand(seed), irand(), irand(), irand()
8615 end program test_irand
8623 @section @code{IS_CONTIGUOUS} --- Test whether an array is contiguous
8624 @fnindex IS_IOSTAT_EOR
8625 @cindex array, contiguity
8628 @item @emph{Description}:
8629 @code{IS_CONTIGUOUS} tests whether an array is contiguous.
8631 @item @emph{Standard}:
8632 Fortran 2008 and later
8637 @item @emph{Syntax}:
8638 @code{RESULT = IS_CONTIGUOUS(ARRAY)}
8640 @item @emph{Arguments}:
8641 @multitable @columnfractions .15 .70
8642 @item @var{ARRAY} @tab Shall be an array of any type.
8645 @item @emph{Return value}:
8646 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
8647 @var{ARRAY} is contiguous and false otherwise.
8649 @item @emph{Example}:
8653 a = [1,2,3,4,5,6,7,8,9,10]
8654 call sub (a) ! every element, is contiguous
8655 call sub (a(::2)) ! every other element, is noncontiguous
8659 if (is_contiguous (x)) then
8660 write (*,*) 'X is contiguous'
8662 write (*,*) 'X is not contiguous'
8672 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
8673 @fnindex IS_IOSTAT_END
8674 @cindex @code{IOSTAT}, end of file
8677 @item @emph{Description}:
8678 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
8679 status ``end of file''. The function is equivalent to comparing the variable
8680 with the @code{IOSTAT_END} parameter of the intrinsic module
8681 @code{ISO_FORTRAN_ENV}.
8683 @item @emph{Standard}:
8684 Fortran 2003 and later
8689 @item @emph{Syntax}:
8690 @code{RESULT = IS_IOSTAT_END(I)}
8692 @item @emph{Arguments}:
8693 @multitable @columnfractions .15 .70
8694 @item @var{I} @tab Shall be of the type @code{INTEGER}.
8697 @item @emph{Return value}:
8698 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
8699 @var{I} has the value which indicates an end of file condition for
8700 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
8702 @item @emph{Example}:
8707 OPEN(88, FILE='test.dat')
8708 READ(88, *, IOSTAT=stat) i
8709 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
8717 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
8718 @fnindex IS_IOSTAT_EOR
8719 @cindex @code{IOSTAT}, end of record
8722 @item @emph{Description}:
8723 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
8724 status ``end of record''. The function is equivalent to comparing the
8725 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
8726 @code{ISO_FORTRAN_ENV}.
8728 @item @emph{Standard}:
8729 Fortran 2003 and later
8734 @item @emph{Syntax}:
8735 @code{RESULT = IS_IOSTAT_EOR(I)}
8737 @item @emph{Arguments}:
8738 @multitable @columnfractions .15 .70
8739 @item @var{I} @tab Shall be of the type @code{INTEGER}.
8742 @item @emph{Return value}:
8743 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
8744 @var{I} has the value which indicates an end of file condition for
8745 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
8747 @item @emph{Example}:
8751 INTEGER :: stat, i(50)
8752 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
8753 READ(88, IOSTAT=stat) i
8754 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
8761 @section @code{ISATTY} --- Whether a unit is a terminal device.
8763 @cindex system, terminal
8766 @item @emph{Description}:
8767 Determine whether a unit is connected to a terminal device.
8769 @item @emph{Standard}:
8775 @item @emph{Syntax}:
8776 @code{RESULT = ISATTY(UNIT)}
8778 @item @emph{Arguments}:
8779 @multitable @columnfractions .15 .70
8780 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
8783 @item @emph{Return value}:
8784 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
8785 device, @code{.FALSE.} otherwise.
8787 @item @emph{Example}:
8790 INTEGER(kind=1) :: unit
8792 write(*,*) isatty(unit=unit)
8796 @item @emph{See also}:
8803 @section @code{ISHFT} --- Shift bits
8812 @item @emph{Description}:
8813 @code{ISHFT} returns a value corresponding to @var{I} with all of the
8814 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
8815 zero corresponds to a left shift, a value of zero corresponds to no
8816 shift, and a value less than zero corresponds to a right shift. If the
8817 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
8818 value is undefined. Bits shifted out from the left end or right end are
8819 lost; zeros are shifted in from the opposite end.
8821 @item @emph{Standard}:
8822 Fortran 90 and later, has overloads that are GNU extensions
8827 @item @emph{Syntax}:
8828 @code{RESULT = ISHFT(I, SHIFT)}
8830 @item @emph{Arguments}:
8831 @multitable @columnfractions .15 .70
8832 @item @var{I} @tab The type shall be @code{INTEGER}.
8833 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8836 @item @emph{Return value}:
8837 The return value is of type @code{INTEGER} and of the same kind as
8840 @item @emph{Specific names}:
8841 @multitable @columnfractions .20 .20 .20 .25
8842 @item Name @tab Argument @tab Return type @tab Standard
8843 @item @code{ISHFT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
8844 @item @code{BSHFT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8845 @item @code{IISHFT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8846 @item @code{JISHFT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8847 @item @code{KISHFT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8850 @item @emph{See also}:
8857 @section @code{ISHFTC} --- Shift bits circularly
8863 @cindex bits, shift circular
8866 @item @emph{Description}:
8867 @code{ISHFTC} returns a value corresponding to @var{I} with the
8868 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
8869 is, bits shifted out one end are shifted into the opposite end. A value
8870 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
8871 zero corresponds to no shift, and a value less than zero corresponds to
8872 a right shift. The absolute value of @var{SHIFT} must be less than
8873 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
8874 equivalent to @code{BIT_SIZE(I)}.
8876 @item @emph{Standard}:
8877 Fortran 90 and later, has overloads that are GNU extensions
8882 @item @emph{Syntax}:
8883 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
8885 @item @emph{Arguments}:
8886 @multitable @columnfractions .15 .70
8887 @item @var{I} @tab The type shall be @code{INTEGER}.
8888 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8889 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
8890 the value must be greater than zero and less than or equal to
8894 @item @emph{Return value}:
8895 The return value is of type @code{INTEGER} and of the same kind as
8898 @item @emph{Specific names}:
8899 @multitable @columnfractions .20 .20 .20 .25
8900 @item Name @tab Argument @tab Return type @tab Standard
8901 @item @code{ISHFTC(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
8902 @item @code{BSHFTC(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8903 @item @code{IISHFTC(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8904 @item @code{JISHFTC(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8905 @item @code{KISHFTC(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8908 @item @emph{See also}:
8915 @section @code{ISNAN} --- Test for a NaN
8920 @item @emph{Description}:
8921 @code{ISNAN} tests whether a floating-point value is an IEEE
8923 @item @emph{Standard}:
8929 @item @emph{Syntax}:
8932 @item @emph{Arguments}:
8933 @multitable @columnfractions .15 .70
8934 @item @var{X} @tab Variable of the type @code{REAL}.
8938 @item @emph{Return value}:
8939 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
8940 if @var{X} is a NaN and @code{FALSE} otherwise.
8942 @item @emph{Example}:
8949 if (isnan(x)) stop '"x" is a NaN'
8950 end program test_nan
8957 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
8959 @cindex time, current
8960 @cindex current time
8963 @item @emph{Description}:
8964 @code{ITIME(VALUES)} Fills @var{VALUES} with the numerical values at the
8965 current local time. The hour (in the range 1-24), minute (in the range 1-60),
8966 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
8969 This intrinsic routine is provided for backwards compatibility with
8970 GNU Fortran 77. In new code, programmers should consider the use of
8971 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
8974 @item @emph{Standard}:
8980 @item @emph{Syntax}:
8981 @code{CALL ITIME(VALUES)}
8983 @item @emph{Arguments}:
8984 @multitable @columnfractions .15 .70
8985 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
8986 and the kind shall be the default integer kind.
8989 @item @emph{Return value}:
8990 Does not return anything.
8993 @item @emph{Example}:
8996 integer, dimension(3) :: tarray
9001 end program test_itime
9004 @item @emph{See also}:
9011 @section @code{KILL} --- Send a signal to a process
9015 @item @emph{Description}:
9016 Sends the signal specified by @var{SIG} to the process @var{PID}.
9019 This intrinsic is provided in both subroutine and function forms;
9020 however, only one form can be used in any given program unit.
9021 @item @emph{Standard}:
9024 @item @emph{Standard}:
9028 Subroutine, function
9030 @item @emph{Syntax}:
9031 @multitable @columnfractions .80
9032 @item @code{CALL KILL(PID, SIG [, STATUS])}
9033 @item @code{STATUS = KILL(PID, SIG)}
9036 @item @emph{Arguments}:
9037 @multitable @columnfractions .15 .70
9038 @item @var{PID} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}.
9039 @item @var{SIG} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}.
9040 @item @var{STATUS} @tab [Subroutine](Optional)
9041 Shall be a scalar @code{INTEGER}.
9042 Returns 0 on success; otherwise a system-specific error code is returned.
9043 @item @var{STATUS} @tab [Function] The kind type parameter is that of
9045 Returns 0 on success; otherwise a system-specific error code is returned.
9048 @item @emph{See also}:
9055 @section @code{KIND} --- Kind of an entity
9060 @item @emph{Description}:
9061 @code{KIND(X)} returns the kind value of the entity @var{X}.
9063 @item @emph{Standard}:
9064 Fortran 95 and later
9069 @item @emph{Syntax}:
9072 @item @emph{Arguments}:
9073 @multitable @columnfractions .15 .70
9074 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
9075 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}. It may be scalar or
9079 @item @emph{Return value}:
9080 The return value is a scalar of type @code{INTEGER} and of the default
9083 @item @emph{Example}:
9086 integer,parameter :: kc = kind(' ')
9087 integer,parameter :: kl = kind(.true.)
9089 print *, "The default character kind is ", kc
9090 print *, "The default logical kind is ", kl
9091 end program test_kind
9099 @section @code{LBOUND} --- Lower dimension bounds of an array
9101 @cindex array, lower bound
9104 @item @emph{Description}:
9105 Returns the lower bounds of an array, or a single lower bound
9106 along the @var{DIM} dimension.
9107 @item @emph{Standard}:
9108 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
9113 @item @emph{Syntax}:
9114 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
9116 @item @emph{Arguments}:
9117 @multitable @columnfractions .15 .70
9118 @item @var{ARRAY} @tab Shall be an array, of any type.
9119 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
9120 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9121 expression indicating the kind parameter of the result.
9124 @item @emph{Return value}:
9125 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9126 @var{KIND} is absent, the return value is of default integer kind.
9127 If @var{DIM} is absent, the result is an array of the lower bounds of
9128 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
9129 corresponding to the lower bound of the array along that dimension. If
9130 @var{ARRAY} is an expression rather than a whole array or array
9131 structure component, or if it has a zero extent along the relevant
9132 dimension, the lower bound is taken to be 1.
9134 @item @emph{See also}:
9142 @section @code{LCOBOUND} --- Lower codimension bounds of an array
9144 @cindex coarray, lower bound
9147 @item @emph{Description}:
9148 Returns the lower bounds of a coarray, or a single lower cobound
9149 along the @var{DIM} codimension.
9150 @item @emph{Standard}:
9151 Fortran 2008 and later
9156 @item @emph{Syntax}:
9157 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
9159 @item @emph{Arguments}:
9160 @multitable @columnfractions .15 .70
9161 @item @var{ARRAY} @tab Shall be an coarray, of any type.
9162 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
9163 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9164 expression indicating the kind parameter of the result.
9167 @item @emph{Return value}:
9168 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9169 @var{KIND} is absent, the return value is of default integer kind.
9170 If @var{DIM} is absent, the result is an array of the lower cobounds of
9171 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
9172 corresponding to the lower cobound of the array along that codimension.
9174 @item @emph{See also}:
9175 @ref{UCOBOUND}, @gol
9182 @section @code{LEADZ} --- Number of leading zero bits of an integer
9187 @item @emph{Description}:
9188 @code{LEADZ} returns the number of leading zero bits of an integer.
9190 @item @emph{Standard}:
9191 Fortran 2008 and later
9196 @item @emph{Syntax}:
9197 @code{RESULT = LEADZ(I)}
9199 @item @emph{Arguments}:
9200 @multitable @columnfractions .15 .70
9201 @item @var{I} @tab Shall be of type @code{INTEGER}.
9204 @item @emph{Return value}:
9205 The type of the return value is the default @code{INTEGER}.
9206 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
9208 @item @emph{Example}:
9211 WRITE (*,*) BIT_SIZE(1) ! prints 32
9212 WRITE (*,*) LEADZ(1) ! prints 31
9216 @item @emph{See also}:
9217 @ref{BIT_SIZE}, @gol
9226 @section @code{LEN} --- Length of a character entity
9228 @cindex string, length
9231 @item @emph{Description}:
9232 Returns the length of a character string. If @var{STRING} is an array,
9233 the length of an element of @var{STRING} is returned. Note that
9234 @var{STRING} need not be defined when this intrinsic is invoked, since
9235 only the length, not the content, of @var{STRING} is needed.
9237 @item @emph{Standard}:
9238 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
9243 @item @emph{Syntax}:
9244 @code{L = LEN(STRING [, KIND])}
9246 @item @emph{Arguments}:
9247 @multitable @columnfractions .15 .70
9248 @item @var{STRING} @tab Shall be a scalar or array of type
9249 @code{CHARACTER}, with @code{INTENT(IN)}
9250 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9251 expression indicating the kind parameter of the result.
9254 @item @emph{Return value}:
9255 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9256 @var{KIND} is absent, the return value is of default integer kind.
9259 @item @emph{Specific names}:
9260 @multitable @columnfractions .20 .20 .20 .25
9261 @item Name @tab Argument @tab Return type @tab Standard
9262 @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
9266 @item @emph{See also}:
9267 @ref{LEN_TRIM}, @gol
9275 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
9277 @cindex string, length, without trailing whitespace
9280 @item @emph{Description}:
9281 Returns the length of a character string, ignoring any trailing blanks.
9283 @item @emph{Standard}:
9284 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
9289 @item @emph{Syntax}:
9290 @code{RESULT = LEN_TRIM(STRING [, KIND])}
9292 @item @emph{Arguments}:
9293 @multitable @columnfractions .15 .70
9294 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
9295 with @code{INTENT(IN)}
9296 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9297 expression indicating the kind parameter of the result.
9300 @item @emph{Return value}:
9301 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9302 @var{KIND} is absent, the return value is of default integer kind.
9304 @item @emph{See also}:
9313 @section @code{LGE} --- Lexical greater than or equal
9315 @cindex lexical comparison of strings
9316 @cindex string, comparison
9319 @item @emph{Description}:
9320 Determines whether one string is lexically greater than or equal to
9321 another string, where the two strings are interpreted as containing
9322 ASCII character codes. If the String A and String B are not the same
9323 length, the shorter is compared as if spaces were appended to it to form
9324 a value that has the same length as the longer.
9326 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9327 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9328 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9329 that the latter use the processor's character ordering (which is not
9330 ASCII on some targets), whereas the former always use the ASCII
9333 @item @emph{Standard}:
9334 Fortran 77 and later
9339 @item @emph{Syntax}:
9340 @code{RESULT = LGE(STRING_A, STRING_B)}
9342 @item @emph{Arguments}:
9343 @multitable @columnfractions .15 .70
9344 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9345 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9348 @item @emph{Return value}:
9349 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
9350 otherwise, based on the ASCII ordering.
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{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9358 @item @emph{See also}:
9367 @section @code{LGT} --- Lexical greater than
9369 @cindex lexical comparison of strings
9370 @cindex string, comparison
9373 @item @emph{Description}:
9374 Determines whether one string is lexically greater than another string,
9375 where the two strings are interpreted as containing ASCII character
9376 codes. If the String A and String B are not the same length, the
9377 shorter is compared as if spaces were appended to it to form a value
9378 that has the same length as the longer.
9380 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9381 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9382 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9383 that the latter use the processor's character ordering (which is not
9384 ASCII on some targets), whereas the former always use the ASCII
9387 @item @emph{Standard}:
9388 Fortran 77 and later
9393 @item @emph{Syntax}:
9394 @code{RESULT = LGT(STRING_A, STRING_B)}
9396 @item @emph{Arguments}:
9397 @multitable @columnfractions .15 .70
9398 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9399 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9402 @item @emph{Return value}:
9403 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
9404 otherwise, based on the ASCII ordering.
9406 @item @emph{Specific names}:
9407 @multitable @columnfractions .20 .20 .20 .25
9408 @item Name @tab Argument @tab Return type @tab Standard
9409 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9412 @item @emph{See also}:
9421 @section @code{LINK} --- Create a hard link
9423 @cindex file system, create link
9424 @cindex file system, hard link
9427 @item @emph{Description}:
9428 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
9429 character (@code{CHAR(0)}) can be used to mark the end of the names in
9430 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
9431 names are ignored. If the @var{STATUS} argument is supplied, it
9432 contains 0 on success or a nonzero error code upon return; see
9435 This intrinsic is provided in both subroutine and function forms;
9436 however, only one form can be used in any given program unit.
9438 @item @emph{Standard}:
9442 Subroutine, function
9444 @item @emph{Syntax}:
9445 @multitable @columnfractions .80
9446 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
9447 @item @code{STATUS = LINK(PATH1, PATH2)}
9450 @item @emph{Arguments}:
9451 @multitable @columnfractions .15 .70
9452 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
9453 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
9454 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9457 @item @emph{See also}:
9465 @section @code{LLE} --- Lexical less than or equal
9467 @cindex lexical comparison of strings
9468 @cindex string, comparison
9471 @item @emph{Description}:
9472 Determines whether one string is lexically less than or equal to another
9473 string, where the two strings are interpreted as containing ASCII
9474 character codes. If the String A and String B are not the same length,
9475 the shorter is compared as if spaces were appended to it to form a value
9476 that has the same length as the longer.
9478 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9479 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9480 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9481 that the latter use the processor's character ordering (which is not
9482 ASCII on some targets), whereas the former always use the ASCII
9485 @item @emph{Standard}:
9486 Fortran 77 and later
9491 @item @emph{Syntax}:
9492 @code{RESULT = LLE(STRING_A, STRING_B)}
9494 @item @emph{Arguments}:
9495 @multitable @columnfractions .15 .70
9496 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9497 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9500 @item @emph{Return value}:
9501 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
9502 otherwise, based on the ASCII ordering.
9504 @item @emph{Specific names}:
9505 @multitable @columnfractions .20 .20 .20 .25
9506 @item Name @tab Argument @tab Return type @tab Standard
9507 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9510 @item @emph{See also}:
9519 @section @code{LLT} --- Lexical less than
9521 @cindex lexical comparison of strings
9522 @cindex string, comparison
9525 @item @emph{Description}:
9526 Determines whether one string is lexically less than another string,
9527 where the two strings are interpreted as containing ASCII character
9528 codes. If the String A and String B are not the same length, the
9529 shorter is compared as if spaces were appended to it to form a value
9530 that has the same length as the longer.
9532 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9533 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9534 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9535 that the latter use the processor's character ordering (which is not
9536 ASCII on some targets), whereas the former always use the ASCII
9539 @item @emph{Standard}:
9540 Fortran 77 and later
9545 @item @emph{Syntax}:
9546 @code{RESULT = LLT(STRING_A, STRING_B)}
9548 @item @emph{Arguments}:
9549 @multitable @columnfractions .15 .70
9550 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9551 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9554 @item @emph{Return value}:
9555 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
9556 otherwise, based on the ASCII ordering.
9558 @item @emph{Specific names}:
9559 @multitable @columnfractions .20 .20 .20 .25
9560 @item Name @tab Argument @tab Return type @tab Standard
9561 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9564 @item @emph{See also}:
9573 @section @code{LNBLNK} --- Index of the last non-blank character in a string
9575 @cindex string, find non-blank character
9578 @item @emph{Description}:
9579 Returns the length of a character string, ignoring any trailing blanks.
9580 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
9581 included for backwards compatibility.
9583 @item @emph{Standard}:
9589 @item @emph{Syntax}:
9590 @code{RESULT = LNBLNK(STRING)}
9592 @item @emph{Arguments}:
9593 @multitable @columnfractions .15 .70
9594 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
9595 with @code{INTENT(IN)}
9598 @item @emph{Return value}:
9599 The return value is of @code{INTEGER(kind=4)} type.
9601 @item @emph{See also}:
9602 @ref{INDEX intrinsic}, @gol
9609 @section @code{LOC} --- Returns the address of a variable
9611 @cindex location of a variable in memory
9614 @item @emph{Description}:
9615 @code{LOC(X)} returns the address of @var{X} as an integer.
9617 @item @emph{Standard}:
9623 @item @emph{Syntax}:
9624 @code{RESULT = LOC(X)}
9626 @item @emph{Arguments}:
9627 @multitable @columnfractions .15 .70
9628 @item @var{X} @tab Variable of any type.
9631 @item @emph{Return value}:
9632 The return value is of type @code{INTEGER}, with a @code{KIND}
9633 corresponding to the size (in bytes) of a memory address on the target
9636 @item @emph{Example}:
9643 end program test_loc
9650 @section @code{LOG} --- Natural logarithm function
9657 @cindex exponential function, inverse
9658 @cindex logarithm function
9659 @cindex natural logarithm function
9662 @item @emph{Description}:
9663 @code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the
9664 logarithm to the base @math{e}.
9666 @item @emph{Standard}:
9667 Fortran 77 and later, has GNU extensions
9672 @item @emph{Syntax}:
9673 @code{RESULT = LOG(X)}
9675 @item @emph{Arguments}:
9676 @multitable @columnfractions .15 .70
9677 @item @var{X} @tab The type shall be @code{REAL} or
9681 @item @emph{Return value}:
9682 The return value is of type @code{REAL} or @code{COMPLEX}.
9683 The kind type parameter is the same as @var{X}.
9684 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
9685 @math{-\pi < \omega \leq \pi}.
9687 @item @emph{Example}:
9690 real(8) :: x = 2.7182818284590451_8
9691 complex :: z = (1.0, 2.0)
9692 x = log(x) ! will yield (approximately) 1
9694 end program test_log
9697 @item @emph{Specific names}:
9698 @multitable @columnfractions .20 .20 .20 .25
9699 @item Name @tab Argument @tab Return type @tab Standard
9700 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 or later
9701 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 or later
9702 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 or later
9703 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
9704 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
9711 @section @code{LOG10} --- Base 10 logarithm function
9715 @cindex exponential function, inverse
9716 @cindex logarithm function with base 10
9717 @cindex base 10 logarithm function
9720 @item @emph{Description}:
9721 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
9723 @item @emph{Standard}:
9724 Fortran 77 and later
9729 @item @emph{Syntax}:
9730 @code{RESULT = LOG10(X)}
9732 @item @emph{Arguments}:
9733 @multitable @columnfractions .15 .70
9734 @item @var{X} @tab The type shall be @code{REAL}.
9737 @item @emph{Return value}:
9738 The return value is of type @code{REAL} or @code{COMPLEX}.
9739 The kind type parameter is the same as @var{X}.
9741 @item @emph{Example}:
9744 real(8) :: x = 10.0_8
9746 end program test_log10
9749 @item @emph{Specific names}:
9750 @multitable @columnfractions .20 .20 .20 .25
9751 @item Name @tab Argument @tab Return type @tab Standard
9752 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
9753 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
9760 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
9765 @cindex Gamma function, logarithm of
9768 @item @emph{Description}:
9769 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
9770 of the Gamma (@math{\Gamma}) function.
9772 @item @emph{Standard}:
9773 Fortran 2008 and later
9778 @item @emph{Syntax}:
9779 @code{X = LOG_GAMMA(X)}
9781 @item @emph{Arguments}:
9782 @multitable @columnfractions .15 .70
9783 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
9784 nor a negative integer.
9787 @item @emph{Return value}:
9788 The return value is of type @code{REAL} of the same kind as @var{X}.
9790 @item @emph{Example}:
9792 program test_log_gamma
9794 x = lgamma(x) ! returns 0.0
9795 end program test_log_gamma
9798 @item @emph{Specific names}:
9799 @multitable @columnfractions .20 .20 .20 .25
9800 @item Name @tab Argument @tab Return type @tab Standard
9801 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
9802 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
9803 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
9806 @item @emph{See also}:
9807 Gamma function: @gol
9814 @section @code{LOGICAL} --- Convert to logical type
9816 @cindex conversion, to logical
9819 @item @emph{Description}:
9820 Converts one kind of @code{LOGICAL} variable to another.
9822 @item @emph{Standard}:
9823 Fortran 90 and later
9828 @item @emph{Syntax}:
9829 @code{RESULT = LOGICAL(L [, KIND])}
9831 @item @emph{Arguments}:
9832 @multitable @columnfractions .15 .70
9833 @item @var{L} @tab The type shall be @code{LOGICAL}.
9834 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9835 expression indicating the kind parameter of the result.
9838 @item @emph{Return value}:
9839 The return value is a @code{LOGICAL} value equal to @var{L}, with a
9840 kind corresponding to @var{KIND}, or of the default logical kind if
9841 @var{KIND} is not given.
9843 @item @emph{See also}:
9852 @section @code{LONG} --- Convert to integer type
9854 @cindex conversion, to integer
9857 @item @emph{Description}:
9858 Convert to a @code{KIND=4} integer type, which is the same size as a C
9859 @code{long} integer. This is equivalent to the standard @code{INT}
9860 intrinsic with an optional argument of @code{KIND=4}, and is only
9861 included for backwards compatibility.
9863 @item @emph{Standard}:
9869 @item @emph{Syntax}:
9870 @code{RESULT = LONG(A)}
9872 @item @emph{Arguments}:
9873 @multitable @columnfractions .15 .70
9874 @item @var{A} @tab Shall be of type @code{INTEGER},
9875 @code{REAL}, or @code{COMPLEX}.
9878 @item @emph{Return value}:
9879 The return value is a @code{INTEGER(4)} variable.
9881 @item @emph{See also}:
9890 @section @code{LSHIFT} --- Left shift bits
9892 @cindex bits, shift left
9895 @item @emph{Description}:
9896 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
9897 bits shifted left by @var{SHIFT} places. @var{SHIFT} shall be
9898 nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
9899 the result value is undefined. Bits shifted out from the left end are
9900 lost; zeros are shifted in from the opposite end.
9902 This function has been superseded by the @code{ISHFT} intrinsic, which
9903 is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
9904 which is standard in Fortran 2008 and later.
9906 @item @emph{Standard}:
9912 @item @emph{Syntax}:
9913 @code{RESULT = LSHIFT(I, SHIFT)}
9915 @item @emph{Arguments}:
9916 @multitable @columnfractions .15 .70
9917 @item @var{I} @tab The type shall be @code{INTEGER}.
9918 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
9921 @item @emph{Return value}:
9922 The return value is of type @code{INTEGER} and of the same kind as
9925 @item @emph{See also}:
9937 @section @code{LSTAT} --- Get file status
9939 @cindex file system, file status
9942 @item @emph{Description}:
9943 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
9944 symbolic link, then the link itself is statted, not the file that it
9947 The elements in @code{VALUES} are the same as described by @ref{STAT}.
9949 This intrinsic is provided in both subroutine and function forms;
9950 however, only one form can be used in any given program unit.
9952 @item @emph{Standard}:
9956 Subroutine, function
9958 @item @emph{Syntax}:
9959 @multitable @columnfractions .80
9960 @item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
9961 @item @code{STATUS = LSTAT(NAME, VALUES)}
9964 @item @emph{Arguments}:
9965 @multitable @columnfractions .15 .70
9966 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
9967 kind, a valid path within the file system.
9968 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
9969 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
9970 Returns 0 on success and a system specific error code otherwise.
9973 @item @emph{Example}:
9974 See @ref{STAT} for an example.
9976 @item @emph{See also}:
9977 To stat an open file: @gol
9979 To stat a file: @gol
9986 @section @code{LTIME} --- Convert time to local time info
9988 @cindex time, conversion to local time info
9991 @item @emph{Description}:
9992 Given a system time value @var{TIME} (as provided by the @ref{TIME}
9993 intrinsic), fills @var{VALUES} with values extracted from it appropriate
9994 to the local time zone using @code{localtime(3)}.
9996 This intrinsic routine is provided for backwards compatibility with
9997 GNU Fortran 77. In new code, programmers should consider the use of
9998 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
10001 @item @emph{Standard}:
10004 @item @emph{Class}:
10007 @item @emph{Syntax}:
10008 @code{CALL LTIME(TIME, VALUES)}
10010 @item @emph{Arguments}:
10011 @multitable @columnfractions .15 .70
10012 @item @var{TIME} @tab An @code{INTEGER} scalar expression
10013 corresponding to a system time, with @code{INTENT(IN)}.
10014 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
10015 with @code{INTENT(OUT)}.
10018 @item @emph{Return value}:
10019 The elements of @var{VALUES} are assigned as follows:
10021 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
10023 @item Minutes after the hour, range 0--59
10024 @item Hours past midnight, range 0--23
10025 @item Day of month, range 1--31
10026 @item Number of months since January, range 0--11
10027 @item Years since 1900
10028 @item Number of days since Sunday, range 0--6
10029 @item Days since January 1, range 0--365
10030 @item Daylight savings indicator: positive if daylight savings is in
10031 effect, zero if not, and negative if the information is not available.
10034 @item @emph{See also}:
10035 @ref{DATE_AND_TIME}, @gol
10045 @section @code{MALLOC} --- Allocate dynamic memory
10047 @cindex pointer, cray
10050 @item @emph{Description}:
10051 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
10052 returns the address of the allocated memory. The @code{MALLOC} intrinsic
10053 is an extension intended to be used with Cray pointers, and is provided
10054 in GNU Fortran to allow the user to compile legacy code. For new code
10055 using Fortran 95 pointers, the memory allocation intrinsic is
10058 @item @emph{Standard}:
10061 @item @emph{Class}:
10064 @item @emph{Syntax}:
10065 @code{PTR = MALLOC(SIZE)}
10067 @item @emph{Arguments}:
10068 @multitable @columnfractions .15 .70
10069 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
10072 @item @emph{Return value}:
10073 The return value is of type @code{INTEGER(K)}, with @var{K} such that
10074 variables of type @code{INTEGER(K)} have the same size as
10075 C pointers (@code{sizeof(void *)}).
10077 @item @emph{Example}:
10078 The following example demonstrates the use of @code{MALLOC} and
10079 @code{FREE} with Cray pointers.
10082 program test_malloc
10088 ptr_x = malloc(20*8)
10090 x(i) = sqrt(1.0d0 / i)
10098 end program test_malloc
10101 @item @emph{See also}:
10108 @section @code{MASKL} --- Left justified mask
10110 @cindex mask, left justified
10113 @item @emph{Description}:
10114 @code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
10115 remaining bits set to 0.
10117 @item @emph{Standard}:
10118 Fortran 2008 and later
10120 @item @emph{Class}:
10123 @item @emph{Syntax}:
10124 @code{RESULT = MASKL(I[, KIND])}
10126 @item @emph{Arguments}:
10127 @multitable @columnfractions .15 .70
10128 @item @var{I} @tab Shall be of type @code{INTEGER}.
10129 @item @var{KIND} @tab Shall be a scalar constant expression of type
10133 @item @emph{Return value}:
10134 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
10135 specifies the kind value of the return type; otherwise, it is of the
10136 default integer kind.
10138 @item @emph{See also}:
10145 @section @code{MASKR} --- Right justified mask
10147 @cindex mask, right justified
10150 @item @emph{Description}:
10151 @code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
10152 remaining bits set to 0.
10154 @item @emph{Standard}:
10155 Fortran 2008 and later
10157 @item @emph{Class}:
10160 @item @emph{Syntax}:
10161 @code{RESULT = MASKR(I[, KIND])}
10163 @item @emph{Arguments}:
10164 @multitable @columnfractions .15 .70
10165 @item @var{I} @tab Shall be of type @code{INTEGER}.
10166 @item @var{KIND} @tab Shall be a scalar constant expression of type
10170 @item @emph{Return value}:
10171 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
10172 specifies the kind value of the return type; otherwise, it is of the
10173 default integer kind.
10175 @item @emph{See also}:
10182 @section @code{MATMUL} --- matrix multiplication
10184 @cindex matrix multiplication
10185 @cindex product, matrix
10188 @item @emph{Description}:
10189 Performs a matrix multiplication on numeric or logical arguments.
10191 @item @emph{Standard}:
10192 Fortran 90 and later
10194 @item @emph{Class}:
10195 Transformational function
10197 @item @emph{Syntax}:
10198 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
10200 @item @emph{Arguments}:
10201 @multitable @columnfractions .15 .70
10202 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
10203 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
10205 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
10206 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
10207 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
10208 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
10209 equal to the last (or only) dimension of @var{MATRIX_A}.
10210 @var{MATRIX_A} and @var{MATRIX_B} shall not both be rank one arrays.
10213 @item @emph{Return value}:
10214 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
10215 kind of the result follow the usual type and kind promotion rules, as
10216 for the @code{*} or @code{.AND.} operators.
10222 @section @code{MAX} --- Maximum value of an argument list
10229 @cindex maximum value
10232 @item @emph{Description}:
10233 Returns the argument with the largest (most positive) value.
10235 @item @emph{Standard}:
10236 Fortran 77 and later
10238 @item @emph{Class}:
10241 @item @emph{Syntax}:
10242 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
10244 @item @emph{Arguments}:
10245 @multitable @columnfractions .15 .70
10246 @item @var{A1} @tab The type shall be @code{INTEGER} or
10248 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
10249 as @var{A1}. (As a GNU extension, arguments of different kinds are
10253 @item @emph{Return value}:
10254 The return value corresponds to the maximum value among the arguments,
10255 and has the same type and kind as the first argument.
10257 @item @emph{Specific names}:
10258 @multitable @columnfractions .20 .20 .20 .25
10259 @item Name @tab Argument @tab Return type @tab Standard
10260 @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
10261 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
10262 @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
10263 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
10264 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
10267 @item @emph{See also}:
10276 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
10277 @fnindex MAXEXPONENT
10278 @cindex model representation, maximum exponent
10281 @item @emph{Description}:
10282 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
10285 @item @emph{Standard}:
10286 Fortran 90 and later
10288 @item @emph{Class}:
10291 @item @emph{Syntax}:
10292 @code{RESULT = MAXEXPONENT(X)}
10294 @item @emph{Arguments}:
10295 @multitable @columnfractions .15 .70
10296 @item @var{X} @tab Shall be of type @code{REAL}.
10299 @item @emph{Return value}:
10300 The return value is of type @code{INTEGER} and of the default integer
10303 @item @emph{Example}:
10309 print *, minexponent(x), maxexponent(x)
10310 print *, minexponent(y), maxexponent(y)
10311 end program exponents
10318 @section @code{MAXLOC} --- Location of the maximum value within an array
10320 @cindex array, location of maximum element
10323 @item @emph{Description}:
10324 Determines the location of the element in the array with the maximum
10325 value, or, if the @var{DIM} argument is supplied, determines the
10326 locations of the maximum element along each row of the array in the
10327 @var{DIM} direction. If @var{MASK} is present, only the elements for
10328 which @var{MASK} is @code{.TRUE.} are considered. If more than one
10329 element in the array has the maximum value, the location returned is
10330 that of the first such element in array element order if the
10331 @var{BACK} is not present, or is false; if @var{BACK} is true, the location
10332 returned is that of the last such element. If the array has zero
10333 size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
10334 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
10335 and all of the elements of @var{MASK} along a given row are zero, the
10336 result value for that row is zero.
10338 @item @emph{Standard}:
10339 Fortran 95 and later; @var{ARRAY} of @code{CHARACTER} and the
10340 @var{KIND} argument are available in Fortran 2003 and later.
10341 The @var{BACK} argument is available in Fortran 2008 and later.
10343 @item @emph{Class}:
10344 Transformational function
10346 @item @emph{Syntax}:
10347 @multitable @columnfractions .80
10348 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK])}
10349 @item @code{RESULT = MAXLOC(ARRAY [, MASK] [,KIND] [,BACK])}
10352 @item @emph{Arguments}:
10353 @multitable @columnfractions .15 .70
10354 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10356 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10357 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10358 inclusive. It may not be an optional dummy argument.
10359 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
10360 and conformable with @var{ARRAY}.
10361 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10362 expression indicating the kind parameter of the result.
10363 @item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}.
10366 @item @emph{Return value}:
10367 If @var{DIM} is absent, the result is a rank-one array with a length
10368 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
10369 is an array with a rank one less than the rank of @var{ARRAY}, and a
10370 size corresponding to the size of @var{ARRAY} with the @var{DIM}
10371 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
10372 of one, the result is a scalar. If the optional argument @var{KIND}
10373 is present, the result is an integer of kind @var{KIND}, otherwise it
10374 is of default kind.
10376 @item @emph{See also}:
10377 @ref{FINDLOC}, @gol
10385 @section @code{MAXVAL} --- Maximum value of an array
10387 @cindex array, maximum value
10388 @cindex maximum value
10391 @item @emph{Description}:
10392 Determines the maximum value of the elements in an array value, or, if
10393 the @var{DIM} argument is supplied, determines the maximum value along
10394 each row of the array in the @var{DIM} direction. If @var{MASK} is
10395 present, only the elements for which @var{MASK} is @code{.TRUE.} are
10396 considered. If the array has zero size, or all of the elements of
10397 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
10398 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
10401 @item @emph{Standard}:
10402 Fortran 90 and later
10404 @item @emph{Class}:
10405 Transformational function
10407 @item @emph{Syntax}:
10408 @multitable @columnfractions .80
10409 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
10410 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
10413 @item @emph{Arguments}:
10414 @multitable @columnfractions .15 .70
10415 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10417 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10418 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10419 inclusive. It may not be an optional dummy argument.
10420 @item @var{MASK} @tab (Optional) Shall be an array of type @code{LOGICAL},
10421 and conformable with @var{ARRAY}.
10424 @item @emph{Return value}:
10425 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
10426 is a scalar. If @var{DIM} is present, the result is an array with a
10427 rank one less than the rank of @var{ARRAY}, and a size corresponding to
10428 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
10429 cases, the result is of the same type and kind as @var{ARRAY}.
10431 @item @emph{See also}:
10439 @section @code{MCLOCK} --- Time function
10441 @cindex time, clock ticks
10442 @cindex clock ticks
10445 @item @emph{Description}:
10446 Returns the number of clock ticks since the start of the process, based
10447 on the function @code{clock(3)} in the C standard library.
10449 This intrinsic is not fully portable, such as to systems with 32-bit
10450 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
10451 the values returned by this intrinsic might be, or become, negative, or
10452 numerically less than previous values, during a single run of the
10455 @item @emph{Standard}:
10458 @item @emph{Class}:
10461 @item @emph{Syntax}:
10462 @code{RESULT = MCLOCK()}
10464 @item @emph{Return value}:
10465 The return value is a scalar of type @code{INTEGER(4)}, equal to the
10466 number of clock ticks since the start of the process, or @code{-1} if
10467 the system does not support @code{clock(3)}.
10469 @item @emph{See also}:
10480 @section @code{MCLOCK8} --- Time function (64-bit)
10482 @cindex time, clock ticks
10483 @cindex clock ticks
10486 @item @emph{Description}:
10487 Returns the number of clock ticks since the start of the process, based
10488 on the function @code{clock(3)} in the C standard library.
10490 @emph{Warning:} this intrinsic does not increase the range of the timing
10491 values over that returned by @code{clock(3)}. On a system with a 32-bit
10492 @code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though
10493 it is converted to a 64-bit @code{INTEGER(8)} value. That means
10494 overflows of the 32-bit value can still occur. Therefore, the values
10495 returned by this intrinsic might be or become negative or numerically
10496 less than previous values during a single run of the compiled program.
10498 @item @emph{Standard}:
10501 @item @emph{Class}:
10504 @item @emph{Syntax}:
10505 @code{RESULT = MCLOCK8()}
10507 @item @emph{Return value}:
10508 The return value is a scalar of type @code{INTEGER(8)}, equal to the
10509 number of clock ticks since the start of the process, or @code{-1} if
10510 the system does not support @code{clock(3)}.
10512 @item @emph{See also}:
10523 @section @code{MERGE} --- Merge variables
10525 @cindex array, merge arrays
10526 @cindex array, combine arrays
10529 @item @emph{Description}:
10530 Select values from two arrays according to a logical mask. The result
10531 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
10532 @var{FSOURCE} if it is @code{.FALSE.}.
10534 @item @emph{Standard}:
10535 Fortran 90 and later
10537 @item @emph{Class}:
10540 @item @emph{Syntax}:
10541 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
10543 @item @emph{Arguments}:
10544 @multitable @columnfractions .15 .70
10545 @item @var{TSOURCE} @tab May be of any type.
10546 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
10548 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
10551 @item @emph{Return value}:
10552 The result is of the same type and type parameters as @var{TSOURCE}.
10559 @section @code{MERGE_BITS} --- Merge of bits under mask
10560 @fnindex MERGE_BITS
10561 @cindex bits, merge
10564 @item @emph{Description}:
10565 @code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
10566 as determined by the mask. The i-th bit of the result is equal to the
10567 i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
10568 the i-th bit of @var{J} otherwise.
10570 @item @emph{Standard}:
10571 Fortran 2008 and later
10573 @item @emph{Class}:
10576 @item @emph{Syntax}:
10577 @code{RESULT = MERGE_BITS(I, J, MASK)}
10579 @item @emph{Arguments}:
10580 @multitable @columnfractions .15 .70
10581 @item @var{I} @tab Shall be of type @code{INTEGER} or a boz-literal-constant.
10582 @item @var{J} @tab Shall be of type @code{INTEGER} with the same
10583 kind type parameter as @var{I} or a boz-literal-constant.
10584 @var{I} and @var{J} shall not both be boz-literal-constants.
10585 @item @var{MASK} @tab Shall be of type @code{INTEGER} or a boz-literal-constant
10586 and of the same kind as @var{I}.
10589 @item @emph{Return value}:
10590 The result is of the same type and kind as @var{I}.
10597 @section @code{MIN} --- Minimum value of an argument list
10604 @cindex minimum value
10607 @item @emph{Description}:
10608 Returns the argument with the smallest (most negative) value.
10610 @item @emph{Standard}:
10611 Fortran 77 and later
10613 @item @emph{Class}:
10616 @item @emph{Syntax}:
10617 @code{RESULT = MIN(A1, A2 [, A3, ...])}
10619 @item @emph{Arguments}:
10620 @multitable @columnfractions .15 .70
10621 @item @var{A1} @tab The type shall be @code{INTEGER} or
10623 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
10624 as @var{A1}. (As a GNU extension, arguments of different kinds are
10628 @item @emph{Return value}:
10629 The return value corresponds to the maximum value among the arguments,
10630 and has the same type and kind as the first argument.
10632 @item @emph{Specific names}:
10633 @multitable @columnfractions .20 .20 .20 .25
10634 @item Name @tab Argument @tab Return type @tab Standard
10635 @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
10636 @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
10637 @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
10638 @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
10639 @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
10642 @item @emph{See also}:
10651 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
10652 @fnindex MINEXPONENT
10653 @cindex model representation, minimum exponent
10656 @item @emph{Description}:
10657 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
10660 @item @emph{Standard}:
10661 Fortran 90 and later
10663 @item @emph{Class}:
10666 @item @emph{Syntax}:
10667 @code{RESULT = MINEXPONENT(X)}
10669 @item @emph{Arguments}:
10670 @multitable @columnfractions .15 .70
10671 @item @var{X} @tab Shall be of type @code{REAL}.
10674 @item @emph{Return value}:
10675 The return value is of type @code{INTEGER} and of the default integer
10678 @item @emph{Example}:
10679 See @code{MAXEXPONENT} for an example.
10685 @section @code{MINLOC} --- Location of the minimum value within an array
10687 @cindex array, location of minimum element
10690 @item @emph{Description}:
10691 Determines the location of the element in the array with the minimum
10692 value, or, if the @var{DIM} argument is supplied, determines the
10693 locations of the minimum element along each row of the array in the
10694 @var{DIM} direction. If @var{MASK} is present, only the elements for
10695 which @var{MASK} is @code{.TRUE.} are considered. If more than one
10696 element in the array has the minimum value, the location returned is
10697 that of the first such element in array element order if the
10698 @var{BACK} is not present, or is false; if @var{BACK} is true, the location
10699 returned is that of the last such element. If the array has
10700 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
10701 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
10702 and all of the elements of @var{MASK} along a given row are zero, the
10703 result value for that row is zero.
10705 @item @emph{Standard}:
10706 Fortran 90 and later; @var{ARRAY} of @code{CHARACTER} and the
10707 @var{KIND} argument are available in Fortran 2003 and later.
10708 The @var{BACK} argument is available in Fortran 2008 and later.
10710 @item @emph{Class}:
10711 Transformational function
10713 @item @emph{Syntax}:
10714 @multitable @columnfractions .80
10715 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK])}
10716 @item @code{RESULT = MINLOC(ARRAY [, MASK], [,KIND] [,BACK])}
10719 @item @emph{Arguments}:
10720 @multitable @columnfractions .15 .70
10721 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
10722 @code{REAL} or @code{CHARACTER}.
10723 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10724 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10725 inclusive. It may not be an optional dummy argument.
10726 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
10727 and conformable with @var{ARRAY}.
10728 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10729 expression indicating the kind parameter of the result.
10730 @item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}.
10733 @item @emph{Return value}:
10734 If @var{DIM} is absent, the result is a rank-one array with a length
10735 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
10736 is an array with a rank one less than the rank of @var{ARRAY}, and a
10737 size corresponding to the size of @var{ARRAY} with the @var{DIM}
10738 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
10739 of one, the result is a scalar. If the optional argument @var{KIND}
10740 is present, the result is an integer of kind @var{KIND}, otherwise it
10741 is of default kind.
10743 @item @emph{See also}:
10744 @ref{FINDLOC}, @gol
10752 @section @code{MINVAL} --- Minimum value of an array
10754 @cindex array, minimum value
10755 @cindex minimum value
10758 @item @emph{Description}:
10759 Determines the minimum value of the elements in an array value, or, if
10760 the @var{DIM} argument is supplied, determines the minimum value along
10761 each row of the array in the @var{DIM} direction. If @var{MASK} is
10762 present, only the elements for which @var{MASK} is @code{.TRUE.} are
10763 considered. If the array has zero size, or all of the elements of
10764 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
10765 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
10766 @var{ARRAY} is of character type.
10768 @item @emph{Standard}:
10769 Fortran 90 and later
10771 @item @emph{Class}:
10772 Transformational function
10774 @item @emph{Syntax}:
10775 @multitable @columnfractions .80
10776 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
10777 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
10780 @item @emph{Arguments}:
10781 @multitable @columnfractions .15 .70
10782 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10784 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10785 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10786 inclusive. It may not be an optional dummy argument.
10787 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
10788 and conformable with @var{ARRAY}.
10791 @item @emph{Return value}:
10792 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
10793 is a scalar. If @var{DIM} is present, the result is an array with a
10794 rank one less than the rank of @var{ARRAY}, and a size corresponding to
10795 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
10796 cases, the result is of the same type and kind as @var{ARRAY}.
10798 @item @emph{See also}:
10806 @section @code{MOD} --- Remainder function
10815 @cindex division, remainder
10818 @item @emph{Description}:
10819 @code{MOD(A,P)} computes the remainder of the division of A by P@.
10821 @item @emph{Standard}:
10822 Fortran 77 and later, has overloads that are GNU extensions
10824 @item @emph{Class}:
10827 @item @emph{Syntax}:
10828 @code{RESULT = MOD(A, P)}
10830 @item @emph{Arguments}:
10831 @multitable @columnfractions .15 .70
10832 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
10833 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
10834 and not equal to zero. (As a GNU extension, arguments of different kinds are
10838 @item @emph{Return value}:
10839 The return value is the result of @code{A - (INT(A/P) * P)}. The type
10840 and kind of the return value is the same as that of the arguments. The
10841 returned value has the same sign as A and a magnitude less than the
10842 magnitude of P. (As a GNU extension, kind is the largest kind of the actual
10845 @item @emph{Example}:
10849 print *, mod(17.5,5.5)
10850 print *, mod(17.5d0,5.5)
10851 print *, mod(17.5,5.5d0)
10853 print *, mod(-17,3)
10854 print *, mod(-17.5,5.5)
10855 print *, mod(-17.5d0,5.5)
10856 print *, mod(-17.5,5.5d0)
10858 print *, mod(17,-3)
10859 print *, mod(17.5,-5.5)
10860 print *, mod(17.5d0,-5.5)
10861 print *, mod(17.5,-5.5d0)
10862 end program test_mod
10865 @item @emph{Specific names}:
10866 @multitable @columnfractions .20 .20 .20 .25
10867 @item Name @tab Arguments @tab Return type @tab Standard
10868 @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 77 and later
10869 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 77 and later
10870 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 77 and later
10871 @item @code{BMOD(A,P)} @tab @code{INTEGER(1) A,P} @tab @code{INTEGER(1)} @tab GNU extension
10872 @item @code{IMOD(A,P)} @tab @code{INTEGER(2) A,P} @tab @code{INTEGER(2)} @tab GNU extension
10873 @item @code{JMOD(A,P)} @tab @code{INTEGER(4) A,P} @tab @code{INTEGER(4)} @tab GNU extension
10874 @item @code{KMOD(A,P)} @tab @code{INTEGER(8) A,P} @tab @code{INTEGER(8)} @tab GNU extension
10877 @item @emph{See also}:
10885 @section @code{MODULO} --- Modulo function
10888 @cindex division, modulo
10891 @item @emph{Description}:
10892 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
10894 @item @emph{Standard}:
10895 Fortran 95 and later
10897 @item @emph{Class}:
10900 @item @emph{Syntax}:
10901 @code{RESULT = MODULO(A, P)}
10903 @item @emph{Arguments}:
10904 @multitable @columnfractions .15 .70
10905 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
10906 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}.
10907 It shall not be zero. (As a GNU extension, arguments of different kinds are
10911 @item @emph{Return value}:
10912 The type and kind of the result are those of the arguments. (As a GNU
10913 extension, kind is the largest kind of the actual arguments.)
10915 @item If @var{A} and @var{P} are of type @code{INTEGER}:
10916 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
10917 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
10919 @item If @var{A} and @var{P} are of type @code{REAL}:
10920 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
10922 The returned value has the same sign as P and a magnitude less than
10923 the magnitude of P.
10925 @item @emph{Example}:
10927 program test_modulo
10928 print *, modulo(17,3)
10929 print *, modulo(17.5,5.5)
10931 print *, modulo(-17,3)
10932 print *, modulo(-17.5,5.5)
10934 print *, modulo(17,-3)
10935 print *, modulo(17.5,-5.5)
10939 @item @emph{See also}:
10947 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
10948 @fnindex MOVE_ALLOC
10949 @cindex moving allocation
10950 @cindex allocation, moving
10953 @item @emph{Description}:
10954 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
10955 @var{TO}. @var{FROM} will become deallocated in the process.
10957 @item @emph{Standard}:
10958 Fortran 2003 and later
10960 @item @emph{Class}:
10963 @item @emph{Syntax}:
10964 @code{CALL MOVE_ALLOC(FROM, TO)}
10966 @item @emph{Arguments}:
10967 @multitable @columnfractions .15 .70
10968 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
10969 of any type and kind.
10970 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
10971 of the same type, kind and rank as @var{FROM}.
10974 @item @emph{Return value}:
10977 @item @emph{Example}:
10979 program test_move_alloc
10980 integer, allocatable :: a(:), b(:)
10984 call move_alloc(a, b)
10985 print *, allocated(a), allocated(b)
10987 end program test_move_alloc
10994 @section @code{MVBITS} --- Move bits from one integer to another
11003 @item @emph{Description}:
11004 Moves @var{LEN} bits from positions @var{FROMPOS} through
11005 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
11006 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
11007 affected by the movement of bits is unchanged. The values of
11008 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
11009 @code{BIT_SIZE(FROM)}.
11011 @item @emph{Standard}:
11012 Fortran 90 and later, has overloads that are GNU extensions
11014 @item @emph{Class}:
11015 Elemental subroutine
11017 @item @emph{Syntax}:
11018 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
11020 @item @emph{Arguments}:
11021 @multitable @columnfractions .15 .70
11022 @item @var{FROM} @tab The type shall be @code{INTEGER}.
11023 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
11024 @item @var{LEN} @tab The type shall be @code{INTEGER}.
11025 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
11026 same kind as @var{FROM}.
11027 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
11030 @item @emph{Specific names}:
11031 @multitable @columnfractions .20 .20 .20 .25
11032 @item Name @tab Argument @tab Return type @tab Standard
11033 @item @code{MVBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
11034 @item @code{BMVBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
11035 @item @code{IMVBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
11036 @item @code{JMVBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
11037 @item @code{KMVBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
11040 @item @emph{See also}:
11052 @section @code{NEAREST} --- Nearest representable number
11054 @cindex real number, nearest different
11055 @cindex floating point, nearest different
11058 @item @emph{Description}:
11059 @code{NEAREST(X, S)} returns the processor-representable number nearest
11060 to @code{X} in the direction indicated by the sign of @code{S}.
11062 @item @emph{Standard}:
11063 Fortran 90 and later
11065 @item @emph{Class}:
11068 @item @emph{Syntax}:
11069 @code{RESULT = NEAREST(X, S)}
11071 @item @emph{Arguments}:
11072 @multitable @columnfractions .15 .70
11073 @item @var{X} @tab Shall be of type @code{REAL}.
11074 @item @var{S} @tab Shall be of type @code{REAL} and
11078 @item @emph{Return value}:
11079 The return value is of the same type as @code{X}. If @code{S} is
11080 positive, @code{NEAREST} returns the processor-representable number
11081 greater than @code{X} and nearest to it. If @code{S} is negative,
11082 @code{NEAREST} returns the processor-representable number smaller than
11083 @code{X} and nearest to it.
11085 @item @emph{Example}:
11087 program test_nearest
11089 x = nearest(42.0, 1.0)
11090 y = nearest(42.0, -1.0)
11091 write (*,"(3(G20.15))") x, y, x - y
11092 end program test_nearest
11099 @section @code{NEW_LINE} --- New line character
11102 @cindex output, newline
11105 @item @emph{Description}:
11106 @code{NEW_LINE(C)} returns the new-line character.
11108 @item @emph{Standard}:
11109 Fortran 2003 and later
11111 @item @emph{Class}:
11114 @item @emph{Syntax}:
11115 @code{RESULT = NEW_LINE(C)}
11117 @item @emph{Arguments}:
11118 @multitable @columnfractions .15 .70
11119 @item @var{C} @tab The argument shall be a scalar or array of the
11120 type @code{CHARACTER}.
11123 @item @emph{Return value}:
11124 Returns a @var{CHARACTER} scalar of length one with the new-line character of
11125 the same kind as parameter @var{C}.
11127 @item @emph{Example}:
11131 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
11132 end program newline
11139 @section @code{NINT} --- Nearest whole number
11142 @cindex rounding, nearest whole number
11145 @item @emph{Description}:
11146 @code{NINT(A)} rounds its argument to the nearest whole number.
11148 @item @emph{Standard}:
11149 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
11151 @item @emph{Class}:
11154 @item @emph{Syntax}:
11155 @code{RESULT = NINT(A [, KIND])}
11157 @item @emph{Arguments}:
11158 @multitable @columnfractions .15 .70
11159 @item @var{A} @tab The type of the argument shall be @code{REAL}.
11160 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11161 expression indicating the kind parameter of the result.
11164 @item @emph{Return value}:
11165 Returns @var{A} with the fractional portion of its magnitude eliminated by
11166 rounding to the nearest whole number and with its sign preserved,
11167 converted to an @code{INTEGER} of the default kind.
11169 @item @emph{Example}:
11176 print *, nint(x4), idnint(x8)
11177 end program test_nint
11180 @item @emph{Specific names}:
11181 @multitable @columnfractions .20 .20 .20 .25
11182 @item Name @tab Argument @tab Return Type @tab Standard
11183 @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
11184 @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
11187 @item @emph{See also}:
11188 @ref{CEILING}, @gol
11195 @section @code{NORM2} --- Euclidean vector norms
11197 @cindex Euclidean vector norm
11198 @cindex L2 vector norm
11199 @cindex norm, Euclidean
11202 @item @emph{Description}:
11203 Calculates the Euclidean vector norm (@math{L_2} norm) of
11204 of @var{ARRAY} along dimension @var{DIM}.
11206 @item @emph{Standard}:
11207 Fortran 2008 and later
11209 @item @emph{Class}:
11210 Transformational function
11212 @item @emph{Syntax}:
11213 @multitable @columnfractions .80
11214 @item @code{RESULT = NORM2(ARRAY[, DIM])}
11217 @item @emph{Arguments}:
11218 @multitable @columnfractions .15 .70
11219 @item @var{ARRAY} @tab Shall be an array of type @code{REAL}
11220 @item @var{DIM} @tab (Optional) shall be a scalar of type
11221 @code{INTEGER} with a value in the range from 1 to n, where n
11222 equals the rank of @var{ARRAY}.
11225 @item @emph{Return value}:
11226 The result is of the same type as @var{ARRAY}.
11228 If @var{DIM} is absent, a scalar with the square root of the sum of all
11229 elements in @var{ARRAY} squared is returned. Otherwise, an array of
11230 rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
11231 shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
11234 @item @emph{Example}:
11237 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
11238 print *, NORM2(x) ! = sqrt(55.) ~ 7.416
11246 @section @code{NOT} --- Logical negation
11252 @cindex bits, negate
11253 @cindex bitwise logical not
11254 @cindex logical not, bitwise
11257 @item @emph{Description}:
11258 @code{NOT} returns the bitwise Boolean inverse of @var{I}.
11260 @item @emph{Standard}:
11261 Fortran 90 and later, has overloads that are GNU extensions
11263 @item @emph{Class}:
11266 @item @emph{Syntax}:
11267 @code{RESULT = NOT(I)}
11269 @item @emph{Arguments}:
11270 @multitable @columnfractions .15 .70
11271 @item @var{I} @tab The type shall be @code{INTEGER}.
11274 @item @emph{Return value}:
11275 The return type is @code{INTEGER}, of the same kind as the
11278 @item @emph{Specific names}:
11279 @multitable @columnfractions .20 .20 .20 .25
11280 @item Name @tab Argument @tab Return type @tab Standard
11281 @item @code{NOT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
11282 @item @code{BNOT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
11283 @item @code{INOT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
11284 @item @code{JNOT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
11285 @item @code{KNOT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
11288 @item @emph{See also}:
11300 @section @code{NULL} --- Function that returns an disassociated pointer
11302 @cindex pointer, status
11303 @cindex pointer, disassociated
11306 @item @emph{Description}:
11307 Returns a disassociated pointer.
11309 If @var{MOLD} is present, a disassociated pointer of the same type is
11310 returned, otherwise the type is determined by context.
11312 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
11313 includes cases where it is required.
11315 @item @emph{Standard}:
11316 Fortran 95 and later
11318 @item @emph{Class}:
11319 Transformational function
11321 @item @emph{Syntax}:
11322 @code{PTR => NULL([MOLD])}
11324 @item @emph{Arguments}:
11325 @multitable @columnfractions .15 .70
11326 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
11327 status and of any type.
11330 @item @emph{Return value}:
11331 A disassociated pointer.
11333 @item @emph{Example}:
11335 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
11338 @item @emph{See also}:
11345 @section @code{NUM_IMAGES} --- Function that returns the number of images
11346 @fnindex NUM_IMAGES
11347 @cindex coarray, @code{NUM_IMAGES}
11348 @cindex images, number of
11351 @item @emph{Description}:
11352 Returns the number of images.
11354 @item @emph{Standard}:
11355 Fortran 2008 and later. With @var{DISTANCE} or @var{FAILED} argument,
11356 Technical Specification (TS) 18508 or later
11359 @item @emph{Class}:
11360 Transformational function
11362 @item @emph{Syntax}:
11363 @code{RESULT = NUM_IMAGES(DISTANCE, FAILED)}
11365 @item @emph{Arguments}:
11366 @multitable @columnfractions .15 .70
11367 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
11368 @item @var{FAILED} @tab (optional, intent(in)) Scalar logical expression
11371 @item @emph{Return value}:
11372 Scalar default-kind integer. If @var{DISTANCE} is not present or has value 0,
11373 the number of images in the current team is returned. For values smaller or
11374 equal distance to the initial team, it returns the number of images index
11375 on the ancestor team which has a distance of @var{DISTANCE} from the invoking
11376 team. If @var{DISTANCE} is larger than the distance to the initial team, the
11377 number of images of the initial team is returned. If @var{FAILED} is not present
11378 the total number of images is returned; if it has the value @code{.TRUE.},
11379 the number of failed images is returned, otherwise, the number of images which
11380 do have not the failed status.
11382 @item @emph{Example}:
11384 INTEGER :: value[*]
11386 value = THIS_IMAGE()
11388 IF (THIS_IMAGE() == 1) THEN
11389 DO i = 1, NUM_IMAGES()
11390 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
11395 @item @emph{See also}:
11396 @ref{THIS_IMAGE}, @gol
11403 @section @code{OR} --- Bitwise logical OR
11405 @cindex bitwise logical or
11406 @cindex logical or, bitwise
11409 @item @emph{Description}:
11410 Bitwise logical @code{OR}.
11412 This intrinsic routine is provided for backwards compatibility with
11413 GNU Fortran 77. For integer arguments, programmers should consider
11414 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
11416 @item @emph{Standard}:
11419 @item @emph{Class}:
11422 @item @emph{Syntax}:
11423 @code{RESULT = OR(I, J)}
11425 @item @emph{Arguments}:
11426 @multitable @columnfractions .15 .70
11427 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
11428 type or a scalar @code{LOGICAL} type or a boz-literal-constant.
11429 @item @var{J} @tab The type shall be the same as the type of @var{I} or
11430 a boz-literal-constant. @var{I} and @var{J} shall not both be
11431 boz-literal-constants. If either @var{I} and @var{J} is a
11432 boz-literal-constant, then the other argument must be a scalar @code{INTEGER}.
11435 @item @emph{Return value}:
11436 The return type is either a scalar @code{INTEGER} or a scalar
11437 @code{LOGICAL}. If the kind type parameters differ, then the
11438 smaller kind type is implicitly converted to larger kind, and the
11439 return has the larger kind. A boz-literal-constant is
11440 converted to an @code{INTEGER} with the kind type parameter of
11441 the other argument as-if a call to @ref{INT} occurred.
11443 @item @emph{Example}:
11446 LOGICAL :: T = .TRUE., F = .FALSE.
11448 DATA a / Z'F' /, b / Z'3' /
11450 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
11451 WRITE (*,*) OR(a, b)
11455 @item @emph{See also}:
11456 Fortran 95 elemental function: @gol
11463 @section @code{PACK} --- Pack an array into an array of rank one
11465 @cindex array, packing
11466 @cindex array, reduce dimension
11467 @cindex array, gather elements
11470 @item @emph{Description}:
11471 Stores the elements of @var{ARRAY} in an array of rank one.
11473 The beginning of the resulting array is made up of elements whose @var{MASK}
11474 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
11477 @item @emph{Standard}:
11478 Fortran 90 and later
11480 @item @emph{Class}:
11481 Transformational function
11483 @item @emph{Syntax}:
11484 @code{RESULT = PACK(ARRAY, MASK[,VECTOR])}
11486 @item @emph{Arguments}:
11487 @multitable @columnfractions .15 .70
11488 @item @var{ARRAY} @tab Shall be an array of any type.
11489 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
11490 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
11492 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
11493 as @var{ARRAY} and of rank one. If present, the number of elements in
11494 @var{VECTOR} shall be equal to or greater than the number of true elements
11495 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
11496 @var{VECTOR} shall be equal to or greater than the number of elements in
11500 @item @emph{Return value}:
11501 The result is an array of rank one and the same type as that of @var{ARRAY}.
11502 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
11503 number of @code{TRUE} values in @var{MASK} otherwise.
11505 @item @emph{Example}:
11506 Gathering nonzero elements from an array:
11508 PROGRAM test_pack_1
11510 m = (/ 1, 0, 0, 0, 5, 0 /)
11511 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
11515 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
11517 PROGRAM test_pack_2
11519 m = (/ 1, 0, 0, 2 /)
11520 ! The following results in "1 2 3 4"
11521 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /))
11525 @item @emph{See also}:
11532 @section @code{PARITY} --- Reduction with exclusive OR
11535 @cindex Reduction, XOR
11536 @cindex XOR reduction
11539 @item @emph{Description}:
11540 Calculates the parity, i.e. the reduction using @code{.XOR.},
11541 of @var{MASK} along dimension @var{DIM}.
11543 @item @emph{Standard}:
11544 Fortran 2008 and later
11546 @item @emph{Class}:
11547 Transformational function
11549 @item @emph{Syntax}:
11550 @multitable @columnfractions .80
11551 @item @code{RESULT = PARITY(MASK[, DIM])}
11554 @item @emph{Arguments}:
11555 @multitable @columnfractions .15 .70
11556 @item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL}
11557 @item @var{DIM} @tab (Optional) shall be a scalar of type
11558 @code{INTEGER} with a value in the range from 1 to n, where n
11559 equals the rank of @var{MASK}.
11562 @item @emph{Return value}:
11563 The result is of the same type as @var{MASK}.
11565 If @var{DIM} is absent, a scalar with the parity of all elements in
11566 @var{MASK} is returned, i.e. true if an odd number of elements is
11567 @code{.true.} and false otherwise. If @var{DIM} is present, an array
11568 of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
11569 and a shape similar to that of @var{MASK} with dimension @var{DIM}
11570 dropped is returned.
11572 @item @emph{Example}:
11575 LOGICAL :: x(2) = [ .true., .false. ]
11576 print *, PARITY(x) ! prints "T" (true).
11584 @section @code{PERROR} --- Print system error message
11586 @cindex system, error handling
11589 @item @emph{Description}:
11590 Prints (on the C @code{stderr} stream) a newline-terminated error
11591 message corresponding to the last system error. This is prefixed by
11592 @var{STRING}, a colon and a space. See @code{perror(3)}.
11594 @item @emph{Standard}:
11597 @item @emph{Class}:
11600 @item @emph{Syntax}:
11601 @code{CALL PERROR(STRING)}
11603 @item @emph{Arguments}:
11604 @multitable @columnfractions .15 .70
11605 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
11609 @item @emph{See also}:
11616 @section @code{POPCNT} --- Number of bits set
11618 @cindex binary representation
11622 @item @emph{Description}:
11623 @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
11624 representation of @code{I}.
11626 @item @emph{Standard}:
11627 Fortran 2008 and later
11629 @item @emph{Class}:
11632 @item @emph{Syntax}:
11633 @code{RESULT = POPCNT(I)}
11635 @item @emph{Arguments}:
11636 @multitable @columnfractions .15 .70
11637 @item @var{I} @tab Shall be of type @code{INTEGER}.
11640 @item @emph{Return value}:
11641 The return value is of type @code{INTEGER} and of the default integer
11644 @item @emph{Example}:
11646 program test_population
11647 print *, popcnt(127), poppar(127)
11648 print *, popcnt(huge(0_4)), poppar(huge(0_4))
11649 print *, popcnt(huge(0_8)), poppar(huge(0_8))
11650 end program test_population
11652 @item @emph{See also}:
11661 @section @code{POPPAR} --- Parity of the number of bits set
11663 @cindex binary representation
11667 @item @emph{Description}:
11668 @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
11669 of the number of bits set ('1' bits) in the binary representation of
11670 @code{I}. It is equal to 0 if @code{I} has an even number of bits set,
11671 and 1 for an odd number of '1' bits.
11673 @item @emph{Standard}:
11674 Fortran 2008 and later
11676 @item @emph{Class}:
11679 @item @emph{Syntax}:
11680 @code{RESULT = POPPAR(I)}
11682 @item @emph{Arguments}:
11683 @multitable @columnfractions .15 .70
11684 @item @var{I} @tab Shall be of type @code{INTEGER}.
11687 @item @emph{Return value}:
11688 The return value is of type @code{INTEGER} and of the default integer
11691 @item @emph{Example}:
11693 program test_population
11694 print *, popcnt(127), poppar(127)
11695 print *, popcnt(huge(0_4)), poppar(huge(0_4))
11696 print *, popcnt(huge(0_8)), poppar(huge(0_8))
11697 end program test_population
11699 @item @emph{See also}:
11708 @section @code{PRECISION} --- Decimal precision of a real kind
11710 @cindex model representation, precision
11713 @item @emph{Description}:
11714 @code{PRECISION(X)} returns the decimal precision in the model of the
11717 @item @emph{Standard}:
11718 Fortran 90 and later
11720 @item @emph{Class}:
11723 @item @emph{Syntax}:
11724 @code{RESULT = PRECISION(X)}
11726 @item @emph{Arguments}:
11727 @multitable @columnfractions .15 .70
11728 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}. It may
11729 be scalar or valued.
11732 @item @emph{Return value}:
11733 The return value is of type @code{INTEGER} and of the default integer
11736 @item @emph{Example}:
11738 program prec_and_range
11739 real(kind=4) :: x(2)
11740 complex(kind=8) :: y
11742 print *, precision(x), range(x)
11743 print *, precision(y), range(y)
11744 end program prec_and_range
11746 @item @emph{See also}:
11747 @ref{SELECTED_REAL_KIND}, @gol
11754 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
11758 @item @emph{Description}:
11759 Determines whether an optional dummy argument is present.
11761 @item @emph{Standard}:
11762 Fortran 90 and later
11764 @item @emph{Class}:
11767 @item @emph{Syntax}:
11768 @code{RESULT = PRESENT(A)}
11770 @item @emph{Arguments}:
11771 @multitable @columnfractions .15 .70
11772 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
11773 value, or a dummy procedure. It shall be the name of an optional dummy argument
11774 accessible within the current subroutine or function.
11777 @item @emph{Return value}:
11778 Returns either @code{TRUE} if the optional argument @var{A} is present, or
11779 @code{FALSE} otherwise.
11781 @item @emph{Example}:
11783 PROGRAM test_present
11784 WRITE(*,*) f(), f(42) ! "F T"
11786 LOGICAL FUNCTION f(x)
11787 INTEGER, INTENT(IN), OPTIONAL :: x
11797 @section @code{PRODUCT} --- Product of array elements
11799 @cindex array, product
11800 @cindex array, multiply elements
11801 @cindex array, conditionally multiply elements
11802 @cindex multiply array elements
11805 @item @emph{Description}:
11806 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
11807 the corresponding element in @var{MASK} is @code{TRUE}.
11809 @item @emph{Standard}:
11810 Fortran 90 and later
11812 @item @emph{Class}:
11813 Transformational function
11815 @item @emph{Syntax}:
11816 @multitable @columnfractions .80
11817 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
11818 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
11821 @item @emph{Arguments}:
11822 @multitable @columnfractions .15 .70
11823 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
11824 @code{REAL} or @code{COMPLEX}.
11825 @item @var{DIM} @tab (Optional) shall be a scalar of type
11826 @code{INTEGER} with a value in the range from 1 to n, where n
11827 equals the rank of @var{ARRAY}.
11828 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
11829 and either be a scalar or an array of the same shape as @var{ARRAY}.
11832 @item @emph{Return value}:
11833 The result is of the same type as @var{ARRAY}.
11835 If @var{DIM} is absent, a scalar with the product of all elements in
11836 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
11837 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
11838 dimension @var{DIM} dropped is returned.
11841 @item @emph{Example}:
11843 PROGRAM test_product
11844 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
11845 print *, PRODUCT(x) ! all elements, product = 120
11846 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
11850 @item @emph{See also}:
11857 @section @code{RADIX} --- Base of a model number
11859 @cindex model representation, base
11860 @cindex model representation, radix
11863 @item @emph{Description}:
11864 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
11866 @item @emph{Standard}:
11867 Fortran 90 and later
11869 @item @emph{Class}:
11872 @item @emph{Syntax}:
11873 @code{RESULT = RADIX(X)}
11875 @item @emph{Arguments}:
11876 @multitable @columnfractions .15 .70
11877 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
11880 @item @emph{Return value}:
11881 The return value is a scalar of type @code{INTEGER} and of the default
11884 @item @emph{Example}:
11887 print *, "The radix for the default integer kind is", radix(0)
11888 print *, "The radix for the default real kind is", radix(0.0)
11889 end program test_radix
11891 @item @emph{See also}:
11892 @ref{SELECTED_REAL_KIND}
11898 @section @code{RAN} --- Real pseudo-random number
11900 @cindex random number generation
11903 @item @emph{Description}:
11904 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
11905 provided as an alias for @code{RAND}. See @ref{RAND} for complete
11908 @item @emph{Standard}:
11911 @item @emph{Class}:
11914 @item @emph{See also}:
11916 @ref{RANDOM_NUMBER}
11922 @section @code{RAND} --- Real pseudo-random number
11924 @cindex random number generation
11927 @item @emph{Description}:
11928 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
11929 distribution between 0 and 1. If @var{FLAG} is 0, the next number
11930 in the current sequence is returned; if @var{FLAG} is 1, the generator
11931 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
11932 it is used as a new seed with @code{SRAND}.
11934 This intrinsic routine is provided for backwards compatibility with
11935 GNU Fortran 77. It implements a simple modulo generator as provided
11936 by @command{g77}. For new code, one should consider the use of
11937 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
11939 @item @emph{Standard}:
11942 @item @emph{Class}:
11945 @item @emph{Syntax}:
11946 @code{RESULT = RAND(I)}
11948 @item @emph{Arguments}:
11949 @multitable @columnfractions .15 .70
11950 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
11953 @item @emph{Return value}:
11954 The return value is of @code{REAL} type and the default kind.
11956 @item @emph{Example}:
11959 integer,parameter :: seed = 86456
11962 print *, rand(), rand(), rand(), rand()
11963 print *, rand(seed), rand(), rand(), rand()
11964 end program test_rand
11967 @item @emph{See also}:
11969 @ref{RANDOM_NUMBER}
11975 @section @code{RANDOM_INIT} --- Initialize a pseudo-random number generator
11976 @fnindex RANDOM_INIT
11977 @cindex random number generation, initialization
11980 @item @emph{Description}:
11981 Initializes the state of the pseudorandom number generator used by
11982 @code{RANDOM_NUMBER}.
11984 @item @emph{Standard}:
11987 @item @emph{Class}:
11990 @item @emph{Syntax}:
11991 @code{CALL RANDOM_INIT(REPEATABLE, IMAGE_DISTINCT)}
11993 @item @emph{Arguments}:
11994 @multitable @columnfractions .25 .70
11995 @item @var{REPEATABLE} @tab Shall be a scalar with a @code{LOGICAL} type,
11996 and it is @code{INTENT(IN)}. If it is @code{.true.}, the seed is set to
11997 a processor-dependent value that is the same each time @code{RANDOM_INIT}
11998 is called from the same image. The term ``same image'' means a single
11999 instance of program execution. The sequence of random numbers is different
12000 for repeated execution of the program. If it is @code{.false.}, the seed
12001 is set to a processor-dependent value.
12002 @item @var{IMAGE_DISTINCT} @tab Shall be a scalar with a
12003 @code{LOGICAL} type, and it is @code{INTENT(IN)}. If it is @code{.true.},
12004 the seed is set to a processor-dependent value that is distinct from th
12005 seed set by a call to @code{RANDOM_INIT} in another image. If it is
12006 @code{.false.}, the seed is set value that does depend which image called
12007 @code{RANDOM_INIT}.
12010 @item @emph{Example}:
12012 program test_random_seed
12015 call random_init(.true., .true.)
12016 call random_number(x)
12017 call random_init(.true., .true.)
12018 call random_number(y)
12019 ! x and y are the same sequence
12020 if (any(x /= y)) call abort
12021 end program test_random_seed
12024 @item @emph{See also}:
12025 @ref{RANDOM_NUMBER}, @gol
12030 @node RANDOM_NUMBER
12031 @section @code{RANDOM_NUMBER} --- Pseudo-random number
12032 @fnindex RANDOM_NUMBER
12033 @cindex random number generation
12036 @item @emph{Description}:
12037 Returns a single pseudorandom number or an array of pseudorandom numbers
12038 from the uniform distribution over the range @math{ 0 \leq x < 1}.
12040 The runtime-library implements the xoshiro256** pseudorandom number
12041 generator (PRNG). This generator has a period of @math{2^{256} - 1},
12042 and when using multiple threads up to @math{2^{128}} threads can each
12043 generate @math{2^{128}} random numbers before any aliasing occurs.
12045 Note that in a multi-threaded program (e.g. using OpenMP directives),
12046 each thread will have its own random number state. For details of the
12047 seeding procedure, see the documentation for the @code{RANDOM_SEED}
12051 @item @emph{Standard}:
12052 Fortran 90 and later
12054 @item @emph{Class}:
12057 @item @emph{Syntax}:
12058 @code{RANDOM_NUMBER(HARVEST)}
12060 @item @emph{Arguments}:
12061 @multitable @columnfractions .15 .70
12062 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
12065 @item @emph{Example}:
12067 program test_random_number
12069 CALL RANDOM_NUMBER(r)
12073 @item @emph{See also}:
12074 @ref{RANDOM_SEED}, @gol
12081 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
12082 @fnindex RANDOM_SEED
12083 @cindex random number generation, seeding
12084 @cindex seeding a random number generator
12087 @item @emph{Description}:
12088 Restarts or queries the state of the pseudorandom number generator used by
12089 @code{RANDOM_NUMBER}.
12091 If @code{RANDOM_SEED} is called without arguments, it is seeded with
12092 random data retrieved from the operating system.
12094 As an extension to the Fortran standard, the GFortran
12095 @code{RANDOM_NUMBER} supports multiple threads. Each thread in a
12096 multi-threaded program has its own seed. When @code{RANDOM_SEED} is
12097 called either without arguments or with the @var{PUT} argument, the
12098 given seed is copied into a master seed as well as the seed of the
12099 current thread. When a new thread uses @code{RANDOM_NUMBER} for the
12100 first time, the seed is copied from the master seed, and forwarded
12101 @math{N * 2^{128}} steps to guarantee that the random stream does not
12102 alias any other stream in the system, where @var{N} is the number of
12103 threads that have used @code{RANDOM_NUMBER} so far during the program
12106 @item @emph{Standard}:
12107 Fortran 90 and later
12109 @item @emph{Class}:
12112 @item @emph{Syntax}:
12113 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
12115 @item @emph{Arguments}:
12116 @multitable @columnfractions .15 .70
12117 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
12118 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
12119 of the arrays used with the @var{PUT} and @var{GET} arguments.
12120 @item @var{PUT} @tab (Optional) Shall be an array of type default
12121 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
12122 the array must be larger than or equal to the number returned by the
12123 @var{SIZE} argument.
12124 @item @var{GET} @tab (Optional) Shall be an array of type default
12125 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
12126 of the array must be larger than or equal to the number returned by
12127 the @var{SIZE} argument.
12130 @item @emph{Example}:
12132 program test_random_seed
12134 integer, allocatable :: seed(:)
12137 call random_seed(size = n)
12139 call random_seed(get=seed)
12141 end program test_random_seed
12144 @item @emph{See also}:
12145 @ref{RANDOM_NUMBER}, @gol
12152 @section @code{RANGE} --- Decimal exponent range
12154 @cindex model representation, range
12157 @item @emph{Description}:
12158 @code{RANGE(X)} returns the decimal exponent range in the model of the
12161 @item @emph{Standard}:
12162 Fortran 90 and later
12164 @item @emph{Class}:
12167 @item @emph{Syntax}:
12168 @code{RESULT = RANGE(X)}
12170 @item @emph{Arguments}:
12171 @multitable @columnfractions .15 .70
12172 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
12176 @item @emph{Return value}:
12177 The return value is of type @code{INTEGER} and of the default integer
12180 @item @emph{Example}:
12181 See @code{PRECISION} for an example.
12182 @item @emph{See also}:
12183 @ref{SELECTED_REAL_KIND}, @gol
12190 @section @code{RANK} --- Rank of a data object
12195 @item @emph{Description}:
12196 @code{RANK(A)} returns the rank of a scalar or array data object.
12198 @item @emph{Standard}:
12199 Technical Specification (TS) 29113
12201 @item @emph{Class}:
12204 @item @emph{Syntax}:
12205 @code{RESULT = RANK(A)}
12207 @item @emph{Arguments}:
12208 @multitable @columnfractions .15 .70
12209 @item @var{A} @tab can be of any type
12212 @item @emph{Return value}:
12213 The return value is of type @code{INTEGER} and of the default integer
12214 kind. For arrays, their rank is returned; for scalars zero is returned.
12216 @item @emph{Example}:
12220 real, allocatable :: b(:,:)
12222 print *, rank(a), rank(b) ! Prints: 0 2
12223 end program test_rank
12231 @section @code{REAL} --- Convert to real type
12240 @cindex conversion, to real
12241 @cindex complex numbers, real part
12244 @item @emph{Description}:
12245 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
12246 @code{REALPART} function is provided for compatibility with @command{g77},
12247 and its use is strongly discouraged.
12249 @item @emph{Standard}:
12250 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later, has GNU extensions
12252 @item @emph{Class}:
12255 @item @emph{Syntax}:
12256 @multitable @columnfractions .80
12257 @item @code{RESULT = REAL(A [, KIND])}
12258 @item @code{RESULT = REALPART(Z)}
12261 @item @emph{Arguments}:
12262 @multitable @columnfractions .15 .70
12263 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
12265 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12266 expression indicating the kind parameter of the result.
12269 @item @emph{Return value}:
12270 These functions return a @code{REAL} variable or array under
12271 the following rules:
12275 @code{REAL(A)} is converted to a default real type if @var{A} is an
12276 integer or real variable.
12278 @code{REAL(A)} is converted to a real type with the kind type parameter
12279 of @var{A} if @var{A} is a complex variable.
12281 @code{REAL(A, KIND)} is converted to a real type with kind type
12282 parameter @var{KIND} if @var{A} is a complex, integer, or real
12286 @item @emph{Example}:
12289 complex :: x = (1.0, 2.0)
12290 print *, real(x), real(x,8), realpart(x)
12291 end program test_real
12294 @item @emph{Specific names}:
12295 @multitable @columnfractions .20 .20 .20 .25
12296 @item Name @tab Argument @tab Return type @tab Standard
12297 @item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab GNU extension
12298 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension
12299 @item @code{FLOATI(A)} @tab @code{INTEGER(2)} @tab @code{REAL(4)} @tab GNU extension
12300 @item @code{FLOATJ(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab GNU extension
12301 @item @code{FLOATK(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab GNU extension
12302 @item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab GNU extension
12306 @item @emph{See also}:
12314 @section @code{RENAME} --- Rename a file
12316 @cindex file system, rename file
12319 @item @emph{Description}:
12320 Renames a file from file @var{PATH1} to @var{PATH2}. A null
12321 character (@code{CHAR(0)}) can be used to mark the end of the names in
12322 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
12323 names are ignored. If the @var{STATUS} argument is supplied, it
12324 contains 0 on success or a nonzero error code upon return; see
12327 This intrinsic is provided in both subroutine and function forms;
12328 however, only one form can be used in any given program unit.
12330 @item @emph{Standard}:
12333 @item @emph{Class}:
12334 Subroutine, function
12336 @item @emph{Syntax}:
12337 @multitable @columnfractions .80
12338 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
12339 @item @code{STATUS = RENAME(PATH1, PATH2)}
12342 @item @emph{Arguments}:
12343 @multitable @columnfractions .15 .70
12344 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
12345 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
12346 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12349 @item @emph{See also}:
12357 @section @code{REPEAT} --- Repeated string concatenation
12359 @cindex string, repeat
12360 @cindex string, concatenate
12363 @item @emph{Description}:
12364 Concatenates @var{NCOPIES} copies of a string.
12366 @item @emph{Standard}:
12367 Fortran 90 and later
12369 @item @emph{Class}:
12370 Transformational function
12372 @item @emph{Syntax}:
12373 @code{RESULT = REPEAT(STRING, NCOPIES)}
12375 @item @emph{Arguments}:
12376 @multitable @columnfractions .15 .70
12377 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
12378 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
12381 @item @emph{Return value}:
12382 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
12385 @item @emph{Example}:
12387 program test_repeat
12388 write(*,*) repeat("x", 5) ! "xxxxx"
12396 @section @code{RESHAPE} --- Function to reshape an array
12398 @cindex array, change dimensions
12399 @cindex array, transmogrify
12402 @item @emph{Description}:
12403 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
12404 the new array may be padded with elements from @var{PAD} or permuted
12405 as defined by @var{ORDER}.
12407 @item @emph{Standard}:
12408 Fortran 90 and later
12410 @item @emph{Class}:
12411 Transformational function
12413 @item @emph{Syntax}:
12414 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
12416 @item @emph{Arguments}:
12417 @multitable @columnfractions .15 .70
12418 @item @var{SOURCE} @tab Shall be an array of any type.
12419 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
12420 array of rank one. Its values must be positive or zero.
12421 @item @var{PAD} @tab (Optional) shall be an array of the same
12422 type as @var{SOURCE}.
12423 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
12424 and an array of the same shape as @var{SHAPE}. Its values shall
12425 be a permutation of the numbers from 1 to n, where n is the size of
12426 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
12430 @item @emph{Return value}:
12431 The result is an array of shape @var{SHAPE} with the same type as
12434 @item @emph{Example}:
12436 PROGRAM test_reshape
12437 INTEGER, DIMENSION(4) :: x
12438 WRITE(*,*) SHAPE(x) ! prints "4"
12439 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
12443 @item @emph{See also}:
12450 @section @code{RRSPACING} --- Reciprocal of the relative spacing
12452 @cindex real number, relative spacing
12453 @cindex floating point, relative spacing
12457 @item @emph{Description}:
12458 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
12459 model numbers near @var{X}.
12461 @item @emph{Standard}:
12462 Fortran 90 and later
12464 @item @emph{Class}:
12467 @item @emph{Syntax}:
12468 @code{RESULT = RRSPACING(X)}
12470 @item @emph{Arguments}:
12471 @multitable @columnfractions .15 .70
12472 @item @var{X} @tab Shall be of type @code{REAL}.
12475 @item @emph{Return value}:
12476 The return value is of the same type and kind as @var{X}.
12477 The value returned is equal to
12478 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
12480 @item @emph{See also}:
12487 @section @code{RSHIFT} --- Right shift bits
12489 @cindex bits, shift right
12492 @item @emph{Description}:
12493 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
12494 bits shifted right by @var{SHIFT} places. @var{SHIFT} shall be
12495 nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
12496 the result value is undefined. Bits shifted out from the right end
12497 are lost. The fill is arithmetic: the bits shifted in from the left
12498 end are equal to the leftmost bit, which in two's complement
12499 representation is the sign bit.
12501 This function has been superseded by the @code{SHIFTA} intrinsic, which
12502 is standard in Fortran 2008 and later.
12504 @item @emph{Standard}:
12507 @item @emph{Class}:
12510 @item @emph{Syntax}:
12511 @code{RESULT = RSHIFT(I, SHIFT)}
12513 @item @emph{Arguments}:
12514 @multitable @columnfractions .15 .70
12515 @item @var{I} @tab The type shall be @code{INTEGER}.
12516 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12519 @item @emph{Return value}:
12520 The return value is of type @code{INTEGER} and of the same kind as
12523 @item @emph{See also}:
12536 @section @code{SAME_TYPE_AS} --- Query dynamic types for equality
12537 @fnindex SAME_TYPE_AS
12540 @item @emph{Description}:
12541 Query dynamic types for equality.
12543 @item @emph{Standard}:
12544 Fortran 2003 and later
12546 @item @emph{Class}:
12549 @item @emph{Syntax}:
12550 @code{RESULT = SAME_TYPE_AS(A, B)}
12552 @item @emph{Arguments}:
12553 @multitable @columnfractions .15 .70
12554 @item @var{A} @tab Shall be an object of extensible declared type or
12555 unlimited polymorphic.
12556 @item @var{B} @tab Shall be an object of extensible declared type or
12557 unlimited polymorphic.
12560 @item @emph{Return value}:
12561 The return value is a scalar of type default logical. It is true if and
12562 only if the dynamic type of A is the same as the dynamic type of B.
12564 @item @emph{See also}:
12565 @ref{EXTENDS_TYPE_OF}
12572 @section @code{SCALE} --- Scale a real value
12574 @cindex real number, scale
12575 @cindex floating point, scale
12578 @item @emph{Description}:
12579 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
12581 @item @emph{Standard}:
12582 Fortran 90 and later
12584 @item @emph{Class}:
12587 @item @emph{Syntax}:
12588 @code{RESULT = SCALE(X, I)}
12590 @item @emph{Arguments}:
12591 @multitable @columnfractions .15 .70
12592 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
12593 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
12596 @item @emph{Return value}:
12597 The return value is of the same type and kind as @var{X}.
12598 Its value is @code{X * RADIX(X)**I}.
12600 @item @emph{Example}:
12603 real :: x = 178.1387e-4
12605 print *, scale(x,i), x*radix(x)**i
12606 end program test_scale
12614 @section @code{SCAN} --- Scan a string for the presence of a set of characters
12616 @cindex string, find subset
12619 @item @emph{Description}:
12620 Scans a @var{STRING} for any of the characters in a @var{SET}
12623 If @var{BACK} is either absent or equals @code{FALSE}, this function
12624 returns the position of the leftmost character of @var{STRING} that is
12625 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
12626 is returned. If no character of @var{SET} is found in @var{STRING}, the
12629 @item @emph{Standard}:
12630 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
12632 @item @emph{Class}:
12635 @item @emph{Syntax}:
12636 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
12638 @item @emph{Arguments}:
12639 @multitable @columnfractions .15 .70
12640 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
12641 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
12642 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
12643 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12644 expression indicating the kind parameter of the result.
12647 @item @emph{Return value}:
12648 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12649 @var{KIND} is absent, the return value is of default integer kind.
12651 @item @emph{Example}:
12654 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
12655 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
12656 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
12660 @item @emph{See also}:
12661 @ref{INDEX intrinsic}, @gol
12668 @section @code{SECNDS} --- Time function
12670 @cindex time, elapsed
12671 @cindex elapsed time
12674 @item @emph{Description}:
12675 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
12676 @var{X} is a reference time, also in seconds. If this is zero, the time in
12677 seconds from midnight is returned. This function is non-standard and its
12678 use is discouraged.
12680 @item @emph{Standard}:
12683 @item @emph{Class}:
12686 @item @emph{Syntax}:
12687 @code{RESULT = SECNDS (X)}
12689 @item @emph{Arguments}:
12690 @multitable @columnfractions .15 .70
12691 @item @var{T} @tab Shall be of type @code{REAL(4)}.
12692 @item @var{X} @tab Shall be of type @code{REAL(4)}.
12695 @item @emph{Return value}:
12698 @item @emph{Example}:
12700 program test_secnds
12703 print *, secnds (0.0) ! seconds since midnight
12704 t1 = secnds (0.0) ! reference time
12705 do i = 1, 10000000 ! do something
12707 t2 = secnds (t1) ! elapsed time
12708 print *, "Something took ", t2, " seconds."
12709 end program test_secnds
12716 @section @code{SECOND} --- CPU time function
12718 @cindex time, elapsed
12719 @cindex elapsed time
12722 @item @emph{Description}:
12723 Returns a @code{REAL(4)} value representing the elapsed CPU time in
12724 seconds. This provides the same functionality as the standard
12725 @code{CPU_TIME} intrinsic, and is only included for backwards
12728 This intrinsic is provided in both subroutine and function forms;
12729 however, only one form can be used in any given program unit.
12731 @item @emph{Standard}:
12734 @item @emph{Class}:
12735 Subroutine, function
12737 @item @emph{Syntax}:
12738 @multitable @columnfractions .80
12739 @item @code{CALL SECOND(TIME)}
12740 @item @code{TIME = SECOND()}
12743 @item @emph{Arguments}:
12744 @multitable @columnfractions .15 .70
12745 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
12748 @item @emph{Return value}:
12749 In either syntax, @var{TIME} is set to the process's current runtime in
12752 @item @emph{See also}:
12759 @node SELECTED_CHAR_KIND
12760 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
12761 @fnindex SELECTED_CHAR_KIND
12762 @cindex character kind
12763 @cindex kind, character
12766 @item @emph{Description}:
12768 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
12769 set named @var{NAME}, if a character set with such a name is supported,
12770 or @math{-1} otherwise. Currently, supported character sets include
12771 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
12772 (Universal Character Set, UCS-4) which is commonly known as Unicode.
12774 @item @emph{Standard}:
12775 Fortran 2003 and later
12777 @item @emph{Class}:
12778 Transformational function
12780 @item @emph{Syntax}:
12781 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
12783 @item @emph{Arguments}:
12784 @multitable @columnfractions .15 .70
12785 @item @var{NAME} @tab Shall be a scalar and of the default character type.
12788 @item @emph{Example}:
12790 program character_kind
12791 use iso_fortran_env
12793 integer, parameter :: ascii = selected_char_kind ("ascii")
12794 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646')
12796 character(kind=ascii, len=26) :: alphabet
12797 character(kind=ucs4, len=30) :: hello_world
12799 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
12800 hello_world = ucs4_'Hello World and Ni Hao -- ' &
12801 // char (int (z'4F60'), ucs4) &
12802 // char (int (z'597D'), ucs4)
12804 write (*,*) alphabet
12806 open (output_unit, encoding='UTF-8')
12807 write (*,*) trim (hello_world)
12808 end program character_kind
12814 @node SELECTED_INT_KIND
12815 @section @code{SELECTED_INT_KIND} --- Choose integer kind
12816 @fnindex SELECTED_INT_KIND
12817 @cindex integer kind
12818 @cindex kind, integer
12821 @item @emph{Description}:
12822 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
12823 type that can represent all values ranging from @math{-10^R} (exclusive)
12824 to @math{10^R} (exclusive). If there is no integer kind that accommodates
12825 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
12827 @item @emph{Standard}:
12828 Fortran 90 and later
12830 @item @emph{Class}:
12831 Transformational function
12833 @item @emph{Syntax}:
12834 @code{RESULT = SELECTED_INT_KIND(R)}
12836 @item @emph{Arguments}:
12837 @multitable @columnfractions .15 .70
12838 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
12841 @item @emph{Example}:
12843 program large_integers
12844 integer,parameter :: k5 = selected_int_kind(5)
12845 integer,parameter :: k15 = selected_int_kind(15)
12846 integer(kind=k5) :: i5
12847 integer(kind=k15) :: i15
12849 print *, huge(i5), huge(i15)
12851 ! The following inequalities are always true
12852 print *, huge(i5) >= 10_k5**5-1
12853 print *, huge(i15) >= 10_k15**15-1
12854 end program large_integers
12860 @node SELECTED_REAL_KIND
12861 @section @code{SELECTED_REAL_KIND} --- Choose real kind
12862 @fnindex SELECTED_REAL_KIND
12865 @cindex radix, real
12868 @item @emph{Description}:
12869 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
12870 with decimal precision of at least @code{P} digits, exponent range of
12871 at least @code{R}, and with a radix of @code{RADIX}.
12873 @item @emph{Standard}:
12874 Fortran 90 and later, with @code{RADIX} Fortran 2008 or later
12876 @item @emph{Class}:
12877 Transformational function
12879 @item @emph{Syntax}:
12880 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
12882 @item @emph{Arguments}:
12883 @multitable @columnfractions .15 .70
12884 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12885 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12886 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12888 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
12889 be present; since Fortran 2008, they are assumed to be zero if absent.
12891 @item @emph{Return value}:
12893 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
12894 a real data type with decimal precision of at least @code{P} digits, a
12895 decimal exponent range of at least @code{R}, and with the requested
12896 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
12897 any radix can be returned. If more than one real data type meet the
12898 criteria, the kind of the data type with the smallest decimal precision
12899 is returned. If no real data type matches the criteria, the result is
12901 @item -1 if the processor does not support a real data type with a
12902 precision greater than or equal to @code{P}, but the @code{R} and
12903 @code{RADIX} requirements can be fulfilled
12904 @item -2 if the processor does not support a real type with an exponent
12905 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
12907 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
12909 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
12911 @item -5 if there is no real type with the given @code{RADIX}
12914 @item @emph{Example}:
12917 integer,parameter :: p6 = selected_real_kind(6)
12918 integer,parameter :: p10r100 = selected_real_kind(10,100)
12919 integer,parameter :: r400 = selected_real_kind(r=400)
12921 real(kind=p10r100) :: y
12922 real(kind=r400) :: z
12924 print *, precision(x), range(x)
12925 print *, precision(y), range(y)
12926 print *, precision(z), range(z)
12927 end program real_kinds
12929 @item @emph{See also}:
12930 @ref{PRECISION}, @gol
12938 @section @code{SET_EXPONENT} --- Set the exponent of the model
12939 @fnindex SET_EXPONENT
12940 @cindex real number, set exponent
12941 @cindex floating point, set exponent
12944 @item @emph{Description}:
12945 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
12946 is that that of @var{X} and whose exponent part is @var{I}.
12948 @item @emph{Standard}:
12949 Fortran 90 and later
12951 @item @emph{Class}:
12954 @item @emph{Syntax}:
12955 @code{RESULT = SET_EXPONENT(X, I)}
12957 @item @emph{Arguments}:
12958 @multitable @columnfractions .15 .70
12959 @item @var{X} @tab Shall be of type @code{REAL}.
12960 @item @var{I} @tab Shall be of type @code{INTEGER}.
12963 @item @emph{Return value}:
12964 The return value is of the same type and kind as @var{X}.
12965 The real number whose fractional part
12966 is that that of @var{X} and whose exponent part if @var{I} is returned;
12967 it is @code{FRACTION(X) * RADIX(X)**I}.
12969 @item @emph{Example}:
12971 PROGRAM test_setexp
12972 REAL :: x = 178.1387e-4
12974 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
12983 @section @code{SHAPE} --- Determine the shape of an array
12985 @cindex array, shape
12988 @item @emph{Description}:
12989 Determines the shape of an array.
12991 @item @emph{Standard}:
12992 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
12994 @item @emph{Class}:
12997 @item @emph{Syntax}:
12998 @code{RESULT = SHAPE(SOURCE [, KIND])}
13000 @item @emph{Arguments}:
13001 @multitable @columnfractions .15 .70
13002 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
13003 If @var{SOURCE} is a pointer it must be associated and allocatable
13004 arrays must be allocated.
13005 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
13006 expression indicating the kind parameter of the result.
13009 @item @emph{Return value}:
13010 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
13011 has dimensions. The elements of the resulting array correspond to the extend
13012 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
13013 the result is the rank one array of size zero. If @var{KIND} is absent, the
13014 return value has the default integer kind otherwise the specified kind.
13016 @item @emph{Example}:
13019 INTEGER, DIMENSION(-1:1, -1:2) :: A
13020 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
13021 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
13025 @item @emph{See also}:
13026 @ref{RESHAPE}, @gol
13033 @section @code{SHIFTA} --- Right shift with fill
13035 @cindex bits, shift right
13036 @cindex shift, right with fill
13039 @item @emph{Description}:
13040 @code{SHIFTA} returns a value corresponding to @var{I} with all of the
13041 bits shifted right by @var{SHIFT} places. @var{SHIFT} that be
13042 nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
13043 the result value is undefined. Bits shifted out from the right end
13044 are lost. The fill is arithmetic: the bits shifted in from the left
13045 end are equal to the leftmost bit, which in two's complement
13046 representation is the sign bit.
13048 @item @emph{Standard}:
13049 Fortran 2008 and later
13051 @item @emph{Class}:
13054 @item @emph{Syntax}:
13055 @code{RESULT = SHIFTA(I, SHIFT)}
13057 @item @emph{Arguments}:
13058 @multitable @columnfractions .15 .70
13059 @item @var{I} @tab The type shall be @code{INTEGER}.
13060 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
13063 @item @emph{Return value}:
13064 The return value is of type @code{INTEGER} and of the same kind as
13067 @item @emph{See also}:
13075 @section @code{SHIFTL} --- Left shift
13077 @cindex bits, shift left
13078 @cindex shift, left
13081 @item @emph{Description}:
13082 @code{SHIFTL} returns a value corresponding to @var{I} with all of the
13083 bits shifted left by @var{SHIFT} places. @var{SHIFT} shall be
13084 nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
13085 the result value is undefined. Bits shifted out from the left end are
13086 lost, and bits shifted in from the right end are set to 0.
13088 @item @emph{Standard}:
13089 Fortran 2008 and later
13091 @item @emph{Class}:
13094 @item @emph{Syntax}:
13095 @code{RESULT = SHIFTL(I, SHIFT)}
13097 @item @emph{Arguments}:
13098 @multitable @columnfractions .15 .70
13099 @item @var{I} @tab The type shall be @code{INTEGER}.
13100 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
13103 @item @emph{Return value}:
13104 The return value is of type @code{INTEGER} and of the same kind as
13107 @item @emph{See also}:
13115 @section @code{SHIFTR} --- Right shift
13117 @cindex bits, shift right
13118 @cindex shift, right
13121 @item @emph{Description}:
13122 @code{SHIFTR} returns a value corresponding to @var{I} with all of the
13123 bits shifted right by @var{SHIFT} places. @var{SHIFT} shall be
13124 nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
13125 the result value is undefined. Bits shifted out from the right end
13126 are lost, and bits shifted in from the left end are set to 0.
13128 @item @emph{Standard}:
13129 Fortran 2008 and later
13131 @item @emph{Class}:
13134 @item @emph{Syntax}:
13135 @code{RESULT = SHIFTR(I, SHIFT)}
13137 @item @emph{Arguments}:
13138 @multitable @columnfractions .15 .70
13139 @item @var{I} @tab The type shall be @code{INTEGER}.
13140 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
13143 @item @emph{Return value}:
13144 The return value is of type @code{INTEGER} and of the same kind as
13147 @item @emph{See also}:
13155 @section @code{SIGN} --- Sign copying function
13159 @cindex sign copying
13162 @item @emph{Description}:
13163 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
13165 @item @emph{Standard}:
13166 Fortran 77 and later
13168 @item @emph{Class}:
13171 @item @emph{Syntax}:
13172 @code{RESULT = SIGN(A, B)}
13174 @item @emph{Arguments}:
13175 @multitable @columnfractions .15 .70
13176 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
13177 @item @var{B} @tab Shall be of the same type and kind as @var{A}.
13180 @item @emph{Return value}:
13181 The kind of the return value is that of @var{A} and @var{B}.
13182 If @math{B\ge 0} then the result is @code{ABS(A)}, else
13183 it is @code{-ABS(A)}.
13185 @item @emph{Example}:
13188 print *, sign(-12,1)
13189 print *, sign(-12,0)
13190 print *, sign(-12,-1)
13192 print *, sign(-12.,1.)
13193 print *, sign(-12.,0.)
13194 print *, sign(-12.,-1.)
13195 end program test_sign
13198 @item @emph{Specific names}:
13199 @multitable @columnfractions .20 .20 .20 .25
13200 @item Name @tab Arguments @tab Return type @tab Standard
13201 @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab Fortran 77 and later
13202 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab Fortran 77 and later
13203 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab Fortran 77 and later
13210 @section @code{SIGNAL} --- Signal handling subroutine (or function)
13212 @cindex system, signal handling
13215 @item @emph{Description}:
13216 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
13217 @var{HANDLER} to be executed with a single integer argument when signal
13218 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
13219 turn off handling of signal @var{NUMBER} or revert to its default
13220 action. See @code{signal(2)}.
13222 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
13223 is supplied, it is set to the value returned by @code{signal(2)}.
13225 @item @emph{Standard}:
13228 @item @emph{Class}:
13229 Subroutine, function
13231 @item @emph{Syntax}:
13232 @multitable @columnfractions .80
13233 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
13234 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
13237 @item @emph{Arguments}:
13238 @multitable @columnfractions .15 .70
13239 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
13240 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
13241 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
13242 @code{INTEGER}. It is @code{INTENT(IN)}.
13243 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
13244 integer. It has @code{INTENT(OUT)}.
13246 @c TODO: What should the interface of the handler be? Does it take arguments?
13248 @item @emph{Return value}:
13249 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
13251 @item @emph{Example}:
13253 program test_signal
13255 external handler_print
13257 call signal (12, handler_print)
13258 call signal (10, 1)
13261 end program test_signal
13268 @section @code{SIN} --- Sine function
13274 @cindex trigonometric function, sine
13278 @item @emph{Description}:
13279 @code{SIN(X)} computes the sine of @var{X}.
13281 @item @emph{Standard}:
13282 Fortran 77 and later
13284 @item @emph{Class}:
13287 @item @emph{Syntax}:
13288 @code{RESULT = SIN(X)}
13290 @item @emph{Arguments}:
13291 @multitable @columnfractions .15 .70
13292 @item @var{X} @tab The type shall be @code{REAL} or
13296 @item @emph{Return value}:
13297 The return value has same type and kind as @var{X}.
13299 @item @emph{Example}:
13304 end program test_sin
13307 @item @emph{Specific names}:
13308 @multitable @columnfractions .20 .20 .20 .25
13309 @item Name @tab Argument @tab Return type @tab Standard
13310 @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
13311 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
13312 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
13313 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13314 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13317 @item @emph{See also}:
13318 Inverse function: @gol
13320 Degrees function: @gol
13327 @section @code{SIND} --- Sine function, degrees
13333 @cindex trigonometric function, sine, degrees
13334 @cindex sine, degrees
13337 @item @emph{Description}:
13338 @code{SIND(X)} computes the sine of @var{X} in degrees.
13340 This function is for compatibility only and should be avoided in favor of
13341 standard constructs wherever possible.
13343 @item @emph{Standard}:
13344 GNU extension, enabled with @option{-fdec-math}.
13346 @item @emph{Class}:
13349 @item @emph{Syntax}:
13350 @code{RESULT = SIND(X)}
13352 @item @emph{Arguments}:
13353 @multitable @columnfractions .15 .70
13354 @item @var{X} @tab The type shall be @code{REAL} or
13358 @item @emph{Return value}:
13359 The return value has same type and kind as @var{X}, and its value is in degrees.
13361 @item @emph{Example}:
13366 end program test_sind
13369 @item @emph{Specific names}:
13370 @multitable @columnfractions .20 .20 .20 .25
13371 @item Name @tab Argument @tab Return type @tab Standard
13372 @item @code{SIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
13373 @item @code{DSIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
13374 @item @code{CSIND(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU extension
13375 @item @code{ZSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13376 @item @code{CDSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13379 @item @emph{See also}:
13380 Inverse function: @gol
13382 Radians function: @gol
13389 @section @code{SINH} --- Hyperbolic sine function
13392 @cindex hyperbolic sine
13393 @cindex hyperbolic function, sine
13394 @cindex sine, hyperbolic
13397 @item @emph{Description}:
13398 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
13400 @item @emph{Standard}:
13401 Fortran 90 and later, for a complex argument Fortran 2008 or later, has
13404 @item @emph{Class}:
13407 @item @emph{Syntax}:
13408 @code{RESULT = SINH(X)}
13410 @item @emph{Arguments}:
13411 @multitable @columnfractions .15 .70
13412 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13415 @item @emph{Return value}:
13416 The return value has same type and kind as @var{X}.
13418 @item @emph{Example}:
13421 real(8) :: x = - 1.0_8
13423 end program test_sinh
13426 @item @emph{Specific names}:
13427 @multitable @columnfractions .20 .20 .20 .25
13428 @item Name @tab Argument @tab Return type @tab Standard
13429 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 90 and later
13432 @item @emph{See also}:
13439 @section @code{SIZE} --- Determine the size of an array
13441 @cindex array, size
13442 @cindex array, number of elements
13443 @cindex array, count elements
13446 @item @emph{Description}:
13447 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
13448 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
13450 @item @emph{Standard}:
13451 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
13453 @item @emph{Class}:
13456 @item @emph{Syntax}:
13457 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
13459 @item @emph{Arguments}:
13460 @multitable @columnfractions .15 .70
13461 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
13462 a pointer it must be associated and allocatable arrays must be allocated.
13463 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
13464 and its value shall be in the range from 1 to n, where n equals the rank
13466 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
13467 expression indicating the kind parameter of the result.
13470 @item @emph{Return value}:
13471 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
13472 @var{KIND} is absent, the return value is of default integer kind.
13474 @item @emph{Example}:
13477 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
13481 @item @emph{See also}:
13488 @section @code{SIZEOF} --- Size in bytes of an expression
13490 @cindex expression size
13491 @cindex size of an expression
13494 @item @emph{Description}:
13495 @code{SIZEOF(X)} calculates the number of bytes of storage the
13496 expression @code{X} occupies.
13498 @item @emph{Standard}:
13501 @item @emph{Class}:
13504 @item @emph{Syntax}:
13505 @code{N = SIZEOF(X)}
13507 @item @emph{Arguments}:
13508 @multitable @columnfractions .15 .70
13509 @item @var{X} @tab The argument shall be of any type, rank or shape.
13512 @item @emph{Return value}:
13513 The return value is of type integer and of the system-dependent kind
13514 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
13515 number of bytes occupied by the argument. If the argument has the
13516 @code{POINTER} attribute, the number of bytes of the storage area pointed
13517 to is returned. If the argument is of a derived type with @code{POINTER}
13518 or @code{ALLOCATABLE} components, the return value does not account for
13519 the sizes of the data pointed to by these components. If the argument is
13520 polymorphic, the size according to the dynamic type is returned. The argument
13521 may not be a procedure or procedure pointer. Note that the code assumes for
13522 arrays that those are contiguous; for contiguous arrays, it returns the
13523 storage or an array element multiplied by the size of the array.
13525 @item @emph{Example}:
13529 print *, (sizeof(s)/sizeof(r) == 5)
13532 The example will print @code{.TRUE.} unless you are using a platform
13533 where default @code{REAL} variables are unusually padded.
13535 @item @emph{See also}:
13536 @ref{C_SIZEOF}, @gol
13542 @section @code{SLEEP} --- Sleep for the specified number of seconds
13544 @cindex delayed execution
13547 @item @emph{Description}:
13548 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
13550 @item @emph{Standard}:
13553 @item @emph{Class}:
13556 @item @emph{Syntax}:
13557 @code{CALL SLEEP(SECONDS)}
13559 @item @emph{Arguments}:
13560 @multitable @columnfractions .15 .70
13561 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
13564 @item @emph{Example}:
13575 @section @code{SPACING} --- Smallest distance between two numbers of a given type
13577 @cindex real number, relative spacing
13578 @cindex floating point, relative spacing
13581 @item @emph{Description}:
13582 Determines the distance between the argument @var{X} and the nearest
13583 adjacent number of the same type.
13585 @item @emph{Standard}:
13586 Fortran 90 and later
13588 @item @emph{Class}:
13591 @item @emph{Syntax}:
13592 @code{RESULT = SPACING(X)}
13594 @item @emph{Arguments}:
13595 @multitable @columnfractions .15 .70
13596 @item @var{X} @tab Shall be of type @code{REAL}.
13599 @item @emph{Return value}:
13600 The result is of the same type as the input argument @var{X}.
13602 @item @emph{Example}:
13604 PROGRAM test_spacing
13605 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
13606 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
13608 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
13609 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
13613 @item @emph{See also}:
13620 @section @code{SPREAD} --- Add a dimension to an array
13622 @cindex array, increase dimension
13623 @cindex array, duplicate elements
13624 @cindex array, duplicate dimensions
13627 @item @emph{Description}:
13628 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
13629 dimension @var{DIM}.
13631 @item @emph{Standard}:
13632 Fortran 90 and later
13634 @item @emph{Class}:
13635 Transformational function
13637 @item @emph{Syntax}:
13638 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
13640 @item @emph{Arguments}:
13641 @multitable @columnfractions .15 .70
13642 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
13643 a rank less than seven.
13644 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
13645 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
13646 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
13649 @item @emph{Return value}:
13650 The result is an array of the same type as @var{SOURCE} and has rank n+1
13651 where n equals the rank of @var{SOURCE}.
13653 @item @emph{Example}:
13655 PROGRAM test_spread
13656 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
13657 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
13658 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
13662 @item @emph{See also}:
13669 @section @code{SQRT} --- Square-root function
13676 @cindex square-root
13679 @item @emph{Description}:
13680 @code{SQRT(X)} computes the square root of @var{X}.
13682 @item @emph{Standard}:
13683 Fortran 77 and later
13685 @item @emph{Class}:
13688 @item @emph{Syntax}:
13689 @code{RESULT = SQRT(X)}
13691 @item @emph{Arguments}:
13692 @multitable @columnfractions .15 .70
13693 @item @var{X} @tab The type shall be @code{REAL} or
13697 @item @emph{Return value}:
13698 The return value is of type @code{REAL} or @code{COMPLEX}.
13699 The kind type parameter is the same as @var{X}.
13701 @item @emph{Example}:
13704 real(8) :: x = 2.0_8
13705 complex :: z = (1.0, 2.0)
13708 end program test_sqrt
13711 @item @emph{Specific names}:
13712 @multitable @columnfractions .20 .20 .20 .25
13713 @item Name @tab Argument @tab Return type @tab Standard
13714 @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
13715 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
13716 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
13717 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13718 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13725 @section @code{SRAND} --- Reinitialize the random number generator
13727 @cindex random number generation, seeding
13728 @cindex seeding a random number generator
13731 @item @emph{Description}:
13732 @code{SRAND} reinitializes the pseudo-random number generator
13733 called by @code{RAND} and @code{IRAND}. The new seed used by the
13734 generator is specified by the required argument @var{SEED}.
13736 @item @emph{Standard}:
13739 @item @emph{Class}:
13742 @item @emph{Syntax}:
13743 @code{CALL SRAND(SEED)}
13745 @item @emph{Arguments}:
13746 @multitable @columnfractions .15 .70
13747 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
13750 @item @emph{Return value}:
13751 Does not return anything.
13753 @item @emph{Example}:
13754 See @code{RAND} and @code{IRAND} for examples.
13756 @item @emph{Notes}:
13757 The Fortran standard specifies the intrinsic subroutines
13758 @code{RANDOM_SEED} to initialize the pseudo-random number
13759 generator and @code{RANDOM_NUMBER} to generate pseudo-random numbers.
13760 These subroutines should be used in new codes.
13762 Please note that in GNU Fortran, these two sets of intrinsics (@code{RAND},
13763 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
13764 @code{RANDOM_SEED} on the other hand) access two independent
13765 pseudo-random number generators.
13767 @item @emph{See also}:
13769 @ref{RANDOM_SEED}, @gol
13770 @ref{RANDOM_NUMBER}
13776 @section @code{STAT} --- Get file status
13778 @cindex file system, file status
13781 @item @emph{Description}:
13782 This function returns information about a file. No permissions are required on
13783 the file itself, but execute (search) permission is required on all of the
13784 directories in path that lead to the file.
13786 The elements that are obtained and stored in the array @code{VALUES}:
13787 @multitable @columnfractions .15 .70
13788 @item @code{VALUES(1)} @tab Device ID
13789 @item @code{VALUES(2)} @tab Inode number
13790 @item @code{VALUES(3)} @tab File mode
13791 @item @code{VALUES(4)} @tab Number of links
13792 @item @code{VALUES(5)} @tab Owner's uid
13793 @item @code{VALUES(6)} @tab Owner's gid
13794 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
13795 @item @code{VALUES(8)} @tab File size (bytes)
13796 @item @code{VALUES(9)} @tab Last access time
13797 @item @code{VALUES(10)} @tab Last modification time
13798 @item @code{VALUES(11)} @tab Last file status change time
13799 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
13800 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
13803 Not all these elements are relevant on all systems.
13804 If an element is not relevant, it is returned as 0.
13806 This intrinsic is provided in both subroutine and function forms; however,
13807 only one form can be used in any given program unit.
13809 @item @emph{Standard}:
13812 @item @emph{Class}:
13813 Subroutine, function
13815 @item @emph{Syntax}:
13816 @multitable @columnfractions .80
13817 @item @code{CALL STAT(NAME, VALUES [, STATUS])}
13818 @item @code{STATUS = STAT(NAME, VALUES)}
13821 @item @emph{Arguments}:
13822 @multitable @columnfractions .15 .70
13823 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
13824 default kind and a valid path within the file system.
13825 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
13826 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
13827 on success and a system specific error code otherwise.
13830 @item @emph{Example}:
13833 INTEGER, DIMENSION(13) :: buff
13836 CALL STAT("/etc/passwd", buff, status)
13838 IF (status == 0) THEN
13839 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
13840 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
13841 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
13842 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
13843 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
13844 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
13845 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
13846 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
13847 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
13848 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
13849 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
13850 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
13851 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
13856 @item @emph{See also}:
13857 To stat an open file: @gol
13859 To stat a link: @gol
13866 @section @code{STORAGE_SIZE} --- Storage size in bits
13867 @fnindex STORAGE_SIZE
13868 @cindex storage size
13871 @item @emph{Description}:
13872 Returns the storage size of argument @var{A} in bits.
13873 @item @emph{Standard}:
13874 Fortran 2008 and later
13875 @item @emph{Class}:
13877 @item @emph{Syntax}:
13878 @code{RESULT = STORAGE_SIZE(A [, KIND])}
13880 @item @emph{Arguments}:
13881 @multitable @columnfractions .15 .70
13882 @item @var{A} @tab Shall be a scalar or array of any type.
13883 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
13886 @item @emph{Return Value}:
13887 The result is a scalar integer with the kind type parameter specified by KIND
13888 (or default integer type if KIND is missing). The result value is the size
13889 expressed in bits for an element of an array that has the dynamic type and type
13892 @item @emph{See also}:
13893 @ref{C_SIZEOF}, @gol
13900 @section @code{SUM} --- Sum of array elements
13903 @cindex array, add elements
13904 @cindex array, conditionally add elements
13905 @cindex sum array elements
13908 @item @emph{Description}:
13909 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
13910 the corresponding element in @var{MASK} is @code{TRUE}.
13912 @item @emph{Standard}:
13913 Fortran 90 and later
13915 @item @emph{Class}:
13916 Transformational function
13918 @item @emph{Syntax}:
13919 @multitable @columnfractions .80
13920 @item @code{RESULT = SUM(ARRAY[, MASK])}
13921 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
13924 @item @emph{Arguments}:
13925 @multitable @columnfractions .15 .70
13926 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
13927 @code{REAL} or @code{COMPLEX}.
13928 @item @var{DIM} @tab (Optional) shall be a scalar of type
13929 @code{INTEGER} with a value in the range from 1 to n, where n
13930 equals the rank of @var{ARRAY}.
13931 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
13932 and either be a scalar or an array of the same shape as @var{ARRAY}.
13935 @item @emph{Return value}:
13936 The result is of the same type as @var{ARRAY}.
13938 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
13939 is returned. Otherwise, an array of rank n-1, where n equals the rank of
13940 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
13941 dropped is returned.
13943 @item @emph{Example}:
13946 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
13947 print *, SUM(x) ! all elements, sum = 15
13948 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
13952 @item @emph{See also}:
13959 @section @code{SYMLNK} --- Create a symbolic link
13961 @cindex file system, create link
13962 @cindex file system, soft link
13965 @item @emph{Description}:
13966 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
13967 character (@code{CHAR(0)}) can be used to mark the end of the names in
13968 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
13969 names are ignored. If the @var{STATUS} argument is supplied, it
13970 contains 0 on success or a nonzero error code upon return; see
13971 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
13972 @code{ENOSYS} is returned.
13974 This intrinsic is provided in both subroutine and function forms;
13975 however, only one form can be used in any given program unit.
13977 @item @emph{Standard}:
13980 @item @emph{Class}:
13981 Subroutine, function
13983 @item @emph{Syntax}:
13984 @multitable @columnfractions .80
13985 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
13986 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
13989 @item @emph{Arguments}:
13990 @multitable @columnfractions .15 .70
13991 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
13992 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
13993 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
13996 @item @emph{See also}:
14004 @section @code{SYSTEM} --- Execute a shell command
14006 @cindex system, system call
14009 @item @emph{Description}:
14010 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
14011 argument @var{STATUS} is present, it contains the value returned by
14012 @code{system(3)}, which is presumably 0 if the shell command succeeded.
14013 Note that which shell is used to invoke the command is system-dependent
14014 and environment-dependent.
14016 This intrinsic is provided in both subroutine and function forms;
14017 however, only one form can be used in any given program unit.
14019 Note that the @code{system} function need not be thread-safe. It is
14020 the responsibility of the user to ensure that @code{system} is not
14021 called concurrently.
14023 @item @emph{Standard}:
14026 @item @emph{Class}:
14027 Subroutine, function
14029 @item @emph{Syntax}:
14030 @multitable @columnfractions .80
14031 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
14032 @item @code{STATUS = SYSTEM(COMMAND)}
14035 @item @emph{Arguments}:
14036 @multitable @columnfractions .15 .70
14037 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
14038 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
14041 @item @emph{See also}:
14042 @ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
14043 and should considered in new code for future portability.
14049 @section @code{SYSTEM_CLOCK} --- Time function
14050 @fnindex SYSTEM_CLOCK
14051 @cindex time, clock ticks
14052 @cindex clock ticks
14055 @item @emph{Description}:
14056 Determines the @var{COUNT} of a processor clock since an unspecified
14057 time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines
14058 the number of clock ticks per second. If the platform supports a
14059 monotonic clock, that clock is used and can, depending on the platform
14060 clock implementation, provide up to nanosecond resolution. If a
14061 monotonic clock is not available, the implementation falls back to a
14064 @var{COUNT_RATE} is system dependent and can vary depending on the kind of
14065 the arguments. For @var{kind=4} arguments (and smaller integer kinds),
14066 @var{COUNT} represents milliseconds, while for @var{kind=8} arguments (and
14067 larger integer kinds), @var{COUNT} typically represents micro- or
14068 nanoseconds depending on resolution of the underlying platform clock.
14069 @var{COUNT_MAX} usually equals @code{HUGE(COUNT_MAX)}. Note that the
14070 millisecond resolution of the @var{kind=4} version implies that the
14071 @var{COUNT} will wrap around in roughly 25 days. In order to avoid issues
14072 with the wrap around and for more precise timing, please use the
14073 @var{kind=8} version.
14075 If there is no clock, or querying the clock fails, @var{COUNT} is set
14076 to @code{-HUGE(COUNT)}, and @var{COUNT_RATE} and @var{COUNT_MAX} are
14079 When running on a platform using the GNU C library (glibc) version
14080 2.16 or older, or a derivative thereof, the high resolution monotonic
14081 clock is available only when linking with the @var{rt} library. This
14082 can be done explicitly by adding the @code{-lrt} flag when linking the
14083 application, but is also done implicitly when using OpenMP.
14085 On the Windows platform, the version with @var{kind=4} arguments uses
14086 the @code{GetTickCount} function, whereas the @var{kind=8} version
14087 uses @code{QueryPerformanceCounter} and
14088 @code{QueryPerformanceCounterFrequency}. For more information, and
14089 potential caveats, please see the platform documentation.
14091 @item @emph{Standard}:
14092 Fortran 90 and later
14094 @item @emph{Class}:
14097 @item @emph{Syntax}:
14098 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
14100 @item @emph{Arguments}:
14101 @multitable @columnfractions .20 .65
14102 @item @var{COUNT} @tab (Optional) shall be a scalar of type
14103 @code{INTEGER} with @code{INTENT(OUT)}.
14104 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type
14105 @code{INTEGER} or @code{REAL}, with @code{INTENT(OUT)}.
14106 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type
14107 @code{INTEGER} with @code{INTENT(OUT)}.
14110 @item @emph{Example}:
14112 PROGRAM test_system_clock
14113 INTEGER :: count, count_rate, count_max
14114 CALL SYSTEM_CLOCK(count, count_rate, count_max)
14115 WRITE(*,*) count, count_rate, count_max
14119 @item @emph{See also}:
14120 @ref{DATE_AND_TIME}, @gol
14127 @section @code{TAN} --- Tangent function
14130 @cindex trigonometric function, tangent
14134 @item @emph{Description}:
14135 @code{TAN(X)} computes the tangent of @var{X}.
14137 @item @emph{Standard}:
14138 Fortran 77 and later, for a complex argument Fortran 2008 or later
14140 @item @emph{Class}:
14143 @item @emph{Syntax}:
14144 @code{RESULT = TAN(X)}
14146 @item @emph{Arguments}:
14147 @multitable @columnfractions .15 .70
14148 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
14151 @item @emph{Return value}:
14152 The return value has same type and kind as @var{X}, and its value is in radians.
14154 @item @emph{Example}:
14157 real(8) :: x = 0.165_8
14159 end program test_tan
14162 @item @emph{Specific names}:
14163 @multitable @columnfractions .20 .20 .20 .25
14164 @item Name @tab Argument @tab Return type @tab Standard
14165 @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
14166 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
14169 @item @emph{See also}:
14170 Inverse function: @gol
14172 Degrees function: @gol
14179 @section @code{TAND} --- Tangent function, degrees
14182 @cindex trigonometric function, tangent, degrees
14183 @cindex tangent, degrees
14186 @item @emph{Description}:
14187 @code{TAND(X)} computes the tangent of @var{X} in degrees.
14189 This function is for compatibility only and should be avoided in favor of
14190 standard constructs wherever possible.
14192 @item @emph{Standard}:
14193 GNU extension, enabled with @option{-fdec-math}.
14195 @item @emph{Class}:
14198 @item @emph{Syntax}:
14199 @code{RESULT = TAND(X)}
14201 @item @emph{Arguments}:
14202 @multitable @columnfractions .15 .70
14203 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
14206 @item @emph{Return value}:
14207 The return value has same type and kind as @var{X}, and its value is in degrees.
14209 @item @emph{Example}:
14212 real(8) :: x = 0.165_8
14214 end program test_tand
14217 @item @emph{Specific names}:
14218 @multitable @columnfractions .20 .20 .20 .25
14219 @item Name @tab Argument @tab Return type @tab Standard
14220 @item @code{TAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
14221 @item @code{DTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
14224 @item @emph{See also}:
14225 Inverse function: @gol
14227 Radians function: @gol
14234 @section @code{TANH} --- Hyperbolic tangent function
14237 @cindex hyperbolic tangent
14238 @cindex hyperbolic function, tangent
14239 @cindex tangent, hyperbolic
14242 @item @emph{Description}:
14243 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
14245 @item @emph{Standard}:
14246 Fortran 77 and later, for a complex argument Fortran 2008 or later
14248 @item @emph{Class}:
14251 @item @emph{Syntax}:
14254 @item @emph{Arguments}:
14255 @multitable @columnfractions .15 .70
14256 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
14259 @item @emph{Return value}:
14260 The return value has same type and kind as @var{X}. If @var{X} is
14261 complex, the imaginary part of the result is in radians. If @var{X}
14262 is @code{REAL}, the return value lies in the range
14263 @math{ - 1 \leq tanh(x) \leq 1 }.
14265 @item @emph{Example}:
14268 real(8) :: x = 2.1_8
14270 end program test_tanh
14273 @item @emph{Specific names}:
14274 @multitable @columnfractions .20 .20 .20 .25
14275 @item Name @tab Argument @tab Return type @tab Standard
14276 @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
14277 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
14280 @item @emph{See also}:
14287 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
14288 @fnindex THIS_IMAGE
14289 @cindex coarray, @code{THIS_IMAGE}
14290 @cindex images, index of this image
14293 @item @emph{Description}:
14294 Returns the cosubscript for this image.
14296 @item @emph{Standard}:
14297 Fortran 2008 and later. With @var{DISTANCE} argument,
14298 Technical Specification (TS) 18508 or later
14300 @item @emph{Class}:
14301 Transformational function
14303 @item @emph{Syntax}:
14304 @multitable @columnfractions .80
14305 @item @code{RESULT = THIS_IMAGE()}
14306 @item @code{RESULT = THIS_IMAGE(DISTANCE)}
14307 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
14310 @item @emph{Arguments}:
14311 @multitable @columnfractions .15 .70
14312 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
14313 (not permitted together with @var{COARRAY}).
14314 @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
14315 present, required).
14316 @item @var{DIM} @tab default integer scalar (optional). If present,
14317 @var{DIM} shall be between one and the corank of @var{COARRAY}.
14321 @item @emph{Return value}:
14322 Default integer. If @var{COARRAY} is not present, it is scalar; if
14323 @var{DISTANCE} is not present or has value 0, its value is the image index on
14324 the invoking image for the current team, for values smaller or equal
14325 distance to the initial team, it returns the image index on the ancestor team
14326 which has a distance of @var{DISTANCE} from the invoking team. If
14327 @var{DISTANCE} is larger than the distance to the initial team, the image
14328 index of the initial team is returned. Otherwise when the @var{COARRAY} is
14329 present, if @var{DIM} is not present, a rank-1 array with corank elements is
14330 returned, containing the cosubscripts for @var{COARRAY} specifying the invoking
14331 image. If @var{DIM} is present, a scalar is returned, with the value of
14332 the @var{DIM} element of @code{THIS_IMAGE(COARRAY)}.
14334 @item @emph{Example}:
14336 INTEGER :: value[*]
14338 value = THIS_IMAGE()
14340 IF (THIS_IMAGE() == 1) THEN
14341 DO i = 1, NUM_IMAGES()
14342 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
14346 ! Check whether the current image is the initial image
14347 IF (THIS_IMAGE(HUGE(1)) /= THIS_IMAGE())
14348 error stop "something is rotten here"
14351 @item @emph{See also}:
14352 @ref{NUM_IMAGES}, @gol
14359 @section @code{TIME} --- Time function
14361 @cindex time, current
14362 @cindex current time
14365 @item @emph{Description}:
14366 Returns the current time encoded as an integer (in the manner of the
14367 function @code{time(3)} in the C standard library). This value is
14368 suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}.
14370 This intrinsic is not fully portable, such as to systems with 32-bit
14371 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
14372 the values returned by this intrinsic might be, or become, negative, or
14373 numerically less than previous values, during a single run of the
14376 See @ref{TIME8}, for information on a similar intrinsic that might be
14377 portable to more GNU Fortran implementations, though to fewer Fortran
14380 @item @emph{Standard}:
14383 @item @emph{Class}:
14386 @item @emph{Syntax}:
14387 @code{RESULT = TIME()}
14389 @item @emph{Return value}:
14390 The return value is a scalar of type @code{INTEGER(4)}.
14392 @item @emph{See also}:
14393 @ref{DATE_AND_TIME}, @gol
14404 @section @code{TIME8} --- Time function (64-bit)
14406 @cindex time, current
14407 @cindex current time
14410 @item @emph{Description}:
14411 Returns the current time encoded as an integer (in the manner of the
14412 function @code{time(3)} in the C standard library). This value is
14413 suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}.
14415 @emph{Warning:} this intrinsic does not increase the range of the timing
14416 values over that returned by @code{time(3)}. On a system with a 32-bit
14417 @code{time(3)}, @code{TIME8} will return a 32-bit value, even though
14418 it is converted to a 64-bit @code{INTEGER(8)} value. That means
14419 overflows of the 32-bit value can still occur. Therefore, the values
14420 returned by this intrinsic might be or become negative or numerically
14421 less than previous values during a single run of the compiled program.
14423 @item @emph{Standard}:
14426 @item @emph{Class}:
14429 @item @emph{Syntax}:
14430 @code{RESULT = TIME8()}
14432 @item @emph{Return value}:
14433 The return value is a scalar of type @code{INTEGER(8)}.
14435 @item @emph{See also}:
14436 @ref{DATE_AND_TIME}, @gol
14440 @ref{MCLOCK8}, @gol
14447 @section @code{TINY} --- Smallest positive number of a real kind
14449 @cindex limits, smallest number
14450 @cindex model representation, smallest number
14453 @item @emph{Description}:
14454 @code{TINY(X)} returns the smallest positive (non zero) number
14455 in the model of the type of @code{X}.
14457 @item @emph{Standard}:
14458 Fortran 90 and later
14460 @item @emph{Class}:
14463 @item @emph{Syntax}:
14464 @code{RESULT = TINY(X)}
14466 @item @emph{Arguments}:
14467 @multitable @columnfractions .15 .70
14468 @item @var{X} @tab Shall be of type @code{REAL}.
14471 @item @emph{Return value}:
14472 The return value is of the same type and kind as @var{X}
14474 @item @emph{Example}:
14475 See @code{HUGE} for an example.
14481 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
14486 @item @emph{Description}:
14487 @code{TRAILZ} returns the number of trailing zero bits of an integer.
14489 @item @emph{Standard}:
14490 Fortran 2008 and later
14492 @item @emph{Class}:
14495 @item @emph{Syntax}:
14496 @code{RESULT = TRAILZ(I)}
14498 @item @emph{Arguments}:
14499 @multitable @columnfractions .15 .70
14500 @item @var{I} @tab Shall be of type @code{INTEGER}.
14503 @item @emph{Return value}:
14504 The type of the return value is the default @code{INTEGER}.
14505 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
14507 @item @emph{Example}:
14509 PROGRAM test_trailz
14510 WRITE (*,*) TRAILZ(8) ! prints 3
14514 @item @emph{See also}:
14515 @ref{BIT_SIZE}, @gol
14524 @section @code{TRANSFER} --- Transfer bit patterns
14530 @item @emph{Description}:
14531 Interprets the bitwise representation of @var{SOURCE} in memory as if it
14532 is the representation of a variable or array of the same type and type
14533 parameters as @var{MOLD}.
14535 This is approximately equivalent to the C concept of @emph{casting} one
14538 @item @emph{Standard}:
14539 Fortran 90 and later
14541 @item @emph{Class}:
14542 Transformational function
14544 @item @emph{Syntax}:
14545 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
14547 @item @emph{Arguments}:
14548 @multitable @columnfractions .15 .70
14549 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
14550 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
14551 @item @var{SIZE} @tab (Optional) shall be a scalar of type
14555 @item @emph{Return value}:
14556 The result has the same type as @var{MOLD}, with the bit level
14557 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
14558 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
14559 but @var{MOLD} is an array (of any size or shape), the result is a one-
14560 dimensional array of the minimum length needed to contain the entirety
14561 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
14562 and @var{MOLD} is a scalar, the result is a scalar.
14564 If the bitwise representation of the result is longer than that of
14565 @var{SOURCE}, then the leading bits of the result correspond to those of
14566 @var{SOURCE} and any trailing bits are filled arbitrarily.
14568 When the resulting bit representation does not correspond to a valid
14569 representation of a variable of the same type as @var{MOLD}, the results
14570 are undefined, and subsequent operations on the result cannot be
14571 guaranteed to produce sensible behavior. For example, it is possible to
14572 create @code{LOGICAL} variables for which @code{@var{VAR}} and
14573 @code{.NOT.@var{VAR}} both appear to be true.
14575 @item @emph{Example}:
14577 PROGRAM test_transfer
14578 integer :: x = 2143289344
14579 print *, transfer(x, 1.0) ! prints "NaN" on i686
14587 @section @code{TRANSPOSE} --- Transpose an array of rank two
14589 @cindex array, transpose
14590 @cindex matrix, transpose
14594 @item @emph{Description}:
14595 Transpose an array of rank two. Element (i, j) of the result has the value
14596 @code{MATRIX(j, i)}, for all i, j.
14598 @item @emph{Standard}:
14599 Fortran 90 and later
14601 @item @emph{Class}:
14602 Transformational function
14604 @item @emph{Syntax}:
14605 @code{RESULT = TRANSPOSE(MATRIX)}
14607 @item @emph{Arguments}:
14608 @multitable @columnfractions .15 .70
14609 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
14612 @item @emph{Return value}:
14613 The result has the same type as @var{MATRIX}, and has shape
14614 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
14620 @section @code{TRIM} --- Remove trailing blank characters of a string
14622 @cindex string, remove trailing whitespace
14625 @item @emph{Description}:
14626 Removes trailing blank characters of a string.
14628 @item @emph{Standard}:
14629 Fortran 90 and later
14631 @item @emph{Class}:
14632 Transformational function
14634 @item @emph{Syntax}:
14635 @code{RESULT = TRIM(STRING)}
14637 @item @emph{Arguments}:
14638 @multitable @columnfractions .15 .70
14639 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
14642 @item @emph{Return value}:
14643 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
14644 less the number of trailing blanks.
14646 @item @emph{Example}:
14649 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
14650 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
14654 @item @emph{See also}:
14655 @ref{ADJUSTL}, @gol
14662 @section @code{TTYNAM} --- Get the name of a terminal device.
14664 @cindex system, terminal
14667 @item @emph{Description}:
14668 Get the name of a terminal device. For more information,
14669 see @code{ttyname(3)}.
14671 This intrinsic is provided in both subroutine and function forms;
14672 however, only one form can be used in any given program unit.
14674 @item @emph{Standard}:
14677 @item @emph{Class}:
14678 Subroutine, function
14680 @item @emph{Syntax}:
14681 @multitable @columnfractions .80
14682 @item @code{CALL TTYNAM(UNIT, NAME)}
14683 @item @code{NAME = TTYNAM(UNIT)}
14686 @item @emph{Arguments}:
14687 @multitable @columnfractions .15 .70
14688 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
14689 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
14692 @item @emph{Example}:
14694 PROGRAM test_ttynam
14697 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
14702 @item @emph{See also}:
14709 @section @code{UBOUND} --- Upper dimension bounds of an array
14711 @cindex array, upper bound
14714 @item @emph{Description}:
14715 Returns the upper bounds of an array, or a single upper bound
14716 along the @var{DIM} dimension.
14717 @item @emph{Standard}:
14718 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
14720 @item @emph{Class}:
14723 @item @emph{Syntax}:
14724 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
14726 @item @emph{Arguments}:
14727 @multitable @columnfractions .15 .70
14728 @item @var{ARRAY} @tab Shall be an array, of any type.
14729 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
14730 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
14731 expression indicating the kind parameter of the result.
14734 @item @emph{Return value}:
14735 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14736 @var{KIND} is absent, the return value is of default integer kind.
14737 If @var{DIM} is absent, the result is an array of the upper bounds of
14738 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
14739 corresponding to the upper bound of the array along that dimension. If
14740 @var{ARRAY} is an expression rather than a whole array or array
14741 structure component, or if it has a zero extent along the relevant
14742 dimension, the upper bound is taken to be the number of elements along
14743 the relevant dimension.
14745 @item @emph{See also}:
14753 @section @code{UCOBOUND} --- Upper codimension bounds of an array
14755 @cindex coarray, upper bound
14758 @item @emph{Description}:
14759 Returns the upper cobounds of a coarray, or a single upper cobound
14760 along the @var{DIM} codimension.
14761 @item @emph{Standard}:
14762 Fortran 2008 and later
14764 @item @emph{Class}:
14767 @item @emph{Syntax}:
14768 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
14770 @item @emph{Arguments}:
14771 @multitable @columnfractions .15 .70
14772 @item @var{ARRAY} @tab Shall be an coarray, of any type.
14773 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
14774 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
14775 expression indicating the kind parameter of the result.
14778 @item @emph{Return value}:
14779 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14780 @var{KIND} is absent, the return value is of default integer kind.
14781 If @var{DIM} is absent, the result is an array of the lower cobounds of
14782 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
14783 corresponding to the lower cobound of the array along that codimension.
14785 @item @emph{See also}:
14786 @ref{LCOBOUND}, @gol
14793 @section @code{UMASK} --- Set the file creation mask
14795 @cindex file system, file creation mask
14798 @item @emph{Description}:
14799 Sets the file creation mask to @var{MASK}. If called as a function, it
14800 returns the old value. If called as a subroutine and argument @var{OLD}
14801 if it is supplied, it is set to the old value. See @code{umask(2)}.
14803 @item @emph{Standard}:
14806 @item @emph{Class}:
14807 Subroutine, function
14809 @item @emph{Syntax}:
14810 @multitable @columnfractions .80
14811 @item @code{CALL UMASK(MASK [, OLD])}
14812 @item @code{OLD = UMASK(MASK)}
14815 @item @emph{Arguments}:
14816 @multitable @columnfractions .15 .70
14817 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
14818 @item @var{OLD} @tab (Optional) Shall be a scalar of type
14827 @section @code{UNLINK} --- Remove a file from the file system
14829 @cindex file system, remove file
14832 @item @emph{Description}:
14833 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
14834 used to mark the end of the name in @var{PATH}; otherwise, trailing
14835 blanks in the file name are ignored. If the @var{STATUS} argument is
14836 supplied, it contains 0 on success or a nonzero error code upon return;
14837 see @code{unlink(2)}.
14839 This intrinsic is provided in both subroutine and function forms;
14840 however, only one form can be used in any given program unit.
14842 @item @emph{Standard}:
14845 @item @emph{Class}:
14846 Subroutine, function
14848 @item @emph{Syntax}:
14849 @multitable @columnfractions .80
14850 @item @code{CALL UNLINK(PATH [, STATUS])}
14851 @item @code{STATUS = UNLINK(PATH)}
14854 @item @emph{Arguments}:
14855 @multitable @columnfractions .15 .70
14856 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
14857 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
14860 @item @emph{See also}:
14868 @section @code{UNPACK} --- Unpack an array of rank one into an array
14870 @cindex array, unpacking
14871 @cindex array, increase dimension
14872 @cindex array, scatter elements
14875 @item @emph{Description}:
14876 Store the elements of @var{VECTOR} in an array of higher rank.
14878 @item @emph{Standard}:
14879 Fortran 90 and later
14881 @item @emph{Class}:
14882 Transformational function
14884 @item @emph{Syntax}:
14885 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
14887 @item @emph{Arguments}:
14888 @multitable @columnfractions .15 .70
14889 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
14890 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
14891 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
14892 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
14893 the same shape as @var{MASK}.
14896 @item @emph{Return value}:
14897 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
14898 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
14900 @item @emph{Example}:
14902 PROGRAM test_unpack
14903 integer :: vector(2) = (/1,1/)
14904 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
14905 integer :: field(2,2) = 0, unity(2,2)
14907 ! result: unity matrix
14908 unity = unpack(vector, reshape(mask, (/2,2/)), field)
14912 @item @emph{See also}:
14920 @section @code{VERIFY} --- Scan a string for characters not a given set
14922 @cindex string, find missing set
14925 @item @emph{Description}:
14926 Verifies that all the characters in @var{STRING} belong to the set of
14927 characters in @var{SET}.
14929 If @var{BACK} is either absent or equals @code{FALSE}, this function
14930 returns the position of the leftmost character of @var{STRING} that is
14931 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost
14932 position is returned. If all characters of @var{STRING} are found in
14933 @var{SET}, the result is zero.
14935 @item @emph{Standard}:
14936 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
14938 @item @emph{Class}:
14941 @item @emph{Syntax}:
14942 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
14944 @item @emph{Arguments}:
14945 @multitable @columnfractions .15 .70
14946 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
14947 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
14948 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
14949 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
14950 expression indicating the kind parameter of the result.
14953 @item @emph{Return value}:
14954 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14955 @var{KIND} is absent, the return value is of default integer kind.
14957 @item @emph{Example}:
14959 PROGRAM test_verify
14960 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
14961 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
14962 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
14963 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
14964 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
14968 @item @emph{See also}:
14970 @ref{INDEX intrinsic}
14976 @section @code{XOR} --- Bitwise logical exclusive OR
14978 @cindex bitwise logical exclusive or
14979 @cindex logical exclusive or, bitwise
14982 @item @emph{Description}:
14983 Bitwise logical exclusive or.
14985 This intrinsic routine is provided for backwards compatibility with
14986 GNU Fortran 77. For integer arguments, programmers should consider
14987 the use of the @ref{IEOR} intrinsic and for logical arguments the
14988 @code{.NEQV.} operator, which are both defined by the Fortran standard.
14990 @item @emph{Standard}:
14993 @item @emph{Class}:
14996 @item @emph{Syntax}:
14997 @code{RESULT = XOR(I, J)}
14999 @item @emph{Arguments}:
15000 @multitable @columnfractions .15 .70
15001 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
15002 type or a scalar @code{LOGICAL} type or a boz-literal-constant.
15003 @item @var{J} @tab The type shall be the same as the type of @var{I} or
15004 a boz-literal-constant. @var{I} and @var{J} shall not both be
15005 boz-literal-constants. If either @var{I} and @var{J} is a
15006 boz-literal-constant, then the other argument must be a scalar @code{INTEGER}.
15009 @item @emph{Return value}:
15010 The return type is either a scalar @code{INTEGER} or a scalar
15011 @code{LOGICAL}. If the kind type parameters differ, then the
15012 smaller kind type is implicitly converted to larger kind, and the
15013 return has the larger kind. A boz-literal-constant is
15014 converted to an @code{INTEGER} with the kind type parameter of
15015 the other argument as-if a call to @ref{INT} occurred.
15017 @item @emph{Example}:
15020 LOGICAL :: T = .TRUE., F = .FALSE.
15022 DATA a / Z'F' /, b / Z'3' /
15024 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
15025 WRITE (*,*) XOR(a, b)
15029 @item @emph{See also}:
15030 Fortran 95 elemental function: @gol
15036 @node Intrinsic Modules
15037 @chapter Intrinsic Modules
15038 @cindex intrinsic Modules
15041 * ISO_FORTRAN_ENV::
15044 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
15045 * OpenACC Module OPENACC::
15048 @node ISO_FORTRAN_ENV
15049 @section @code{ISO_FORTRAN_ENV}
15051 @item @emph{Standard}:
15052 Fortran 2003 and later, except when otherwise noted
15055 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
15059 @item @code{ATOMIC_INT_KIND}:
15060 Default-kind integer constant to be used as kind parameter when defining
15061 integer variables used in atomic operations. (Fortran 2008 or later.)
15063 @item @code{ATOMIC_LOGICAL_KIND}:
15064 Default-kind integer constant to be used as kind parameter when defining
15065 logical variables used in atomic operations. (Fortran 2008 or later.)
15067 @item @code{CHARACTER_KINDS}:
15068 Default-kind integer constant array of rank one containing the supported kind
15069 parameters of the @code{CHARACTER} type. (Fortran 2008 or later.)
15071 @item @code{CHARACTER_STORAGE_SIZE}:
15072 Size in bits of the character storage unit.
15074 @item @code{ERROR_UNIT}:
15075 Identifies the preconnected unit used for error reporting.
15077 @item @code{FILE_STORAGE_SIZE}:
15078 Size in bits of the file-storage unit.
15080 @item @code{INPUT_UNIT}:
15081 Identifies the preconnected unit identified by the asterisk
15082 (@code{*}) in @code{READ} statement.
15084 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
15085 Kind type parameters to specify an INTEGER type with a storage
15086 size of 16, 32, and 64 bits. It is negative if a target platform
15087 does not support the particular kind. (Fortran 2008 or later.)
15089 @item @code{INTEGER_KINDS}:
15090 Default-kind integer constant array of rank one containing the supported kind
15091 parameters of the @code{INTEGER} type. (Fortran 2008 or later.)
15093 @item @code{IOSTAT_END}:
15094 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
15095 an input/output statement if an end-of-file condition occurred.
15097 @item @code{IOSTAT_EOR}:
15098 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
15099 an input/output statement if an end-of-record condition occurred.
15101 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
15102 Scalar default-integer constant, used by @code{INQUIRE} for the
15103 @code{IOSTAT=} specifier to denote an that a unit number identifies an
15104 internal unit. (Fortran 2008 or later.)
15106 @item @code{NUMERIC_STORAGE_SIZE}:
15107 The size in bits of the numeric storage unit.
15109 @item @code{LOGICAL_KINDS}:
15110 Default-kind integer constant array of rank one containing the supported kind
15111 parameters of the @code{LOGICAL} type. (Fortran 2008 or later.)
15113 @item @code{OUTPUT_UNIT}:
15114 Identifies the preconnected unit identified by the asterisk
15115 (@code{*}) in @code{WRITE} statement.
15117 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
15118 Kind type parameters to specify a REAL type with a storage
15119 size of 32, 64, and 128 bits. It is negative if a target platform
15120 does not support the particular kind. (Fortran 2008 or later.)
15122 @item @code{REAL_KINDS}:
15123 Default-kind integer constant array of rank one containing the supported kind
15124 parameters of the @code{REAL} type. (Fortran 2008 or later.)
15126 @item @code{STAT_LOCKED}:
15127 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
15128 denote that the lock variable is locked by the executing image. (Fortran 2008
15131 @item @code{STAT_LOCKED_OTHER_IMAGE}:
15132 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
15133 denote that the lock variable is locked by another image. (Fortran 2008 or
15136 @item @code{STAT_STOPPED_IMAGE}:
15137 Positive, scalar default-integer constant used as STAT= return value if the
15138 argument in the statement requires synchronisation with an image, which has
15139 initiated the termination of the execution. (Fortran 2008 or later.)
15141 @item @code{STAT_FAILED_IMAGE}:
15142 Positive, scalar default-integer constant used as STAT= return value if the
15143 argument in the statement requires communication with an image, which has
15144 is in the failed state. (TS 18508 or later.)
15146 @item @code{STAT_UNLOCKED}:
15147 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
15148 denote that the lock variable is unlocked. (Fortran 2008 or later.)
15151 The module provides the following derived type:
15154 @item @code{LOCK_TYPE}:
15155 Derived type with private components to be use with the @code{LOCK} and
15156 @code{UNLOCK} statement. A variable of its type has to be always declared
15157 as coarray and may not appear in a variable-definition context.
15158 (Fortran 2008 or later.)
15161 The module also provides the following intrinsic procedures:
15162 @ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}.
15166 @node ISO_C_BINDING
15167 @section @code{ISO_C_BINDING}
15169 @item @emph{Standard}:
15170 Fortran 2003 and later, GNU extensions
15173 The following intrinsic procedures are provided by the module; their
15174 definition can be found in the section Intrinsic Procedures of this
15178 @item @code{C_ASSOCIATED}
15179 @item @code{C_F_POINTER}
15180 @item @code{C_F_PROCPOINTER}
15181 @item @code{C_FUNLOC}
15183 @item @code{C_SIZEOF}
15185 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
15186 @c don't really know why.
15188 The @code{ISO_C_BINDING} module provides the following named constants of
15189 type default integer, which can be used as KIND type parameters.
15191 In addition to the integer named constants required by the Fortran 2003
15192 standard and @code{C_PTRDIFF_T} of TS 29113, GNU Fortran provides as an
15193 extension named constants for the 128-bit integer types supported by the
15194 C compiler: @code{C_INT128_T, C_INT_LEAST128_T, C_INT_FAST128_T}.
15195 Furthermore, if @code{__float128} is supported in C, the named constants
15196 @code{C_FLOAT128, C_FLOAT128_COMPLEX} are defined.
15198 @multitable @columnfractions .15 .35 .35 .35
15199 @item Fortran Type @tab Named constant @tab C type @tab Extension
15200 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
15201 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
15202 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
15203 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
15204 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
15205 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
15206 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
15207 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
15208 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
15209 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
15210 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
15211 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
15212 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
15213 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
15214 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
15215 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
15216 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
15217 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
15218 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
15219 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
15220 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
15221 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
15222 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
15223 @item @code{INTEGER}@tab @code{C_PTRDIFF_T} @tab @code{ptrdiff_t} @tab TS 29113
15224 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
15225 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
15226 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
15227 @item @code{REAL} @tab @code{C_FLOAT128} @tab @code{__float128} @tab Ext.
15228 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
15229 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
15230 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
15231 @item @code{REAL} @tab @code{C_FLOAT128_COMPLEX} @tab @code{__float128 _Complex} @tab Ext.
15232 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
15233 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
15236 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
15239 @multitable @columnfractions .20 .45 .15
15240 @item Name @tab C definition @tab Value
15241 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
15242 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
15243 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
15244 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
15245 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
15246 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
15247 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
15248 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
15251 Moreover, the following two named constants are defined:
15253 @multitable @columnfractions .20 .80
15254 @item Name @tab Type
15255 @item @code{C_NULL_PTR} @tab @code{C_PTR}
15256 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
15259 Both are equivalent to the value @code{NULL} in C.
15264 @section IEEE modules: @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
15266 @item @emph{Standard}:
15267 Fortran 2003 and later
15270 The @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
15271 intrinsic modules provide support for exceptions and IEEE arithmetic, as
15272 defined in Fortran 2003 and later standards, and the IEC 60559:1989 standard
15273 (@emph{Binary floating-point arithmetic for microprocessor systems}). These
15274 modules are only provided on the following supported platforms:
15277 @item i386 and x86_64 processors
15278 @item platforms which use the GNU C Library (glibc)
15279 @item platforms with support for SysV/386 routines for floating point
15280 interface (including Solaris and BSDs)
15281 @item platforms with the AIX OS
15284 For full compliance with the Fortran standards, code using the
15285 @code{IEEE_EXCEPTIONS} or @code{IEEE_ARITHMETIC} modules should be compiled
15286 with the following options: @code{-fno-unsafe-math-optimizations
15287 -frounding-math -fsignaling-nans}.
15291 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
15292 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
15294 @item @emph{Standard}:
15295 OpenMP Application Program Interface v4.5 and
15296 OpenMP Application Program Interface v5.0 (partially supported).
15299 The OpenMP Fortran runtime library routines are provided both in
15300 a form of two Fortran modules, named @code{OMP_LIB} and
15301 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
15302 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
15303 in the @ref{Top,,Introduction,libgomp,GNU Offloading and Multi
15304 Processing Runtime Library} manual,
15305 the named constants defined in the modules are listed
15308 For details refer to the actual
15309 @uref{http://www.openmp.org/wp-content/uploads/openmp-4.5.pdf,
15310 OpenMP Application Program Interface v4.5} and
15311 @uref{https://www.openmp.org/wp-content/uploads/OpenMP-API-Specification-5.0.pdf,
15312 OpenMP Application Program Interface v5.0}.
15314 @code{OMP_LIB_KINDS} provides the following scalar default-integer
15318 @item @code{omp_allocator_handle_kind}
15319 @item @code{omp_alloctrait_key_kind}
15320 @item @code{omp_alloctrait_val_kind}
15321 @item @code{omp_depend_kind}
15322 @item @code{omp_lock_kind}
15323 @item @code{omp_lock_hint_kind}
15324 @item @code{omp_nest_lock_kind}
15325 @item @code{omp_pause_resource_kind}
15326 @item @code{omp_memspace_handle_kind}
15327 @item @code{omp_proc_bind_kind}
15328 @item @code{omp_sched_kind}
15329 @item @code{omp_sync_hint_kind}
15332 @code{OMP_LIB} provides the scalar default-integer
15333 named constant @code{openmp_version} with a value of the form
15334 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
15335 of the OpenMP version; for OpenMP v4.5 the value is @code{201511}.
15337 The following derived type:
15340 @item @code{omp_alloctrait}
15343 The following scalar integer named constants of the
15344 kind @code{omp_sched_kind}:
15347 @item @code{omp_sched_static}
15348 @item @code{omp_sched_dynamic}
15349 @item @code{omp_sched_guided}
15350 @item @code{omp_sched_auto}
15353 And the following scalar integer named constants of the
15354 kind @code{omp_proc_bind_kind}:
15357 @item @code{omp_proc_bind_false}
15358 @item @code{omp_proc_bind_true}
15359 @item @code{omp_proc_bind_master}
15360 @item @code{omp_proc_bind_close}
15361 @item @code{omp_proc_bind_spread}
15364 The following scalar integer named constants are of the
15365 kind @code{omp_lock_hint_kind}:
15368 @item @code{omp_lock_hint_none}
15369 @item @code{omp_lock_hint_uncontended}
15370 @item @code{omp_lock_hint_contended}
15371 @item @code{omp_lock_hint_nonspeculative}
15372 @item @code{omp_lock_hint_speculative}
15373 @item @code{omp_sync_hint_none}
15374 @item @code{omp_sync_hint_uncontended}
15375 @item @code{omp_sync_hint_contended}
15376 @item @code{omp_sync_hint_nonspeculative}
15377 @item @code{omp_sync_hint_speculative}
15380 And the following two scalar integer named constants are of the
15381 kind @code{omp_pause_resource_kind}:
15384 @item @code{omp_pause_soft}
15385 @item @code{omp_pause_hard}
15388 The following scalar integer named constants are of the kind
15389 @code{omp_alloctrait_key_kind}:
15392 @item @code{omp_atk_sync_hint}
15393 @item @code{omp_atk_alignment}
15394 @item @code{omp_atk_access}
15395 @item @code{omp_atk_pool_size}
15396 @item @code{omp_atk_fallback}
15397 @item @code{omp_atk_fb_data}
15398 @item @code{omp_atk_pinned}
15399 @item @code{omp_atk_partition}
15402 The following scalar integer named constants are of the kind
15403 @code{omp_alloctrait_val_kind}:
15406 @code{omp_alloctrait_key_kind}:
15407 @item @code{omp_atv_default}
15408 @item @code{omp_atv_false}
15409 @item @code{omp_atv_true}
15410 @item @code{omp_atv_contended}
15411 @item @code{omp_atv_uncontended}
15412 @item @code{omp_atv_serialized}
15413 @item @code{omp_atv_sequential}
15414 @item @code{omp_atv_private}
15415 @item @code{omp_atv_all}
15416 @item @code{omp_atv_thread}
15417 @item @code{omp_atv_pteam}
15418 @item @code{omp_atv_cgroup}
15419 @item @code{omp_atv_default_mem_fb}
15420 @item @code{omp_atv_null_fb}
15421 @item @code{omp_atv_abort_fb}
15422 @item @code{omp_atv_allocator_fb}
15423 @item @code{omp_atv_environment}
15424 @item @code{omp_atv_nearest}
15425 @item @code{omp_atv_blocked}
15428 The following scalar integer named constants are of the kind
15429 @code{omp_allocator_handle_kind}:
15432 @item @code{omp_null_allocator}
15433 @item @code{omp_default_mem_alloc}
15434 @item @code{omp_large_cap_mem_alloc}
15435 @item @code{omp_const_mem_alloc}
15436 @item @code{omp_high_bw_mem_alloc}
15437 @item @code{omp_low_lat_mem_alloc}
15438 @item @code{omp_cgroup_mem_alloc}
15439 @item @code{omp_pteam_mem_alloc}
15440 @item @code{omp_thread_mem_alloc}
15443 The following scalar integer named constants are of the kind
15444 @code{omp_memspace_handle_kind}:
15447 @item @code{omp_default_mem_space}
15448 @item @code{omp_large_cap_mem_space}
15449 @item @code{omp_const_mem_space}
15450 @item @code{omp_high_bw_mem_space}
15451 @item @code{omp_low_lat_mem_space}
15456 @node OpenACC Module OPENACC
15457 @section OpenACC Module @code{OPENACC}
15459 @item @emph{Standard}:
15460 OpenACC Application Programming Interface v2.6
15464 The OpenACC Fortran runtime library routines are provided both in a
15465 form of a Fortran 90 module, named @code{OPENACC}, and in form of a
15466 Fortran @code{include} file named @file{openacc_lib.h}. The
15467 procedures provided by @code{OPENACC} can be found in the
15468 @ref{Top,,Introduction,libgomp,GNU Offloading and Multi Processing
15469 Runtime Library} manual, the named constants defined in the modules
15472 For details refer to the actual
15473 @uref{http://www.openacc.org/,
15474 OpenACC Application Programming Interface v2.6}.
15476 @code{OPENACC} provides the scalar default-integer
15477 named constant @code{openacc_version} with a value of the form
15478 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
15479 of the OpenACC version; for OpenACC v2.6 the value is @code{201711}.