2 Copyright (C) 2005-2018 Free Software Foundation, Inc.
3 This is part of the GNU Fortran manual.
4 For copying conditions, see the file gfortran.texi.
6 Permission is granted to copy, distribute and/or modify this document
7 under the terms of the GNU Free Documentation License, Version 1.3 or
8 any later version published by the Free Software Foundation; with the
9 Invariant Sections being ``Funding Free Software'', the Front-Cover
10 Texts being (a) (see below), and with the Back-Cover Texts being (b)
11 (see below). A copy of the license is included in the gfdl(7) man page.
14 Some basic guidelines for editing this document:
16 (1) The intrinsic procedures are to be listed in alphabetical order.
17 (2) The generic name is to be used.
18 (3) The specific names are included in the function index and in a
19 table at the end of the node (See ABS entry).
20 (4) Try to maintain the same style for each entry.
26 \gdef\acosd{\mathop{\rm acosd}\nolimits}
27 \gdef\asind{\mathop{\rm asind}\nolimits}
28 \gdef\atand{\mathop{\rm atand}\nolimits}
29 \gdef\acos{\mathop{\rm acos}\nolimits}
30 \gdef\asin{\mathop{\rm asin}\nolimits}
31 \gdef\atan{\mathop{\rm atan}\nolimits}
32 \gdef\acosh{\mathop{\rm acosh}\nolimits}
33 \gdef\asinh{\mathop{\rm asinh}\nolimits}
34 \gdef\atanh{\mathop{\rm atanh}\nolimits}
35 \gdef\cosd{\mathop{\rm cosd}\nolimits}
39 @node Intrinsic Procedures
40 @chapter Intrinsic Procedures
41 @cindex intrinsic procedures
44 * Introduction: Introduction to Intrinsics
45 * @code{ABORT}: ABORT, Abort the program
46 * @code{ABS}: ABS, Absolute value
47 * @code{ACCESS}: ACCESS, Checks file access modes
48 * @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence
49 * @code{ACOS}: ACOS, Arccosine function
50 * @code{ACOSD}: ACOSD, Arccosine function, degrees
51 * @code{ACOSH}: ACOSH, Inverse hyperbolic cosine function
52 * @code{ADJUSTL}: ADJUSTL, Left adjust a string
53 * @code{ADJUSTR}: ADJUSTR, Right adjust a string
54 * @code{AIMAG}: AIMAG, Imaginary part of complex number
55 * @code{AINT}: AINT, Truncate to a whole number
56 * @code{ALARM}: ALARM, Set an alarm clock
57 * @code{ALL}: ALL, Determine if all values are true
58 * @code{ALLOCATED}: ALLOCATED, Status of allocatable entity
59 * @code{AND}: AND, Bitwise logical AND
60 * @code{ANINT}: ANINT, Nearest whole number
61 * @code{ANY}: ANY, Determine if any values are true
62 * @code{ASIN}: ASIN, Arcsine function
63 * @code{ASIND}: ASIND, Arcsine function, degrees
64 * @code{ASINH}: ASINH, Inverse hyperbolic sine function
65 * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair
66 * @code{ATAN}: ATAN, Arctangent function
67 * @code{ATAND}: ATAND, Arctangent function, degrees
68 * @code{ATAN2}: ATAN2, Arctangent function
69 * @code{ATAN2D}: ATAN2D, Arctangent function, degrees
70 * @code{ATANH}: ATANH, Inverse hyperbolic tangent function
71 * @code{ATOMIC_ADD}: ATOMIC_ADD, Atomic ADD operation
72 * @code{ATOMIC_AND}: ATOMIC_AND, Atomic bitwise AND operation
73 * @code{ATOMIC_CAS}: ATOMIC_CAS, Atomic compare and swap
74 * @code{ATOMIC_DEFINE}: ATOMIC_DEFINE, Setting a variable atomically
75 * @code{ATOMIC_FETCH_ADD}: ATOMIC_FETCH_ADD, Atomic ADD operation with prior fetch
76 * @code{ATOMIC_FETCH_AND}: ATOMIC_FETCH_AND, Atomic bitwise AND operation with prior fetch
77 * @code{ATOMIC_FETCH_OR}: ATOMIC_FETCH_OR, Atomic bitwise OR operation with prior fetch
78 * @code{ATOMIC_FETCH_XOR}: ATOMIC_FETCH_XOR, Atomic bitwise XOR operation with prior fetch
79 * @code{ATOMIC_OR}: ATOMIC_OR, Atomic bitwise OR operation
80 * @code{ATOMIC_REF}: ATOMIC_REF, Obtaining the value of a variable atomically
81 * @code{ATOMIC_XOR}: ATOMIC_XOR, Atomic bitwise OR operation
82 * @code{BACKTRACE}: BACKTRACE, Show a backtrace
83 * @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0
84 * @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1
85 * @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind
86 * @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0
87 * @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1
88 * @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind
89 * @code{BGE}: BGE, Bitwise greater than or equal to
90 * @code{BGT}: BGT, Bitwise greater than
91 * @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function
92 * @code{BLE}: BLE, Bitwise less than or equal to
93 * @code{BLT}: BLT, Bitwise less than
94 * @code{BTEST}: BTEST, Bit test function
95 * @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer
96 * @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer
97 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
98 * @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure
99 * @code{C_LOC}: C_LOC, Obtain the C address of an object
100 * @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression
101 * @code{CEILING}: CEILING, Integer ceiling function
102 * @code{CHAR}: CHAR, Integer-to-character conversion function
103 * @code{CHDIR}: CHDIR, Change working directory
104 * @code{CHMOD}: CHMOD, Change access permissions of files
105 * @code{CMPLX}: CMPLX, Complex conversion function
106 * @code{CO_BROADCAST}: CO_BROADCAST, Copy a value to all images the current set of images
107 * @code{CO_MAX}: CO_MAX, Maximal value on the current set of images
108 * @code{CO_MIN}: CO_MIN, Minimal value on the current set of images
109 * @code{CO_REDUCE}: CO_REDUCE, Reduction of values on the current set of images
110 * @code{CO_SUM}: CO_SUM, Sum of values on the current set of images
111 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
112 * @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler
113 * @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string
114 * @code{COMPLEX}: COMPLEX, Complex conversion function
115 * @code{CONJG}: CONJG, Complex conjugate function
116 * @code{COS}: COS, Cosine function
117 * @code{COSD}: COSD, Cosine function, degrees
118 * @code{COSH}: COSH, Hyperbolic cosine function
119 * @code{COTAN}: COTAN, Cotangent function
120 * @code{COTAND}: COTAND, Cotangent function, degrees
121 * @code{COUNT}: COUNT, Count occurrences of TRUE in an array
122 * @code{CPU_TIME}: CPU_TIME, CPU time subroutine
123 * @code{CSHIFT}: CSHIFT, Circular shift elements of an array
124 * @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string
125 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
126 * @code{DBLE}: DBLE, Double precision conversion function
127 * @code{DCMPLX}: DCMPLX, Double complex conversion function
128 * @code{DIGITS}: DIGITS, Significant digits function
129 * @code{DIM}: DIM, Positive difference
130 * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
131 * @code{DPROD}: DPROD, Double product function
132 * @code{DREAL}: DREAL, Double real part function
133 * @code{DSHIFTL}: DSHIFTL, Combined left shift
134 * @code{DSHIFTR}: DSHIFTR, Combined right shift
135 * @code{DTIME}: DTIME, Execution time subroutine (or function)
136 * @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array
137 * @code{EPSILON}: EPSILON, Epsilon function
138 * @code{ERF}: ERF, Error function
139 * @code{ERFC}: ERFC, Complementary error function
140 * @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function
141 * @code{ETIME}: ETIME, Execution time subroutine (or function)
142 * @code{EVENT_QUERY}: EVENT_QUERY, Query whether a coarray event has occurred
143 * @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command
144 * @code{EXIT}: EXIT, Exit the program with status.
145 * @code{EXP}: EXP, Exponential function
146 * @code{EXPONENT}: EXPONENT, Exponent function
147 * @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF, Query dynamic type for extension
148 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
149 * @code{FGET}: FGET, Read a single character in stream mode from stdin
150 * @code{FGETC}: FGETC, Read a single character in stream mode
151 * @code{FLOOR}: FLOOR, Integer floor function
152 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
153 * @code{FNUM}: FNUM, File number function
154 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
155 * @code{FPUTC}: FPUTC, Write a single character in stream mode
156 * @code{FRACTION}: FRACTION, Fractional part of the model representation
157 * @code{FREE}: FREE, Memory de-allocation subroutine
158 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
159 * @code{FSTAT}: FSTAT, Get file status
160 * @code{FTELL}: FTELL, Current stream position
161 * @code{GAMMA}: GAMMA, Gamma function
162 * @code{GERROR}: GERROR, Get last system error message
163 * @code{GETARG}: GETARG, Get command line arguments
164 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
165 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
166 * @code{GETCWD}: GETCWD, Get current working directory
167 * @code{GETENV}: GETENV, Get an environmental variable
168 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
169 * @code{GETGID}: GETGID, Group ID function
170 * @code{GETLOG}: GETLOG, Get login name
171 * @code{GETPID}: GETPID, Process ID function
172 * @code{GETUID}: GETUID, User ID function
173 * @code{GMTIME}: GMTIME, Convert time to GMT info
174 * @code{HOSTNM}: HOSTNM, Get system host name
175 * @code{HUGE}: HUGE, Largest number of a kind
176 * @code{HYPOT}: HYPOT, Euclidean distance function
177 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
178 * @code{IALL}: IALL, Bitwise AND of array elements
179 * @code{IAND}: IAND, Bitwise logical and
180 * @code{IANY}: IANY, Bitwise OR of array elements
181 * @code{IARGC}: IARGC, Get the number of command line arguments
182 * @code{IBCLR}: IBCLR, Clear bit
183 * @code{IBITS}: IBITS, Bit extraction
184 * @code{IBSET}: IBSET, Set bit
185 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
186 * @code{IDATE}: IDATE, Current local time (day/month/year)
187 * @code{IEOR}: IEOR, Bitwise logical exclusive or
188 * @code{IERRNO}: IERRNO, Function to get the last system error number
189 * @code{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index conversion
190 * @code{INDEX}: INDEX intrinsic, Position of a substring within a string
191 * @code{INT}: INT, Convert to integer type
192 * @code{INT2}: INT2, Convert to 16-bit integer type
193 * @code{INT8}: INT8, Convert to 64-bit integer type
194 * @code{IOR}: IOR, Bitwise logical or
195 * @code{IPARITY}: IPARITY, Bitwise XOR of array elements
196 * @code{IRAND}: IRAND, Integer pseudo-random number
197 * @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value
198 * @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value
199 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
200 * @code{ISHFT}: ISHFT, Shift bits
201 * @code{ISHFTC}: ISHFTC, Shift bits circularly
202 * @code{ISNAN}: ISNAN, Tests for a NaN
203 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
204 * @code{KILL}: KILL, Send a signal to a process
205 * @code{KIND}: KIND, Kind of an entity
206 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
207 * @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array
208 * @code{LEADZ}: LEADZ, Number of leading zero bits of an integer
209 * @code{LEN}: LEN, Length of a character entity
210 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
211 * @code{LGE}: LGE, Lexical greater than or equal
212 * @code{LGT}: LGT, Lexical greater than
213 * @code{LINK}: LINK, Create a hard link
214 * @code{LLE}: LLE, Lexical less than or equal
215 * @code{LLT}: LLT, Lexical less than
216 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
217 * @code{LOC}: LOC, Returns the address of a variable
218 * @code{LOG}: LOG, Logarithm function
219 * @code{LOG10}: LOG10, Base 10 logarithm function
220 * @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
221 * @code{LOGICAL}: LOGICAL, Convert to logical type
222 * @code{LONG}: LONG, Convert to integer type
223 * @code{LSHIFT}: LSHIFT, Left shift bits
224 * @code{LSTAT}: LSTAT, Get file status
225 * @code{LTIME}: LTIME, Convert time to local time info
226 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
227 * @code{MASKL}: MASKL, Left justified mask
228 * @code{MASKR}: MASKR, Right justified mask
229 * @code{MATMUL}: MATMUL, matrix multiplication
230 * @code{MAX}: MAX, Maximum value of an argument list
231 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
232 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
233 * @code{MAXVAL}: MAXVAL, Maximum value of an array
234 * @code{MCLOCK}: MCLOCK, Time function
235 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
236 * @code{MERGE}: MERGE, Merge arrays
237 * @code{MERGE_BITS}: MERGE_BITS, Merge of bits under mask
238 * @code{MIN}: MIN, Minimum value of an argument list
239 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
240 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
241 * @code{MINVAL}: MINVAL, Minimum value of an array
242 * @code{MOD}: MOD, Remainder function
243 * @code{MODULO}: MODULO, Modulo function
244 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
245 * @code{MVBITS}: MVBITS, Move bits from one integer to another
246 * @code{NEAREST}: NEAREST, Nearest representable number
247 * @code{NEW_LINE}: NEW_LINE, New line character
248 * @code{NINT}: NINT, Nearest whole number
249 * @code{NORM2}: NORM2, Euclidean vector norm
250 * @code{NOT}: NOT, Logical negation
251 * @code{NULL}: NULL, Function that returns an disassociated pointer
252 * @code{NUM_IMAGES}: NUM_IMAGES, Number of images
253 * @code{OR}: OR, Bitwise logical OR
254 * @code{PACK}: PACK, Pack an array into an array of rank one
255 * @code{PARITY}: PARITY, Reduction with exclusive OR
256 * @code{PERROR}: PERROR, Print system error message
257 * @code{POPCNT}: POPCNT, Number of bits set
258 * @code{POPPAR}: POPPAR, Parity of the number of bits set
259 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
260 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
261 * @code{PRODUCT}: PRODUCT, Product of array elements
262 * @code{RADIX}: RADIX, Base of a data model
263 * @code{RAN}: RAN, Real pseudo-random number
264 * @code{RAND}: RAND, Real pseudo-random number
265 * @code{RANDOM_INIT}: RANDOM_INIT, Initialize pseudo-random number generator
266 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
267 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
268 * @code{RANGE}: RANGE, Decimal exponent range
269 * @code{RANK} : RANK, Rank of a data object
270 * @code{REAL}: REAL, Convert to real type
271 * @code{RENAME}: RENAME, Rename a file
272 * @code{REPEAT}: REPEAT, Repeated string concatenation
273 * @code{RESHAPE}: RESHAPE, Function to reshape an array
274 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
275 * @code{RSHIFT}: RSHIFT, Right shift bits
276 * @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality
277 * @code{SCALE}: SCALE, Scale a real value
278 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
279 * @code{SECNDS}: SECNDS, Time function
280 * @code{SECOND}: SECOND, CPU time function
281 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind
282 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
283 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
284 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
285 * @code{SHAPE}: SHAPE, Determine the shape of an array
286 * @code{SHIFTA}: SHIFTA, Right shift with fill
287 * @code{SHIFTL}: SHIFTL, Left shift
288 * @code{SHIFTR}: SHIFTR, Right shift
289 * @code{SIGN}: SIGN, Sign copying function
290 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
291 * @code{SIN}: SIN, Sine function
292 * @code{SIND}: SIND, Sine function, degrees
293 * @code{SINH}: SINH, Hyperbolic sine function
294 * @code{SIZE}: SIZE, Function to determine the size of an array
295 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
296 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
297 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
298 * @code{SPREAD}: SPREAD, Add a dimension to an array
299 * @code{SQRT}: SQRT, Square-root function
300 * @code{SRAND}: SRAND, Reinitialize the random number generator
301 * @code{STAT}: STAT, Get file status
302 * @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits
303 * @code{SUM}: SUM, Sum of array elements
304 * @code{SYMLNK}: SYMLNK, Create a symbolic link
305 * @code{SYSTEM}: SYSTEM, Execute a shell command
306 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
307 * @code{TAN}: TAN, Tangent function
308 * @code{TAND}: TAND, Tangent function, degrees
309 * @code{TANH}: TANH, Hyperbolic tangent function
310 * @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image
311 * @code{TIME}: TIME, Time function
312 * @code{TIME8}: TIME8, Time function (64-bit)
313 * @code{TINY}: TINY, Smallest positive number of a real kind
314 * @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer
315 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
316 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
317 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
318 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
319 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
320 * @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array
321 * @code{UMASK}: UMASK, Set the file creation mask
322 * @code{UNLINK}: UNLINK, Remove a file from the file system
323 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
324 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
325 * @code{XOR}: XOR, Bitwise logical exclusive or
328 @node Introduction to Intrinsics
329 @section Introduction to intrinsic procedures
331 The intrinsic procedures provided by GNU Fortran include all of the
332 intrinsic procedures required by the Fortran 95 standard, a set of
333 intrinsic procedures for backwards compatibility with G77, and a
334 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
335 standards. Any conflict between a description here and a description in
336 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
337 2008 standard is unintentional, and the standard(s) should be considered
340 The enumeration of the @code{KIND} type parameter is processor defined in
341 the Fortran 95 standard. GNU Fortran defines the default integer type and
342 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
343 respectively. The standard mandates that both data types shall have
344 another kind, which have more precision. On typical target architectures
345 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
346 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
347 In the description of generic intrinsic procedures, the kind type parameter
348 will be specified by @code{KIND=*}, and in the description of specific
349 names for an intrinsic procedure the kind type parameter will be explicitly
350 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
351 brevity the optional @code{KIND=} syntax will be omitted.
353 Many of the intrinsic procedures take one or more optional arguments.
354 This document follows the convention used in the Fortran 95 standard,
355 and denotes such arguments by square brackets.
357 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
358 which can be used to restrict the set of intrinsic procedures to a
359 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
360 option, and so all intrinsic procedures described here are accepted. There
361 is one caveat. For a select group of intrinsic procedures, @command{g77}
362 implemented both a function and a subroutine. Both classes
363 have been implemented in @command{gfortran} for backwards compatibility
364 with @command{g77}. It is noted here that these functions and subroutines
365 cannot be intermixed in a given subprogram. In the descriptions that follow,
366 the applicable standard for each intrinsic procedure is noted.
371 @section @code{ABORT} --- Abort the program
373 @cindex program termination, with core dump
374 @cindex terminate program, with core dump
378 @item @emph{Description}:
379 @code{ABORT} causes immediate termination of the program. On operating
380 systems that support a core dump, @code{ABORT} will produce a core dump.
381 It will also print a backtrace, unless @code{-fno-backtrace} is given.
383 @item @emph{Standard}:
392 @item @emph{Return value}:
395 @item @emph{Example}:
398 integer :: i = 1, j = 2
399 if (i /= j) call abort
400 end program test_abort
403 @item @emph{See also}:
404 @ref{EXIT}, @ref{KILL}, @ref{BACKTRACE}
411 @section @code{ABS} --- Absolute value
422 @cindex absolute value
425 @item @emph{Description}:
426 @code{ABS(A)} computes the absolute value of @code{A}.
428 @item @emph{Standard}:
429 Fortran 77 and later, has overloads that are GNU extensions
435 @code{RESULT = ABS(A)}
437 @item @emph{Arguments}:
438 @multitable @columnfractions .15 .70
439 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
440 @code{REAL}, or @code{COMPLEX}.
443 @item @emph{Return value}:
444 The return value is of the same type and
445 kind as the argument except the return value is @code{REAL} for a
446 @code{COMPLEX} argument.
448 @item @emph{Example}:
453 complex :: z = (-1.e0,0.e0)
460 @item @emph{Specific names}:
461 @multitable @columnfractions .20 .20 .20 .25
462 @item Name @tab Argument @tab Return type @tab Standard
463 @item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
464 @item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
465 @item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
466 @item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
467 @item @code{BABS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
468 @item @code{IIABS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
469 @item @code{JIABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
470 @item @code{KIABS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
471 @item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
472 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
479 @section @code{ACCESS} --- Checks file access modes
481 @cindex file system, access mode
484 @item @emph{Description}:
485 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
486 exists, is readable, writable or executable. Except for the
487 executable check, @code{ACCESS} can be replaced by
488 Fortran 95's @code{INQUIRE}.
490 @item @emph{Standard}:
497 @code{RESULT = ACCESS(NAME, MODE)}
499 @item @emph{Arguments}:
500 @multitable @columnfractions .15 .70
501 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
502 file name. Tailing blank are ignored unless the character @code{achar(0)}
503 is present, then all characters up to and excluding @code{achar(0)} are
505 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
506 file access mode, may be any concatenation of @code{"r"} (readable),
507 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
511 @item @emph{Return value}:
512 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
513 accessible in the given mode; otherwise or if an invalid argument
514 has been given for @code{MODE} the value @code{1} is returned.
516 @item @emph{Example}:
520 character(len=*), parameter :: file = 'test.dat'
521 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
522 if(access(file,' ') == 0) print *, trim(file),' is exists'
523 if(access(file,'r') == 0) print *, trim(file),' is readable'
524 if(access(file,'w') == 0) print *, trim(file),' is writable'
525 if(access(file,'x') == 0) print *, trim(file),' is executable'
526 if(access(file2,'rwx') == 0) &
527 print *, trim(file2),' is readable, writable and executable'
528 end program access_test
530 @item @emph{Specific names}:
531 @item @emph{See also}:
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}:
582 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
589 @section @code{ACOS} --- Arccosine function
592 @cindex trigonometric function, cosine, inverse
593 @cindex cosine, inverse
596 @item @emph{Description}:
597 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
599 @item @emph{Standard}:
600 Fortran 77 and later, for a complex argument Fortran 2008 or later
606 @code{RESULT = ACOS(X)}
608 @item @emph{Arguments}:
609 @multitable @columnfractions .15 .70
610 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
611 less than or equal to one - or the type shall be @code{COMPLEX}.
614 @item @emph{Return value}:
615 The return value is of the same type and kind as @var{X}.
616 The real part of the result is in radians and lies in the range
617 @math{0 \leq \Re \acos(x) \leq \pi}.
619 @item @emph{Example}:
622 real(8) :: x = 0.866_8
624 end program test_acos
627 @item @emph{Specific names}:
628 @multitable @columnfractions .20 .20 .20 .25
629 @item Name @tab Argument @tab Return type @tab Standard
630 @item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
631 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
634 @item @emph{See also}:
635 Inverse function: @ref{COS}
636 Degrees function: @ref{ACOSD}
643 @section @code{ACOSD} --- Arccosine function, degrees
646 @cindex trigonometric function, cosine, inverse, degrees
647 @cindex cosine, inverse, degrees
650 @item @emph{Description}:
651 @code{ACOSD(X)} computes the arccosine of @var{X} in degrees (inverse of
654 This function is for compatibility only and should be avoided in favor of
655 standard constructs wherever possible.
657 @item @emph{Standard}:
658 GNU Extension, enabled with @option{-fdec-math}
664 @code{RESULT = ACOSD(X)}
666 @item @emph{Arguments}:
667 @multitable @columnfractions .15 .70
668 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
669 less than or equal to one - or the type shall be @code{COMPLEX}.
672 @item @emph{Return value}:
673 The return value is of the same type and kind as @var{X}.
674 The real part of the result is in degrees and lies in the range
675 @math{0 \leq \Re \acos(x) \leq 180}.
677 @item @emph{Example}:
680 real(8) :: x = 0.866_8
682 end program test_acosd
685 @item @emph{Specific names}:
686 @multitable @columnfractions .20 .20 .20 .25
687 @item Name @tab Argument @tab Return type @tab Standard
688 @item @code{ACOSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
689 @item @code{DACOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
692 @item @emph{See also}:
693 Inverse function: @ref{COSD}
694 Radians function: @ref{ACOS}
701 @section @code{ACOSH} --- Inverse hyperbolic cosine function
704 @cindex area hyperbolic cosine
705 @cindex inverse hyperbolic cosine
706 @cindex hyperbolic function, cosine, inverse
707 @cindex cosine, hyperbolic, inverse
710 @item @emph{Description}:
711 @code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
713 @item @emph{Standard}:
714 Fortran 2008 and later
720 @code{RESULT = ACOSH(X)}
722 @item @emph{Arguments}:
723 @multitable @columnfractions .15 .70
724 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
727 @item @emph{Return value}:
728 The return value has the same type and kind as @var{X}. If @var{X} is
729 complex, the imaginary part of the result is in radians and lies between
730 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
732 @item @emph{Example}:
735 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
740 @item @emph{Specific names}:
741 @multitable @columnfractions .20 .20 .20 .25
742 @item Name @tab Argument @tab Return type @tab Standard
743 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
746 @item @emph{See also}:
747 Inverse function: @ref{COSH}
753 @section @code{ADJUSTL} --- Left adjust a string
755 @cindex string, adjust left
756 @cindex adjust string
759 @item @emph{Description}:
760 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
761 Spaces are inserted at the end of the string as needed.
763 @item @emph{Standard}:
770 @code{RESULT = ADJUSTL(STRING)}
772 @item @emph{Arguments}:
773 @multitable @columnfractions .15 .70
774 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
777 @item @emph{Return value}:
778 The return value is of type @code{CHARACTER} and of the same kind as
779 @var{STRING} where leading spaces are removed and the same number of
780 spaces are inserted on the end of @var{STRING}.
782 @item @emph{Example}:
785 character(len=20) :: str = ' gfortran'
788 end program test_adjustl
791 @item @emph{See also}:
792 @ref{ADJUSTR}, @ref{TRIM}
798 @section @code{ADJUSTR} --- Right adjust a string
800 @cindex string, adjust right
801 @cindex adjust string
804 @item @emph{Description}:
805 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
806 Spaces are inserted at the start of the string as needed.
808 @item @emph{Standard}:
815 @code{RESULT = ADJUSTR(STRING)}
817 @item @emph{Arguments}:
818 @multitable @columnfractions .15 .70
819 @item @var{STR} @tab The type shall be @code{CHARACTER}.
822 @item @emph{Return value}:
823 The return value is of type @code{CHARACTER} and of the same kind as
824 @var{STRING} where trailing spaces are removed and the same number of
825 spaces are inserted at the start of @var{STRING}.
827 @item @emph{Example}:
830 character(len=20) :: str = 'gfortran'
833 end program test_adjustr
836 @item @emph{See also}:
837 @ref{ADJUSTL}, @ref{TRIM}
843 @section @code{AIMAG} --- Imaginary part of complex number
848 @cindex complex numbers, imaginary part
851 @item @emph{Description}:
852 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
853 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
854 for compatibility with @command{g77}, and their use in new code is
855 strongly discouraged.
857 @item @emph{Standard}:
858 Fortran 77 and later, has overloads that are GNU extensions
864 @code{RESULT = AIMAG(Z)}
866 @item @emph{Arguments}:
867 @multitable @columnfractions .15 .70
868 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
871 @item @emph{Return value}:
872 The return value is of type @code{REAL} with the
873 kind type parameter of the argument.
875 @item @emph{Example}:
880 z4 = cmplx(1.e0_4, 0.e0_4)
881 z8 = cmplx(0.e0_8, 1.e0_8)
882 print *, aimag(z4), dimag(z8)
883 end program test_aimag
886 @item @emph{Specific names}:
887 @multitable @columnfractions .20 .20 .20 .25
888 @item Name @tab Argument @tab Return type @tab Standard
889 @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
890 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
891 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
892 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
899 @section @code{AINT} --- Truncate to a whole number
903 @cindex rounding, floor
906 @item @emph{Description}:
907 @code{AINT(A [, KIND])} truncates its argument to a whole number.
909 @item @emph{Standard}:
916 @code{RESULT = AINT(A [, KIND])}
918 @item @emph{Arguments}:
919 @multitable @columnfractions .15 .70
920 @item @var{A} @tab The type of the argument shall be @code{REAL}.
921 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
922 expression indicating the kind parameter of the result.
925 @item @emph{Return value}:
926 The return value is of type @code{REAL} with the kind type parameter of the
927 argument if the optional @var{KIND} is absent; otherwise, the kind
928 type parameter will be given by @var{KIND}. If the magnitude of
929 @var{X} is less than one, @code{AINT(X)} returns zero. If the
930 magnitude is equal to or greater than one then it returns the largest
931 whole number that does not exceed its magnitude. The sign is the same
932 as the sign of @var{X}.
934 @item @emph{Example}:
941 print *, aint(x4), dint(x8)
943 end program test_aint
946 @item @emph{Specific names}:
947 @multitable @columnfractions .20 .20 .20 .25
948 @item Name @tab Argument @tab Return type @tab Standard
949 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
950 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
957 @section @code{ALARM} --- Execute a routine after a given delay
959 @cindex delayed execution
962 @item @emph{Description}:
963 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
964 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
965 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
966 supplied, it will be returned with the number of seconds remaining until
967 any previously scheduled alarm was due to be delivered, or zero if there
968 was no previously scheduled alarm.
970 @item @emph{Standard}:
977 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
979 @item @emph{Arguments}:
980 @multitable @columnfractions .15 .70
981 @item @var{SECONDS} @tab The type of the argument shall be a scalar
982 @code{INTEGER}. It is @code{INTENT(IN)}.
983 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
984 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
985 values may be either @code{SIG_IGN=1} to ignore the alarm generated
986 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
987 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
988 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
991 @item @emph{Example}:
994 external handler_print
996 call alarm (3, handler_print, i)
999 end program test_alarm
1001 This will cause the external routine @var{handler_print} to be called
1008 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
1010 @cindex array, apply condition
1011 @cindex array, condition testing
1014 @item @emph{Description}:
1015 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
1016 in the array along dimension @var{DIM}.
1018 @item @emph{Standard}:
1019 Fortran 95 and later
1022 Transformational function
1024 @item @emph{Syntax}:
1025 @code{RESULT = ALL(MASK [, DIM])}
1027 @item @emph{Arguments}:
1028 @multitable @columnfractions .15 .70
1029 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1030 it shall not be scalar.
1031 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1032 with a value that lies between one and the rank of @var{MASK}.
1035 @item @emph{Return value}:
1036 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
1037 the kind type parameter is the same as the kind type parameter of
1038 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
1039 an array with the rank of @var{MASK} minus 1. The shape is determined from
1040 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1044 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
1045 It also is true if @var{MASK} has zero size; otherwise, it is false.
1047 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
1048 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
1049 is determined by applying @code{ALL} to the array sections.
1052 @item @emph{Example}:
1056 l = all((/.true., .true., .true./))
1061 integer a(2,3), b(2,3)
1065 print *, all(a .eq. b, 1)
1066 print *, all(a .eq. b, 2)
1067 end subroutine section
1068 end program test_all
1075 @section @code{ALLOCATED} --- Status of an allocatable entity
1077 @cindex allocation, status
1080 @item @emph{Description}:
1081 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
1082 status of @var{ARRAY} and @var{SCALAR}, respectively.
1084 @item @emph{Standard}:
1085 Fortran 95 and later. Note, the @code{SCALAR=} keyword and allocatable
1086 scalar entities are available in Fortran 2003 and later.
1091 @item @emph{Syntax}:
1092 @multitable @columnfractions .80
1093 @item @code{RESULT = ALLOCATED(ARRAY)}
1094 @item @code{RESULT = ALLOCATED(SCALAR)}
1097 @item @emph{Arguments}:
1098 @multitable @columnfractions .15 .70
1099 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
1100 @item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar.
1103 @item @emph{Return value}:
1104 The return value is a scalar @code{LOGICAL} with the default logical
1105 kind type parameter. If the argument is allocated, then the result is
1106 @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
1108 @item @emph{Example}:
1110 program test_allocated
1112 real(4), allocatable :: x(:)
1113 if (.not. allocated(x)) allocate(x(i))
1114 end program test_allocated
1121 @section @code{AND} --- Bitwise logical AND
1123 @cindex bitwise logical and
1124 @cindex logical and, bitwise
1127 @item @emph{Description}:
1128 Bitwise logical @code{AND}.
1130 This intrinsic routine is provided for backwards compatibility with
1131 GNU Fortran 77. For integer arguments, programmers should consider
1132 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1134 @item @emph{Standard}:
1140 @item @emph{Syntax}:
1141 @code{RESULT = AND(I, J)}
1143 @item @emph{Arguments}:
1144 @multitable @columnfractions .15 .70
1145 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1146 type or a scalar @code{LOGICAL} type.
1147 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1150 @item @emph{Return value}:
1151 The return type is either a scalar @code{INTEGER} or a scalar
1152 @code{LOGICAL}. If the kind type parameters differ, then the
1153 smaller kind type is implicitly converted to larger kind, and the
1154 return has the larger kind.
1156 @item @emph{Example}:
1159 LOGICAL :: T = .TRUE., F = .FALSE.
1161 DATA a / Z'F' /, b / Z'3' /
1163 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1164 WRITE (*,*) AND(a, b)
1168 @item @emph{See also}:
1169 Fortran 95 elemental function: @ref{IAND}
1175 @section @code{ANINT} --- Nearest whole number
1179 @cindex rounding, ceiling
1182 @item @emph{Description}:
1183 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1185 @item @emph{Standard}:
1186 Fortran 77 and later
1191 @item @emph{Syntax}:
1192 @code{RESULT = ANINT(A [, KIND])}
1194 @item @emph{Arguments}:
1195 @multitable @columnfractions .15 .70
1196 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1197 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1198 expression indicating the kind parameter of the result.
1201 @item @emph{Return value}:
1202 The return value is of type real with the kind type parameter of the
1203 argument if the optional @var{KIND} is absent; otherwise, the kind
1204 type parameter will be given by @var{KIND}. If @var{A} is greater than
1205 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1206 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1208 @item @emph{Example}:
1215 print *, anint(x4), dnint(x8)
1217 end program test_anint
1220 @item @emph{Specific names}:
1221 @multitable @columnfractions .20 .20 .20 .25
1222 @item Name @tab Argument @tab Return type @tab Standard
1223 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
1224 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1231 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1233 @cindex array, apply condition
1234 @cindex array, condition testing
1237 @item @emph{Description}:
1238 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1239 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1241 @item @emph{Standard}:
1242 Fortran 95 and later
1245 Transformational function
1247 @item @emph{Syntax}:
1248 @code{RESULT = ANY(MASK [, DIM])}
1250 @item @emph{Arguments}:
1251 @multitable @columnfractions .15 .70
1252 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1253 it shall not be scalar.
1254 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1255 with a value that lies between one and the rank of @var{MASK}.
1258 @item @emph{Return value}:
1259 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1260 the kind type parameter is the same as the kind type parameter of
1261 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1262 an array with the rank of @var{MASK} minus 1. The shape is determined from
1263 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1267 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1268 otherwise, it is false. It also is false if @var{MASK} has zero size.
1270 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1271 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1272 is determined by applying @code{ANY} to the array sections.
1275 @item @emph{Example}:
1279 l = any((/.true., .true., .true./))
1284 integer a(2,3), b(2,3)
1288 print *, any(a .eq. b, 1)
1289 print *, any(a .eq. b, 2)
1290 end subroutine section
1291 end program test_any
1298 @section @code{ASIN} --- Arcsine function
1301 @cindex trigonometric function, sine, inverse
1302 @cindex sine, inverse
1305 @item @emph{Description}:
1306 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1308 @item @emph{Standard}:
1309 Fortran 77 and later, for a complex argument Fortran 2008 or later
1314 @item @emph{Syntax}:
1315 @code{RESULT = ASIN(X)}
1317 @item @emph{Arguments}:
1318 @multitable @columnfractions .15 .70
1319 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1320 less than or equal to one - or be @code{COMPLEX}.
1323 @item @emph{Return value}:
1324 The return value is of the same type and kind as @var{X}.
1325 The real part of the result is in radians and lies in the range
1326 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1328 @item @emph{Example}:
1331 real(8) :: x = 0.866_8
1333 end program test_asin
1336 @item @emph{Specific names}:
1337 @multitable @columnfractions .20 .20 .20 .25
1338 @item Name @tab Argument @tab Return type @tab Standard
1339 @item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1340 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1343 @item @emph{See also}:
1344 Inverse function: @ref{SIN}
1345 Degrees function: @ref{ASIND}
1352 @section @code{ASIND} --- Arcsine function, degrees
1355 @cindex trigonometric function, sine, inverse, degrees
1356 @cindex sine, inverse, degrees
1359 @item @emph{Description}:
1360 @code{ASIND(X)} computes the arcsine of its @var{X} in degrees (inverse of
1363 This function is for compatibility only and should be avoided in favor of
1364 standard constructs wherever possible.
1366 @item @emph{Standard}:
1367 GNU Extension, enabled with @option{-fdec-math}.
1372 @item @emph{Syntax}:
1373 @code{RESULT = ASIND(X)}
1375 @item @emph{Arguments}:
1376 @multitable @columnfractions .15 .70
1377 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1378 less than or equal to one - or be @code{COMPLEX}.
1381 @item @emph{Return value}:
1382 The return value is of the same type and kind as @var{X}.
1383 The real part of the result is in degrees and lies in the range
1384 @math{-90 \leq \Re \asin(x) \leq 90}.
1386 @item @emph{Example}:
1389 real(8) :: x = 0.866_8
1391 end program test_asind
1394 @item @emph{Specific names}:
1395 @multitable @columnfractions .20 .20 .20 .25
1396 @item Name @tab Argument @tab Return type @tab Standard
1397 @item @code{ASIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
1398 @item @code{DASIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
1401 @item @emph{See also}:
1402 Inverse function: @ref{SIND}
1403 Radians function: @ref{ASIN}
1410 @section @code{ASINH} --- Inverse hyperbolic sine function
1413 @cindex area hyperbolic sine
1414 @cindex inverse hyperbolic sine
1415 @cindex hyperbolic function, sine, inverse
1416 @cindex sine, hyperbolic, inverse
1419 @item @emph{Description}:
1420 @code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
1422 @item @emph{Standard}:
1423 Fortran 2008 and later
1428 @item @emph{Syntax}:
1429 @code{RESULT = ASINH(X)}
1431 @item @emph{Arguments}:
1432 @multitable @columnfractions .15 .70
1433 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1436 @item @emph{Return value}:
1437 The return value is of the same type and kind as @var{X}. If @var{X} is
1438 complex, the imaginary part of the result is in radians and lies between
1439 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1441 @item @emph{Example}:
1444 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1445 WRITE (*,*) ASINH(x)
1449 @item @emph{Specific names}:
1450 @multitable @columnfractions .20 .20 .20 .25
1451 @item Name @tab Argument @tab Return type @tab Standard
1452 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1455 @item @emph{See also}:
1456 Inverse function: @ref{SINH}
1462 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1464 @cindex pointer, status
1465 @cindex association status
1468 @item @emph{Description}:
1469 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1470 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1472 @item @emph{Standard}:
1473 Fortran 95 and later
1478 @item @emph{Syntax}:
1479 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1481 @item @emph{Arguments}:
1482 @multitable @columnfractions .15 .70
1483 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1484 and it can be of any type.
1485 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1486 a target. It must have the same type, kind type parameter, and
1487 array rank as @var{POINTER}.
1489 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1492 @item @emph{Return value}:
1493 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1494 There are several cases:
1496 @item (A) When the optional @var{TARGET} is not present then
1497 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1498 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1499 @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
1500 disassociated, the result is false.
1501 @item (C) If @var{TARGET} is present and an array target, the result is true if
1502 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1503 are arrays whose elements are not zero-sized storage sequences, and
1504 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1506 As in case(B), the result is false, if @var{POINTER} is disassociated.
1507 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1508 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1509 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1511 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1512 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1513 target associated with @var{POINTER} and the target associated with @var{TARGET}
1514 have the same shape, are not zero-sized arrays, are arrays whose elements are
1515 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1516 the same storage units in array element order.
1517 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1520 @item @emph{Example}:
1522 program test_associated
1524 real, target :: tgt(2) = (/1., 2./)
1525 real, pointer :: ptr(:)
1527 if (associated(ptr) .eqv. .false.) call abort
1528 if (associated(ptr,tgt) .eqv. .false.) call abort
1529 end program test_associated
1532 @item @emph{See also}:
1539 @section @code{ATAN} --- Arctangent function
1542 @cindex trigonometric function, tangent, inverse
1543 @cindex tangent, inverse
1546 @item @emph{Description}:
1547 @code{ATAN(X)} computes the arctangent of @var{X}.
1549 @item @emph{Standard}:
1550 Fortran 77 and later, for a complex argument and for two arguments
1551 Fortran 2008 or later
1556 @item @emph{Syntax}:
1557 @multitable @columnfractions .80
1558 @item @code{RESULT = ATAN(X)}
1559 @item @code{RESULT = ATAN(Y, X)}
1562 @item @emph{Arguments}:
1563 @multitable @columnfractions .15 .70
1564 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1565 if @var{Y} is present, @var{X} shall be REAL.
1566 @item @var{Y} shall be of the same type and kind as @var{X}.
1569 @item @emph{Return value}:
1570 The return value is of the same type and kind as @var{X}.
1571 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1572 Otherwise, it the arcus tangent of @var{X}, where the real part of
1573 the result is in radians and lies in the range
1574 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1576 @item @emph{Example}:
1579 real(8) :: x = 2.866_8
1581 end program test_atan
1584 @item @emph{Specific names}:
1585 @multitable @columnfractions .20 .20 .20 .25
1586 @item Name @tab Argument @tab Return type @tab Standard
1587 @item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1588 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1591 @item @emph{See also}:
1592 Inverse function: @ref{TAN}
1593 Degrees function: @ref{ATAND}
1600 @section @code{ATAND} --- Arctangent function, degrees
1603 @cindex trigonometric function, tangent, inverse, degrees
1604 @cindex tangent, inverse, degrees
1607 @item @emph{Description}:
1608 @code{ATAND(X)} computes the arctangent of @var{X} in degrees (inverse of
1611 This function is for compatibility only and should be avoided in favor of
1612 standard constructs wherever possible.
1614 @item @emph{Standard}:
1615 GNU Extension, enabled with @option{-fdec-math}.
1620 @item @emph{Syntax}:
1621 @multitable @columnfractions .80
1622 @item @code{RESULT = ATAND(X)}
1623 @item @code{RESULT = ATAND(Y, X)}
1626 @item @emph{Arguments}:
1627 @multitable @columnfractions .15 .70
1628 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1629 if @var{Y} is present, @var{X} shall be REAL.
1630 @item @var{Y} shall be of the same type and kind as @var{X}.
1633 @item @emph{Return value}:
1634 The return value is of the same type and kind as @var{X}.
1635 If @var{Y} is present, the result is identical to @code{ATAND2(Y,X)}.
1636 Otherwise, it is the arcus tangent of @var{X}, where the real part of
1637 the result is in degrees and lies in the range
1638 @math{-90 \leq \Re \atand(x) \leq 90}.
1640 @item @emph{Example}:
1643 real(8) :: x = 2.866_8
1645 end program test_atand
1648 @item @emph{Specific names}:
1649 @multitable @columnfractions .20 .20 .20 .25
1650 @item Name @tab Argument @tab Return type @tab Standard
1651 @item @code{ATAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
1652 @item @code{DATAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
1655 @item @emph{See also}:
1656 Inverse function: @ref{TAND}
1657 Radians function: @ref{ATAN}
1664 @section @code{ATAN2} --- Arctangent function
1667 @cindex trigonometric function, tangent, inverse
1668 @cindex tangent, inverse
1671 @item @emph{Description}:
1672 @code{ATAN2(Y, X)} computes the principal value of the argument
1673 function of the complex number @math{X + i Y}. This function can
1674 be used to transform from Cartesian into polar coordinates and
1675 allows to determine the angle in the correct quadrant.
1677 @item @emph{Standard}:
1678 Fortran 77 and later
1683 @item @emph{Syntax}:
1684 @code{RESULT = ATAN2(Y, X)}
1686 @item @emph{Arguments}:
1687 @multitable @columnfractions .15 .70
1688 @item @var{Y} @tab The type shall be @code{REAL}.
1689 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1690 If @var{Y} is zero, then @var{X} must be nonzero.
1693 @item @emph{Return value}:
1694 The return value has the same type and kind type parameter as @var{Y}. It
1695 is the principal value of the complex number @math{X + i Y}. If @var{X}
1696 is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1697 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1698 the return value is zero if @var{X} is strictly positive, @math{\pi} if
1699 @var{X} is negative and @var{Y} is positive zero (or the processor does
1700 not handle signed zeros), and @math{-\pi} if @var{X} is negative and
1701 @var{Y} is negative zero. Finally, if @var{X} is zero, then the
1702 magnitude of the result is @math{\pi/2}.
1704 @item @emph{Example}:
1707 real(4) :: x = 1.e0_4, y = 0.5e0_4
1709 end program test_atan2
1712 @item @emph{Specific names}:
1713 @multitable @columnfractions .20 .20 .20 .25
1714 @item Name @tab Argument @tab Return type @tab Standard
1715 @item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1716 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1719 @item @emph{See also}:
1721 Degrees function: @ref{ATAN2D}
1728 @section @code{ATAN2D} --- Arctangent function, degrees
1731 @cindex trigonometric function, tangent, inverse, degrees
1732 @cindex tangent, inverse, degrees
1735 @item @emph{Description}:
1736 @code{ATAN2D(Y, X)} computes the principal value of the argument
1737 function of the complex number @math{X + i Y} in degrees. This function can
1738 be used to transform from Cartesian into polar coordinates and
1739 allows to determine the angle in the correct quadrant.
1741 This function is for compatibility only and should be avoided in favor of
1742 standard constructs wherever possible.
1744 @item @emph{Standard}:
1745 GNU Extension, enabled with @option{-fdec-math}.
1750 @item @emph{Syntax}:
1751 @code{RESULT = ATAN2D(Y, X)}
1753 @item @emph{Arguments}:
1754 @multitable @columnfractions .15 .70
1755 @item @var{Y} @tab The type shall be @code{REAL}.
1756 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1757 If @var{Y} is zero, then @var{X} must be nonzero.
1760 @item @emph{Return value}:
1761 The return value has the same type and kind type parameter as @var{Y}. It
1762 is the principal value of the complex number @math{X + i Y}. If @var{X}
1763 is nonzero, then it lies in the range @math{-180 \le \atan (x) \leq 180}.
1764 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1765 the return value is zero if @var{X} is strictly positive, @math{180} if
1766 @var{X} is negative and @var{Y} is positive zero (or the processor does
1767 not handle signed zeros), and @math{-180} if @var{X} is negative and
1768 @var{Y} is negative zero. Finally, if @var{X} is zero, then the
1769 magnitude of the result is @math{90}.
1771 @item @emph{Example}:
1774 real(4) :: x = 1.e0_4, y = 0.5e0_4
1776 end program test_atan2d
1779 @item @emph{Specific names}:
1780 @multitable @columnfractions .20 .20 .20 .25
1781 @item Name @tab Argument @tab Return type @tab Standard
1782 @item @code{ATAN2D(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab GNU Extension
1783 @item @code{DATAN2D(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab GNU Extension
1786 @item @emph{See also}:
1788 Radians function: @ref{ATAN2}
1795 @section @code{ATANH} --- Inverse hyperbolic tangent function
1798 @cindex area hyperbolic tangent
1799 @cindex inverse hyperbolic tangent
1800 @cindex hyperbolic function, tangent, inverse
1801 @cindex tangent, hyperbolic, inverse
1804 @item @emph{Description}:
1805 @code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
1807 @item @emph{Standard}:
1808 Fortran 2008 and later
1813 @item @emph{Syntax}:
1814 @code{RESULT = ATANH(X)}
1816 @item @emph{Arguments}:
1817 @multitable @columnfractions .15 .70
1818 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1821 @item @emph{Return value}:
1822 The return value has same type and kind as @var{X}. If @var{X} is
1823 complex, the imaginary part of the result is in radians and lies between
1824 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1826 @item @emph{Example}:
1829 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1830 WRITE (*,*) ATANH(x)
1834 @item @emph{Specific names}:
1835 @multitable @columnfractions .20 .20 .20 .25
1836 @item Name @tab Argument @tab Return type @tab Standard
1837 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1840 @item @emph{See also}:
1841 Inverse function: @ref{TANH}
1847 @section @code{ATOMIC_ADD} --- Atomic ADD operation
1849 @cindex Atomic subroutine, add
1852 @item @emph{Description}:
1853 @code{ATOMIC_ADD(ATOM, VALUE)} atomically adds the value of @var{VAR} to the
1854 variable @var{ATOM}. When @var{STAT} is present and the invocation was
1855 successful, it is assigned the value 0. If it is present and the invocation
1856 has failed, it is assigned a positive value; in particular, for a coindexed
1857 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1858 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1859 failed, the value @code{STAT_FAILED_IMAGE}.
1861 @item @emph{Standard}:
1867 @item @emph{Syntax}:
1868 @code{CALL ATOMIC_ADD (ATOM, VALUE [, STAT])}
1870 @item @emph{Arguments}:
1871 @multitable @columnfractions .15 .70
1872 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1873 type with @code{ATOMIC_INT_KIND} kind.
1874 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1875 is different, the value is converted to the kind of @var{ATOM}.
1876 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1879 @item @emph{Example}:
1883 integer(atomic_int_kind) :: atom[*]
1884 call atomic_add (atom[1], this_image())
1888 @item @emph{See also}:
1889 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_ADD}, @ref{ISO_FORTRAN_ENV},
1890 @ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
1897 @section @code{ATOMIC_AND} --- Atomic bitwise AND operation
1899 @cindex Atomic subroutine, AND
1902 @item @emph{Description}:
1903 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
1904 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
1905 and the invocation was successful, it is assigned the value 0. If it is present
1906 and the invocation has failed, it is assigned a positive value; in particular,
1907 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
1908 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
1909 image has failed, the value @code{STAT_FAILED_IMAGE}.
1911 @item @emph{Standard}:
1917 @item @emph{Syntax}:
1918 @code{CALL ATOMIC_AND (ATOM, VALUE [, STAT])}
1920 @item @emph{Arguments}:
1921 @multitable @columnfractions .15 .70
1922 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1923 type with @code{ATOMIC_INT_KIND} kind.
1924 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1925 is different, the value is converted to the kind of @var{ATOM}.
1926 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1929 @item @emph{Example}:
1933 integer(atomic_int_kind) :: atom[*]
1934 call atomic_and (atom[1], int(b'10100011101'))
1938 @item @emph{See also}:
1939 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_AND}, @ref{ISO_FORTRAN_ENV},
1940 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
1946 @section @code{ATOMIC_CAS} --- Atomic compare and swap
1947 @fnindex ATOMIC_DEFINE
1948 @cindex Atomic subroutine, compare and swap
1951 @item @emph{Description}:
1952 @code{ATOMIC_CAS} compares the variable @var{ATOM} with the value of
1953 @var{COMPARE}; if the value is the same, @var{ATOM} is set to the value
1954 of @var{NEW}. Additionally, @var{OLD} is set to the value of @var{ATOM}
1955 that was used for the comparison. When @var{STAT} is present and the invocation
1956 was successful, it is assigned the value 0. If it is present and the invocation
1957 has failed, it is assigned a positive value; in particular, for a coindexed
1958 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1959 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1960 failed, the value @code{STAT_FAILED_IMAGE}.
1962 @item @emph{Standard}:
1968 @item @emph{Syntax}:
1969 @code{CALL ATOMIC_CAS (ATOM, OLD, COMPARE, NEW [, STAT])}
1971 @item @emph{Arguments}:
1972 @multitable @columnfractions .15 .70
1973 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
1974 type with @code{ATOMIC_INT_KIND} kind or logical type with
1975 @code{ATOMIC_LOGICAL_KIND} kind.
1976 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1977 @item @var{COMPARE} @tab Scalar variable of the same type and kind as
1979 @item @var{NEW} @tab Scalar variable of the same type as @var{ATOM}. If kind
1980 is different, the value is converted to the kind of @var{ATOM}.
1981 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1984 @item @emph{Example}:
1988 logical(atomic_logical_kind) :: atom[*], prev
1989 call atomic_cas (atom[1], prev, .false., .true.))
1993 @item @emph{See also}:
1994 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_REF}, @ref{ISO_FORTRAN_ENV}
2000 @section @code{ATOMIC_DEFINE} --- Setting a variable atomically
2001 @fnindex ATOMIC_DEFINE
2002 @cindex Atomic subroutine, define
2005 @item @emph{Description}:
2006 @code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value
2007 @var{VALUE} atomically. When @var{STAT} is present and the invocation was
2008 successful, it is assigned the value 0. If it is present and the invocation
2009 has failed, it is assigned a positive value; in particular, for a coindexed
2010 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2011 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2012 failed, the value @code{STAT_FAILED_IMAGE}.
2014 @item @emph{Standard}:
2015 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
2020 @item @emph{Syntax}:
2021 @code{CALL ATOMIC_DEFINE (ATOM, VALUE [, STAT])}
2023 @item @emph{Arguments}:
2024 @multitable @columnfractions .15 .70
2025 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
2026 type with @code{ATOMIC_INT_KIND} kind or logical type with
2027 @code{ATOMIC_LOGICAL_KIND} kind.
2029 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2030 is different, the value is converted to the kind of @var{ATOM}.
2031 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2034 @item @emph{Example}:
2038 integer(atomic_int_kind) :: atom[*]
2039 call atomic_define (atom[1], this_image())
2043 @item @emph{See also}:
2044 @ref{ATOMIC_REF}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV},
2045 @ref{ATOMIC_ADD}, @ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
2050 @node ATOMIC_FETCH_ADD
2051 @section @code{ATOMIC_FETCH_ADD} --- Atomic ADD operation with prior fetch
2052 @fnindex ATOMIC_FETCH_ADD
2053 @cindex Atomic subroutine, ADD with fetch
2056 @item @emph{Description}:
2057 @code{ATOMIC_FETCH_ADD(ATOM, VALUE, OLD)} atomically stores the value of
2058 @var{ATOM} in @var{OLD} and adds the value of @var{VAR} to the
2059 variable @var{ATOM}. When @var{STAT} is present and the invocation was
2060 successful, it is assigned the value 0. If it is present and the invocation
2061 has failed, it is assigned a positive value; in particular, for a coindexed
2062 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2063 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2064 failed, the value @code{STAT_FAILED_IMAGE}.
2066 @item @emph{Standard}:
2072 @item @emph{Syntax}:
2073 @code{CALL ATOMIC_FETCH_ADD (ATOM, VALUE, old [, STAT])}
2075 @item @emph{Arguments}:
2076 @multitable @columnfractions .15 .70
2077 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2078 type with @code{ATOMIC_INT_KIND} kind.
2079 @code{ATOMIC_LOGICAL_KIND} kind.
2081 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2082 is different, the value is converted to the kind of @var{ATOM}.
2083 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2084 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2087 @item @emph{Example}:
2091 integer(atomic_int_kind) :: atom[*], old
2092 call atomic_add (atom[1], this_image(), old)
2096 @item @emph{See also}:
2097 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_ADD}, @ref{ISO_FORTRAN_ENV},
2098 @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR}
2103 @node ATOMIC_FETCH_AND
2104 @section @code{ATOMIC_FETCH_AND} --- Atomic bitwise AND operation with prior fetch
2105 @fnindex ATOMIC_FETCH_AND
2106 @cindex Atomic subroutine, AND with fetch
2109 @item @emph{Description}:
2110 @code{ATOMIC_AND(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2111 @var{OLD} and defines @var{ATOM} with the bitwise AND between the values of
2112 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
2113 successful, it is assigned the value 0. If it is present and the invocation has
2114 failed, it is assigned a positive value; in particular, for a coindexed
2115 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2116 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2117 failed, the value @code{STAT_FAILED_IMAGE}.
2119 @item @emph{Standard}:
2125 @item @emph{Syntax}:
2126 @code{CALL ATOMIC_FETCH_AND (ATOM, VALUE, OLD [, STAT])}
2128 @item @emph{Arguments}:
2129 @multitable @columnfractions .15 .70
2130 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2131 type with @code{ATOMIC_INT_KIND} kind.
2132 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2133 is different, the value is converted to the kind of @var{ATOM}.
2134 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2135 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2138 @item @emph{Example}:
2142 integer(atomic_int_kind) :: atom[*], old
2143 call atomic_fetch_and (atom[1], int(b'10100011101'), old)
2147 @item @emph{See also}:
2148 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_AND}, @ref{ISO_FORTRAN_ENV},
2149 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR}
2154 @node ATOMIC_FETCH_OR
2155 @section @code{ATOMIC_FETCH_OR} --- Atomic bitwise OR operation with prior fetch
2156 @fnindex ATOMIC_FETCH_OR
2157 @cindex Atomic subroutine, OR with fetch
2160 @item @emph{Description}:
2161 @code{ATOMIC_OR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2162 @var{OLD} and defines @var{ATOM} with the bitwise OR between the values of
2163 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
2164 successful, it is assigned the value 0. If it is present and the invocation has
2165 failed, it is assigned a positive value; in particular, for a coindexed
2166 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2167 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2168 failed, the value @code{STAT_FAILED_IMAGE}.
2170 @item @emph{Standard}:
2176 @item @emph{Syntax}:
2177 @code{CALL ATOMIC_FETCH_OR (ATOM, VALUE, OLD [, STAT])}
2179 @item @emph{Arguments}:
2180 @multitable @columnfractions .15 .70
2181 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2182 type with @code{ATOMIC_INT_KIND} kind.
2183 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2184 is different, the value is converted to the kind of @var{ATOM}.
2185 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2186 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2189 @item @emph{Example}:
2193 integer(atomic_int_kind) :: atom[*], old
2194 call atomic_fetch_or (atom[1], int(b'10100011101'), old)
2198 @item @emph{See also}:
2199 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_OR}, @ref{ISO_FORTRAN_ENV},
2200 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_XOR}
2205 @node ATOMIC_FETCH_XOR
2206 @section @code{ATOMIC_FETCH_XOR} --- Atomic bitwise XOR operation with prior fetch
2207 @fnindex ATOMIC_FETCH_XOR
2208 @cindex Atomic subroutine, XOR with fetch
2211 @item @emph{Description}:
2212 @code{ATOMIC_XOR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2213 @var{OLD} and defines @var{ATOM} with the bitwise XOR between the values of
2214 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
2215 successful, it is assigned the value 0. If it is present and the invocation has
2216 failed, it is assigned a positive value; in particular, for a coindexed
2217 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2218 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2219 failed, the value @code{STAT_FAILED_IMAGE}.
2221 @item @emph{Standard}:
2227 @item @emph{Syntax}:
2228 @code{CALL ATOMIC_FETCH_XOR (ATOM, VALUE, OLD [, STAT])}
2230 @item @emph{Arguments}:
2231 @multitable @columnfractions .15 .70
2232 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2233 type with @code{ATOMIC_INT_KIND} kind.
2234 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2235 is different, the value is converted to the kind of @var{ATOM}.
2236 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2237 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2240 @item @emph{Example}:
2244 integer(atomic_int_kind) :: atom[*], old
2245 call atomic_fetch_xor (atom[1], int(b'10100011101'), old)
2249 @item @emph{See also}:
2250 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_XOR}, @ref{ISO_FORTRAN_ENV},
2251 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}
2257 @section @code{ATOMIC_OR} --- Atomic bitwise OR operation
2259 @cindex Atomic subroutine, OR
2262 @item @emph{Description}:
2263 @code{ATOMIC_OR(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
2264 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
2265 and the invocation was successful, it is assigned the value 0. If it is present
2266 and the invocation has failed, it is assigned a positive value; in particular,
2267 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
2268 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
2269 image has failed, the value @code{STAT_FAILED_IMAGE}.
2271 @item @emph{Standard}:
2277 @item @emph{Syntax}:
2278 @code{CALL ATOMIC_OR (ATOM, VALUE [, STAT])}
2280 @item @emph{Arguments}:
2281 @multitable @columnfractions .15 .70
2282 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2283 type with @code{ATOMIC_INT_KIND} kind.
2284 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2285 is different, the value is converted to the kind of @var{ATOM}.
2286 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2289 @item @emph{Example}:
2293 integer(atomic_int_kind) :: atom[*]
2294 call atomic_or (atom[1], int(b'10100011101'))
2298 @item @emph{See also}:
2299 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_OR}, @ref{ISO_FORTRAN_ENV},
2300 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
2306 @section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically
2308 @cindex Atomic subroutine, reference
2311 @item @emph{Description}:
2312 @code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the
2313 variable @var{ATOM} to @var{VALUE}. When @var{STAT} is present and the
2314 invocation was successful, it is assigned the value 0. If it is present and the
2315 invocation has failed, it is assigned a positive value; in particular, for a
2316 coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value
2317 of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image
2318 has failed, the value @code{STAT_FAILED_IMAGE}.
2321 @item @emph{Standard}:
2322 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
2327 @item @emph{Syntax}:
2328 @code{CALL ATOMIC_REF(VALUE, ATOM [, STAT])}
2330 @item @emph{Arguments}:
2331 @multitable @columnfractions .15 .70
2332 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2333 is different, the value is converted to the kind of @var{ATOM}.
2334 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
2335 type with @code{ATOMIC_INT_KIND} kind or logical type with
2336 @code{ATOMIC_LOGICAL_KIND} kind.
2337 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2340 @item @emph{Example}:
2344 logical(atomic_logical_kind) :: atom[*]
2346 call atomic_ref (atom, .false.)
2348 call atomic_ref (atom, val)
2355 @item @emph{See also}:
2356 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV},
2357 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR},
2358 @ref{ATOMIC_FETCH_XOR}
2363 @section @code{ATOMIC_XOR} --- Atomic bitwise OR operation
2365 @cindex Atomic subroutine, XOR
2368 @item @emph{Description}:
2369 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
2370 XOR between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
2371 and the invocation was successful, it is assigned the value 0. If it is present
2372 and the invocation has failed, it is assigned a positive value; in particular,
2373 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
2374 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
2375 image has failed, the value @code{STAT_FAILED_IMAGE}.
2377 @item @emph{Standard}:
2383 @item @emph{Syntax}:
2384 @code{CALL ATOMIC_XOR (ATOM, VALUE [, STAT])}
2386 @item @emph{Arguments}:
2387 @multitable @columnfractions .15 .70
2388 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2389 type with @code{ATOMIC_INT_KIND} kind.
2390 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2391 is different, the value is converted to the kind of @var{ATOM}.
2392 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2395 @item @emph{Example}:
2399 integer(atomic_int_kind) :: atom[*]
2400 call atomic_xor (atom[1], int(b'10100011101'))
2404 @item @emph{See also}:
2405 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_XOR}, @ref{ISO_FORTRAN_ENV},
2406 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
2411 @section @code{BACKTRACE} --- Show a backtrace
2416 @item @emph{Description}:
2417 @code{BACKTRACE} shows a backtrace at an arbitrary place in user code. Program
2418 execution continues normally afterwards. The backtrace information is printed
2419 to the unit corresponding to @code{ERROR_UNIT} in @code{ISO_FORTRAN_ENV}.
2421 @item @emph{Standard}:
2427 @item @emph{Syntax}:
2428 @code{CALL BACKTRACE}
2430 @item @emph{Arguments}:
2433 @item @emph{See also}:
2440 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
2444 @cindex Bessel function, first kind
2447 @item @emph{Description}:
2448 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
2449 order 0 of @var{X}. This function is available under the name
2450 @code{BESJ0} as a GNU extension.
2452 @item @emph{Standard}:
2453 Fortran 2008 and later
2458 @item @emph{Syntax}:
2459 @code{RESULT = BESSEL_J0(X)}
2461 @item @emph{Arguments}:
2462 @multitable @columnfractions .15 .70
2463 @item @var{X} @tab The type shall be @code{REAL}.
2466 @item @emph{Return value}:
2467 The return value is of type @code{REAL} and lies in the
2468 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
2471 @item @emph{Example}:
2474 real(8) :: x = 0.0_8
2476 end program test_besj0
2479 @item @emph{Specific names}:
2480 @multitable @columnfractions .20 .20 .20 .25
2481 @item Name @tab Argument @tab Return type @tab Standard
2482 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2489 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
2493 @cindex Bessel function, first kind
2496 @item @emph{Description}:
2497 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
2498 order 1 of @var{X}. This function is available under the name
2499 @code{BESJ1} as a GNU extension.
2501 @item @emph{Standard}:
2507 @item @emph{Syntax}:
2508 @code{RESULT = BESSEL_J1(X)}
2510 @item @emph{Arguments}:
2511 @multitable @columnfractions .15 .70
2512 @item @var{X} @tab The type shall be @code{REAL}.
2515 @item @emph{Return value}:
2516 The return value is of type @code{REAL} and lies in the
2517 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
2520 @item @emph{Example}:
2523 real(8) :: x = 1.0_8
2525 end program test_besj1
2528 @item @emph{Specific names}:
2529 @multitable @columnfractions .20 .20 .20 .25
2530 @item Name @tab Argument @tab Return type @tab Standard
2531 @item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2538 @section @code{BESSEL_JN} --- Bessel function of the first kind
2542 @cindex Bessel function, first kind
2545 @item @emph{Description}:
2546 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
2547 order @var{N} of @var{X}. This function is available under the name
2548 @code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays,
2549 their ranks and shapes shall conform.
2551 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
2552 of the first kind of the orders @var{N1} to @var{N2}.
2554 @item @emph{Standard}:
2555 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2558 Elemental function, except for the transformational function
2559 @code{BESSEL_JN(N1, N2, X)}
2561 @item @emph{Syntax}:
2562 @multitable @columnfractions .80
2563 @item @code{RESULT = BESSEL_JN(N, X)}
2564 @item @code{RESULT = BESSEL_JN(N1, N2, X)}
2567 @item @emph{Arguments}:
2568 @multitable @columnfractions .15 .70
2569 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
2570 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2571 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2572 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2573 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
2576 @item @emph{Return value}:
2577 The return value is a scalar of type @code{REAL}. It has the same
2581 The transformational function uses a recurrence algorithm which might,
2582 for some values of @var{X}, lead to different results than calls to
2583 the elemental function.
2585 @item @emph{Example}:
2588 real(8) :: x = 1.0_8
2590 end program test_besjn
2593 @item @emph{Specific names}:
2594 @multitable @columnfractions .20 .20 .20 .25
2595 @item Name @tab Argument @tab Return type @tab Standard
2596 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2597 @item @tab @code{REAL(8) X} @tab @tab
2604 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
2608 @cindex Bessel function, second kind
2611 @item @emph{Description}:
2612 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
2613 order 0 of @var{X}. This function is available under the name
2614 @code{BESY0} as a GNU extension.
2616 @item @emph{Standard}:
2617 Fortran 2008 and later
2622 @item @emph{Syntax}:
2623 @code{RESULT = BESSEL_Y0(X)}
2625 @item @emph{Arguments}:
2626 @multitable @columnfractions .15 .70
2627 @item @var{X} @tab The type shall be @code{REAL}.
2630 @item @emph{Return value}:
2631 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2633 @item @emph{Example}:
2636 real(8) :: x = 0.0_8
2638 end program test_besy0
2641 @item @emph{Specific names}:
2642 @multitable @columnfractions .20 .20 .20 .25
2643 @item Name @tab Argument @tab Return type @tab Standard
2644 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2651 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
2655 @cindex Bessel function, second kind
2658 @item @emph{Description}:
2659 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
2660 order 1 of @var{X}. This function is available under the name
2661 @code{BESY1} as a GNU extension.
2663 @item @emph{Standard}:
2664 Fortran 2008 and later
2669 @item @emph{Syntax}:
2670 @code{RESULT = BESSEL_Y1(X)}
2672 @item @emph{Arguments}:
2673 @multitable @columnfractions .15 .70
2674 @item @var{X} @tab The type shall be @code{REAL}.
2677 @item @emph{Return value}:
2678 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2680 @item @emph{Example}:
2683 real(8) :: x = 1.0_8
2685 end program test_besy1
2688 @item @emph{Specific names}:
2689 @multitable @columnfractions .20 .20 .20 .25
2690 @item Name @tab Argument @tab Return type @tab Standard
2691 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2698 @section @code{BESSEL_YN} --- Bessel function of the second kind
2702 @cindex Bessel function, second kind
2705 @item @emph{Description}:
2706 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
2707 order @var{N} of @var{X}. This function is available under the name
2708 @code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays,
2709 their ranks and shapes shall conform.
2711 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
2712 of the first kind of the orders @var{N1} to @var{N2}.
2714 @item @emph{Standard}:
2715 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2718 Elemental function, except for the transformational function
2719 @code{BESSEL_YN(N1, N2, X)}
2721 @item @emph{Syntax}:
2722 @multitable @columnfractions .80
2723 @item @code{RESULT = BESSEL_YN(N, X)}
2724 @item @code{RESULT = BESSEL_YN(N1, N2, X)}
2727 @item @emph{Arguments}:
2728 @multitable @columnfractions .15 .70
2729 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} .
2730 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2731 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2732 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2733 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
2736 @item @emph{Return value}:
2737 The return value is a scalar of type @code{REAL}. It has the same
2741 The transformational function uses a recurrence algorithm which might,
2742 for some values of @var{X}, lead to different results than calls to
2743 the elemental function.
2745 @item @emph{Example}:
2748 real(8) :: x = 1.0_8
2750 end program test_besyn
2753 @item @emph{Specific names}:
2754 @multitable @columnfractions .20 .20 .20 .25
2755 @item Name @tab Argument @tab Return type @tab Standard
2756 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2757 @item @tab @code{REAL(8) X} @tab @tab
2764 @section @code{BGE} --- Bitwise greater than or equal to
2766 @cindex bitwise comparison
2769 @item @emph{Description}:
2770 Determines whether an integral is a bitwise greater than or equal to
2773 @item @emph{Standard}:
2774 Fortran 2008 and later
2779 @item @emph{Syntax}:
2780 @code{RESULT = BGE(I, J)}
2782 @item @emph{Arguments}:
2783 @multitable @columnfractions .15 .70
2784 @item @var{I} @tab Shall be of @code{INTEGER} type.
2785 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2789 @item @emph{Return value}:
2790 The return value is of type @code{LOGICAL} and of the default kind.
2792 @item @emph{See also}:
2793 @ref{BGT}, @ref{BLE}, @ref{BLT}
2799 @section @code{BGT} --- Bitwise greater than
2801 @cindex bitwise comparison
2804 @item @emph{Description}:
2805 Determines whether an integral is a bitwise greater than another.
2807 @item @emph{Standard}:
2808 Fortran 2008 and later
2813 @item @emph{Syntax}:
2814 @code{RESULT = BGT(I, J)}
2816 @item @emph{Arguments}:
2817 @multitable @columnfractions .15 .70
2818 @item @var{I} @tab Shall be of @code{INTEGER} type.
2819 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2823 @item @emph{Return value}:
2824 The return value is of type @code{LOGICAL} and of the default kind.
2826 @item @emph{See also}:
2827 @ref{BGE}, @ref{BLE}, @ref{BLT}
2833 @section @code{BIT_SIZE} --- Bit size inquiry function
2835 @cindex bits, number of
2836 @cindex size of a variable, in bits
2839 @item @emph{Description}:
2840 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
2841 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
2842 independent of the actual value of @var{I}.
2844 @item @emph{Standard}:
2845 Fortran 95 and later
2850 @item @emph{Syntax}:
2851 @code{RESULT = BIT_SIZE(I)}
2853 @item @emph{Arguments}:
2854 @multitable @columnfractions .15 .70
2855 @item @var{I} @tab The type shall be @code{INTEGER}.
2858 @item @emph{Return value}:
2859 The return value is of type @code{INTEGER}
2861 @item @emph{Example}:
2863 program test_bit_size
2868 end program test_bit_size
2875 @section @code{BLE} --- Bitwise less than or equal to
2877 @cindex bitwise comparison
2880 @item @emph{Description}:
2881 Determines whether an integral is a bitwise less than or equal to
2884 @item @emph{Standard}:
2885 Fortran 2008 and later
2890 @item @emph{Syntax}:
2891 @code{RESULT = BLE(I, J)}
2893 @item @emph{Arguments}:
2894 @multitable @columnfractions .15 .70
2895 @item @var{I} @tab Shall be of @code{INTEGER} type.
2896 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2900 @item @emph{Return value}:
2901 The return value is of type @code{LOGICAL} and of the default kind.
2903 @item @emph{See also}:
2904 @ref{BGT}, @ref{BGE}, @ref{BLT}
2910 @section @code{BLT} --- Bitwise less than
2912 @cindex bitwise comparison
2915 @item @emph{Description}:
2916 Determines whether an integral is a bitwise less than another.
2918 @item @emph{Standard}:
2919 Fortran 2008 and later
2924 @item @emph{Syntax}:
2925 @code{RESULT = BLT(I, J)}
2927 @item @emph{Arguments}:
2928 @multitable @columnfractions .15 .70
2929 @item @var{I} @tab Shall be of @code{INTEGER} type.
2930 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2934 @item @emph{Return value}:
2935 The return value is of type @code{LOGICAL} and of the default kind.
2937 @item @emph{See also}:
2938 @ref{BGE}, @ref{BGT}, @ref{BLE}
2944 @section @code{BTEST} --- Bit test function
2950 @cindex bits, testing
2953 @item @emph{Description}:
2954 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
2955 in @var{I} is set. The counting of the bits starts at 0.
2957 @item @emph{Standard}:
2958 Fortran 95 and later, has overloads that are GNU extensions
2963 @item @emph{Syntax}:
2964 @code{RESULT = BTEST(I, POS)}
2966 @item @emph{Arguments}:
2967 @multitable @columnfractions .15 .70
2968 @item @var{I} @tab The type shall be @code{INTEGER}.
2969 @item @var{POS} @tab The type shall be @code{INTEGER}.
2972 @item @emph{Return value}:
2973 The return value is of type @code{LOGICAL}
2975 @item @emph{Example}:
2978 integer :: i = 32768 + 1024 + 64
2982 bool = btest(i, pos)
2985 end program test_btest
2988 @item @emph{Specific names}:
2989 @multitable @columnfractions .20 .20 .20 .25
2990 @item Name @tab Argument @tab Return type @tab Standard
2991 @item @code{BTEST(I,POS)} @tab @code{INTEGER I,POS} @tab @code{LOGICAL} @tab F95 and later
2992 @item @code{BBTEST(I,POS)} @tab @code{INTEGER(1) I,POS} @tab @code{LOGICAL(1)} @tab GNU extension
2993 @item @code{BITEST(I,POS)} @tab @code{INTEGER(2) I,POS} @tab @code{LOGICAL(2)} @tab GNU extension
2994 @item @code{BJTEST(I,POS)} @tab @code{INTEGER(4) I,POS} @tab @code{LOGICAL(4)} @tab GNU extension
2995 @item @code{BKTEST(I,POS)} @tab @code{INTEGER(8) I,POS} @tab @code{LOGICAL(8)} @tab GNU extension
3000 @section @code{C_ASSOCIATED} --- Status of a C pointer
3001 @fnindex C_ASSOCIATED
3002 @cindex association status, C pointer
3003 @cindex pointer, C association status
3006 @item @emph{Description}:
3007 @code{C_ASSOCIATED(c_ptr_1[, c_ptr_2])} determines the status of the C pointer
3008 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
3010 @item @emph{Standard}:
3011 Fortran 2003 and later
3016 @item @emph{Syntax}:
3017 @code{RESULT = C_ASSOCIATED(c_ptr_1[, c_ptr_2])}
3019 @item @emph{Arguments}:
3020 @multitable @columnfractions .15 .70
3021 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
3022 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
3025 @item @emph{Return value}:
3026 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
3027 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
3028 point to different addresses.
3030 @item @emph{Example}:
3032 subroutine association_test(a,b)
3033 use iso_c_binding, only: c_associated, c_loc, c_ptr
3037 if(c_associated(b, c_loc(a))) &
3038 stop 'b and a do not point to same target'
3039 end subroutine association_test
3042 @item @emph{See also}:
3043 @ref{C_LOC}, @ref{C_FUNLOC}
3048 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
3049 @fnindex C_F_POINTER
3050 @cindex pointer, convert C to Fortran
3053 @item @emph{Description}:
3054 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} assigns the target of the C pointer
3055 @var{CPTR} to the Fortran pointer @var{FPTR} and specifies its shape.
3057 @item @emph{Standard}:
3058 Fortran 2003 and later
3063 @item @emph{Syntax}:
3064 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
3066 @item @emph{Arguments}:
3067 @multitable @columnfractions .15 .70
3068 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
3070 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
3072 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
3073 with @code{INTENT(IN)}. It shall be present
3074 if and only if @var{fptr} is an array. The size
3075 must be equal to the rank of @var{fptr}.
3078 @item @emph{Example}:
3084 subroutine my_routine(p) bind(c,name='myC_func')
3086 type(c_ptr), intent(out) :: p
3090 real,pointer :: a(:)
3091 call my_routine(cptr)
3092 call c_f_pointer(cptr, a, [12])
3096 @item @emph{See also}:
3097 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
3101 @node C_F_PROCPOINTER
3102 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
3103 @fnindex C_F_PROCPOINTER
3104 @cindex pointer, C address of pointers
3107 @item @emph{Description}:
3108 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
3109 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
3111 @item @emph{Standard}:
3112 Fortran 2003 and later
3117 @item @emph{Syntax}:
3118 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
3120 @item @emph{Arguments}:
3121 @multitable @columnfractions .15 .70
3122 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
3124 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
3128 @item @emph{Example}:
3136 real(c_float), intent(in) :: a
3137 real(c_float) :: func
3141 function getIterFunc() bind(c,name="getIterFunc")
3143 type(c_funptr) :: getIterFunc
3146 type(c_funptr) :: cfunptr
3147 procedure(func), pointer :: myFunc
3148 cfunptr = getIterFunc()
3149 call c_f_procpointer(cfunptr, myFunc)
3153 @item @emph{See also}:
3154 @ref{C_LOC}, @ref{C_F_POINTER}
3159 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
3161 @cindex pointer, C address of procedures
3164 @item @emph{Description}:
3165 @code{C_FUNLOC(x)} determines the C address of the argument.
3167 @item @emph{Standard}:
3168 Fortran 2003 and later
3173 @item @emph{Syntax}:
3174 @code{RESULT = C_FUNLOC(x)}
3176 @item @emph{Arguments}:
3177 @multitable @columnfractions .15 .70
3178 @item @var{x} @tab Interoperable function or pointer to such function.
3181 @item @emph{Return value}:
3182 The return value is of type @code{C_FUNPTR} and contains the C address
3185 @item @emph{Example}:
3191 subroutine sub(a) bind(c)
3201 subroutine my_routine(p) bind(c,name='myC_func')
3203 type(c_funptr), intent(in) :: p
3206 call my_routine(c_funloc(sub))
3210 @item @emph{See also}:
3211 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
3216 @section @code{C_LOC} --- Obtain the C address of an object
3218 @cindex procedure pointer, convert C to Fortran
3221 @item @emph{Description}:
3222 @code{C_LOC(X)} determines the C address of the argument.
3224 @item @emph{Standard}:
3225 Fortran 2003 and later
3230 @item @emph{Syntax}:
3231 @code{RESULT = C_LOC(X)}
3233 @item @emph{Arguments}:
3234 @multitable @columnfractions .10 .75
3235 @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.
3239 @item @emph{Return value}:
3240 The return value is of type @code{C_PTR} and contains the C address
3243 @item @emph{Example}:
3245 subroutine association_test(a,b)
3246 use iso_c_binding, only: c_associated, c_loc, c_ptr
3250 if(c_associated(b, c_loc(a))) &
3251 stop 'b and a do not point to same target'
3252 end subroutine association_test
3255 @item @emph{See also}:
3256 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
3261 @section @code{C_SIZEOF} --- Size in bytes of an expression
3263 @cindex expression size
3264 @cindex size of an expression
3267 @item @emph{Description}:
3268 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
3269 expression @code{X} occupies.
3271 @item @emph{Standard}:
3275 Inquiry function of the module @code{ISO_C_BINDING}
3277 @item @emph{Syntax}:
3278 @code{N = C_SIZEOF(X)}
3280 @item @emph{Arguments}:
3281 @multitable @columnfractions .15 .70
3282 @item @var{X} @tab The argument shall be an interoperable data entity.
3285 @item @emph{Return value}:
3286 The return value is of type integer and of the system-dependent kind
3287 @code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the
3288 number of bytes occupied by the argument. If the argument has the
3289 @code{POINTER} attribute, the number of bytes of the storage area pointed
3290 to is returned. If the argument is of a derived type with @code{POINTER}
3291 or @code{ALLOCATABLE} components, the return value does not account for
3292 the sizes of the data pointed to by these components.
3294 @item @emph{Example}:
3298 real(c_float) :: r, s(5)
3299 print *, (c_sizeof(s)/c_sizeof(r) == 5)
3302 The example will print @code{.TRUE.} unless you are using a platform
3303 where default @code{REAL} variables are unusually padded.
3305 @item @emph{See also}:
3306 @ref{SIZEOF}, @ref{STORAGE_SIZE}
3311 @section @code{CEILING} --- Integer ceiling function
3314 @cindex rounding, ceiling
3317 @item @emph{Description}:
3318 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
3320 @item @emph{Standard}:
3321 Fortran 95 and later
3326 @item @emph{Syntax}:
3327 @code{RESULT = CEILING(A [, KIND])}
3329 @item @emph{Arguments}:
3330 @multitable @columnfractions .15 .70
3331 @item @var{A} @tab The type shall be @code{REAL}.
3332 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3333 expression indicating the kind parameter of the result.
3336 @item @emph{Return value}:
3337 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
3338 and a default-kind @code{INTEGER} otherwise.
3340 @item @emph{Example}:
3342 program test_ceiling
3345 print *, ceiling(x) ! returns 64
3346 print *, ceiling(y) ! returns -63
3347 end program test_ceiling
3350 @item @emph{See also}:
3351 @ref{FLOOR}, @ref{NINT}
3358 @section @code{CHAR} --- Character conversion function
3360 @cindex conversion, to character
3363 @item @emph{Description}:
3364 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
3366 @item @emph{Standard}:
3367 Fortran 77 and later
3372 @item @emph{Syntax}:
3373 @code{RESULT = CHAR(I [, KIND])}
3375 @item @emph{Arguments}:
3376 @multitable @columnfractions .15 .70
3377 @item @var{I} @tab The type shall be @code{INTEGER}.
3378 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3379 expression indicating the kind parameter of the result.
3382 @item @emph{Return value}:
3383 The return value is of type @code{CHARACTER(1)}
3385 @item @emph{Example}:
3391 print *, i, c ! returns 'J'
3392 end program test_char
3395 @item @emph{Specific names}:
3396 @multitable @columnfractions .20 .20 .20 .25
3397 @item Name @tab Argument @tab Return type @tab Standard
3398 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
3402 See @ref{ICHAR} for a discussion of converting between numerical values
3403 and formatted string representations.
3405 @item @emph{See also}:
3406 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
3413 @section @code{CHDIR} --- Change working directory
3415 @cindex system, working directory
3418 @item @emph{Description}:
3419 Change current working directory to a specified path.
3421 This intrinsic is provided in both subroutine and function forms; however,
3422 only one form can be used in any given program unit.
3424 @item @emph{Standard}:
3428 Subroutine, function
3430 @item @emph{Syntax}:
3431 @multitable @columnfractions .80
3432 @item @code{CALL CHDIR(NAME [, STATUS])}
3433 @item @code{STATUS = CHDIR(NAME)}
3436 @item @emph{Arguments}:
3437 @multitable @columnfractions .15 .70
3438 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
3439 kind and shall specify a valid path within the file system.
3440 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
3441 kind. Returns 0 on success, and a system specific and nonzero error code
3445 @item @emph{Example}:
3448 CHARACTER(len=255) :: path
3450 WRITE(*,*) TRIM(path)
3453 WRITE(*,*) TRIM(path)
3457 @item @emph{See also}:
3464 @section @code{CHMOD} --- Change access permissions of files
3466 @cindex file system, change access mode
3469 @item @emph{Description}:
3470 @code{CHMOD} changes the permissions of a file.
3472 This intrinsic is provided in both subroutine and function forms; however,
3473 only one form can be used in any given program unit.
3475 @item @emph{Standard}:
3479 Subroutine, function
3481 @item @emph{Syntax}:
3482 @multitable @columnfractions .80
3483 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
3484 @item @code{STATUS = CHMOD(NAME, MODE)}
3487 @item @emph{Arguments}:
3488 @multitable @columnfractions .15 .70
3490 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
3491 file name. Trailing blanks are ignored unless the character
3492 @code{achar(0)} is present, then all characters up to and excluding
3493 @code{achar(0)} are used as the file name.
3495 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
3496 file permission. @var{MODE} uses the same syntax as the @code{chmod} utility
3497 as defined by the POSIX standard. The argument shall either be a string of
3498 a nonnegative octal number or a symbolic mode.
3500 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
3501 @code{0} on success and nonzero otherwise.
3504 @item @emph{Return value}:
3505 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
3508 @item @emph{Example}:
3509 @code{CHMOD} as subroutine
3514 call chmod('test.dat','u+x',status)
3515 print *, 'Status: ', status
3516 end program chmod_test
3518 @code{CHMOD} as function:
3523 status = chmod('test.dat','u+x')
3524 print *, 'Status: ', status
3525 end program chmod_test
3533 @section @code{CMPLX} --- Complex conversion function
3535 @cindex complex numbers, conversion to
3536 @cindex conversion, to complex
3539 @item @emph{Description}:
3540 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
3541 the real component. If @var{Y} is present it is converted to the imaginary
3542 component. If @var{Y} is not present then the imaginary component is set to
3543 0.0. If @var{X} is complex then @var{Y} must not be present.
3545 @item @emph{Standard}:
3546 Fortran 77 and later
3551 @item @emph{Syntax}:
3552 @code{RESULT = CMPLX(X [, Y [, KIND]])}
3554 @item @emph{Arguments}:
3555 @multitable @columnfractions .15 .70
3556 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3558 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
3559 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
3560 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3561 expression indicating the kind parameter of the result.
3564 @item @emph{Return value}:
3565 The return value is of @code{COMPLEX} type, with a kind equal to
3566 @var{KIND} if it is specified. If @var{KIND} is not specified, the
3567 result is of the default @code{COMPLEX} kind, regardless of the kinds of
3568 @var{X} and @var{Y}.
3570 @item @emph{Example}:
3577 print *, z, cmplx(x)
3578 end program test_cmplx
3581 @item @emph{See also}:
3588 @section @code{CO_BROADCAST} --- Copy a value to all images the current set of images
3589 @fnindex CO_BROADCAST
3590 @cindex Collectives, value broadcasting
3593 @item @emph{Description}:
3594 @code{CO_BROADCAST} copies the value of argument @var{A} on the image with
3595 image index @code{SOURCE_IMAGE} to all images in the current team. @var{A}
3596 becomes defined as if by intrinsic assignment. If the execution was
3597 successful and @var{STAT} is present, it is assigned the value zero. If the
3598 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3599 @var{ERRMSG} gets assigned a value describing the occurred error.
3601 @item @emph{Standard}:
3602 Technical Specification (TS) 18508 or later
3605 Collective subroutine
3607 @item @emph{Syntax}:
3608 @code{CALL CO_BROADCAST(A, SOURCE_IMAGE [, STAT, ERRMSG])}
3610 @item @emph{Arguments}:
3611 @multitable @columnfractions .15 .70
3612 @item @var{A} @tab INTENT(INOUT) argument; shall have the same
3613 dynamic type and type paramters on all images of the current team. If it
3614 is an array, it shall have the same shape on all images.
3615 @item @var{SOURCE_IMAGE} @tab a scalar integer expression.
3616 It shall have the same the same value on all images and refer to an
3617 image of the current team.
3618 @item @var{STAT} @tab (optional) a scalar integer variable
3619 @item @var{ERRMSG} @tab (optional) a scalar character variable
3622 @item @emph{Example}:
3626 if (this_image() == 1) then
3629 call co_broadcast (val, source_image=1)
3630 print *, this_image, ":", val
3634 @item @emph{See also}:
3635 @ref{CO_MAX}, @ref{CO_MIN}, @ref{CO_SUM}, @ref{CO_REDUCE}
3641 @section @code{CO_MAX} --- Maximal value on the current set of images
3643 @cindex Collectives, maximal value
3646 @item @emph{Description}:
3647 @code{CO_MAX} determines element-wise the maximal value of @var{A} on all
3648 images of the current team. If @var{RESULT_IMAGE} is present, the maximum
3649 values are returned in @var{A} on the specified image only and the value
3650 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3651 not present, the value is returned on all images. If the execution was
3652 successful and @var{STAT} is present, it is assigned the value zero. If the
3653 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3654 @var{ERRMSG} gets assigned a value describing the occurred error.
3656 @item @emph{Standard}:
3657 Technical Specification (TS) 18508 or later
3660 Collective subroutine
3662 @item @emph{Syntax}:
3663 @code{CALL CO_MAX(A [, RESULT_IMAGE, STAT, ERRMSG])}
3665 @item @emph{Arguments}:
3666 @multitable @columnfractions .15 .70
3667 @item @var{A} @tab shall be an integer, real or character variable,
3668 which has the same type and type parameters on all images of the team.
3669 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3670 present, it shall have the same the same value on all images and refer to an
3671 image of the current team.
3672 @item @var{STAT} @tab (optional) a scalar integer variable
3673 @item @var{ERRMSG} @tab (optional) a scalar character variable
3676 @item @emph{Example}:
3681 call co_max (val, result_image=1)
3682 if (this_image() == 1) then
3683 write(*,*) "Maximal value", val ! prints num_images()
3688 @item @emph{See also}:
3689 @ref{CO_MIN}, @ref{CO_SUM}, @ref{CO_REDUCE}, @ref{CO_BROADCAST}
3695 @section @code{CO_MIN} --- Minimal value on the current set of images
3697 @cindex Collectives, minimal value
3700 @item @emph{Description}:
3701 @code{CO_MIN} determines element-wise the minimal value of @var{A} on all
3702 images of the current team. If @var{RESULT_IMAGE} is present, the minimal
3703 values are returned in @var{A} on the specified image only and the value
3704 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3705 not present, the value is returned on all images. If the execution was
3706 successful and @var{STAT} is present, it is assigned the value zero. If the
3707 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3708 @var{ERRMSG} gets assigned a value describing the occurred error.
3710 @item @emph{Standard}:
3711 Technical Specification (TS) 18508 or later
3714 Collective subroutine
3716 @item @emph{Syntax}:
3717 @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3719 @item @emph{Arguments}:
3720 @multitable @columnfractions .15 .70
3721 @item @var{A} @tab shall be an integer, real or character variable,
3722 which has the same type and type parameters on all images of the team.
3723 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3724 present, it shall have the same the same value on all images and refer to an
3725 image of the current team.
3726 @item @var{STAT} @tab (optional) a scalar integer variable
3727 @item @var{ERRMSG} @tab (optional) a scalar character variable
3730 @item @emph{Example}:
3735 call co_min (val, result_image=1)
3736 if (this_image() == 1) then
3737 write(*,*) "Minimal value", val ! prints 1
3742 @item @emph{See also}:
3743 @ref{CO_MAX}, @ref{CO_SUM}, @ref{CO_REDUCE}, @ref{CO_BROADCAST}
3749 @section @code{CO_REDUCE} --- Reduction of values on the current set of images
3751 @cindex Collectives, generic reduction
3754 @item @emph{Description}:
3755 @code{CO_REDUCE} determines element-wise the reduction of the value of @var{A}
3756 on all images of the current team. The pure function passed as @var{OPERATOR}
3757 is used to pairwise reduce the values of @var{A} by passing either the value
3758 of @var{A} of different images or the result values of such a reduction as
3759 argument. If @var{A} is an array, the deduction is done element wise. If
3760 @var{RESULT_IMAGE} is present, the result values are returned in @var{A} on
3761 the specified image only and the value of @var{A} on the other images become
3762 undefined. If @var{RESULT_IMAGE} is not present, the value is returned on all
3763 images. If the execution was successful and @var{STAT} is present, it is
3764 assigned the value zero. If the execution failed, @var{STAT} gets assigned
3765 a nonzero value and, if present, @var{ERRMSG} gets assigned a value describing
3768 @item @emph{Standard}:
3769 Technical Specification (TS) 18508 or later
3772 Collective subroutine
3774 @item @emph{Syntax}:
3775 @code{CALL CO_REDUCE(A, OPERATOR, [, RESULT_IMAGE, STAT, ERRMSG])}
3777 @item @emph{Arguments}:
3778 @multitable @columnfractions .15 .70
3779 @item @var{A} @tab is an @code{INTENT(INOUT)} argument and shall be
3780 nonpolymorphic. If it is allocatable, it shall be allocated; if it is a pointer,
3781 it shall be associated. @var{A} shall have the same type and type parameters on
3782 all images of the team; if it is an array, it shall have the same shape on all
3784 @item @var{OPERATOR} @tab pure function with two scalar nonallocatable
3785 arguments, which shall be nonpolymorphic and have the same type and type
3786 parameters as @var{A}. The function shall return a nonallocatable scalar of
3787 the same type and type parameters as @var{A}. The function shall be the same on
3788 all images and with regards to the arguments mathematically commutative and
3789 associative. Note that @var{OPERATOR} may not be an elemental function, unless
3790 it is an intrisic function.
3791 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3792 present, it shall have the same the same value on all images and refer to an
3793 image of the current team.
3794 @item @var{STAT} @tab (optional) a scalar integer variable
3795 @item @var{ERRMSG} @tab (optional) a scalar character variable
3798 @item @emph{Example}:
3803 call co_reduce (val, result_image=1, operator=myprod)
3804 if (this_image() == 1) then
3805 write(*,*) "Product value", val ! prints num_images() factorial
3808 pure function myprod(a, b)
3809 integer, value :: a, b
3817 While the rules permit in principle an intrinsic function, none of the
3818 intrinsics in the standard fulfill the criteria of having a specific
3819 function, which takes two arguments of the same type and returning that
3822 @item @emph{See also}:
3823 @ref{CO_MIN}, @ref{CO_MAX}, @ref{CO_SUM}, @ref{CO_BROADCAST}
3829 @section @code{CO_SUM} --- Sum of values on the current set of images
3831 @cindex Collectives, sum of values
3834 @item @emph{Description}:
3835 @code{CO_SUM} sums up the values of each element of @var{A} on all
3836 images of the current team. If @var{RESULT_IMAGE} is present, the summed-up
3837 values are returned in @var{A} on the specified image only and the value
3838 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3839 not present, the value is returned on all images. If the execution was
3840 successful and @var{STAT} is present, it is assigned the value zero. If the
3841 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3842 @var{ERRMSG} gets assigned a value describing the occurred error.
3844 @item @emph{Standard}:
3845 Technical Specification (TS) 18508 or later
3848 Collective subroutine
3850 @item @emph{Syntax}:
3851 @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3853 @item @emph{Arguments}:
3854 @multitable @columnfractions .15 .70
3855 @item @var{A} @tab shall be an integer, real or complex variable,
3856 which has the same type and type parameters on all images of the team.
3857 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3858 present, it shall have the same the same value on all images and refer to an
3859 image of the current team.
3860 @item @var{STAT} @tab (optional) a scalar integer variable
3861 @item @var{ERRMSG} @tab (optional) a scalar character variable
3864 @item @emph{Example}:
3869 call co_sum (val, result_image=1)
3870 if (this_image() == 1) then
3871 write(*,*) "The sum is ", val ! prints (n**2 + n)/2, with n = num_images()
3876 @item @emph{See also}:
3877 @ref{CO_MAX}, @ref{CO_MIN}, @ref{CO_REDUCE}, @ref{CO_BROADCAST}
3882 @node COMMAND_ARGUMENT_COUNT
3883 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
3884 @fnindex COMMAND_ARGUMENT_COUNT
3885 @cindex command-line arguments
3886 @cindex command-line arguments, number of
3887 @cindex arguments, to program
3890 @item @emph{Description}:
3891 @code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the
3892 command line when the containing program was invoked.
3894 @item @emph{Standard}:
3895 Fortran 2003 and later
3900 @item @emph{Syntax}:
3901 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
3903 @item @emph{Arguments}:
3904 @multitable @columnfractions .15 .70
3908 @item @emph{Return value}:
3909 The return value is an @code{INTEGER} of default kind.
3911 @item @emph{Example}:
3913 program test_command_argument_count
3915 count = command_argument_count()
3917 end program test_command_argument_count
3920 @item @emph{See also}:
3921 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
3926 @node COMPILER_OPTIONS
3927 @section @code{COMPILER_OPTIONS} --- Options passed to the compiler
3928 @fnindex COMPILER_OPTIONS
3929 @cindex flags inquiry function
3930 @cindex options inquiry function
3931 @cindex compiler flags inquiry function
3934 @item @emph{Description}:
3935 @code{COMPILER_OPTIONS} returns a string with the options used for
3938 @item @emph{Standard}:
3942 Inquiry function of the module @code{ISO_FORTRAN_ENV}
3944 @item @emph{Syntax}:
3945 @code{STR = COMPILER_OPTIONS()}
3947 @item @emph{Arguments}:
3950 @item @emph{Return value}:
3951 The return value is a default-kind string with system-dependent length.
3952 It contains the compiler flags used to compile the file, which called
3953 the @code{COMPILER_OPTIONS} intrinsic.
3955 @item @emph{Example}:
3958 print '(4a)', 'This file was compiled by ', &
3959 compiler_version(), ' using the options ', &
3964 @item @emph{See also}:
3965 @ref{COMPILER_VERSION}, @ref{ISO_FORTRAN_ENV}
3970 @node COMPILER_VERSION
3971 @section @code{COMPILER_VERSION} --- Compiler version string
3972 @fnindex COMPILER_VERSION
3973 @cindex compiler, name and version
3974 @cindex version of the compiler
3977 @item @emph{Description}:
3978 @code{COMPILER_VERSION} returns a string with the name and the
3979 version of the compiler.
3981 @item @emph{Standard}:
3985 Inquiry function of the module @code{ISO_FORTRAN_ENV}
3987 @item @emph{Syntax}:
3988 @code{STR = COMPILER_VERSION()}
3990 @item @emph{Arguments}:
3993 @item @emph{Return value}:
3994 The return value is a default-kind string with system-dependent length.
3995 It contains the name of the compiler and its version number.
3997 @item @emph{Example}:
4000 print '(4a)', 'This file was compiled by ', &
4001 compiler_version(), ' using the options ', &
4006 @item @emph{See also}:
4007 @ref{COMPILER_OPTIONS}, @ref{ISO_FORTRAN_ENV}
4013 @section @code{COMPLEX} --- Complex conversion function
4015 @cindex complex numbers, conversion to
4016 @cindex conversion, to complex
4019 @item @emph{Description}:
4020 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
4021 to the real component and @var{Y} is converted to the imaginary
4024 @item @emph{Standard}:
4030 @item @emph{Syntax}:
4031 @code{RESULT = COMPLEX(X, Y)}
4033 @item @emph{Arguments}:
4034 @multitable @columnfractions .15 .70
4035 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
4036 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
4039 @item @emph{Return value}:
4040 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
4041 value is of default @code{COMPLEX} type.
4043 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
4044 type and one is of @code{INTEGER} type, then the return value is of
4045 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
4046 argument with the highest precision.
4048 @item @emph{Example}:
4050 program test_complex
4053 print *, complex(i, x)
4054 end program test_complex
4057 @item @emph{See also}:
4064 @section @code{CONJG} --- Complex conjugate function
4067 @cindex complex conjugate
4070 @item @emph{Description}:
4071 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
4072 then the result is @code{(x, -y)}
4074 @item @emph{Standard}:
4075 Fortran 77 and later, has overloads that are GNU extensions
4080 @item @emph{Syntax}:
4083 @item @emph{Arguments}:
4084 @multitable @columnfractions .15 .70
4085 @item @var{Z} @tab The type shall be @code{COMPLEX}.
4088 @item @emph{Return value}:
4089 The return value is of type @code{COMPLEX}.
4091 @item @emph{Example}:
4094 complex :: z = (2.0, 3.0)
4095 complex(8) :: dz = (2.71_8, -3.14_8)
4100 end program test_conjg
4103 @item @emph{Specific names}:
4104 @multitable @columnfractions .20 .20 .20 .25
4105 @item Name @tab Argument @tab Return type @tab Standard
4106 @item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension
4107 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
4114 @section @code{COS} --- Cosine function
4120 @cindex trigonometric function, cosine
4124 @item @emph{Description}:
4125 @code{COS(X)} computes the cosine of @var{X}.
4127 @item @emph{Standard}:
4128 Fortran 77 and later, has overloads that are GNU extensions
4133 @item @emph{Syntax}:
4134 @code{RESULT = COS(X)}
4136 @item @emph{Arguments}:
4137 @multitable @columnfractions .15 .70
4138 @item @var{X} @tab The type shall be @code{REAL} or
4142 @item @emph{Return value}:
4143 The return value is of the same type and kind as @var{X}. The real part
4144 of the result is in radians. If @var{X} is of the type @code{REAL},
4145 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
4147 @item @emph{Example}:
4152 end program test_cos
4155 @item @emph{Specific names}:
4156 @multitable @columnfractions .20 .20 .20 .25
4157 @item Name @tab Argument @tab Return type @tab Standard
4158 @item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
4159 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
4160 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
4161 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4162 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4165 @item @emph{See also}:
4166 Inverse function: @ref{ACOS}
4167 Degrees function: @ref{COSD}
4174 @section @code{COSD} --- Cosine function, degrees
4180 @cindex trigonometric function, cosine, degrees
4181 @cindex cosine, degrees
4184 @item @emph{Description}:
4185 @code{COSD(X)} computes the cosine of @var{X} in degrees.
4187 This function is for compatibility only and should be avoided in favor of
4188 standard constructs wherever possible.
4190 @item @emph{Standard}:
4191 GNU Extension, enabled with @option{-fdec-math}.
4196 @item @emph{Syntax}:
4197 @code{RESULT = COSD(X)}
4199 @item @emph{Arguments}:
4200 @multitable @columnfractions .15 .70
4201 @item @var{X} @tab The type shall be @code{REAL} or
4205 @item @emph{Return value}:
4206 The return value is of the same type and kind as @var{X}. The real part
4207 of the result is in degrees. If @var{X} is of the type @code{REAL},
4208 the return value lies in the range @math{ -1 \leq \cosd (x) \leq 1}.
4210 @item @emph{Example}:
4215 end program test_cosd
4218 @item @emph{Specific names}:
4219 @multitable @columnfractions .20 .20 .20 .25
4220 @item Name @tab Argument @tab Return type @tab Standard
4221 @item @code{COSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4222 @item @code{DCOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4223 @item @code{CCOSD(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU Extension
4224 @item @code{ZCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4225 @item @code{CDCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4228 @item @emph{See also}:
4229 Inverse function: @ref{ACOSD}
4230 Radians function: @ref{COS}
4237 @section @code{COSH} --- Hyperbolic cosine function
4240 @cindex hyperbolic cosine
4241 @cindex hyperbolic function, cosine
4242 @cindex cosine, hyperbolic
4245 @item @emph{Description}:
4246 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
4248 @item @emph{Standard}:
4249 Fortran 77 and later, for a complex argument Fortran 2008 or later
4254 @item @emph{Syntax}:
4257 @item @emph{Arguments}:
4258 @multitable @columnfractions .15 .70
4259 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4262 @item @emph{Return value}:
4263 The return value has same type and kind as @var{X}. If @var{X} is
4264 complex, the imaginary part of the result is in radians. If @var{X}
4265 is @code{REAL}, the return value has a lower bound of one,
4266 @math{\cosh (x) \geq 1}.
4268 @item @emph{Example}:
4271 real(8) :: x = 1.0_8
4273 end program test_cosh
4276 @item @emph{Specific names}:
4277 @multitable @columnfractions .20 .20 .20 .25
4278 @item Name @tab Argument @tab Return type @tab Standard
4279 @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
4280 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
4283 @item @emph{See also}:
4284 Inverse function: @ref{ACOSH}
4291 @section @code{COTAN} --- Cotangent function
4294 @cindex trigonometric function, cotangent
4298 @item @emph{Description}:
4299 @code{COTAN(X)} computes the cotangent of @var{X}. Equivalent to @code{COS(x)}
4300 divided by @code{SIN(x)}, or @code{1 / TAN(x)}.
4302 This function is for compatibility only and should be avoided in favor of
4303 standard constructs wherever possible.
4305 @item @emph{Standard}:
4306 GNU Extension, enabled with @option{-fdec-math}.
4311 @item @emph{Syntax}:
4312 @code{RESULT = COTAN(X)}
4314 @item @emph{Arguments}:
4315 @multitable @columnfractions .15 .70
4316 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4319 @item @emph{Return value}:
4320 The return value has same type and kind as @var{X}, and its value is in radians.
4322 @item @emph{Example}:
4325 real(8) :: x = 0.165_8
4327 end program test_cotan
4330 @item @emph{Specific names}:
4331 @multitable @columnfractions .20 .20 .20 .25
4332 @item Name @tab Argument @tab Return type @tab Standard
4333 @item @code{COTAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4334 @item @code{DCOTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4337 @item @emph{See also}:
4338 Converse function: @ref{TAN}
4339 Degrees function: @ref{COTAND}
4345 @section @code{COTAND} --- Cotangent function, degrees
4348 @cindex trigonometric function, cotangent, degrees
4349 @cindex cotangent, degrees
4352 @item @emph{Description}:
4353 @code{COTAND(X)} computes the cotangent of @var{X} in degrees. Equivalent to
4354 @code{COSD(x)} divided by @code{SIND(x)}, or @code{1 / TAND(x)}.
4356 @item @emph{Standard}:
4357 GNU Extension, enabled with @option{-fdec-math}.
4359 This function is for compatibility only and should be avoided in favor of
4360 standard constructs wherever possible.
4365 @item @emph{Syntax}:
4366 @code{RESULT = COTAND(X)}
4368 @item @emph{Arguments}:
4369 @multitable @columnfractions .15 .70
4370 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4373 @item @emph{Return value}:
4374 The return value has same type and kind as @var{X}, and its value is in degrees.
4376 @item @emph{Example}:
4379 real(8) :: x = 0.165_8
4381 end program test_cotand
4384 @item @emph{Specific names}:
4385 @multitable @columnfractions .20 .20 .20 .25
4386 @item Name @tab Argument @tab Return type @tab Standard
4387 @item @code{COTAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4388 @item @code{DCOTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4391 @item @emph{See also}:
4392 Converse function: @ref{TAND}
4393 Radians function: @ref{COTAN}
4400 @section @code{COUNT} --- Count function
4402 @cindex array, conditionally count elements
4403 @cindex array, element counting
4404 @cindex array, number of elements
4407 @item @emph{Description}:
4409 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
4410 or, if the @var{DIM} argument is supplied, counts the number of
4411 elements along each row of the array in the @var{DIM} direction.
4412 If the array has zero size, or all of the elements of @var{MASK} are
4413 @code{.FALSE.}, then the result is @code{0}.
4415 @item @emph{Standard}:
4416 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
4419 Transformational function
4421 @item @emph{Syntax}:
4422 @code{RESULT = COUNT(MASK [, DIM, KIND])}
4424 @item @emph{Arguments}:
4425 @multitable @columnfractions .15 .70
4426 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
4427 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
4428 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4429 expression indicating the kind parameter of the result.
4432 @item @emph{Return value}:
4433 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
4434 @var{KIND} is absent, the return value is of default integer kind.
4435 If @var{DIM} is present, the result is an array with a rank one less
4436 than the rank of @var{ARRAY}, and a size corresponding to the shape
4437 of @var{ARRAY} with the @var{DIM} dimension removed.
4439 @item @emph{Example}:
4442 integer, dimension(2,3) :: a, b
4443 logical, dimension(2,3) :: mask
4444 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
4445 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
4446 print '(3i3)', a(1,:)
4447 print '(3i3)', a(2,:)
4449 print '(3i3)', b(1,:)
4450 print '(3i3)', b(2,:)
4453 print '(3l3)', mask(1,:)
4454 print '(3l3)', mask(2,:)
4456 print '(3i3)', count(mask)
4458 print '(3i3)', count(mask, 1)
4460 print '(3i3)', count(mask, 2)
4461 end program test_count
4468 @section @code{CPU_TIME} --- CPU elapsed time in seconds
4470 @cindex time, elapsed
4473 @item @emph{Description}:
4474 Returns a @code{REAL} value representing the elapsed CPU time in
4475 seconds. This is useful for testing segments of code to determine
4478 If a time source is available, time will be reported with microsecond
4479 resolution. If no time source is available, @var{TIME} is set to
4482 Note that @var{TIME} may contain a, system dependent, arbitrary offset
4483 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
4484 value is meaningless, only differences between subsequent calls to
4485 this subroutine, as shown in the example below, should be used.
4488 @item @emph{Standard}:
4489 Fortran 95 and later
4494 @item @emph{Syntax}:
4495 @code{CALL CPU_TIME(TIME)}
4497 @item @emph{Arguments}:
4498 @multitable @columnfractions .15 .70
4499 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
4502 @item @emph{Return value}:
4505 @item @emph{Example}:
4507 program test_cpu_time
4508 real :: start, finish
4509 call cpu_time(start)
4510 ! put code to test here
4511 call cpu_time(finish)
4512 print '("Time = ",f6.3," seconds.")',finish-start
4513 end program test_cpu_time
4516 @item @emph{See also}:
4517 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
4523 @section @code{CSHIFT} --- Circular shift elements of an array
4525 @cindex array, shift circularly
4526 @cindex array, permutation
4527 @cindex array, rotate
4530 @item @emph{Description}:
4531 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
4532 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
4533 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
4534 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
4535 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
4536 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
4537 sections of @var{ARRAY} along the given dimension are shifted. Elements
4538 shifted out one end of each rank one section are shifted back in the other end.
4540 @item @emph{Standard}:
4541 Fortran 95 and later
4544 Transformational function
4546 @item @emph{Syntax}:
4547 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
4549 @item @emph{Arguments}:
4550 @multitable @columnfractions .15 .70
4551 @item @var{ARRAY} @tab Shall be an array of any type.
4552 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
4553 @item @var{DIM} @tab The type shall be @code{INTEGER}.
4556 @item @emph{Return value}:
4557 Returns an array of same type and rank as the @var{ARRAY} argument.
4559 @item @emph{Example}:
4562 integer, dimension(3,3) :: a
4563 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
4564 print '(3i3)', a(1,:)
4565 print '(3i3)', a(2,:)
4566 print '(3i3)', a(3,:)
4567 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
4569 print '(3i3)', a(1,:)
4570 print '(3i3)', a(2,:)
4571 print '(3i3)', a(3,:)
4572 end program test_cshift
4579 @section @code{CTIME} --- Convert a time into a string
4581 @cindex time, conversion to string
4582 @cindex conversion, to string
4585 @item @emph{Description}:
4586 @code{CTIME} converts a system time value, such as returned by
4587 @ref{TIME8}, to a string. The output will be of the form @samp{Sat
4588 Aug 19 18:13:14 1995}.
4590 This intrinsic is provided in both subroutine and function forms; however,
4591 only one form can be used in any given program unit.
4593 @item @emph{Standard}:
4597 Subroutine, function
4599 @item @emph{Syntax}:
4600 @multitable @columnfractions .80
4601 @item @code{CALL CTIME(TIME, RESULT)}.
4602 @item @code{RESULT = CTIME(TIME)}.
4605 @item @emph{Arguments}:
4606 @multitable @columnfractions .15 .70
4607 @item @var{TIME} @tab The type shall be of type @code{INTEGER}.
4608 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
4609 of default kind. It is an @code{INTENT(OUT)} argument. If the length
4610 of this variable is too short for the time and date string to fit
4611 completely, it will be blank on procedure return.
4614 @item @emph{Return value}:
4615 The converted date and time as a string.
4617 @item @emph{Example}:
4621 character(len=30) :: date
4624 ! Do something, main part of the program
4627 print *, 'Program was started on ', date
4628 end program test_ctime
4631 @item @emph{See Also}:
4632 @ref{DATE_AND_TIME}, @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
4638 @section @code{DATE_AND_TIME} --- Date and time subroutine
4639 @fnindex DATE_AND_TIME
4640 @cindex date, current
4641 @cindex current date
4642 @cindex time, current
4643 @cindex current time
4646 @item @emph{Description}:
4647 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
4648 time information from the real-time system clock. @var{DATE} is
4649 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
4650 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
4651 representing the difference with respect to Coordinated Universal Time (UTC).
4652 Unavailable time and date parameters return blanks.
4654 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
4656 @multitable @columnfractions .15 .30 .40
4657 @item @tab @code{VALUE(1)}: @tab The year
4658 @item @tab @code{VALUE(2)}: @tab The month
4659 @item @tab @code{VALUE(3)}: @tab The day of the month
4660 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
4661 @item @tab @code{VALUE(5)}: @tab The hour of the day
4662 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
4663 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
4664 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
4667 @item @emph{Standard}:
4668 Fortran 95 and later
4673 @item @emph{Syntax}:
4674 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
4676 @item @emph{Arguments}:
4677 @multitable @columnfractions .15 .70
4678 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
4679 or larger, and of default kind.
4680 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
4681 or larger, and of default kind.
4682 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
4683 or larger, and of default kind.
4684 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
4687 @item @emph{Return value}:
4690 @item @emph{Example}:
4692 program test_time_and_date
4693 character(8) :: date
4694 character(10) :: time
4695 character(5) :: zone
4696 integer,dimension(8) :: values
4697 ! using keyword arguments
4698 call date_and_time(date,time,zone,values)
4699 call date_and_time(DATE=date,ZONE=zone)
4700 call date_and_time(TIME=time)
4701 call date_and_time(VALUES=values)
4702 print '(a,2x,a,2x,a)', date, time, zone
4703 print '(8i5)', values
4704 end program test_time_and_date
4707 @item @emph{See also}:
4708 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
4714 @section @code{DBLE} --- Double conversion function
4716 @cindex conversion, to real
4719 @item @emph{Description}:
4720 @code{DBLE(A)} Converts @var{A} to double precision real type.
4722 @item @emph{Standard}:
4723 Fortran 77 and later
4728 @item @emph{Syntax}:
4729 @code{RESULT = DBLE(A)}
4731 @item @emph{Arguments}:
4732 @multitable @columnfractions .15 .70
4733 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
4737 @item @emph{Return value}:
4738 The return value is of type double precision real.
4740 @item @emph{Example}:
4745 complex :: z = (2.3,1.14)
4746 print *, dble(x), dble(i), dble(z)
4747 end program test_dble
4750 @item @emph{See also}:
4757 @section @code{DCMPLX} --- Double complex conversion function
4759 @cindex complex numbers, conversion to
4760 @cindex conversion, to complex
4763 @item @emph{Description}:
4764 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
4765 converted to the real component. If @var{Y} is present it is converted to the
4766 imaginary component. If @var{Y} is not present then the imaginary component is
4767 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
4769 @item @emph{Standard}:
4775 @item @emph{Syntax}:
4776 @code{RESULT = DCMPLX(X [, Y])}
4778 @item @emph{Arguments}:
4779 @multitable @columnfractions .15 .70
4780 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
4782 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
4783 @code{INTEGER} or @code{REAL}.
4786 @item @emph{Return value}:
4787 The return value is of type @code{COMPLEX(8)}
4789 @item @emph{Example}:
4799 print *, dcmplx(x,i)
4800 end program test_dcmplx
4806 @section @code{DIGITS} --- Significant binary digits function
4808 @cindex model representation, significant digits
4811 @item @emph{Description}:
4812 @code{DIGITS(X)} returns the number of significant binary digits of the internal
4813 model representation of @var{X}. For example, on a system using a 32-bit
4814 floating point representation, a default real number would likely return 24.
4816 @item @emph{Standard}:
4817 Fortran 95 and later
4822 @item @emph{Syntax}:
4823 @code{RESULT = DIGITS(X)}
4825 @item @emph{Arguments}:
4826 @multitable @columnfractions .15 .70
4827 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
4830 @item @emph{Return value}:
4831 The return value is of type @code{INTEGER}.
4833 @item @emph{Example}:
4836 integer :: i = 12345
4842 end program test_digits
4849 @section @code{DIM} --- Positive difference
4853 @cindex positive difference
4856 @item @emph{Description}:
4857 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
4858 otherwise returns zero.
4860 @item @emph{Standard}:
4861 Fortran 77 and later
4866 @item @emph{Syntax}:
4867 @code{RESULT = DIM(X, Y)}
4869 @item @emph{Arguments}:
4870 @multitable @columnfractions .15 .70
4871 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
4872 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
4875 @item @emph{Return value}:
4876 The return value is of type @code{INTEGER} or @code{REAL}.
4878 @item @emph{Example}:
4884 x = dim(4.345_8, 2.111_8)
4887 end program test_dim
4890 @item @emph{Specific names}:
4891 @multitable @columnfractions .20 .20 .20 .25
4892 @item Name @tab Argument @tab Return type @tab Standard
4893 @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
4894 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
4895 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
4902 @section @code{DOT_PRODUCT} --- Dot product function
4903 @fnindex DOT_PRODUCT
4905 @cindex vector product
4906 @cindex product, vector
4909 @item @emph{Description}:
4910 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
4911 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
4912 either numeric or logical and must be arrays of rank one and of equal size. If
4913 the vectors are @code{INTEGER} or @code{REAL}, the result is
4914 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
4915 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
4916 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
4918 @item @emph{Standard}:
4919 Fortran 95 and later
4922 Transformational function
4924 @item @emph{Syntax}:
4925 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
4927 @item @emph{Arguments}:
4928 @multitable @columnfractions .15 .70
4929 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
4930 @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.
4933 @item @emph{Return value}:
4934 If the arguments are numeric, the return value is a scalar of numeric type,
4935 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
4936 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
4938 @item @emph{Example}:
4940 program test_dot_prod
4941 integer, dimension(3) :: a, b
4948 print *, dot_product(a,b)
4949 end program test_dot_prod
4956 @section @code{DPROD} --- Double product function
4958 @cindex product, double-precision
4961 @item @emph{Description}:
4962 @code{DPROD(X,Y)} returns the product @code{X*Y}.
4964 @item @emph{Standard}:
4965 Fortran 77 and later
4970 @item @emph{Syntax}:
4971 @code{RESULT = DPROD(X, Y)}
4973 @item @emph{Arguments}:
4974 @multitable @columnfractions .15 .70
4975 @item @var{X} @tab The type shall be @code{REAL}.
4976 @item @var{Y} @tab The type shall be @code{REAL}.
4979 @item @emph{Return value}:
4980 The return value is of type @code{REAL(8)}.
4982 @item @emph{Example}:
4990 end program test_dprod
4993 @item @emph{Specific names}:
4994 @multitable @columnfractions .20 .20 .20 .25
4995 @item Name @tab Argument @tab Return type @tab Standard
4996 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
5003 @section @code{DREAL} --- Double real part function
5005 @cindex complex numbers, real part
5008 @item @emph{Description}:
5009 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
5011 @item @emph{Standard}:
5017 @item @emph{Syntax}:
5018 @code{RESULT = DREAL(A)}
5020 @item @emph{Arguments}:
5021 @multitable @columnfractions .15 .70
5022 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
5025 @item @emph{Return value}:
5026 The return value is of type @code{REAL(8)}.
5028 @item @emph{Example}:
5031 complex(8) :: z = (1.3_8,7.2_8)
5033 end program test_dreal
5036 @item @emph{See also}:
5044 @section @code{DSHIFTL} --- Combined left shift
5046 @cindex left shift, combined
5050 @item @emph{Description}:
5051 @code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
5052 rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
5053 bits of @var{J}, and the remaining bits are the rightmost bits of
5056 @item @emph{Standard}:
5057 Fortran 2008 and later
5062 @item @emph{Syntax}:
5063 @code{RESULT = DSHIFTL(I, J, SHIFT)}
5065 @item @emph{Arguments}:
5066 @multitable @columnfractions .15 .70
5067 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5068 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5069 If both @var{I} and @var{J} have integer type, then they shall have
5070 the same kind type parameter. @var{I} and @var{J} shall not both be
5072 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
5073 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
5074 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
5075 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
5078 @item @emph{Return value}:
5079 If either @var{I} or @var{J} is a BOZ constant, it is first converted
5080 as if by the intrinsic function @code{INT} to an integer type with the
5081 kind type parameter of the other.
5083 @item @emph{See also}:
5089 @section @code{DSHIFTR} --- Combined right shift
5091 @cindex right shift, combined
5092 @cindex shift, right
5095 @item @emph{Description}:
5096 @code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
5097 leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
5098 bits of @var{I}, and the remaining bits are the leftmost bits of
5101 @item @emph{Standard}:
5102 Fortran 2008 and later
5107 @item @emph{Syntax}:
5108 @code{RESULT = DSHIFTR(I, J, SHIFT)}
5110 @item @emph{Arguments}:
5111 @multitable @columnfractions .15 .70
5112 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5113 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5114 If both @var{I} and @var{J} have integer type, then they shall have
5115 the same kind type parameter. @var{I} and @var{J} shall not both be
5117 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
5118 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
5119 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
5120 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
5123 @item @emph{Return value}:
5124 If either @var{I} or @var{J} is a BOZ constant, it is first converted
5125 as if by the intrinsic function @code{INT} to an integer type with the
5126 kind type parameter of the other.
5128 @item @emph{See also}:
5134 @section @code{DTIME} --- Execution time subroutine (or function)
5136 @cindex time, elapsed
5137 @cindex elapsed time
5140 @item @emph{Description}:
5141 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
5142 since the start of the process's execution in @var{TIME}. @var{VALUES}
5143 returns the user and system components of this time in @code{VALUES(1)} and
5144 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
5147 Subsequent invocations of @code{DTIME} return values accumulated since the
5148 previous invocation.
5150 On some systems, the underlying timings are represented using types with
5151 sufficiently small limits that overflows (wrap around) are possible, such as
5152 32-bit types. Therefore, the values returned by this intrinsic might be, or
5153 become, negative, or numerically less than previous values, during a single
5154 run of the compiled program.
5156 Please note, that this implementation is thread safe if used within OpenMP
5157 directives, i.e., its state will be consistent while called from multiple
5158 threads. However, if @code{DTIME} is called from multiple threads, the result
5159 is still the time since the last invocation. This may not give the intended
5160 results. If possible, use @code{CPU_TIME} instead.
5162 This intrinsic is provided in both subroutine and function forms; however,
5163 only one form can be used in any given program unit.
5165 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
5167 @multitable @columnfractions .15 .30 .40
5168 @item @tab @code{VALUES(1)}: @tab User time in seconds.
5169 @item @tab @code{VALUES(2)}: @tab System time in seconds.
5170 @item @tab @code{TIME}: @tab Run time since start in seconds.
5173 @item @emph{Standard}:
5177 Subroutine, function
5179 @item @emph{Syntax}:
5180 @multitable @columnfractions .80
5181 @item @code{CALL DTIME(VALUES, TIME)}.
5182 @item @code{TIME = DTIME(VALUES)}, (not recommended).
5185 @item @emph{Arguments}:
5186 @multitable @columnfractions .15 .70
5187 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
5188 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
5191 @item @emph{Return value}:
5192 Elapsed time in seconds since the last invocation or since the start of program
5193 execution if not called before.
5195 @item @emph{Example}:
5199 real, dimension(2) :: tarray
5201 call dtime(tarray, result)
5205 do i=1,100000000 ! Just a delay
5208 call dtime(tarray, result)
5212 end program test_dtime
5215 @item @emph{See also}:
5223 @section @code{EOSHIFT} --- End-off shift elements of an array
5225 @cindex array, shift
5228 @item @emph{Description}:
5229 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
5230 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
5231 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
5232 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
5233 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
5234 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
5235 then all complete rank one sections of @var{ARRAY} along the given dimension are
5236 shifted. Elements shifted out one end of each rank one section are dropped. If
5237 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
5238 is copied back in the other end. If @var{BOUNDARY} is not present then the
5239 following are copied in depending on the type of @var{ARRAY}.
5241 @multitable @columnfractions .15 .80
5242 @item @emph{Array Type} @tab @emph{Boundary Value}
5243 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
5244 @item Logical @tab @code{.FALSE.}.
5245 @item Character(@var{len}) @tab @var{len} blanks.
5248 @item @emph{Standard}:
5249 Fortran 95 and later
5252 Transformational function
5254 @item @emph{Syntax}:
5255 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
5257 @item @emph{Arguments}:
5258 @multitable @columnfractions .15 .70
5259 @item @var{ARRAY} @tab May be any type, not scalar.
5260 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
5261 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
5262 @item @var{DIM} @tab The type shall be @code{INTEGER}.
5265 @item @emph{Return value}:
5266 Returns an array of same type and rank as the @var{ARRAY} argument.
5268 @item @emph{Example}:
5270 program test_eoshift
5271 integer, dimension(3,3) :: a
5272 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
5273 print '(3i3)', a(1,:)
5274 print '(3i3)', a(2,:)
5275 print '(3i3)', a(3,:)
5276 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
5278 print '(3i3)', a(1,:)
5279 print '(3i3)', a(2,:)
5280 print '(3i3)', a(3,:)
5281 end program test_eoshift
5288 @section @code{EPSILON} --- Epsilon function
5290 @cindex model representation, epsilon
5293 @item @emph{Description}:
5294 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
5295 as @var{X} such that @math{1 + E > 1}.
5297 @item @emph{Standard}:
5298 Fortran 95 and later
5303 @item @emph{Syntax}:
5304 @code{RESULT = EPSILON(X)}
5306 @item @emph{Arguments}:
5307 @multitable @columnfractions .15 .70
5308 @item @var{X} @tab The type shall be @code{REAL}.
5311 @item @emph{Return value}:
5312 The return value is of same type as the argument.
5314 @item @emph{Example}:
5316 program test_epsilon
5321 end program test_epsilon
5328 @section @code{ERF} --- Error function
5330 @cindex error function
5333 @item @emph{Description}:
5334 @code{ERF(X)} computes the error function of @var{X}.
5336 @item @emph{Standard}:
5337 Fortran 2008 and later
5342 @item @emph{Syntax}:
5343 @code{RESULT = ERF(X)}
5345 @item @emph{Arguments}:
5346 @multitable @columnfractions .15 .70
5347 @item @var{X} @tab The type shall be @code{REAL}.
5350 @item @emph{Return value}:
5351 The return value is of type @code{REAL}, of the same kind as
5352 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
5354 @item @emph{Example}:
5357 real(8) :: x = 0.17_8
5359 end program test_erf
5362 @item @emph{Specific names}:
5363 @multitable @columnfractions .20 .20 .20 .25
5364 @item Name @tab Argument @tab Return type @tab Standard
5365 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
5372 @section @code{ERFC} --- Error function
5374 @cindex error function, complementary
5377 @item @emph{Description}:
5378 @code{ERFC(X)} computes the complementary error function of @var{X}.
5380 @item @emph{Standard}:
5381 Fortran 2008 and later
5386 @item @emph{Syntax}:
5387 @code{RESULT = ERFC(X)}
5389 @item @emph{Arguments}:
5390 @multitable @columnfractions .15 .70
5391 @item @var{X} @tab The type shall be @code{REAL}.
5394 @item @emph{Return value}:
5395 The return value is of type @code{REAL} and of the same kind as @var{X}.
5396 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
5398 @item @emph{Example}:
5401 real(8) :: x = 0.17_8
5403 end program test_erfc
5406 @item @emph{Specific names}:
5407 @multitable @columnfractions .20 .20 .20 .25
5408 @item Name @tab Argument @tab Return type @tab Standard
5409 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
5416 @section @code{ERFC_SCALED} --- Error function
5417 @fnindex ERFC_SCALED
5418 @cindex error function, complementary, exponentially-scaled
5421 @item @emph{Description}:
5422 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
5423 error function of @var{X}.
5425 @item @emph{Standard}:
5426 Fortran 2008 and later
5431 @item @emph{Syntax}:
5432 @code{RESULT = ERFC_SCALED(X)}
5434 @item @emph{Arguments}:
5435 @multitable @columnfractions .15 .70
5436 @item @var{X} @tab The type shall be @code{REAL}.
5439 @item @emph{Return value}:
5440 The return value is of type @code{REAL} and of the same kind as @var{X}.
5442 @item @emph{Example}:
5444 program test_erfc_scaled
5445 real(8) :: x = 0.17_8
5447 end program test_erfc_scaled
5454 @section @code{ETIME} --- Execution time subroutine (or function)
5456 @cindex time, elapsed
5459 @item @emph{Description}:
5460 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
5461 since the start of the process's execution in @var{TIME}. @var{VALUES}
5462 returns the user and system components of this time in @code{VALUES(1)} and
5463 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
5465 On some systems, the underlying timings are represented using types with
5466 sufficiently small limits that overflows (wrap around) are possible, such as
5467 32-bit types. Therefore, the values returned by this intrinsic might be, or
5468 become, negative, or numerically less than previous values, during a single
5469 run of the compiled program.
5471 This intrinsic is provided in both subroutine and function forms; however,
5472 only one form can be used in any given program unit.
5474 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
5476 @multitable @columnfractions .15 .30 .60
5477 @item @tab @code{VALUES(1)}: @tab User time in seconds.
5478 @item @tab @code{VALUES(2)}: @tab System time in seconds.
5479 @item @tab @code{TIME}: @tab Run time since start in seconds.
5482 @item @emph{Standard}:
5486 Subroutine, function
5488 @item @emph{Syntax}:
5489 @multitable @columnfractions .80
5490 @item @code{CALL ETIME(VALUES, TIME)}.
5491 @item @code{TIME = ETIME(VALUES)}, (not recommended).
5494 @item @emph{Arguments}:
5495 @multitable @columnfractions .15 .70
5496 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
5497 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
5500 @item @emph{Return value}:
5501 Elapsed time in seconds since the start of program execution.
5503 @item @emph{Example}:
5507 real, dimension(2) :: tarray
5509 call ETIME(tarray, result)
5513 do i=1,100000000 ! Just a delay
5516 call ETIME(tarray, result)
5520 end program test_etime
5523 @item @emph{See also}:
5531 @section @code{EVENT_QUERY} --- Query whether a coarray event has occurred
5532 @fnindex EVENT_QUERY
5533 @cindex Events, EVENT_QUERY
5536 @item @emph{Description}:
5537 @code{EVENT_QUERY} assignes the number of events to @var{COUNT} which have been
5538 posted to the @var{EVENT} variable and not yet been removed by calling
5539 @code{EVENT WAIT}. When @var{STAT} is present and the invocation was successful,
5540 it is assigned the value 0. If it is present and the invocation has failed,
5541 it is assigned a positive value and @var{COUNT} is assigned the value @math{-1}.
5543 @item @emph{Standard}:
5549 @item @emph{Syntax}:
5550 @code{CALL EVENT_QUERY (EVENT, COUNT [, STAT])}
5552 @item @emph{Arguments}:
5553 @multitable @columnfractions .15 .70
5554 @item @var{EVENT} @tab (intent(IN)) Scalar of type @code{EVENT_TYPE},
5555 defined in @code{ISO_FORTRAN_ENV}; shall not be coindexed.
5556 @item @var{COUNT} @tab (intent(out))Scalar integer with at least the
5557 precision of default integer.
5558 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
5561 @item @emph{Example}:
5566 type(event_type) :: event_value_has_been_set[*]
5568 if (this_image() == 1) then
5569 call event_query (event_value_has_been_set, cnt)
5570 if (cnt > 0) write(*,*) "Value has been set"
5571 elseif (this_image() == 2) then
5572 event post (event_value_has_been_set[1])
5581 @node EXECUTE_COMMAND_LINE
5582 @section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
5583 @fnindex EXECUTE_COMMAND_LINE
5584 @cindex system, system call
5585 @cindex command line
5588 @item @emph{Description}:
5589 @code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
5592 The @code{COMMAND} argument is passed to the shell and executed, using
5593 the C library's @code{system} call. (The shell is @code{sh} on Unix
5594 systems, and @code{cmd.exe} on Windows.) If @code{WAIT} is present
5595 and has the value false, the execution of the command is asynchronous
5596 if the system supports it; otherwise, the command is executed
5599 The three last arguments allow the user to get status information. After
5600 synchronous execution, @code{EXITSTAT} contains the integer exit code of
5601 the command, as returned by @code{system}. @code{CMDSTAT} is set to zero
5602 if the command line was executed (whatever its exit status was).
5603 @code{CMDMSG} is assigned an error message if an error has occurred.
5605 Note that the @code{system} function need not be thread-safe. It is
5606 the responsibility of the user to ensure that @code{system} is not
5607 called concurrently.
5609 @item @emph{Standard}:
5610 Fortran 2008 and later
5615 @item @emph{Syntax}:
5616 @code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
5618 @item @emph{Arguments}:
5619 @multitable @columnfractions .15 .70
5620 @item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
5621 @item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
5622 @item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5624 @item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5626 @item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
5630 @item @emph{Example}:
5635 call execute_command_line ("external_prog.exe", exitstat=i)
5636 print *, "Exit status of external_prog.exe was ", i
5638 call execute_command_line ("reindex_files.exe", wait=.false.)
5639 print *, "Now reindexing files in the background"
5641 end program test_exec
5647 Because this intrinsic is implemented in terms of the @code{system}
5648 function call, its behavior with respect to signaling is processor
5649 dependent. In particular, on POSIX-compliant systems, the SIGINT and
5650 SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
5651 such, if the parent process is terminated, the child process might not be
5652 terminated alongside.
5655 @item @emph{See also}:
5662 @section @code{EXIT} --- Exit the program with status.
5664 @cindex program termination
5665 @cindex terminate program
5668 @item @emph{Description}:
5669 @code{EXIT} causes immediate termination of the program with status. If status
5670 is omitted it returns the canonical @emph{success} for the system. All Fortran
5671 I/O units are closed.
5673 @item @emph{Standard}:
5679 @item @emph{Syntax}:
5680 @code{CALL EXIT([STATUS])}
5682 @item @emph{Arguments}:
5683 @multitable @columnfractions .15 .70
5684 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
5687 @item @emph{Return value}:
5688 @code{STATUS} is passed to the parent process on exit.
5690 @item @emph{Example}:
5693 integer :: STATUS = 0
5694 print *, 'This program is going to exit.'
5696 end program test_exit
5699 @item @emph{See also}:
5700 @ref{ABORT}, @ref{KILL}
5706 @section @code{EXP} --- Exponential function
5712 @cindex exponential function
5713 @cindex logarithm function, inverse
5716 @item @emph{Description}:
5717 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
5719 @item @emph{Standard}:
5720 Fortran 77 and later, has overloads that are GNU extensions
5725 @item @emph{Syntax}:
5726 @code{RESULT = EXP(X)}
5728 @item @emph{Arguments}:
5729 @multitable @columnfractions .15 .70
5730 @item @var{X} @tab The type shall be @code{REAL} or
5734 @item @emph{Return value}:
5735 The return value has same type and kind as @var{X}.
5737 @item @emph{Example}:
5742 end program test_exp
5745 @item @emph{Specific names}:
5746 @multitable @columnfractions .20 .20 .20 .25
5747 @item Name @tab Argument @tab Return type @tab Standard
5748 @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
5749 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
5750 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
5751 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5752 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5759 @section @code{EXPONENT} --- Exponent function
5761 @cindex real number, exponent
5762 @cindex floating point, exponent
5765 @item @emph{Description}:
5766 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
5767 is zero the value returned is zero.
5769 @item @emph{Standard}:
5770 Fortran 95 and later
5775 @item @emph{Syntax}:
5776 @code{RESULT = EXPONENT(X)}
5778 @item @emph{Arguments}:
5779 @multitable @columnfractions .15 .70
5780 @item @var{X} @tab The type shall be @code{REAL}.
5783 @item @emph{Return value}:
5784 The return value is of type default @code{INTEGER}.
5786 @item @emph{Example}:
5788 program test_exponent
5793 print *, exponent(0.0)
5794 end program test_exponent
5800 @node EXTENDS_TYPE_OF
5801 @section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension
5802 @fnindex EXTENDS_TYPE_OF
5805 @item @emph{Description}:
5806 Query dynamic type for extension.
5808 @item @emph{Standard}:
5809 Fortran 2003 and later
5814 @item @emph{Syntax}:
5815 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
5817 @item @emph{Arguments}:
5818 @multitable @columnfractions .15 .70
5819 @item @var{A} @tab Shall be an object of extensible declared type or
5820 unlimited polymorphic.
5821 @item @var{MOLD} @tab Shall be an object of extensible declared type or
5822 unlimited polymorphic.
5825 @item @emph{Return value}:
5826 The return value is a scalar of type default logical. It is true if and only if
5827 the dynamic type of A is an extension type of the dynamic type of MOLD.
5830 @item @emph{See also}:
5837 @section @code{FDATE} --- Get the current time as a string
5839 @cindex time, current
5840 @cindex current time
5841 @cindex date, current
5842 @cindex current date
5845 @item @emph{Description}:
5846 @code{FDATE(DATE)} returns the current date (using the same format as
5847 @ref{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
5850 This intrinsic is provided in both subroutine and function forms; however,
5851 only one form can be used in any given program unit.
5853 @item @emph{Standard}:
5857 Subroutine, function
5859 @item @emph{Syntax}:
5860 @multitable @columnfractions .80
5861 @item @code{CALL FDATE(DATE)}.
5862 @item @code{DATE = FDATE()}.
5865 @item @emph{Arguments}:
5866 @multitable @columnfractions .15 .70
5867 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
5868 default kind. It is an @code{INTENT(OUT)} argument. If the length of
5869 this variable is too short for the date and time string to fit
5870 completely, it will be blank on procedure return.
5873 @item @emph{Return value}:
5874 The current date and time as a string.
5876 @item @emph{Example}:
5880 character(len=30) :: date
5882 print *, 'Program started on ', date
5883 do i = 1, 100000000 ! Just a delay
5887 print *, 'Program ended on ', date
5888 end program test_fdate
5891 @item @emph{See also}:
5892 @ref{DATE_AND_TIME}, @ref{CTIME}
5897 @section @code{FGET} --- Read a single character in stream mode from stdin
5899 @cindex read character, stream mode
5900 @cindex stream mode, read character
5901 @cindex file operation, read character
5904 @item @emph{Description}:
5905 Read a single character in stream mode from stdin by bypassing normal
5906 formatted output. Stream I/O should not be mixed with normal record-oriented
5907 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
5909 This intrinsic is provided in both subroutine and function forms; however,
5910 only one form can be used in any given program unit.
5912 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
5913 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5914 Programmers should consider the use of new stream IO feature in new code
5915 for future portability. See also @ref{Fortran 2003 status}.
5917 @item @emph{Standard}:
5921 Subroutine, function
5923 @item @emph{Syntax}:
5924 @multitable @columnfractions .80
5925 @item @code{CALL FGET(C [, STATUS])}
5926 @item @code{STATUS = FGET(C)}
5929 @item @emph{Arguments}:
5930 @multitable @columnfractions .15 .70
5931 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5933 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5934 Returns 0 on success, -1 on end-of-file, and a system specific positive
5935 error code otherwise.
5938 @item @emph{Example}:
5941 INTEGER, PARAMETER :: strlen = 100
5942 INTEGER :: status, i = 1
5943 CHARACTER(len=strlen) :: str = ""
5945 WRITE (*,*) 'Enter text:'
5947 CALL fget(str(i:i), status)
5948 if (status /= 0 .OR. i > strlen) exit
5951 WRITE (*,*) TRIM(str)
5955 @item @emph{See also}:
5956 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
5962 @section @code{FGETC} --- Read a single character in stream mode
5964 @cindex read character, stream mode
5965 @cindex stream mode, read character
5966 @cindex file operation, read character
5969 @item @emph{Description}:
5970 Read a single character in stream mode by bypassing normal formatted output.
5971 Stream I/O should not be mixed with normal record-oriented (formatted or
5972 unformatted) I/O on the same unit; the results are unpredictable.
5974 This intrinsic is provided in both subroutine and function forms; however,
5975 only one form can be used in any given program unit.
5977 Note that the @code{FGET} intrinsic is provided for backwards compatibility
5978 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5979 Programmers should consider the use of new stream IO feature in new code
5980 for future portability. See also @ref{Fortran 2003 status}.
5982 @item @emph{Standard}:
5986 Subroutine, function
5988 @item @emph{Syntax}:
5989 @multitable @columnfractions .80
5990 @item @code{CALL FGETC(UNIT, C [, STATUS])}
5991 @item @code{STATUS = FGETC(UNIT, C)}
5994 @item @emph{Arguments}:
5995 @multitable @columnfractions .15 .70
5996 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
5997 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5999 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6000 Returns 0 on success, -1 on end-of-file and a system specific positive
6001 error code otherwise.
6004 @item @emph{Example}:
6007 INTEGER :: fd = 42, status
6010 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
6012 CALL fgetc(fd, c, status)
6013 IF (status /= 0) EXIT
6020 @item @emph{See also}:
6021 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
6027 @section @code{FLOOR} --- Integer floor function
6030 @cindex rounding, floor
6033 @item @emph{Description}:
6034 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
6036 @item @emph{Standard}:
6037 Fortran 95 and later
6042 @item @emph{Syntax}:
6043 @code{RESULT = FLOOR(A [, KIND])}
6045 @item @emph{Arguments}:
6046 @multitable @columnfractions .15 .70
6047 @item @var{A} @tab The type shall be @code{REAL}.
6048 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6049 expression indicating the kind parameter of the result.
6052 @item @emph{Return value}:
6053 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
6054 and of default-kind @code{INTEGER} otherwise.
6056 @item @emph{Example}:
6061 print *, floor(x) ! returns 63
6062 print *, floor(y) ! returns -64
6063 end program test_floor
6066 @item @emph{See also}:
6067 @ref{CEILING}, @ref{NINT}
6074 @section @code{FLUSH} --- Flush I/O unit(s)
6076 @cindex file operation, flush
6079 @item @emph{Description}:
6080 Flushes Fortran unit(s) currently open for output. Without the optional
6081 argument, all units are flushed, otherwise just the unit specified.
6083 @item @emph{Standard}:
6089 @item @emph{Syntax}:
6090 @code{CALL FLUSH(UNIT)}
6092 @item @emph{Arguments}:
6093 @multitable @columnfractions .15 .70
6094 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
6098 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
6099 statement that should be preferred over the @code{FLUSH} intrinsic.
6101 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
6102 have identical effect: they flush the runtime library's I/O buffer so
6103 that the data becomes visible to other processes. This does not guarantee
6104 that the data is committed to disk.
6106 On POSIX systems, you can request that all data is transferred to the
6107 storage device by calling the @code{fsync} function, with the POSIX file
6108 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
6109 @code{FNUM}). The following example shows how:
6112 ! Declare the interface for POSIX fsync function
6114 function fsync (fd) bind(c,name="fsync")
6115 use iso_c_binding, only: c_int
6116 integer(c_int), value :: fd
6117 integer(c_int) :: fsync
6121 ! Variable declaration
6125 open (10,file="foo")
6128 ! Perform I/O on unit 10
6133 ret = fsync(fnum(10))
6135 ! Handle possible error
6136 if (ret /= 0) stop "Error calling FSYNC"
6144 @section @code{FNUM} --- File number function
6146 @cindex file operation, file number
6149 @item @emph{Description}:
6150 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
6151 open Fortran I/O unit @code{UNIT}.
6153 @item @emph{Standard}:
6159 @item @emph{Syntax}:
6160 @code{RESULT = FNUM(UNIT)}
6162 @item @emph{Arguments}:
6163 @multitable @columnfractions .15 .70
6164 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
6167 @item @emph{Return value}:
6168 The return value is of type @code{INTEGER}
6170 @item @emph{Example}:
6174 open (unit=10, status = "scratch")
6178 end program test_fnum
6185 @section @code{FPUT} --- Write a single character in stream mode to stdout
6187 @cindex write character, stream mode
6188 @cindex stream mode, write character
6189 @cindex file operation, write character
6192 @item @emph{Description}:
6193 Write a single character in stream mode to stdout by bypassing normal
6194 formatted output. Stream I/O should not be mixed with normal record-oriented
6195 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
6197 This intrinsic is provided in both subroutine and function forms; however,
6198 only one form can be used in any given program unit.
6200 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
6201 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
6202 Programmers should consider the use of new stream IO feature in new code
6203 for future portability. See also @ref{Fortran 2003 status}.
6205 @item @emph{Standard}:
6209 Subroutine, function
6211 @item @emph{Syntax}:
6212 @multitable @columnfractions .80
6213 @item @code{CALL FPUT(C [, STATUS])}
6214 @item @code{STATUS = FPUT(C)}
6217 @item @emph{Arguments}:
6218 @multitable @columnfractions .15 .70
6219 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6221 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6222 Returns 0 on success, -1 on end-of-file and a system specific positive
6223 error code otherwise.
6226 @item @emph{Example}:
6229 CHARACTER(len=10) :: str = "gfortran"
6231 DO i = 1, len_trim(str)
6237 @item @emph{See also}:
6238 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
6244 @section @code{FPUTC} --- Write a single character in stream mode
6246 @cindex write character, stream mode
6247 @cindex stream mode, write character
6248 @cindex file operation, write character
6251 @item @emph{Description}:
6252 Write a single character in stream mode by bypassing normal formatted
6253 output. Stream I/O should not be mixed with normal record-oriented
6254 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
6256 This intrinsic is provided in both subroutine and function forms; however,
6257 only one form can be used in any given program unit.
6259 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
6260 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
6261 Programmers should consider the use of new stream IO feature in new code
6262 for future portability. See also @ref{Fortran 2003 status}.
6264 @item @emph{Standard}:
6268 Subroutine, function
6270 @item @emph{Syntax}:
6271 @multitable @columnfractions .80
6272 @item @code{CALL FPUTC(UNIT, C [, STATUS])}
6273 @item @code{STATUS = FPUTC(UNIT, C)}
6276 @item @emph{Arguments}:
6277 @multitable @columnfractions .15 .70
6278 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
6279 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6281 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6282 Returns 0 on success, -1 on end-of-file and a system specific positive
6283 error code otherwise.
6286 @item @emph{Example}:
6289 CHARACTER(len=10) :: str = "gfortran"
6290 INTEGER :: fd = 42, i
6292 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
6293 DO i = 1, len_trim(str)
6294 CALL fputc(fd, str(i:i))
6300 @item @emph{See also}:
6301 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
6307 @section @code{FRACTION} --- Fractional part of the model representation
6309 @cindex real number, fraction
6310 @cindex floating point, fraction
6313 @item @emph{Description}:
6314 @code{FRACTION(X)} returns the fractional part of the model
6315 representation of @code{X}.
6317 @item @emph{Standard}:
6318 Fortran 95 and later
6323 @item @emph{Syntax}:
6324 @code{Y = FRACTION(X)}
6326 @item @emph{Arguments}:
6327 @multitable @columnfractions .15 .70
6328 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
6331 @item @emph{Return value}:
6332 The return value is of the same type and kind as the argument.
6333 The fractional part of the model representation of @code{X} is returned;
6334 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
6336 @item @emph{Example}:
6338 program test_fraction
6341 print *, fraction(x), x * radix(x)**(-exponent(x))
6342 end program test_fraction
6350 @section @code{FREE} --- Frees memory
6352 @cindex pointer, cray
6355 @item @emph{Description}:
6356 Frees memory previously allocated by @code{MALLOC}. The @code{FREE}
6357 intrinsic is an extension intended to be used with Cray pointers, and is
6358 provided in GNU Fortran to allow user to compile legacy code. For
6359 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
6362 @item @emph{Standard}:
6368 @item @emph{Syntax}:
6369 @code{CALL FREE(PTR)}
6371 @item @emph{Arguments}:
6372 @multitable @columnfractions .15 .70
6373 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
6374 location of the memory that should be de-allocated.
6377 @item @emph{Return value}:
6380 @item @emph{Example}:
6381 See @code{MALLOC} for an example.
6383 @item @emph{See also}:
6390 @section @code{FSEEK} --- Low level file positioning subroutine
6392 @cindex file operation, seek
6393 @cindex file operation, position
6396 @item @emph{Description}:
6397 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
6398 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
6399 if set to 1, @var{OFFSET} is taken to be relative to the current position
6400 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
6401 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
6404 This intrinsic routine is not fully backwards compatible with @command{g77}.
6405 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
6406 @var{STATUS} variable. If FSEEK is used in old code, change
6408 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
6413 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
6414 IF (status /= 0) GOTO label
6417 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
6418 Programmers should consider the use of new stream IO feature in new code
6419 for future portability. See also @ref{Fortran 2003 status}.
6421 @item @emph{Standard}:
6427 @item @emph{Syntax}:
6428 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
6430 @item @emph{Arguments}:
6431 @multitable @columnfractions .15 .70
6432 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
6433 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
6434 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
6435 Its value shall be either 0, 1 or 2.
6436 @item @var{STATUS} @tab (Optional) shall be a scalar of type
6440 @item @emph{Example}:
6443 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
6444 INTEGER :: fd, offset, ierr
6450 OPEN(UNIT=fd, FILE="fseek.test")
6451 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
6452 print *, FTELL(fd), ierr
6454 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
6455 print *, FTELL(fd), ierr
6457 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
6458 print *, FTELL(fd), ierr
6464 @item @emph{See also}:
6471 @section @code{FSTAT} --- Get file status
6473 @cindex file system, file status
6476 @item @emph{Description}:
6477 @code{FSTAT} is identical to @ref{STAT}, except that information about an
6478 already opened file is obtained.
6480 The elements in @code{VALUES} are the same as described by @ref{STAT}.
6482 This intrinsic is provided in both subroutine and function forms; however,
6483 only one form can be used in any given program unit.
6485 @item @emph{Standard}:
6489 Subroutine, function
6491 @item @emph{Syntax}:
6492 @multitable @columnfractions .80
6493 @item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
6494 @item @code{STATUS = FSTAT(UNIT, VALUES)}
6497 @item @emph{Arguments}:
6498 @multitable @columnfractions .15 .70
6499 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
6500 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
6501 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
6502 on success and a system specific error code otherwise.
6505 @item @emph{Example}:
6506 See @ref{STAT} for an example.
6508 @item @emph{See also}:
6509 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
6515 @section @code{FTELL} --- Current stream position
6517 @cindex file operation, position
6520 @item @emph{Description}:
6521 Retrieves the current position within an open file.
6523 This intrinsic is provided in both subroutine and function forms; however,
6524 only one form can be used in any given program unit.
6526 @item @emph{Standard}:
6530 Subroutine, function
6532 @item @emph{Syntax}:
6533 @multitable @columnfractions .80
6534 @item @code{CALL FTELL(UNIT, OFFSET)}
6535 @item @code{OFFSET = FTELL(UNIT)}
6538 @item @emph{Arguments}:
6539 @multitable @columnfractions .15 .70
6540 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
6541 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
6544 @item @emph{Return value}:
6545 In either syntax, @var{OFFSET} is set to the current offset of unit
6546 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
6548 @item @emph{Example}:
6552 OPEN(10, FILE="temp.dat")
6558 @item @emph{See also}:
6565 @section @code{GAMMA} --- Gamma function
6568 @cindex Gamma function
6569 @cindex Factorial function
6572 @item @emph{Description}:
6573 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
6574 integer values of @var{X} the Gamma function simplifies to the factorial
6575 function @math{\Gamma(x)=(x-1)!}.
6579 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
6583 @item @emph{Standard}:
6584 Fortran 2008 and later
6589 @item @emph{Syntax}:
6592 @item @emph{Arguments}:
6593 @multitable @columnfractions .15 .70
6594 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
6595 nor a negative integer.
6598 @item @emph{Return value}:
6599 The return value is of type @code{REAL} of the same kind as @var{X}.
6601 @item @emph{Example}:
6605 x = gamma(x) ! returns 1.0
6606 end program test_gamma
6609 @item @emph{Specific names}:
6610 @multitable @columnfractions .20 .20 .20 .25
6611 @item Name @tab Argument @tab Return type @tab Standard
6612 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
6613 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
6616 @item @emph{See also}:
6617 Logarithm of the Gamma function: @ref{LOG_GAMMA}
6624 @section @code{GERROR} --- Get last system error message
6626 @cindex system, error handling
6629 @item @emph{Description}:
6630 Returns the system error message corresponding to the last system error.
6631 This resembles the functionality of @code{strerror(3)} in C.
6633 @item @emph{Standard}:
6639 @item @emph{Syntax}:
6640 @code{CALL GERROR(RESULT)}
6642 @item @emph{Arguments}:
6643 @multitable @columnfractions .15 .70
6644 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
6647 @item @emph{Example}:
6650 CHARACTER(len=100) :: msg
6656 @item @emph{See also}:
6657 @ref{IERRNO}, @ref{PERROR}
6663 @section @code{GETARG} --- Get command line arguments
6665 @cindex command-line arguments
6666 @cindex arguments, to program
6669 @item @emph{Description}:
6670 Retrieve the @var{POS}-th argument that was passed on the
6671 command line when the containing program was invoked.
6673 This intrinsic routine is provided for backwards compatibility with
6674 GNU Fortran 77. In new code, programmers should consider the use of
6675 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
6678 @item @emph{Standard}:
6684 @item @emph{Syntax}:
6685 @code{CALL GETARG(POS, VALUE)}
6687 @item @emph{Arguments}:
6688 @multitable @columnfractions .15 .70
6689 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
6690 the default integer kind; @math{@var{POS} \geq 0}
6691 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
6693 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
6696 @item @emph{Return value}:
6697 After @code{GETARG} returns, the @var{VALUE} argument holds the
6698 @var{POS}th command line argument. If @var{VALUE} can not hold the
6699 argument, it is truncated to fit the length of @var{VALUE}. If there are
6700 less than @var{POS} arguments specified at the command line, @var{VALUE}
6701 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
6702 to the name of the program (on systems that support this feature).
6704 @item @emph{Example}:
6708 CHARACTER(len=32) :: arg
6717 @item @emph{See also}:
6718 GNU Fortran 77 compatibility function: @ref{IARGC}
6720 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
6721 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6727 @section @code{GET_COMMAND} --- Get the entire command line
6728 @fnindex GET_COMMAND
6729 @cindex command-line arguments
6730 @cindex arguments, to program
6733 @item @emph{Description}:
6734 Retrieve the entire command line that was used to invoke the program.
6736 @item @emph{Standard}:
6737 Fortran 2003 and later
6742 @item @emph{Syntax}:
6743 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
6745 @item @emph{Arguments}:
6746 @multitable @columnfractions .15 .70
6747 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
6749 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
6751 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
6755 @item @emph{Return value}:
6756 If @var{COMMAND} is present, stores the entire command line that was used
6757 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
6758 assigned the length of the command line. If @var{STATUS} is present, it
6759 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
6760 short to store the command line, or a positive value in case of an error.
6762 @item @emph{Example}:
6764 PROGRAM test_get_command
6765 CHARACTER(len=255) :: cmd
6766 CALL get_command(cmd)
6767 WRITE (*,*) TRIM(cmd)
6771 @item @emph{See also}:
6772 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6777 @node GET_COMMAND_ARGUMENT
6778 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
6779 @fnindex GET_COMMAND_ARGUMENT
6780 @cindex command-line arguments
6781 @cindex arguments, to program
6784 @item @emph{Description}:
6785 Retrieve the @var{NUMBER}-th argument that was passed on the
6786 command line when the containing program was invoked.
6788 @item @emph{Standard}:
6789 Fortran 2003 and later
6794 @item @emph{Syntax}:
6795 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
6797 @item @emph{Arguments}:
6798 @multitable @columnfractions .15 .70
6799 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
6800 default kind, @math{@var{NUMBER} \geq 0}
6801 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
6802 and of default kind.
6803 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6804 and of default kind.
6805 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6806 and of default kind.
6809 @item @emph{Return value}:
6810 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
6811 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
6812 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
6813 arguments specified at the command line, @var{VALUE} will be filled with blanks.
6814 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
6815 systems that support this feature). The @var{LENGTH} argument contains the
6816 length of the @var{NUMBER}-th command line argument. If the argument retrieval
6817 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
6818 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
6821 @item @emph{Example}:
6823 PROGRAM test_get_command_argument
6825 CHARACTER(len=32) :: arg
6829 CALL get_command_argument(i, arg)
6830 IF (LEN_TRIM(arg) == 0) EXIT
6832 WRITE (*,*) TRIM(arg)
6838 @item @emph{See also}:
6839 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
6845 @section @code{GETCWD} --- Get current working directory
6847 @cindex system, working directory
6850 @item @emph{Description}:
6851 Get current working directory.
6853 This intrinsic is provided in both subroutine and function forms; however,
6854 only one form can be used in any given program unit.
6856 @item @emph{Standard}:
6860 Subroutine, function
6862 @item @emph{Syntax}:
6863 @multitable @columnfractions .80
6864 @item @code{CALL GETCWD(C [, STATUS])}
6865 @item @code{STATUS = GETCWD(C)}
6868 @item @emph{Arguments}:
6869 @multitable @columnfractions .15 .70
6870 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
6871 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
6872 a system specific and nonzero error code otherwise.
6875 @item @emph{Example}:
6878 CHARACTER(len=255) :: cwd
6880 WRITE(*,*) TRIM(cwd)
6884 @item @emph{See also}:
6891 @section @code{GETENV} --- Get an environmental variable
6893 @cindex environment variable
6896 @item @emph{Description}:
6897 Get the @var{VALUE} of the environmental variable @var{NAME}.
6899 This intrinsic routine is provided for backwards compatibility with
6900 GNU Fortran 77. In new code, programmers should consider the use of
6901 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
6904 Note that @code{GETENV} need not be thread-safe. It is the
6905 responsibility of the user to ensure that the environment is not being
6906 updated concurrently with a call to the @code{GETENV} intrinsic.
6908 @item @emph{Standard}:
6914 @item @emph{Syntax}:
6915 @code{CALL GETENV(NAME, VALUE)}
6917 @item @emph{Arguments}:
6918 @multitable @columnfractions .15 .70
6919 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
6920 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
6923 @item @emph{Return value}:
6924 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
6925 not large enough to hold the data, it is truncated. If @var{NAME}
6926 is not set, @var{VALUE} will be filled with blanks.
6928 @item @emph{Example}:
6931 CHARACTER(len=255) :: homedir
6932 CALL getenv("HOME", homedir)
6933 WRITE (*,*) TRIM(homedir)
6937 @item @emph{See also}:
6938 @ref{GET_ENVIRONMENT_VARIABLE}
6943 @node GET_ENVIRONMENT_VARIABLE
6944 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
6945 @fnindex GET_ENVIRONMENT_VARIABLE
6946 @cindex environment variable
6949 @item @emph{Description}:
6950 Get the @var{VALUE} of the environmental variable @var{NAME}.
6952 Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It
6953 is the responsibility of the user to ensure that the environment is
6954 not being updated concurrently with a call to the
6955 @code{GET_ENVIRONMENT_VARIABLE} intrinsic.
6957 @item @emph{Standard}:
6958 Fortran 2003 and later
6963 @item @emph{Syntax}:
6964 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
6966 @item @emph{Arguments}:
6967 @multitable @columnfractions .15 .70
6968 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
6969 and of default kind.
6970 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
6971 and of default kind.
6972 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6973 and of default kind.
6974 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6975 and of default kind.
6976 @item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL}
6977 and of default kind.
6980 @item @emph{Return value}:
6981 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
6982 not large enough to hold the data, it is truncated. If @var{NAME}
6983 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
6984 contains the length needed for storing the environment variable @var{NAME}
6985 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
6986 but too short for the environment variable; it is 1 if the environment
6987 variable does not exist and 2 if the processor does not support environment
6988 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
6989 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
6990 are significant; otherwise they are not part of the environment variable
6993 @item @emph{Example}:
6996 CHARACTER(len=255) :: homedir
6997 CALL get_environment_variable("HOME", homedir)
6998 WRITE (*,*) TRIM(homedir)
7006 @section @code{GETGID} --- Group ID function
7008 @cindex system, group ID
7011 @item @emph{Description}:
7012 Returns the numerical group ID of the current process.
7014 @item @emph{Standard}:
7020 @item @emph{Syntax}:
7021 @code{RESULT = GETGID()}
7023 @item @emph{Return value}:
7024 The return value of @code{GETGID} is an @code{INTEGER} of the default
7028 @item @emph{Example}:
7029 See @code{GETPID} for an example.
7031 @item @emph{See also}:
7032 @ref{GETPID}, @ref{GETUID}
7038 @section @code{GETLOG} --- Get login name
7040 @cindex system, login name
7044 @item @emph{Description}:
7045 Gets the username under which the program is running.
7047 @item @emph{Standard}:
7053 @item @emph{Syntax}:
7054 @code{CALL GETLOG(C)}
7056 @item @emph{Arguments}:
7057 @multitable @columnfractions .15 .70
7058 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
7061 @item @emph{Return value}:
7062 Stores the current user name in @var{LOGIN}. (On systems where POSIX
7063 functions @code{geteuid} and @code{getpwuid} are not available, and
7064 the @code{getlogin} function is not implemented either, this will
7065 return a blank string.)
7067 @item @emph{Example}:
7070 CHARACTER(32) :: login
7076 @item @emph{See also}:
7083 @section @code{GETPID} --- Process ID function
7085 @cindex system, process ID
7089 @item @emph{Description}:
7090 Returns the numerical process identifier of the current process.
7092 @item @emph{Standard}:
7098 @item @emph{Syntax}:
7099 @code{RESULT = GETPID()}
7101 @item @emph{Return value}:
7102 The return value of @code{GETPID} is an @code{INTEGER} of the default
7106 @item @emph{Example}:
7109 print *, "The current process ID is ", getpid()
7110 print *, "Your numerical user ID is ", getuid()
7111 print *, "Your numerical group ID is ", getgid()
7115 @item @emph{See also}:
7116 @ref{GETGID}, @ref{GETUID}
7122 @section @code{GETUID} --- User ID function
7124 @cindex system, user ID
7128 @item @emph{Description}:
7129 Returns the numerical user ID of the current process.
7131 @item @emph{Standard}:
7137 @item @emph{Syntax}:
7138 @code{RESULT = GETUID()}
7140 @item @emph{Return value}:
7141 The return value of @code{GETUID} is an @code{INTEGER} of the default
7145 @item @emph{Example}:
7146 See @code{GETPID} for an example.
7148 @item @emph{See also}:
7149 @ref{GETPID}, @ref{GETLOG}
7155 @section @code{GMTIME} --- Convert time to GMT info
7157 @cindex time, conversion to GMT info
7160 @item @emph{Description}:
7161 Given a system time value @var{TIME} (as provided by the @ref{TIME}
7162 intrinsic), fills @var{VALUES} with values extracted from it appropriate
7163 to the UTC time zone (Universal Coordinated Time, also known in some
7164 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
7166 This intrinsic routine is provided for backwards compatibility with
7167 GNU Fortran 77. In new code, programmers should consider the use of
7168 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
7171 @item @emph{Standard}:
7177 @item @emph{Syntax}:
7178 @code{CALL GMTIME(TIME, VALUES)}
7180 @item @emph{Arguments}:
7181 @multitable @columnfractions .15 .70
7182 @item @var{TIME} @tab An @code{INTEGER} scalar expression
7183 corresponding to a system time, with @code{INTENT(IN)}.
7184 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
7185 with @code{INTENT(OUT)}.
7188 @item @emph{Return value}:
7189 The elements of @var{VALUES} are assigned as follows:
7191 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
7193 @item Minutes after the hour, range 0--59
7194 @item Hours past midnight, range 0--23
7195 @item Day of month, range 1--31
7196 @item Number of months since January, range 0--11
7197 @item Years since 1900
7198 @item Number of days since Sunday, range 0--6
7199 @item Days since January 1, range 0--365
7200 @item Daylight savings indicator: positive if daylight savings is in
7201 effect, zero if not, and negative if the information is not available.
7204 @item @emph{See also}:
7205 @ref{DATE_AND_TIME}, @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
7212 @section @code{HOSTNM} --- Get system host name
7214 @cindex system, host name
7217 @item @emph{Description}:
7218 Retrieves the host name of the system on which the program is running.
7220 This intrinsic is provided in both subroutine and function forms; however,
7221 only one form can be used in any given program unit.
7223 @item @emph{Standard}:
7227 Subroutine, function
7229 @item @emph{Syntax}:
7230 @multitable @columnfractions .80
7231 @item @code{CALL HOSTNM(C [, STATUS])}
7232 @item @code{STATUS = HOSTNM(NAME)}
7235 @item @emph{Arguments}:
7236 @multitable @columnfractions .15 .70
7237 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
7238 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
7239 Returns 0 on success, or a system specific error code otherwise.
7242 @item @emph{Return value}:
7243 In either syntax, @var{NAME} is set to the current hostname if it can
7244 be obtained, or to a blank string otherwise.
7251 @section @code{HUGE} --- Largest number of a kind
7253 @cindex limits, largest number
7254 @cindex model representation, largest number
7257 @item @emph{Description}:
7258 @code{HUGE(X)} returns the largest number that is not an infinity in
7259 the model of the type of @code{X}.
7261 @item @emph{Standard}:
7262 Fortran 95 and later
7267 @item @emph{Syntax}:
7268 @code{RESULT = HUGE(X)}
7270 @item @emph{Arguments}:
7271 @multitable @columnfractions .15 .70
7272 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
7275 @item @emph{Return value}:
7276 The return value is of the same type and kind as @var{X}
7278 @item @emph{Example}:
7280 program test_huge_tiny
7281 print *, huge(0), huge(0.0), huge(0.0d0)
7282 print *, tiny(0.0), tiny(0.0d0)
7283 end program test_huge_tiny
7290 @section @code{HYPOT} --- Euclidean distance function
7292 @cindex Euclidean distance
7295 @item @emph{Description}:
7296 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
7297 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
7299 @item @emph{Standard}:
7300 Fortran 2008 and later
7305 @item @emph{Syntax}:
7306 @code{RESULT = HYPOT(X, Y)}
7308 @item @emph{Arguments}:
7309 @multitable @columnfractions .15 .70
7310 @item @var{X} @tab The type shall be @code{REAL}.
7311 @item @var{Y} @tab The type and kind type parameter shall be the same as
7315 @item @emph{Return value}:
7316 The return value has the same type and kind type parameter as @var{X}.
7318 @item @emph{Example}:
7321 real(4) :: x = 1.e0_4, y = 0.5e0_4
7323 end program test_hypot
7330 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
7332 @cindex @acronym{ASCII} collating sequence
7333 @cindex collating sequence, @acronym{ASCII}
7334 @cindex conversion, to integer
7337 @item @emph{Description}:
7338 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
7339 in the first character position of @code{C}.
7341 @item @emph{Standard}:
7342 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7347 @item @emph{Syntax}:
7348 @code{RESULT = IACHAR(C [, KIND])}
7350 @item @emph{Arguments}:
7351 @multitable @columnfractions .15 .70
7352 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
7353 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7354 expression indicating the kind parameter of the result.
7357 @item @emph{Return value}:
7358 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7359 @var{KIND} is absent, the return value is of default integer kind.
7361 @item @emph{Example}:
7366 end program test_iachar
7370 See @ref{ICHAR} for a discussion of converting between numerical values
7371 and formatted string representations.
7373 @item @emph{See also}:
7374 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
7381 @section @code{IALL} --- Bitwise AND of array elements
7384 @cindex bits, AND of array elements
7387 @item @emph{Description}:
7388 Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
7389 if the corresponding element in @var{MASK} is @code{TRUE}.
7391 @item @emph{Standard}:
7392 Fortran 2008 and later
7395 Transformational function
7397 @item @emph{Syntax}:
7398 @multitable @columnfractions .80
7399 @item @code{RESULT = IALL(ARRAY[, MASK])}
7400 @item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
7403 @item @emph{Arguments}:
7404 @multitable @columnfractions .15 .70
7405 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7406 @item @var{DIM} @tab (Optional) shall be a scalar of type
7407 @code{INTEGER} with a value in the range from 1 to n, where n
7408 equals the rank of @var{ARRAY}.
7409 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
7410 and either be a scalar or an array of the same shape as @var{ARRAY}.
7413 @item @emph{Return value}:
7414 The result is of the same type as @var{ARRAY}.
7416 If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
7417 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7418 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7419 dimension @var{DIM} dropped is returned.
7421 @item @emph{Example}:
7430 PRINT '(b8.8)', IALL(a)
7434 @item @emph{See also}:
7435 @ref{IANY}, @ref{IPARITY}, @ref{IAND}
7441 @section @code{IAND} --- Bitwise logical and
7447 @cindex bitwise logical and
7448 @cindex logical and, bitwise
7451 @item @emph{Description}:
7452 Bitwise logical @code{AND}.
7454 @item @emph{Standard}:
7455 Fortran 95 and later, has overloads that are GNU extensions
7460 @item @emph{Syntax}:
7461 @code{RESULT = IAND(I, J)}
7463 @item @emph{Arguments}:
7464 @multitable @columnfractions .15 .70
7465 @item @var{I} @tab The type shall be @code{INTEGER}.
7466 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
7467 kind as @var{I}. (As a GNU extension, different kinds are also
7471 @item @emph{Return value}:
7472 The return type is @code{INTEGER}, of the same kind as the
7473 arguments. (If the argument kinds differ, it is of the same kind as
7474 the larger argument.)
7476 @item @emph{Example}:
7480 DATA a / Z'F' /, b / Z'3' /
7481 WRITE (*,*) IAND(a, b)
7485 @item @emph{Specific names}:
7486 @multitable @columnfractions .20 .20 .20 .25
7487 @item Name @tab Argument @tab Return type @tab Standard
7488 @item @code{IAND(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7489 @item @code{BIAND(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7490 @item @code{IIAND(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7491 @item @code{JIAND(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7492 @item @code{KIAND(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7495 @item @emph{See also}:
7496 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
7503 @section @code{IANY} --- Bitwise OR of array elements
7506 @cindex bits, OR of array elements
7509 @item @emph{Description}:
7510 Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
7511 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
7513 @item @emph{Standard}:
7514 Fortran 2008 and later
7517 Transformational function
7519 @item @emph{Syntax}:
7520 @multitable @columnfractions .80
7521 @item @code{RESULT = IANY(ARRAY[, MASK])}
7522 @item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
7525 @item @emph{Arguments}:
7526 @multitable @columnfractions .15 .70
7527 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7528 @item @var{DIM} @tab (Optional) shall be a scalar of type
7529 @code{INTEGER} with a value in the range from 1 to n, where n
7530 equals the rank of @var{ARRAY}.
7531 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
7532 and either be a scalar or an array of the same shape as @var{ARRAY}.
7535 @item @emph{Return value}:
7536 The result is of the same type as @var{ARRAY}.
7538 If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
7539 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7540 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7541 dimension @var{DIM} dropped is returned.
7543 @item @emph{Example}:
7552 PRINT '(b8.8)', IANY(a)
7556 @item @emph{See also}:
7557 @ref{IPARITY}, @ref{IALL}, @ref{IOR}
7563 @section @code{IARGC} --- Get the number of command line arguments
7565 @cindex command-line arguments
7566 @cindex command-line arguments, number of
7567 @cindex arguments, to program
7570 @item @emph{Description}:
7571 @code{IARGC} returns the number of arguments passed on the
7572 command line when the containing program was invoked.
7574 This intrinsic routine is provided for backwards compatibility with
7575 GNU Fortran 77. In new code, programmers should consider the use of
7576 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
7579 @item @emph{Standard}:
7585 @item @emph{Syntax}:
7586 @code{RESULT = IARGC()}
7588 @item @emph{Arguments}:
7591 @item @emph{Return value}:
7592 The number of command line arguments, type @code{INTEGER(4)}.
7594 @item @emph{Example}:
7597 @item @emph{See also}:
7598 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
7600 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
7601 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
7607 @section @code{IBCLR} --- Clear bit
7617 @item @emph{Description}:
7618 @code{IBCLR} returns the value of @var{I} with the bit at position
7619 @var{POS} set to zero.
7621 @item @emph{Standard}:
7622 Fortran 95 and later, has overloads that are GNU extensions
7627 @item @emph{Syntax}:
7628 @code{RESULT = IBCLR(I, POS)}
7630 @item @emph{Arguments}:
7631 @multitable @columnfractions .15 .70
7632 @item @var{I} @tab The type shall be @code{INTEGER}.
7633 @item @var{POS} @tab The type shall be @code{INTEGER}.
7636 @item @emph{Return value}:
7637 The return value is of type @code{INTEGER} and of the same kind as
7640 @item @emph{Specific names}:
7641 @multitable @columnfractions .20 .20 .20 .25
7642 @item Name @tab Argument @tab Return type @tab Standard
7643 @item @code{IBCLR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7644 @item @code{BBCLR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7645 @item @code{IIBCLR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7646 @item @code{JIBCLR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7647 @item @code{KIBCLR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7650 @item @emph{See also}:
7651 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
7658 @section @code{IBITS} --- Bit extraction
7665 @cindex bits, extract
7668 @item @emph{Description}:
7669 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
7670 starting from bit position @var{POS} and extending left for @var{LEN}
7671 bits. The result is right-justified and the remaining bits are
7672 zeroed. The value of @code{POS+LEN} must be less than or equal to the
7673 value @code{BIT_SIZE(I)}.
7675 @item @emph{Standard}:
7676 Fortran 95 and later, has overloads that are GNU extensions
7681 @item @emph{Syntax}:
7682 @code{RESULT = IBITS(I, POS, LEN)}
7684 @item @emph{Arguments}:
7685 @multitable @columnfractions .15 .70
7686 @item @var{I} @tab The type shall be @code{INTEGER}.
7687 @item @var{POS} @tab The type shall be @code{INTEGER}.
7688 @item @var{LEN} @tab The type shall be @code{INTEGER}.
7691 @item @emph{Return value}:
7692 The return value is of type @code{INTEGER} and of the same kind as
7695 @item @emph{Specific names}:
7696 @multitable @columnfractions .20 .20 .20 .25
7697 @item Name @tab Argument @tab Return type @tab Standard
7698 @item @code{IBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7699 @item @code{BBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7700 @item @code{IIBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7701 @item @code{JIBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7702 @item @code{KIBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7705 @item @emph{See also}:
7706 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
7712 @section @code{IBSET} --- Set bit
7721 @item @emph{Description}:
7722 @code{IBSET} returns the value of @var{I} with the bit at position
7723 @var{POS} set to one.
7725 @item @emph{Standard}:
7726 Fortran 95 and later, has overloads that are GNU extensions
7731 @item @emph{Syntax}:
7732 @code{RESULT = IBSET(I, POS)}
7734 @item @emph{Arguments}:
7735 @multitable @columnfractions .15 .70
7736 @item @var{I} @tab The type shall be @code{INTEGER}.
7737 @item @var{POS} @tab The type shall be @code{INTEGER}.
7740 @item @emph{Return value}:
7741 The return value is of type @code{INTEGER} and of the same kind as
7744 @item @emph{Specific names}:
7745 @multitable @columnfractions .20 .20 .20 .25
7746 @item Name @tab Argument @tab Return type @tab Standard
7747 @item @code{IBSET(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7748 @item @code{BBSET(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7749 @item @code{IIBSET(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7750 @item @code{JIBSET(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7751 @item @code{KIBSET(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7754 @item @emph{See also}:
7755 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
7762 @section @code{ICHAR} --- Character-to-integer conversion function
7764 @cindex conversion, to integer
7767 @item @emph{Description}:
7768 @code{ICHAR(C)} returns the code for the character in the first character
7769 position of @code{C} in the system's native character set.
7770 The correspondence between characters and their codes is not necessarily
7771 the same across different GNU Fortran implementations.
7773 @item @emph{Standard}:
7774 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7779 @item @emph{Syntax}:
7780 @code{RESULT = ICHAR(C [, KIND])}
7782 @item @emph{Arguments}:
7783 @multitable @columnfractions .15 .70
7784 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
7785 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7786 expression indicating the kind parameter of the result.
7789 @item @emph{Return value}:
7790 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7791 @var{KIND} is absent, the return value is of default integer kind.
7793 @item @emph{Example}:
7798 end program test_ichar
7801 @item @emph{Specific names}:
7802 @multitable @columnfractions .20 .20 .20 .25
7803 @item Name @tab Argument @tab Return type @tab Standard
7804 @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7808 No intrinsic exists to convert between a numeric value and a formatted
7809 character string representation -- for instance, given the
7810 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
7811 @code{REAL} value with the value 154, or vice versa. Instead, this
7812 functionality is provided by internal-file I/O, as in the following
7817 character(len=10) string, string2
7820 ! Convert a string to a numeric value
7821 read (string,'(I10)') value
7824 ! Convert a value to a formatted string
7825 write (string2,'(I10)') value
7827 end program read_val
7830 @item @emph{See also}:
7831 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
7838 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
7840 @cindex date, current
7841 @cindex current date
7844 @item @emph{Description}:
7845 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
7846 current local time. The day (in the range 1-31), month (in the range 1-12),
7847 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
7848 The year has four significant digits.
7850 This intrinsic routine is provided for backwards compatibility with
7851 GNU Fortran 77. In new code, programmers should consider the use of
7852 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
7855 @item @emph{Standard}:
7861 @item @emph{Syntax}:
7862 @code{CALL IDATE(VALUES)}
7864 @item @emph{Arguments}:
7865 @multitable @columnfractions .15 .70
7866 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
7867 the kind shall be the default integer kind.
7870 @item @emph{Return value}:
7871 Does not return anything.
7873 @item @emph{Example}:
7876 integer, dimension(3) :: tarray
7881 end program test_idate
7884 @item @emph{See also}:
7890 @section @code{IEOR} --- Bitwise logical exclusive or
7896 @cindex bitwise logical exclusive or
7897 @cindex logical exclusive or, bitwise
7900 @item @emph{Description}:
7901 @code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
7904 @item @emph{Standard}:
7905 Fortran 95 and later, has overloads that are GNU extensions
7910 @item @emph{Syntax}:
7911 @code{RESULT = IEOR(I, J)}
7913 @item @emph{Arguments}:
7914 @multitable @columnfractions .15 .70
7915 @item @var{I} @tab The type shall be @code{INTEGER}.
7916 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
7917 kind as @var{I}. (As a GNU extension, different kinds are also
7921 @item @emph{Return value}:
7922 The return type is @code{INTEGER}, of the same kind as the
7923 arguments. (If the argument kinds differ, it is of the same kind as
7924 the larger argument.)
7926 @item @emph{Specific names}:
7927 @multitable @columnfractions .20 .20 .20 .25
7928 @item Name @tab Argument @tab Return type @tab Standard
7929 @item @code{IEOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7930 @item @code{BIEOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7931 @item @code{IIEOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7932 @item @code{JIEOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7933 @item @code{KIEOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7936 @item @emph{See also}:
7937 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
7943 @section @code{IERRNO} --- Get the last system error number
7945 @cindex system, error handling
7948 @item @emph{Description}:
7949 Returns the last system error number, as given by the C @code{errno}
7952 @item @emph{Standard}:
7958 @item @emph{Syntax}:
7959 @code{RESULT = IERRNO()}
7961 @item @emph{Arguments}:
7964 @item @emph{Return value}:
7965 The return value is of type @code{INTEGER} and of the default integer
7968 @item @emph{See also}:
7975 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
7976 @fnindex IMAGE_INDEX
7977 @cindex coarray, @code{IMAGE_INDEX}
7978 @cindex images, cosubscript to image index conversion
7981 @item @emph{Description}:
7982 Returns the image index belonging to a cosubscript.
7984 @item @emph{Standard}:
7985 Fortran 2008 and later
7990 @item @emph{Syntax}:
7991 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
7993 @item @emph{Arguments}: None.
7994 @multitable @columnfractions .15 .70
7995 @item @var{COARRAY} @tab Coarray of any type.
7996 @item @var{SUB} @tab default integer rank-1 array of a size equal to
7997 the corank of @var{COARRAY}.
8001 @item @emph{Return value}:
8002 Scalar default integer with the value of the image index which corresponds
8003 to the cosubscripts. For invalid cosubscripts the result is zero.
8005 @item @emph{Example}:
8007 INTEGER :: array[2,-1:4,8,*]
8008 ! Writes 28 (or 0 if there are fewer than 28 images)
8009 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
8012 @item @emph{See also}:
8013 @ref{THIS_IMAGE}, @ref{NUM_IMAGES}
8018 @node INDEX intrinsic
8019 @section @code{INDEX} --- Position of a substring within a string
8021 @cindex substring position
8022 @cindex string, find substring
8025 @item @emph{Description}:
8026 Returns the position of the start of the first occurrence of string
8027 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
8028 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
8029 the @var{BACK} argument is present and true, the return value is the
8030 start of the last occurrence rather than the first.
8032 @item @emph{Standard}:
8033 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
8038 @item @emph{Syntax}:
8039 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
8041 @item @emph{Arguments}:
8042 @multitable @columnfractions .15 .70
8043 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
8045 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
8047 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
8049 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8050 expression indicating the kind parameter of the result.
8053 @item @emph{Return value}:
8054 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8055 @var{KIND} is absent, the return value is of default integer kind.
8057 @item @emph{Specific names}:
8058 @multitable @columnfractions .20 .20 .20 .25
8059 @item Name @tab Argument @tab Return type @tab Standard
8060 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8063 @item @emph{See also}:
8064 @ref{SCAN}, @ref{VERIFY}
8070 @section @code{INT} --- Convert to integer type
8074 @cindex conversion, to integer
8077 @item @emph{Description}:
8078 Convert to integer type
8080 @item @emph{Standard}:
8081 Fortran 77 and later
8086 @item @emph{Syntax}:
8087 @code{RESULT = INT(A [, KIND))}
8089 @item @emph{Arguments}:
8090 @multitable @columnfractions .15 .70
8091 @item @var{A} @tab Shall be of type @code{INTEGER},
8092 @code{REAL}, or @code{COMPLEX}.
8093 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8094 expression indicating the kind parameter of the result.
8097 @item @emph{Return value}:
8098 These functions return a @code{INTEGER} variable or array under
8099 the following rules:
8103 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
8105 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)}
8106 equals @code{0}. If @math{|A| \geq 1}, then @code{INT(A)} is the integer
8107 whose magnitude is the largest integer that does not exceed the magnitude
8108 of @var{A} and whose sign is the same as the sign of @var{A}.
8110 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
8113 @item @emph{Example}:
8117 complex :: z = (-3.7, 1.0)
8119 print *, int(z), int(z,8)
8123 @item @emph{Specific names}:
8124 @multitable @columnfractions .20 .20 .20 .25
8125 @item Name @tab Argument @tab Return type @tab Standard
8126 @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
8127 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
8128 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
8135 @section @code{INT2} --- Convert to 16-bit integer type
8138 @cindex conversion, to integer
8141 @item @emph{Description}:
8142 Convert to a @code{KIND=2} integer type. This is equivalent to the
8143 standard @code{INT} intrinsic with an optional argument of
8144 @code{KIND=2}, and is only included for backwards compatibility.
8146 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
8148 @item @emph{Standard}:
8154 @item @emph{Syntax}:
8155 @code{RESULT = INT2(A)}
8157 @item @emph{Arguments}:
8158 @multitable @columnfractions .15 .70
8159 @item @var{A} @tab Shall be of type @code{INTEGER},
8160 @code{REAL}, or @code{COMPLEX}.
8163 @item @emph{Return value}:
8164 The return value is a @code{INTEGER(2)} variable.
8166 @item @emph{See also}:
8167 @ref{INT}, @ref{INT8}, @ref{LONG}
8173 @section @code{INT8} --- Convert to 64-bit integer type
8175 @cindex conversion, to integer
8178 @item @emph{Description}:
8179 Convert to a @code{KIND=8} integer type. This is equivalent to the
8180 standard @code{INT} intrinsic with an optional argument of
8181 @code{KIND=8}, and is only included for backwards compatibility.
8183 @item @emph{Standard}:
8189 @item @emph{Syntax}:
8190 @code{RESULT = INT8(A)}
8192 @item @emph{Arguments}:
8193 @multitable @columnfractions .15 .70
8194 @item @var{A} @tab Shall be of type @code{INTEGER},
8195 @code{REAL}, or @code{COMPLEX}.
8198 @item @emph{Return value}:
8199 The return value is a @code{INTEGER(8)} variable.
8201 @item @emph{See also}:
8202 @ref{INT}, @ref{INT2}, @ref{LONG}
8208 @section @code{IOR} --- Bitwise logical or
8214 @cindex bitwise logical or
8215 @cindex logical or, bitwise
8218 @item @emph{Description}:
8219 @code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
8222 @item @emph{Standard}:
8223 Fortran 95 and later, has overloads that are GNU extensions
8228 @item @emph{Syntax}:
8229 @code{RESULT = IOR(I, J)}
8231 @item @emph{Arguments}:
8232 @multitable @columnfractions .15 .70
8233 @item @var{I} @tab The type shall be @code{INTEGER}.
8234 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
8235 kind as @var{I}. (As a GNU extension, different kinds are also
8239 @item @emph{Return value}:
8240 The return type is @code{INTEGER}, of the same kind as the
8241 arguments. (If the argument kinds differ, it is of the same kind as
8242 the larger argument.)
8244 @item @emph{Specific names}:
8245 @multitable @columnfractions .20 .20 .20 .25
8246 @item Name @tab Argument @tab Return type @tab Standard
8247 @item @code{IOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
8248 @item @code{BIOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8249 @item @code{IIOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8250 @item @code{JIOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8251 @item @code{KIOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8254 @item @emph{See also}:
8255 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
8261 @section @code{IPARITY} --- Bitwise XOR of array elements
8263 @cindex array, parity
8265 @cindex bits, XOR of array elements
8268 @item @emph{Description}:
8269 Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
8270 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
8272 @item @emph{Standard}:
8273 Fortran 2008 and later
8276 Transformational function
8278 @item @emph{Syntax}:
8279 @multitable @columnfractions .80
8280 @item @code{RESULT = IPARITY(ARRAY[, MASK])}
8281 @item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
8284 @item @emph{Arguments}:
8285 @multitable @columnfractions .15 .70
8286 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
8287 @item @var{DIM} @tab (Optional) shall be a scalar of type
8288 @code{INTEGER} with a value in the range from 1 to n, where n
8289 equals the rank of @var{ARRAY}.
8290 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
8291 and either be a scalar or an array of the same shape as @var{ARRAY}.
8294 @item @emph{Return value}:
8295 The result is of the same type as @var{ARRAY}.
8297 If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
8298 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
8299 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
8300 dimension @var{DIM} dropped is returned.
8302 @item @emph{Example}:
8304 PROGRAM test_iparity
8311 PRINT '(b8.8)', IPARITY(a)
8315 @item @emph{See also}:
8316 @ref{IANY}, @ref{IALL}, @ref{IEOR}, @ref{PARITY}
8322 @section @code{IRAND} --- Integer pseudo-random number
8324 @cindex random number generation
8327 @item @emph{Description}:
8328 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
8329 distribution between 0 and a system-dependent limit (which is in most
8330 cases 2147483647). If @var{FLAG} is 0, the next number
8331 in the current sequence is returned; if @var{FLAG} is 1, the generator
8332 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
8333 it is used as a new seed with @code{SRAND}.
8335 This intrinsic routine is provided for backwards compatibility with
8336 GNU Fortran 77. It implements a simple modulo generator as provided
8337 by @command{g77}. For new code, one should consider the use of
8338 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
8340 @item @emph{Standard}:
8346 @item @emph{Syntax}:
8347 @code{RESULT = IRAND(I)}
8349 @item @emph{Arguments}:
8350 @multitable @columnfractions .15 .70
8351 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
8354 @item @emph{Return value}:
8355 The return value is of @code{INTEGER(kind=4)} type.
8357 @item @emph{Example}:
8360 integer,parameter :: seed = 86456
8363 print *, irand(), irand(), irand(), irand()
8364 print *, irand(seed), irand(), irand(), irand()
8365 end program test_irand
8373 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
8374 @fnindex IS_IOSTAT_END
8375 @cindex @code{IOSTAT}, end of file
8378 @item @emph{Description}:
8379 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
8380 status ``end of file''. The function is equivalent to comparing the variable
8381 with the @code{IOSTAT_END} parameter of the intrinsic module
8382 @code{ISO_FORTRAN_ENV}.
8384 @item @emph{Standard}:
8385 Fortran 2003 and later
8390 @item @emph{Syntax}:
8391 @code{RESULT = IS_IOSTAT_END(I)}
8393 @item @emph{Arguments}:
8394 @multitable @columnfractions .15 .70
8395 @item @var{I} @tab Shall be of the type @code{INTEGER}.
8398 @item @emph{Return value}:
8399 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
8400 @var{I} has the value which indicates an end of file condition for
8401 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
8403 @item @emph{Example}:
8408 OPEN(88, FILE='test.dat')
8409 READ(88, *, IOSTAT=stat) i
8410 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
8418 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
8419 @fnindex IS_IOSTAT_EOR
8420 @cindex @code{IOSTAT}, end of record
8423 @item @emph{Description}:
8424 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
8425 status ``end of record''. The function is equivalent to comparing the
8426 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
8427 @code{ISO_FORTRAN_ENV}.
8429 @item @emph{Standard}:
8430 Fortran 2003 and later
8435 @item @emph{Syntax}:
8436 @code{RESULT = IS_IOSTAT_EOR(I)}
8438 @item @emph{Arguments}:
8439 @multitable @columnfractions .15 .70
8440 @item @var{I} @tab Shall be of the type @code{INTEGER}.
8443 @item @emph{Return value}:
8444 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
8445 @var{I} has the value which indicates an end of file condition for
8446 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
8448 @item @emph{Example}:
8452 INTEGER :: stat, i(50)
8453 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
8454 READ(88, IOSTAT=stat) i
8455 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
8463 @section @code{ISATTY} --- Whether a unit is a terminal device.
8465 @cindex system, terminal
8468 @item @emph{Description}:
8469 Determine whether a unit is connected to a terminal device.
8471 @item @emph{Standard}:
8477 @item @emph{Syntax}:
8478 @code{RESULT = ISATTY(UNIT)}
8480 @item @emph{Arguments}:
8481 @multitable @columnfractions .15 .70
8482 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
8485 @item @emph{Return value}:
8486 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
8487 device, @code{.FALSE.} otherwise.
8489 @item @emph{Example}:
8492 INTEGER(kind=1) :: unit
8494 write(*,*) isatty(unit=unit)
8498 @item @emph{See also}:
8505 @section @code{ISHFT} --- Shift bits
8514 @item @emph{Description}:
8515 @code{ISHFT} returns a value corresponding to @var{I} with all of the
8516 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
8517 zero corresponds to a left shift, a value of zero corresponds to no
8518 shift, and a value less than zero corresponds to a right shift. If the
8519 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
8520 value is undefined. Bits shifted out from the left end or right end are
8521 lost; zeros are shifted in from the opposite end.
8523 @item @emph{Standard}:
8524 Fortran 95 and later, has overloads that are GNU extensions
8529 @item @emph{Syntax}:
8530 @code{RESULT = ISHFT(I, SHIFT)}
8532 @item @emph{Arguments}:
8533 @multitable @columnfractions .15 .70
8534 @item @var{I} @tab The type shall be @code{INTEGER}.
8535 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8538 @item @emph{Return value}:
8539 The return value is of type @code{INTEGER} and of the same kind as
8542 @item @emph{Specific names}:
8543 @multitable @columnfractions .20 .20 .20 .25
8544 @item Name @tab Argument @tab Return type @tab Standard
8545 @item @code{ISHFT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
8546 @item @code{BSHFT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8547 @item @code{IISHFT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8548 @item @code{JISHFT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8549 @item @code{KISHFT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8552 @item @emph{See also}:
8559 @section @code{ISHFTC} --- Shift bits circularly
8565 @cindex bits, shift circular
8568 @item @emph{Description}:
8569 @code{ISHFTC} returns a value corresponding to @var{I} with the
8570 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
8571 is, bits shifted out one end are shifted into the opposite end. A value
8572 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
8573 zero corresponds to no shift, and a value less than zero corresponds to
8574 a right shift. The absolute value of @var{SHIFT} must be less than
8575 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
8576 equivalent to @code{BIT_SIZE(I)}.
8578 @item @emph{Standard}:
8579 Fortran 95 and later, has overloads that are GNU extensions
8584 @item @emph{Syntax}:
8585 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
8587 @item @emph{Arguments}:
8588 @multitable @columnfractions .15 .70
8589 @item @var{I} @tab The type shall be @code{INTEGER}.
8590 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8591 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
8592 the value must be greater than zero and less than or equal to
8596 @item @emph{Return value}:
8597 The return value is of type @code{INTEGER} and of the same kind as
8600 @item @emph{Specific names}:
8601 @multitable @columnfractions .20 .20 .20 .25
8602 @item Name @tab Argument @tab Return type @tab Standard
8603 @item @code{ISHFTC(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
8604 @item @code{BSHFTC(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8605 @item @code{IISHFTC(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8606 @item @code{JISHFTC(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8607 @item @code{KISHFTC(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8610 @item @emph{See also}:
8617 @section @code{ISNAN} --- Test for a NaN
8622 @item @emph{Description}:
8623 @code{ISNAN} tests whether a floating-point value is an IEEE
8625 @item @emph{Standard}:
8631 @item @emph{Syntax}:
8634 @item @emph{Arguments}:
8635 @multitable @columnfractions .15 .70
8636 @item @var{X} @tab Variable of the type @code{REAL}.
8640 @item @emph{Return value}:
8641 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
8642 if @var{X} is a NaN and @code{FALSE} otherwise.
8644 @item @emph{Example}:
8651 if (isnan(x)) stop '"x" is a NaN'
8652 end program test_nan
8659 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
8661 @cindex time, current
8662 @cindex current time
8665 @item @emph{Description}:
8666 @code{ITIME(VALUES)} Fills @var{VALUES} with the numerical values at the
8667 current local time. The hour (in the range 1-24), minute (in the range 1-60),
8668 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
8671 This intrinsic routine is provided for backwards compatibility with
8672 GNU Fortran 77. In new code, programmers should consider the use of
8673 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
8676 @item @emph{Standard}:
8682 @item @emph{Syntax}:
8683 @code{CALL ITIME(VALUES)}
8685 @item @emph{Arguments}:
8686 @multitable @columnfractions .15 .70
8687 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
8688 and the kind shall be the default integer kind.
8691 @item @emph{Return value}:
8692 Does not return anything.
8695 @item @emph{Example}:
8698 integer, dimension(3) :: tarray
8703 end program test_itime
8706 @item @emph{See also}:
8713 @section @code{KILL} --- Send a signal to a process
8717 @item @emph{Description}:
8718 @item @emph{Standard}:
8719 Sends the signal specified by @var{SIG} to the process @var{PID}.
8722 This intrinsic is provided in both subroutine and function forms;
8723 however, only one form can be used in any given program unit.
8726 Subroutine, function
8728 @item @emph{Syntax}:
8729 @multitable @columnfractions .80
8730 @item @code{CALL KILL(PID, SIG [, STATUS])}
8731 @item @code{STATUS = KILL(PID, SIG)}
8734 @item @emph{Arguments}:
8735 @multitable @columnfractions .15 .70
8736 @item @var{PID} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}.
8737 @item @var{SIG} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}.
8738 @item @var{STATUS} @tab [Subroutine](Optional)
8739 Shall be a scalar @code{INTEGER}.
8740 Returns 0 on success; otherwise a system-specific error code is returned.
8741 @item @var{STATUS} @tab [Function] The kind type parameter is that of
8743 Returns 0 on success; otherwise a system-specific error code is returned.
8746 @item @emph{See also}:
8747 @ref{ABORT}, @ref{EXIT}
8752 @section @code{KIND} --- Kind of an entity
8757 @item @emph{Description}:
8758 @code{KIND(X)} returns the kind value of the entity @var{X}.
8760 @item @emph{Standard}:
8761 Fortran 95 and later
8766 @item @emph{Syntax}:
8769 @item @emph{Arguments}:
8770 @multitable @columnfractions .15 .70
8771 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
8772 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
8775 @item @emph{Return value}:
8776 The return value is a scalar of type @code{INTEGER} and of the default
8779 @item @emph{Example}:
8782 integer,parameter :: kc = kind(' ')
8783 integer,parameter :: kl = kind(.true.)
8785 print *, "The default character kind is ", kc
8786 print *, "The default logical kind is ", kl
8787 end program test_kind
8795 @section @code{LBOUND} --- Lower dimension bounds of an array
8797 @cindex array, lower bound
8800 @item @emph{Description}:
8801 Returns the lower bounds of an array, or a single lower bound
8802 along the @var{DIM} dimension.
8803 @item @emph{Standard}:
8804 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
8809 @item @emph{Syntax}:
8810 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
8812 @item @emph{Arguments}:
8813 @multitable @columnfractions .15 .70
8814 @item @var{ARRAY} @tab Shall be an array, of any type.
8815 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
8816 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8817 expression indicating the kind parameter of the result.
8820 @item @emph{Return value}:
8821 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8822 @var{KIND} is absent, the return value is of default integer kind.
8823 If @var{DIM} is absent, the result is an array of the lower bounds of
8824 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
8825 corresponding to the lower bound of the array along that dimension. If
8826 @var{ARRAY} is an expression rather than a whole array or array
8827 structure component, or if it has a zero extent along the relevant
8828 dimension, the lower bound is taken to be 1.
8830 @item @emph{See also}:
8831 @ref{UBOUND}, @ref{LCOBOUND}
8837 @section @code{LCOBOUND} --- Lower codimension bounds of an array
8839 @cindex coarray, lower bound
8842 @item @emph{Description}:
8843 Returns the lower bounds of a coarray, or a single lower cobound
8844 along the @var{DIM} codimension.
8845 @item @emph{Standard}:
8846 Fortran 2008 and later
8851 @item @emph{Syntax}:
8852 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
8854 @item @emph{Arguments}:
8855 @multitable @columnfractions .15 .70
8856 @item @var{ARRAY} @tab Shall be an coarray, of any type.
8857 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
8858 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8859 expression indicating the kind parameter of the result.
8862 @item @emph{Return value}:
8863 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8864 @var{KIND} is absent, the return value is of default integer kind.
8865 If @var{DIM} is absent, the result is an array of the lower cobounds of
8866 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
8867 corresponding to the lower cobound of the array along that codimension.
8869 @item @emph{See also}:
8870 @ref{UCOBOUND}, @ref{LBOUND}
8876 @section @code{LEADZ} --- Number of leading zero bits of an integer
8881 @item @emph{Description}:
8882 @code{LEADZ} returns the number of leading zero bits of an integer.
8884 @item @emph{Standard}:
8885 Fortran 2008 and later
8890 @item @emph{Syntax}:
8891 @code{RESULT = LEADZ(I)}
8893 @item @emph{Arguments}:
8894 @multitable @columnfractions .15 .70
8895 @item @var{I} @tab Shall be of type @code{INTEGER}.
8898 @item @emph{Return value}:
8899 The type of the return value is the default @code{INTEGER}.
8900 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
8902 @item @emph{Example}:
8905 WRITE (*,*) BIT_SIZE(1) ! prints 32
8906 WRITE (*,*) LEADZ(1) ! prints 31
8910 @item @emph{See also}:
8911 @ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR}
8917 @section @code{LEN} --- Length of a character entity
8919 @cindex string, length
8922 @item @emph{Description}:
8923 Returns the length of a character string. If @var{STRING} is an array,
8924 the length of an element of @var{STRING} is returned. Note that
8925 @var{STRING} need not be defined when this intrinsic is invoked, since
8926 only the length, not the content, of @var{STRING} is needed.
8928 @item @emph{Standard}:
8929 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
8934 @item @emph{Syntax}:
8935 @code{L = LEN(STRING [, KIND])}
8937 @item @emph{Arguments}:
8938 @multitable @columnfractions .15 .70
8939 @item @var{STRING} @tab Shall be a scalar or array of type
8940 @code{CHARACTER}, with @code{INTENT(IN)}
8941 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8942 expression indicating the kind parameter of the result.
8945 @item @emph{Return value}:
8946 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8947 @var{KIND} is absent, the return value is of default integer kind.
8950 @item @emph{Specific names}:
8951 @multitable @columnfractions .20 .20 .20 .25
8952 @item Name @tab Argument @tab Return type @tab Standard
8953 @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
8957 @item @emph{See also}:
8958 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
8964 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
8966 @cindex string, length, without trailing whitespace
8969 @item @emph{Description}:
8970 Returns the length of a character string, ignoring any trailing blanks.
8972 @item @emph{Standard}:
8973 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
8978 @item @emph{Syntax}:
8979 @code{RESULT = LEN_TRIM(STRING [, KIND])}
8981 @item @emph{Arguments}:
8982 @multitable @columnfractions .15 .70
8983 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
8984 with @code{INTENT(IN)}
8985 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8986 expression indicating the kind parameter of the result.
8989 @item @emph{Return value}:
8990 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8991 @var{KIND} is absent, the return value is of default integer kind.
8993 @item @emph{See also}:
8994 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
9000 @section @code{LGE} --- Lexical greater than or equal
9002 @cindex lexical comparison of strings
9003 @cindex string, comparison
9006 @item @emph{Description}:
9007 Determines whether one string is lexically greater than or equal to
9008 another string, where the two strings are interpreted as containing
9009 ASCII character codes. If the String A and String B are not the same
9010 length, the shorter is compared as if spaces were appended to it to form
9011 a value that has the same length as the longer.
9013 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9014 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9015 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9016 that the latter use the processor's character ordering (which is not
9017 ASCII on some targets), whereas the former always use the ASCII
9020 @item @emph{Standard}:
9021 Fortran 77 and later
9026 @item @emph{Syntax}:
9027 @code{RESULT = LGE(STRING_A, STRING_B)}
9029 @item @emph{Arguments}:
9030 @multitable @columnfractions .15 .70
9031 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9032 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9035 @item @emph{Return value}:
9036 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
9037 otherwise, based on the ASCII ordering.
9039 @item @emph{Specific names}:
9040 @multitable @columnfractions .20 .20 .20 .25
9041 @item Name @tab Argument @tab Return type @tab Standard
9042 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9045 @item @emph{See also}:
9046 @ref{LGT}, @ref{LLE}, @ref{LLT}
9052 @section @code{LGT} --- Lexical greater than
9054 @cindex lexical comparison of strings
9055 @cindex string, comparison
9058 @item @emph{Description}:
9059 Determines whether one string is lexically greater than another string,
9060 where the two strings are interpreted as containing ASCII character
9061 codes. If the String A and String B are not the same length, the
9062 shorter is compared as if spaces were appended to it to form a value
9063 that has the same length as the longer.
9065 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9066 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9067 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9068 that the latter use the processor's character ordering (which is not
9069 ASCII on some targets), whereas the former always use the ASCII
9072 @item @emph{Standard}:
9073 Fortran 77 and later
9078 @item @emph{Syntax}:
9079 @code{RESULT = LGT(STRING_A, STRING_B)}
9081 @item @emph{Arguments}:
9082 @multitable @columnfractions .15 .70
9083 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9084 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9087 @item @emph{Return value}:
9088 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
9089 otherwise, based on the ASCII ordering.
9091 @item @emph{Specific names}:
9092 @multitable @columnfractions .20 .20 .20 .25
9093 @item Name @tab Argument @tab Return type @tab Standard
9094 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9097 @item @emph{See also}:
9098 @ref{LGE}, @ref{LLE}, @ref{LLT}
9104 @section @code{LINK} --- Create a hard link
9106 @cindex file system, create link
9107 @cindex file system, hard link
9110 @item @emph{Description}:
9111 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
9112 character (@code{CHAR(0)}) can be used to mark the end of the names in
9113 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
9114 names are ignored. If the @var{STATUS} argument is supplied, it
9115 contains 0 on success or a nonzero error code upon return; see
9118 This intrinsic is provided in both subroutine and function forms;
9119 however, only one form can be used in any given program unit.
9121 @item @emph{Standard}:
9125 Subroutine, function
9127 @item @emph{Syntax}:
9128 @multitable @columnfractions .80
9129 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
9130 @item @code{STATUS = LINK(PATH1, PATH2)}
9133 @item @emph{Arguments}:
9134 @multitable @columnfractions .15 .70
9135 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
9136 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
9137 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9140 @item @emph{See also}:
9141 @ref{SYMLNK}, @ref{UNLINK}
9147 @section @code{LLE} --- Lexical less than or equal
9149 @cindex lexical comparison of strings
9150 @cindex string, comparison
9153 @item @emph{Description}:
9154 Determines whether one string is lexically less than or equal to another
9155 string, where the two strings are interpreted as containing ASCII
9156 character codes. If the String A and String B are not the same length,
9157 the shorter is compared as if spaces were appended to it to form a value
9158 that has the same length as the longer.
9160 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9161 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9162 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9163 that the latter use the processor's character ordering (which is not
9164 ASCII on some targets), whereas the former always use the ASCII
9167 @item @emph{Standard}:
9168 Fortran 77 and later
9173 @item @emph{Syntax}:
9174 @code{RESULT = LLE(STRING_A, STRING_B)}
9176 @item @emph{Arguments}:
9177 @multitable @columnfractions .15 .70
9178 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9179 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9182 @item @emph{Return value}:
9183 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
9184 otherwise, based on the ASCII ordering.
9186 @item @emph{Specific names}:
9187 @multitable @columnfractions .20 .20 .20 .25
9188 @item Name @tab Argument @tab Return type @tab Standard
9189 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9192 @item @emph{See also}:
9193 @ref{LGE}, @ref{LGT}, @ref{LLT}
9199 @section @code{LLT} --- Lexical less than
9201 @cindex lexical comparison of strings
9202 @cindex string, comparison
9205 @item @emph{Description}:
9206 Determines whether one string is lexically less than another string,
9207 where the two strings are interpreted as containing ASCII character
9208 codes. If the String A and String B are not the same length, the
9209 shorter is compared as if spaces were appended to it to form a value
9210 that has the same length as the longer.
9212 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9213 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9214 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9215 that the latter use the processor's character ordering (which is not
9216 ASCII on some targets), whereas the former always use the ASCII
9219 @item @emph{Standard}:
9220 Fortran 77 and later
9225 @item @emph{Syntax}:
9226 @code{RESULT = LLT(STRING_A, STRING_B)}
9228 @item @emph{Arguments}:
9229 @multitable @columnfractions .15 .70
9230 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9231 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9234 @item @emph{Return value}:
9235 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
9236 otherwise, based on the ASCII ordering.
9238 @item @emph{Specific names}:
9239 @multitable @columnfractions .20 .20 .20 .25
9240 @item Name @tab Argument @tab Return type @tab Standard
9241 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9244 @item @emph{See also}:
9245 @ref{LGE}, @ref{LGT}, @ref{LLE}
9251 @section @code{LNBLNK} --- Index of the last non-blank character in a string
9253 @cindex string, find non-blank character
9256 @item @emph{Description}:
9257 Returns the length of a character string, ignoring any trailing blanks.
9258 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
9259 included for backwards compatibility.
9261 @item @emph{Standard}:
9267 @item @emph{Syntax}:
9268 @code{RESULT = LNBLNK(STRING)}
9270 @item @emph{Arguments}:
9271 @multitable @columnfractions .15 .70
9272 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
9273 with @code{INTENT(IN)}
9276 @item @emph{Return value}:
9277 The return value is of @code{INTEGER(kind=4)} type.
9279 @item @emph{See also}:
9280 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
9286 @section @code{LOC} --- Returns the address of a variable
9288 @cindex location of a variable in memory
9291 @item @emph{Description}:
9292 @code{LOC(X)} returns the address of @var{X} as an integer.
9294 @item @emph{Standard}:
9300 @item @emph{Syntax}:
9301 @code{RESULT = LOC(X)}
9303 @item @emph{Arguments}:
9304 @multitable @columnfractions .15 .70
9305 @item @var{X} @tab Variable of any type.
9308 @item @emph{Return value}:
9309 The return value is of type @code{INTEGER}, with a @code{KIND}
9310 corresponding to the size (in bytes) of a memory address on the target
9313 @item @emph{Example}:
9320 end program test_loc
9327 @section @code{LOG} --- Natural logarithm function
9334 @cindex exponential function, inverse
9335 @cindex logarithm function
9336 @cindex natural logarithm function
9339 @item @emph{Description}:
9340 @code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the
9341 logarithm to the base @math{e}.
9343 @item @emph{Standard}:
9344 Fortran 77 and later
9349 @item @emph{Syntax}:
9350 @code{RESULT = LOG(X)}
9352 @item @emph{Arguments}:
9353 @multitable @columnfractions .15 .70
9354 @item @var{X} @tab The type shall be @code{REAL} or
9358 @item @emph{Return value}:
9359 The return value is of type @code{REAL} or @code{COMPLEX}.
9360 The kind type parameter is the same as @var{X}.
9361 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
9362 @math{-\pi < \omega \leq \pi}.
9364 @item @emph{Example}:
9367 real(8) :: x = 2.7182818284590451_8
9368 complex :: z = (1.0, 2.0)
9369 x = log(x) ! will yield (approximately) 1
9371 end program test_log
9374 @item @emph{Specific names}:
9375 @multitable @columnfractions .20 .20 .20 .25
9376 @item Name @tab Argument @tab Return type @tab Standard
9377 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
9378 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
9379 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
9380 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9381 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9388 @section @code{LOG10} --- Base 10 logarithm function
9392 @cindex exponential function, inverse
9393 @cindex logarithm function with base 10
9394 @cindex base 10 logarithm function
9397 @item @emph{Description}:
9398 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
9400 @item @emph{Standard}:
9401 Fortran 77 and later
9406 @item @emph{Syntax}:
9407 @code{RESULT = LOG10(X)}
9409 @item @emph{Arguments}:
9410 @multitable @columnfractions .15 .70
9411 @item @var{X} @tab The type shall be @code{REAL}.
9414 @item @emph{Return value}:
9415 The return value is of type @code{REAL} or @code{COMPLEX}.
9416 The kind type parameter is the same as @var{X}.
9418 @item @emph{Example}:
9421 real(8) :: x = 10.0_8
9423 end program test_log10
9426 @item @emph{Specific names}:
9427 @multitable @columnfractions .20 .20 .20 .25
9428 @item Name @tab Argument @tab Return type @tab Standard
9429 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
9430 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
9437 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
9442 @cindex Gamma function, logarithm of
9445 @item @emph{Description}:
9446 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
9447 of the Gamma (@math{\Gamma}) function.
9449 @item @emph{Standard}:
9450 Fortran 2008 and later
9455 @item @emph{Syntax}:
9456 @code{X = LOG_GAMMA(X)}
9458 @item @emph{Arguments}:
9459 @multitable @columnfractions .15 .70
9460 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
9461 nor a negative integer.
9464 @item @emph{Return value}:
9465 The return value is of type @code{REAL} of the same kind as @var{X}.
9467 @item @emph{Example}:
9469 program test_log_gamma
9471 x = lgamma(x) ! returns 0.0
9472 end program test_log_gamma
9475 @item @emph{Specific names}:
9476 @multitable @columnfractions .20 .20 .20 .25
9477 @item Name @tab Argument @tab Return type @tab Standard
9478 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
9479 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
9480 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
9483 @item @emph{See also}:
9484 Gamma function: @ref{GAMMA}
9491 @section @code{LOGICAL} --- Convert to logical type
9493 @cindex conversion, to logical
9496 @item @emph{Description}:
9497 Converts one kind of @code{LOGICAL} variable to another.
9499 @item @emph{Standard}:
9500 Fortran 95 and later
9505 @item @emph{Syntax}:
9506 @code{RESULT = LOGICAL(L [, KIND])}
9508 @item @emph{Arguments}:
9509 @multitable @columnfractions .15 .70
9510 @item @var{L} @tab The type shall be @code{LOGICAL}.
9511 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9512 expression indicating the kind parameter of the result.
9515 @item @emph{Return value}:
9516 The return value is a @code{LOGICAL} value equal to @var{L}, with a
9517 kind corresponding to @var{KIND}, or of the default logical kind if
9518 @var{KIND} is not given.
9520 @item @emph{See also}:
9521 @ref{INT}, @ref{REAL}, @ref{CMPLX}
9527 @section @code{LONG} --- Convert to integer type
9529 @cindex conversion, to integer
9532 @item @emph{Description}:
9533 Convert to a @code{KIND=4} integer type, which is the same size as a C
9534 @code{long} integer. This is equivalent to the standard @code{INT}
9535 intrinsic with an optional argument of @code{KIND=4}, and is only
9536 included for backwards compatibility.
9538 @item @emph{Standard}:
9544 @item @emph{Syntax}:
9545 @code{RESULT = LONG(A)}
9547 @item @emph{Arguments}:
9548 @multitable @columnfractions .15 .70
9549 @item @var{A} @tab Shall be of type @code{INTEGER},
9550 @code{REAL}, or @code{COMPLEX}.
9553 @item @emph{Return value}:
9554 The return value is a @code{INTEGER(4)} variable.
9556 @item @emph{See also}:
9557 @ref{INT}, @ref{INT2}, @ref{INT8}
9563 @section @code{LSHIFT} --- Left shift bits
9565 @cindex bits, shift left
9568 @item @emph{Description}:
9569 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
9570 bits shifted left by @var{SHIFT} places. If the absolute value of
9571 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
9572 Bits shifted out from the left end are lost; zeros are shifted in from
9575 This function has been superseded by the @code{ISHFT} intrinsic, which
9576 is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
9577 which is standard in Fortran 2008 and later.
9579 @item @emph{Standard}:
9585 @item @emph{Syntax}:
9586 @code{RESULT = LSHIFT(I, SHIFT)}
9588 @item @emph{Arguments}:
9589 @multitable @columnfractions .15 .70
9590 @item @var{I} @tab The type shall be @code{INTEGER}.
9591 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
9594 @item @emph{Return value}:
9595 The return value is of type @code{INTEGER} and of the same kind as
9598 @item @emph{See also}:
9599 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}, @ref{SHIFTA}, @ref{SHIFTL},
9607 @section @code{LSTAT} --- Get file status
9609 @cindex file system, file status
9612 @item @emph{Description}:
9613 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
9614 symbolic link, then the link itself is statted, not the file that it
9617 The elements in @code{VALUES} are the same as described by @ref{STAT}.
9619 This intrinsic is provided in both subroutine and function forms;
9620 however, only one form can be used in any given program unit.
9622 @item @emph{Standard}:
9626 Subroutine, function
9628 @item @emph{Syntax}:
9629 @multitable @columnfractions .80
9630 @item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
9631 @item @code{STATUS = LSTAT(NAME, VALUES)}
9634 @item @emph{Arguments}:
9635 @multitable @columnfractions .15 .70
9636 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
9637 kind, a valid path within the file system.
9638 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
9639 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
9640 Returns 0 on success and a system specific error code otherwise.
9643 @item @emph{Example}:
9644 See @ref{STAT} for an example.
9646 @item @emph{See also}:
9647 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
9653 @section @code{LTIME} --- Convert time to local time info
9655 @cindex time, conversion to local time info
9658 @item @emph{Description}:
9659 Given a system time value @var{TIME} (as provided by the @ref{TIME}
9660 intrinsic), fills @var{VALUES} with values extracted from it appropriate
9661 to the local time zone using @code{localtime(3)}.
9663 This intrinsic routine is provided for backwards compatibility with
9664 GNU Fortran 77. In new code, programmers should consider the use of
9665 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
9668 @item @emph{Standard}:
9674 @item @emph{Syntax}:
9675 @code{CALL LTIME(TIME, VALUES)}
9677 @item @emph{Arguments}:
9678 @multitable @columnfractions .15 .70
9679 @item @var{TIME} @tab An @code{INTEGER} scalar expression
9680 corresponding to a system time, with @code{INTENT(IN)}.
9681 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
9682 with @code{INTENT(OUT)}.
9685 @item @emph{Return value}:
9686 The elements of @var{VALUES} are assigned as follows:
9688 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
9690 @item Minutes after the hour, range 0--59
9691 @item Hours past midnight, range 0--23
9692 @item Day of month, range 1--31
9693 @item Number of months since January, range 0--11
9694 @item Years since 1900
9695 @item Number of days since Sunday, range 0--6
9696 @item Days since January 1, range 0--365
9697 @item Daylight savings indicator: positive if daylight savings is in
9698 effect, zero if not, and negative if the information is not available.
9701 @item @emph{See also}:
9702 @ref{DATE_AND_TIME}, @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
9709 @section @code{MALLOC} --- Allocate dynamic memory
9711 @cindex pointer, cray
9714 @item @emph{Description}:
9715 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
9716 returns the address of the allocated memory. The @code{MALLOC} intrinsic
9717 is an extension intended to be used with Cray pointers, and is provided
9718 in GNU Fortran to allow the user to compile legacy code. For new code
9719 using Fortran 95 pointers, the memory allocation intrinsic is
9722 @item @emph{Standard}:
9728 @item @emph{Syntax}:
9729 @code{PTR = MALLOC(SIZE)}
9731 @item @emph{Arguments}:
9732 @multitable @columnfractions .15 .70
9733 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
9736 @item @emph{Return value}:
9737 The return value is of type @code{INTEGER(K)}, with @var{K} such that
9738 variables of type @code{INTEGER(K)} have the same size as
9739 C pointers (@code{sizeof(void *)}).
9741 @item @emph{Example}:
9742 The following example demonstrates the use of @code{MALLOC} and
9743 @code{FREE} with Cray pointers.
9752 ptr_x = malloc(20*8)
9754 x(i) = sqrt(1.0d0 / i)
9762 end program test_malloc
9765 @item @emph{See also}:
9772 @section @code{MASKL} --- Left justified mask
9774 @cindex mask, left justified
9777 @item @emph{Description}:
9778 @code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
9779 remaining bits set to 0.
9781 @item @emph{Standard}:
9782 Fortran 2008 and later
9787 @item @emph{Syntax}:
9788 @code{RESULT = MASKL(I[, KIND])}
9790 @item @emph{Arguments}:
9791 @multitable @columnfractions .15 .70
9792 @item @var{I} @tab Shall be of type @code{INTEGER}.
9793 @item @var{KIND} @tab Shall be a scalar constant expression of type
9797 @item @emph{Return value}:
9798 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
9799 specifies the kind value of the return type; otherwise, it is of the
9800 default integer kind.
9802 @item @emph{See also}:
9809 @section @code{MASKR} --- Right justified mask
9811 @cindex mask, right justified
9814 @item @emph{Description}:
9815 @code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
9816 remaining bits set to 0.
9818 @item @emph{Standard}:
9819 Fortran 2008 and later
9824 @item @emph{Syntax}:
9825 @code{RESULT = MASKR(I[, KIND])}
9827 @item @emph{Arguments}:
9828 @multitable @columnfractions .15 .70
9829 @item @var{I} @tab Shall be of type @code{INTEGER}.
9830 @item @var{KIND} @tab Shall be a scalar constant expression of type
9834 @item @emph{Return value}:
9835 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
9836 specifies the kind value of the return type; otherwise, it is of the
9837 default integer kind.
9839 @item @emph{See also}:
9846 @section @code{MATMUL} --- matrix multiplication
9848 @cindex matrix multiplication
9849 @cindex product, matrix
9852 @item @emph{Description}:
9853 Performs a matrix multiplication on numeric or logical arguments.
9855 @item @emph{Standard}:
9856 Fortran 95 and later
9859 Transformational function
9861 @item @emph{Syntax}:
9862 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
9864 @item @emph{Arguments}:
9865 @multitable @columnfractions .15 .70
9866 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
9867 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
9869 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
9870 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
9871 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
9872 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
9873 equal to the last (or only) dimension of @var{MATRIX_A}.
9874 @var{MATRIX_A} and @var{MATRIX_B} shall not both be rank one arrays.
9877 @item @emph{Return value}:
9878 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
9879 kind of the result follow the usual type and kind promotion rules, as
9880 for the @code{*} or @code{.AND.} operators.
9882 @item @emph{See also}:
9888 @section @code{MAX} --- Maximum value of an argument list
9895 @cindex maximum value
9898 @item @emph{Description}:
9899 Returns the argument with the largest (most positive) value.
9901 @item @emph{Standard}:
9902 Fortran 77 and later
9907 @item @emph{Syntax}:
9908 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
9910 @item @emph{Arguments}:
9911 @multitable @columnfractions .15 .70
9912 @item @var{A1} @tab The type shall be @code{INTEGER} or
9914 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
9915 as @var{A1}. (As a GNU extension, arguments of different kinds are
9919 @item @emph{Return value}:
9920 The return value corresponds to the maximum value among the arguments,
9921 and has the same type and kind as the first argument.
9923 @item @emph{Specific names}:
9924 @multitable @columnfractions .20 .20 .20 .25
9925 @item Name @tab Argument @tab Return type @tab Standard
9926 @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
9927 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
9928 @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
9929 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
9930 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
9933 @item @emph{See also}:
9934 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
9941 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
9942 @fnindex MAXEXPONENT
9943 @cindex model representation, maximum exponent
9946 @item @emph{Description}:
9947 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
9950 @item @emph{Standard}:
9951 Fortran 95 and later
9956 @item @emph{Syntax}:
9957 @code{RESULT = MAXEXPONENT(X)}
9959 @item @emph{Arguments}:
9960 @multitable @columnfractions .15 .70
9961 @item @var{X} @tab Shall be of type @code{REAL}.
9964 @item @emph{Return value}:
9965 The return value is of type @code{INTEGER} and of the default integer
9968 @item @emph{Example}:
9974 print *, minexponent(x), maxexponent(x)
9975 print *, minexponent(y), maxexponent(y)
9976 end program exponents
9983 @section @code{MAXLOC} --- Location of the maximum value within an array
9985 @cindex array, location of maximum element
9988 @item @emph{Description}:
9989 Determines the location of the element in the array with the maximum
9990 value, or, if the @var{DIM} argument is supplied, determines the
9991 locations of the maximum element along each row of the array in the
9992 @var{DIM} direction. If @var{MASK} is present, only the elements for
9993 which @var{MASK} is @code{.TRUE.} are considered. If more than one
9994 element in the array has the maximum value, the location returned is
9995 that of the first such element in array element order if the
9996 @var{BACK} is not present, or if it false; otherwise, the location
9997 returned is that of the first such element. If the array has zero
9998 size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
9999 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
10000 and all of the elements of @var{MASK} along a given row are zero, the
10001 result value for that row is zero.
10003 @item @emph{Standard}:
10004 Fortran 95 and later; @var{ARRAY} of @code{CHARACTER} and the
10005 @var{KIND} argument are available in Fortran 2003 and later.
10006 The @var{BACK} argument is available in Fortran 2008 and later.
10008 @item @emph{Class}:
10009 Transformational function
10011 @item @emph{Syntax}:
10012 @multitable @columnfractions .80
10013 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK])}
10014 @item @code{RESULT = MAXLOC(ARRAY [, MASK] [,KIND] [,BACK])}
10017 @item @emph{Arguments}:
10018 @multitable @columnfractions .15 .70
10019 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10021 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10022 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10023 inclusive. It may not be an optional dummy argument.
10024 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
10025 and conformable with @var{ARRAY}.
10026 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10027 expression indicating the kind parameter of the result.
10028 @item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}.
10031 @item @emph{Return value}:
10032 If @var{DIM} is absent, the result is a rank-one array with a length
10033 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
10034 is an array with a rank one less than the rank of @var{ARRAY}, and a
10035 size corresponding to the size of @var{ARRAY} with the @var{DIM}
10036 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
10037 of one, the result is a scalar. If the optional argument @var{KIND}
10038 is present, the result is an integer of kind @var{KIND}, otherwise it
10039 is of default kind.
10041 @item @emph{See also}:
10042 @ref{MAX}, @ref{MAXVAL}
10049 @section @code{MAXVAL} --- Maximum value of an array
10051 @cindex array, maximum value
10052 @cindex maximum value
10055 @item @emph{Description}:
10056 Determines the maximum value of the elements in an array value, or, if
10057 the @var{DIM} argument is supplied, determines the maximum value along
10058 each row of the array in the @var{DIM} direction. If @var{MASK} is
10059 present, only the elements for which @var{MASK} is @code{.TRUE.} are
10060 considered. If the array has zero size, or all of the elements of
10061 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
10062 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
10065 @item @emph{Standard}:
10066 Fortran 95 and later
10068 @item @emph{Class}:
10069 Transformational function
10071 @item @emph{Syntax}:
10072 @multitable @columnfractions .80
10073 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
10074 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
10077 @item @emph{Arguments}:
10078 @multitable @columnfractions .15 .70
10079 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10081 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10082 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10083 inclusive. It may not be an optional dummy argument.
10084 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
10085 and conformable with @var{ARRAY}.
10088 @item @emph{Return value}:
10089 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
10090 is a scalar. If @var{DIM} is present, the result is an array with a
10091 rank one less than the rank of @var{ARRAY}, and a size corresponding to
10092 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
10093 cases, the result is of the same type and kind as @var{ARRAY}.
10095 @item @emph{See also}:
10096 @ref{MAX}, @ref{MAXLOC}
10102 @section @code{MCLOCK} --- Time function
10104 @cindex time, clock ticks
10105 @cindex clock ticks
10108 @item @emph{Description}:
10109 Returns the number of clock ticks since the start of the process, based
10110 on the function @code{clock(3)} in the C standard library.
10112 This intrinsic is not fully portable, such as to systems with 32-bit
10113 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
10114 the values returned by this intrinsic might be, or become, negative, or
10115 numerically less than previous values, during a single run of the
10118 @item @emph{Standard}:
10121 @item @emph{Class}:
10124 @item @emph{Syntax}:
10125 @code{RESULT = MCLOCK()}
10127 @item @emph{Return value}:
10128 The return value is a scalar of type @code{INTEGER(4)}, equal to the
10129 number of clock ticks since the start of the process, or @code{-1} if
10130 the system does not support @code{clock(3)}.
10132 @item @emph{See also}:
10133 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
10140 @section @code{MCLOCK8} --- Time function (64-bit)
10142 @cindex time, clock ticks
10143 @cindex clock ticks
10146 @item @emph{Description}:
10147 Returns the number of clock ticks since the start of the process, based
10148 on the function @code{clock(3)} in the C standard library.
10150 @emph{Warning:} this intrinsic does not increase the range of the timing
10151 values over that returned by @code{clock(3)}. On a system with a 32-bit
10152 @code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though
10153 it is converted to a 64-bit @code{INTEGER(8)} value. That means
10154 overflows of the 32-bit value can still occur. Therefore, the values
10155 returned by this intrinsic might be or become negative or numerically
10156 less than previous values during a single run of the compiled program.
10158 @item @emph{Standard}:
10161 @item @emph{Class}:
10164 @item @emph{Syntax}:
10165 @code{RESULT = MCLOCK8()}
10167 @item @emph{Return value}:
10168 The return value is a scalar of type @code{INTEGER(8)}, equal to the
10169 number of clock ticks since the start of the process, or @code{-1} if
10170 the system does not support @code{clock(3)}.
10172 @item @emph{See also}:
10173 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
10180 @section @code{MERGE} --- Merge variables
10182 @cindex array, merge arrays
10183 @cindex array, combine arrays
10186 @item @emph{Description}:
10187 Select values from two arrays according to a logical mask. The result
10188 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
10189 @var{FSOURCE} if it is @code{.FALSE.}.
10191 @item @emph{Standard}:
10192 Fortran 95 and later
10194 @item @emph{Class}:
10197 @item @emph{Syntax}:
10198 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
10200 @item @emph{Arguments}:
10201 @multitable @columnfractions .15 .70
10202 @item @var{TSOURCE} @tab May be of any type.
10203 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
10205 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
10208 @item @emph{Return value}:
10209 The result is of the same type and type parameters as @var{TSOURCE}.
10216 @section @code{MERGE_BITS} --- Merge of bits under mask
10217 @fnindex MERGE_BITS
10218 @cindex bits, merge
10221 @item @emph{Description}:
10222 @code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
10223 as determined by the mask. The i-th bit of the result is equal to the
10224 i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
10225 the i-th bit of @var{J} otherwise.
10227 @item @emph{Standard}:
10228 Fortran 2008 and later
10230 @item @emph{Class}:
10233 @item @emph{Syntax}:
10234 @code{RESULT = MERGE_BITS(I, J, MASK)}
10236 @item @emph{Arguments}:
10237 @multitable @columnfractions .15 .70
10238 @item @var{I} @tab Shall be of type @code{INTEGER}.
10239 @item @var{J} @tab Shall be of type @code{INTEGER} and of the same
10241 @item @var{MASK} @tab Shall be of type @code{INTEGER} and of the same
10245 @item @emph{Return value}:
10246 The result is of the same type and kind as @var{I}.
10253 @section @code{MIN} --- Minimum value of an argument list
10260 @cindex minimum value
10263 @item @emph{Description}:
10264 Returns the argument with the smallest (most negative) value.
10266 @item @emph{Standard}:
10267 Fortran 77 and later
10269 @item @emph{Class}:
10272 @item @emph{Syntax}:
10273 @code{RESULT = MIN(A1, A2 [, A3, ...])}
10275 @item @emph{Arguments}:
10276 @multitable @columnfractions .15 .70
10277 @item @var{A1} @tab The type shall be @code{INTEGER} or
10279 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
10280 as @var{A1}. (As a GNU extension, arguments of different kinds are
10284 @item @emph{Return value}:
10285 The return value corresponds to the maximum value among the arguments,
10286 and has the same type and kind as the first argument.
10288 @item @emph{Specific names}:
10289 @multitable @columnfractions .20 .20 .20 .25
10290 @item Name @tab Argument @tab Return type @tab Standard
10291 @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
10292 @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
10293 @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
10294 @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
10295 @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
10298 @item @emph{See also}:
10299 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
10305 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
10306 @fnindex MINEXPONENT
10307 @cindex model representation, minimum exponent
10310 @item @emph{Description}:
10311 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
10314 @item @emph{Standard}:
10315 Fortran 95 and later
10317 @item @emph{Class}:
10320 @item @emph{Syntax}:
10321 @code{RESULT = MINEXPONENT(X)}
10323 @item @emph{Arguments}:
10324 @multitable @columnfractions .15 .70
10325 @item @var{X} @tab Shall be of type @code{REAL}.
10328 @item @emph{Return value}:
10329 The return value is of type @code{INTEGER} and of the default integer
10332 @item @emph{Example}:
10333 See @code{MAXEXPONENT} for an example.
10339 @section @code{MINLOC} --- Location of the minimum value within an array
10341 @cindex array, location of minimum element
10344 @item @emph{Description}:
10345 Determines the location of the element in the array with the minimum
10346 value, or, if the @var{DIM} argument is supplied, determines the
10347 locations of the minimum element along each row of the array in the
10348 @var{DIM} direction. If @var{MASK} is present, only the elements for
10349 which @var{MASK} is @code{.TRUE.} are considered. If more than one
10350 element in the array has the minimum value, the location returned is
10351 that of the first such element in array element order if the
10352 @var{BACK} is not present, or if it false; otherwise, the location
10353 returned is that of the first such element. If the array has
10354 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
10355 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
10356 and all of the elements of @var{MASK} along a given row are zero, the
10357 result value for that row is zero.
10359 @item @emph{Standard}:
10360 Fortran 95 and later; @var{ARRAY} of @code{CHARACTER} and the
10361 @var{KIND} argument are available in Fortran 2003 and later.
10362 The @var{BACK} argument is available in Fortran 2008 and later.
10364 @item @emph{Class}:
10365 Transformational function
10367 @item @emph{Syntax}:
10368 @multitable @columnfractions .80
10369 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK])}
10370 @item @code{RESULT = MINLOC(ARRAY [, MASK], [,KIND] [,BACK])}
10373 @item @emph{Arguments}:
10374 @multitable @columnfractions .15 .70
10375 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
10376 @code{REAL} or @code{CHARACTER}.
10377 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10378 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10379 inclusive. It may not be an optional dummy argument.
10380 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
10381 and conformable with @var{ARRAY}.
10382 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10383 expression indicating the kind parameter of the result.
10384 @item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}.
10387 @item @emph{Return value}:
10388 If @var{DIM} is absent, the result is a rank-one array with a length
10389 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
10390 is an array with a rank one less than the rank of @var{ARRAY}, and a
10391 size corresponding to the size of @var{ARRAY} with the @var{DIM}
10392 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
10393 of one, the result is a scalar. If the optional argument @var{KIND}
10394 is present, the result is an integer of kind @var{KIND}, otherwise it
10395 is of default kind.
10397 @item @emph{See also}:
10398 @ref{MIN}, @ref{MINVAL}
10405 @section @code{MINVAL} --- Minimum value of an array
10407 @cindex array, minimum value
10408 @cindex minimum value
10411 @item @emph{Description}:
10412 Determines the minimum value of the elements in an array value, or, if
10413 the @var{DIM} argument is supplied, determines the minimum value along
10414 each row of the array in the @var{DIM} direction. If @var{MASK} is
10415 present, only the elements for which @var{MASK} is @code{.TRUE.} are
10416 considered. If the array has zero size, or all of the elements of
10417 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
10418 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
10419 @var{ARRAY} is of character type.
10421 @item @emph{Standard}:
10422 Fortran 95 and later
10424 @item @emph{Class}:
10425 Transformational function
10427 @item @emph{Syntax}:
10428 @multitable @columnfractions .80
10429 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
10430 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
10433 @item @emph{Arguments}:
10434 @multitable @columnfractions .15 .70
10435 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10437 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10438 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10439 inclusive. It may not be an optional dummy argument.
10440 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
10441 and conformable with @var{ARRAY}.
10444 @item @emph{Return value}:
10445 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
10446 is a scalar. If @var{DIM} is present, the result is an array with a
10447 rank one less than the rank of @var{ARRAY}, and a size corresponding to
10448 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
10449 cases, the result is of the same type and kind as @var{ARRAY}.
10451 @item @emph{See also}:
10452 @ref{MIN}, @ref{MINLOC}
10459 @section @code{MOD} --- Remainder function
10468 @cindex division, remainder
10471 @item @emph{Description}:
10472 @code{MOD(A,P)} computes the remainder of the division of A by P@.
10474 @item @emph{Standard}:
10475 Fortran 77 and later, has overloads that are GNU extensions
10477 @item @emph{Class}:
10480 @item @emph{Syntax}:
10481 @code{RESULT = MOD(A, P)}
10483 @item @emph{Arguments}:
10484 @multitable @columnfractions .15 .70
10485 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
10486 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
10487 and not equal to zero.
10490 @item @emph{Return value}:
10491 The return value is the result of @code{A - (INT(A/P) * P)}. The type
10492 and kind of the return value is the same as that of the arguments. The
10493 returned value has the same sign as A and a magnitude less than the
10496 @item @emph{Example}:
10500 print *, mod(17.5,5.5)
10501 print *, mod(17.5d0,5.5)
10502 print *, mod(17.5,5.5d0)
10504 print *, mod(-17,3)
10505 print *, mod(-17.5,5.5)
10506 print *, mod(-17.5d0,5.5)
10507 print *, mod(-17.5,5.5d0)
10509 print *, mod(17,-3)
10510 print *, mod(17.5,-5.5)
10511 print *, mod(17.5d0,-5.5)
10512 print *, mod(17.5,-5.5d0)
10513 end program test_mod
10516 @item @emph{Specific names}:
10517 @multitable @columnfractions .20 .20 .20 .25
10518 @item Name @tab Arguments @tab Return type @tab Standard
10519 @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
10520 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
10521 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
10522 @item @code{BMOD(A,P)} @tab @code{INTEGER(1) A,P} @tab @code{INTEGER(1)} @tab GNU extension
10523 @item @code{IMOD(A,P)} @tab @code{INTEGER(2) A,P} @tab @code{INTEGER(2)} @tab GNU extension
10524 @item @code{JMOD(A,P)} @tab @code{INTEGER(4) A,P} @tab @code{INTEGER(4)} @tab GNU extension
10525 @item @code{KMOD(A,P)} @tab @code{INTEGER(8) A,P} @tab @code{INTEGER(8)} @tab GNU extension
10528 @item @emph{See also}:
10536 @section @code{MODULO} --- Modulo function
10539 @cindex division, modulo
10542 @item @emph{Description}:
10543 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
10545 @item @emph{Standard}:
10546 Fortran 95 and later
10548 @item @emph{Class}:
10551 @item @emph{Syntax}:
10552 @code{RESULT = MODULO(A, P)}
10554 @item @emph{Arguments}:
10555 @multitable @columnfractions .15 .70
10556 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
10557 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}.
10558 It shall not be zero.
10561 @item @emph{Return value}:
10562 The type and kind of the result are those of the arguments.
10564 @item If @var{A} and @var{P} are of type @code{INTEGER}:
10565 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
10566 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
10568 @item If @var{A} and @var{P} are of type @code{REAL}:
10569 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
10571 The returned value has the same sign as P and a magnitude less than
10572 the magnitude of P.
10574 @item @emph{Example}:
10576 program test_modulo
10577 print *, modulo(17,3)
10578 print *, modulo(17.5,5.5)
10580 print *, modulo(-17,3)
10581 print *, modulo(-17.5,5.5)
10583 print *, modulo(17,-3)
10584 print *, modulo(17.5,-5.5)
10588 @item @emph{See also}:
10596 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
10597 @fnindex MOVE_ALLOC
10598 @cindex moving allocation
10599 @cindex allocation, moving
10602 @item @emph{Description}:
10603 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
10604 @var{TO}. @var{FROM} will become deallocated in the process.
10606 @item @emph{Standard}:
10607 Fortran 2003 and later
10609 @item @emph{Class}:
10612 @item @emph{Syntax}:
10613 @code{CALL MOVE_ALLOC(FROM, TO)}
10615 @item @emph{Arguments}:
10616 @multitable @columnfractions .15 .70
10617 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
10618 of any type and kind.
10619 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
10620 of the same type, kind and rank as @var{FROM}.
10623 @item @emph{Return value}:
10626 @item @emph{Example}:
10628 program test_move_alloc
10629 integer, allocatable :: a(:), b(:)
10633 call move_alloc(a, b)
10634 print *, allocated(a), allocated(b)
10636 end program test_move_alloc
10643 @section @code{MVBITS} --- Move bits from one integer to another
10652 @item @emph{Description}:
10653 Moves @var{LEN} bits from positions @var{FROMPOS} through
10654 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
10655 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
10656 affected by the movement of bits is unchanged. The values of
10657 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
10658 @code{BIT_SIZE(FROM)}.
10660 @item @emph{Standard}:
10661 Fortran 95 and later, has overloads that are GNU extensions
10663 @item @emph{Class}:
10664 Elemental subroutine
10666 @item @emph{Syntax}:
10667 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
10669 @item @emph{Arguments}:
10670 @multitable @columnfractions .15 .70
10671 @item @var{FROM} @tab The type shall be @code{INTEGER}.
10672 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
10673 @item @var{LEN} @tab The type shall be @code{INTEGER}.
10674 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
10675 same kind as @var{FROM}.
10676 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
10679 @item @emph{Specific names}:
10680 @multitable @columnfractions .20 .20 .20 .25
10681 @item Name @tab Argument @tab Return type @tab Standard
10682 @item @code{MVBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
10683 @item @code{BMVBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
10684 @item @code{IMVBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
10685 @item @code{JMVBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
10686 @item @code{KMVBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
10689 @item @emph{See also}:
10690 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
10696 @section @code{NEAREST} --- Nearest representable number
10698 @cindex real number, nearest different
10699 @cindex floating point, nearest different
10702 @item @emph{Description}:
10703 @code{NEAREST(X, S)} returns the processor-representable number nearest
10704 to @code{X} in the direction indicated by the sign of @code{S}.
10706 @item @emph{Standard}:
10707 Fortran 95 and later
10709 @item @emph{Class}:
10712 @item @emph{Syntax}:
10713 @code{RESULT = NEAREST(X, S)}
10715 @item @emph{Arguments}:
10716 @multitable @columnfractions .15 .70
10717 @item @var{X} @tab Shall be of type @code{REAL}.
10718 @item @var{S} @tab Shall be of type @code{REAL} and
10722 @item @emph{Return value}:
10723 The return value is of the same type as @code{X}. If @code{S} is
10724 positive, @code{NEAREST} returns the processor-representable number
10725 greater than @code{X} and nearest to it. If @code{S} is negative,
10726 @code{NEAREST} returns the processor-representable number smaller than
10727 @code{X} and nearest to it.
10729 @item @emph{Example}:
10731 program test_nearest
10733 x = nearest(42.0, 1.0)
10734 y = nearest(42.0, -1.0)
10735 write (*,"(3(G20.15))") x, y, x - y
10736 end program test_nearest
10743 @section @code{NEW_LINE} --- New line character
10746 @cindex output, newline
10749 @item @emph{Description}:
10750 @code{NEW_LINE(C)} returns the new-line character.
10752 @item @emph{Standard}:
10753 Fortran 2003 and later
10755 @item @emph{Class}:
10758 @item @emph{Syntax}:
10759 @code{RESULT = NEW_LINE(C)}
10761 @item @emph{Arguments}:
10762 @multitable @columnfractions .15 .70
10763 @item @var{C} @tab The argument shall be a scalar or array of the
10764 type @code{CHARACTER}.
10767 @item @emph{Return value}:
10768 Returns a @var{CHARACTER} scalar of length one with the new-line character of
10769 the same kind as parameter @var{C}.
10771 @item @emph{Example}:
10775 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
10776 end program newline
10783 @section @code{NINT} --- Nearest whole number
10786 @cindex rounding, nearest whole number
10789 @item @emph{Description}:
10790 @code{NINT(A)} rounds its argument to the nearest whole number.
10792 @item @emph{Standard}:
10793 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
10795 @item @emph{Class}:
10798 @item @emph{Syntax}:
10799 @code{RESULT = NINT(A [, KIND])}
10801 @item @emph{Arguments}:
10802 @multitable @columnfractions .15 .70
10803 @item @var{A} @tab The type of the argument shall be @code{REAL}.
10804 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10805 expression indicating the kind parameter of the result.
10808 @item @emph{Return value}:
10809 Returns @var{A} with the fractional portion of its magnitude eliminated by
10810 rounding to the nearest whole number and with its sign preserved,
10811 converted to an @code{INTEGER} of the default kind.
10813 @item @emph{Example}:
10820 print *, nint(x4), idnint(x8)
10821 end program test_nint
10824 @item @emph{Specific names}:
10825 @multitable @columnfractions .20 .20 .20 .25
10826 @item Name @tab Argument @tab Return Type @tab Standard
10827 @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later
10828 @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later
10831 @item @emph{See also}:
10832 @ref{CEILING}, @ref{FLOOR}
10839 @section @code{NORM2} --- Euclidean vector norms
10841 @cindex Euclidean vector norm
10842 @cindex L2 vector norm
10843 @cindex norm, Euclidean
10846 @item @emph{Description}:
10847 Calculates the Euclidean vector norm (@math{L_2} norm) of
10848 of @var{ARRAY} along dimension @var{DIM}.
10850 @item @emph{Standard}:
10851 Fortran 2008 and later
10853 @item @emph{Class}:
10854 Transformational function
10856 @item @emph{Syntax}:
10857 @multitable @columnfractions .80
10858 @item @code{RESULT = NORM2(ARRAY[, DIM])}
10861 @item @emph{Arguments}:
10862 @multitable @columnfractions .15 .70
10863 @item @var{ARRAY} @tab Shall be an array of type @code{REAL}
10864 @item @var{DIM} @tab (Optional) shall be a scalar of type
10865 @code{INTEGER} with a value in the range from 1 to n, where n
10866 equals the rank of @var{ARRAY}.
10869 @item @emph{Return value}:
10870 The result is of the same type as @var{ARRAY}.
10872 If @var{DIM} is absent, a scalar with the square root of the sum of all
10873 elements in @var{ARRAY} squared is returned. Otherwise, an array of
10874 rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
10875 shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
10878 @item @emph{Example}:
10881 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
10882 print *, NORM2(x) ! = sqrt(55.) ~ 7.416
10890 @section @code{NOT} --- Logical negation
10896 @cindex bits, negate
10897 @cindex bitwise logical not
10898 @cindex logical not, bitwise
10901 @item @emph{Description}:
10902 @code{NOT} returns the bitwise Boolean inverse of @var{I}.
10904 @item @emph{Standard}:
10905 Fortran 95 and later, has overloads that are GNU extensions
10907 @item @emph{Class}:
10910 @item @emph{Syntax}:
10911 @code{RESULT = NOT(I)}
10913 @item @emph{Arguments}:
10914 @multitable @columnfractions .15 .70
10915 @item @var{I} @tab The type shall be @code{INTEGER}.
10918 @item @emph{Return value}:
10919 The return type is @code{INTEGER}, of the same kind as the
10922 @item @emph{Specific names}:
10923 @multitable @columnfractions .20 .20 .20 .25
10924 @item Name @tab Argument @tab Return type @tab Standard
10925 @item @code{NOT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
10926 @item @code{BNOT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
10927 @item @code{INOT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
10928 @item @code{JNOT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
10929 @item @code{KNOT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
10932 @item @emph{See also}:
10933 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
10940 @section @code{NULL} --- Function that returns an disassociated pointer
10942 @cindex pointer, status
10943 @cindex pointer, disassociated
10946 @item @emph{Description}:
10947 Returns a disassociated pointer.
10949 If @var{MOLD} is present, a disassociated pointer of the same type is
10950 returned, otherwise the type is determined by context.
10952 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
10953 includes cases where it is required.
10955 @item @emph{Standard}:
10956 Fortran 95 and later
10958 @item @emph{Class}:
10959 Transformational function
10961 @item @emph{Syntax}:
10962 @code{PTR => NULL([MOLD])}
10964 @item @emph{Arguments}:
10965 @multitable @columnfractions .15 .70
10966 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
10967 status and of any type.
10970 @item @emph{Return value}:
10971 A disassociated pointer.
10973 @item @emph{Example}:
10975 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
10978 @item @emph{See also}:
10985 @section @code{NUM_IMAGES} --- Function that returns the number of images
10986 @fnindex NUM_IMAGES
10987 @cindex coarray, @code{NUM_IMAGES}
10988 @cindex images, number of
10991 @item @emph{Description}:
10992 Returns the number of images.
10994 @item @emph{Standard}:
10995 Fortran 2008 and later. With @var{DISTANCE} or @var{FAILED} argument,
10996 Technical Specification (TS) 18508 or later
10999 @item @emph{Class}:
11000 Transformational function
11002 @item @emph{Syntax}:
11003 @code{RESULT = NUM_IMAGES(DISTANCE, FAILED)}
11005 @item @emph{Arguments}:
11006 @multitable @columnfractions .15 .70
11007 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
11008 @item @var{FAILED} @tab (optional, intent(in)) Scalar logical expression
11011 @item @emph{Return value}:
11012 Scalar default-kind integer. If @var{DISTANCE} is not present or has value 0,
11013 the number of images in the current team is returned. For values smaller or
11014 equal distance to the initial team, it returns the number of images index
11015 on the ancestor team which has a distance of @var{DISTANCE} from the invoking
11016 team. If @var{DISTANCE} is larger than the distance to the initial team, the
11017 number of images of the initial team is returned. If @var{FAILED} is not present
11018 the total number of images is returned; if it has the value @code{.TRUE.},
11019 the number of failed images is returned, otherwise, the number of images which
11020 do have not the failed status.
11022 @item @emph{Example}:
11024 INTEGER :: value[*]
11026 value = THIS_IMAGE()
11028 IF (THIS_IMAGE() == 1) THEN
11029 DO i = 1, NUM_IMAGES()
11030 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
11035 @item @emph{See also}:
11036 @ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
11042 @section @code{OR} --- Bitwise logical OR
11044 @cindex bitwise logical or
11045 @cindex logical or, bitwise
11048 @item @emph{Description}:
11049 Bitwise logical @code{OR}.
11051 This intrinsic routine is provided for backwards compatibility with
11052 GNU Fortran 77. For integer arguments, programmers should consider
11053 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
11055 @item @emph{Standard}:
11058 @item @emph{Class}:
11061 @item @emph{Syntax}:
11062 @code{RESULT = OR(I, J)}
11064 @item @emph{Arguments}:
11065 @multitable @columnfractions .15 .70
11066 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
11067 type or a scalar @code{LOGICAL} type.
11068 @item @var{J} @tab The type shall be the same as the type of @var{J}.
11071 @item @emph{Return value}:
11072 The return type is either a scalar @code{INTEGER} or a scalar
11073 @code{LOGICAL}. If the kind type parameters differ, then the
11074 smaller kind type is implicitly converted to larger kind, and the
11075 return has the larger kind.
11077 @item @emph{Example}:
11080 LOGICAL :: T = .TRUE., F = .FALSE.
11082 DATA a / Z'F' /, b / Z'3' /
11084 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
11085 WRITE (*,*) OR(a, b)
11089 @item @emph{See also}:
11090 Fortran 95 elemental function: @ref{IOR}
11096 @section @code{PACK} --- Pack an array into an array of rank one
11098 @cindex array, packing
11099 @cindex array, reduce dimension
11100 @cindex array, gather elements
11103 @item @emph{Description}:
11104 Stores the elements of @var{ARRAY} in an array of rank one.
11106 The beginning of the resulting array is made up of elements whose @var{MASK}
11107 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
11110 @item @emph{Standard}:
11111 Fortran 95 and later
11113 @item @emph{Class}:
11114 Transformational function
11116 @item @emph{Syntax}:
11117 @code{RESULT = PACK(ARRAY, MASK[,VECTOR])}
11119 @item @emph{Arguments}:
11120 @multitable @columnfractions .15 .70
11121 @item @var{ARRAY} @tab Shall be an array of any type.
11122 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
11123 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
11125 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
11126 as @var{ARRAY} and of rank one. If present, the number of elements in
11127 @var{VECTOR} shall be equal to or greater than the number of true elements
11128 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
11129 @var{VECTOR} shall be equal to or greater than the number of elements in
11133 @item @emph{Return value}:
11134 The result is an array of rank one and the same type as that of @var{ARRAY}.
11135 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
11136 number of @code{TRUE} values in @var{MASK} otherwise.
11138 @item @emph{Example}:
11139 Gathering nonzero elements from an array:
11141 PROGRAM test_pack_1
11143 m = (/ 1, 0, 0, 0, 5, 0 /)
11144 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
11148 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
11150 PROGRAM test_pack_2
11152 m = (/ 1, 0, 0, 2 /)
11153 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
11157 @item @emph{See also}:
11164 @section @code{PARITY} --- Reduction with exclusive OR
11167 @cindex Reduction, XOR
11168 @cindex XOR reduction
11171 @item @emph{Description}:
11172 Calculates the parity, i.e. the reduction using @code{.XOR.},
11173 of @var{MASK} along dimension @var{DIM}.
11175 @item @emph{Standard}:
11176 Fortran 2008 and later
11178 @item @emph{Class}:
11179 Transformational function
11181 @item @emph{Syntax}:
11182 @multitable @columnfractions .80
11183 @item @code{RESULT = PARITY(MASK[, DIM])}
11186 @item @emph{Arguments}:
11187 @multitable @columnfractions .15 .70
11188 @item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL}
11189 @item @var{DIM} @tab (Optional) shall be a scalar of type
11190 @code{INTEGER} with a value in the range from 1 to n, where n
11191 equals the rank of @var{MASK}.
11194 @item @emph{Return value}:
11195 The result is of the same type as @var{MASK}.
11197 If @var{DIM} is absent, a scalar with the parity of all elements in
11198 @var{MASK} is returned, i.e. true if an odd number of elements is
11199 @code{.true.} and false otherwise. If @var{DIM} is present, an array
11200 of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
11201 and a shape similar to that of @var{MASK} with dimension @var{DIM}
11202 dropped is returned.
11204 @item @emph{Example}:
11207 LOGICAL :: x(2) = [ .true., .false. ]
11208 print *, PARITY(x) ! prints "T" (true).
11216 @section @code{PERROR} --- Print system error message
11218 @cindex system, error handling
11221 @item @emph{Description}:
11222 Prints (on the C @code{stderr} stream) a newline-terminated error
11223 message corresponding to the last system error. This is prefixed by
11224 @var{STRING}, a colon and a space. See @code{perror(3)}.
11226 @item @emph{Standard}:
11229 @item @emph{Class}:
11232 @item @emph{Syntax}:
11233 @code{CALL PERROR(STRING)}
11235 @item @emph{Arguments}:
11236 @multitable @columnfractions .15 .70
11237 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
11241 @item @emph{See also}:
11248 @section @code{POPCNT} --- Number of bits set
11250 @cindex binary representation
11254 @item @emph{Description}:
11255 @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
11256 representation of @code{I}.
11258 @item @emph{Standard}:
11259 Fortran 2008 and later
11261 @item @emph{Class}:
11264 @item @emph{Syntax}:
11265 @code{RESULT = POPCNT(I)}
11267 @item @emph{Arguments}:
11268 @multitable @columnfractions .15 .70
11269 @item @var{I} @tab Shall be of type @code{INTEGER}.
11272 @item @emph{Return value}:
11273 The return value is of type @code{INTEGER} and of the default integer
11276 @item @emph{See also}:
11277 @ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ}
11279 @item @emph{Example}:
11281 program test_population
11282 print *, popcnt(127), poppar(127)
11283 print *, popcnt(huge(0_4)), poppar(huge(0_4))
11284 print *, popcnt(huge(0_8)), poppar(huge(0_8))
11285 end program test_population
11291 @section @code{POPPAR} --- Parity of the number of bits set
11293 @cindex binary representation
11297 @item @emph{Description}:
11298 @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
11299 of the number of bits set ('1' bits) in the binary representation of
11300 @code{I}. It is equal to 0 if @code{I} has an even number of bits set,
11301 and 1 for an odd number of '1' bits.
11303 @item @emph{Standard}:
11304 Fortran 2008 and later
11306 @item @emph{Class}:
11309 @item @emph{Syntax}:
11310 @code{RESULT = POPPAR(I)}
11312 @item @emph{Arguments}:
11313 @multitable @columnfractions .15 .70
11314 @item @var{I} @tab Shall be of type @code{INTEGER}.
11317 @item @emph{Return value}:
11318 The return value is of type @code{INTEGER} and of the default integer
11321 @item @emph{See also}:
11322 @ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ}
11324 @item @emph{Example}:
11326 program test_population
11327 print *, popcnt(127), poppar(127)
11328 print *, popcnt(huge(0_4)), poppar(huge(0_4))
11329 print *, popcnt(huge(0_8)), poppar(huge(0_8))
11330 end program test_population
11337 @section @code{PRECISION} --- Decimal precision of a real kind
11339 @cindex model representation, precision
11342 @item @emph{Description}:
11343 @code{PRECISION(X)} returns the decimal precision in the model of the
11346 @item @emph{Standard}:
11347 Fortran 95 and later
11349 @item @emph{Class}:
11352 @item @emph{Syntax}:
11353 @code{RESULT = PRECISION(X)}
11355 @item @emph{Arguments}:
11356 @multitable @columnfractions .15 .70
11357 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
11360 @item @emph{Return value}:
11361 The return value is of type @code{INTEGER} and of the default integer
11364 @item @emph{See also}:
11365 @ref{SELECTED_REAL_KIND}, @ref{RANGE}
11367 @item @emph{Example}:
11369 program prec_and_range
11370 real(kind=4) :: x(2)
11371 complex(kind=8) :: y
11373 print *, precision(x), range(x)
11374 print *, precision(y), range(y)
11375 end program prec_and_range
11382 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
11386 @item @emph{Description}:
11387 Determines whether an optional dummy argument is present.
11389 @item @emph{Standard}:
11390 Fortran 95 and later
11392 @item @emph{Class}:
11395 @item @emph{Syntax}:
11396 @code{RESULT = PRESENT(A)}
11398 @item @emph{Arguments}:
11399 @multitable @columnfractions .15 .70
11400 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
11401 value, or a dummy procedure. It shall be the name of an optional dummy argument
11402 accessible within the current subroutine or function.
11405 @item @emph{Return value}:
11406 Returns either @code{TRUE} if the optional argument @var{A} is present, or
11407 @code{FALSE} otherwise.
11409 @item @emph{Example}:
11411 PROGRAM test_present
11412 WRITE(*,*) f(), f(42) ! "F T"
11414 LOGICAL FUNCTION f(x)
11415 INTEGER, INTENT(IN), OPTIONAL :: x
11425 @section @code{PRODUCT} --- Product of array elements
11427 @cindex array, product
11428 @cindex array, multiply elements
11429 @cindex array, conditionally multiply elements
11430 @cindex multiply array elements
11433 @item @emph{Description}:
11434 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
11435 the corresponding element in @var{MASK} is @code{TRUE}.
11437 @item @emph{Standard}:
11438 Fortran 95 and later
11440 @item @emph{Class}:
11441 Transformational function
11443 @item @emph{Syntax}:
11444 @multitable @columnfractions .80
11445 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
11446 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
11449 @item @emph{Arguments}:
11450 @multitable @columnfractions .15 .70
11451 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
11452 @code{REAL} or @code{COMPLEX}.
11453 @item @var{DIM} @tab (Optional) shall be a scalar of type
11454 @code{INTEGER} with a value in the range from 1 to n, where n
11455 equals the rank of @var{ARRAY}.
11456 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
11457 and either be a scalar or an array of the same shape as @var{ARRAY}.
11460 @item @emph{Return value}:
11461 The result is of the same type as @var{ARRAY}.
11463 If @var{DIM} is absent, a scalar with the product of all elements in
11464 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
11465 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
11466 dimension @var{DIM} dropped is returned.
11469 @item @emph{Example}:
11471 PROGRAM test_product
11472 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
11473 print *, PRODUCT(x) ! all elements, product = 120
11474 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
11478 @item @emph{See also}:
11485 @section @code{RADIX} --- Base of a model number
11487 @cindex model representation, base
11488 @cindex model representation, radix
11491 @item @emph{Description}:
11492 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
11494 @item @emph{Standard}:
11495 Fortran 95 and later
11497 @item @emph{Class}:
11500 @item @emph{Syntax}:
11501 @code{RESULT = RADIX(X)}
11503 @item @emph{Arguments}:
11504 @multitable @columnfractions .15 .70
11505 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
11508 @item @emph{Return value}:
11509 The return value is a scalar of type @code{INTEGER} and of the default
11512 @item @emph{See also}:
11513 @ref{SELECTED_REAL_KIND}
11515 @item @emph{Example}:
11518 print *, "The radix for the default integer kind is", radix(0)
11519 print *, "The radix for the default real kind is", radix(0.0)
11520 end program test_radix
11528 @section @code{RAN} --- Real pseudo-random number
11530 @cindex random number generation
11533 @item @emph{Description}:
11534 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
11535 provided as an alias for @code{RAND}. See @ref{RAND} for complete
11538 @item @emph{Standard}:
11541 @item @emph{Class}:
11544 @item @emph{See also}:
11545 @ref{RAND}, @ref{RANDOM_NUMBER}
11551 @section @code{RAND} --- Real pseudo-random number
11553 @cindex random number generation
11556 @item @emph{Description}:
11557 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
11558 distribution between 0 and 1. If @var{FLAG} is 0, the next number
11559 in the current sequence is returned; if @var{FLAG} is 1, the generator
11560 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
11561 it is used as a new seed with @code{SRAND}.
11563 This intrinsic routine is provided for backwards compatibility with
11564 GNU Fortran 77. It implements a simple modulo generator as provided
11565 by @command{g77}. For new code, one should consider the use of
11566 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
11568 @item @emph{Standard}:
11571 @item @emph{Class}:
11574 @item @emph{Syntax}:
11575 @code{RESULT = RAND(I)}
11577 @item @emph{Arguments}:
11578 @multitable @columnfractions .15 .70
11579 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
11582 @item @emph{Return value}:
11583 The return value is of @code{REAL} type and the default kind.
11585 @item @emph{Example}:
11588 integer,parameter :: seed = 86456
11591 print *, rand(), rand(), rand(), rand()
11592 print *, rand(seed), rand(), rand(), rand()
11593 end program test_rand
11596 @item @emph{See also}:
11597 @ref{SRAND}, @ref{RANDOM_NUMBER}
11603 @section @code{RANDOM_INIT} --- Initialize a pseudo-random number generator
11604 @fnindex RANDOM_INIT
11605 @cindex random number generation, initialization
11608 @item @emph{Description}:
11609 Initializes the state of the pseudorandom number generator used by
11610 @code{RANDOM_NUMBER}.
11612 @item @emph{Standard}:
11615 @item @emph{Class}:
11618 @item @emph{Syntax}:
11619 @code{CALL RANDOM_INIT(REPEATABLE, IMAGE_DISTINCT)}
11621 @item @emph{Arguments}:
11622 @multitable @columnfractions .20 .75
11623 @item @var{REPEATABLE} @tab Shall be a scalar with a @code{LOGICAL} type,
11624 and it is @code{INTENT(IN)}. If it is @code{.true.}, the seed is set to
11625 a processor-dependent value that is the same each time @code{RANDOM_INIT}
11626 is called from the same image. The term ``same image'' means a single
11627 instance of program execution. The sequence of random numbers is different
11628 for repeated execution of the program. If it is @code{.false.}, the seed
11629 is set to a processor-dependent value.
11630 @item @var{IMAGE_DISTINCT} @tab Shall be a scalar with a
11631 @code{LOGICAL} type, and it is @code{INTENT(IN)}. If it is @code{.true.},
11632 the seed is set to a processor-dependent value that is distinct from th
11633 seed set by a call to @code{RANDOM_INIT} in another image. If it is
11634 @code{.false.}, the seed is set value that does depend which image called
11635 @code{RANDOM_INIT}.
11638 @item @emph{Example}:
11640 program test_random_seed
11643 call random_init(.true., .true.)
11644 call random_number(x)
11645 call random_init(.true., .true.)
11646 call random_number(y)
11647 ! x and y are the same sequence
11648 if (any(x /= y)) call abort
11649 end program test_random_seed
11652 @item @emph{See also}:
11653 @ref{RANDOM_NUMBER}, @ref{RANDOM_SEED}
11657 @node RANDOM_NUMBER
11658 @section @code{RANDOM_NUMBER} --- Pseudo-random number
11659 @fnindex RANDOM_NUMBER
11660 @cindex random number generation
11663 @item @emph{Description}:
11664 Returns a single pseudorandom number or an array of pseudorandom numbers
11665 from the uniform distribution over the range @math{ 0 \leq x < 1}.
11667 The runtime-library implements the xorshift1024* random number
11668 generator (RNG). This generator has a period of @math{2^{1024} - 1},
11669 and when using multiple threads up to @math{2^{512}} threads can each
11670 generate @math{2^{512}} random numbers before any aliasing occurs.
11672 Note that in a multi-threaded program (e.g. using OpenMP directives),
11673 each thread will have its own random number state. For details of the
11674 seeding procedure, see the documentation for the @code{RANDOM_SEED}
11678 @item @emph{Standard}:
11679 Fortran 95 and later
11681 @item @emph{Class}:
11684 @item @emph{Syntax}:
11685 @code{RANDOM_NUMBER(HARVEST)}
11687 @item @emph{Arguments}:
11688 @multitable @columnfractions .15 .70
11689 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
11692 @item @emph{Example}:
11694 program test_random_number
11696 CALL RANDOM_NUMBER(r)
11700 @item @emph{See also}:
11701 @ref{RANDOM_SEED}, @ref{RANDOM_INIT}
11707 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
11708 @fnindex RANDOM_SEED
11709 @cindex random number generation, seeding
11710 @cindex seeding a random number generator
11713 @item @emph{Description}:
11714 Restarts or queries the state of the pseudorandom number generator used by
11715 @code{RANDOM_NUMBER}.
11717 If @code{RANDOM_SEED} is called without arguments, it is seeded with
11718 random data retrieved from the operating system.
11720 As an extension to the Fortran standard, the GFortran
11721 @code{RANDOM_NUMBER} supports multiple threads. Each thread in a
11722 multi-threaded program has its own seed. When @code{RANDOM_SEED} is
11723 called either without arguments or with the @var{PUT} argument, the
11724 given seed is copied into a master seed as well as the seed of the
11725 current thread. When a new thread uses @code{RANDOM_NUMBER} for the
11726 first time, the seed is copied from the master seed, and forwarded
11727 @math{N * 2^{512}} steps to guarantee that the random stream does not
11728 alias any other stream in the system, where @var{N} is the number of
11729 threads that have used @code{RANDOM_NUMBER} so far during the program
11732 @item @emph{Standard}:
11733 Fortran 95 and later
11735 @item @emph{Class}:
11738 @item @emph{Syntax}:
11739 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
11741 @item @emph{Arguments}:
11742 @multitable @columnfractions .15 .70
11743 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
11744 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
11745 of the arrays used with the @var{PUT} and @var{GET} arguments.
11746 @item @var{PUT} @tab (Optional) Shall be an array of type default
11747 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
11748 the array must be larger than or equal to the number returned by the
11749 @var{SIZE} argument.
11750 @item @var{GET} @tab (Optional) Shall be an array of type default
11751 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
11752 of the array must be larger than or equal to the number returned by
11753 the @var{SIZE} argument.
11756 @item @emph{Example}:
11758 program test_random_seed
11760 integer, allocatable :: seed(:)
11763 call random_seed(size = n)
11765 call random_seed(get=seed)
11767 end program test_random_seed
11770 @item @emph{See also}:
11771 @ref{RANDOM_NUMBER}, @ref{RANDOM_INIT}
11777 @section @code{RANGE} --- Decimal exponent range
11779 @cindex model representation, range
11782 @item @emph{Description}:
11783 @code{RANGE(X)} returns the decimal exponent range in the model of the
11786 @item @emph{Standard}:
11787 Fortran 95 and later
11789 @item @emph{Class}:
11792 @item @emph{Syntax}:
11793 @code{RESULT = RANGE(X)}
11795 @item @emph{Arguments}:
11796 @multitable @columnfractions .15 .70
11797 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
11801 @item @emph{Return value}:
11802 The return value is of type @code{INTEGER} and of the default integer
11805 @item @emph{See also}:
11806 @ref{SELECTED_REAL_KIND}, @ref{PRECISION}
11808 @item @emph{Example}:
11809 See @code{PRECISION} for an example.
11815 @section @code{RANK} --- Rank of a data object
11820 @item @emph{Description}:
11821 @code{RANK(A)} returns the rank of a scalar or array data object.
11823 @item @emph{Standard}:
11824 Technical Specification (TS) 29113
11826 @item @emph{Class}:
11829 @item @emph{Syntax}:
11830 @code{RESULT = RANK(A)}
11832 @item @emph{Arguments}:
11833 @multitable @columnfractions .15 .70
11834 @item @var{A} @tab can be of any type
11837 @item @emph{Return value}:
11838 The return value is of type @code{INTEGER} and of the default integer
11839 kind. For arrays, their rank is returned; for scalars zero is returned.
11841 @item @emph{Example}:
11845 real, allocatable :: b(:,:)
11847 print *, rank(a), rank(b) ! Prints: 0 2
11848 end program test_rank
11856 @section @code{REAL} --- Convert to real type
11865 @cindex conversion, to real
11866 @cindex complex numbers, real part
11869 @item @emph{Description}:
11870 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
11871 @code{REALPART} function is provided for compatibility with @command{g77},
11872 and its use is strongly discouraged.
11874 @item @emph{Standard}:
11875 Fortran 77 and later
11877 @item @emph{Class}:
11880 @item @emph{Syntax}:
11881 @multitable @columnfractions .80
11882 @item @code{RESULT = REAL(A [, KIND])}
11883 @item @code{RESULT = REALPART(Z)}
11886 @item @emph{Arguments}:
11887 @multitable @columnfractions .15 .70
11888 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
11890 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11891 expression indicating the kind parameter of the result.
11894 @item @emph{Return value}:
11895 These functions return a @code{REAL} variable or array under
11896 the following rules:
11900 @code{REAL(A)} is converted to a default real type if @var{A} is an
11901 integer or real variable.
11903 @code{REAL(A)} is converted to a real type with the kind type parameter
11904 of @var{A} if @var{A} is a complex variable.
11906 @code{REAL(A, KIND)} is converted to a real type with kind type
11907 parameter @var{KIND} if @var{A} is a complex, integer, or real
11911 @item @emph{Example}:
11914 complex :: x = (1.0, 2.0)
11915 print *, real(x), real(x,8), realpart(x)
11916 end program test_real
11919 @item @emph{Specific names}:
11920 @multitable @columnfractions .20 .20 .20 .25
11921 @item Name @tab Argument @tab Return type @tab Standard
11922 @item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later
11923 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension
11924 @item @code{FLOATI(A)} @tab @code{INTEGER(2)} @tab @code{REAL(4)} @tab GNU extension
11925 @item @code{FLOATJ(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab GNU extension
11926 @item @code{FLOATK(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab GNU extension
11927 @item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab Fortran 77 and later
11931 @item @emph{See also}:
11939 @section @code{RENAME} --- Rename a file
11941 @cindex file system, rename file
11944 @item @emph{Description}:
11945 Renames a file from file @var{PATH1} to @var{PATH2}. A null
11946 character (@code{CHAR(0)}) can be used to mark the end of the names in
11947 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
11948 names are ignored. If the @var{STATUS} argument is supplied, it
11949 contains 0 on success or a nonzero error code upon return; see
11952 This intrinsic is provided in both subroutine and function forms;
11953 however, only one form can be used in any given program unit.
11955 @item @emph{Standard}:
11958 @item @emph{Class}:
11959 Subroutine, function
11961 @item @emph{Syntax}:
11962 @multitable @columnfractions .80
11963 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
11964 @item @code{STATUS = RENAME(PATH1, PATH2)}
11967 @item @emph{Arguments}:
11968 @multitable @columnfractions .15 .70
11969 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
11970 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
11971 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11974 @item @emph{See also}:
11982 @section @code{REPEAT} --- Repeated string concatenation
11984 @cindex string, repeat
11985 @cindex string, concatenate
11988 @item @emph{Description}:
11989 Concatenates @var{NCOPIES} copies of a string.
11991 @item @emph{Standard}:
11992 Fortran 95 and later
11994 @item @emph{Class}:
11995 Transformational function
11997 @item @emph{Syntax}:
11998 @code{RESULT = REPEAT(STRING, NCOPIES)}
12000 @item @emph{Arguments}:
12001 @multitable @columnfractions .15 .70
12002 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
12003 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
12006 @item @emph{Return value}:
12007 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
12010 @item @emph{Example}:
12012 program test_repeat
12013 write(*,*) repeat("x", 5) ! "xxxxx"
12021 @section @code{RESHAPE} --- Function to reshape an array
12023 @cindex array, change dimensions
12024 @cindex array, transmogrify
12027 @item @emph{Description}:
12028 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
12029 the new array may be padded with elements from @var{PAD} or permuted
12030 as defined by @var{ORDER}.
12032 @item @emph{Standard}:
12033 Fortran 95 and later
12035 @item @emph{Class}:
12036 Transformational function
12038 @item @emph{Syntax}:
12039 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
12041 @item @emph{Arguments}:
12042 @multitable @columnfractions .15 .70
12043 @item @var{SOURCE} @tab Shall be an array of any type.
12044 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
12045 array of rank one. Its values must be positive or zero.
12046 @item @var{PAD} @tab (Optional) shall be an array of the same
12047 type as @var{SOURCE}.
12048 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
12049 and an array of the same shape as @var{SHAPE}. Its values shall
12050 be a permutation of the numbers from 1 to n, where n is the size of
12051 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
12055 @item @emph{Return value}:
12056 The result is an array of shape @var{SHAPE} with the same type as
12059 @item @emph{Example}:
12061 PROGRAM test_reshape
12062 INTEGER, DIMENSION(4) :: x
12063 WRITE(*,*) SHAPE(x) ! prints "4"
12064 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
12068 @item @emph{See also}:
12075 @section @code{RRSPACING} --- Reciprocal of the relative spacing
12077 @cindex real number, relative spacing
12078 @cindex floating point, relative spacing
12082 @item @emph{Description}:
12083 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
12084 model numbers near @var{X}.
12086 @item @emph{Standard}:
12087 Fortran 95 and later
12089 @item @emph{Class}:
12092 @item @emph{Syntax}:
12093 @code{RESULT = RRSPACING(X)}
12095 @item @emph{Arguments}:
12096 @multitable @columnfractions .15 .70
12097 @item @var{X} @tab Shall be of type @code{REAL}.
12100 @item @emph{Return value}:
12101 The return value is of the same type and kind as @var{X}.
12102 The value returned is equal to
12103 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
12105 @item @emph{See also}:
12112 @section @code{RSHIFT} --- Right shift bits
12114 @cindex bits, shift right
12117 @item @emph{Description}:
12118 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
12119 bits shifted right by @var{SHIFT} places. If the absolute value of
12120 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12121 Bits shifted out from the right end are lost. The fill is arithmetic: the
12122 bits shifted in from the left end are equal to the leftmost bit, which in
12123 two's complement representation is the sign bit.
12125 This function has been superseded by the @code{SHIFTA} intrinsic, which
12126 is standard in Fortran 2008 and later.
12128 @item @emph{Standard}:
12131 @item @emph{Class}:
12134 @item @emph{Syntax}:
12135 @code{RESULT = RSHIFT(I, SHIFT)}
12137 @item @emph{Arguments}:
12138 @multitable @columnfractions .15 .70
12139 @item @var{I} @tab The type shall be @code{INTEGER}.
12140 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12143 @item @emph{Return value}:
12144 The return value is of type @code{INTEGER} and of the same kind as
12147 @item @emph{See also}:
12148 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}, @ref{SHIFTA}, @ref{SHIFTR},
12156 @section @code{SAME_TYPE_AS} --- Query dynamic types for equality
12157 @fnindex SAME_TYPE_AS
12160 @item @emph{Description}:
12161 Query dynamic types for equality.
12163 @item @emph{Standard}:
12164 Fortran 2003 and later
12166 @item @emph{Class}:
12169 @item @emph{Syntax}:
12170 @code{RESULT = SAME_TYPE_AS(A, B)}
12172 @item @emph{Arguments}:
12173 @multitable @columnfractions .15 .70
12174 @item @var{A} @tab Shall be an object of extensible declared type or
12175 unlimited polymorphic.
12176 @item @var{B} @tab Shall be an object of extensible declared type or
12177 unlimited polymorphic.
12180 @item @emph{Return value}:
12181 The return value is a scalar of type default logical. It is true if and
12182 only if the dynamic type of A is the same as the dynamic type of B.
12184 @item @emph{See also}:
12185 @ref{EXTENDS_TYPE_OF}
12192 @section @code{SCALE} --- Scale a real value
12194 @cindex real number, scale
12195 @cindex floating point, scale
12198 @item @emph{Description}:
12199 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
12201 @item @emph{Standard}:
12202 Fortran 95 and later
12204 @item @emph{Class}:
12207 @item @emph{Syntax}:
12208 @code{RESULT = SCALE(X, I)}
12210 @item @emph{Arguments}:
12211 @multitable @columnfractions .15 .70
12212 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
12213 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
12216 @item @emph{Return value}:
12217 The return value is of the same type and kind as @var{X}.
12218 Its value is @code{X * RADIX(X)**I}.
12220 @item @emph{Example}:
12223 real :: x = 178.1387e-4
12225 print *, scale(x,i), x*radix(x)**i
12226 end program test_scale
12234 @section @code{SCAN} --- Scan a string for the presence of a set of characters
12236 @cindex string, find subset
12239 @item @emph{Description}:
12240 Scans a @var{STRING} for any of the characters in a @var{SET}
12243 If @var{BACK} is either absent or equals @code{FALSE}, this function
12244 returns the position of the leftmost character of @var{STRING} that is
12245 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
12246 is returned. If no character of @var{SET} is found in @var{STRING}, the
12249 @item @emph{Standard}:
12250 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12252 @item @emph{Class}:
12255 @item @emph{Syntax}:
12256 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
12258 @item @emph{Arguments}:
12259 @multitable @columnfractions .15 .70
12260 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
12261 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
12262 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
12263 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12264 expression indicating the kind parameter of the result.
12267 @item @emph{Return value}:
12268 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12269 @var{KIND} is absent, the return value is of default integer kind.
12271 @item @emph{Example}:
12274 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
12275 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
12276 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
12280 @item @emph{See also}:
12281 @ref{INDEX intrinsic}, @ref{VERIFY}
12287 @section @code{SECNDS} --- Time function
12289 @cindex time, elapsed
12290 @cindex elapsed time
12293 @item @emph{Description}:
12294 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
12295 @var{X} is a reference time, also in seconds. If this is zero, the time in
12296 seconds from midnight is returned. This function is non-standard and its
12297 use is discouraged.
12299 @item @emph{Standard}:
12302 @item @emph{Class}:
12305 @item @emph{Syntax}:
12306 @code{RESULT = SECNDS (X)}
12308 @item @emph{Arguments}:
12309 @multitable @columnfractions .15 .70
12310 @item @var{T} @tab Shall be of type @code{REAL(4)}.
12311 @item @var{X} @tab Shall be of type @code{REAL(4)}.
12314 @item @emph{Return value}:
12317 @item @emph{Example}:
12319 program test_secnds
12322 print *, secnds (0.0) ! seconds since midnight
12323 t1 = secnds (0.0) ! reference time
12324 do i = 1, 10000000 ! do something
12326 t2 = secnds (t1) ! elapsed time
12327 print *, "Something took ", t2, " seconds."
12328 end program test_secnds
12335 @section @code{SECOND} --- CPU time function
12337 @cindex time, elapsed
12338 @cindex elapsed time
12341 @item @emph{Description}:
12342 Returns a @code{REAL(4)} value representing the elapsed CPU time in
12343 seconds. This provides the same functionality as the standard
12344 @code{CPU_TIME} intrinsic, and is only included for backwards
12347 This intrinsic is provided in both subroutine and function forms;
12348 however, only one form can be used in any given program unit.
12350 @item @emph{Standard}:
12353 @item @emph{Class}:
12354 Subroutine, function
12356 @item @emph{Syntax}:
12357 @multitable @columnfractions .80
12358 @item @code{CALL SECOND(TIME)}
12359 @item @code{TIME = SECOND()}
12362 @item @emph{Arguments}:
12363 @multitable @columnfractions .15 .70
12364 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
12367 @item @emph{Return value}:
12368 In either syntax, @var{TIME} is set to the process's current runtime in
12371 @item @emph{See also}:
12378 @node SELECTED_CHAR_KIND
12379 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
12380 @fnindex SELECTED_CHAR_KIND
12381 @cindex character kind
12382 @cindex kind, character
12385 @item @emph{Description}:
12387 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
12388 set named @var{NAME}, if a character set with such a name is supported,
12389 or @math{-1} otherwise. Currently, supported character sets include
12390 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
12391 (Universal Character Set, UCS-4) which is commonly known as Unicode.
12393 @item @emph{Standard}:
12394 Fortran 2003 and later
12396 @item @emph{Class}:
12397 Transformational function
12399 @item @emph{Syntax}:
12400 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
12402 @item @emph{Arguments}:
12403 @multitable @columnfractions .15 .70
12404 @item @var{NAME} @tab Shall be a scalar and of the default character type.
12407 @item @emph{Example}:
12409 program character_kind
12410 use iso_fortran_env
12412 integer, parameter :: ascii = selected_char_kind ("ascii")
12413 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646')
12415 character(kind=ascii, len=26) :: alphabet
12416 character(kind=ucs4, len=30) :: hello_world
12418 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
12419 hello_world = ucs4_'Hello World and Ni Hao -- ' &
12420 // char (int (z'4F60'), ucs4) &
12421 // char (int (z'597D'), ucs4)
12423 write (*,*) alphabet
12425 open (output_unit, encoding='UTF-8')
12426 write (*,*) trim (hello_world)
12427 end program character_kind
12433 @node SELECTED_INT_KIND
12434 @section @code{SELECTED_INT_KIND} --- Choose integer kind
12435 @fnindex SELECTED_INT_KIND
12436 @cindex integer kind
12437 @cindex kind, integer
12440 @item @emph{Description}:
12441 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
12442 type that can represent all values ranging from @math{-10^R} (exclusive)
12443 to @math{10^R} (exclusive). If there is no integer kind that accommodates
12444 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
12446 @item @emph{Standard}:
12447 Fortran 95 and later
12449 @item @emph{Class}:
12450 Transformational function
12452 @item @emph{Syntax}:
12453 @code{RESULT = SELECTED_INT_KIND(R)}
12455 @item @emph{Arguments}:
12456 @multitable @columnfractions .15 .70
12457 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
12460 @item @emph{Example}:
12462 program large_integers
12463 integer,parameter :: k5 = selected_int_kind(5)
12464 integer,parameter :: k15 = selected_int_kind(15)
12465 integer(kind=k5) :: i5
12466 integer(kind=k15) :: i15
12468 print *, huge(i5), huge(i15)
12470 ! The following inequalities are always true
12471 print *, huge(i5) >= 10_k5**5-1
12472 print *, huge(i15) >= 10_k15**15-1
12473 end program large_integers
12479 @node SELECTED_REAL_KIND
12480 @section @code{SELECTED_REAL_KIND} --- Choose real kind
12481 @fnindex SELECTED_REAL_KIND
12484 @cindex radix, real
12487 @item @emph{Description}:
12488 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
12489 with decimal precision of at least @code{P} digits, exponent range of
12490 at least @code{R}, and with a radix of @code{RADIX}.
12492 @item @emph{Standard}:
12493 Fortran 95 and later, with @code{RADIX} Fortran 2008 or later
12495 @item @emph{Class}:
12496 Transformational function
12498 @item @emph{Syntax}:
12499 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
12501 @item @emph{Arguments}:
12502 @multitable @columnfractions .15 .70
12503 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12504 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12505 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12507 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
12508 be present; since Fortran 2008, they are assumed to be zero if absent.
12510 @item @emph{Return value}:
12512 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
12513 a real data type with decimal precision of at least @code{P} digits, a
12514 decimal exponent range of at least @code{R}, and with the requested
12515 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
12516 any radix can be returned. If more than one real data type meet the
12517 criteria, the kind of the data type with the smallest decimal precision
12518 is returned. If no real data type matches the criteria, the result is
12520 @item -1 if the processor does not support a real data type with a
12521 precision greater than or equal to @code{P}, but the @code{R} and
12522 @code{RADIX} requirements can be fulfilled
12523 @item -2 if the processor does not support a real type with an exponent
12524 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
12526 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
12528 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
12530 @item -5 if there is no real type with the given @code{RADIX}
12533 @item @emph{See also}:
12534 @ref{PRECISION}, @ref{RANGE}, @ref{RADIX}
12536 @item @emph{Example}:
12539 integer,parameter :: p6 = selected_real_kind(6)
12540 integer,parameter :: p10r100 = selected_real_kind(10,100)
12541 integer,parameter :: r400 = selected_real_kind(r=400)
12543 real(kind=p10r100) :: y
12544 real(kind=r400) :: z
12546 print *, precision(x), range(x)
12547 print *, precision(y), range(y)
12548 print *, precision(z), range(z)
12549 end program real_kinds
12556 @section @code{SET_EXPONENT} --- Set the exponent of the model
12557 @fnindex SET_EXPONENT
12558 @cindex real number, set exponent
12559 @cindex floating point, set exponent
12562 @item @emph{Description}:
12563 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
12564 is that that of @var{X} and whose exponent part is @var{I}.
12566 @item @emph{Standard}:
12567 Fortran 95 and later
12569 @item @emph{Class}:
12572 @item @emph{Syntax}:
12573 @code{RESULT = SET_EXPONENT(X, I)}
12575 @item @emph{Arguments}:
12576 @multitable @columnfractions .15 .70
12577 @item @var{X} @tab Shall be of type @code{REAL}.
12578 @item @var{I} @tab Shall be of type @code{INTEGER}.
12581 @item @emph{Return value}:
12582 The return value is of the same type and kind as @var{X}.
12583 The real number whose fractional part
12584 is that that of @var{X} and whose exponent part if @var{I} is returned;
12585 it is @code{FRACTION(X) * RADIX(X)**I}.
12587 @item @emph{Example}:
12589 PROGRAM test_setexp
12590 REAL :: x = 178.1387e-4
12592 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
12601 @section @code{SHAPE} --- Determine the shape of an array
12603 @cindex array, shape
12606 @item @emph{Description}:
12607 Determines the shape of an array.
12609 @item @emph{Standard}:
12610 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12612 @item @emph{Class}:
12615 @item @emph{Syntax}:
12616 @code{RESULT = SHAPE(SOURCE [, KIND])}
12618 @item @emph{Arguments}:
12619 @multitable @columnfractions .15 .70
12620 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
12621 If @var{SOURCE} is a pointer it must be associated and allocatable
12622 arrays must be allocated.
12623 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12624 expression indicating the kind parameter of the result.
12627 @item @emph{Return value}:
12628 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
12629 has dimensions. The elements of the resulting array correspond to the extend
12630 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
12631 the result is the rank one array of size zero. If @var{KIND} is absent, the
12632 return value has the default integer kind otherwise the specified kind.
12634 @item @emph{Example}:
12637 INTEGER, DIMENSION(-1:1, -1:2) :: A
12638 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
12639 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
12643 @item @emph{See also}:
12644 @ref{RESHAPE}, @ref{SIZE}
12650 @section @code{SHIFTA} --- Right shift with fill
12652 @cindex bits, shift right
12653 @cindex shift, right with fill
12656 @item @emph{Description}:
12657 @code{SHIFTA} returns a value corresponding to @var{I} with all of the
12658 bits shifted right by @var{SHIFT} places. If the absolute value of
12659 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12660 Bits shifted out from the right end are lost. The fill is arithmetic: the
12661 bits shifted in from the left end are equal to the leftmost bit, which in
12662 two's complement representation is the sign bit.
12664 @item @emph{Standard}:
12665 Fortran 2008 and later
12667 @item @emph{Class}:
12670 @item @emph{Syntax}:
12671 @code{RESULT = SHIFTA(I, SHIFT)}
12673 @item @emph{Arguments}:
12674 @multitable @columnfractions .15 .70
12675 @item @var{I} @tab The type shall be @code{INTEGER}.
12676 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12679 @item @emph{Return value}:
12680 The return value is of type @code{INTEGER} and of the same kind as
12683 @item @emph{See also}:
12684 @ref{SHIFTL}, @ref{SHIFTR}
12690 @section @code{SHIFTL} --- Left shift
12692 @cindex bits, shift left
12693 @cindex shift, left
12696 @item @emph{Description}:
12697 @code{SHIFTL} returns a value corresponding to @var{I} with all of the
12698 bits shifted left by @var{SHIFT} places. If the absolute value of
12699 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12700 Bits shifted out from the left end are lost, and bits shifted in from
12701 the right end are set to 0.
12703 @item @emph{Standard}:
12704 Fortran 2008 and later
12706 @item @emph{Class}:
12709 @item @emph{Syntax}:
12710 @code{RESULT = SHIFTL(I, SHIFT)}
12712 @item @emph{Arguments}:
12713 @multitable @columnfractions .15 .70
12714 @item @var{I} @tab The type shall be @code{INTEGER}.
12715 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12718 @item @emph{Return value}:
12719 The return value is of type @code{INTEGER} and of the same kind as
12722 @item @emph{See also}:
12723 @ref{SHIFTA}, @ref{SHIFTR}
12729 @section @code{SHIFTR} --- Right shift
12731 @cindex bits, shift right
12732 @cindex shift, right
12735 @item @emph{Description}:
12736 @code{SHIFTR} returns a value corresponding to @var{I} with all of the
12737 bits shifted right by @var{SHIFT} places. If the absolute value of
12738 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12739 Bits shifted out from the right end are lost, and bits shifted in from
12740 the left end are set to 0.
12742 @item @emph{Standard}:
12743 Fortran 2008 and later
12745 @item @emph{Class}:
12748 @item @emph{Syntax}:
12749 @code{RESULT = SHIFTR(I, SHIFT)}
12751 @item @emph{Arguments}:
12752 @multitable @columnfractions .15 .70
12753 @item @var{I} @tab The type shall be @code{INTEGER}.
12754 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12757 @item @emph{Return value}:
12758 The return value is of type @code{INTEGER} and of the same kind as
12761 @item @emph{See also}:
12762 @ref{SHIFTA}, @ref{SHIFTL}
12768 @section @code{SIGN} --- Sign copying function
12772 @cindex sign copying
12775 @item @emph{Description}:
12776 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
12778 @item @emph{Standard}:
12779 Fortran 77 and later
12781 @item @emph{Class}:
12784 @item @emph{Syntax}:
12785 @code{RESULT = SIGN(A, B)}
12787 @item @emph{Arguments}:
12788 @multitable @columnfractions .15 .70
12789 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
12790 @item @var{B} @tab Shall be of the same type and kind as @var{A}
12793 @item @emph{Return value}:
12794 The kind of the return value is that of @var{A} and @var{B}.
12795 If @math{B\ge 0} then the result is @code{ABS(A)}, else
12796 it is @code{-ABS(A)}.
12798 @item @emph{Example}:
12801 print *, sign(-12,1)
12802 print *, sign(-12,0)
12803 print *, sign(-12,-1)
12805 print *, sign(-12.,1.)
12806 print *, sign(-12.,0.)
12807 print *, sign(-12.,-1.)
12808 end program test_sign
12811 @item @emph{Specific names}:
12812 @multitable @columnfractions .20 .20 .20 .25
12813 @item Name @tab Arguments @tab Return type @tab Standard
12814 @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu
12815 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
12816 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu
12823 @section @code{SIGNAL} --- Signal handling subroutine (or function)
12825 @cindex system, signal handling
12828 @item @emph{Description}:
12829 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
12830 @var{HANDLER} to be executed with a single integer argument when signal
12831 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
12832 turn off handling of signal @var{NUMBER} or revert to its default
12833 action. See @code{signal(2)}.
12835 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
12836 is supplied, it is set to the value returned by @code{signal(2)}.
12838 @item @emph{Standard}:
12841 @item @emph{Class}:
12842 Subroutine, function
12844 @item @emph{Syntax}:
12845 @multitable @columnfractions .80
12846 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
12847 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
12850 @item @emph{Arguments}:
12851 @multitable @columnfractions .15 .70
12852 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
12853 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
12854 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
12855 @code{INTEGER}. It is @code{INTENT(IN)}.
12856 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
12857 integer. It has @code{INTENT(OUT)}.
12859 @c TODO: What should the interface of the handler be? Does it take arguments?
12861 @item @emph{Return value}:
12862 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
12864 @item @emph{Example}:
12866 program test_signal
12868 external handler_print
12870 call signal (12, handler_print)
12871 call signal (10, 1)
12874 end program test_signal
12881 @section @code{SIN} --- Sine function
12887 @cindex trigonometric function, sine
12891 @item @emph{Description}:
12892 @code{SIN(X)} computes the sine of @var{X}.
12894 @item @emph{Standard}:
12895 Fortran 77 and later
12897 @item @emph{Class}:
12900 @item @emph{Syntax}:
12901 @code{RESULT = SIN(X)}
12903 @item @emph{Arguments}:
12904 @multitable @columnfractions .15 .70
12905 @item @var{X} @tab The type shall be @code{REAL} or
12909 @item @emph{Return value}:
12910 The return value has same type and kind as @var{X}.
12912 @item @emph{Example}:
12917 end program test_sin
12920 @item @emph{Specific names}:
12921 @multitable @columnfractions .20 .20 .20 .25
12922 @item Name @tab Argument @tab Return type @tab Standard
12923 @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu
12924 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
12925 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
12926 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
12927 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
12930 @item @emph{See also}:
12931 Inverse function: @ref{ASIN}
12932 Degrees function: @ref{SIND}
12938 @section @code{SIND} --- Sine function, degrees
12944 @cindex trigonometric function, sine, degrees
12945 @cindex sine, degrees
12948 @item @emph{Description}:
12949 @code{SIND(X)} computes the sine of @var{X} in degrees.
12951 This function is for compatibility only and should be avoided in favor of
12952 standard constructs wherever possible.
12954 @item @emph{Standard}:
12955 GNU Extension, enabled with @option{-fdec-math}.
12957 @item @emph{Class}:
12960 @item @emph{Syntax}:
12961 @code{RESULT = SIND(X)}
12963 @item @emph{Arguments}:
12964 @multitable @columnfractions .15 .70
12965 @item @var{X} @tab The type shall be @code{REAL} or
12969 @item @emph{Return value}:
12970 The return value has same type and kind as @var{X}, and its value is in degrees.
12972 @item @emph{Example}:
12977 end program test_sind
12980 @item @emph{Specific names}:
12981 @multitable @columnfractions .20 .20 .20 .25
12982 @item Name @tab Argument @tab Return type @tab Standard
12983 @item @code{SIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
12984 @item @code{DSIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
12985 @item @code{CSIND(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU Extension
12986 @item @code{ZSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU Extension
12987 @item @code{CDSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU Extension
12990 @item @emph{See also}:
12991 Inverse function: @ref{ASIND}
12992 Radians function: @ref{SIN}
12999 @section @code{SINH} --- Hyperbolic sine function
13002 @cindex hyperbolic sine
13003 @cindex hyperbolic function, sine
13004 @cindex sine, hyperbolic
13007 @item @emph{Description}:
13008 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
13010 @item @emph{Standard}:
13011 Fortran 95 and later, for a complex argument Fortran 2008 or later
13013 @item @emph{Class}:
13016 @item @emph{Syntax}:
13017 @code{RESULT = SINH(X)}
13019 @item @emph{Arguments}:
13020 @multitable @columnfractions .15 .70
13021 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13024 @item @emph{Return value}:
13025 The return value has same type and kind as @var{X}.
13027 @item @emph{Example}:
13030 real(8) :: x = - 1.0_8
13032 end program test_sinh
13035 @item @emph{Specific names}:
13036 @multitable @columnfractions .20 .20 .20 .25
13037 @item Name @tab Argument @tab Return type @tab Standard
13038 @item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
13039 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
13042 @item @emph{See also}:
13049 @section @code{SIZE} --- Determine the size of an array
13051 @cindex array, size
13052 @cindex array, number of elements
13053 @cindex array, count elements
13056 @item @emph{Description}:
13057 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
13058 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
13060 @item @emph{Standard}:
13061 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
13063 @item @emph{Class}:
13066 @item @emph{Syntax}:
13067 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
13069 @item @emph{Arguments}:
13070 @multitable @columnfractions .15 .70
13071 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
13072 a pointer it must be associated and allocatable arrays must be allocated.
13073 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
13074 and its value shall be in the range from 1 to n, where n equals the rank
13076 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
13077 expression indicating the kind parameter of the result.
13080 @item @emph{Return value}:
13081 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
13082 @var{KIND} is absent, the return value is of default integer kind.
13084 @item @emph{Example}:
13087 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
13091 @item @emph{See also}:
13092 @ref{SHAPE}, @ref{RESHAPE}
13097 @section @code{SIZEOF} --- Size in bytes of an expression
13099 @cindex expression size
13100 @cindex size of an expression
13103 @item @emph{Description}:
13104 @code{SIZEOF(X)} calculates the number of bytes of storage the
13105 expression @code{X} occupies.
13107 @item @emph{Standard}:
13110 @item @emph{Class}:
13113 @item @emph{Syntax}:
13114 @code{N = SIZEOF(X)}
13116 @item @emph{Arguments}:
13117 @multitable @columnfractions .15 .70
13118 @item @var{X} @tab The argument shall be of any type, rank or shape.
13121 @item @emph{Return value}:
13122 The return value is of type integer and of the system-dependent kind
13123 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
13124 number of bytes occupied by the argument. If the argument has the
13125 @code{POINTER} attribute, the number of bytes of the storage area pointed
13126 to is returned. If the argument is of a derived type with @code{POINTER}
13127 or @code{ALLOCATABLE} components, the return value does not account for
13128 the sizes of the data pointed to by these components. If the argument is
13129 polymorphic, the size according to the dynamic type is returned. The argument
13130 may not be a procedure or procedure pointer. Note that the code assumes for
13131 arrays that those are contiguous; for contiguous arrays, it returns the
13132 storage or an array element multiplied by the size of the array.
13134 @item @emph{Example}:
13138 print *, (sizeof(s)/sizeof(r) == 5)
13141 The example will print @code{.TRUE.} unless you are using a platform
13142 where default @code{REAL} variables are unusually padded.
13144 @item @emph{See also}:
13145 @ref{C_SIZEOF}, @ref{STORAGE_SIZE}
13150 @section @code{SLEEP} --- Sleep for the specified number of seconds
13152 @cindex delayed execution
13155 @item @emph{Description}:
13156 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
13158 @item @emph{Standard}:
13161 @item @emph{Class}:
13164 @item @emph{Syntax}:
13165 @code{CALL SLEEP(SECONDS)}
13167 @item @emph{Arguments}:
13168 @multitable @columnfractions .15 .70
13169 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
13172 @item @emph{Example}:
13183 @section @code{SPACING} --- Smallest distance between two numbers of a given type
13185 @cindex real number, relative spacing
13186 @cindex floating point, relative spacing
13189 @item @emph{Description}:
13190 Determines the distance between the argument @var{X} and the nearest
13191 adjacent number of the same type.
13193 @item @emph{Standard}:
13194 Fortran 95 and later
13196 @item @emph{Class}:
13199 @item @emph{Syntax}:
13200 @code{RESULT = SPACING(X)}
13202 @item @emph{Arguments}:
13203 @multitable @columnfractions .15 .70
13204 @item @var{X} @tab Shall be of type @code{REAL}.
13207 @item @emph{Return value}:
13208 The result is of the same type as the input argument @var{X}.
13210 @item @emph{Example}:
13212 PROGRAM test_spacing
13213 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
13214 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
13216 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
13217 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
13221 @item @emph{See also}:
13228 @section @code{SPREAD} --- Add a dimension to an array
13230 @cindex array, increase dimension
13231 @cindex array, duplicate elements
13232 @cindex array, duplicate dimensions
13235 @item @emph{Description}:
13236 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
13237 dimension @var{DIM}.
13239 @item @emph{Standard}:
13240 Fortran 95 and later
13242 @item @emph{Class}:
13243 Transformational function
13245 @item @emph{Syntax}:
13246 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
13248 @item @emph{Arguments}:
13249 @multitable @columnfractions .15 .70
13250 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
13251 a rank less than seven.
13252 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
13253 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
13254 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
13257 @item @emph{Return value}:
13258 The result is an array of the same type as @var{SOURCE} and has rank n+1
13259 where n equals the rank of @var{SOURCE}.
13261 @item @emph{Example}:
13263 PROGRAM test_spread
13264 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
13265 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
13266 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
13270 @item @emph{See also}:
13277 @section @code{SQRT} --- Square-root function
13284 @cindex square-root
13287 @item @emph{Description}:
13288 @code{SQRT(X)} computes the square root of @var{X}.
13290 @item @emph{Standard}:
13291 Fortran 77 and later
13293 @item @emph{Class}:
13296 @item @emph{Syntax}:
13297 @code{RESULT = SQRT(X)}
13299 @item @emph{Arguments}:
13300 @multitable @columnfractions .15 .70
13301 @item @var{X} @tab The type shall be @code{REAL} or
13305 @item @emph{Return value}:
13306 The return value is of type @code{REAL} or @code{COMPLEX}.
13307 The kind type parameter is the same as @var{X}.
13309 @item @emph{Example}:
13312 real(8) :: x = 2.0_8
13313 complex :: z = (1.0, 2.0)
13316 end program test_sqrt
13319 @item @emph{Specific names}:
13320 @multitable @columnfractions .20 .20 .20 .25
13321 @item Name @tab Argument @tab Return type @tab Standard
13322 @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
13323 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
13324 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
13325 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13326 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13333 @section @code{SRAND} --- Reinitialize the random number generator
13335 @cindex random number generation, seeding
13336 @cindex seeding a random number generator
13339 @item @emph{Description}:
13340 @code{SRAND} reinitializes the pseudo-random number generator
13341 called by @code{RAND} and @code{IRAND}. The new seed used by the
13342 generator is specified by the required argument @var{SEED}.
13344 @item @emph{Standard}:
13347 @item @emph{Class}:
13350 @item @emph{Syntax}:
13351 @code{CALL SRAND(SEED)}
13353 @item @emph{Arguments}:
13354 @multitable @columnfractions .15 .70
13355 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
13358 @item @emph{Return value}:
13359 Does not return anything.
13361 @item @emph{Example}:
13362 See @code{RAND} and @code{IRAND} for examples.
13364 @item @emph{Notes}:
13365 The Fortran standard specifies the intrinsic subroutines
13366 @code{RANDOM_SEED} to initialize the pseudo-random number
13367 generator and @code{RANDOM_NUMBER} to generate pseudo-random numbers.
13368 These subroutines should be used in new codes.
13370 Please note that in GNU Fortran, these two sets of intrinsics (@code{RAND},
13371 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
13372 @code{RANDOM_SEED} on the other hand) access two independent
13373 pseudo-random number generators.
13375 @item @emph{See also}:
13376 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
13383 @section @code{STAT} --- Get file status
13385 @cindex file system, file status
13388 @item @emph{Description}:
13389 This function returns information about a file. No permissions are required on
13390 the file itself, but execute (search) permission is required on all of the
13391 directories in path that lead to the file.
13393 The elements that are obtained and stored in the array @code{VALUES}:
13394 @multitable @columnfractions .15 .70
13395 @item @code{VALUES(1)} @tab Device ID
13396 @item @code{VALUES(2)} @tab Inode number
13397 @item @code{VALUES(3)} @tab File mode
13398 @item @code{VALUES(4)} @tab Number of links
13399 @item @code{VALUES(5)} @tab Owner's uid
13400 @item @code{VALUES(6)} @tab Owner's gid
13401 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
13402 @item @code{VALUES(8)} @tab File size (bytes)
13403 @item @code{VALUES(9)} @tab Last access time
13404 @item @code{VALUES(10)} @tab Last modification time
13405 @item @code{VALUES(11)} @tab Last file status change time
13406 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
13407 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
13410 Not all these elements are relevant on all systems.
13411 If an element is not relevant, it is returned as 0.
13413 This intrinsic is provided in both subroutine and function forms; however,
13414 only one form can be used in any given program unit.
13416 @item @emph{Standard}:
13419 @item @emph{Class}:
13420 Subroutine, function
13422 @item @emph{Syntax}:
13423 @multitable @columnfractions .80
13424 @item @code{CALL STAT(NAME, VALUES [, STATUS])}
13425 @item @code{STATUS = STAT(NAME, VALUES)}
13428 @item @emph{Arguments}:
13429 @multitable @columnfractions .15 .70
13430 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
13431 default kind and a valid path within the file system.
13432 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
13433 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
13434 on success and a system specific error code otherwise.
13437 @item @emph{Example}:
13440 INTEGER, DIMENSION(13) :: buff
13443 CALL STAT("/etc/passwd", buff, status)
13445 IF (status == 0) THEN
13446 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
13447 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
13448 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
13449 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
13450 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
13451 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
13452 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
13453 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
13454 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
13455 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
13456 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
13457 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
13458 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
13463 @item @emph{See also}:
13464 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
13470 @section @code{STORAGE_SIZE} --- Storage size in bits
13471 @fnindex STORAGE_SIZE
13472 @cindex storage size
13475 @item @emph{Description}:
13476 Returns the storage size of argument @var{A} in bits.
13477 @item @emph{Standard}:
13478 Fortran 2008 and later
13479 @item @emph{Class}:
13481 @item @emph{Syntax}:
13482 @code{RESULT = STORAGE_SIZE(A [, KIND])}
13484 @item @emph{Arguments}:
13485 @multitable @columnfractions .15 .70
13486 @item @var{A} @tab Shall be a scalar or array of any type.
13487 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
13490 @item @emph{Return Value}:
13491 The result is a scalar integer with the kind type parameter specified by KIND
13492 (or default integer type if KIND is missing). The result value is the size
13493 expressed in bits for an element of an array that has the dynamic type and type
13496 @item @emph{See also}:
13497 @ref{C_SIZEOF}, @ref{SIZEOF}
13503 @section @code{SUM} --- Sum of array elements
13506 @cindex array, add elements
13507 @cindex array, conditionally add elements
13508 @cindex sum array elements
13511 @item @emph{Description}:
13512 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
13513 the corresponding element in @var{MASK} is @code{TRUE}.
13515 @item @emph{Standard}:
13516 Fortran 95 and later
13518 @item @emph{Class}:
13519 Transformational function
13521 @item @emph{Syntax}:
13522 @multitable @columnfractions .80
13523 @item @code{RESULT = SUM(ARRAY[, MASK])}
13524 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
13527 @item @emph{Arguments}:
13528 @multitable @columnfractions .15 .70
13529 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
13530 @code{REAL} or @code{COMPLEX}.
13531 @item @var{DIM} @tab (Optional) shall be a scalar of type
13532 @code{INTEGER} with a value in the range from 1 to n, where n
13533 equals the rank of @var{ARRAY}.
13534 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
13535 and either be a scalar or an array of the same shape as @var{ARRAY}.
13538 @item @emph{Return value}:
13539 The result is of the same type as @var{ARRAY}.
13541 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
13542 is returned. Otherwise, an array of rank n-1, where n equals the rank of
13543 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
13544 dropped is returned.
13546 @item @emph{Example}:
13549 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
13550 print *, SUM(x) ! all elements, sum = 15
13551 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
13555 @item @emph{See also}:
13562 @section @code{SYMLNK} --- Create a symbolic link
13564 @cindex file system, create link
13565 @cindex file system, soft link
13568 @item @emph{Description}:
13569 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
13570 character (@code{CHAR(0)}) can be used to mark the end of the names in
13571 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
13572 names are ignored. If the @var{STATUS} argument is supplied, it
13573 contains 0 on success or a nonzero error code upon return; see
13574 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
13575 @code{ENOSYS} is returned.
13577 This intrinsic is provided in both subroutine and function forms;
13578 however, only one form can be used in any given program unit.
13580 @item @emph{Standard}:
13583 @item @emph{Class}:
13584 Subroutine, function
13586 @item @emph{Syntax}:
13587 @multitable @columnfractions .80
13588 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
13589 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
13592 @item @emph{Arguments}:
13593 @multitable @columnfractions .15 .70
13594 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
13595 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
13596 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
13599 @item @emph{See also}:
13600 @ref{LINK}, @ref{UNLINK}
13607 @section @code{SYSTEM} --- Execute a shell command
13609 @cindex system, system call
13612 @item @emph{Description}:
13613 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
13614 argument @var{STATUS} is present, it contains the value returned by
13615 @code{system(3)}, which is presumably 0 if the shell command succeeded.
13616 Note that which shell is used to invoke the command is system-dependent
13617 and environment-dependent.
13619 This intrinsic is provided in both subroutine and function forms;
13620 however, only one form can be used in any given program unit.
13622 Note that the @code{system} function need not be thread-safe. It is
13623 the responsibility of the user to ensure that @code{system} is not
13624 called concurrently.
13626 @item @emph{Standard}:
13629 @item @emph{Class}:
13630 Subroutine, function
13632 @item @emph{Syntax}:
13633 @multitable @columnfractions .80
13634 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
13635 @item @code{STATUS = SYSTEM(COMMAND)}
13638 @item @emph{Arguments}:
13639 @multitable @columnfractions .15 .70
13640 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
13641 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
13644 @item @emph{See also}:
13645 @ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
13646 and should considered in new code for future portability.
13652 @section @code{SYSTEM_CLOCK} --- Time function
13653 @fnindex SYSTEM_CLOCK
13654 @cindex time, clock ticks
13655 @cindex clock ticks
13658 @item @emph{Description}:
13659 Determines the @var{COUNT} of a processor clock since an unspecified
13660 time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines
13661 the number of clock ticks per second. If the platform supports a
13662 monotonic clock, that clock is used and can, depending on the platform
13663 clock implementation, provide up to nanosecond resolution. If a
13664 monotonic clock is not available, the implementation falls back to a
13667 @var{COUNT_RATE} is system dependent and can vary depending on the kind of
13668 the arguments. For @var{kind=4} arguments (and smaller integer kinds),
13669 @var{COUNT} represents milliseconds, while for @var{kind=8} arguments (and
13670 larger integer kinds), @var{COUNT} typically represents micro- or
13671 nanoseconds depending on resolution of the underlying platform clock.
13672 @var{COUNT_MAX} usually equals @code{HUGE(COUNT_MAX)}. Note that the
13673 millisecond resolution of the @var{kind=4} version implies that the
13674 @var{COUNT} will wrap around in roughly 25 days. In order to avoid issues
13675 with the wrap around and for more precise timing, please use the
13676 @var{kind=8} version.
13678 If there is no clock, or querying the clock fails, @var{COUNT} is set
13679 to @code{-HUGE(COUNT)}, and @var{COUNT_RATE} and @var{COUNT_MAX} are
13682 When running on a platform using the GNU C library (glibc) version
13683 2.16 or older, or a derivative thereof, the high resolution monotonic
13684 clock is available only when linking with the @var{rt} library. This
13685 can be done explicitly by adding the @code{-lrt} flag when linking the
13686 application, but is also done implicitly when using OpenMP.
13688 On the Windows platform, the version with @var{kind=4} arguments uses
13689 the @code{GetTickCount} function, whereas the @var{kind=8} version
13690 uses @code{QueryPerformanceCounter} and
13691 @code{QueryPerformanceCounterFrequency}. For more information, and
13692 potential caveats, please see the platform documentation.
13694 @item @emph{Standard}:
13695 Fortran 95 and later
13697 @item @emph{Class}:
13700 @item @emph{Syntax}:
13701 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
13703 @item @emph{Arguments}:
13704 @multitable @columnfractions .15 .70
13705 @item @var{COUNT} @tab (Optional) shall be a scalar of type
13706 @code{INTEGER} with @code{INTENT(OUT)}.
13707 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type
13708 @code{INTEGER} or @code{REAL}, with @code{INTENT(OUT)}.
13709 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type
13710 @code{INTEGER} with @code{INTENT(OUT)}.
13713 @item @emph{Example}:
13715 PROGRAM test_system_clock
13716 INTEGER :: count, count_rate, count_max
13717 CALL SYSTEM_CLOCK(count, count_rate, count_max)
13718 WRITE(*,*) count, count_rate, count_max
13722 @item @emph{See also}:
13723 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
13729 @section @code{TAN} --- Tangent function
13732 @cindex trigonometric function, tangent
13736 @item @emph{Description}:
13737 @code{TAN(X)} computes the tangent of @var{X}.
13739 @item @emph{Standard}:
13740 Fortran 77 and later, for a complex argument Fortran 2008 or later
13742 @item @emph{Class}:
13745 @item @emph{Syntax}:
13746 @code{RESULT = TAN(X)}
13748 @item @emph{Arguments}:
13749 @multitable @columnfractions .15 .70
13750 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13753 @item @emph{Return value}:
13754 The return value has same type and kind as @var{X}, and its value is in radians.
13756 @item @emph{Example}:
13759 real(8) :: x = 0.165_8
13761 end program test_tan
13764 @item @emph{Specific names}:
13765 @multitable @columnfractions .20 .20 .20 .25
13766 @item Name @tab Argument @tab Return type @tab Standard
13767 @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
13768 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
13771 @item @emph{See also}:
13772 Inverse function: @ref{ATAN}
13773 Degrees function: @ref{TAND}
13779 @section @code{TAND} --- Tangent function, degrees
13782 @cindex trigonometric function, tangent, degrees
13783 @cindex tangent, degrees
13786 @item @emph{Description}:
13787 @code{TAND(X)} computes the tangent of @var{X} in degrees.
13789 This function is for compatibility only and should be avoided in favor of
13790 standard constructs wherever possible.
13792 @item @emph{Standard}:
13793 GNU Extension, enabled with @option{-fdec-math}.
13795 @item @emph{Class}:
13798 @item @emph{Syntax}:
13799 @code{RESULT = TAND(X)}
13801 @item @emph{Arguments}:
13802 @multitable @columnfractions .15 .70
13803 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13806 @item @emph{Return value}:
13807 The return value has same type and kind as @var{X}, and its value is in degrees.
13809 @item @emph{Example}:
13812 real(8) :: x = 0.165_8
13814 end program test_tand
13817 @item @emph{Specific names}:
13818 @multitable @columnfractions .20 .20 .20 .25
13819 @item Name @tab Argument @tab Return type @tab Standard
13820 @item @code{TAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
13821 @item @code{DTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
13824 @item @emph{See also}:
13825 Inverse function: @ref{ATAND}
13826 Radians function: @ref{TAN}
13832 @section @code{TANH} --- Hyperbolic tangent function
13835 @cindex hyperbolic tangent
13836 @cindex hyperbolic function, tangent
13837 @cindex tangent, hyperbolic
13840 @item @emph{Description}:
13841 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
13843 @item @emph{Standard}:
13844 Fortran 77 and later, for a complex argument Fortran 2008 or later
13846 @item @emph{Class}:
13849 @item @emph{Syntax}:
13852 @item @emph{Arguments}:
13853 @multitable @columnfractions .15 .70
13854 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13857 @item @emph{Return value}:
13858 The return value has same type and kind as @var{X}. If @var{X} is
13859 complex, the imaginary part of the result is in radians. If @var{X}
13860 is @code{REAL}, the return value lies in the range
13861 @math{ - 1 \leq tanh(x) \leq 1 }.
13863 @item @emph{Example}:
13866 real(8) :: x = 2.1_8
13868 end program test_tanh
13871 @item @emph{Specific names}:
13872 @multitable @columnfractions .20 .20 .20 .25
13873 @item Name @tab Argument @tab Return type @tab Standard
13874 @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
13875 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
13878 @item @emph{See also}:
13885 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
13886 @fnindex THIS_IMAGE
13887 @cindex coarray, @code{THIS_IMAGE}
13888 @cindex images, index of this image
13891 @item @emph{Description}:
13892 Returns the cosubscript for this image.
13894 @item @emph{Standard}:
13895 Fortran 2008 and later. With @var{DISTANCE} argument,
13896 Technical Specification (TS) 18508 or later
13898 @item @emph{Class}:
13899 Transformational function
13901 @item @emph{Syntax}:
13902 @multitable @columnfractions .80
13903 @item @code{RESULT = THIS_IMAGE()}
13904 @item @code{RESULT = THIS_IMAGE(DISTANCE)}
13905 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
13908 @item @emph{Arguments}:
13909 @multitable @columnfractions .15 .70
13910 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
13911 (not permitted together with @var{COARRAY}).
13912 @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
13913 present, required).
13914 @item @var{DIM} @tab default integer scalar (optional). If present,
13915 @var{DIM} shall be between one and the corank of @var{COARRAY}.
13919 @item @emph{Return value}:
13920 Default integer. If @var{COARRAY} is not present, it is scalar; if
13921 @var{DISTANCE} is not present or has value 0, its value is the image index on
13922 the invoking image for the current team, for values smaller or equal
13923 distance to the initial team, it returns the image index on the ancestor team
13924 which has a distance of @var{DISTANCE} from the invoking team. If
13925 @var{DISTANCE} is larger than the distance to the initial team, the image
13926 index of the initial team is returned. Otherwise when the @var{COARRAY} is
13927 present, if @var{DIM} is not present, a rank-1 array with corank elements is
13928 returned, containing the cosubscripts for @var{COARRAY} specifying the invoking
13929 image. If @var{DIM} is present, a scalar is returned, with the value of
13930 the @var{DIM} element of @code{THIS_IMAGE(COARRAY)}.
13932 @item @emph{Example}:
13934 INTEGER :: value[*]
13936 value = THIS_IMAGE()
13938 IF (THIS_IMAGE() == 1) THEN
13939 DO i = 1, NUM_IMAGES()
13940 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
13944 ! Check whether the current image is the initial image
13945 IF (THIS_IMAGE(HUGE(1)) /= THIS_IMAGE())
13946 error stop "something is rotten here"
13949 @item @emph{See also}:
13950 @ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
13956 @section @code{TIME} --- Time function
13958 @cindex time, current
13959 @cindex current time
13962 @item @emph{Description}:
13963 Returns the current time encoded as an integer (in the manner of the
13964 function @code{time(3)} in the C standard library). This value is
13965 suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}.
13967 This intrinsic is not fully portable, such as to systems with 32-bit
13968 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
13969 the values returned by this intrinsic might be, or become, negative, or
13970 numerically less than previous values, during a single run of the
13973 See @ref{TIME8}, for information on a similar intrinsic that might be
13974 portable to more GNU Fortran implementations, though to fewer Fortran
13977 @item @emph{Standard}:
13980 @item @emph{Class}:
13983 @item @emph{Syntax}:
13984 @code{RESULT = TIME()}
13986 @item @emph{Return value}:
13987 The return value is a scalar of type @code{INTEGER(4)}.
13989 @item @emph{See also}:
13990 @ref{DATE_AND_TIME}, @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
13997 @section @code{TIME8} --- Time function (64-bit)
13999 @cindex time, current
14000 @cindex current time
14003 @item @emph{Description}:
14004 Returns the current time encoded as an integer (in the manner of the
14005 function @code{time(3)} in the C standard library). This value is
14006 suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}.
14008 @emph{Warning:} this intrinsic does not increase the range of the timing
14009 values over that returned by @code{time(3)}. On a system with a 32-bit
14010 @code{time(3)}, @code{TIME8} will return a 32-bit value, even though
14011 it is converted to a 64-bit @code{INTEGER(8)} value. That means
14012 overflows of the 32-bit value can still occur. Therefore, the values
14013 returned by this intrinsic might be or become negative or numerically
14014 less than previous values during a single run of the compiled program.
14016 @item @emph{Standard}:
14019 @item @emph{Class}:
14022 @item @emph{Syntax}:
14023 @code{RESULT = TIME8()}
14025 @item @emph{Return value}:
14026 The return value is a scalar of type @code{INTEGER(8)}.
14028 @item @emph{See also}:
14029 @ref{DATE_AND_TIME}, @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
14036 @section @code{TINY} --- Smallest positive number of a real kind
14038 @cindex limits, smallest number
14039 @cindex model representation, smallest number
14042 @item @emph{Description}:
14043 @code{TINY(X)} returns the smallest positive (non zero) number
14044 in the model of the type of @code{X}.
14046 @item @emph{Standard}:
14047 Fortran 95 and later
14049 @item @emph{Class}:
14052 @item @emph{Syntax}:
14053 @code{RESULT = TINY(X)}
14055 @item @emph{Arguments}:
14056 @multitable @columnfractions .15 .70
14057 @item @var{X} @tab Shall be of type @code{REAL}.
14060 @item @emph{Return value}:
14061 The return value is of the same type and kind as @var{X}
14063 @item @emph{Example}:
14064 See @code{HUGE} for an example.
14070 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
14075 @item @emph{Description}:
14076 @code{TRAILZ} returns the number of trailing zero bits of an integer.
14078 @item @emph{Standard}:
14079 Fortran 2008 and later
14081 @item @emph{Class}:
14084 @item @emph{Syntax}:
14085 @code{RESULT = TRAILZ(I)}
14087 @item @emph{Arguments}:
14088 @multitable @columnfractions .15 .70
14089 @item @var{I} @tab Shall be of type @code{INTEGER}.
14092 @item @emph{Return value}:
14093 The type of the return value is the default @code{INTEGER}.
14094 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
14096 @item @emph{Example}:
14098 PROGRAM test_trailz
14099 WRITE (*,*) TRAILZ(8) ! prints 3
14103 @item @emph{See also}:
14104 @ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT}
14110 @section @code{TRANSFER} --- Transfer bit patterns
14116 @item @emph{Description}:
14117 Interprets the bitwise representation of @var{SOURCE} in memory as if it
14118 is the representation of a variable or array of the same type and type
14119 parameters as @var{MOLD}.
14121 This is approximately equivalent to the C concept of @emph{casting} one
14124 @item @emph{Standard}:
14125 Fortran 95 and later
14127 @item @emph{Class}:
14128 Transformational function
14130 @item @emph{Syntax}:
14131 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
14133 @item @emph{Arguments}:
14134 @multitable @columnfractions .15 .70
14135 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
14136 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
14137 @item @var{SIZE} @tab (Optional) shall be a scalar of type
14141 @item @emph{Return value}:
14142 The result has the same type as @var{MOLD}, with the bit level
14143 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
14144 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
14145 but @var{MOLD} is an array (of any size or shape), the result is a one-
14146 dimensional array of the minimum length needed to contain the entirety
14147 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
14148 and @var{MOLD} is a scalar, the result is a scalar.
14150 If the bitwise representation of the result is longer than that of
14151 @var{SOURCE}, then the leading bits of the result correspond to those of
14152 @var{SOURCE} and any trailing bits are filled arbitrarily.
14154 When the resulting bit representation does not correspond to a valid
14155 representation of a variable of the same type as @var{MOLD}, the results
14156 are undefined, and subsequent operations on the result cannot be
14157 guaranteed to produce sensible behavior. For example, it is possible to
14158 create @code{LOGICAL} variables for which @code{@var{VAR}} and
14159 @code{.NOT.@var{VAR}} both appear to be true.
14161 @item @emph{Example}:
14163 PROGRAM test_transfer
14164 integer :: x = 2143289344
14165 print *, transfer(x, 1.0) ! prints "NaN" on i686
14173 @section @code{TRANSPOSE} --- Transpose an array of rank two
14175 @cindex array, transpose
14176 @cindex matrix, transpose
14180 @item @emph{Description}:
14181 Transpose an array of rank two. Element (i, j) of the result has the value
14182 @code{MATRIX(j, i)}, for all i, j.
14184 @item @emph{Standard}:
14185 Fortran 95 and later
14187 @item @emph{Class}:
14188 Transformational function
14190 @item @emph{Syntax}:
14191 @code{RESULT = TRANSPOSE(MATRIX)}
14193 @item @emph{Arguments}:
14194 @multitable @columnfractions .15 .70
14195 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
14198 @item @emph{Return value}:
14199 The result has the same type as @var{MATRIX}, and has shape
14200 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
14206 @section @code{TRIM} --- Remove trailing blank characters of a string
14208 @cindex string, remove trailing whitespace
14211 @item @emph{Description}:
14212 Removes trailing blank characters of a string.
14214 @item @emph{Standard}:
14215 Fortran 95 and later
14217 @item @emph{Class}:
14218 Transformational function
14220 @item @emph{Syntax}:
14221 @code{RESULT = TRIM(STRING)}
14223 @item @emph{Arguments}:
14224 @multitable @columnfractions .15 .70
14225 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
14228 @item @emph{Return value}:
14229 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
14230 less the number of trailing blanks.
14232 @item @emph{Example}:
14235 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
14236 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
14240 @item @emph{See also}:
14241 @ref{ADJUSTL}, @ref{ADJUSTR}
14247 @section @code{TTYNAM} --- Get the name of a terminal device.
14249 @cindex system, terminal
14252 @item @emph{Description}:
14253 Get the name of a terminal device. For more information,
14254 see @code{ttyname(3)}.
14256 This intrinsic is provided in both subroutine and function forms;
14257 however, only one form can be used in any given program unit.
14259 @item @emph{Standard}:
14262 @item @emph{Class}:
14263 Subroutine, function
14265 @item @emph{Syntax}:
14266 @multitable @columnfractions .80
14267 @item @code{CALL TTYNAM(UNIT, NAME)}
14268 @item @code{NAME = TTYNAM(UNIT)}
14271 @item @emph{Arguments}:
14272 @multitable @columnfractions .15 .70
14273 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
14274 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
14277 @item @emph{Example}:
14279 PROGRAM test_ttynam
14282 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
14287 @item @emph{See also}:
14294 @section @code{UBOUND} --- Upper dimension bounds of an array
14296 @cindex array, upper bound
14299 @item @emph{Description}:
14300 Returns the upper bounds of an array, or a single upper bound
14301 along the @var{DIM} dimension.
14302 @item @emph{Standard}:
14303 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
14305 @item @emph{Class}:
14308 @item @emph{Syntax}:
14309 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
14311 @item @emph{Arguments}:
14312 @multitable @columnfractions .15 .70
14313 @item @var{ARRAY} @tab Shall be an array, of any type.
14314 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
14315 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
14316 expression indicating the kind parameter of the result.
14319 @item @emph{Return value}:
14320 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14321 @var{KIND} is absent, the return value is of default integer kind.
14322 If @var{DIM} is absent, the result is an array of the upper bounds of
14323 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
14324 corresponding to the upper bound of the array along that dimension. If
14325 @var{ARRAY} is an expression rather than a whole array or array
14326 structure component, or if it has a zero extent along the relevant
14327 dimension, the upper bound is taken to be the number of elements along
14328 the relevant dimension.
14330 @item @emph{See also}:
14331 @ref{LBOUND}, @ref{LCOBOUND}
14337 @section @code{UCOBOUND} --- Upper codimension bounds of an array
14339 @cindex coarray, upper bound
14342 @item @emph{Description}:
14343 Returns the upper cobounds of a coarray, or a single upper cobound
14344 along the @var{DIM} codimension.
14345 @item @emph{Standard}:
14346 Fortran 2008 and later
14348 @item @emph{Class}:
14351 @item @emph{Syntax}:
14352 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
14354 @item @emph{Arguments}:
14355 @multitable @columnfractions .15 .70
14356 @item @var{ARRAY} @tab Shall be an coarray, of any type.
14357 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
14358 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
14359 expression indicating the kind parameter of the result.
14362 @item @emph{Return value}:
14363 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14364 @var{KIND} is absent, the return value is of default integer kind.
14365 If @var{DIM} is absent, the result is an array of the lower cobounds of
14366 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
14367 corresponding to the lower cobound of the array along that codimension.
14369 @item @emph{See also}:
14370 @ref{LCOBOUND}, @ref{LBOUND}
14376 @section @code{UMASK} --- Set the file creation mask
14378 @cindex file system, file creation mask
14381 @item @emph{Description}:
14382 Sets the file creation mask to @var{MASK}. If called as a function, it
14383 returns the old value. If called as a subroutine and argument @var{OLD}
14384 if it is supplied, it is set to the old value. See @code{umask(2)}.
14386 @item @emph{Standard}:
14389 @item @emph{Class}:
14390 Subroutine, function
14392 @item @emph{Syntax}:
14393 @multitable @columnfractions .80
14394 @item @code{CALL UMASK(MASK [, OLD])}
14395 @item @code{OLD = UMASK(MASK)}
14398 @item @emph{Arguments}:
14399 @multitable @columnfractions .15 .70
14400 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
14401 @item @var{OLD} @tab (Optional) Shall be a scalar of type
14410 @section @code{UNLINK} --- Remove a file from the file system
14412 @cindex file system, remove file
14415 @item @emph{Description}:
14416 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
14417 used to mark the end of the name in @var{PATH}; otherwise, trailing
14418 blanks in the file name are ignored. If the @var{STATUS} argument is
14419 supplied, it contains 0 on success or a nonzero error code upon return;
14420 see @code{unlink(2)}.
14422 This intrinsic is provided in both subroutine and function forms;
14423 however, only one form can be used in any given program unit.
14425 @item @emph{Standard}:
14428 @item @emph{Class}:
14429 Subroutine, function
14431 @item @emph{Syntax}:
14432 @multitable @columnfractions .80
14433 @item @code{CALL UNLINK(PATH [, STATUS])}
14434 @item @code{STATUS = UNLINK(PATH)}
14437 @item @emph{Arguments}:
14438 @multitable @columnfractions .15 .70
14439 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
14440 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
14443 @item @emph{See also}:
14444 @ref{LINK}, @ref{SYMLNK}
14450 @section @code{UNPACK} --- Unpack an array of rank one into an array
14452 @cindex array, unpacking
14453 @cindex array, increase dimension
14454 @cindex array, scatter elements
14457 @item @emph{Description}:
14458 Store the elements of @var{VECTOR} in an array of higher rank.
14460 @item @emph{Standard}:
14461 Fortran 95 and later
14463 @item @emph{Class}:
14464 Transformational function
14466 @item @emph{Syntax}:
14467 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
14469 @item @emph{Arguments}:
14470 @multitable @columnfractions .15 .70
14471 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
14472 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
14473 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
14474 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
14475 the same shape as @var{MASK}.
14478 @item @emph{Return value}:
14479 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
14480 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
14482 @item @emph{Example}:
14484 PROGRAM test_unpack
14485 integer :: vector(2) = (/1,1/)
14486 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
14487 integer :: field(2,2) = 0, unity(2,2)
14489 ! result: unity matrix
14490 unity = unpack(vector, reshape(mask, (/2,2/)), field)
14494 @item @emph{See also}:
14495 @ref{PACK}, @ref{SPREAD}
14501 @section @code{VERIFY} --- Scan a string for characters not a given set
14503 @cindex string, find missing set
14506 @item @emph{Description}:
14507 Verifies that all the characters in @var{STRING} belong to the set of
14508 characters in @var{SET}.
14510 If @var{BACK} is either absent or equals @code{FALSE}, this function
14511 returns the position of the leftmost character of @var{STRING} that is
14512 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost
14513 position is returned. If all characters of @var{STRING} are found in
14514 @var{SET}, the result is zero.
14516 @item @emph{Standard}:
14517 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
14519 @item @emph{Class}:
14522 @item @emph{Syntax}:
14523 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
14525 @item @emph{Arguments}:
14526 @multitable @columnfractions .15 .70
14527 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
14528 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
14529 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
14530 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
14531 expression indicating the kind parameter of the result.
14534 @item @emph{Return value}:
14535 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14536 @var{KIND} is absent, the return value is of default integer kind.
14538 @item @emph{Example}:
14540 PROGRAM test_verify
14541 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
14542 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
14543 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
14544 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
14545 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
14549 @item @emph{See also}:
14550 @ref{SCAN}, @ref{INDEX intrinsic}
14556 @section @code{XOR} --- Bitwise logical exclusive OR
14558 @cindex bitwise logical exclusive or
14559 @cindex logical exclusive or, bitwise
14562 @item @emph{Description}:
14563 Bitwise logical exclusive or.
14565 This intrinsic routine is provided for backwards compatibility with
14566 GNU Fortran 77. For integer arguments, programmers should consider
14567 the use of the @ref{IEOR} intrinsic and for logical arguments the
14568 @code{.NEQV.} operator, which are both defined by the Fortran standard.
14570 @item @emph{Standard}:
14573 @item @emph{Class}:
14576 @item @emph{Syntax}:
14577 @code{RESULT = XOR(I, J)}
14579 @item @emph{Arguments}:
14580 @multitable @columnfractions .15 .70
14581 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
14582 type or a scalar @code{LOGICAL} type.
14583 @item @var{J} @tab The type shall be the same as the type of @var{I}.
14586 @item @emph{Return value}:
14587 The return type is either a scalar @code{INTEGER} or a scalar
14588 @code{LOGICAL}. If the kind type parameters differ, then the
14589 smaller kind type is implicitly converted to larger kind, and the
14590 return has the larger kind.
14592 @item @emph{Example}:
14595 LOGICAL :: T = .TRUE., F = .FALSE.
14597 DATA a / Z'F' /, b / Z'3' /
14599 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
14600 WRITE (*,*) XOR(a, b)
14604 @item @emph{See also}:
14605 Fortran 95 elemental function: @ref{IEOR}
14610 @node Intrinsic Modules
14611 @chapter Intrinsic Modules
14612 @cindex intrinsic Modules
14615 * ISO_FORTRAN_ENV::
14618 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
14619 * OpenACC Module OPENACC::
14622 @node ISO_FORTRAN_ENV
14623 @section @code{ISO_FORTRAN_ENV}
14625 @item @emph{Standard}:
14626 Fortran 2003 and later, except when otherwise noted
14629 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
14633 @item @code{ATOMIC_INT_KIND}:
14634 Default-kind integer constant to be used as kind parameter when defining
14635 integer variables used in atomic operations. (Fortran 2008 or later.)
14637 @item @code{ATOMIC_LOGICAL_KIND}:
14638 Default-kind integer constant to be used as kind parameter when defining
14639 logical variables used in atomic operations. (Fortran 2008 or later.)
14641 @item @code{CHARACTER_KINDS}:
14642 Default-kind integer constant array of rank one containing the supported kind
14643 parameters of the @code{CHARACTER} type. (Fortran 2008 or later.)
14645 @item @code{CHARACTER_STORAGE_SIZE}:
14646 Size in bits of the character storage unit.
14648 @item @code{ERROR_UNIT}:
14649 Identifies the preconnected unit used for error reporting.
14651 @item @code{FILE_STORAGE_SIZE}:
14652 Size in bits of the file-storage unit.
14654 @item @code{INPUT_UNIT}:
14655 Identifies the preconnected unit identified by the asterisk
14656 (@code{*}) in @code{READ} statement.
14658 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
14659 Kind type parameters to specify an INTEGER type with a storage
14660 size of 16, 32, and 64 bits. It is negative if a target platform
14661 does not support the particular kind. (Fortran 2008 or later.)
14663 @item @code{INTEGER_KINDS}:
14664 Default-kind integer constant array of rank one containing the supported kind
14665 parameters of the @code{INTEGER} type. (Fortran 2008 or later.)
14667 @item @code{IOSTAT_END}:
14668 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
14669 an input/output statement if an end-of-file condition occurred.
14671 @item @code{IOSTAT_EOR}:
14672 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
14673 an input/output statement if an end-of-record condition occurred.
14675 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
14676 Scalar default-integer constant, used by @code{INQUIRE} for the
14677 @code{IOSTAT=} specifier to denote an that a unit number identifies an
14678 internal unit. (Fortran 2008 or later.)
14680 @item @code{NUMERIC_STORAGE_SIZE}:
14681 The size in bits of the numeric storage unit.
14683 @item @code{LOGICAL_KINDS}:
14684 Default-kind integer constant array of rank one containing the supported kind
14685 parameters of the @code{LOGICAL} type. (Fortran 2008 or later.)
14687 @item @code{OUTPUT_UNIT}:
14688 Identifies the preconnected unit identified by the asterisk
14689 (@code{*}) in @code{WRITE} statement.
14691 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
14692 Kind type parameters to specify a REAL type with a storage
14693 size of 32, 64, and 128 bits. It is negative if a target platform
14694 does not support the particular kind. (Fortran 2008 or later.)
14696 @item @code{REAL_KINDS}:
14697 Default-kind integer constant array of rank one containing the supported kind
14698 parameters of the @code{REAL} type. (Fortran 2008 or later.)
14700 @item @code{STAT_LOCKED}:
14701 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
14702 denote that the lock variable is locked by the executing image. (Fortran 2008
14705 @item @code{STAT_LOCKED_OTHER_IMAGE}:
14706 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
14707 denote that the lock variable is locked by another image. (Fortran 2008 or
14710 @item @code{STAT_STOPPED_IMAGE}:
14711 Positive, scalar default-integer constant used as STAT= return value if the
14712 argument in the statement requires synchronisation with an image, which has
14713 initiated the termination of the execution. (Fortran 2008 or later.)
14715 @item @code{STAT_FAILED_IMAGE}:
14716 Positive, scalar default-integer constant used as STAT= return value if the
14717 argument in the statement requires communication with an image, which has
14718 is in the failed state. (TS 18508 or later.)
14720 @item @code{STAT_UNLOCKED}:
14721 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
14722 denote that the lock variable is unlocked. (Fortran 2008 or later.)
14725 The module provides the following derived type:
14728 @item @code{LOCK_TYPE}:
14729 Derived type with private components to be use with the @code{LOCK} and
14730 @code{UNLOCK} statement. A variable of its type has to be always declared
14731 as coarray and may not appear in a variable-definition context.
14732 (Fortran 2008 or later.)
14735 The module also provides the following intrinsic procedures:
14736 @ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}.
14740 @node ISO_C_BINDING
14741 @section @code{ISO_C_BINDING}
14743 @item @emph{Standard}:
14744 Fortran 2003 and later, GNU extensions
14747 The following intrinsic procedures are provided by the module; their
14748 definition can be found in the section Intrinsic Procedures of this
14752 @item @code{C_ASSOCIATED}
14753 @item @code{C_F_POINTER}
14754 @item @code{C_F_PROCPOINTER}
14755 @item @code{C_FUNLOC}
14757 @item @code{C_SIZEOF}
14759 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
14760 @c don't really know why.
14762 The @code{ISO_C_BINDING} module provides the following named constants of
14763 type default integer, which can be used as KIND type parameters.
14765 In addition to the integer named constants required by the Fortran 2003
14766 standard and @code{C_PTRDIFF_T} of TS 29113, GNU Fortran provides as an
14767 extension named constants for the 128-bit integer types supported by the
14768 C compiler: @code{C_INT128_T, C_INT_LEAST128_T, C_INT_FAST128_T}.
14769 Furthermore, if @code{__float128} is supported in C, the named constants
14770 @code{C_FLOAT128, C_FLOAT128_COMPLEX} are defined.
14772 @multitable @columnfractions .15 .35 .35 .35
14773 @item Fortran Type @tab Named constant @tab C type @tab Extension
14774 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
14775 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
14776 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
14777 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
14778 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
14779 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
14780 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
14781 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
14782 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
14783 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
14784 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
14785 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
14786 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
14787 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
14788 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
14789 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
14790 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
14791 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
14792 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
14793 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
14794 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
14795 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
14796 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
14797 @item @code{INTEGER}@tab @code{C_PTRDIFF_T} @tab @code{ptrdiff_t} @tab TS 29113
14798 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
14799 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
14800 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
14801 @item @code{REAL} @tab @code{C_FLOAT128} @tab @code{__float128} @tab Ext.
14802 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
14803 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
14804 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
14805 @item @code{REAL} @tab @code{C_FLOAT128_COMPLEX} @tab @code{__float128 _Complex} @tab Ext.
14806 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
14807 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
14810 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
14813 @multitable @columnfractions .20 .45 .15
14814 @item Name @tab C definition @tab Value
14815 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
14816 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
14817 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
14818 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
14819 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
14820 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
14821 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
14822 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
14825 Moreover, the following two named constants are defined:
14827 @multitable @columnfractions .20 .80
14828 @item Name @tab Type
14829 @item @code{C_NULL_PTR} @tab @code{C_PTR}
14830 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
14833 Both are equivalent to the value @code{NULL} in C.
14838 @section IEEE modules: @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
14840 @item @emph{Standard}:
14841 Fortran 2003 and later
14844 The @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
14845 intrinsic modules provide support for exceptions and IEEE arithmetic, as
14846 defined in Fortran 2003 and later standards, and the IEC 60559:1989 standard
14847 (@emph{Binary floating-point arithmetic for microprocessor systems}). These
14848 modules are only provided on the following supported platforms:
14851 @item i386 and x86_64 processors
14852 @item platforms which use the GNU C Library (glibc)
14853 @item platforms with support for SysV/386 routines for floating point
14854 interface (including Solaris and BSDs)
14855 @item platforms with the AIX OS
14858 For full compliance with the Fortran standards, code using the
14859 @code{IEEE_EXCEPTIONS} or @code{IEEE_ARITHMETIC} modules should be compiled
14860 with the following options: @code{-fno-unsafe-math-optimizations
14861 -frounding-math -fsignaling-nans}.
14865 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
14866 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
14868 @item @emph{Standard}:
14869 OpenMP Application Program Interface v4.5
14873 The OpenMP Fortran runtime library routines are provided both in
14874 a form of two Fortran 90 modules, named @code{OMP_LIB} and
14875 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
14876 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
14877 in the @ref{Top,,Introduction,libgomp,GNU Offloading and Multi
14878 Processing Runtime Library} manual,
14879 the named constants defined in the modules are listed
14882 For details refer to the actual
14883 @uref{http://www.openmp.org/wp-content/uploads/openmp-4.5.pdf,
14884 OpenMP Application Program Interface v4.5}.
14886 @code{OMP_LIB_KINDS} provides the following scalar default-integer
14890 @item @code{omp_lock_kind}
14891 @item @code{omp_nest_lock_kind}
14892 @item @code{omp_proc_bind_kind}
14893 @item @code{omp_sched_kind}
14896 @code{OMP_LIB} provides the scalar default-integer
14897 named constant @code{openmp_version} with a value of the form
14898 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
14899 of the OpenMP version; for OpenMP v4.5 the value is @code{201511}.
14901 The following scalar integer named constants of the
14902 kind @code{omp_sched_kind}:
14905 @item @code{omp_sched_static}
14906 @item @code{omp_sched_dynamic}
14907 @item @code{omp_sched_guided}
14908 @item @code{omp_sched_auto}
14911 And the following scalar integer named constants of the
14912 kind @code{omp_proc_bind_kind}:
14915 @item @code{omp_proc_bind_false}
14916 @item @code{omp_proc_bind_true}
14917 @item @code{omp_proc_bind_master}
14918 @item @code{omp_proc_bind_close}
14919 @item @code{omp_proc_bind_spread}
14924 @node OpenACC Module OPENACC
14925 @section OpenACC Module @code{OPENACC}
14927 @item @emph{Standard}:
14928 OpenACC Application Programming Interface v2.0
14932 The OpenACC Fortran runtime library routines are provided both in a
14933 form of a Fortran 90 module, named @code{OPENACC}, and in form of a
14934 Fortran @code{include} file named @file{openacc_lib.h}. The
14935 procedures provided by @code{OPENACC} can be found in the
14936 @ref{Top,,Introduction,libgomp,GNU Offloading and Multi Processing
14937 Runtime Library} manual, the named constants defined in the modules
14940 For details refer to the actual
14941 @uref{http://www.openacc.org/,
14942 OpenACC Application Programming Interface v2.0}.
14944 @code{OPENACC} provides the scalar default-integer
14945 named constant @code{openacc_version} with a value of the form
14946 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
14947 of the OpenACC version; for OpenACC v2.0 the value is @code{201306}.