2 Copyright (C) 2005-2023 Free Software Foundation, Inc.
3 This is part of the GNU Fortran manual.
4 For copying conditions, see the file gfortran.texi.
6 Permission is granted to copy, distribute and/or modify this document
7 under the terms of the GNU Free Documentation License, Version 1.3 or
8 any later version published by the Free Software Foundation; with the
9 Invariant Sections being ``Funding Free Software'', the Front-Cover
10 Texts being (a) (see below), and with the Back-Cover Texts being (b)
11 (see below). A copy of the license is included in the gfdl(7) man page.
14 Some basic guidelines for editing this document:
16 (1) The intrinsic procedures are to be listed in alphabetical order.
17 (2) The generic name is to be used.
18 (3) The specific names are included in the function index and in a
19 table at the end of the node (See ABS entry).
20 (4) Try to maintain the same style for each entry.
26 \gdef\acosd{\mathop{\rm acosd}\nolimits}
27 \gdef\asind{\mathop{\rm asind}\nolimits}
28 \gdef\atand{\mathop{\rm atand}\nolimits}
29 \gdef\acos{\mathop{\rm acos}\nolimits}
30 \gdef\asin{\mathop{\rm asin}\nolimits}
31 \gdef\atan{\mathop{\rm atan}\nolimits}
32 \gdef\acosh{\mathop{\rm acosh}\nolimits}
33 \gdef\asinh{\mathop{\rm asinh}\nolimits}
34 \gdef\atanh{\mathop{\rm atanh}\nolimits}
35 \gdef\cosd{\mathop{\rm cosd}\nolimits}
39 @node Intrinsic Procedures
40 @chapter Intrinsic Procedures
41 @cindex intrinsic procedures
44 * Introduction: Introduction to Intrinsics
45 * @code{ABORT}: ABORT, Abort the program
46 * @code{ABS}: ABS, Absolute value
47 * @code{ACCESS}: ACCESS, Checks file access modes
48 * @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence
49 * @code{ACOS}: ACOS, Arccosine function
50 * @code{ACOSD}: ACOSD, Arccosine function, degrees
51 * @code{ACOSH}: ACOSH, Inverse hyperbolic cosine function
52 * @code{ADJUSTL}: ADJUSTL, Left adjust a string
53 * @code{ADJUSTR}: ADJUSTR, Right adjust a string
54 * @code{AIMAG}: AIMAG, Imaginary part of complex number
55 * @code{AINT}: AINT, Truncate to a whole number
56 * @code{ALARM}: ALARM, Set an alarm clock
57 * @code{ALL}: ALL, Determine if all values are true
58 * @code{ALLOCATED}: ALLOCATED, Status of allocatable entity
59 * @code{AND}: AND, Bitwise logical AND
60 * @code{ANINT}: ANINT, Nearest whole number
61 * @code{ANY}: ANY, Determine if any values are true
62 * @code{ASIN}: ASIN, Arcsine function
63 * @code{ASIND}: ASIND, Arcsine function, degrees
64 * @code{ASINH}: ASINH, Inverse hyperbolic sine function
65 * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair
66 * @code{ATAN}: ATAN, Arctangent function
67 * @code{ATAND}: ATAND, Arctangent function, degrees
68 * @code{ATAN2}: ATAN2, Arctangent function
69 * @code{ATAN2D}: ATAN2D, Arctangent function, degrees
70 * @code{ATANH}: ATANH, Inverse hyperbolic tangent function
71 * @code{ATOMIC_ADD}: ATOMIC_ADD, Atomic ADD operation
72 * @code{ATOMIC_AND}: ATOMIC_AND, Atomic bitwise AND operation
73 * @code{ATOMIC_CAS}: ATOMIC_CAS, Atomic compare and swap
74 * @code{ATOMIC_DEFINE}: ATOMIC_DEFINE, Setting a variable atomically
75 * @code{ATOMIC_FETCH_ADD}: ATOMIC_FETCH_ADD, Atomic ADD operation with prior fetch
76 * @code{ATOMIC_FETCH_AND}: ATOMIC_FETCH_AND, Atomic bitwise AND operation with prior fetch
77 * @code{ATOMIC_FETCH_OR}: ATOMIC_FETCH_OR, Atomic bitwise OR operation with prior fetch
78 * @code{ATOMIC_FETCH_XOR}: ATOMIC_FETCH_XOR, Atomic bitwise XOR operation with prior fetch
79 * @code{ATOMIC_OR}: ATOMIC_OR, Atomic bitwise OR operation
80 * @code{ATOMIC_REF}: ATOMIC_REF, Obtaining the value of a variable atomically
81 * @code{ATOMIC_XOR}: ATOMIC_XOR, Atomic bitwise OR operation
82 * @code{BACKTRACE}: BACKTRACE, Show a backtrace
83 * @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0
84 * @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1
85 * @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind
86 * @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0
87 * @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1
88 * @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind
89 * @code{BGE}: BGE, Bitwise greater than or equal to
90 * @code{BGT}: BGT, Bitwise greater than
91 * @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function
92 * @code{BLE}: BLE, Bitwise less than or equal to
93 * @code{BLT}: BLT, Bitwise less than
94 * @code{BTEST}: BTEST, Bit test function
95 * @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer
96 * @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer
97 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
98 * @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure
99 * @code{C_LOC}: C_LOC, Obtain the C address of an object
100 * @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression
101 * @code{CEILING}: CEILING, Integer ceiling function
102 * @code{CHAR}: CHAR, Integer-to-character conversion function
103 * @code{CHDIR}: CHDIR, Change working directory
104 * @code{CHMOD}: CHMOD, Change access permissions of files
105 * @code{CMPLX}: CMPLX, Complex conversion function
106 * @code{CO_BROADCAST}: CO_BROADCAST, Copy a value to all images the current set of images
107 * @code{CO_MAX}: CO_MAX, Maximal value on the current set of images
108 * @code{CO_MIN}: CO_MIN, Minimal value on the current set of images
109 * @code{CO_REDUCE}: CO_REDUCE, Reduction of values on the current set of images
110 * @code{CO_SUM}: CO_SUM, Sum of values on the current set of images
111 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
112 * @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler
113 * @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string
114 * @code{COMPLEX}: COMPLEX, Complex conversion function
115 * @code{CONJG}: CONJG, Complex conjugate function
116 * @code{COS}: COS, Cosine function
117 * @code{COSD}: COSD, Cosine function, degrees
118 * @code{COSH}: COSH, Hyperbolic cosine function
119 * @code{COTAN}: COTAN, Cotangent function
120 * @code{COTAND}: COTAND, Cotangent function, degrees
121 * @code{COUNT}: COUNT, Count occurrences of TRUE in an array
122 * @code{CPU_TIME}: CPU_TIME, CPU time subroutine
123 * @code{CSHIFT}: CSHIFT, Circular shift elements of an array
124 * @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string
125 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
126 * @code{DBLE}: DBLE, Double precision conversion function
127 * @code{DCMPLX}: DCMPLX, Double complex conversion function
128 * @code{DIGITS}: DIGITS, Significant digits function
129 * @code{DIM}: DIM, Positive difference
130 * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
131 * @code{DPROD}: DPROD, Double product function
132 * @code{DREAL}: DREAL, Double real part function
133 * @code{DSHIFTL}: DSHIFTL, Combined left shift
134 * @code{DSHIFTR}: DSHIFTR, Combined right shift
135 * @code{DTIME}: DTIME, Execution time subroutine (or function)
136 * @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array
137 * @code{EPSILON}: EPSILON, Epsilon function
138 * @code{ERF}: ERF, Error function
139 * @code{ERFC}: ERFC, Complementary error function
140 * @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function
141 * @code{ETIME}: ETIME, Execution time subroutine (or function)
142 * @code{EVENT_QUERY}: EVENT_QUERY, Query whether a coarray event has occurred
143 * @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command
144 * @code{EXIT}: EXIT, Exit the program with status.
145 * @code{EXP}: EXP, Exponential function
146 * @code{EXPONENT}: EXPONENT, Exponent function
147 * @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF, Query dynamic type for extension
148 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
149 * @code{FGET}: FGET, Read a single character in stream mode from stdin
150 * @code{FGETC}: FGETC, Read a single character in stream mode
151 * @code{FINDLOC}: FINDLOC, Search an array for a value
152 * @code{FLOOR}: FLOOR, Integer floor function
153 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
154 * @code{FNUM}: FNUM, File number function
155 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
156 * @code{FPUTC}: FPUTC, Write a single character in stream mode
157 * @code{FRACTION}: FRACTION, Fractional part of the model representation
158 * @code{FREE}: FREE, Memory de-allocation subroutine
159 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
160 * @code{FSTAT}: FSTAT, Get file status
161 * @code{FTELL}: FTELL, Current stream position
162 * @code{GAMMA}: GAMMA, Gamma function
163 * @code{GERROR}: GERROR, Get last system error message
164 * @code{GETARG}: GETARG, Get command line arguments
165 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
166 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
167 * @code{GETCWD}: GETCWD, Get current working directory
168 * @code{GETENV}: GETENV, Get an environmental variable
169 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
170 * @code{GETGID}: GETGID, Group ID function
171 * @code{GETLOG}: GETLOG, Get login name
172 * @code{GETPID}: GETPID, Process ID function
173 * @code{GETUID}: GETUID, User ID function
174 * @code{GMTIME}: GMTIME, Convert time to GMT info
175 * @code{HOSTNM}: HOSTNM, Get system host name
176 * @code{HUGE}: HUGE, Largest number of a kind
177 * @code{HYPOT}: HYPOT, Euclidean distance function
178 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
179 * @code{IALL}: IALL, Bitwise AND of array elements
180 * @code{IAND}: IAND, Bitwise logical and
181 * @code{IANY}: IANY, Bitwise OR of array elements
182 * @code{IARGC}: IARGC, Get the number of command line arguments
183 * @code{IBCLR}: IBCLR, Clear bit
184 * @code{IBITS}: IBITS, Bit extraction
185 * @code{IBSET}: IBSET, Set bit
186 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
187 * @code{IDATE}: IDATE, Current local time (day/month/year)
188 * @code{IEOR}: IEOR, Bitwise logical exclusive or
189 * @code{IERRNO}: IERRNO, Function to get the last system error number
190 * @code{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index conversion
191 * @code{INDEX}: INDEX intrinsic, Position of a substring within a string
192 * @code{INT}: INT, Convert to integer type
193 * @code{INT2}: INT2, Convert to 16-bit integer type
194 * @code{INT8}: INT8, Convert to 64-bit integer type
195 * @code{IOR}: IOR, Bitwise logical or
196 * @code{IPARITY}: IPARITY, Bitwise XOR of array elements
197 * @code{IRAND}: IRAND, Integer pseudo-random number
198 * @code{IS_CONTIGUOUS}: IS_CONTIGUOUS, Test whether an array is contiguous
199 * @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value
200 * @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value
201 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
202 * @code{ISHFT}: ISHFT, Shift bits
203 * @code{ISHFTC}: ISHFTC, Shift bits circularly
204 * @code{ISNAN}: ISNAN, Tests for a NaN
205 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
206 * @code{KILL}: KILL, Send a signal to a process
207 * @code{KIND}: KIND, Kind of an entity
208 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
209 * @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array
210 * @code{LEADZ}: LEADZ, Number of leading zero bits of an integer
211 * @code{LEN}: LEN, Length of a character entity
212 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
213 * @code{LGE}: LGE, Lexical greater than or equal
214 * @code{LGT}: LGT, Lexical greater than
215 * @code{LINK}: LINK, Create a hard link
216 * @code{LLE}: LLE, Lexical less than or equal
217 * @code{LLT}: LLT, Lexical less than
218 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
219 * @code{LOC}: LOC, Returns the address of a variable
220 * @code{LOG}: LOG, Logarithm function
221 * @code{LOG10}: LOG10, Base 10 logarithm function
222 * @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
223 * @code{LOGICAL}: LOGICAL, Convert to logical type
224 * @code{LSHIFT}: LSHIFT, Left shift bits
225 * @code{LSTAT}: LSTAT, Get file status
226 * @code{LTIME}: LTIME, Convert time to local time info
227 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
228 * @code{MASKL}: MASKL, Left justified mask
229 * @code{MASKR}: MASKR, Right justified mask
230 * @code{MATMUL}: MATMUL, matrix multiplication
231 * @code{MAX}: MAX, Maximum value of an argument list
232 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
233 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
234 * @code{MAXVAL}: MAXVAL, Maximum value of an array
235 * @code{MCLOCK}: MCLOCK, Time function
236 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
237 * @code{MERGE}: MERGE, Merge arrays
238 * @code{MERGE_BITS}: MERGE_BITS, Merge of bits under mask
239 * @code{MIN}: MIN, Minimum value of an argument list
240 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
241 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
242 * @code{MINVAL}: MINVAL, Minimum value of an array
243 * @code{MOD}: MOD, Remainder function
244 * @code{MODULO}: MODULO, Modulo function
245 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
246 * @code{MVBITS}: MVBITS, Move bits from one integer to another
247 * @code{NEAREST}: NEAREST, Nearest representable number
248 * @code{NEW_LINE}: NEW_LINE, New line character
249 * @code{NINT}: NINT, Nearest whole number
250 * @code{NORM2}: NORM2, Euclidean vector norm
251 * @code{NOT}: NOT, Logical negation
252 * @code{NULL}: NULL, Function that returns an disassociated pointer
253 * @code{NUM_IMAGES}: NUM_IMAGES, Number of images
254 * @code{OR}: OR, Bitwise logical OR
255 * @code{PACK}: PACK, Pack an array into an array of rank one
256 * @code{PARITY}: PARITY, Reduction with exclusive OR
257 * @code{PERROR}: PERROR, Print system error message
258 * @code{POPCNT}: POPCNT, Number of bits set
259 * @code{POPPAR}: POPPAR, Parity of the number of bits set
260 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
261 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
262 * @code{PRODUCT}: PRODUCT, Product of array elements
263 * @code{RADIX}: RADIX, Base of a data model
264 * @code{RAN}: RAN, Real pseudo-random number
265 * @code{RAND}: RAND, Real pseudo-random number
266 * @code{RANDOM_INIT}: RANDOM_INIT, Initialize pseudo-random number generator
267 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
268 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
269 * @code{RANGE}: RANGE, Decimal exponent range
270 * @code{RANK} : RANK, Rank of a data object
271 * @code{REAL}: REAL, Convert to real type
272 * @code{RENAME}: RENAME, Rename a file
273 * @code{REPEAT}: REPEAT, Repeated string concatenation
274 * @code{RESHAPE}: RESHAPE, Function to reshape an array
275 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
276 * @code{RSHIFT}: RSHIFT, Right shift bits
277 * @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality
278 * @code{SCALE}: SCALE, Scale a real value
279 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
280 * @code{SECNDS}: SECNDS, Time function
281 * @code{SECOND}: SECOND, CPU time function
282 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind
283 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
284 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
285 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
286 * @code{SHAPE}: SHAPE, Determine the shape of an array
287 * @code{SHIFTA}: SHIFTA, Right shift with fill
288 * @code{SHIFTL}: SHIFTL, Left shift
289 * @code{SHIFTR}: SHIFTR, Right shift
290 * @code{SIGN}: SIGN, Sign copying function
291 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
292 * @code{SIN}: SIN, Sine function
293 * @code{SIND}: SIND, Sine function, degrees
294 * @code{SINH}: SINH, Hyperbolic sine function
295 * @code{SIZE}: SIZE, Function to determine the size of an array
296 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
297 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
298 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
299 * @code{SPREAD}: SPREAD, Add a dimension to an array
300 * @code{SQRT}: SQRT, Square-root function
301 * @code{SRAND}: SRAND, Reinitialize the random number generator
302 * @code{STAT}: STAT, Get file status
303 * @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits
304 * @code{SUM}: SUM, Sum of array elements
305 * @code{SYMLNK}: SYMLNK, Create a symbolic link
306 * @code{SYSTEM}: SYSTEM, Execute a shell command
307 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
308 * @code{TAN}: TAN, Tangent function
309 * @code{TAND}: TAND, Tangent function, degrees
310 * @code{TANH}: TANH, Hyperbolic tangent function
311 * @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image
312 * @code{TIME}: TIME, Time function
313 * @code{TIME8}: TIME8, Time function (64-bit)
314 * @code{TINY}: TINY, Smallest positive number of a real kind
315 * @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer
316 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
317 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
318 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
319 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device
320 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
321 * @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array
322 * @code{UMASK}: UMASK, Set the file creation mask
323 * @code{UNLINK}: UNLINK, Remove a file from the file system
324 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
325 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
326 * @code{XOR}: XOR, Bitwise logical exclusive or
329 @node Introduction to Intrinsics
330 @section Introduction to intrinsic procedures
332 The intrinsic procedures provided by GNU Fortran include procedures required
333 by the Fortran 95 and later supported standards, and a set of intrinsic
334 procedures for backwards compatibility with G77. Any conflict between
335 a description here and a description in the Fortran standards is
336 unintentional, and the standard(s) should be considered authoritative.
338 The enumeration of the @code{KIND} type parameter is processor defined in
339 the Fortran 95 standard. GNU Fortran defines the default integer type and
340 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
341 respectively. The standard mandates that both data types shall have
342 another kind, which have more precision. On typical target architectures
343 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
344 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
345 In the description of generic intrinsic procedures, the kind type parameter
346 will be specified by @code{KIND=*}, and in the description of specific
347 names for an intrinsic procedure the kind type parameter will be explicitly
348 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
349 brevity the optional @code{KIND=} syntax will be omitted.
351 Many of the intrinsic procedures take one or more optional arguments.
352 This document follows the convention used in the Fortran 95 standard,
353 and denotes such arguments by square brackets.
355 GNU Fortran offers the @option{-std=} command-line option,
356 which can be used to restrict the set of intrinsic procedures to a
357 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
358 option, and so all intrinsic procedures described here are accepted. There
359 is one caveat. For a select group of intrinsic procedures, @command{g77}
360 implemented both a function and a subroutine. Both classes
361 have been implemented in @command{gfortran} for backwards compatibility
362 with @command{g77}. It is noted here that these functions and subroutines
363 cannot be intermixed in a given subprogram. In the descriptions that follow,
364 the applicable standard for each intrinsic procedure is noted.
369 @section @code{ABORT} --- Abort the program
371 @cindex program termination, with core dump
372 @cindex terminate program, with core dump
376 @item @emph{Description}:
377 @code{ABORT} causes immediate termination of the program. On operating
378 systems that support a core dump, @code{ABORT} will produce a core dump.
379 It will also print a backtrace, unless @code{-fno-backtrace} is given.
381 @item @emph{Standard}:
390 @item @emph{Return value}:
393 @item @emph{Example}:
396 integer :: i = 1, j = 2
397 if (i /= j) call abort
398 end program test_abort
401 @item @emph{See also}:
410 @section @code{ABS} --- Absolute value
421 @cindex absolute value
424 @item @emph{Description}:
425 @code{ABS(A)} computes the absolute value of @code{A}.
427 @item @emph{Standard}:
428 Fortran 77 and later, has overloads that are GNU extensions
434 @code{RESULT = ABS(A)}
436 @item @emph{Arguments}:
437 @multitable @columnfractions .15 .70
438 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
439 @code{REAL}, or @code{COMPLEX}.
442 @item @emph{Return value}:
443 The return value is of the same type and
444 kind as the argument except the return value is @code{REAL} for a
445 @code{COMPLEX} argument.
447 @item @emph{Example}:
452 complex :: z = (-1.e0,0.e0)
459 @item @emph{Specific names}:
460 @multitable @columnfractions .20 .23 .20 .33
461 @headitem Name @tab Argument @tab Return type @tab Standard
462 @item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
463 @item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
464 @item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
465 @item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
466 @item @code{BABS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
467 @item @code{IIABS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
468 @item @code{JIABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
469 @item @code{KIABS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
470 @item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{REAL(8)} @tab GNU extension
471 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{REAL(8)} @tab GNU extension
478 @section @code{ACCESS} --- Checks file access modes
480 @cindex file system, access mode
483 @item @emph{Description}:
484 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
485 exists, is readable, writable or executable. Except for the
486 executable check, @code{ACCESS} can be replaced by
487 Fortran 95's @code{INQUIRE}.
489 @item @emph{Standard}:
496 @code{RESULT = ACCESS(NAME, MODE)}
498 @item @emph{Arguments}:
499 @multitable @columnfractions .15 .70
500 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
501 file name. Trailing blank are ignored unless the character @code{achar(0)}
502 is present, then all characters up to and excluding @code{achar(0)} are
504 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
505 file access mode, may be any concatenation of @code{"r"} (readable),
506 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
510 @item @emph{Return value}:
511 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
512 accessible in the given mode; otherwise or if an invalid argument
513 has been given for @code{MODE} the value @code{1} is returned.
515 @item @emph{Example}:
519 character(len=*), parameter :: file = 'test.dat'
520 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
521 if(access(file,' ') == 0) print *, trim(file),' is exists'
522 if(access(file,'r') == 0) print *, trim(file),' is readable'
523 if(access(file,'w') == 0) print *, trim(file),' is writable'
524 if(access(file,'x') == 0) print *, trim(file),' is executable'
525 if(access(file2,'rwx') == 0) &
526 print *, trim(file2),' is readable, writable and executable'
527 end program access_test
534 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
536 @cindex @acronym{ASCII} collating sequence
537 @cindex collating sequence, @acronym{ASCII}
540 @item @emph{Description}:
541 @code{ACHAR(I)} returns the character located at position @code{I}
542 in the @acronym{ASCII} collating sequence.
544 @item @emph{Standard}:
545 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
551 @code{RESULT = ACHAR(I [, KIND])}
553 @item @emph{Arguments}:
554 @multitable @columnfractions .15 .70
555 @item @var{I} @tab The type shall be @code{INTEGER}.
556 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
557 expression indicating the kind parameter of the result.
560 @item @emph{Return value}:
561 The return value is of type @code{CHARACTER} with a length of one.
562 If the @var{KIND} argument is present, the return value is of the
563 specified kind and of the default kind otherwise.
565 @item @emph{Example}:
570 end program test_achar
574 See @ref{ICHAR} for a discussion of converting between numerical values
575 and formatted string representations.
577 @item @emph{See also}:
586 @section @code{ACOS} --- Arccosine function
589 @cindex trigonometric function, cosine, inverse
590 @cindex cosine, inverse
593 @item @emph{Description}:
594 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
596 @item @emph{Standard}:
597 Fortran 77 and later, for a complex argument Fortran 2008 or later
603 @code{RESULT = ACOS(X)}
605 @item @emph{Arguments}:
606 @multitable @columnfractions .15 .70
607 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
608 less than or equal to one - or the type shall be @code{COMPLEX}.
611 @item @emph{Return value}:
612 The return value is of the same type and kind as @var{X}.
613 The real part of the result is in radians and lies in the range
614 @math{0 \leq \Re \acos(x) \leq \pi}.
616 @item @emph{Example}:
619 real(8) :: x = 0.866_8
621 end program test_acos
624 @item @emph{Specific names}:
625 @multitable @columnfractions .20 .23 .20 .33
626 @headitem Name @tab Argument @tab Return type @tab Standard
627 @item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
628 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
631 @item @emph{See also}:
641 @section @code{ACOSD} --- Arccosine function, degrees
644 @cindex trigonometric function, cosine, inverse, degrees
645 @cindex cosine, inverse, degrees
648 @item @emph{Description}:
649 @code{ACOSD(X)} computes the arccosine of @var{X} in degrees (inverse of
652 @item @emph{Standard}:
659 @code{RESULT = ACOSD(X)}
661 @item @emph{Arguments}:
662 @multitable @columnfractions .15 .70
663 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
664 less than or equal to one.
667 @item @emph{Return value}:
668 The return value is of the same type and kind as @var{X}.
669 The real part of the result is in degrees and lies in the range
670 @math{0 \leq \Re \acos(x) \leq 180}.
672 @item @emph{Example}:
675 real(8) :: x = 0.866_8
677 end program test_acosd
680 @item @emph{Specific names}:
681 @multitable @columnfractions .20 .23 .20 .33
682 @headitem Name @tab Argument @tab Return type @tab Standard
683 @item @code{ACOSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 2023
684 @item @code{DACOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
687 @item @emph{See also}:
697 @section @code{ACOSH} --- Inverse hyperbolic cosine function
700 @cindex area hyperbolic cosine
701 @cindex inverse hyperbolic cosine
702 @cindex hyperbolic function, cosine, inverse
703 @cindex cosine, hyperbolic, inverse
706 @item @emph{Description}:
707 @code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
709 @item @emph{Standard}:
710 Fortran 2008 and later
716 @code{RESULT = ACOSH(X)}
718 @item @emph{Arguments}:
719 @multitable @columnfractions .15 .70
720 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
723 @item @emph{Return value}:
724 The return value has the same type and kind as @var{X}. If @var{X} is
725 complex, the imaginary part of the result is in radians and lies between
726 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
728 @item @emph{Example}:
731 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
736 @item @emph{Specific names}:
737 @multitable @columnfractions .20 .23 .20 .33
738 @headitem Name @tab Argument @tab Return type @tab Standard
739 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
742 @item @emph{See also}:
750 @section @code{ADJUSTL} --- Left adjust a string
752 @cindex string, adjust left
753 @cindex adjust string
756 @item @emph{Description}:
757 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
758 Spaces are inserted at the end of the string as needed.
760 @item @emph{Standard}:
767 @code{RESULT = ADJUSTL(STRING)}
769 @item @emph{Arguments}:
770 @multitable @columnfractions .15 .70
771 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
774 @item @emph{Return value}:
775 The return value is of type @code{CHARACTER} and of the same kind as
776 @var{STRING} where leading spaces are removed and the same number of
777 spaces are inserted on the end of @var{STRING}.
779 @item @emph{Example}:
782 character(len=20) :: str = ' gfortran'
785 end program test_adjustl
788 @item @emph{See also}:
796 @section @code{ADJUSTR} --- Right adjust a string
798 @cindex string, adjust right
799 @cindex adjust string
802 @item @emph{Description}:
803 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
804 Spaces are inserted at the start of the string as needed.
806 @item @emph{Standard}:
813 @code{RESULT = ADJUSTR(STRING)}
815 @item @emph{Arguments}:
816 @multitable @columnfractions .15 .70
817 @item @var{STR} @tab The type shall be @code{CHARACTER}.
820 @item @emph{Return value}:
821 The return value is of type @code{CHARACTER} and of the same kind as
822 @var{STRING} where trailing spaces are removed and the same number of
823 spaces are inserted at the start of @var{STRING}.
825 @item @emph{Example}:
828 character(len=20) :: str = 'gfortran'
831 end program test_adjustr
834 @item @emph{See also}:
842 @section @code{AIMAG} --- Imaginary part of complex number
847 @cindex complex numbers, imaginary part
850 @item @emph{Description}:
851 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
852 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
853 for compatibility with @command{g77}, and their use in new code is
854 strongly discouraged.
856 @item @emph{Standard}:
857 Fortran 77 and later, has overloads that are GNU extensions
863 @code{RESULT = AIMAG(Z)}
865 @item @emph{Arguments}:
866 @multitable @columnfractions .15 .70
867 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
870 @item @emph{Return value}:
871 The return value is of type @code{REAL} with the
872 kind type parameter of the argument.
874 @item @emph{Example}:
879 z4 = cmplx(1.e0_4, 0.e0_4)
880 z8 = cmplx(0.e0_8, 1.e0_8)
881 print *, aimag(z4), dimag(z8)
882 end program test_aimag
885 @item @emph{Specific names}:
886 @multitable @columnfractions .20 .23 .20 .33
887 @headitem Name @tab Argument @tab Return type @tab Standard
888 @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab Fortran 77 and later
889 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
890 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
891 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
898 @section @code{AINT} --- Truncate to a whole number
902 @cindex rounding, floor
905 @item @emph{Description}:
906 @code{AINT(A [, KIND])} truncates its argument to a whole number.
908 @item @emph{Standard}:
915 @code{RESULT = AINT(A [, KIND])}
917 @item @emph{Arguments}:
918 @multitable @columnfractions .15 .70
919 @item @var{A} @tab The type of the argument shall be @code{REAL}.
920 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
921 expression indicating the kind parameter of the result.
924 @item @emph{Return value}:
925 The return value is of type @code{REAL} with the kind type parameter of the
926 argument if the optional @var{KIND} is absent; otherwise, the kind
927 type parameter will be given by @var{KIND}. If the magnitude of
928 @var{X} is less than one, @code{AINT(X)} returns zero. If the
929 magnitude is equal to or greater than one then it returns the largest
930 whole number that does not exceed its magnitude. The sign is the same
931 as the sign of @var{X}.
933 @item @emph{Example}:
940 print *, aint(x4), dint(x8)
942 end program test_aint
945 @item @emph{Specific names}:
946 @multitable @columnfractions .20 .23 .20 .33
947 @headitem Name @tab Argument @tab Return type @tab Standard
948 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
949 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
956 @section @code{ALARM} --- Execute a routine after a given delay
958 @cindex delayed execution
961 @item @emph{Description}:
962 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
963 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
964 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
965 supplied, it will be returned with the number of seconds remaining until
966 any previously scheduled alarm was due to be delivered, or zero if there
967 was no previously scheduled alarm.
969 @item @emph{Standard}:
976 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
978 @item @emph{Arguments}:
979 @multitable @columnfractions .15 .70
980 @item @var{SECONDS} @tab The type of the argument shall be a scalar
981 @code{INTEGER}. It is @code{INTENT(IN)}.
982 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
983 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
984 values may be either @code{SIG_IGN=1} to ignore the alarm generated
985 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
986 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
987 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
990 @item @emph{Example}:
993 external handler_print
995 call alarm (3, handler_print, i)
998 end program test_alarm
1000 This will cause the external routine @var{handler_print} to be called
1007 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
1009 @cindex array, apply condition
1010 @cindex array, condition testing
1013 @item @emph{Description}:
1014 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
1015 in the array along dimension @var{DIM}.
1017 @item @emph{Standard}:
1018 Fortran 90 and later
1021 Transformational function
1023 @item @emph{Syntax}:
1024 @code{RESULT = ALL(MASK [, DIM])}
1026 @item @emph{Arguments}:
1027 @multitable @columnfractions .15 .70
1028 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1029 it shall not be scalar.
1030 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1031 with a value that lies between one and the rank of @var{MASK}.
1034 @item @emph{Return value}:
1035 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
1036 the kind type parameter is the same as the kind type parameter of
1037 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
1038 an array with the rank of @var{MASK} minus 1. The shape is determined from
1039 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1043 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
1044 It also is true if @var{MASK} has zero size; otherwise, it is false.
1046 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
1047 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
1048 is determined by applying @code{ALL} to the array sections.
1051 @item @emph{Example}:
1055 l = all((/.true., .true., .true./))
1060 integer a(2,3), b(2,3)
1064 print *, all(a .eq. b, 1)
1065 print *, all(a .eq. b, 2)
1066 end subroutine section
1067 end program test_all
1074 @section @code{ALLOCATED} --- Status of an allocatable entity
1076 @cindex allocation, status
1079 @item @emph{Description}:
1080 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
1081 status of @var{ARRAY} and @var{SCALAR}, respectively.
1083 @item @emph{Standard}:
1084 Fortran 90 and later. Note, the @code{SCALAR=} keyword and allocatable
1085 scalar entities are available in Fortran 2003 and later.
1090 @item @emph{Syntax}:
1091 @multitable @columnfractions .80
1092 @item @code{RESULT = ALLOCATED(ARRAY)}
1093 @item @code{RESULT = ALLOCATED(SCALAR)}
1096 @item @emph{Arguments}:
1097 @multitable @columnfractions .15 .70
1098 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
1099 @item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar.
1102 @item @emph{Return value}:
1103 The return value is a scalar @code{LOGICAL} with the default logical
1104 kind type parameter. If the argument is allocated, then the result is
1105 @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
1107 @item @emph{Example}:
1109 program test_allocated
1111 real(4), allocatable :: x(:)
1112 if (.not. allocated(x)) allocate(x(i))
1113 end program test_allocated
1120 @section @code{AND} --- Bitwise logical AND
1122 @cindex bitwise logical and
1123 @cindex logical and, bitwise
1126 @item @emph{Description}:
1127 Bitwise logical @code{AND}.
1129 This intrinsic routine is provided for backwards compatibility with
1130 GNU Fortran 77. For integer arguments, programmers should consider
1131 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1133 @item @emph{Standard}:
1139 @item @emph{Syntax}:
1140 @code{RESULT = AND(I, J)}
1142 @item @emph{Arguments}:
1143 @multitable @columnfractions .15 .70
1144 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1145 type or a scalar @code{LOGICAL} type or a boz-literal-constant.
1146 @item @var{J} @tab The type shall be the same as the type of @var{I} or
1147 a boz-literal-constant. @var{I} and @var{J} shall not both be
1148 boz-literal-constants. If either @var{I} or @var{J} is a
1149 boz-literal-constant, then the other argument must be a scalar @code{INTEGER}.
1152 @item @emph{Return value}:
1153 The return type is either a scalar @code{INTEGER} or a scalar
1154 @code{LOGICAL}. If the kind type parameters differ, then the
1155 smaller kind type is implicitly converted to larger kind, and the
1156 return has the larger kind. A boz-literal-constant is
1157 converted to an @code{INTEGER} with the kind type parameter of
1158 the other argument as-if a call to @ref{INT} occurred.
1160 @item @emph{Example}:
1163 LOGICAL :: T = .TRUE., F = .FALSE.
1165 DATA a / Z'F' /, b / Z'3' /
1167 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1168 WRITE (*,*) AND(a, b)
1172 @item @emph{See also}:
1173 Fortran 95 elemental function: @*
1180 @section @code{ANINT} --- Nearest whole number
1184 @cindex rounding, ceiling
1187 @item @emph{Description}:
1188 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1190 @item @emph{Standard}:
1191 Fortran 77 and later
1196 @item @emph{Syntax}:
1197 @code{RESULT = ANINT(A [, KIND])}
1199 @item @emph{Arguments}:
1200 @multitable @columnfractions .15 .70
1201 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1202 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
1203 expression indicating the kind parameter of the result.
1206 @item @emph{Return value}:
1207 The return value is of type real with the kind type parameter of the
1208 argument if the optional @var{KIND} is absent; otherwise, the kind
1209 type parameter will be given by @var{KIND}. If @var{A} is greater than
1210 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1211 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1213 @item @emph{Example}:
1220 print *, anint(x4), dnint(x8)
1222 end program test_anint
1225 @item @emph{Specific names}:
1226 @multitable @columnfractions .20 .23 .20 .33
1227 @headitem Name @tab Argument @tab Return type @tab Standard
1228 @item @code{ANINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
1229 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1236 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1238 @cindex array, apply condition
1239 @cindex array, condition testing
1242 @item @emph{Description}:
1243 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1244 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1246 @item @emph{Standard}:
1247 Fortran 90 and later
1250 Transformational function
1252 @item @emph{Syntax}:
1253 @code{RESULT = ANY(MASK [, DIM])}
1255 @item @emph{Arguments}:
1256 @multitable @columnfractions .15 .70
1257 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1258 it shall not be scalar.
1259 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1260 with a value that lies between one and the rank of @var{MASK}.
1263 @item @emph{Return value}:
1264 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1265 the kind type parameter is the same as the kind type parameter of
1266 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1267 an array with the rank of @var{MASK} minus 1. The shape is determined from
1268 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1272 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1273 otherwise, it is false. It also is false if @var{MASK} has zero size.
1275 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1276 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1277 is determined by applying @code{ANY} to the array sections.
1280 @item @emph{Example}:
1284 l = any((/.true., .true., .true./))
1289 integer a(2,3), b(2,3)
1293 print *, any(a .eq. b, 1)
1294 print *, any(a .eq. b, 2)
1295 end subroutine section
1296 end program test_any
1303 @section @code{ASIN} --- Arcsine function
1306 @cindex trigonometric function, sine, inverse
1307 @cindex sine, inverse
1310 @item @emph{Description}:
1311 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1313 @item @emph{Standard}:
1314 Fortran 77 and later, for a complex argument Fortran 2008 or later
1319 @item @emph{Syntax}:
1320 @code{RESULT = ASIN(X)}
1322 @item @emph{Arguments}:
1323 @multitable @columnfractions .15 .70
1324 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1325 less than or equal to one - or be @code{COMPLEX}.
1328 @item @emph{Return value}:
1329 The return value is of the same type and kind as @var{X}.
1330 The real part of the result is in radians and lies in the range
1331 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1333 @item @emph{Example}:
1336 real(8) :: x = 0.866_8
1338 end program test_asin
1341 @item @emph{Specific names}:
1342 @multitable @columnfractions .20 .23 .20 .33
1343 @headitem Name @tab Argument @tab Return type @tab Standard
1344 @item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1345 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1348 @item @emph{See also}:
1349 Inverse function: @*
1351 Degrees function: @*
1358 @section @code{ASIND} --- Arcsine function, degrees
1361 @cindex trigonometric function, sine, inverse, degrees
1362 @cindex sine, inverse, degrees
1365 @item @emph{Description}:
1366 @code{ASIND(X)} computes the arcsine of its @var{X} in degrees (inverse of
1369 @item @emph{Standard}:
1375 @item @emph{Syntax}:
1376 @code{RESULT = ASIND(X)}
1378 @item @emph{Arguments}:
1379 @multitable @columnfractions .15 .70
1380 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1381 less than or equal to one.
1384 @item @emph{Return value}:
1385 The return value is of the same type and kind as @var{X}.
1386 The result is in degrees and lies in the range
1387 @math{-90 \leq \Re \asin(x) \leq 90}.
1389 @item @emph{Example}:
1392 real(8) :: x = 0.866_8
1394 end program test_asind
1397 @item @emph{Specific names}:
1398 @multitable @columnfractions .20 .23 .20 .33
1399 @headitem Name @tab Argument @tab Return type @tab Standard
1400 @item @code{ASIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 2023
1401 @item @code{DASIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1404 @item @emph{See also}:
1405 Inverse function: @*
1407 Radians function: @*
1412 @section @code{ASINH} --- Inverse hyperbolic sine function
1415 @cindex area hyperbolic sine
1416 @cindex inverse hyperbolic sine
1417 @cindex hyperbolic function, sine, inverse
1418 @cindex sine, hyperbolic, inverse
1421 @item @emph{Description}:
1422 @code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
1424 @item @emph{Standard}:
1425 Fortran 2008 and later
1430 @item @emph{Syntax}:
1431 @code{RESULT = ASINH(X)}
1433 @item @emph{Arguments}:
1434 @multitable @columnfractions .15 .70
1435 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1438 @item @emph{Return value}:
1439 The return value is of the same type and kind as @var{X}. If @var{X} is
1440 complex, the imaginary part of the result is in radians and lies between
1441 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1443 @item @emph{Example}:
1446 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1447 WRITE (*,*) ASINH(x)
1451 @item @emph{Specific names}:
1452 @multitable @columnfractions .20 .23 .20 .33
1453 @headitem Name @tab Argument @tab Return type @tab Standard
1454 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1457 @item @emph{See also}:
1458 Inverse function: @*
1465 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1467 @cindex pointer, status
1468 @cindex association status
1471 @item @emph{Description}:
1472 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1473 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1475 @item @emph{Standard}:
1476 Fortran 90 and later
1481 @item @emph{Syntax}:
1482 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1484 @item @emph{Arguments}:
1485 @multitable @columnfractions .15 .70
1486 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1487 and it can be of any type.
1488 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1489 a target. It must have the same type, kind type parameter, and
1490 array rank as @var{POINTER}.
1492 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1495 @item @emph{Return value}:
1496 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1497 There are several cases:
1499 @item (A) When the optional @var{TARGET} is not present then
1500 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1501 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1502 @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
1503 disassociated, the result is false.
1504 @item (C) If @var{TARGET} is present and an array target, the result is true if
1505 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1506 are arrays whose elements are not zero-sized storage sequences, and
1507 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1509 As in case(B), the result is false, if @var{POINTER} is disassociated.
1510 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1511 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1512 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1514 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1515 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1516 target associated with @var{POINTER} and the target associated with @var{TARGET}
1517 have the same shape, are not zero-sized arrays, are arrays whose elements are
1518 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1519 the same storage units in array element order.
1520 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1523 @item @emph{Example}:
1525 program test_associated
1527 real, target :: tgt(2) = (/1., 2./)
1528 real, pointer :: ptr(:)
1530 if (associated(ptr) .eqv. .false.) call abort
1531 if (associated(ptr,tgt) .eqv. .false.) call abort
1532 end program test_associated
1535 @item @emph{See also}:
1542 @section @code{ATAN} --- Arctangent function
1545 @cindex trigonometric function, tangent, inverse
1546 @cindex tangent, inverse
1549 @item @emph{Description}:
1550 @code{ATAN(X)} computes the arctangent of @var{X}.
1552 @item @emph{Standard}:
1553 Fortran 77 and later, for a complex argument and for two arguments
1554 Fortran 2008 or later
1559 @item @emph{Syntax}:
1560 @multitable @columnfractions .80
1561 @item @code{RESULT = ATAN(X)}
1562 @item @code{RESULT = ATAN(Y, X)}
1565 @item @emph{Arguments}:
1566 @multitable @columnfractions .15 .70
1567 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1568 if @var{Y} is present, @var{X} shall be REAL.
1569 @item @var{Y} @tab The type and kind type parameter shall be the same as @var{X}.
1572 @item @emph{Return value}:
1573 The return value is of the same type and kind as @var{X}.
1574 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1575 Otherwise, it the arcus tangent of @var{X}, where the real part of
1576 the result is in radians and lies in the range
1577 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1579 @item @emph{Example}:
1582 real(8) :: x = 2.866_8
1584 end program test_atan
1587 @item @emph{Specific names}:
1588 @multitable @columnfractions .20 .23 .20 .33
1589 @headitem Name @tab Argument @tab Return type @tab Standard
1590 @item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1591 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1594 @item @emph{See also}:
1595 Inverse function: @*
1597 Degrees function: @*
1604 @section @code{ATAND} --- Arctangent function, degrees
1607 @cindex trigonometric function, tangent, inverse, degrees
1608 @cindex tangent, inverse, degrees
1611 @item @emph{Description}:
1612 @code{ATAND(X)} computes the arctangent of @var{X} in degrees (inverse of
1615 @item @emph{Standard}:
1621 @item @emph{Syntax}:
1622 @multitable @columnfractions .80
1623 @item @code{RESULT = ATAND(X)}
1626 @item @emph{Arguments}:
1627 @multitable @columnfractions .15 .70
1628 @item @var{X} @tab The type shall be @code{REAL};
1629 if @var{Y} is present, @var{X} shall be REAL.
1630 @item @var{Y} @tab The type and kind type parameter shall be the same as @var{X}.
1633 @item @emph{Return value}:
1634 The return value is of the same type and kind as @var{X}.
1635 The result is in degrees and lies in the range
1636 @math{-90 \leq \Re \atand(x) \leq 90}.
1638 @item @emph{Example}:
1641 real(8) :: x = 2.866_8
1643 end program test_atand
1646 @item @emph{Specific names}:
1647 @multitable @columnfractions .23 .23 .20 .30
1648 @headitem Name @tab Argument @tab Return type @tab Standard
1649 @item @code{ATAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 2023
1650 @item @code{DATAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1653 @item @emph{See also}:
1654 Inverse function: @*
1656 Radians function: @*
1663 @section @code{ATAN2} --- Arctangent function
1666 @cindex trigonometric function, tangent, inverse
1667 @cindex tangent, inverse
1670 @item @emph{Description}:
1671 @code{ATAN2(Y, X)} computes the principal value of the argument
1672 function of the complex number @math{X + i Y}. This function can
1673 be used to transform from Cartesian into polar coordinates and
1674 allows to determine the angle in the correct quadrant.
1676 @item @emph{Standard}:
1677 Fortran 77 and later
1682 @item @emph{Syntax}:
1683 @code{RESULT = ATAN2(Y, X)}
1685 @item @emph{Arguments}:
1686 @multitable @columnfractions .15 .70
1687 @item @var{Y} @tab The type shall be @code{REAL}.
1688 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1689 If @var{Y} is zero, then @var{X} must be nonzero.
1692 @item @emph{Return value}:
1693 The return value has the same type and kind type parameter as @var{Y}. It
1694 is the principal value of the complex number @math{X + i Y}. If @var{X}
1695 is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1696 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1697 the return value is zero if @var{X} is strictly positive, @math{\pi} if
1698 @var{X} is negative and @var{Y} is positive zero (or the processor does
1699 not handle signed zeros), and @math{-\pi} if @var{X} is negative and
1700 @var{Y} is negative zero. Finally, if @var{X} is zero, then the
1701 magnitude of the result is @math{\pi/2}.
1703 @item @emph{Example}:
1706 real(4) :: x = 1.e0_4, y = 0.5e0_4
1708 end program test_atan2
1711 @item @emph{Specific names}:
1712 @multitable @columnfractions .22 .22 .20 .32
1713 @headitem Name @tab Argument @tab Return type @tab Standard
1714 @item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1715 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1718 @item @emph{See also}:
1721 Degrees function: @*
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 @item @emph{Standard}:
1747 @item @emph{Syntax}:
1748 @code{RESULT = ATAN2D(Y, X)}
1750 @item @emph{Arguments}:
1751 @multitable @columnfractions .15 .70
1752 @item @var{Y} @tab The type shall be @code{REAL}.
1753 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1754 If @var{Y} is zero, then @var{X} must be nonzero.
1757 @item @emph{Return value}:
1758 The return value has the same type and kind type parameter as @var{Y}. It
1759 is the principal value of the complex number @math{X + i Y}. If @var{X}
1760 is nonzero, then it lies in the range @math{-180 \le \atan (x) \leq 180}.
1761 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1762 the return value is zero if @var{X} is strictly positive, @math{180} if
1763 @var{X} is negative and @var{Y} is positive zero (or the processor does
1764 not handle signed zeros), and @math{-180} if @var{X} is negative and
1765 @var{Y} is negative zero. Finally, if @var{X} is zero, then the
1766 magnitude of the result is @math{90}.
1768 @item @emph{Example}:
1771 real(4) :: x = 1.e0_4, y = 0.5e0_4
1773 end program test_atan2d
1776 @item @emph{Specific names}:
1777 @multitable @columnfractions .23 .23 .20 .30
1778 @headitem Name @tab Argument @tab Return type @tab Standard
1779 @item @code{ATAN2D(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 2023
1780 @item @code{DATAN2D(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab GNU extension
1783 @item @emph{See also}:
1786 Radians function: @*
1791 @section @code{ATANH} --- Inverse hyperbolic tangent function
1794 @cindex area hyperbolic tangent
1795 @cindex inverse hyperbolic tangent
1796 @cindex hyperbolic function, tangent, inverse
1797 @cindex tangent, hyperbolic, inverse
1800 @item @emph{Description}:
1801 @code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
1803 @item @emph{Standard}:
1804 Fortran 2008 and later
1809 @item @emph{Syntax}:
1810 @code{RESULT = ATANH(X)}
1812 @item @emph{Arguments}:
1813 @multitable @columnfractions .15 .70
1814 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1817 @item @emph{Return value}:
1818 The return value has same type and kind as @var{X}. If @var{X} is
1819 complex, the imaginary part of the result is in radians and lies between
1820 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1822 @item @emph{Example}:
1825 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1826 WRITE (*,*) ATANH(x)
1830 @item @emph{Specific names}:
1831 @multitable @columnfractions .20 .23 .20 .33
1832 @headitem Name @tab Argument @tab Return type @tab Standard
1833 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1836 @item @emph{See also}:
1837 Inverse function: @*
1844 @section @code{ATOMIC_ADD} --- Atomic ADD operation
1846 @cindex Atomic subroutine, add
1849 @item @emph{Description}:
1850 @code{ATOMIC_ADD(ATOM, VALUE)} atomically adds the value of @var{VALUE} to the
1851 variable @var{ATOM}. When @var{STAT} is present and the invocation was
1852 successful, it is assigned the value 0. If it is present and the invocation
1853 has failed, it is assigned a positive value; in particular, for a coindexed
1854 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1855 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1856 failed, the value @code{STAT_FAILED_IMAGE}.
1858 @item @emph{Standard}:
1864 @item @emph{Syntax}:
1865 @code{CALL ATOMIC_ADD (ATOM, VALUE [, STAT])}
1867 @item @emph{Arguments}:
1868 @multitable @columnfractions .15 .70
1869 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1870 type with @code{ATOMIC_INT_KIND} kind.
1871 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1872 is different, the value is converted to the kind of @var{ATOM}.
1873 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1876 @item @emph{Example}:
1880 integer(atomic_int_kind) :: atom[*]
1881 call atomic_add (atom[1], this_image())
1885 @item @emph{See also}:
1886 @ref{ATOMIC_DEFINE}, @*
1887 @ref{ATOMIC_FETCH_ADD}, @*
1888 @ref{ISO_FORTRAN_ENV}, @*
1889 @ref{ATOMIC_AND}, @*
1898 @section @code{ATOMIC_AND} --- Atomic bitwise AND operation
1900 @cindex Atomic subroutine, AND
1903 @item @emph{Description}:
1904 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
1905 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
1906 and the invocation was successful, it is assigned the value 0. If it is present
1907 and the invocation has failed, it is assigned a positive value; in particular,
1908 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
1909 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
1910 image has failed, the value @code{STAT_FAILED_IMAGE}.
1912 @item @emph{Standard}:
1918 @item @emph{Syntax}:
1919 @code{CALL ATOMIC_AND (ATOM, VALUE [, STAT])}
1921 @item @emph{Arguments}:
1922 @multitable @columnfractions .15 .70
1923 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1924 type with @code{ATOMIC_INT_KIND} kind.
1925 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1926 is different, the value is converted to the kind of @var{ATOM}.
1927 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1930 @item @emph{Example}:
1934 integer(atomic_int_kind) :: atom[*]
1935 call atomic_and (atom[1], int(b'10100011101'))
1939 @item @emph{See also}:
1940 @ref{ATOMIC_DEFINE}, @*
1941 @ref{ATOMIC_FETCH_AND}, @*
1942 @ref{ISO_FORTRAN_ENV}, @*
1943 @ref{ATOMIC_ADD}, @*
1951 @section @code{ATOMIC_CAS} --- Atomic compare and swap
1952 @fnindex ATOMIC_DEFINE
1953 @cindex Atomic subroutine, compare and swap
1956 @item @emph{Description}:
1957 @code{ATOMIC_CAS} compares the variable @var{ATOM} with the value of
1958 @var{COMPARE}; if the value is the same, @var{ATOM} is set to the value
1959 of @var{NEW}. Additionally, @var{OLD} is set to the value of @var{ATOM}
1960 that was used for the comparison. When @var{STAT} is present and the invocation
1961 was successful, it is assigned the value 0. If it is present and the invocation
1962 has failed, it is assigned a positive value; in particular, for a coindexed
1963 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1964 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1965 failed, the value @code{STAT_FAILED_IMAGE}.
1967 @item @emph{Standard}:
1973 @item @emph{Syntax}:
1974 @code{CALL ATOMIC_CAS (ATOM, OLD, COMPARE, NEW [, STAT])}
1976 @item @emph{Arguments}:
1977 @multitable @columnfractions .15 .70
1978 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
1979 type with @code{ATOMIC_INT_KIND} kind or logical type with
1980 @code{ATOMIC_LOGICAL_KIND} kind.
1981 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1982 @item @var{COMPARE} @tab Scalar variable of the same type and kind as
1984 @item @var{NEW} @tab Scalar variable of the same type as @var{ATOM}. If kind
1985 is different, the value is converted to the kind of @var{ATOM}.
1986 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1989 @item @emph{Example}:
1993 logical(atomic_logical_kind) :: atom[*], prev
1994 call atomic_cas (atom[1], prev, .false., .true.))
1998 @item @emph{See also}:
1999 @ref{ATOMIC_DEFINE}, @*
2000 @ref{ATOMIC_REF}, @*
2001 @ref{ISO_FORTRAN_ENV}
2007 @section @code{ATOMIC_DEFINE} --- Setting a variable atomically
2008 @fnindex ATOMIC_DEFINE
2009 @cindex Atomic subroutine, define
2012 @item @emph{Description}:
2013 @code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value
2014 @var{VALUE} atomically. When @var{STAT} is present and the invocation was
2015 successful, it is assigned the value 0. If it is present and the invocation
2016 has failed, it is assigned a positive value; in particular, for a coindexed
2017 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2018 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2019 failed, the value @code{STAT_FAILED_IMAGE}.
2021 @item @emph{Standard}:
2022 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
2027 @item @emph{Syntax}:
2028 @code{CALL ATOMIC_DEFINE (ATOM, VALUE [, STAT])}
2030 @item @emph{Arguments}:
2031 @multitable @columnfractions .15 .70
2032 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
2033 type with @code{ATOMIC_INT_KIND} kind or logical type with
2034 @code{ATOMIC_LOGICAL_KIND} kind.
2036 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2037 is different, the value is converted to the kind of @var{ATOM}.
2038 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2041 @item @emph{Example}:
2045 integer(atomic_int_kind) :: atom[*]
2046 call atomic_define (atom[1], this_image())
2050 @item @emph{See also}:
2051 @ref{ATOMIC_REF}, @*
2052 @ref{ATOMIC_CAS}, @*
2053 @ref{ISO_FORTRAN_ENV}, @*
2054 @ref{ATOMIC_ADD}, @*
2055 @ref{ATOMIC_AND}, @*
2062 @node ATOMIC_FETCH_ADD
2063 @section @code{ATOMIC_FETCH_ADD} --- Atomic ADD operation with prior fetch
2064 @fnindex ATOMIC_FETCH_ADD
2065 @cindex Atomic subroutine, ADD with fetch
2068 @item @emph{Description}:
2069 @code{ATOMIC_FETCH_ADD(ATOM, VALUE, OLD)} atomically stores the value of
2070 @var{ATOM} in @var{OLD} and adds the value of @var{VALUE} to the
2071 variable @var{ATOM}. When @var{STAT} is present and the invocation was
2072 successful, it is assigned the value 0. If it is present and the invocation
2073 has failed, it is assigned a positive value; in particular, for a coindexed
2074 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2075 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2076 failed, the value @code{STAT_FAILED_IMAGE}.
2078 @item @emph{Standard}:
2084 @item @emph{Syntax}:
2085 @code{CALL ATOMIC_FETCH_ADD (ATOM, VALUE, old [, STAT])}
2087 @item @emph{Arguments}:
2088 @multitable @columnfractions .15 .70
2089 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2090 type with @code{ATOMIC_INT_KIND} kind.
2091 @code{ATOMIC_LOGICAL_KIND} kind.
2093 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2094 is different, the value is converted to the kind of @var{ATOM}.
2095 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2096 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2099 @item @emph{Example}:
2103 integer(atomic_int_kind) :: atom[*], old
2104 call atomic_add (atom[1], this_image(), old)
2108 @item @emph{See also}:
2109 @ref{ATOMIC_DEFINE}, @*
2110 @ref{ATOMIC_ADD}, @*
2111 @ref{ISO_FORTRAN_ENV}, @*
2112 @ref{ATOMIC_FETCH_AND}, @*
2113 @ref{ATOMIC_FETCH_OR}, @*
2114 @ref{ATOMIC_FETCH_XOR}
2119 @node ATOMIC_FETCH_AND
2120 @section @code{ATOMIC_FETCH_AND} --- Atomic bitwise AND operation with prior fetch
2121 @fnindex ATOMIC_FETCH_AND
2122 @cindex Atomic subroutine, AND with fetch
2125 @item @emph{Description}:
2126 @code{ATOMIC_AND(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2127 @var{OLD} and defines @var{ATOM} with the bitwise AND between the values of
2128 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
2129 successful, it is assigned the value 0. If it is present and the invocation has
2130 failed, it is assigned a positive value; in particular, for a coindexed
2131 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2132 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2133 failed, the value @code{STAT_FAILED_IMAGE}.
2135 @item @emph{Standard}:
2141 @item @emph{Syntax}:
2142 @code{CALL ATOMIC_FETCH_AND (ATOM, VALUE, OLD [, STAT])}
2144 @item @emph{Arguments}:
2145 @multitable @columnfractions .15 .70
2146 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2147 type with @code{ATOMIC_INT_KIND} kind.
2148 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2149 is different, the value is converted to the kind of @var{ATOM}.
2150 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2151 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2154 @item @emph{Example}:
2158 integer(atomic_int_kind) :: atom[*], old
2159 call atomic_fetch_and (atom[1], int(b'10100011101'), old)
2163 @item @emph{See also}:
2164 @ref{ATOMIC_DEFINE}, @*
2165 @ref{ATOMIC_AND}, @*
2166 @ref{ISO_FORTRAN_ENV}, @*
2167 @ref{ATOMIC_FETCH_ADD}, @*
2168 @ref{ATOMIC_FETCH_OR}, @*
2169 @ref{ATOMIC_FETCH_XOR}
2174 @node ATOMIC_FETCH_OR
2175 @section @code{ATOMIC_FETCH_OR} --- Atomic bitwise OR operation with prior fetch
2176 @fnindex ATOMIC_FETCH_OR
2177 @cindex Atomic subroutine, OR with fetch
2180 @item @emph{Description}:
2181 @code{ATOMIC_OR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2182 @var{OLD} and defines @var{ATOM} with the bitwise OR between the values of
2183 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
2184 successful, it is assigned the value 0. If it is present and the invocation has
2185 failed, it is assigned a positive value; in particular, for a coindexed
2186 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2187 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2188 failed, the value @code{STAT_FAILED_IMAGE}.
2190 @item @emph{Standard}:
2196 @item @emph{Syntax}:
2197 @code{CALL ATOMIC_FETCH_OR (ATOM, VALUE, OLD [, STAT])}
2199 @item @emph{Arguments}:
2200 @multitable @columnfractions .15 .70
2201 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2202 type with @code{ATOMIC_INT_KIND} kind.
2203 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2204 is different, the value is converted to the kind of @var{ATOM}.
2205 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2206 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2209 @item @emph{Example}:
2213 integer(atomic_int_kind) :: atom[*], old
2214 call atomic_fetch_or (atom[1], int(b'10100011101'), old)
2218 @item @emph{See also}:
2219 @ref{ATOMIC_DEFINE}, @*
2221 @ref{ISO_FORTRAN_ENV}, @*
2222 @ref{ATOMIC_FETCH_ADD}, @*
2223 @ref{ATOMIC_FETCH_AND}, @*
2224 @ref{ATOMIC_FETCH_XOR}
2229 @node ATOMIC_FETCH_XOR
2230 @section @code{ATOMIC_FETCH_XOR} --- Atomic bitwise XOR operation with prior fetch
2231 @fnindex ATOMIC_FETCH_XOR
2232 @cindex Atomic subroutine, XOR with fetch
2235 @item @emph{Description}:
2236 @code{ATOMIC_XOR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2237 @var{OLD} and defines @var{ATOM} with the bitwise XOR between the values of
2238 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
2239 successful, it is assigned the value 0. If it is present and the invocation has
2240 failed, it is assigned a positive value; in particular, for a coindexed
2241 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2242 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2243 failed, the value @code{STAT_FAILED_IMAGE}.
2245 @item @emph{Standard}:
2251 @item @emph{Syntax}:
2252 @code{CALL ATOMIC_FETCH_XOR (ATOM, VALUE, OLD [, STAT])}
2254 @item @emph{Arguments}:
2255 @multitable @columnfractions .15 .70
2256 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2257 type with @code{ATOMIC_INT_KIND} kind.
2258 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2259 is different, the value is converted to the kind of @var{ATOM}.
2260 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2261 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2264 @item @emph{Example}:
2268 integer(atomic_int_kind) :: atom[*], old
2269 call atomic_fetch_xor (atom[1], int(b'10100011101'), old)
2273 @item @emph{See also}:
2274 @ref{ATOMIC_DEFINE}, @*
2275 @ref{ATOMIC_XOR}, @*
2276 @ref{ISO_FORTRAN_ENV}, @*
2277 @ref{ATOMIC_FETCH_ADD}, @*
2278 @ref{ATOMIC_FETCH_AND}, @*
2279 @ref{ATOMIC_FETCH_OR}
2285 @section @code{ATOMIC_OR} --- Atomic bitwise OR operation
2287 @cindex Atomic subroutine, OR
2290 @item @emph{Description}:
2291 @code{ATOMIC_OR(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
2292 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
2293 and the invocation was successful, it is assigned the value 0. If it is present
2294 and the invocation has failed, it is assigned a positive value; in particular,
2295 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
2296 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
2297 image has failed, the value @code{STAT_FAILED_IMAGE}.
2299 @item @emph{Standard}:
2305 @item @emph{Syntax}:
2306 @code{CALL ATOMIC_OR (ATOM, VALUE [, STAT])}
2308 @item @emph{Arguments}:
2309 @multitable @columnfractions .15 .70
2310 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2311 type with @code{ATOMIC_INT_KIND} kind.
2312 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2313 is different, the value is converted to the kind of @var{ATOM}.
2314 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2317 @item @emph{Example}:
2321 integer(atomic_int_kind) :: atom[*]
2322 call atomic_or (atom[1], int(b'10100011101'))
2326 @item @emph{See also}:
2327 @ref{ATOMIC_DEFINE}, @*
2328 @ref{ATOMIC_FETCH_OR}, @*
2329 @ref{ISO_FORTRAN_ENV}, @*
2330 @ref{ATOMIC_ADD}, @*
2338 @section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically
2340 @cindex Atomic subroutine, reference
2343 @item @emph{Description}:
2344 @code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the
2345 variable @var{ATOM} to @var{VALUE}. When @var{STAT} is present and the
2346 invocation was successful, it is assigned the value 0. If it is present and the
2347 invocation has failed, it is assigned a positive value; in particular, for a
2348 coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value
2349 of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image
2350 has failed, the value @code{STAT_FAILED_IMAGE}.
2353 @item @emph{Standard}:
2354 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
2359 @item @emph{Syntax}:
2360 @code{CALL ATOMIC_REF(VALUE, ATOM [, STAT])}
2362 @item @emph{Arguments}:
2363 @multitable @columnfractions .15 .70
2364 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2365 is different, the value is converted to the kind of @var{ATOM}.
2366 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
2367 type with @code{ATOMIC_INT_KIND} kind or logical type with
2368 @code{ATOMIC_LOGICAL_KIND} kind.
2369 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2372 @item @emph{Example}:
2376 logical(atomic_logical_kind) :: atom[*]
2378 call atomic_ref (atom, .false.)
2380 call atomic_ref (atom, val)
2387 @item @emph{See also}:
2388 @ref{ATOMIC_DEFINE}, @*
2389 @ref{ATOMIC_CAS}, @*
2390 @ref{ISO_FORTRAN_ENV}, @*
2391 @ref{ATOMIC_FETCH_ADD}, @*
2392 @ref{ATOMIC_FETCH_AND}, @*
2393 @ref{ATOMIC_FETCH_OR}, @*
2394 @ref{ATOMIC_FETCH_XOR}
2399 @section @code{ATOMIC_XOR} --- Atomic bitwise OR operation
2401 @cindex Atomic subroutine, XOR
2404 @item @emph{Description}:
2405 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
2406 XOR between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
2407 and the invocation was successful, it is assigned the value 0. If it is present
2408 and the invocation has failed, it is assigned a positive value; in particular,
2409 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
2410 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
2411 image has failed, the value @code{STAT_FAILED_IMAGE}.
2413 @item @emph{Standard}:
2419 @item @emph{Syntax}:
2420 @code{CALL ATOMIC_XOR (ATOM, VALUE [, STAT])}
2422 @item @emph{Arguments}:
2423 @multitable @columnfractions .15 .70
2424 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2425 type with @code{ATOMIC_INT_KIND} kind.
2426 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2427 is different, the value is converted to the kind of @var{ATOM}.
2428 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2431 @item @emph{Example}:
2435 integer(atomic_int_kind) :: atom[*]
2436 call atomic_xor (atom[1], int(b'10100011101'))
2440 @item @emph{See also}:
2441 @ref{ATOMIC_DEFINE}, @*
2442 @ref{ATOMIC_FETCH_XOR}, @*
2443 @ref{ISO_FORTRAN_ENV}, @*
2444 @ref{ATOMIC_ADD}, @*
2451 @section @code{BACKTRACE} --- Show a backtrace
2456 @item @emph{Description}:
2457 @code{BACKTRACE} shows a backtrace at an arbitrary place in user code. Program
2458 execution continues normally afterwards. The backtrace information is printed
2459 to the unit corresponding to @code{ERROR_UNIT} in @code{ISO_FORTRAN_ENV}.
2461 @item @emph{Standard}:
2467 @item @emph{Syntax}:
2468 @code{CALL BACKTRACE}
2470 @item @emph{Arguments}:
2473 @item @emph{See also}:
2480 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
2484 @cindex Bessel function, first kind
2487 @item @emph{Description}:
2488 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
2489 order 0 of @var{X}. This function is available under the name
2490 @code{BESJ0} as a GNU extension.
2492 @item @emph{Standard}:
2493 Fortran 2008 and later
2498 @item @emph{Syntax}:
2499 @code{RESULT = BESSEL_J0(X)}
2501 @item @emph{Arguments}:
2502 @multitable @columnfractions .15 .70
2503 @item @var{X} @tab The type shall be @code{REAL}.
2506 @item @emph{Return value}:
2507 The return value is of type @code{REAL} and lies in the
2508 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
2511 @item @emph{Example}:
2514 real(8) :: x = 0.0_8
2516 end program test_besj0
2519 @item @emph{Specific names}:
2520 @multitable @columnfractions .21 .22 .20 .33
2521 @headitem Name @tab Argument @tab Return type @tab Standard
2522 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2529 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
2533 @cindex Bessel function, first kind
2536 @item @emph{Description}:
2537 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
2538 order 1 of @var{X}. This function is available under the name
2539 @code{BESJ1} as a GNU extension.
2541 @item @emph{Standard}:
2547 @item @emph{Syntax}:
2548 @code{RESULT = BESSEL_J1(X)}
2550 @item @emph{Arguments}:
2551 @multitable @columnfractions .15 .70
2552 @item @var{X} @tab The type shall be @code{REAL}.
2555 @item @emph{Return value}:
2556 The return value is of type @code{REAL} and lies in the
2557 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
2560 @item @emph{Example}:
2563 real(8) :: x = 1.0_8
2565 end program test_besj1
2568 @item @emph{Specific names}:
2569 @multitable @columnfractions .20 .23 .20 .33
2570 @headitem Name @tab Argument @tab Return type @tab Standard
2571 @item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2578 @section @code{BESSEL_JN} --- Bessel function of the first kind
2582 @cindex Bessel function, first kind
2585 @item @emph{Description}:
2586 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
2587 order @var{N} of @var{X}. This function is available under the name
2588 @code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays,
2589 their ranks and shapes shall conform.
2591 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
2592 of the first kind of the orders @var{N1} to @var{N2}.
2594 @item @emph{Standard}:
2595 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2598 Elemental function, except for the transformational function
2599 @code{BESSEL_JN(N1, N2, X)}
2601 @item @emph{Syntax}:
2602 @multitable @columnfractions .80
2603 @item @code{RESULT = BESSEL_JN(N, X)}
2604 @item @code{RESULT = BESSEL_JN(N1, N2, X)}
2607 @item @emph{Arguments}:
2608 @multitable @columnfractions .15 .70
2609 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
2610 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2611 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2612 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2613 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
2616 @item @emph{Return value}:
2617 The return value is a scalar of type @code{REAL}. It has the same
2621 The transformational function uses a recurrence algorithm which might,
2622 for some values of @var{X}, lead to different results than calls to
2623 the elemental function.
2625 @item @emph{Example}:
2628 real(8) :: x = 1.0_8
2630 end program test_besjn
2633 @item @emph{Specific names}:
2634 @multitable @columnfractions .22 .22 .20 .32
2635 @headitem Name @tab Argument @tab Return type @tab Standard
2636 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2637 @item @tab @code{REAL(8) X} @tab @tab
2644 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
2648 @cindex Bessel function, second kind
2651 @item @emph{Description}:
2652 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
2653 order 0 of @var{X}. This function is available under the name
2654 @code{BESY0} as a GNU extension.
2656 @item @emph{Standard}:
2657 Fortran 2008 and later
2662 @item @emph{Syntax}:
2663 @code{RESULT = BESSEL_Y0(X)}
2665 @item @emph{Arguments}:
2666 @multitable @columnfractions .15 .70
2667 @item @var{X} @tab The type shall be @code{REAL}.
2670 @item @emph{Return value}:
2671 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2673 @item @emph{Example}:
2676 real(8) :: x = 0.0_8
2678 end program test_besy0
2681 @item @emph{Specific names}:
2682 @multitable @columnfractions .20 .23 .20 .33
2683 @headitem Name @tab Argument @tab Return type @tab Standard
2684 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2691 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
2695 @cindex Bessel function, second kind
2698 @item @emph{Description}:
2699 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
2700 order 1 of @var{X}. This function is available under the name
2701 @code{BESY1} as a GNU extension.
2703 @item @emph{Standard}:
2704 Fortran 2008 and later
2709 @item @emph{Syntax}:
2710 @code{RESULT = BESSEL_Y1(X)}
2712 @item @emph{Arguments}:
2713 @multitable @columnfractions .15 .70
2714 @item @var{X} @tab The type shall be @code{REAL}.
2717 @item @emph{Return value}:
2718 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2720 @item @emph{Example}:
2723 real(8) :: x = 1.0_8
2725 end program test_besy1
2728 @item @emph{Specific names}:
2729 @multitable @columnfractions .20 .23 .20 .33
2730 @headitem Name @tab Argument @tab Return type @tab Standard
2731 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2738 @section @code{BESSEL_YN} --- Bessel function of the second kind
2742 @cindex Bessel function, second kind
2745 @item @emph{Description}:
2746 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
2747 order @var{N} of @var{X}. This function is available under the name
2748 @code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays,
2749 their ranks and shapes shall conform.
2751 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
2752 of the first kind of the orders @var{N1} to @var{N2}.
2754 @item @emph{Standard}:
2755 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2758 Elemental function, except for the transformational function
2759 @code{BESSEL_YN(N1, N2, X)}
2761 @item @emph{Syntax}:
2762 @multitable @columnfractions .80
2763 @item @code{RESULT = BESSEL_YN(N, X)}
2764 @item @code{RESULT = BESSEL_YN(N1, N2, X)}
2767 @item @emph{Arguments}:
2768 @multitable @columnfractions .15 .70
2769 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} .
2770 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2771 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2772 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2773 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
2776 @item @emph{Return value}:
2777 The return value is a scalar of type @code{REAL}. It has the same
2781 The transformational function uses a recurrence algorithm which might,
2782 for some values of @var{X}, lead to different results than calls to
2783 the elemental function.
2785 @item @emph{Example}:
2788 real(8) :: x = 1.0_8
2790 end program test_besyn
2793 @item @emph{Specific names}:
2794 @multitable @columnfractions .20 .23 .20 .33
2795 @headitem Name @tab Argument @tab Return type @tab Standard
2796 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2797 @item @tab @code{REAL(8) X} @tab @tab
2804 @section @code{BGE} --- Bitwise greater than or equal to
2806 @cindex bitwise comparison
2809 @item @emph{Description}:
2810 Determines whether an integral is a bitwise greater than or equal to
2813 @item @emph{Standard}:
2814 Fortran 2008 and later
2819 @item @emph{Syntax}:
2820 @code{RESULT = BGE(I, J)}
2822 @item @emph{Arguments}:
2823 @multitable @columnfractions .15 .70
2824 @item @var{I} @tab Shall be of @code{INTEGER} type.
2825 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2829 @item @emph{Return value}:
2830 The return value is of type @code{LOGICAL} and of the default kind.
2832 @item @emph{See also}:
2841 @section @code{BGT} --- Bitwise greater than
2843 @cindex bitwise comparison
2846 @item @emph{Description}:
2847 Determines whether an integral is a bitwise greater than another.
2849 @item @emph{Standard}:
2850 Fortran 2008 and later
2855 @item @emph{Syntax}:
2856 @code{RESULT = BGT(I, J)}
2858 @item @emph{Arguments}:
2859 @multitable @columnfractions .15 .70
2860 @item @var{I} @tab Shall be of @code{INTEGER} type.
2861 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2865 @item @emph{Return value}:
2866 The return value is of type @code{LOGICAL} and of the default kind.
2868 @item @emph{See also}:
2877 @section @code{BIT_SIZE} --- Bit size inquiry function
2879 @cindex bits, number of
2880 @cindex size of a variable, in bits
2883 @item @emph{Description}:
2884 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
2885 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
2886 independent of the actual value of @var{I}.
2888 @item @emph{Standard}:
2889 Fortran 90 and later
2894 @item @emph{Syntax}:
2895 @code{RESULT = BIT_SIZE(I)}
2897 @item @emph{Arguments}:
2898 @multitable @columnfractions .15 .70
2899 @item @var{I} @tab The type shall be @code{INTEGER}.
2902 @item @emph{Return value}:
2903 The return value is of type @code{INTEGER}
2905 @item @emph{Example}:
2907 program test_bit_size
2912 end program test_bit_size
2919 @section @code{BLE} --- Bitwise less than or equal to
2921 @cindex bitwise comparison
2924 @item @emph{Description}:
2925 Determines whether an integral is a bitwise less than or equal to
2928 @item @emph{Standard}:
2929 Fortran 2008 and later
2934 @item @emph{Syntax}:
2935 @code{RESULT = BLE(I, J)}
2937 @item @emph{Arguments}:
2938 @multitable @columnfractions .15 .70
2939 @item @var{I} @tab Shall be of @code{INTEGER} type.
2940 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2944 @item @emph{Return value}:
2945 The return value is of type @code{LOGICAL} and of the default kind.
2947 @item @emph{See also}:
2956 @section @code{BLT} --- Bitwise less than
2958 @cindex bitwise comparison
2961 @item @emph{Description}:
2962 Determines whether an integral is a bitwise less than another.
2964 @item @emph{Standard}:
2965 Fortran 2008 and later
2970 @item @emph{Syntax}:
2971 @code{RESULT = BLT(I, J)}
2973 @item @emph{Arguments}:
2974 @multitable @columnfractions .15 .70
2975 @item @var{I} @tab Shall be of @code{INTEGER} type.
2976 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2980 @item @emph{Return value}:
2981 The return value is of type @code{LOGICAL} and of the default kind.
2983 @item @emph{See also}:
2992 @section @code{BTEST} --- Bit test function
2998 @cindex bits, testing
3001 @item @emph{Description}:
3002 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
3003 in @var{I} is set. The counting of the bits starts at 0.
3005 @item @emph{Standard}:
3006 Fortran 90 and later, has overloads that are GNU extensions
3011 @item @emph{Syntax}:
3012 @code{RESULT = BTEST(I, POS)}
3014 @item @emph{Arguments}:
3015 @multitable @columnfractions .15 .70
3016 @item @var{I} @tab The type shall be @code{INTEGER}.
3017 @item @var{POS} @tab The type shall be @code{INTEGER}.
3020 @item @emph{Return value}:
3021 The return value is of type @code{LOGICAL}
3023 @item @emph{Example}:
3026 integer :: i = 32768 + 1024 + 64
3030 bool = btest(i, pos)
3033 end program test_btest
3036 @item @emph{Specific names}:
3037 @multitable @columnfractions .21 .28 .18 .30
3038 @headitem Name @tab Argument @tab Return type @tab Standard
3039 @item @code{BTEST(I,POS)} @tab @code{INTEGER I,POS} @tab @code{LOGICAL} @tab Fortran 95 and later
3040 @item @code{BBTEST(I,POS)} @tab @code{INTEGER(1) I,POS} @tab @code{LOGICAL(1)} @tab GNU extension
3041 @item @code{BITEST(I,POS)} @tab @code{INTEGER(2) I,POS} @tab @code{LOGICAL(2)} @tab GNU extension
3042 @item @code{BJTEST(I,POS)} @tab @code{INTEGER(4) I,POS} @tab @code{LOGICAL(4)} @tab GNU extension
3043 @item @code{BKTEST(I,POS)} @tab @code{INTEGER(8) I,POS} @tab @code{LOGICAL(8)} @tab GNU extension
3048 @section @code{C_ASSOCIATED} --- Status of a C pointer
3049 @fnindex C_ASSOCIATED
3050 @cindex association status, C pointer
3051 @cindex pointer, C association status
3054 @item @emph{Description}:
3055 @code{C_ASSOCIATED(c_ptr_1[, c_ptr_2])} determines the status of the C pointer
3056 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
3058 @item @emph{Standard}:
3059 Fortran 2003 and later
3064 @item @emph{Syntax}:
3065 @code{RESULT = C_ASSOCIATED(c_ptr_1[, c_ptr_2])}
3067 @item @emph{Arguments}:
3068 @multitable @columnfractions .15 .70
3069 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
3070 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
3073 @item @emph{Return value}:
3074 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
3075 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
3076 point to different addresses.
3078 @item @emph{Example}:
3080 subroutine association_test(a,b)
3081 use iso_c_binding, only: c_associated, c_loc, c_ptr
3085 if(c_associated(b, c_loc(a))) &
3086 stop 'b and a do not point to same target'
3087 end subroutine association_test
3090 @item @emph{See also}:
3097 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
3098 @fnindex C_F_POINTER
3099 @cindex pointer, convert C to Fortran
3102 @item @emph{Description}:
3103 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} assigns the target of the C pointer
3104 @var{CPTR} to the Fortran pointer @var{FPTR} and specifies its shape.
3106 @item @emph{Standard}:
3107 Fortran 2003 and later
3112 @item @emph{Syntax}:
3113 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
3115 @item @emph{Arguments}:
3116 @multitable @columnfractions .15 .70
3117 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
3119 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
3121 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
3122 with @code{INTENT(IN)}. It shall be present
3123 if and only if @var{fptr} is an array. The size
3124 must be equal to the rank of @var{fptr}.
3127 @item @emph{Example}:
3133 subroutine my_routine(p) bind(c,name='myC_func')
3135 type(c_ptr), intent(out) :: p
3139 real,pointer :: a(:)
3140 call my_routine(cptr)
3141 call c_f_pointer(cptr, a, [12])
3145 @item @emph{See also}:
3147 @ref{C_F_PROCPOINTER}
3151 @node C_F_PROCPOINTER
3152 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
3153 @fnindex C_F_PROCPOINTER
3154 @cindex pointer, C address of pointers
3157 @item @emph{Description}:
3158 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
3159 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
3161 @item @emph{Standard}:
3162 Fortran 2003 and later
3167 @item @emph{Syntax}:
3168 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
3170 @item @emph{Arguments}:
3171 @multitable @columnfractions .15 .70
3172 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
3174 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
3178 @item @emph{Example}:
3186 real(c_float), intent(in) :: a
3187 real(c_float) :: func
3191 function getIterFunc() bind(c,name="getIterFunc")
3193 type(c_funptr) :: getIterFunc
3196 type(c_funptr) :: cfunptr
3197 procedure(func), pointer :: myFunc
3198 cfunptr = getIterFunc()
3199 call c_f_procpointer(cfunptr, myFunc)
3203 @item @emph{See also}:
3210 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
3212 @cindex pointer, C address of procedures
3215 @item @emph{Description}:
3216 @code{C_FUNLOC(x)} determines the C address of the argument.
3218 @item @emph{Standard}:
3219 Fortran 2003 and later
3224 @item @emph{Syntax}:
3225 @code{RESULT = C_FUNLOC(x)}
3227 @item @emph{Arguments}:
3228 @multitable @columnfractions .15 .70
3229 @item @var{x} @tab Interoperable function or pointer to such function.
3232 @item @emph{Return value}:
3233 The return value is of type @code{C_FUNPTR} and contains the C address
3236 @item @emph{Example}:
3242 subroutine sub(a) bind(c)
3252 subroutine my_routine(p) bind(c,name='myC_func')
3254 type(c_funptr), intent(in) :: p
3257 call my_routine(c_funloc(sub))
3261 @item @emph{See also}:
3262 @ref{C_ASSOCIATED}, @*
3264 @ref{C_F_POINTER}, @*
3265 @ref{C_F_PROCPOINTER}
3270 @section @code{C_LOC} --- Obtain the C address of an object
3272 @cindex procedure pointer, convert C to Fortran
3275 @item @emph{Description}:
3276 @code{C_LOC(X)} determines the C address of the argument.
3278 @item @emph{Standard}:
3279 Fortran 2003 and later
3284 @item @emph{Syntax}:
3285 @code{RESULT = C_LOC(X)}
3287 @item @emph{Arguments}:
3288 @multitable @columnfractions .10 .75
3289 @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.
3293 @item @emph{Return value}:
3294 The return value is of type @code{C_PTR} and contains the C address
3297 @item @emph{Example}:
3299 subroutine association_test(a,b)
3300 use iso_c_binding, only: c_associated, c_loc, c_ptr
3304 if(c_associated(b, c_loc(a))) &
3305 stop 'b and a do not point to same target'
3306 end subroutine association_test
3309 @item @emph{See also}:
3310 @ref{C_ASSOCIATED}, @*
3312 @ref{C_F_POINTER}, @*
3313 @ref{C_F_PROCPOINTER}
3318 @section @code{C_SIZEOF} --- Size in bytes of an expression
3320 @cindex expression size
3321 @cindex size of an expression
3324 @item @emph{Description}:
3325 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
3326 expression @code{X} occupies.
3328 @item @emph{Standard}:
3332 Inquiry function of the module @code{ISO_C_BINDING}
3334 @item @emph{Syntax}:
3335 @code{N = C_SIZEOF(X)}
3337 @item @emph{Arguments}:
3338 @multitable @columnfractions .15 .70
3339 @item @var{X} @tab The argument shall be an interoperable data entity.
3342 @item @emph{Return value}:
3343 The return value is of type integer and of the system-dependent kind
3344 @code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the
3345 number of bytes occupied by the argument. If the argument has the
3346 @code{POINTER} attribute, the number of bytes of the storage area pointed
3347 to is returned. If the argument is of a derived type with @code{POINTER}
3348 or @code{ALLOCATABLE} components, the return value does not account for
3349 the sizes of the data pointed to by these components.
3351 @item @emph{Example}:
3355 real(c_float) :: r, s(5)
3356 print *, (c_sizeof(s)/c_sizeof(r) == 5)
3359 The example will print @code{T} unless you are using a platform
3360 where default @code{REAL} variables are unusually padded.
3362 @item @emph{See also}:
3369 @section @code{CEILING} --- Integer ceiling function
3372 @cindex rounding, ceiling
3375 @item @emph{Description}:
3376 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
3378 @item @emph{Standard}:
3379 Fortran 95 and later
3384 @item @emph{Syntax}:
3385 @code{RESULT = CEILING(A [, KIND])}
3387 @item @emph{Arguments}:
3388 @multitable @columnfractions .15 .70
3389 @item @var{A} @tab The type shall be @code{REAL}.
3390 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
3391 expression indicating the kind parameter of the result.
3394 @item @emph{Return value}:
3395 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
3396 and a default-kind @code{INTEGER} otherwise.
3398 @item @emph{Example}:
3400 program test_ceiling
3403 print *, ceiling(x) ! returns 64
3404 print *, ceiling(y) ! returns -63
3405 end program test_ceiling
3408 @item @emph{See also}:
3416 @section @code{CHAR} --- Character conversion function
3418 @cindex conversion, to character
3421 @item @emph{Description}:
3422 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
3424 @item @emph{Standard}:
3425 Fortran 77 and later
3430 @item @emph{Syntax}:
3431 @code{RESULT = CHAR(I [, KIND])}
3433 @item @emph{Arguments}:
3434 @multitable @columnfractions .15 .70
3435 @item @var{I} @tab The type shall be @code{INTEGER}.
3436 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
3437 expression indicating the kind parameter of the result.
3440 @item @emph{Return value}:
3441 The return value is of type @code{CHARACTER(1)}
3443 @item @emph{Example}:
3449 print *, i, c ! returns 'J'
3450 end program test_char
3453 @item @emph{Specific names}:
3454 @multitable @columnfractions .19 .19 .25 .33
3455 @headitem Name @tab Argument @tab Return type @tab Standard
3456 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab Fortran 77 and later
3460 See @ref{ICHAR} for a discussion of converting between numerical values
3461 and formatted string representations.
3463 @item @emph{See also}:
3473 @section @code{CHDIR} --- Change working directory
3475 @cindex system, working directory
3478 @item @emph{Description}:
3479 Change current working directory to a specified path.
3481 This intrinsic is provided in both subroutine and function forms; however,
3482 only one form can be used in any given program unit.
3484 @item @emph{Standard}:
3488 Subroutine, function
3490 @item @emph{Syntax}:
3491 @multitable @columnfractions .80
3492 @item @code{CALL CHDIR(NAME [, STATUS])}
3493 @item @code{STATUS = CHDIR(NAME)}
3496 @item @emph{Arguments}:
3497 @multitable @columnfractions .15 .70
3498 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
3499 kind and shall specify a valid path within the file system.
3500 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
3501 kind. Returns 0 on success, and a system specific and nonzero error code
3505 @item @emph{Example}:
3508 CHARACTER(len=255) :: path
3510 WRITE(*,*) TRIM(path)
3513 WRITE(*,*) TRIM(path)
3517 @item @emph{See also}:
3524 @section @code{CHMOD} --- Change access permissions of files
3526 @cindex file system, change access mode
3529 @item @emph{Description}:
3530 @code{CHMOD} changes the permissions of a file.
3532 This intrinsic is provided in both subroutine and function forms; however,
3533 only one form can be used in any given program unit.
3535 @item @emph{Standard}:
3539 Subroutine, function
3541 @item @emph{Syntax}:
3542 @multitable @columnfractions .80
3543 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
3544 @item @code{STATUS = CHMOD(NAME, MODE)}
3547 @item @emph{Arguments}:
3548 @multitable @columnfractions .15 .70
3550 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
3551 file name. Trailing blanks are ignored unless the character
3552 @code{achar(0)} is present, then all characters up to and excluding
3553 @code{achar(0)} are used as the file name.
3555 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
3556 file permission. @var{MODE} uses the same syntax as the @code{chmod} utility
3557 as defined by the POSIX standard. The argument shall either be a string of
3558 a nonnegative octal number or a symbolic mode.
3560 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
3561 @code{0} on success and nonzero otherwise.
3564 @item @emph{Return value}:
3565 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
3568 @item @emph{Example}:
3569 @code{CHMOD} as subroutine
3574 call chmod('test.dat','u+x',status)
3575 print *, 'Status: ', status
3576 end program chmod_test
3578 @code{CHMOD} as function:
3583 status = chmod('test.dat','u+x')
3584 print *, 'Status: ', status
3585 end program chmod_test
3593 @section @code{CMPLX} --- Complex conversion function
3595 @cindex complex numbers, conversion to
3596 @cindex conversion, to complex
3599 @item @emph{Description}:
3600 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
3601 the real component. If @var{Y} is present it is converted to the imaginary
3602 component. If @var{Y} is not present then the imaginary component is set to
3603 0.0. If @var{X} is complex then @var{Y} must not be present.
3605 @item @emph{Standard}:
3606 Fortran 77 and later
3611 @item @emph{Syntax}:
3612 @code{RESULT = CMPLX(X [, Y [, KIND]])}
3614 @item @emph{Arguments}:
3615 @multitable @columnfractions .15 .70
3616 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3618 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
3619 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
3620 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
3621 expression indicating the kind parameter of the result.
3624 @item @emph{Return value}:
3625 The return value is of @code{COMPLEX} type, with a kind equal to
3626 @var{KIND} if it is specified. If @var{KIND} is not specified, the
3627 result is of the default @code{COMPLEX} kind, regardless of the kinds of
3628 @var{X} and @var{Y}.
3630 @item @emph{Example}:
3637 print *, z, cmplx(x)
3638 end program test_cmplx
3641 @item @emph{See also}:
3648 @section @code{CO_BROADCAST} --- Copy a value to all images the current set of images
3649 @fnindex CO_BROADCAST
3650 @cindex Collectives, value broadcasting
3653 @item @emph{Description}:
3654 @code{CO_BROADCAST} copies the value of argument @var{A} on the image with
3655 image index @code{SOURCE_IMAGE} to all images in the current team. @var{A}
3656 becomes defined as if by intrinsic assignment. If the execution was
3657 successful and @var{STAT} is present, it is assigned the value zero. If the
3658 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3659 @var{ERRMSG} gets assigned a value describing the occurred error.
3661 @item @emph{Standard}:
3662 Technical Specification (TS) 18508 or later
3665 Collective subroutine
3667 @item @emph{Syntax}:
3668 @code{CALL CO_BROADCAST(A, SOURCE_IMAGE [, STAT, ERRMSG])}
3670 @item @emph{Arguments}:
3671 @multitable @columnfractions .20 .65
3672 @item @var{A} @tab INTENT(INOUT) argument; shall have the same
3673 dynamic type and type parameters on all images of the current team. If it
3674 is an array, it shall have the same shape on all images.
3675 @item @var{SOURCE_IMAGE} @tab a scalar integer expression.
3676 It shall have the same value on all images and refer to an
3677 image of the current team.
3678 @item @var{STAT} @tab (optional) a scalar integer variable
3679 @item @var{ERRMSG} @tab (optional) a scalar character variable
3682 @item @emph{Example}:
3686 if (this_image() == 1) then
3689 call co_broadcast (val, source_image=1)
3690 print *, this_image, ":", val
3694 @item @emph{See also}:
3704 @section @code{CO_MAX} --- Maximal value on the current set of images
3706 @cindex Collectives, maximal value
3709 @item @emph{Description}:
3710 @code{CO_MAX} determines element-wise the maximal value of @var{A} on all
3711 images of the current team. If @var{RESULT_IMAGE} is present, the maximum
3712 values are returned in @var{A} on the specified image only and the value
3713 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3714 not present, the value is returned on all images. If the execution was
3715 successful and @var{STAT} is present, it is assigned the value zero. If the
3716 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3717 @var{ERRMSG} gets assigned a value describing the occurred error.
3719 @item @emph{Standard}:
3720 Technical Specification (TS) 18508 or later
3723 Collective subroutine
3725 @item @emph{Syntax}:
3726 @code{CALL CO_MAX(A [, RESULT_IMAGE, STAT, ERRMSG])}
3728 @item @emph{Arguments}:
3729 @multitable @columnfractions .20 .65
3730 @item @var{A} @tab shall be an integer, real or character variable,
3731 which has the same type and type parameters on all images of the team.
3732 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3733 present, it shall have the same value on all images and refer to an
3734 image of the current team.
3735 @item @var{STAT} @tab (optional) a scalar integer variable
3736 @item @var{ERRMSG} @tab (optional) a scalar character variable
3739 @item @emph{Example}:
3744 call co_max (val, result_image=1)
3745 if (this_image() == 1) then
3746 write(*,*) "Maximal value", val ! prints num_images()
3751 @item @emph{See also}:
3761 @section @code{CO_MIN} --- Minimal value on the current set of images
3763 @cindex Collectives, minimal value
3766 @item @emph{Description}:
3767 @code{CO_MIN} determines element-wise the minimal value of @var{A} on all
3768 images of the current team. If @var{RESULT_IMAGE} is present, the minimal
3769 values are returned in @var{A} on the specified image only and the value
3770 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3771 not present, the value is returned on all images. If the execution was
3772 successful and @var{STAT} is present, it is assigned the value zero. If the
3773 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3774 @var{ERRMSG} gets assigned a value describing the occurred error.
3776 @item @emph{Standard}:
3777 Technical Specification (TS) 18508 or later
3780 Collective subroutine
3782 @item @emph{Syntax}:
3783 @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3785 @item @emph{Arguments}:
3786 @multitable @columnfractions .20 .65
3787 @item @var{A} @tab shall be an integer, real or character variable,
3788 which has the same type and type parameters on all images of the team.
3789 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3790 present, it shall have the same value on all images and refer to an
3791 image of the current team.
3792 @item @var{STAT} @tab (optional) a scalar integer variable
3793 @item @var{ERRMSG} @tab (optional) a scalar character variable
3796 @item @emph{Example}:
3801 call co_min (val, result_image=1)
3802 if (this_image() == 1) then
3803 write(*,*) "Minimal value", val ! prints 1
3808 @item @emph{See also}:
3818 @section @code{CO_REDUCE} --- Reduction of values on the current set of images
3820 @cindex Collectives, generic reduction
3823 @item @emph{Description}:
3824 @code{CO_REDUCE} determines element-wise the reduction of the value of @var{A}
3825 on all images of the current team. The pure function passed as @var{OPERATION}
3826 is used to pairwise reduce the values of @var{A} by passing either the value
3827 of @var{A} of different images or the result values of such a reduction as
3828 argument. If @var{A} is an array, the deduction is done element wise. If
3829 @var{RESULT_IMAGE} is present, the result values are returned in @var{A} on
3830 the specified image only and the value of @var{A} on the other images become
3831 undefined. If @var{RESULT_IMAGE} is not present, the value is returned on all
3832 images. If the execution was successful and @var{STAT} is present, it is
3833 assigned the value zero. If the execution failed, @var{STAT} gets assigned
3834 a nonzero value and, if present, @var{ERRMSG} gets assigned a value describing
3837 @item @emph{Standard}:
3838 Technical Specification (TS) 18508 or later
3841 Collective subroutine
3843 @item @emph{Syntax}:
3844 @code{CALL CO_REDUCE(A, OPERATION, [, RESULT_IMAGE, STAT, ERRMSG])}
3846 @item @emph{Arguments}:
3847 @multitable @columnfractions .20 .65
3848 @item @var{A} @tab is an @code{INTENT(INOUT)} argument and shall be
3849 nonpolymorphic. If it is allocatable, it shall be allocated; if it is a pointer,
3850 it shall be associated. @var{A} shall have the same type and type parameters on
3851 all images of the team; if it is an array, it shall have the same shape on all
3853 @item @var{OPERATION} @tab pure function with two scalar nonallocatable
3854 arguments, which shall be nonpolymorphic and have the same type and type
3855 parameters as @var{A}. The function shall return a nonallocatable scalar of
3856 the same type and type parameters as @var{A}. The function shall be the same on
3857 all images and with regards to the arguments mathematically commutative and
3858 associative. Note that @var{OPERATION} may not be an elemental function, unless
3859 it is an intrisic function.
3860 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3861 present, it shall have the same value on all images and refer to an
3862 image of the current team.
3863 @item @var{STAT} @tab (optional) a scalar integer variable
3864 @item @var{ERRMSG} @tab (optional) a scalar character variable
3867 @item @emph{Example}:
3872 call co_reduce (val, result_image=1, operation=myprod)
3873 if (this_image() == 1) then
3874 write(*,*) "Product value", val ! prints num_images() factorial
3877 pure function myprod(a, b)
3878 integer, value :: a, b
3886 While the rules permit in principle an intrinsic function, none of the
3887 intrinsics in the standard fulfill the criteria of having a specific
3888 function, which takes two arguments of the same type and returning that
3891 @item @emph{See also}:
3901 @section @code{CO_SUM} --- Sum of values on the current set of images
3903 @cindex Collectives, sum of values
3906 @item @emph{Description}:
3907 @code{CO_SUM} sums up the values of each element of @var{A} on all
3908 images of the current team. If @var{RESULT_IMAGE} is present, the summed-up
3909 values are returned in @var{A} on the specified image only and the value
3910 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3911 not present, the value is returned on all images. If the execution was
3912 successful and @var{STAT} is present, it is assigned the value zero. If the
3913 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3914 @var{ERRMSG} gets assigned a value describing the occurred error.
3916 @item @emph{Standard}:
3917 Technical Specification (TS) 18508 or later
3920 Collective subroutine
3922 @item @emph{Syntax}:
3923 @code{CALL CO_SUM(A [, RESULT_IMAGE, STAT, ERRMSG])}
3925 @item @emph{Arguments}:
3926 @multitable @columnfractions .20 .65
3927 @item @var{A} @tab shall be an integer, real or complex variable,
3928 which has the same type and type parameters on all images of the team.
3929 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3930 present, it shall have the same value on all images and refer to an
3931 image of the current team.
3932 @item @var{STAT} @tab (optional) a scalar integer variable
3933 @item @var{ERRMSG} @tab (optional) a scalar character variable
3936 @item @emph{Example}:
3941 call co_sum (val, result_image=1)
3942 if (this_image() == 1) then
3943 write(*,*) "The sum is ", val ! prints (n**2 + n)/2,
3944 ! with n = num_images()
3949 @item @emph{See also}:
3958 @node COMMAND_ARGUMENT_COUNT
3959 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
3960 @fnindex COMMAND_ARGUMENT_COUNT
3961 @cindex command-line arguments
3962 @cindex command-line arguments, number of
3963 @cindex arguments, to program
3966 @item @emph{Description}:
3967 @code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the
3968 command line when the containing program was invoked.
3970 @item @emph{Standard}:
3971 Fortran 2003 and later
3976 @item @emph{Syntax}:
3977 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
3979 @item @emph{Arguments}:
3980 @multitable @columnfractions .15 .70
3984 @item @emph{Return value}:
3985 The return value is an @code{INTEGER} of default kind.
3987 @item @emph{Example}:
3989 program test_command_argument_count
3991 count = command_argument_count()
3993 end program test_command_argument_count
3996 @item @emph{See also}:
3997 @ref{GET_COMMAND}, @*
3998 @ref{GET_COMMAND_ARGUMENT}
4003 @node COMPILER_OPTIONS
4004 @section @code{COMPILER_OPTIONS} --- Options passed to the compiler
4005 @fnindex COMPILER_OPTIONS
4006 @cindex flags inquiry function
4007 @cindex options inquiry function
4008 @cindex compiler flags inquiry function
4011 @item @emph{Description}:
4012 @code{COMPILER_OPTIONS} returns a string with the options used for
4015 @item @emph{Standard}:
4019 Inquiry function of the module @code{ISO_FORTRAN_ENV}
4021 @item @emph{Syntax}:
4022 @code{STR = COMPILER_OPTIONS()}
4024 @item @emph{Arguments}:
4027 @item @emph{Return value}:
4028 The return value is a default-kind string with system-dependent length.
4029 It contains the compiler flags used to compile the file, which called
4030 the @code{COMPILER_OPTIONS} intrinsic.
4032 @item @emph{Example}:
4035 print '(4a)', 'This file was compiled by ', &
4036 compiler_version(), ' using the options ', &
4041 @item @emph{See also}:
4042 @ref{COMPILER_VERSION}, @*
4043 @ref{ISO_FORTRAN_ENV}
4048 @node COMPILER_VERSION
4049 @section @code{COMPILER_VERSION} --- Compiler version string
4050 @fnindex COMPILER_VERSION
4051 @cindex compiler, name and version
4052 @cindex version of the compiler
4055 @item @emph{Description}:
4056 @code{COMPILER_VERSION} returns a string with the name and the
4057 version of the compiler.
4059 @item @emph{Standard}:
4063 Inquiry function of the module @code{ISO_FORTRAN_ENV}
4065 @item @emph{Syntax}:
4066 @code{STR = COMPILER_VERSION()}
4068 @item @emph{Arguments}:
4071 @item @emph{Return value}:
4072 The return value is a default-kind string with system-dependent length.
4073 It contains the name of the compiler and its version number.
4075 @item @emph{Example}:
4078 print '(4a)', 'This file was compiled by ', &
4079 compiler_version(), ' using the options ', &
4084 @item @emph{See also}:
4085 @ref{COMPILER_OPTIONS}, @*
4086 @ref{ISO_FORTRAN_ENV}
4092 @section @code{COMPLEX} --- Complex conversion function
4094 @cindex complex numbers, conversion to
4095 @cindex conversion, to complex
4098 @item @emph{Description}:
4099 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
4100 to the real component and @var{Y} is converted to the imaginary
4103 @item @emph{Standard}:
4109 @item @emph{Syntax}:
4110 @code{RESULT = COMPLEX(X, Y)}
4112 @item @emph{Arguments}:
4113 @multitable @columnfractions .15 .70
4114 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
4115 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
4118 @item @emph{Return value}:
4119 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
4120 value is of default @code{COMPLEX} type.
4122 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
4123 type and one is of @code{INTEGER} type, then the return value is of
4124 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
4125 argument with the highest precision.
4127 @item @emph{Example}:
4129 program test_complex
4132 print *, complex(i, x)
4133 end program test_complex
4136 @item @emph{See also}:
4143 @section @code{CONJG} --- Complex conjugate function
4146 @cindex complex conjugate
4149 @item @emph{Description}:
4150 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
4151 then the result is @code{(x, -y)}
4153 @item @emph{Standard}:
4154 Fortran 77 and later, has an overload that is a GNU extension
4159 @item @emph{Syntax}:
4162 @item @emph{Arguments}:
4163 @multitable @columnfractions .15 .70
4164 @item @var{Z} @tab The type shall be @code{COMPLEX}.
4167 @item @emph{Return value}:
4168 The return value is of type @code{COMPLEX}.
4170 @item @emph{Example}:
4173 complex :: z = (2.0, 3.0)
4174 complex(8) :: dz = (2.71_8, -3.14_8)
4179 end program test_conjg
4182 @item @emph{Specific names}:
4183 @multitable @columnfractions .20 .23 .20 .33
4184 @headitem Name @tab Argument @tab Return type @tab Standard
4185 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
4192 @section @code{COS} --- Cosine function
4198 @cindex trigonometric function, cosine
4202 @item @emph{Description}:
4203 @code{COS(X)} computes the cosine of @var{X}.
4205 @item @emph{Standard}:
4206 Fortran 77 and later, has overloads that are GNU extensions
4211 @item @emph{Syntax}:
4212 @code{RESULT = COS(X)}
4214 @item @emph{Arguments}:
4215 @multitable @columnfractions .15 .70
4216 @item @var{X} @tab The type shall be @code{REAL} or
4220 @item @emph{Return value}:
4221 The return value is of the same type and kind as @var{X}. The real part
4222 of the result is in radians. If @var{X} is of the type @code{REAL},
4223 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
4225 @item @emph{Example}:
4230 end program test_cos
4233 @item @emph{Specific names}:
4234 @multitable @columnfractions .20 .23 .20 .33
4235 @headitem Name @tab Argument @tab Return type @tab Standard
4236 @item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
4237 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
4238 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
4239 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4240 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4243 @item @emph{See also}:
4244 Inverse function: @*
4246 Degrees function: @*
4253 @section @code{COSD} --- Cosine function, degrees
4259 @cindex trigonometric function, cosine, degrees
4260 @cindex cosine, degrees
4263 @item @emph{Description}:
4264 @code{COSD(X)} computes the cosine of @var{X} in degrees.
4266 @item @emph{Standard}:
4272 @item @emph{Syntax}:
4273 @code{RESULT = COSD(X)}
4275 @item @emph{Arguments}:
4276 @multitable @columnfractions .15 .70
4277 @item @var{X} @tab The type shall be @code{REAL}.
4280 @item @emph{Return value}:
4281 The return value is of the same type and kind as @var{X} and
4282 lies in the range @math{ -1 \leq \cosd (x) \leq 1}.
4284 @item @emph{Example}:
4289 end program test_cosd
4292 @item @emph{Specific names}:
4293 @multitable @columnfractions .20 .23 .20 .33
4294 @headitem Name @tab Argument @tab Return type @tab Standard
4295 @item @code{COSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 2023
4296 @item @code{DCOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4297 @item @code{CCOSD(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU extension
4298 @item @code{ZCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4299 @item @code{CDCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4302 @item @emph{See also}:
4303 Inverse function: @*
4305 Radians function: @*
4312 @section @code{COSH} --- Hyperbolic cosine function
4315 @cindex hyperbolic cosine
4316 @cindex hyperbolic function, cosine
4317 @cindex cosine, hyperbolic
4320 @item @emph{Description}:
4321 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
4323 @item @emph{Standard}:
4324 Fortran 77 and later, for a complex argument Fortran 2008 or later
4329 @item @emph{Syntax}:
4332 @item @emph{Arguments}:
4333 @multitable @columnfractions .15 .70
4334 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4337 @item @emph{Return value}:
4338 The return value has same type and kind as @var{X}. If @var{X} is
4339 complex, the imaginary part of the result is in radians. If @var{X}
4340 is @code{REAL}, the return value has a lower bound of one,
4341 @math{\cosh (x) \geq 1}.
4343 @item @emph{Example}:
4346 real(8) :: x = 1.0_8
4348 end program test_cosh
4351 @item @emph{Specific names}:
4352 @multitable @columnfractions .20 .23 .20 .33
4353 @headitem Name @tab Argument @tab Return type @tab Standard
4354 @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
4355 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
4358 @item @emph{See also}:
4359 Inverse function: @*
4366 @section @code{COTAN} --- Cotangent function
4369 @cindex trigonometric function, cotangent
4373 @item @emph{Description}:
4374 @code{COTAN(X)} computes the cotangent of @var{X}. Equivalent to @code{COS(x)}
4375 divided by @code{SIN(x)}, or @code{1 / TAN(x)}.
4377 This function is for compatibility only and should be avoided in favor of
4378 standard constructs wherever possible.
4380 @item @emph{Standard}:
4381 GNU extension, enabled with @option{-fdec-math}.
4386 @item @emph{Syntax}:
4387 @code{RESULT = COTAN(X)}
4389 @item @emph{Arguments}:
4390 @multitable @columnfractions .15 .70
4391 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4394 @item @emph{Return value}:
4395 The return value has same type and kind as @var{X}, and its value is in radians.
4397 @item @emph{Example}:
4400 real(8) :: x = 0.165_8
4402 end program test_cotan
4405 @item @emph{Specific names}:
4406 @multitable @columnfractions .20 .23 .20 .33
4407 @headitem Name @tab Argument @tab Return type @tab Standard
4408 @item @code{COTAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
4409 @item @code{DCOTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4412 @item @emph{See also}:
4413 Converse function: @*
4415 Degrees function: @*
4422 @section @code{COTAND} --- Cotangent function, degrees
4425 @cindex trigonometric function, cotangent, degrees
4426 @cindex cotangent, degrees
4429 @item @emph{Description}:
4430 @code{COTAND(X)} computes the cotangent of @var{X} in degrees. Equivalent to
4431 @code{COSD(x)} divided by @code{SIND(x)}, or @code{1 / TAND(x)}.
4433 @item @emph{Standard}:
4436 This function is for compatibility only and should be avoided in favor of
4437 standard constructs wherever possible.
4442 @item @emph{Syntax}:
4443 @code{RESULT = COTAND(X)}
4445 @item @emph{Arguments}:
4446 @multitable @columnfractions .15 .70
4447 @item @var{X} @tab The type shall be @code{REAL}.
4450 @item @emph{Return value}:
4451 The return value has same type and kind as @var{X}, and its value is in degrees.
4453 @item @emph{Example}:
4456 real(8) :: x = 0.165_8
4458 end program test_cotand
4461 @item @emph{Specific names}:
4462 @multitable @columnfractions .20 .23 .20 .33
4463 @headitem Name @tab Argument @tab Return type @tab Standard
4464 @item @code{COTAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
4465 @item @code{DCOTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4468 @item @emph{See also}:
4469 Converse function: @*
4471 Radians function: @*
4478 @section @code{COUNT} --- Count function
4480 @cindex array, conditionally count elements
4481 @cindex array, element counting
4482 @cindex array, number of elements
4485 @item @emph{Description}:
4487 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
4488 or, if the @var{DIM} argument is supplied, counts the number of
4489 elements along each row of the array in the @var{DIM} direction.
4490 If the array has zero size, or all of the elements of @var{MASK} are
4491 @code{.FALSE.}, then the result is @code{0}.
4493 @item @emph{Standard}:
4494 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
4497 Transformational function
4499 @item @emph{Syntax}:
4500 @code{RESULT = COUNT(MASK [, DIM, KIND])}
4502 @item @emph{Arguments}:
4503 @multitable @columnfractions .15 .70
4504 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
4505 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
4506 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
4507 expression indicating the kind parameter of the result.
4510 @item @emph{Return value}:
4511 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
4512 @var{KIND} is absent, the return value is of default integer kind.
4513 If @var{DIM} is present, the result is an array with a rank one less
4514 than the rank of @var{ARRAY}, and a size corresponding to the shape
4515 of @var{ARRAY} with the @var{DIM} dimension removed.
4517 @item @emph{Example}:
4520 integer, dimension(2,3) :: a, b
4521 logical, dimension(2,3) :: mask
4522 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
4523 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
4524 print '(3i3)', a(1,:)
4525 print '(3i3)', a(2,:)
4527 print '(3i3)', b(1,:)
4528 print '(3i3)', b(2,:)
4531 print '(3l3)', mask(1,:)
4532 print '(3l3)', mask(2,:)
4534 print '(3i3)', count(mask)
4536 print '(3i3)', count(mask, 1)
4538 print '(3i3)', count(mask, 2)
4539 end program test_count
4546 @section @code{CPU_TIME} --- CPU elapsed time in seconds
4548 @cindex time, elapsed
4551 @item @emph{Description}:
4552 Returns a @code{REAL} value representing the elapsed CPU time in
4553 seconds. This is useful for testing segments of code to determine
4556 If a time source is available, time will be reported with microsecond
4557 resolution. If no time source is available, @var{TIME} is set to
4560 Note that @var{TIME} may contain a, system dependent, arbitrary offset
4561 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
4562 value is meaningless, only differences between subsequent calls to
4563 this subroutine, as shown in the example below, should be used.
4566 @item @emph{Standard}:
4567 Fortran 95 and later
4572 @item @emph{Syntax}:
4573 @code{CALL CPU_TIME(TIME)}
4575 @item @emph{Arguments}:
4576 @multitable @columnfractions .15 .70
4577 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
4580 @item @emph{Return value}:
4583 @item @emph{Example}:
4585 program test_cpu_time
4586 real :: start, finish
4587 call cpu_time(start)
4588 ! put code to test here
4589 call cpu_time(finish)
4590 print '("Time = ",f6.3," seconds.")',finish-start
4591 end program test_cpu_time
4594 @item @emph{See also}:
4595 @ref{SYSTEM_CLOCK}, @*
4602 @section @code{CSHIFT} --- Circular shift elements of an array
4604 @cindex array, shift circularly
4605 @cindex array, permutation
4606 @cindex array, rotate
4609 @item @emph{Description}:
4610 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
4611 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
4612 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
4613 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
4614 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
4615 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
4616 sections of @var{ARRAY} along the given dimension are shifted. Elements
4617 shifted out one end of each rank one section are shifted back in the other end.
4619 @item @emph{Standard}:
4620 Fortran 90 and later
4623 Transformational function
4625 @item @emph{Syntax}:
4626 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
4628 @item @emph{Arguments}:
4629 @multitable @columnfractions .15 .70
4630 @item @var{ARRAY} @tab Shall be an array of any type.
4631 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
4632 @item @var{DIM} @tab The type shall be @code{INTEGER}.
4635 @item @emph{Return value}:
4636 Returns an array of same type and rank as the @var{ARRAY} argument.
4638 @item @emph{Example}:
4641 integer, dimension(3,3) :: a
4642 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
4643 print '(3i3)', a(1,:)
4644 print '(3i3)', a(2,:)
4645 print '(3i3)', a(3,:)
4646 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
4648 print '(3i3)', a(1,:)
4649 print '(3i3)', a(2,:)
4650 print '(3i3)', a(3,:)
4651 end program test_cshift
4658 @section @code{CTIME} --- Convert a time into a string
4660 @cindex time, conversion to string
4661 @cindex conversion, to string
4664 @item @emph{Description}:
4665 @code{CTIME} converts a system time value, such as returned by
4666 @ref{TIME8}, to a string. The output will be of the form @samp{Sat
4667 Aug 19 18:13:14 1995}.
4669 This intrinsic is provided in both subroutine and function forms; however,
4670 only one form can be used in any given program unit.
4672 @item @emph{Standard}:
4676 Subroutine, function
4678 @item @emph{Syntax}:
4679 @multitable @columnfractions .80
4680 @item @code{CALL CTIME(TIME, RESULT)}.
4681 @item @code{RESULT = CTIME(TIME)}.
4684 @item @emph{Arguments}:
4685 @multitable @columnfractions .15 .70
4686 @item @var{TIME} @tab The type shall be of type @code{INTEGER}.
4687 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
4688 of default kind. It is an @code{INTENT(OUT)} argument. If the length
4689 of this variable is too short for the time and date string to fit
4690 completely, it will be blank on procedure return.
4693 @item @emph{Return value}:
4694 The converted date and time as a string.
4696 @item @emph{Example}:
4700 character(len=30) :: date
4703 ! Do something, main part of the program
4706 print *, 'Program was started on ', date
4707 end program test_ctime
4710 @item @emph{See Also}:
4711 @ref{DATE_AND_TIME}, @*
4721 @section @code{DATE_AND_TIME} --- Date and time subroutine
4722 @fnindex DATE_AND_TIME
4723 @cindex date, current
4724 @cindex current date
4725 @cindex time, current
4726 @cindex current time
4729 @item @emph{Description}:
4730 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
4731 time information from the real-time system clock. @var{DATE} is
4732 @code{INTENT(OUT)} and of the form ccyymmdd. @var{TIME} is @code{INTENT(OUT)}
4733 and of the form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and of the form
4734 (+-)hhmm, representing the difference with respect to Coordinated Universal
4735 Time (UTC). Unavailable time and date parameters return blanks.
4737 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
4739 @multitable @columnfractions .15 .70
4740 @item @code{VALUES(1)}: @tab The year, including the century
4741 @item @code{VALUES(2)}: @tab The month of the year
4742 @item @code{VALUES(3)}: @tab The day of the month
4743 @item @code{VALUES(4)}: @tab The time difference from UTC in minutes
4744 @item @code{VALUES(5)}: @tab The hour of the day
4745 @item @code{VALUES(6)}: @tab The minutes of the hour
4746 @item @code{VALUES(7)}: @tab The seconds of the minute
4747 @item @code{VALUES(8)}: @tab The milliseconds of the second
4750 @item @emph{Standard}:
4751 Fortran 90 and later
4756 @item @emph{Syntax}:
4757 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
4759 @item @emph{Arguments}:
4760 @multitable @columnfractions .15 .70
4761 @item @var{DATE} @tab (Optional) Scalar of type default @code{CHARACTER}.
4762 Recommended length is 8 or larger.
4763 @item @var{TIME} @tab (Optional) Scalar of type default @code{CHARACTER}.
4764 Recommended length is 10 or larger.
4765 @item @var{ZONE} @tab (Optional) Scalar of type default @code{CHARACTER}.
4766 Recommended length is 5 or larger.
4767 @item @var{VALUES}@tab (Optional) Rank-1 array of type @code{INTEGER} with
4768 a decimal exponent range of at least four and array size at least 8.
4771 @item @emph{Return value}:
4774 @item @emph{Example}:
4776 program test_time_and_date
4777 character(8) :: date
4778 character(10) :: time
4779 character(5) :: zone
4780 integer,dimension(8) :: values
4781 ! using keyword arguments
4782 call date_and_time(date,time,zone,values)
4783 call date_and_time(DATE=date,ZONE=zone)
4784 call date_and_time(TIME=time)
4785 call date_and_time(VALUES=values)
4786 print '(a,2x,a,2x,a)', date, time, zone
4787 print '(8i5)', values
4788 end program test_time_and_date
4791 @item @emph{See also}:
4799 @section @code{DBLE} --- Double conversion function
4801 @cindex conversion, to real
4804 @item @emph{Description}:
4805 @code{DBLE(A)} Converts @var{A} to double precision real type.
4807 @item @emph{Standard}:
4808 Fortran 77 and later
4813 @item @emph{Syntax}:
4814 @code{RESULT = DBLE(A)}
4816 @item @emph{Arguments}:
4817 @multitable @columnfractions .15 .70
4818 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
4822 @item @emph{Return value}:
4823 The return value is of type double precision real.
4825 @item @emph{Example}:
4830 complex :: z = (2.3,1.14)
4831 print *, dble(x), dble(i), dble(z)
4832 end program test_dble
4835 @item @emph{See also}:
4842 @section @code{DCMPLX} --- Double complex conversion function
4844 @cindex complex numbers, conversion to
4845 @cindex conversion, to complex
4848 @item @emph{Description}:
4849 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
4850 converted to the real component. If @var{Y} is present it is converted to the
4851 imaginary component. If @var{Y} is not present then the imaginary component is
4852 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
4854 @item @emph{Standard}:
4860 @item @emph{Syntax}:
4861 @code{RESULT = DCMPLX(X [, Y])}
4863 @item @emph{Arguments}:
4864 @multitable @columnfractions .15 .70
4865 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
4867 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
4868 @code{INTEGER} or @code{REAL}.
4871 @item @emph{Return value}:
4872 The return value is of type @code{COMPLEX(8)}
4874 @item @emph{Example}:
4884 print *, dcmplx(x,i)
4885 end program test_dcmplx
4891 @section @code{DIGITS} --- Significant binary digits function
4893 @cindex model representation, significant digits
4896 @item @emph{Description}:
4897 @code{DIGITS(X)} returns the number of significant binary digits of the internal
4898 model representation of @var{X}. For example, on a system using a 32-bit
4899 floating point representation, a default real number would likely return 24.
4901 @item @emph{Standard}:
4902 Fortran 90 and later
4907 @item @emph{Syntax}:
4908 @code{RESULT = DIGITS(X)}
4910 @item @emph{Arguments}:
4911 @multitable @columnfractions .15 .70
4912 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
4915 @item @emph{Return value}:
4916 The return value is of type @code{INTEGER}.
4918 @item @emph{Example}:
4921 integer :: i = 12345
4927 end program test_digits
4934 @section @code{DIM} --- Positive difference
4938 @cindex positive difference
4941 @item @emph{Description}:
4942 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
4943 otherwise returns zero.
4945 @item @emph{Standard}:
4946 Fortran 77 and later
4951 @item @emph{Syntax}:
4952 @code{RESULT = DIM(X, Y)}
4954 @item @emph{Arguments}:
4955 @multitable @columnfractions .15 .70
4956 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
4957 @item @var{Y} @tab The type shall be the same type and kind as @var{X}. (As
4958 a GNU extension, arguments of different kinds are permitted.)
4961 @item @emph{Return value}:
4962 The return value is of type @code{INTEGER} or @code{REAL}. (As a GNU
4963 extension, kind is the largest kind of the actual arguments.)
4965 @item @emph{Example}:
4971 x = dim(4.345_8, 2.111_8)
4974 end program test_dim
4977 @item @emph{Specific names}:
4978 @multitable @columnfractions .20 .26 .20 .30
4979 @headitem Name @tab Argument @tab Return type @tab Standard
4980 @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
4981 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
4982 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
4989 @section @code{DOT_PRODUCT} --- Dot product function
4990 @fnindex DOT_PRODUCT
4992 @cindex vector product
4993 @cindex product, vector
4996 @item @emph{Description}:
4997 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
4998 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
4999 either numeric or logical and must be arrays of rank one and of equal size. If
5000 the vectors are @code{INTEGER} or @code{REAL}, the result is
5001 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
5002 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
5003 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
5005 @item @emph{Standard}:
5006 Fortran 90 and later
5009 Transformational function
5011 @item @emph{Syntax}:
5012 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
5014 @item @emph{Arguments}:
5015 @multitable @columnfractions .15 .70
5016 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
5017 @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.
5020 @item @emph{Return value}:
5021 If the arguments are numeric, the return value is a scalar of numeric type,
5022 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
5023 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
5025 @item @emph{Example}:
5027 program test_dot_prod
5028 integer, dimension(3) :: a, b
5035 print *, dot_product(a,b)
5036 end program test_dot_prod
5043 @section @code{DPROD} --- Double product function
5045 @cindex product, double-precision
5048 @item @emph{Description}:
5049 @code{DPROD(X,Y)} returns the product @code{X*Y}.
5051 @item @emph{Standard}:
5052 Fortran 77 and later
5057 @item @emph{Syntax}:
5058 @code{RESULT = DPROD(X, Y)}
5060 @item @emph{Arguments}:
5061 @multitable @columnfractions .15 .70
5062 @item @var{X} @tab The type shall be @code{REAL}.
5063 @item @var{Y} @tab The type shall be @code{REAL}.
5066 @item @emph{Return value}:
5067 The return value is of type @code{REAL(8)}.
5069 @item @emph{Example}:
5077 end program test_dprod
5080 @item @emph{Specific names}:
5081 @multitable @columnfractions .20 .23 .20 .33
5082 @headitem Name @tab Argument @tab Return type @tab Standard
5083 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
5090 @section @code{DREAL} --- Double real part function
5092 @cindex complex numbers, real part
5095 @item @emph{Description}:
5096 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
5098 @item @emph{Standard}:
5104 @item @emph{Syntax}:
5105 @code{RESULT = DREAL(A)}
5107 @item @emph{Arguments}:
5108 @multitable @columnfractions .15 .70
5109 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
5112 @item @emph{Return value}:
5113 The return value is of type @code{REAL(8)}.
5115 @item @emph{Example}:
5118 complex(8) :: z = (1.3_8,7.2_8)
5120 end program test_dreal
5123 @item @emph{See also}:
5131 @section @code{DSHIFTL} --- Combined left shift
5133 @cindex left shift, combined
5137 @item @emph{Description}:
5138 @code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
5139 rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
5140 bits of @var{J}, and the remaining bits are the rightmost bits of
5143 @item @emph{Standard}:
5144 Fortran 2008 and later
5149 @item @emph{Syntax}:
5150 @code{RESULT = DSHIFTL(I, J, SHIFT)}
5152 @item @emph{Arguments}:
5153 @multitable @columnfractions .15 .70
5154 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5155 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5156 If both @var{I} and @var{J} have integer type, then they shall have
5157 the same kind type parameter. @var{I} and @var{J} shall not both be
5159 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
5160 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
5161 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
5162 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
5165 @item @emph{Return value}:
5166 If either @var{I} or @var{J} is a BOZ constant, it is first converted
5167 as if by the intrinsic function @code{INT} to an integer type with the
5168 kind type parameter of the other.
5170 @item @emph{See also}:
5176 @section @code{DSHIFTR} --- Combined right shift
5178 @cindex right shift, combined
5179 @cindex shift, right
5182 @item @emph{Description}:
5183 @code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
5184 leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
5185 bits of @var{I}, and the remaining bits are the leftmost bits of
5188 @item @emph{Standard}:
5189 Fortran 2008 and later
5194 @item @emph{Syntax}:
5195 @code{RESULT = DSHIFTR(I, J, SHIFT)}
5197 @item @emph{Arguments}:
5198 @multitable @columnfractions .15 .70
5199 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5200 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5201 If both @var{I} and @var{J} have integer type, then they shall have
5202 the same kind type parameter. @var{I} and @var{J} shall not both be
5204 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
5205 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
5206 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
5207 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
5210 @item @emph{Return value}:
5211 If either @var{I} or @var{J} is a BOZ constant, it is first converted
5212 as if by the intrinsic function @code{INT} to an integer type with the
5213 kind type parameter of the other.
5215 @item @emph{See also}:
5221 @section @code{DTIME} --- Execution time subroutine (or function)
5223 @cindex time, elapsed
5224 @cindex elapsed time
5227 @item @emph{Description}:
5228 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
5229 since the start of the process's execution in @var{TIME}. @var{VALUES}
5230 returns the user and system components of this time in @code{VALUES(1)} and
5231 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
5234 Subsequent invocations of @code{DTIME} return values accumulated since the
5235 previous invocation.
5237 On some systems, the underlying timings are represented using types with
5238 sufficiently small limits that overflows (wrap around) are possible, such as
5239 32-bit types. Therefore, the values returned by this intrinsic might be, or
5240 become, negative, or numerically less than previous values, during a single
5241 run of the compiled program.
5243 Please note, that this implementation is thread safe if used within OpenMP
5244 directives, i.e., its state will be consistent while called from multiple
5245 threads. However, if @code{DTIME} is called from multiple threads, the result
5246 is still the time since the last invocation. This may not give the intended
5247 results. If possible, use @code{CPU_TIME} instead.
5249 This intrinsic is provided in both subroutine and function forms; however,
5250 only one form can be used in any given program unit.
5252 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
5254 @multitable @columnfractions .15 .70
5255 @item @code{VALUES(1)}: @tab User time in seconds.
5256 @item @code{VALUES(2)}: @tab System time in seconds.
5257 @item @code{TIME}: @tab Run time since start in seconds.
5260 @item @emph{Standard}:
5264 Subroutine, function
5266 @item @emph{Syntax}:
5267 @multitable @columnfractions .80
5268 @item @code{CALL DTIME(VALUES, TIME)}.
5269 @item @code{TIME = DTIME(VALUES)}, (not recommended).
5272 @item @emph{Arguments}:
5273 @multitable @columnfractions .15 .70
5274 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
5275 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
5278 @item @emph{Return value}:
5279 Elapsed time in seconds since the last invocation or since the start of program
5280 execution if not called before.
5282 @item @emph{Example}:
5286 real, dimension(2) :: tarray
5288 call dtime(tarray, result)
5292 do i=1,100000000 ! Just a delay
5295 call dtime(tarray, result)
5299 end program test_dtime
5302 @item @emph{See also}:
5310 @section @code{EOSHIFT} --- End-off shift elements of an array
5312 @cindex array, shift
5315 @item @emph{Description}:
5316 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
5317 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
5318 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
5319 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
5320 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
5321 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
5322 then all complete rank one sections of @var{ARRAY} along the given dimension are
5323 shifted. Elements shifted out one end of each rank one section are dropped. If
5324 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
5325 is copied back in the other end. If @var{BOUNDARY} is not present then the
5326 following are copied in depending on the type of @var{ARRAY}.
5328 @multitable @columnfractions .15 .80
5329 @item @emph{Array Type} @tab @emph{Boundary Value}
5330 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
5331 @item Logical @tab @code{.FALSE.}.
5332 @item Character(@var{len}) @tab @var{len} blanks.
5335 @item @emph{Standard}:
5336 Fortran 90 and later
5339 Transformational function
5341 @item @emph{Syntax}:
5342 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
5344 @item @emph{Arguments}:
5345 @multitable @columnfractions .15 .70
5346 @item @var{ARRAY} @tab May be any type, not scalar.
5347 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
5348 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
5349 @item @var{DIM} @tab The type shall be @code{INTEGER}.
5352 @item @emph{Return value}:
5353 Returns an array of same type and rank as the @var{ARRAY} argument.
5355 @item @emph{Example}:
5357 program test_eoshift
5358 integer, dimension(3,3) :: a
5359 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
5360 print '(3i3)', a(1,:)
5361 print '(3i3)', a(2,:)
5362 print '(3i3)', a(3,:)
5363 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
5365 print '(3i3)', a(1,:)
5366 print '(3i3)', a(2,:)
5367 print '(3i3)', a(3,:)
5368 end program test_eoshift
5375 @section @code{EPSILON} --- Epsilon function
5377 @cindex model representation, epsilon
5380 @item @emph{Description}:
5381 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
5382 as @var{X} such that @math{1 + E > 1}.
5384 @item @emph{Standard}:
5385 Fortran 90 and later
5390 @item @emph{Syntax}:
5391 @code{RESULT = EPSILON(X)}
5393 @item @emph{Arguments}:
5394 @multitable @columnfractions .15 .70
5395 @item @var{X} @tab The type shall be @code{REAL}.
5398 @item @emph{Return value}:
5399 The return value is of same type as the argument.
5401 @item @emph{Example}:
5403 program test_epsilon
5408 end program test_epsilon
5415 @section @code{ERF} --- Error function
5417 @cindex error function
5420 @item @emph{Description}:
5421 @code{ERF(X)} computes the error function of @var{X}.
5423 @item @emph{Standard}:
5424 Fortran 2008 and later
5429 @item @emph{Syntax}:
5430 @code{RESULT = ERF(X)}
5432 @item @emph{Arguments}:
5433 @multitable @columnfractions .15 .70
5434 @item @var{X} @tab The type shall be @code{REAL}.
5437 @item @emph{Return value}:
5438 The return value is of type @code{REAL}, of the same kind as
5439 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
5441 @item @emph{Example}:
5444 real(8) :: x = 0.17_8
5446 end program test_erf
5449 @item @emph{Specific names}:
5450 @multitable @columnfractions .20 .23 .20 .33
5451 @headitem Name @tab Argument @tab Return type @tab Standard
5452 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
5459 @section @code{ERFC} --- Error function
5461 @cindex error function, complementary
5464 @item @emph{Description}:
5465 @code{ERFC(X)} computes the complementary error function of @var{X}.
5467 @item @emph{Standard}:
5468 Fortran 2008 and later
5473 @item @emph{Syntax}:
5474 @code{RESULT = ERFC(X)}
5476 @item @emph{Arguments}:
5477 @multitable @columnfractions .15 .70
5478 @item @var{X} @tab The type shall be @code{REAL}.
5481 @item @emph{Return value}:
5482 The return value is of type @code{REAL} and of the same kind as @var{X}.
5483 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
5485 @item @emph{Example}:
5488 real(8) :: x = 0.17_8
5490 end program test_erfc
5493 @item @emph{Specific names}:
5494 @multitable @columnfractions .20 .23 .20 .33
5495 @headitem Name @tab Argument @tab Return type @tab Standard
5496 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
5503 @section @code{ERFC_SCALED} --- Error function
5504 @fnindex ERFC_SCALED
5505 @cindex error function, complementary, exponentially-scaled
5508 @item @emph{Description}:
5509 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
5510 error function of @var{X}.
5512 @item @emph{Standard}:
5513 Fortran 2008 and later
5518 @item @emph{Syntax}:
5519 @code{RESULT = ERFC_SCALED(X)}
5521 @item @emph{Arguments}:
5522 @multitable @columnfractions .15 .70
5523 @item @var{X} @tab The type shall be @code{REAL}.
5526 @item @emph{Return value}:
5527 The return value is of type @code{REAL} and of the same kind as @var{X}.
5529 @item @emph{Example}:
5531 program test_erfc_scaled
5532 real(8) :: x = 0.17_8
5534 end program test_erfc_scaled
5541 @section @code{ETIME} --- Execution time subroutine (or function)
5543 @cindex time, elapsed
5546 @item @emph{Description}:
5547 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
5548 since the start of the process's execution in @var{TIME}. @var{VALUES}
5549 returns the user and system components of this time in @code{VALUES(1)} and
5550 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
5552 On some systems, the underlying timings are represented using types with
5553 sufficiently small limits that overflows (wrap around) are possible, such as
5554 32-bit types. Therefore, the values returned by this intrinsic might be, or
5555 become, negative, or numerically less than previous values, during a single
5556 run of the compiled program.
5558 This intrinsic is provided in both subroutine and function forms; however,
5559 only one form can be used in any given program unit.
5561 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
5563 @multitable @columnfractions .15 .70
5564 @item @code{VALUES(1)}: @tab User time in seconds.
5565 @item @code{VALUES(2)}: @tab System time in seconds.
5566 @item @code{TIME}: @tab Run time since start in seconds.
5569 @item @emph{Standard}:
5573 Subroutine, function
5575 @item @emph{Syntax}:
5576 @multitable @columnfractions .80
5577 @item @code{CALL ETIME(VALUES, TIME)}.
5578 @item @code{TIME = ETIME(VALUES)}, (not recommended).
5581 @item @emph{Arguments}:
5582 @multitable @columnfractions .15 .70
5583 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
5584 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
5587 @item @emph{Return value}:
5588 Elapsed time in seconds since the start of program execution.
5590 @item @emph{Example}:
5594 real, dimension(2) :: tarray
5596 call ETIME(tarray, result)
5600 do i=1,100000000 ! Just a delay
5603 call ETIME(tarray, result)
5607 end program test_etime
5610 @item @emph{See also}:
5618 @section @code{EVENT_QUERY} --- Query whether a coarray event has occurred
5619 @fnindex EVENT_QUERY
5620 @cindex Events, EVENT_QUERY
5623 @item @emph{Description}:
5624 @code{EVENT_QUERY} assignes the number of events to @var{COUNT} which have been
5625 posted to the @var{EVENT} variable and not yet been removed by calling
5626 @code{EVENT WAIT}. When @var{STAT} is present and the invocation was successful,
5627 it is assigned the value 0. If it is present and the invocation has failed,
5628 it is assigned a positive value and @var{COUNT} is assigned the value @math{-1}.
5630 @item @emph{Standard}:
5636 @item @emph{Syntax}:
5637 @code{CALL EVENT_QUERY (EVENT, COUNT [, STAT])}
5639 @item @emph{Arguments}:
5640 @multitable @columnfractions .15 .70
5641 @item @var{EVENT} @tab (intent(IN)) Scalar of type @code{EVENT_TYPE},
5642 defined in @code{ISO_FORTRAN_ENV}; shall not be coindexed.
5643 @item @var{COUNT} @tab (intent(out))Scalar integer with at least the
5644 precision of default integer.
5645 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
5648 @item @emph{Example}:
5653 type(event_type) :: event_value_has_been_set[*]
5655 if (this_image() == 1) then
5656 call event_query (event_value_has_been_set, cnt)
5657 if (cnt > 0) write(*,*) "Value has been set"
5658 elseif (this_image() == 2) then
5659 event post (event_value_has_been_set[1])
5668 @node EXECUTE_COMMAND_LINE
5669 @section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
5670 @fnindex EXECUTE_COMMAND_LINE
5671 @cindex system, system call
5672 @cindex command line
5675 @item @emph{Description}:
5676 @code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
5679 The @code{COMMAND} argument is passed to the shell and executed (The
5680 shell is @code{sh} on Unix systems, and @code{cmd.exe} on Windows.).
5681 If @code{WAIT} is present and has the value false, the execution of
5682 the command is asynchronous if the system supports it; otherwise, the
5683 command is executed synchronously using the C library's @code{system}
5686 The three last arguments allow the user to get status information. After
5687 synchronous execution, @code{EXITSTAT} contains the integer exit code of
5688 the command, as returned by @code{system}. @code{CMDSTAT} is set to zero
5689 if the command line was executed (whatever its exit status was).
5690 @code{CMDMSG} is assigned an error message if an error has occurred.
5692 Note that the @code{system} function need not be thread-safe. It is
5693 the responsibility of the user to ensure that @code{system} is not
5694 called concurrently.
5696 For asynchronous execution on supported targets, the POSIX
5697 @code{posix_spawn} or @code{fork} functions are used. Also, a signal
5698 handler for the @code{SIGCHLD} signal is installed.
5700 @item @emph{Standard}:
5701 Fortran 2008 and later
5706 @item @emph{Syntax}:
5707 @code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
5709 @item @emph{Arguments}:
5710 @multitable @columnfractions .15 .70
5711 @item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
5712 @item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
5713 @item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5715 @item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5717 @item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
5721 @item @emph{Example}:
5726 call execute_command_line ("external_prog.exe", exitstat=i)
5727 print *, "Exit status of external_prog.exe was ", i
5729 call execute_command_line ("reindex_files.exe", wait=.false.)
5730 print *, "Now reindexing files in the background"
5732 end program test_exec
5738 Because this intrinsic is implemented in terms of the @code{system}
5739 function call, its behavior with respect to signaling is processor
5740 dependent. In particular, on POSIX-compliant systems, the SIGINT and
5741 SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
5742 such, if the parent process is terminated, the child process might not be
5743 terminated alongside.
5746 @item @emph{See also}:
5753 @section @code{EXIT} --- Exit the program with status.
5755 @cindex program termination
5756 @cindex terminate program
5759 @item @emph{Description}:
5760 @code{EXIT} causes immediate termination of the program with status. If status
5761 is omitted it returns the canonical @emph{success} for the system. All Fortran
5762 I/O units are closed.
5764 @item @emph{Standard}:
5770 @item @emph{Syntax}:
5771 @code{CALL EXIT([STATUS])}
5773 @item @emph{Arguments}:
5774 @multitable @columnfractions .15 .70
5775 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
5778 @item @emph{Return value}:
5779 @code{STATUS} is passed to the parent process on exit.
5781 @item @emph{Example}:
5784 integer :: STATUS = 0
5785 print *, 'This program is going to exit.'
5787 end program test_exit
5790 @item @emph{See also}:
5798 @section @code{EXP} --- Exponential function
5804 @cindex exponential function
5805 @cindex logarithm function, inverse
5808 @item @emph{Description}:
5809 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
5811 @item @emph{Standard}:
5812 Fortran 77 and later, has overloads that are GNU extensions
5817 @item @emph{Syntax}:
5818 @code{RESULT = EXP(X)}
5820 @item @emph{Arguments}:
5821 @multitable @columnfractions .15 .70
5822 @item @var{X} @tab The type shall be @code{REAL} or
5826 @item @emph{Return value}:
5827 The return value has same type and kind as @var{X}.
5829 @item @emph{Example}:
5834 end program test_exp
5837 @item @emph{Specific names}:
5838 @multitable @columnfractions .20 .23 .20 .33
5839 @headitem Name @tab Argument @tab Return type @tab Standard
5840 @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
5841 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
5842 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
5843 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5844 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5851 @section @code{EXPONENT} --- Exponent function
5853 @cindex real number, exponent
5854 @cindex floating point, exponent
5857 @item @emph{Description}:
5858 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
5859 is zero the value returned is zero.
5861 @item @emph{Standard}:
5862 Fortran 90 and later
5867 @item @emph{Syntax}:
5868 @code{RESULT = EXPONENT(X)}
5870 @item @emph{Arguments}:
5871 @multitable @columnfractions .15 .70
5872 @item @var{X} @tab The type shall be @code{REAL}.
5875 @item @emph{Return value}:
5876 The return value is of type default @code{INTEGER}.
5878 @item @emph{Example}:
5880 program test_exponent
5885 print *, exponent(0.0)
5886 end program test_exponent
5892 @node EXTENDS_TYPE_OF
5893 @section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension
5894 @fnindex EXTENDS_TYPE_OF
5897 @item @emph{Description}:
5898 Query dynamic type for extension.
5900 @item @emph{Standard}:
5901 Fortran 2003 and later
5906 @item @emph{Syntax}:
5907 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
5909 @item @emph{Arguments}:
5910 @multitable @columnfractions .15 .70
5911 @item @var{A} @tab Shall be an object of extensible declared type or
5912 unlimited polymorphic.
5913 @item @var{MOLD} @tab Shall be an object of extensible declared type or
5914 unlimited polymorphic.
5917 @item @emph{Return value}:
5918 The return value is a scalar of type default logical. It is true if and only if
5919 the dynamic type of A is an extension type of the dynamic type of MOLD.
5922 @item @emph{See also}:
5929 @section @code{FDATE} --- Get the current time as a string
5931 @cindex time, current
5932 @cindex current time
5933 @cindex date, current
5934 @cindex current date
5937 @item @emph{Description}:
5938 @code{FDATE(DATE)} returns the current date (using the same format as
5939 @ref{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
5942 This intrinsic is provided in both subroutine and function forms; however,
5943 only one form can be used in any given program unit.
5945 @item @emph{Standard}:
5949 Subroutine, function
5951 @item @emph{Syntax}:
5952 @multitable @columnfractions .80
5953 @item @code{CALL FDATE(DATE)}.
5954 @item @code{DATE = FDATE()}.
5957 @item @emph{Arguments}:
5958 @multitable @columnfractions .15 .70
5959 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
5960 default kind. It is an @code{INTENT(OUT)} argument. If the length of
5961 this variable is too short for the date and time string to fit
5962 completely, it will be blank on procedure return.
5965 @item @emph{Return value}:
5966 The current date and time as a string.
5968 @item @emph{Example}:
5972 character(len=30) :: date
5974 print *, 'Program started on ', date
5975 do i = 1, 100000000 ! Just a delay
5979 print *, 'Program ended on ', date
5980 end program test_fdate
5983 @item @emph{See also}:
5984 @ref{DATE_AND_TIME}, @*
5990 @section @code{FGET} --- Read a single character in stream mode from stdin
5992 @cindex read character, stream mode
5993 @cindex stream mode, read character
5994 @cindex file operation, read character
5997 @item @emph{Description}:
5998 Read a single character in stream mode from stdin by bypassing normal
5999 formatted output. Stream I/O should not be mixed with normal record-oriented
6000 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
6002 This intrinsic is provided in both subroutine and function forms; however,
6003 only one form can be used in any given program unit.
6005 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
6006 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
6007 Programmers should consider the use of new stream IO feature in new code
6008 for future portability. See also @ref{Fortran 2003 status}.
6010 @item @emph{Standard}:
6014 Subroutine, function
6016 @item @emph{Syntax}:
6017 @multitable @columnfractions .80
6018 @item @code{CALL FGET(C [, STATUS])}
6019 @item @code{STATUS = FGET(C)}
6022 @item @emph{Arguments}:
6023 @multitable @columnfractions .15 .70
6024 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6026 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6027 Returns 0 on success, -1 on end-of-file, and a system specific positive
6028 error code otherwise.
6031 @item @emph{Example}:
6034 INTEGER, PARAMETER :: strlen = 100
6035 INTEGER :: status, i = 1
6036 CHARACTER(len=strlen) :: str = ""
6038 WRITE (*,*) 'Enter text:'
6040 CALL fget(str(i:i), status)
6041 if (status /= 0 .OR. i > strlen) exit
6044 WRITE (*,*) TRIM(str)
6048 @item @emph{See also}:
6057 @section @code{FGETC} --- Read a single character in stream mode
6059 @cindex read character, stream mode
6060 @cindex stream mode, read character
6061 @cindex file operation, read character
6064 @item @emph{Description}:
6065 Read a single character in stream mode by bypassing normal formatted output.
6066 Stream I/O should not be mixed with normal record-oriented (formatted or
6067 unformatted) I/O on the same unit; the results are unpredictable.
6069 This intrinsic is provided in both subroutine and function forms; however,
6070 only one form can be used in any given program unit.
6072 Note that the @code{FGET} intrinsic is provided for backwards compatibility
6073 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
6074 Programmers should consider the use of new stream IO feature in new code
6075 for future portability. See also @ref{Fortran 2003 status}.
6077 @item @emph{Standard}:
6081 Subroutine, function
6083 @item @emph{Syntax}:
6084 @multitable @columnfractions .80
6085 @item @code{CALL FGETC(UNIT, C [, STATUS])}
6086 @item @code{STATUS = FGETC(UNIT, C)}
6089 @item @emph{Arguments}:
6090 @multitable @columnfractions .15 .70
6091 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
6092 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6094 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6095 Returns 0 on success, -1 on end-of-file and a system specific positive
6096 error code otherwise.
6099 @item @emph{Example}:
6102 INTEGER :: fd = 42, status
6105 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
6107 CALL fgetc(fd, c, status)
6108 IF (status /= 0) EXIT
6115 @item @emph{See also}:
6122 @section @code{FINDLOC} --- Search an array for a value
6127 @item @emph{Description}:
6128 Determines the location of the element in the array with the value
6129 given in the @var{VALUE} argument, or, if the @var{DIM} argument is
6130 supplied, determines the locations of the elements equal to the
6131 @var{VALUE} argument element along each
6132 row of the array in the @var{DIM} direction. If @var{MASK} is
6133 present, only the elements for which @var{MASK} is @code{.TRUE.} are
6134 considered. If more than one element in the array has the value
6135 @var{VALUE}, the location returned is that of the first such element
6136 in array element order if the @var{BACK} is not present or if it is
6137 @code{.FALSE.}. If @var{BACK} is true, the location returned is that
6138 of the last such element. If the array has zero size, or all of the
6139 elements of @var{MASK} are @code{.FALSE.}, then the result is an array
6140 of zeroes. Similarly, if @var{DIM} is supplied and all of the
6141 elements of @var{MASK} along a given row are zero, the result value
6142 for that row is zero.
6144 @item @emph{Standard}:
6145 Fortran 2008 and later.
6148 Transformational function
6150 @item @emph{Syntax}:
6151 @multitable @columnfractions .80
6152 @item @code{RESULT = FINDLOC(ARRAY, VALUE, DIM [, MASK] [,KIND] [,BACK])}
6153 @item @code{RESULT = FINDLOC(ARRAY, VALUE, [, MASK] [,KIND] [,BACK])}
6156 @item @emph{Arguments}:
6157 @multitable @columnfractions .15 .70
6158 @item @var{ARRAY} @tab Shall be an array of intrinsic type.
6159 @item @var{VALUE} @tab A scalar of intrinsic type which is in type
6160 conformance with @var{ARRAY}.
6161 @item @var{DIM} @tab (Optional) Shall be a scalar of type
6162 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
6163 inclusive. It may not be an optional dummy argument.
6164 @item @var{MASK} @tab (Optional) Shall be of type @code{LOGICAL},
6165 and conformable with @var{ARRAY}.
6166 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
6167 expression indicating the kind parameter of the result.
6168 @item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}.
6171 @item @emph{Return value}:
6172 If @var{DIM} is absent, the result is a rank-one array with a length
6173 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
6174 is an array with a rank one less than the rank of @var{ARRAY}, and a
6175 size corresponding to the size of @var{ARRAY} with the @var{DIM}
6176 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
6177 of one, the result is a scalar. If the optional argument @var{KIND}
6178 is present, the result is an integer of kind @var{KIND}, otherwise it
6181 @item @emph{See also}:
6188 @section @code{FLOOR} --- Integer floor function
6191 @cindex rounding, floor
6194 @item @emph{Description}:
6195 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{A}.
6197 @item @emph{Standard}:
6198 Fortran 95 and later
6203 @item @emph{Syntax}:
6204 @code{RESULT = FLOOR(A [, KIND])}
6206 @item @emph{Arguments}:
6207 @multitable @columnfractions .15 .70
6208 @item @var{A} @tab The type shall be @code{REAL}.
6209 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
6210 expression indicating the kind parameter of the result.
6213 @item @emph{Return value}:
6214 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
6215 and of default-kind @code{INTEGER} otherwise.
6217 @item @emph{Example}:
6222 print *, floor(x) ! returns 63
6223 print *, floor(y) ! returns -64
6224 end program test_floor
6227 @item @emph{See also}:
6235 @section @code{FLUSH} --- Flush I/O unit(s)
6237 @cindex file operation, flush
6240 @item @emph{Description}:
6241 Flushes Fortran unit(s) currently open for output. Without the optional
6242 argument, all units are flushed, otherwise just the unit specified.
6244 @item @emph{Standard}:
6250 @item @emph{Syntax}:
6251 @code{CALL FLUSH(UNIT)}
6253 @item @emph{Arguments}:
6254 @multitable @columnfractions .15 .70
6255 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
6259 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
6260 statement that should be preferred over the @code{FLUSH} intrinsic.
6262 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
6263 have identical effect: they flush the runtime library's I/O buffer so
6264 that the data becomes visible to other processes. This does not guarantee
6265 that the data is committed to disk.
6267 On POSIX systems, you can request that all data is transferred to the
6268 storage device by calling the @code{fsync} function, with the POSIX file
6269 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
6270 @code{FNUM}). The following example shows how:
6273 ! Declare the interface for POSIX fsync function
6275 function fsync (fd) bind(c,name="fsync")
6276 use iso_c_binding, only: c_int
6277 integer(c_int), value :: fd
6278 integer(c_int) :: fsync
6282 ! Variable declaration
6286 open (10,file="foo")
6289 ! Perform I/O on unit 10
6294 ret = fsync(fnum(10))
6296 ! Handle possible error
6297 if (ret /= 0) stop "Error calling FSYNC"
6305 @section @code{FNUM} --- File number function
6307 @cindex file operation, file number
6310 @item @emph{Description}:
6311 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
6312 open Fortran I/O unit @code{UNIT}.
6314 @item @emph{Standard}:
6320 @item @emph{Syntax}:
6321 @code{RESULT = FNUM(UNIT)}
6323 @item @emph{Arguments}:
6324 @multitable @columnfractions .15 .70
6325 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
6328 @item @emph{Return value}:
6329 The return value is of type @code{INTEGER}
6331 @item @emph{Example}:
6335 open (unit=10, status = "scratch")
6339 end program test_fnum
6346 @section @code{FPUT} --- Write a single character in stream mode to stdout
6348 @cindex write character, stream mode
6349 @cindex stream mode, write character
6350 @cindex file operation, write character
6353 @item @emph{Description}:
6354 Write a single character in stream mode to stdout by bypassing normal
6355 formatted output. Stream I/O should not be mixed with normal record-oriented
6356 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
6358 This intrinsic is provided in both subroutine and function forms; however,
6359 only one form can be used in any given program unit.
6361 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
6362 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
6363 Programmers should consider the use of new stream IO feature in new code
6364 for future portability. See also @ref{Fortran 2003 status}.
6366 @item @emph{Standard}:
6370 Subroutine, function
6372 @item @emph{Syntax}:
6373 @multitable @columnfractions .80
6374 @item @code{CALL FPUT(C [, STATUS])}
6375 @item @code{STATUS = FPUT(C)}
6378 @item @emph{Arguments}:
6379 @multitable @columnfractions .15 .70
6380 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6382 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6383 Returns 0 on success, -1 on end-of-file and a system specific positive
6384 error code otherwise.
6387 @item @emph{Example}:
6390 CHARACTER(len=10) :: str = "gfortran"
6392 DO i = 1, len_trim(str)
6398 @item @emph{See also}:
6407 @section @code{FPUTC} --- Write a single character in stream mode
6409 @cindex write character, stream mode
6410 @cindex stream mode, write character
6411 @cindex file operation, write character
6414 @item @emph{Description}:
6415 Write a single character in stream mode by bypassing normal formatted
6416 output. Stream I/O should not be mixed with normal record-oriented
6417 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
6419 This intrinsic is provided in both subroutine and function forms; however,
6420 only one form can be used in any given program unit.
6422 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
6423 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
6424 Programmers should consider the use of new stream IO feature in new code
6425 for future portability. See also @ref{Fortran 2003 status}.
6427 @item @emph{Standard}:
6431 Subroutine, function
6433 @item @emph{Syntax}:
6434 @multitable @columnfractions .80
6435 @item @code{CALL FPUTC(UNIT, C [, STATUS])}
6436 @item @code{STATUS = FPUTC(UNIT, C)}
6439 @item @emph{Arguments}:
6440 @multitable @columnfractions .15 .70
6441 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
6442 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6444 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6445 Returns 0 on success, -1 on end-of-file and a system specific positive
6446 error code otherwise.
6449 @item @emph{Example}:
6452 CHARACTER(len=10) :: str = "gfortran"
6453 INTEGER :: fd = 42, i
6455 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
6456 DO i = 1, len_trim(str)
6457 CALL fputc(fd, str(i:i))
6463 @item @emph{See also}:
6472 @section @code{FRACTION} --- Fractional part of the model representation
6474 @cindex real number, fraction
6475 @cindex floating point, fraction
6478 @item @emph{Description}:
6479 @code{FRACTION(X)} returns the fractional part of the model
6480 representation of @code{X}.
6482 @item @emph{Standard}:
6483 Fortran 90 and later
6488 @item @emph{Syntax}:
6489 @code{Y = FRACTION(X)}
6491 @item @emph{Arguments}:
6492 @multitable @columnfractions .15 .70
6493 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
6496 @item @emph{Return value}:
6497 The return value is of the same type and kind as the argument.
6498 The fractional part of the model representation of @code{X} is returned;
6499 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
6501 @item @emph{Example}:
6503 program test_fraction
6506 print *, fraction(x), x * radix(x)**(-exponent(x))
6507 end program test_fraction
6515 @section @code{FREE} --- Frees memory
6517 @cindex pointer, cray
6520 @item @emph{Description}:
6521 Frees memory previously allocated by @code{MALLOC}. The @code{FREE}
6522 intrinsic is an extension intended to be used with Cray pointers, and is
6523 provided in GNU Fortran to allow user to compile legacy code. For
6524 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
6527 @item @emph{Standard}:
6533 @item @emph{Syntax}:
6534 @code{CALL FREE(PTR)}
6536 @item @emph{Arguments}:
6537 @multitable @columnfractions .15 .70
6538 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
6539 location of the memory that should be de-allocated.
6542 @item @emph{Return value}:
6545 @item @emph{Example}:
6546 See @code{MALLOC} for an example.
6548 @item @emph{See also}:
6555 @section @code{FSEEK} --- Low level file positioning subroutine
6557 @cindex file operation, seek
6558 @cindex file operation, position
6561 @item @emph{Description}:
6562 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
6563 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
6564 if set to 1, @var{OFFSET} is taken to be relative to the current position
6565 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
6566 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
6569 This intrinsic routine is not fully backwards compatible with @command{g77}.
6570 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
6571 @var{STATUS} variable. If FSEEK is used in old code, change
6573 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
6578 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
6579 IF (status /= 0) GOTO label
6582 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
6583 Programmers should consider the use of new stream IO feature in new code
6584 for future portability. See also @ref{Fortran 2003 status}.
6586 @item @emph{Standard}:
6592 @item @emph{Syntax}:
6593 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
6595 @item @emph{Arguments}:
6596 @multitable @columnfractions .15 .70
6597 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
6598 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
6599 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
6600 Its value shall be either 0, 1 or 2.
6601 @item @var{STATUS} @tab (Optional) shall be a scalar of type
6605 @item @emph{Example}:
6608 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
6609 INTEGER :: fd, offset, ierr
6615 OPEN(UNIT=fd, FILE="fseek.test")
6616 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
6617 print *, FTELL(fd), ierr
6619 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
6620 print *, FTELL(fd), ierr
6622 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
6623 print *, FTELL(fd), ierr
6629 @item @emph{See also}:
6636 @section @code{FSTAT} --- Get file status
6638 @cindex file system, file status
6641 @item @emph{Description}:
6642 @code{FSTAT} is identical to @ref{STAT}, except that information about an
6643 already opened file is obtained.
6645 The elements in @code{VALUES} are the same as described by @ref{STAT}.
6647 This intrinsic is provided in both subroutine and function forms; however,
6648 only one form can be used in any given program unit.
6650 @item @emph{Standard}:
6654 Subroutine, function
6656 @item @emph{Syntax}:
6657 @multitable @columnfractions .80
6658 @item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
6659 @item @code{STATUS = FSTAT(UNIT, VALUES)}
6662 @item @emph{Arguments}:
6663 @multitable @columnfractions .15 .70
6664 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
6665 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
6666 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
6667 on success and a system specific error code otherwise.
6670 @item @emph{Example}:
6671 See @ref{STAT} for an example.
6673 @item @emph{See also}:
6683 @section @code{FTELL} --- Current stream position
6685 @cindex file operation, position
6688 @item @emph{Description}:
6689 Retrieves the current position within an open file.
6691 This intrinsic is provided in both subroutine and function forms; however,
6692 only one form can be used in any given program unit.
6694 @item @emph{Standard}:
6698 Subroutine, function
6700 @item @emph{Syntax}:
6701 @multitable @columnfractions .80
6702 @item @code{CALL FTELL(UNIT, OFFSET)}
6703 @item @code{OFFSET = FTELL(UNIT)}
6706 @item @emph{Arguments}:
6707 @multitable @columnfractions .15 .70
6708 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
6709 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
6712 @item @emph{Return value}:
6713 In either syntax, @var{OFFSET} is set to the current offset of unit
6714 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
6716 @item @emph{Example}:
6720 OPEN(10, FILE="temp.dat")
6726 @item @emph{See also}:
6733 @section @code{GAMMA} --- Gamma function
6736 @cindex Gamma function
6737 @cindex Factorial function
6740 @item @emph{Description}:
6741 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
6742 integer values of @var{X} the Gamma function simplifies to the factorial
6743 function @math{\Gamma(x)=(x-1)!}.
6747 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
6751 @item @emph{Standard}:
6752 Fortran 2008 and later
6757 @item @emph{Syntax}:
6760 @item @emph{Arguments}:
6761 @multitable @columnfractions .15 .70
6762 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
6763 nor a negative integer.
6766 @item @emph{Return value}:
6767 The return value is of type @code{REAL} of the same kind as @var{X}.
6769 @item @emph{Example}:
6773 x = gamma(x) ! returns 1.0
6774 end program test_gamma
6777 @item @emph{Specific names}:
6778 @multitable @columnfractions .20 .23 .20 .33
6779 @headitem Name @tab Argument @tab Return type @tab Standard
6780 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
6783 @item @emph{See also}:
6784 Logarithm of the Gamma function: @*
6791 @section @code{GERROR} --- Get last system error message
6793 @cindex system, error handling
6796 @item @emph{Description}:
6797 Returns the system error message corresponding to the last system error.
6798 This resembles the functionality of @code{strerror(3)} in C.
6800 @item @emph{Standard}:
6806 @item @emph{Syntax}:
6807 @code{CALL GERROR(RESULT)}
6809 @item @emph{Arguments}:
6810 @multitable @columnfractions .15 .70
6811 @item @var{RESULT} @tab Shall be of type @code{CHARACTER} and of default kind.
6814 @item @emph{Example}:
6817 CHARACTER(len=100) :: msg
6823 @item @emph{See also}:
6831 @section @code{GETARG} --- Get command line arguments
6833 @cindex command-line arguments
6834 @cindex arguments, to program
6837 @item @emph{Description}:
6838 Retrieve the @var{POS}-th argument that was passed on the
6839 command line when the containing program was invoked.
6841 This intrinsic routine is provided for backwards compatibility with
6842 GNU Fortran 77. In new code, programmers should consider the use of
6843 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
6846 @item @emph{Standard}:
6852 @item @emph{Syntax}:
6853 @code{CALL GETARG(POS, VALUE)}
6855 @item @emph{Arguments}:
6856 @multitable @columnfractions .15 .70
6857 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
6858 the default integer kind; @math{@var{POS} \geq 0}
6859 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
6863 @item @emph{Return value}:
6864 After @code{GETARG} returns, the @var{VALUE} argument holds the
6865 @var{POS}th command line argument. If @var{VALUE} cannot hold the
6866 argument, it is truncated to fit the length of @var{VALUE}. If there are
6867 less than @var{POS} arguments specified at the command line, @var{VALUE}
6868 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
6869 to the name of the program (on systems that support this feature).
6871 @item @emph{Example}:
6875 CHARACTER(len=32) :: arg
6884 @item @emph{See also}:
6885 GNU Fortran 77 compatibility function: @*
6887 Fortran 2003 functions and subroutines: @*
6888 @ref{GET_COMMAND}, @*
6889 @ref{GET_COMMAND_ARGUMENT}, @*
6890 @ref{COMMAND_ARGUMENT_COUNT}
6896 @section @code{GET_COMMAND} --- Get the entire command line
6897 @fnindex GET_COMMAND
6898 @cindex command-line arguments
6899 @cindex arguments, to program
6902 @item @emph{Description}:
6903 Retrieve the entire command line that was used to invoke the program.
6905 @item @emph{Standard}:
6906 Fortran 2003 and later
6911 @item @emph{Syntax}:
6912 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
6914 @item @emph{Arguments}:
6915 @multitable @columnfractions .15 .70
6916 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
6918 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
6920 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
6924 @item @emph{Return value}:
6925 If @var{COMMAND} is present, stores the entire command line that was used
6926 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
6927 assigned the length of the command line. If @var{STATUS} is present, it
6928 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
6929 short to store the command line, or a positive value in case of an error.
6931 @item @emph{Example}:
6933 PROGRAM test_get_command
6934 CHARACTER(len=255) :: cmd
6935 CALL get_command(cmd)
6936 WRITE (*,*) TRIM(cmd)
6940 @item @emph{See also}:
6941 @ref{GET_COMMAND_ARGUMENT}, @*
6942 @ref{COMMAND_ARGUMENT_COUNT}
6947 @node GET_COMMAND_ARGUMENT
6948 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
6949 @fnindex GET_COMMAND_ARGUMENT
6950 @cindex command-line arguments
6951 @cindex arguments, to program
6954 @item @emph{Description}:
6955 Retrieve the @var{NUMBER}-th argument that was passed on the
6956 command line when the containing program was invoked.
6958 @item @emph{Standard}:
6959 Fortran 2003 and later
6964 @item @emph{Syntax}:
6965 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
6967 @item @emph{Arguments}:
6968 @multitable @columnfractions .15 .70
6969 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
6970 default kind, @math{@var{NUMBER} \geq 0}
6971 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
6972 and of default kind.
6973 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6974 and of default kind.
6975 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6976 and of default kind.
6979 @item @emph{Return value}:
6980 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
6981 @var{NUMBER}-th command line argument. If @var{VALUE} cannot hold the argument, it is
6982 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
6983 arguments specified at the command line, @var{VALUE} will be filled with blanks.
6984 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
6985 systems that support this feature). The @var{LENGTH} argument contains the
6986 length of the @var{NUMBER}-th command line argument. If the argument retrieval
6987 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
6988 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
6991 @item @emph{Example}:
6993 PROGRAM test_get_command_argument
6995 CHARACTER(len=32) :: arg
6999 CALL get_command_argument(i, arg)
7000 IF (LEN_TRIM(arg) == 0) EXIT
7002 WRITE (*,*) TRIM(arg)
7008 @item @emph{See also}:
7009 @ref{GET_COMMAND}, @*
7010 @ref{COMMAND_ARGUMENT_COUNT}
7016 @section @code{GETCWD} --- Get current working directory
7018 @cindex system, working directory
7021 @item @emph{Description}:
7022 Get current working directory.
7024 This intrinsic is provided in both subroutine and function forms; however,
7025 only one form can be used in any given program unit.
7027 @item @emph{Standard}:
7031 Subroutine, function
7033 @item @emph{Syntax}:
7034 @multitable @columnfractions .80
7035 @item @code{CALL GETCWD(C [, STATUS])}
7036 @item @code{STATUS = GETCWD(C)}
7039 @item @emph{Arguments}:
7040 @multitable @columnfractions .15 .70
7041 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
7042 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
7043 a system specific and nonzero error code otherwise.
7046 @item @emph{Example}:
7049 CHARACTER(len=255) :: cwd
7051 WRITE(*,*) TRIM(cwd)
7055 @item @emph{See also}:
7062 @section @code{GETENV} --- Get an environmental variable
7064 @cindex environment variable
7067 @item @emph{Description}:
7068 Get the @var{VALUE} of the environmental variable @var{NAME}.
7070 This intrinsic routine is provided for backwards compatibility with
7071 GNU Fortran 77. In new code, programmers should consider the use of
7072 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
7075 Note that @code{GETENV} need not be thread-safe. It is the
7076 responsibility of the user to ensure that the environment is not being
7077 updated concurrently with a call to the @code{GETENV} intrinsic.
7079 @item @emph{Standard}:
7085 @item @emph{Syntax}:
7086 @code{CALL GETENV(NAME, VALUE)}
7088 @item @emph{Arguments}:
7089 @multitable @columnfractions .15 .70
7090 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
7091 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
7094 @item @emph{Return value}:
7095 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
7096 not large enough to hold the data, it is truncated. If @var{NAME}
7097 is not set, @var{VALUE} will be filled with blanks.
7099 @item @emph{Example}:
7102 CHARACTER(len=255) :: homedir
7103 CALL getenv("HOME", homedir)
7104 WRITE (*,*) TRIM(homedir)
7108 @item @emph{See also}:
7109 @ref{GET_ENVIRONMENT_VARIABLE}
7114 @node GET_ENVIRONMENT_VARIABLE
7115 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
7116 @fnindex GET_ENVIRONMENT_VARIABLE
7117 @cindex environment variable
7120 @item @emph{Description}:
7121 Get the @var{VALUE} of the environmental variable @var{NAME}.
7123 Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It
7124 is the responsibility of the user to ensure that the environment is
7125 not being updated concurrently with a call to the
7126 @code{GET_ENVIRONMENT_VARIABLE} intrinsic.
7128 @item @emph{Standard}:
7129 Fortran 2003 and later
7134 @item @emph{Syntax}:
7135 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
7137 @item @emph{Arguments}:
7138 @multitable @columnfractions .15 .70
7139 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
7140 and of default kind.
7141 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
7142 and of default kind.
7143 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
7144 and of default kind.
7145 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
7146 and of default kind.
7147 @item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL}
7148 and of default kind.
7151 @item @emph{Return value}:
7152 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
7153 not large enough to hold the data, it is truncated. If @var{NAME}
7154 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
7155 contains the length needed for storing the environment variable @var{NAME}
7156 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
7157 but too short for the environment variable; it is 1 if the environment
7158 variable does not exist and 2 if the processor does not support environment
7159 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
7160 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
7161 are significant; otherwise they are not part of the environment variable
7164 @item @emph{Example}:
7167 CHARACTER(len=255) :: homedir
7168 CALL get_environment_variable("HOME", homedir)
7169 WRITE (*,*) TRIM(homedir)
7177 @section @code{GETGID} --- Group ID function
7179 @cindex system, group ID
7182 @item @emph{Description}:
7183 Returns the numerical group ID of the current process.
7185 @item @emph{Standard}:
7191 @item @emph{Syntax}:
7192 @code{RESULT = GETGID()}
7194 @item @emph{Return value}:
7195 The return value of @code{GETGID} is an @code{INTEGER} of the default
7199 @item @emph{Example}:
7200 See @code{GETPID} for an example.
7202 @item @emph{See also}:
7210 @section @code{GETLOG} --- Get login name
7212 @cindex system, login name
7216 @item @emph{Description}:
7217 Gets the username under which the program is running.
7219 @item @emph{Standard}:
7225 @item @emph{Syntax}:
7226 @code{CALL GETLOG(C)}
7228 @item @emph{Arguments}:
7229 @multitable @columnfractions .15 .70
7230 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
7233 @item @emph{Return value}:
7234 Stores the current user name in @var{C}. (On systems where POSIX
7235 functions @code{geteuid} and @code{getpwuid} are not available, and
7236 the @code{getlogin} function is not implemented either, this will
7237 return a blank string.)
7239 @item @emph{Example}:
7242 CHARACTER(32) :: login
7248 @item @emph{See also}:
7255 @section @code{GETPID} --- Process ID function
7257 @cindex system, process ID
7261 @item @emph{Description}:
7262 Returns the numerical process identifier of the current process.
7264 @item @emph{Standard}:
7270 @item @emph{Syntax}:
7271 @code{RESULT = GETPID()}
7273 @item @emph{Return value}:
7274 The return value of @code{GETPID} is an @code{INTEGER} of the default
7278 @item @emph{Example}:
7281 print *, "The current process ID is ", getpid()
7282 print *, "Your numerical user ID is ", getuid()
7283 print *, "Your numerical group ID is ", getgid()
7287 @item @emph{See also}:
7295 @section @code{GETUID} --- User ID function
7297 @cindex system, user ID
7301 @item @emph{Description}:
7302 Returns the numerical user ID of the current process.
7304 @item @emph{Standard}:
7310 @item @emph{Syntax}:
7311 @code{RESULT = GETUID()}
7313 @item @emph{Return value}:
7314 The return value of @code{GETUID} is an @code{INTEGER} of the default
7318 @item @emph{Example}:
7319 See @code{GETPID} for an example.
7321 @item @emph{See also}:
7329 @section @code{GMTIME} --- Convert time to GMT info
7331 @cindex time, conversion to GMT info
7334 @item @emph{Description}:
7335 Given a system time value @var{TIME} (as provided by the @ref{TIME}
7336 intrinsic), fills @var{VALUES} with values extracted from it appropriate
7337 to the UTC time zone (Universal Coordinated Time, also known in some
7338 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
7340 This intrinsic routine is provided for backwards compatibility with
7341 GNU Fortran 77. In new code, programmers should consider the use of
7342 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
7345 @item @emph{Standard}:
7351 @item @emph{Syntax}:
7352 @code{CALL GMTIME(TIME, VALUES)}
7354 @item @emph{Arguments}:
7355 @multitable @columnfractions .15 .70
7356 @item @var{TIME} @tab An @code{INTEGER} scalar expression
7357 corresponding to a system time, with @code{INTENT(IN)}.
7358 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
7359 with @code{INTENT(OUT)}.
7362 @item @emph{Return value}:
7363 The elements of @var{VALUES} are assigned as follows:
7365 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
7367 @item Minutes after the hour, range 0--59
7368 @item Hours past midnight, range 0--23
7369 @item Day of month, range 1--31
7370 @item Number of months since January, range 0--11
7371 @item Years since 1900
7372 @item Number of days since Sunday, range 0--6
7373 @item Days since January 1, range 0--365
7374 @item Daylight savings indicator: positive if daylight savings is in
7375 effect, zero if not, and negative if the information is not available.
7378 @item @emph{See also}:
7379 @ref{DATE_AND_TIME}, @*
7389 @section @code{HOSTNM} --- Get system host name
7391 @cindex system, host name
7394 @item @emph{Description}:
7395 Retrieves the host name of the system on which the program is running.
7397 This intrinsic is provided in both subroutine and function forms; however,
7398 only one form can be used in any given program unit.
7400 @item @emph{Standard}:
7404 Subroutine, function
7406 @item @emph{Syntax}:
7407 @multitable @columnfractions .80
7408 @item @code{CALL HOSTNM(C [, STATUS])}
7409 @item @code{STATUS = HOSTNM(NAME)}
7412 @item @emph{Arguments}:
7413 @multitable @columnfractions .15 .70
7414 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
7415 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
7416 Returns 0 on success, or a system specific error code otherwise.
7419 @item @emph{Return value}:
7420 In either syntax, @var{NAME} is set to the current hostname if it can
7421 be obtained, or to a blank string otherwise.
7428 @section @code{HUGE} --- Largest number of a kind
7430 @cindex limits, largest number
7431 @cindex model representation, largest number
7434 @item @emph{Description}:
7435 @code{HUGE(X)} returns the largest number that is not an infinity in
7436 the model of the type of @code{X}.
7438 @item @emph{Standard}:
7439 Fortran 90 and later
7444 @item @emph{Syntax}:
7445 @code{RESULT = HUGE(X)}
7447 @item @emph{Arguments}:
7448 @multitable @columnfractions .15 .70
7449 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
7452 @item @emph{Return value}:
7453 The return value is of the same type and kind as @var{X}
7455 @item @emph{Example}:
7457 program test_huge_tiny
7458 print *, huge(0), huge(0.0), huge(0.0d0)
7459 print *, tiny(0.0), tiny(0.0d0)
7460 end program test_huge_tiny
7467 @section @code{HYPOT} --- Euclidean distance function
7469 @cindex Euclidean distance
7472 @item @emph{Description}:
7473 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
7474 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
7476 @item @emph{Standard}:
7477 Fortran 2008 and later
7482 @item @emph{Syntax}:
7483 @code{RESULT = HYPOT(X, Y)}
7485 @item @emph{Arguments}:
7486 @multitable @columnfractions .15 .70
7487 @item @var{X} @tab The type shall be @code{REAL}.
7488 @item @var{Y} @tab The type and kind type parameter shall be the same as
7492 @item @emph{Return value}:
7493 The return value has the same type and kind type parameter as @var{X}.
7495 @item @emph{Example}:
7498 real(4) :: x = 1.e0_4, y = 0.5e0_4
7500 end program test_hypot
7507 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
7509 @cindex @acronym{ASCII} collating sequence
7510 @cindex collating sequence, @acronym{ASCII}
7511 @cindex conversion, to integer
7514 @item @emph{Description}:
7515 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
7516 in the first character position of @code{C}.
7518 @item @emph{Standard}:
7519 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7524 @item @emph{Syntax}:
7525 @code{RESULT = IACHAR(C [, KIND])}
7527 @item @emph{Arguments}:
7528 @multitable @columnfractions .15 .70
7529 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
7530 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
7531 expression indicating the kind parameter of the result.
7534 @item @emph{Return value}:
7535 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7536 @var{KIND} is absent, the return value is of default integer kind.
7538 @item @emph{Example}:
7543 end program test_iachar
7547 See @ref{ICHAR} for a discussion of converting between numerical values
7548 and formatted string representations.
7550 @item @emph{See also}:
7559 @section @code{IALL} --- Bitwise AND of array elements
7562 @cindex bits, AND of array elements
7565 @item @emph{Description}:
7566 Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
7567 if the corresponding element in @var{MASK} is @code{TRUE}.
7569 @item @emph{Standard}:
7570 Fortran 2008 and later
7573 Transformational function
7575 @item @emph{Syntax}:
7576 @multitable @columnfractions .80
7577 @item @code{RESULT = IALL(ARRAY[, MASK])}
7578 @item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
7581 @item @emph{Arguments}:
7582 @multitable @columnfractions .15 .70
7583 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7584 @item @var{DIM} @tab (Optional) shall be a scalar of type
7585 @code{INTEGER} with a value in the range from 1 to n, where n
7586 equals the rank of @var{ARRAY}.
7587 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
7588 and either be a scalar or an array of the same shape as @var{ARRAY}.
7591 @item @emph{Return value}:
7592 The result is of the same type as @var{ARRAY}.
7594 If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
7595 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7596 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7597 dimension @var{DIM} dropped is returned.
7599 @item @emph{Example}:
7608 PRINT '(b8.8)', IALL(a)
7612 @item @emph{See also}:
7621 @section @code{IAND} --- Bitwise logical and
7627 @cindex bitwise logical and
7628 @cindex logical and, bitwise
7631 @item @emph{Description}:
7632 Bitwise logical @code{AND}.
7634 @item @emph{Standard}:
7635 Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions
7640 @item @emph{Syntax}:
7641 @code{RESULT = IAND(I, J)}
7643 @item @emph{Arguments}:
7644 @multitable @columnfractions .15 .70
7645 @item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant.
7646 @item @var{J} @tab The type shall be @code{INTEGER} with the same
7647 kind type parameter as @var{I} or a boz-literal-constant.
7648 @var{I} and @var{J} shall not both be boz-literal-constants.
7651 @item @emph{Return value}:
7652 The return type is @code{INTEGER} with the kind type parameter of the
7654 A boz-literal-constant is converted to an @code{INTEGER} with the kind
7655 type parameter of the other argument as-if a call to @ref{INT} occurred.
7657 @item @emph{Example}:
7661 DATA a / Z'F' /, b / Z'3' /
7662 WRITE (*,*) IAND(a, b)
7666 @item @emph{Specific names}:
7667 @multitable @columnfractions .20 .23 .20 .33
7668 @headitem Name @tab Argument @tab Return type @tab Standard
7669 @item @code{IAND(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
7670 @item @code{BIAND(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7671 @item @code{IIAND(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7672 @item @code{JIAND(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7673 @item @code{KIAND(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7676 @item @emph{See also}:
7688 @section @code{IANY} --- Bitwise OR of array elements
7691 @cindex bits, OR of array elements
7694 @item @emph{Description}:
7695 Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
7696 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
7698 @item @emph{Standard}:
7699 Fortran 2008 and later
7702 Transformational function
7704 @item @emph{Syntax}:
7705 @multitable @columnfractions .80
7706 @item @code{RESULT = IANY(ARRAY[, MASK])}
7707 @item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
7710 @item @emph{Arguments}:
7711 @multitable @columnfractions .15 .70
7712 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7713 @item @var{DIM} @tab (Optional) shall be a scalar of type
7714 @code{INTEGER} with a value in the range from 1 to n, where n
7715 equals the rank of @var{ARRAY}.
7716 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
7717 and either be a scalar or an array of the same shape as @var{ARRAY}.
7720 @item @emph{Return value}:
7721 The result is of the same type as @var{ARRAY}.
7723 If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
7724 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7725 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7726 dimension @var{DIM} dropped is returned.
7728 @item @emph{Example}:
7737 PRINT '(b8.8)', IANY(a)
7741 @item @emph{See also}:
7750 @section @code{IARGC} --- Get the number of command line arguments
7752 @cindex command-line arguments
7753 @cindex command-line arguments, number of
7754 @cindex arguments, to program
7757 @item @emph{Description}:
7758 @code{IARGC} returns the number of arguments passed on the
7759 command line when the containing program was invoked.
7761 This intrinsic routine is provided for backwards compatibility with
7762 GNU Fortran 77. In new code, programmers should consider the use of
7763 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
7766 @item @emph{Standard}:
7772 @item @emph{Syntax}:
7773 @code{RESULT = IARGC()}
7775 @item @emph{Arguments}:
7778 @item @emph{Return value}:
7779 The number of command line arguments, type @code{INTEGER(4)}.
7781 @item @emph{Example}:
7784 @item @emph{See also}:
7785 GNU Fortran 77 compatibility subroutine: @*
7787 Fortran 2003 functions and subroutines: @*
7788 @ref{GET_COMMAND}, @*
7789 @ref{GET_COMMAND_ARGUMENT}, @*
7790 @ref{COMMAND_ARGUMENT_COUNT}
7796 @section @code{IBCLR} --- Clear bit
7806 @item @emph{Description}:
7807 @code{IBCLR} returns the value of @var{I} with the bit at position
7808 @var{POS} set to zero.
7810 @item @emph{Standard}:
7811 Fortran 90 and later, has overloads that are GNU extensions
7816 @item @emph{Syntax}:
7817 @code{RESULT = IBCLR(I, POS)}
7819 @item @emph{Arguments}:
7820 @multitable @columnfractions .15 .70
7821 @item @var{I} @tab The type shall be @code{INTEGER}.
7822 @item @var{POS} @tab The type shall be @code{INTEGER}.
7825 @item @emph{Return value}:
7826 The return value is of type @code{INTEGER} and of the same kind as
7829 @item @emph{Specific names}:
7830 @multitable @columnfractions .20 .23 .20 .33
7831 @headitem Name @tab Argument @tab Return type @tab Standard
7832 @item @code{IBCLR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
7833 @item @code{BBCLR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7834 @item @code{IIBCLR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7835 @item @code{JIBCLR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7836 @item @code{KIBCLR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7839 @item @emph{See also}:
7851 @section @code{IBITS} --- Bit extraction
7858 @cindex bits, extract
7861 @item @emph{Description}:
7862 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
7863 starting from bit position @var{POS} and extending left for @var{LEN}
7864 bits. The result is right-justified and the remaining bits are
7865 zeroed. The value of @code{POS+LEN} must be less than or equal to the
7866 value @code{BIT_SIZE(I)}.
7868 @item @emph{Standard}:
7869 Fortran 90 and later, has overloads that are GNU extensions
7874 @item @emph{Syntax}:
7875 @code{RESULT = IBITS(I, POS, LEN)}
7877 @item @emph{Arguments}:
7878 @multitable @columnfractions .15 .70
7879 @item @var{I} @tab The type shall be @code{INTEGER}.
7880 @item @var{POS} @tab The type shall be @code{INTEGER}.
7881 @item @var{LEN} @tab The type shall be @code{INTEGER}.
7884 @item @emph{Return value}:
7885 The return value is of type @code{INTEGER} and of the same kind as
7888 @item @emph{Specific names}:
7889 @multitable @columnfractions .20 .23 .20 .33
7890 @headitem Name @tab Argument @tab Return type @tab Standard
7891 @item @code{IBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
7892 @item @code{BBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7893 @item @code{IIBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7894 @item @code{JIBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7895 @item @code{KIBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7898 @item @emph{See also}:
7910 @section @code{IBSET} --- Set bit
7919 @item @emph{Description}:
7920 @code{IBSET} returns the value of @var{I} with the bit at position
7921 @var{POS} set to one.
7923 @item @emph{Standard}:
7924 Fortran 90 and later, has overloads that are GNU extensions
7929 @item @emph{Syntax}:
7930 @code{RESULT = IBSET(I, POS)}
7932 @item @emph{Arguments}:
7933 @multitable @columnfractions .15 .70
7934 @item @var{I} @tab The type shall be @code{INTEGER}.
7935 @item @var{POS} @tab The type shall be @code{INTEGER}.
7938 @item @emph{Return value}:
7939 The return value is of type @code{INTEGER} and of the same kind as
7942 @item @emph{Specific names}:
7943 @multitable @columnfractions .20 .23 .20 .33
7944 @headitem Name @tab Argument @tab Return type @tab Standard
7945 @item @code{IBSET(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
7946 @item @code{BBSET(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7947 @item @code{IIBSET(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7948 @item @code{JIBSET(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7949 @item @code{KIBSET(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7952 @item @emph{See also}:
7964 @section @code{ICHAR} --- Character-to-integer conversion function
7966 @cindex conversion, to integer
7969 @item @emph{Description}:
7970 @code{ICHAR(C)} returns the code for the character in the first character
7971 position of @code{C} in the system's native character set.
7972 The correspondence between characters and their codes is not necessarily
7973 the same across different GNU Fortran implementations.
7975 @item @emph{Standard}:
7976 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
7981 @item @emph{Syntax}:
7982 @code{RESULT = ICHAR(C [, KIND])}
7984 @item @emph{Arguments}:
7985 @multitable @columnfractions .15 .70
7986 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
7987 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
7988 expression indicating the kind parameter of the result.
7991 @item @emph{Return value}:
7992 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7993 @var{KIND} is absent, the return value is of default integer kind.
7995 @item @emph{Example}:
8000 end program test_ichar
8003 @item @emph{Specific names}:
8004 @multitable @columnfractions .20 .23 .20 .33
8005 @headitem Name @tab Argument @tab Return type @tab Standard
8006 @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8010 No intrinsic exists to convert between a numeric value and a formatted
8011 character string representation -- for instance, given the
8012 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
8013 @code{REAL} value with the value 154, or vice versa. Instead, this
8014 functionality is provided by internal-file I/O, as in the following
8019 character(len=10) string, string2
8022 ! Convert a string to a numeric value
8023 read (string,'(I10)') value
8026 ! Convert a value to a formatted string
8027 write (string2,'(I10)') value
8029 end program read_val
8032 @item @emph{See also}:
8041 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
8043 @cindex date, current
8044 @cindex current date
8047 @item @emph{Description}:
8048 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
8049 current local time. The day (in the range 1-31), month (in the range 1-12),
8050 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
8051 The year has four significant digits.
8053 This intrinsic routine is provided for backwards compatibility with
8054 GNU Fortran 77. In new code, programmers should consider the use of
8055 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
8058 @item @emph{Standard}:
8064 @item @emph{Syntax}:
8065 @code{CALL IDATE(VALUES)}
8067 @item @emph{Arguments}:
8068 @multitable @columnfractions .15 .70
8069 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
8070 the kind shall be the default integer kind.
8073 @item @emph{Return value}:
8074 Does not return anything.
8076 @item @emph{Example}:
8079 integer, dimension(3) :: tarray
8084 end program test_idate
8087 @item @emph{See also}:
8093 @section @code{IEOR} --- Bitwise logical exclusive or
8099 @cindex bitwise logical exclusive or
8100 @cindex logical exclusive or, bitwise
8103 @item @emph{Description}:
8104 @code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
8107 @item @emph{Standard}:
8108 Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions
8113 @item @emph{Syntax}:
8114 @code{RESULT = IEOR(I, J)}
8116 @item @emph{Arguments}:
8117 @multitable @columnfractions .15 .70
8118 @item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant.
8119 @item @var{J} @tab The type shall be @code{INTEGER} with the same
8120 kind type parameter as @var{I} or a boz-literal-constant.
8121 @var{I} and @var{J} shall not both be boz-literal-constants.
8124 @item @emph{Return value}:
8125 The return type is @code{INTEGER} with the kind type parameter of the
8127 A boz-literal-constant is converted to an @code{INTEGER} with the kind
8128 type parameter of the other argument as-if a call to @ref{INT} occurred.
8130 @item @emph{Specific names}:
8131 @multitable @columnfractions .20 .23 .20 .33
8132 @headitem Name @tab Argument @tab Return type @tab Standard
8133 @item @code{IEOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
8134 @item @code{BIEOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8135 @item @code{IIEOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8136 @item @code{JIEOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8137 @item @code{KIEOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8140 @item @emph{See also}:
8152 @section @code{IERRNO} --- Get the last system error number
8154 @cindex system, error handling
8157 @item @emph{Description}:
8158 Returns the last system error number, as given by the C @code{errno}
8161 @item @emph{Standard}:
8167 @item @emph{Syntax}:
8168 @code{RESULT = IERRNO()}
8170 @item @emph{Arguments}:
8173 @item @emph{Return value}:
8174 The return value is of type @code{INTEGER} and of the default integer
8177 @item @emph{See also}:
8184 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
8185 @fnindex IMAGE_INDEX
8186 @cindex coarray, @code{IMAGE_INDEX}
8187 @cindex images, cosubscript to image index conversion
8190 @item @emph{Description}:
8191 Returns the image index belonging to a cosubscript.
8193 @item @emph{Standard}:
8194 Fortran 2008 and later
8199 @item @emph{Syntax}:
8200 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
8202 @item @emph{Arguments}:
8203 @multitable @columnfractions .15 .70
8204 @item @var{COARRAY} @tab Coarray of any type.
8205 @item @var{SUB} @tab default integer rank-1 array of a size equal to
8206 the corank of @var{COARRAY}.
8210 @item @emph{Return value}:
8211 Scalar default integer with the value of the image index which corresponds
8212 to the cosubscripts. For invalid cosubscripts the result is zero.
8214 @item @emph{Example}:
8216 INTEGER :: array[2,-1:4,8,*]
8217 ! Writes 28 (or 0 if there are fewer than 28 images)
8218 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
8221 @item @emph{See also}:
8222 @ref{THIS_IMAGE}, @*
8228 @node INDEX intrinsic
8229 @section @code{INDEX} --- Position of a substring within a string
8231 @cindex substring position
8232 @cindex string, find substring
8235 @item @emph{Description}:
8236 Returns the position of the start of the first occurrence of string
8237 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
8238 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
8239 the @var{BACK} argument is present and true, the return value is the
8240 start of the last occurrence rather than the first.
8242 @item @emph{Standard}:
8243 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
8248 @item @emph{Syntax}:
8249 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
8251 @item @emph{Arguments}:
8252 @multitable @columnfractions .15 .70
8253 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
8255 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
8257 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
8259 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
8260 expression indicating the kind parameter of the result.
8263 @item @emph{Return value}:
8264 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8265 @var{KIND} is absent, the return value is of default integer kind.
8267 @item @emph{Specific names}:
8268 @multitable @columnfractions .35 .15 .17 .30
8269 @headitem Name @tab Argument @tab Return type @tab Standard
8270 @item @code{INDEX(STRING,SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8273 @item @emph{See also}:
8281 @section @code{INT} --- Convert to integer type
8285 @cindex conversion, to integer
8288 @item @emph{Description}:
8289 Convert to integer type
8291 @item @emph{Standard}:
8292 Fortran 77 and later, with boz-literal-constant Fortran 2008 and later.
8297 @item @emph{Syntax}:
8298 @code{RESULT = INT(A [, KIND))}
8300 @item @emph{Arguments}:
8301 @multitable @columnfractions .15 .70
8302 @item @var{A} @tab Shall be of type @code{INTEGER},
8303 @code{REAL}, or @code{COMPLEX} or a boz-literal-constant.
8304 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
8305 expression indicating the kind parameter of the result.
8308 @item @emph{Return value}:
8309 These functions return a @code{INTEGER} variable or array under
8310 the following rules:
8314 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
8316 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)}
8317 equals @code{0}. If @math{|A| \geq 1}, then @code{INT(A)} is the integer
8318 whose magnitude is the largest integer that does not exceed the magnitude
8319 of @var{A} and whose sign is the same as the sign of @var{A}.
8321 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
8324 @item @emph{Example}:
8328 complex :: z = (-3.7, 1.0)
8330 print *, int(z), int(z,8)
8334 @item @emph{Specific names}:
8335 @multitable @columnfractions .20 .23 .20 .33
8336 @headitem Name @tab Argument @tab Return type @tab Standard
8337 @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
8338 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
8339 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
8346 @section @code{INT2} --- Convert to 16-bit integer type
8348 @cindex conversion, to integer
8351 @item @emph{Description}:
8352 Convert to a @code{KIND=2} integer type. This is equivalent to the
8353 standard @code{INT} intrinsic with an optional argument of
8354 @code{KIND=2}, and is only included for backwards compatibility.
8356 @item @emph{Standard}:
8362 @item @emph{Syntax}:
8363 @code{RESULT = INT2(A)}
8365 @item @emph{Arguments}:
8366 @multitable @columnfractions .15 .70
8367 @item @var{A} @tab Shall be of type @code{INTEGER},
8368 @code{REAL}, or @code{COMPLEX}.
8371 @item @emph{Return value}:
8372 The return value is a @code{INTEGER(2)} variable.
8374 @item @emph{See also}:
8382 @section @code{INT8} --- Convert to 64-bit integer type
8384 @cindex conversion, to integer
8387 @item @emph{Description}:
8388 Convert to a @code{KIND=8} integer type. This is equivalent to the
8389 standard @code{INT} intrinsic with an optional argument of
8390 @code{KIND=8}, and is only included for backwards compatibility.
8392 @item @emph{Standard}:
8398 @item @emph{Syntax}:
8399 @code{RESULT = INT8(A)}
8401 @item @emph{Arguments}:
8402 @multitable @columnfractions .15 .70
8403 @item @var{A} @tab Shall be of type @code{INTEGER},
8404 @code{REAL}, or @code{COMPLEX}.
8407 @item @emph{Return value}:
8408 The return value is a @code{INTEGER(8)} variable.
8410 @item @emph{See also}:
8418 @section @code{IOR} --- Bitwise logical or
8424 @cindex bitwise logical or
8425 @cindex logical or, bitwise
8428 @item @emph{Description}:
8429 @code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
8432 @item @emph{Standard}:
8433 Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions
8438 @item @emph{Syntax}:
8439 @code{RESULT = IOR(I, J)}
8441 @item @emph{Arguments}:
8442 @multitable @columnfractions .15 .70
8443 @item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant.
8444 @item @var{J} @tab The type shall be @code{INTEGER} with the same
8445 kind type parameter as @var{I} or a boz-literal-constant.
8446 @var{I} and @var{J} shall not both be boz-literal-constants.
8449 @item @emph{Return value}:
8450 The return type is @code{INTEGER} with the kind type parameter of the
8452 A boz-literal-constant is converted to an @code{INTEGER} with the kind
8453 type parameter of the other argument as-if a call to @ref{INT} occurred.
8455 @item @emph{Specific names}:
8456 @multitable @columnfractions .20 .23 .20 .33
8457 @headitem Name @tab Argument @tab Return type @tab Standard
8458 @item @code{IOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
8459 @item @code{BIOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8460 @item @code{IIOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8461 @item @code{JIOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8462 @item @code{KIOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8465 @item @emph{See also}:
8477 @section @code{IPARITY} --- Bitwise XOR of array elements
8479 @cindex array, parity
8481 @cindex bits, XOR of array elements
8484 @item @emph{Description}:
8485 Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
8486 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
8488 @item @emph{Standard}:
8489 Fortran 2008 and later
8492 Transformational function
8494 @item @emph{Syntax}:
8495 @multitable @columnfractions .80
8496 @item @code{RESULT = IPARITY(ARRAY[, MASK])}
8497 @item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
8500 @item @emph{Arguments}:
8501 @multitable @columnfractions .15 .70
8502 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
8503 @item @var{DIM} @tab (Optional) shall be a scalar of type
8504 @code{INTEGER} with a value in the range from 1 to n, where n
8505 equals the rank of @var{ARRAY}.
8506 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
8507 and either be a scalar or an array of the same shape as @var{ARRAY}.
8510 @item @emph{Return value}:
8511 The result is of the same type as @var{ARRAY}.
8513 If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
8514 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
8515 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
8516 dimension @var{DIM} dropped is returned.
8518 @item @emph{Example}:
8520 PROGRAM test_iparity
8523 a(1) = int(b'00100100', 1)
8524 a(2) = int(b'01101010', 1)
8527 PRINT '(b8.8)', IPARITY(a)
8531 @item @emph{See also}:
8541 @section @code{IRAND} --- Integer pseudo-random number
8543 @cindex random number generation
8546 @item @emph{Description}:
8547 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
8548 distribution between 0 and a system-dependent limit (which is in most
8549 cases 2147483647). If @var{FLAG} is 0, the next number
8550 in the current sequence is returned; if @var{FLAG} is 1, the generator
8551 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
8552 it is used as a new seed with @code{SRAND}.
8554 This intrinsic routine is provided for backwards compatibility with
8555 GNU Fortran 77. It implements a simple modulo generator as provided
8556 by @command{g77}. For new code, one should consider the use of
8557 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
8559 @item @emph{Standard}:
8565 @item @emph{Syntax}:
8566 @code{RESULT = IRAND(I)}
8568 @item @emph{Arguments}:
8569 @multitable @columnfractions .15 .70
8570 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
8573 @item @emph{Return value}:
8574 The return value is of @code{INTEGER(kind=4)} type.
8576 @item @emph{Example}:
8579 integer,parameter :: seed = 86456
8582 print *, irand(), irand(), irand(), irand()
8583 print *, irand(seed), irand(), irand(), irand()
8584 end program test_irand
8592 @section @code{IS_CONTIGUOUS} --- Test whether an array is contiguous
8593 @fnindex IS_IOSTAT_EOR
8594 @cindex array, contiguity
8597 @item @emph{Description}:
8598 @code{IS_CONTIGUOUS} tests whether an array is contiguous.
8600 @item @emph{Standard}:
8601 Fortran 2008 and later
8606 @item @emph{Syntax}:
8607 @code{RESULT = IS_CONTIGUOUS(ARRAY)}
8609 @item @emph{Arguments}:
8610 @multitable @columnfractions .15 .70
8611 @item @var{ARRAY} @tab Shall be an array of any type.
8614 @item @emph{Return value}:
8615 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
8616 @var{ARRAY} is contiguous and false otherwise.
8618 @item @emph{Example}:
8622 a = [1,2,3,4,5,6,7,8,9,10]
8623 call sub (a) ! every element, is contiguous
8624 call sub (a(::2)) ! every other element, is noncontiguous
8628 if (is_contiguous (x)) then
8629 write (*,*) 'X is contiguous'
8631 write (*,*) 'X is not contiguous'
8641 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
8642 @fnindex IS_IOSTAT_END
8643 @cindex @code{IOSTAT}, end of file
8646 @item @emph{Description}:
8647 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
8648 status ``end of file''. The function is equivalent to comparing the variable
8649 with the @code{IOSTAT_END} parameter of the intrinsic module
8650 @code{ISO_FORTRAN_ENV}.
8652 @item @emph{Standard}:
8653 Fortran 2003 and later
8658 @item @emph{Syntax}:
8659 @code{RESULT = IS_IOSTAT_END(I)}
8661 @item @emph{Arguments}:
8662 @multitable @columnfractions .15 .70
8663 @item @var{I} @tab Shall be of the type @code{INTEGER}.
8666 @item @emph{Return value}:
8667 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
8668 @var{I} has the value which indicates an end of file condition for
8669 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
8671 @item @emph{Example}:
8676 OPEN(88, FILE='test.dat')
8677 READ(88, *, IOSTAT=stat) i
8678 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
8686 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
8687 @fnindex IS_IOSTAT_EOR
8688 @cindex @code{IOSTAT}, end of record
8691 @item @emph{Description}:
8692 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
8693 status ``end of record''. The function is equivalent to comparing the
8694 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
8695 @code{ISO_FORTRAN_ENV}.
8697 @item @emph{Standard}:
8698 Fortran 2003 and later
8703 @item @emph{Syntax}:
8704 @code{RESULT = IS_IOSTAT_EOR(I)}
8706 @item @emph{Arguments}:
8707 @multitable @columnfractions .15 .70
8708 @item @var{I} @tab Shall be of the type @code{INTEGER}.
8711 @item @emph{Return value}:
8712 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
8713 @var{I} has the value which indicates an end of file condition for
8714 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
8716 @item @emph{Example}:
8720 INTEGER :: stat, i(50)
8721 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
8722 READ(88, IOSTAT=stat) i
8723 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
8730 @section @code{ISATTY} --- Whether a unit is a terminal device
8732 @cindex system, terminal
8735 @item @emph{Description}:
8736 Determine whether a unit is connected to a terminal device.
8738 @item @emph{Standard}:
8744 @item @emph{Syntax}:
8745 @code{RESULT = ISATTY(UNIT)}
8747 @item @emph{Arguments}:
8748 @multitable @columnfractions .15 .70
8749 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
8752 @item @emph{Return value}:
8753 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
8754 device, @code{.FALSE.} otherwise.
8756 @item @emph{Example}:
8759 INTEGER(kind=1) :: unit
8761 write(*,*) isatty(unit=unit)
8765 @item @emph{See also}:
8772 @section @code{ISHFT} --- Shift bits
8781 @item @emph{Description}:
8782 @code{ISHFT} returns a value corresponding to @var{I} with all of the
8783 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
8784 zero corresponds to a left shift, a value of zero corresponds to no
8785 shift, and a value less than zero corresponds to a right shift. If the
8786 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
8787 value is undefined. Bits shifted out from the left end or right end are
8788 lost; zeros are shifted in from the opposite end.
8790 @item @emph{Standard}:
8791 Fortran 90 and later, has overloads that are GNU extensions
8796 @item @emph{Syntax}:
8797 @code{RESULT = ISHFT(I, SHIFT)}
8799 @item @emph{Arguments}:
8800 @multitable @columnfractions .15 .70
8801 @item @var{I} @tab The type shall be @code{INTEGER}.
8802 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8805 @item @emph{Return value}:
8806 The return value is of type @code{INTEGER} and of the same kind as
8809 @item @emph{Specific names}:
8810 @multitable @columnfractions .20 .23 .20 .33
8811 @headitem Name @tab Argument @tab Return type @tab Standard
8812 @item @code{ISHFT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
8813 @item @code{BSHFT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8814 @item @code{IISHFT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8815 @item @code{JISHFT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8816 @item @code{KISHFT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8819 @item @emph{See also}:
8826 @section @code{ISHFTC} --- Shift bits circularly
8832 @cindex bits, shift circular
8835 @item @emph{Description}:
8836 @code{ISHFTC} returns a value corresponding to @var{I} with the
8837 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
8838 is, bits shifted out one end are shifted into the opposite end. A value
8839 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
8840 zero corresponds to no shift, and a value less than zero corresponds to
8841 a right shift. The absolute value of @var{SHIFT} must be less than
8842 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
8843 equivalent to @code{BIT_SIZE(I)}.
8845 @item @emph{Standard}:
8846 Fortran 90 and later, has overloads that are GNU extensions
8851 @item @emph{Syntax}:
8852 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
8854 @item @emph{Arguments}:
8855 @multitable @columnfractions .15 .70
8856 @item @var{I} @tab The type shall be @code{INTEGER}.
8857 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8858 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
8859 the value must be greater than zero and less than or equal to
8863 @item @emph{Return value}:
8864 The return value is of type @code{INTEGER} and of the same kind as
8867 @item @emph{Specific names}:
8868 @multitable @columnfractions .20 .23 .20 .33
8869 @headitem Name @tab Argument @tab Return type @tab Standard
8870 @item @code{ISHFTC(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
8871 @item @code{BSHFTC(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8872 @item @code{IISHFTC(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8873 @item @code{JISHFTC(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8874 @item @code{KISHFTC(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8877 @item @emph{See also}:
8884 @section @code{ISNAN} --- Test for a NaN
8889 @item @emph{Description}:
8890 @code{ISNAN} tests whether a floating-point value is an IEEE
8892 @item @emph{Standard}:
8898 @item @emph{Syntax}:
8901 @item @emph{Arguments}:
8902 @multitable @columnfractions .15 .70
8903 @item @var{X} @tab Variable of the type @code{REAL}.
8907 @item @emph{Return value}:
8908 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
8909 if @var{X} is a NaN and @code{FALSE} otherwise.
8911 @item @emph{Example}:
8918 if (isnan(x)) stop '"x" is a NaN'
8919 end program test_nan
8926 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
8928 @cindex time, current
8929 @cindex current time
8932 @item @emph{Description}:
8933 @code{ITIME(VALUES)} Fills @var{VALUES} with the numerical values at the
8934 current local time. The hour (in the range 1-24), minute (in the range 1-60),
8935 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
8938 This intrinsic routine is provided for backwards compatibility with
8939 GNU Fortran 77. In new code, programmers should consider the use of
8940 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
8943 @item @emph{Standard}:
8949 @item @emph{Syntax}:
8950 @code{CALL ITIME(VALUES)}
8952 @item @emph{Arguments}:
8953 @multitable @columnfractions .15 .70
8954 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
8955 and the kind shall be the default integer kind.
8958 @item @emph{Return value}:
8959 Does not return anything.
8962 @item @emph{Example}:
8965 integer, dimension(3) :: tarray
8970 end program test_itime
8973 @item @emph{See also}:
8980 @section @code{KILL} --- Send a signal to a process
8984 @item @emph{Description}:
8985 Sends the signal specified by @var{SIG} to the process @var{PID}.
8988 This intrinsic is provided in both subroutine and function forms;
8989 however, only one form can be used in any given program unit.
8990 @item @emph{Standard}:
8993 @item @emph{Standard}:
8997 Subroutine, function
8999 @item @emph{Syntax}:
9000 @multitable @columnfractions .80
9001 @item @code{CALL KILL(PID, SIG [, STATUS])}
9002 @item @code{STATUS = KILL(PID, SIG)}
9005 @item @emph{Arguments}:
9006 @multitable @columnfractions .15 .70
9007 @item @var{PID} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}.
9008 @item @var{SIG} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}.
9009 @item @var{STATUS} @tab [Subroutine](Optional)
9010 Shall be a scalar @code{INTEGER}.
9011 Returns 0 on success; otherwise a system-specific error code is returned.
9012 @item @var{STATUS} @tab [Function] The kind type parameter is that of
9014 Returns 0 on success; otherwise a system-specific error code is returned.
9017 @item @emph{See also}:
9024 @section @code{KIND} --- Kind of an entity
9029 @item @emph{Description}:
9030 @code{KIND(X)} returns the kind value of the entity @var{X}.
9032 @item @emph{Standard}:
9033 Fortran 95 and later
9038 @item @emph{Syntax}:
9041 @item @emph{Arguments}:
9042 @multitable @columnfractions .15 .70
9043 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
9044 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}. It may be scalar or
9048 @item @emph{Return value}:
9049 The return value is a scalar of type @code{INTEGER} and of the default
9052 @item @emph{Example}:
9055 integer,parameter :: kc = kind(' ')
9056 integer,parameter :: kl = kind(.true.)
9058 print *, "The default character kind is ", kc
9059 print *, "The default logical kind is ", kl
9060 end program test_kind
9068 @section @code{LBOUND} --- Lower dimension bounds of an array
9070 @cindex array, lower bound
9073 @item @emph{Description}:
9074 Returns the lower bounds of an array, or a single lower bound
9075 along the @var{DIM} dimension.
9076 @item @emph{Standard}:
9077 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
9082 @item @emph{Syntax}:
9083 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
9085 @item @emph{Arguments}:
9086 @multitable @columnfractions .15 .70
9087 @item @var{ARRAY} @tab Shall be an array, of any type.
9088 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
9089 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
9090 expression indicating the kind parameter of the result.
9093 @item @emph{Return value}:
9094 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9095 @var{KIND} is absent, the return value is of default integer kind.
9096 If @var{DIM} is absent, the result is an array of the lower bounds of
9097 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
9098 corresponding to the lower bound of the array along that dimension. If
9099 @var{ARRAY} is an expression rather than a whole array or array
9100 structure component, or if it has a zero extent along the relevant
9101 dimension, the lower bound is taken to be 1.
9103 @item @emph{See also}:
9111 @section @code{LCOBOUND} --- Lower codimension bounds of an array
9113 @cindex coarray, lower bound
9116 @item @emph{Description}:
9117 Returns the lower bounds of a coarray, or a single lower cobound
9118 along the @var{DIM} codimension.
9119 @item @emph{Standard}:
9120 Fortran 2008 and later
9125 @item @emph{Syntax}:
9126 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
9128 @item @emph{Arguments}:
9129 @multitable @columnfractions .15 .70
9130 @item @var{ARRAY} @tab Shall be an coarray, of any type.
9131 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
9132 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
9133 expression indicating the kind parameter of the result.
9136 @item @emph{Return value}:
9137 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9138 @var{KIND} is absent, the return value is of default integer kind.
9139 If @var{DIM} is absent, the result is an array of the lower cobounds of
9140 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
9141 corresponding to the lower cobound of the array along that codimension.
9143 @item @emph{See also}:
9151 @section @code{LEADZ} --- Number of leading zero bits of an integer
9156 @item @emph{Description}:
9157 @code{LEADZ} returns the number of leading zero bits of an integer.
9159 @item @emph{Standard}:
9160 Fortran 2008 and later
9165 @item @emph{Syntax}:
9166 @code{RESULT = LEADZ(I)}
9168 @item @emph{Arguments}:
9169 @multitable @columnfractions .15 .70
9170 @item @var{I} @tab Shall be of type @code{INTEGER}.
9173 @item @emph{Return value}:
9174 The type of the return value is the default @code{INTEGER}.
9175 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
9177 @item @emph{Example}:
9180 WRITE (*,*) BIT_SIZE(1) ! prints 32
9181 WRITE (*,*) LEADZ(1) ! prints 31
9185 @item @emph{See also}:
9195 @section @code{LEN} --- Length of a character entity
9197 @cindex string, length
9200 @item @emph{Description}:
9201 Returns the length of a character string. If @var{STRING} is an array,
9202 the length of an element of @var{STRING} is returned. Note that
9203 @var{STRING} need not be defined when this intrinsic is invoked, since
9204 only the length, not the content, of @var{STRING} is needed.
9206 @item @emph{Standard}:
9207 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
9212 @item @emph{Syntax}:
9213 @code{L = LEN(STRING [, KIND])}
9215 @item @emph{Arguments}:
9216 @multitable @columnfractions .15 .70
9217 @item @var{STRING} @tab Shall be a scalar or array of type
9218 @code{CHARACTER}, with @code{INTENT(IN)}
9219 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
9220 expression indicating the kind parameter of the result.
9223 @item @emph{Return value}:
9224 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9225 @var{KIND} is absent, the return value is of default integer kind.
9228 @item @emph{Specific names}:
9229 @multitable @columnfractions .20 .23 .20 .33
9230 @headitem Name @tab Argument @tab Return type @tab Standard
9231 @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
9235 @item @emph{See also}:
9244 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
9246 @cindex string, length, without trailing whitespace
9249 @item @emph{Description}:
9250 Returns the length of a character string, ignoring any trailing blanks.
9252 @item @emph{Standard}:
9253 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
9258 @item @emph{Syntax}:
9259 @code{RESULT = LEN_TRIM(STRING [, KIND])}
9261 @item @emph{Arguments}:
9262 @multitable @columnfractions .15 .70
9263 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
9264 with @code{INTENT(IN)}
9265 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
9266 expression indicating the kind parameter of the result.
9269 @item @emph{Return value}:
9270 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9271 @var{KIND} is absent, the return value is of default integer kind.
9273 @item @emph{See also}:
9282 @section @code{LGE} --- Lexical greater than or equal
9284 @cindex lexical comparison of strings
9285 @cindex string, comparison
9288 @item @emph{Description}:
9289 Determines whether one string is lexically greater than or equal to
9290 another string, where the two strings are interpreted as containing
9291 ASCII character codes. If the String A and String B are not the same
9292 length, the shorter is compared as if spaces were appended to it to form
9293 a value that has the same length as the longer.
9295 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9296 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9297 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9298 that the latter use the processor's character ordering (which is not
9299 ASCII on some targets), whereas the former always use the ASCII
9302 @item @emph{Standard}:
9303 Fortran 77 and later
9308 @item @emph{Syntax}:
9309 @code{RESULT = LGE(STRING_A, STRING_B)}
9311 @item @emph{Arguments}:
9312 @multitable @columnfractions .15 .70
9313 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9314 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9317 @item @emph{Return value}:
9318 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
9319 otherwise, based on the ASCII ordering.
9321 @item @emph{Specific names}:
9322 @multitable @columnfractions .34 .16 .17 .30
9323 @headitem Name @tab Argument @tab Return type @tab Standard
9324 @item @code{LGE(STRING_A,STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9327 @item @emph{See also}:
9336 @section @code{LGT} --- Lexical greater than
9338 @cindex lexical comparison of strings
9339 @cindex string, comparison
9342 @item @emph{Description}:
9343 Determines whether one string is lexically greater than another string,
9344 where the two strings are interpreted as containing ASCII character
9345 codes. If the String A and String B are not the same length, the
9346 shorter is compared as if spaces were appended to it to form a value
9347 that has the same length as the longer.
9349 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9350 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9351 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9352 that the latter use the processor's character ordering (which is not
9353 ASCII on some targets), whereas the former always use the ASCII
9356 @item @emph{Standard}:
9357 Fortran 77 and later
9362 @item @emph{Syntax}:
9363 @code{RESULT = LGT(STRING_A, STRING_B)}
9365 @item @emph{Arguments}:
9366 @multitable @columnfractions .15 .70
9367 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9368 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9371 @item @emph{Return value}:
9372 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
9373 otherwise, based on the ASCII ordering.
9375 @item @emph{Specific names}:
9376 @multitable @columnfractions .34 .16 .17 .30
9377 @headitem Name @tab Argument @tab Return type @tab Standard
9378 @item @code{LGT(STRING_A,STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9381 @item @emph{See also}:
9390 @section @code{LINK} --- Create a hard link
9392 @cindex file system, create link
9393 @cindex file system, hard link
9396 @item @emph{Description}:
9397 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
9398 character (@code{CHAR(0)}) can be used to mark the end of the names in
9399 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
9400 names are ignored. If the @var{STATUS} argument is supplied, it
9401 contains 0 on success or a nonzero error code upon return; see
9404 This intrinsic is provided in both subroutine and function forms;
9405 however, only one form can be used in any given program unit.
9407 @item @emph{Standard}:
9411 Subroutine, function
9413 @item @emph{Syntax}:
9414 @multitable @columnfractions .80
9415 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
9416 @item @code{STATUS = LINK(PATH1, PATH2)}
9419 @item @emph{Arguments}:
9420 @multitable @columnfractions .15 .70
9421 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
9422 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
9423 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9426 @item @emph{See also}:
9434 @section @code{LLE} --- Lexical less than or equal
9436 @cindex lexical comparison of strings
9437 @cindex string, comparison
9440 @item @emph{Description}:
9441 Determines whether one string is lexically less than or equal to another
9442 string, where the two strings are interpreted as containing ASCII
9443 character codes. If the String A and String B are not the same length,
9444 the shorter is compared as if spaces were appended to it to form a value
9445 that has the same length as the longer.
9447 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9448 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9449 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9450 that the latter use the processor's character ordering (which is not
9451 ASCII on some targets), whereas the former always use the ASCII
9454 @item @emph{Standard}:
9455 Fortran 77 and later
9460 @item @emph{Syntax}:
9461 @code{RESULT = LLE(STRING_A, STRING_B)}
9463 @item @emph{Arguments}:
9464 @multitable @columnfractions .15 .70
9465 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9466 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9469 @item @emph{Return value}:
9470 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
9471 otherwise, based on the ASCII ordering.
9473 @item @emph{Specific names}:
9474 @multitable @columnfractions .34 .16 .17 .30
9475 @headitem Name @tab Argument @tab Return type @tab Standard
9476 @item @code{LLE(STRING_A,STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9479 @item @emph{See also}:
9488 @section @code{LLT} --- Lexical less than
9490 @cindex lexical comparison of strings
9491 @cindex string, comparison
9494 @item @emph{Description}:
9495 Determines whether one string is lexically less than another string,
9496 where the two strings are interpreted as containing ASCII character
9497 codes. If the String A and String B are not the same length, the
9498 shorter is compared as if spaces were appended to it to form a value
9499 that has the same length as the longer.
9501 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9502 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9503 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9504 that the latter use the processor's character ordering (which is not
9505 ASCII on some targets), whereas the former always use the ASCII
9508 @item @emph{Standard}:
9509 Fortran 77 and later
9514 @item @emph{Syntax}:
9515 @code{RESULT = LLT(STRING_A, STRING_B)}
9517 @item @emph{Arguments}:
9518 @multitable @columnfractions .15 .70
9519 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9520 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9523 @item @emph{Return value}:
9524 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
9525 otherwise, based on the ASCII ordering.
9527 @item @emph{Specific names}:
9528 @multitable @columnfractions .34 .16 .17 .30
9529 @headitem Name @tab Argument @tab Return type @tab Standard
9530 @item @code{LLT(STRING_A,STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9533 @item @emph{See also}:
9542 @section @code{LNBLNK} --- Index of the last non-blank character in a string
9544 @cindex string, find non-blank character
9547 @item @emph{Description}:
9548 Returns the length of a character string, ignoring any trailing blanks.
9549 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
9550 included for backwards compatibility.
9552 @item @emph{Standard}:
9558 @item @emph{Syntax}:
9559 @code{RESULT = LNBLNK(STRING)}
9561 @item @emph{Arguments}:
9562 @multitable @columnfractions .15 .70
9563 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
9564 with @code{INTENT(IN)}
9567 @item @emph{Return value}:
9568 The return value is of @code{INTEGER(kind=4)} type.
9570 @item @emph{See also}:
9571 @ref{INDEX intrinsic}, @*
9578 @section @code{LOC} --- Returns the address of a variable
9580 @cindex location of a variable in memory
9583 @item @emph{Description}:
9584 @code{LOC(X)} returns the address of @var{X} as an integer.
9586 @item @emph{Standard}:
9592 @item @emph{Syntax}:
9593 @code{RESULT = LOC(X)}
9595 @item @emph{Arguments}:
9596 @multitable @columnfractions .15 .70
9597 @item @var{X} @tab Variable of any type.
9600 @item @emph{Return value}:
9601 The return value is of type @code{INTEGER}, with a @code{KIND}
9602 corresponding to the size (in bytes) of a memory address on the target
9605 @item @emph{Example}:
9612 end program test_loc
9619 @section @code{LOG} --- Natural logarithm function
9626 @cindex exponential function, inverse
9627 @cindex logarithm function
9628 @cindex natural logarithm function
9631 @item @emph{Description}:
9632 @code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the
9633 logarithm to the base @math{e}.
9635 @item @emph{Standard}:
9636 Fortran 77 and later, has GNU extensions
9641 @item @emph{Syntax}:
9642 @code{RESULT = LOG(X)}
9644 @item @emph{Arguments}:
9645 @multitable @columnfractions .15 .70
9646 @item @var{X} @tab The type shall be @code{REAL} or
9650 @item @emph{Return value}:
9651 The return value is of type @code{REAL} or @code{COMPLEX}.
9652 The kind type parameter is the same as @var{X}.
9653 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
9654 @math{-\pi < \omega \leq \pi}.
9656 @item @emph{Example}:
9659 real(8) :: x = 2.7182818284590451_8
9660 complex :: z = (1.0, 2.0)
9661 x = log(x) ! will yield (approximately) 1
9663 end program test_log
9666 @item @emph{Specific names}:
9667 @multitable @columnfractions .20 .23 .20 .33
9668 @headitem Name @tab Argument @tab Return type @tab Standard
9669 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 or later
9670 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 or later
9671 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 or later
9672 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
9673 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
9680 @section @code{LOG10} --- Base 10 logarithm function
9684 @cindex exponential function, inverse
9685 @cindex logarithm function with base 10
9686 @cindex base 10 logarithm function
9689 @item @emph{Description}:
9690 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
9692 @item @emph{Standard}:
9693 Fortran 77 and later
9698 @item @emph{Syntax}:
9699 @code{RESULT = LOG10(X)}
9701 @item @emph{Arguments}:
9702 @multitable @columnfractions .15 .70
9703 @item @var{X} @tab The type shall be @code{REAL}.
9706 @item @emph{Return value}:
9707 The return value is of type @code{REAL} or @code{COMPLEX}.
9708 The kind type parameter is the same as @var{X}.
9710 @item @emph{Example}:
9713 real(8) :: x = 10.0_8
9715 end program test_log10
9718 @item @emph{Specific names}:
9719 @multitable @columnfractions .20 .23 .20 .33
9720 @headitem Name @tab Argument @tab Return type @tab Standard
9721 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
9722 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
9729 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
9734 @cindex Gamma function, logarithm of
9737 @item @emph{Description}:
9738 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
9739 of the Gamma (@math{\Gamma}) function.
9741 @item @emph{Standard}:
9742 Fortran 2008 and later
9747 @item @emph{Syntax}:
9748 @code{X = LOG_GAMMA(X)}
9750 @item @emph{Arguments}:
9751 @multitable @columnfractions .15 .70
9752 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
9753 nor a negative integer.
9756 @item @emph{Return value}:
9757 The return value is of type @code{REAL} of the same kind as @var{X}.
9759 @item @emph{Example}:
9761 program test_log_gamma
9763 x = lgamma(x) ! returns 0.0
9764 end program test_log_gamma
9767 @item @emph{Specific names}:
9768 @multitable @columnfractions .20 .23 .20 .33
9769 @headitem Name @tab Argument @tab Return type @tab Standard
9770 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
9771 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
9772 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
9775 @item @emph{See also}:
9783 @section @code{LOGICAL} --- Convert to logical type
9785 @cindex conversion, to logical
9788 @item @emph{Description}:
9789 Converts one kind of @code{LOGICAL} variable to another.
9791 @item @emph{Standard}:
9792 Fortran 90 and later
9797 @item @emph{Syntax}:
9798 @code{RESULT = LOGICAL(L [, KIND])}
9800 @item @emph{Arguments}:
9801 @multitable @columnfractions .15 .70
9802 @item @var{L} @tab The type shall be @code{LOGICAL}.
9803 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
9804 expression indicating the kind parameter of the result.
9807 @item @emph{Return value}:
9808 The return value is a @code{LOGICAL} value equal to @var{L}, with a
9809 kind corresponding to @var{KIND}, or of the default logical kind if
9810 @var{KIND} is not given.
9812 @item @emph{See also}:
9821 @section @code{LSHIFT} --- Left shift bits
9823 @cindex bits, shift left
9826 @item @emph{Description}:
9827 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
9828 bits shifted left by @var{SHIFT} places. @var{SHIFT} shall be
9829 nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
9830 the result value is undefined. Bits shifted out from the left end are
9831 lost; zeros are shifted in from the opposite end.
9833 This function has been superseded by the @code{ISHFT} intrinsic, which
9834 is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
9835 which is standard in Fortran 2008 and later.
9837 @item @emph{Standard}:
9843 @item @emph{Syntax}:
9844 @code{RESULT = LSHIFT(I, SHIFT)}
9846 @item @emph{Arguments}:
9847 @multitable @columnfractions .15 .70
9848 @item @var{I} @tab The type shall be @code{INTEGER}.
9849 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
9852 @item @emph{Return value}:
9853 The return value is of type @code{INTEGER} and of the same kind as
9856 @item @emph{See also}:
9868 @section @code{LSTAT} --- Get file status
9870 @cindex file system, file status
9873 @item @emph{Description}:
9874 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
9875 symbolic link, then the link itself is statted, not the file that it
9878 The elements in @code{VALUES} are the same as described by @ref{STAT}.
9880 This intrinsic is provided in both subroutine and function forms;
9881 however, only one form can be used in any given program unit.
9883 @item @emph{Standard}:
9887 Subroutine, function
9889 @item @emph{Syntax}:
9890 @multitable @columnfractions .80
9891 @item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
9892 @item @code{STATUS = LSTAT(NAME, VALUES)}
9895 @item @emph{Arguments}:
9896 @multitable @columnfractions .15 .70
9897 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
9898 kind, a valid path within the file system.
9899 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
9900 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
9901 Returns 0 on success and a system specific error code otherwise.
9904 @item @emph{Example}:
9905 See @ref{STAT} for an example.
9907 @item @emph{See also}:
9908 To stat an open file: @*
9917 @section @code{LTIME} --- Convert time to local time info
9919 @cindex time, conversion to local time info
9922 @item @emph{Description}:
9923 Given a system time value @var{TIME} (as provided by the @ref{TIME}
9924 intrinsic), fills @var{VALUES} with values extracted from it appropriate
9925 to the local time zone using @code{localtime(3)}.
9927 This intrinsic routine is provided for backwards compatibility with
9928 GNU Fortran 77. In new code, programmers should consider the use of
9929 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
9932 @item @emph{Standard}:
9938 @item @emph{Syntax}:
9939 @code{CALL LTIME(TIME, VALUES)}
9941 @item @emph{Arguments}:
9942 @multitable @columnfractions .15 .70
9943 @item @var{TIME} @tab An @code{INTEGER} scalar expression
9944 corresponding to a system time, with @code{INTENT(IN)}.
9945 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
9946 with @code{INTENT(OUT)}.
9949 @item @emph{Return value}:
9950 The elements of @var{VALUES} are assigned as follows:
9952 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
9954 @item Minutes after the hour, range 0--59
9955 @item Hours past midnight, range 0--23
9956 @item Day of month, range 1--31
9957 @item Number of months since January, range 0--11
9958 @item Years since 1900
9959 @item Number of days since Sunday, range 0--6
9960 @item Days since January 1, range 0--365
9961 @item Daylight savings indicator: positive if daylight savings is in
9962 effect, zero if not, and negative if the information is not available.
9965 @item @emph{See also}:
9966 @ref{DATE_AND_TIME}, @*
9976 @section @code{MALLOC} --- Allocate dynamic memory
9978 @cindex pointer, cray
9981 @item @emph{Description}:
9982 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
9983 returns the address of the allocated memory. The @code{MALLOC} intrinsic
9984 is an extension intended to be used with Cray pointers, and is provided
9985 in GNU Fortran to allow the user to compile legacy code. For new code
9986 using Fortran 95 pointers, the memory allocation intrinsic is
9989 @item @emph{Standard}:
9995 @item @emph{Syntax}:
9996 @code{PTR = MALLOC(SIZE)}
9998 @item @emph{Arguments}:
9999 @multitable @columnfractions .15 .70
10000 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
10003 @item @emph{Return value}:
10004 The return value is of type @code{INTEGER(K)}, with @var{K} such that
10005 variables of type @code{INTEGER(K)} have the same size as
10006 C pointers (@code{sizeof(void *)}).
10008 @item @emph{Example}:
10009 The following example demonstrates the use of @code{MALLOC} and
10010 @code{FREE} with Cray pointers.
10013 program test_malloc
10019 ptr_x = malloc(20*8)
10021 x(i) = sqrt(1.0d0 / i)
10029 end program test_malloc
10032 @item @emph{See also}:
10039 @section @code{MASKL} --- Left justified mask
10041 @cindex mask, left justified
10044 @item @emph{Description}:
10045 @code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
10046 remaining bits set to 0.
10048 @item @emph{Standard}:
10049 Fortran 2008 and later
10051 @item @emph{Class}:
10054 @item @emph{Syntax}:
10055 @code{RESULT = MASKL(I[, KIND])}
10057 @item @emph{Arguments}:
10058 @multitable @columnfractions .15 .70
10059 @item @var{I} @tab Shall be of type @code{INTEGER}.
10060 @item @var{KIND} @tab Shall be a scalar constant expression of type
10064 @item @emph{Return value}:
10065 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
10066 specifies the kind value of the return type; otherwise, it is of the
10067 default integer kind.
10069 @item @emph{See also}:
10076 @section @code{MASKR} --- Right justified mask
10078 @cindex mask, right justified
10081 @item @emph{Description}:
10082 @code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
10083 remaining bits set to 0.
10085 @item @emph{Standard}:
10086 Fortran 2008 and later
10088 @item @emph{Class}:
10091 @item @emph{Syntax}:
10092 @code{RESULT = MASKR(I[, KIND])}
10094 @item @emph{Arguments}:
10095 @multitable @columnfractions .15 .70
10096 @item @var{I} @tab Shall be of type @code{INTEGER}.
10097 @item @var{KIND} @tab Shall be a scalar constant expression of type
10101 @item @emph{Return value}:
10102 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
10103 specifies the kind value of the return type; otherwise, it is of the
10104 default integer kind.
10106 @item @emph{See also}:
10113 @section @code{MATMUL} --- matrix multiplication
10115 @cindex matrix multiplication
10116 @cindex product, matrix
10119 @item @emph{Description}:
10120 Performs a matrix multiplication on numeric or logical arguments.
10122 @item @emph{Standard}:
10123 Fortran 90 and later
10125 @item @emph{Class}:
10126 Transformational function
10128 @item @emph{Syntax}:
10129 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
10131 @item @emph{Arguments}:
10132 @multitable @columnfractions .15 .70
10133 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
10134 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
10136 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
10137 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
10138 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
10139 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
10140 equal to the last (or only) dimension of @var{MATRIX_A}.
10141 @var{MATRIX_A} and @var{MATRIX_B} shall not both be rank one arrays.
10144 @item @emph{Return value}:
10145 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
10146 kind of the result follow the usual type and kind promotion rules, as
10147 for the @code{*} or @code{.AND.} operators.
10153 @section @code{MAX} --- Maximum value of an argument list
10160 @cindex maximum value
10163 @item @emph{Description}:
10164 Returns the argument with the largest (most positive) value.
10166 @item @emph{Standard}:
10167 Fortran 77 and later
10169 @item @emph{Class}:
10172 @item @emph{Syntax}:
10173 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
10175 @item @emph{Arguments}:
10176 @multitable @columnfractions .15 .70
10177 @item @var{A1} @tab The type shall be @code{INTEGER} or
10179 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
10180 as @var{A1}. (As a GNU extension, arguments of different kinds are
10184 @item @emph{Return value}:
10185 The return value corresponds to the maximum value among the arguments,
10186 and has the same type and kind as the first argument.
10188 @item @emph{Specific names}:
10189 @multitable @columnfractions .20 .23 .20 .33
10190 @headitem Name @tab Argument @tab Return type @tab Standard
10191 @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
10192 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
10193 @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
10194 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
10195 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
10198 @item @emph{See also}:
10207 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
10208 @fnindex MAXEXPONENT
10209 @cindex model representation, maximum exponent
10212 @item @emph{Description}:
10213 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
10216 @item @emph{Standard}:
10217 Fortran 90 and later
10219 @item @emph{Class}:
10222 @item @emph{Syntax}:
10223 @code{RESULT = MAXEXPONENT(X)}
10225 @item @emph{Arguments}:
10226 @multitable @columnfractions .15 .70
10227 @item @var{X} @tab Shall be of type @code{REAL}.
10230 @item @emph{Return value}:
10231 The return value is of type @code{INTEGER} and of the default integer
10234 @item @emph{Example}:
10240 print *, minexponent(x), maxexponent(x)
10241 print *, minexponent(y), maxexponent(y)
10242 end program exponents
10249 @section @code{MAXLOC} --- Location of the maximum value within an array
10251 @cindex array, location of maximum element
10254 @item @emph{Description}:
10255 Determines the location of the element in the array with the maximum
10256 value, or, if the @var{DIM} argument is supplied, determines the
10257 locations of the maximum element along each row of the array in the
10258 @var{DIM} direction. If @var{MASK} is present, only the elements for
10259 which @var{MASK} is @code{.TRUE.} are considered. If more than one
10260 element in the array has the maximum value, the location returned is
10261 that of the first such element in array element order if the
10262 @var{BACK} is not present, or is false; if @var{BACK} is true, the location
10263 returned is that of the last such element. If the array has zero
10264 size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
10265 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
10266 and all of the elements of @var{MASK} along a given row are zero, the
10267 result value for that row is zero.
10269 @item @emph{Standard}:
10270 Fortran 95 and later; @var{ARRAY} of @code{CHARACTER} and the
10271 @var{KIND} argument are available in Fortran 2003 and later.
10272 The @var{BACK} argument is available in Fortran 2008 and later.
10274 @item @emph{Class}:
10275 Transformational function
10277 @item @emph{Syntax}:
10278 @multitable @columnfractions .80
10279 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK])}
10280 @item @code{RESULT = MAXLOC(ARRAY [, MASK] [,KIND] [,BACK])}
10283 @item @emph{Arguments}:
10284 @multitable @columnfractions .15 .70
10285 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10287 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10288 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10289 inclusive. It may not be an optional dummy argument.
10290 @item @var{MASK} @tab Shall be of type @code{LOGICAL},
10291 and conformable with @var{ARRAY}.
10292 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
10293 expression indicating the kind parameter of the result.
10294 @item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}.
10297 @item @emph{Return value}:
10298 If @var{DIM} is absent, the result is a rank-one array with a length
10299 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
10300 is an array with a rank one less than the rank of @var{ARRAY}, and a
10301 size corresponding to the size of @var{ARRAY} with the @var{DIM}
10302 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
10303 of one, the result is a scalar. If the optional argument @var{KIND}
10304 is present, the result is an integer of kind @var{KIND}, otherwise it
10305 is of default kind.
10307 @item @emph{See also}:
10316 @section @code{MAXVAL} --- Maximum value of an array
10318 @cindex array, maximum value
10319 @cindex maximum value
10322 @item @emph{Description}:
10323 Determines the maximum value of the elements in an array value, or, if
10324 the @var{DIM} argument is supplied, determines the maximum value along
10325 each row of the array in the @var{DIM} direction. If @var{MASK} is
10326 present, only the elements for which @var{MASK} is @code{.TRUE.} are
10327 considered. If the array has zero size, or all of the elements of
10328 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
10329 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
10332 @item @emph{Standard}:
10333 Fortran 90 and later
10335 @item @emph{Class}:
10336 Transformational function
10338 @item @emph{Syntax}:
10339 @multitable @columnfractions .80
10340 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
10341 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
10344 @item @emph{Arguments}:
10345 @multitable @columnfractions .15 .70
10346 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10348 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10349 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10350 inclusive. It may not be an optional dummy argument.
10351 @item @var{MASK} @tab (Optional) Shall be of type @code{LOGICAL},
10352 and conformable with @var{ARRAY}.
10355 @item @emph{Return value}:
10356 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
10357 is a scalar. If @var{DIM} is present, the result is an array with a
10358 rank one less than the rank of @var{ARRAY}, and a size corresponding to
10359 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
10360 cases, the result is of the same type and kind as @var{ARRAY}.
10362 @item @emph{See also}:
10370 @section @code{MCLOCK} --- Time function
10372 @cindex time, clock ticks
10373 @cindex clock ticks
10376 @item @emph{Description}:
10377 Returns the number of clock ticks since the start of the process, based
10378 on the function @code{clock(3)} in the C standard library.
10380 This intrinsic is not fully portable, such as to systems with 32-bit
10381 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
10382 the values returned by this intrinsic might be, or become, negative, or
10383 numerically less than previous values, during a single run of the
10386 @item @emph{Standard}:
10389 @item @emph{Class}:
10392 @item @emph{Syntax}:
10393 @code{RESULT = MCLOCK()}
10395 @item @emph{Return value}:
10396 The return value is a scalar of type @code{INTEGER(4)}, equal to the
10397 number of clock ticks since the start of the process, or @code{-1} if
10398 the system does not support @code{clock(3)}.
10400 @item @emph{See also}:
10411 @section @code{MCLOCK8} --- Time function (64-bit)
10413 @cindex time, clock ticks
10414 @cindex clock ticks
10417 @item @emph{Description}:
10418 Returns the number of clock ticks since the start of the process, based
10419 on the function @code{clock(3)} in the C standard library.
10421 @emph{Warning:} this intrinsic does not increase the range of the timing
10422 values over that returned by @code{clock(3)}. On a system with a 32-bit
10423 @code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though
10424 it is converted to a 64-bit @code{INTEGER(8)} value. That means
10425 overflows of the 32-bit value can still occur. Therefore, the values
10426 returned by this intrinsic might be or become negative or numerically
10427 less than previous values during a single run of the compiled program.
10429 @item @emph{Standard}:
10432 @item @emph{Class}:
10435 @item @emph{Syntax}:
10436 @code{RESULT = MCLOCK8()}
10438 @item @emph{Return value}:
10439 The return value is a scalar of type @code{INTEGER(8)}, equal to the
10440 number of clock ticks since the start of the process, or @code{-1} if
10441 the system does not support @code{clock(3)}.
10443 @item @emph{See also}:
10454 @section @code{MERGE} --- Merge variables
10456 @cindex array, merge arrays
10457 @cindex array, combine arrays
10460 @item @emph{Description}:
10461 Select values from two arrays according to a logical mask. The result
10462 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
10463 @var{FSOURCE} if it is @code{.FALSE.}.
10465 @item @emph{Standard}:
10466 Fortran 90 and later
10468 @item @emph{Class}:
10471 @item @emph{Syntax}:
10472 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
10474 @item @emph{Arguments}:
10475 @multitable @columnfractions .15 .70
10476 @item @var{TSOURCE} @tab May be of any type.
10477 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
10479 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
10482 @item @emph{Return value}:
10483 The result is of the same type and type parameters as @var{TSOURCE}.
10490 @section @code{MERGE_BITS} --- Merge of bits under mask
10491 @fnindex MERGE_BITS
10492 @cindex bits, merge
10495 @item @emph{Description}:
10496 @code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
10497 as determined by the mask. The i-th bit of the result is equal to the
10498 i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
10499 the i-th bit of @var{J} otherwise.
10501 @item @emph{Standard}:
10502 Fortran 2008 and later
10504 @item @emph{Class}:
10507 @item @emph{Syntax}:
10508 @code{RESULT = MERGE_BITS(I, J, MASK)}
10510 @item @emph{Arguments}:
10511 @multitable @columnfractions .15 .70
10512 @item @var{I} @tab Shall be of type @code{INTEGER} or a boz-literal-constant.
10513 @item @var{J} @tab Shall be of type @code{INTEGER} with the same
10514 kind type parameter as @var{I} or a boz-literal-constant.
10515 @var{I} and @var{J} shall not both be boz-literal-constants.
10516 @item @var{MASK} @tab Shall be of type @code{INTEGER} or a boz-literal-constant
10517 and of the same kind as @var{I}.
10520 @item @emph{Return value}:
10521 The result is of the same type and kind as @var{I}.
10528 @section @code{MIN} --- Minimum value of an argument list
10535 @cindex minimum value
10538 @item @emph{Description}:
10539 Returns the argument with the smallest (most negative) value.
10541 @item @emph{Standard}:
10542 Fortran 77 and later
10544 @item @emph{Class}:
10547 @item @emph{Syntax}:
10548 @code{RESULT = MIN(A1, A2 [, A3, ...])}
10550 @item @emph{Arguments}:
10551 @multitable @columnfractions .15 .70
10552 @item @var{A1} @tab The type shall be @code{INTEGER} or
10554 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
10555 as @var{A1}. (As a GNU extension, arguments of different kinds are
10559 @item @emph{Return value}:
10560 The return value corresponds to the minimum value among the arguments,
10561 and has the same type and kind as the first argument.
10563 @item @emph{Specific names}:
10564 @multitable @columnfractions .20 .23 .20 .33
10565 @headitem Name @tab Argument @tab Return type @tab Standard
10566 @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
10567 @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
10568 @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
10569 @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
10570 @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
10573 @item @emph{See also}:
10582 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
10583 @fnindex MINEXPONENT
10584 @cindex model representation, minimum exponent
10587 @item @emph{Description}:
10588 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
10591 @item @emph{Standard}:
10592 Fortran 90 and later
10594 @item @emph{Class}:
10597 @item @emph{Syntax}:
10598 @code{RESULT = MINEXPONENT(X)}
10600 @item @emph{Arguments}:
10601 @multitable @columnfractions .15 .70
10602 @item @var{X} @tab Shall be of type @code{REAL}.
10605 @item @emph{Return value}:
10606 The return value is of type @code{INTEGER} and of the default integer
10609 @item @emph{Example}:
10610 See @code{MAXEXPONENT} for an example.
10616 @section @code{MINLOC} --- Location of the minimum value within an array
10618 @cindex array, location of minimum element
10621 @item @emph{Description}:
10622 Determines the location of the element in the array with the minimum
10623 value, or, if the @var{DIM} argument is supplied, determines the
10624 locations of the minimum element along each row of the array in the
10625 @var{DIM} direction. If @var{MASK} is present, only the elements for
10626 which @var{MASK} is @code{.TRUE.} are considered. If more than one
10627 element in the array has the minimum value, the location returned is
10628 that of the first such element in array element order if the
10629 @var{BACK} is not present, or is false; if @var{BACK} is true, the location
10630 returned is that of the last such element. If the array has
10631 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
10632 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
10633 and all of the elements of @var{MASK} along a given row are zero, the
10634 result value for that row is zero.
10636 @item @emph{Standard}:
10637 Fortran 90 and later; @var{ARRAY} of @code{CHARACTER} and the
10638 @var{KIND} argument are available in Fortran 2003 and later.
10639 The @var{BACK} argument is available in Fortran 2008 and later.
10641 @item @emph{Class}:
10642 Transformational function
10644 @item @emph{Syntax}:
10645 @multitable @columnfractions .80
10646 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK])}
10647 @item @code{RESULT = MINLOC(ARRAY [, MASK], [,KIND] [,BACK])}
10650 @item @emph{Arguments}:
10651 @multitable @columnfractions .15 .70
10652 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
10653 @code{REAL} or @code{CHARACTER}.
10654 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10655 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10656 inclusive. It may not be an optional dummy argument.
10657 @item @var{MASK} @tab Shall be of type @code{LOGICAL},
10658 and conformable with @var{ARRAY}.
10659 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
10660 expression indicating the kind parameter of the result.
10661 @item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}.
10664 @item @emph{Return value}:
10665 If @var{DIM} is absent, the result is a rank-one array with a length
10666 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
10667 is an array with a rank one less than the rank of @var{ARRAY}, and a
10668 size corresponding to the size of @var{ARRAY} with the @var{DIM}
10669 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
10670 of one, the result is a scalar. If the optional argument @var{KIND}
10671 is present, the result is an integer of kind @var{KIND}, otherwise it
10672 is of default kind.
10674 @item @emph{See also}:
10683 @section @code{MINVAL} --- Minimum value of an array
10685 @cindex array, minimum value
10686 @cindex minimum value
10689 @item @emph{Description}:
10690 Determines the minimum value of the elements in an array value, or, if
10691 the @var{DIM} argument is supplied, determines the minimum value along
10692 each row of the array in the @var{DIM} direction. If @var{MASK} is
10693 present, only the elements for which @var{MASK} is @code{.TRUE.} are
10694 considered. If the array has zero size, or all of the elements of
10695 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
10696 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
10697 @var{ARRAY} is of character type.
10699 @item @emph{Standard}:
10700 Fortran 90 and later
10702 @item @emph{Class}:
10703 Transformational function
10705 @item @emph{Syntax}:
10706 @multitable @columnfractions .80
10707 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
10708 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
10711 @item @emph{Arguments}:
10712 @multitable @columnfractions .15 .70
10713 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10715 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10716 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10717 inclusive. It may not be an optional dummy argument.
10718 @item @var{MASK} @tab Shall be of type @code{LOGICAL},
10719 and conformable with @var{ARRAY}.
10722 @item @emph{Return value}:
10723 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
10724 is a scalar. If @var{DIM} is present, the result is an array with a
10725 rank one less than the rank of @var{ARRAY}, and a size corresponding to
10726 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
10727 cases, the result is of the same type and kind as @var{ARRAY}.
10729 @item @emph{See also}:
10737 @section @code{MOD} --- Remainder function
10746 @cindex division, remainder
10749 @item @emph{Description}:
10750 @code{MOD(A,P)} computes the remainder of the division of A by P@.
10752 @item @emph{Standard}:
10753 Fortran 77 and later, has overloads that are GNU extensions
10755 @item @emph{Class}:
10758 @item @emph{Syntax}:
10759 @code{RESULT = MOD(A, P)}
10761 @item @emph{Arguments}:
10762 @multitable @columnfractions .15 .70
10763 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
10764 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
10765 and not equal to zero. (As a GNU extension, arguments of different kinds are
10769 @item @emph{Return value}:
10770 The return value is the result of @code{A - (INT(A/P) * P)}. The type
10771 and kind of the return value is the same as that of the arguments. The
10772 returned value has the same sign as A and a magnitude less than the
10773 magnitude of P. (As a GNU extension, kind is the largest kind of the actual
10776 @item @emph{Example}:
10780 print *, mod(17.5,5.5)
10781 print *, mod(17.5d0,5.5)
10782 print *, mod(17.5,5.5d0)
10784 print *, mod(-17,3)
10785 print *, mod(-17.5,5.5)
10786 print *, mod(-17.5d0,5.5)
10787 print *, mod(-17.5,5.5d0)
10789 print *, mod(17,-3)
10790 print *, mod(17.5,-5.5)
10791 print *, mod(17.5d0,-5.5)
10792 print *, mod(17.5,-5.5d0)
10793 end program test_mod
10796 @item @emph{Specific names}:
10797 @multitable @columnfractions .20 .25 .20 .31
10798 @headitem Name @tab Arguments @tab Return type @tab Standard
10799 @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 77 and later
10800 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 77 and later
10801 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 77 and later
10802 @item @code{BMOD(A,P)} @tab @code{INTEGER(1) A,P} @tab @code{INTEGER(1)} @tab GNU extension
10803 @item @code{IMOD(A,P)} @tab @code{INTEGER(2) A,P} @tab @code{INTEGER(2)} @tab GNU extension
10804 @item @code{JMOD(A,P)} @tab @code{INTEGER(4) A,P} @tab @code{INTEGER(4)} @tab GNU extension
10805 @item @code{KMOD(A,P)} @tab @code{INTEGER(8) A,P} @tab @code{INTEGER(8)} @tab GNU extension
10808 @item @emph{See also}:
10816 @section @code{MODULO} --- Modulo function
10819 @cindex division, modulo
10822 @item @emph{Description}:
10823 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
10825 @item @emph{Standard}:
10826 Fortran 95 and later
10828 @item @emph{Class}:
10831 @item @emph{Syntax}:
10832 @code{RESULT = MODULO(A, P)}
10834 @item @emph{Arguments}:
10835 @multitable @columnfractions .15 .70
10836 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
10837 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}.
10838 It shall not be zero. (As a GNU extension, arguments of different kinds are
10842 @item @emph{Return value}:
10843 The type and kind of the result are those of the arguments. (As a GNU
10844 extension, kind is the largest kind of the actual arguments.)
10846 @item If @var{A} and @var{P} are of type @code{INTEGER}:
10847 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
10848 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
10850 @item If @var{A} and @var{P} are of type @code{REAL}:
10851 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
10853 The returned value has the same sign as P and a magnitude less than
10854 the magnitude of P.
10856 @item @emph{Example}:
10858 program test_modulo
10859 print *, modulo(17,3)
10860 print *, modulo(17.5,5.5)
10862 print *, modulo(-17,3)
10863 print *, modulo(-17.5,5.5)
10865 print *, modulo(17,-3)
10866 print *, modulo(17.5,-5.5)
10870 @item @emph{See also}:
10878 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
10879 @fnindex MOVE_ALLOC
10880 @cindex moving allocation
10881 @cindex allocation, moving
10884 @item @emph{Description}:
10885 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
10886 @var{TO}. @var{FROM} will become deallocated in the process.
10888 @item @emph{Standard}:
10889 Fortran 2003 and later
10891 @item @emph{Class}:
10894 @item @emph{Syntax}:
10895 @code{CALL MOVE_ALLOC(FROM, TO)}
10897 @item @emph{Arguments}:
10898 @multitable @columnfractions .15 .70
10899 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
10900 of any type and kind.
10901 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
10902 of the same type, kind and rank as @var{FROM}.
10905 @item @emph{Return value}:
10908 @item @emph{Example}:
10910 program test_move_alloc
10911 integer, allocatable :: a(:), b(:)
10915 call move_alloc(a, b)
10916 print *, allocated(a), allocated(b)
10918 end program test_move_alloc
10925 @section @code{MVBITS} --- Move bits from one integer to another
10934 @item @emph{Description}:
10935 Moves @var{LEN} bits from positions @var{FROMPOS} through
10936 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
10937 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
10938 affected by the movement of bits is unchanged. The values of
10939 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
10940 @code{BIT_SIZE(FROM)}.
10942 @item @emph{Standard}:
10943 Fortran 90 and later, has overloads that are GNU extensions
10945 @item @emph{Class}:
10946 Elemental subroutine
10948 @item @emph{Syntax}:
10949 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
10951 @item @emph{Arguments}:
10952 @multitable @columnfractions .15 .70
10953 @item @var{FROM} @tab The type shall be @code{INTEGER}.
10954 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
10955 @item @var{LEN} @tab The type shall be @code{INTEGER}.
10956 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
10957 same kind as @var{FROM}.
10958 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
10961 @item @emph{Specific names}:
10962 @multitable @columnfractions .20 .23 .20 .33
10963 @headitem Name @tab Argument @tab Return type @tab Standard
10964 @item @code{MVBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
10965 @item @code{BMVBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
10966 @item @code{IMVBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
10967 @item @code{JMVBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
10968 @item @code{KMVBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
10971 @item @emph{See also}:
10983 @section @code{NEAREST} --- Nearest representable number
10985 @cindex real number, nearest different
10986 @cindex floating point, nearest different
10989 @item @emph{Description}:
10990 @code{NEAREST(X, S)} returns the processor-representable number nearest
10991 to @code{X} in the direction indicated by the sign of @code{S}.
10993 @item @emph{Standard}:
10994 Fortran 90 and later
10996 @item @emph{Class}:
10999 @item @emph{Syntax}:
11000 @code{RESULT = NEAREST(X, S)}
11002 @item @emph{Arguments}:
11003 @multitable @columnfractions .15 .70
11004 @item @var{X} @tab Shall be of type @code{REAL}.
11005 @item @var{S} @tab Shall be of type @code{REAL} and
11009 @item @emph{Return value}:
11010 The return value is of the same type as @code{X}. If @code{S} is
11011 positive, @code{NEAREST} returns the processor-representable number
11012 greater than @code{X} and nearest to it. If @code{S} is negative,
11013 @code{NEAREST} returns the processor-representable number smaller than
11014 @code{X} and nearest to it.
11016 @item @emph{Example}:
11018 program test_nearest
11020 x = nearest(42.0, 1.0)
11021 y = nearest(42.0, -1.0)
11022 write (*,"(3(G20.15))") x, y, x - y
11023 end program test_nearest
11030 @section @code{NEW_LINE} --- New line character
11033 @cindex output, newline
11036 @item @emph{Description}:
11037 @code{NEW_LINE(C)} returns the new-line character.
11039 @item @emph{Standard}:
11040 Fortran 2003 and later
11042 @item @emph{Class}:
11045 @item @emph{Syntax}:
11046 @code{RESULT = NEW_LINE(C)}
11048 @item @emph{Arguments}:
11049 @multitable @columnfractions .15 .70
11050 @item @var{C} @tab The argument shall be a scalar or array of the
11051 type @code{CHARACTER}.
11054 @item @emph{Return value}:
11055 Returns a @var{CHARACTER} scalar of length one with the new-line character of
11056 the same kind as parameter @var{C}.
11058 @item @emph{Example}:
11062 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
11063 end program newline
11070 @section @code{NINT} --- Nearest whole number
11073 @cindex rounding, nearest whole number
11076 @item @emph{Description}:
11077 @code{NINT(A)} rounds its argument to the nearest whole number.
11079 @item @emph{Standard}:
11080 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
11082 @item @emph{Class}:
11085 @item @emph{Syntax}:
11086 @code{RESULT = NINT(A [, KIND])}
11088 @item @emph{Arguments}:
11089 @multitable @columnfractions .15 .70
11090 @item @var{A} @tab The type of the argument shall be @code{REAL}.
11091 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
11092 expression indicating the kind parameter of the result.
11095 @item @emph{Return value}:
11096 Returns @var{A} with the fractional portion of its magnitude eliminated by
11097 rounding to the nearest whole number and with its sign preserved,
11098 converted to an @code{INTEGER} of the default kind.
11100 @item @emph{Example}:
11107 print *, nint(x4), idnint(x8)
11108 end program test_nint
11111 @item @emph{Specific names}:
11112 @multitable @columnfractions .20 .23 .20 .33
11113 @headitem Name @tab Argument @tab Return Type @tab Standard
11114 @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
11115 @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
11118 @item @emph{See also}:
11126 @section @code{NORM2} --- Euclidean vector norms
11128 @cindex Euclidean vector norm
11129 @cindex L2 vector norm
11130 @cindex norm, Euclidean
11133 @item @emph{Description}:
11134 Calculates the Euclidean vector norm (@math{L_2} norm)
11135 of @var{ARRAY} along dimension @var{DIM}.
11137 @item @emph{Standard}:
11138 Fortran 2008 and later
11140 @item @emph{Class}:
11141 Transformational function
11143 @item @emph{Syntax}:
11144 @multitable @columnfractions .80
11145 @item @code{RESULT = NORM2(ARRAY[, DIM])}
11148 @item @emph{Arguments}:
11149 @multitable @columnfractions .15 .70
11150 @item @var{ARRAY} @tab Shall be an array of type @code{REAL}
11151 @item @var{DIM} @tab (Optional) shall be a scalar of type
11152 @code{INTEGER} with a value in the range from 1 to n, where n
11153 equals the rank of @var{ARRAY}.
11156 @item @emph{Return value}:
11157 The result is of the same type as @var{ARRAY}.
11159 If @var{DIM} is absent, a scalar with the square root of the sum of all
11160 elements in @var{ARRAY} squared is returned. Otherwise, an array of
11161 rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
11162 shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
11165 @item @emph{Example}:
11168 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
11169 print *, NORM2(x) ! = sqrt(55.) ~ 7.416
11177 @section @code{NOT} --- Logical negation
11183 @cindex bits, negate
11184 @cindex bitwise logical not
11185 @cindex logical not, bitwise
11188 @item @emph{Description}:
11189 @code{NOT} returns the bitwise Boolean inverse of @var{I}.
11191 @item @emph{Standard}:
11192 Fortran 90 and later, has overloads that are GNU extensions
11194 @item @emph{Class}:
11197 @item @emph{Syntax}:
11198 @code{RESULT = NOT(I)}
11200 @item @emph{Arguments}:
11201 @multitable @columnfractions .15 .70
11202 @item @var{I} @tab The type shall be @code{INTEGER}.
11205 @item @emph{Return value}:
11206 The return type is @code{INTEGER}, of the same kind as the
11209 @item @emph{Specific names}:
11210 @multitable @columnfractions .20 .23 .20 .33
11211 @headitem Name @tab Argument @tab Return type @tab Standard
11212 @item @code{NOT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
11213 @item @code{BNOT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
11214 @item @code{INOT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
11215 @item @code{JNOT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
11216 @item @code{KNOT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
11219 @item @emph{See also}:
11231 @section @code{NULL} --- Function that returns an disassociated pointer
11233 @cindex pointer, status
11234 @cindex pointer, disassociated
11237 @item @emph{Description}:
11238 Returns a disassociated pointer.
11240 If @var{MOLD} is present, a disassociated pointer of the same type is
11241 returned, otherwise the type is determined by context.
11243 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
11244 includes cases where it is required.
11246 @item @emph{Standard}:
11247 Fortran 95 and later
11249 @item @emph{Class}:
11250 Transformational function
11252 @item @emph{Syntax}:
11253 @code{PTR => NULL([MOLD])}
11255 @item @emph{Arguments}:
11256 @multitable @columnfractions .15 .70
11257 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
11258 status and of any type.
11261 @item @emph{Return value}:
11262 A disassociated pointer.
11264 @item @emph{Example}:
11266 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
11269 @item @emph{See also}:
11276 @section @code{NUM_IMAGES} --- Function that returns the number of images
11277 @fnindex NUM_IMAGES
11278 @cindex coarray, @code{NUM_IMAGES}
11279 @cindex images, number of
11282 @item @emph{Description}:
11283 Returns the number of images.
11285 @item @emph{Standard}:
11286 Fortran 2008 and later. With @var{DISTANCE} or @var{FAILED} argument,
11287 Technical Specification (TS) 18508 or later
11290 @item @emph{Class}:
11291 Transformational function
11293 @item @emph{Syntax}:
11294 @code{RESULT = NUM_IMAGES(DISTANCE, FAILED)}
11296 @item @emph{Arguments}:
11297 @multitable @columnfractions .15 .70
11298 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
11299 @item @var{FAILED} @tab (optional, intent(in)) Scalar logical expression
11302 @item @emph{Return value}:
11303 Scalar default-kind integer. If @var{DISTANCE} is not present or has value 0,
11304 the number of images in the current team is returned. For values smaller or
11305 equal distance to the initial team, it returns the number of images index
11306 on the ancestor team which has a distance of @var{DISTANCE} from the invoking
11307 team. If @var{DISTANCE} is larger than the distance to the initial team, the
11308 number of images of the initial team is returned. If @var{FAILED} is not present
11309 the total number of images is returned; if it has the value @code{.TRUE.},
11310 the number of failed images is returned, otherwise, the number of images which
11311 do have not the failed status.
11313 @item @emph{Example}:
11315 INTEGER :: value[*]
11317 value = THIS_IMAGE()
11319 IF (THIS_IMAGE() == 1) THEN
11320 DO i = 1, NUM_IMAGES()
11321 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
11326 @item @emph{See also}:
11327 @ref{THIS_IMAGE}, @*
11334 @section @code{OR} --- Bitwise logical OR
11336 @cindex bitwise logical or
11337 @cindex logical or, bitwise
11340 @item @emph{Description}:
11341 Bitwise logical @code{OR}.
11343 This intrinsic routine is provided for backwards compatibility with
11344 GNU Fortran 77. For integer arguments, programmers should consider
11345 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
11347 @item @emph{Standard}:
11350 @item @emph{Class}:
11353 @item @emph{Syntax}:
11354 @code{RESULT = OR(I, J)}
11356 @item @emph{Arguments}:
11357 @multitable @columnfractions .15 .70
11358 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
11359 type or a scalar @code{LOGICAL} type or a boz-literal-constant.
11360 @item @var{J} @tab The type shall be the same as the type of @var{I} or
11361 a boz-literal-constant. @var{I} and @var{J} shall not both be
11362 boz-literal-constants. If either @var{I} and @var{J} is a
11363 boz-literal-constant, then the other argument must be a scalar @code{INTEGER}.
11366 @item @emph{Return value}:
11367 The return type is either a scalar @code{INTEGER} or a scalar
11368 @code{LOGICAL}. If the kind type parameters differ, then the
11369 smaller kind type is implicitly converted to larger kind, and the
11370 return has the larger kind. A boz-literal-constant is
11371 converted to an @code{INTEGER} with the kind type parameter of
11372 the other argument as-if a call to @ref{INT} occurred.
11374 @item @emph{Example}:
11377 LOGICAL :: T = .TRUE., F = .FALSE.
11379 DATA a / Z'F' /, b / Z'3' /
11381 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
11382 WRITE (*,*) OR(a, b)
11386 @item @emph{See also}:
11387 Fortran 95 elemental function: @*
11394 @section @code{PACK} --- Pack an array into an array of rank one
11396 @cindex array, packing
11397 @cindex array, reduce dimension
11398 @cindex array, gather elements
11401 @item @emph{Description}:
11402 Stores the elements of @var{ARRAY} in an array of rank one.
11404 The beginning of the resulting array is made up of elements whose @var{MASK}
11405 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
11408 @item @emph{Standard}:
11409 Fortran 90 and later
11411 @item @emph{Class}:
11412 Transformational function
11414 @item @emph{Syntax}:
11415 @code{RESULT = PACK(ARRAY, MASK[,VECTOR])}
11417 @item @emph{Arguments}:
11418 @multitable @columnfractions .15 .70
11419 @item @var{ARRAY} @tab Shall be an array of any type.
11420 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
11421 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
11423 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
11424 as @var{ARRAY} and of rank one. If present, the number of elements in
11425 @var{VECTOR} shall be equal to or greater than the number of true elements
11426 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
11427 @var{VECTOR} shall be equal to or greater than the number of elements in
11431 @item @emph{Return value}:
11432 The result is an array of rank one and the same type as that of @var{ARRAY}.
11433 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
11434 number of @code{TRUE} values in @var{MASK} otherwise.
11436 @item @emph{Example}:
11437 Gathering nonzero elements from an array:
11439 PROGRAM test_pack_1
11441 m = (/ 1, 0, 0, 0, 5, 0 /)
11442 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
11446 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
11448 PROGRAM test_pack_2
11450 m = (/ 1, 0, 0, 2 /)
11451 ! The following results in "1 2 3 4"
11452 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /))
11456 @item @emph{See also}:
11463 @section @code{PARITY} --- Reduction with exclusive OR
11466 @cindex Reduction, XOR
11467 @cindex XOR reduction
11470 @item @emph{Description}:
11471 Calculates the parity, i.e. the reduction using @code{.XOR.},
11472 of @var{MASK} along dimension @var{DIM}.
11474 @item @emph{Standard}:
11475 Fortran 2008 and later
11477 @item @emph{Class}:
11478 Transformational function
11480 @item @emph{Syntax}:
11481 @multitable @columnfractions .80
11482 @item @code{RESULT = PARITY(MASK[, DIM])}
11485 @item @emph{Arguments}:
11486 @multitable @columnfractions .15 .70
11487 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}
11488 @item @var{DIM} @tab (Optional) shall be a scalar of type
11489 @code{INTEGER} with a value in the range from 1 to n, where n
11490 equals the rank of @var{MASK}.
11493 @item @emph{Return value}:
11494 The result is of the same type as @var{MASK}.
11496 If @var{DIM} is absent, a scalar with the parity of all elements in
11497 @var{MASK} is returned, i.e. true if an odd number of elements is
11498 @code{.true.} and false otherwise. If @var{DIM} is present, an array
11499 of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
11500 and a shape similar to that of @var{MASK} with dimension @var{DIM}
11501 dropped is returned.
11503 @item @emph{Example}:
11506 LOGICAL :: x(2) = [ .true., .false. ]
11507 print *, PARITY(x) ! prints "T" (true).
11515 @section @code{PERROR} --- Print system error message
11517 @cindex system, error handling
11520 @item @emph{Description}:
11521 Prints (on the C @code{stderr} stream) a newline-terminated error
11522 message corresponding to the last system error. This is prefixed by
11523 @var{STRING}, a colon and a space. See @code{perror(3)}.
11525 @item @emph{Standard}:
11528 @item @emph{Class}:
11531 @item @emph{Syntax}:
11532 @code{CALL PERROR(STRING)}
11534 @item @emph{Arguments}:
11535 @multitable @columnfractions .15 .70
11536 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
11540 @item @emph{See also}:
11547 @section @code{POPCNT} --- Number of bits set
11549 @cindex binary representation
11553 @item @emph{Description}:
11554 @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
11555 representation of @code{I}.
11557 @item @emph{Standard}:
11558 Fortran 2008 and later
11560 @item @emph{Class}:
11563 @item @emph{Syntax}:
11564 @code{RESULT = POPCNT(I)}
11566 @item @emph{Arguments}:
11567 @multitable @columnfractions .15 .70
11568 @item @var{I} @tab Shall be of type @code{INTEGER}.
11571 @item @emph{Return value}:
11572 The return value is of type @code{INTEGER} and of the default integer
11575 @item @emph{Example}:
11577 program test_population
11578 print *, popcnt(127), poppar(127)
11579 print *, popcnt(huge(0_4)), poppar(huge(0_4))
11580 print *, popcnt(huge(0_8)), poppar(huge(0_8))
11581 end program test_population
11583 @item @emph{See also}:
11592 @section @code{POPPAR} --- Parity of the number of bits set
11594 @cindex binary representation
11598 @item @emph{Description}:
11599 @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
11600 of the number of bits set ('1' bits) in the binary representation of
11601 @code{I}. It is equal to 0 if @code{I} has an even number of bits set,
11602 and 1 for an odd number of '1' bits.
11604 @item @emph{Standard}:
11605 Fortran 2008 and later
11607 @item @emph{Class}:
11610 @item @emph{Syntax}:
11611 @code{RESULT = POPPAR(I)}
11613 @item @emph{Arguments}:
11614 @multitable @columnfractions .15 .70
11615 @item @var{I} @tab Shall be of type @code{INTEGER}.
11618 @item @emph{Return value}:
11619 The return value is of type @code{INTEGER} and of the default integer
11622 @item @emph{Example}:
11624 program test_population
11625 print *, popcnt(127), poppar(127)
11626 print *, popcnt(huge(0_4)), poppar(huge(0_4))
11627 print *, popcnt(huge(0_8)), poppar(huge(0_8))
11628 end program test_population
11630 @item @emph{See also}:
11639 @section @code{PRECISION} --- Decimal precision of a real kind
11641 @cindex model representation, precision
11644 @item @emph{Description}:
11645 @code{PRECISION(X)} returns the decimal precision in the model of the
11648 @item @emph{Standard}:
11649 Fortran 90 and later
11651 @item @emph{Class}:
11654 @item @emph{Syntax}:
11655 @code{RESULT = PRECISION(X)}
11657 @item @emph{Arguments}:
11658 @multitable @columnfractions .15 .70
11659 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}. It may
11660 be scalar or valued.
11663 @item @emph{Return value}:
11664 The return value is of type @code{INTEGER} and of the default integer
11667 @item @emph{Example}:
11669 program prec_and_range
11670 real(kind=4) :: x(2)
11671 complex(kind=8) :: y
11673 print *, precision(x), range(x)
11674 print *, precision(y), range(y)
11675 end program prec_and_range
11677 @item @emph{See also}:
11678 @ref{SELECTED_REAL_KIND}, @*
11685 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
11689 @item @emph{Description}:
11690 Determines whether an optional dummy argument is present.
11692 @item @emph{Standard}:
11693 Fortran 90 and later
11695 @item @emph{Class}:
11698 @item @emph{Syntax}:
11699 @code{RESULT = PRESENT(A)}
11701 @item @emph{Arguments}:
11702 @multitable @columnfractions .15 .70
11703 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
11704 value, or a dummy procedure. It shall be the name of an optional dummy argument
11705 accessible within the current subroutine or function.
11708 @item @emph{Return value}:
11709 Returns either @code{TRUE} if the optional argument @var{A} is present, or
11710 @code{FALSE} otherwise.
11712 @item @emph{Example}:
11714 PROGRAM test_present
11715 WRITE(*,*) f(), f(42) ! "F T"
11717 LOGICAL FUNCTION f(x)
11718 INTEGER, INTENT(IN), OPTIONAL :: x
11728 @section @code{PRODUCT} --- Product of array elements
11730 @cindex array, product
11731 @cindex array, multiply elements
11732 @cindex array, conditionally multiply elements
11733 @cindex multiply array elements
11736 @item @emph{Description}:
11737 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
11738 the corresponding element in @var{MASK} is @code{TRUE}.
11740 @item @emph{Standard}:
11741 Fortran 90 and later
11743 @item @emph{Class}:
11744 Transformational function
11746 @item @emph{Syntax}:
11747 @multitable @columnfractions .80
11748 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
11749 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
11752 @item @emph{Arguments}:
11753 @multitable @columnfractions .15 .70
11754 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
11755 @code{REAL} or @code{COMPLEX}.
11756 @item @var{DIM} @tab (Optional) shall be a scalar of type
11757 @code{INTEGER} with a value in the range from 1 to n, where n
11758 equals the rank of @var{ARRAY}.
11759 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
11760 and either be a scalar or an array of the same shape as @var{ARRAY}.
11763 @item @emph{Return value}:
11764 The result is of the same type as @var{ARRAY}.
11766 If @var{DIM} is absent, a scalar with the product of all elements in
11767 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
11768 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
11769 dimension @var{DIM} dropped is returned.
11772 @item @emph{Example}:
11774 PROGRAM test_product
11775 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
11776 print *, PRODUCT(x) ! all elements, product = 120
11777 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
11781 @item @emph{See also}:
11788 @section @code{RADIX} --- Base of a model number
11790 @cindex model representation, base
11791 @cindex model representation, radix
11794 @item @emph{Description}:
11795 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
11797 @item @emph{Standard}:
11798 Fortran 90 and later
11800 @item @emph{Class}:
11803 @item @emph{Syntax}:
11804 @code{RESULT = RADIX(X)}
11806 @item @emph{Arguments}:
11807 @multitable @columnfractions .15 .70
11808 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
11811 @item @emph{Return value}:
11812 The return value is a scalar of type @code{INTEGER} and of the default
11815 @item @emph{Example}:
11818 print *, "The radix for the default integer kind is", radix(0)
11819 print *, "The radix for the default real kind is", radix(0.0)
11820 end program test_radix
11822 @item @emph{See also}:
11823 @ref{SELECTED_REAL_KIND}
11829 @section @code{RAN} --- Real pseudo-random number
11831 @cindex random number generation
11834 @item @emph{Description}:
11835 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
11836 provided as an alias for @code{RAND}. See @ref{RAND} for complete
11839 @item @emph{Standard}:
11842 @item @emph{Class}:
11845 @item @emph{See also}:
11847 @ref{RANDOM_NUMBER}
11853 @section @code{RAND} --- Real pseudo-random number
11855 @cindex random number generation
11858 @item @emph{Description}:
11859 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
11860 distribution between 0 and 1. If @var{FLAG} is 0, the next number
11861 in the current sequence is returned; if @var{FLAG} is 1, the generator
11862 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
11863 it is used as a new seed with @code{SRAND}.
11865 This intrinsic routine is provided for backwards compatibility with
11866 GNU Fortran 77. It implements a simple modulo generator as provided
11867 by @command{g77}. For new code, one should consider the use of
11868 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
11870 @item @emph{Standard}:
11873 @item @emph{Class}:
11876 @item @emph{Syntax}:
11877 @code{RESULT = RAND(I)}
11879 @item @emph{Arguments}:
11880 @multitable @columnfractions .15 .70
11881 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
11884 @item @emph{Return value}:
11885 The return value is of @code{REAL} type and the default kind.
11887 @item @emph{Example}:
11890 integer,parameter :: seed = 86456
11893 print *, rand(), rand(), rand(), rand()
11894 print *, rand(seed), rand(), rand(), rand()
11895 end program test_rand
11898 @item @emph{See also}:
11900 @ref{RANDOM_NUMBER}
11906 @section @code{RANDOM_INIT} --- Initialize a pseudo-random number generator
11907 @fnindex RANDOM_INIT
11908 @cindex random number generation, initialization
11911 @item @emph{Description}:
11912 Initializes the state of the pseudorandom number generator used by
11913 @code{RANDOM_NUMBER}.
11915 @item @emph{Standard}:
11918 @item @emph{Class}:
11921 @item @emph{Syntax}:
11922 @code{CALL RANDOM_INIT(REPEATABLE, IMAGE_DISTINCT)}
11924 @item @emph{Arguments}:
11925 @multitable @columnfractions .25 .70
11926 @item @var{REPEATABLE} @tab Shall be a scalar with a @code{LOGICAL} type,
11927 and it is @code{INTENT(IN)}. If it is @code{.true.}, the seed is set to
11928 a processor-dependent value that is the same each time @code{RANDOM_INIT}
11929 is called from the same image. The term ``same image'' means a single
11930 instance of program execution. The sequence of random numbers is different
11931 for repeated execution of the program. If it is @code{.false.}, the seed
11932 is set to a processor-dependent value.
11933 @item @var{IMAGE_DISTINCT} @tab Shall be a scalar with a
11934 @code{LOGICAL} type, and it is @code{INTENT(IN)}. If it is @code{.true.},
11935 the seed is set to a processor-dependent value that is distinct from th
11936 seed set by a call to @code{RANDOM_INIT} in another image. If it is
11937 @code{.false.}, the seed is set to a value that does depend which image called
11938 @code{RANDOM_INIT}.
11941 @item @emph{Example}:
11943 program test_random_seed
11946 call random_init(.true., .true.)
11947 call random_number(x)
11948 call random_init(.true., .true.)
11949 call random_number(y)
11950 ! x and y are the same sequence
11951 if (any(x /= y)) call abort
11952 end program test_random_seed
11955 @item @emph{See also}:
11956 @ref{RANDOM_NUMBER}, @*
11961 @node RANDOM_NUMBER
11962 @section @code{RANDOM_NUMBER} --- Pseudo-random number
11963 @fnindex RANDOM_NUMBER
11964 @cindex random number generation
11967 @item @emph{Description}:
11968 Returns a single pseudorandom number or an array of pseudorandom numbers
11969 from the uniform distribution over the range @math{ 0 \leq x < 1}.
11971 The runtime-library implements the xoshiro256** pseudorandom number
11972 generator (PRNG). This generator has a period of @math{2^{256} - 1},
11973 and when using multiple threads up to @math{2^{128}} threads can each
11974 generate @math{2^{128}} random numbers before any aliasing occurs.
11976 Note that in a multi-threaded program (e.g. using OpenMP directives),
11977 each thread will have its own random number state. For details of the
11978 seeding procedure, see the documentation for the @code{RANDOM_SEED}
11982 @item @emph{Standard}:
11983 Fortran 90 and later
11985 @item @emph{Class}:
11988 @item @emph{Syntax}:
11989 @code{CALL RANDOM_NUMBER(HARVEST)}
11991 @item @emph{Arguments}:
11992 @multitable @columnfractions .15 .70
11993 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
11996 @item @emph{Example}:
11998 program test_random_number
12000 CALL RANDOM_NUMBER(r)
12004 @item @emph{See also}:
12005 @ref{RANDOM_SEED}, @*
12012 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
12013 @fnindex RANDOM_SEED
12014 @cindex random number generation, seeding
12015 @cindex seeding a random number generator
12018 @item @emph{Description}:
12019 Restarts or queries the state of the pseudorandom number generator used by
12020 @code{RANDOM_NUMBER}.
12022 If @code{RANDOM_SEED} is called without arguments, it is seeded with
12023 random data retrieved from the operating system.
12025 As an extension to the Fortran standard, the GFortran
12026 @code{RANDOM_NUMBER} supports multiple threads. Each thread in a
12027 multi-threaded program has its own seed. When @code{RANDOM_SEED} is
12028 called either without arguments or with the @var{PUT} argument, the
12029 given seed is copied into a master seed as well as the seed of the
12030 current thread. When a new thread uses @code{RANDOM_NUMBER} for the
12031 first time, the seed is copied from the master seed, and forwarded
12032 @math{N * 2^{128}} steps to guarantee that the random stream does not
12033 alias any other stream in the system, where @var{N} is the number of
12034 threads that have used @code{RANDOM_NUMBER} so far during the program
12037 @item @emph{Standard}:
12038 Fortran 90 and later
12040 @item @emph{Class}:
12043 @item @emph{Syntax}:
12044 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
12046 @item @emph{Arguments}:
12047 @multitable @columnfractions .15 .70
12048 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
12049 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
12050 of the arrays used with the @var{PUT} and @var{GET} arguments.
12051 @item @var{PUT} @tab (Optional) Shall be an array of type default
12052 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
12053 the array must be larger than or equal to the number returned by the
12054 @var{SIZE} argument.
12055 @item @var{GET} @tab (Optional) Shall be an array of type default
12056 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
12057 of the array must be larger than or equal to the number returned by
12058 the @var{SIZE} argument.
12061 @item @emph{Example}:
12063 program test_random_seed
12065 integer, allocatable :: seed(:)
12068 call random_seed(size = n)
12070 call random_seed(get=seed)
12072 end program test_random_seed
12075 @item @emph{See also}:
12076 @ref{RANDOM_NUMBER}, @*
12083 @section @code{RANGE} --- Decimal exponent range
12085 @cindex model representation, range
12088 @item @emph{Description}:
12089 @code{RANGE(X)} returns the decimal exponent range in the model of the
12092 @item @emph{Standard}:
12093 Fortran 90 and later
12095 @item @emph{Class}:
12098 @item @emph{Syntax}:
12099 @code{RESULT = RANGE(X)}
12101 @item @emph{Arguments}:
12102 @multitable @columnfractions .15 .70
12103 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
12107 @item @emph{Return value}:
12108 The return value is of type @code{INTEGER} and of the default integer
12111 @item @emph{Example}:
12112 See @code{PRECISION} for an example.
12113 @item @emph{See also}:
12114 @ref{SELECTED_REAL_KIND}, @*
12121 @section @code{RANK} --- Rank of a data object
12126 @item @emph{Description}:
12127 @code{RANK(A)} returns the rank of a scalar or array data object.
12129 @item @emph{Standard}:
12130 Technical Specification (TS) 29113
12132 @item @emph{Class}:
12135 @item @emph{Syntax}:
12136 @code{RESULT = RANK(A)}
12138 @item @emph{Arguments}:
12139 @multitable @columnfractions .15 .70
12140 @item @var{A} @tab can be of any type
12143 @item @emph{Return value}:
12144 The return value is of type @code{INTEGER} and of the default integer
12145 kind. For arrays, their rank is returned; for scalars zero is returned.
12147 @item @emph{Example}:
12151 real, allocatable :: b(:,:)
12153 print *, rank(a), rank(b) ! Prints: 0 2
12154 end program test_rank
12162 @section @code{REAL} --- Convert to real type
12171 @cindex conversion, to real
12172 @cindex complex numbers, real part
12175 @item @emph{Description}:
12176 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
12177 @code{REALPART} function is provided for compatibility with @command{g77},
12178 and its use is strongly discouraged.
12180 @item @emph{Standard}:
12181 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later, has GNU extensions
12183 @item @emph{Class}:
12186 @item @emph{Syntax}:
12187 @multitable @columnfractions .80
12188 @item @code{RESULT = REAL(A [, KIND])}
12189 @item @code{RESULT = REALPART(Z)}
12192 @item @emph{Arguments}:
12193 @multitable @columnfractions .15 .70
12194 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
12196 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
12197 expression indicating the kind parameter of the result.
12200 @item @emph{Return value}:
12201 These functions return a @code{REAL} variable or array under
12202 the following rules:
12206 @code{REAL(A)} is converted to a default real type if @var{A} is an
12207 integer or real variable.
12209 @code{REAL(A)} is converted to a real type with the kind type parameter
12210 of @var{A} if @var{A} is a complex variable.
12212 @code{REAL(A, KIND)} is converted to a real type with kind type
12213 parameter @var{KIND} if @var{A} is a complex, integer, or real
12217 @item @emph{Example}:
12220 complex :: x = (1.0, 2.0)
12221 print *, real(x), real(x,8), realpart(x)
12222 end program test_real
12225 @item @emph{Specific names}:
12226 @multitable @columnfractions .20 .23 .20 .33
12227 @headitem Name @tab Argument @tab Return type @tab Standard
12228 @item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later
12229 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension
12230 @item @code{FLOATI(A)} @tab @code{INTEGER(2)} @tab @code{REAL(4)} @tab GNU extension (-fdec)
12231 @item @code{FLOATJ(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab GNU extension (-fdec)
12232 @item @code{FLOATK(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab GNU extension (-fdec)
12233 @item @code{SNGL(A)} @tab @code{REAL(8)} @tab @code{REAL(4)} @tab Fortran 77 and later
12237 @item @emph{See also}:
12245 @section @code{RENAME} --- Rename a file
12247 @cindex file system, rename file
12250 @item @emph{Description}:
12251 Renames a file from file @var{PATH1} to @var{PATH2}. A null
12252 character (@code{CHAR(0)}) can be used to mark the end of the names in
12253 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
12254 names are ignored. If the @var{STATUS} argument is supplied, it
12255 contains 0 on success or a nonzero error code upon return; see
12258 This intrinsic is provided in both subroutine and function forms;
12259 however, only one form can be used in any given program unit.
12261 @item @emph{Standard}:
12264 @item @emph{Class}:
12265 Subroutine, function
12267 @item @emph{Syntax}:
12268 @multitable @columnfractions .80
12269 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
12270 @item @code{STATUS = RENAME(PATH1, PATH2)}
12273 @item @emph{Arguments}:
12274 @multitable @columnfractions .15 .70
12275 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
12276 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
12277 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12280 @item @emph{See also}:
12288 @section @code{REPEAT} --- Repeated string concatenation
12290 @cindex string, repeat
12291 @cindex string, concatenate
12294 @item @emph{Description}:
12295 Concatenates @var{NCOPIES} copies of a string.
12297 @item @emph{Standard}:
12298 Fortran 90 and later
12300 @item @emph{Class}:
12301 Transformational function
12303 @item @emph{Syntax}:
12304 @code{RESULT = REPEAT(STRING, NCOPIES)}
12306 @item @emph{Arguments}:
12307 @multitable @columnfractions .15 .70
12308 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
12309 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
12312 @item @emph{Return value}:
12313 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
12316 @item @emph{Example}:
12318 program test_repeat
12319 write(*,*) repeat("x", 5) ! "xxxxx"
12327 @section @code{RESHAPE} --- Function to reshape an array
12329 @cindex array, change dimensions
12330 @cindex array, transmogrify
12333 @item @emph{Description}:
12334 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
12335 the new array may be padded with elements from @var{PAD} or permuted
12336 as defined by @var{ORDER}.
12338 @item @emph{Standard}:
12339 Fortran 90 and later
12341 @item @emph{Class}:
12342 Transformational function
12344 @item @emph{Syntax}:
12345 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
12347 @item @emph{Arguments}:
12348 @multitable @columnfractions .15 .70
12349 @item @var{SOURCE} @tab Shall be an array of any type.
12350 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
12351 array of rank one. Its values must be positive or zero.
12352 @item @var{PAD} @tab (Optional) shall be an array of the same
12353 type as @var{SOURCE}.
12354 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
12355 and an array of the same shape as @var{SHAPE}. Its values shall
12356 be a permutation of the numbers from 1 to n, where n is the size of
12357 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
12361 @item @emph{Return value}:
12362 The result is an array of shape @var{SHAPE} with the same type as
12365 @item @emph{Example}:
12367 PROGRAM test_reshape
12368 INTEGER, DIMENSION(4) :: x
12369 WRITE(*,*) SHAPE(x) ! prints "4"
12370 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
12374 @item @emph{See also}:
12381 @section @code{RRSPACING} --- Reciprocal of the relative spacing
12383 @cindex real number, relative spacing
12384 @cindex floating point, relative spacing
12388 @item @emph{Description}:
12389 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
12390 model numbers near @var{X}.
12392 @item @emph{Standard}:
12393 Fortran 90 and later
12395 @item @emph{Class}:
12398 @item @emph{Syntax}:
12399 @code{RESULT = RRSPACING(X)}
12401 @item @emph{Arguments}:
12402 @multitable @columnfractions .15 .70
12403 @item @var{X} @tab Shall be of type @code{REAL}.
12406 @item @emph{Return value}:
12407 The return value is of the same type and kind as @var{X}.
12408 The value returned is equal to
12409 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
12411 @item @emph{See also}:
12418 @section @code{RSHIFT} --- Right shift bits
12420 @cindex bits, shift right
12423 @item @emph{Description}:
12424 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
12425 bits shifted right by @var{SHIFT} places. @var{SHIFT} shall be
12426 nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
12427 the result value is undefined. Bits shifted out from the right end
12428 are lost. The fill is arithmetic: the bits shifted in from the left
12429 end are equal to the leftmost bit, which in two's complement
12430 representation is the sign bit.
12432 This function has been superseded by the @code{SHIFTA} intrinsic, which
12433 is standard in Fortran 2008 and later.
12435 @item @emph{Standard}:
12438 @item @emph{Class}:
12441 @item @emph{Syntax}:
12442 @code{RESULT = RSHIFT(I, SHIFT)}
12444 @item @emph{Arguments}:
12445 @multitable @columnfractions .15 .70
12446 @item @var{I} @tab The type shall be @code{INTEGER}.
12447 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12450 @item @emph{Return value}:
12451 The return value is of type @code{INTEGER} and of the same kind as
12454 @item @emph{See also}:
12467 @section @code{SAME_TYPE_AS} --- Query dynamic types for equality
12468 @fnindex SAME_TYPE_AS
12471 @item @emph{Description}:
12472 Query dynamic types for equality.
12474 @item @emph{Standard}:
12475 Fortran 2003 and later
12477 @item @emph{Class}:
12480 @item @emph{Syntax}:
12481 @code{RESULT = SAME_TYPE_AS(A, B)}
12483 @item @emph{Arguments}:
12484 @multitable @columnfractions .15 .70
12485 @item @var{A} @tab Shall be an object of extensible declared type or
12486 unlimited polymorphic.
12487 @item @var{B} @tab Shall be an object of extensible declared type or
12488 unlimited polymorphic.
12491 @item @emph{Return value}:
12492 The return value is a scalar of type default logical. It is true if and
12493 only if the dynamic type of A is the same as the dynamic type of B.
12495 @item @emph{See also}:
12496 @ref{EXTENDS_TYPE_OF}
12503 @section @code{SCALE} --- Scale a real value
12505 @cindex real number, scale
12506 @cindex floating point, scale
12509 @item @emph{Description}:
12510 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
12512 @item @emph{Standard}:
12513 Fortran 90 and later
12515 @item @emph{Class}:
12518 @item @emph{Syntax}:
12519 @code{RESULT = SCALE(X, I)}
12521 @item @emph{Arguments}:
12522 @multitable @columnfractions .15 .70
12523 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
12524 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
12527 @item @emph{Return value}:
12528 The return value is of the same type and kind as @var{X}.
12529 Its value is @code{X * RADIX(X)**I}.
12531 @item @emph{Example}:
12534 real :: x = 178.1387e-4
12536 print *, scale(x,i), x*radix(x)**i
12537 end program test_scale
12545 @section @code{SCAN} --- Scan a string for the presence of a set of characters
12547 @cindex string, find subset
12550 @item @emph{Description}:
12551 Scans a @var{STRING} for any of the characters in a @var{SET}
12554 If @var{BACK} is either absent or equals @code{FALSE}, this function
12555 returns the position of the leftmost character of @var{STRING} that is
12556 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
12557 is returned. If no character of @var{SET} is found in @var{STRING}, the
12560 @item @emph{Standard}:
12561 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
12563 @item @emph{Class}:
12566 @item @emph{Syntax}:
12567 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
12569 @item @emph{Arguments}:
12570 @multitable @columnfractions .15 .70
12571 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
12572 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
12573 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
12574 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
12575 expression indicating the kind parameter of the result.
12578 @item @emph{Return value}:
12579 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12580 @var{KIND} is absent, the return value is of default integer kind.
12582 @item @emph{Example}:
12585 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
12586 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
12587 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
12591 @item @emph{See also}:
12592 @ref{INDEX intrinsic}, @*
12599 @section @code{SECNDS} --- Time function
12601 @cindex time, elapsed
12602 @cindex elapsed time
12605 @item @emph{Description}:
12606 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
12607 @var{X} is a reference time, also in seconds. If this is zero, the time in
12608 seconds from midnight is returned. This function is non-standard and its
12609 use is discouraged.
12611 @item @emph{Standard}:
12614 @item @emph{Class}:
12617 @item @emph{Syntax}:
12618 @code{RESULT = SECNDS (X)}
12620 @item @emph{Arguments}:
12621 @multitable @columnfractions .15 .70
12622 @item @var{T} @tab Shall be of type @code{REAL(4)}.
12623 @item @var{X} @tab Shall be of type @code{REAL(4)}.
12626 @item @emph{Return value}:
12629 @item @emph{Example}:
12631 program test_secnds
12634 print *, secnds (0.0) ! seconds since midnight
12635 t1 = secnds (0.0) ! reference time
12636 do i = 1, 10000000 ! do something
12638 t2 = secnds (t1) ! elapsed time
12639 print *, "Something took ", t2, " seconds."
12640 end program test_secnds
12647 @section @code{SECOND} --- CPU time function
12649 @cindex time, elapsed
12650 @cindex elapsed time
12653 @item @emph{Description}:
12654 Returns a @code{REAL(4)} value representing the elapsed CPU time in
12655 seconds. This provides the same functionality as the standard
12656 @code{CPU_TIME} intrinsic, and is only included for backwards
12659 This intrinsic is provided in both subroutine and function forms;
12660 however, only one form can be used in any given program unit.
12662 @item @emph{Standard}:
12665 @item @emph{Class}:
12666 Subroutine, function
12668 @item @emph{Syntax}:
12669 @multitable @columnfractions .80
12670 @item @code{CALL SECOND(TIME)}
12671 @item @code{TIME = SECOND()}
12674 @item @emph{Arguments}:
12675 @multitable @columnfractions .15 .70
12676 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
12679 @item @emph{Return value}:
12680 In either syntax, @var{TIME} is set to the process's current runtime in
12683 @item @emph{See also}:
12690 @node SELECTED_CHAR_KIND
12691 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
12692 @fnindex SELECTED_CHAR_KIND
12693 @cindex character kind
12694 @cindex kind, character
12697 @item @emph{Description}:
12699 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
12700 set named @var{NAME}, if a character set with such a name is supported,
12701 or @math{-1} otherwise. Currently, supported character sets include
12702 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
12703 (Universal Character Set, UCS-4) which is commonly known as Unicode.
12705 @item @emph{Standard}:
12706 Fortran 2003 and later
12708 @item @emph{Class}:
12709 Transformational function
12711 @item @emph{Syntax}:
12712 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
12714 @item @emph{Arguments}:
12715 @multitable @columnfractions .15 .70
12716 @item @var{NAME} @tab Shall be a scalar and of the default character type.
12719 @item @emph{Example}:
12721 program character_kind
12722 use iso_fortran_env
12724 integer, parameter :: ascii = selected_char_kind ("ascii")
12725 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646')
12727 character(kind=ascii, len=26) :: alphabet
12728 character(kind=ucs4, len=30) :: hello_world
12730 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
12731 hello_world = ucs4_'Hello World and Ni Hao -- ' &
12732 // char (int (z'4F60'), ucs4) &
12733 // char (int (z'597D'), ucs4)
12735 write (*,*) alphabet
12737 open (output_unit, encoding='UTF-8')
12738 write (*,*) trim (hello_world)
12739 end program character_kind
12745 @node SELECTED_INT_KIND
12746 @section @code{SELECTED_INT_KIND} --- Choose integer kind
12747 @fnindex SELECTED_INT_KIND
12748 @cindex integer kind
12749 @cindex kind, integer
12752 @item @emph{Description}:
12753 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
12754 type that can represent all values ranging from @math{-10^R} (exclusive)
12755 to @math{10^R} (exclusive). If there is no integer kind that accommodates
12756 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
12758 @item @emph{Standard}:
12759 Fortran 90 and later
12761 @item @emph{Class}:
12762 Transformational function
12764 @item @emph{Syntax}:
12765 @code{RESULT = SELECTED_INT_KIND(R)}
12767 @item @emph{Arguments}:
12768 @multitable @columnfractions .15 .70
12769 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
12772 @item @emph{Example}:
12774 program large_integers
12775 integer,parameter :: k5 = selected_int_kind(5)
12776 integer,parameter :: k15 = selected_int_kind(15)
12777 integer(kind=k5) :: i5
12778 integer(kind=k15) :: i15
12780 print *, huge(i5), huge(i15)
12782 ! The following inequalities are always true
12783 print *, huge(i5) >= 10_k5**5-1
12784 print *, huge(i15) >= 10_k15**15-1
12785 end program large_integers
12791 @node SELECTED_REAL_KIND
12792 @section @code{SELECTED_REAL_KIND} --- Choose real kind
12793 @fnindex SELECTED_REAL_KIND
12796 @cindex radix, real
12799 @item @emph{Description}:
12800 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
12801 with decimal precision of at least @code{P} digits, exponent range of
12802 at least @code{R}, and with a radix of @code{RADIX}.
12804 @item @emph{Standard}:
12805 Fortran 90 and later, with @code{RADIX} Fortran 2008 or later
12807 @item @emph{Class}:
12808 Transformational function
12810 @item @emph{Syntax}:
12811 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
12813 @item @emph{Arguments}:
12814 @multitable @columnfractions .15 .70
12815 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12816 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12817 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12819 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
12820 be present; since Fortran 2008, they are assumed to be zero if absent.
12822 @item @emph{Return value}:
12824 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
12825 a real data type with decimal precision of at least @code{P} digits, a
12826 decimal exponent range of at least @code{R}, and with the requested
12827 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
12828 any radix can be returned. If more than one real data type meet the
12829 criteria, the kind of the data type with the smallest decimal precision
12830 is returned. If no real data type matches the criteria, the result is
12832 @item -1 if the processor does not support a real data type with a
12833 precision greater than or equal to @code{P}, but the @code{R} and
12834 @code{RADIX} requirements can be fulfilled
12835 @item -2 if the processor does not support a real type with an exponent
12836 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
12838 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
12840 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
12842 @item -5 if there is no real type with the given @code{RADIX}
12845 @item @emph{Example}:
12848 integer,parameter :: p6 = selected_real_kind(6)
12849 integer,parameter :: p10r100 = selected_real_kind(10,100)
12850 integer,parameter :: r400 = selected_real_kind(r=400)
12852 real(kind=p10r100) :: y
12853 real(kind=r400) :: z
12855 print *, precision(x), range(x)
12856 print *, precision(y), range(y)
12857 print *, precision(z), range(z)
12858 end program real_kinds
12860 @item @emph{See also}:
12861 @ref{PRECISION}, @*
12869 @section @code{SET_EXPONENT} --- Set the exponent of the model
12870 @fnindex SET_EXPONENT
12871 @cindex real number, set exponent
12872 @cindex floating point, set exponent
12875 @item @emph{Description}:
12876 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
12877 is that of @var{X} and whose exponent part is @var{I}.
12879 @item @emph{Standard}:
12880 Fortran 90 and later
12882 @item @emph{Class}:
12885 @item @emph{Syntax}:
12886 @code{RESULT = SET_EXPONENT(X, I)}
12888 @item @emph{Arguments}:
12889 @multitable @columnfractions .15 .70
12890 @item @var{X} @tab Shall be of type @code{REAL}.
12891 @item @var{I} @tab Shall be of type @code{INTEGER}.
12894 @item @emph{Return value}:
12895 The return value is of the same type and kind as @var{X}.
12896 The real number whose fractional part
12897 is that of @var{X} and whose exponent part if @var{I} is returned;
12898 it is @code{FRACTION(X) * RADIX(X)**I}.
12900 @item @emph{Example}:
12902 PROGRAM test_setexp
12903 REAL :: x = 178.1387e-4
12905 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
12914 @section @code{SHAPE} --- Determine the shape of an array
12916 @cindex array, shape
12919 @item @emph{Description}:
12920 Determines the shape of an array.
12922 @item @emph{Standard}:
12923 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
12925 @item @emph{Class}:
12928 @item @emph{Syntax}:
12929 @code{RESULT = SHAPE(SOURCE [, KIND])}
12931 @item @emph{Arguments}:
12932 @multitable @columnfractions .15 .70
12933 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
12934 If @var{SOURCE} is a pointer it must be associated and allocatable
12935 arrays must be allocated.
12936 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
12937 expression indicating the kind parameter of the result.
12940 @item @emph{Return value}:
12941 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
12942 has dimensions. The elements of the resulting array correspond to the extend
12943 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
12944 the result is the rank one array of size zero. If @var{KIND} is absent, the
12945 return value has the default integer kind otherwise the specified kind.
12947 @item @emph{Example}:
12950 INTEGER, DIMENSION(-1:1, -1:2) :: A
12951 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
12952 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
12956 @item @emph{See also}:
12964 @section @code{SHIFTA} --- Right shift with fill
12966 @cindex bits, shift right
12967 @cindex shift, right with fill
12970 @item @emph{Description}:
12971 @code{SHIFTA} returns a value corresponding to @var{I} with all of the
12972 bits shifted right by @var{SHIFT} places. @var{SHIFT} that be
12973 nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
12974 the result value is undefined. Bits shifted out from the right end
12975 are lost. The fill is arithmetic: the bits shifted in from the left
12976 end are equal to the leftmost bit, which in two's complement
12977 representation is the sign bit.
12979 @item @emph{Standard}:
12980 Fortran 2008 and later
12982 @item @emph{Class}:
12985 @item @emph{Syntax}:
12986 @code{RESULT = SHIFTA(I, SHIFT)}
12988 @item @emph{Arguments}:
12989 @multitable @columnfractions .15 .70
12990 @item @var{I} @tab The type shall be @code{INTEGER}.
12991 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12994 @item @emph{Return value}:
12995 The return value is of type @code{INTEGER} and of the same kind as
12998 @item @emph{See also}:
13006 @section @code{SHIFTL} --- Left shift
13008 @cindex bits, shift left
13009 @cindex shift, left
13012 @item @emph{Description}:
13013 @code{SHIFTL} returns a value corresponding to @var{I} with all of the
13014 bits shifted left by @var{SHIFT} places. @var{SHIFT} shall be
13015 nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
13016 the result value is undefined. Bits shifted out from the left end are
13017 lost, and bits shifted in from the right end are set to 0.
13019 @item @emph{Standard}:
13020 Fortran 2008 and later
13022 @item @emph{Class}:
13025 @item @emph{Syntax}:
13026 @code{RESULT = SHIFTL(I, SHIFT)}
13028 @item @emph{Arguments}:
13029 @multitable @columnfractions .15 .70
13030 @item @var{I} @tab The type shall be @code{INTEGER}.
13031 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
13034 @item @emph{Return value}:
13035 The return value is of type @code{INTEGER} and of the same kind as
13038 @item @emph{See also}:
13046 @section @code{SHIFTR} --- Right shift
13048 @cindex bits, shift right
13049 @cindex shift, right
13052 @item @emph{Description}:
13053 @code{SHIFTR} returns a value corresponding to @var{I} with all of the
13054 bits shifted right by @var{SHIFT} places. @var{SHIFT} shall be
13055 nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
13056 the result value is undefined. Bits shifted out from the right end
13057 are lost, and bits shifted in from the left end are set to 0.
13059 @item @emph{Standard}:
13060 Fortran 2008 and later
13062 @item @emph{Class}:
13065 @item @emph{Syntax}:
13066 @code{RESULT = SHIFTR(I, SHIFT)}
13068 @item @emph{Arguments}:
13069 @multitable @columnfractions .15 .70
13070 @item @var{I} @tab The type shall be @code{INTEGER}.
13071 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
13074 @item @emph{Return value}:
13075 The return value is of type @code{INTEGER} and of the same kind as
13078 @item @emph{See also}:
13086 @section @code{SIGN} --- Sign copying function
13090 @cindex sign copying
13093 @item @emph{Description}:
13094 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
13096 @item @emph{Standard}:
13097 Fortran 77 and later
13099 @item @emph{Class}:
13102 @item @emph{Syntax}:
13103 @code{RESULT = SIGN(A, B)}
13105 @item @emph{Arguments}:
13106 @multitable @columnfractions .15 .70
13107 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
13108 @item @var{B} @tab Shall be of the same type and kind as @var{A}.
13111 @item @emph{Return value}:
13112 The kind of the return value is that of @var{A} and @var{B}.
13113 If @math{B \ge 0} then the result is @code{ABS(A)}, else
13114 it is @code{-ABS(A)}.
13116 @item @emph{Example}:
13119 print *, sign(-12,1)
13120 print *, sign(-12,0)
13121 print *, sign(-12,-1)
13123 print *, sign(-12.,1.)
13124 print *, sign(-12.,0.)
13125 print *, sign(-12.,-1.)
13126 end program test_sign
13129 @item @emph{Specific names}:
13130 @multitable @columnfractions .20 .26 .20 .30
13131 @headitem Name @tab Arguments @tab Return type @tab Standard
13132 @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab Fortran 77 and later
13133 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab Fortran 77 and later
13134 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab Fortran 77 and later
13141 @section @code{SIGNAL} --- Signal handling subroutine (or function)
13143 @cindex system, signal handling
13146 @item @emph{Description}:
13147 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
13148 @var{HANDLER} to be executed with a single integer argument passed by
13149 value when signal @var{NUMBER} occurs. If @var{HANDLER} is an integer,
13150 it can be used to turn off handling of signal @var{NUMBER} or revert to
13151 its default action. See @code{signal(2)}.
13153 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
13154 is supplied, it is set to the value returned by @code{signal(2)}.
13156 @item @emph{Standard}:
13159 @item @emph{Class}:
13160 Subroutine, function
13162 @item @emph{Syntax}:
13163 @multitable @columnfractions .80
13164 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
13165 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
13168 @item @emph{Arguments}:
13169 @multitable @columnfractions .15 .70
13170 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
13171 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
13172 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
13173 @code{INTEGER}. It is @code{INTENT(IN)}.
13174 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
13175 integer. It has @code{INTENT(OUT)}.
13178 @item @emph{Return value}:
13179 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
13181 @item @emph{Example}:
13185 ! POSIX.1-2017: void (*func)(int)
13186 subroutine handler_print(signum) bind(C)
13187 use iso_c_binding, only: c_int
13188 integer(c_int), value :: signum
13189 print *, 'handler_print invoked with signum =', signum
13192 program test_signal
13194 intrinsic :: signal, sleep
13195 call signal (12, handler_print) ! 12 = SIGUSR2 (on some systems)
13196 call signal (10, 1) ! 10 = SIGUSR1 and 1 = SIG_IGN (on some systems)
13199 end program test_signal
13206 @section @code{SIN} --- Sine function
13212 @cindex trigonometric function, sine
13216 @item @emph{Description}:
13217 @code{SIN(X)} computes the sine of @var{X}.
13219 @item @emph{Standard}:
13220 Fortran 77 and later
13222 @item @emph{Class}:
13225 @item @emph{Syntax}:
13226 @code{RESULT = SIN(X)}
13228 @item @emph{Arguments}:
13229 @multitable @columnfractions .15 .70
13230 @item @var{X} @tab The type shall be @code{REAL} or
13234 @item @emph{Return value}:
13235 The return value has same type and kind as @var{X}.
13237 @item @emph{Example}:
13242 end program test_sin
13245 @item @emph{Specific names}:
13246 @multitable @columnfractions .20 .23 .20 .33
13247 @headitem Name @tab Argument @tab Return type @tab Standard
13248 @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
13249 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
13250 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
13251 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13252 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13255 @item @emph{See also}:
13256 Inverse function: @*
13258 Degrees function: @*
13265 @section @code{SIND} --- Sine function, degrees
13271 @cindex trigonometric function, sine, degrees
13272 @cindex sine, degrees
13275 @item @emph{Description}:
13276 @code{SIND(X)} computes the sine of @var{X} in degrees.
13278 @item @emph{Standard}:
13281 @item @emph{Class}:
13284 @item @emph{Syntax}:
13285 @code{RESULT = SIND(X)}
13287 @item @emph{Arguments}:
13288 @multitable @columnfractions .15 .70
13289 @item @var{X} @tab The type shall be @code{REAL}.
13292 @item @emph{Return value}:
13293 The return value has same type and kind as @var{X}, and its value is in degrees.
13295 @item @emph{Example}:
13300 end program test_sind
13303 @item @emph{Specific names}:
13304 @multitable @columnfractions .20 .23 .20 .33
13305 @headitem Name @tab Argument @tab Return type @tab Standard
13306 @item @code{SIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 2023
13307 @item @code{DSIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
13308 @item @code{CSIND(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU extension
13309 @item @code{ZSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13310 @item @code{CDSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13313 @item @emph{See also}:
13314 Inverse function: @*
13316 Radians function: @*
13321 @section @code{SINH} --- Hyperbolic sine function
13324 @cindex hyperbolic sine
13325 @cindex hyperbolic function, sine
13326 @cindex sine, hyperbolic
13329 @item @emph{Description}:
13330 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
13332 @item @emph{Standard}:
13333 Fortran 90 and later, for a complex argument Fortran 2008 or later, has
13336 @item @emph{Class}:
13339 @item @emph{Syntax}:
13340 @code{RESULT = SINH(X)}
13342 @item @emph{Arguments}:
13343 @multitable @columnfractions .15 .70
13344 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13347 @item @emph{Return value}:
13348 The return value has same type and kind as @var{X}.
13350 @item @emph{Example}:
13353 real(8) :: x = - 1.0_8
13355 end program test_sinh
13358 @item @emph{Specific names}:
13359 @multitable @columnfractions .20 .23 .20 .33
13360 @headitem Name @tab Argument @tab Return type @tab Standard
13361 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 90 and later
13364 @item @emph{See also}:
13371 @section @code{SIZE} --- Determine the size of an array
13373 @cindex array, size
13374 @cindex array, number of elements
13375 @cindex array, count elements
13378 @item @emph{Description}:
13379 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
13380 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
13382 @item @emph{Standard}:
13383 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
13385 @item @emph{Class}:
13388 @item @emph{Syntax}:
13389 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
13391 @item @emph{Arguments}:
13392 @multitable @columnfractions .15 .70
13393 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
13394 a pointer it must be associated and allocatable arrays must be allocated.
13395 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
13396 and its value shall be in the range from 1 to n, where n equals the rank
13398 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
13399 expression indicating the kind parameter of the result.
13402 @item @emph{Return value}:
13403 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
13404 @var{KIND} is absent, the return value is of default integer kind.
13406 @item @emph{Example}:
13409 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
13413 @item @emph{See also}:
13420 @section @code{SIZEOF} --- Size in bytes of an expression
13422 @cindex expression size
13423 @cindex size of an expression
13426 @item @emph{Description}:
13427 @code{SIZEOF(X)} calculates the number of bytes of storage the
13428 expression @code{X} occupies.
13430 @item @emph{Standard}:
13433 @item @emph{Class}:
13436 @item @emph{Syntax}:
13437 @code{N = SIZEOF(X)}
13439 @item @emph{Arguments}:
13440 @multitable @columnfractions .15 .70
13441 @item @var{X} @tab The argument shall be of any type, rank or shape.
13444 @item @emph{Return value}:
13445 The return value is of type integer and of the system-dependent kind
13446 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
13447 number of bytes occupied by the argument. If the argument has the
13448 @code{POINTER} attribute, the number of bytes of the storage area pointed
13449 to is returned. If the argument is of a derived type with @code{POINTER}
13450 or @code{ALLOCATABLE} components, the return value does not account for
13451 the sizes of the data pointed to by these components. If the argument is
13452 polymorphic, the size according to the dynamic type is returned. The argument
13453 may not be a procedure or procedure pointer. Note that the code assumes for
13454 arrays that those are contiguous; for contiguous arrays, it returns the
13455 storage or an array element multiplied by the size of the array.
13457 @item @emph{Example}:
13461 print *, (sizeof(s)/sizeof(r) == 5)
13464 The example will print @code{.TRUE.} unless you are using a platform
13465 where default @code{REAL} variables are unusually padded.
13467 @item @emph{See also}:
13474 @section @code{SLEEP} --- Sleep for the specified number of seconds
13476 @cindex delayed execution
13479 @item @emph{Description}:
13480 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
13482 @item @emph{Standard}:
13485 @item @emph{Class}:
13488 @item @emph{Syntax}:
13489 @code{CALL SLEEP(SECONDS)}
13491 @item @emph{Arguments}:
13492 @multitable @columnfractions .15 .70
13493 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
13496 @item @emph{Example}:
13507 @section @code{SPACING} --- Smallest distance between two numbers of a given type
13509 @cindex real number, relative spacing
13510 @cindex floating point, relative spacing
13513 @item @emph{Description}:
13514 Determines the distance between the argument @var{X} and the nearest
13515 adjacent number of the same type.
13517 @item @emph{Standard}:
13518 Fortran 90 and later
13520 @item @emph{Class}:
13523 @item @emph{Syntax}:
13524 @code{RESULT = SPACING(X)}
13526 @item @emph{Arguments}:
13527 @multitable @columnfractions .15 .70
13528 @item @var{X} @tab Shall be of type @code{REAL}.
13531 @item @emph{Return value}:
13532 The result is of the same type as the input argument @var{X}.
13534 @item @emph{Example}:
13536 PROGRAM test_spacing
13537 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
13538 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
13540 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
13541 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
13545 @item @emph{See also}:
13552 @section @code{SPREAD} --- Add a dimension to an array
13554 @cindex array, increase dimension
13555 @cindex array, duplicate elements
13556 @cindex array, duplicate dimensions
13559 @item @emph{Description}:
13560 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
13561 dimension @var{DIM}.
13563 @item @emph{Standard}:
13564 Fortran 90 and later
13566 @item @emph{Class}:
13567 Transformational function
13569 @item @emph{Syntax}:
13570 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
13572 @item @emph{Arguments}:
13573 @multitable @columnfractions .15 .70
13574 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
13575 a rank less than seven.
13576 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
13577 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
13578 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
13581 @item @emph{Return value}:
13582 The result is an array of the same type as @var{SOURCE} and has rank n+1
13583 where n equals the rank of @var{SOURCE}.
13585 @item @emph{Example}:
13587 PROGRAM test_spread
13588 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
13589 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
13590 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
13594 @item @emph{See also}:
13601 @section @code{SQRT} --- Square-root function
13608 @cindex square-root
13611 @item @emph{Description}:
13612 @code{SQRT(X)} computes the square root of @var{X}.
13614 @item @emph{Standard}:
13615 Fortran 77 and later
13617 @item @emph{Class}:
13620 @item @emph{Syntax}:
13621 @code{RESULT = SQRT(X)}
13623 @item @emph{Arguments}:
13624 @multitable @columnfractions .15 .70
13625 @item @var{X} @tab The type shall be @code{REAL} or
13629 @item @emph{Return value}:
13630 The return value is of type @code{REAL} or @code{COMPLEX}.
13631 The kind type parameter is the same as @var{X}.
13633 @item @emph{Example}:
13636 real(8) :: x = 2.0_8
13637 complex :: z = (1.0, 2.0)
13640 end program test_sqrt
13643 @item @emph{Specific names}:
13644 @multitable @columnfractions .20 .23 .20 .33
13645 @headitem Name @tab Argument @tab Return type @tab Standard
13646 @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
13647 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
13648 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
13649 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13650 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13657 @section @code{SRAND} --- Reinitialize the random number generator
13659 @cindex random number generation, seeding
13660 @cindex seeding a random number generator
13663 @item @emph{Description}:
13664 @code{SRAND} reinitializes the pseudo-random number generator
13665 called by @code{RAND} and @code{IRAND}. The new seed used by the
13666 generator is specified by the required argument @var{SEED}.
13668 @item @emph{Standard}:
13671 @item @emph{Class}:
13674 @item @emph{Syntax}:
13675 @code{CALL SRAND(SEED)}
13677 @item @emph{Arguments}:
13678 @multitable @columnfractions .15 .70
13679 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
13682 @item @emph{Return value}:
13683 Does not return anything.
13685 @item @emph{Example}:
13686 See @code{RAND} and @code{IRAND} for examples.
13688 @item @emph{Notes}:
13689 The Fortran standard specifies the intrinsic subroutines
13690 @code{RANDOM_SEED} to initialize the pseudo-random number
13691 generator and @code{RANDOM_NUMBER} to generate pseudo-random numbers.
13692 These subroutines should be used in new codes.
13694 Please note that in GNU Fortran, these two sets of intrinsics (@code{RAND},
13695 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
13696 @code{RANDOM_SEED} on the other hand) access two independent
13697 pseudo-random number generators.
13699 @item @emph{See also}:
13701 @ref{RANDOM_SEED}, @*
13702 @ref{RANDOM_NUMBER}
13708 @section @code{STAT} --- Get file status
13710 @cindex file system, file status
13713 @item @emph{Description}:
13714 This function returns information about a file. No permissions are required on
13715 the file itself, but execute (search) permission is required on all of the
13716 directories in path that lead to the file.
13718 The elements that are obtained and stored in the array @code{VALUES}:
13719 @multitable @columnfractions .15 .70
13720 @item @code{VALUES(1)} @tab Device ID
13721 @item @code{VALUES(2)} @tab Inode number
13722 @item @code{VALUES(3)} @tab File mode
13723 @item @code{VALUES(4)} @tab Number of links
13724 @item @code{VALUES(5)} @tab Owner's uid
13725 @item @code{VALUES(6)} @tab Owner's gid
13726 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
13727 @item @code{VALUES(8)} @tab File size (bytes)
13728 @item @code{VALUES(9)} @tab Last access time
13729 @item @code{VALUES(10)} @tab Last modification time
13730 @item @code{VALUES(11)} @tab Last file status change time
13731 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
13732 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
13735 Not all these elements are relevant on all systems.
13736 If an element is not relevant, it is returned as 0.
13738 This intrinsic is provided in both subroutine and function forms; however,
13739 only one form can be used in any given program unit.
13741 @item @emph{Standard}:
13744 @item @emph{Class}:
13745 Subroutine, function
13747 @item @emph{Syntax}:
13748 @multitable @columnfractions .80
13749 @item @code{CALL STAT(NAME, VALUES [, STATUS])}
13750 @item @code{STATUS = STAT(NAME, VALUES)}
13753 @item @emph{Arguments}:
13754 @multitable @columnfractions .15 .70
13755 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
13756 default kind and a valid path within the file system.
13757 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
13758 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
13759 on success and a system specific error code otherwise.
13762 @item @emph{Example}:
13765 INTEGER, DIMENSION(13) :: buff
13768 CALL STAT("/etc/passwd", buff, status)
13770 IF (status == 0) THEN
13771 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
13772 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
13773 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
13774 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
13775 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
13776 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
13777 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
13778 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
13779 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
13780 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
13781 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
13782 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
13783 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
13788 @item @emph{See also}:
13789 To stat an open file: @*
13798 @section @code{STORAGE_SIZE} --- Storage size in bits
13799 @fnindex STORAGE_SIZE
13800 @cindex storage size
13803 @item @emph{Description}:
13804 Returns the storage size of argument @var{A} in bits.
13805 @item @emph{Standard}:
13806 Fortran 2008 and later
13807 @item @emph{Class}:
13809 @item @emph{Syntax}:
13810 @code{RESULT = STORAGE_SIZE(A [, KIND])}
13812 @item @emph{Arguments}:
13813 @multitable @columnfractions .15 .70
13814 @item @var{A} @tab Shall be a scalar or array of any type.
13815 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
13818 @item @emph{Return Value}:
13819 The result is a scalar integer with the kind type parameter specified by KIND
13820 (or default integer type if KIND is missing). The result value is the size
13821 expressed in bits for an element of an array that has the dynamic type and type
13824 @item @emph{See also}:
13832 @section @code{SUM} --- Sum of array elements
13835 @cindex array, add elements
13836 @cindex array, conditionally add elements
13837 @cindex sum array elements
13840 @item @emph{Description}:
13841 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
13842 the corresponding element in @var{MASK} is @code{TRUE}.
13844 @item @emph{Standard}:
13845 Fortran 90 and later
13847 @item @emph{Class}:
13848 Transformational function
13850 @item @emph{Syntax}:
13851 @multitable @columnfractions .80
13852 @item @code{RESULT = SUM(ARRAY[, MASK])}
13853 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
13856 @item @emph{Arguments}:
13857 @multitable @columnfractions .15 .70
13858 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
13859 @code{REAL} or @code{COMPLEX}.
13860 @item @var{DIM} @tab (Optional) shall be a scalar of type
13861 @code{INTEGER} with a value in the range from 1 to n, where n
13862 equals the rank of @var{ARRAY}.
13863 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
13864 and either be a scalar or an array of the same shape as @var{ARRAY}.
13867 @item @emph{Return value}:
13868 The result is of the same type as @var{ARRAY}.
13870 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
13871 is returned. Otherwise, an array of rank n-1, where n equals the rank of
13872 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
13873 dropped is returned.
13875 @item @emph{Example}:
13878 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
13879 print *, SUM(x) ! all elements, sum = 15
13880 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
13884 @item @emph{See also}:
13891 @section @code{SYMLNK} --- Create a symbolic link
13893 @cindex file system, create link
13894 @cindex file system, soft link
13897 @item @emph{Description}:
13898 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
13899 character (@code{CHAR(0)}) can be used to mark the end of the names in
13900 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
13901 names are ignored. If the @var{STATUS} argument is supplied, it
13902 contains 0 on success or a nonzero error code upon return; see
13903 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
13904 @code{ENOSYS} is returned.
13906 This intrinsic is provided in both subroutine and function forms;
13907 however, only one form can be used in any given program unit.
13909 @item @emph{Standard}:
13912 @item @emph{Class}:
13913 Subroutine, function
13915 @item @emph{Syntax}:
13916 @multitable @columnfractions .80
13917 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
13918 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
13921 @item @emph{Arguments}:
13922 @multitable @columnfractions .15 .70
13923 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
13924 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
13925 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
13928 @item @emph{See also}:
13936 @section @code{SYSTEM} --- Execute a shell command
13938 @cindex system, system call
13941 @item @emph{Description}:
13942 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
13943 argument @var{STATUS} is present, it contains the value returned by
13944 @code{system(3)}, which is presumably 0 if the shell command succeeded.
13945 Note that which shell is used to invoke the command is system-dependent
13946 and environment-dependent.
13948 This intrinsic is provided in both subroutine and function forms;
13949 however, only one form can be used in any given program unit.
13951 Note that the @code{system} function need not be thread-safe. It is
13952 the responsibility of the user to ensure that @code{system} is not
13953 called concurrently.
13955 @item @emph{Standard}:
13958 @item @emph{Class}:
13959 Subroutine, function
13961 @item @emph{Syntax}:
13962 @multitable @columnfractions .80
13963 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
13964 @item @code{STATUS = SYSTEM(COMMAND)}
13967 @item @emph{Arguments}:
13968 @multitable @columnfractions .15 .70
13969 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
13970 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
13973 @item @emph{See also}:
13974 @ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
13975 and should considered in new code for future portability.
13981 @section @code{SYSTEM_CLOCK} --- Time function
13982 @fnindex SYSTEM_CLOCK
13983 @cindex time, clock ticks
13984 @cindex clock ticks
13987 @item @emph{Description}:
13988 Determines the @var{COUNT} of a processor clock since an unspecified
13989 time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines
13990 the number of clock ticks per second. If the platform supports a
13991 monotonic clock, that clock is used and can, depending on the platform
13992 clock implementation, provide up to nanosecond resolution. If a
13993 monotonic clock is not available, the implementation falls back to a
13996 @var{COUNT_RATE} is system dependent and can vary depending on the kind of
13997 the arguments. For @var{kind=4} arguments (and smaller integer kinds),
13998 @var{COUNT} represents milliseconds, while for @var{kind=8} arguments (and
13999 larger integer kinds), @var{COUNT} typically represents micro- or
14000 nanoseconds depending on resolution of the underlying platform clock.
14001 @var{COUNT_MAX} usually equals @code{HUGE(COUNT_MAX)}. Note that the
14002 millisecond resolution of the @var{kind=4} version implies that the
14003 @var{COUNT} will wrap around in roughly 25 days. In order to avoid issues
14004 with the wrap around and for more precise timing, please use the
14005 @var{kind=8} version.
14007 If there is no clock, or querying the clock fails, @var{COUNT} is set
14008 to @code{-HUGE(COUNT)}, and @var{COUNT_RATE} and @var{COUNT_MAX} are
14011 When running on a platform using the GNU C library (glibc) version
14012 2.16 or older, or a derivative thereof, the high resolution monotonic
14013 clock is available only when linking with the @var{rt} library. This
14014 can be done explicitly by adding the @code{-lrt} flag when linking the
14015 application, but is also done implicitly when using OpenMP.
14017 On the Windows platform, the version with @var{kind=4} arguments uses
14018 the @code{GetTickCount} function, whereas the @var{kind=8} version
14019 uses @code{QueryPerformanceCounter} and
14020 @code{QueryPerformanceCounterFrequency}. For more information, and
14021 potential caveats, please see the platform documentation.
14023 @item @emph{Standard}:
14024 Fortran 90 and later
14026 @item @emph{Class}:
14029 @item @emph{Syntax}:
14030 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
14032 @item @emph{Arguments}:
14033 @multitable @columnfractions .20 .65
14034 @item @var{COUNT} @tab (Optional) shall be a scalar of type
14035 @code{INTEGER} with @code{INTENT(OUT)}.
14036 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type
14037 @code{INTEGER} or @code{REAL}, with @code{INTENT(OUT)}.
14038 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type
14039 @code{INTEGER} with @code{INTENT(OUT)}.
14042 @item @emph{Example}:
14044 PROGRAM test_system_clock
14045 INTEGER :: count, count_rate, count_max
14046 CALL SYSTEM_CLOCK(count, count_rate, count_max)
14047 WRITE(*,*) count, count_rate, count_max
14051 @item @emph{See also}:
14052 @ref{DATE_AND_TIME}, @*
14059 @section @code{TAN} --- Tangent function
14062 @cindex trigonometric function, tangent
14066 @item @emph{Description}:
14067 @code{TAN(X)} computes the tangent of @var{X}.
14069 @item @emph{Standard}:
14070 Fortran 77 and later, for a complex argument Fortran 2008 or later
14072 @item @emph{Class}:
14075 @item @emph{Syntax}:
14076 @code{RESULT = TAN(X)}
14078 @item @emph{Arguments}:
14079 @multitable @columnfractions .15 .70
14080 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
14083 @item @emph{Return value}:
14084 The return value has same type and kind as @var{X}, and its value is in radians.
14086 @item @emph{Example}:
14089 real(8) :: x = 0.165_8
14091 end program test_tan
14094 @item @emph{Specific names}:
14095 @multitable @columnfractions .20 .23 .20 .33
14096 @headitem Name @tab Argument @tab Return type @tab Standard
14097 @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
14098 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
14101 @item @emph{See also}:
14102 Inverse function: @*
14104 Degrees function: @*
14111 @section @code{TAND} --- Tangent function, degrees
14114 @cindex trigonometric function, tangent, degrees
14115 @cindex tangent, degrees
14118 @item @emph{Description}:
14119 @code{TAND(X)} computes the tangent of @var{X} in degrees.
14121 @item @emph{Standard}:
14124 @item @emph{Class}:
14127 @item @emph{Syntax}:
14128 @code{RESULT = TAND(X)}
14130 @item @emph{Arguments}:
14131 @multitable @columnfractions .15 .70
14132 @item @var{X} @tab The type shall be @code{REAL}.
14135 @item @emph{Return value}:
14136 The return value has same type and kind as @var{X}.
14138 @item @emph{Example}:
14141 real(8) :: x = 45_8
14143 end program test_tand
14146 @item @emph{Specific names}:
14147 @multitable @columnfractions .20 .23 .20 .33
14148 @headitem Name @tab Argument @tab Return type @tab Standard
14149 @item @code{TAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 2023
14150 @item @code{DTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
14153 @item @emph{See also}:
14154 Inverse function: @*
14156 Radians function: @*
14163 @section @code{TANH} --- Hyperbolic tangent function
14166 @cindex hyperbolic tangent
14167 @cindex hyperbolic function, tangent
14168 @cindex tangent, hyperbolic
14171 @item @emph{Description}:
14172 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
14174 @item @emph{Standard}:
14175 Fortran 77 and later, for a complex argument Fortran 2008 or later
14177 @item @emph{Class}:
14180 @item @emph{Syntax}:
14183 @item @emph{Arguments}:
14184 @multitable @columnfractions .15 .70
14185 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
14188 @item @emph{Return value}:
14189 The return value has same type and kind as @var{X}. If @var{X} is
14190 complex, the imaginary part of the result is in radians. If @var{X}
14191 is @code{REAL}, the return value lies in the range
14192 @math{ - 1 \leq tanh(x) \leq 1 }.
14194 @item @emph{Example}:
14197 real(8) :: x = 2.1_8
14199 end program test_tanh
14202 @item @emph{Specific names}:
14203 @multitable @columnfractions .20 .23 .20 .33
14204 @headitem Name @tab Argument @tab Return type @tab Standard
14205 @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
14206 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
14209 @item @emph{See also}:
14216 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
14217 @fnindex THIS_IMAGE
14218 @cindex coarray, @code{THIS_IMAGE}
14219 @cindex images, index of this image
14222 @item @emph{Description}:
14223 Returns the cosubscript for this image.
14225 @item @emph{Standard}:
14226 Fortran 2008 and later. With @var{DISTANCE} argument,
14227 Technical Specification (TS) 18508 or later
14229 @item @emph{Class}:
14230 Transformational function
14232 @item @emph{Syntax}:
14233 @multitable @columnfractions .80
14234 @item @code{RESULT = THIS_IMAGE()}
14235 @item @code{RESULT = THIS_IMAGE(DISTANCE)}
14236 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
14239 @item @emph{Arguments}:
14240 @multitable @columnfractions .15 .70
14241 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
14242 (not permitted together with @var{COARRAY}).
14243 @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
14244 present, required).
14245 @item @var{DIM} @tab default integer scalar (optional). If present,
14246 @var{DIM} shall be between one and the corank of @var{COARRAY}.
14250 @item @emph{Return value}:
14251 Default integer. If @var{COARRAY} is not present, it is scalar; if
14252 @var{DISTANCE} is not present or has value 0, its value is the image index on
14253 the invoking image for the current team, for values smaller or equal
14254 distance to the initial team, it returns the image index on the ancestor team
14255 which has a distance of @var{DISTANCE} from the invoking team. If
14256 @var{DISTANCE} is larger than the distance to the initial team, the image
14257 index of the initial team is returned. Otherwise when the @var{COARRAY} is
14258 present, if @var{DIM} is not present, a rank-1 array with corank elements is
14259 returned, containing the cosubscripts for @var{COARRAY} specifying the invoking
14260 image. If @var{DIM} is present, a scalar is returned, with the value of
14261 the @var{DIM} element of @code{THIS_IMAGE(COARRAY)}.
14263 @item @emph{Example}:
14265 INTEGER :: value[*]
14267 value = THIS_IMAGE()
14269 IF (THIS_IMAGE() == 1) THEN
14270 DO i = 1, NUM_IMAGES()
14271 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
14275 ! Check whether the current image is the initial image
14276 IF (THIS_IMAGE(HUGE(1)) /= THIS_IMAGE())
14277 error stop "something is rotten here"
14280 @item @emph{See also}:
14281 @ref{NUM_IMAGES}, @*
14288 @section @code{TIME} --- Time function
14290 @cindex time, current
14291 @cindex current time
14294 @item @emph{Description}:
14295 Returns the current time encoded as an integer (in the manner of the
14296 function @code{time(3)} in the C standard library). This value is
14297 suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}.
14299 This intrinsic is not fully portable, such as to systems with 32-bit
14300 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
14301 the values returned by this intrinsic might be, or become, negative, or
14302 numerically less than previous values, during a single run of the
14305 See @ref{TIME8}, for information on a similar intrinsic that might be
14306 portable to more GNU Fortran implementations, though to fewer Fortran
14309 @item @emph{Standard}:
14312 @item @emph{Class}:
14315 @item @emph{Syntax}:
14316 @code{RESULT = TIME()}
14318 @item @emph{Return value}:
14319 The return value is a scalar of type @code{INTEGER(4)}.
14321 @item @emph{See also}:
14322 @ref{DATE_AND_TIME}, @*
14333 @section @code{TIME8} --- Time function (64-bit)
14335 @cindex time, current
14336 @cindex current time
14339 @item @emph{Description}:
14340 Returns the current time encoded as an integer (in the manner of the
14341 function @code{time(3)} in the C standard library). This value is
14342 suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}.
14344 @emph{Warning:} this intrinsic does not increase the range of the timing
14345 values over that returned by @code{time(3)}. On a system with a 32-bit
14346 @code{time(3)}, @code{TIME8} will return a 32-bit value, even though
14347 it is converted to a 64-bit @code{INTEGER(8)} value. That means
14348 overflows of the 32-bit value can still occur. Therefore, the values
14349 returned by this intrinsic might be or become negative or numerically
14350 less than previous values during a single run of the compiled program.
14352 @item @emph{Standard}:
14355 @item @emph{Class}:
14358 @item @emph{Syntax}:
14359 @code{RESULT = TIME8()}
14361 @item @emph{Return value}:
14362 The return value is a scalar of type @code{INTEGER(8)}.
14364 @item @emph{See also}:
14365 @ref{DATE_AND_TIME}, @*
14376 @section @code{TINY} --- Smallest positive number of a real kind
14378 @cindex limits, smallest number
14379 @cindex model representation, smallest number
14382 @item @emph{Description}:
14383 @code{TINY(X)} returns the smallest positive (non zero) number
14384 in the model of the type of @code{X}.
14386 @item @emph{Standard}:
14387 Fortran 90 and later
14389 @item @emph{Class}:
14392 @item @emph{Syntax}:
14393 @code{RESULT = TINY(X)}
14395 @item @emph{Arguments}:
14396 @multitable @columnfractions .15 .70
14397 @item @var{X} @tab Shall be of type @code{REAL}.
14400 @item @emph{Return value}:
14401 The return value is of the same type and kind as @var{X}
14403 @item @emph{Example}:
14404 See @code{HUGE} for an example.
14410 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
14415 @item @emph{Description}:
14416 @code{TRAILZ} returns the number of trailing zero bits of an integer.
14418 @item @emph{Standard}:
14419 Fortran 2008 and later
14421 @item @emph{Class}:
14424 @item @emph{Syntax}:
14425 @code{RESULT = TRAILZ(I)}
14427 @item @emph{Arguments}:
14428 @multitable @columnfractions .15 .70
14429 @item @var{I} @tab Shall be of type @code{INTEGER}.
14432 @item @emph{Return value}:
14433 The type of the return value is the default @code{INTEGER}.
14434 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
14436 @item @emph{Example}:
14438 PROGRAM test_trailz
14439 WRITE (*,*) TRAILZ(8) ! prints 3
14443 @item @emph{See also}:
14453 @section @code{TRANSFER} --- Transfer bit patterns
14459 @item @emph{Description}:
14460 Interprets the bitwise representation of @var{SOURCE} in memory as if it
14461 is the representation of a variable or array of the same type and type
14462 parameters as @var{MOLD}.
14464 This is approximately equivalent to the C concept of @emph{casting} one
14467 @item @emph{Standard}:
14468 Fortran 90 and later
14470 @item @emph{Class}:
14471 Transformational function
14473 @item @emph{Syntax}:
14474 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
14476 @item @emph{Arguments}:
14477 @multitable @columnfractions .15 .70
14478 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
14479 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
14480 @item @var{SIZE} @tab (Optional) shall be a scalar of type
14484 @item @emph{Return value}:
14485 The result has the same type as @var{MOLD}, with the bit level
14486 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
14487 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
14488 but @var{MOLD} is an array (of any size or shape), the result is a one-
14489 dimensional array of the minimum length needed to contain the entirety
14490 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
14491 and @var{MOLD} is a scalar, the result is a scalar.
14493 If the bitwise representation of the result is longer than that of
14494 @var{SOURCE}, then the leading bits of the result correspond to those of
14495 @var{SOURCE} and any trailing bits are filled arbitrarily.
14497 When the resulting bit representation does not correspond to a valid
14498 representation of a variable of the same type as @var{MOLD}, the results
14499 are undefined, and subsequent operations on the result cannot be
14500 guaranteed to produce sensible behavior. For example, it is possible to
14501 create @code{LOGICAL} variables for which @code{@var{VAR}} and
14502 @code{.NOT.@var{VAR}} both appear to be true.
14504 @item @emph{Example}:
14506 PROGRAM test_transfer
14507 integer :: x = 2143289344
14508 print *, transfer(x, 1.0) ! prints "NaN" on i686
14516 @section @code{TRANSPOSE} --- Transpose an array of rank two
14518 @cindex array, transpose
14519 @cindex matrix, transpose
14523 @item @emph{Description}:
14524 Transpose an array of rank two. Element (i, j) of the result has the value
14525 @code{MATRIX(j, i)}, for all i, j.
14527 @item @emph{Standard}:
14528 Fortran 90 and later
14530 @item @emph{Class}:
14531 Transformational function
14533 @item @emph{Syntax}:
14534 @code{RESULT = TRANSPOSE(MATRIX)}
14536 @item @emph{Arguments}:
14537 @multitable @columnfractions .15 .70
14538 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
14541 @item @emph{Return value}:
14542 The result has the same type as @var{MATRIX}, and has shape
14543 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
14549 @section @code{TRIM} --- Remove trailing blank characters of a string
14551 @cindex string, remove trailing whitespace
14554 @item @emph{Description}:
14555 Removes trailing blank characters of a string.
14557 @item @emph{Standard}:
14558 Fortran 90 and later
14560 @item @emph{Class}:
14561 Transformational function
14563 @item @emph{Syntax}:
14564 @code{RESULT = TRIM(STRING)}
14566 @item @emph{Arguments}:
14567 @multitable @columnfractions .15 .70
14568 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
14571 @item @emph{Return value}:
14572 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
14573 less the number of trailing blanks.
14575 @item @emph{Example}:
14578 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
14579 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
14583 @item @emph{See also}:
14591 @section @code{TTYNAM} --- Get the name of a terminal device
14593 @cindex system, terminal
14596 @item @emph{Description}:
14597 Get the name of a terminal device. For more information,
14598 see @code{ttyname(3)}.
14600 This intrinsic is provided in both subroutine and function forms;
14601 however, only one form can be used in any given program unit.
14603 @item @emph{Standard}:
14606 @item @emph{Class}:
14607 Subroutine, function
14609 @item @emph{Syntax}:
14610 @multitable @columnfractions .80
14611 @item @code{CALL TTYNAM(UNIT, NAME)}
14612 @item @code{NAME = TTYNAM(UNIT)}
14615 @item @emph{Arguments}:
14616 @multitable @columnfractions .15 .70
14617 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
14618 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
14621 @item @emph{Example}:
14623 PROGRAM test_ttynam
14626 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
14631 @item @emph{See also}:
14638 @section @code{UBOUND} --- Upper dimension bounds of an array
14640 @cindex array, upper bound
14643 @item @emph{Description}:
14644 Returns the upper bounds of an array, or a single upper bound
14645 along the @var{DIM} dimension.
14646 @item @emph{Standard}:
14647 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
14649 @item @emph{Class}:
14652 @item @emph{Syntax}:
14653 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
14655 @item @emph{Arguments}:
14656 @multitable @columnfractions .15 .70
14657 @item @var{ARRAY} @tab Shall be an array, of any type.
14658 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
14659 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
14660 expression indicating the kind parameter of the result.
14663 @item @emph{Return value}:
14664 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14665 @var{KIND} is absent, the return value is of default integer kind.
14666 If @var{DIM} is absent, the result is an array of the upper bounds of
14667 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
14668 corresponding to the upper bound of the array along that dimension. If
14669 @var{ARRAY} is an expression rather than a whole array or array
14670 structure component, or if it has a zero extent along the relevant
14671 dimension, the upper bound is taken to be the number of elements along
14672 the relevant dimension.
14674 @item @emph{See also}:
14682 @section @code{UCOBOUND} --- Upper codimension bounds of an array
14684 @cindex coarray, upper bound
14687 @item @emph{Description}:
14688 Returns the upper cobounds of a coarray, or a single upper cobound
14689 along the @var{DIM} codimension.
14690 @item @emph{Standard}:
14691 Fortran 2008 and later
14693 @item @emph{Class}:
14696 @item @emph{Syntax}:
14697 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
14699 @item @emph{Arguments}:
14700 @multitable @columnfractions .15 .70
14701 @item @var{ARRAY} @tab Shall be an coarray, of any type.
14702 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
14703 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
14704 expression indicating the kind parameter of the result.
14707 @item @emph{Return value}:
14708 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14709 @var{KIND} is absent, the return value is of default integer kind.
14710 If @var{DIM} is absent, the result is an array of the lower cobounds of
14711 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
14712 corresponding to the lower cobound of the array along that codimension.
14714 @item @emph{See also}:
14722 @section @code{UMASK} --- Set the file creation mask
14724 @cindex file system, file creation mask
14727 @item @emph{Description}:
14728 Sets the file creation mask to @var{MASK}. If called as a function, it
14729 returns the old value. If called as a subroutine and argument @var{OLD}
14730 if it is supplied, it is set to the old value. See @code{umask(2)}.
14732 @item @emph{Standard}:
14735 @item @emph{Class}:
14736 Subroutine, function
14738 @item @emph{Syntax}:
14739 @multitable @columnfractions .80
14740 @item @code{CALL UMASK(MASK [, OLD])}
14741 @item @code{OLD = UMASK(MASK)}
14744 @item @emph{Arguments}:
14745 @multitable @columnfractions .15 .70
14746 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
14747 @item @var{OLD} @tab (Optional) Shall be a scalar of type
14756 @section @code{UNLINK} --- Remove a file from the file system
14758 @cindex file system, remove file
14761 @item @emph{Description}:
14762 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
14763 used to mark the end of the name in @var{PATH}; otherwise, trailing
14764 blanks in the file name are ignored. If the @var{STATUS} argument is
14765 supplied, it contains 0 on success or a nonzero error code upon return;
14766 see @code{unlink(2)}.
14768 This intrinsic is provided in both subroutine and function forms;
14769 however, only one form can be used in any given program unit.
14771 @item @emph{Standard}:
14774 @item @emph{Class}:
14775 Subroutine, function
14777 @item @emph{Syntax}:
14778 @multitable @columnfractions .80
14779 @item @code{CALL UNLINK(PATH [, STATUS])}
14780 @item @code{STATUS = UNLINK(PATH)}
14783 @item @emph{Arguments}:
14784 @multitable @columnfractions .15 .70
14785 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
14786 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
14789 @item @emph{See also}:
14797 @section @code{UNPACK} --- Unpack an array of rank one into an array
14799 @cindex array, unpacking
14800 @cindex array, increase dimension
14801 @cindex array, scatter elements
14804 @item @emph{Description}:
14805 Store the elements of @var{VECTOR} in an array of higher rank.
14807 @item @emph{Standard}:
14808 Fortran 90 and later
14810 @item @emph{Class}:
14811 Transformational function
14813 @item @emph{Syntax}:
14814 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
14816 @item @emph{Arguments}:
14817 @multitable @columnfractions .15 .70
14818 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
14819 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
14820 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
14821 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
14822 the same shape as @var{MASK}.
14825 @item @emph{Return value}:
14826 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
14827 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
14829 @item @emph{Example}:
14831 PROGRAM test_unpack
14832 integer :: vector(2) = (/1,1/)
14833 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
14834 integer :: field(2,2) = 0, unity(2,2)
14836 ! result: unity matrix
14837 unity = unpack(vector, reshape(mask, (/2,2/)), field)
14841 @item @emph{See also}:
14849 @section @code{VERIFY} --- Scan a string for characters not a given set
14851 @cindex string, find missing set
14854 @item @emph{Description}:
14855 Verifies that all the characters in @var{STRING} belong to the set of
14856 characters in @var{SET}.
14858 If @var{BACK} is either absent or equals @code{FALSE}, this function
14859 returns the position of the leftmost character of @var{STRING} that is
14860 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost
14861 position is returned. If all characters of @var{STRING} are found in
14862 @var{SET}, the result is zero.
14864 @item @emph{Standard}:
14865 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
14867 @item @emph{Class}:
14870 @item @emph{Syntax}:
14871 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
14873 @item @emph{Arguments}:
14874 @multitable @columnfractions .15 .70
14875 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
14876 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
14877 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
14878 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
14879 expression indicating the kind parameter of the result.
14882 @item @emph{Return value}:
14883 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14884 @var{KIND} is absent, the return value is of default integer kind.
14886 @item @emph{Example}:
14888 PROGRAM test_verify
14889 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
14890 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
14891 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
14892 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
14893 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
14897 @item @emph{See also}:
14899 @ref{INDEX intrinsic}
14905 @section @code{XOR} --- Bitwise logical exclusive OR
14907 @cindex bitwise logical exclusive or
14908 @cindex logical exclusive or, bitwise
14911 @item @emph{Description}:
14912 Bitwise logical exclusive or.
14914 This intrinsic routine is provided for backwards compatibility with
14915 GNU Fortran 77. For integer arguments, programmers should consider
14916 the use of the @ref{IEOR} intrinsic and for logical arguments the
14917 @code{.NEQV.} operator, which are both defined by the Fortran standard.
14919 @item @emph{Standard}:
14922 @item @emph{Class}:
14925 @item @emph{Syntax}:
14926 @code{RESULT = XOR(I, J)}
14928 @item @emph{Arguments}:
14929 @multitable @columnfractions .15 .70
14930 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
14931 type or a scalar @code{LOGICAL} type or a boz-literal-constant.
14932 @item @var{J} @tab The type shall be the same as the type of @var{I} or
14933 a boz-literal-constant. @var{I} and @var{J} shall not both be
14934 boz-literal-constants. If either @var{I} and @var{J} is a
14935 boz-literal-constant, then the other argument must be a scalar @code{INTEGER}.
14938 @item @emph{Return value}:
14939 The return type is either a scalar @code{INTEGER} or a scalar
14940 @code{LOGICAL}. If the kind type parameters differ, then the
14941 smaller kind type is implicitly converted to larger kind, and the
14942 return has the larger kind. A boz-literal-constant is
14943 converted to an @code{INTEGER} with the kind type parameter of
14944 the other argument as-if a call to @ref{INT} occurred.
14946 @item @emph{Example}:
14949 LOGICAL :: T = .TRUE., F = .FALSE.
14951 DATA a / Z'F' /, b / Z'3' /
14953 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
14954 WRITE (*,*) XOR(a, b)
14958 @item @emph{See also}:
14959 Fortran 95 elemental function: @*
14965 @node Intrinsic Modules
14966 @chapter Intrinsic Modules
14967 @cindex intrinsic Modules
14970 * ISO_FORTRAN_ENV::
14973 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
14974 * OpenACC Module OPENACC::
14977 @node ISO_FORTRAN_ENV
14978 @section @code{ISO_FORTRAN_ENV}
14980 @item @emph{Standard}:
14981 Fortran 2003 and later, except when otherwise noted
14984 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
14988 @item @code{ATOMIC_INT_KIND}:
14989 Default-kind integer constant to be used as kind parameter when defining
14990 integer variables used in atomic operations. (Fortran 2008 or later.)
14992 @item @code{ATOMIC_LOGICAL_KIND}:
14993 Default-kind integer constant to be used as kind parameter when defining
14994 logical variables used in atomic operations. (Fortran 2008 or later.)
14996 @item @code{CHARACTER_KINDS}:
14997 Default-kind integer constant array of rank one containing the supported kind
14998 parameters of the @code{CHARACTER} type. (Fortran 2008 or later.)
15000 @item @code{CHARACTER_STORAGE_SIZE}:
15001 Size in bits of the character storage unit.
15003 @item @code{ERROR_UNIT}:
15004 Identifies the preconnected unit used for error reporting.
15006 @item @code{FILE_STORAGE_SIZE}:
15007 Size in bits of the file-storage unit.
15009 @item @code{INPUT_UNIT}:
15010 Identifies the preconnected unit identified by the asterisk
15011 (@code{*}) in @code{READ} statement.
15013 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
15014 Kind type parameters to specify an INTEGER type with a storage
15015 size of 16, 32, and 64 bits. It is negative if a target platform
15016 does not support the particular kind. (Fortran 2008 or later.)
15018 @item @code{INTEGER_KINDS}:
15019 Default-kind integer constant array of rank one containing the supported kind
15020 parameters of the @code{INTEGER} type. (Fortran 2008 or later.)
15022 @item @code{IOSTAT_END}:
15023 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
15024 an input/output statement if an end-of-file condition occurred.
15026 @item @code{IOSTAT_EOR}:
15027 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
15028 an input/output statement if an end-of-record condition occurred.
15030 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
15031 Scalar default-integer constant, used by @code{INQUIRE} for the
15032 @code{IOSTAT=} specifier to denote an that a unit number identifies an
15033 internal unit. (Fortran 2008 or later.)
15035 @item @code{NUMERIC_STORAGE_SIZE}:
15036 The size in bits of the numeric storage unit.
15038 @item @code{LOGICAL_KINDS}:
15039 Default-kind integer constant array of rank one containing the supported kind
15040 parameters of the @code{LOGICAL} type. (Fortran 2008 or later.)
15042 @item @code{OUTPUT_UNIT}:
15043 Identifies the preconnected unit identified by the asterisk
15044 (@code{*}) in @code{WRITE} statement.
15046 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
15047 Kind type parameters to specify a REAL type with a storage
15048 size of 32, 64, and 128 bits. It is negative if a target platform
15049 does not support the particular kind. (Fortran 2008 or later.)
15051 @item @code{REAL_KINDS}:
15052 Default-kind integer constant array of rank one containing the supported kind
15053 parameters of the @code{REAL} type. (Fortran 2008 or later.)
15055 @item @code{STAT_LOCKED}:
15056 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
15057 denote that the lock variable is locked by the executing image. (Fortran 2008
15060 @item @code{STAT_LOCKED_OTHER_IMAGE}:
15061 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
15062 denote that the lock variable is locked by another image. (Fortran 2008 or
15065 @item @code{STAT_STOPPED_IMAGE}:
15066 Positive, scalar default-integer constant used as STAT= return value if the
15067 argument in the statement requires synchronisation with an image, which has
15068 initiated the termination of the execution. (Fortran 2008 or later.)
15070 @item @code{STAT_FAILED_IMAGE}:
15071 Positive, scalar default-integer constant used as STAT= return value if the
15072 argument in the statement requires communication with an image, which has
15073 is in the failed state. (TS 18508 or later.)
15075 @item @code{STAT_UNLOCKED}:
15076 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
15077 denote that the lock variable is unlocked. (Fortran 2008 or later.)
15080 The module provides the following derived type:
15083 @item @code{LOCK_TYPE}:
15084 Derived type with private components to be use with the @code{LOCK} and
15085 @code{UNLOCK} statement. A variable of its type has to be always declared
15086 as coarray and may not appear in a variable-definition context.
15087 (Fortran 2008 or later.)
15090 The module also provides the following intrinsic procedures:
15091 @ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}.
15095 @node ISO_C_BINDING
15096 @section @code{ISO_C_BINDING}
15098 @item @emph{Standard}:
15099 Fortran 2003 and later, GNU extensions
15102 The following intrinsic procedures are provided by the module; their
15103 definition can be found in the section Intrinsic Procedures of this
15107 @item @code{C_ASSOCIATED}
15108 @item @code{C_F_POINTER}
15109 @item @code{C_F_PROCPOINTER}
15110 @item @code{C_FUNLOC}
15112 @item @code{C_SIZEOF}
15114 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
15115 @c don't really know why.
15117 The @code{ISO_C_BINDING} module provides the following named constants of
15118 type default integer, which can be used as KIND type parameters.
15120 In addition to the integer named constants required by the Fortran 2003
15121 standard and @code{C_PTRDIFF_T} of TS 29113, GNU Fortran provides as an
15122 extension named constants for the 128-bit integer types supported by the
15123 C compiler: @code{C_INT128_T, C_INT_LEAST128_T, C_INT_FAST128_T}.
15124 Furthermore, if @code{_Float128} is supported in C, the named constants
15125 @code{C_FLOAT128} and @code{C_FLOAT128_COMPLEX} are defined.
15127 @multitable @columnfractions .19 .32 .34 .15
15128 @headitem Fortran Type @tab Named constant @tab C type @tab Extension
15129 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
15130 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
15131 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
15132 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
15133 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
15134 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
15135 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
15136 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
15137 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
15138 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
15139 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
15140 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
15141 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
15142 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
15143 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
15144 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
15145 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
15146 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
15147 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
15148 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
15149 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
15150 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
15151 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
15152 @item @code{INTEGER}@tab @code{C_PTRDIFF_T} @tab @code{ptrdiff_t} @tab TS 29113
15153 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
15154 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
15155 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
15156 @item @code{REAL} @tab @code{C_FLOAT128} @tab @code{_Float128} @tab Ext.
15157 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
15158 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
15159 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
15160 @item @code{COMPLEX}@tab @code{C_FLOAT128_COMPLEX} @tab @code{_Float128 _Complex} @tab Ext.
15161 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
15162 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
15165 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
15168 @multitable @columnfractions .20 .45 .15
15169 @headitem Name @tab C definition @tab Value
15170 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
15171 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
15172 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
15173 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
15174 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
15175 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
15176 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
15177 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
15180 Moreover, the following two named constants are defined:
15182 @multitable @columnfractions .20 .80
15183 @headitem Name @tab Type
15184 @item @code{C_NULL_PTR} @tab @code{C_PTR}
15185 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
15188 Both are equivalent to the value @code{NULL} in C.
15193 @section IEEE modules: @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
15195 @item @emph{Standard}:
15196 Fortran 2003 and later
15199 The @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
15200 intrinsic modules provide support for exceptions and IEEE arithmetic, as
15201 defined in Fortran 2003 and later standards, and the IEC 60559:1989 standard
15202 (@emph{Binary floating-point arithmetic for microprocessor systems}). These
15203 modules are only provided on the following supported platforms:
15206 @item i386 and x86_64 processors
15207 @item platforms which use the GNU C Library (glibc)
15208 @item platforms with support for SysV/386 routines for floating point
15209 interface (including Solaris and BSDs)
15210 @item platforms with the AIX OS
15213 For full compliance with the Fortran standards, code using the
15214 @code{IEEE_EXCEPTIONS} or @code{IEEE_ARITHMETIC} modules should be compiled
15215 with the following options: @code{-fno-unsafe-math-optimizations
15216 -frounding-math -fsignaling-nans}.
15220 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
15221 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
15223 @item @emph{Standard}:
15224 OpenMP Application Program Interface v4.5,
15225 OpenMP Application Program Interface v5.0 (partially supported),
15226 OpenMP Application Program Interface v5.1 (partially supported) and
15227 OpenMP Application Program Interface v5.2 (partially supported).
15230 The OpenMP Fortran runtime library routines are provided both in
15231 a form of two Fortran modules, named @code{OMP_LIB} and
15232 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
15233 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
15234 in the @ref{Top,,Introduction,libgomp,GNU Offloading and Multi
15235 Processing Runtime Library} manual,
15236 the named constants defined in the modules are listed
15239 For details refer to the actual
15240 @uref{https://www.openmp.org/wp-content/uploads/openmp-4.5.pdf,
15241 OpenMP Application Program Interface v4.5},
15242 @uref{https://www.openmp.org/wp-content/uploads/OpenMP-API-Specification-5.0.pdf,
15243 OpenMP Application Program Interface v5.0},
15244 @uref{https://www.openmp.org/wp-content/uploads/OpenMP-API-Specification-5-1.pdf,
15245 OpenMP Application Program Interface v5.1} and
15246 @uref{https://www.openmp.org/wp-content/uploads/OpenMP-API-Specification-5-2.pdf,
15247 OpenMP Application Program Interface v5.2}.
15249 @code{OMP_LIB_KINDS} provides the following scalar default-integer
15253 @item @code{omp_allocator_handle_kind}
15254 @item @code{omp_alloctrait_key_kind}
15255 @item @code{omp_alloctrait_val_kind}
15256 @item @code{omp_depend_kind}
15257 @item @code{omp_lock_kind}
15258 @item @code{omp_lock_hint_kind}
15259 @item @code{omp_nest_lock_kind}
15260 @item @code{omp_pause_resource_kind}
15261 @item @code{omp_memspace_handle_kind}
15262 @item @code{omp_proc_bind_kind}
15263 @item @code{omp_sched_kind}
15264 @item @code{omp_sync_hint_kind}
15267 @code{OMP_LIB} provides the scalar default-integer
15268 named constant @code{openmp_version} with a value of the form
15269 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
15270 of the OpenMP version; for OpenMP v4.5 the value is @code{201511}.
15272 The following derived type:
15275 @item @code{omp_alloctrait}
15278 The following scalar default-integer named constants:
15280 @item @code{omp_initial_device}
15281 @item @code{omp_invalid_device}
15285 The following scalar integer named constants of the
15286 kind @code{omp_sched_kind}:
15289 @item @code{omp_sched_static}
15290 @item @code{omp_sched_dynamic}
15291 @item @code{omp_sched_guided}
15292 @item @code{omp_sched_auto}
15295 And the following scalar integer named constants of the
15296 kind @code{omp_proc_bind_kind}:
15299 @item @code{omp_proc_bind_false}
15300 @item @code{omp_proc_bind_true}
15301 @item @code{omp_proc_bind_primary}
15302 @item @code{omp_proc_bind_master}
15303 @item @code{omp_proc_bind_close}
15304 @item @code{omp_proc_bind_spread}
15307 The following scalar integer named constants are of the
15308 kind @code{omp_lock_hint_kind}:
15311 @item @code{omp_lock_hint_none}
15312 @item @code{omp_lock_hint_uncontended}
15313 @item @code{omp_lock_hint_contended}
15314 @item @code{omp_lock_hint_nonspeculative}
15315 @item @code{omp_lock_hint_speculative}
15316 @item @code{omp_sync_hint_none}
15317 @item @code{omp_sync_hint_uncontended}
15318 @item @code{omp_sync_hint_contended}
15319 @item @code{omp_sync_hint_nonspeculative}
15320 @item @code{omp_sync_hint_speculative}
15323 And the following two scalar integer named constants are of the
15324 kind @code{omp_pause_resource_kind}:
15327 @item @code{omp_pause_soft}
15328 @item @code{omp_pause_hard}
15331 The following scalar integer named constants are of the kind
15332 @code{omp_alloctrait_key_kind}:
15335 @item @code{omp_atk_sync_hint}
15336 @item @code{omp_atk_alignment}
15337 @item @code{omp_atk_access}
15338 @item @code{omp_atk_pool_size}
15339 @item @code{omp_atk_fallback}
15340 @item @code{omp_atk_fb_data}
15341 @item @code{omp_atk_pinned}
15342 @item @code{omp_atk_partition}
15345 The following scalar integer named constants are of the kind
15346 @code{omp_alloctrait_val_kind}:
15349 @code{omp_alloctrait_key_kind}:
15350 @item @code{omp_atv_default}
15351 @item @code{omp_atv_false}
15352 @item @code{omp_atv_true}
15353 @item @code{omp_atv_contended}
15354 @item @code{omp_atv_uncontended}
15355 @item @code{omp_atv_serialized}
15356 @item @code{omp_atv_sequential}
15357 @item @code{omp_atv_private}
15358 @item @code{omp_atv_all}
15359 @item @code{omp_atv_thread}
15360 @item @code{omp_atv_pteam}
15361 @item @code{omp_atv_cgroup}
15362 @item @code{omp_atv_default_mem_fb}
15363 @item @code{omp_atv_null_fb}
15364 @item @code{omp_atv_abort_fb}
15365 @item @code{omp_atv_allocator_fb}
15366 @item @code{omp_atv_environment}
15367 @item @code{omp_atv_nearest}
15368 @item @code{omp_atv_blocked}
15371 The following scalar integer named constants are of the kind
15372 @code{omp_allocator_handle_kind}:
15375 @item @code{omp_null_allocator}
15376 @item @code{omp_default_mem_alloc}
15377 @item @code{omp_large_cap_mem_alloc}
15378 @item @code{omp_const_mem_alloc}
15379 @item @code{omp_high_bw_mem_alloc}
15380 @item @code{omp_low_lat_mem_alloc}
15381 @item @code{omp_cgroup_mem_alloc}
15382 @item @code{omp_pteam_mem_alloc}
15383 @item @code{omp_thread_mem_alloc}
15386 The following scalar integer named constants are of the kind
15387 @code{omp_memspace_handle_kind}:
15390 @item @code{omp_default_mem_space}
15391 @item @code{omp_large_cap_mem_space}
15392 @item @code{omp_const_mem_space}
15393 @item @code{omp_high_bw_mem_space}
15394 @item @code{omp_low_lat_mem_space}
15399 @node OpenACC Module OPENACC
15400 @section OpenACC Module @code{OPENACC}
15402 @item @emph{Standard}:
15403 OpenACC Application Programming Interface v2.6
15407 The OpenACC Fortran runtime library routines are provided both in a
15408 form of a Fortran 90 module, named @code{OPENACC}, and in form of a
15409 Fortran @code{include} file named @file{openacc_lib.h}. The
15410 procedures provided by @code{OPENACC} can be found in the
15411 @ref{Top,,Introduction,libgomp,GNU Offloading and Multi Processing
15412 Runtime Library} manual, the named constants defined in the modules
15415 For details refer to the actual
15416 @uref{https://www.openacc.org/,
15417 OpenACC Application Programming Interface v2.6}.
15419 @code{OPENACC} provides the scalar default-integer
15420 named constant @code{openacc_version} with a value of the form
15421 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
15422 of the OpenACC version; for OpenACC v2.6 the value is @code{201711}.