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 - or the type shall be @code{COMPLEX}.
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 - or be @code{COMPLEX}.
1384 @item @emph{Return value}:
1385 The return value is of the same type and kind as @var{X}.
1386 The real part of 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)}
1624 @item @code{RESULT = ATAND(Y, X)}
1627 @item @emph{Arguments}:
1628 @multitable @columnfractions .15 .70
1629 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1630 if @var{Y} is present, @var{X} shall be REAL.
1631 @item @var{Y} @tab The type and kind type parameter shall be the same as @var{X}.
1634 @item @emph{Return value}:
1635 The return value is of the same type and kind as @var{X}.
1636 If @var{Y} is present, the result is identical to @code{ATAND2(Y,X)}.
1637 Otherwise, it is the arcus tangent of @var{X}, where the real part of
1638 the result is in degrees and lies in the range
1639 @math{-90 \leq \Re \atand(x) \leq 90}.
1641 @item @emph{Example}:
1644 real(8) :: x = 2.866_8
1646 end program test_atand
1649 @item @emph{Specific names}:
1650 @multitable @columnfractions .23 .23 .20 .30
1651 @headitem Name @tab Argument @tab Return type @tab Standard
1652 @item @code{ATAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 2023
1653 @item @code{DATAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1656 @item @emph{See also}:
1657 Inverse function: @*
1659 Radians function: @*
1666 @section @code{ATAN2} --- Arctangent function
1669 @cindex trigonometric function, tangent, inverse
1670 @cindex tangent, inverse
1673 @item @emph{Description}:
1674 @code{ATAN2(Y, X)} computes the principal value of the argument
1675 function of the complex number @math{X + i Y}. This function can
1676 be used to transform from Cartesian into polar coordinates and
1677 allows to determine the angle in the correct quadrant.
1679 @item @emph{Standard}:
1680 Fortran 77 and later
1685 @item @emph{Syntax}:
1686 @code{RESULT = ATAN2(Y, X)}
1688 @item @emph{Arguments}:
1689 @multitable @columnfractions .15 .70
1690 @item @var{Y} @tab The type shall be @code{REAL}.
1691 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1692 If @var{Y} is zero, then @var{X} must be nonzero.
1695 @item @emph{Return value}:
1696 The return value has the same type and kind type parameter as @var{Y}. It
1697 is the principal value of the complex number @math{X + i Y}. If @var{X}
1698 is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1699 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1700 the return value is zero if @var{X} is strictly positive, @math{\pi} if
1701 @var{X} is negative and @var{Y} is positive zero (or the processor does
1702 not handle signed zeros), and @math{-\pi} if @var{X} is negative and
1703 @var{Y} is negative zero. Finally, if @var{X} is zero, then the
1704 magnitude of the result is @math{\pi/2}.
1706 @item @emph{Example}:
1709 real(4) :: x = 1.e0_4, y = 0.5e0_4
1711 end program test_atan2
1714 @item @emph{Specific names}:
1715 @multitable @columnfractions .22 .22 .20 .32
1716 @headitem Name @tab Argument @tab Return type @tab Standard
1717 @item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1718 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1721 @item @emph{See also}:
1724 Degrees function: @*
1731 @section @code{ATAN2D} --- Arctangent function, degrees
1734 @cindex trigonometric function, tangent, inverse, degrees
1735 @cindex tangent, inverse, degrees
1738 @item @emph{Description}:
1739 @code{ATAN2D(Y, X)} computes the principal value of the argument
1740 function of the complex number @math{X + i Y} in degrees. This function can
1741 be used to transform from Cartesian into polar coordinates and
1742 allows to determine the angle in the correct quadrant.
1744 @item @emph{Standard}:
1750 @item @emph{Syntax}:
1751 @code{RESULT = ATAN2D(Y, X)}
1753 @item @emph{Arguments}:
1754 @multitable @columnfractions .15 .70
1755 @item @var{Y} @tab The type shall be @code{REAL}.
1756 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1757 If @var{Y} is zero, then @var{X} must be nonzero.
1760 @item @emph{Return value}:
1761 The return value has the same type and kind type parameter as @var{Y}. It
1762 is the principal value of the complex number @math{X + i Y}. If @var{X}
1763 is nonzero, then it lies in the range @math{-180 \le \atan (x) \leq 180}.
1764 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1765 the return value is zero if @var{X} is strictly positive, @math{180} if
1766 @var{X} is negative and @var{Y} is positive zero (or the processor does
1767 not handle signed zeros), and @math{-180} if @var{X} is negative and
1768 @var{Y} is negative zero. Finally, if @var{X} is zero, then the
1769 magnitude of the result is @math{90}.
1771 @item @emph{Example}:
1774 real(4) :: x = 1.e0_4, y = 0.5e0_4
1776 end program test_atan2d
1779 @item @emph{Specific names}:
1780 @multitable @columnfractions .23 .23 .20 .30
1781 @headitem Name @tab Argument @tab Return type @tab Standard
1782 @item @code{ATAN2D(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 2023
1783 @item @code{DATAN2D(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab GNU extension
1786 @item @emph{See also}:
1789 Radians function: @*
1794 @section @code{ATANH} --- Inverse hyperbolic tangent function
1797 @cindex area hyperbolic tangent
1798 @cindex inverse hyperbolic tangent
1799 @cindex hyperbolic function, tangent, inverse
1800 @cindex tangent, hyperbolic, inverse
1803 @item @emph{Description}:
1804 @code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
1806 @item @emph{Standard}:
1807 Fortran 2008 and later
1812 @item @emph{Syntax}:
1813 @code{RESULT = ATANH(X)}
1815 @item @emph{Arguments}:
1816 @multitable @columnfractions .15 .70
1817 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1820 @item @emph{Return value}:
1821 The return value has same type and kind as @var{X}. If @var{X} is
1822 complex, the imaginary part of the result is in radians and lies between
1823 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1825 @item @emph{Example}:
1828 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1829 WRITE (*,*) ATANH(x)
1833 @item @emph{Specific names}:
1834 @multitable @columnfractions .20 .23 .20 .33
1835 @headitem Name @tab Argument @tab Return type @tab Standard
1836 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1839 @item @emph{See also}:
1840 Inverse function: @*
1847 @section @code{ATOMIC_ADD} --- Atomic ADD operation
1849 @cindex Atomic subroutine, add
1852 @item @emph{Description}:
1853 @code{ATOMIC_ADD(ATOM, VALUE)} atomically adds the value of @var{VALUE} to the
1854 variable @var{ATOM}. When @var{STAT} is present and the invocation was
1855 successful, it is assigned the value 0. If it is present and the invocation
1856 has failed, it is assigned a positive value; in particular, for a coindexed
1857 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1858 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1859 failed, the value @code{STAT_FAILED_IMAGE}.
1861 @item @emph{Standard}:
1867 @item @emph{Syntax}:
1868 @code{CALL ATOMIC_ADD (ATOM, VALUE [, STAT])}
1870 @item @emph{Arguments}:
1871 @multitable @columnfractions .15 .70
1872 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1873 type with @code{ATOMIC_INT_KIND} kind.
1874 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1875 is different, the value is converted to the kind of @var{ATOM}.
1876 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1879 @item @emph{Example}:
1883 integer(atomic_int_kind) :: atom[*]
1884 call atomic_add (atom[1], this_image())
1888 @item @emph{See also}:
1889 @ref{ATOMIC_DEFINE}, @*
1890 @ref{ATOMIC_FETCH_ADD}, @*
1891 @ref{ISO_FORTRAN_ENV}, @*
1892 @ref{ATOMIC_AND}, @*
1901 @section @code{ATOMIC_AND} --- Atomic bitwise AND operation
1903 @cindex Atomic subroutine, AND
1906 @item @emph{Description}:
1907 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
1908 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
1909 and the invocation was successful, it is assigned the value 0. If it is present
1910 and the invocation has failed, it is assigned a positive value; in particular,
1911 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
1912 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
1913 image has failed, the value @code{STAT_FAILED_IMAGE}.
1915 @item @emph{Standard}:
1921 @item @emph{Syntax}:
1922 @code{CALL ATOMIC_AND (ATOM, VALUE [, STAT])}
1924 @item @emph{Arguments}:
1925 @multitable @columnfractions .15 .70
1926 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1927 type with @code{ATOMIC_INT_KIND} kind.
1928 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1929 is different, the value is converted to the kind of @var{ATOM}.
1930 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1933 @item @emph{Example}:
1937 integer(atomic_int_kind) :: atom[*]
1938 call atomic_and (atom[1], int(b'10100011101'))
1942 @item @emph{See also}:
1943 @ref{ATOMIC_DEFINE}, @*
1944 @ref{ATOMIC_FETCH_AND}, @*
1945 @ref{ISO_FORTRAN_ENV}, @*
1946 @ref{ATOMIC_ADD}, @*
1954 @section @code{ATOMIC_CAS} --- Atomic compare and swap
1955 @fnindex ATOMIC_DEFINE
1956 @cindex Atomic subroutine, compare and swap
1959 @item @emph{Description}:
1960 @code{ATOMIC_CAS} compares the variable @var{ATOM} with the value of
1961 @var{COMPARE}; if the value is the same, @var{ATOM} is set to the value
1962 of @var{NEW}. Additionally, @var{OLD} is set to the value of @var{ATOM}
1963 that was used for the comparison. When @var{STAT} is present and the invocation
1964 was successful, it is assigned the value 0. If it is present and the invocation
1965 has failed, it is assigned a positive value; in particular, for a coindexed
1966 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1967 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1968 failed, the value @code{STAT_FAILED_IMAGE}.
1970 @item @emph{Standard}:
1976 @item @emph{Syntax}:
1977 @code{CALL ATOMIC_CAS (ATOM, OLD, COMPARE, NEW [, STAT])}
1979 @item @emph{Arguments}:
1980 @multitable @columnfractions .15 .70
1981 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
1982 type with @code{ATOMIC_INT_KIND} kind or logical type with
1983 @code{ATOMIC_LOGICAL_KIND} kind.
1984 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1985 @item @var{COMPARE} @tab Scalar variable of the same type and kind as
1987 @item @var{NEW} @tab Scalar variable of the same type as @var{ATOM}. If kind
1988 is different, the value is converted to the kind of @var{ATOM}.
1989 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1992 @item @emph{Example}:
1996 logical(atomic_logical_kind) :: atom[*], prev
1997 call atomic_cas (atom[1], prev, .false., .true.))
2001 @item @emph{See also}:
2002 @ref{ATOMIC_DEFINE}, @*
2003 @ref{ATOMIC_REF}, @*
2004 @ref{ISO_FORTRAN_ENV}
2010 @section @code{ATOMIC_DEFINE} --- Setting a variable atomically
2011 @fnindex ATOMIC_DEFINE
2012 @cindex Atomic subroutine, define
2015 @item @emph{Description}:
2016 @code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value
2017 @var{VALUE} atomically. When @var{STAT} is present and the invocation was
2018 successful, it is assigned the value 0. If it is present and the invocation
2019 has failed, it is assigned a positive value; in particular, for a coindexed
2020 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2021 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2022 failed, the value @code{STAT_FAILED_IMAGE}.
2024 @item @emph{Standard}:
2025 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
2030 @item @emph{Syntax}:
2031 @code{CALL ATOMIC_DEFINE (ATOM, VALUE [, STAT])}
2033 @item @emph{Arguments}:
2034 @multitable @columnfractions .15 .70
2035 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
2036 type with @code{ATOMIC_INT_KIND} kind or logical type with
2037 @code{ATOMIC_LOGICAL_KIND} kind.
2039 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2040 is different, the value is converted to the kind of @var{ATOM}.
2041 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2044 @item @emph{Example}:
2048 integer(atomic_int_kind) :: atom[*]
2049 call atomic_define (atom[1], this_image())
2053 @item @emph{See also}:
2054 @ref{ATOMIC_REF}, @*
2055 @ref{ATOMIC_CAS}, @*
2056 @ref{ISO_FORTRAN_ENV}, @*
2057 @ref{ATOMIC_ADD}, @*
2058 @ref{ATOMIC_AND}, @*
2065 @node ATOMIC_FETCH_ADD
2066 @section @code{ATOMIC_FETCH_ADD} --- Atomic ADD operation with prior fetch
2067 @fnindex ATOMIC_FETCH_ADD
2068 @cindex Atomic subroutine, ADD with fetch
2071 @item @emph{Description}:
2072 @code{ATOMIC_FETCH_ADD(ATOM, VALUE, OLD)} atomically stores the value of
2073 @var{ATOM} in @var{OLD} and adds the value of @var{VALUE} to the
2074 variable @var{ATOM}. When @var{STAT} is present and the invocation was
2075 successful, it is assigned the value 0. If it is present and the invocation
2076 has failed, it is assigned a positive value; in particular, for a coindexed
2077 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2078 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2079 failed, the value @code{STAT_FAILED_IMAGE}.
2081 @item @emph{Standard}:
2087 @item @emph{Syntax}:
2088 @code{CALL ATOMIC_FETCH_ADD (ATOM, VALUE, old [, STAT])}
2090 @item @emph{Arguments}:
2091 @multitable @columnfractions .15 .70
2092 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2093 type with @code{ATOMIC_INT_KIND} kind.
2094 @code{ATOMIC_LOGICAL_KIND} kind.
2096 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2097 is different, the value is converted to the kind of @var{ATOM}.
2098 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2099 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2102 @item @emph{Example}:
2106 integer(atomic_int_kind) :: atom[*], old
2107 call atomic_add (atom[1], this_image(), old)
2111 @item @emph{See also}:
2112 @ref{ATOMIC_DEFINE}, @*
2113 @ref{ATOMIC_ADD}, @*
2114 @ref{ISO_FORTRAN_ENV}, @*
2115 @ref{ATOMIC_FETCH_AND}, @*
2116 @ref{ATOMIC_FETCH_OR}, @*
2117 @ref{ATOMIC_FETCH_XOR}
2122 @node ATOMIC_FETCH_AND
2123 @section @code{ATOMIC_FETCH_AND} --- Atomic bitwise AND operation with prior fetch
2124 @fnindex ATOMIC_FETCH_AND
2125 @cindex Atomic subroutine, AND with fetch
2128 @item @emph{Description}:
2129 @code{ATOMIC_AND(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2130 @var{OLD} and defines @var{ATOM} with the bitwise AND between the values of
2131 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
2132 successful, it is assigned the value 0. If it is present and the invocation has
2133 failed, it is assigned a positive value; in particular, for a coindexed
2134 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2135 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2136 failed, the value @code{STAT_FAILED_IMAGE}.
2138 @item @emph{Standard}:
2144 @item @emph{Syntax}:
2145 @code{CALL ATOMIC_FETCH_AND (ATOM, VALUE, OLD [, STAT])}
2147 @item @emph{Arguments}:
2148 @multitable @columnfractions .15 .70
2149 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2150 type with @code{ATOMIC_INT_KIND} kind.
2151 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2152 is different, the value is converted to the kind of @var{ATOM}.
2153 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2154 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2157 @item @emph{Example}:
2161 integer(atomic_int_kind) :: atom[*], old
2162 call atomic_fetch_and (atom[1], int(b'10100011101'), old)
2166 @item @emph{See also}:
2167 @ref{ATOMIC_DEFINE}, @*
2168 @ref{ATOMIC_AND}, @*
2169 @ref{ISO_FORTRAN_ENV}, @*
2170 @ref{ATOMIC_FETCH_ADD}, @*
2171 @ref{ATOMIC_FETCH_OR}, @*
2172 @ref{ATOMIC_FETCH_XOR}
2177 @node ATOMIC_FETCH_OR
2178 @section @code{ATOMIC_FETCH_OR} --- Atomic bitwise OR operation with prior fetch
2179 @fnindex ATOMIC_FETCH_OR
2180 @cindex Atomic subroutine, OR with fetch
2183 @item @emph{Description}:
2184 @code{ATOMIC_OR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2185 @var{OLD} and defines @var{ATOM} with the bitwise OR between the values of
2186 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
2187 successful, it is assigned the value 0. If it is present and the invocation has
2188 failed, it is assigned a positive value; in particular, for a coindexed
2189 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2190 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2191 failed, the value @code{STAT_FAILED_IMAGE}.
2193 @item @emph{Standard}:
2199 @item @emph{Syntax}:
2200 @code{CALL ATOMIC_FETCH_OR (ATOM, VALUE, OLD [, STAT])}
2202 @item @emph{Arguments}:
2203 @multitable @columnfractions .15 .70
2204 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2205 type with @code{ATOMIC_INT_KIND} kind.
2206 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2207 is different, the value is converted to the kind of @var{ATOM}.
2208 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2209 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2212 @item @emph{Example}:
2216 integer(atomic_int_kind) :: atom[*], old
2217 call atomic_fetch_or (atom[1], int(b'10100011101'), old)
2221 @item @emph{See also}:
2222 @ref{ATOMIC_DEFINE}, @*
2224 @ref{ISO_FORTRAN_ENV}, @*
2225 @ref{ATOMIC_FETCH_ADD}, @*
2226 @ref{ATOMIC_FETCH_AND}, @*
2227 @ref{ATOMIC_FETCH_XOR}
2232 @node ATOMIC_FETCH_XOR
2233 @section @code{ATOMIC_FETCH_XOR} --- Atomic bitwise XOR operation with prior fetch
2234 @fnindex ATOMIC_FETCH_XOR
2235 @cindex Atomic subroutine, XOR with fetch
2238 @item @emph{Description}:
2239 @code{ATOMIC_XOR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2240 @var{OLD} and defines @var{ATOM} with the bitwise XOR between the values of
2241 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
2242 successful, it is assigned the value 0. If it is present and the invocation has
2243 failed, it is assigned a positive value; in particular, for a coindexed
2244 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2245 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2246 failed, the value @code{STAT_FAILED_IMAGE}.
2248 @item @emph{Standard}:
2254 @item @emph{Syntax}:
2255 @code{CALL ATOMIC_FETCH_XOR (ATOM, VALUE, OLD [, STAT])}
2257 @item @emph{Arguments}:
2258 @multitable @columnfractions .15 .70
2259 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2260 type with @code{ATOMIC_INT_KIND} kind.
2261 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2262 is different, the value is converted to the kind of @var{ATOM}.
2263 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2264 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2267 @item @emph{Example}:
2271 integer(atomic_int_kind) :: atom[*], old
2272 call atomic_fetch_xor (atom[1], int(b'10100011101'), old)
2276 @item @emph{See also}:
2277 @ref{ATOMIC_DEFINE}, @*
2278 @ref{ATOMIC_XOR}, @*
2279 @ref{ISO_FORTRAN_ENV}, @*
2280 @ref{ATOMIC_FETCH_ADD}, @*
2281 @ref{ATOMIC_FETCH_AND}, @*
2282 @ref{ATOMIC_FETCH_OR}
2288 @section @code{ATOMIC_OR} --- Atomic bitwise OR operation
2290 @cindex Atomic subroutine, OR
2293 @item @emph{Description}:
2294 @code{ATOMIC_OR(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
2295 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
2296 and the invocation was successful, it is assigned the value 0. If it is present
2297 and the invocation has failed, it is assigned a positive value; in particular,
2298 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
2299 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
2300 image has failed, the value @code{STAT_FAILED_IMAGE}.
2302 @item @emph{Standard}:
2308 @item @emph{Syntax}:
2309 @code{CALL ATOMIC_OR (ATOM, VALUE [, STAT])}
2311 @item @emph{Arguments}:
2312 @multitable @columnfractions .15 .70
2313 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2314 type with @code{ATOMIC_INT_KIND} kind.
2315 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2316 is different, the value is converted to the kind of @var{ATOM}.
2317 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2320 @item @emph{Example}:
2324 integer(atomic_int_kind) :: atom[*]
2325 call atomic_or (atom[1], int(b'10100011101'))
2329 @item @emph{See also}:
2330 @ref{ATOMIC_DEFINE}, @*
2331 @ref{ATOMIC_FETCH_OR}, @*
2332 @ref{ISO_FORTRAN_ENV}, @*
2333 @ref{ATOMIC_ADD}, @*
2341 @section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically
2343 @cindex Atomic subroutine, reference
2346 @item @emph{Description}:
2347 @code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the
2348 variable @var{ATOM} to @var{VALUE}. When @var{STAT} is present and the
2349 invocation was successful, it is assigned the value 0. If it is present and the
2350 invocation has failed, it is assigned a positive value; in particular, for a
2351 coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value
2352 of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image
2353 has failed, the value @code{STAT_FAILED_IMAGE}.
2356 @item @emph{Standard}:
2357 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
2362 @item @emph{Syntax}:
2363 @code{CALL ATOMIC_REF(VALUE, ATOM [, STAT])}
2365 @item @emph{Arguments}:
2366 @multitable @columnfractions .15 .70
2367 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2368 is different, the value is converted to the kind of @var{ATOM}.
2369 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
2370 type with @code{ATOMIC_INT_KIND} kind or logical type with
2371 @code{ATOMIC_LOGICAL_KIND} kind.
2372 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2375 @item @emph{Example}:
2379 logical(atomic_logical_kind) :: atom[*]
2381 call atomic_ref (atom, .false.)
2383 call atomic_ref (atom, val)
2390 @item @emph{See also}:
2391 @ref{ATOMIC_DEFINE}, @*
2392 @ref{ATOMIC_CAS}, @*
2393 @ref{ISO_FORTRAN_ENV}, @*
2394 @ref{ATOMIC_FETCH_ADD}, @*
2395 @ref{ATOMIC_FETCH_AND}, @*
2396 @ref{ATOMIC_FETCH_OR}, @*
2397 @ref{ATOMIC_FETCH_XOR}
2402 @section @code{ATOMIC_XOR} --- Atomic bitwise OR operation
2404 @cindex Atomic subroutine, XOR
2407 @item @emph{Description}:
2408 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
2409 XOR between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
2410 and the invocation was successful, it is assigned the value 0. If it is present
2411 and the invocation has failed, it is assigned a positive value; in particular,
2412 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
2413 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
2414 image has failed, the value @code{STAT_FAILED_IMAGE}.
2416 @item @emph{Standard}:
2422 @item @emph{Syntax}:
2423 @code{CALL ATOMIC_XOR (ATOM, VALUE [, STAT])}
2425 @item @emph{Arguments}:
2426 @multitable @columnfractions .15 .70
2427 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2428 type with @code{ATOMIC_INT_KIND} kind.
2429 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2430 is different, the value is converted to the kind of @var{ATOM}.
2431 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2434 @item @emph{Example}:
2438 integer(atomic_int_kind) :: atom[*]
2439 call atomic_xor (atom[1], int(b'10100011101'))
2443 @item @emph{See also}:
2444 @ref{ATOMIC_DEFINE}, @*
2445 @ref{ATOMIC_FETCH_XOR}, @*
2446 @ref{ISO_FORTRAN_ENV}, @*
2447 @ref{ATOMIC_ADD}, @*
2454 @section @code{BACKTRACE} --- Show a backtrace
2459 @item @emph{Description}:
2460 @code{BACKTRACE} shows a backtrace at an arbitrary place in user code. Program
2461 execution continues normally afterwards. The backtrace information is printed
2462 to the unit corresponding to @code{ERROR_UNIT} in @code{ISO_FORTRAN_ENV}.
2464 @item @emph{Standard}:
2470 @item @emph{Syntax}:
2471 @code{CALL BACKTRACE}
2473 @item @emph{Arguments}:
2476 @item @emph{See also}:
2483 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
2487 @cindex Bessel function, first kind
2490 @item @emph{Description}:
2491 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
2492 order 0 of @var{X}. This function is available under the name
2493 @code{BESJ0} as a GNU extension.
2495 @item @emph{Standard}:
2496 Fortran 2008 and later
2501 @item @emph{Syntax}:
2502 @code{RESULT = BESSEL_J0(X)}
2504 @item @emph{Arguments}:
2505 @multitable @columnfractions .15 .70
2506 @item @var{X} @tab The type shall be @code{REAL}.
2509 @item @emph{Return value}:
2510 The return value is of type @code{REAL} and lies in the
2511 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
2514 @item @emph{Example}:
2517 real(8) :: x = 0.0_8
2519 end program test_besj0
2522 @item @emph{Specific names}:
2523 @multitable @columnfractions .21 .22 .20 .33
2524 @headitem Name @tab Argument @tab Return type @tab Standard
2525 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2532 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
2536 @cindex Bessel function, first kind
2539 @item @emph{Description}:
2540 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
2541 order 1 of @var{X}. This function is available under the name
2542 @code{BESJ1} as a GNU extension.
2544 @item @emph{Standard}:
2550 @item @emph{Syntax}:
2551 @code{RESULT = BESSEL_J1(X)}
2553 @item @emph{Arguments}:
2554 @multitable @columnfractions .15 .70
2555 @item @var{X} @tab The type shall be @code{REAL}.
2558 @item @emph{Return value}:
2559 The return value is of type @code{REAL} and lies in the
2560 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
2563 @item @emph{Example}:
2566 real(8) :: x = 1.0_8
2568 end program test_besj1
2571 @item @emph{Specific names}:
2572 @multitable @columnfractions .20 .23 .20 .33
2573 @headitem Name @tab Argument @tab Return type @tab Standard
2574 @item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2581 @section @code{BESSEL_JN} --- Bessel function of the first kind
2585 @cindex Bessel function, first kind
2588 @item @emph{Description}:
2589 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
2590 order @var{N} of @var{X}. This function is available under the name
2591 @code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays,
2592 their ranks and shapes shall conform.
2594 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
2595 of the first kind of the orders @var{N1} to @var{N2}.
2597 @item @emph{Standard}:
2598 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2601 Elemental function, except for the transformational function
2602 @code{BESSEL_JN(N1, N2, X)}
2604 @item @emph{Syntax}:
2605 @multitable @columnfractions .80
2606 @item @code{RESULT = BESSEL_JN(N, X)}
2607 @item @code{RESULT = BESSEL_JN(N1, N2, X)}
2610 @item @emph{Arguments}:
2611 @multitable @columnfractions .15 .70
2612 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
2613 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2614 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2615 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2616 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
2619 @item @emph{Return value}:
2620 The return value is a scalar of type @code{REAL}. It has the same
2624 The transformational function uses a recurrence algorithm which might,
2625 for some values of @var{X}, lead to different results than calls to
2626 the elemental function.
2628 @item @emph{Example}:
2631 real(8) :: x = 1.0_8
2633 end program test_besjn
2636 @item @emph{Specific names}:
2637 @multitable @columnfractions .22 .22 .20 .32
2638 @headitem Name @tab Argument @tab Return type @tab Standard
2639 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2640 @item @tab @code{REAL(8) X} @tab @tab
2647 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
2651 @cindex Bessel function, second kind
2654 @item @emph{Description}:
2655 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
2656 order 0 of @var{X}. This function is available under the name
2657 @code{BESY0} as a GNU extension.
2659 @item @emph{Standard}:
2660 Fortran 2008 and later
2665 @item @emph{Syntax}:
2666 @code{RESULT = BESSEL_Y0(X)}
2668 @item @emph{Arguments}:
2669 @multitable @columnfractions .15 .70
2670 @item @var{X} @tab The type shall be @code{REAL}.
2673 @item @emph{Return value}:
2674 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2676 @item @emph{Example}:
2679 real(8) :: x = 0.0_8
2681 end program test_besy0
2684 @item @emph{Specific names}:
2685 @multitable @columnfractions .20 .23 .20 .33
2686 @headitem Name @tab Argument @tab Return type @tab Standard
2687 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2694 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
2698 @cindex Bessel function, second kind
2701 @item @emph{Description}:
2702 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
2703 order 1 of @var{X}. This function is available under the name
2704 @code{BESY1} as a GNU extension.
2706 @item @emph{Standard}:
2707 Fortran 2008 and later
2712 @item @emph{Syntax}:
2713 @code{RESULT = BESSEL_Y1(X)}
2715 @item @emph{Arguments}:
2716 @multitable @columnfractions .15 .70
2717 @item @var{X} @tab The type shall be @code{REAL}.
2720 @item @emph{Return value}:
2721 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2723 @item @emph{Example}:
2726 real(8) :: x = 1.0_8
2728 end program test_besy1
2731 @item @emph{Specific names}:
2732 @multitable @columnfractions .20 .23 .20 .33
2733 @headitem Name @tab Argument @tab Return type @tab Standard
2734 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2741 @section @code{BESSEL_YN} --- Bessel function of the second kind
2745 @cindex Bessel function, second kind
2748 @item @emph{Description}:
2749 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
2750 order @var{N} of @var{X}. This function is available under the name
2751 @code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays,
2752 their ranks and shapes shall conform.
2754 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
2755 of the first kind of the orders @var{N1} to @var{N2}.
2757 @item @emph{Standard}:
2758 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2761 Elemental function, except for the transformational function
2762 @code{BESSEL_YN(N1, N2, X)}
2764 @item @emph{Syntax}:
2765 @multitable @columnfractions .80
2766 @item @code{RESULT = BESSEL_YN(N, X)}
2767 @item @code{RESULT = BESSEL_YN(N1, N2, X)}
2770 @item @emph{Arguments}:
2771 @multitable @columnfractions .15 .70
2772 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} .
2773 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2774 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2775 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2776 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
2779 @item @emph{Return value}:
2780 The return value is a scalar of type @code{REAL}. It has the same
2784 The transformational function uses a recurrence algorithm which might,
2785 for some values of @var{X}, lead to different results than calls to
2786 the elemental function.
2788 @item @emph{Example}:
2791 real(8) :: x = 1.0_8
2793 end program test_besyn
2796 @item @emph{Specific names}:
2797 @multitable @columnfractions .20 .23 .20 .33
2798 @headitem Name @tab Argument @tab Return type @tab Standard
2799 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2800 @item @tab @code{REAL(8) X} @tab @tab
2807 @section @code{BGE} --- Bitwise greater than or equal to
2809 @cindex bitwise comparison
2812 @item @emph{Description}:
2813 Determines whether an integral is a bitwise greater than or equal to
2816 @item @emph{Standard}:
2817 Fortran 2008 and later
2822 @item @emph{Syntax}:
2823 @code{RESULT = BGE(I, J)}
2825 @item @emph{Arguments}:
2826 @multitable @columnfractions .15 .70
2827 @item @var{I} @tab Shall be of @code{INTEGER} type.
2828 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2832 @item @emph{Return value}:
2833 The return value is of type @code{LOGICAL} and of the default kind.
2835 @item @emph{See also}:
2844 @section @code{BGT} --- Bitwise greater than
2846 @cindex bitwise comparison
2849 @item @emph{Description}:
2850 Determines whether an integral is a bitwise greater than another.
2852 @item @emph{Standard}:
2853 Fortran 2008 and later
2858 @item @emph{Syntax}:
2859 @code{RESULT = BGT(I, J)}
2861 @item @emph{Arguments}:
2862 @multitable @columnfractions .15 .70
2863 @item @var{I} @tab Shall be of @code{INTEGER} type.
2864 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2868 @item @emph{Return value}:
2869 The return value is of type @code{LOGICAL} and of the default kind.
2871 @item @emph{See also}:
2880 @section @code{BIT_SIZE} --- Bit size inquiry function
2882 @cindex bits, number of
2883 @cindex size of a variable, in bits
2886 @item @emph{Description}:
2887 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
2888 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
2889 independent of the actual value of @var{I}.
2891 @item @emph{Standard}:
2892 Fortran 90 and later
2897 @item @emph{Syntax}:
2898 @code{RESULT = BIT_SIZE(I)}
2900 @item @emph{Arguments}:
2901 @multitable @columnfractions .15 .70
2902 @item @var{I} @tab The type shall be @code{INTEGER}.
2905 @item @emph{Return value}:
2906 The return value is of type @code{INTEGER}
2908 @item @emph{Example}:
2910 program test_bit_size
2915 end program test_bit_size
2922 @section @code{BLE} --- Bitwise less than or equal to
2924 @cindex bitwise comparison
2927 @item @emph{Description}:
2928 Determines whether an integral is a bitwise less than or equal to
2931 @item @emph{Standard}:
2932 Fortran 2008 and later
2937 @item @emph{Syntax}:
2938 @code{RESULT = BLE(I, J)}
2940 @item @emph{Arguments}:
2941 @multitable @columnfractions .15 .70
2942 @item @var{I} @tab Shall be of @code{INTEGER} type.
2943 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2947 @item @emph{Return value}:
2948 The return value is of type @code{LOGICAL} and of the default kind.
2950 @item @emph{See also}:
2959 @section @code{BLT} --- Bitwise less than
2961 @cindex bitwise comparison
2964 @item @emph{Description}:
2965 Determines whether an integral is a bitwise less than another.
2967 @item @emph{Standard}:
2968 Fortran 2008 and later
2973 @item @emph{Syntax}:
2974 @code{RESULT = BLT(I, J)}
2976 @item @emph{Arguments}:
2977 @multitable @columnfractions .15 .70
2978 @item @var{I} @tab Shall be of @code{INTEGER} type.
2979 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2983 @item @emph{Return value}:
2984 The return value is of type @code{LOGICAL} and of the default kind.
2986 @item @emph{See also}:
2995 @section @code{BTEST} --- Bit test function
3001 @cindex bits, testing
3004 @item @emph{Description}:
3005 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
3006 in @var{I} is set. The counting of the bits starts at 0.
3008 @item @emph{Standard}:
3009 Fortran 90 and later, has overloads that are GNU extensions
3014 @item @emph{Syntax}:
3015 @code{RESULT = BTEST(I, POS)}
3017 @item @emph{Arguments}:
3018 @multitable @columnfractions .15 .70
3019 @item @var{I} @tab The type shall be @code{INTEGER}.
3020 @item @var{POS} @tab The type shall be @code{INTEGER}.
3023 @item @emph{Return value}:
3024 The return value is of type @code{LOGICAL}
3026 @item @emph{Example}:
3029 integer :: i = 32768 + 1024 + 64
3033 bool = btest(i, pos)
3036 end program test_btest
3039 @item @emph{Specific names}:
3040 @multitable @columnfractions .21 .28 .18 .30
3041 @headitem Name @tab Argument @tab Return type @tab Standard
3042 @item @code{BTEST(I,POS)} @tab @code{INTEGER I,POS} @tab @code{LOGICAL} @tab Fortran 95 and later
3043 @item @code{BBTEST(I,POS)} @tab @code{INTEGER(1) I,POS} @tab @code{LOGICAL(1)} @tab GNU extension
3044 @item @code{BITEST(I,POS)} @tab @code{INTEGER(2) I,POS} @tab @code{LOGICAL(2)} @tab GNU extension
3045 @item @code{BJTEST(I,POS)} @tab @code{INTEGER(4) I,POS} @tab @code{LOGICAL(4)} @tab GNU extension
3046 @item @code{BKTEST(I,POS)} @tab @code{INTEGER(8) I,POS} @tab @code{LOGICAL(8)} @tab GNU extension
3051 @section @code{C_ASSOCIATED} --- Status of a C pointer
3052 @fnindex C_ASSOCIATED
3053 @cindex association status, C pointer
3054 @cindex pointer, C association status
3057 @item @emph{Description}:
3058 @code{C_ASSOCIATED(c_ptr_1[, c_ptr_2])} determines the status of the C pointer
3059 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
3061 @item @emph{Standard}:
3062 Fortran 2003 and later
3067 @item @emph{Syntax}:
3068 @code{RESULT = C_ASSOCIATED(c_ptr_1[, c_ptr_2])}
3070 @item @emph{Arguments}:
3071 @multitable @columnfractions .15 .70
3072 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
3073 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
3076 @item @emph{Return value}:
3077 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
3078 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
3079 point to different addresses.
3081 @item @emph{Example}:
3083 subroutine association_test(a,b)
3084 use iso_c_binding, only: c_associated, c_loc, c_ptr
3088 if(c_associated(b, c_loc(a))) &
3089 stop 'b and a do not point to same target'
3090 end subroutine association_test
3093 @item @emph{See also}:
3100 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
3101 @fnindex C_F_POINTER
3102 @cindex pointer, convert C to Fortran
3105 @item @emph{Description}:
3106 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} assigns the target of the C pointer
3107 @var{CPTR} to the Fortran pointer @var{FPTR} and specifies its shape.
3109 @item @emph{Standard}:
3110 Fortran 2003 and later
3115 @item @emph{Syntax}:
3116 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
3118 @item @emph{Arguments}:
3119 @multitable @columnfractions .15 .70
3120 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
3122 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
3124 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
3125 with @code{INTENT(IN)}. It shall be present
3126 if and only if @var{fptr} is an array. The size
3127 must be equal to the rank of @var{fptr}.
3130 @item @emph{Example}:
3136 subroutine my_routine(p) bind(c,name='myC_func')
3138 type(c_ptr), intent(out) :: p
3142 real,pointer :: a(:)
3143 call my_routine(cptr)
3144 call c_f_pointer(cptr, a, [12])
3148 @item @emph{See also}:
3150 @ref{C_F_PROCPOINTER}
3154 @node C_F_PROCPOINTER
3155 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
3156 @fnindex C_F_PROCPOINTER
3157 @cindex pointer, C address of pointers
3160 @item @emph{Description}:
3161 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
3162 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
3164 @item @emph{Standard}:
3165 Fortran 2003 and later
3170 @item @emph{Syntax}:
3171 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
3173 @item @emph{Arguments}:
3174 @multitable @columnfractions .15 .70
3175 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
3177 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
3181 @item @emph{Example}:
3189 real(c_float), intent(in) :: a
3190 real(c_float) :: func
3194 function getIterFunc() bind(c,name="getIterFunc")
3196 type(c_funptr) :: getIterFunc
3199 type(c_funptr) :: cfunptr
3200 procedure(func), pointer :: myFunc
3201 cfunptr = getIterFunc()
3202 call c_f_procpointer(cfunptr, myFunc)
3206 @item @emph{See also}:
3213 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
3215 @cindex pointer, C address of procedures
3218 @item @emph{Description}:
3219 @code{C_FUNLOC(x)} determines the C address of the argument.
3221 @item @emph{Standard}:
3222 Fortran 2003 and later
3227 @item @emph{Syntax}:
3228 @code{RESULT = C_FUNLOC(x)}
3230 @item @emph{Arguments}:
3231 @multitable @columnfractions .15 .70
3232 @item @var{x} @tab Interoperable function or pointer to such function.
3235 @item @emph{Return value}:
3236 The return value is of type @code{C_FUNPTR} and contains the C address
3239 @item @emph{Example}:
3245 subroutine sub(a) bind(c)
3255 subroutine my_routine(p) bind(c,name='myC_func')
3257 type(c_funptr), intent(in) :: p
3260 call my_routine(c_funloc(sub))
3264 @item @emph{See also}:
3265 @ref{C_ASSOCIATED}, @*
3267 @ref{C_F_POINTER}, @*
3268 @ref{C_F_PROCPOINTER}
3273 @section @code{C_LOC} --- Obtain the C address of an object
3275 @cindex procedure pointer, convert C to Fortran
3278 @item @emph{Description}:
3279 @code{C_LOC(X)} determines the C address of the argument.
3281 @item @emph{Standard}:
3282 Fortran 2003 and later
3287 @item @emph{Syntax}:
3288 @code{RESULT = C_LOC(X)}
3290 @item @emph{Arguments}:
3291 @multitable @columnfractions .10 .75
3292 @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.
3296 @item @emph{Return value}:
3297 The return value is of type @code{C_PTR} and contains the C address
3300 @item @emph{Example}:
3302 subroutine association_test(a,b)
3303 use iso_c_binding, only: c_associated, c_loc, c_ptr
3307 if(c_associated(b, c_loc(a))) &
3308 stop 'b and a do not point to same target'
3309 end subroutine association_test
3312 @item @emph{See also}:
3313 @ref{C_ASSOCIATED}, @*
3315 @ref{C_F_POINTER}, @*
3316 @ref{C_F_PROCPOINTER}
3321 @section @code{C_SIZEOF} --- Size in bytes of an expression
3323 @cindex expression size
3324 @cindex size of an expression
3327 @item @emph{Description}:
3328 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
3329 expression @code{X} occupies.
3331 @item @emph{Standard}:
3335 Inquiry function of the module @code{ISO_C_BINDING}
3337 @item @emph{Syntax}:
3338 @code{N = C_SIZEOF(X)}
3340 @item @emph{Arguments}:
3341 @multitable @columnfractions .15 .70
3342 @item @var{X} @tab The argument shall be an interoperable data entity.
3345 @item @emph{Return value}:
3346 The return value is of type integer and of the system-dependent kind
3347 @code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the
3348 number of bytes occupied by the argument. If the argument has the
3349 @code{POINTER} attribute, the number of bytes of the storage area pointed
3350 to is returned. If the argument is of a derived type with @code{POINTER}
3351 or @code{ALLOCATABLE} components, the return value does not account for
3352 the sizes of the data pointed to by these components.
3354 @item @emph{Example}:
3358 real(c_float) :: r, s(5)
3359 print *, (c_sizeof(s)/c_sizeof(r) == 5)
3362 The example will print @code{T} unless you are using a platform
3363 where default @code{REAL} variables are unusually padded.
3365 @item @emph{See also}:
3372 @section @code{CEILING} --- Integer ceiling function
3375 @cindex rounding, ceiling
3378 @item @emph{Description}:
3379 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
3381 @item @emph{Standard}:
3382 Fortran 95 and later
3387 @item @emph{Syntax}:
3388 @code{RESULT = CEILING(A [, KIND])}
3390 @item @emph{Arguments}:
3391 @multitable @columnfractions .15 .70
3392 @item @var{A} @tab The type shall be @code{REAL}.
3393 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
3394 expression indicating the kind parameter of the result.
3397 @item @emph{Return value}:
3398 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
3399 and a default-kind @code{INTEGER} otherwise.
3401 @item @emph{Example}:
3403 program test_ceiling
3406 print *, ceiling(x) ! returns 64
3407 print *, ceiling(y) ! returns -63
3408 end program test_ceiling
3411 @item @emph{See also}:
3419 @section @code{CHAR} --- Character conversion function
3421 @cindex conversion, to character
3424 @item @emph{Description}:
3425 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
3427 @item @emph{Standard}:
3428 Fortran 77 and later
3433 @item @emph{Syntax}:
3434 @code{RESULT = CHAR(I [, KIND])}
3436 @item @emph{Arguments}:
3437 @multitable @columnfractions .15 .70
3438 @item @var{I} @tab The type shall be @code{INTEGER}.
3439 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
3440 expression indicating the kind parameter of the result.
3443 @item @emph{Return value}:
3444 The return value is of type @code{CHARACTER(1)}
3446 @item @emph{Example}:
3452 print *, i, c ! returns 'J'
3453 end program test_char
3456 @item @emph{Specific names}:
3457 @multitable @columnfractions .19 .19 .25 .33
3458 @headitem Name @tab Argument @tab Return type @tab Standard
3459 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab Fortran 77 and later
3463 See @ref{ICHAR} for a discussion of converting between numerical values
3464 and formatted string representations.
3466 @item @emph{See also}:
3476 @section @code{CHDIR} --- Change working directory
3478 @cindex system, working directory
3481 @item @emph{Description}:
3482 Change current working directory to a specified path.
3484 This intrinsic is provided in both subroutine and function forms; however,
3485 only one form can be used in any given program unit.
3487 @item @emph{Standard}:
3491 Subroutine, function
3493 @item @emph{Syntax}:
3494 @multitable @columnfractions .80
3495 @item @code{CALL CHDIR(NAME [, STATUS])}
3496 @item @code{STATUS = CHDIR(NAME)}
3499 @item @emph{Arguments}:
3500 @multitable @columnfractions .15 .70
3501 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
3502 kind and shall specify a valid path within the file system.
3503 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
3504 kind. Returns 0 on success, and a system specific and nonzero error code
3508 @item @emph{Example}:
3511 CHARACTER(len=255) :: path
3513 WRITE(*,*) TRIM(path)
3516 WRITE(*,*) TRIM(path)
3520 @item @emph{See also}:
3527 @section @code{CHMOD} --- Change access permissions of files
3529 @cindex file system, change access mode
3532 @item @emph{Description}:
3533 @code{CHMOD} changes the permissions of a file.
3535 This intrinsic is provided in both subroutine and function forms; however,
3536 only one form can be used in any given program unit.
3538 @item @emph{Standard}:
3542 Subroutine, function
3544 @item @emph{Syntax}:
3545 @multitable @columnfractions .80
3546 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
3547 @item @code{STATUS = CHMOD(NAME, MODE)}
3550 @item @emph{Arguments}:
3551 @multitable @columnfractions .15 .70
3553 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
3554 file name. Trailing blanks are ignored unless the character
3555 @code{achar(0)} is present, then all characters up to and excluding
3556 @code{achar(0)} are used as the file name.
3558 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
3559 file permission. @var{MODE} uses the same syntax as the @code{chmod} utility
3560 as defined by the POSIX standard. The argument shall either be a string of
3561 a nonnegative octal number or a symbolic mode.
3563 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
3564 @code{0} on success and nonzero otherwise.
3567 @item @emph{Return value}:
3568 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
3571 @item @emph{Example}:
3572 @code{CHMOD} as subroutine
3577 call chmod('test.dat','u+x',status)
3578 print *, 'Status: ', status
3579 end program chmod_test
3581 @code{CHMOD} as function:
3586 status = chmod('test.dat','u+x')
3587 print *, 'Status: ', status
3588 end program chmod_test
3596 @section @code{CMPLX} --- Complex conversion function
3598 @cindex complex numbers, conversion to
3599 @cindex conversion, to complex
3602 @item @emph{Description}:
3603 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
3604 the real component. If @var{Y} is present it is converted to the imaginary
3605 component. If @var{Y} is not present then the imaginary component is set to
3606 0.0. If @var{X} is complex then @var{Y} must not be present.
3608 @item @emph{Standard}:
3609 Fortran 77 and later
3614 @item @emph{Syntax}:
3615 @code{RESULT = CMPLX(X [, Y [, KIND]])}
3617 @item @emph{Arguments}:
3618 @multitable @columnfractions .15 .70
3619 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3621 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
3622 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
3623 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
3624 expression indicating the kind parameter of the result.
3627 @item @emph{Return value}:
3628 The return value is of @code{COMPLEX} type, with a kind equal to
3629 @var{KIND} if it is specified. If @var{KIND} is not specified, the
3630 result is of the default @code{COMPLEX} kind, regardless of the kinds of
3631 @var{X} and @var{Y}.
3633 @item @emph{Example}:
3640 print *, z, cmplx(x)
3641 end program test_cmplx
3644 @item @emph{See also}:
3651 @section @code{CO_BROADCAST} --- Copy a value to all images the current set of images
3652 @fnindex CO_BROADCAST
3653 @cindex Collectives, value broadcasting
3656 @item @emph{Description}:
3657 @code{CO_BROADCAST} copies the value of argument @var{A} on the image with
3658 image index @code{SOURCE_IMAGE} to all images in the current team. @var{A}
3659 becomes defined as if by intrinsic assignment. If the execution was
3660 successful and @var{STAT} is present, it is assigned the value zero. If the
3661 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3662 @var{ERRMSG} gets assigned a value describing the occurred error.
3664 @item @emph{Standard}:
3665 Technical Specification (TS) 18508 or later
3668 Collective subroutine
3670 @item @emph{Syntax}:
3671 @code{CALL CO_BROADCAST(A, SOURCE_IMAGE [, STAT, ERRMSG])}
3673 @item @emph{Arguments}:
3674 @multitable @columnfractions .20 .65
3675 @item @var{A} @tab INTENT(INOUT) argument; shall have the same
3676 dynamic type and type parameters on all images of the current team. If it
3677 is an array, it shall have the same shape on all images.
3678 @item @var{SOURCE_IMAGE} @tab a scalar integer expression.
3679 It shall have the same value on all images and refer to an
3680 image of the current team.
3681 @item @var{STAT} @tab (optional) a scalar integer variable
3682 @item @var{ERRMSG} @tab (optional) a scalar character variable
3685 @item @emph{Example}:
3689 if (this_image() == 1) then
3692 call co_broadcast (val, source_image=1)
3693 print *, this_image, ":", val
3697 @item @emph{See also}:
3707 @section @code{CO_MAX} --- Maximal value on the current set of images
3709 @cindex Collectives, maximal value
3712 @item @emph{Description}:
3713 @code{CO_MAX} determines element-wise the maximal value of @var{A} on all
3714 images of the current team. If @var{RESULT_IMAGE} is present, the maximum
3715 values are returned in @var{A} on the specified image only and the value
3716 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3717 not present, the value is returned on all images. If the execution was
3718 successful and @var{STAT} is present, it is assigned the value zero. If the
3719 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3720 @var{ERRMSG} gets assigned a value describing the occurred error.
3722 @item @emph{Standard}:
3723 Technical Specification (TS) 18508 or later
3726 Collective subroutine
3728 @item @emph{Syntax}:
3729 @code{CALL CO_MAX(A [, RESULT_IMAGE, STAT, ERRMSG])}
3731 @item @emph{Arguments}:
3732 @multitable @columnfractions .20 .65
3733 @item @var{A} @tab shall be an integer, real or character variable,
3734 which has the same type and type parameters on all images of the team.
3735 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3736 present, it shall have the same value on all images and refer to an
3737 image of the current team.
3738 @item @var{STAT} @tab (optional) a scalar integer variable
3739 @item @var{ERRMSG} @tab (optional) a scalar character variable
3742 @item @emph{Example}:
3747 call co_max (val, result_image=1)
3748 if (this_image() == 1) then
3749 write(*,*) "Maximal value", val ! prints num_images()
3754 @item @emph{See also}:
3764 @section @code{CO_MIN} --- Minimal value on the current set of images
3766 @cindex Collectives, minimal value
3769 @item @emph{Description}:
3770 @code{CO_MIN} determines element-wise the minimal value of @var{A} on all
3771 images of the current team. If @var{RESULT_IMAGE} is present, the minimal
3772 values are returned in @var{A} on the specified image only and the value
3773 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3774 not present, the value is returned on all images. If the execution was
3775 successful and @var{STAT} is present, it is assigned the value zero. If the
3776 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3777 @var{ERRMSG} gets assigned a value describing the occurred error.
3779 @item @emph{Standard}:
3780 Technical Specification (TS) 18508 or later
3783 Collective subroutine
3785 @item @emph{Syntax}:
3786 @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3788 @item @emph{Arguments}:
3789 @multitable @columnfractions .20 .65
3790 @item @var{A} @tab shall be an integer, real or character variable,
3791 which has the same type and type parameters on all images of the team.
3792 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3793 present, it shall have the same value on all images and refer to an
3794 image of the current team.
3795 @item @var{STAT} @tab (optional) a scalar integer variable
3796 @item @var{ERRMSG} @tab (optional) a scalar character variable
3799 @item @emph{Example}:
3804 call co_min (val, result_image=1)
3805 if (this_image() == 1) then
3806 write(*,*) "Minimal value", val ! prints 1
3811 @item @emph{See also}:
3821 @section @code{CO_REDUCE} --- Reduction of values on the current set of images
3823 @cindex Collectives, generic reduction
3826 @item @emph{Description}:
3827 @code{CO_REDUCE} determines element-wise the reduction of the value of @var{A}
3828 on all images of the current team. The pure function passed as @var{OPERATION}
3829 is used to pairwise reduce the values of @var{A} by passing either the value
3830 of @var{A} of different images or the result values of such a reduction as
3831 argument. If @var{A} is an array, the deduction is done element wise. If
3832 @var{RESULT_IMAGE} is present, the result values are returned in @var{A} on
3833 the specified image only and the value of @var{A} on the other images become
3834 undefined. If @var{RESULT_IMAGE} is not present, the value is returned on all
3835 images. If the execution was successful and @var{STAT} is present, it is
3836 assigned the value zero. If the execution failed, @var{STAT} gets assigned
3837 a nonzero value and, if present, @var{ERRMSG} gets assigned a value describing
3840 @item @emph{Standard}:
3841 Technical Specification (TS) 18508 or later
3844 Collective subroutine
3846 @item @emph{Syntax}:
3847 @code{CALL CO_REDUCE(A, OPERATION, [, RESULT_IMAGE, STAT, ERRMSG])}
3849 @item @emph{Arguments}:
3850 @multitable @columnfractions .20 .65
3851 @item @var{A} @tab is an @code{INTENT(INOUT)} argument and shall be
3852 nonpolymorphic. If it is allocatable, it shall be allocated; if it is a pointer,
3853 it shall be associated. @var{A} shall have the same type and type parameters on
3854 all images of the team; if it is an array, it shall have the same shape on all
3856 @item @var{OPERATION} @tab pure function with two scalar nonallocatable
3857 arguments, which shall be nonpolymorphic and have the same type and type
3858 parameters as @var{A}. The function shall return a nonallocatable scalar of
3859 the same type and type parameters as @var{A}. The function shall be the same on
3860 all images and with regards to the arguments mathematically commutative and
3861 associative. Note that @var{OPERATION} may not be an elemental function, unless
3862 it is an intrisic function.
3863 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3864 present, it shall have the same value on all images and refer to an
3865 image of the current team.
3866 @item @var{STAT} @tab (optional) a scalar integer variable
3867 @item @var{ERRMSG} @tab (optional) a scalar character variable
3870 @item @emph{Example}:
3875 call co_reduce (val, result_image=1, operation=myprod)
3876 if (this_image() == 1) then
3877 write(*,*) "Product value", val ! prints num_images() factorial
3880 pure function myprod(a, b)
3881 integer, value :: a, b
3889 While the rules permit in principle an intrinsic function, none of the
3890 intrinsics in the standard fulfill the criteria of having a specific
3891 function, which takes two arguments of the same type and returning that
3894 @item @emph{See also}:
3904 @section @code{CO_SUM} --- Sum of values on the current set of images
3906 @cindex Collectives, sum of values
3909 @item @emph{Description}:
3910 @code{CO_SUM} sums up the values of each element of @var{A} on all
3911 images of the current team. If @var{RESULT_IMAGE} is present, the summed-up
3912 values are returned in @var{A} on the specified image only and the value
3913 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3914 not present, the value is returned on all images. If the execution was
3915 successful and @var{STAT} is present, it is assigned the value zero. If the
3916 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3917 @var{ERRMSG} gets assigned a value describing the occurred error.
3919 @item @emph{Standard}:
3920 Technical Specification (TS) 18508 or later
3923 Collective subroutine
3925 @item @emph{Syntax}:
3926 @code{CALL CO_SUM(A [, RESULT_IMAGE, STAT, ERRMSG])}
3928 @item @emph{Arguments}:
3929 @multitable @columnfractions .20 .65
3930 @item @var{A} @tab shall be an integer, real or complex variable,
3931 which has the same type and type parameters on all images of the team.
3932 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3933 present, it shall have the same value on all images and refer to an
3934 image of the current team.
3935 @item @var{STAT} @tab (optional) a scalar integer variable
3936 @item @var{ERRMSG} @tab (optional) a scalar character variable
3939 @item @emph{Example}:
3944 call co_sum (val, result_image=1)
3945 if (this_image() == 1) then
3946 write(*,*) "The sum is ", val ! prints (n**2 + n)/2,
3947 ! with n = num_images()
3952 @item @emph{See also}:
3961 @node COMMAND_ARGUMENT_COUNT
3962 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
3963 @fnindex COMMAND_ARGUMENT_COUNT
3964 @cindex command-line arguments
3965 @cindex command-line arguments, number of
3966 @cindex arguments, to program
3969 @item @emph{Description}:
3970 @code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the
3971 command line when the containing program was invoked.
3973 @item @emph{Standard}:
3974 Fortran 2003 and later
3979 @item @emph{Syntax}:
3980 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
3982 @item @emph{Arguments}:
3983 @multitable @columnfractions .15 .70
3987 @item @emph{Return value}:
3988 The return value is an @code{INTEGER} of default kind.
3990 @item @emph{Example}:
3992 program test_command_argument_count
3994 count = command_argument_count()
3996 end program test_command_argument_count
3999 @item @emph{See also}:
4000 @ref{GET_COMMAND}, @*
4001 @ref{GET_COMMAND_ARGUMENT}
4006 @node COMPILER_OPTIONS
4007 @section @code{COMPILER_OPTIONS} --- Options passed to the compiler
4008 @fnindex COMPILER_OPTIONS
4009 @cindex flags inquiry function
4010 @cindex options inquiry function
4011 @cindex compiler flags inquiry function
4014 @item @emph{Description}:
4015 @code{COMPILER_OPTIONS} returns a string with the options used for
4018 @item @emph{Standard}:
4022 Inquiry function of the module @code{ISO_FORTRAN_ENV}
4024 @item @emph{Syntax}:
4025 @code{STR = COMPILER_OPTIONS()}
4027 @item @emph{Arguments}:
4030 @item @emph{Return value}:
4031 The return value is a default-kind string with system-dependent length.
4032 It contains the compiler flags used to compile the file, which called
4033 the @code{COMPILER_OPTIONS} intrinsic.
4035 @item @emph{Example}:
4038 print '(4a)', 'This file was compiled by ', &
4039 compiler_version(), ' using the options ', &
4044 @item @emph{See also}:
4045 @ref{COMPILER_VERSION}, @*
4046 @ref{ISO_FORTRAN_ENV}
4051 @node COMPILER_VERSION
4052 @section @code{COMPILER_VERSION} --- Compiler version string
4053 @fnindex COMPILER_VERSION
4054 @cindex compiler, name and version
4055 @cindex version of the compiler
4058 @item @emph{Description}:
4059 @code{COMPILER_VERSION} returns a string with the name and the
4060 version of the compiler.
4062 @item @emph{Standard}:
4066 Inquiry function of the module @code{ISO_FORTRAN_ENV}
4068 @item @emph{Syntax}:
4069 @code{STR = COMPILER_VERSION()}
4071 @item @emph{Arguments}:
4074 @item @emph{Return value}:
4075 The return value is a default-kind string with system-dependent length.
4076 It contains the name of the compiler and its version number.
4078 @item @emph{Example}:
4081 print '(4a)', 'This file was compiled by ', &
4082 compiler_version(), ' using the options ', &
4087 @item @emph{See also}:
4088 @ref{COMPILER_OPTIONS}, @*
4089 @ref{ISO_FORTRAN_ENV}
4095 @section @code{COMPLEX} --- Complex conversion function
4097 @cindex complex numbers, conversion to
4098 @cindex conversion, to complex
4101 @item @emph{Description}:
4102 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
4103 to the real component and @var{Y} is converted to the imaginary
4106 @item @emph{Standard}:
4112 @item @emph{Syntax}:
4113 @code{RESULT = COMPLEX(X, Y)}
4115 @item @emph{Arguments}:
4116 @multitable @columnfractions .15 .70
4117 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
4118 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
4121 @item @emph{Return value}:
4122 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
4123 value is of default @code{COMPLEX} type.
4125 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
4126 type and one is of @code{INTEGER} type, then the return value is of
4127 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
4128 argument with the highest precision.
4130 @item @emph{Example}:
4132 program test_complex
4135 print *, complex(i, x)
4136 end program test_complex
4139 @item @emph{See also}:
4146 @section @code{CONJG} --- Complex conjugate function
4149 @cindex complex conjugate
4152 @item @emph{Description}:
4153 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
4154 then the result is @code{(x, -y)}
4156 @item @emph{Standard}:
4157 Fortran 77 and later, has an overload that is a GNU extension
4162 @item @emph{Syntax}:
4165 @item @emph{Arguments}:
4166 @multitable @columnfractions .15 .70
4167 @item @var{Z} @tab The type shall be @code{COMPLEX}.
4170 @item @emph{Return value}:
4171 The return value is of type @code{COMPLEX}.
4173 @item @emph{Example}:
4176 complex :: z = (2.0, 3.0)
4177 complex(8) :: dz = (2.71_8, -3.14_8)
4182 end program test_conjg
4185 @item @emph{Specific names}:
4186 @multitable @columnfractions .20 .23 .20 .33
4187 @headitem Name @tab Argument @tab Return type @tab Standard
4188 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
4195 @section @code{COS} --- Cosine function
4201 @cindex trigonometric function, cosine
4205 @item @emph{Description}:
4206 @code{COS(X)} computes the cosine of @var{X}.
4208 @item @emph{Standard}:
4209 Fortran 77 and later, has overloads that are GNU extensions
4214 @item @emph{Syntax}:
4215 @code{RESULT = COS(X)}
4217 @item @emph{Arguments}:
4218 @multitable @columnfractions .15 .70
4219 @item @var{X} @tab The type shall be @code{REAL} or
4223 @item @emph{Return value}:
4224 The return value is of the same type and kind as @var{X}. The real part
4225 of the result is in radians. If @var{X} is of the type @code{REAL},
4226 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
4228 @item @emph{Example}:
4233 end program test_cos
4236 @item @emph{Specific names}:
4237 @multitable @columnfractions .20 .23 .20 .33
4238 @headitem Name @tab Argument @tab Return type @tab Standard
4239 @item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
4240 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
4241 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
4242 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4243 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4246 @item @emph{See also}:
4247 Inverse function: @*
4249 Degrees function: @*
4256 @section @code{COSD} --- Cosine function, degrees
4262 @cindex trigonometric function, cosine, degrees
4263 @cindex cosine, degrees
4266 @item @emph{Description}:
4267 @code{COSD(X)} computes the cosine of @var{X} in degrees.
4269 @item @emph{Standard}:
4275 @item @emph{Syntax}:
4276 @code{RESULT = COSD(X)}
4278 @item @emph{Arguments}:
4279 @multitable @columnfractions .15 .70
4280 @item @var{X} @tab The type shall be @code{REAL} or
4284 @item @emph{Return value}:
4285 The return value is of the same type and kind as @var{X}. The real part
4286 of the result is in degrees. If @var{X} is of the type @code{REAL},
4287 the return value lies in the range @math{ -1 \leq \cosd (x) \leq 1}.
4289 @item @emph{Example}:
4294 end program test_cosd
4297 @item @emph{Specific names}:
4298 @multitable @columnfractions .20 .23 .20 .33
4299 @headitem Name @tab Argument @tab Return type @tab Standard
4300 @item @code{COSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 2023
4301 @item @code{DCOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4302 @item @code{CCOSD(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU extension
4303 @item @code{ZCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4304 @item @code{CDCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4307 @item @emph{See also}:
4308 Inverse function: @*
4310 Radians function: @*
4317 @section @code{COSH} --- Hyperbolic cosine function
4320 @cindex hyperbolic cosine
4321 @cindex hyperbolic function, cosine
4322 @cindex cosine, hyperbolic
4325 @item @emph{Description}:
4326 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
4328 @item @emph{Standard}:
4329 Fortran 77 and later, for a complex argument Fortran 2008 or later
4334 @item @emph{Syntax}:
4337 @item @emph{Arguments}:
4338 @multitable @columnfractions .15 .70
4339 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4342 @item @emph{Return value}:
4343 The return value has same type and kind as @var{X}. If @var{X} is
4344 complex, the imaginary part of the result is in radians. If @var{X}
4345 is @code{REAL}, the return value has a lower bound of one,
4346 @math{\cosh (x) \geq 1}.
4348 @item @emph{Example}:
4351 real(8) :: x = 1.0_8
4353 end program test_cosh
4356 @item @emph{Specific names}:
4357 @multitable @columnfractions .20 .23 .20 .33
4358 @headitem Name @tab Argument @tab Return type @tab Standard
4359 @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
4360 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
4363 @item @emph{See also}:
4364 Inverse function: @*
4371 @section @code{COTAN} --- Cotangent function
4374 @cindex trigonometric function, cotangent
4378 @item @emph{Description}:
4379 @code{COTAN(X)} computes the cotangent of @var{X}. Equivalent to @code{COS(x)}
4380 divided by @code{SIN(x)}, or @code{1 / TAN(x)}.
4382 This function is for compatibility only and should be avoided in favor of
4383 standard constructs wherever possible.
4385 @item @emph{Standard}:
4386 GNU extension, enabled with @option{-fdec-math}.
4391 @item @emph{Syntax}:
4392 @code{RESULT = COTAN(X)}
4394 @item @emph{Arguments}:
4395 @multitable @columnfractions .15 .70
4396 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4399 @item @emph{Return value}:
4400 The return value has same type and kind as @var{X}, and its value is in radians.
4402 @item @emph{Example}:
4405 real(8) :: x = 0.165_8
4407 end program test_cotan
4410 @item @emph{Specific names}:
4411 @multitable @columnfractions .20 .23 .20 .33
4412 @headitem Name @tab Argument @tab Return type @tab Standard
4413 @item @code{COTAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
4414 @item @code{DCOTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4417 @item @emph{See also}:
4418 Converse function: @*
4420 Degrees function: @*
4427 @section @code{COTAND} --- Cotangent function, degrees
4430 @cindex trigonometric function, cotangent, degrees
4431 @cindex cotangent, degrees
4434 @item @emph{Description}:
4435 @code{COTAND(X)} computes the cotangent of @var{X} in degrees. Equivalent to
4436 @code{COSD(x)} divided by @code{SIND(x)}, or @code{1 / TAND(x)}.
4438 @item @emph{Standard}:
4439 GNU extension, enabled with @option{-fdec-math}.
4441 This function is for compatibility only and should be avoided in favor of
4442 standard constructs wherever possible.
4447 @item @emph{Syntax}:
4448 @code{RESULT = COTAND(X)}
4450 @item @emph{Arguments}:
4451 @multitable @columnfractions .15 .70
4452 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4455 @item @emph{Return value}:
4456 The return value has same type and kind as @var{X}, and its value is in degrees.
4458 @item @emph{Example}:
4461 real(8) :: x = 0.165_8
4463 end program test_cotand
4466 @item @emph{Specific names}:
4467 @multitable @columnfractions .20 .23 .20 .33
4468 @headitem Name @tab Argument @tab Return type @tab Standard
4469 @item @code{COTAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
4470 @item @code{DCOTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4473 @item @emph{See also}:
4474 Converse function: @*
4476 Radians function: @*
4483 @section @code{COUNT} --- Count function
4485 @cindex array, conditionally count elements
4486 @cindex array, element counting
4487 @cindex array, number of elements
4490 @item @emph{Description}:
4492 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
4493 or, if the @var{DIM} argument is supplied, counts the number of
4494 elements along each row of the array in the @var{DIM} direction.
4495 If the array has zero size, or all of the elements of @var{MASK} are
4496 @code{.FALSE.}, then the result is @code{0}.
4498 @item @emph{Standard}:
4499 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
4502 Transformational function
4504 @item @emph{Syntax}:
4505 @code{RESULT = COUNT(MASK [, DIM, KIND])}
4507 @item @emph{Arguments}:
4508 @multitable @columnfractions .15 .70
4509 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
4510 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
4511 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
4512 expression indicating the kind parameter of the result.
4515 @item @emph{Return value}:
4516 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
4517 @var{KIND} is absent, the return value is of default integer kind.
4518 If @var{DIM} is present, the result is an array with a rank one less
4519 than the rank of @var{ARRAY}, and a size corresponding to the shape
4520 of @var{ARRAY} with the @var{DIM} dimension removed.
4522 @item @emph{Example}:
4525 integer, dimension(2,3) :: a, b
4526 logical, dimension(2,3) :: mask
4527 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
4528 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
4529 print '(3i3)', a(1,:)
4530 print '(3i3)', a(2,:)
4532 print '(3i3)', b(1,:)
4533 print '(3i3)', b(2,:)
4536 print '(3l3)', mask(1,:)
4537 print '(3l3)', mask(2,:)
4539 print '(3i3)', count(mask)
4541 print '(3i3)', count(mask, 1)
4543 print '(3i3)', count(mask, 2)
4544 end program test_count
4551 @section @code{CPU_TIME} --- CPU elapsed time in seconds
4553 @cindex time, elapsed
4556 @item @emph{Description}:
4557 Returns a @code{REAL} value representing the elapsed CPU time in
4558 seconds. This is useful for testing segments of code to determine
4561 If a time source is available, time will be reported with microsecond
4562 resolution. If no time source is available, @var{TIME} is set to
4565 Note that @var{TIME} may contain a, system dependent, arbitrary offset
4566 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
4567 value is meaningless, only differences between subsequent calls to
4568 this subroutine, as shown in the example below, should be used.
4571 @item @emph{Standard}:
4572 Fortran 95 and later
4577 @item @emph{Syntax}:
4578 @code{CALL CPU_TIME(TIME)}
4580 @item @emph{Arguments}:
4581 @multitable @columnfractions .15 .70
4582 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
4585 @item @emph{Return value}:
4588 @item @emph{Example}:
4590 program test_cpu_time
4591 real :: start, finish
4592 call cpu_time(start)
4593 ! put code to test here
4594 call cpu_time(finish)
4595 print '("Time = ",f6.3," seconds.")',finish-start
4596 end program test_cpu_time
4599 @item @emph{See also}:
4600 @ref{SYSTEM_CLOCK}, @*
4607 @section @code{CSHIFT} --- Circular shift elements of an array
4609 @cindex array, shift circularly
4610 @cindex array, permutation
4611 @cindex array, rotate
4614 @item @emph{Description}:
4615 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
4616 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
4617 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
4618 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
4619 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
4620 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
4621 sections of @var{ARRAY} along the given dimension are shifted. Elements
4622 shifted out one end of each rank one section are shifted back in the other end.
4624 @item @emph{Standard}:
4625 Fortran 90 and later
4628 Transformational function
4630 @item @emph{Syntax}:
4631 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
4633 @item @emph{Arguments}:
4634 @multitable @columnfractions .15 .70
4635 @item @var{ARRAY} @tab Shall be an array of any type.
4636 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
4637 @item @var{DIM} @tab The type shall be @code{INTEGER}.
4640 @item @emph{Return value}:
4641 Returns an array of same type and rank as the @var{ARRAY} argument.
4643 @item @emph{Example}:
4646 integer, dimension(3,3) :: a
4647 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
4648 print '(3i3)', a(1,:)
4649 print '(3i3)', a(2,:)
4650 print '(3i3)', a(3,:)
4651 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
4653 print '(3i3)', a(1,:)
4654 print '(3i3)', a(2,:)
4655 print '(3i3)', a(3,:)
4656 end program test_cshift
4663 @section @code{CTIME} --- Convert a time into a string
4665 @cindex time, conversion to string
4666 @cindex conversion, to string
4669 @item @emph{Description}:
4670 @code{CTIME} converts a system time value, such as returned by
4671 @ref{TIME8}, to a string. The output will be of the form @samp{Sat
4672 Aug 19 18:13:14 1995}.
4674 This intrinsic is provided in both subroutine and function forms; however,
4675 only one form can be used in any given program unit.
4677 @item @emph{Standard}:
4681 Subroutine, function
4683 @item @emph{Syntax}:
4684 @multitable @columnfractions .80
4685 @item @code{CALL CTIME(TIME, RESULT)}.
4686 @item @code{RESULT = CTIME(TIME)}.
4689 @item @emph{Arguments}:
4690 @multitable @columnfractions .15 .70
4691 @item @var{TIME} @tab The type shall be of type @code{INTEGER}.
4692 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
4693 of default kind. It is an @code{INTENT(OUT)} argument. If the length
4694 of this variable is too short for the time and date string to fit
4695 completely, it will be blank on procedure return.
4698 @item @emph{Return value}:
4699 The converted date and time as a string.
4701 @item @emph{Example}:
4705 character(len=30) :: date
4708 ! Do something, main part of the program
4711 print *, 'Program was started on ', date
4712 end program test_ctime
4715 @item @emph{See Also}:
4716 @ref{DATE_AND_TIME}, @*
4726 @section @code{DATE_AND_TIME} --- Date and time subroutine
4727 @fnindex DATE_AND_TIME
4728 @cindex date, current
4729 @cindex current date
4730 @cindex time, current
4731 @cindex current time
4734 @item @emph{Description}:
4735 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
4736 time information from the real-time system clock. @var{DATE} is
4737 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
4738 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
4739 representing the difference with respect to Coordinated Universal Time (UTC).
4740 Unavailable time and date parameters return blanks.
4742 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
4744 @multitable @columnfractions .15 .70
4745 @item @code{VALUE(1)}: @tab The year
4746 @item @code{VALUE(2)}: @tab The month
4747 @item @code{VALUE(3)}: @tab The day of the month
4748 @item @code{VALUE(4)}: @tab Time difference with UTC in minutes
4749 @item @code{VALUE(5)}: @tab The hour of the day
4750 @item @code{VALUE(6)}: @tab The minutes of the hour
4751 @item @code{VALUE(7)}: @tab The seconds of the minute
4752 @item @code{VALUE(8)}: @tab The milliseconds of the second
4755 @item @emph{Standard}:
4756 Fortran 90 and later
4761 @item @emph{Syntax}:
4762 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
4764 @item @emph{Arguments}:
4765 @multitable @columnfractions .15 .70
4766 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
4767 or larger, and of default kind.
4768 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
4769 or larger, and of default kind.
4770 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
4771 or larger, and of default kind.
4772 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
4775 @item @emph{Return value}:
4778 @item @emph{Example}:
4780 program test_time_and_date
4781 character(8) :: date
4782 character(10) :: time
4783 character(5) :: zone
4784 integer,dimension(8) :: values
4785 ! using keyword arguments
4786 call date_and_time(date,time,zone,values)
4787 call date_and_time(DATE=date,ZONE=zone)
4788 call date_and_time(TIME=time)
4789 call date_and_time(VALUES=values)
4790 print '(a,2x,a,2x,a)', date, time, zone
4791 print '(8i5)', values
4792 end program test_time_and_date
4795 @item @emph{See also}:
4803 @section @code{DBLE} --- Double conversion function
4805 @cindex conversion, to real
4808 @item @emph{Description}:
4809 @code{DBLE(A)} Converts @var{A} to double precision real type.
4811 @item @emph{Standard}:
4812 Fortran 77 and later
4817 @item @emph{Syntax}:
4818 @code{RESULT = DBLE(A)}
4820 @item @emph{Arguments}:
4821 @multitable @columnfractions .15 .70
4822 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
4826 @item @emph{Return value}:
4827 The return value is of type double precision real.
4829 @item @emph{Example}:
4834 complex :: z = (2.3,1.14)
4835 print *, dble(x), dble(i), dble(z)
4836 end program test_dble
4839 @item @emph{See also}:
4846 @section @code{DCMPLX} --- Double complex conversion function
4848 @cindex complex numbers, conversion to
4849 @cindex conversion, to complex
4852 @item @emph{Description}:
4853 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
4854 converted to the real component. If @var{Y} is present it is converted to the
4855 imaginary component. If @var{Y} is not present then the imaginary component is
4856 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
4858 @item @emph{Standard}:
4864 @item @emph{Syntax}:
4865 @code{RESULT = DCMPLX(X [, Y])}
4867 @item @emph{Arguments}:
4868 @multitable @columnfractions .15 .70
4869 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
4871 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
4872 @code{INTEGER} or @code{REAL}.
4875 @item @emph{Return value}:
4876 The return value is of type @code{COMPLEX(8)}
4878 @item @emph{Example}:
4888 print *, dcmplx(x,i)
4889 end program test_dcmplx
4895 @section @code{DIGITS} --- Significant binary digits function
4897 @cindex model representation, significant digits
4900 @item @emph{Description}:
4901 @code{DIGITS(X)} returns the number of significant binary digits of the internal
4902 model representation of @var{X}. For example, on a system using a 32-bit
4903 floating point representation, a default real number would likely return 24.
4905 @item @emph{Standard}:
4906 Fortran 90 and later
4911 @item @emph{Syntax}:
4912 @code{RESULT = DIGITS(X)}
4914 @item @emph{Arguments}:
4915 @multitable @columnfractions .15 .70
4916 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
4919 @item @emph{Return value}:
4920 The return value is of type @code{INTEGER}.
4922 @item @emph{Example}:
4925 integer :: i = 12345
4931 end program test_digits
4938 @section @code{DIM} --- Positive difference
4942 @cindex positive difference
4945 @item @emph{Description}:
4946 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
4947 otherwise returns zero.
4949 @item @emph{Standard}:
4950 Fortran 77 and later
4955 @item @emph{Syntax}:
4956 @code{RESULT = DIM(X, Y)}
4958 @item @emph{Arguments}:
4959 @multitable @columnfractions .15 .70
4960 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
4961 @item @var{Y} @tab The type shall be the same type and kind as @var{X}. (As
4962 a GNU extension, arguments of different kinds are permitted.)
4965 @item @emph{Return value}:
4966 The return value is of type @code{INTEGER} or @code{REAL}. (As a GNU
4967 extension, kind is the largest kind of the actual arguments.)
4969 @item @emph{Example}:
4975 x = dim(4.345_8, 2.111_8)
4978 end program test_dim
4981 @item @emph{Specific names}:
4982 @multitable @columnfractions .20 .26 .20 .30
4983 @headitem Name @tab Argument @tab Return type @tab Standard
4984 @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
4985 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
4986 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
4993 @section @code{DOT_PRODUCT} --- Dot product function
4994 @fnindex DOT_PRODUCT
4996 @cindex vector product
4997 @cindex product, vector
5000 @item @emph{Description}:
5001 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
5002 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
5003 either numeric or logical and must be arrays of rank one and of equal size. If
5004 the vectors are @code{INTEGER} or @code{REAL}, the result is
5005 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
5006 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
5007 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
5009 @item @emph{Standard}:
5010 Fortran 90 and later
5013 Transformational function
5015 @item @emph{Syntax}:
5016 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
5018 @item @emph{Arguments}:
5019 @multitable @columnfractions .15 .70
5020 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
5021 @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.
5024 @item @emph{Return value}:
5025 If the arguments are numeric, the return value is a scalar of numeric type,
5026 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
5027 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
5029 @item @emph{Example}:
5031 program test_dot_prod
5032 integer, dimension(3) :: a, b
5039 print *, dot_product(a,b)
5040 end program test_dot_prod
5047 @section @code{DPROD} --- Double product function
5049 @cindex product, double-precision
5052 @item @emph{Description}:
5053 @code{DPROD(X,Y)} returns the product @code{X*Y}.
5055 @item @emph{Standard}:
5056 Fortran 77 and later
5061 @item @emph{Syntax}:
5062 @code{RESULT = DPROD(X, Y)}
5064 @item @emph{Arguments}:
5065 @multitable @columnfractions .15 .70
5066 @item @var{X} @tab The type shall be @code{REAL}.
5067 @item @var{Y} @tab The type shall be @code{REAL}.
5070 @item @emph{Return value}:
5071 The return value is of type @code{REAL(8)}.
5073 @item @emph{Example}:
5081 end program test_dprod
5084 @item @emph{Specific names}:
5085 @multitable @columnfractions .20 .23 .20 .33
5086 @headitem Name @tab Argument @tab Return type @tab Standard
5087 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
5094 @section @code{DREAL} --- Double real part function
5096 @cindex complex numbers, real part
5099 @item @emph{Description}:
5100 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
5102 @item @emph{Standard}:
5108 @item @emph{Syntax}:
5109 @code{RESULT = DREAL(A)}
5111 @item @emph{Arguments}:
5112 @multitable @columnfractions .15 .70
5113 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
5116 @item @emph{Return value}:
5117 The return value is of type @code{REAL(8)}.
5119 @item @emph{Example}:
5122 complex(8) :: z = (1.3_8,7.2_8)
5124 end program test_dreal
5127 @item @emph{See also}:
5135 @section @code{DSHIFTL} --- Combined left shift
5137 @cindex left shift, combined
5141 @item @emph{Description}:
5142 @code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
5143 rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
5144 bits of @var{J}, and the remaining bits are the rightmost bits of
5147 @item @emph{Standard}:
5148 Fortran 2008 and later
5153 @item @emph{Syntax}:
5154 @code{RESULT = DSHIFTL(I, J, SHIFT)}
5156 @item @emph{Arguments}:
5157 @multitable @columnfractions .15 .70
5158 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5159 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5160 If both @var{I} and @var{J} have integer type, then they shall have
5161 the same kind type parameter. @var{I} and @var{J} shall not both be
5163 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
5164 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
5165 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
5166 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
5169 @item @emph{Return value}:
5170 If either @var{I} or @var{J} is a BOZ constant, it is first converted
5171 as if by the intrinsic function @code{INT} to an integer type with the
5172 kind type parameter of the other.
5174 @item @emph{See also}:
5180 @section @code{DSHIFTR} --- Combined right shift
5182 @cindex right shift, combined
5183 @cindex shift, right
5186 @item @emph{Description}:
5187 @code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
5188 leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
5189 bits of @var{I}, and the remaining bits are the leftmost bits of
5192 @item @emph{Standard}:
5193 Fortran 2008 and later
5198 @item @emph{Syntax}:
5199 @code{RESULT = DSHIFTR(I, J, SHIFT)}
5201 @item @emph{Arguments}:
5202 @multitable @columnfractions .15 .70
5203 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5204 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5205 If both @var{I} and @var{J} have integer type, then they shall have
5206 the same kind type parameter. @var{I} and @var{J} shall not both be
5208 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
5209 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
5210 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
5211 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
5214 @item @emph{Return value}:
5215 If either @var{I} or @var{J} is a BOZ constant, it is first converted
5216 as if by the intrinsic function @code{INT} to an integer type with the
5217 kind type parameter of the other.
5219 @item @emph{See also}:
5225 @section @code{DTIME} --- Execution time subroutine (or function)
5227 @cindex time, elapsed
5228 @cindex elapsed time
5231 @item @emph{Description}:
5232 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
5233 since the start of the process's execution in @var{TIME}. @var{VALUES}
5234 returns the user and system components of this time in @code{VALUES(1)} and
5235 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
5238 Subsequent invocations of @code{DTIME} return values accumulated since the
5239 previous invocation.
5241 On some systems, the underlying timings are represented using types with
5242 sufficiently small limits that overflows (wrap around) are possible, such as
5243 32-bit types. Therefore, the values returned by this intrinsic might be, or
5244 become, negative, or numerically less than previous values, during a single
5245 run of the compiled program.
5247 Please note, that this implementation is thread safe if used within OpenMP
5248 directives, i.e., its state will be consistent while called from multiple
5249 threads. However, if @code{DTIME} is called from multiple threads, the result
5250 is still the time since the last invocation. This may not give the intended
5251 results. If possible, use @code{CPU_TIME} instead.
5253 This intrinsic is provided in both subroutine and function forms; however,
5254 only one form can be used in any given program unit.
5256 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
5258 @multitable @columnfractions .15 .70
5259 @item @code{VALUES(1)}: @tab User time in seconds.
5260 @item @code{VALUES(2)}: @tab System time in seconds.
5261 @item @code{TIME}: @tab Run time since start in seconds.
5264 @item @emph{Standard}:
5268 Subroutine, function
5270 @item @emph{Syntax}:
5271 @multitable @columnfractions .80
5272 @item @code{CALL DTIME(VALUES, TIME)}.
5273 @item @code{TIME = DTIME(VALUES)}, (not recommended).
5276 @item @emph{Arguments}:
5277 @multitable @columnfractions .15 .70
5278 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
5279 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
5282 @item @emph{Return value}:
5283 Elapsed time in seconds since the last invocation or since the start of program
5284 execution if not called before.
5286 @item @emph{Example}:
5290 real, dimension(2) :: tarray
5292 call dtime(tarray, result)
5296 do i=1,100000000 ! Just a delay
5299 call dtime(tarray, result)
5303 end program test_dtime
5306 @item @emph{See also}:
5314 @section @code{EOSHIFT} --- End-off shift elements of an array
5316 @cindex array, shift
5319 @item @emph{Description}:
5320 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
5321 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
5322 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
5323 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
5324 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
5325 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
5326 then all complete rank one sections of @var{ARRAY} along the given dimension are
5327 shifted. Elements shifted out one end of each rank one section are dropped. If
5328 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
5329 is copied back in the other end. If @var{BOUNDARY} is not present then the
5330 following are copied in depending on the type of @var{ARRAY}.
5332 @multitable @columnfractions .15 .80
5333 @item @emph{Array Type} @tab @emph{Boundary Value}
5334 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
5335 @item Logical @tab @code{.FALSE.}.
5336 @item Character(@var{len}) @tab @var{len} blanks.
5339 @item @emph{Standard}:
5340 Fortran 90 and later
5343 Transformational function
5345 @item @emph{Syntax}:
5346 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
5348 @item @emph{Arguments}:
5349 @multitable @columnfractions .15 .70
5350 @item @var{ARRAY} @tab May be any type, not scalar.
5351 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
5352 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
5353 @item @var{DIM} @tab The type shall be @code{INTEGER}.
5356 @item @emph{Return value}:
5357 Returns an array of same type and rank as the @var{ARRAY} argument.
5359 @item @emph{Example}:
5361 program test_eoshift
5362 integer, dimension(3,3) :: a
5363 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
5364 print '(3i3)', a(1,:)
5365 print '(3i3)', a(2,:)
5366 print '(3i3)', a(3,:)
5367 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
5369 print '(3i3)', a(1,:)
5370 print '(3i3)', a(2,:)
5371 print '(3i3)', a(3,:)
5372 end program test_eoshift
5379 @section @code{EPSILON} --- Epsilon function
5381 @cindex model representation, epsilon
5384 @item @emph{Description}:
5385 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
5386 as @var{X} such that @math{1 + E > 1}.
5388 @item @emph{Standard}:
5389 Fortran 90 and later
5394 @item @emph{Syntax}:
5395 @code{RESULT = EPSILON(X)}
5397 @item @emph{Arguments}:
5398 @multitable @columnfractions .15 .70
5399 @item @var{X} @tab The type shall be @code{REAL}.
5402 @item @emph{Return value}:
5403 The return value is of same type as the argument.
5405 @item @emph{Example}:
5407 program test_epsilon
5412 end program test_epsilon
5419 @section @code{ERF} --- Error function
5421 @cindex error function
5424 @item @emph{Description}:
5425 @code{ERF(X)} computes the error function of @var{X}.
5427 @item @emph{Standard}:
5428 Fortran 2008 and later
5433 @item @emph{Syntax}:
5434 @code{RESULT = ERF(X)}
5436 @item @emph{Arguments}:
5437 @multitable @columnfractions .15 .70
5438 @item @var{X} @tab The type shall be @code{REAL}.
5441 @item @emph{Return value}:
5442 The return value is of type @code{REAL}, of the same kind as
5443 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
5445 @item @emph{Example}:
5448 real(8) :: x = 0.17_8
5450 end program test_erf
5453 @item @emph{Specific names}:
5454 @multitable @columnfractions .20 .23 .20 .33
5455 @headitem Name @tab Argument @tab Return type @tab Standard
5456 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
5463 @section @code{ERFC} --- Error function
5465 @cindex error function, complementary
5468 @item @emph{Description}:
5469 @code{ERFC(X)} computes the complementary error function of @var{X}.
5471 @item @emph{Standard}:
5472 Fortran 2008 and later
5477 @item @emph{Syntax}:
5478 @code{RESULT = ERFC(X)}
5480 @item @emph{Arguments}:
5481 @multitable @columnfractions .15 .70
5482 @item @var{X} @tab The type shall be @code{REAL}.
5485 @item @emph{Return value}:
5486 The return value is of type @code{REAL} and of the same kind as @var{X}.
5487 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
5489 @item @emph{Example}:
5492 real(8) :: x = 0.17_8
5494 end program test_erfc
5497 @item @emph{Specific names}:
5498 @multitable @columnfractions .20 .23 .20 .33
5499 @headitem Name @tab Argument @tab Return type @tab Standard
5500 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
5507 @section @code{ERFC_SCALED} --- Error function
5508 @fnindex ERFC_SCALED
5509 @cindex error function, complementary, exponentially-scaled
5512 @item @emph{Description}:
5513 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
5514 error function of @var{X}.
5516 @item @emph{Standard}:
5517 Fortran 2008 and later
5522 @item @emph{Syntax}:
5523 @code{RESULT = ERFC_SCALED(X)}
5525 @item @emph{Arguments}:
5526 @multitable @columnfractions .15 .70
5527 @item @var{X} @tab The type shall be @code{REAL}.
5530 @item @emph{Return value}:
5531 The return value is of type @code{REAL} and of the same kind as @var{X}.
5533 @item @emph{Example}:
5535 program test_erfc_scaled
5536 real(8) :: x = 0.17_8
5538 end program test_erfc_scaled
5545 @section @code{ETIME} --- Execution time subroutine (or function)
5547 @cindex time, elapsed
5550 @item @emph{Description}:
5551 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
5552 since the start of the process's execution in @var{TIME}. @var{VALUES}
5553 returns the user and system components of this time in @code{VALUES(1)} and
5554 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
5556 On some systems, the underlying timings are represented using types with
5557 sufficiently small limits that overflows (wrap around) are possible, such as
5558 32-bit types. Therefore, the values returned by this intrinsic might be, or
5559 become, negative, or numerically less than previous values, during a single
5560 run of the compiled program.
5562 This intrinsic is provided in both subroutine and function forms; however,
5563 only one form can be used in any given program unit.
5565 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
5567 @multitable @columnfractions .15 .70
5568 @item @code{VALUES(1)}: @tab User time in seconds.
5569 @item @code{VALUES(2)}: @tab System time in seconds.
5570 @item @code{TIME}: @tab Run time since start in seconds.
5573 @item @emph{Standard}:
5577 Subroutine, function
5579 @item @emph{Syntax}:
5580 @multitable @columnfractions .80
5581 @item @code{CALL ETIME(VALUES, TIME)}.
5582 @item @code{TIME = ETIME(VALUES)}, (not recommended).
5585 @item @emph{Arguments}:
5586 @multitable @columnfractions .15 .70
5587 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
5588 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
5591 @item @emph{Return value}:
5592 Elapsed time in seconds since the start of program execution.
5594 @item @emph{Example}:
5598 real, dimension(2) :: tarray
5600 call ETIME(tarray, result)
5604 do i=1,100000000 ! Just a delay
5607 call ETIME(tarray, result)
5611 end program test_etime
5614 @item @emph{See also}:
5622 @section @code{EVENT_QUERY} --- Query whether a coarray event has occurred
5623 @fnindex EVENT_QUERY
5624 @cindex Events, EVENT_QUERY
5627 @item @emph{Description}:
5628 @code{EVENT_QUERY} assignes the number of events to @var{COUNT} which have been
5629 posted to the @var{EVENT} variable and not yet been removed by calling
5630 @code{EVENT WAIT}. When @var{STAT} is present and the invocation was successful,
5631 it is assigned the value 0. If it is present and the invocation has failed,
5632 it is assigned a positive value and @var{COUNT} is assigned the value @math{-1}.
5634 @item @emph{Standard}:
5640 @item @emph{Syntax}:
5641 @code{CALL EVENT_QUERY (EVENT, COUNT [, STAT])}
5643 @item @emph{Arguments}:
5644 @multitable @columnfractions .15 .70
5645 @item @var{EVENT} @tab (intent(IN)) Scalar of type @code{EVENT_TYPE},
5646 defined in @code{ISO_FORTRAN_ENV}; shall not be coindexed.
5647 @item @var{COUNT} @tab (intent(out))Scalar integer with at least the
5648 precision of default integer.
5649 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
5652 @item @emph{Example}:
5657 type(event_type) :: event_value_has_been_set[*]
5659 if (this_image() == 1) then
5660 call event_query (event_value_has_been_set, cnt)
5661 if (cnt > 0) write(*,*) "Value has been set"
5662 elseif (this_image() == 2) then
5663 event post (event_value_has_been_set[1])
5672 @node EXECUTE_COMMAND_LINE
5673 @section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
5674 @fnindex EXECUTE_COMMAND_LINE
5675 @cindex system, system call
5676 @cindex command line
5679 @item @emph{Description}:
5680 @code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
5683 The @code{COMMAND} argument is passed to the shell and executed (The
5684 shell is @code{sh} on Unix systems, and @code{cmd.exe} on Windows.).
5685 If @code{WAIT} is present and has the value false, the execution of
5686 the command is asynchronous if the system supports it; otherwise, the
5687 command is executed synchronously using the C library's @code{system}
5690 The three last arguments allow the user to get status information. After
5691 synchronous execution, @code{EXITSTAT} contains the integer exit code of
5692 the command, as returned by @code{system}. @code{CMDSTAT} is set to zero
5693 if the command line was executed (whatever its exit status was).
5694 @code{CMDMSG} is assigned an error message if an error has occurred.
5696 Note that the @code{system} function need not be thread-safe. It is
5697 the responsibility of the user to ensure that @code{system} is not
5698 called concurrently.
5700 For asynchronous execution on supported targets, the POSIX
5701 @code{posix_spawn} or @code{fork} functions are used. Also, a signal
5702 handler for the @code{SIGCHLD} signal is installed.
5704 @item @emph{Standard}:
5705 Fortran 2008 and later
5710 @item @emph{Syntax}:
5711 @code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
5713 @item @emph{Arguments}:
5714 @multitable @columnfractions .15 .70
5715 @item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
5716 @item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
5717 @item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5719 @item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5721 @item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
5725 @item @emph{Example}:
5730 call execute_command_line ("external_prog.exe", exitstat=i)
5731 print *, "Exit status of external_prog.exe was ", i
5733 call execute_command_line ("reindex_files.exe", wait=.false.)
5734 print *, "Now reindexing files in the background"
5736 end program test_exec
5742 Because this intrinsic is implemented in terms of the @code{system}
5743 function call, its behavior with respect to signaling is processor
5744 dependent. In particular, on POSIX-compliant systems, the SIGINT and
5745 SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
5746 such, if the parent process is terminated, the child process might not be
5747 terminated alongside.
5750 @item @emph{See also}:
5757 @section @code{EXIT} --- Exit the program with status.
5759 @cindex program termination
5760 @cindex terminate program
5763 @item @emph{Description}:
5764 @code{EXIT} causes immediate termination of the program with status. If status
5765 is omitted it returns the canonical @emph{success} for the system. All Fortran
5766 I/O units are closed.
5768 @item @emph{Standard}:
5774 @item @emph{Syntax}:
5775 @code{CALL EXIT([STATUS])}
5777 @item @emph{Arguments}:
5778 @multitable @columnfractions .15 .70
5779 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
5782 @item @emph{Return value}:
5783 @code{STATUS} is passed to the parent process on exit.
5785 @item @emph{Example}:
5788 integer :: STATUS = 0
5789 print *, 'This program is going to exit.'
5791 end program test_exit
5794 @item @emph{See also}:
5802 @section @code{EXP} --- Exponential function
5808 @cindex exponential function
5809 @cindex logarithm function, inverse
5812 @item @emph{Description}:
5813 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
5815 @item @emph{Standard}:
5816 Fortran 77 and later, has overloads that are GNU extensions
5821 @item @emph{Syntax}:
5822 @code{RESULT = EXP(X)}
5824 @item @emph{Arguments}:
5825 @multitable @columnfractions .15 .70
5826 @item @var{X} @tab The type shall be @code{REAL} or
5830 @item @emph{Return value}:
5831 The return value has same type and kind as @var{X}.
5833 @item @emph{Example}:
5838 end program test_exp
5841 @item @emph{Specific names}:
5842 @multitable @columnfractions .20 .23 .20 .33
5843 @headitem Name @tab Argument @tab Return type @tab Standard
5844 @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
5845 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
5846 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
5847 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5848 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5855 @section @code{EXPONENT} --- Exponent function
5857 @cindex real number, exponent
5858 @cindex floating point, exponent
5861 @item @emph{Description}:
5862 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
5863 is zero the value returned is zero.
5865 @item @emph{Standard}:
5866 Fortran 90 and later
5871 @item @emph{Syntax}:
5872 @code{RESULT = EXPONENT(X)}
5874 @item @emph{Arguments}:
5875 @multitable @columnfractions .15 .70
5876 @item @var{X} @tab The type shall be @code{REAL}.
5879 @item @emph{Return value}:
5880 The return value is of type default @code{INTEGER}.
5882 @item @emph{Example}:
5884 program test_exponent
5889 print *, exponent(0.0)
5890 end program test_exponent
5896 @node EXTENDS_TYPE_OF
5897 @section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension
5898 @fnindex EXTENDS_TYPE_OF
5901 @item @emph{Description}:
5902 Query dynamic type for extension.
5904 @item @emph{Standard}:
5905 Fortran 2003 and later
5910 @item @emph{Syntax}:
5911 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
5913 @item @emph{Arguments}:
5914 @multitable @columnfractions .15 .70
5915 @item @var{A} @tab Shall be an object of extensible declared type or
5916 unlimited polymorphic.
5917 @item @var{MOLD} @tab Shall be an object of extensible declared type or
5918 unlimited polymorphic.
5921 @item @emph{Return value}:
5922 The return value is a scalar of type default logical. It is true if and only if
5923 the dynamic type of A is an extension type of the dynamic type of MOLD.
5926 @item @emph{See also}:
5933 @section @code{FDATE} --- Get the current time as a string
5935 @cindex time, current
5936 @cindex current time
5937 @cindex date, current
5938 @cindex current date
5941 @item @emph{Description}:
5942 @code{FDATE(DATE)} returns the current date (using the same format as
5943 @ref{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
5946 This intrinsic is provided in both subroutine and function forms; however,
5947 only one form can be used in any given program unit.
5949 @item @emph{Standard}:
5953 Subroutine, function
5955 @item @emph{Syntax}:
5956 @multitable @columnfractions .80
5957 @item @code{CALL FDATE(DATE)}.
5958 @item @code{DATE = FDATE()}.
5961 @item @emph{Arguments}:
5962 @multitable @columnfractions .15 .70
5963 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
5964 default kind. It is an @code{INTENT(OUT)} argument. If the length of
5965 this variable is too short for the date and time string to fit
5966 completely, it will be blank on procedure return.
5969 @item @emph{Return value}:
5970 The current date and time as a string.
5972 @item @emph{Example}:
5976 character(len=30) :: date
5978 print *, 'Program started on ', date
5979 do i = 1, 100000000 ! Just a delay
5983 print *, 'Program ended on ', date
5984 end program test_fdate
5987 @item @emph{See also}:
5988 @ref{DATE_AND_TIME}, @*
5994 @section @code{FGET} --- Read a single character in stream mode from stdin
5996 @cindex read character, stream mode
5997 @cindex stream mode, read character
5998 @cindex file operation, read character
6001 @item @emph{Description}:
6002 Read a single character in stream mode from stdin by bypassing normal
6003 formatted output. Stream I/O should not be mixed with normal record-oriented
6004 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
6006 This intrinsic is provided in both subroutine and function forms; however,
6007 only one form can be used in any given program unit.
6009 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
6010 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
6011 Programmers should consider the use of new stream IO feature in new code
6012 for future portability. See also @ref{Fortran 2003 status}.
6014 @item @emph{Standard}:
6018 Subroutine, function
6020 @item @emph{Syntax}:
6021 @multitable @columnfractions .80
6022 @item @code{CALL FGET(C [, STATUS])}
6023 @item @code{STATUS = FGET(C)}
6026 @item @emph{Arguments}:
6027 @multitable @columnfractions .15 .70
6028 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6030 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6031 Returns 0 on success, -1 on end-of-file, and a system specific positive
6032 error code otherwise.
6035 @item @emph{Example}:
6038 INTEGER, PARAMETER :: strlen = 100
6039 INTEGER :: status, i = 1
6040 CHARACTER(len=strlen) :: str = ""
6042 WRITE (*,*) 'Enter text:'
6044 CALL fget(str(i:i), status)
6045 if (status /= 0 .OR. i > strlen) exit
6048 WRITE (*,*) TRIM(str)
6052 @item @emph{See also}:
6061 @section @code{FGETC} --- Read a single character in stream mode
6063 @cindex read character, stream mode
6064 @cindex stream mode, read character
6065 @cindex file operation, read character
6068 @item @emph{Description}:
6069 Read a single character in stream mode by bypassing normal formatted output.
6070 Stream I/O should not be mixed with normal record-oriented (formatted or
6071 unformatted) I/O on the same unit; the results are unpredictable.
6073 This intrinsic is provided in both subroutine and function forms; however,
6074 only one form can be used in any given program unit.
6076 Note that the @code{FGET} intrinsic is provided for backwards compatibility
6077 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
6078 Programmers should consider the use of new stream IO feature in new code
6079 for future portability. See also @ref{Fortran 2003 status}.
6081 @item @emph{Standard}:
6085 Subroutine, function
6087 @item @emph{Syntax}:
6088 @multitable @columnfractions .80
6089 @item @code{CALL FGETC(UNIT, C [, STATUS])}
6090 @item @code{STATUS = FGETC(UNIT, C)}
6093 @item @emph{Arguments}:
6094 @multitable @columnfractions .15 .70
6095 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
6096 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6098 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6099 Returns 0 on success, -1 on end-of-file and a system specific positive
6100 error code otherwise.
6103 @item @emph{Example}:
6106 INTEGER :: fd = 42, status
6109 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
6111 CALL fgetc(fd, c, status)
6112 IF (status /= 0) EXIT
6119 @item @emph{See also}:
6126 @section @code{FINDLOC} --- Search an array for a value
6131 @item @emph{Description}:
6132 Determines the location of the element in the array with the value
6133 given in the @var{VALUE} argument, or, if the @var{DIM} argument is
6134 supplied, determines the locations of the elements equal to the
6135 @var{VALUE} argument element along each
6136 row of the array in the @var{DIM} direction. If @var{MASK} is
6137 present, only the elements for which @var{MASK} is @code{.TRUE.} are
6138 considered. If more than one element in the array has the value
6139 @var{VALUE}, the location returned is that of the first such element
6140 in array element order if the @var{BACK} is not present or if it is
6141 @code{.FALSE.}. If @var{BACK} is true, the location returned is that
6142 of the last such element. If the array has zero size, or all of the
6143 elements of @var{MASK} are @code{.FALSE.}, then the result is an array
6144 of zeroes. Similarly, if @var{DIM} is supplied and all of the
6145 elements of @var{MASK} along a given row are zero, the result value
6146 for that row is zero.
6148 @item @emph{Standard}:
6149 Fortran 2008 and later.
6152 Transformational function
6154 @item @emph{Syntax}:
6155 @multitable @columnfractions .80
6156 @item @code{RESULT = FINDLOC(ARRAY, VALUE, DIM [, MASK] [,KIND] [,BACK])}
6157 @item @code{RESULT = FINDLOC(ARRAY, VALUE, [, MASK] [,KIND] [,BACK])}
6160 @item @emph{Arguments}:
6161 @multitable @columnfractions .15 .70
6162 @item @var{ARRAY} @tab Shall be an array of intrinsic type.
6163 @item @var{VALUE} @tab A scalar of intrinsic type which is in type
6164 conformance with @var{ARRAY}.
6165 @item @var{DIM} @tab (Optional) Shall be a scalar of type
6166 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
6167 inclusive. It may not be an optional dummy argument.
6168 @item @var{MASK} @tab (Optional) Shall be of type @code{LOGICAL},
6169 and conformable with @var{ARRAY}.
6170 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
6171 expression indicating the kind parameter of the result.
6172 @item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}.
6175 @item @emph{Return value}:
6176 If @var{DIM} is absent, the result is a rank-one array with a length
6177 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
6178 is an array with a rank one less than the rank of @var{ARRAY}, and a
6179 size corresponding to the size of @var{ARRAY} with the @var{DIM}
6180 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
6181 of one, the result is a scalar. If the optional argument @var{KIND}
6182 is present, the result is an integer of kind @var{KIND}, otherwise it
6185 @item @emph{See also}:
6192 @section @code{FLOOR} --- Integer floor function
6195 @cindex rounding, floor
6198 @item @emph{Description}:
6199 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{A}.
6201 @item @emph{Standard}:
6202 Fortran 95 and later
6207 @item @emph{Syntax}:
6208 @code{RESULT = FLOOR(A [, KIND])}
6210 @item @emph{Arguments}:
6211 @multitable @columnfractions .15 .70
6212 @item @var{A} @tab The type shall be @code{REAL}.
6213 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
6214 expression indicating the kind parameter of the result.
6217 @item @emph{Return value}:
6218 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
6219 and of default-kind @code{INTEGER} otherwise.
6221 @item @emph{Example}:
6226 print *, floor(x) ! returns 63
6227 print *, floor(y) ! returns -64
6228 end program test_floor
6231 @item @emph{See also}:
6239 @section @code{FLUSH} --- Flush I/O unit(s)
6241 @cindex file operation, flush
6244 @item @emph{Description}:
6245 Flushes Fortran unit(s) currently open for output. Without the optional
6246 argument, all units are flushed, otherwise just the unit specified.
6248 @item @emph{Standard}:
6254 @item @emph{Syntax}:
6255 @code{CALL FLUSH(UNIT)}
6257 @item @emph{Arguments}:
6258 @multitable @columnfractions .15 .70
6259 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
6263 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
6264 statement that should be preferred over the @code{FLUSH} intrinsic.
6266 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
6267 have identical effect: they flush the runtime library's I/O buffer so
6268 that the data becomes visible to other processes. This does not guarantee
6269 that the data is committed to disk.
6271 On POSIX systems, you can request that all data is transferred to the
6272 storage device by calling the @code{fsync} function, with the POSIX file
6273 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
6274 @code{FNUM}). The following example shows how:
6277 ! Declare the interface for POSIX fsync function
6279 function fsync (fd) bind(c,name="fsync")
6280 use iso_c_binding, only: c_int
6281 integer(c_int), value :: fd
6282 integer(c_int) :: fsync
6286 ! Variable declaration
6290 open (10,file="foo")
6293 ! Perform I/O on unit 10
6298 ret = fsync(fnum(10))
6300 ! Handle possible error
6301 if (ret /= 0) stop "Error calling FSYNC"
6309 @section @code{FNUM} --- File number function
6311 @cindex file operation, file number
6314 @item @emph{Description}:
6315 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
6316 open Fortran I/O unit @code{UNIT}.
6318 @item @emph{Standard}:
6324 @item @emph{Syntax}:
6325 @code{RESULT = FNUM(UNIT)}
6327 @item @emph{Arguments}:
6328 @multitable @columnfractions .15 .70
6329 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
6332 @item @emph{Return value}:
6333 The return value is of type @code{INTEGER}
6335 @item @emph{Example}:
6339 open (unit=10, status = "scratch")
6343 end program test_fnum
6350 @section @code{FPUT} --- Write a single character in stream mode to stdout
6352 @cindex write character, stream mode
6353 @cindex stream mode, write character
6354 @cindex file operation, write character
6357 @item @emph{Description}:
6358 Write a single character in stream mode to stdout by bypassing normal
6359 formatted output. Stream I/O should not be mixed with normal record-oriented
6360 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
6362 This intrinsic is provided in both subroutine and function forms; however,
6363 only one form can be used in any given program unit.
6365 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
6366 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
6367 Programmers should consider the use of new stream IO feature in new code
6368 for future portability. See also @ref{Fortran 2003 status}.
6370 @item @emph{Standard}:
6374 Subroutine, function
6376 @item @emph{Syntax}:
6377 @multitable @columnfractions .80
6378 @item @code{CALL FPUT(C [, STATUS])}
6379 @item @code{STATUS = FPUT(C)}
6382 @item @emph{Arguments}:
6383 @multitable @columnfractions .15 .70
6384 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6386 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6387 Returns 0 on success, -1 on end-of-file and a system specific positive
6388 error code otherwise.
6391 @item @emph{Example}:
6394 CHARACTER(len=10) :: str = "gfortran"
6396 DO i = 1, len_trim(str)
6402 @item @emph{See also}:
6411 @section @code{FPUTC} --- Write a single character in stream mode
6413 @cindex write character, stream mode
6414 @cindex stream mode, write character
6415 @cindex file operation, write character
6418 @item @emph{Description}:
6419 Write a single character in stream mode by bypassing normal formatted
6420 output. Stream I/O should not be mixed with normal record-oriented
6421 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
6423 This intrinsic is provided in both subroutine and function forms; however,
6424 only one form can be used in any given program unit.
6426 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
6427 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
6428 Programmers should consider the use of new stream IO feature in new code
6429 for future portability. See also @ref{Fortran 2003 status}.
6431 @item @emph{Standard}:
6435 Subroutine, function
6437 @item @emph{Syntax}:
6438 @multitable @columnfractions .80
6439 @item @code{CALL FPUTC(UNIT, C [, STATUS])}
6440 @item @code{STATUS = FPUTC(UNIT, C)}
6443 @item @emph{Arguments}:
6444 @multitable @columnfractions .15 .70
6445 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
6446 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6448 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6449 Returns 0 on success, -1 on end-of-file and a system specific positive
6450 error code otherwise.
6453 @item @emph{Example}:
6456 CHARACTER(len=10) :: str = "gfortran"
6457 INTEGER :: fd = 42, i
6459 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
6460 DO i = 1, len_trim(str)
6461 CALL fputc(fd, str(i:i))
6467 @item @emph{See also}:
6476 @section @code{FRACTION} --- Fractional part of the model representation
6478 @cindex real number, fraction
6479 @cindex floating point, fraction
6482 @item @emph{Description}:
6483 @code{FRACTION(X)} returns the fractional part of the model
6484 representation of @code{X}.
6486 @item @emph{Standard}:
6487 Fortran 90 and later
6492 @item @emph{Syntax}:
6493 @code{Y = FRACTION(X)}
6495 @item @emph{Arguments}:
6496 @multitable @columnfractions .15 .70
6497 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
6500 @item @emph{Return value}:
6501 The return value is of the same type and kind as the argument.
6502 The fractional part of the model representation of @code{X} is returned;
6503 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
6505 @item @emph{Example}:
6507 program test_fraction
6510 print *, fraction(x), x * radix(x)**(-exponent(x))
6511 end program test_fraction
6519 @section @code{FREE} --- Frees memory
6521 @cindex pointer, cray
6524 @item @emph{Description}:
6525 Frees memory previously allocated by @code{MALLOC}. The @code{FREE}
6526 intrinsic is an extension intended to be used with Cray pointers, and is
6527 provided in GNU Fortran to allow user to compile legacy code. For
6528 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
6531 @item @emph{Standard}:
6537 @item @emph{Syntax}:
6538 @code{CALL FREE(PTR)}
6540 @item @emph{Arguments}:
6541 @multitable @columnfractions .15 .70
6542 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
6543 location of the memory that should be de-allocated.
6546 @item @emph{Return value}:
6549 @item @emph{Example}:
6550 See @code{MALLOC} for an example.
6552 @item @emph{See also}:
6559 @section @code{FSEEK} --- Low level file positioning subroutine
6561 @cindex file operation, seek
6562 @cindex file operation, position
6565 @item @emph{Description}:
6566 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
6567 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
6568 if set to 1, @var{OFFSET} is taken to be relative to the current position
6569 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
6570 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
6573 This intrinsic routine is not fully backwards compatible with @command{g77}.
6574 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
6575 @var{STATUS} variable. If FSEEK is used in old code, change
6577 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
6582 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
6583 IF (status /= 0) GOTO label
6586 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
6587 Programmers should consider the use of new stream IO feature in new code
6588 for future portability. See also @ref{Fortran 2003 status}.
6590 @item @emph{Standard}:
6596 @item @emph{Syntax}:
6597 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
6599 @item @emph{Arguments}:
6600 @multitable @columnfractions .15 .70
6601 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
6602 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
6603 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
6604 Its value shall be either 0, 1 or 2.
6605 @item @var{STATUS} @tab (Optional) shall be a scalar of type
6609 @item @emph{Example}:
6612 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
6613 INTEGER :: fd, offset, ierr
6619 OPEN(UNIT=fd, FILE="fseek.test")
6620 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
6621 print *, FTELL(fd), ierr
6623 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
6624 print *, FTELL(fd), ierr
6626 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
6627 print *, FTELL(fd), ierr
6633 @item @emph{See also}:
6640 @section @code{FSTAT} --- Get file status
6642 @cindex file system, file status
6645 @item @emph{Description}:
6646 @code{FSTAT} is identical to @ref{STAT}, except that information about an
6647 already opened file is obtained.
6649 The elements in @code{VALUES} are the same as described by @ref{STAT}.
6651 This intrinsic is provided in both subroutine and function forms; however,
6652 only one form can be used in any given program unit.
6654 @item @emph{Standard}:
6658 Subroutine, function
6660 @item @emph{Syntax}:
6661 @multitable @columnfractions .80
6662 @item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
6663 @item @code{STATUS = FSTAT(UNIT, VALUES)}
6666 @item @emph{Arguments}:
6667 @multitable @columnfractions .15 .70
6668 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
6669 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
6670 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
6671 on success and a system specific error code otherwise.
6674 @item @emph{Example}:
6675 See @ref{STAT} for an example.
6677 @item @emph{See also}:
6687 @section @code{FTELL} --- Current stream position
6689 @cindex file operation, position
6692 @item @emph{Description}:
6693 Retrieves the current position within an open file.
6695 This intrinsic is provided in both subroutine and function forms; however,
6696 only one form can be used in any given program unit.
6698 @item @emph{Standard}:
6702 Subroutine, function
6704 @item @emph{Syntax}:
6705 @multitable @columnfractions .80
6706 @item @code{CALL FTELL(UNIT, OFFSET)}
6707 @item @code{OFFSET = FTELL(UNIT)}
6710 @item @emph{Arguments}:
6711 @multitable @columnfractions .15 .70
6712 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
6713 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
6716 @item @emph{Return value}:
6717 In either syntax, @var{OFFSET} is set to the current offset of unit
6718 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
6720 @item @emph{Example}:
6724 OPEN(10, FILE="temp.dat")
6730 @item @emph{See also}:
6737 @section @code{GAMMA} --- Gamma function
6740 @cindex Gamma function
6741 @cindex Factorial function
6744 @item @emph{Description}:
6745 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
6746 integer values of @var{X} the Gamma function simplifies to the factorial
6747 function @math{\Gamma(x)=(x-1)!}.
6751 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
6755 @item @emph{Standard}:
6756 Fortran 2008 and later
6761 @item @emph{Syntax}:
6764 @item @emph{Arguments}:
6765 @multitable @columnfractions .15 .70
6766 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
6767 nor a negative integer.
6770 @item @emph{Return value}:
6771 The return value is of type @code{REAL} of the same kind as @var{X}.
6773 @item @emph{Example}:
6777 x = gamma(x) ! returns 1.0
6778 end program test_gamma
6781 @item @emph{Specific names}:
6782 @multitable @columnfractions .20 .23 .20 .33
6783 @headitem Name @tab Argument @tab Return type @tab Standard
6784 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
6787 @item @emph{See also}:
6788 Logarithm of the Gamma function: @*
6795 @section @code{GERROR} --- Get last system error message
6797 @cindex system, error handling
6800 @item @emph{Description}:
6801 Returns the system error message corresponding to the last system error.
6802 This resembles the functionality of @code{strerror(3)} in C.
6804 @item @emph{Standard}:
6810 @item @emph{Syntax}:
6811 @code{CALL GERROR(RESULT)}
6813 @item @emph{Arguments}:
6814 @multitable @columnfractions .15 .70
6815 @item @var{RESULT} @tab Shall be of type @code{CHARACTER} and of default kind.
6818 @item @emph{Example}:
6821 CHARACTER(len=100) :: msg
6827 @item @emph{See also}:
6835 @section @code{GETARG} --- Get command line arguments
6837 @cindex command-line arguments
6838 @cindex arguments, to program
6841 @item @emph{Description}:
6842 Retrieve the @var{POS}-th argument that was passed on the
6843 command line when the containing program was invoked.
6845 This intrinsic routine is provided for backwards compatibility with
6846 GNU Fortran 77. In new code, programmers should consider the use of
6847 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
6850 @item @emph{Standard}:
6856 @item @emph{Syntax}:
6857 @code{CALL GETARG(POS, VALUE)}
6859 @item @emph{Arguments}:
6860 @multitable @columnfractions .15 .70
6861 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
6862 the default integer kind; @math{@var{POS} \geq 0}
6863 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
6867 @item @emph{Return value}:
6868 After @code{GETARG} returns, the @var{VALUE} argument holds the
6869 @var{POS}th command line argument. If @var{VALUE} cannot hold the
6870 argument, it is truncated to fit the length of @var{VALUE}. If there are
6871 less than @var{POS} arguments specified at the command line, @var{VALUE}
6872 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
6873 to the name of the program (on systems that support this feature).
6875 @item @emph{Example}:
6879 CHARACTER(len=32) :: arg
6888 @item @emph{See also}:
6889 GNU Fortran 77 compatibility function: @*
6891 Fortran 2003 functions and subroutines: @*
6892 @ref{GET_COMMAND}, @*
6893 @ref{GET_COMMAND_ARGUMENT}, @*
6894 @ref{COMMAND_ARGUMENT_COUNT}
6900 @section @code{GET_COMMAND} --- Get the entire command line
6901 @fnindex GET_COMMAND
6902 @cindex command-line arguments
6903 @cindex arguments, to program
6906 @item @emph{Description}:
6907 Retrieve the entire command line that was used to invoke the program.
6909 @item @emph{Standard}:
6910 Fortran 2003 and later
6915 @item @emph{Syntax}:
6916 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
6918 @item @emph{Arguments}:
6919 @multitable @columnfractions .15 .70
6920 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
6922 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
6924 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
6928 @item @emph{Return value}:
6929 If @var{COMMAND} is present, stores the entire command line that was used
6930 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
6931 assigned the length of the command line. If @var{STATUS} is present, it
6932 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
6933 short to store the command line, or a positive value in case of an error.
6935 @item @emph{Example}:
6937 PROGRAM test_get_command
6938 CHARACTER(len=255) :: cmd
6939 CALL get_command(cmd)
6940 WRITE (*,*) TRIM(cmd)
6944 @item @emph{See also}:
6945 @ref{GET_COMMAND_ARGUMENT}, @*
6946 @ref{COMMAND_ARGUMENT_COUNT}
6951 @node GET_COMMAND_ARGUMENT
6952 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
6953 @fnindex GET_COMMAND_ARGUMENT
6954 @cindex command-line arguments
6955 @cindex arguments, to program
6958 @item @emph{Description}:
6959 Retrieve the @var{NUMBER}-th argument that was passed on the
6960 command line when the containing program was invoked.
6962 @item @emph{Standard}:
6963 Fortran 2003 and later
6968 @item @emph{Syntax}:
6969 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
6971 @item @emph{Arguments}:
6972 @multitable @columnfractions .15 .70
6973 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
6974 default kind, @math{@var{NUMBER} \geq 0}
6975 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
6976 and of default kind.
6977 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6978 and of default kind.
6979 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6980 and of default kind.
6983 @item @emph{Return value}:
6984 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
6985 @var{NUMBER}-th command line argument. If @var{VALUE} cannot hold the argument, it is
6986 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
6987 arguments specified at the command line, @var{VALUE} will be filled with blanks.
6988 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
6989 systems that support this feature). The @var{LENGTH} argument contains the
6990 length of the @var{NUMBER}-th command line argument. If the argument retrieval
6991 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
6992 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
6995 @item @emph{Example}:
6997 PROGRAM test_get_command_argument
6999 CHARACTER(len=32) :: arg
7003 CALL get_command_argument(i, arg)
7004 IF (LEN_TRIM(arg) == 0) EXIT
7006 WRITE (*,*) TRIM(arg)
7012 @item @emph{See also}:
7013 @ref{GET_COMMAND}, @*
7014 @ref{COMMAND_ARGUMENT_COUNT}
7020 @section @code{GETCWD} --- Get current working directory
7022 @cindex system, working directory
7025 @item @emph{Description}:
7026 Get current working directory.
7028 This intrinsic is provided in both subroutine and function forms; however,
7029 only one form can be used in any given program unit.
7031 @item @emph{Standard}:
7035 Subroutine, function
7037 @item @emph{Syntax}:
7038 @multitable @columnfractions .80
7039 @item @code{CALL GETCWD(C [, STATUS])}
7040 @item @code{STATUS = GETCWD(C)}
7043 @item @emph{Arguments}:
7044 @multitable @columnfractions .15 .70
7045 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
7046 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
7047 a system specific and nonzero error code otherwise.
7050 @item @emph{Example}:
7053 CHARACTER(len=255) :: cwd
7055 WRITE(*,*) TRIM(cwd)
7059 @item @emph{See also}:
7066 @section @code{GETENV} --- Get an environmental variable
7068 @cindex environment variable
7071 @item @emph{Description}:
7072 Get the @var{VALUE} of the environmental variable @var{NAME}.
7074 This intrinsic routine is provided for backwards compatibility with
7075 GNU Fortran 77. In new code, programmers should consider the use of
7076 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
7079 Note that @code{GETENV} need not be thread-safe. It is the
7080 responsibility of the user to ensure that the environment is not being
7081 updated concurrently with a call to the @code{GETENV} intrinsic.
7083 @item @emph{Standard}:
7089 @item @emph{Syntax}:
7090 @code{CALL GETENV(NAME, VALUE)}
7092 @item @emph{Arguments}:
7093 @multitable @columnfractions .15 .70
7094 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
7095 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
7098 @item @emph{Return value}:
7099 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
7100 not large enough to hold the data, it is truncated. If @var{NAME}
7101 is not set, @var{VALUE} will be filled with blanks.
7103 @item @emph{Example}:
7106 CHARACTER(len=255) :: homedir
7107 CALL getenv("HOME", homedir)
7108 WRITE (*,*) TRIM(homedir)
7112 @item @emph{See also}:
7113 @ref{GET_ENVIRONMENT_VARIABLE}
7118 @node GET_ENVIRONMENT_VARIABLE
7119 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
7120 @fnindex GET_ENVIRONMENT_VARIABLE
7121 @cindex environment variable
7124 @item @emph{Description}:
7125 Get the @var{VALUE} of the environmental variable @var{NAME}.
7127 Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It
7128 is the responsibility of the user to ensure that the environment is
7129 not being updated concurrently with a call to the
7130 @code{GET_ENVIRONMENT_VARIABLE} intrinsic.
7132 @item @emph{Standard}:
7133 Fortran 2003 and later
7138 @item @emph{Syntax}:
7139 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
7141 @item @emph{Arguments}:
7142 @multitable @columnfractions .15 .70
7143 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
7144 and of default kind.
7145 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
7146 and of default kind.
7147 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
7148 and of default kind.
7149 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
7150 and of default kind.
7151 @item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL}
7152 and of default kind.
7155 @item @emph{Return value}:
7156 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
7157 not large enough to hold the data, it is truncated. If @var{NAME}
7158 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
7159 contains the length needed for storing the environment variable @var{NAME}
7160 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
7161 but too short for the environment variable; it is 1 if the environment
7162 variable does not exist and 2 if the processor does not support environment
7163 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
7164 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
7165 are significant; otherwise they are not part of the environment variable
7168 @item @emph{Example}:
7171 CHARACTER(len=255) :: homedir
7172 CALL get_environment_variable("HOME", homedir)
7173 WRITE (*,*) TRIM(homedir)
7181 @section @code{GETGID} --- Group ID function
7183 @cindex system, group ID
7186 @item @emph{Description}:
7187 Returns the numerical group ID of the current process.
7189 @item @emph{Standard}:
7195 @item @emph{Syntax}:
7196 @code{RESULT = GETGID()}
7198 @item @emph{Return value}:
7199 The return value of @code{GETGID} is an @code{INTEGER} of the default
7203 @item @emph{Example}:
7204 See @code{GETPID} for an example.
7206 @item @emph{See also}:
7214 @section @code{GETLOG} --- Get login name
7216 @cindex system, login name
7220 @item @emph{Description}:
7221 Gets the username under which the program is running.
7223 @item @emph{Standard}:
7229 @item @emph{Syntax}:
7230 @code{CALL GETLOG(C)}
7232 @item @emph{Arguments}:
7233 @multitable @columnfractions .15 .70
7234 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
7237 @item @emph{Return value}:
7238 Stores the current user name in @var{C}. (On systems where POSIX
7239 functions @code{geteuid} and @code{getpwuid} are not available, and
7240 the @code{getlogin} function is not implemented either, this will
7241 return a blank string.)
7243 @item @emph{Example}:
7246 CHARACTER(32) :: login
7252 @item @emph{See also}:
7259 @section @code{GETPID} --- Process ID function
7261 @cindex system, process ID
7265 @item @emph{Description}:
7266 Returns the numerical process identifier of the current process.
7268 @item @emph{Standard}:
7274 @item @emph{Syntax}:
7275 @code{RESULT = GETPID()}
7277 @item @emph{Return value}:
7278 The return value of @code{GETPID} is an @code{INTEGER} of the default
7282 @item @emph{Example}:
7285 print *, "The current process ID is ", getpid()
7286 print *, "Your numerical user ID is ", getuid()
7287 print *, "Your numerical group ID is ", getgid()
7291 @item @emph{See also}:
7299 @section @code{GETUID} --- User ID function
7301 @cindex system, user ID
7305 @item @emph{Description}:
7306 Returns the numerical user ID of the current process.
7308 @item @emph{Standard}:
7314 @item @emph{Syntax}:
7315 @code{RESULT = GETUID()}
7317 @item @emph{Return value}:
7318 The return value of @code{GETUID} is an @code{INTEGER} of the default
7322 @item @emph{Example}:
7323 See @code{GETPID} for an example.
7325 @item @emph{See also}:
7333 @section @code{GMTIME} --- Convert time to GMT info
7335 @cindex time, conversion to GMT info
7338 @item @emph{Description}:
7339 Given a system time value @var{TIME} (as provided by the @ref{TIME}
7340 intrinsic), fills @var{VALUES} with values extracted from it appropriate
7341 to the UTC time zone (Universal Coordinated Time, also known in some
7342 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
7344 This intrinsic routine is provided for backwards compatibility with
7345 GNU Fortran 77. In new code, programmers should consider the use of
7346 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
7349 @item @emph{Standard}:
7355 @item @emph{Syntax}:
7356 @code{CALL GMTIME(TIME, VALUES)}
7358 @item @emph{Arguments}:
7359 @multitable @columnfractions .15 .70
7360 @item @var{TIME} @tab An @code{INTEGER} scalar expression
7361 corresponding to a system time, with @code{INTENT(IN)}.
7362 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
7363 with @code{INTENT(OUT)}.
7366 @item @emph{Return value}:
7367 The elements of @var{VALUES} are assigned as follows:
7369 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
7371 @item Minutes after the hour, range 0--59
7372 @item Hours past midnight, range 0--23
7373 @item Day of month, range 1--31
7374 @item Number of months since January, range 0--11
7375 @item Years since 1900
7376 @item Number of days since Sunday, range 0--6
7377 @item Days since January 1, range 0--365
7378 @item Daylight savings indicator: positive if daylight savings is in
7379 effect, zero if not, and negative if the information is not available.
7382 @item @emph{See also}:
7383 @ref{DATE_AND_TIME}, @*
7393 @section @code{HOSTNM} --- Get system host name
7395 @cindex system, host name
7398 @item @emph{Description}:
7399 Retrieves the host name of the system on which the program is running.
7401 This intrinsic is provided in both subroutine and function forms; however,
7402 only one form can be used in any given program unit.
7404 @item @emph{Standard}:
7408 Subroutine, function
7410 @item @emph{Syntax}:
7411 @multitable @columnfractions .80
7412 @item @code{CALL HOSTNM(C [, STATUS])}
7413 @item @code{STATUS = HOSTNM(NAME)}
7416 @item @emph{Arguments}:
7417 @multitable @columnfractions .15 .70
7418 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
7419 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
7420 Returns 0 on success, or a system specific error code otherwise.
7423 @item @emph{Return value}:
7424 In either syntax, @var{NAME} is set to the current hostname if it can
7425 be obtained, or to a blank string otherwise.
7432 @section @code{HUGE} --- Largest number of a kind
7434 @cindex limits, largest number
7435 @cindex model representation, largest number
7438 @item @emph{Description}:
7439 @code{HUGE(X)} returns the largest number that is not an infinity in
7440 the model of the type of @code{X}.
7442 @item @emph{Standard}:
7443 Fortran 90 and later
7448 @item @emph{Syntax}:
7449 @code{RESULT = HUGE(X)}
7451 @item @emph{Arguments}:
7452 @multitable @columnfractions .15 .70
7453 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
7456 @item @emph{Return value}:
7457 The return value is of the same type and kind as @var{X}
7459 @item @emph{Example}:
7461 program test_huge_tiny
7462 print *, huge(0), huge(0.0), huge(0.0d0)
7463 print *, tiny(0.0), tiny(0.0d0)
7464 end program test_huge_tiny
7471 @section @code{HYPOT} --- Euclidean distance function
7473 @cindex Euclidean distance
7476 @item @emph{Description}:
7477 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
7478 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
7480 @item @emph{Standard}:
7481 Fortran 2008 and later
7486 @item @emph{Syntax}:
7487 @code{RESULT = HYPOT(X, Y)}
7489 @item @emph{Arguments}:
7490 @multitable @columnfractions .15 .70
7491 @item @var{X} @tab The type shall be @code{REAL}.
7492 @item @var{Y} @tab The type and kind type parameter shall be the same as
7496 @item @emph{Return value}:
7497 The return value has the same type and kind type parameter as @var{X}.
7499 @item @emph{Example}:
7502 real(4) :: x = 1.e0_4, y = 0.5e0_4
7504 end program test_hypot
7511 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
7513 @cindex @acronym{ASCII} collating sequence
7514 @cindex collating sequence, @acronym{ASCII}
7515 @cindex conversion, to integer
7518 @item @emph{Description}:
7519 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
7520 in the first character position of @code{C}.
7522 @item @emph{Standard}:
7523 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7528 @item @emph{Syntax}:
7529 @code{RESULT = IACHAR(C [, KIND])}
7531 @item @emph{Arguments}:
7532 @multitable @columnfractions .15 .70
7533 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
7534 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
7535 expression indicating the kind parameter of the result.
7538 @item @emph{Return value}:
7539 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7540 @var{KIND} is absent, the return value is of default integer kind.
7542 @item @emph{Example}:
7547 end program test_iachar
7551 See @ref{ICHAR} for a discussion of converting between numerical values
7552 and formatted string representations.
7554 @item @emph{See also}:
7563 @section @code{IALL} --- Bitwise AND of array elements
7566 @cindex bits, AND of array elements
7569 @item @emph{Description}:
7570 Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
7571 if the corresponding element in @var{MASK} is @code{TRUE}.
7573 @item @emph{Standard}:
7574 Fortran 2008 and later
7577 Transformational function
7579 @item @emph{Syntax}:
7580 @multitable @columnfractions .80
7581 @item @code{RESULT = IALL(ARRAY[, MASK])}
7582 @item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
7585 @item @emph{Arguments}:
7586 @multitable @columnfractions .15 .70
7587 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7588 @item @var{DIM} @tab (Optional) shall be a scalar of type
7589 @code{INTEGER} with a value in the range from 1 to n, where n
7590 equals the rank of @var{ARRAY}.
7591 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
7592 and either be a scalar or an array of the same shape as @var{ARRAY}.
7595 @item @emph{Return value}:
7596 The result is of the same type as @var{ARRAY}.
7598 If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
7599 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7600 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7601 dimension @var{DIM} dropped is returned.
7603 @item @emph{Example}:
7612 PRINT '(b8.8)', IALL(a)
7616 @item @emph{See also}:
7625 @section @code{IAND} --- Bitwise logical and
7631 @cindex bitwise logical and
7632 @cindex logical and, bitwise
7635 @item @emph{Description}:
7636 Bitwise logical @code{AND}.
7638 @item @emph{Standard}:
7639 Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions
7644 @item @emph{Syntax}:
7645 @code{RESULT = IAND(I, J)}
7647 @item @emph{Arguments}:
7648 @multitable @columnfractions .15 .70
7649 @item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant.
7650 @item @var{J} @tab The type shall be @code{INTEGER} with the same
7651 kind type parameter as @var{I} or a boz-literal-constant.
7652 @var{I} and @var{J} shall not both be boz-literal-constants.
7655 @item @emph{Return value}:
7656 The return type is @code{INTEGER} with the kind type parameter of the
7658 A boz-literal-constant is converted to an @code{INTEGER} with the kind
7659 type parameter of the other argument as-if a call to @ref{INT} occurred.
7661 @item @emph{Example}:
7665 DATA a / Z'F' /, b / Z'3' /
7666 WRITE (*,*) IAND(a, b)
7670 @item @emph{Specific names}:
7671 @multitable @columnfractions .20 .23 .20 .33
7672 @headitem Name @tab Argument @tab Return type @tab Standard
7673 @item @code{IAND(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
7674 @item @code{BIAND(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7675 @item @code{IIAND(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7676 @item @code{JIAND(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7677 @item @code{KIAND(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7680 @item @emph{See also}:
7692 @section @code{IANY} --- Bitwise OR of array elements
7695 @cindex bits, OR of array elements
7698 @item @emph{Description}:
7699 Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
7700 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
7702 @item @emph{Standard}:
7703 Fortran 2008 and later
7706 Transformational function
7708 @item @emph{Syntax}:
7709 @multitable @columnfractions .80
7710 @item @code{RESULT = IANY(ARRAY[, MASK])}
7711 @item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
7714 @item @emph{Arguments}:
7715 @multitable @columnfractions .15 .70
7716 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7717 @item @var{DIM} @tab (Optional) shall be a scalar of type
7718 @code{INTEGER} with a value in the range from 1 to n, where n
7719 equals the rank of @var{ARRAY}.
7720 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
7721 and either be a scalar or an array of the same shape as @var{ARRAY}.
7724 @item @emph{Return value}:
7725 The result is of the same type as @var{ARRAY}.
7727 If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
7728 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7729 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7730 dimension @var{DIM} dropped is returned.
7732 @item @emph{Example}:
7741 PRINT '(b8.8)', IANY(a)
7745 @item @emph{See also}:
7754 @section @code{IARGC} --- Get the number of command line arguments
7756 @cindex command-line arguments
7757 @cindex command-line arguments, number of
7758 @cindex arguments, to program
7761 @item @emph{Description}:
7762 @code{IARGC} returns the number of arguments passed on the
7763 command line when the containing program was invoked.
7765 This intrinsic routine is provided for backwards compatibility with
7766 GNU Fortran 77. In new code, programmers should consider the use of
7767 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
7770 @item @emph{Standard}:
7776 @item @emph{Syntax}:
7777 @code{RESULT = IARGC()}
7779 @item @emph{Arguments}:
7782 @item @emph{Return value}:
7783 The number of command line arguments, type @code{INTEGER(4)}.
7785 @item @emph{Example}:
7788 @item @emph{See also}:
7789 GNU Fortran 77 compatibility subroutine: @*
7791 Fortran 2003 functions and subroutines: @*
7792 @ref{GET_COMMAND}, @*
7793 @ref{GET_COMMAND_ARGUMENT}, @*
7794 @ref{COMMAND_ARGUMENT_COUNT}
7800 @section @code{IBCLR} --- Clear bit
7810 @item @emph{Description}:
7811 @code{IBCLR} returns the value of @var{I} with the bit at position
7812 @var{POS} set to zero.
7814 @item @emph{Standard}:
7815 Fortran 90 and later, has overloads that are GNU extensions
7820 @item @emph{Syntax}:
7821 @code{RESULT = IBCLR(I, POS)}
7823 @item @emph{Arguments}:
7824 @multitable @columnfractions .15 .70
7825 @item @var{I} @tab The type shall be @code{INTEGER}.
7826 @item @var{POS} @tab The type shall be @code{INTEGER}.
7829 @item @emph{Return value}:
7830 The return value is of type @code{INTEGER} and of the same kind as
7833 @item @emph{Specific names}:
7834 @multitable @columnfractions .20 .23 .20 .33
7835 @headitem Name @tab Argument @tab Return type @tab Standard
7836 @item @code{IBCLR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
7837 @item @code{BBCLR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7838 @item @code{IIBCLR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7839 @item @code{JIBCLR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7840 @item @code{KIBCLR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7843 @item @emph{See also}:
7855 @section @code{IBITS} --- Bit extraction
7862 @cindex bits, extract
7865 @item @emph{Description}:
7866 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
7867 starting from bit position @var{POS} and extending left for @var{LEN}
7868 bits. The result is right-justified and the remaining bits are
7869 zeroed. The value of @code{POS+LEN} must be less than or equal to the
7870 value @code{BIT_SIZE(I)}.
7872 @item @emph{Standard}:
7873 Fortran 90 and later, has overloads that are GNU extensions
7878 @item @emph{Syntax}:
7879 @code{RESULT = IBITS(I, POS, LEN)}
7881 @item @emph{Arguments}:
7882 @multitable @columnfractions .15 .70
7883 @item @var{I} @tab The type shall be @code{INTEGER}.
7884 @item @var{POS} @tab The type shall be @code{INTEGER}.
7885 @item @var{LEN} @tab The type shall be @code{INTEGER}.
7888 @item @emph{Return value}:
7889 The return value is of type @code{INTEGER} and of the same kind as
7892 @item @emph{Specific names}:
7893 @multitable @columnfractions .20 .23 .20 .33
7894 @headitem Name @tab Argument @tab Return type @tab Standard
7895 @item @code{IBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
7896 @item @code{BBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7897 @item @code{IIBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7898 @item @code{JIBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7899 @item @code{KIBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7902 @item @emph{See also}:
7914 @section @code{IBSET} --- Set bit
7923 @item @emph{Description}:
7924 @code{IBSET} returns the value of @var{I} with the bit at position
7925 @var{POS} set to one.
7927 @item @emph{Standard}:
7928 Fortran 90 and later, has overloads that are GNU extensions
7933 @item @emph{Syntax}:
7934 @code{RESULT = IBSET(I, POS)}
7936 @item @emph{Arguments}:
7937 @multitable @columnfractions .15 .70
7938 @item @var{I} @tab The type shall be @code{INTEGER}.
7939 @item @var{POS} @tab The type shall be @code{INTEGER}.
7942 @item @emph{Return value}:
7943 The return value is of type @code{INTEGER} and of the same kind as
7946 @item @emph{Specific names}:
7947 @multitable @columnfractions .20 .23 .20 .33
7948 @headitem Name @tab Argument @tab Return type @tab Standard
7949 @item @code{IBSET(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
7950 @item @code{BBSET(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7951 @item @code{IIBSET(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7952 @item @code{JIBSET(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7953 @item @code{KIBSET(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7956 @item @emph{See also}:
7968 @section @code{ICHAR} --- Character-to-integer conversion function
7970 @cindex conversion, to integer
7973 @item @emph{Description}:
7974 @code{ICHAR(C)} returns the code for the character in the first character
7975 position of @code{C} in the system's native character set.
7976 The correspondence between characters and their codes is not necessarily
7977 the same across different GNU Fortran implementations.
7979 @item @emph{Standard}:
7980 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
7985 @item @emph{Syntax}:
7986 @code{RESULT = ICHAR(C [, KIND])}
7988 @item @emph{Arguments}:
7989 @multitable @columnfractions .15 .70
7990 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
7991 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
7992 expression indicating the kind parameter of the result.
7995 @item @emph{Return value}:
7996 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7997 @var{KIND} is absent, the return value is of default integer kind.
7999 @item @emph{Example}:
8004 end program test_ichar
8007 @item @emph{Specific names}:
8008 @multitable @columnfractions .20 .23 .20 .33
8009 @headitem Name @tab Argument @tab Return type @tab Standard
8010 @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8014 No intrinsic exists to convert between a numeric value and a formatted
8015 character string representation -- for instance, given the
8016 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
8017 @code{REAL} value with the value 154, or vice versa. Instead, this
8018 functionality is provided by internal-file I/O, as in the following
8023 character(len=10) string, string2
8026 ! Convert a string to a numeric value
8027 read (string,'(I10)') value
8030 ! Convert a value to a formatted string
8031 write (string2,'(I10)') value
8033 end program read_val
8036 @item @emph{See also}:
8045 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
8047 @cindex date, current
8048 @cindex current date
8051 @item @emph{Description}:
8052 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
8053 current local time. The day (in the range 1-31), month (in the range 1-12),
8054 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
8055 The year has four significant digits.
8057 This intrinsic routine is provided for backwards compatibility with
8058 GNU Fortran 77. In new code, programmers should consider the use of
8059 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
8062 @item @emph{Standard}:
8068 @item @emph{Syntax}:
8069 @code{CALL IDATE(VALUES)}
8071 @item @emph{Arguments}:
8072 @multitable @columnfractions .15 .70
8073 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
8074 the kind shall be the default integer kind.
8077 @item @emph{Return value}:
8078 Does not return anything.
8080 @item @emph{Example}:
8083 integer, dimension(3) :: tarray
8088 end program test_idate
8091 @item @emph{See also}:
8097 @section @code{IEOR} --- Bitwise logical exclusive or
8103 @cindex bitwise logical exclusive or
8104 @cindex logical exclusive or, bitwise
8107 @item @emph{Description}:
8108 @code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
8111 @item @emph{Standard}:
8112 Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions
8117 @item @emph{Syntax}:
8118 @code{RESULT = IEOR(I, J)}
8120 @item @emph{Arguments}:
8121 @multitable @columnfractions .15 .70
8122 @item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant.
8123 @item @var{J} @tab The type shall be @code{INTEGER} with the same
8124 kind type parameter as @var{I} or a boz-literal-constant.
8125 @var{I} and @var{J} shall not both be boz-literal-constants.
8128 @item @emph{Return value}:
8129 The return type is @code{INTEGER} with the kind type parameter of the
8131 A boz-literal-constant is converted to an @code{INTEGER} with the kind
8132 type parameter of the other argument as-if a call to @ref{INT} occurred.
8134 @item @emph{Specific names}:
8135 @multitable @columnfractions .20 .23 .20 .33
8136 @headitem Name @tab Argument @tab Return type @tab Standard
8137 @item @code{IEOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
8138 @item @code{BIEOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8139 @item @code{IIEOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8140 @item @code{JIEOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8141 @item @code{KIEOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8144 @item @emph{See also}:
8156 @section @code{IERRNO} --- Get the last system error number
8158 @cindex system, error handling
8161 @item @emph{Description}:
8162 Returns the last system error number, as given by the C @code{errno}
8165 @item @emph{Standard}:
8171 @item @emph{Syntax}:
8172 @code{RESULT = IERRNO()}
8174 @item @emph{Arguments}:
8177 @item @emph{Return value}:
8178 The return value is of type @code{INTEGER} and of the default integer
8181 @item @emph{See also}:
8188 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
8189 @fnindex IMAGE_INDEX
8190 @cindex coarray, @code{IMAGE_INDEX}
8191 @cindex images, cosubscript to image index conversion
8194 @item @emph{Description}:
8195 Returns the image index belonging to a cosubscript.
8197 @item @emph{Standard}:
8198 Fortran 2008 and later
8203 @item @emph{Syntax}:
8204 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
8206 @item @emph{Arguments}:
8207 @multitable @columnfractions .15 .70
8208 @item @var{COARRAY} @tab Coarray of any type.
8209 @item @var{SUB} @tab default integer rank-1 array of a size equal to
8210 the corank of @var{COARRAY}.
8214 @item @emph{Return value}:
8215 Scalar default integer with the value of the image index which corresponds
8216 to the cosubscripts. For invalid cosubscripts the result is zero.
8218 @item @emph{Example}:
8220 INTEGER :: array[2,-1:4,8,*]
8221 ! Writes 28 (or 0 if there are fewer than 28 images)
8222 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
8225 @item @emph{See also}:
8226 @ref{THIS_IMAGE}, @*
8232 @node INDEX intrinsic
8233 @section @code{INDEX} --- Position of a substring within a string
8235 @cindex substring position
8236 @cindex string, find substring
8239 @item @emph{Description}:
8240 Returns the position of the start of the first occurrence of string
8241 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
8242 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
8243 the @var{BACK} argument is present and true, the return value is the
8244 start of the last occurrence rather than the first.
8246 @item @emph{Standard}:
8247 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
8252 @item @emph{Syntax}:
8253 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
8255 @item @emph{Arguments}:
8256 @multitable @columnfractions .15 .70
8257 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
8259 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
8261 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
8263 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
8264 expression indicating the kind parameter of the result.
8267 @item @emph{Return value}:
8268 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8269 @var{KIND} is absent, the return value is of default integer kind.
8271 @item @emph{Specific names}:
8272 @multitable @columnfractions .35 .15 .17 .30
8273 @headitem Name @tab Argument @tab Return type @tab Standard
8274 @item @code{INDEX(STRING,SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8277 @item @emph{See also}:
8285 @section @code{INT} --- Convert to integer type
8289 @cindex conversion, to integer
8292 @item @emph{Description}:
8293 Convert to integer type
8295 @item @emph{Standard}:
8296 Fortran 77 and later, with boz-literal-constant Fortran 2008 and later.
8301 @item @emph{Syntax}:
8302 @code{RESULT = INT(A [, KIND))}
8304 @item @emph{Arguments}:
8305 @multitable @columnfractions .15 .70
8306 @item @var{A} @tab Shall be of type @code{INTEGER},
8307 @code{REAL}, or @code{COMPLEX} or a boz-literal-constant.
8308 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
8309 expression indicating the kind parameter of the result.
8312 @item @emph{Return value}:
8313 These functions return a @code{INTEGER} variable or array under
8314 the following rules:
8318 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
8320 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)}
8321 equals @code{0}. If @math{|A| \geq 1}, then @code{INT(A)} is the integer
8322 whose magnitude is the largest integer that does not exceed the magnitude
8323 of @var{A} and whose sign is the same as the sign of @var{A}.
8325 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
8328 @item @emph{Example}:
8332 complex :: z = (-3.7, 1.0)
8334 print *, int(z), int(z,8)
8338 @item @emph{Specific names}:
8339 @multitable @columnfractions .20 .23 .20 .33
8340 @headitem Name @tab Argument @tab Return type @tab Standard
8341 @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
8342 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
8343 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
8350 @section @code{INT2} --- Convert to 16-bit integer type
8352 @cindex conversion, to integer
8355 @item @emph{Description}:
8356 Convert to a @code{KIND=2} integer type. This is equivalent to the
8357 standard @code{INT} intrinsic with an optional argument of
8358 @code{KIND=2}, and is only included for backwards compatibility.
8360 @item @emph{Standard}:
8366 @item @emph{Syntax}:
8367 @code{RESULT = INT2(A)}
8369 @item @emph{Arguments}:
8370 @multitable @columnfractions .15 .70
8371 @item @var{A} @tab Shall be of type @code{INTEGER},
8372 @code{REAL}, or @code{COMPLEX}.
8375 @item @emph{Return value}:
8376 The return value is a @code{INTEGER(2)} variable.
8378 @item @emph{See also}:
8386 @section @code{INT8} --- Convert to 64-bit integer type
8388 @cindex conversion, to integer
8391 @item @emph{Description}:
8392 Convert to a @code{KIND=8} integer type. This is equivalent to the
8393 standard @code{INT} intrinsic with an optional argument of
8394 @code{KIND=8}, and is only included for backwards compatibility.
8396 @item @emph{Standard}:
8402 @item @emph{Syntax}:
8403 @code{RESULT = INT8(A)}
8405 @item @emph{Arguments}:
8406 @multitable @columnfractions .15 .70
8407 @item @var{A} @tab Shall be of type @code{INTEGER},
8408 @code{REAL}, or @code{COMPLEX}.
8411 @item @emph{Return value}:
8412 The return value is a @code{INTEGER(8)} variable.
8414 @item @emph{See also}:
8422 @section @code{IOR} --- Bitwise logical or
8428 @cindex bitwise logical or
8429 @cindex logical or, bitwise
8432 @item @emph{Description}:
8433 @code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
8436 @item @emph{Standard}:
8437 Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions
8442 @item @emph{Syntax}:
8443 @code{RESULT = IOR(I, J)}
8445 @item @emph{Arguments}:
8446 @multitable @columnfractions .15 .70
8447 @item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant.
8448 @item @var{J} @tab The type shall be @code{INTEGER} with the same
8449 kind type parameter as @var{I} or a boz-literal-constant.
8450 @var{I} and @var{J} shall not both be boz-literal-constants.
8453 @item @emph{Return value}:
8454 The return type is @code{INTEGER} with the kind type parameter of the
8456 A boz-literal-constant is converted to an @code{INTEGER} with the kind
8457 type parameter of the other argument as-if a call to @ref{INT} occurred.
8459 @item @emph{Specific names}:
8460 @multitable @columnfractions .20 .23 .20 .33
8461 @headitem Name @tab Argument @tab Return type @tab Standard
8462 @item @code{IOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
8463 @item @code{BIOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8464 @item @code{IIOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8465 @item @code{JIOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8466 @item @code{KIOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8469 @item @emph{See also}:
8481 @section @code{IPARITY} --- Bitwise XOR of array elements
8483 @cindex array, parity
8485 @cindex bits, XOR of array elements
8488 @item @emph{Description}:
8489 Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
8490 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
8492 @item @emph{Standard}:
8493 Fortran 2008 and later
8496 Transformational function
8498 @item @emph{Syntax}:
8499 @multitable @columnfractions .80
8500 @item @code{RESULT = IPARITY(ARRAY[, MASK])}
8501 @item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
8504 @item @emph{Arguments}:
8505 @multitable @columnfractions .15 .70
8506 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
8507 @item @var{DIM} @tab (Optional) shall be a scalar of type
8508 @code{INTEGER} with a value in the range from 1 to n, where n
8509 equals the rank of @var{ARRAY}.
8510 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
8511 and either be a scalar or an array of the same shape as @var{ARRAY}.
8514 @item @emph{Return value}:
8515 The result is of the same type as @var{ARRAY}.
8517 If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
8518 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
8519 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
8520 dimension @var{DIM} dropped is returned.
8522 @item @emph{Example}:
8524 PROGRAM test_iparity
8527 a(1) = int(b'00100100', 1)
8528 a(2) = int(b'01101010', 1)
8531 PRINT '(b8.8)', IPARITY(a)
8535 @item @emph{See also}:
8545 @section @code{IRAND} --- Integer pseudo-random number
8547 @cindex random number generation
8550 @item @emph{Description}:
8551 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
8552 distribution between 0 and a system-dependent limit (which is in most
8553 cases 2147483647). If @var{FLAG} is 0, the next number
8554 in the current sequence is returned; if @var{FLAG} is 1, the generator
8555 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
8556 it is used as a new seed with @code{SRAND}.
8558 This intrinsic routine is provided for backwards compatibility with
8559 GNU Fortran 77. It implements a simple modulo generator as provided
8560 by @command{g77}. For new code, one should consider the use of
8561 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
8563 @item @emph{Standard}:
8569 @item @emph{Syntax}:
8570 @code{RESULT = IRAND(I)}
8572 @item @emph{Arguments}:
8573 @multitable @columnfractions .15 .70
8574 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
8577 @item @emph{Return value}:
8578 The return value is of @code{INTEGER(kind=4)} type.
8580 @item @emph{Example}:
8583 integer,parameter :: seed = 86456
8586 print *, irand(), irand(), irand(), irand()
8587 print *, irand(seed), irand(), irand(), irand()
8588 end program test_irand
8596 @section @code{IS_CONTIGUOUS} --- Test whether an array is contiguous
8597 @fnindex IS_IOSTAT_EOR
8598 @cindex array, contiguity
8601 @item @emph{Description}:
8602 @code{IS_CONTIGUOUS} tests whether an array is contiguous.
8604 @item @emph{Standard}:
8605 Fortran 2008 and later
8610 @item @emph{Syntax}:
8611 @code{RESULT = IS_CONTIGUOUS(ARRAY)}
8613 @item @emph{Arguments}:
8614 @multitable @columnfractions .15 .70
8615 @item @var{ARRAY} @tab Shall be an array of any type.
8618 @item @emph{Return value}:
8619 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
8620 @var{ARRAY} is contiguous and false otherwise.
8622 @item @emph{Example}:
8626 a = [1,2,3,4,5,6,7,8,9,10]
8627 call sub (a) ! every element, is contiguous
8628 call sub (a(::2)) ! every other element, is noncontiguous
8632 if (is_contiguous (x)) then
8633 write (*,*) 'X is contiguous'
8635 write (*,*) 'X is not contiguous'
8645 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
8646 @fnindex IS_IOSTAT_END
8647 @cindex @code{IOSTAT}, end of file
8650 @item @emph{Description}:
8651 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
8652 status ``end of file''. The function is equivalent to comparing the variable
8653 with the @code{IOSTAT_END} parameter of the intrinsic module
8654 @code{ISO_FORTRAN_ENV}.
8656 @item @emph{Standard}:
8657 Fortran 2003 and later
8662 @item @emph{Syntax}:
8663 @code{RESULT = IS_IOSTAT_END(I)}
8665 @item @emph{Arguments}:
8666 @multitable @columnfractions .15 .70
8667 @item @var{I} @tab Shall be of the type @code{INTEGER}.
8670 @item @emph{Return value}:
8671 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
8672 @var{I} has the value which indicates an end of file condition for
8673 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
8675 @item @emph{Example}:
8680 OPEN(88, FILE='test.dat')
8681 READ(88, *, IOSTAT=stat) i
8682 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
8690 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
8691 @fnindex IS_IOSTAT_EOR
8692 @cindex @code{IOSTAT}, end of record
8695 @item @emph{Description}:
8696 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
8697 status ``end of record''. The function is equivalent to comparing the
8698 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
8699 @code{ISO_FORTRAN_ENV}.
8701 @item @emph{Standard}:
8702 Fortran 2003 and later
8707 @item @emph{Syntax}:
8708 @code{RESULT = IS_IOSTAT_EOR(I)}
8710 @item @emph{Arguments}:
8711 @multitable @columnfractions .15 .70
8712 @item @var{I} @tab Shall be of the type @code{INTEGER}.
8715 @item @emph{Return value}:
8716 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
8717 @var{I} has the value which indicates an end of file condition for
8718 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
8720 @item @emph{Example}:
8724 INTEGER :: stat, i(50)
8725 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
8726 READ(88, IOSTAT=stat) i
8727 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
8734 @section @code{ISATTY} --- Whether a unit is a terminal device
8736 @cindex system, terminal
8739 @item @emph{Description}:
8740 Determine whether a unit is connected to a terminal device.
8742 @item @emph{Standard}:
8748 @item @emph{Syntax}:
8749 @code{RESULT = ISATTY(UNIT)}
8751 @item @emph{Arguments}:
8752 @multitable @columnfractions .15 .70
8753 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
8756 @item @emph{Return value}:
8757 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
8758 device, @code{.FALSE.} otherwise.
8760 @item @emph{Example}:
8763 INTEGER(kind=1) :: unit
8765 write(*,*) isatty(unit=unit)
8769 @item @emph{See also}:
8776 @section @code{ISHFT} --- Shift bits
8785 @item @emph{Description}:
8786 @code{ISHFT} returns a value corresponding to @var{I} with all of the
8787 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
8788 zero corresponds to a left shift, a value of zero corresponds to no
8789 shift, and a value less than zero corresponds to a right shift. If the
8790 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
8791 value is undefined. Bits shifted out from the left end or right end are
8792 lost; zeros are shifted in from the opposite end.
8794 @item @emph{Standard}:
8795 Fortran 90 and later, has overloads that are GNU extensions
8800 @item @emph{Syntax}:
8801 @code{RESULT = ISHFT(I, SHIFT)}
8803 @item @emph{Arguments}:
8804 @multitable @columnfractions .15 .70
8805 @item @var{I} @tab The type shall be @code{INTEGER}.
8806 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8809 @item @emph{Return value}:
8810 The return value is of type @code{INTEGER} and of the same kind as
8813 @item @emph{Specific names}:
8814 @multitable @columnfractions .20 .23 .20 .33
8815 @headitem Name @tab Argument @tab Return type @tab Standard
8816 @item @code{ISHFT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
8817 @item @code{BSHFT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8818 @item @code{IISHFT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8819 @item @code{JISHFT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8820 @item @code{KISHFT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8823 @item @emph{See also}:
8830 @section @code{ISHFTC} --- Shift bits circularly
8836 @cindex bits, shift circular
8839 @item @emph{Description}:
8840 @code{ISHFTC} returns a value corresponding to @var{I} with the
8841 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
8842 is, bits shifted out one end are shifted into the opposite end. A value
8843 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
8844 zero corresponds to no shift, and a value less than zero corresponds to
8845 a right shift. The absolute value of @var{SHIFT} must be less than
8846 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
8847 equivalent to @code{BIT_SIZE(I)}.
8849 @item @emph{Standard}:
8850 Fortran 90 and later, has overloads that are GNU extensions
8855 @item @emph{Syntax}:
8856 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
8858 @item @emph{Arguments}:
8859 @multitable @columnfractions .15 .70
8860 @item @var{I} @tab The type shall be @code{INTEGER}.
8861 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8862 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
8863 the value must be greater than zero and less than or equal to
8867 @item @emph{Return value}:
8868 The return value is of type @code{INTEGER} and of the same kind as
8871 @item @emph{Specific names}:
8872 @multitable @columnfractions .20 .23 .20 .33
8873 @headitem Name @tab Argument @tab Return type @tab Standard
8874 @item @code{ISHFTC(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
8875 @item @code{BSHFTC(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8876 @item @code{IISHFTC(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8877 @item @code{JISHFTC(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8878 @item @code{KISHFTC(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8881 @item @emph{See also}:
8888 @section @code{ISNAN} --- Test for a NaN
8893 @item @emph{Description}:
8894 @code{ISNAN} tests whether a floating-point value is an IEEE
8896 @item @emph{Standard}:
8902 @item @emph{Syntax}:
8905 @item @emph{Arguments}:
8906 @multitable @columnfractions .15 .70
8907 @item @var{X} @tab Variable of the type @code{REAL}.
8911 @item @emph{Return value}:
8912 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
8913 if @var{X} is a NaN and @code{FALSE} otherwise.
8915 @item @emph{Example}:
8922 if (isnan(x)) stop '"x" is a NaN'
8923 end program test_nan
8930 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
8932 @cindex time, current
8933 @cindex current time
8936 @item @emph{Description}:
8937 @code{ITIME(VALUES)} Fills @var{VALUES} with the numerical values at the
8938 current local time. The hour (in the range 1-24), minute (in the range 1-60),
8939 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
8942 This intrinsic routine is provided for backwards compatibility with
8943 GNU Fortran 77. In new code, programmers should consider the use of
8944 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
8947 @item @emph{Standard}:
8953 @item @emph{Syntax}:
8954 @code{CALL ITIME(VALUES)}
8956 @item @emph{Arguments}:
8957 @multitable @columnfractions .15 .70
8958 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
8959 and the kind shall be the default integer kind.
8962 @item @emph{Return value}:
8963 Does not return anything.
8966 @item @emph{Example}:
8969 integer, dimension(3) :: tarray
8974 end program test_itime
8977 @item @emph{See also}:
8984 @section @code{KILL} --- Send a signal to a process
8988 @item @emph{Description}:
8989 Sends the signal specified by @var{SIG} to the process @var{PID}.
8992 This intrinsic is provided in both subroutine and function forms;
8993 however, only one form can be used in any given program unit.
8994 @item @emph{Standard}:
8997 @item @emph{Standard}:
9001 Subroutine, function
9003 @item @emph{Syntax}:
9004 @multitable @columnfractions .80
9005 @item @code{CALL KILL(PID, SIG [, STATUS])}
9006 @item @code{STATUS = KILL(PID, SIG)}
9009 @item @emph{Arguments}:
9010 @multitable @columnfractions .15 .70
9011 @item @var{PID} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}.
9012 @item @var{SIG} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}.
9013 @item @var{STATUS} @tab [Subroutine](Optional)
9014 Shall be a scalar @code{INTEGER}.
9015 Returns 0 on success; otherwise a system-specific error code is returned.
9016 @item @var{STATUS} @tab [Function] The kind type parameter is that of
9018 Returns 0 on success; otherwise a system-specific error code is returned.
9021 @item @emph{See also}:
9028 @section @code{KIND} --- Kind of an entity
9033 @item @emph{Description}:
9034 @code{KIND(X)} returns the kind value of the entity @var{X}.
9036 @item @emph{Standard}:
9037 Fortran 95 and later
9042 @item @emph{Syntax}:
9045 @item @emph{Arguments}:
9046 @multitable @columnfractions .15 .70
9047 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
9048 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}. It may be scalar or
9052 @item @emph{Return value}:
9053 The return value is a scalar of type @code{INTEGER} and of the default
9056 @item @emph{Example}:
9059 integer,parameter :: kc = kind(' ')
9060 integer,parameter :: kl = kind(.true.)
9062 print *, "The default character kind is ", kc
9063 print *, "The default logical kind is ", kl
9064 end program test_kind
9072 @section @code{LBOUND} --- Lower dimension bounds of an array
9074 @cindex array, lower bound
9077 @item @emph{Description}:
9078 Returns the lower bounds of an array, or a single lower bound
9079 along the @var{DIM} dimension.
9080 @item @emph{Standard}:
9081 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
9086 @item @emph{Syntax}:
9087 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
9089 @item @emph{Arguments}:
9090 @multitable @columnfractions .15 .70
9091 @item @var{ARRAY} @tab Shall be an array, of any type.
9092 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
9093 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
9094 expression indicating the kind parameter of the result.
9097 @item @emph{Return value}:
9098 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9099 @var{KIND} is absent, the return value is of default integer kind.
9100 If @var{DIM} is absent, the result is an array of the lower bounds of
9101 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
9102 corresponding to the lower bound of the array along that dimension. If
9103 @var{ARRAY} is an expression rather than a whole array or array
9104 structure component, or if it has a zero extent along the relevant
9105 dimension, the lower bound is taken to be 1.
9107 @item @emph{See also}:
9115 @section @code{LCOBOUND} --- Lower codimension bounds of an array
9117 @cindex coarray, lower bound
9120 @item @emph{Description}:
9121 Returns the lower bounds of a coarray, or a single lower cobound
9122 along the @var{DIM} codimension.
9123 @item @emph{Standard}:
9124 Fortran 2008 and later
9129 @item @emph{Syntax}:
9130 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
9132 @item @emph{Arguments}:
9133 @multitable @columnfractions .15 .70
9134 @item @var{ARRAY} @tab Shall be an coarray, of any type.
9135 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
9136 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
9137 expression indicating the kind parameter of the result.
9140 @item @emph{Return value}:
9141 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9142 @var{KIND} is absent, the return value is of default integer kind.
9143 If @var{DIM} is absent, the result is an array of the lower cobounds of
9144 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
9145 corresponding to the lower cobound of the array along that codimension.
9147 @item @emph{See also}:
9155 @section @code{LEADZ} --- Number of leading zero bits of an integer
9160 @item @emph{Description}:
9161 @code{LEADZ} returns the number of leading zero bits of an integer.
9163 @item @emph{Standard}:
9164 Fortran 2008 and later
9169 @item @emph{Syntax}:
9170 @code{RESULT = LEADZ(I)}
9172 @item @emph{Arguments}:
9173 @multitable @columnfractions .15 .70
9174 @item @var{I} @tab Shall be of type @code{INTEGER}.
9177 @item @emph{Return value}:
9178 The type of the return value is the default @code{INTEGER}.
9179 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
9181 @item @emph{Example}:
9184 WRITE (*,*) BIT_SIZE(1) ! prints 32
9185 WRITE (*,*) LEADZ(1) ! prints 31
9189 @item @emph{See also}:
9199 @section @code{LEN} --- Length of a character entity
9201 @cindex string, length
9204 @item @emph{Description}:
9205 Returns the length of a character string. If @var{STRING} is an array,
9206 the length of an element of @var{STRING} is returned. Note that
9207 @var{STRING} need not be defined when this intrinsic is invoked, since
9208 only the length, not the content, of @var{STRING} is needed.
9210 @item @emph{Standard}:
9211 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
9216 @item @emph{Syntax}:
9217 @code{L = LEN(STRING [, KIND])}
9219 @item @emph{Arguments}:
9220 @multitable @columnfractions .15 .70
9221 @item @var{STRING} @tab Shall be a scalar or array of type
9222 @code{CHARACTER}, with @code{INTENT(IN)}
9223 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
9224 expression indicating the kind parameter of the result.
9227 @item @emph{Return value}:
9228 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9229 @var{KIND} is absent, the return value is of default integer kind.
9232 @item @emph{Specific names}:
9233 @multitable @columnfractions .20 .23 .20 .33
9234 @headitem Name @tab Argument @tab Return type @tab Standard
9235 @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
9239 @item @emph{See also}:
9248 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
9250 @cindex string, length, without trailing whitespace
9253 @item @emph{Description}:
9254 Returns the length of a character string, ignoring any trailing blanks.
9256 @item @emph{Standard}:
9257 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
9262 @item @emph{Syntax}:
9263 @code{RESULT = LEN_TRIM(STRING [, KIND])}
9265 @item @emph{Arguments}:
9266 @multitable @columnfractions .15 .70
9267 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
9268 with @code{INTENT(IN)}
9269 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
9270 expression indicating the kind parameter of the result.
9273 @item @emph{Return value}:
9274 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9275 @var{KIND} is absent, the return value is of default integer kind.
9277 @item @emph{See also}:
9286 @section @code{LGE} --- Lexical greater than or equal
9288 @cindex lexical comparison of strings
9289 @cindex string, comparison
9292 @item @emph{Description}:
9293 Determines whether one string is lexically greater than or equal to
9294 another string, where the two strings are interpreted as containing
9295 ASCII character codes. If the String A and String B are not the same
9296 length, the shorter is compared as if spaces were appended to it to form
9297 a value that has the same length as the longer.
9299 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9300 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9301 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9302 that the latter use the processor's character ordering (which is not
9303 ASCII on some targets), whereas the former always use the ASCII
9306 @item @emph{Standard}:
9307 Fortran 77 and later
9312 @item @emph{Syntax}:
9313 @code{RESULT = LGE(STRING_A, STRING_B)}
9315 @item @emph{Arguments}:
9316 @multitable @columnfractions .15 .70
9317 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9318 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9321 @item @emph{Return value}:
9322 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
9323 otherwise, based on the ASCII ordering.
9325 @item @emph{Specific names}:
9326 @multitable @columnfractions .34 .16 .17 .30
9327 @headitem Name @tab Argument @tab Return type @tab Standard
9328 @item @code{LGE(STRING_A,STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9331 @item @emph{See also}:
9340 @section @code{LGT} --- Lexical greater than
9342 @cindex lexical comparison of strings
9343 @cindex string, comparison
9346 @item @emph{Description}:
9347 Determines whether one string is lexically greater than another string,
9348 where the two strings are interpreted as containing ASCII character
9349 codes. If the String A and String B are not the same length, the
9350 shorter is compared as if spaces were appended to it to form a value
9351 that has the same length as the longer.
9353 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9354 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9355 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9356 that the latter use the processor's character ordering (which is not
9357 ASCII on some targets), whereas the former always use the ASCII
9360 @item @emph{Standard}:
9361 Fortran 77 and later
9366 @item @emph{Syntax}:
9367 @code{RESULT = LGT(STRING_A, STRING_B)}
9369 @item @emph{Arguments}:
9370 @multitable @columnfractions .15 .70
9371 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9372 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9375 @item @emph{Return value}:
9376 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
9377 otherwise, based on the ASCII ordering.
9379 @item @emph{Specific names}:
9380 @multitable @columnfractions .34 .16 .17 .30
9381 @headitem Name @tab Argument @tab Return type @tab Standard
9382 @item @code{LGT(STRING_A,STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9385 @item @emph{See also}:
9394 @section @code{LINK} --- Create a hard link
9396 @cindex file system, create link
9397 @cindex file system, hard link
9400 @item @emph{Description}:
9401 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
9402 character (@code{CHAR(0)}) can be used to mark the end of the names in
9403 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
9404 names are ignored. If the @var{STATUS} argument is supplied, it
9405 contains 0 on success or a nonzero error code upon return; see
9408 This intrinsic is provided in both subroutine and function forms;
9409 however, only one form can be used in any given program unit.
9411 @item @emph{Standard}:
9415 Subroutine, function
9417 @item @emph{Syntax}:
9418 @multitable @columnfractions .80
9419 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
9420 @item @code{STATUS = LINK(PATH1, PATH2)}
9423 @item @emph{Arguments}:
9424 @multitable @columnfractions .15 .70
9425 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
9426 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
9427 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9430 @item @emph{See also}:
9438 @section @code{LLE} --- Lexical less than or equal
9440 @cindex lexical comparison of strings
9441 @cindex string, comparison
9444 @item @emph{Description}:
9445 Determines whether one string is lexically less than or equal to another
9446 string, where the two strings are interpreted as containing ASCII
9447 character codes. If the String A and String B are not the same length,
9448 the shorter is compared as if spaces were appended to it to form a value
9449 that has the same length as the longer.
9451 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9452 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9453 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9454 that the latter use the processor's character ordering (which is not
9455 ASCII on some targets), whereas the former always use the ASCII
9458 @item @emph{Standard}:
9459 Fortran 77 and later
9464 @item @emph{Syntax}:
9465 @code{RESULT = LLE(STRING_A, STRING_B)}
9467 @item @emph{Arguments}:
9468 @multitable @columnfractions .15 .70
9469 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9470 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9473 @item @emph{Return value}:
9474 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
9475 otherwise, based on the ASCII ordering.
9477 @item @emph{Specific names}:
9478 @multitable @columnfractions .34 .16 .17 .30
9479 @headitem Name @tab Argument @tab Return type @tab Standard
9480 @item @code{LLE(STRING_A,STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9483 @item @emph{See also}:
9492 @section @code{LLT} --- Lexical less than
9494 @cindex lexical comparison of strings
9495 @cindex string, comparison
9498 @item @emph{Description}:
9499 Determines whether one string is lexically less than another string,
9500 where the two strings are interpreted as containing ASCII character
9501 codes. If the String A and String B are not the same length, the
9502 shorter is compared as if spaces were appended to it to form a value
9503 that has the same length as the longer.
9505 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9506 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9507 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9508 that the latter use the processor's character ordering (which is not
9509 ASCII on some targets), whereas the former always use the ASCII
9512 @item @emph{Standard}:
9513 Fortran 77 and later
9518 @item @emph{Syntax}:
9519 @code{RESULT = LLT(STRING_A, STRING_B)}
9521 @item @emph{Arguments}:
9522 @multitable @columnfractions .15 .70
9523 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9524 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9527 @item @emph{Return value}:
9528 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
9529 otherwise, based on the ASCII ordering.
9531 @item @emph{Specific names}:
9532 @multitable @columnfractions .34 .16 .17 .30
9533 @headitem Name @tab Argument @tab Return type @tab Standard
9534 @item @code{LLT(STRING_A,STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9537 @item @emph{See also}:
9546 @section @code{LNBLNK} --- Index of the last non-blank character in a string
9548 @cindex string, find non-blank character
9551 @item @emph{Description}:
9552 Returns the length of a character string, ignoring any trailing blanks.
9553 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
9554 included for backwards compatibility.
9556 @item @emph{Standard}:
9562 @item @emph{Syntax}:
9563 @code{RESULT = LNBLNK(STRING)}
9565 @item @emph{Arguments}:
9566 @multitable @columnfractions .15 .70
9567 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
9568 with @code{INTENT(IN)}
9571 @item @emph{Return value}:
9572 The return value is of @code{INTEGER(kind=4)} type.
9574 @item @emph{See also}:
9575 @ref{INDEX intrinsic}, @*
9582 @section @code{LOC} --- Returns the address of a variable
9584 @cindex location of a variable in memory
9587 @item @emph{Description}:
9588 @code{LOC(X)} returns the address of @var{X} as an integer.
9590 @item @emph{Standard}:
9596 @item @emph{Syntax}:
9597 @code{RESULT = LOC(X)}
9599 @item @emph{Arguments}:
9600 @multitable @columnfractions .15 .70
9601 @item @var{X} @tab Variable of any type.
9604 @item @emph{Return value}:
9605 The return value is of type @code{INTEGER}, with a @code{KIND}
9606 corresponding to the size (in bytes) of a memory address on the target
9609 @item @emph{Example}:
9616 end program test_loc
9623 @section @code{LOG} --- Natural logarithm function
9630 @cindex exponential function, inverse
9631 @cindex logarithm function
9632 @cindex natural logarithm function
9635 @item @emph{Description}:
9636 @code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the
9637 logarithm to the base @math{e}.
9639 @item @emph{Standard}:
9640 Fortran 77 and later, has GNU extensions
9645 @item @emph{Syntax}:
9646 @code{RESULT = LOG(X)}
9648 @item @emph{Arguments}:
9649 @multitable @columnfractions .15 .70
9650 @item @var{X} @tab The type shall be @code{REAL} or
9654 @item @emph{Return value}:
9655 The return value is of type @code{REAL} or @code{COMPLEX}.
9656 The kind type parameter is the same as @var{X}.
9657 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
9658 @math{-\pi < \omega \leq \pi}.
9660 @item @emph{Example}:
9663 real(8) :: x = 2.7182818284590451_8
9664 complex :: z = (1.0, 2.0)
9665 x = log(x) ! will yield (approximately) 1
9667 end program test_log
9670 @item @emph{Specific names}:
9671 @multitable @columnfractions .20 .23 .20 .33
9672 @headitem Name @tab Argument @tab Return type @tab Standard
9673 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 or later
9674 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 or later
9675 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 or later
9676 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
9677 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
9684 @section @code{LOG10} --- Base 10 logarithm function
9688 @cindex exponential function, inverse
9689 @cindex logarithm function with base 10
9690 @cindex base 10 logarithm function
9693 @item @emph{Description}:
9694 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
9696 @item @emph{Standard}:
9697 Fortran 77 and later
9702 @item @emph{Syntax}:
9703 @code{RESULT = LOG10(X)}
9705 @item @emph{Arguments}:
9706 @multitable @columnfractions .15 .70
9707 @item @var{X} @tab The type shall be @code{REAL}.
9710 @item @emph{Return value}:
9711 The return value is of type @code{REAL} or @code{COMPLEX}.
9712 The kind type parameter is the same as @var{X}.
9714 @item @emph{Example}:
9717 real(8) :: x = 10.0_8
9719 end program test_log10
9722 @item @emph{Specific names}:
9723 @multitable @columnfractions .20 .23 .20 .33
9724 @headitem Name @tab Argument @tab Return type @tab Standard
9725 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
9726 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
9733 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
9738 @cindex Gamma function, logarithm of
9741 @item @emph{Description}:
9742 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
9743 of the Gamma (@math{\Gamma}) function.
9745 @item @emph{Standard}:
9746 Fortran 2008 and later
9751 @item @emph{Syntax}:
9752 @code{X = LOG_GAMMA(X)}
9754 @item @emph{Arguments}:
9755 @multitable @columnfractions .15 .70
9756 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
9757 nor a negative integer.
9760 @item @emph{Return value}:
9761 The return value is of type @code{REAL} of the same kind as @var{X}.
9763 @item @emph{Example}:
9765 program test_log_gamma
9767 x = lgamma(x) ! returns 0.0
9768 end program test_log_gamma
9771 @item @emph{Specific names}:
9772 @multitable @columnfractions .20 .23 .20 .33
9773 @headitem Name @tab Argument @tab Return type @tab Standard
9774 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
9775 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
9776 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
9779 @item @emph{See also}:
9787 @section @code{LOGICAL} --- Convert to logical type
9789 @cindex conversion, to logical
9792 @item @emph{Description}:
9793 Converts one kind of @code{LOGICAL} variable to another.
9795 @item @emph{Standard}:
9796 Fortran 90 and later
9801 @item @emph{Syntax}:
9802 @code{RESULT = LOGICAL(L [, KIND])}
9804 @item @emph{Arguments}:
9805 @multitable @columnfractions .15 .70
9806 @item @var{L} @tab The type shall be @code{LOGICAL}.
9807 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
9808 expression indicating the kind parameter of the result.
9811 @item @emph{Return value}:
9812 The return value is a @code{LOGICAL} value equal to @var{L}, with a
9813 kind corresponding to @var{KIND}, or of the default logical kind if
9814 @var{KIND} is not given.
9816 @item @emph{See also}:
9825 @section @code{LSHIFT} --- Left shift bits
9827 @cindex bits, shift left
9830 @item @emph{Description}:
9831 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
9832 bits shifted left by @var{SHIFT} places. @var{SHIFT} shall be
9833 nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
9834 the result value is undefined. Bits shifted out from the left end are
9835 lost; zeros are shifted in from the opposite end.
9837 This function has been superseded by the @code{ISHFT} intrinsic, which
9838 is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
9839 which is standard in Fortran 2008 and later.
9841 @item @emph{Standard}:
9847 @item @emph{Syntax}:
9848 @code{RESULT = LSHIFT(I, SHIFT)}
9850 @item @emph{Arguments}:
9851 @multitable @columnfractions .15 .70
9852 @item @var{I} @tab The type shall be @code{INTEGER}.
9853 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
9856 @item @emph{Return value}:
9857 The return value is of type @code{INTEGER} and of the same kind as
9860 @item @emph{See also}:
9872 @section @code{LSTAT} --- Get file status
9874 @cindex file system, file status
9877 @item @emph{Description}:
9878 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
9879 symbolic link, then the link itself is statted, not the file that it
9882 The elements in @code{VALUES} are the same as described by @ref{STAT}.
9884 This intrinsic is provided in both subroutine and function forms;
9885 however, only one form can be used in any given program unit.
9887 @item @emph{Standard}:
9891 Subroutine, function
9893 @item @emph{Syntax}:
9894 @multitable @columnfractions .80
9895 @item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
9896 @item @code{STATUS = LSTAT(NAME, VALUES)}
9899 @item @emph{Arguments}:
9900 @multitable @columnfractions .15 .70
9901 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
9902 kind, a valid path within the file system.
9903 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
9904 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
9905 Returns 0 on success and a system specific error code otherwise.
9908 @item @emph{Example}:
9909 See @ref{STAT} for an example.
9911 @item @emph{See also}:
9912 To stat an open file: @*
9921 @section @code{LTIME} --- Convert time to local time info
9923 @cindex time, conversion to local time info
9926 @item @emph{Description}:
9927 Given a system time value @var{TIME} (as provided by the @ref{TIME}
9928 intrinsic), fills @var{VALUES} with values extracted from it appropriate
9929 to the local time zone using @code{localtime(3)}.
9931 This intrinsic routine is provided for backwards compatibility with
9932 GNU Fortran 77. In new code, programmers should consider the use of
9933 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
9936 @item @emph{Standard}:
9942 @item @emph{Syntax}:
9943 @code{CALL LTIME(TIME, VALUES)}
9945 @item @emph{Arguments}:
9946 @multitable @columnfractions .15 .70
9947 @item @var{TIME} @tab An @code{INTEGER} scalar expression
9948 corresponding to a system time, with @code{INTENT(IN)}.
9949 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
9950 with @code{INTENT(OUT)}.
9953 @item @emph{Return value}:
9954 The elements of @var{VALUES} are assigned as follows:
9956 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
9958 @item Minutes after the hour, range 0--59
9959 @item Hours past midnight, range 0--23
9960 @item Day of month, range 1--31
9961 @item Number of months since January, range 0--11
9962 @item Years since 1900
9963 @item Number of days since Sunday, range 0--6
9964 @item Days since January 1, range 0--365
9965 @item Daylight savings indicator: positive if daylight savings is in
9966 effect, zero if not, and negative if the information is not available.
9969 @item @emph{See also}:
9970 @ref{DATE_AND_TIME}, @*
9980 @section @code{MALLOC} --- Allocate dynamic memory
9982 @cindex pointer, cray
9985 @item @emph{Description}:
9986 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
9987 returns the address of the allocated memory. The @code{MALLOC} intrinsic
9988 is an extension intended to be used with Cray pointers, and is provided
9989 in GNU Fortran to allow the user to compile legacy code. For new code
9990 using Fortran 95 pointers, the memory allocation intrinsic is
9993 @item @emph{Standard}:
9999 @item @emph{Syntax}:
10000 @code{PTR = MALLOC(SIZE)}
10002 @item @emph{Arguments}:
10003 @multitable @columnfractions .15 .70
10004 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
10007 @item @emph{Return value}:
10008 The return value is of type @code{INTEGER(K)}, with @var{K} such that
10009 variables of type @code{INTEGER(K)} have the same size as
10010 C pointers (@code{sizeof(void *)}).
10012 @item @emph{Example}:
10013 The following example demonstrates the use of @code{MALLOC} and
10014 @code{FREE} with Cray pointers.
10017 program test_malloc
10023 ptr_x = malloc(20*8)
10025 x(i) = sqrt(1.0d0 / i)
10033 end program test_malloc
10036 @item @emph{See also}:
10043 @section @code{MASKL} --- Left justified mask
10045 @cindex mask, left justified
10048 @item @emph{Description}:
10049 @code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
10050 remaining bits set to 0.
10052 @item @emph{Standard}:
10053 Fortran 2008 and later
10055 @item @emph{Class}:
10058 @item @emph{Syntax}:
10059 @code{RESULT = MASKL(I[, KIND])}
10061 @item @emph{Arguments}:
10062 @multitable @columnfractions .15 .70
10063 @item @var{I} @tab Shall be of type @code{INTEGER}.
10064 @item @var{KIND} @tab Shall be a scalar constant expression of type
10068 @item @emph{Return value}:
10069 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
10070 specifies the kind value of the return type; otherwise, it is of the
10071 default integer kind.
10073 @item @emph{See also}:
10080 @section @code{MASKR} --- Right justified mask
10082 @cindex mask, right justified
10085 @item @emph{Description}:
10086 @code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
10087 remaining bits set to 0.
10089 @item @emph{Standard}:
10090 Fortran 2008 and later
10092 @item @emph{Class}:
10095 @item @emph{Syntax}:
10096 @code{RESULT = MASKR(I[, KIND])}
10098 @item @emph{Arguments}:
10099 @multitable @columnfractions .15 .70
10100 @item @var{I} @tab Shall be of type @code{INTEGER}.
10101 @item @var{KIND} @tab Shall be a scalar constant expression of type
10105 @item @emph{Return value}:
10106 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
10107 specifies the kind value of the return type; otherwise, it is of the
10108 default integer kind.
10110 @item @emph{See also}:
10117 @section @code{MATMUL} --- matrix multiplication
10119 @cindex matrix multiplication
10120 @cindex product, matrix
10123 @item @emph{Description}:
10124 Performs a matrix multiplication on numeric or logical arguments.
10126 @item @emph{Standard}:
10127 Fortran 90 and later
10129 @item @emph{Class}:
10130 Transformational function
10132 @item @emph{Syntax}:
10133 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
10135 @item @emph{Arguments}:
10136 @multitable @columnfractions .15 .70
10137 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
10138 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
10140 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
10141 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
10142 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
10143 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
10144 equal to the last (or only) dimension of @var{MATRIX_A}.
10145 @var{MATRIX_A} and @var{MATRIX_B} shall not both be rank one arrays.
10148 @item @emph{Return value}:
10149 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
10150 kind of the result follow the usual type and kind promotion rules, as
10151 for the @code{*} or @code{.AND.} operators.
10157 @section @code{MAX} --- Maximum value of an argument list
10164 @cindex maximum value
10167 @item @emph{Description}:
10168 Returns the argument with the largest (most positive) value.
10170 @item @emph{Standard}:
10171 Fortran 77 and later
10173 @item @emph{Class}:
10176 @item @emph{Syntax}:
10177 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
10179 @item @emph{Arguments}:
10180 @multitable @columnfractions .15 .70
10181 @item @var{A1} @tab The type shall be @code{INTEGER} or
10183 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
10184 as @var{A1}. (As a GNU extension, arguments of different kinds are
10188 @item @emph{Return value}:
10189 The return value corresponds to the maximum value among the arguments,
10190 and has the same type and kind as the first argument.
10192 @item @emph{Specific names}:
10193 @multitable @columnfractions .20 .23 .20 .33
10194 @headitem Name @tab Argument @tab Return type @tab Standard
10195 @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
10196 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
10197 @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
10198 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
10199 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
10202 @item @emph{See also}:
10211 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
10212 @fnindex MAXEXPONENT
10213 @cindex model representation, maximum exponent
10216 @item @emph{Description}:
10217 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
10220 @item @emph{Standard}:
10221 Fortran 90 and later
10223 @item @emph{Class}:
10226 @item @emph{Syntax}:
10227 @code{RESULT = MAXEXPONENT(X)}
10229 @item @emph{Arguments}:
10230 @multitable @columnfractions .15 .70
10231 @item @var{X} @tab Shall be of type @code{REAL}.
10234 @item @emph{Return value}:
10235 The return value is of type @code{INTEGER} and of the default integer
10238 @item @emph{Example}:
10244 print *, minexponent(x), maxexponent(x)
10245 print *, minexponent(y), maxexponent(y)
10246 end program exponents
10253 @section @code{MAXLOC} --- Location of the maximum value within an array
10255 @cindex array, location of maximum element
10258 @item @emph{Description}:
10259 Determines the location of the element in the array with the maximum
10260 value, or, if the @var{DIM} argument is supplied, determines the
10261 locations of the maximum element along each row of the array in the
10262 @var{DIM} direction. If @var{MASK} is present, only the elements for
10263 which @var{MASK} is @code{.TRUE.} are considered. If more than one
10264 element in the array has the maximum value, the location returned is
10265 that of the first such element in array element order if the
10266 @var{BACK} is not present, or is false; if @var{BACK} is true, the location
10267 returned is that of the last such element. If the array has zero
10268 size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
10269 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
10270 and all of the elements of @var{MASK} along a given row are zero, the
10271 result value for that row is zero.
10273 @item @emph{Standard}:
10274 Fortran 95 and later; @var{ARRAY} of @code{CHARACTER} and the
10275 @var{KIND} argument are available in Fortran 2003 and later.
10276 The @var{BACK} argument is available in Fortran 2008 and later.
10278 @item @emph{Class}:
10279 Transformational function
10281 @item @emph{Syntax}:
10282 @multitable @columnfractions .80
10283 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK])}
10284 @item @code{RESULT = MAXLOC(ARRAY [, MASK] [,KIND] [,BACK])}
10287 @item @emph{Arguments}:
10288 @multitable @columnfractions .15 .70
10289 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10291 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10292 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10293 inclusive. It may not be an optional dummy argument.
10294 @item @var{MASK} @tab Shall be of type @code{LOGICAL},
10295 and conformable with @var{ARRAY}.
10296 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
10297 expression indicating the kind parameter of the result.
10298 @item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}.
10301 @item @emph{Return value}:
10302 If @var{DIM} is absent, the result is a rank-one array with a length
10303 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
10304 is an array with a rank one less than the rank of @var{ARRAY}, and a
10305 size corresponding to the size of @var{ARRAY} with the @var{DIM}
10306 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
10307 of one, the result is a scalar. If the optional argument @var{KIND}
10308 is present, the result is an integer of kind @var{KIND}, otherwise it
10309 is of default kind.
10311 @item @emph{See also}:
10320 @section @code{MAXVAL} --- Maximum value of an array
10322 @cindex array, maximum value
10323 @cindex maximum value
10326 @item @emph{Description}:
10327 Determines the maximum value of the elements in an array value, or, if
10328 the @var{DIM} argument is supplied, determines the maximum value along
10329 each row of the array in the @var{DIM} direction. If @var{MASK} is
10330 present, only the elements for which @var{MASK} is @code{.TRUE.} are
10331 considered. If the array has zero size, or all of the elements of
10332 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
10333 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
10336 @item @emph{Standard}:
10337 Fortran 90 and later
10339 @item @emph{Class}:
10340 Transformational function
10342 @item @emph{Syntax}:
10343 @multitable @columnfractions .80
10344 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
10345 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
10348 @item @emph{Arguments}:
10349 @multitable @columnfractions .15 .70
10350 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10352 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10353 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10354 inclusive. It may not be an optional dummy argument.
10355 @item @var{MASK} @tab (Optional) Shall be of type @code{LOGICAL},
10356 and conformable with @var{ARRAY}.
10359 @item @emph{Return value}:
10360 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
10361 is a scalar. If @var{DIM} is present, the result is an array with a
10362 rank one less than the rank of @var{ARRAY}, and a size corresponding to
10363 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
10364 cases, the result is of the same type and kind as @var{ARRAY}.
10366 @item @emph{See also}:
10374 @section @code{MCLOCK} --- Time function
10376 @cindex time, clock ticks
10377 @cindex clock ticks
10380 @item @emph{Description}:
10381 Returns the number of clock ticks since the start of the process, based
10382 on the function @code{clock(3)} in the C standard library.
10384 This intrinsic is not fully portable, such as to systems with 32-bit
10385 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
10386 the values returned by this intrinsic might be, or become, negative, or
10387 numerically less than previous values, during a single run of the
10390 @item @emph{Standard}:
10393 @item @emph{Class}:
10396 @item @emph{Syntax}:
10397 @code{RESULT = MCLOCK()}
10399 @item @emph{Return value}:
10400 The return value is a scalar of type @code{INTEGER(4)}, equal to the
10401 number of clock ticks since the start of the process, or @code{-1} if
10402 the system does not support @code{clock(3)}.
10404 @item @emph{See also}:
10415 @section @code{MCLOCK8} --- Time function (64-bit)
10417 @cindex time, clock ticks
10418 @cindex clock ticks
10421 @item @emph{Description}:
10422 Returns the number of clock ticks since the start of the process, based
10423 on the function @code{clock(3)} in the C standard library.
10425 @emph{Warning:} this intrinsic does not increase the range of the timing
10426 values over that returned by @code{clock(3)}. On a system with a 32-bit
10427 @code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though
10428 it is converted to a 64-bit @code{INTEGER(8)} value. That means
10429 overflows of the 32-bit value can still occur. Therefore, the values
10430 returned by this intrinsic might be or become negative or numerically
10431 less than previous values during a single run of the compiled program.
10433 @item @emph{Standard}:
10436 @item @emph{Class}:
10439 @item @emph{Syntax}:
10440 @code{RESULT = MCLOCK8()}
10442 @item @emph{Return value}:
10443 The return value is a scalar of type @code{INTEGER(8)}, equal to the
10444 number of clock ticks since the start of the process, or @code{-1} if
10445 the system does not support @code{clock(3)}.
10447 @item @emph{See also}:
10458 @section @code{MERGE} --- Merge variables
10460 @cindex array, merge arrays
10461 @cindex array, combine arrays
10464 @item @emph{Description}:
10465 Select values from two arrays according to a logical mask. The result
10466 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
10467 @var{FSOURCE} if it is @code{.FALSE.}.
10469 @item @emph{Standard}:
10470 Fortran 90 and later
10472 @item @emph{Class}:
10475 @item @emph{Syntax}:
10476 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
10478 @item @emph{Arguments}:
10479 @multitable @columnfractions .15 .70
10480 @item @var{TSOURCE} @tab May be of any type.
10481 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
10483 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
10486 @item @emph{Return value}:
10487 The result is of the same type and type parameters as @var{TSOURCE}.
10494 @section @code{MERGE_BITS} --- Merge of bits under mask
10495 @fnindex MERGE_BITS
10496 @cindex bits, merge
10499 @item @emph{Description}:
10500 @code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
10501 as determined by the mask. The i-th bit of the result is equal to the
10502 i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
10503 the i-th bit of @var{J} otherwise.
10505 @item @emph{Standard}:
10506 Fortran 2008 and later
10508 @item @emph{Class}:
10511 @item @emph{Syntax}:
10512 @code{RESULT = MERGE_BITS(I, J, MASK)}
10514 @item @emph{Arguments}:
10515 @multitable @columnfractions .15 .70
10516 @item @var{I} @tab Shall be of type @code{INTEGER} or a boz-literal-constant.
10517 @item @var{J} @tab Shall be of type @code{INTEGER} with the same
10518 kind type parameter as @var{I} or a boz-literal-constant.
10519 @var{I} and @var{J} shall not both be boz-literal-constants.
10520 @item @var{MASK} @tab Shall be of type @code{INTEGER} or a boz-literal-constant
10521 and of the same kind as @var{I}.
10524 @item @emph{Return value}:
10525 The result is of the same type and kind as @var{I}.
10532 @section @code{MIN} --- Minimum value of an argument list
10539 @cindex minimum value
10542 @item @emph{Description}:
10543 Returns the argument with the smallest (most negative) value.
10545 @item @emph{Standard}:
10546 Fortran 77 and later
10548 @item @emph{Class}:
10551 @item @emph{Syntax}:
10552 @code{RESULT = MIN(A1, A2 [, A3, ...])}
10554 @item @emph{Arguments}:
10555 @multitable @columnfractions .15 .70
10556 @item @var{A1} @tab The type shall be @code{INTEGER} or
10558 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
10559 as @var{A1}. (As a GNU extension, arguments of different kinds are
10563 @item @emph{Return value}:
10564 The return value corresponds to the minimum value among the arguments,
10565 and has the same type and kind as the first argument.
10567 @item @emph{Specific names}:
10568 @multitable @columnfractions .20 .23 .20 .33
10569 @headitem Name @tab Argument @tab Return type @tab Standard
10570 @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
10571 @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
10572 @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
10573 @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
10574 @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
10577 @item @emph{See also}:
10586 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
10587 @fnindex MINEXPONENT
10588 @cindex model representation, minimum exponent
10591 @item @emph{Description}:
10592 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
10595 @item @emph{Standard}:
10596 Fortran 90 and later
10598 @item @emph{Class}:
10601 @item @emph{Syntax}:
10602 @code{RESULT = MINEXPONENT(X)}
10604 @item @emph{Arguments}:
10605 @multitable @columnfractions .15 .70
10606 @item @var{X} @tab Shall be of type @code{REAL}.
10609 @item @emph{Return value}:
10610 The return value is of type @code{INTEGER} and of the default integer
10613 @item @emph{Example}:
10614 See @code{MAXEXPONENT} for an example.
10620 @section @code{MINLOC} --- Location of the minimum value within an array
10622 @cindex array, location of minimum element
10625 @item @emph{Description}:
10626 Determines the location of the element in the array with the minimum
10627 value, or, if the @var{DIM} argument is supplied, determines the
10628 locations of the minimum element along each row of the array in the
10629 @var{DIM} direction. If @var{MASK} is present, only the elements for
10630 which @var{MASK} is @code{.TRUE.} are considered. If more than one
10631 element in the array has the minimum value, the location returned is
10632 that of the first such element in array element order if the
10633 @var{BACK} is not present, or is false; if @var{BACK} is true, the location
10634 returned is that of the last such element. If the array has
10635 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
10636 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
10637 and all of the elements of @var{MASK} along a given row are zero, the
10638 result value for that row is zero.
10640 @item @emph{Standard}:
10641 Fortran 90 and later; @var{ARRAY} of @code{CHARACTER} and the
10642 @var{KIND} argument are available in Fortran 2003 and later.
10643 The @var{BACK} argument is available in Fortran 2008 and later.
10645 @item @emph{Class}:
10646 Transformational function
10648 @item @emph{Syntax}:
10649 @multitable @columnfractions .80
10650 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK])}
10651 @item @code{RESULT = MINLOC(ARRAY [, MASK], [,KIND] [,BACK])}
10654 @item @emph{Arguments}:
10655 @multitable @columnfractions .15 .70
10656 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
10657 @code{REAL} or @code{CHARACTER}.
10658 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10659 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10660 inclusive. It may not be an optional dummy argument.
10661 @item @var{MASK} @tab Shall be of type @code{LOGICAL},
10662 and conformable with @var{ARRAY}.
10663 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
10664 expression indicating the kind parameter of the result.
10665 @item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}.
10668 @item @emph{Return value}:
10669 If @var{DIM} is absent, the result is a rank-one array with a length
10670 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
10671 is an array with a rank one less than the rank of @var{ARRAY}, and a
10672 size corresponding to the size of @var{ARRAY} with the @var{DIM}
10673 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
10674 of one, the result is a scalar. If the optional argument @var{KIND}
10675 is present, the result is an integer of kind @var{KIND}, otherwise it
10676 is of default kind.
10678 @item @emph{See also}:
10687 @section @code{MINVAL} --- Minimum value of an array
10689 @cindex array, minimum value
10690 @cindex minimum value
10693 @item @emph{Description}:
10694 Determines the minimum value of the elements in an array value, or, if
10695 the @var{DIM} argument is supplied, determines the minimum value along
10696 each row of the array in the @var{DIM} direction. If @var{MASK} is
10697 present, only the elements for which @var{MASK} is @code{.TRUE.} are
10698 considered. If the array has zero size, or all of the elements of
10699 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
10700 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
10701 @var{ARRAY} is of character type.
10703 @item @emph{Standard}:
10704 Fortran 90 and later
10706 @item @emph{Class}:
10707 Transformational function
10709 @item @emph{Syntax}:
10710 @multitable @columnfractions .80
10711 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
10712 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
10715 @item @emph{Arguments}:
10716 @multitable @columnfractions .15 .70
10717 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10719 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10720 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10721 inclusive. It may not be an optional dummy argument.
10722 @item @var{MASK} @tab Shall be of type @code{LOGICAL},
10723 and conformable with @var{ARRAY}.
10726 @item @emph{Return value}:
10727 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
10728 is a scalar. If @var{DIM} is present, the result is an array with a
10729 rank one less than the rank of @var{ARRAY}, and a size corresponding to
10730 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
10731 cases, the result is of the same type and kind as @var{ARRAY}.
10733 @item @emph{See also}:
10741 @section @code{MOD} --- Remainder function
10750 @cindex division, remainder
10753 @item @emph{Description}:
10754 @code{MOD(A,P)} computes the remainder of the division of A by P@.
10756 @item @emph{Standard}:
10757 Fortran 77 and later, has overloads that are GNU extensions
10759 @item @emph{Class}:
10762 @item @emph{Syntax}:
10763 @code{RESULT = MOD(A, P)}
10765 @item @emph{Arguments}:
10766 @multitable @columnfractions .15 .70
10767 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
10768 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
10769 and not equal to zero. (As a GNU extension, arguments of different kinds are
10773 @item @emph{Return value}:
10774 The return value is the result of @code{A - (INT(A/P) * P)}. The type
10775 and kind of the return value is the same as that of the arguments. The
10776 returned value has the same sign as A and a magnitude less than the
10777 magnitude of P. (As a GNU extension, kind is the largest kind of the actual
10780 @item @emph{Example}:
10784 print *, mod(17.5,5.5)
10785 print *, mod(17.5d0,5.5)
10786 print *, mod(17.5,5.5d0)
10788 print *, mod(-17,3)
10789 print *, mod(-17.5,5.5)
10790 print *, mod(-17.5d0,5.5)
10791 print *, mod(-17.5,5.5d0)
10793 print *, mod(17,-3)
10794 print *, mod(17.5,-5.5)
10795 print *, mod(17.5d0,-5.5)
10796 print *, mod(17.5,-5.5d0)
10797 end program test_mod
10800 @item @emph{Specific names}:
10801 @multitable @columnfractions .20 .25 .20 .31
10802 @headitem Name @tab Arguments @tab Return type @tab Standard
10803 @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 77 and later
10804 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 77 and later
10805 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 77 and later
10806 @item @code{BMOD(A,P)} @tab @code{INTEGER(1) A,P} @tab @code{INTEGER(1)} @tab GNU extension
10807 @item @code{IMOD(A,P)} @tab @code{INTEGER(2) A,P} @tab @code{INTEGER(2)} @tab GNU extension
10808 @item @code{JMOD(A,P)} @tab @code{INTEGER(4) A,P} @tab @code{INTEGER(4)} @tab GNU extension
10809 @item @code{KMOD(A,P)} @tab @code{INTEGER(8) A,P} @tab @code{INTEGER(8)} @tab GNU extension
10812 @item @emph{See also}:
10820 @section @code{MODULO} --- Modulo function
10823 @cindex division, modulo
10826 @item @emph{Description}:
10827 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
10829 @item @emph{Standard}:
10830 Fortran 95 and later
10832 @item @emph{Class}:
10835 @item @emph{Syntax}:
10836 @code{RESULT = MODULO(A, P)}
10838 @item @emph{Arguments}:
10839 @multitable @columnfractions .15 .70
10840 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
10841 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}.
10842 It shall not be zero. (As a GNU extension, arguments of different kinds are
10846 @item @emph{Return value}:
10847 The type and kind of the result are those of the arguments. (As a GNU
10848 extension, kind is the largest kind of the actual arguments.)
10850 @item If @var{A} and @var{P} are of type @code{INTEGER}:
10851 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
10852 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
10854 @item If @var{A} and @var{P} are of type @code{REAL}:
10855 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
10857 The returned value has the same sign as P and a magnitude less than
10858 the magnitude of P.
10860 @item @emph{Example}:
10862 program test_modulo
10863 print *, modulo(17,3)
10864 print *, modulo(17.5,5.5)
10866 print *, modulo(-17,3)
10867 print *, modulo(-17.5,5.5)
10869 print *, modulo(17,-3)
10870 print *, modulo(17.5,-5.5)
10874 @item @emph{See also}:
10882 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
10883 @fnindex MOVE_ALLOC
10884 @cindex moving allocation
10885 @cindex allocation, moving
10888 @item @emph{Description}:
10889 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
10890 @var{TO}. @var{FROM} will become deallocated in the process.
10892 @item @emph{Standard}:
10893 Fortran 2003 and later
10895 @item @emph{Class}:
10898 @item @emph{Syntax}:
10899 @code{CALL MOVE_ALLOC(FROM, TO)}
10901 @item @emph{Arguments}:
10902 @multitable @columnfractions .15 .70
10903 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
10904 of any type and kind.
10905 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
10906 of the same type, kind and rank as @var{FROM}.
10909 @item @emph{Return value}:
10912 @item @emph{Example}:
10914 program test_move_alloc
10915 integer, allocatable :: a(:), b(:)
10919 call move_alloc(a, b)
10920 print *, allocated(a), allocated(b)
10922 end program test_move_alloc
10929 @section @code{MVBITS} --- Move bits from one integer to another
10938 @item @emph{Description}:
10939 Moves @var{LEN} bits from positions @var{FROMPOS} through
10940 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
10941 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
10942 affected by the movement of bits is unchanged. The values of
10943 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
10944 @code{BIT_SIZE(FROM)}.
10946 @item @emph{Standard}:
10947 Fortran 90 and later, has overloads that are GNU extensions
10949 @item @emph{Class}:
10950 Elemental subroutine
10952 @item @emph{Syntax}:
10953 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
10955 @item @emph{Arguments}:
10956 @multitable @columnfractions .15 .70
10957 @item @var{FROM} @tab The type shall be @code{INTEGER}.
10958 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
10959 @item @var{LEN} @tab The type shall be @code{INTEGER}.
10960 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
10961 same kind as @var{FROM}.
10962 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
10965 @item @emph{Specific names}:
10966 @multitable @columnfractions .20 .23 .20 .33
10967 @headitem Name @tab Argument @tab Return type @tab Standard
10968 @item @code{MVBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
10969 @item @code{BMVBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
10970 @item @code{IMVBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
10971 @item @code{JMVBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
10972 @item @code{KMVBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
10975 @item @emph{See also}:
10987 @section @code{NEAREST} --- Nearest representable number
10989 @cindex real number, nearest different
10990 @cindex floating point, nearest different
10993 @item @emph{Description}:
10994 @code{NEAREST(X, S)} returns the processor-representable number nearest
10995 to @code{X} in the direction indicated by the sign of @code{S}.
10997 @item @emph{Standard}:
10998 Fortran 90 and later
11000 @item @emph{Class}:
11003 @item @emph{Syntax}:
11004 @code{RESULT = NEAREST(X, S)}
11006 @item @emph{Arguments}:
11007 @multitable @columnfractions .15 .70
11008 @item @var{X} @tab Shall be of type @code{REAL}.
11009 @item @var{S} @tab Shall be of type @code{REAL} and
11013 @item @emph{Return value}:
11014 The return value is of the same type as @code{X}. If @code{S} is
11015 positive, @code{NEAREST} returns the processor-representable number
11016 greater than @code{X} and nearest to it. If @code{S} is negative,
11017 @code{NEAREST} returns the processor-representable number smaller than
11018 @code{X} and nearest to it.
11020 @item @emph{Example}:
11022 program test_nearest
11024 x = nearest(42.0, 1.0)
11025 y = nearest(42.0, -1.0)
11026 write (*,"(3(G20.15))") x, y, x - y
11027 end program test_nearest
11034 @section @code{NEW_LINE} --- New line character
11037 @cindex output, newline
11040 @item @emph{Description}:
11041 @code{NEW_LINE(C)} returns the new-line character.
11043 @item @emph{Standard}:
11044 Fortran 2003 and later
11046 @item @emph{Class}:
11049 @item @emph{Syntax}:
11050 @code{RESULT = NEW_LINE(C)}
11052 @item @emph{Arguments}:
11053 @multitable @columnfractions .15 .70
11054 @item @var{C} @tab The argument shall be a scalar or array of the
11055 type @code{CHARACTER}.
11058 @item @emph{Return value}:
11059 Returns a @var{CHARACTER} scalar of length one with the new-line character of
11060 the same kind as parameter @var{C}.
11062 @item @emph{Example}:
11066 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
11067 end program newline
11074 @section @code{NINT} --- Nearest whole number
11077 @cindex rounding, nearest whole number
11080 @item @emph{Description}:
11081 @code{NINT(A)} rounds its argument to the nearest whole number.
11083 @item @emph{Standard}:
11084 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
11086 @item @emph{Class}:
11089 @item @emph{Syntax}:
11090 @code{RESULT = NINT(A [, KIND])}
11092 @item @emph{Arguments}:
11093 @multitable @columnfractions .15 .70
11094 @item @var{A} @tab The type of the argument shall be @code{REAL}.
11095 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
11096 expression indicating the kind parameter of the result.
11099 @item @emph{Return value}:
11100 Returns @var{A} with the fractional portion of its magnitude eliminated by
11101 rounding to the nearest whole number and with its sign preserved,
11102 converted to an @code{INTEGER} of the default kind.
11104 @item @emph{Example}:
11111 print *, nint(x4), idnint(x8)
11112 end program test_nint
11115 @item @emph{Specific names}:
11116 @multitable @columnfractions .20 .23 .20 .33
11117 @headitem Name @tab Argument @tab Return Type @tab Standard
11118 @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
11119 @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
11122 @item @emph{See also}:
11130 @section @code{NORM2} --- Euclidean vector norms
11132 @cindex Euclidean vector norm
11133 @cindex L2 vector norm
11134 @cindex norm, Euclidean
11137 @item @emph{Description}:
11138 Calculates the Euclidean vector norm (@math{L_2} norm)
11139 of @var{ARRAY} along dimension @var{DIM}.
11141 @item @emph{Standard}:
11142 Fortran 2008 and later
11144 @item @emph{Class}:
11145 Transformational function
11147 @item @emph{Syntax}:
11148 @multitable @columnfractions .80
11149 @item @code{RESULT = NORM2(ARRAY[, DIM])}
11152 @item @emph{Arguments}:
11153 @multitable @columnfractions .15 .70
11154 @item @var{ARRAY} @tab Shall be an array of type @code{REAL}
11155 @item @var{DIM} @tab (Optional) shall be a scalar of type
11156 @code{INTEGER} with a value in the range from 1 to n, where n
11157 equals the rank of @var{ARRAY}.
11160 @item @emph{Return value}:
11161 The result is of the same type as @var{ARRAY}.
11163 If @var{DIM} is absent, a scalar with the square root of the sum of all
11164 elements in @var{ARRAY} squared is returned. Otherwise, an array of
11165 rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
11166 shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
11169 @item @emph{Example}:
11172 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
11173 print *, NORM2(x) ! = sqrt(55.) ~ 7.416
11181 @section @code{NOT} --- Logical negation
11187 @cindex bits, negate
11188 @cindex bitwise logical not
11189 @cindex logical not, bitwise
11192 @item @emph{Description}:
11193 @code{NOT} returns the bitwise Boolean inverse of @var{I}.
11195 @item @emph{Standard}:
11196 Fortran 90 and later, has overloads that are GNU extensions
11198 @item @emph{Class}:
11201 @item @emph{Syntax}:
11202 @code{RESULT = NOT(I)}
11204 @item @emph{Arguments}:
11205 @multitable @columnfractions .15 .70
11206 @item @var{I} @tab The type shall be @code{INTEGER}.
11209 @item @emph{Return value}:
11210 The return type is @code{INTEGER}, of the same kind as the
11213 @item @emph{Specific names}:
11214 @multitable @columnfractions .20 .23 .20 .33
11215 @headitem Name @tab Argument @tab Return type @tab Standard
11216 @item @code{NOT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
11217 @item @code{BNOT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
11218 @item @code{INOT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
11219 @item @code{JNOT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
11220 @item @code{KNOT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
11223 @item @emph{See also}:
11235 @section @code{NULL} --- Function that returns an disassociated pointer
11237 @cindex pointer, status
11238 @cindex pointer, disassociated
11241 @item @emph{Description}:
11242 Returns a disassociated pointer.
11244 If @var{MOLD} is present, a disassociated pointer of the same type is
11245 returned, otherwise the type is determined by context.
11247 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
11248 includes cases where it is required.
11250 @item @emph{Standard}:
11251 Fortran 95 and later
11253 @item @emph{Class}:
11254 Transformational function
11256 @item @emph{Syntax}:
11257 @code{PTR => NULL([MOLD])}
11259 @item @emph{Arguments}:
11260 @multitable @columnfractions .15 .70
11261 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
11262 status and of any type.
11265 @item @emph{Return value}:
11266 A disassociated pointer.
11268 @item @emph{Example}:
11270 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
11273 @item @emph{See also}:
11280 @section @code{NUM_IMAGES} --- Function that returns the number of images
11281 @fnindex NUM_IMAGES
11282 @cindex coarray, @code{NUM_IMAGES}
11283 @cindex images, number of
11286 @item @emph{Description}:
11287 Returns the number of images.
11289 @item @emph{Standard}:
11290 Fortran 2008 and later. With @var{DISTANCE} or @var{FAILED} argument,
11291 Technical Specification (TS) 18508 or later
11294 @item @emph{Class}:
11295 Transformational function
11297 @item @emph{Syntax}:
11298 @code{RESULT = NUM_IMAGES(DISTANCE, FAILED)}
11300 @item @emph{Arguments}:
11301 @multitable @columnfractions .15 .70
11302 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
11303 @item @var{FAILED} @tab (optional, intent(in)) Scalar logical expression
11306 @item @emph{Return value}:
11307 Scalar default-kind integer. If @var{DISTANCE} is not present or has value 0,
11308 the number of images in the current team is returned. For values smaller or
11309 equal distance to the initial team, it returns the number of images index
11310 on the ancestor team which has a distance of @var{DISTANCE} from the invoking
11311 team. If @var{DISTANCE} is larger than the distance to the initial team, the
11312 number of images of the initial team is returned. If @var{FAILED} is not present
11313 the total number of images is returned; if it has the value @code{.TRUE.},
11314 the number of failed images is returned, otherwise, the number of images which
11315 do have not the failed status.
11317 @item @emph{Example}:
11319 INTEGER :: value[*]
11321 value = THIS_IMAGE()
11323 IF (THIS_IMAGE() == 1) THEN
11324 DO i = 1, NUM_IMAGES()
11325 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
11330 @item @emph{See also}:
11331 @ref{THIS_IMAGE}, @*
11338 @section @code{OR} --- Bitwise logical OR
11340 @cindex bitwise logical or
11341 @cindex logical or, bitwise
11344 @item @emph{Description}:
11345 Bitwise logical @code{OR}.
11347 This intrinsic routine is provided for backwards compatibility with
11348 GNU Fortran 77. For integer arguments, programmers should consider
11349 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
11351 @item @emph{Standard}:
11354 @item @emph{Class}:
11357 @item @emph{Syntax}:
11358 @code{RESULT = OR(I, J)}
11360 @item @emph{Arguments}:
11361 @multitable @columnfractions .15 .70
11362 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
11363 type or a scalar @code{LOGICAL} type or a boz-literal-constant.
11364 @item @var{J} @tab The type shall be the same as the type of @var{I} or
11365 a boz-literal-constant. @var{I} and @var{J} shall not both be
11366 boz-literal-constants. If either @var{I} and @var{J} is a
11367 boz-literal-constant, then the other argument must be a scalar @code{INTEGER}.
11370 @item @emph{Return value}:
11371 The return type is either a scalar @code{INTEGER} or a scalar
11372 @code{LOGICAL}. If the kind type parameters differ, then the
11373 smaller kind type is implicitly converted to larger kind, and the
11374 return has the larger kind. A boz-literal-constant is
11375 converted to an @code{INTEGER} with the kind type parameter of
11376 the other argument as-if a call to @ref{INT} occurred.
11378 @item @emph{Example}:
11381 LOGICAL :: T = .TRUE., F = .FALSE.
11383 DATA a / Z'F' /, b / Z'3' /
11385 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
11386 WRITE (*,*) OR(a, b)
11390 @item @emph{See also}:
11391 Fortran 95 elemental function: @*
11398 @section @code{PACK} --- Pack an array into an array of rank one
11400 @cindex array, packing
11401 @cindex array, reduce dimension
11402 @cindex array, gather elements
11405 @item @emph{Description}:
11406 Stores the elements of @var{ARRAY} in an array of rank one.
11408 The beginning of the resulting array is made up of elements whose @var{MASK}
11409 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
11412 @item @emph{Standard}:
11413 Fortran 90 and later
11415 @item @emph{Class}:
11416 Transformational function
11418 @item @emph{Syntax}:
11419 @code{RESULT = PACK(ARRAY, MASK[,VECTOR])}
11421 @item @emph{Arguments}:
11422 @multitable @columnfractions .15 .70
11423 @item @var{ARRAY} @tab Shall be an array of any type.
11424 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
11425 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
11427 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
11428 as @var{ARRAY} and of rank one. If present, the number of elements in
11429 @var{VECTOR} shall be equal to or greater than the number of true elements
11430 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
11431 @var{VECTOR} shall be equal to or greater than the number of elements in
11435 @item @emph{Return value}:
11436 The result is an array of rank one and the same type as that of @var{ARRAY}.
11437 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
11438 number of @code{TRUE} values in @var{MASK} otherwise.
11440 @item @emph{Example}:
11441 Gathering nonzero elements from an array:
11443 PROGRAM test_pack_1
11445 m = (/ 1, 0, 0, 0, 5, 0 /)
11446 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
11450 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
11452 PROGRAM test_pack_2
11454 m = (/ 1, 0, 0, 2 /)
11455 ! The following results in "1 2 3 4"
11456 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /))
11460 @item @emph{See also}:
11467 @section @code{PARITY} --- Reduction with exclusive OR
11470 @cindex Reduction, XOR
11471 @cindex XOR reduction
11474 @item @emph{Description}:
11475 Calculates the parity, i.e. the reduction using @code{.XOR.},
11476 of @var{MASK} along dimension @var{DIM}.
11478 @item @emph{Standard}:
11479 Fortran 2008 and later
11481 @item @emph{Class}:
11482 Transformational function
11484 @item @emph{Syntax}:
11485 @multitable @columnfractions .80
11486 @item @code{RESULT = PARITY(MASK[, DIM])}
11489 @item @emph{Arguments}:
11490 @multitable @columnfractions .15 .70
11491 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}
11492 @item @var{DIM} @tab (Optional) shall be a scalar of type
11493 @code{INTEGER} with a value in the range from 1 to n, where n
11494 equals the rank of @var{MASK}.
11497 @item @emph{Return value}:
11498 The result is of the same type as @var{MASK}.
11500 If @var{DIM} is absent, a scalar with the parity of all elements in
11501 @var{MASK} is returned, i.e. true if an odd number of elements is
11502 @code{.true.} and false otherwise. If @var{DIM} is present, an array
11503 of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
11504 and a shape similar to that of @var{MASK} with dimension @var{DIM}
11505 dropped is returned.
11507 @item @emph{Example}:
11510 LOGICAL :: x(2) = [ .true., .false. ]
11511 print *, PARITY(x) ! prints "T" (true).
11519 @section @code{PERROR} --- Print system error message
11521 @cindex system, error handling
11524 @item @emph{Description}:
11525 Prints (on the C @code{stderr} stream) a newline-terminated error
11526 message corresponding to the last system error. This is prefixed by
11527 @var{STRING}, a colon and a space. See @code{perror(3)}.
11529 @item @emph{Standard}:
11532 @item @emph{Class}:
11535 @item @emph{Syntax}:
11536 @code{CALL PERROR(STRING)}
11538 @item @emph{Arguments}:
11539 @multitable @columnfractions .15 .70
11540 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
11544 @item @emph{See also}:
11551 @section @code{POPCNT} --- Number of bits set
11553 @cindex binary representation
11557 @item @emph{Description}:
11558 @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
11559 representation of @code{I}.
11561 @item @emph{Standard}:
11562 Fortran 2008 and later
11564 @item @emph{Class}:
11567 @item @emph{Syntax}:
11568 @code{RESULT = POPCNT(I)}
11570 @item @emph{Arguments}:
11571 @multitable @columnfractions .15 .70
11572 @item @var{I} @tab Shall be of type @code{INTEGER}.
11575 @item @emph{Return value}:
11576 The return value is of type @code{INTEGER} and of the default integer
11579 @item @emph{Example}:
11581 program test_population
11582 print *, popcnt(127), poppar(127)
11583 print *, popcnt(huge(0_4)), poppar(huge(0_4))
11584 print *, popcnt(huge(0_8)), poppar(huge(0_8))
11585 end program test_population
11587 @item @emph{See also}:
11596 @section @code{POPPAR} --- Parity of the number of bits set
11598 @cindex binary representation
11602 @item @emph{Description}:
11603 @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
11604 of the number of bits set ('1' bits) in the binary representation of
11605 @code{I}. It is equal to 0 if @code{I} has an even number of bits set,
11606 and 1 for an odd number of '1' bits.
11608 @item @emph{Standard}:
11609 Fortran 2008 and later
11611 @item @emph{Class}:
11614 @item @emph{Syntax}:
11615 @code{RESULT = POPPAR(I)}
11617 @item @emph{Arguments}:
11618 @multitable @columnfractions .15 .70
11619 @item @var{I} @tab Shall be of type @code{INTEGER}.
11622 @item @emph{Return value}:
11623 The return value is of type @code{INTEGER} and of the default integer
11626 @item @emph{Example}:
11628 program test_population
11629 print *, popcnt(127), poppar(127)
11630 print *, popcnt(huge(0_4)), poppar(huge(0_4))
11631 print *, popcnt(huge(0_8)), poppar(huge(0_8))
11632 end program test_population
11634 @item @emph{See also}:
11643 @section @code{PRECISION} --- Decimal precision of a real kind
11645 @cindex model representation, precision
11648 @item @emph{Description}:
11649 @code{PRECISION(X)} returns the decimal precision in the model of the
11652 @item @emph{Standard}:
11653 Fortran 90 and later
11655 @item @emph{Class}:
11658 @item @emph{Syntax}:
11659 @code{RESULT = PRECISION(X)}
11661 @item @emph{Arguments}:
11662 @multitable @columnfractions .15 .70
11663 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}. It may
11664 be scalar or valued.
11667 @item @emph{Return value}:
11668 The return value is of type @code{INTEGER} and of the default integer
11671 @item @emph{Example}:
11673 program prec_and_range
11674 real(kind=4) :: x(2)
11675 complex(kind=8) :: y
11677 print *, precision(x), range(x)
11678 print *, precision(y), range(y)
11679 end program prec_and_range
11681 @item @emph{See also}:
11682 @ref{SELECTED_REAL_KIND}, @*
11689 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
11693 @item @emph{Description}:
11694 Determines whether an optional dummy argument is present.
11696 @item @emph{Standard}:
11697 Fortran 90 and later
11699 @item @emph{Class}:
11702 @item @emph{Syntax}:
11703 @code{RESULT = PRESENT(A)}
11705 @item @emph{Arguments}:
11706 @multitable @columnfractions .15 .70
11707 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
11708 value, or a dummy procedure. It shall be the name of an optional dummy argument
11709 accessible within the current subroutine or function.
11712 @item @emph{Return value}:
11713 Returns either @code{TRUE} if the optional argument @var{A} is present, or
11714 @code{FALSE} otherwise.
11716 @item @emph{Example}:
11718 PROGRAM test_present
11719 WRITE(*,*) f(), f(42) ! "F T"
11721 LOGICAL FUNCTION f(x)
11722 INTEGER, INTENT(IN), OPTIONAL :: x
11732 @section @code{PRODUCT} --- Product of array elements
11734 @cindex array, product
11735 @cindex array, multiply elements
11736 @cindex array, conditionally multiply elements
11737 @cindex multiply array elements
11740 @item @emph{Description}:
11741 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
11742 the corresponding element in @var{MASK} is @code{TRUE}.
11744 @item @emph{Standard}:
11745 Fortran 90 and later
11747 @item @emph{Class}:
11748 Transformational function
11750 @item @emph{Syntax}:
11751 @multitable @columnfractions .80
11752 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
11753 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
11756 @item @emph{Arguments}:
11757 @multitable @columnfractions .15 .70
11758 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
11759 @code{REAL} or @code{COMPLEX}.
11760 @item @var{DIM} @tab (Optional) shall be a scalar of type
11761 @code{INTEGER} with a value in the range from 1 to n, where n
11762 equals the rank of @var{ARRAY}.
11763 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
11764 and either be a scalar or an array of the same shape as @var{ARRAY}.
11767 @item @emph{Return value}:
11768 The result is of the same type as @var{ARRAY}.
11770 If @var{DIM} is absent, a scalar with the product of all elements in
11771 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
11772 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
11773 dimension @var{DIM} dropped is returned.
11776 @item @emph{Example}:
11778 PROGRAM test_product
11779 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
11780 print *, PRODUCT(x) ! all elements, product = 120
11781 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
11785 @item @emph{See also}:
11792 @section @code{RADIX} --- Base of a model number
11794 @cindex model representation, base
11795 @cindex model representation, radix
11798 @item @emph{Description}:
11799 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
11801 @item @emph{Standard}:
11802 Fortran 90 and later
11804 @item @emph{Class}:
11807 @item @emph{Syntax}:
11808 @code{RESULT = RADIX(X)}
11810 @item @emph{Arguments}:
11811 @multitable @columnfractions .15 .70
11812 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
11815 @item @emph{Return value}:
11816 The return value is a scalar of type @code{INTEGER} and of the default
11819 @item @emph{Example}:
11822 print *, "The radix for the default integer kind is", radix(0)
11823 print *, "The radix for the default real kind is", radix(0.0)
11824 end program test_radix
11826 @item @emph{See also}:
11827 @ref{SELECTED_REAL_KIND}
11833 @section @code{RAN} --- Real pseudo-random number
11835 @cindex random number generation
11838 @item @emph{Description}:
11839 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
11840 provided as an alias for @code{RAND}. See @ref{RAND} for complete
11843 @item @emph{Standard}:
11846 @item @emph{Class}:
11849 @item @emph{See also}:
11851 @ref{RANDOM_NUMBER}
11857 @section @code{RAND} --- Real pseudo-random number
11859 @cindex random number generation
11862 @item @emph{Description}:
11863 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
11864 distribution between 0 and 1. If @var{FLAG} is 0, the next number
11865 in the current sequence is returned; if @var{FLAG} is 1, the generator
11866 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
11867 it is used as a new seed with @code{SRAND}.
11869 This intrinsic routine is provided for backwards compatibility with
11870 GNU Fortran 77. It implements a simple modulo generator as provided
11871 by @command{g77}. For new code, one should consider the use of
11872 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
11874 @item @emph{Standard}:
11877 @item @emph{Class}:
11880 @item @emph{Syntax}:
11881 @code{RESULT = RAND(I)}
11883 @item @emph{Arguments}:
11884 @multitable @columnfractions .15 .70
11885 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
11888 @item @emph{Return value}:
11889 The return value is of @code{REAL} type and the default kind.
11891 @item @emph{Example}:
11894 integer,parameter :: seed = 86456
11897 print *, rand(), rand(), rand(), rand()
11898 print *, rand(seed), rand(), rand(), rand()
11899 end program test_rand
11902 @item @emph{See also}:
11904 @ref{RANDOM_NUMBER}
11910 @section @code{RANDOM_INIT} --- Initialize a pseudo-random number generator
11911 @fnindex RANDOM_INIT
11912 @cindex random number generation, initialization
11915 @item @emph{Description}:
11916 Initializes the state of the pseudorandom number generator used by
11917 @code{RANDOM_NUMBER}.
11919 @item @emph{Standard}:
11922 @item @emph{Class}:
11925 @item @emph{Syntax}:
11926 @code{CALL RANDOM_INIT(REPEATABLE, IMAGE_DISTINCT)}
11928 @item @emph{Arguments}:
11929 @multitable @columnfractions .25 .70
11930 @item @var{REPEATABLE} @tab Shall be a scalar with a @code{LOGICAL} type,
11931 and it is @code{INTENT(IN)}. If it is @code{.true.}, the seed is set to
11932 a processor-dependent value that is the same each time @code{RANDOM_INIT}
11933 is called from the same image. The term ``same image'' means a single
11934 instance of program execution. The sequence of random numbers is different
11935 for repeated execution of the program. If it is @code{.false.}, the seed
11936 is set to a processor-dependent value.
11937 @item @var{IMAGE_DISTINCT} @tab Shall be a scalar with a
11938 @code{LOGICAL} type, and it is @code{INTENT(IN)}. If it is @code{.true.},
11939 the seed is set to a processor-dependent value that is distinct from th
11940 seed set by a call to @code{RANDOM_INIT} in another image. If it is
11941 @code{.false.}, the seed is set to a value that does depend which image called
11942 @code{RANDOM_INIT}.
11945 @item @emph{Example}:
11947 program test_random_seed
11950 call random_init(.true., .true.)
11951 call random_number(x)
11952 call random_init(.true., .true.)
11953 call random_number(y)
11954 ! x and y are the same sequence
11955 if (any(x /= y)) call abort
11956 end program test_random_seed
11959 @item @emph{See also}:
11960 @ref{RANDOM_NUMBER}, @*
11965 @node RANDOM_NUMBER
11966 @section @code{RANDOM_NUMBER} --- Pseudo-random number
11967 @fnindex RANDOM_NUMBER
11968 @cindex random number generation
11971 @item @emph{Description}:
11972 Returns a single pseudorandom number or an array of pseudorandom numbers
11973 from the uniform distribution over the range @math{ 0 \leq x < 1}.
11975 The runtime-library implements the xoshiro256** pseudorandom number
11976 generator (PRNG). This generator has a period of @math{2^{256} - 1},
11977 and when using multiple threads up to @math{2^{128}} threads can each
11978 generate @math{2^{128}} random numbers before any aliasing occurs.
11980 Note that in a multi-threaded program (e.g. using OpenMP directives),
11981 each thread will have its own random number state. For details of the
11982 seeding procedure, see the documentation for the @code{RANDOM_SEED}
11986 @item @emph{Standard}:
11987 Fortran 90 and later
11989 @item @emph{Class}:
11992 @item @emph{Syntax}:
11993 @code{CALL RANDOM_NUMBER(HARVEST)}
11995 @item @emph{Arguments}:
11996 @multitable @columnfractions .15 .70
11997 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
12000 @item @emph{Example}:
12002 program test_random_number
12004 CALL RANDOM_NUMBER(r)
12008 @item @emph{See also}:
12009 @ref{RANDOM_SEED}, @*
12016 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
12017 @fnindex RANDOM_SEED
12018 @cindex random number generation, seeding
12019 @cindex seeding a random number generator
12022 @item @emph{Description}:
12023 Restarts or queries the state of the pseudorandom number generator used by
12024 @code{RANDOM_NUMBER}.
12026 If @code{RANDOM_SEED} is called without arguments, it is seeded with
12027 random data retrieved from the operating system.
12029 As an extension to the Fortran standard, the GFortran
12030 @code{RANDOM_NUMBER} supports multiple threads. Each thread in a
12031 multi-threaded program has its own seed. When @code{RANDOM_SEED} is
12032 called either without arguments or with the @var{PUT} argument, the
12033 given seed is copied into a master seed as well as the seed of the
12034 current thread. When a new thread uses @code{RANDOM_NUMBER} for the
12035 first time, the seed is copied from the master seed, and forwarded
12036 @math{N * 2^{128}} steps to guarantee that the random stream does not
12037 alias any other stream in the system, where @var{N} is the number of
12038 threads that have used @code{RANDOM_NUMBER} so far during the program
12041 @item @emph{Standard}:
12042 Fortran 90 and later
12044 @item @emph{Class}:
12047 @item @emph{Syntax}:
12048 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
12050 @item @emph{Arguments}:
12051 @multitable @columnfractions .15 .70
12052 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
12053 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
12054 of the arrays used with the @var{PUT} and @var{GET} arguments.
12055 @item @var{PUT} @tab (Optional) Shall be an array of type default
12056 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
12057 the array must be larger than or equal to the number returned by the
12058 @var{SIZE} argument.
12059 @item @var{GET} @tab (Optional) Shall be an array of type default
12060 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
12061 of the array must be larger than or equal to the number returned by
12062 the @var{SIZE} argument.
12065 @item @emph{Example}:
12067 program test_random_seed
12069 integer, allocatable :: seed(:)
12072 call random_seed(size = n)
12074 call random_seed(get=seed)
12076 end program test_random_seed
12079 @item @emph{See also}:
12080 @ref{RANDOM_NUMBER}, @*
12087 @section @code{RANGE} --- Decimal exponent range
12089 @cindex model representation, range
12092 @item @emph{Description}:
12093 @code{RANGE(X)} returns the decimal exponent range in the model of the
12096 @item @emph{Standard}:
12097 Fortran 90 and later
12099 @item @emph{Class}:
12102 @item @emph{Syntax}:
12103 @code{RESULT = RANGE(X)}
12105 @item @emph{Arguments}:
12106 @multitable @columnfractions .15 .70
12107 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
12111 @item @emph{Return value}:
12112 The return value is of type @code{INTEGER} and of the default integer
12115 @item @emph{Example}:
12116 See @code{PRECISION} for an example.
12117 @item @emph{See also}:
12118 @ref{SELECTED_REAL_KIND}, @*
12125 @section @code{RANK} --- Rank of a data object
12130 @item @emph{Description}:
12131 @code{RANK(A)} returns the rank of a scalar or array data object.
12133 @item @emph{Standard}:
12134 Technical Specification (TS) 29113
12136 @item @emph{Class}:
12139 @item @emph{Syntax}:
12140 @code{RESULT = RANK(A)}
12142 @item @emph{Arguments}:
12143 @multitable @columnfractions .15 .70
12144 @item @var{A} @tab can be of any type
12147 @item @emph{Return value}:
12148 The return value is of type @code{INTEGER} and of the default integer
12149 kind. For arrays, their rank is returned; for scalars zero is returned.
12151 @item @emph{Example}:
12155 real, allocatable :: b(:,:)
12157 print *, rank(a), rank(b) ! Prints: 0 2
12158 end program test_rank
12166 @section @code{REAL} --- Convert to real type
12175 @cindex conversion, to real
12176 @cindex complex numbers, real part
12179 @item @emph{Description}:
12180 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
12181 @code{REALPART} function is provided for compatibility with @command{g77},
12182 and its use is strongly discouraged.
12184 @item @emph{Standard}:
12185 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later, has GNU extensions
12187 @item @emph{Class}:
12190 @item @emph{Syntax}:
12191 @multitable @columnfractions .80
12192 @item @code{RESULT = REAL(A [, KIND])}
12193 @item @code{RESULT = REALPART(Z)}
12196 @item @emph{Arguments}:
12197 @multitable @columnfractions .15 .70
12198 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
12200 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
12201 expression indicating the kind parameter of the result.
12204 @item @emph{Return value}:
12205 These functions return a @code{REAL} variable or array under
12206 the following rules:
12210 @code{REAL(A)} is converted to a default real type if @var{A} is an
12211 integer or real variable.
12213 @code{REAL(A)} is converted to a real type with the kind type parameter
12214 of @var{A} if @var{A} is a complex variable.
12216 @code{REAL(A, KIND)} is converted to a real type with kind type
12217 parameter @var{KIND} if @var{A} is a complex, integer, or real
12221 @item @emph{Example}:
12224 complex :: x = (1.0, 2.0)
12225 print *, real(x), real(x,8), realpart(x)
12226 end program test_real
12229 @item @emph{Specific names}:
12230 @multitable @columnfractions .20 .23 .20 .33
12231 @headitem Name @tab Argument @tab Return type @tab Standard
12232 @item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later
12233 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension
12234 @item @code{FLOATI(A)} @tab @code{INTEGER(2)} @tab @code{REAL(4)} @tab GNU extension (-fdec)
12235 @item @code{FLOATJ(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab GNU extension (-fdec)
12236 @item @code{FLOATK(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab GNU extension (-fdec)
12237 @item @code{SNGL(A)} @tab @code{REAL(8)} @tab @code{REAL(4)} @tab Fortran 77 and later
12241 @item @emph{See also}:
12249 @section @code{RENAME} --- Rename a file
12251 @cindex file system, rename file
12254 @item @emph{Description}:
12255 Renames a file from file @var{PATH1} to @var{PATH2}. A null
12256 character (@code{CHAR(0)}) can be used to mark the end of the names in
12257 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
12258 names are ignored. If the @var{STATUS} argument is supplied, it
12259 contains 0 on success or a nonzero error code upon return; see
12262 This intrinsic is provided in both subroutine and function forms;
12263 however, only one form can be used in any given program unit.
12265 @item @emph{Standard}:
12268 @item @emph{Class}:
12269 Subroutine, function
12271 @item @emph{Syntax}:
12272 @multitable @columnfractions .80
12273 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
12274 @item @code{STATUS = RENAME(PATH1, PATH2)}
12277 @item @emph{Arguments}:
12278 @multitable @columnfractions .15 .70
12279 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
12280 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
12281 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12284 @item @emph{See also}:
12292 @section @code{REPEAT} --- Repeated string concatenation
12294 @cindex string, repeat
12295 @cindex string, concatenate
12298 @item @emph{Description}:
12299 Concatenates @var{NCOPIES} copies of a string.
12301 @item @emph{Standard}:
12302 Fortran 90 and later
12304 @item @emph{Class}:
12305 Transformational function
12307 @item @emph{Syntax}:
12308 @code{RESULT = REPEAT(STRING, NCOPIES)}
12310 @item @emph{Arguments}:
12311 @multitable @columnfractions .15 .70
12312 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
12313 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
12316 @item @emph{Return value}:
12317 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
12320 @item @emph{Example}:
12322 program test_repeat
12323 write(*,*) repeat("x", 5) ! "xxxxx"
12331 @section @code{RESHAPE} --- Function to reshape an array
12333 @cindex array, change dimensions
12334 @cindex array, transmogrify
12337 @item @emph{Description}:
12338 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
12339 the new array may be padded with elements from @var{PAD} or permuted
12340 as defined by @var{ORDER}.
12342 @item @emph{Standard}:
12343 Fortran 90 and later
12345 @item @emph{Class}:
12346 Transformational function
12348 @item @emph{Syntax}:
12349 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
12351 @item @emph{Arguments}:
12352 @multitable @columnfractions .15 .70
12353 @item @var{SOURCE} @tab Shall be an array of any type.
12354 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
12355 array of rank one. Its values must be positive or zero.
12356 @item @var{PAD} @tab (Optional) shall be an array of the same
12357 type as @var{SOURCE}.
12358 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
12359 and an array of the same shape as @var{SHAPE}. Its values shall
12360 be a permutation of the numbers from 1 to n, where n is the size of
12361 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
12365 @item @emph{Return value}:
12366 The result is an array of shape @var{SHAPE} with the same type as
12369 @item @emph{Example}:
12371 PROGRAM test_reshape
12372 INTEGER, DIMENSION(4) :: x
12373 WRITE(*,*) SHAPE(x) ! prints "4"
12374 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
12378 @item @emph{See also}:
12385 @section @code{RRSPACING} --- Reciprocal of the relative spacing
12387 @cindex real number, relative spacing
12388 @cindex floating point, relative spacing
12392 @item @emph{Description}:
12393 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
12394 model numbers near @var{X}.
12396 @item @emph{Standard}:
12397 Fortran 90 and later
12399 @item @emph{Class}:
12402 @item @emph{Syntax}:
12403 @code{RESULT = RRSPACING(X)}
12405 @item @emph{Arguments}:
12406 @multitable @columnfractions .15 .70
12407 @item @var{X} @tab Shall be of type @code{REAL}.
12410 @item @emph{Return value}:
12411 The return value is of the same type and kind as @var{X}.
12412 The value returned is equal to
12413 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
12415 @item @emph{See also}:
12422 @section @code{RSHIFT} --- Right shift bits
12424 @cindex bits, shift right
12427 @item @emph{Description}:
12428 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
12429 bits shifted right by @var{SHIFT} places. @var{SHIFT} shall be
12430 nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
12431 the result value is undefined. Bits shifted out from the right end
12432 are lost. The fill is arithmetic: the bits shifted in from the left
12433 end are equal to the leftmost bit, which in two's complement
12434 representation is the sign bit.
12436 This function has been superseded by the @code{SHIFTA} intrinsic, which
12437 is standard in Fortran 2008 and later.
12439 @item @emph{Standard}:
12442 @item @emph{Class}:
12445 @item @emph{Syntax}:
12446 @code{RESULT = RSHIFT(I, SHIFT)}
12448 @item @emph{Arguments}:
12449 @multitable @columnfractions .15 .70
12450 @item @var{I} @tab The type shall be @code{INTEGER}.
12451 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12454 @item @emph{Return value}:
12455 The return value is of type @code{INTEGER} and of the same kind as
12458 @item @emph{See also}:
12471 @section @code{SAME_TYPE_AS} --- Query dynamic types for equality
12472 @fnindex SAME_TYPE_AS
12475 @item @emph{Description}:
12476 Query dynamic types for equality.
12478 @item @emph{Standard}:
12479 Fortran 2003 and later
12481 @item @emph{Class}:
12484 @item @emph{Syntax}:
12485 @code{RESULT = SAME_TYPE_AS(A, B)}
12487 @item @emph{Arguments}:
12488 @multitable @columnfractions .15 .70
12489 @item @var{A} @tab Shall be an object of extensible declared type or
12490 unlimited polymorphic.
12491 @item @var{B} @tab Shall be an object of extensible declared type or
12492 unlimited polymorphic.
12495 @item @emph{Return value}:
12496 The return value is a scalar of type default logical. It is true if and
12497 only if the dynamic type of A is the same as the dynamic type of B.
12499 @item @emph{See also}:
12500 @ref{EXTENDS_TYPE_OF}
12507 @section @code{SCALE} --- Scale a real value
12509 @cindex real number, scale
12510 @cindex floating point, scale
12513 @item @emph{Description}:
12514 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
12516 @item @emph{Standard}:
12517 Fortran 90 and later
12519 @item @emph{Class}:
12522 @item @emph{Syntax}:
12523 @code{RESULT = SCALE(X, I)}
12525 @item @emph{Arguments}:
12526 @multitable @columnfractions .15 .70
12527 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
12528 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
12531 @item @emph{Return value}:
12532 The return value is of the same type and kind as @var{X}.
12533 Its value is @code{X * RADIX(X)**I}.
12535 @item @emph{Example}:
12538 real :: x = 178.1387e-4
12540 print *, scale(x,i), x*radix(x)**i
12541 end program test_scale
12549 @section @code{SCAN} --- Scan a string for the presence of a set of characters
12551 @cindex string, find subset
12554 @item @emph{Description}:
12555 Scans a @var{STRING} for any of the characters in a @var{SET}
12558 If @var{BACK} is either absent or equals @code{FALSE}, this function
12559 returns the position of the leftmost character of @var{STRING} that is
12560 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
12561 is returned. If no character of @var{SET} is found in @var{STRING}, the
12564 @item @emph{Standard}:
12565 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
12567 @item @emph{Class}:
12570 @item @emph{Syntax}:
12571 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
12573 @item @emph{Arguments}:
12574 @multitable @columnfractions .15 .70
12575 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
12576 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
12577 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
12578 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
12579 expression indicating the kind parameter of the result.
12582 @item @emph{Return value}:
12583 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12584 @var{KIND} is absent, the return value is of default integer kind.
12586 @item @emph{Example}:
12589 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
12590 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
12591 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
12595 @item @emph{See also}:
12596 @ref{INDEX intrinsic}, @*
12603 @section @code{SECNDS} --- Time function
12605 @cindex time, elapsed
12606 @cindex elapsed time
12609 @item @emph{Description}:
12610 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
12611 @var{X} is a reference time, also in seconds. If this is zero, the time in
12612 seconds from midnight is returned. This function is non-standard and its
12613 use is discouraged.
12615 @item @emph{Standard}:
12618 @item @emph{Class}:
12621 @item @emph{Syntax}:
12622 @code{RESULT = SECNDS (X)}
12624 @item @emph{Arguments}:
12625 @multitable @columnfractions .15 .70
12626 @item @var{T} @tab Shall be of type @code{REAL(4)}.
12627 @item @var{X} @tab Shall be of type @code{REAL(4)}.
12630 @item @emph{Return value}:
12633 @item @emph{Example}:
12635 program test_secnds
12638 print *, secnds (0.0) ! seconds since midnight
12639 t1 = secnds (0.0) ! reference time
12640 do i = 1, 10000000 ! do something
12642 t2 = secnds (t1) ! elapsed time
12643 print *, "Something took ", t2, " seconds."
12644 end program test_secnds
12651 @section @code{SECOND} --- CPU time function
12653 @cindex time, elapsed
12654 @cindex elapsed time
12657 @item @emph{Description}:
12658 Returns a @code{REAL(4)} value representing the elapsed CPU time in
12659 seconds. This provides the same functionality as the standard
12660 @code{CPU_TIME} intrinsic, and is only included for backwards
12663 This intrinsic is provided in both subroutine and function forms;
12664 however, only one form can be used in any given program unit.
12666 @item @emph{Standard}:
12669 @item @emph{Class}:
12670 Subroutine, function
12672 @item @emph{Syntax}:
12673 @multitable @columnfractions .80
12674 @item @code{CALL SECOND(TIME)}
12675 @item @code{TIME = SECOND()}
12678 @item @emph{Arguments}:
12679 @multitable @columnfractions .15 .70
12680 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
12683 @item @emph{Return value}:
12684 In either syntax, @var{TIME} is set to the process's current runtime in
12687 @item @emph{See also}:
12694 @node SELECTED_CHAR_KIND
12695 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
12696 @fnindex SELECTED_CHAR_KIND
12697 @cindex character kind
12698 @cindex kind, character
12701 @item @emph{Description}:
12703 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
12704 set named @var{NAME}, if a character set with such a name is supported,
12705 or @math{-1} otherwise. Currently, supported character sets include
12706 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
12707 (Universal Character Set, UCS-4) which is commonly known as Unicode.
12709 @item @emph{Standard}:
12710 Fortran 2003 and later
12712 @item @emph{Class}:
12713 Transformational function
12715 @item @emph{Syntax}:
12716 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
12718 @item @emph{Arguments}:
12719 @multitable @columnfractions .15 .70
12720 @item @var{NAME} @tab Shall be a scalar and of the default character type.
12723 @item @emph{Example}:
12725 program character_kind
12726 use iso_fortran_env
12728 integer, parameter :: ascii = selected_char_kind ("ascii")
12729 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646')
12731 character(kind=ascii, len=26) :: alphabet
12732 character(kind=ucs4, len=30) :: hello_world
12734 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
12735 hello_world = ucs4_'Hello World and Ni Hao -- ' &
12736 // char (int (z'4F60'), ucs4) &
12737 // char (int (z'597D'), ucs4)
12739 write (*,*) alphabet
12741 open (output_unit, encoding='UTF-8')
12742 write (*,*) trim (hello_world)
12743 end program character_kind
12749 @node SELECTED_INT_KIND
12750 @section @code{SELECTED_INT_KIND} --- Choose integer kind
12751 @fnindex SELECTED_INT_KIND
12752 @cindex integer kind
12753 @cindex kind, integer
12756 @item @emph{Description}:
12757 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
12758 type that can represent all values ranging from @math{-10^R} (exclusive)
12759 to @math{10^R} (exclusive). If there is no integer kind that accommodates
12760 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
12762 @item @emph{Standard}:
12763 Fortran 90 and later
12765 @item @emph{Class}:
12766 Transformational function
12768 @item @emph{Syntax}:
12769 @code{RESULT = SELECTED_INT_KIND(R)}
12771 @item @emph{Arguments}:
12772 @multitable @columnfractions .15 .70
12773 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
12776 @item @emph{Example}:
12778 program large_integers
12779 integer,parameter :: k5 = selected_int_kind(5)
12780 integer,parameter :: k15 = selected_int_kind(15)
12781 integer(kind=k5) :: i5
12782 integer(kind=k15) :: i15
12784 print *, huge(i5), huge(i15)
12786 ! The following inequalities are always true
12787 print *, huge(i5) >= 10_k5**5-1
12788 print *, huge(i15) >= 10_k15**15-1
12789 end program large_integers
12795 @node SELECTED_REAL_KIND
12796 @section @code{SELECTED_REAL_KIND} --- Choose real kind
12797 @fnindex SELECTED_REAL_KIND
12800 @cindex radix, real
12803 @item @emph{Description}:
12804 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
12805 with decimal precision of at least @code{P} digits, exponent range of
12806 at least @code{R}, and with a radix of @code{RADIX}.
12808 @item @emph{Standard}:
12809 Fortran 90 and later, with @code{RADIX} Fortran 2008 or later
12811 @item @emph{Class}:
12812 Transformational function
12814 @item @emph{Syntax}:
12815 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
12817 @item @emph{Arguments}:
12818 @multitable @columnfractions .15 .70
12819 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12820 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12821 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12823 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
12824 be present; since Fortran 2008, they are assumed to be zero if absent.
12826 @item @emph{Return value}:
12828 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
12829 a real data type with decimal precision of at least @code{P} digits, a
12830 decimal exponent range of at least @code{R}, and with the requested
12831 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
12832 any radix can be returned. If more than one real data type meet the
12833 criteria, the kind of the data type with the smallest decimal precision
12834 is returned. If no real data type matches the criteria, the result is
12836 @item -1 if the processor does not support a real data type with a
12837 precision greater than or equal to @code{P}, but the @code{R} and
12838 @code{RADIX} requirements can be fulfilled
12839 @item -2 if the processor does not support a real type with an exponent
12840 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
12842 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
12844 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
12846 @item -5 if there is no real type with the given @code{RADIX}
12849 @item @emph{Example}:
12852 integer,parameter :: p6 = selected_real_kind(6)
12853 integer,parameter :: p10r100 = selected_real_kind(10,100)
12854 integer,parameter :: r400 = selected_real_kind(r=400)
12856 real(kind=p10r100) :: y
12857 real(kind=r400) :: z
12859 print *, precision(x), range(x)
12860 print *, precision(y), range(y)
12861 print *, precision(z), range(z)
12862 end program real_kinds
12864 @item @emph{See also}:
12865 @ref{PRECISION}, @*
12873 @section @code{SET_EXPONENT} --- Set the exponent of the model
12874 @fnindex SET_EXPONENT
12875 @cindex real number, set exponent
12876 @cindex floating point, set exponent
12879 @item @emph{Description}:
12880 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
12881 is that of @var{X} and whose exponent part is @var{I}.
12883 @item @emph{Standard}:
12884 Fortran 90 and later
12886 @item @emph{Class}:
12889 @item @emph{Syntax}:
12890 @code{RESULT = SET_EXPONENT(X, I)}
12892 @item @emph{Arguments}:
12893 @multitable @columnfractions .15 .70
12894 @item @var{X} @tab Shall be of type @code{REAL}.
12895 @item @var{I} @tab Shall be of type @code{INTEGER}.
12898 @item @emph{Return value}:
12899 The return value is of the same type and kind as @var{X}.
12900 The real number whose fractional part
12901 is that of @var{X} and whose exponent part if @var{I} is returned;
12902 it is @code{FRACTION(X) * RADIX(X)**I}.
12904 @item @emph{Example}:
12906 PROGRAM test_setexp
12907 REAL :: x = 178.1387e-4
12909 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
12918 @section @code{SHAPE} --- Determine the shape of an array
12920 @cindex array, shape
12923 @item @emph{Description}:
12924 Determines the shape of an array.
12926 @item @emph{Standard}:
12927 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
12929 @item @emph{Class}:
12932 @item @emph{Syntax}:
12933 @code{RESULT = SHAPE(SOURCE [, KIND])}
12935 @item @emph{Arguments}:
12936 @multitable @columnfractions .15 .70
12937 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
12938 If @var{SOURCE} is a pointer it must be associated and allocatable
12939 arrays must be allocated.
12940 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
12941 expression indicating the kind parameter of the result.
12944 @item @emph{Return value}:
12945 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
12946 has dimensions. The elements of the resulting array correspond to the extend
12947 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
12948 the result is the rank one array of size zero. If @var{KIND} is absent, the
12949 return value has the default integer kind otherwise the specified kind.
12951 @item @emph{Example}:
12954 INTEGER, DIMENSION(-1:1, -1:2) :: A
12955 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
12956 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
12960 @item @emph{See also}:
12968 @section @code{SHIFTA} --- Right shift with fill
12970 @cindex bits, shift right
12971 @cindex shift, right with fill
12974 @item @emph{Description}:
12975 @code{SHIFTA} returns a value corresponding to @var{I} with all of the
12976 bits shifted right by @var{SHIFT} places. @var{SHIFT} that be
12977 nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
12978 the result value is undefined. Bits shifted out from the right end
12979 are lost. The fill is arithmetic: the bits shifted in from the left
12980 end are equal to the leftmost bit, which in two's complement
12981 representation is the sign bit.
12983 @item @emph{Standard}:
12984 Fortran 2008 and later
12986 @item @emph{Class}:
12989 @item @emph{Syntax}:
12990 @code{RESULT = SHIFTA(I, SHIFT)}
12992 @item @emph{Arguments}:
12993 @multitable @columnfractions .15 .70
12994 @item @var{I} @tab The type shall be @code{INTEGER}.
12995 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12998 @item @emph{Return value}:
12999 The return value is of type @code{INTEGER} and of the same kind as
13002 @item @emph{See also}:
13010 @section @code{SHIFTL} --- Left shift
13012 @cindex bits, shift left
13013 @cindex shift, left
13016 @item @emph{Description}:
13017 @code{SHIFTL} returns a value corresponding to @var{I} with all of the
13018 bits shifted left by @var{SHIFT} places. @var{SHIFT} shall be
13019 nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
13020 the result value is undefined. Bits shifted out from the left end are
13021 lost, and bits shifted in from the right end are set to 0.
13023 @item @emph{Standard}:
13024 Fortran 2008 and later
13026 @item @emph{Class}:
13029 @item @emph{Syntax}:
13030 @code{RESULT = SHIFTL(I, SHIFT)}
13032 @item @emph{Arguments}:
13033 @multitable @columnfractions .15 .70
13034 @item @var{I} @tab The type shall be @code{INTEGER}.
13035 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
13038 @item @emph{Return value}:
13039 The return value is of type @code{INTEGER} and of the same kind as
13042 @item @emph{See also}:
13050 @section @code{SHIFTR} --- Right shift
13052 @cindex bits, shift right
13053 @cindex shift, right
13056 @item @emph{Description}:
13057 @code{SHIFTR} returns a value corresponding to @var{I} with all of the
13058 bits shifted right by @var{SHIFT} places. @var{SHIFT} shall be
13059 nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
13060 the result value is undefined. Bits shifted out from the right end
13061 are lost, and bits shifted in from the left end are set to 0.
13063 @item @emph{Standard}:
13064 Fortran 2008 and later
13066 @item @emph{Class}:
13069 @item @emph{Syntax}:
13070 @code{RESULT = SHIFTR(I, SHIFT)}
13072 @item @emph{Arguments}:
13073 @multitable @columnfractions .15 .70
13074 @item @var{I} @tab The type shall be @code{INTEGER}.
13075 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
13078 @item @emph{Return value}:
13079 The return value is of type @code{INTEGER} and of the same kind as
13082 @item @emph{See also}:
13090 @section @code{SIGN} --- Sign copying function
13094 @cindex sign copying
13097 @item @emph{Description}:
13098 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
13100 @item @emph{Standard}:
13101 Fortran 77 and later
13103 @item @emph{Class}:
13106 @item @emph{Syntax}:
13107 @code{RESULT = SIGN(A, B)}
13109 @item @emph{Arguments}:
13110 @multitable @columnfractions .15 .70
13111 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
13112 @item @var{B} @tab Shall be of the same type and kind as @var{A}.
13115 @item @emph{Return value}:
13116 The kind of the return value is that of @var{A} and @var{B}.
13117 If @math{B \ge 0} then the result is @code{ABS(A)}, else
13118 it is @code{-ABS(A)}.
13120 @item @emph{Example}:
13123 print *, sign(-12,1)
13124 print *, sign(-12,0)
13125 print *, sign(-12,-1)
13127 print *, sign(-12.,1.)
13128 print *, sign(-12.,0.)
13129 print *, sign(-12.,-1.)
13130 end program test_sign
13133 @item @emph{Specific names}:
13134 @multitable @columnfractions .20 .26 .20 .30
13135 @headitem Name @tab Arguments @tab Return type @tab Standard
13136 @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab Fortran 77 and later
13137 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab Fortran 77 and later
13138 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab Fortran 77 and later
13145 @section @code{SIGNAL} --- Signal handling subroutine (or function)
13147 @cindex system, signal handling
13150 @item @emph{Description}:
13151 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
13152 @var{HANDLER} to be executed with a single integer argument passed by
13153 value when signal @var{NUMBER} occurs. If @var{HANDLER} is an integer,
13154 it can be used to turn off handling of signal @var{NUMBER} or revert to
13155 its default action. See @code{signal(2)}.
13157 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
13158 is supplied, it is set to the value returned by @code{signal(2)}.
13160 @item @emph{Standard}:
13163 @item @emph{Class}:
13164 Subroutine, function
13166 @item @emph{Syntax}:
13167 @multitable @columnfractions .80
13168 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
13169 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
13172 @item @emph{Arguments}:
13173 @multitable @columnfractions .15 .70
13174 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
13175 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
13176 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
13177 @code{INTEGER}. It is @code{INTENT(IN)}.
13178 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
13179 integer. It has @code{INTENT(OUT)}.
13182 @item @emph{Return value}:
13183 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
13185 @item @emph{Example}:
13189 ! POSIX.1-2017: void (*func)(int)
13190 subroutine handler_print(signum) bind(C)
13191 use iso_c_binding, only: c_int
13192 integer(c_int), value :: signum
13193 print *, 'handler_print invoked with signum =', signum
13196 program test_signal
13198 intrinsic :: signal, sleep
13199 call signal (12, handler_print) ! 12 = SIGUSR2 (on some systems)
13200 call signal (10, 1) ! 10 = SIGUSR1 and 1 = SIG_IGN (on some systems)
13203 end program test_signal
13210 @section @code{SIN} --- Sine function
13216 @cindex trigonometric function, sine
13220 @item @emph{Description}:
13221 @code{SIN(X)} computes the sine of @var{X}.
13223 @item @emph{Standard}:
13224 Fortran 77 and later
13226 @item @emph{Class}:
13229 @item @emph{Syntax}:
13230 @code{RESULT = SIN(X)}
13232 @item @emph{Arguments}:
13233 @multitable @columnfractions .15 .70
13234 @item @var{X} @tab The type shall be @code{REAL} or
13238 @item @emph{Return value}:
13239 The return value has same type and kind as @var{X}.
13241 @item @emph{Example}:
13246 end program test_sin
13249 @item @emph{Specific names}:
13250 @multitable @columnfractions .20 .23 .20 .33
13251 @headitem Name @tab Argument @tab Return type @tab Standard
13252 @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
13253 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
13254 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
13255 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13256 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13259 @item @emph{See also}:
13260 Inverse function: @*
13262 Degrees function: @*
13269 @section @code{SIND} --- Sine function, degrees
13275 @cindex trigonometric function, sine, degrees
13276 @cindex sine, degrees
13279 @item @emph{Description}:
13280 @code{SIND(X)} computes the sine of @var{X} in degrees.
13282 @item @emph{Standard}:
13285 @item @emph{Class}:
13288 @item @emph{Syntax}:
13289 @code{RESULT = SIND(X)}
13291 @item @emph{Arguments}:
13292 @multitable @columnfractions .15 .70
13293 @item @var{X} @tab The type shall be @code{REAL} or
13297 @item @emph{Return value}:
13298 The return value has same type and kind as @var{X}, and its value is in degrees.
13300 @item @emph{Example}:
13305 end program test_sind
13308 @item @emph{Specific names}:
13309 @multitable @columnfractions .20 .23 .20 .33
13310 @headitem Name @tab Argument @tab Return type @tab Standard
13311 @item @code{SIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 2023
13312 @item @code{DSIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
13313 @item @code{CSIND(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU extension
13314 @item @code{ZSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13315 @item @code{CDSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13318 @item @emph{See also}:
13319 Inverse function: @*
13321 Radians function: @*
13326 @section @code{SINH} --- Hyperbolic sine function
13329 @cindex hyperbolic sine
13330 @cindex hyperbolic function, sine
13331 @cindex sine, hyperbolic
13334 @item @emph{Description}:
13335 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
13337 @item @emph{Standard}:
13338 Fortran 90 and later, for a complex argument Fortran 2008 or later, has
13341 @item @emph{Class}:
13344 @item @emph{Syntax}:
13345 @code{RESULT = SINH(X)}
13347 @item @emph{Arguments}:
13348 @multitable @columnfractions .15 .70
13349 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13352 @item @emph{Return value}:
13353 The return value has same type and kind as @var{X}.
13355 @item @emph{Example}:
13358 real(8) :: x = - 1.0_8
13360 end program test_sinh
13363 @item @emph{Specific names}:
13364 @multitable @columnfractions .20 .23 .20 .33
13365 @headitem Name @tab Argument @tab Return type @tab Standard
13366 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 90 and later
13369 @item @emph{See also}:
13376 @section @code{SIZE} --- Determine the size of an array
13378 @cindex array, size
13379 @cindex array, number of elements
13380 @cindex array, count elements
13383 @item @emph{Description}:
13384 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
13385 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
13387 @item @emph{Standard}:
13388 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
13390 @item @emph{Class}:
13393 @item @emph{Syntax}:
13394 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
13396 @item @emph{Arguments}:
13397 @multitable @columnfractions .15 .70
13398 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
13399 a pointer it must be associated and allocatable arrays must be allocated.
13400 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
13401 and its value shall be in the range from 1 to n, where n equals the rank
13403 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
13404 expression indicating the kind parameter of the result.
13407 @item @emph{Return value}:
13408 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
13409 @var{KIND} is absent, the return value is of default integer kind.
13411 @item @emph{Example}:
13414 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
13418 @item @emph{See also}:
13425 @section @code{SIZEOF} --- Size in bytes of an expression
13427 @cindex expression size
13428 @cindex size of an expression
13431 @item @emph{Description}:
13432 @code{SIZEOF(X)} calculates the number of bytes of storage the
13433 expression @code{X} occupies.
13435 @item @emph{Standard}:
13438 @item @emph{Class}:
13441 @item @emph{Syntax}:
13442 @code{N = SIZEOF(X)}
13444 @item @emph{Arguments}:
13445 @multitable @columnfractions .15 .70
13446 @item @var{X} @tab The argument shall be of any type, rank or shape.
13449 @item @emph{Return value}:
13450 The return value is of type integer and of the system-dependent kind
13451 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
13452 number of bytes occupied by the argument. If the argument has the
13453 @code{POINTER} attribute, the number of bytes of the storage area pointed
13454 to is returned. If the argument is of a derived type with @code{POINTER}
13455 or @code{ALLOCATABLE} components, the return value does not account for
13456 the sizes of the data pointed to by these components. If the argument is
13457 polymorphic, the size according to the dynamic type is returned. The argument
13458 may not be a procedure or procedure pointer. Note that the code assumes for
13459 arrays that those are contiguous; for contiguous arrays, it returns the
13460 storage or an array element multiplied by the size of the array.
13462 @item @emph{Example}:
13466 print *, (sizeof(s)/sizeof(r) == 5)
13469 The example will print @code{.TRUE.} unless you are using a platform
13470 where default @code{REAL} variables are unusually padded.
13472 @item @emph{See also}:
13479 @section @code{SLEEP} --- Sleep for the specified number of seconds
13481 @cindex delayed execution
13484 @item @emph{Description}:
13485 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
13487 @item @emph{Standard}:
13490 @item @emph{Class}:
13493 @item @emph{Syntax}:
13494 @code{CALL SLEEP(SECONDS)}
13496 @item @emph{Arguments}:
13497 @multitable @columnfractions .15 .70
13498 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
13501 @item @emph{Example}:
13512 @section @code{SPACING} --- Smallest distance between two numbers of a given type
13514 @cindex real number, relative spacing
13515 @cindex floating point, relative spacing
13518 @item @emph{Description}:
13519 Determines the distance between the argument @var{X} and the nearest
13520 adjacent number of the same type.
13522 @item @emph{Standard}:
13523 Fortran 90 and later
13525 @item @emph{Class}:
13528 @item @emph{Syntax}:
13529 @code{RESULT = SPACING(X)}
13531 @item @emph{Arguments}:
13532 @multitable @columnfractions .15 .70
13533 @item @var{X} @tab Shall be of type @code{REAL}.
13536 @item @emph{Return value}:
13537 The result is of the same type as the input argument @var{X}.
13539 @item @emph{Example}:
13541 PROGRAM test_spacing
13542 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
13543 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
13545 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
13546 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
13550 @item @emph{See also}:
13557 @section @code{SPREAD} --- Add a dimension to an array
13559 @cindex array, increase dimension
13560 @cindex array, duplicate elements
13561 @cindex array, duplicate dimensions
13564 @item @emph{Description}:
13565 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
13566 dimension @var{DIM}.
13568 @item @emph{Standard}:
13569 Fortran 90 and later
13571 @item @emph{Class}:
13572 Transformational function
13574 @item @emph{Syntax}:
13575 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
13577 @item @emph{Arguments}:
13578 @multitable @columnfractions .15 .70
13579 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
13580 a rank less than seven.
13581 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
13582 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
13583 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
13586 @item @emph{Return value}:
13587 The result is an array of the same type as @var{SOURCE} and has rank n+1
13588 where n equals the rank of @var{SOURCE}.
13590 @item @emph{Example}:
13592 PROGRAM test_spread
13593 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
13594 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
13595 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
13599 @item @emph{See also}:
13606 @section @code{SQRT} --- Square-root function
13613 @cindex square-root
13616 @item @emph{Description}:
13617 @code{SQRT(X)} computes the square root of @var{X}.
13619 @item @emph{Standard}:
13620 Fortran 77 and later
13622 @item @emph{Class}:
13625 @item @emph{Syntax}:
13626 @code{RESULT = SQRT(X)}
13628 @item @emph{Arguments}:
13629 @multitable @columnfractions .15 .70
13630 @item @var{X} @tab The type shall be @code{REAL} or
13634 @item @emph{Return value}:
13635 The return value is of type @code{REAL} or @code{COMPLEX}.
13636 The kind type parameter is the same as @var{X}.
13638 @item @emph{Example}:
13641 real(8) :: x = 2.0_8
13642 complex :: z = (1.0, 2.0)
13645 end program test_sqrt
13648 @item @emph{Specific names}:
13649 @multitable @columnfractions .20 .23 .20 .33
13650 @headitem Name @tab Argument @tab Return type @tab Standard
13651 @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
13652 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
13653 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
13654 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13655 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13662 @section @code{SRAND} --- Reinitialize the random number generator
13664 @cindex random number generation, seeding
13665 @cindex seeding a random number generator
13668 @item @emph{Description}:
13669 @code{SRAND} reinitializes the pseudo-random number generator
13670 called by @code{RAND} and @code{IRAND}. The new seed used by the
13671 generator is specified by the required argument @var{SEED}.
13673 @item @emph{Standard}:
13676 @item @emph{Class}:
13679 @item @emph{Syntax}:
13680 @code{CALL SRAND(SEED)}
13682 @item @emph{Arguments}:
13683 @multitable @columnfractions .15 .70
13684 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
13687 @item @emph{Return value}:
13688 Does not return anything.
13690 @item @emph{Example}:
13691 See @code{RAND} and @code{IRAND} for examples.
13693 @item @emph{Notes}:
13694 The Fortran standard specifies the intrinsic subroutines
13695 @code{RANDOM_SEED} to initialize the pseudo-random number
13696 generator and @code{RANDOM_NUMBER} to generate pseudo-random numbers.
13697 These subroutines should be used in new codes.
13699 Please note that in GNU Fortran, these two sets of intrinsics (@code{RAND},
13700 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
13701 @code{RANDOM_SEED} on the other hand) access two independent
13702 pseudo-random number generators.
13704 @item @emph{See also}:
13706 @ref{RANDOM_SEED}, @*
13707 @ref{RANDOM_NUMBER}
13713 @section @code{STAT} --- Get file status
13715 @cindex file system, file status
13718 @item @emph{Description}:
13719 This function returns information about a file. No permissions are required on
13720 the file itself, but execute (search) permission is required on all of the
13721 directories in path that lead to the file.
13723 The elements that are obtained and stored in the array @code{VALUES}:
13724 @multitable @columnfractions .15 .70
13725 @item @code{VALUES(1)} @tab Device ID
13726 @item @code{VALUES(2)} @tab Inode number
13727 @item @code{VALUES(3)} @tab File mode
13728 @item @code{VALUES(4)} @tab Number of links
13729 @item @code{VALUES(5)} @tab Owner's uid
13730 @item @code{VALUES(6)} @tab Owner's gid
13731 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
13732 @item @code{VALUES(8)} @tab File size (bytes)
13733 @item @code{VALUES(9)} @tab Last access time
13734 @item @code{VALUES(10)} @tab Last modification time
13735 @item @code{VALUES(11)} @tab Last file status change time
13736 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
13737 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
13740 Not all these elements are relevant on all systems.
13741 If an element is not relevant, it is returned as 0.
13743 This intrinsic is provided in both subroutine and function forms; however,
13744 only one form can be used in any given program unit.
13746 @item @emph{Standard}:
13749 @item @emph{Class}:
13750 Subroutine, function
13752 @item @emph{Syntax}:
13753 @multitable @columnfractions .80
13754 @item @code{CALL STAT(NAME, VALUES [, STATUS])}
13755 @item @code{STATUS = STAT(NAME, VALUES)}
13758 @item @emph{Arguments}:
13759 @multitable @columnfractions .15 .70
13760 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
13761 default kind and a valid path within the file system.
13762 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
13763 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
13764 on success and a system specific error code otherwise.
13767 @item @emph{Example}:
13770 INTEGER, DIMENSION(13) :: buff
13773 CALL STAT("/etc/passwd", buff, status)
13775 IF (status == 0) THEN
13776 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
13777 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
13778 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
13779 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
13780 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
13781 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
13782 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
13783 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
13784 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
13785 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
13786 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
13787 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
13788 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
13793 @item @emph{See also}:
13794 To stat an open file: @*
13803 @section @code{STORAGE_SIZE} --- Storage size in bits
13804 @fnindex STORAGE_SIZE
13805 @cindex storage size
13808 @item @emph{Description}:
13809 Returns the storage size of argument @var{A} in bits.
13810 @item @emph{Standard}:
13811 Fortran 2008 and later
13812 @item @emph{Class}:
13814 @item @emph{Syntax}:
13815 @code{RESULT = STORAGE_SIZE(A [, KIND])}
13817 @item @emph{Arguments}:
13818 @multitable @columnfractions .15 .70
13819 @item @var{A} @tab Shall be a scalar or array of any type.
13820 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
13823 @item @emph{Return Value}:
13824 The result is a scalar integer with the kind type parameter specified by KIND
13825 (or default integer type if KIND is missing). The result value is the size
13826 expressed in bits for an element of an array that has the dynamic type and type
13829 @item @emph{See also}:
13837 @section @code{SUM} --- Sum of array elements
13840 @cindex array, add elements
13841 @cindex array, conditionally add elements
13842 @cindex sum array elements
13845 @item @emph{Description}:
13846 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
13847 the corresponding element in @var{MASK} is @code{TRUE}.
13849 @item @emph{Standard}:
13850 Fortran 90 and later
13852 @item @emph{Class}:
13853 Transformational function
13855 @item @emph{Syntax}:
13856 @multitable @columnfractions .80
13857 @item @code{RESULT = SUM(ARRAY[, MASK])}
13858 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
13861 @item @emph{Arguments}:
13862 @multitable @columnfractions .15 .70
13863 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
13864 @code{REAL} or @code{COMPLEX}.
13865 @item @var{DIM} @tab (Optional) shall be a scalar of type
13866 @code{INTEGER} with a value in the range from 1 to n, where n
13867 equals the rank of @var{ARRAY}.
13868 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
13869 and either be a scalar or an array of the same shape as @var{ARRAY}.
13872 @item @emph{Return value}:
13873 The result is of the same type as @var{ARRAY}.
13875 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
13876 is returned. Otherwise, an array of rank n-1, where n equals the rank of
13877 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
13878 dropped is returned.
13880 @item @emph{Example}:
13883 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
13884 print *, SUM(x) ! all elements, sum = 15
13885 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
13889 @item @emph{See also}:
13896 @section @code{SYMLNK} --- Create a symbolic link
13898 @cindex file system, create link
13899 @cindex file system, soft link
13902 @item @emph{Description}:
13903 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
13904 character (@code{CHAR(0)}) can be used to mark the end of the names in
13905 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
13906 names are ignored. If the @var{STATUS} argument is supplied, it
13907 contains 0 on success or a nonzero error code upon return; see
13908 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
13909 @code{ENOSYS} is returned.
13911 This intrinsic is provided in both subroutine and function forms;
13912 however, only one form can be used in any given program unit.
13914 @item @emph{Standard}:
13917 @item @emph{Class}:
13918 Subroutine, function
13920 @item @emph{Syntax}:
13921 @multitable @columnfractions .80
13922 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
13923 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
13926 @item @emph{Arguments}:
13927 @multitable @columnfractions .15 .70
13928 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
13929 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
13930 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
13933 @item @emph{See also}:
13941 @section @code{SYSTEM} --- Execute a shell command
13943 @cindex system, system call
13946 @item @emph{Description}:
13947 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
13948 argument @var{STATUS} is present, it contains the value returned by
13949 @code{system(3)}, which is presumably 0 if the shell command succeeded.
13950 Note that which shell is used to invoke the command is system-dependent
13951 and environment-dependent.
13953 This intrinsic is provided in both subroutine and function forms;
13954 however, only one form can be used in any given program unit.
13956 Note that the @code{system} function need not be thread-safe. It is
13957 the responsibility of the user to ensure that @code{system} is not
13958 called concurrently.
13960 @item @emph{Standard}:
13963 @item @emph{Class}:
13964 Subroutine, function
13966 @item @emph{Syntax}:
13967 @multitable @columnfractions .80
13968 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
13969 @item @code{STATUS = SYSTEM(COMMAND)}
13972 @item @emph{Arguments}:
13973 @multitable @columnfractions .15 .70
13974 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
13975 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
13978 @item @emph{See also}:
13979 @ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
13980 and should considered in new code for future portability.
13986 @section @code{SYSTEM_CLOCK} --- Time function
13987 @fnindex SYSTEM_CLOCK
13988 @cindex time, clock ticks
13989 @cindex clock ticks
13992 @item @emph{Description}:
13993 Determines the @var{COUNT} of a processor clock since an unspecified
13994 time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines
13995 the number of clock ticks per second. If the platform supports a
13996 monotonic clock, that clock is used and can, depending on the platform
13997 clock implementation, provide up to nanosecond resolution. If a
13998 monotonic clock is not available, the implementation falls back to a
14001 @var{COUNT_RATE} is system dependent and can vary depending on the kind of
14002 the arguments. For @var{kind=4} arguments (and smaller integer kinds),
14003 @var{COUNT} represents milliseconds, while for @var{kind=8} arguments (and
14004 larger integer kinds), @var{COUNT} typically represents micro- or
14005 nanoseconds depending on resolution of the underlying platform clock.
14006 @var{COUNT_MAX} usually equals @code{HUGE(COUNT_MAX)}. Note that the
14007 millisecond resolution of the @var{kind=4} version implies that the
14008 @var{COUNT} will wrap around in roughly 25 days. In order to avoid issues
14009 with the wrap around and for more precise timing, please use the
14010 @var{kind=8} version.
14012 If there is no clock, or querying the clock fails, @var{COUNT} is set
14013 to @code{-HUGE(COUNT)}, and @var{COUNT_RATE} and @var{COUNT_MAX} are
14016 When running on a platform using the GNU C library (glibc) version
14017 2.16 or older, or a derivative thereof, the high resolution monotonic
14018 clock is available only when linking with the @var{rt} library. This
14019 can be done explicitly by adding the @code{-lrt} flag when linking the
14020 application, but is also done implicitly when using OpenMP.
14022 On the Windows platform, the version with @var{kind=4} arguments uses
14023 the @code{GetTickCount} function, whereas the @var{kind=8} version
14024 uses @code{QueryPerformanceCounter} and
14025 @code{QueryPerformanceCounterFrequency}. For more information, and
14026 potential caveats, please see the platform documentation.
14028 @item @emph{Standard}:
14029 Fortran 90 and later
14031 @item @emph{Class}:
14034 @item @emph{Syntax}:
14035 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
14037 @item @emph{Arguments}:
14038 @multitable @columnfractions .20 .65
14039 @item @var{COUNT} @tab (Optional) shall be a scalar of type
14040 @code{INTEGER} with @code{INTENT(OUT)}.
14041 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type
14042 @code{INTEGER} or @code{REAL}, with @code{INTENT(OUT)}.
14043 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type
14044 @code{INTEGER} with @code{INTENT(OUT)}.
14047 @item @emph{Example}:
14049 PROGRAM test_system_clock
14050 INTEGER :: count, count_rate, count_max
14051 CALL SYSTEM_CLOCK(count, count_rate, count_max)
14052 WRITE(*,*) count, count_rate, count_max
14056 @item @emph{See also}:
14057 @ref{DATE_AND_TIME}, @*
14064 @section @code{TAN} --- Tangent function
14067 @cindex trigonometric function, tangent
14071 @item @emph{Description}:
14072 @code{TAN(X)} computes the tangent of @var{X}.
14074 @item @emph{Standard}:
14075 Fortran 77 and later, for a complex argument Fortran 2008 or later
14077 @item @emph{Class}:
14080 @item @emph{Syntax}:
14081 @code{RESULT = TAN(X)}
14083 @item @emph{Arguments}:
14084 @multitable @columnfractions .15 .70
14085 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
14088 @item @emph{Return value}:
14089 The return value has same type and kind as @var{X}, and its value is in radians.
14091 @item @emph{Example}:
14094 real(8) :: x = 0.165_8
14096 end program test_tan
14099 @item @emph{Specific names}:
14100 @multitable @columnfractions .20 .23 .20 .33
14101 @headitem Name @tab Argument @tab Return type @tab Standard
14102 @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
14103 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
14106 @item @emph{See also}:
14107 Inverse function: @*
14109 Degrees function: @*
14116 @section @code{TAND} --- Tangent function, degrees
14119 @cindex trigonometric function, tangent, degrees
14120 @cindex tangent, degrees
14123 @item @emph{Description}:
14124 @code{TAND(X)} computes the tangent of @var{X} in degrees.
14126 @item @emph{Standard}:
14129 @item @emph{Class}:
14132 @item @emph{Syntax}:
14133 @code{RESULT = TAND(X)}
14135 @item @emph{Arguments}:
14136 @multitable @columnfractions .15 .70
14137 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
14140 @item @emph{Return value}:
14141 The return value has same type and kind as @var{X}, and its value is in degrees.
14143 @item @emph{Example}:
14146 real(8) :: x = 0.165_8
14148 end program test_tand
14151 @item @emph{Specific names}:
14152 @multitable @columnfractions .20 .23 .20 .33
14153 @headitem Name @tab Argument @tab Return type @tab Standard
14154 @item @code{TAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 2023
14155 @item @code{DTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
14158 @item @emph{See also}:
14159 Inverse function: @*
14161 Radians function: @*
14168 @section @code{TANH} --- Hyperbolic tangent function
14171 @cindex hyperbolic tangent
14172 @cindex hyperbolic function, tangent
14173 @cindex tangent, hyperbolic
14176 @item @emph{Description}:
14177 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
14179 @item @emph{Standard}:
14180 Fortran 77 and later, for a complex argument Fortran 2008 or later
14182 @item @emph{Class}:
14185 @item @emph{Syntax}:
14188 @item @emph{Arguments}:
14189 @multitable @columnfractions .15 .70
14190 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
14193 @item @emph{Return value}:
14194 The return value has same type and kind as @var{X}. If @var{X} is
14195 complex, the imaginary part of the result is in radians. If @var{X}
14196 is @code{REAL}, the return value lies in the range
14197 @math{ - 1 \leq tanh(x) \leq 1 }.
14199 @item @emph{Example}:
14202 real(8) :: x = 2.1_8
14204 end program test_tanh
14207 @item @emph{Specific names}:
14208 @multitable @columnfractions .20 .23 .20 .33
14209 @headitem Name @tab Argument @tab Return type @tab Standard
14210 @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
14211 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
14214 @item @emph{See also}:
14221 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
14222 @fnindex THIS_IMAGE
14223 @cindex coarray, @code{THIS_IMAGE}
14224 @cindex images, index of this image
14227 @item @emph{Description}:
14228 Returns the cosubscript for this image.
14230 @item @emph{Standard}:
14231 Fortran 2008 and later. With @var{DISTANCE} argument,
14232 Technical Specification (TS) 18508 or later
14234 @item @emph{Class}:
14235 Transformational function
14237 @item @emph{Syntax}:
14238 @multitable @columnfractions .80
14239 @item @code{RESULT = THIS_IMAGE()}
14240 @item @code{RESULT = THIS_IMAGE(DISTANCE)}
14241 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
14244 @item @emph{Arguments}:
14245 @multitable @columnfractions .15 .70
14246 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
14247 (not permitted together with @var{COARRAY}).
14248 @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
14249 present, required).
14250 @item @var{DIM} @tab default integer scalar (optional). If present,
14251 @var{DIM} shall be between one and the corank of @var{COARRAY}.
14255 @item @emph{Return value}:
14256 Default integer. If @var{COARRAY} is not present, it is scalar; if
14257 @var{DISTANCE} is not present or has value 0, its value is the image index on
14258 the invoking image for the current team, for values smaller or equal
14259 distance to the initial team, it returns the image index on the ancestor team
14260 which has a distance of @var{DISTANCE} from the invoking team. If
14261 @var{DISTANCE} is larger than the distance to the initial team, the image
14262 index of the initial team is returned. Otherwise when the @var{COARRAY} is
14263 present, if @var{DIM} is not present, a rank-1 array with corank elements is
14264 returned, containing the cosubscripts for @var{COARRAY} specifying the invoking
14265 image. If @var{DIM} is present, a scalar is returned, with the value of
14266 the @var{DIM} element of @code{THIS_IMAGE(COARRAY)}.
14268 @item @emph{Example}:
14270 INTEGER :: value[*]
14272 value = THIS_IMAGE()
14274 IF (THIS_IMAGE() == 1) THEN
14275 DO i = 1, NUM_IMAGES()
14276 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
14280 ! Check whether the current image is the initial image
14281 IF (THIS_IMAGE(HUGE(1)) /= THIS_IMAGE())
14282 error stop "something is rotten here"
14285 @item @emph{See also}:
14286 @ref{NUM_IMAGES}, @*
14293 @section @code{TIME} --- Time function
14295 @cindex time, current
14296 @cindex current time
14299 @item @emph{Description}:
14300 Returns the current time encoded as an integer (in the manner of the
14301 function @code{time(3)} in the C standard library). This value is
14302 suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}.
14304 This intrinsic is not fully portable, such as to systems with 32-bit
14305 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
14306 the values returned by this intrinsic might be, or become, negative, or
14307 numerically less than previous values, during a single run of the
14310 See @ref{TIME8}, for information on a similar intrinsic that might be
14311 portable to more GNU Fortran implementations, though to fewer Fortran
14314 @item @emph{Standard}:
14317 @item @emph{Class}:
14320 @item @emph{Syntax}:
14321 @code{RESULT = TIME()}
14323 @item @emph{Return value}:
14324 The return value is a scalar of type @code{INTEGER(4)}.
14326 @item @emph{See also}:
14327 @ref{DATE_AND_TIME}, @*
14338 @section @code{TIME8} --- Time function (64-bit)
14340 @cindex time, current
14341 @cindex current time
14344 @item @emph{Description}:
14345 Returns the current time encoded as an integer (in the manner of the
14346 function @code{time(3)} in the C standard library). This value is
14347 suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}.
14349 @emph{Warning:} this intrinsic does not increase the range of the timing
14350 values over that returned by @code{time(3)}. On a system with a 32-bit
14351 @code{time(3)}, @code{TIME8} will return a 32-bit value, even though
14352 it is converted to a 64-bit @code{INTEGER(8)} value. That means
14353 overflows of the 32-bit value can still occur. Therefore, the values
14354 returned by this intrinsic might be or become negative or numerically
14355 less than previous values during a single run of the compiled program.
14357 @item @emph{Standard}:
14360 @item @emph{Class}:
14363 @item @emph{Syntax}:
14364 @code{RESULT = TIME8()}
14366 @item @emph{Return value}:
14367 The return value is a scalar of type @code{INTEGER(8)}.
14369 @item @emph{See also}:
14370 @ref{DATE_AND_TIME}, @*
14381 @section @code{TINY} --- Smallest positive number of a real kind
14383 @cindex limits, smallest number
14384 @cindex model representation, smallest number
14387 @item @emph{Description}:
14388 @code{TINY(X)} returns the smallest positive (non zero) number
14389 in the model of the type of @code{X}.
14391 @item @emph{Standard}:
14392 Fortran 90 and later
14394 @item @emph{Class}:
14397 @item @emph{Syntax}:
14398 @code{RESULT = TINY(X)}
14400 @item @emph{Arguments}:
14401 @multitable @columnfractions .15 .70
14402 @item @var{X} @tab Shall be of type @code{REAL}.
14405 @item @emph{Return value}:
14406 The return value is of the same type and kind as @var{X}
14408 @item @emph{Example}:
14409 See @code{HUGE} for an example.
14415 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
14420 @item @emph{Description}:
14421 @code{TRAILZ} returns the number of trailing zero bits of an integer.
14423 @item @emph{Standard}:
14424 Fortran 2008 and later
14426 @item @emph{Class}:
14429 @item @emph{Syntax}:
14430 @code{RESULT = TRAILZ(I)}
14432 @item @emph{Arguments}:
14433 @multitable @columnfractions .15 .70
14434 @item @var{I} @tab Shall be of type @code{INTEGER}.
14437 @item @emph{Return value}:
14438 The type of the return value is the default @code{INTEGER}.
14439 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
14441 @item @emph{Example}:
14443 PROGRAM test_trailz
14444 WRITE (*,*) TRAILZ(8) ! prints 3
14448 @item @emph{See also}:
14458 @section @code{TRANSFER} --- Transfer bit patterns
14464 @item @emph{Description}:
14465 Interprets the bitwise representation of @var{SOURCE} in memory as if it
14466 is the representation of a variable or array of the same type and type
14467 parameters as @var{MOLD}.
14469 This is approximately equivalent to the C concept of @emph{casting} one
14472 @item @emph{Standard}:
14473 Fortran 90 and later
14475 @item @emph{Class}:
14476 Transformational function
14478 @item @emph{Syntax}:
14479 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
14481 @item @emph{Arguments}:
14482 @multitable @columnfractions .15 .70
14483 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
14484 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
14485 @item @var{SIZE} @tab (Optional) shall be a scalar of type
14489 @item @emph{Return value}:
14490 The result has the same type as @var{MOLD}, with the bit level
14491 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
14492 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
14493 but @var{MOLD} is an array (of any size or shape), the result is a one-
14494 dimensional array of the minimum length needed to contain the entirety
14495 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
14496 and @var{MOLD} is a scalar, the result is a scalar.
14498 If the bitwise representation of the result is longer than that of
14499 @var{SOURCE}, then the leading bits of the result correspond to those of
14500 @var{SOURCE} and any trailing bits are filled arbitrarily.
14502 When the resulting bit representation does not correspond to a valid
14503 representation of a variable of the same type as @var{MOLD}, the results
14504 are undefined, and subsequent operations on the result cannot be
14505 guaranteed to produce sensible behavior. For example, it is possible to
14506 create @code{LOGICAL} variables for which @code{@var{VAR}} and
14507 @code{.NOT.@var{VAR}} both appear to be true.
14509 @item @emph{Example}:
14511 PROGRAM test_transfer
14512 integer :: x = 2143289344
14513 print *, transfer(x, 1.0) ! prints "NaN" on i686
14521 @section @code{TRANSPOSE} --- Transpose an array of rank two
14523 @cindex array, transpose
14524 @cindex matrix, transpose
14528 @item @emph{Description}:
14529 Transpose an array of rank two. Element (i, j) of the result has the value
14530 @code{MATRIX(j, i)}, for all i, j.
14532 @item @emph{Standard}:
14533 Fortran 90 and later
14535 @item @emph{Class}:
14536 Transformational function
14538 @item @emph{Syntax}:
14539 @code{RESULT = TRANSPOSE(MATRIX)}
14541 @item @emph{Arguments}:
14542 @multitable @columnfractions .15 .70
14543 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
14546 @item @emph{Return value}:
14547 The result has the same type as @var{MATRIX}, and has shape
14548 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
14554 @section @code{TRIM} --- Remove trailing blank characters of a string
14556 @cindex string, remove trailing whitespace
14559 @item @emph{Description}:
14560 Removes trailing blank characters of a string.
14562 @item @emph{Standard}:
14563 Fortran 90 and later
14565 @item @emph{Class}:
14566 Transformational function
14568 @item @emph{Syntax}:
14569 @code{RESULT = TRIM(STRING)}
14571 @item @emph{Arguments}:
14572 @multitable @columnfractions .15 .70
14573 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
14576 @item @emph{Return value}:
14577 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
14578 less the number of trailing blanks.
14580 @item @emph{Example}:
14583 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
14584 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
14588 @item @emph{See also}:
14596 @section @code{TTYNAM} --- Get the name of a terminal device
14598 @cindex system, terminal
14601 @item @emph{Description}:
14602 Get the name of a terminal device. For more information,
14603 see @code{ttyname(3)}.
14605 This intrinsic is provided in both subroutine and function forms;
14606 however, only one form can be used in any given program unit.
14608 @item @emph{Standard}:
14611 @item @emph{Class}:
14612 Subroutine, function
14614 @item @emph{Syntax}:
14615 @multitable @columnfractions .80
14616 @item @code{CALL TTYNAM(UNIT, NAME)}
14617 @item @code{NAME = TTYNAM(UNIT)}
14620 @item @emph{Arguments}:
14621 @multitable @columnfractions .15 .70
14622 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
14623 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
14626 @item @emph{Example}:
14628 PROGRAM test_ttynam
14631 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
14636 @item @emph{See also}:
14643 @section @code{UBOUND} --- Upper dimension bounds of an array
14645 @cindex array, upper bound
14648 @item @emph{Description}:
14649 Returns the upper bounds of an array, or a single upper bound
14650 along the @var{DIM} dimension.
14651 @item @emph{Standard}:
14652 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
14654 @item @emph{Class}:
14657 @item @emph{Syntax}:
14658 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
14660 @item @emph{Arguments}:
14661 @multitable @columnfractions .15 .70
14662 @item @var{ARRAY} @tab Shall be an array, of any type.
14663 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
14664 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
14665 expression indicating the kind parameter of the result.
14668 @item @emph{Return value}:
14669 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14670 @var{KIND} is absent, the return value is of default integer kind.
14671 If @var{DIM} is absent, the result is an array of the upper bounds of
14672 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
14673 corresponding to the upper bound of the array along that dimension. If
14674 @var{ARRAY} is an expression rather than a whole array or array
14675 structure component, or if it has a zero extent along the relevant
14676 dimension, the upper bound is taken to be the number of elements along
14677 the relevant dimension.
14679 @item @emph{See also}:
14687 @section @code{UCOBOUND} --- Upper codimension bounds of an array
14689 @cindex coarray, upper bound
14692 @item @emph{Description}:
14693 Returns the upper cobounds of a coarray, or a single upper cobound
14694 along the @var{DIM} codimension.
14695 @item @emph{Standard}:
14696 Fortran 2008 and later
14698 @item @emph{Class}:
14701 @item @emph{Syntax}:
14702 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
14704 @item @emph{Arguments}:
14705 @multitable @columnfractions .15 .70
14706 @item @var{ARRAY} @tab Shall be an coarray, of any type.
14707 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
14708 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
14709 expression indicating the kind parameter of the result.
14712 @item @emph{Return value}:
14713 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14714 @var{KIND} is absent, the return value is of default integer kind.
14715 If @var{DIM} is absent, the result is an array of the lower cobounds of
14716 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
14717 corresponding to the lower cobound of the array along that codimension.
14719 @item @emph{See also}:
14727 @section @code{UMASK} --- Set the file creation mask
14729 @cindex file system, file creation mask
14732 @item @emph{Description}:
14733 Sets the file creation mask to @var{MASK}. If called as a function, it
14734 returns the old value. If called as a subroutine and argument @var{OLD}
14735 if it is supplied, it is set to the old value. See @code{umask(2)}.
14737 @item @emph{Standard}:
14740 @item @emph{Class}:
14741 Subroutine, function
14743 @item @emph{Syntax}:
14744 @multitable @columnfractions .80
14745 @item @code{CALL UMASK(MASK [, OLD])}
14746 @item @code{OLD = UMASK(MASK)}
14749 @item @emph{Arguments}:
14750 @multitable @columnfractions .15 .70
14751 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
14752 @item @var{OLD} @tab (Optional) Shall be a scalar of type
14761 @section @code{UNLINK} --- Remove a file from the file system
14763 @cindex file system, remove file
14766 @item @emph{Description}:
14767 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
14768 used to mark the end of the name in @var{PATH}; otherwise, trailing
14769 blanks in the file name are ignored. If the @var{STATUS} argument is
14770 supplied, it contains 0 on success or a nonzero error code upon return;
14771 see @code{unlink(2)}.
14773 This intrinsic is provided in both subroutine and function forms;
14774 however, only one form can be used in any given program unit.
14776 @item @emph{Standard}:
14779 @item @emph{Class}:
14780 Subroutine, function
14782 @item @emph{Syntax}:
14783 @multitable @columnfractions .80
14784 @item @code{CALL UNLINK(PATH [, STATUS])}
14785 @item @code{STATUS = UNLINK(PATH)}
14788 @item @emph{Arguments}:
14789 @multitable @columnfractions .15 .70
14790 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
14791 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
14794 @item @emph{See also}:
14802 @section @code{UNPACK} --- Unpack an array of rank one into an array
14804 @cindex array, unpacking
14805 @cindex array, increase dimension
14806 @cindex array, scatter elements
14809 @item @emph{Description}:
14810 Store the elements of @var{VECTOR} in an array of higher rank.
14812 @item @emph{Standard}:
14813 Fortran 90 and later
14815 @item @emph{Class}:
14816 Transformational function
14818 @item @emph{Syntax}:
14819 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
14821 @item @emph{Arguments}:
14822 @multitable @columnfractions .15 .70
14823 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
14824 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
14825 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
14826 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
14827 the same shape as @var{MASK}.
14830 @item @emph{Return value}:
14831 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
14832 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
14834 @item @emph{Example}:
14836 PROGRAM test_unpack
14837 integer :: vector(2) = (/1,1/)
14838 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
14839 integer :: field(2,2) = 0, unity(2,2)
14841 ! result: unity matrix
14842 unity = unpack(vector, reshape(mask, (/2,2/)), field)
14846 @item @emph{See also}:
14854 @section @code{VERIFY} --- Scan a string for characters not a given set
14856 @cindex string, find missing set
14859 @item @emph{Description}:
14860 Verifies that all the characters in @var{STRING} belong to the set of
14861 characters in @var{SET}.
14863 If @var{BACK} is either absent or equals @code{FALSE}, this function
14864 returns the position of the leftmost character of @var{STRING} that is
14865 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost
14866 position is returned. If all characters of @var{STRING} are found in
14867 @var{SET}, the result is zero.
14869 @item @emph{Standard}:
14870 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
14872 @item @emph{Class}:
14875 @item @emph{Syntax}:
14876 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
14878 @item @emph{Arguments}:
14879 @multitable @columnfractions .15 .70
14880 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
14881 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
14882 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
14883 @item @var{KIND} @tab (Optional) A scalar @code{INTEGER} constant
14884 expression indicating the kind parameter of the result.
14887 @item @emph{Return value}:
14888 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14889 @var{KIND} is absent, the return value is of default integer kind.
14891 @item @emph{Example}:
14893 PROGRAM test_verify
14894 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
14895 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
14896 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
14897 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
14898 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
14902 @item @emph{See also}:
14904 @ref{INDEX intrinsic}
14910 @section @code{XOR} --- Bitwise logical exclusive OR
14912 @cindex bitwise logical exclusive or
14913 @cindex logical exclusive or, bitwise
14916 @item @emph{Description}:
14917 Bitwise logical exclusive or.
14919 This intrinsic routine is provided for backwards compatibility with
14920 GNU Fortran 77. For integer arguments, programmers should consider
14921 the use of the @ref{IEOR} intrinsic and for logical arguments the
14922 @code{.NEQV.} operator, which are both defined by the Fortran standard.
14924 @item @emph{Standard}:
14927 @item @emph{Class}:
14930 @item @emph{Syntax}:
14931 @code{RESULT = XOR(I, J)}
14933 @item @emph{Arguments}:
14934 @multitable @columnfractions .15 .70
14935 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
14936 type or a scalar @code{LOGICAL} type or a boz-literal-constant.
14937 @item @var{J} @tab The type shall be the same as the type of @var{I} or
14938 a boz-literal-constant. @var{I} and @var{J} shall not both be
14939 boz-literal-constants. If either @var{I} and @var{J} is a
14940 boz-literal-constant, then the other argument must be a scalar @code{INTEGER}.
14943 @item @emph{Return value}:
14944 The return type is either a scalar @code{INTEGER} or a scalar
14945 @code{LOGICAL}. If the kind type parameters differ, then the
14946 smaller kind type is implicitly converted to larger kind, and the
14947 return has the larger kind. A boz-literal-constant is
14948 converted to an @code{INTEGER} with the kind type parameter of
14949 the other argument as-if a call to @ref{INT} occurred.
14951 @item @emph{Example}:
14954 LOGICAL :: T = .TRUE., F = .FALSE.
14956 DATA a / Z'F' /, b / Z'3' /
14958 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
14959 WRITE (*,*) XOR(a, b)
14963 @item @emph{See also}:
14964 Fortran 95 elemental function: @*
14970 @node Intrinsic Modules
14971 @chapter Intrinsic Modules
14972 @cindex intrinsic Modules
14975 * ISO_FORTRAN_ENV::
14978 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
14979 * OpenACC Module OPENACC::
14982 @node ISO_FORTRAN_ENV
14983 @section @code{ISO_FORTRAN_ENV}
14985 @item @emph{Standard}:
14986 Fortran 2003 and later, except when otherwise noted
14989 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
14993 @item @code{ATOMIC_INT_KIND}:
14994 Default-kind integer constant to be used as kind parameter when defining
14995 integer variables used in atomic operations. (Fortran 2008 or later.)
14997 @item @code{ATOMIC_LOGICAL_KIND}:
14998 Default-kind integer constant to be used as kind parameter when defining
14999 logical variables used in atomic operations. (Fortran 2008 or later.)
15001 @item @code{CHARACTER_KINDS}:
15002 Default-kind integer constant array of rank one containing the supported kind
15003 parameters of the @code{CHARACTER} type. (Fortran 2008 or later.)
15005 @item @code{CHARACTER_STORAGE_SIZE}:
15006 Size in bits of the character storage unit.
15008 @item @code{ERROR_UNIT}:
15009 Identifies the preconnected unit used for error reporting.
15011 @item @code{FILE_STORAGE_SIZE}:
15012 Size in bits of the file-storage unit.
15014 @item @code{INPUT_UNIT}:
15015 Identifies the preconnected unit identified by the asterisk
15016 (@code{*}) in @code{READ} statement.
15018 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
15019 Kind type parameters to specify an INTEGER type with a storage
15020 size of 16, 32, and 64 bits. It is negative if a target platform
15021 does not support the particular kind. (Fortran 2008 or later.)
15023 @item @code{INTEGER_KINDS}:
15024 Default-kind integer constant array of rank one containing the supported kind
15025 parameters of the @code{INTEGER} type. (Fortran 2008 or later.)
15027 @item @code{IOSTAT_END}:
15028 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
15029 an input/output statement if an end-of-file condition occurred.
15031 @item @code{IOSTAT_EOR}:
15032 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
15033 an input/output statement if an end-of-record condition occurred.
15035 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
15036 Scalar default-integer constant, used by @code{INQUIRE} for the
15037 @code{IOSTAT=} specifier to denote an that a unit number identifies an
15038 internal unit. (Fortran 2008 or later.)
15040 @item @code{NUMERIC_STORAGE_SIZE}:
15041 The size in bits of the numeric storage unit.
15043 @item @code{LOGICAL_KINDS}:
15044 Default-kind integer constant array of rank one containing the supported kind
15045 parameters of the @code{LOGICAL} type. (Fortran 2008 or later.)
15047 @item @code{OUTPUT_UNIT}:
15048 Identifies the preconnected unit identified by the asterisk
15049 (@code{*}) in @code{WRITE} statement.
15051 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
15052 Kind type parameters to specify a REAL type with a storage
15053 size of 32, 64, and 128 bits. It is negative if a target platform
15054 does not support the particular kind. (Fortran 2008 or later.)
15056 @item @code{REAL_KINDS}:
15057 Default-kind integer constant array of rank one containing the supported kind
15058 parameters of the @code{REAL} type. (Fortran 2008 or later.)
15060 @item @code{STAT_LOCKED}:
15061 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
15062 denote that the lock variable is locked by the executing image. (Fortran 2008
15065 @item @code{STAT_LOCKED_OTHER_IMAGE}:
15066 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
15067 denote that the lock variable is locked by another image. (Fortran 2008 or
15070 @item @code{STAT_STOPPED_IMAGE}:
15071 Positive, scalar default-integer constant used as STAT= return value if the
15072 argument in the statement requires synchronisation with an image, which has
15073 initiated the termination of the execution. (Fortran 2008 or later.)
15075 @item @code{STAT_FAILED_IMAGE}:
15076 Positive, scalar default-integer constant used as STAT= return value if the
15077 argument in the statement requires communication with an image, which has
15078 is in the failed state. (TS 18508 or later.)
15080 @item @code{STAT_UNLOCKED}:
15081 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
15082 denote that the lock variable is unlocked. (Fortran 2008 or later.)
15085 The module provides the following derived type:
15088 @item @code{LOCK_TYPE}:
15089 Derived type with private components to be use with the @code{LOCK} and
15090 @code{UNLOCK} statement. A variable of its type has to be always declared
15091 as coarray and may not appear in a variable-definition context.
15092 (Fortran 2008 or later.)
15095 The module also provides the following intrinsic procedures:
15096 @ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}.
15100 @node ISO_C_BINDING
15101 @section @code{ISO_C_BINDING}
15103 @item @emph{Standard}:
15104 Fortran 2003 and later, GNU extensions
15107 The following intrinsic procedures are provided by the module; their
15108 definition can be found in the section Intrinsic Procedures of this
15112 @item @code{C_ASSOCIATED}
15113 @item @code{C_F_POINTER}
15114 @item @code{C_F_PROCPOINTER}
15115 @item @code{C_FUNLOC}
15117 @item @code{C_SIZEOF}
15119 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
15120 @c don't really know why.
15122 The @code{ISO_C_BINDING} module provides the following named constants of
15123 type default integer, which can be used as KIND type parameters.
15125 In addition to the integer named constants required by the Fortran 2003
15126 standard and @code{C_PTRDIFF_T} of TS 29113, GNU Fortran provides as an
15127 extension named constants for the 128-bit integer types supported by the
15128 C compiler: @code{C_INT128_T, C_INT_LEAST128_T, C_INT_FAST128_T}.
15129 Furthermore, if @code{_Float128} is supported in C, the named constants
15130 @code{C_FLOAT128} and @code{C_FLOAT128_COMPLEX} are defined.
15132 @multitable @columnfractions .19 .32 .34 .15
15133 @headitem Fortran Type @tab Named constant @tab C type @tab Extension
15134 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
15135 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
15136 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
15137 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
15138 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
15139 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
15140 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
15141 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
15142 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
15143 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
15144 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
15145 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
15146 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
15147 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
15148 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
15149 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
15150 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
15151 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
15152 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
15153 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
15154 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
15155 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
15156 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
15157 @item @code{INTEGER}@tab @code{C_PTRDIFF_T} @tab @code{ptrdiff_t} @tab TS 29113
15158 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
15159 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
15160 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
15161 @item @code{REAL} @tab @code{C_FLOAT128} @tab @code{_Float128} @tab Ext.
15162 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
15163 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
15164 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
15165 @item @code{COMPLEX}@tab @code{C_FLOAT128_COMPLEX} @tab @code{_Float128 _Complex} @tab Ext.
15166 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
15167 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
15170 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
15173 @multitable @columnfractions .20 .45 .15
15174 @headitem Name @tab C definition @tab Value
15175 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
15176 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
15177 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
15178 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
15179 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
15180 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
15181 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
15182 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
15185 Moreover, the following two named constants are defined:
15187 @multitable @columnfractions .20 .80
15188 @headitem Name @tab Type
15189 @item @code{C_NULL_PTR} @tab @code{C_PTR}
15190 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
15193 Both are equivalent to the value @code{NULL} in C.
15198 @section IEEE modules: @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
15200 @item @emph{Standard}:
15201 Fortran 2003 and later
15204 The @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
15205 intrinsic modules provide support for exceptions and IEEE arithmetic, as
15206 defined in Fortran 2003 and later standards, and the IEC 60559:1989 standard
15207 (@emph{Binary floating-point arithmetic for microprocessor systems}). These
15208 modules are only provided on the following supported platforms:
15211 @item i386 and x86_64 processors
15212 @item platforms which use the GNU C Library (glibc)
15213 @item platforms with support for SysV/386 routines for floating point
15214 interface (including Solaris and BSDs)
15215 @item platforms with the AIX OS
15218 For full compliance with the Fortran standards, code using the
15219 @code{IEEE_EXCEPTIONS} or @code{IEEE_ARITHMETIC} modules should be compiled
15220 with the following options: @code{-fno-unsafe-math-optimizations
15221 -frounding-math -fsignaling-nans}.
15225 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
15226 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
15228 @item @emph{Standard}:
15229 OpenMP Application Program Interface v4.5,
15230 OpenMP Application Program Interface v5.0 (partially supported),
15231 OpenMP Application Program Interface v5.1 (partially supported) and
15232 OpenMP Application Program Interface v5.2 (partially supported).
15235 The OpenMP Fortran runtime library routines are provided both in
15236 a form of two Fortran modules, named @code{OMP_LIB} and
15237 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
15238 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
15239 in the @ref{Top,,Introduction,libgomp,GNU Offloading and Multi
15240 Processing Runtime Library} manual,
15241 the named constants defined in the modules are listed
15244 For details refer to the actual
15245 @uref{https://www.openmp.org/wp-content/uploads/openmp-4.5.pdf,
15246 OpenMP Application Program Interface v4.5},
15247 @uref{https://www.openmp.org/wp-content/uploads/OpenMP-API-Specification-5.0.pdf,
15248 OpenMP Application Program Interface v5.0},
15249 @uref{https://www.openmp.org/wp-content/uploads/OpenMP-API-Specification-5-1.pdf,
15250 OpenMP Application Program Interface v5.1} and
15251 @uref{https://www.openmp.org/wp-content/uploads/OpenMP-API-Specification-5-2.pdf,
15252 OpenMP Application Program Interface v5.2}.
15254 @code{OMP_LIB_KINDS} provides the following scalar default-integer
15258 @item @code{omp_allocator_handle_kind}
15259 @item @code{omp_alloctrait_key_kind}
15260 @item @code{omp_alloctrait_val_kind}
15261 @item @code{omp_depend_kind}
15262 @item @code{omp_lock_kind}
15263 @item @code{omp_lock_hint_kind}
15264 @item @code{omp_nest_lock_kind}
15265 @item @code{omp_pause_resource_kind}
15266 @item @code{omp_memspace_handle_kind}
15267 @item @code{omp_proc_bind_kind}
15268 @item @code{omp_sched_kind}
15269 @item @code{omp_sync_hint_kind}
15272 @code{OMP_LIB} provides the scalar default-integer
15273 named constant @code{openmp_version} with a value of the form
15274 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
15275 of the OpenMP version; for OpenMP v4.5 the value is @code{201511}.
15277 The following derived type:
15280 @item @code{omp_alloctrait}
15283 The following scalar default-integer named constants:
15285 @item @code{omp_initial_device}
15286 @item @code{omp_invalid_device}
15290 The following scalar integer named constants of the
15291 kind @code{omp_sched_kind}:
15294 @item @code{omp_sched_static}
15295 @item @code{omp_sched_dynamic}
15296 @item @code{omp_sched_guided}
15297 @item @code{omp_sched_auto}
15300 And the following scalar integer named constants of the
15301 kind @code{omp_proc_bind_kind}:
15304 @item @code{omp_proc_bind_false}
15305 @item @code{omp_proc_bind_true}
15306 @item @code{omp_proc_bind_primary}
15307 @item @code{omp_proc_bind_master}
15308 @item @code{omp_proc_bind_close}
15309 @item @code{omp_proc_bind_spread}
15312 The following scalar integer named constants are of the
15313 kind @code{omp_lock_hint_kind}:
15316 @item @code{omp_lock_hint_none}
15317 @item @code{omp_lock_hint_uncontended}
15318 @item @code{omp_lock_hint_contended}
15319 @item @code{omp_lock_hint_nonspeculative}
15320 @item @code{omp_lock_hint_speculative}
15321 @item @code{omp_sync_hint_none}
15322 @item @code{omp_sync_hint_uncontended}
15323 @item @code{omp_sync_hint_contended}
15324 @item @code{omp_sync_hint_nonspeculative}
15325 @item @code{omp_sync_hint_speculative}
15328 And the following two scalar integer named constants are of the
15329 kind @code{omp_pause_resource_kind}:
15332 @item @code{omp_pause_soft}
15333 @item @code{omp_pause_hard}
15336 The following scalar integer named constants are of the kind
15337 @code{omp_alloctrait_key_kind}:
15340 @item @code{omp_atk_sync_hint}
15341 @item @code{omp_atk_alignment}
15342 @item @code{omp_atk_access}
15343 @item @code{omp_atk_pool_size}
15344 @item @code{omp_atk_fallback}
15345 @item @code{omp_atk_fb_data}
15346 @item @code{omp_atk_pinned}
15347 @item @code{omp_atk_partition}
15350 The following scalar integer named constants are of the kind
15351 @code{omp_alloctrait_val_kind}:
15354 @code{omp_alloctrait_key_kind}:
15355 @item @code{omp_atv_default}
15356 @item @code{omp_atv_false}
15357 @item @code{omp_atv_true}
15358 @item @code{omp_atv_contended}
15359 @item @code{omp_atv_uncontended}
15360 @item @code{omp_atv_serialized}
15361 @item @code{omp_atv_sequential}
15362 @item @code{omp_atv_private}
15363 @item @code{omp_atv_all}
15364 @item @code{omp_atv_thread}
15365 @item @code{omp_atv_pteam}
15366 @item @code{omp_atv_cgroup}
15367 @item @code{omp_atv_default_mem_fb}
15368 @item @code{omp_atv_null_fb}
15369 @item @code{omp_atv_abort_fb}
15370 @item @code{omp_atv_allocator_fb}
15371 @item @code{omp_atv_environment}
15372 @item @code{omp_atv_nearest}
15373 @item @code{omp_atv_blocked}
15376 The following scalar integer named constants are of the kind
15377 @code{omp_allocator_handle_kind}:
15380 @item @code{omp_null_allocator}
15381 @item @code{omp_default_mem_alloc}
15382 @item @code{omp_large_cap_mem_alloc}
15383 @item @code{omp_const_mem_alloc}
15384 @item @code{omp_high_bw_mem_alloc}
15385 @item @code{omp_low_lat_mem_alloc}
15386 @item @code{omp_cgroup_mem_alloc}
15387 @item @code{omp_pteam_mem_alloc}
15388 @item @code{omp_thread_mem_alloc}
15391 The following scalar integer named constants are of the kind
15392 @code{omp_memspace_handle_kind}:
15395 @item @code{omp_default_mem_space}
15396 @item @code{omp_large_cap_mem_space}
15397 @item @code{omp_const_mem_space}
15398 @item @code{omp_high_bw_mem_space}
15399 @item @code{omp_low_lat_mem_space}
15404 @node OpenACC Module OPENACC
15405 @section OpenACC Module @code{OPENACC}
15407 @item @emph{Standard}:
15408 OpenACC Application Programming Interface v2.6
15412 The OpenACC Fortran runtime library routines are provided both in a
15413 form of a Fortran 90 module, named @code{OPENACC}, and in form of a
15414 Fortran @code{include} file named @file{openacc_lib.h}. The
15415 procedures provided by @code{OPENACC} can be found in the
15416 @ref{Top,,Introduction,libgomp,GNU Offloading and Multi Processing
15417 Runtime Library} manual, the named constants defined in the modules
15420 For details refer to the actual
15421 @uref{https://www.openacc.org/,
15422 OpenACC Application Programming Interface v2.6}.
15424 @code{OPENACC} provides the scalar default-integer
15425 named constant @code{openacc_version} with a value of the form
15426 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
15427 of the OpenACC version; for OpenACC v2.6 the value is @code{201711}.