2 Copyright (C) 2005-2018 Free Software Foundation, Inc.
3 This is part of the GNU Fortran manual.
4 For copying conditions, see the file gfortran.texi.
6 Permission is granted to copy, distribute and/or modify this document
7 under the terms of the GNU Free Documentation License, Version 1.3 or
8 any later version published by the Free Software Foundation; with the
9 Invariant Sections being ``Funding Free Software'', the Front-Cover
10 Texts being (a) (see below), and with the Back-Cover Texts being (b)
11 (see below). A copy of the license is included in the gfdl(7) man page.
14 Some basic guidelines for editing this document:
16 (1) The intrinsic procedures are to be listed in alphabetical order.
17 (2) The generic name is to be used.
18 (3) The specific names are included in the function index and in a
19 table at the end of the node (See ABS entry).
20 (4) Try to maintain the same style for each entry.
26 \gdef\acosd{\mathop{\rm acosd}\nolimits}
27 \gdef\asind{\mathop{\rm asind}\nolimits}
28 \gdef\atand{\mathop{\rm atand}\nolimits}
29 \gdef\acos{\mathop{\rm acos}\nolimits}
30 \gdef\asin{\mathop{\rm asin}\nolimits}
31 \gdef\atan{\mathop{\rm atan}\nolimits}
32 \gdef\acosh{\mathop{\rm acosh}\nolimits}
33 \gdef\asinh{\mathop{\rm asinh}\nolimits}
34 \gdef\atanh{\mathop{\rm atanh}\nolimits}
35 \gdef\cosd{\mathop{\rm cosd}\nolimits}
39 @node Intrinsic Procedures
40 @chapter Intrinsic Procedures
41 @cindex intrinsic procedures
44 * Introduction: Introduction to Intrinsics
45 * @code{ABORT}: ABORT, Abort the program
46 * @code{ABS}: ABS, Absolute value
47 * @code{ACCESS}: ACCESS, Checks file access modes
48 * @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence
49 * @code{ACOS}: ACOS, Arccosine function
50 * @code{ACOSD}: ACOSD, Arccosine function, degrees
51 * @code{ACOSH}: ACOSH, Inverse hyperbolic cosine function
52 * @code{ADJUSTL}: ADJUSTL, Left adjust a string
53 * @code{ADJUSTR}: ADJUSTR, Right adjust a string
54 * @code{AIMAG}: AIMAG, Imaginary part of complex number
55 * @code{AINT}: AINT, Truncate to a whole number
56 * @code{ALARM}: ALARM, Set an alarm clock
57 * @code{ALL}: ALL, Determine if all values are true
58 * @code{ALLOCATED}: ALLOCATED, Status of allocatable entity
59 * @code{AND}: AND, Bitwise logical AND
60 * @code{ANINT}: ANINT, Nearest whole number
61 * @code{ANY}: ANY, Determine if any values are true
62 * @code{ASIN}: ASIN, Arcsine function
63 * @code{ASIND}: ASIND, Arcsine function, degrees
64 * @code{ASINH}: ASINH, Inverse hyperbolic sine function
65 * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair
66 * @code{ATAN}: ATAN, Arctangent function
67 * @code{ATAND}: ATAND, Arctangent function, degrees
68 * @code{ATAN2}: ATAN2, Arctangent function
69 * @code{ATAN2D}: ATAN2D, Arctangent function, degrees
70 * @code{ATANH}: ATANH, Inverse hyperbolic tangent function
71 * @code{ATOMIC_ADD}: ATOMIC_ADD, Atomic ADD operation
72 * @code{ATOMIC_AND}: ATOMIC_AND, Atomic bitwise AND operation
73 * @code{ATOMIC_CAS}: ATOMIC_CAS, Atomic compare and swap
74 * @code{ATOMIC_DEFINE}: ATOMIC_DEFINE, Setting a variable atomically
75 * @code{ATOMIC_FETCH_ADD}: ATOMIC_FETCH_ADD, Atomic ADD operation with prior fetch
76 * @code{ATOMIC_FETCH_AND}: ATOMIC_FETCH_AND, Atomic bitwise AND operation with prior fetch
77 * @code{ATOMIC_FETCH_OR}: ATOMIC_FETCH_OR, Atomic bitwise OR operation with prior fetch
78 * @code{ATOMIC_FETCH_XOR}: ATOMIC_FETCH_XOR, Atomic bitwise XOR operation with prior fetch
79 * @code{ATOMIC_OR}: ATOMIC_OR, Atomic bitwise OR operation
80 * @code{ATOMIC_REF}: ATOMIC_REF, Obtaining the value of a variable atomically
81 * @code{ATOMIC_XOR}: ATOMIC_XOR, Atomic bitwise OR operation
82 * @code{BACKTRACE}: BACKTRACE, Show a backtrace
83 * @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0
84 * @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1
85 * @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind
86 * @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0
87 * @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1
88 * @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind
89 * @code{BGE}: BGE, Bitwise greater than or equal to
90 * @code{BGT}: BGT, Bitwise greater than
91 * @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function
92 * @code{BLE}: BLE, Bitwise less than or equal to
93 * @code{BLT}: BLT, Bitwise less than
94 * @code{BTEST}: BTEST, Bit test function
95 * @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer
96 * @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer
97 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
98 * @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure
99 * @code{C_LOC}: C_LOC, Obtain the C address of an object
100 * @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression
101 * @code{CEILING}: CEILING, Integer ceiling function
102 * @code{CHAR}: CHAR, Integer-to-character conversion function
103 * @code{CHDIR}: CHDIR, Change working directory
104 * @code{CHMOD}: CHMOD, Change access permissions of files
105 * @code{CMPLX}: CMPLX, Complex conversion function
106 * @code{CO_BROADCAST}: CO_BROADCAST, Copy a value to all images the current set of images
107 * @code{CO_MAX}: CO_MAX, Maximal value on the current set of images
108 * @code{CO_MIN}: CO_MIN, Minimal value on the current set of images
109 * @code{CO_REDUCE}: CO_REDUCE, Reduction of values on the current set of images
110 * @code{CO_SUM}: CO_SUM, Sum of values on the current set of images
111 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
112 * @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler
113 * @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string
114 * @code{COMPLEX}: COMPLEX, Complex conversion function
115 * @code{CONJG}: CONJG, Complex conjugate function
116 * @code{COS}: COS, Cosine function
117 * @code{COSD}: COSD, Cosine function, degrees
118 * @code{COSH}: COSH, Hyperbolic cosine function
119 * @code{COTAN}: COTAN, Cotangent function
120 * @code{COTAND}: COTAND, Cotangent function, degrees
121 * @code{COUNT}: COUNT, Count occurrences of TRUE in an array
122 * @code{CPU_TIME}: CPU_TIME, CPU time subroutine
123 * @code{CSHIFT}: CSHIFT, Circular shift elements of an array
124 * @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string
125 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
126 * @code{DBLE}: DBLE, Double precision conversion function
127 * @code{DCMPLX}: DCMPLX, Double complex conversion function
128 * @code{DIGITS}: DIGITS, Significant digits function
129 * @code{DIM}: DIM, Positive difference
130 * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
131 * @code{DPROD}: DPROD, Double product function
132 * @code{DREAL}: DREAL, Double real part function
133 * @code{DSHIFTL}: DSHIFTL, Combined left shift
134 * @code{DSHIFTR}: DSHIFTR, Combined right shift
135 * @code{DTIME}: DTIME, Execution time subroutine (or function)
136 * @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array
137 * @code{EPSILON}: EPSILON, Epsilon function
138 * @code{ERF}: ERF, Error function
139 * @code{ERFC}: ERFC, Complementary error function
140 * @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function
141 * @code{ETIME}: ETIME, Execution time subroutine (or function)
142 * @code{EVENT_QUERY}: EVENT_QUERY, Query whether a coarray event has occurred
143 * @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command
144 * @code{EXIT}: EXIT, Exit the program with status.
145 * @code{EXP}: EXP, Exponential function
146 * @code{EXPONENT}: EXPONENT, Exponent function
147 * @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF, Query dynamic type for extension
148 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
149 * @code{FGET}: FGET, Read a single character in stream mode from stdin
150 * @code{FGETC}: FGETC, Read a single character in stream mode
151 * @code{FLOOR}: FLOOR, Integer floor function
152 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
153 * @code{FNUM}: FNUM, File number function
154 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
155 * @code{FPUTC}: FPUTC, Write a single character in stream mode
156 * @code{FRACTION}: FRACTION, Fractional part of the model representation
157 * @code{FREE}: FREE, Memory de-allocation subroutine
158 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
159 * @code{FSTAT}: FSTAT, Get file status
160 * @code{FTELL}: FTELL, Current stream position
161 * @code{GAMMA}: GAMMA, Gamma function
162 * @code{GERROR}: GERROR, Get last system error message
163 * @code{GETARG}: GETARG, Get command line arguments
164 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
165 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
166 * @code{GETCWD}: GETCWD, Get current working directory
167 * @code{GETENV}: GETENV, Get an environmental variable
168 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
169 * @code{GETGID}: GETGID, Group ID function
170 * @code{GETLOG}: GETLOG, Get login name
171 * @code{GETPID}: GETPID, Process ID function
172 * @code{GETUID}: GETUID, User ID function
173 * @code{GMTIME}: GMTIME, Convert time to GMT info
174 * @code{HOSTNM}: HOSTNM, Get system host name
175 * @code{HUGE}: HUGE, Largest number of a kind
176 * @code{HYPOT}: HYPOT, Euclidean distance function
177 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
178 * @code{IALL}: IALL, Bitwise AND of array elements
179 * @code{IAND}: IAND, Bitwise logical and
180 * @code{IANY}: IANY, Bitwise OR of array elements
181 * @code{IARGC}: IARGC, Get the number of command line arguments
182 * @code{IBCLR}: IBCLR, Clear bit
183 * @code{IBITS}: IBITS, Bit extraction
184 * @code{IBSET}: IBSET, Set bit
185 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
186 * @code{IDATE}: IDATE, Current local time (day/month/year)
187 * @code{IEOR}: IEOR, Bitwise logical exclusive or
188 * @code{IERRNO}: IERRNO, Function to get the last system error number
189 * @code{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index conversion
190 * @code{INDEX}: INDEX intrinsic, Position of a substring within a string
191 * @code{INT}: INT, Convert to integer type
192 * @code{INT2}: INT2, Convert to 16-bit integer type
193 * @code{INT8}: INT8, Convert to 64-bit integer type
194 * @code{IOR}: IOR, Bitwise logical or
195 * @code{IPARITY}: IPARITY, Bitwise XOR of array elements
196 * @code{IRAND}: IRAND, Integer pseudo-random number
197 * @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value
198 * @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value
199 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
200 * @code{ISHFT}: ISHFT, Shift bits
201 * @code{ISHFTC}: ISHFTC, Shift bits circularly
202 * @code{ISNAN}: ISNAN, Tests for a NaN
203 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
204 * @code{KILL}: KILL, Send a signal to a process
205 * @code{KIND}: KIND, Kind of an entity
206 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
207 * @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array
208 * @code{LEADZ}: LEADZ, Number of leading zero bits of an integer
209 * @code{LEN}: LEN, Length of a character entity
210 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
211 * @code{LGE}: LGE, Lexical greater than or equal
212 * @code{LGT}: LGT, Lexical greater than
213 * @code{LINK}: LINK, Create a hard link
214 * @code{LLE}: LLE, Lexical less than or equal
215 * @code{LLT}: LLT, Lexical less than
216 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
217 * @code{LOC}: LOC, Returns the address of a variable
218 * @code{LOG}: LOG, Logarithm function
219 * @code{LOG10}: LOG10, Base 10 logarithm function
220 * @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
221 * @code{LOGICAL}: LOGICAL, Convert to logical type
222 * @code{LONG}: LONG, Convert to integer type
223 * @code{LSHIFT}: LSHIFT, Left shift bits
224 * @code{LSTAT}: LSTAT, Get file status
225 * @code{LTIME}: LTIME, Convert time to local time info
226 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
227 * @code{MASKL}: MASKL, Left justified mask
228 * @code{MASKR}: MASKR, Right justified mask
229 * @code{MATMUL}: MATMUL, matrix multiplication
230 * @code{MAX}: MAX, Maximum value of an argument list
231 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
232 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
233 * @code{MAXVAL}: MAXVAL, Maximum value of an array
234 * @code{MCLOCK}: MCLOCK, Time function
235 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
236 * @code{MERGE}: MERGE, Merge arrays
237 * @code{MERGE_BITS}: MERGE_BITS, Merge of bits under mask
238 * @code{MIN}: MIN, Minimum value of an argument list
239 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
240 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
241 * @code{MINVAL}: MINVAL, Minimum value of an array
242 * @code{MOD}: MOD, Remainder function
243 * @code{MODULO}: MODULO, Modulo function
244 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
245 * @code{MVBITS}: MVBITS, Move bits from one integer to another
246 * @code{NEAREST}: NEAREST, Nearest representable number
247 * @code{NEW_LINE}: NEW_LINE, New line character
248 * @code{NINT}: NINT, Nearest whole number
249 * @code{NORM2}: NORM2, Euclidean vector norm
250 * @code{NOT}: NOT, Logical negation
251 * @code{NULL}: NULL, Function that returns an disassociated pointer
252 * @code{NUM_IMAGES}: NUM_IMAGES, Number of images
253 * @code{OR}: OR, Bitwise logical OR
254 * @code{PACK}: PACK, Pack an array into an array of rank one
255 * @code{PARITY}: PARITY, Reduction with exclusive OR
256 * @code{PERROR}: PERROR, Print system error message
257 * @code{POPCNT}: POPCNT, Number of bits set
258 * @code{POPPAR}: POPPAR, Parity of the number of bits set
259 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
260 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
261 * @code{PRODUCT}: PRODUCT, Product of array elements
262 * @code{RADIX}: RADIX, Base of a data model
263 * @code{RAN}: RAN, Real pseudo-random number
264 * @code{RAND}: RAND, Real pseudo-random number
265 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
266 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
267 * @code{RANGE}: RANGE, Decimal exponent range
268 * @code{RANK} : RANK, Rank of a data object
269 * @code{REAL}: REAL, Convert to real type
270 * @code{RENAME}: RENAME, Rename a file
271 * @code{REPEAT}: REPEAT, Repeated string concatenation
272 * @code{RESHAPE}: RESHAPE, Function to reshape an array
273 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
274 * @code{RSHIFT}: RSHIFT, Right shift bits
275 * @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality
276 * @code{SCALE}: SCALE, Scale a real value
277 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
278 * @code{SECNDS}: SECNDS, Time function
279 * @code{SECOND}: SECOND, CPU time function
280 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind
281 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
282 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
283 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
284 * @code{SHAPE}: SHAPE, Determine the shape of an array
285 * @code{SHIFTA}: SHIFTA, Right shift with fill
286 * @code{SHIFTL}: SHIFTL, Left shift
287 * @code{SHIFTR}: SHIFTR, Right shift
288 * @code{SIGN}: SIGN, Sign copying function
289 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
290 * @code{SIN}: SIN, Sine function
291 * @code{SIND}: SIND, Sine function, degrees
292 * @code{SINH}: SINH, Hyperbolic sine function
293 * @code{SIZE}: SIZE, Function to determine the size of an array
294 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
295 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
296 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
297 * @code{SPREAD}: SPREAD, Add a dimension to an array
298 * @code{SQRT}: SQRT, Square-root function
299 * @code{SRAND}: SRAND, Reinitialize the random number generator
300 * @code{STAT}: STAT, Get file status
301 * @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits
302 * @code{SUM}: SUM, Sum of array elements
303 * @code{SYMLNK}: SYMLNK, Create a symbolic link
304 * @code{SYSTEM}: SYSTEM, Execute a shell command
305 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
306 * @code{TAN}: TAN, Tangent function
307 * @code{TAND}: TAND, Tangent function, degrees
308 * @code{TANH}: TANH, Hyperbolic tangent function
309 * @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image
310 * @code{TIME}: TIME, Time function
311 * @code{TIME8}: TIME8, Time function (64-bit)
312 * @code{TINY}: TINY, Smallest positive number of a real kind
313 * @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer
314 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
315 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
316 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
317 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
318 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
319 * @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array
320 * @code{UMASK}: UMASK, Set the file creation mask
321 * @code{UNLINK}: UNLINK, Remove a file from the file system
322 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
323 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
324 * @code{XOR}: XOR, Bitwise logical exclusive or
327 @node Introduction to Intrinsics
328 @section Introduction to intrinsic procedures
330 The intrinsic procedures provided by GNU Fortran include all of the
331 intrinsic procedures required by the Fortran 95 standard, a set of
332 intrinsic procedures for backwards compatibility with G77, and a
333 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
334 standards. Any conflict between a description here and a description in
335 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
336 2008 standard is unintentional, and the standard(s) should be considered
339 The enumeration of the @code{KIND} type parameter is processor defined in
340 the Fortran 95 standard. GNU Fortran defines the default integer type and
341 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
342 respectively. The standard mandates that both data types shall have
343 another kind, which have more precision. On typical target architectures
344 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
345 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
346 In the description of generic intrinsic procedures, the kind type parameter
347 will be specified by @code{KIND=*}, and in the description of specific
348 names for an intrinsic procedure the kind type parameter will be explicitly
349 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
350 brevity the optional @code{KIND=} syntax will be omitted.
352 Many of the intrinsic procedures take one or more optional arguments.
353 This document follows the convention used in the Fortran 95 standard,
354 and denotes such arguments by square brackets.
356 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
357 which can be used to restrict the set of intrinsic procedures to a
358 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
359 option, and so all intrinsic procedures described here are accepted. There
360 is one caveat. For a select group of intrinsic procedures, @command{g77}
361 implemented both a function and a subroutine. Both classes
362 have been implemented in @command{gfortran} for backwards compatibility
363 with @command{g77}. It is noted here that these functions and subroutines
364 cannot be intermixed in a given subprogram. In the descriptions that follow,
365 the applicable standard for each intrinsic procedure is noted.
370 @section @code{ABORT} --- Abort the program
372 @cindex program termination, with core dump
373 @cindex terminate program, with core dump
377 @item @emph{Description}:
378 @code{ABORT} causes immediate termination of the program. On operating
379 systems that support a core dump, @code{ABORT} will produce a core dump.
380 It will also print a backtrace, unless @code{-fno-backtrace} is given.
382 @item @emph{Standard}:
391 @item @emph{Return value}:
394 @item @emph{Example}:
397 integer :: i = 1, j = 2
398 if (i /= j) call abort
399 end program test_abort
402 @item @emph{See also}:
403 @ref{EXIT}, @ref{KILL}, @ref{BACKTRACE}
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 .20 .20 .25
461 @item 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{COMPLEX(8)} @tab GNU extension
471 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(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. Tailing 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
529 @item @emph{Specific names}:
530 @item @emph{See also}:
537 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
539 @cindex @acronym{ASCII} collating sequence
540 @cindex collating sequence, @acronym{ASCII}
543 @item @emph{Description}:
544 @code{ACHAR(I)} returns the character located at position @code{I}
545 in the @acronym{ASCII} collating sequence.
547 @item @emph{Standard}:
548 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
554 @code{RESULT = ACHAR(I [, KIND])}
556 @item @emph{Arguments}:
557 @multitable @columnfractions .15 .70
558 @item @var{I} @tab The type shall be @code{INTEGER}.
559 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
560 expression indicating the kind parameter of the result.
563 @item @emph{Return value}:
564 The return value is of type @code{CHARACTER} with a length of one.
565 If the @var{KIND} argument is present, the return value is of the
566 specified kind and of the default kind otherwise.
568 @item @emph{Example}:
573 end program test_achar
577 See @ref{ICHAR} for a discussion of converting between numerical values
578 and formatted string representations.
580 @item @emph{See also}:
581 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
588 @section @code{ACOS} --- Arccosine function
591 @cindex trigonometric function, cosine, inverse
592 @cindex cosine, inverse
595 @item @emph{Description}:
596 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
598 @item @emph{Standard}:
599 Fortran 77 and later, for a complex argument Fortran 2008 or later
605 @code{RESULT = ACOS(X)}
607 @item @emph{Arguments}:
608 @multitable @columnfractions .15 .70
609 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
610 less than or equal to one - or the type shall be @code{COMPLEX}.
613 @item @emph{Return value}:
614 The return value is of the same type and kind as @var{X}.
615 The real part of the result is in radians and lies in the range
616 @math{0 \leq \Re \acos(x) \leq \pi}.
618 @item @emph{Example}:
621 real(8) :: x = 0.866_8
623 end program test_acos
626 @item @emph{Specific names}:
627 @multitable @columnfractions .20 .20 .20 .25
628 @item Name @tab Argument @tab Return type @tab Standard
629 @item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
630 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
633 @item @emph{See also}:
634 Inverse function: @ref{COS}
635 Degrees function: @ref{ACOSD}
642 @section @code{ACOSD} --- Arccosine function, degrees
645 @cindex trigonometric function, cosine, inverse, degrees
646 @cindex cosine, inverse, degrees
649 @item @emph{Description}:
650 @code{ACOSD(X)} computes the arccosine of @var{X} in degrees (inverse of
653 This function is for compatibility only and should be avoided in favor of
654 standard constructs wherever possible.
656 @item @emph{Standard}:
657 GNU Extension, enabled with @option{-fdec-math}
663 @code{RESULT = ACOSD(X)}
665 @item @emph{Arguments}:
666 @multitable @columnfractions .15 .70
667 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
668 less than or equal to one - or the type shall be @code{COMPLEX}.
671 @item @emph{Return value}:
672 The return value is of the same type and kind as @var{X}.
673 The real part of the result is in degrees and lies in the range
674 @math{0 \leq \Re \acos(x) \leq 180}.
676 @item @emph{Example}:
679 real(8) :: x = 0.866_8
681 end program test_acosd
684 @item @emph{Specific names}:
685 @multitable @columnfractions .20 .20 .20 .25
686 @item Name @tab Argument @tab Return type @tab Standard
687 @item @code{ACOSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
688 @item @code{DACOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
691 @item @emph{See also}:
692 Inverse function: @ref{COSD}
693 Radians function: @ref{ACOS}
700 @section @code{ACOSH} --- Inverse hyperbolic cosine function
703 @cindex area hyperbolic cosine
704 @cindex inverse hyperbolic cosine
705 @cindex hyperbolic function, cosine, inverse
706 @cindex cosine, hyperbolic, inverse
709 @item @emph{Description}:
710 @code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
712 @item @emph{Standard}:
713 Fortran 2008 and later
719 @code{RESULT = ACOSH(X)}
721 @item @emph{Arguments}:
722 @multitable @columnfractions .15 .70
723 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
726 @item @emph{Return value}:
727 The return value has the same type and kind as @var{X}. If @var{X} is
728 complex, the imaginary part of the result is in radians and lies between
729 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
731 @item @emph{Example}:
734 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
739 @item @emph{Specific names}:
740 @multitable @columnfractions .20 .20 .20 .25
741 @item Name @tab Argument @tab Return type @tab Standard
742 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
745 @item @emph{See also}:
746 Inverse function: @ref{COSH}
752 @section @code{ADJUSTL} --- Left adjust a string
754 @cindex string, adjust left
755 @cindex adjust string
758 @item @emph{Description}:
759 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
760 Spaces are inserted at the end of the string as needed.
762 @item @emph{Standard}:
769 @code{RESULT = ADJUSTL(STRING)}
771 @item @emph{Arguments}:
772 @multitable @columnfractions .15 .70
773 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
776 @item @emph{Return value}:
777 The return value is of type @code{CHARACTER} and of the same kind as
778 @var{STRING} where leading spaces are removed and the same number of
779 spaces are inserted on the end of @var{STRING}.
781 @item @emph{Example}:
784 character(len=20) :: str = ' gfortran'
787 end program test_adjustl
790 @item @emph{See also}:
791 @ref{ADJUSTR}, @ref{TRIM}
797 @section @code{ADJUSTR} --- Right adjust a string
799 @cindex string, adjust right
800 @cindex adjust string
803 @item @emph{Description}:
804 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
805 Spaces are inserted at the start of the string as needed.
807 @item @emph{Standard}:
814 @code{RESULT = ADJUSTR(STRING)}
816 @item @emph{Arguments}:
817 @multitable @columnfractions .15 .70
818 @item @var{STR} @tab The type shall be @code{CHARACTER}.
821 @item @emph{Return value}:
822 The return value is of type @code{CHARACTER} and of the same kind as
823 @var{STRING} where trailing spaces are removed and the same number of
824 spaces are inserted at the start of @var{STRING}.
826 @item @emph{Example}:
829 character(len=20) :: str = 'gfortran'
832 end program test_adjustr
835 @item @emph{See also}:
836 @ref{ADJUSTL}, @ref{TRIM}
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 .20 .20 .25
887 @item Name @tab Argument @tab Return type @tab Standard
888 @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
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) An @code{INTEGER} initialization
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 .20 .20 .25
947 @item 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 95 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 95 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.
1146 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1149 @item @emph{Return value}:
1150 The return type is either a scalar @code{INTEGER} or a scalar
1151 @code{LOGICAL}. If the kind type parameters differ, then the
1152 smaller kind type is implicitly converted to larger kind, and the
1153 return has the larger kind.
1155 @item @emph{Example}:
1158 LOGICAL :: T = .TRUE., F = .FALSE.
1160 DATA a / Z'F' /, b / Z'3' /
1162 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1163 WRITE (*,*) AND(a, b)
1167 @item @emph{See also}:
1168 Fortran 95 elemental function: @ref{IAND}
1174 @section @code{ANINT} --- Nearest whole number
1178 @cindex rounding, ceiling
1181 @item @emph{Description}:
1182 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1184 @item @emph{Standard}:
1185 Fortran 77 and later
1190 @item @emph{Syntax}:
1191 @code{RESULT = ANINT(A [, KIND])}
1193 @item @emph{Arguments}:
1194 @multitable @columnfractions .15 .70
1195 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1196 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1197 expression indicating the kind parameter of the result.
1200 @item @emph{Return value}:
1201 The return value is of type real with the kind type parameter of the
1202 argument if the optional @var{KIND} is absent; otherwise, the kind
1203 type parameter will be given by @var{KIND}. If @var{A} is greater than
1204 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1205 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1207 @item @emph{Example}:
1214 print *, anint(x4), dnint(x8)
1216 end program test_anint
1219 @item @emph{Specific names}:
1220 @multitable @columnfractions .20 .20 .20 .25
1221 @item Name @tab Argument @tab Return type @tab Standard
1222 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
1223 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1230 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1232 @cindex array, apply condition
1233 @cindex array, condition testing
1236 @item @emph{Description}:
1237 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1238 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1240 @item @emph{Standard}:
1241 Fortran 95 and later
1244 Transformational function
1246 @item @emph{Syntax}:
1247 @code{RESULT = ANY(MASK [, DIM])}
1249 @item @emph{Arguments}:
1250 @multitable @columnfractions .15 .70
1251 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1252 it shall not be scalar.
1253 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1254 with a value that lies between one and the rank of @var{MASK}.
1257 @item @emph{Return value}:
1258 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1259 the kind type parameter is the same as the kind type parameter of
1260 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1261 an array with the rank of @var{MASK} minus 1. The shape is determined from
1262 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1266 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1267 otherwise, it is false. It also is false if @var{MASK} has zero size.
1269 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1270 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1271 is determined by applying @code{ANY} to the array sections.
1274 @item @emph{Example}:
1278 l = any((/.true., .true., .true./))
1283 integer a(2,3), b(2,3)
1287 print *, any(a .eq. b, 1)
1288 print *, any(a .eq. b, 2)
1289 end subroutine section
1290 end program test_any
1297 @section @code{ASIN} --- Arcsine function
1300 @cindex trigonometric function, sine, inverse
1301 @cindex sine, inverse
1304 @item @emph{Description}:
1305 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1307 @item @emph{Standard}:
1308 Fortran 77 and later, for a complex argument Fortran 2008 or later
1313 @item @emph{Syntax}:
1314 @code{RESULT = ASIN(X)}
1316 @item @emph{Arguments}:
1317 @multitable @columnfractions .15 .70
1318 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1319 less than or equal to one - or be @code{COMPLEX}.
1322 @item @emph{Return value}:
1323 The return value is of the same type and kind as @var{X}.
1324 The real part of the result is in radians and lies in the range
1325 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1327 @item @emph{Example}:
1330 real(8) :: x = 0.866_8
1332 end program test_asin
1335 @item @emph{Specific names}:
1336 @multitable @columnfractions .20 .20 .20 .25
1337 @item Name @tab Argument @tab Return type @tab Standard
1338 @item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1339 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1342 @item @emph{See also}:
1343 Inverse function: @ref{SIN}
1344 Degrees function: @ref{ASIND}
1351 @section @code{ASIND} --- Arcsine function, degrees
1354 @cindex trigonometric function, sine, inverse, degrees
1355 @cindex sine, inverse, degrees
1358 @item @emph{Description}:
1359 @code{ASIND(X)} computes the arcsine of its @var{X} in degrees (inverse of
1362 This function is for compatibility only and should be avoided in favor of
1363 standard constructs wherever possible.
1365 @item @emph{Standard}:
1366 GNU Extension, enabled with @option{-fdec-math}.
1371 @item @emph{Syntax}:
1372 @code{RESULT = ASIND(X)}
1374 @item @emph{Arguments}:
1375 @multitable @columnfractions .15 .70
1376 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1377 less than or equal to one - or be @code{COMPLEX}.
1380 @item @emph{Return value}:
1381 The return value is of the same type and kind as @var{X}.
1382 The real part of the result is in degrees and lies in the range
1383 @math{-90 \leq \Re \asin(x) \leq 90}.
1385 @item @emph{Example}:
1388 real(8) :: x = 0.866_8
1390 end program test_asind
1393 @item @emph{Specific names}:
1394 @multitable @columnfractions .20 .20 .20 .25
1395 @item Name @tab Argument @tab Return type @tab Standard
1396 @item @code{ASIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
1397 @item @code{DASIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
1400 @item @emph{See also}:
1401 Inverse function: @ref{SIND}
1402 Radians function: @ref{ASIN}
1409 @section @code{ASINH} --- Inverse hyperbolic sine function
1412 @cindex area hyperbolic sine
1413 @cindex inverse hyperbolic sine
1414 @cindex hyperbolic function, sine, inverse
1415 @cindex sine, hyperbolic, inverse
1418 @item @emph{Description}:
1419 @code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
1421 @item @emph{Standard}:
1422 Fortran 2008 and later
1427 @item @emph{Syntax}:
1428 @code{RESULT = ASINH(X)}
1430 @item @emph{Arguments}:
1431 @multitable @columnfractions .15 .70
1432 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1435 @item @emph{Return value}:
1436 The return value is of the same type and kind as @var{X}. If @var{X} is
1437 complex, the imaginary part of the result is in radians and lies between
1438 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1440 @item @emph{Example}:
1443 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1444 WRITE (*,*) ASINH(x)
1448 @item @emph{Specific names}:
1449 @multitable @columnfractions .20 .20 .20 .25
1450 @item Name @tab Argument @tab Return type @tab Standard
1451 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1454 @item @emph{See also}:
1455 Inverse function: @ref{SINH}
1461 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1463 @cindex pointer, status
1464 @cindex association status
1467 @item @emph{Description}:
1468 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1469 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1471 @item @emph{Standard}:
1472 Fortran 95 and later
1477 @item @emph{Syntax}:
1478 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1480 @item @emph{Arguments}:
1481 @multitable @columnfractions .15 .70
1482 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1483 and it can be of any type.
1484 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1485 a target. It must have the same type, kind type parameter, and
1486 array rank as @var{POINTER}.
1488 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1491 @item @emph{Return value}:
1492 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1493 There are several cases:
1495 @item (A) When the optional @var{TARGET} is not present then
1496 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1497 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1498 @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
1499 disassociated, the result is false.
1500 @item (C) If @var{TARGET} is present and an array target, the result is true if
1501 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1502 are arrays whose elements are not zero-sized storage sequences, and
1503 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1505 As in case(B), the result is false, if @var{POINTER} is disassociated.
1506 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1507 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1508 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1510 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1511 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1512 target associated with @var{POINTER} and the target associated with @var{TARGET}
1513 have the same shape, are not zero-sized arrays, are arrays whose elements are
1514 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1515 the same storage units in array element order.
1516 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1519 @item @emph{Example}:
1521 program test_associated
1523 real, target :: tgt(2) = (/1., 2./)
1524 real, pointer :: ptr(:)
1526 if (associated(ptr) .eqv. .false.) call abort
1527 if (associated(ptr,tgt) .eqv. .false.) call abort
1528 end program test_associated
1531 @item @emph{See also}:
1538 @section @code{ATAN} --- Arctangent function
1541 @cindex trigonometric function, tangent, inverse
1542 @cindex tangent, inverse
1545 @item @emph{Description}:
1546 @code{ATAN(X)} computes the arctangent of @var{X}.
1548 @item @emph{Standard}:
1549 Fortran 77 and later, for a complex argument and for two arguments
1550 Fortran 2008 or later
1555 @item @emph{Syntax}:
1556 @multitable @columnfractions .80
1557 @item @code{RESULT = ATAN(X)}
1558 @item @code{RESULT = ATAN(Y, X)}
1561 @item @emph{Arguments}:
1562 @multitable @columnfractions .15 .70
1563 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1564 if @var{Y} is present, @var{X} shall be REAL.
1565 @item @var{Y} shall be of the same type and kind as @var{X}.
1568 @item @emph{Return value}:
1569 The return value is of the same type and kind as @var{X}.
1570 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1571 Otherwise, it the arcus tangent of @var{X}, where the real part of
1572 the result is in radians and lies in the range
1573 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1575 @item @emph{Example}:
1578 real(8) :: x = 2.866_8
1580 end program test_atan
1583 @item @emph{Specific names}:
1584 @multitable @columnfractions .20 .20 .20 .25
1585 @item Name @tab Argument @tab Return type @tab Standard
1586 @item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1587 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1590 @item @emph{See also}:
1591 Inverse function: @ref{TAN}
1592 Degrees function: @ref{ATAND}
1599 @section @code{ATAND} --- Arctangent function, degrees
1602 @cindex trigonometric function, tangent, inverse, degrees
1603 @cindex tangent, inverse, degrees
1606 @item @emph{Description}:
1607 @code{ATAND(X)} computes the arctangent of @var{X} in degrees (inverse of
1610 This function is for compatibility only and should be avoided in favor of
1611 standard constructs wherever possible.
1613 @item @emph{Standard}:
1614 GNU Extension, enabled with @option{-fdec-math}.
1619 @item @emph{Syntax}:
1620 @multitable @columnfractions .80
1621 @item @code{RESULT = ATAND(X)}
1622 @item @code{RESULT = ATAND(Y, X)}
1625 @item @emph{Arguments}:
1626 @multitable @columnfractions .15 .70
1627 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1628 if @var{Y} is present, @var{X} shall be REAL.
1629 @item @var{Y} shall be of the same type and kind as @var{X}.
1632 @item @emph{Return value}:
1633 The return value is of the same type and kind as @var{X}.
1634 If @var{Y} is present, the result is identical to @code{ATAND2(Y,X)}.
1635 Otherwise, it is the arcus tangent of @var{X}, where the real part of
1636 the result is in degrees and lies in the range
1637 @math{-90 \leq \Re \atand(x) \leq 90}.
1639 @item @emph{Example}:
1642 real(8) :: x = 2.866_8
1644 end program test_atand
1647 @item @emph{Specific names}:
1648 @multitable @columnfractions .20 .20 .20 .25
1649 @item Name @tab Argument @tab Return type @tab Standard
1650 @item @code{ATAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
1651 @item @code{DATAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
1654 @item @emph{See also}:
1655 Inverse function: @ref{TAND}
1656 Radians function: @ref{ATAN}
1663 @section @code{ATAN2} --- Arctangent function
1666 @cindex trigonometric function, tangent, inverse
1667 @cindex tangent, inverse
1670 @item @emph{Description}:
1671 @code{ATAN2(Y, X)} computes the principal value of the argument
1672 function of the complex number @math{X + i Y}. This function can
1673 be used to transform from Cartesian into polar coordinates and
1674 allows to determine the angle in the correct quadrant.
1676 @item @emph{Standard}:
1677 Fortran 77 and later
1682 @item @emph{Syntax}:
1683 @code{RESULT = ATAN2(Y, X)}
1685 @item @emph{Arguments}:
1686 @multitable @columnfractions .15 .70
1687 @item @var{Y} @tab The type shall be @code{REAL}.
1688 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1689 If @var{Y} is zero, then @var{X} must be nonzero.
1692 @item @emph{Return value}:
1693 The return value has the same type and kind type parameter as @var{Y}. It
1694 is the principal value of the complex number @math{X + i Y}. If @var{X}
1695 is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1696 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1697 the return value is zero if @var{X} is strictly positive, @math{\pi} if
1698 @var{X} is negative and @var{Y} is positive zero (or the processor does
1699 not handle signed zeros), and @math{-\pi} if @var{X} is negative and
1700 @var{Y} is negative zero. Finally, if @var{X} is zero, then the
1701 magnitude of the result is @math{\pi/2}.
1703 @item @emph{Example}:
1706 real(4) :: x = 1.e0_4, y = 0.5e0_4
1708 end program test_atan2
1711 @item @emph{Specific names}:
1712 @multitable @columnfractions .20 .20 .20 .25
1713 @item Name @tab Argument @tab Return type @tab Standard
1714 @item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1715 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1718 @item @emph{See also}:
1720 Degrees function: @ref{ATAN2D}
1727 @section @code{ATAN2D} --- Arctangent function, degrees
1730 @cindex trigonometric function, tangent, inverse, degrees
1731 @cindex tangent, inverse, degrees
1734 @item @emph{Description}:
1735 @code{ATAN2D(Y, X)} computes the principal value of the argument
1736 function of the complex number @math{X + i Y} in degrees. This function can
1737 be used to transform from Cartesian into polar coordinates and
1738 allows to determine the angle in the correct quadrant.
1740 This function is for compatibility only and should be avoided in favor of
1741 standard constructs wherever possible.
1743 @item @emph{Standard}:
1744 GNU Extension, enabled with @option{-fdec-math}.
1749 @item @emph{Syntax}:
1750 @code{RESULT = ATAN2D(Y, X)}
1752 @item @emph{Arguments}:
1753 @multitable @columnfractions .15 .70
1754 @item @var{Y} @tab The type shall be @code{REAL}.
1755 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1756 If @var{Y} is zero, then @var{X} must be nonzero.
1759 @item @emph{Return value}:
1760 The return value has the same type and kind type parameter as @var{Y}. It
1761 is the principal value of the complex number @math{X + i Y}. If @var{X}
1762 is nonzero, then it lies in the range @math{-180 \le \atan (x) \leq 180}.
1763 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1764 the return value is zero if @var{X} is strictly positive, @math{180} if
1765 @var{X} is negative and @var{Y} is positive zero (or the processor does
1766 not handle signed zeros), and @math{-180} if @var{X} is negative and
1767 @var{Y} is negative zero. Finally, if @var{X} is zero, then the
1768 magnitude of the result is @math{90}.
1770 @item @emph{Example}:
1773 real(4) :: x = 1.e0_4, y = 0.5e0_4
1775 end program test_atan2d
1778 @item @emph{Specific names}:
1779 @multitable @columnfractions .20 .20 .20 .25
1780 @item Name @tab Argument @tab Return type @tab Standard
1781 @item @code{ATAN2D(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab GNU Extension
1782 @item @code{DATAN2D(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab GNU Extension
1785 @item @emph{See also}:
1787 Radians function: @ref{ATAN2}
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 .20 .20 .25
1835 @item 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: @ref{TANH}
1846 @section @code{ATOMIC_ADD} --- Atomic ADD operation
1848 @cindex Atomic subroutine, add
1851 @item @emph{Description}:
1852 @code{ATOMIC_ADD(ATOM, VALUE)} atomically adds the value of @var{VAR} to the
1853 variable @var{ATOM}. When @var{STAT} is present and the invocation was
1854 successful, it is assigned the value 0. If it is present and the invocation
1855 has failed, it is assigned a positive value; in particular, for a coindexed
1856 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1857 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1858 failed, the value @code{STAT_FAILED_IMAGE}.
1860 @item @emph{Standard}:
1866 @item @emph{Syntax}:
1867 @code{CALL ATOMIC_ADD (ATOM, VALUE [, STAT])}
1869 @item @emph{Arguments}:
1870 @multitable @columnfractions .15 .70
1871 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1872 type with @code{ATOMIC_INT_KIND} kind.
1873 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1874 is different, the value is converted to the kind of @var{ATOM}.
1875 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1878 @item @emph{Example}:
1882 integer(atomic_int_kind) :: atom[*]
1883 call atomic_add (atom[1], this_image())
1887 @item @emph{See also}:
1888 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_ADD}, @ref{ISO_FORTRAN_ENV},
1889 @ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
1896 @section @code{ATOMIC_AND} --- Atomic bitwise AND operation
1898 @cindex Atomic subroutine, AND
1901 @item @emph{Description}:
1902 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
1903 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
1904 and the invocation was successful, it is assigned the value 0. If it is present
1905 and the invocation has failed, it is assigned a positive value; in particular,
1906 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
1907 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
1908 image has failed, the value @code{STAT_FAILED_IMAGE}.
1910 @item @emph{Standard}:
1916 @item @emph{Syntax}:
1917 @code{CALL ATOMIC_AND (ATOM, VALUE [, STAT])}
1919 @item @emph{Arguments}:
1920 @multitable @columnfractions .15 .70
1921 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1922 type with @code{ATOMIC_INT_KIND} kind.
1923 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1924 is different, the value is converted to the kind of @var{ATOM}.
1925 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1928 @item @emph{Example}:
1932 integer(atomic_int_kind) :: atom[*]
1933 call atomic_and (atom[1], int(b'10100011101'))
1937 @item @emph{See also}:
1938 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_AND}, @ref{ISO_FORTRAN_ENV},
1939 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
1945 @section @code{ATOMIC_CAS} --- Atomic compare and swap
1946 @fnindex ATOMIC_DEFINE
1947 @cindex Atomic subroutine, compare and swap
1950 @item @emph{Description}:
1951 @code{ATOMIC_CAS} compares the variable @var{ATOM} with the value of
1952 @var{COMPARE}; if the value is the same, @var{ATOM} is set to the value
1953 of @var{NEW}. Additionally, @var{OLD} is set to the value of @var{ATOM}
1954 that was used for the comparison. When @var{STAT} is present and the invocation
1955 was successful, it is assigned the value 0. If it is present and the invocation
1956 has failed, it is assigned a positive value; in particular, for a coindexed
1957 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1958 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1959 failed, the value @code{STAT_FAILED_IMAGE}.
1961 @item @emph{Standard}:
1967 @item @emph{Syntax}:
1968 @code{CALL ATOMIC_CAS (ATOM, OLD, COMPARE, NEW [, STAT])}
1970 @item @emph{Arguments}:
1971 @multitable @columnfractions .15 .70
1972 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
1973 type with @code{ATOMIC_INT_KIND} kind or logical type with
1974 @code{ATOMIC_LOGICAL_KIND} kind.
1975 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1976 @item @var{COMPARE} @tab Scalar variable of the same type and kind as
1978 @item @var{NEW} @tab Scalar variable of the same type as @var{ATOM}. If kind
1979 is different, the value is converted to the kind of @var{ATOM}.
1980 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1983 @item @emph{Example}:
1987 logical(atomic_logical_kind) :: atom[*], prev
1988 call atomic_cas (atom[1], prev, .false., .true.))
1992 @item @emph{See also}:
1993 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_REF}, @ref{ISO_FORTRAN_ENV}
1999 @section @code{ATOMIC_DEFINE} --- Setting a variable atomically
2000 @fnindex ATOMIC_DEFINE
2001 @cindex Atomic subroutine, define
2004 @item @emph{Description}:
2005 @code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value
2006 @var{VALUE} atomically. When @var{STAT} is present and the invocation was
2007 successful, it is assigned the value 0. If it is present and the invocation
2008 has failed, it is assigned a positive value; in particular, for a coindexed
2009 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2010 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2011 failed, the value @code{STAT_FAILED_IMAGE}.
2013 @item @emph{Standard}:
2014 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
2019 @item @emph{Syntax}:
2020 @code{CALL ATOMIC_DEFINE (ATOM, VALUE [, STAT])}
2022 @item @emph{Arguments}:
2023 @multitable @columnfractions .15 .70
2024 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
2025 type with @code{ATOMIC_INT_KIND} kind or logical type with
2026 @code{ATOMIC_LOGICAL_KIND} kind.
2028 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2029 is different, the value is converted to the kind of @var{ATOM}.
2030 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2033 @item @emph{Example}:
2037 integer(atomic_int_kind) :: atom[*]
2038 call atomic_define (atom[1], this_image())
2042 @item @emph{See also}:
2043 @ref{ATOMIC_REF}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV},
2044 @ref{ATOMIC_ADD}, @ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
2049 @node ATOMIC_FETCH_ADD
2050 @section @code{ATOMIC_FETCH_ADD} --- Atomic ADD operation with prior fetch
2051 @fnindex ATOMIC_FETCH_ADD
2052 @cindex Atomic subroutine, ADD with fetch
2055 @item @emph{Description}:
2056 @code{ATOMIC_FETCH_ADD(ATOM, VALUE, OLD)} atomically stores the value of
2057 @var{ATOM} in @var{OLD} and adds the value of @var{VAR} to the
2058 variable @var{ATOM}. When @var{STAT} is present and the invocation was
2059 successful, it is assigned the value 0. If it is present and the invocation
2060 has failed, it is assigned a positive value; in particular, for a coindexed
2061 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2062 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2063 failed, the value @code{STAT_FAILED_IMAGE}.
2065 @item @emph{Standard}:
2071 @item @emph{Syntax}:
2072 @code{CALL ATOMIC_FETCH_ADD (ATOM, VALUE, old [, STAT])}
2074 @item @emph{Arguments}:
2075 @multitable @columnfractions .15 .70
2076 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2077 type with @code{ATOMIC_INT_KIND} kind.
2078 @code{ATOMIC_LOGICAL_KIND} kind.
2080 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2081 is different, the value is converted to the kind of @var{ATOM}.
2082 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2083 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2086 @item @emph{Example}:
2090 integer(atomic_int_kind) :: atom[*], old
2091 call atomic_add (atom[1], this_image(), old)
2095 @item @emph{See also}:
2096 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_ADD}, @ref{ISO_FORTRAN_ENV},
2097 @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR}
2102 @node ATOMIC_FETCH_AND
2103 @section @code{ATOMIC_FETCH_AND} --- Atomic bitwise AND operation with prior fetch
2104 @fnindex ATOMIC_FETCH_AND
2105 @cindex Atomic subroutine, AND with fetch
2108 @item @emph{Description}:
2109 @code{ATOMIC_AND(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2110 @var{OLD} and defines @var{ATOM} with the bitwise AND between the values of
2111 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
2112 successful, it is assigned the value 0. If it is present and the invocation has
2113 failed, it is assigned a positive value; in particular, for a coindexed
2114 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2115 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2116 failed, the value @code{STAT_FAILED_IMAGE}.
2118 @item @emph{Standard}:
2124 @item @emph{Syntax}:
2125 @code{CALL ATOMIC_FETCH_AND (ATOM, VALUE, OLD [, STAT])}
2127 @item @emph{Arguments}:
2128 @multitable @columnfractions .15 .70
2129 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2130 type with @code{ATOMIC_INT_KIND} kind.
2131 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2132 is different, the value is converted to the kind of @var{ATOM}.
2133 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2134 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2137 @item @emph{Example}:
2141 integer(atomic_int_kind) :: atom[*], old
2142 call atomic_fetch_and (atom[1], int(b'10100011101'), old)
2146 @item @emph{See also}:
2147 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_AND}, @ref{ISO_FORTRAN_ENV},
2148 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR}
2153 @node ATOMIC_FETCH_OR
2154 @section @code{ATOMIC_FETCH_OR} --- Atomic bitwise OR operation with prior fetch
2155 @fnindex ATOMIC_FETCH_OR
2156 @cindex Atomic subroutine, OR with fetch
2159 @item @emph{Description}:
2160 @code{ATOMIC_OR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2161 @var{OLD} and defines @var{ATOM} with the bitwise OR between the values of
2162 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
2163 successful, it is assigned the value 0. If it is present and the invocation has
2164 failed, it is assigned a positive value; in particular, for a coindexed
2165 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2166 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2167 failed, the value @code{STAT_FAILED_IMAGE}.
2169 @item @emph{Standard}:
2175 @item @emph{Syntax}:
2176 @code{CALL ATOMIC_FETCH_OR (ATOM, VALUE, OLD [, STAT])}
2178 @item @emph{Arguments}:
2179 @multitable @columnfractions .15 .70
2180 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2181 type with @code{ATOMIC_INT_KIND} kind.
2182 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2183 is different, the value is converted to the kind of @var{ATOM}.
2184 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2185 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2188 @item @emph{Example}:
2192 integer(atomic_int_kind) :: atom[*], old
2193 call atomic_fetch_or (atom[1], int(b'10100011101'), old)
2197 @item @emph{See also}:
2198 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_OR}, @ref{ISO_FORTRAN_ENV},
2199 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_XOR}
2204 @node ATOMIC_FETCH_XOR
2205 @section @code{ATOMIC_FETCH_XOR} --- Atomic bitwise XOR operation with prior fetch
2206 @fnindex ATOMIC_FETCH_XOR
2207 @cindex Atomic subroutine, XOR with fetch
2210 @item @emph{Description}:
2211 @code{ATOMIC_XOR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2212 @var{OLD} and defines @var{ATOM} with the bitwise XOR between the values of
2213 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
2214 successful, it is assigned the value 0. If it is present and the invocation has
2215 failed, it is assigned a positive value; in particular, for a coindexed
2216 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2217 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2218 failed, the value @code{STAT_FAILED_IMAGE}.
2220 @item @emph{Standard}:
2226 @item @emph{Syntax}:
2227 @code{CALL ATOMIC_FETCH_XOR (ATOM, VALUE, OLD [, STAT])}
2229 @item @emph{Arguments}:
2230 @multitable @columnfractions .15 .70
2231 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2232 type with @code{ATOMIC_INT_KIND} kind.
2233 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2234 is different, the value is converted to the kind of @var{ATOM}.
2235 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2236 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2239 @item @emph{Example}:
2243 integer(atomic_int_kind) :: atom[*], old
2244 call atomic_fetch_xor (atom[1], int(b'10100011101'), old)
2248 @item @emph{See also}:
2249 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_XOR}, @ref{ISO_FORTRAN_ENV},
2250 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}
2256 @section @code{ATOMIC_OR} --- Atomic bitwise OR operation
2258 @cindex Atomic subroutine, OR
2261 @item @emph{Description}:
2262 @code{ATOMIC_OR(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
2263 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
2264 and the invocation was successful, it is assigned the value 0. If it is present
2265 and the invocation has failed, it is assigned a positive value; in particular,
2266 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
2267 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
2268 image has failed, the value @code{STAT_FAILED_IMAGE}.
2270 @item @emph{Standard}:
2276 @item @emph{Syntax}:
2277 @code{CALL ATOMIC_OR (ATOM, VALUE [, STAT])}
2279 @item @emph{Arguments}:
2280 @multitable @columnfractions .15 .70
2281 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2282 type with @code{ATOMIC_INT_KIND} kind.
2283 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2284 is different, the value is converted to the kind of @var{ATOM}.
2285 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2288 @item @emph{Example}:
2292 integer(atomic_int_kind) :: atom[*]
2293 call atomic_or (atom[1], int(b'10100011101'))
2297 @item @emph{See also}:
2298 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_OR}, @ref{ISO_FORTRAN_ENV},
2299 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
2305 @section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically
2307 @cindex Atomic subroutine, reference
2310 @item @emph{Description}:
2311 @code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the
2312 variable @var{ATOM} to @var{VALUE}. When @var{STAT} is present and the
2313 invocation was successful, it is assigned the value 0. If it is present and the
2314 invocation has failed, it is assigned a positive value; in particular, for a
2315 coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value
2316 of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image
2317 has failed, the value @code{STAT_FAILED_IMAGE}.
2320 @item @emph{Standard}:
2321 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
2326 @item @emph{Syntax}:
2327 @code{CALL ATOMIC_REF(VALUE, ATOM [, STAT])}
2329 @item @emph{Arguments}:
2330 @multitable @columnfractions .15 .70
2331 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2332 is different, the value is converted to the kind of @var{ATOM}.
2333 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
2334 type with @code{ATOMIC_INT_KIND} kind or logical type with
2335 @code{ATOMIC_LOGICAL_KIND} kind.
2336 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2339 @item @emph{Example}:
2343 logical(atomic_logical_kind) :: atom[*]
2345 call atomic_ref (atom, .false.)
2347 call atomic_ref (atom, val)
2354 @item @emph{See also}:
2355 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV},
2356 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR},
2357 @ref{ATOMIC_FETCH_XOR}
2362 @section @code{ATOMIC_XOR} --- Atomic bitwise OR operation
2364 @cindex Atomic subroutine, XOR
2367 @item @emph{Description}:
2368 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
2369 XOR between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
2370 and the invocation was successful, it is assigned the value 0. If it is present
2371 and the invocation has failed, it is assigned a positive value; in particular,
2372 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
2373 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
2374 image has failed, the value @code{STAT_FAILED_IMAGE}.
2376 @item @emph{Standard}:
2382 @item @emph{Syntax}:
2383 @code{CALL ATOMIC_XOR (ATOM, VALUE [, STAT])}
2385 @item @emph{Arguments}:
2386 @multitable @columnfractions .15 .70
2387 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2388 type with @code{ATOMIC_INT_KIND} kind.
2389 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2390 is different, the value is converted to the kind of @var{ATOM}.
2391 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2394 @item @emph{Example}:
2398 integer(atomic_int_kind) :: atom[*]
2399 call atomic_xor (atom[1], int(b'10100011101'))
2403 @item @emph{See also}:
2404 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_XOR}, @ref{ISO_FORTRAN_ENV},
2405 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
2410 @section @code{BACKTRACE} --- Show a backtrace
2415 @item @emph{Description}:
2416 @code{BACKTRACE} shows a backtrace at an arbitrary place in user code. Program
2417 execution continues normally afterwards. The backtrace information is printed
2418 to the unit corresponding to @code{ERROR_UNIT} in @code{ISO_FORTRAN_ENV}.
2420 @item @emph{Standard}:
2426 @item @emph{Syntax}:
2427 @code{CALL BACKTRACE}
2429 @item @emph{Arguments}:
2432 @item @emph{See also}:
2439 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
2443 @cindex Bessel function, first kind
2446 @item @emph{Description}:
2447 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
2448 order 0 of @var{X}. This function is available under the name
2449 @code{BESJ0} as a GNU extension.
2451 @item @emph{Standard}:
2452 Fortran 2008 and later
2457 @item @emph{Syntax}:
2458 @code{RESULT = BESSEL_J0(X)}
2460 @item @emph{Arguments}:
2461 @multitable @columnfractions .15 .70
2462 @item @var{X} @tab The type shall be @code{REAL}.
2465 @item @emph{Return value}:
2466 The return value is of type @code{REAL} and lies in the
2467 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
2470 @item @emph{Example}:
2473 real(8) :: x = 0.0_8
2475 end program test_besj0
2478 @item @emph{Specific names}:
2479 @multitable @columnfractions .20 .20 .20 .25
2480 @item Name @tab Argument @tab Return type @tab Standard
2481 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2488 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
2492 @cindex Bessel function, first kind
2495 @item @emph{Description}:
2496 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
2497 order 1 of @var{X}. This function is available under the name
2498 @code{BESJ1} as a GNU extension.
2500 @item @emph{Standard}:
2506 @item @emph{Syntax}:
2507 @code{RESULT = BESSEL_J1(X)}
2509 @item @emph{Arguments}:
2510 @multitable @columnfractions .15 .70
2511 @item @var{X} @tab The type shall be @code{REAL}.
2514 @item @emph{Return value}:
2515 The return value is of type @code{REAL} and lies in the
2516 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
2519 @item @emph{Example}:
2522 real(8) :: x = 1.0_8
2524 end program test_besj1
2527 @item @emph{Specific names}:
2528 @multitable @columnfractions .20 .20 .20 .25
2529 @item Name @tab Argument @tab Return type @tab Standard
2530 @item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2537 @section @code{BESSEL_JN} --- Bessel function of the first kind
2541 @cindex Bessel function, first kind
2544 @item @emph{Description}:
2545 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
2546 order @var{N} of @var{X}. This function is available under the name
2547 @code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays,
2548 their ranks and shapes shall conform.
2550 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
2551 of the first kind of the orders @var{N1} to @var{N2}.
2553 @item @emph{Standard}:
2554 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2557 Elemental function, except for the transformational function
2558 @code{BESSEL_JN(N1, N2, X)}
2560 @item @emph{Syntax}:
2561 @multitable @columnfractions .80
2562 @item @code{RESULT = BESSEL_JN(N, X)}
2563 @item @code{RESULT = BESSEL_JN(N1, N2, X)}
2566 @item @emph{Arguments}:
2567 @multitable @columnfractions .15 .70
2568 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
2569 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2570 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2571 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2572 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
2575 @item @emph{Return value}:
2576 The return value is a scalar of type @code{REAL}. It has the same
2580 The transformational function uses a recurrence algorithm which might,
2581 for some values of @var{X}, lead to different results than calls to
2582 the elemental function.
2584 @item @emph{Example}:
2587 real(8) :: x = 1.0_8
2589 end program test_besjn
2592 @item @emph{Specific names}:
2593 @multitable @columnfractions .20 .20 .20 .25
2594 @item Name @tab Argument @tab Return type @tab Standard
2595 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2596 @item @tab @code{REAL(8) X} @tab @tab
2603 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
2607 @cindex Bessel function, second kind
2610 @item @emph{Description}:
2611 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
2612 order 0 of @var{X}. This function is available under the name
2613 @code{BESY0} as a GNU extension.
2615 @item @emph{Standard}:
2616 Fortran 2008 and later
2621 @item @emph{Syntax}:
2622 @code{RESULT = BESSEL_Y0(X)}
2624 @item @emph{Arguments}:
2625 @multitable @columnfractions .15 .70
2626 @item @var{X} @tab The type shall be @code{REAL}.
2629 @item @emph{Return value}:
2630 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2632 @item @emph{Example}:
2635 real(8) :: x = 0.0_8
2637 end program test_besy0
2640 @item @emph{Specific names}:
2641 @multitable @columnfractions .20 .20 .20 .25
2642 @item Name @tab Argument @tab Return type @tab Standard
2643 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2650 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
2654 @cindex Bessel function, second kind
2657 @item @emph{Description}:
2658 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
2659 order 1 of @var{X}. This function is available under the name
2660 @code{BESY1} as a GNU extension.
2662 @item @emph{Standard}:
2663 Fortran 2008 and later
2668 @item @emph{Syntax}:
2669 @code{RESULT = BESSEL_Y1(X)}
2671 @item @emph{Arguments}:
2672 @multitable @columnfractions .15 .70
2673 @item @var{X} @tab The type shall be @code{REAL}.
2676 @item @emph{Return value}:
2677 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2679 @item @emph{Example}:
2682 real(8) :: x = 1.0_8
2684 end program test_besy1
2687 @item @emph{Specific names}:
2688 @multitable @columnfractions .20 .20 .20 .25
2689 @item Name @tab Argument @tab Return type @tab Standard
2690 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2697 @section @code{BESSEL_YN} --- Bessel function of the second kind
2701 @cindex Bessel function, second kind
2704 @item @emph{Description}:
2705 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
2706 order @var{N} of @var{X}. This function is available under the name
2707 @code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays,
2708 their ranks and shapes shall conform.
2710 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
2711 of the first kind of the orders @var{N1} to @var{N2}.
2713 @item @emph{Standard}:
2714 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2717 Elemental function, except for the transformational function
2718 @code{BESSEL_YN(N1, N2, X)}
2720 @item @emph{Syntax}:
2721 @multitable @columnfractions .80
2722 @item @code{RESULT = BESSEL_YN(N, X)}
2723 @item @code{RESULT = BESSEL_YN(N1, N2, X)}
2726 @item @emph{Arguments}:
2727 @multitable @columnfractions .15 .70
2728 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} .
2729 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2730 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2731 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2732 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
2735 @item @emph{Return value}:
2736 The return value is a scalar of type @code{REAL}. It has the same
2740 The transformational function uses a recurrence algorithm which might,
2741 for some values of @var{X}, lead to different results than calls to
2742 the elemental function.
2744 @item @emph{Example}:
2747 real(8) :: x = 1.0_8
2749 end program test_besyn
2752 @item @emph{Specific names}:
2753 @multitable @columnfractions .20 .20 .20 .25
2754 @item Name @tab Argument @tab Return type @tab Standard
2755 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2756 @item @tab @code{REAL(8) X} @tab @tab
2763 @section @code{BGE} --- Bitwise greater than or equal to
2765 @cindex bitwise comparison
2768 @item @emph{Description}:
2769 Determines whether an integral is a bitwise greater than or equal to
2772 @item @emph{Standard}:
2773 Fortran 2008 and later
2778 @item @emph{Syntax}:
2779 @code{RESULT = BGE(I, J)}
2781 @item @emph{Arguments}:
2782 @multitable @columnfractions .15 .70
2783 @item @var{I} @tab Shall be of @code{INTEGER} type.
2784 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2788 @item @emph{Return value}:
2789 The return value is of type @code{LOGICAL} and of the default kind.
2791 @item @emph{See also}:
2792 @ref{BGT}, @ref{BLE}, @ref{BLT}
2798 @section @code{BGT} --- Bitwise greater than
2800 @cindex bitwise comparison
2803 @item @emph{Description}:
2804 Determines whether an integral is a bitwise greater than another.
2806 @item @emph{Standard}:
2807 Fortran 2008 and later
2812 @item @emph{Syntax}:
2813 @code{RESULT = BGT(I, J)}
2815 @item @emph{Arguments}:
2816 @multitable @columnfractions .15 .70
2817 @item @var{I} @tab Shall be of @code{INTEGER} type.
2818 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2822 @item @emph{Return value}:
2823 The return value is of type @code{LOGICAL} and of the default kind.
2825 @item @emph{See also}:
2826 @ref{BGE}, @ref{BLE}, @ref{BLT}
2832 @section @code{BIT_SIZE} --- Bit size inquiry function
2834 @cindex bits, number of
2835 @cindex size of a variable, in bits
2838 @item @emph{Description}:
2839 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
2840 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
2841 independent of the actual value of @var{I}.
2843 @item @emph{Standard}:
2844 Fortran 95 and later
2849 @item @emph{Syntax}:
2850 @code{RESULT = BIT_SIZE(I)}
2852 @item @emph{Arguments}:
2853 @multitable @columnfractions .15 .70
2854 @item @var{I} @tab The type shall be @code{INTEGER}.
2857 @item @emph{Return value}:
2858 The return value is of type @code{INTEGER}
2860 @item @emph{Example}:
2862 program test_bit_size
2867 end program test_bit_size
2874 @section @code{BLE} --- Bitwise less than or equal to
2876 @cindex bitwise comparison
2879 @item @emph{Description}:
2880 Determines whether an integral is a bitwise less than or equal to
2883 @item @emph{Standard}:
2884 Fortran 2008 and later
2889 @item @emph{Syntax}:
2890 @code{RESULT = BLE(I, J)}
2892 @item @emph{Arguments}:
2893 @multitable @columnfractions .15 .70
2894 @item @var{I} @tab Shall be of @code{INTEGER} type.
2895 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2899 @item @emph{Return value}:
2900 The return value is of type @code{LOGICAL} and of the default kind.
2902 @item @emph{See also}:
2903 @ref{BGT}, @ref{BGE}, @ref{BLT}
2909 @section @code{BLT} --- Bitwise less than
2911 @cindex bitwise comparison
2914 @item @emph{Description}:
2915 Determines whether an integral is a bitwise less than another.
2917 @item @emph{Standard}:
2918 Fortran 2008 and later
2923 @item @emph{Syntax}:
2924 @code{RESULT = BLT(I, J)}
2926 @item @emph{Arguments}:
2927 @multitable @columnfractions .15 .70
2928 @item @var{I} @tab Shall be of @code{INTEGER} type.
2929 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2933 @item @emph{Return value}:
2934 The return value is of type @code{LOGICAL} and of the default kind.
2936 @item @emph{See also}:
2937 @ref{BGE}, @ref{BGT}, @ref{BLE}
2943 @section @code{BTEST} --- Bit test function
2949 @cindex bits, testing
2952 @item @emph{Description}:
2953 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
2954 in @var{I} is set. The counting of the bits starts at 0.
2956 @item @emph{Standard}:
2957 Fortran 95 and later, has overloads that are GNU extensions
2962 @item @emph{Syntax}:
2963 @code{RESULT = BTEST(I, POS)}
2965 @item @emph{Arguments}:
2966 @multitable @columnfractions .15 .70
2967 @item @var{I} @tab The type shall be @code{INTEGER}.
2968 @item @var{POS} @tab The type shall be @code{INTEGER}.
2971 @item @emph{Return value}:
2972 The return value is of type @code{LOGICAL}
2974 @item @emph{Example}:
2977 integer :: i = 32768 + 1024 + 64
2981 bool = btest(i, pos)
2984 end program test_btest
2987 @item @emph{Specific names}:
2988 @multitable @columnfractions .20 .20 .20 .25
2989 @item Name @tab Argument @tab Return type @tab Standard
2990 @item @code{BTEST(I,POS)} @tab @code{INTEGER I,POS} @tab @code{LOGICAL} @tab F95 and later
2991 @item @code{BBTEST(I,POS)} @tab @code{INTEGER(1) I,POS} @tab @code{LOGICAL(1)} @tab GNU extension
2992 @item @code{BITEST(I,POS)} @tab @code{INTEGER(2) I,POS} @tab @code{LOGICAL(2)} @tab GNU extension
2993 @item @code{BJTEST(I,POS)} @tab @code{INTEGER(4) I,POS} @tab @code{LOGICAL(4)} @tab GNU extension
2994 @item @code{BKTEST(I,POS)} @tab @code{INTEGER(8) I,POS} @tab @code{LOGICAL(8)} @tab GNU extension
2999 @section @code{C_ASSOCIATED} --- Status of a C pointer
3000 @fnindex C_ASSOCIATED
3001 @cindex association status, C pointer
3002 @cindex pointer, C association status
3005 @item @emph{Description}:
3006 @code{C_ASSOCIATED(c_ptr_1[, c_ptr_2])} determines the status of the C pointer
3007 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
3009 @item @emph{Standard}:
3010 Fortran 2003 and later
3015 @item @emph{Syntax}:
3016 @code{RESULT = C_ASSOCIATED(c_ptr_1[, c_ptr_2])}
3018 @item @emph{Arguments}:
3019 @multitable @columnfractions .15 .70
3020 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
3021 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
3024 @item @emph{Return value}:
3025 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
3026 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
3027 point to different addresses.
3029 @item @emph{Example}:
3031 subroutine association_test(a,b)
3032 use iso_c_binding, only: c_associated, c_loc, c_ptr
3036 if(c_associated(b, c_loc(a))) &
3037 stop 'b and a do not point to same target'
3038 end subroutine association_test
3041 @item @emph{See also}:
3042 @ref{C_LOC}, @ref{C_FUNLOC}
3047 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
3048 @fnindex C_F_POINTER
3049 @cindex pointer, convert C to Fortran
3052 @item @emph{Description}:
3053 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} assigns the target of the C pointer
3054 @var{CPTR} to the Fortran pointer @var{FPTR} and specifies its shape.
3056 @item @emph{Standard}:
3057 Fortran 2003 and later
3062 @item @emph{Syntax}:
3063 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
3065 @item @emph{Arguments}:
3066 @multitable @columnfractions .15 .70
3067 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
3069 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
3071 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
3072 with @code{INTENT(IN)}. It shall be present
3073 if and only if @var{fptr} is an array. The size
3074 must be equal to the rank of @var{fptr}.
3077 @item @emph{Example}:
3083 subroutine my_routine(p) bind(c,name='myC_func')
3085 type(c_ptr), intent(out) :: p
3089 real,pointer :: a(:)
3090 call my_routine(cptr)
3091 call c_f_pointer(cptr, a, [12])
3095 @item @emph{See also}:
3096 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
3100 @node C_F_PROCPOINTER
3101 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
3102 @fnindex C_F_PROCPOINTER
3103 @cindex pointer, C address of pointers
3106 @item @emph{Description}:
3107 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
3108 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
3110 @item @emph{Standard}:
3111 Fortran 2003 and later
3116 @item @emph{Syntax}:
3117 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
3119 @item @emph{Arguments}:
3120 @multitable @columnfractions .15 .70
3121 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
3123 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
3127 @item @emph{Example}:
3135 real(c_float), intent(in) :: a
3136 real(c_float) :: func
3140 function getIterFunc() bind(c,name="getIterFunc")
3142 type(c_funptr) :: getIterFunc
3145 type(c_funptr) :: cfunptr
3146 procedure(func), pointer :: myFunc
3147 cfunptr = getIterFunc()
3148 call c_f_procpointer(cfunptr, myFunc)
3152 @item @emph{See also}:
3153 @ref{C_LOC}, @ref{C_F_POINTER}
3158 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
3160 @cindex pointer, C address of procedures
3163 @item @emph{Description}:
3164 @code{C_FUNLOC(x)} determines the C address of the argument.
3166 @item @emph{Standard}:
3167 Fortran 2003 and later
3172 @item @emph{Syntax}:
3173 @code{RESULT = C_FUNLOC(x)}
3175 @item @emph{Arguments}:
3176 @multitable @columnfractions .15 .70
3177 @item @var{x} @tab Interoperable function or pointer to such function.
3180 @item @emph{Return value}:
3181 The return value is of type @code{C_FUNPTR} and contains the C address
3184 @item @emph{Example}:
3190 subroutine sub(a) bind(c)
3200 subroutine my_routine(p) bind(c,name='myC_func')
3202 type(c_funptr), intent(in) :: p
3205 call my_routine(c_funloc(sub))
3209 @item @emph{See also}:
3210 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
3215 @section @code{C_LOC} --- Obtain the C address of an object
3217 @cindex procedure pointer, convert C to Fortran
3220 @item @emph{Description}:
3221 @code{C_LOC(X)} determines the C address of the argument.
3223 @item @emph{Standard}:
3224 Fortran 2003 and later
3229 @item @emph{Syntax}:
3230 @code{RESULT = C_LOC(X)}
3232 @item @emph{Arguments}:
3233 @multitable @columnfractions .10 .75
3234 @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.
3238 @item @emph{Return value}:
3239 The return value is of type @code{C_PTR} and contains the C address
3242 @item @emph{Example}:
3244 subroutine association_test(a,b)
3245 use iso_c_binding, only: c_associated, c_loc, c_ptr
3249 if(c_associated(b, c_loc(a))) &
3250 stop 'b and a do not point to same target'
3251 end subroutine association_test
3254 @item @emph{See also}:
3255 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
3260 @section @code{C_SIZEOF} --- Size in bytes of an expression
3262 @cindex expression size
3263 @cindex size of an expression
3266 @item @emph{Description}:
3267 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
3268 expression @code{X} occupies.
3270 @item @emph{Standard}:
3274 Inquiry function of the module @code{ISO_C_BINDING}
3276 @item @emph{Syntax}:
3277 @code{N = C_SIZEOF(X)}
3279 @item @emph{Arguments}:
3280 @multitable @columnfractions .15 .70
3281 @item @var{X} @tab The argument shall be an interoperable data entity.
3284 @item @emph{Return value}:
3285 The return value is of type integer and of the system-dependent kind
3286 @code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the
3287 number of bytes occupied by the argument. If the argument has the
3288 @code{POINTER} attribute, the number of bytes of the storage area pointed
3289 to is returned. If the argument is of a derived type with @code{POINTER}
3290 or @code{ALLOCATABLE} components, the return value does not account for
3291 the sizes of the data pointed to by these components.
3293 @item @emph{Example}:
3297 real(c_float) :: r, s(5)
3298 print *, (c_sizeof(s)/c_sizeof(r) == 5)
3301 The example will print @code{.TRUE.} unless you are using a platform
3302 where default @code{REAL} variables are unusually padded.
3304 @item @emph{See also}:
3305 @ref{SIZEOF}, @ref{STORAGE_SIZE}
3310 @section @code{CEILING} --- Integer ceiling function
3313 @cindex rounding, ceiling
3316 @item @emph{Description}:
3317 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
3319 @item @emph{Standard}:
3320 Fortran 95 and later
3325 @item @emph{Syntax}:
3326 @code{RESULT = CEILING(A [, KIND])}
3328 @item @emph{Arguments}:
3329 @multitable @columnfractions .15 .70
3330 @item @var{A} @tab The type shall be @code{REAL}.
3331 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3332 expression indicating the kind parameter of the result.
3335 @item @emph{Return value}:
3336 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
3337 and a default-kind @code{INTEGER} otherwise.
3339 @item @emph{Example}:
3341 program test_ceiling
3344 print *, ceiling(x) ! returns 64
3345 print *, ceiling(y) ! returns -63
3346 end program test_ceiling
3349 @item @emph{See also}:
3350 @ref{FLOOR}, @ref{NINT}
3357 @section @code{CHAR} --- Character conversion function
3359 @cindex conversion, to character
3362 @item @emph{Description}:
3363 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
3365 @item @emph{Standard}:
3366 Fortran 77 and later
3371 @item @emph{Syntax}:
3372 @code{RESULT = CHAR(I [, KIND])}
3374 @item @emph{Arguments}:
3375 @multitable @columnfractions .15 .70
3376 @item @var{I} @tab The type shall be @code{INTEGER}.
3377 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3378 expression indicating the kind parameter of the result.
3381 @item @emph{Return value}:
3382 The return value is of type @code{CHARACTER(1)}
3384 @item @emph{Example}:
3390 print *, i, c ! returns 'J'
3391 end program test_char
3394 @item @emph{Specific names}:
3395 @multitable @columnfractions .20 .20 .20 .25
3396 @item Name @tab Argument @tab Return type @tab Standard
3397 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
3401 See @ref{ICHAR} for a discussion of converting between numerical values
3402 and formatted string representations.
3404 @item @emph{See also}:
3405 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
3412 @section @code{CHDIR} --- Change working directory
3414 @cindex system, working directory
3417 @item @emph{Description}:
3418 Change current working directory to a specified path.
3420 This intrinsic is provided in both subroutine and function forms; however,
3421 only one form can be used in any given program unit.
3423 @item @emph{Standard}:
3427 Subroutine, function
3429 @item @emph{Syntax}:
3430 @multitable @columnfractions .80
3431 @item @code{CALL CHDIR(NAME [, STATUS])}
3432 @item @code{STATUS = CHDIR(NAME)}
3435 @item @emph{Arguments}:
3436 @multitable @columnfractions .15 .70
3437 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
3438 kind and shall specify a valid path within the file system.
3439 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
3440 kind. Returns 0 on success, and a system specific and nonzero error code
3444 @item @emph{Example}:
3447 CHARACTER(len=255) :: path
3449 WRITE(*,*) TRIM(path)
3452 WRITE(*,*) TRIM(path)
3456 @item @emph{See also}:
3463 @section @code{CHMOD} --- Change access permissions of files
3465 @cindex file system, change access mode
3468 @item @emph{Description}:
3469 @code{CHMOD} changes the permissions of a file.
3471 This intrinsic is provided in both subroutine and function forms; however,
3472 only one form can be used in any given program unit.
3474 @item @emph{Standard}:
3478 Subroutine, function
3480 @item @emph{Syntax}:
3481 @multitable @columnfractions .80
3482 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
3483 @item @code{STATUS = CHMOD(NAME, MODE)}
3486 @item @emph{Arguments}:
3487 @multitable @columnfractions .15 .70
3489 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
3490 file name. Trailing blanks are ignored unless the character
3491 @code{achar(0)} is present, then all characters up to and excluding
3492 @code{achar(0)} are used as the file name.
3494 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
3495 file permission. @var{MODE} uses the same syntax as the @code{chmod} utility
3496 as defined by the POSIX standard. The argument shall either be a string of
3497 a nonnegative octal number or a symbolic mode.
3499 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
3500 @code{0} on success and nonzero otherwise.
3503 @item @emph{Return value}:
3504 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
3507 @item @emph{Example}:
3508 @code{CHMOD} as subroutine
3513 call chmod('test.dat','u+x',status)
3514 print *, 'Status: ', status
3515 end program chmod_test
3517 @code{CHMOD} as function:
3522 status = chmod('test.dat','u+x')
3523 print *, 'Status: ', status
3524 end program chmod_test
3532 @section @code{CMPLX} --- Complex conversion function
3534 @cindex complex numbers, conversion to
3535 @cindex conversion, to complex
3538 @item @emph{Description}:
3539 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
3540 the real component. If @var{Y} is present it is converted to the imaginary
3541 component. If @var{Y} is not present then the imaginary component is set to
3542 0.0. If @var{X} is complex then @var{Y} must not be present.
3544 @item @emph{Standard}:
3545 Fortran 77 and later
3550 @item @emph{Syntax}:
3551 @code{RESULT = CMPLX(X [, Y [, KIND]])}
3553 @item @emph{Arguments}:
3554 @multitable @columnfractions .15 .70
3555 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3557 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
3558 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
3559 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3560 expression indicating the kind parameter of the result.
3563 @item @emph{Return value}:
3564 The return value is of @code{COMPLEX} type, with a kind equal to
3565 @var{KIND} if it is specified. If @var{KIND} is not specified, the
3566 result is of the default @code{COMPLEX} kind, regardless of the kinds of
3567 @var{X} and @var{Y}.
3569 @item @emph{Example}:
3576 print *, z, cmplx(x)
3577 end program test_cmplx
3580 @item @emph{See also}:
3587 @section @code{CO_BROADCAST} --- Copy a value to all images the current set of images
3588 @fnindex CO_BROADCAST
3589 @cindex Collectives, value broadcasting
3592 @item @emph{Description}:
3593 @code{CO_BROADCAST} copies the value of argument @var{A} on the image with
3594 image index @code{SOURCE_IMAGE} to all images in the current team. @var{A}
3595 becomes defined as if by intrinsic assignment. If the execution was
3596 successful and @var{STAT} is present, it is assigned the value zero. If the
3597 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3598 @var{ERRMSG} gets assigned a value describing the occurred error.
3600 @item @emph{Standard}:
3601 Technical Specification (TS) 18508 or later
3604 Collective subroutine
3606 @item @emph{Syntax}:
3607 @code{CALL CO_BROADCAST(A, SOURCE_IMAGE [, STAT, ERRMSG])}
3609 @item @emph{Arguments}:
3610 @multitable @columnfractions .15 .70
3611 @item @var{A} @tab INTENT(INOUT) argument; shall have the same
3612 dynamic type and type paramters on all images of the current team. If it
3613 is an array, it shall have the same shape on all images.
3614 @item @var{SOURCE_IMAGE} @tab a scalar integer expression.
3615 It shall have the same the same value on all images and refer to an
3616 image of the current team.
3617 @item @var{STAT} @tab (optional) a scalar integer variable
3618 @item @var{ERRMSG} @tab (optional) a scalar character variable
3621 @item @emph{Example}:
3625 if (this_image() == 1) then
3628 call co_broadcast (val, source_image=1)
3629 print *, this_image, ":", val
3633 @item @emph{See also}:
3634 @ref{CO_MAX}, @ref{CO_MIN}, @ref{CO_SUM}, @ref{CO_REDUCE}
3640 @section @code{CO_MAX} --- Maximal value on the current set of images
3642 @cindex Collectives, maximal value
3645 @item @emph{Description}:
3646 @code{CO_MAX} determines element-wise the maximal value of @var{A} on all
3647 images of the current team. If @var{RESULT_IMAGE} is present, the maximum
3648 values are returned in @var{A} on the specified image only and the value
3649 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3650 not present, the value is returned on all images. If the execution was
3651 successful and @var{STAT} is present, it is assigned the value zero. If the
3652 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3653 @var{ERRMSG} gets assigned a value describing the occurred error.
3655 @item @emph{Standard}:
3656 Technical Specification (TS) 18508 or later
3659 Collective subroutine
3661 @item @emph{Syntax}:
3662 @code{CALL CO_MAX(A [, RESULT_IMAGE, STAT, ERRMSG])}
3664 @item @emph{Arguments}:
3665 @multitable @columnfractions .15 .70
3666 @item @var{A} @tab shall be an integer, real or character variable,
3667 which has the same type and type parameters on all images of the team.
3668 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3669 present, it shall have the same the same value on all images and refer to an
3670 image of the current team.
3671 @item @var{STAT} @tab (optional) a scalar integer variable
3672 @item @var{ERRMSG} @tab (optional) a scalar character variable
3675 @item @emph{Example}:
3680 call co_max (val, result_image=1)
3681 if (this_image() == 1) then
3682 write(*,*) "Maximal value", val ! prints num_images()
3687 @item @emph{See also}:
3688 @ref{CO_MIN}, @ref{CO_SUM}, @ref{CO_REDUCE}, @ref{CO_BROADCAST}
3694 @section @code{CO_MIN} --- Minimal value on the current set of images
3696 @cindex Collectives, minimal value
3699 @item @emph{Description}:
3700 @code{CO_MIN} determines element-wise the minimal value of @var{A} on all
3701 images of the current team. If @var{RESULT_IMAGE} is present, the minimal
3702 values are returned in @var{A} on the specified image only and the value
3703 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3704 not present, the value is returned on all images. If the execution was
3705 successful and @var{STAT} is present, it is assigned the value zero. If the
3706 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3707 @var{ERRMSG} gets assigned a value describing the occurred error.
3709 @item @emph{Standard}:
3710 Technical Specification (TS) 18508 or later
3713 Collective subroutine
3715 @item @emph{Syntax}:
3716 @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3718 @item @emph{Arguments}:
3719 @multitable @columnfractions .15 .70
3720 @item @var{A} @tab shall be an integer, real or character variable,
3721 which has the same type and type parameters on all images of the team.
3722 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3723 present, it shall have the same the same value on all images and refer to an
3724 image of the current team.
3725 @item @var{STAT} @tab (optional) a scalar integer variable
3726 @item @var{ERRMSG} @tab (optional) a scalar character variable
3729 @item @emph{Example}:
3734 call co_min (val, result_image=1)
3735 if (this_image() == 1) then
3736 write(*,*) "Minimal value", val ! prints 1
3741 @item @emph{See also}:
3742 @ref{CO_MAX}, @ref{CO_SUM}, @ref{CO_REDUCE}, @ref{CO_BROADCAST}
3748 @section @code{CO_REDUCE} --- Reduction of values on the current set of images
3750 @cindex Collectives, generic reduction
3753 @item @emph{Description}:
3754 @code{CO_REDUCE} determines element-wise the reduction of the value of @var{A}
3755 on all images of the current team. The pure function passed as @var{OPERATOR}
3756 is used to pairwise reduce the values of @var{A} by passing either the value
3757 of @var{A} of different images or the result values of such a reduction as
3758 argument. If @var{A} is an array, the deduction is done element wise. If
3759 @var{RESULT_IMAGE} is present, the result values are returned in @var{A} on
3760 the specified image only and the value of @var{A} on the other images become
3761 undefined. If @var{RESULT_IMAGE} is not present, the value is returned on all
3762 images. If the execution was successful and @var{STAT} is present, it is
3763 assigned the value zero. If the execution failed, @var{STAT} gets assigned
3764 a nonzero value and, if present, @var{ERRMSG} gets assigned a value describing
3767 @item @emph{Standard}:
3768 Technical Specification (TS) 18508 or later
3771 Collective subroutine
3773 @item @emph{Syntax}:
3774 @code{CALL CO_REDUCE(A, OPERATOR, [, RESULT_IMAGE, STAT, ERRMSG])}
3776 @item @emph{Arguments}:
3777 @multitable @columnfractions .15 .70
3778 @item @var{A} @tab is an @code{INTENT(INOUT)} argument and shall be
3779 nonpolymorphic. If it is allocatable, it shall be allocated; if it is a pointer,
3780 it shall be associated. @var{A} shall have the same type and type parameters on
3781 all images of the team; if it is an array, it shall have the same shape on all
3783 @item @var{OPERATOR} @tab pure function with two scalar nonallocatable
3784 arguments, which shall be nonpolymorphic and have the same type and type
3785 parameters as @var{A}. The function shall return a nonallocatable scalar of
3786 the same type and type parameters as @var{A}. The function shall be the same on
3787 all images and with regards to the arguments mathematically commutative and
3788 associative. Note that @var{OPERATOR} may not be an elemental function, unless
3789 it is an intrisic function.
3790 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3791 present, it shall have the same the same value on all images and refer to an
3792 image of the current team.
3793 @item @var{STAT} @tab (optional) a scalar integer variable
3794 @item @var{ERRMSG} @tab (optional) a scalar character variable
3797 @item @emph{Example}:
3802 call co_reduce (val, result_image=1, operator=myprod)
3803 if (this_image() == 1) then
3804 write(*,*) "Product value", val ! prints num_images() factorial
3807 pure function myprod(a, b)
3808 integer, value :: a, b
3816 While the rules permit in principle an intrinsic function, none of the
3817 intrinsics in the standard fulfill the criteria of having a specific
3818 function, which takes two arguments of the same type and returning that
3821 @item @emph{See also}:
3822 @ref{CO_MIN}, @ref{CO_MAX}, @ref{CO_SUM}, @ref{CO_BROADCAST}
3828 @section @code{CO_SUM} --- Sum of values on the current set of images
3830 @cindex Collectives, sum of values
3833 @item @emph{Description}:
3834 @code{CO_SUM} sums up the values of each element of @var{A} on all
3835 images of the current team. If @var{RESULT_IMAGE} is present, the summed-up
3836 values are returned in @var{A} on the specified image only and the value
3837 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3838 not present, the value is returned on all images. If the execution was
3839 successful and @var{STAT} is present, it is assigned the value zero. If the
3840 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3841 @var{ERRMSG} gets assigned a value describing the occurred error.
3843 @item @emph{Standard}:
3844 Technical Specification (TS) 18508 or later
3847 Collective subroutine
3849 @item @emph{Syntax}:
3850 @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3852 @item @emph{Arguments}:
3853 @multitable @columnfractions .15 .70
3854 @item @var{A} @tab shall be an integer, real or complex variable,
3855 which has the same type and type parameters on all images of the team.
3856 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3857 present, it shall have the same the same value on all images and refer to an
3858 image of the current team.
3859 @item @var{STAT} @tab (optional) a scalar integer variable
3860 @item @var{ERRMSG} @tab (optional) a scalar character variable
3863 @item @emph{Example}:
3868 call co_sum (val, result_image=1)
3869 if (this_image() == 1) then
3870 write(*,*) "The sum is ", val ! prints (n**2 + n)/2, with n = num_images()
3875 @item @emph{See also}:
3876 @ref{CO_MAX}, @ref{CO_MIN}, @ref{CO_REDUCE}, @ref{CO_BROADCAST}
3881 @node COMMAND_ARGUMENT_COUNT
3882 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
3883 @fnindex COMMAND_ARGUMENT_COUNT
3884 @cindex command-line arguments
3885 @cindex command-line arguments, number of
3886 @cindex arguments, to program
3889 @item @emph{Description}:
3890 @code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the
3891 command line when the containing program was invoked.
3893 @item @emph{Standard}:
3894 Fortran 2003 and later
3899 @item @emph{Syntax}:
3900 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
3902 @item @emph{Arguments}:
3903 @multitable @columnfractions .15 .70
3907 @item @emph{Return value}:
3908 The return value is an @code{INTEGER} of default kind.
3910 @item @emph{Example}:
3912 program test_command_argument_count
3914 count = command_argument_count()
3916 end program test_command_argument_count
3919 @item @emph{See also}:
3920 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
3925 @node COMPILER_OPTIONS
3926 @section @code{COMPILER_OPTIONS} --- Options passed to the compiler
3927 @fnindex COMPILER_OPTIONS
3928 @cindex flags inquiry function
3929 @cindex options inquiry function
3930 @cindex compiler flags inquiry function
3933 @item @emph{Description}:
3934 @code{COMPILER_OPTIONS} returns a string with the options used for
3937 @item @emph{Standard}:
3941 Inquiry function of the module @code{ISO_FORTRAN_ENV}
3943 @item @emph{Syntax}:
3944 @code{STR = COMPILER_OPTIONS()}
3946 @item @emph{Arguments}:
3949 @item @emph{Return value}:
3950 The return value is a default-kind string with system-dependent length.
3951 It contains the compiler flags used to compile the file, which called
3952 the @code{COMPILER_OPTIONS} intrinsic.
3954 @item @emph{Example}:
3957 print '(4a)', 'This file was compiled by ', &
3958 compiler_version(), ' using the options ', &
3963 @item @emph{See also}:
3964 @ref{COMPILER_VERSION}, @ref{ISO_FORTRAN_ENV}
3969 @node COMPILER_VERSION
3970 @section @code{COMPILER_VERSION} --- Compiler version string
3971 @fnindex COMPILER_VERSION
3972 @cindex compiler, name and version
3973 @cindex version of the compiler
3976 @item @emph{Description}:
3977 @code{COMPILER_VERSION} returns a string with the name and the
3978 version of the compiler.
3980 @item @emph{Standard}:
3984 Inquiry function of the module @code{ISO_FORTRAN_ENV}
3986 @item @emph{Syntax}:
3987 @code{STR = COMPILER_VERSION()}
3989 @item @emph{Arguments}:
3992 @item @emph{Return value}:
3993 The return value is a default-kind string with system-dependent length.
3994 It contains the name of the compiler and its version number.
3996 @item @emph{Example}:
3999 print '(4a)', 'This file was compiled by ', &
4000 compiler_version(), ' using the options ', &
4005 @item @emph{See also}:
4006 @ref{COMPILER_OPTIONS}, @ref{ISO_FORTRAN_ENV}
4012 @section @code{COMPLEX} --- Complex conversion function
4014 @cindex complex numbers, conversion to
4015 @cindex conversion, to complex
4018 @item @emph{Description}:
4019 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
4020 to the real component and @var{Y} is converted to the imaginary
4023 @item @emph{Standard}:
4029 @item @emph{Syntax}:
4030 @code{RESULT = COMPLEX(X, Y)}
4032 @item @emph{Arguments}:
4033 @multitable @columnfractions .15 .70
4034 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
4035 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
4038 @item @emph{Return value}:
4039 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
4040 value is of default @code{COMPLEX} type.
4042 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
4043 type and one is of @code{INTEGER} type, then the return value is of
4044 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
4045 argument with the highest precision.
4047 @item @emph{Example}:
4049 program test_complex
4052 print *, complex(i, x)
4053 end program test_complex
4056 @item @emph{See also}:
4063 @section @code{CONJG} --- Complex conjugate function
4066 @cindex complex conjugate
4069 @item @emph{Description}:
4070 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
4071 then the result is @code{(x, -y)}
4073 @item @emph{Standard}:
4074 Fortran 77 and later, has overloads that are GNU extensions
4079 @item @emph{Syntax}:
4082 @item @emph{Arguments}:
4083 @multitable @columnfractions .15 .70
4084 @item @var{Z} @tab The type shall be @code{COMPLEX}.
4087 @item @emph{Return value}:
4088 The return value is of type @code{COMPLEX}.
4090 @item @emph{Example}:
4093 complex :: z = (2.0, 3.0)
4094 complex(8) :: dz = (2.71_8, -3.14_8)
4099 end program test_conjg
4102 @item @emph{Specific names}:
4103 @multitable @columnfractions .20 .20 .20 .25
4104 @item Name @tab Argument @tab Return type @tab Standard
4105 @item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension
4106 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
4113 @section @code{COS} --- Cosine function
4119 @cindex trigonometric function, cosine
4123 @item @emph{Description}:
4124 @code{COS(X)} computes the cosine of @var{X}.
4126 @item @emph{Standard}:
4127 Fortran 77 and later, has overloads that are GNU extensions
4132 @item @emph{Syntax}:
4133 @code{RESULT = COS(X)}
4135 @item @emph{Arguments}:
4136 @multitable @columnfractions .15 .70
4137 @item @var{X} @tab The type shall be @code{REAL} or
4141 @item @emph{Return value}:
4142 The return value is of the same type and kind as @var{X}. The real part
4143 of the result is in radians. If @var{X} is of the type @code{REAL},
4144 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
4146 @item @emph{Example}:
4151 end program test_cos
4154 @item @emph{Specific names}:
4155 @multitable @columnfractions .20 .20 .20 .25
4156 @item Name @tab Argument @tab Return type @tab Standard
4157 @item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
4158 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
4159 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
4160 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4161 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4164 @item @emph{See also}:
4165 Inverse function: @ref{ACOS}
4166 Degrees function: @ref{COSD}
4173 @section @code{COSD} --- Cosine function, degrees
4179 @cindex trigonometric function, cosine, degrees
4180 @cindex cosine, degrees
4183 @item @emph{Description}:
4184 @code{COSD(X)} computes the cosine of @var{X} in degrees.
4186 This function is for compatibility only and should be avoided in favor of
4187 standard constructs wherever possible.
4189 @item @emph{Standard}:
4190 GNU Extension, enabled with @option{-fdec-math}.
4195 @item @emph{Syntax}:
4196 @code{RESULT = COSD(X)}
4198 @item @emph{Arguments}:
4199 @multitable @columnfractions .15 .70
4200 @item @var{X} @tab The type shall be @code{REAL} or
4204 @item @emph{Return value}:
4205 The return value is of the same type and kind as @var{X}. The real part
4206 of the result is in degrees. If @var{X} is of the type @code{REAL},
4207 the return value lies in the range @math{ -1 \leq \cosd (x) \leq 1}.
4209 @item @emph{Example}:
4214 end program test_cosd
4217 @item @emph{Specific names}:
4218 @multitable @columnfractions .20 .20 .20 .25
4219 @item Name @tab Argument @tab Return type @tab Standard
4220 @item @code{COSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4221 @item @code{DCOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4222 @item @code{CCOSD(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU Extension
4223 @item @code{ZCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4224 @item @code{CDCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4227 @item @emph{See also}:
4228 Inverse function: @ref{ACOSD}
4229 Radians function: @ref{COS}
4236 @section @code{COSH} --- Hyperbolic cosine function
4239 @cindex hyperbolic cosine
4240 @cindex hyperbolic function, cosine
4241 @cindex cosine, hyperbolic
4244 @item @emph{Description}:
4245 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
4247 @item @emph{Standard}:
4248 Fortran 77 and later, for a complex argument Fortran 2008 or later
4253 @item @emph{Syntax}:
4256 @item @emph{Arguments}:
4257 @multitable @columnfractions .15 .70
4258 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4261 @item @emph{Return value}:
4262 The return value has same type and kind as @var{X}. If @var{X} is
4263 complex, the imaginary part of the result is in radians. If @var{X}
4264 is @code{REAL}, the return value has a lower bound of one,
4265 @math{\cosh (x) \geq 1}.
4267 @item @emph{Example}:
4270 real(8) :: x = 1.0_8
4272 end program test_cosh
4275 @item @emph{Specific names}:
4276 @multitable @columnfractions .20 .20 .20 .25
4277 @item Name @tab Argument @tab Return type @tab Standard
4278 @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
4279 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
4282 @item @emph{See also}:
4283 Inverse function: @ref{ACOSH}
4290 @section @code{COTAN} --- Cotangent function
4293 @cindex trigonometric function, cotangent
4297 @item @emph{Description}:
4298 @code{COTAN(X)} computes the cotangent of @var{X}. Equivalent to @code{COS(x)}
4299 divided by @code{SIN(x)}, or @code{1 / TAN(x)}.
4301 This function is for compatibility only and should be avoided in favor of
4302 standard constructs wherever possible.
4304 @item @emph{Standard}:
4305 GNU Extension, enabled with @option{-fdec-math}.
4310 @item @emph{Syntax}:
4311 @code{RESULT = COTAN(X)}
4313 @item @emph{Arguments}:
4314 @multitable @columnfractions .15 .70
4315 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4318 @item @emph{Return value}:
4319 The return value has same type and kind as @var{X}, and its value is in radians.
4321 @item @emph{Example}:
4324 real(8) :: x = 0.165_8
4326 end program test_cotan
4329 @item @emph{Specific names}:
4330 @multitable @columnfractions .20 .20 .20 .25
4331 @item Name @tab Argument @tab Return type @tab Standard
4332 @item @code{COTAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4333 @item @code{DCOTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4336 @item @emph{See also}:
4337 Converse function: @ref{TAN}
4338 Degrees function: @ref{COTAND}
4344 @section @code{COTAND} --- Cotangent function, degrees
4347 @cindex trigonometric function, cotangent, degrees
4348 @cindex cotangent, degrees
4351 @item @emph{Description}:
4352 @code{COTAND(X)} computes the cotangent of @var{X} in degrees. Equivalent to
4353 @code{COSD(x)} divided by @code{SIND(x)}, or @code{1 / TAND(x)}.
4355 @item @emph{Standard}:
4356 GNU Extension, enabled with @option{-fdec-math}.
4358 This function is for compatibility only and should be avoided in favor of
4359 standard constructs wherever possible.
4364 @item @emph{Syntax}:
4365 @code{RESULT = COTAND(X)}
4367 @item @emph{Arguments}:
4368 @multitable @columnfractions .15 .70
4369 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4372 @item @emph{Return value}:
4373 The return value has same type and kind as @var{X}, and its value is in degrees.
4375 @item @emph{Example}:
4378 real(8) :: x = 0.165_8
4380 end program test_cotand
4383 @item @emph{Specific names}:
4384 @multitable @columnfractions .20 .20 .20 .25
4385 @item Name @tab Argument @tab Return type @tab Standard
4386 @item @code{COTAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4387 @item @code{DCOTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4390 @item @emph{See also}:
4391 Converse function: @ref{TAND}
4392 Radians function: @ref{COTAN}
4399 @section @code{COUNT} --- Count function
4401 @cindex array, conditionally count elements
4402 @cindex array, element counting
4403 @cindex array, number of elements
4406 @item @emph{Description}:
4408 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
4409 or, if the @var{DIM} argument is supplied, counts the number of
4410 elements along each row of the array in the @var{DIM} direction.
4411 If the array has zero size, or all of the elements of @var{MASK} are
4412 @code{.FALSE.}, then the result is @code{0}.
4414 @item @emph{Standard}:
4415 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
4418 Transformational function
4420 @item @emph{Syntax}:
4421 @code{RESULT = COUNT(MASK [, DIM, KIND])}
4423 @item @emph{Arguments}:
4424 @multitable @columnfractions .15 .70
4425 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
4426 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
4427 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4428 expression indicating the kind parameter of the result.
4431 @item @emph{Return value}:
4432 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
4433 @var{KIND} is absent, the return value is of default integer kind.
4434 If @var{DIM} is present, the result is an array with a rank one less
4435 than the rank of @var{ARRAY}, and a size corresponding to the shape
4436 of @var{ARRAY} with the @var{DIM} dimension removed.
4438 @item @emph{Example}:
4441 integer, dimension(2,3) :: a, b
4442 logical, dimension(2,3) :: mask
4443 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
4444 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
4445 print '(3i3)', a(1,:)
4446 print '(3i3)', a(2,:)
4448 print '(3i3)', b(1,:)
4449 print '(3i3)', b(2,:)
4452 print '(3l3)', mask(1,:)
4453 print '(3l3)', mask(2,:)
4455 print '(3i3)', count(mask)
4457 print '(3i3)', count(mask, 1)
4459 print '(3i3)', count(mask, 2)
4460 end program test_count
4467 @section @code{CPU_TIME} --- CPU elapsed time in seconds
4469 @cindex time, elapsed
4472 @item @emph{Description}:
4473 Returns a @code{REAL} value representing the elapsed CPU time in
4474 seconds. This is useful for testing segments of code to determine
4477 If a time source is available, time will be reported with microsecond
4478 resolution. If no time source is available, @var{TIME} is set to
4481 Note that @var{TIME} may contain a, system dependent, arbitrary offset
4482 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
4483 value is meaningless, only differences between subsequent calls to
4484 this subroutine, as shown in the example below, should be used.
4487 @item @emph{Standard}:
4488 Fortran 95 and later
4493 @item @emph{Syntax}:
4494 @code{CALL CPU_TIME(TIME)}
4496 @item @emph{Arguments}:
4497 @multitable @columnfractions .15 .70
4498 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
4501 @item @emph{Return value}:
4504 @item @emph{Example}:
4506 program test_cpu_time
4507 real :: start, finish
4508 call cpu_time(start)
4509 ! put code to test here
4510 call cpu_time(finish)
4511 print '("Time = ",f6.3," seconds.")',finish-start
4512 end program test_cpu_time
4515 @item @emph{See also}:
4516 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
4522 @section @code{CSHIFT} --- Circular shift elements of an array
4524 @cindex array, shift circularly
4525 @cindex array, permutation
4526 @cindex array, rotate
4529 @item @emph{Description}:
4530 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
4531 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
4532 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
4533 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
4534 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
4535 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
4536 sections of @var{ARRAY} along the given dimension are shifted. Elements
4537 shifted out one end of each rank one section are shifted back in the other end.
4539 @item @emph{Standard}:
4540 Fortran 95 and later
4543 Transformational function
4545 @item @emph{Syntax}:
4546 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
4548 @item @emph{Arguments}:
4549 @multitable @columnfractions .15 .70
4550 @item @var{ARRAY} @tab Shall be an array of any type.
4551 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
4552 @item @var{DIM} @tab The type shall be @code{INTEGER}.
4555 @item @emph{Return value}:
4556 Returns an array of same type and rank as the @var{ARRAY} argument.
4558 @item @emph{Example}:
4561 integer, dimension(3,3) :: a
4562 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
4563 print '(3i3)', a(1,:)
4564 print '(3i3)', a(2,:)
4565 print '(3i3)', a(3,:)
4566 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
4568 print '(3i3)', a(1,:)
4569 print '(3i3)', a(2,:)
4570 print '(3i3)', a(3,:)
4571 end program test_cshift
4578 @section @code{CTIME} --- Convert a time into a string
4580 @cindex time, conversion to string
4581 @cindex conversion, to string
4584 @item @emph{Description}:
4585 @code{CTIME} converts a system time value, such as returned by
4586 @ref{TIME8}, to a string. The output will be of the form @samp{Sat
4587 Aug 19 18:13:14 1995}.
4589 This intrinsic is provided in both subroutine and function forms; however,
4590 only one form can be used in any given program unit.
4592 @item @emph{Standard}:
4596 Subroutine, function
4598 @item @emph{Syntax}:
4599 @multitable @columnfractions .80
4600 @item @code{CALL CTIME(TIME, RESULT)}.
4601 @item @code{RESULT = CTIME(TIME)}.
4604 @item @emph{Arguments}:
4605 @multitable @columnfractions .15 .70
4606 @item @var{TIME} @tab The type shall be of type @code{INTEGER}.
4607 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
4608 of default kind. It is an @code{INTENT(OUT)} argument. If the length
4609 of this variable is too short for the time and date string to fit
4610 completely, it will be blank on procedure return.
4613 @item @emph{Return value}:
4614 The converted date and time as a string.
4616 @item @emph{Example}:
4620 character(len=30) :: date
4623 ! Do something, main part of the program
4626 print *, 'Program was started on ', date
4627 end program test_ctime
4630 @item @emph{See Also}:
4631 @ref{DATE_AND_TIME}, @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
4637 @section @code{DATE_AND_TIME} --- Date and time subroutine
4638 @fnindex DATE_AND_TIME
4639 @cindex date, current
4640 @cindex current date
4641 @cindex time, current
4642 @cindex current time
4645 @item @emph{Description}:
4646 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
4647 time information from the real-time system clock. @var{DATE} is
4648 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
4649 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
4650 representing the difference with respect to Coordinated Universal Time (UTC).
4651 Unavailable time and date parameters return blanks.
4653 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
4655 @multitable @columnfractions .15 .30 .40
4656 @item @tab @code{VALUE(1)}: @tab The year
4657 @item @tab @code{VALUE(2)}: @tab The month
4658 @item @tab @code{VALUE(3)}: @tab The day of the month
4659 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
4660 @item @tab @code{VALUE(5)}: @tab The hour of the day
4661 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
4662 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
4663 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
4666 @item @emph{Standard}:
4667 Fortran 95 and later
4672 @item @emph{Syntax}:
4673 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
4675 @item @emph{Arguments}:
4676 @multitable @columnfractions .15 .70
4677 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
4678 or larger, and of default kind.
4679 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
4680 or larger, and of default kind.
4681 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
4682 or larger, and of default kind.
4683 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
4686 @item @emph{Return value}:
4689 @item @emph{Example}:
4691 program test_time_and_date
4692 character(8) :: date
4693 character(10) :: time
4694 character(5) :: zone
4695 integer,dimension(8) :: values
4696 ! using keyword arguments
4697 call date_and_time(date,time,zone,values)
4698 call date_and_time(DATE=date,ZONE=zone)
4699 call date_and_time(TIME=time)
4700 call date_and_time(VALUES=values)
4701 print '(a,2x,a,2x,a)', date, time, zone
4702 print '(8i5)', values
4703 end program test_time_and_date
4706 @item @emph{See also}:
4707 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
4713 @section @code{DBLE} --- Double conversion function
4715 @cindex conversion, to real
4718 @item @emph{Description}:
4719 @code{DBLE(A)} Converts @var{A} to double precision real type.
4721 @item @emph{Standard}:
4722 Fortran 77 and later
4727 @item @emph{Syntax}:
4728 @code{RESULT = DBLE(A)}
4730 @item @emph{Arguments}:
4731 @multitable @columnfractions .15 .70
4732 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
4736 @item @emph{Return value}:
4737 The return value is of type double precision real.
4739 @item @emph{Example}:
4744 complex :: z = (2.3,1.14)
4745 print *, dble(x), dble(i), dble(z)
4746 end program test_dble
4749 @item @emph{See also}:
4756 @section @code{DCMPLX} --- Double complex conversion function
4758 @cindex complex numbers, conversion to
4759 @cindex conversion, to complex
4762 @item @emph{Description}:
4763 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
4764 converted to the real component. If @var{Y} is present it is converted to the
4765 imaginary component. If @var{Y} is not present then the imaginary component is
4766 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
4768 @item @emph{Standard}:
4774 @item @emph{Syntax}:
4775 @code{RESULT = DCMPLX(X [, Y])}
4777 @item @emph{Arguments}:
4778 @multitable @columnfractions .15 .70
4779 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
4781 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
4782 @code{INTEGER} or @code{REAL}.
4785 @item @emph{Return value}:
4786 The return value is of type @code{COMPLEX(8)}
4788 @item @emph{Example}:
4798 print *, dcmplx(x,i)
4799 end program test_dcmplx
4805 @section @code{DIGITS} --- Significant binary digits function
4807 @cindex model representation, significant digits
4810 @item @emph{Description}:
4811 @code{DIGITS(X)} returns the number of significant binary digits of the internal
4812 model representation of @var{X}. For example, on a system using a 32-bit
4813 floating point representation, a default real number would likely return 24.
4815 @item @emph{Standard}:
4816 Fortran 95 and later
4821 @item @emph{Syntax}:
4822 @code{RESULT = DIGITS(X)}
4824 @item @emph{Arguments}:
4825 @multitable @columnfractions .15 .70
4826 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
4829 @item @emph{Return value}:
4830 The return value is of type @code{INTEGER}.
4832 @item @emph{Example}:
4835 integer :: i = 12345
4841 end program test_digits
4848 @section @code{DIM} --- Positive difference
4852 @cindex positive difference
4855 @item @emph{Description}:
4856 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
4857 otherwise returns zero.
4859 @item @emph{Standard}:
4860 Fortran 77 and later
4865 @item @emph{Syntax}:
4866 @code{RESULT = DIM(X, Y)}
4868 @item @emph{Arguments}:
4869 @multitable @columnfractions .15 .70
4870 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
4871 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
4874 @item @emph{Return value}:
4875 The return value is of type @code{INTEGER} or @code{REAL}.
4877 @item @emph{Example}:
4883 x = dim(4.345_8, 2.111_8)
4886 end program test_dim
4889 @item @emph{Specific names}:
4890 @multitable @columnfractions .20 .20 .20 .25
4891 @item Name @tab Argument @tab Return type @tab Standard
4892 @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
4893 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
4894 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
4901 @section @code{DOT_PRODUCT} --- Dot product function
4902 @fnindex DOT_PRODUCT
4904 @cindex vector product
4905 @cindex product, vector
4908 @item @emph{Description}:
4909 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
4910 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
4911 either numeric or logical and must be arrays of rank one and of equal size. If
4912 the vectors are @code{INTEGER} or @code{REAL}, the result is
4913 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
4914 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
4915 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
4917 @item @emph{Standard}:
4918 Fortran 95 and later
4921 Transformational function
4923 @item @emph{Syntax}:
4924 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
4926 @item @emph{Arguments}:
4927 @multitable @columnfractions .15 .70
4928 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
4929 @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.
4932 @item @emph{Return value}:
4933 If the arguments are numeric, the return value is a scalar of numeric type,
4934 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
4935 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
4937 @item @emph{Example}:
4939 program test_dot_prod
4940 integer, dimension(3) :: a, b
4947 print *, dot_product(a,b)
4948 end program test_dot_prod
4955 @section @code{DPROD} --- Double product function
4957 @cindex product, double-precision
4960 @item @emph{Description}:
4961 @code{DPROD(X,Y)} returns the product @code{X*Y}.
4963 @item @emph{Standard}:
4964 Fortran 77 and later
4969 @item @emph{Syntax}:
4970 @code{RESULT = DPROD(X, Y)}
4972 @item @emph{Arguments}:
4973 @multitable @columnfractions .15 .70
4974 @item @var{X} @tab The type shall be @code{REAL}.
4975 @item @var{Y} @tab The type shall be @code{REAL}.
4978 @item @emph{Return value}:
4979 The return value is of type @code{REAL(8)}.
4981 @item @emph{Example}:
4989 end program test_dprod
4992 @item @emph{Specific names}:
4993 @multitable @columnfractions .20 .20 .20 .25
4994 @item Name @tab Argument @tab Return type @tab Standard
4995 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
5002 @section @code{DREAL} --- Double real part function
5004 @cindex complex numbers, real part
5007 @item @emph{Description}:
5008 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
5010 @item @emph{Standard}:
5016 @item @emph{Syntax}:
5017 @code{RESULT = DREAL(A)}
5019 @item @emph{Arguments}:
5020 @multitable @columnfractions .15 .70
5021 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
5024 @item @emph{Return value}:
5025 The return value is of type @code{REAL(8)}.
5027 @item @emph{Example}:
5030 complex(8) :: z = (1.3_8,7.2_8)
5032 end program test_dreal
5035 @item @emph{See also}:
5043 @section @code{DSHIFTL} --- Combined left shift
5045 @cindex left shift, combined
5049 @item @emph{Description}:
5050 @code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
5051 rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
5052 bits of @var{J}, and the remaining bits are the rightmost bits of
5055 @item @emph{Standard}:
5056 Fortran 2008 and later
5061 @item @emph{Syntax}:
5062 @code{RESULT = DSHIFTL(I, J, SHIFT)}
5064 @item @emph{Arguments}:
5065 @multitable @columnfractions .15 .70
5066 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5067 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5068 If both @var{I} and @var{J} have integer type, then they shall have
5069 the same kind type parameter. @var{I} and @var{J} shall not both be
5071 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
5072 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
5073 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
5074 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
5077 @item @emph{Return value}:
5078 If either @var{I} or @var{J} is a BOZ constant, it is first converted
5079 as if by the intrinsic function @code{INT} to an integer type with the
5080 kind type parameter of the other.
5082 @item @emph{See also}:
5088 @section @code{DSHIFTR} --- Combined right shift
5090 @cindex right shift, combined
5091 @cindex shift, right
5094 @item @emph{Description}:
5095 @code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
5096 leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
5097 bits of @var{I}, and the remaining bits are the leftmost bits of
5100 @item @emph{Standard}:
5101 Fortran 2008 and later
5106 @item @emph{Syntax}:
5107 @code{RESULT = DSHIFTR(I, J, SHIFT)}
5109 @item @emph{Arguments}:
5110 @multitable @columnfractions .15 .70
5111 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5112 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5113 If both @var{I} and @var{J} have integer type, then they shall have
5114 the same kind type parameter. @var{I} and @var{J} shall not both be
5116 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
5117 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
5118 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
5119 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
5122 @item @emph{Return value}:
5123 If either @var{I} or @var{J} is a BOZ constant, it is first converted
5124 as if by the intrinsic function @code{INT} to an integer type with the
5125 kind type parameter of the other.
5127 @item @emph{See also}:
5133 @section @code{DTIME} --- Execution time subroutine (or function)
5135 @cindex time, elapsed
5136 @cindex elapsed time
5139 @item @emph{Description}:
5140 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
5141 since the start of the process's execution in @var{TIME}. @var{VALUES}
5142 returns the user and system components of this time in @code{VALUES(1)} and
5143 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
5146 Subsequent invocations of @code{DTIME} return values accumulated since the
5147 previous invocation.
5149 On some systems, the underlying timings are represented using types with
5150 sufficiently small limits that overflows (wrap around) are possible, such as
5151 32-bit types. Therefore, the values returned by this intrinsic might be, or
5152 become, negative, or numerically less than previous values, during a single
5153 run of the compiled program.
5155 Please note, that this implementation is thread safe if used within OpenMP
5156 directives, i.e., its state will be consistent while called from multiple
5157 threads. However, if @code{DTIME} is called from multiple threads, the result
5158 is still the time since the last invocation. This may not give the intended
5159 results. If possible, use @code{CPU_TIME} instead.
5161 This intrinsic is provided in both subroutine and function forms; however,
5162 only one form can be used in any given program unit.
5164 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
5166 @multitable @columnfractions .15 .30 .40
5167 @item @tab @code{VALUES(1)}: @tab User time in seconds.
5168 @item @tab @code{VALUES(2)}: @tab System time in seconds.
5169 @item @tab @code{TIME}: @tab Run time since start in seconds.
5172 @item @emph{Standard}:
5176 Subroutine, function
5178 @item @emph{Syntax}:
5179 @multitable @columnfractions .80
5180 @item @code{CALL DTIME(VALUES, TIME)}.
5181 @item @code{TIME = DTIME(VALUES)}, (not recommended).
5184 @item @emph{Arguments}:
5185 @multitable @columnfractions .15 .70
5186 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
5187 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
5190 @item @emph{Return value}:
5191 Elapsed time in seconds since the last invocation or since the start of program
5192 execution if not called before.
5194 @item @emph{Example}:
5198 real, dimension(2) :: tarray
5200 call dtime(tarray, result)
5204 do i=1,100000000 ! Just a delay
5207 call dtime(tarray, result)
5211 end program test_dtime
5214 @item @emph{See also}:
5222 @section @code{EOSHIFT} --- End-off shift elements of an array
5224 @cindex array, shift
5227 @item @emph{Description}:
5228 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
5229 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
5230 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
5231 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
5232 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
5233 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
5234 then all complete rank one sections of @var{ARRAY} along the given dimension are
5235 shifted. Elements shifted out one end of each rank one section are dropped. If
5236 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
5237 is copied back in the other end. If @var{BOUNDARY} is not present then the
5238 following are copied in depending on the type of @var{ARRAY}.
5240 @multitable @columnfractions .15 .80
5241 @item @emph{Array Type} @tab @emph{Boundary Value}
5242 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
5243 @item Logical @tab @code{.FALSE.}.
5244 @item Character(@var{len}) @tab @var{len} blanks.
5247 @item @emph{Standard}:
5248 Fortran 95 and later
5251 Transformational function
5253 @item @emph{Syntax}:
5254 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
5256 @item @emph{Arguments}:
5257 @multitable @columnfractions .15 .70
5258 @item @var{ARRAY} @tab May be any type, not scalar.
5259 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
5260 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
5261 @item @var{DIM} @tab The type shall be @code{INTEGER}.
5264 @item @emph{Return value}:
5265 Returns an array of same type and rank as the @var{ARRAY} argument.
5267 @item @emph{Example}:
5269 program test_eoshift
5270 integer, dimension(3,3) :: a
5271 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
5272 print '(3i3)', a(1,:)
5273 print '(3i3)', a(2,:)
5274 print '(3i3)', a(3,:)
5275 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
5277 print '(3i3)', a(1,:)
5278 print '(3i3)', a(2,:)
5279 print '(3i3)', a(3,:)
5280 end program test_eoshift
5287 @section @code{EPSILON} --- Epsilon function
5289 @cindex model representation, epsilon
5292 @item @emph{Description}:
5293 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
5294 as @var{X} such that @math{1 + E > 1}.
5296 @item @emph{Standard}:
5297 Fortran 95 and later
5302 @item @emph{Syntax}:
5303 @code{RESULT = EPSILON(X)}
5305 @item @emph{Arguments}:
5306 @multitable @columnfractions .15 .70
5307 @item @var{X} @tab The type shall be @code{REAL}.
5310 @item @emph{Return value}:
5311 The return value is of same type as the argument.
5313 @item @emph{Example}:
5315 program test_epsilon
5320 end program test_epsilon
5327 @section @code{ERF} --- Error function
5329 @cindex error function
5332 @item @emph{Description}:
5333 @code{ERF(X)} computes the error function of @var{X}.
5335 @item @emph{Standard}:
5336 Fortran 2008 and later
5341 @item @emph{Syntax}:
5342 @code{RESULT = ERF(X)}
5344 @item @emph{Arguments}:
5345 @multitable @columnfractions .15 .70
5346 @item @var{X} @tab The type shall be @code{REAL}.
5349 @item @emph{Return value}:
5350 The return value is of type @code{REAL}, of the same kind as
5351 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
5353 @item @emph{Example}:
5356 real(8) :: x = 0.17_8
5358 end program test_erf
5361 @item @emph{Specific names}:
5362 @multitable @columnfractions .20 .20 .20 .25
5363 @item Name @tab Argument @tab Return type @tab Standard
5364 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
5371 @section @code{ERFC} --- Error function
5373 @cindex error function, complementary
5376 @item @emph{Description}:
5377 @code{ERFC(X)} computes the complementary error function of @var{X}.
5379 @item @emph{Standard}:
5380 Fortran 2008 and later
5385 @item @emph{Syntax}:
5386 @code{RESULT = ERFC(X)}
5388 @item @emph{Arguments}:
5389 @multitable @columnfractions .15 .70
5390 @item @var{X} @tab The type shall be @code{REAL}.
5393 @item @emph{Return value}:
5394 The return value is of type @code{REAL} and of the same kind as @var{X}.
5395 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
5397 @item @emph{Example}:
5400 real(8) :: x = 0.17_8
5402 end program test_erfc
5405 @item @emph{Specific names}:
5406 @multitable @columnfractions .20 .20 .20 .25
5407 @item Name @tab Argument @tab Return type @tab Standard
5408 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
5415 @section @code{ERFC_SCALED} --- Error function
5416 @fnindex ERFC_SCALED
5417 @cindex error function, complementary, exponentially-scaled
5420 @item @emph{Description}:
5421 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
5422 error function of @var{X}.
5424 @item @emph{Standard}:
5425 Fortran 2008 and later
5430 @item @emph{Syntax}:
5431 @code{RESULT = ERFC_SCALED(X)}
5433 @item @emph{Arguments}:
5434 @multitable @columnfractions .15 .70
5435 @item @var{X} @tab The type shall be @code{REAL}.
5438 @item @emph{Return value}:
5439 The return value is of type @code{REAL} and of the same kind as @var{X}.
5441 @item @emph{Example}:
5443 program test_erfc_scaled
5444 real(8) :: x = 0.17_8
5446 end program test_erfc_scaled
5453 @section @code{ETIME} --- Execution time subroutine (or function)
5455 @cindex time, elapsed
5458 @item @emph{Description}:
5459 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
5460 since the start of the process's execution in @var{TIME}. @var{VALUES}
5461 returns the user and system components of this time in @code{VALUES(1)} and
5462 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
5464 On some systems, the underlying timings are represented using types with
5465 sufficiently small limits that overflows (wrap around) are possible, such as
5466 32-bit types. Therefore, the values returned by this intrinsic might be, or
5467 become, negative, or numerically less than previous values, during a single
5468 run of the compiled program.
5470 This intrinsic is provided in both subroutine and function forms; however,
5471 only one form can be used in any given program unit.
5473 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
5475 @multitable @columnfractions .15 .30 .60
5476 @item @tab @code{VALUES(1)}: @tab User time in seconds.
5477 @item @tab @code{VALUES(2)}: @tab System time in seconds.
5478 @item @tab @code{TIME}: @tab Run time since start in seconds.
5481 @item @emph{Standard}:
5485 Subroutine, function
5487 @item @emph{Syntax}:
5488 @multitable @columnfractions .80
5489 @item @code{CALL ETIME(VALUES, TIME)}.
5490 @item @code{TIME = ETIME(VALUES)}, (not recommended).
5493 @item @emph{Arguments}:
5494 @multitable @columnfractions .15 .70
5495 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
5496 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
5499 @item @emph{Return value}:
5500 Elapsed time in seconds since the start of program execution.
5502 @item @emph{Example}:
5506 real, dimension(2) :: tarray
5508 call ETIME(tarray, result)
5512 do i=1,100000000 ! Just a delay
5515 call ETIME(tarray, result)
5519 end program test_etime
5522 @item @emph{See also}:
5530 @section @code{EVENT_QUERY} --- Query whether a coarray event has occurred
5531 @fnindex EVENT_QUERY
5532 @cindex Events, EVENT_QUERY
5535 @item @emph{Description}:
5536 @code{EVENT_QUERY} assignes the number of events to @var{COUNT} which have been
5537 posted to the @var{EVENT} variable and not yet been removed by calling
5538 @code{EVENT WAIT}. When @var{STAT} is present and the invocation was successful,
5539 it is assigned the value 0. If it is present and the invocation has failed,
5540 it is assigned a positive value and @var{COUNT} is assigned the value @math{-1}.
5542 @item @emph{Standard}:
5548 @item @emph{Syntax}:
5549 @code{CALL EVENT_QUERY (EVENT, COUNT [, STAT])}
5551 @item @emph{Arguments}:
5552 @multitable @columnfractions .15 .70
5553 @item @var{EVENT} @tab (intent(IN)) Scalar of type @code{EVENT_TYPE},
5554 defined in @code{ISO_FORTRAN_ENV}; shall not be coindexed.
5555 @item @var{COUNT} @tab (intent(out))Scalar integer with at least the
5556 precision of default integer.
5557 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
5560 @item @emph{Example}:
5565 type(event_type) :: event_value_has_been_set[*]
5567 if (this_image() == 1) then
5568 call event_query (event_value_has_been_set, cnt)
5569 if (cnt > 0) write(*,*) "Value has been set"
5570 elseif (this_image() == 2) then
5571 event post (event_value_has_been_set[1])
5580 @node EXECUTE_COMMAND_LINE
5581 @section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
5582 @fnindex EXECUTE_COMMAND_LINE
5583 @cindex system, system call
5584 @cindex command line
5587 @item @emph{Description}:
5588 @code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
5591 The @code{COMMAND} argument is passed to the shell and executed, using
5592 the C library's @code{system} call. (The shell is @code{sh} on Unix
5593 systems, and @code{cmd.exe} on Windows.) If @code{WAIT} is present
5594 and has the value false, the execution of the command is asynchronous
5595 if the system supports it; otherwise, the command is executed
5598 The three last arguments allow the user to get status information. After
5599 synchronous execution, @code{EXITSTAT} contains the integer exit code of
5600 the command, as returned by @code{system}. @code{CMDSTAT} is set to zero
5601 if the command line was executed (whatever its exit status was).
5602 @code{CMDMSG} is assigned an error message if an error has occurred.
5604 Note that the @code{system} function need not be thread-safe. It is
5605 the responsibility of the user to ensure that @code{system} is not
5606 called concurrently.
5608 @item @emph{Standard}:
5609 Fortran 2008 and later
5614 @item @emph{Syntax}:
5615 @code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
5617 @item @emph{Arguments}:
5618 @multitable @columnfractions .15 .70
5619 @item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
5620 @item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
5621 @item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5623 @item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5625 @item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
5629 @item @emph{Example}:
5634 call execute_command_line ("external_prog.exe", exitstat=i)
5635 print *, "Exit status of external_prog.exe was ", i
5637 call execute_command_line ("reindex_files.exe", wait=.false.)
5638 print *, "Now reindexing files in the background"
5640 end program test_exec
5646 Because this intrinsic is implemented in terms of the @code{system}
5647 function call, its behavior with respect to signaling is processor
5648 dependent. In particular, on POSIX-compliant systems, the SIGINT and
5649 SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
5650 such, if the parent process is terminated, the child process might not be
5651 terminated alongside.
5654 @item @emph{See also}:
5661 @section @code{EXIT} --- Exit the program with status.
5663 @cindex program termination
5664 @cindex terminate program
5667 @item @emph{Description}:
5668 @code{EXIT} causes immediate termination of the program with status. If status
5669 is omitted it returns the canonical @emph{success} for the system. All Fortran
5670 I/O units are closed.
5672 @item @emph{Standard}:
5678 @item @emph{Syntax}:
5679 @code{CALL EXIT([STATUS])}
5681 @item @emph{Arguments}:
5682 @multitable @columnfractions .15 .70
5683 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
5686 @item @emph{Return value}:
5687 @code{STATUS} is passed to the parent process on exit.
5689 @item @emph{Example}:
5692 integer :: STATUS = 0
5693 print *, 'This program is going to exit.'
5695 end program test_exit
5698 @item @emph{See also}:
5699 @ref{ABORT}, @ref{KILL}
5705 @section @code{EXP} --- Exponential function
5711 @cindex exponential function
5712 @cindex logarithm function, inverse
5715 @item @emph{Description}:
5716 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
5718 @item @emph{Standard}:
5719 Fortran 77 and later, has overloads that are GNU extensions
5724 @item @emph{Syntax}:
5725 @code{RESULT = EXP(X)}
5727 @item @emph{Arguments}:
5728 @multitable @columnfractions .15 .70
5729 @item @var{X} @tab The type shall be @code{REAL} or
5733 @item @emph{Return value}:
5734 The return value has same type and kind as @var{X}.
5736 @item @emph{Example}:
5741 end program test_exp
5744 @item @emph{Specific names}:
5745 @multitable @columnfractions .20 .20 .20 .25
5746 @item Name @tab Argument @tab Return type @tab Standard
5747 @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
5748 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
5749 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
5750 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5751 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5758 @section @code{EXPONENT} --- Exponent function
5760 @cindex real number, exponent
5761 @cindex floating point, exponent
5764 @item @emph{Description}:
5765 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
5766 is zero the value returned is zero.
5768 @item @emph{Standard}:
5769 Fortran 95 and later
5774 @item @emph{Syntax}:
5775 @code{RESULT = EXPONENT(X)}
5777 @item @emph{Arguments}:
5778 @multitable @columnfractions .15 .70
5779 @item @var{X} @tab The type shall be @code{REAL}.
5782 @item @emph{Return value}:
5783 The return value is of type default @code{INTEGER}.
5785 @item @emph{Example}:
5787 program test_exponent
5792 print *, exponent(0.0)
5793 end program test_exponent
5799 @node EXTENDS_TYPE_OF
5800 @section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension
5801 @fnindex EXTENDS_TYPE_OF
5804 @item @emph{Description}:
5805 Query dynamic type for extension.
5807 @item @emph{Standard}:
5808 Fortran 2003 and later
5813 @item @emph{Syntax}:
5814 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
5816 @item @emph{Arguments}:
5817 @multitable @columnfractions .15 .70
5818 @item @var{A} @tab Shall be an object of extensible declared type or
5819 unlimited polymorphic.
5820 @item @var{MOLD} @tab Shall be an object of extensible declared type or
5821 unlimited polymorphic.
5824 @item @emph{Return value}:
5825 The return value is a scalar of type default logical. It is true if and only if
5826 the dynamic type of A is an extension type of the dynamic type of MOLD.
5829 @item @emph{See also}:
5836 @section @code{FDATE} --- Get the current time as a string
5838 @cindex time, current
5839 @cindex current time
5840 @cindex date, current
5841 @cindex current date
5844 @item @emph{Description}:
5845 @code{FDATE(DATE)} returns the current date (using the same format as
5846 @ref{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
5849 This intrinsic is provided in both subroutine and function forms; however,
5850 only one form can be used in any given program unit.
5852 @item @emph{Standard}:
5856 Subroutine, function
5858 @item @emph{Syntax}:
5859 @multitable @columnfractions .80
5860 @item @code{CALL FDATE(DATE)}.
5861 @item @code{DATE = FDATE()}.
5864 @item @emph{Arguments}:
5865 @multitable @columnfractions .15 .70
5866 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
5867 default kind. It is an @code{INTENT(OUT)} argument. If the length of
5868 this variable is too short for the date and time string to fit
5869 completely, it will be blank on procedure return.
5872 @item @emph{Return value}:
5873 The current date and time as a string.
5875 @item @emph{Example}:
5879 character(len=30) :: date
5881 print *, 'Program started on ', date
5882 do i = 1, 100000000 ! Just a delay
5886 print *, 'Program ended on ', date
5887 end program test_fdate
5890 @item @emph{See also}:
5891 @ref{DATE_AND_TIME}, @ref{CTIME}
5896 @section @code{FGET} --- Read a single character in stream mode from stdin
5898 @cindex read character, stream mode
5899 @cindex stream mode, read character
5900 @cindex file operation, read character
5903 @item @emph{Description}:
5904 Read a single character in stream mode from stdin by bypassing normal
5905 formatted output. Stream I/O should not be mixed with normal record-oriented
5906 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
5908 This intrinsic is provided in both subroutine and function forms; however,
5909 only one form can be used in any given program unit.
5911 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
5912 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5913 Programmers should consider the use of new stream IO feature in new code
5914 for future portability. See also @ref{Fortran 2003 status}.
5916 @item @emph{Standard}:
5920 Subroutine, function
5922 @item @emph{Syntax}:
5923 @multitable @columnfractions .80
5924 @item @code{CALL FGET(C [, STATUS])}
5925 @item @code{STATUS = FGET(C)}
5928 @item @emph{Arguments}:
5929 @multitable @columnfractions .15 .70
5930 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5932 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5933 Returns 0 on success, -1 on end-of-file, and a system specific positive
5934 error code otherwise.
5937 @item @emph{Example}:
5940 INTEGER, PARAMETER :: strlen = 100
5941 INTEGER :: status, i = 1
5942 CHARACTER(len=strlen) :: str = ""
5944 WRITE (*,*) 'Enter text:'
5946 CALL fget(str(i:i), status)
5947 if (status /= 0 .OR. i > strlen) exit
5950 WRITE (*,*) TRIM(str)
5954 @item @emph{See also}:
5955 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
5961 @section @code{FGETC} --- Read a single character in stream mode
5963 @cindex read character, stream mode
5964 @cindex stream mode, read character
5965 @cindex file operation, read character
5968 @item @emph{Description}:
5969 Read a single character in stream mode by bypassing normal formatted output.
5970 Stream I/O should not be mixed with normal record-oriented (formatted or
5971 unformatted) I/O on the same unit; the results are unpredictable.
5973 This intrinsic is provided in both subroutine and function forms; however,
5974 only one form can be used in any given program unit.
5976 Note that the @code{FGET} intrinsic is provided for backwards compatibility
5977 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5978 Programmers should consider the use of new stream IO feature in new code
5979 for future portability. See also @ref{Fortran 2003 status}.
5981 @item @emph{Standard}:
5985 Subroutine, function
5987 @item @emph{Syntax}:
5988 @multitable @columnfractions .80
5989 @item @code{CALL FGETC(UNIT, C [, STATUS])}
5990 @item @code{STATUS = FGETC(UNIT, C)}
5993 @item @emph{Arguments}:
5994 @multitable @columnfractions .15 .70
5995 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
5996 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5998 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5999 Returns 0 on success, -1 on end-of-file and a system specific positive
6000 error code otherwise.
6003 @item @emph{Example}:
6006 INTEGER :: fd = 42, status
6009 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
6011 CALL fgetc(fd, c, status)
6012 IF (status /= 0) EXIT
6019 @item @emph{See also}:
6020 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
6026 @section @code{FLOOR} --- Integer floor function
6029 @cindex rounding, floor
6032 @item @emph{Description}:
6033 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
6035 @item @emph{Standard}:
6036 Fortran 95 and later
6041 @item @emph{Syntax}:
6042 @code{RESULT = FLOOR(A [, KIND])}
6044 @item @emph{Arguments}:
6045 @multitable @columnfractions .15 .70
6046 @item @var{A} @tab The type shall be @code{REAL}.
6047 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6048 expression indicating the kind parameter of the result.
6051 @item @emph{Return value}:
6052 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
6053 and of default-kind @code{INTEGER} otherwise.
6055 @item @emph{Example}:
6060 print *, floor(x) ! returns 63
6061 print *, floor(y) ! returns -64
6062 end program test_floor
6065 @item @emph{See also}:
6066 @ref{CEILING}, @ref{NINT}
6073 @section @code{FLUSH} --- Flush I/O unit(s)
6075 @cindex file operation, flush
6078 @item @emph{Description}:
6079 Flushes Fortran unit(s) currently open for output. Without the optional
6080 argument, all units are flushed, otherwise just the unit specified.
6082 @item @emph{Standard}:
6088 @item @emph{Syntax}:
6089 @code{CALL FLUSH(UNIT)}
6091 @item @emph{Arguments}:
6092 @multitable @columnfractions .15 .70
6093 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
6097 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
6098 statement that should be preferred over the @code{FLUSH} intrinsic.
6100 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
6101 have identical effect: they flush the runtime library's I/O buffer so
6102 that the data becomes visible to other processes. This does not guarantee
6103 that the data is committed to disk.
6105 On POSIX systems, you can request that all data is transferred to the
6106 storage device by calling the @code{fsync} function, with the POSIX file
6107 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
6108 @code{FNUM}). The following example shows how:
6111 ! Declare the interface for POSIX fsync function
6113 function fsync (fd) bind(c,name="fsync")
6114 use iso_c_binding, only: c_int
6115 integer(c_int), value :: fd
6116 integer(c_int) :: fsync
6120 ! Variable declaration
6124 open (10,file="foo")
6127 ! Perform I/O on unit 10
6132 ret = fsync(fnum(10))
6134 ! Handle possible error
6135 if (ret /= 0) stop "Error calling FSYNC"
6143 @section @code{FNUM} --- File number function
6145 @cindex file operation, file number
6148 @item @emph{Description}:
6149 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
6150 open Fortran I/O unit @code{UNIT}.
6152 @item @emph{Standard}:
6158 @item @emph{Syntax}:
6159 @code{RESULT = FNUM(UNIT)}
6161 @item @emph{Arguments}:
6162 @multitable @columnfractions .15 .70
6163 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
6166 @item @emph{Return value}:
6167 The return value is of type @code{INTEGER}
6169 @item @emph{Example}:
6173 open (unit=10, status = "scratch")
6177 end program test_fnum
6184 @section @code{FPUT} --- Write a single character in stream mode to stdout
6186 @cindex write character, stream mode
6187 @cindex stream mode, write character
6188 @cindex file operation, write character
6191 @item @emph{Description}:
6192 Write a single character in stream mode to stdout by bypassing normal
6193 formatted output. Stream I/O should not be mixed with normal record-oriented
6194 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
6196 This intrinsic is provided in both subroutine and function forms; however,
6197 only one form can be used in any given program unit.
6199 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
6200 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
6201 Programmers should consider the use of new stream IO feature in new code
6202 for future portability. See also @ref{Fortran 2003 status}.
6204 @item @emph{Standard}:
6208 Subroutine, function
6210 @item @emph{Syntax}:
6211 @multitable @columnfractions .80
6212 @item @code{CALL FPUT(C [, STATUS])}
6213 @item @code{STATUS = FPUT(C)}
6216 @item @emph{Arguments}:
6217 @multitable @columnfractions .15 .70
6218 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6220 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6221 Returns 0 on success, -1 on end-of-file and a system specific positive
6222 error code otherwise.
6225 @item @emph{Example}:
6228 CHARACTER(len=10) :: str = "gfortran"
6230 DO i = 1, len_trim(str)
6236 @item @emph{See also}:
6237 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
6243 @section @code{FPUTC} --- Write a single character in stream mode
6245 @cindex write character, stream mode
6246 @cindex stream mode, write character
6247 @cindex file operation, write character
6250 @item @emph{Description}:
6251 Write a single character in stream mode by bypassing normal formatted
6252 output. Stream I/O should not be mixed with normal record-oriented
6253 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
6255 This intrinsic is provided in both subroutine and function forms; however,
6256 only one form can be used in any given program unit.
6258 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
6259 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
6260 Programmers should consider the use of new stream IO feature in new code
6261 for future portability. See also @ref{Fortran 2003 status}.
6263 @item @emph{Standard}:
6267 Subroutine, function
6269 @item @emph{Syntax}:
6270 @multitable @columnfractions .80
6271 @item @code{CALL FPUTC(UNIT, C [, STATUS])}
6272 @item @code{STATUS = FPUTC(UNIT, C)}
6275 @item @emph{Arguments}:
6276 @multitable @columnfractions .15 .70
6277 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
6278 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6280 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6281 Returns 0 on success, -1 on end-of-file and a system specific positive
6282 error code otherwise.
6285 @item @emph{Example}:
6288 CHARACTER(len=10) :: str = "gfortran"
6289 INTEGER :: fd = 42, i
6291 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
6292 DO i = 1, len_trim(str)
6293 CALL fputc(fd, str(i:i))
6299 @item @emph{See also}:
6300 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
6306 @section @code{FRACTION} --- Fractional part of the model representation
6308 @cindex real number, fraction
6309 @cindex floating point, fraction
6312 @item @emph{Description}:
6313 @code{FRACTION(X)} returns the fractional part of the model
6314 representation of @code{X}.
6316 @item @emph{Standard}:
6317 Fortran 95 and later
6322 @item @emph{Syntax}:
6323 @code{Y = FRACTION(X)}
6325 @item @emph{Arguments}:
6326 @multitable @columnfractions .15 .70
6327 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
6330 @item @emph{Return value}:
6331 The return value is of the same type and kind as the argument.
6332 The fractional part of the model representation of @code{X} is returned;
6333 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
6335 @item @emph{Example}:
6337 program test_fraction
6340 print *, fraction(x), x * radix(x)**(-exponent(x))
6341 end program test_fraction
6349 @section @code{FREE} --- Frees memory
6351 @cindex pointer, cray
6354 @item @emph{Description}:
6355 Frees memory previously allocated by @code{MALLOC}. The @code{FREE}
6356 intrinsic is an extension intended to be used with Cray pointers, and is
6357 provided in GNU Fortran to allow user to compile legacy code. For
6358 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
6361 @item @emph{Standard}:
6367 @item @emph{Syntax}:
6368 @code{CALL FREE(PTR)}
6370 @item @emph{Arguments}:
6371 @multitable @columnfractions .15 .70
6372 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
6373 location of the memory that should be de-allocated.
6376 @item @emph{Return value}:
6379 @item @emph{Example}:
6380 See @code{MALLOC} for an example.
6382 @item @emph{See also}:
6389 @section @code{FSEEK} --- Low level file positioning subroutine
6391 @cindex file operation, seek
6392 @cindex file operation, position
6395 @item @emph{Description}:
6396 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
6397 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
6398 if set to 1, @var{OFFSET} is taken to be relative to the current position
6399 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
6400 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
6403 This intrinsic routine is not fully backwards compatible with @command{g77}.
6404 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
6405 @var{STATUS} variable. If FSEEK is used in old code, change
6407 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
6412 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
6413 IF (status /= 0) GOTO label
6416 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
6417 Programmers should consider the use of new stream IO feature in new code
6418 for future portability. See also @ref{Fortran 2003 status}.
6420 @item @emph{Standard}:
6426 @item @emph{Syntax}:
6427 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
6429 @item @emph{Arguments}:
6430 @multitable @columnfractions .15 .70
6431 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
6432 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
6433 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
6434 Its value shall be either 0, 1 or 2.
6435 @item @var{STATUS} @tab (Optional) shall be a scalar of type
6439 @item @emph{Example}:
6442 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
6443 INTEGER :: fd, offset, ierr
6449 OPEN(UNIT=fd, FILE="fseek.test")
6450 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
6451 print *, FTELL(fd), ierr
6453 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
6454 print *, FTELL(fd), ierr
6456 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
6457 print *, FTELL(fd), ierr
6463 @item @emph{See also}:
6470 @section @code{FSTAT} --- Get file status
6472 @cindex file system, file status
6475 @item @emph{Description}:
6476 @code{FSTAT} is identical to @ref{STAT}, except that information about an
6477 already opened file is obtained.
6479 The elements in @code{VALUES} are the same as described by @ref{STAT}.
6481 This intrinsic is provided in both subroutine and function forms; however,
6482 only one form can be used in any given program unit.
6484 @item @emph{Standard}:
6488 Subroutine, function
6490 @item @emph{Syntax}:
6491 @multitable @columnfractions .80
6492 @item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
6493 @item @code{STATUS = FSTAT(UNIT, VALUES)}
6496 @item @emph{Arguments}:
6497 @multitable @columnfractions .15 .70
6498 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
6499 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
6500 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
6501 on success and a system specific error code otherwise.
6504 @item @emph{Example}:
6505 See @ref{STAT} for an example.
6507 @item @emph{See also}:
6508 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
6514 @section @code{FTELL} --- Current stream position
6516 @cindex file operation, position
6519 @item @emph{Description}:
6520 Retrieves the current position within an open file.
6522 This intrinsic is provided in both subroutine and function forms; however,
6523 only one form can be used in any given program unit.
6525 @item @emph{Standard}:
6529 Subroutine, function
6531 @item @emph{Syntax}:
6532 @multitable @columnfractions .80
6533 @item @code{CALL FTELL(UNIT, OFFSET)}
6534 @item @code{OFFSET = FTELL(UNIT)}
6537 @item @emph{Arguments}:
6538 @multitable @columnfractions .15 .70
6539 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
6540 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
6543 @item @emph{Return value}:
6544 In either syntax, @var{OFFSET} is set to the current offset of unit
6545 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
6547 @item @emph{Example}:
6551 OPEN(10, FILE="temp.dat")
6557 @item @emph{See also}:
6564 @section @code{GAMMA} --- Gamma function
6567 @cindex Gamma function
6568 @cindex Factorial function
6571 @item @emph{Description}:
6572 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
6573 integer values of @var{X} the Gamma function simplifies to the factorial
6574 function @math{\Gamma(x)=(x-1)!}.
6578 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
6582 @item @emph{Standard}:
6583 Fortran 2008 and later
6588 @item @emph{Syntax}:
6591 @item @emph{Arguments}:
6592 @multitable @columnfractions .15 .70
6593 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
6594 nor a negative integer.
6597 @item @emph{Return value}:
6598 The return value is of type @code{REAL} of the same kind as @var{X}.
6600 @item @emph{Example}:
6604 x = gamma(x) ! returns 1.0
6605 end program test_gamma
6608 @item @emph{Specific names}:
6609 @multitable @columnfractions .20 .20 .20 .25
6610 @item Name @tab Argument @tab Return type @tab Standard
6611 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
6612 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
6615 @item @emph{See also}:
6616 Logarithm of the Gamma function: @ref{LOG_GAMMA}
6623 @section @code{GERROR} --- Get last system error message
6625 @cindex system, error handling
6628 @item @emph{Description}:
6629 Returns the system error message corresponding to the last system error.
6630 This resembles the functionality of @code{strerror(3)} in C.
6632 @item @emph{Standard}:
6638 @item @emph{Syntax}:
6639 @code{CALL GERROR(RESULT)}
6641 @item @emph{Arguments}:
6642 @multitable @columnfractions .15 .70
6643 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
6646 @item @emph{Example}:
6649 CHARACTER(len=100) :: msg
6655 @item @emph{See also}:
6656 @ref{IERRNO}, @ref{PERROR}
6662 @section @code{GETARG} --- Get command line arguments
6664 @cindex command-line arguments
6665 @cindex arguments, to program
6668 @item @emph{Description}:
6669 Retrieve the @var{POS}-th argument that was passed on the
6670 command line when the containing program was invoked.
6672 This intrinsic routine is provided for backwards compatibility with
6673 GNU Fortran 77. In new code, programmers should consider the use of
6674 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
6677 @item @emph{Standard}:
6683 @item @emph{Syntax}:
6684 @code{CALL GETARG(POS, VALUE)}
6686 @item @emph{Arguments}:
6687 @multitable @columnfractions .15 .70
6688 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
6689 the default integer kind; @math{@var{POS} \geq 0}
6690 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
6692 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
6695 @item @emph{Return value}:
6696 After @code{GETARG} returns, the @var{VALUE} argument holds the
6697 @var{POS}th command line argument. If @var{VALUE} can not hold the
6698 argument, it is truncated to fit the length of @var{VALUE}. If there are
6699 less than @var{POS} arguments specified at the command line, @var{VALUE}
6700 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
6701 to the name of the program (on systems that support this feature).
6703 @item @emph{Example}:
6707 CHARACTER(len=32) :: arg
6716 @item @emph{See also}:
6717 GNU Fortran 77 compatibility function: @ref{IARGC}
6719 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
6720 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6726 @section @code{GET_COMMAND} --- Get the entire command line
6727 @fnindex GET_COMMAND
6728 @cindex command-line arguments
6729 @cindex arguments, to program
6732 @item @emph{Description}:
6733 Retrieve the entire command line that was used to invoke the program.
6735 @item @emph{Standard}:
6736 Fortran 2003 and later
6741 @item @emph{Syntax}:
6742 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
6744 @item @emph{Arguments}:
6745 @multitable @columnfractions .15 .70
6746 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
6748 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
6750 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
6754 @item @emph{Return value}:
6755 If @var{COMMAND} is present, stores the entire command line that was used
6756 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
6757 assigned the length of the command line. If @var{STATUS} is present, it
6758 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
6759 short to store the command line, or a positive value in case of an error.
6761 @item @emph{Example}:
6763 PROGRAM test_get_command
6764 CHARACTER(len=255) :: cmd
6765 CALL get_command(cmd)
6766 WRITE (*,*) TRIM(cmd)
6770 @item @emph{See also}:
6771 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6776 @node GET_COMMAND_ARGUMENT
6777 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
6778 @fnindex GET_COMMAND_ARGUMENT
6779 @cindex command-line arguments
6780 @cindex arguments, to program
6783 @item @emph{Description}:
6784 Retrieve the @var{NUMBER}-th argument that was passed on the
6785 command line when the containing program was invoked.
6787 @item @emph{Standard}:
6788 Fortran 2003 and later
6793 @item @emph{Syntax}:
6794 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
6796 @item @emph{Arguments}:
6797 @multitable @columnfractions .15 .70
6798 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
6799 default kind, @math{@var{NUMBER} \geq 0}
6800 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
6801 and of default kind.
6802 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6803 and of default kind.
6804 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6805 and of default kind.
6808 @item @emph{Return value}:
6809 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
6810 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
6811 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
6812 arguments specified at the command line, @var{VALUE} will be filled with blanks.
6813 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
6814 systems that support this feature). The @var{LENGTH} argument contains the
6815 length of the @var{NUMBER}-th command line argument. If the argument retrieval
6816 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
6817 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
6820 @item @emph{Example}:
6822 PROGRAM test_get_command_argument
6824 CHARACTER(len=32) :: arg
6828 CALL get_command_argument(i, arg)
6829 IF (LEN_TRIM(arg) == 0) EXIT
6831 WRITE (*,*) TRIM(arg)
6837 @item @emph{See also}:
6838 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
6844 @section @code{GETCWD} --- Get current working directory
6846 @cindex system, working directory
6849 @item @emph{Description}:
6850 Get current working directory.
6852 This intrinsic is provided in both subroutine and function forms; however,
6853 only one form can be used in any given program unit.
6855 @item @emph{Standard}:
6859 Subroutine, function
6861 @item @emph{Syntax}:
6862 @multitable @columnfractions .80
6863 @item @code{CALL GETCWD(C [, STATUS])}
6864 @item @code{STATUS = GETCWD(C)}
6867 @item @emph{Arguments}:
6868 @multitable @columnfractions .15 .70
6869 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
6870 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
6871 a system specific and nonzero error code otherwise.
6874 @item @emph{Example}:
6877 CHARACTER(len=255) :: cwd
6879 WRITE(*,*) TRIM(cwd)
6883 @item @emph{See also}:
6890 @section @code{GETENV} --- Get an environmental variable
6892 @cindex environment variable
6895 @item @emph{Description}:
6896 Get the @var{VALUE} of the environmental variable @var{NAME}.
6898 This intrinsic routine is provided for backwards compatibility with
6899 GNU Fortran 77. In new code, programmers should consider the use of
6900 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
6903 Note that @code{GETENV} need not be thread-safe. It is the
6904 responsibility of the user to ensure that the environment is not being
6905 updated concurrently with a call to the @code{GETENV} intrinsic.
6907 @item @emph{Standard}:
6913 @item @emph{Syntax}:
6914 @code{CALL GETENV(NAME, VALUE)}
6916 @item @emph{Arguments}:
6917 @multitable @columnfractions .15 .70
6918 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
6919 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
6922 @item @emph{Return value}:
6923 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
6924 not large enough to hold the data, it is truncated. If @var{NAME}
6925 is not set, @var{VALUE} will be filled with blanks.
6927 @item @emph{Example}:
6930 CHARACTER(len=255) :: homedir
6931 CALL getenv("HOME", homedir)
6932 WRITE (*,*) TRIM(homedir)
6936 @item @emph{See also}:
6937 @ref{GET_ENVIRONMENT_VARIABLE}
6942 @node GET_ENVIRONMENT_VARIABLE
6943 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
6944 @fnindex GET_ENVIRONMENT_VARIABLE
6945 @cindex environment variable
6948 @item @emph{Description}:
6949 Get the @var{VALUE} of the environmental variable @var{NAME}.
6951 Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It
6952 is the responsibility of the user to ensure that the environment is
6953 not being updated concurrently with a call to the
6954 @code{GET_ENVIRONMENT_VARIABLE} intrinsic.
6956 @item @emph{Standard}:
6957 Fortran 2003 and later
6962 @item @emph{Syntax}:
6963 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
6965 @item @emph{Arguments}:
6966 @multitable @columnfractions .15 .70
6967 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
6968 and of default kind.
6969 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
6970 and of default kind.
6971 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6972 and of default kind.
6973 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6974 and of default kind.
6975 @item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL}
6976 and of default kind.
6979 @item @emph{Return value}:
6980 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
6981 not large enough to hold the data, it is truncated. If @var{NAME}
6982 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
6983 contains the length needed for storing the environment variable @var{NAME}
6984 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
6985 but too short for the environment variable; it is 1 if the environment
6986 variable does not exist and 2 if the processor does not support environment
6987 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
6988 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
6989 are significant; otherwise they are not part of the environment variable
6992 @item @emph{Example}:
6995 CHARACTER(len=255) :: homedir
6996 CALL get_environment_variable("HOME", homedir)
6997 WRITE (*,*) TRIM(homedir)
7005 @section @code{GETGID} --- Group ID function
7007 @cindex system, group ID
7010 @item @emph{Description}:
7011 Returns the numerical group ID of the current process.
7013 @item @emph{Standard}:
7019 @item @emph{Syntax}:
7020 @code{RESULT = GETGID()}
7022 @item @emph{Return value}:
7023 The return value of @code{GETGID} is an @code{INTEGER} of the default
7027 @item @emph{Example}:
7028 See @code{GETPID} for an example.
7030 @item @emph{See also}:
7031 @ref{GETPID}, @ref{GETUID}
7037 @section @code{GETLOG} --- Get login name
7039 @cindex system, login name
7043 @item @emph{Description}:
7044 Gets the username under which the program is running.
7046 @item @emph{Standard}:
7052 @item @emph{Syntax}:
7053 @code{CALL GETLOG(C)}
7055 @item @emph{Arguments}:
7056 @multitable @columnfractions .15 .70
7057 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
7060 @item @emph{Return value}:
7061 Stores the current user name in @var{LOGIN}. (On systems where POSIX
7062 functions @code{geteuid} and @code{getpwuid} are not available, and
7063 the @code{getlogin} function is not implemented either, this will
7064 return a blank string.)
7066 @item @emph{Example}:
7069 CHARACTER(32) :: login
7075 @item @emph{See also}:
7082 @section @code{GETPID} --- Process ID function
7084 @cindex system, process ID
7088 @item @emph{Description}:
7089 Returns the numerical process identifier of the current process.
7091 @item @emph{Standard}:
7097 @item @emph{Syntax}:
7098 @code{RESULT = GETPID()}
7100 @item @emph{Return value}:
7101 The return value of @code{GETPID} is an @code{INTEGER} of the default
7105 @item @emph{Example}:
7108 print *, "The current process ID is ", getpid()
7109 print *, "Your numerical user ID is ", getuid()
7110 print *, "Your numerical group ID is ", getgid()
7114 @item @emph{See also}:
7115 @ref{GETGID}, @ref{GETUID}
7121 @section @code{GETUID} --- User ID function
7123 @cindex system, user ID
7127 @item @emph{Description}:
7128 Returns the numerical user ID of the current process.
7130 @item @emph{Standard}:
7136 @item @emph{Syntax}:
7137 @code{RESULT = GETUID()}
7139 @item @emph{Return value}:
7140 The return value of @code{GETUID} is an @code{INTEGER} of the default
7144 @item @emph{Example}:
7145 See @code{GETPID} for an example.
7147 @item @emph{See also}:
7148 @ref{GETPID}, @ref{GETLOG}
7154 @section @code{GMTIME} --- Convert time to GMT info
7156 @cindex time, conversion to GMT info
7159 @item @emph{Description}:
7160 Given a system time value @var{TIME} (as provided by the @ref{TIME}
7161 intrinsic), fills @var{VALUES} with values extracted from it appropriate
7162 to the UTC time zone (Universal Coordinated Time, also known in some
7163 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
7165 This intrinsic routine is provided for backwards compatibility with
7166 GNU Fortran 77. In new code, programmers should consider the use of
7167 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
7170 @item @emph{Standard}:
7176 @item @emph{Syntax}:
7177 @code{CALL GMTIME(TIME, VALUES)}
7179 @item @emph{Arguments}:
7180 @multitable @columnfractions .15 .70
7181 @item @var{TIME} @tab An @code{INTEGER} scalar expression
7182 corresponding to a system time, with @code{INTENT(IN)}.
7183 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
7184 with @code{INTENT(OUT)}.
7187 @item @emph{Return value}:
7188 The elements of @var{VALUES} are assigned as follows:
7190 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
7192 @item Minutes after the hour, range 0--59
7193 @item Hours past midnight, range 0--23
7194 @item Day of month, range 1--31
7195 @item Number of months since January, range 0--11
7196 @item Years since 1900
7197 @item Number of days since Sunday, range 0--6
7198 @item Days since January 1, range 0--365
7199 @item Daylight savings indicator: positive if daylight savings is in
7200 effect, zero if not, and negative if the information is not available.
7203 @item @emph{See also}:
7204 @ref{DATE_AND_TIME}, @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
7211 @section @code{HOSTNM} --- Get system host name
7213 @cindex system, host name
7216 @item @emph{Description}:
7217 Retrieves the host name of the system on which the program is running.
7219 This intrinsic is provided in both subroutine and function forms; however,
7220 only one form can be used in any given program unit.
7222 @item @emph{Standard}:
7226 Subroutine, function
7228 @item @emph{Syntax}:
7229 @multitable @columnfractions .80
7230 @item @code{CALL HOSTNM(C [, STATUS])}
7231 @item @code{STATUS = HOSTNM(NAME)}
7234 @item @emph{Arguments}:
7235 @multitable @columnfractions .15 .70
7236 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
7237 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
7238 Returns 0 on success, or a system specific error code otherwise.
7241 @item @emph{Return value}:
7242 In either syntax, @var{NAME} is set to the current hostname if it can
7243 be obtained, or to a blank string otherwise.
7250 @section @code{HUGE} --- Largest number of a kind
7252 @cindex limits, largest number
7253 @cindex model representation, largest number
7256 @item @emph{Description}:
7257 @code{HUGE(X)} returns the largest number that is not an infinity in
7258 the model of the type of @code{X}.
7260 @item @emph{Standard}:
7261 Fortran 95 and later
7266 @item @emph{Syntax}:
7267 @code{RESULT = HUGE(X)}
7269 @item @emph{Arguments}:
7270 @multitable @columnfractions .15 .70
7271 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
7274 @item @emph{Return value}:
7275 The return value is of the same type and kind as @var{X}
7277 @item @emph{Example}:
7279 program test_huge_tiny
7280 print *, huge(0), huge(0.0), huge(0.0d0)
7281 print *, tiny(0.0), tiny(0.0d0)
7282 end program test_huge_tiny
7289 @section @code{HYPOT} --- Euclidean distance function
7291 @cindex Euclidean distance
7294 @item @emph{Description}:
7295 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
7296 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
7298 @item @emph{Standard}:
7299 Fortran 2008 and later
7304 @item @emph{Syntax}:
7305 @code{RESULT = HYPOT(X, Y)}
7307 @item @emph{Arguments}:
7308 @multitable @columnfractions .15 .70
7309 @item @var{X} @tab The type shall be @code{REAL}.
7310 @item @var{Y} @tab The type and kind type parameter shall be the same as
7314 @item @emph{Return value}:
7315 The return value has the same type and kind type parameter as @var{X}.
7317 @item @emph{Example}:
7320 real(4) :: x = 1.e0_4, y = 0.5e0_4
7322 end program test_hypot
7329 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
7331 @cindex @acronym{ASCII} collating sequence
7332 @cindex collating sequence, @acronym{ASCII}
7333 @cindex conversion, to integer
7336 @item @emph{Description}:
7337 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
7338 in the first character position of @code{C}.
7340 @item @emph{Standard}:
7341 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7346 @item @emph{Syntax}:
7347 @code{RESULT = IACHAR(C [, KIND])}
7349 @item @emph{Arguments}:
7350 @multitable @columnfractions .15 .70
7351 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
7352 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7353 expression indicating the kind parameter of the result.
7356 @item @emph{Return value}:
7357 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7358 @var{KIND} is absent, the return value is of default integer kind.
7360 @item @emph{Example}:
7365 end program test_iachar
7369 See @ref{ICHAR} for a discussion of converting between numerical values
7370 and formatted string representations.
7372 @item @emph{See also}:
7373 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
7380 @section @code{IALL} --- Bitwise AND of array elements
7383 @cindex bits, AND of array elements
7386 @item @emph{Description}:
7387 Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
7388 if the corresponding element in @var{MASK} is @code{TRUE}.
7390 @item @emph{Standard}:
7391 Fortran 2008 and later
7394 Transformational function
7396 @item @emph{Syntax}:
7397 @multitable @columnfractions .80
7398 @item @code{RESULT = IALL(ARRAY[, MASK])}
7399 @item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
7402 @item @emph{Arguments}:
7403 @multitable @columnfractions .15 .70
7404 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7405 @item @var{DIM} @tab (Optional) shall be a scalar of type
7406 @code{INTEGER} with a value in the range from 1 to n, where n
7407 equals the rank of @var{ARRAY}.
7408 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
7409 and either be a scalar or an array of the same shape as @var{ARRAY}.
7412 @item @emph{Return value}:
7413 The result is of the same type as @var{ARRAY}.
7415 If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
7416 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7417 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7418 dimension @var{DIM} dropped is returned.
7420 @item @emph{Example}:
7429 PRINT '(b8.8)', IALL(a)
7433 @item @emph{See also}:
7434 @ref{IANY}, @ref{IPARITY}, @ref{IAND}
7440 @section @code{IAND} --- Bitwise logical and
7446 @cindex bitwise logical and
7447 @cindex logical and, bitwise
7450 @item @emph{Description}:
7451 Bitwise logical @code{AND}.
7453 @item @emph{Standard}:
7454 Fortran 95 and later, has overloads that are GNU extensions
7459 @item @emph{Syntax}:
7460 @code{RESULT = IAND(I, J)}
7462 @item @emph{Arguments}:
7463 @multitable @columnfractions .15 .70
7464 @item @var{I} @tab The type shall be @code{INTEGER}.
7465 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
7466 kind as @var{I}. (As a GNU extension, different kinds are also
7470 @item @emph{Return value}:
7471 The return type is @code{INTEGER}, of the same kind as the
7472 arguments. (If the argument kinds differ, it is of the same kind as
7473 the larger argument.)
7475 @item @emph{Example}:
7479 DATA a / Z'F' /, b / Z'3' /
7480 WRITE (*,*) IAND(a, b)
7484 @item @emph{Specific names}:
7485 @multitable @columnfractions .20 .20 .20 .25
7486 @item Name @tab Argument @tab Return type @tab Standard
7487 @item @code{IAND(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7488 @item @code{BIAND(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7489 @item @code{IIAND(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7490 @item @code{JIAND(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7491 @item @code{KIAND(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7494 @item @emph{See also}:
7495 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
7502 @section @code{IANY} --- Bitwise OR of array elements
7505 @cindex bits, OR of array elements
7508 @item @emph{Description}:
7509 Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
7510 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
7512 @item @emph{Standard}:
7513 Fortran 2008 and later
7516 Transformational function
7518 @item @emph{Syntax}:
7519 @multitable @columnfractions .80
7520 @item @code{RESULT = IANY(ARRAY[, MASK])}
7521 @item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
7524 @item @emph{Arguments}:
7525 @multitable @columnfractions .15 .70
7526 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7527 @item @var{DIM} @tab (Optional) shall be a scalar of type
7528 @code{INTEGER} with a value in the range from 1 to n, where n
7529 equals the rank of @var{ARRAY}.
7530 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
7531 and either be a scalar or an array of the same shape as @var{ARRAY}.
7534 @item @emph{Return value}:
7535 The result is of the same type as @var{ARRAY}.
7537 If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
7538 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7539 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7540 dimension @var{DIM} dropped is returned.
7542 @item @emph{Example}:
7551 PRINT '(b8.8)', IANY(a)
7555 @item @emph{See also}:
7556 @ref{IPARITY}, @ref{IALL}, @ref{IOR}
7562 @section @code{IARGC} --- Get the number of command line arguments
7564 @cindex command-line arguments
7565 @cindex command-line arguments, number of
7566 @cindex arguments, to program
7569 @item @emph{Description}:
7570 @code{IARGC} returns the number of arguments passed on the
7571 command line when the containing program was invoked.
7573 This intrinsic routine is provided for backwards compatibility with
7574 GNU Fortran 77. In new code, programmers should consider the use of
7575 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
7578 @item @emph{Standard}:
7584 @item @emph{Syntax}:
7585 @code{RESULT = IARGC()}
7587 @item @emph{Arguments}:
7590 @item @emph{Return value}:
7591 The number of command line arguments, type @code{INTEGER(4)}.
7593 @item @emph{Example}:
7596 @item @emph{See also}:
7597 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
7599 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
7600 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
7606 @section @code{IBCLR} --- Clear bit
7616 @item @emph{Description}:
7617 @code{IBCLR} returns the value of @var{I} with the bit at position
7618 @var{POS} set to zero.
7620 @item @emph{Standard}:
7621 Fortran 95 and later, has overloads that are GNU extensions
7626 @item @emph{Syntax}:
7627 @code{RESULT = IBCLR(I, POS)}
7629 @item @emph{Arguments}:
7630 @multitable @columnfractions .15 .70
7631 @item @var{I} @tab The type shall be @code{INTEGER}.
7632 @item @var{POS} @tab The type shall be @code{INTEGER}.
7635 @item @emph{Return value}:
7636 The return value is of type @code{INTEGER} and of the same kind as
7639 @item @emph{Specific names}:
7640 @multitable @columnfractions .20 .20 .20 .25
7641 @item Name @tab Argument @tab Return type @tab Standard
7642 @item @code{IBCLR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7643 @item @code{BBCLR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7644 @item @code{IIBCLR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7645 @item @code{JIBCLR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7646 @item @code{KIBCLR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7649 @item @emph{See also}:
7650 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
7657 @section @code{IBITS} --- Bit extraction
7664 @cindex bits, extract
7667 @item @emph{Description}:
7668 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
7669 starting from bit position @var{POS} and extending left for @var{LEN}
7670 bits. The result is right-justified and the remaining bits are
7671 zeroed. The value of @code{POS+LEN} must be less than or equal to the
7672 value @code{BIT_SIZE(I)}.
7674 @item @emph{Standard}:
7675 Fortran 95 and later, has overloads that are GNU extensions
7680 @item @emph{Syntax}:
7681 @code{RESULT = IBITS(I, POS, LEN)}
7683 @item @emph{Arguments}:
7684 @multitable @columnfractions .15 .70
7685 @item @var{I} @tab The type shall be @code{INTEGER}.
7686 @item @var{POS} @tab The type shall be @code{INTEGER}.
7687 @item @var{LEN} @tab The type shall be @code{INTEGER}.
7690 @item @emph{Return value}:
7691 The return value is of type @code{INTEGER} and of the same kind as
7694 @item @emph{Specific names}:
7695 @multitable @columnfractions .20 .20 .20 .25
7696 @item Name @tab Argument @tab Return type @tab Standard
7697 @item @code{IBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7698 @item @code{BBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7699 @item @code{IIBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7700 @item @code{JIBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7701 @item @code{KIBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7704 @item @emph{See also}:
7705 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
7711 @section @code{IBSET} --- Set bit
7720 @item @emph{Description}:
7721 @code{IBSET} returns the value of @var{I} with the bit at position
7722 @var{POS} set to one.
7724 @item @emph{Standard}:
7725 Fortran 95 and later, has overloads that are GNU extensions
7730 @item @emph{Syntax}:
7731 @code{RESULT = IBSET(I, POS)}
7733 @item @emph{Arguments}:
7734 @multitable @columnfractions .15 .70
7735 @item @var{I} @tab The type shall be @code{INTEGER}.
7736 @item @var{POS} @tab The type shall be @code{INTEGER}.
7739 @item @emph{Return value}:
7740 The return value is of type @code{INTEGER} and of the same kind as
7743 @item @emph{Specific names}:
7744 @multitable @columnfractions .20 .20 .20 .25
7745 @item Name @tab Argument @tab Return type @tab Standard
7746 @item @code{IBSET(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7747 @item @code{BBSET(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7748 @item @code{IIBSET(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7749 @item @code{JIBSET(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7750 @item @code{KIBSET(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7753 @item @emph{See also}:
7754 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
7761 @section @code{ICHAR} --- Character-to-integer conversion function
7763 @cindex conversion, to integer
7766 @item @emph{Description}:
7767 @code{ICHAR(C)} returns the code for the character in the first character
7768 position of @code{C} in the system's native character set.
7769 The correspondence between characters and their codes is not necessarily
7770 the same across different GNU Fortran implementations.
7772 @item @emph{Standard}:
7773 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7778 @item @emph{Syntax}:
7779 @code{RESULT = ICHAR(C [, KIND])}
7781 @item @emph{Arguments}:
7782 @multitable @columnfractions .15 .70
7783 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
7784 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7785 expression indicating the kind parameter of the result.
7788 @item @emph{Return value}:
7789 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7790 @var{KIND} is absent, the return value is of default integer kind.
7792 @item @emph{Example}:
7797 end program test_ichar
7800 @item @emph{Specific names}:
7801 @multitable @columnfractions .20 .20 .20 .25
7802 @item Name @tab Argument @tab Return type @tab Standard
7803 @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7807 No intrinsic exists to convert between a numeric value and a formatted
7808 character string representation -- for instance, given the
7809 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
7810 @code{REAL} value with the value 154, or vice versa. Instead, this
7811 functionality is provided by internal-file I/O, as in the following
7816 character(len=10) string, string2
7819 ! Convert a string to a numeric value
7820 read (string,'(I10)') value
7823 ! Convert a value to a formatted string
7824 write (string2,'(I10)') value
7826 end program read_val
7829 @item @emph{See also}:
7830 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
7837 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
7839 @cindex date, current
7840 @cindex current date
7843 @item @emph{Description}:
7844 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
7845 current local time. The day (in the range 1-31), month (in the range 1-12),
7846 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
7847 The year has four significant digits.
7849 This intrinsic routine is provided for backwards compatibility with
7850 GNU Fortran 77. In new code, programmers should consider the use of
7851 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
7854 @item @emph{Standard}:
7860 @item @emph{Syntax}:
7861 @code{CALL IDATE(VALUES)}
7863 @item @emph{Arguments}:
7864 @multitable @columnfractions .15 .70
7865 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
7866 the kind shall be the default integer kind.
7869 @item @emph{Return value}:
7870 Does not return anything.
7872 @item @emph{Example}:
7875 integer, dimension(3) :: tarray
7880 end program test_idate
7883 @item @emph{See also}:
7889 @section @code{IEOR} --- Bitwise logical exclusive or
7895 @cindex bitwise logical exclusive or
7896 @cindex logical exclusive or, bitwise
7899 @item @emph{Description}:
7900 @code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
7903 @item @emph{Standard}:
7904 Fortran 95 and later, has overloads that are GNU extensions
7909 @item @emph{Syntax}:
7910 @code{RESULT = IEOR(I, J)}
7912 @item @emph{Arguments}:
7913 @multitable @columnfractions .15 .70
7914 @item @var{I} @tab The type shall be @code{INTEGER}.
7915 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
7916 kind as @var{I}. (As a GNU extension, different kinds are also
7920 @item @emph{Return value}:
7921 The return type is @code{INTEGER}, of the same kind as the
7922 arguments. (If the argument kinds differ, it is of the same kind as
7923 the larger argument.)
7925 @item @emph{Specific names}:
7926 @multitable @columnfractions .20 .20 .20 .25
7927 @item Name @tab Argument @tab Return type @tab Standard
7928 @item @code{IEOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7929 @item @code{BIEOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7930 @item @code{IIEOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7931 @item @code{JIEOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7932 @item @code{KIEOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7935 @item @emph{See also}:
7936 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
7942 @section @code{IERRNO} --- Get the last system error number
7944 @cindex system, error handling
7947 @item @emph{Description}:
7948 Returns the last system error number, as given by the C @code{errno}
7951 @item @emph{Standard}:
7957 @item @emph{Syntax}:
7958 @code{RESULT = IERRNO()}
7960 @item @emph{Arguments}:
7963 @item @emph{Return value}:
7964 The return value is of type @code{INTEGER} and of the default integer
7967 @item @emph{See also}:
7974 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
7975 @fnindex IMAGE_INDEX
7976 @cindex coarray, @code{IMAGE_INDEX}
7977 @cindex images, cosubscript to image index conversion
7980 @item @emph{Description}:
7981 Returns the image index belonging to a cosubscript.
7983 @item @emph{Standard}:
7984 Fortran 2008 and later
7989 @item @emph{Syntax}:
7990 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
7992 @item @emph{Arguments}: None.
7993 @multitable @columnfractions .15 .70
7994 @item @var{COARRAY} @tab Coarray of any type.
7995 @item @var{SUB} @tab default integer rank-1 array of a size equal to
7996 the corank of @var{COARRAY}.
8000 @item @emph{Return value}:
8001 Scalar default integer with the value of the image index which corresponds
8002 to the cosubscripts. For invalid cosubscripts the result is zero.
8004 @item @emph{Example}:
8006 INTEGER :: array[2,-1:4,8,*]
8007 ! Writes 28 (or 0 if there are fewer than 28 images)
8008 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
8011 @item @emph{See also}:
8012 @ref{THIS_IMAGE}, @ref{NUM_IMAGES}
8017 @node INDEX intrinsic
8018 @section @code{INDEX} --- Position of a substring within a string
8020 @cindex substring position
8021 @cindex string, find substring
8024 @item @emph{Description}:
8025 Returns the position of the start of the first occurrence of string
8026 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
8027 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
8028 the @var{BACK} argument is present and true, the return value is the
8029 start of the last occurrence rather than the first.
8031 @item @emph{Standard}:
8032 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
8037 @item @emph{Syntax}:
8038 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
8040 @item @emph{Arguments}:
8041 @multitable @columnfractions .15 .70
8042 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
8044 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
8046 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
8048 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8049 expression indicating the kind parameter of the result.
8052 @item @emph{Return value}:
8053 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8054 @var{KIND} is absent, the return value is of default integer kind.
8056 @item @emph{Specific names}:
8057 @multitable @columnfractions .20 .20 .20 .25
8058 @item Name @tab Argument @tab Return type @tab Standard
8059 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8062 @item @emph{See also}:
8063 @ref{SCAN}, @ref{VERIFY}
8069 @section @code{INT} --- Convert to integer type
8073 @cindex conversion, to integer
8076 @item @emph{Description}:
8077 Convert to integer type
8079 @item @emph{Standard}:
8080 Fortran 77 and later
8085 @item @emph{Syntax}:
8086 @code{RESULT = INT(A [, KIND))}
8088 @item @emph{Arguments}:
8089 @multitable @columnfractions .15 .70
8090 @item @var{A} @tab Shall be of type @code{INTEGER},
8091 @code{REAL}, or @code{COMPLEX}.
8092 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8093 expression indicating the kind parameter of the result.
8096 @item @emph{Return value}:
8097 These functions return a @code{INTEGER} variable or array under
8098 the following rules:
8102 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
8104 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)}
8105 equals @code{0}. If @math{|A| \geq 1}, then @code{INT(A)} is the integer
8106 whose magnitude is the largest integer that does not exceed the magnitude
8107 of @var{A} and whose sign is the same as the sign of @var{A}.
8109 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
8112 @item @emph{Example}:
8116 complex :: z = (-3.7, 1.0)
8118 print *, int(z), int(z,8)
8122 @item @emph{Specific names}:
8123 @multitable @columnfractions .20 .20 .20 .25
8124 @item Name @tab Argument @tab Return type @tab Standard
8125 @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
8126 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
8127 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
8134 @section @code{INT2} --- Convert to 16-bit integer type
8137 @cindex conversion, to integer
8140 @item @emph{Description}:
8141 Convert to a @code{KIND=2} integer type. This is equivalent to the
8142 standard @code{INT} intrinsic with an optional argument of
8143 @code{KIND=2}, and is only included for backwards compatibility.
8145 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
8147 @item @emph{Standard}:
8153 @item @emph{Syntax}:
8154 @code{RESULT = INT2(A)}
8156 @item @emph{Arguments}:
8157 @multitable @columnfractions .15 .70
8158 @item @var{A} @tab Shall be of type @code{INTEGER},
8159 @code{REAL}, or @code{COMPLEX}.
8162 @item @emph{Return value}:
8163 The return value is a @code{INTEGER(2)} variable.
8165 @item @emph{See also}:
8166 @ref{INT}, @ref{INT8}, @ref{LONG}
8172 @section @code{INT8} --- Convert to 64-bit integer type
8174 @cindex conversion, to integer
8177 @item @emph{Description}:
8178 Convert to a @code{KIND=8} integer type. This is equivalent to the
8179 standard @code{INT} intrinsic with an optional argument of
8180 @code{KIND=8}, and is only included for backwards compatibility.
8182 @item @emph{Standard}:
8188 @item @emph{Syntax}:
8189 @code{RESULT = INT8(A)}
8191 @item @emph{Arguments}:
8192 @multitable @columnfractions .15 .70
8193 @item @var{A} @tab Shall be of type @code{INTEGER},
8194 @code{REAL}, or @code{COMPLEX}.
8197 @item @emph{Return value}:
8198 The return value is a @code{INTEGER(8)} variable.
8200 @item @emph{See also}:
8201 @ref{INT}, @ref{INT2}, @ref{LONG}
8207 @section @code{IOR} --- Bitwise logical or
8213 @cindex bitwise logical or
8214 @cindex logical or, bitwise
8217 @item @emph{Description}:
8218 @code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
8221 @item @emph{Standard}:
8222 Fortran 95 and later, has overloads that are GNU extensions
8227 @item @emph{Syntax}:
8228 @code{RESULT = IOR(I, J)}
8230 @item @emph{Arguments}:
8231 @multitable @columnfractions .15 .70
8232 @item @var{I} @tab The type shall be @code{INTEGER}.
8233 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
8234 kind as @var{I}. (As a GNU extension, different kinds are also
8238 @item @emph{Return value}:
8239 The return type is @code{INTEGER}, of the same kind as the
8240 arguments. (If the argument kinds differ, it is of the same kind as
8241 the larger argument.)
8243 @item @emph{Specific names}:
8244 @multitable @columnfractions .20 .20 .20 .25
8245 @item Name @tab Argument @tab Return type @tab Standard
8246 @item @code{IOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
8247 @item @code{BIOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8248 @item @code{IIOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8249 @item @code{JIOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8250 @item @code{KIOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8253 @item @emph{See also}:
8254 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
8260 @section @code{IPARITY} --- Bitwise XOR of array elements
8262 @cindex array, parity
8264 @cindex bits, XOR of array elements
8267 @item @emph{Description}:
8268 Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
8269 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
8271 @item @emph{Standard}:
8272 Fortran 2008 and later
8275 Transformational function
8277 @item @emph{Syntax}:
8278 @multitable @columnfractions .80
8279 @item @code{RESULT = IPARITY(ARRAY[, MASK])}
8280 @item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
8283 @item @emph{Arguments}:
8284 @multitable @columnfractions .15 .70
8285 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
8286 @item @var{DIM} @tab (Optional) shall be a scalar of type
8287 @code{INTEGER} with a value in the range from 1 to n, where n
8288 equals the rank of @var{ARRAY}.
8289 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
8290 and either be a scalar or an array of the same shape as @var{ARRAY}.
8293 @item @emph{Return value}:
8294 The result is of the same type as @var{ARRAY}.
8296 If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
8297 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
8298 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
8299 dimension @var{DIM} dropped is returned.
8301 @item @emph{Example}:
8303 PROGRAM test_iparity
8310 PRINT '(b8.8)', IPARITY(a)
8314 @item @emph{See also}:
8315 @ref{IANY}, @ref{IALL}, @ref{IEOR}, @ref{PARITY}
8321 @section @code{IRAND} --- Integer pseudo-random number
8323 @cindex random number generation
8326 @item @emph{Description}:
8327 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
8328 distribution between 0 and a system-dependent limit (which is in most
8329 cases 2147483647). If @var{FLAG} is 0, the next number
8330 in the current sequence is returned; if @var{FLAG} is 1, the generator
8331 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
8332 it is used as a new seed with @code{SRAND}.
8334 This intrinsic routine is provided for backwards compatibility with
8335 GNU Fortran 77. It implements a simple modulo generator as provided
8336 by @command{g77}. For new code, one should consider the use of
8337 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
8339 @item @emph{Standard}:
8345 @item @emph{Syntax}:
8346 @code{RESULT = IRAND(I)}
8348 @item @emph{Arguments}:
8349 @multitable @columnfractions .15 .70
8350 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
8353 @item @emph{Return value}:
8354 The return value is of @code{INTEGER(kind=4)} type.
8356 @item @emph{Example}:
8359 integer,parameter :: seed = 86456
8362 print *, irand(), irand(), irand(), irand()
8363 print *, irand(seed), irand(), irand(), irand()
8364 end program test_irand
8372 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
8373 @fnindex IS_IOSTAT_END
8374 @cindex @code{IOSTAT}, end of file
8377 @item @emph{Description}:
8378 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
8379 status ``end of file''. The function is equivalent to comparing the variable
8380 with the @code{IOSTAT_END} parameter of the intrinsic module
8381 @code{ISO_FORTRAN_ENV}.
8383 @item @emph{Standard}:
8384 Fortran 2003 and later
8389 @item @emph{Syntax}:
8390 @code{RESULT = IS_IOSTAT_END(I)}
8392 @item @emph{Arguments}:
8393 @multitable @columnfractions .15 .70
8394 @item @var{I} @tab Shall be of the type @code{INTEGER}.
8397 @item @emph{Return value}:
8398 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
8399 @var{I} has the value which indicates an end of file condition for
8400 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
8402 @item @emph{Example}:
8407 OPEN(88, FILE='test.dat')
8408 READ(88, *, IOSTAT=stat) i
8409 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
8417 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
8418 @fnindex IS_IOSTAT_EOR
8419 @cindex @code{IOSTAT}, end of record
8422 @item @emph{Description}:
8423 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
8424 status ``end of record''. The function is equivalent to comparing the
8425 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
8426 @code{ISO_FORTRAN_ENV}.
8428 @item @emph{Standard}:
8429 Fortran 2003 and later
8434 @item @emph{Syntax}:
8435 @code{RESULT = IS_IOSTAT_EOR(I)}
8437 @item @emph{Arguments}:
8438 @multitable @columnfractions .15 .70
8439 @item @var{I} @tab Shall be of the type @code{INTEGER}.
8442 @item @emph{Return value}:
8443 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
8444 @var{I} has the value which indicates an end of file condition for
8445 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
8447 @item @emph{Example}:
8451 INTEGER :: stat, i(50)
8452 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
8453 READ(88, IOSTAT=stat) i
8454 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
8462 @section @code{ISATTY} --- Whether a unit is a terminal device.
8464 @cindex system, terminal
8467 @item @emph{Description}:
8468 Determine whether a unit is connected to a terminal device.
8470 @item @emph{Standard}:
8476 @item @emph{Syntax}:
8477 @code{RESULT = ISATTY(UNIT)}
8479 @item @emph{Arguments}:
8480 @multitable @columnfractions .15 .70
8481 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
8484 @item @emph{Return value}:
8485 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
8486 device, @code{.FALSE.} otherwise.
8488 @item @emph{Example}:
8491 INTEGER(kind=1) :: unit
8493 write(*,*) isatty(unit=unit)
8497 @item @emph{See also}:
8504 @section @code{ISHFT} --- Shift bits
8513 @item @emph{Description}:
8514 @code{ISHFT} returns a value corresponding to @var{I} with all of the
8515 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
8516 zero corresponds to a left shift, a value of zero corresponds to no
8517 shift, and a value less than zero corresponds to a right shift. If the
8518 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
8519 value is undefined. Bits shifted out from the left end or right end are
8520 lost; zeros are shifted in from the opposite end.
8522 @item @emph{Standard}:
8523 Fortran 95 and later, has overloads that are GNU extensions
8528 @item @emph{Syntax}:
8529 @code{RESULT = ISHFT(I, SHIFT)}
8531 @item @emph{Arguments}:
8532 @multitable @columnfractions .15 .70
8533 @item @var{I} @tab The type shall be @code{INTEGER}.
8534 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8537 @item @emph{Return value}:
8538 The return value is of type @code{INTEGER} and of the same kind as
8541 @item @emph{Specific names}:
8542 @multitable @columnfractions .20 .20 .20 .25
8543 @item Name @tab Argument @tab Return type @tab Standard
8544 @item @code{ISHFT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
8545 @item @code{BSHFT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8546 @item @code{IISHFT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8547 @item @code{JISHFT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8548 @item @code{KISHFT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8551 @item @emph{See also}:
8558 @section @code{ISHFTC} --- Shift bits circularly
8564 @cindex bits, shift circular
8567 @item @emph{Description}:
8568 @code{ISHFTC} returns a value corresponding to @var{I} with the
8569 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
8570 is, bits shifted out one end are shifted into the opposite end. A value
8571 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
8572 zero corresponds to no shift, and a value less than zero corresponds to
8573 a right shift. The absolute value of @var{SHIFT} must be less than
8574 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
8575 equivalent to @code{BIT_SIZE(I)}.
8577 @item @emph{Standard}:
8578 Fortran 95 and later, has overloads that are GNU extensions
8583 @item @emph{Syntax}:
8584 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
8586 @item @emph{Arguments}:
8587 @multitable @columnfractions .15 .70
8588 @item @var{I} @tab The type shall be @code{INTEGER}.
8589 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8590 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
8591 the value must be greater than zero and less than or equal to
8595 @item @emph{Return value}:
8596 The return value is of type @code{INTEGER} and of the same kind as
8599 @item @emph{Specific names}:
8600 @multitable @columnfractions .20 .20 .20 .25
8601 @item Name @tab Argument @tab Return type @tab Standard
8602 @item @code{ISHFTC(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
8603 @item @code{BSHFTC(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8604 @item @code{IISHFTC(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8605 @item @code{JISHFTC(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8606 @item @code{KISHFTC(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8609 @item @emph{See also}:
8616 @section @code{ISNAN} --- Test for a NaN
8621 @item @emph{Description}:
8622 @code{ISNAN} tests whether a floating-point value is an IEEE
8624 @item @emph{Standard}:
8630 @item @emph{Syntax}:
8633 @item @emph{Arguments}:
8634 @multitable @columnfractions .15 .70
8635 @item @var{X} @tab Variable of the type @code{REAL}.
8639 @item @emph{Return value}:
8640 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
8641 if @var{X} is a NaN and @code{FALSE} otherwise.
8643 @item @emph{Example}:
8650 if (isnan(x)) stop '"x" is a NaN'
8651 end program test_nan
8658 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
8660 @cindex time, current
8661 @cindex current time
8664 @item @emph{Description}:
8665 @code{ITIME(VALUES)} Fills @var{VALUES} with the numerical values at the
8666 current local time. The hour (in the range 1-24), minute (in the range 1-60),
8667 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
8670 This intrinsic routine is provided for backwards compatibility with
8671 GNU Fortran 77. In new code, programmers should consider the use of
8672 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
8675 @item @emph{Standard}:
8681 @item @emph{Syntax}:
8682 @code{CALL ITIME(VALUES)}
8684 @item @emph{Arguments}:
8685 @multitable @columnfractions .15 .70
8686 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
8687 and the kind shall be the default integer kind.
8690 @item @emph{Return value}:
8691 Does not return anything.
8694 @item @emph{Example}:
8697 integer, dimension(3) :: tarray
8702 end program test_itime
8705 @item @emph{See also}:
8712 @section @code{KILL} --- Send a signal to a process
8716 @item @emph{Description}:
8717 @item @emph{Standard}:
8718 Sends the signal specified by @var{SIG} to the process @var{PID}.
8721 This intrinsic is provided in both subroutine and function forms;
8722 however, only one form can be used in any given program unit.
8725 Subroutine, function
8727 @item @emph{Syntax}:
8728 @multitable @columnfractions .80
8729 @item @code{CALL KILL(PID, SIG [, STATUS])}
8730 @item @code{STATUS = KILL(PID, SIG)}
8733 @item @emph{Arguments}:
8734 @multitable @columnfractions .15 .70
8735 @item @var{PID} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}.
8736 @item @var{SIG} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}.
8737 @item @var{STATUS} @tab [Subroutine](Optional)
8738 Shall be a scalar @code{INTEGER}.
8739 Returns 0 on success; otherwise a system-specific error code is returned.
8740 @item @var{STATUS} @tab [Function] The kind type parameter is that of
8742 Returns 0 on success; otherwise a system-specific error code is returned.
8745 @item @emph{See also}:
8746 @ref{ABORT}, @ref{EXIT}
8751 @section @code{KIND} --- Kind of an entity
8756 @item @emph{Description}:
8757 @code{KIND(X)} returns the kind value of the entity @var{X}.
8759 @item @emph{Standard}:
8760 Fortran 95 and later
8765 @item @emph{Syntax}:
8768 @item @emph{Arguments}:
8769 @multitable @columnfractions .15 .70
8770 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
8771 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
8774 @item @emph{Return value}:
8775 The return value is a scalar of type @code{INTEGER} and of the default
8778 @item @emph{Example}:
8781 integer,parameter :: kc = kind(' ')
8782 integer,parameter :: kl = kind(.true.)
8784 print *, "The default character kind is ", kc
8785 print *, "The default logical kind is ", kl
8786 end program test_kind
8794 @section @code{LBOUND} --- Lower dimension bounds of an array
8796 @cindex array, lower bound
8799 @item @emph{Description}:
8800 Returns the lower bounds of an array, or a single lower bound
8801 along the @var{DIM} dimension.
8802 @item @emph{Standard}:
8803 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
8808 @item @emph{Syntax}:
8809 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
8811 @item @emph{Arguments}:
8812 @multitable @columnfractions .15 .70
8813 @item @var{ARRAY} @tab Shall be an array, of any type.
8814 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
8815 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8816 expression indicating the kind parameter of the result.
8819 @item @emph{Return value}:
8820 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8821 @var{KIND} is absent, the return value is of default integer kind.
8822 If @var{DIM} is absent, the result is an array of the lower bounds of
8823 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
8824 corresponding to the lower bound of the array along that dimension. If
8825 @var{ARRAY} is an expression rather than a whole array or array
8826 structure component, or if it has a zero extent along the relevant
8827 dimension, the lower bound is taken to be 1.
8829 @item @emph{See also}:
8830 @ref{UBOUND}, @ref{LCOBOUND}
8836 @section @code{LCOBOUND} --- Lower codimension bounds of an array
8838 @cindex coarray, lower bound
8841 @item @emph{Description}:
8842 Returns the lower bounds of a coarray, or a single lower cobound
8843 along the @var{DIM} codimension.
8844 @item @emph{Standard}:
8845 Fortran 2008 and later
8850 @item @emph{Syntax}:
8851 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
8853 @item @emph{Arguments}:
8854 @multitable @columnfractions .15 .70
8855 @item @var{ARRAY} @tab Shall be an coarray, of any type.
8856 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
8857 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8858 expression indicating the kind parameter of the result.
8861 @item @emph{Return value}:
8862 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8863 @var{KIND} is absent, the return value is of default integer kind.
8864 If @var{DIM} is absent, the result is an array of the lower cobounds of
8865 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
8866 corresponding to the lower cobound of the array along that codimension.
8868 @item @emph{See also}:
8869 @ref{UCOBOUND}, @ref{LBOUND}
8875 @section @code{LEADZ} --- Number of leading zero bits of an integer
8880 @item @emph{Description}:
8881 @code{LEADZ} returns the number of leading zero bits of an integer.
8883 @item @emph{Standard}:
8884 Fortran 2008 and later
8889 @item @emph{Syntax}:
8890 @code{RESULT = LEADZ(I)}
8892 @item @emph{Arguments}:
8893 @multitable @columnfractions .15 .70
8894 @item @var{I} @tab Shall be of type @code{INTEGER}.
8897 @item @emph{Return value}:
8898 The type of the return value is the default @code{INTEGER}.
8899 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
8901 @item @emph{Example}:
8904 WRITE (*,*) BIT_SIZE(1) ! prints 32
8905 WRITE (*,*) LEADZ(1) ! prints 31
8909 @item @emph{See also}:
8910 @ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR}
8916 @section @code{LEN} --- Length of a character entity
8918 @cindex string, length
8921 @item @emph{Description}:
8922 Returns the length of a character string. If @var{STRING} is an array,
8923 the length of an element of @var{STRING} is returned. Note that
8924 @var{STRING} need not be defined when this intrinsic is invoked, since
8925 only the length, not the content, of @var{STRING} is needed.
8927 @item @emph{Standard}:
8928 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
8933 @item @emph{Syntax}:
8934 @code{L = LEN(STRING [, KIND])}
8936 @item @emph{Arguments}:
8937 @multitable @columnfractions .15 .70
8938 @item @var{STRING} @tab Shall be a scalar or array of type
8939 @code{CHARACTER}, with @code{INTENT(IN)}
8940 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8941 expression indicating the kind parameter of the result.
8944 @item @emph{Return value}:
8945 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8946 @var{KIND} is absent, the return value is of default integer kind.
8949 @item @emph{Specific names}:
8950 @multitable @columnfractions .20 .20 .20 .25
8951 @item Name @tab Argument @tab Return type @tab Standard
8952 @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
8956 @item @emph{See also}:
8957 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
8963 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
8965 @cindex string, length, without trailing whitespace
8968 @item @emph{Description}:
8969 Returns the length of a character string, ignoring any trailing blanks.
8971 @item @emph{Standard}:
8972 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
8977 @item @emph{Syntax}:
8978 @code{RESULT = LEN_TRIM(STRING [, KIND])}
8980 @item @emph{Arguments}:
8981 @multitable @columnfractions .15 .70
8982 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
8983 with @code{INTENT(IN)}
8984 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8985 expression indicating the kind parameter of the result.
8988 @item @emph{Return value}:
8989 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8990 @var{KIND} is absent, the return value is of default integer kind.
8992 @item @emph{See also}:
8993 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
8999 @section @code{LGE} --- Lexical greater than or equal
9001 @cindex lexical comparison of strings
9002 @cindex string, comparison
9005 @item @emph{Description}:
9006 Determines whether one string is lexically greater than or equal to
9007 another string, where the two strings are interpreted as containing
9008 ASCII character codes. If the String A and String B are not the same
9009 length, the shorter is compared as if spaces were appended to it to form
9010 a value that has the same length as the longer.
9012 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9013 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9014 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9015 that the latter use the processor's character ordering (which is not
9016 ASCII on some targets), whereas the former always use the ASCII
9019 @item @emph{Standard}:
9020 Fortran 77 and later
9025 @item @emph{Syntax}:
9026 @code{RESULT = LGE(STRING_A, STRING_B)}
9028 @item @emph{Arguments}:
9029 @multitable @columnfractions .15 .70
9030 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9031 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9034 @item @emph{Return value}:
9035 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
9036 otherwise, based on the ASCII ordering.
9038 @item @emph{Specific names}:
9039 @multitable @columnfractions .20 .20 .20 .25
9040 @item Name @tab Argument @tab Return type @tab Standard
9041 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9044 @item @emph{See also}:
9045 @ref{LGT}, @ref{LLE}, @ref{LLT}
9051 @section @code{LGT} --- Lexical greater than
9053 @cindex lexical comparison of strings
9054 @cindex string, comparison
9057 @item @emph{Description}:
9058 Determines whether one string is lexically greater than another string,
9059 where the two strings are interpreted as containing ASCII character
9060 codes. If the String A and String B are not the same length, the
9061 shorter is compared as if spaces were appended to it to form a value
9062 that has the same length as the longer.
9064 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9065 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9066 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9067 that the latter use the processor's character ordering (which is not
9068 ASCII on some targets), whereas the former always use the ASCII
9071 @item @emph{Standard}:
9072 Fortran 77 and later
9077 @item @emph{Syntax}:
9078 @code{RESULT = LGT(STRING_A, STRING_B)}
9080 @item @emph{Arguments}:
9081 @multitable @columnfractions .15 .70
9082 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9083 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9086 @item @emph{Return value}:
9087 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
9088 otherwise, based on the ASCII ordering.
9090 @item @emph{Specific names}:
9091 @multitable @columnfractions .20 .20 .20 .25
9092 @item Name @tab Argument @tab Return type @tab Standard
9093 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9096 @item @emph{See also}:
9097 @ref{LGE}, @ref{LLE}, @ref{LLT}
9103 @section @code{LINK} --- Create a hard link
9105 @cindex file system, create link
9106 @cindex file system, hard link
9109 @item @emph{Description}:
9110 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
9111 character (@code{CHAR(0)}) can be used to mark the end of the names in
9112 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
9113 names are ignored. If the @var{STATUS} argument is supplied, it
9114 contains 0 on success or a nonzero error code upon return; see
9117 This intrinsic is provided in both subroutine and function forms;
9118 however, only one form can be used in any given program unit.
9120 @item @emph{Standard}:
9124 Subroutine, function
9126 @item @emph{Syntax}:
9127 @multitable @columnfractions .80
9128 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
9129 @item @code{STATUS = LINK(PATH1, PATH2)}
9132 @item @emph{Arguments}:
9133 @multitable @columnfractions .15 .70
9134 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
9135 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
9136 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9139 @item @emph{See also}:
9140 @ref{SYMLNK}, @ref{UNLINK}
9146 @section @code{LLE} --- Lexical less than or equal
9148 @cindex lexical comparison of strings
9149 @cindex string, comparison
9152 @item @emph{Description}:
9153 Determines whether one string is lexically less than or equal to another
9154 string, where the two strings are interpreted as containing ASCII
9155 character codes. If the String A and String B are not the same length,
9156 the shorter is compared as if spaces were appended to it to form a value
9157 that has the same length as the longer.
9159 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9160 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9161 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9162 that the latter use the processor's character ordering (which is not
9163 ASCII on some targets), whereas the former always use the ASCII
9166 @item @emph{Standard}:
9167 Fortran 77 and later
9172 @item @emph{Syntax}:
9173 @code{RESULT = LLE(STRING_A, STRING_B)}
9175 @item @emph{Arguments}:
9176 @multitable @columnfractions .15 .70
9177 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9178 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9181 @item @emph{Return value}:
9182 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
9183 otherwise, based on the ASCII ordering.
9185 @item @emph{Specific names}:
9186 @multitable @columnfractions .20 .20 .20 .25
9187 @item Name @tab Argument @tab Return type @tab Standard
9188 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9191 @item @emph{See also}:
9192 @ref{LGE}, @ref{LGT}, @ref{LLT}
9198 @section @code{LLT} --- Lexical less than
9200 @cindex lexical comparison of strings
9201 @cindex string, comparison
9204 @item @emph{Description}:
9205 Determines whether one string is lexically less than another string,
9206 where the two strings are interpreted as containing ASCII character
9207 codes. If the String A and String B are not the same length, the
9208 shorter is compared as if spaces were appended to it to form a value
9209 that has the same length as the longer.
9211 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9212 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9213 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9214 that the latter use the processor's character ordering (which is not
9215 ASCII on some targets), whereas the former always use the ASCII
9218 @item @emph{Standard}:
9219 Fortran 77 and later
9224 @item @emph{Syntax}:
9225 @code{RESULT = LLT(STRING_A, STRING_B)}
9227 @item @emph{Arguments}:
9228 @multitable @columnfractions .15 .70
9229 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9230 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9233 @item @emph{Return value}:
9234 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
9235 otherwise, based on the ASCII ordering.
9237 @item @emph{Specific names}:
9238 @multitable @columnfractions .20 .20 .20 .25
9239 @item Name @tab Argument @tab Return type @tab Standard
9240 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9243 @item @emph{See also}:
9244 @ref{LGE}, @ref{LGT}, @ref{LLE}
9250 @section @code{LNBLNK} --- Index of the last non-blank character in a string
9252 @cindex string, find non-blank character
9255 @item @emph{Description}:
9256 Returns the length of a character string, ignoring any trailing blanks.
9257 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
9258 included for backwards compatibility.
9260 @item @emph{Standard}:
9266 @item @emph{Syntax}:
9267 @code{RESULT = LNBLNK(STRING)}
9269 @item @emph{Arguments}:
9270 @multitable @columnfractions .15 .70
9271 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
9272 with @code{INTENT(IN)}
9275 @item @emph{Return value}:
9276 The return value is of @code{INTEGER(kind=4)} type.
9278 @item @emph{See also}:
9279 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
9285 @section @code{LOC} --- Returns the address of a variable
9287 @cindex location of a variable in memory
9290 @item @emph{Description}:
9291 @code{LOC(X)} returns the address of @var{X} as an integer.
9293 @item @emph{Standard}:
9299 @item @emph{Syntax}:
9300 @code{RESULT = LOC(X)}
9302 @item @emph{Arguments}:
9303 @multitable @columnfractions .15 .70
9304 @item @var{X} @tab Variable of any type.
9307 @item @emph{Return value}:
9308 The return value is of type @code{INTEGER}, with a @code{KIND}
9309 corresponding to the size (in bytes) of a memory address on the target
9312 @item @emph{Example}:
9319 end program test_loc
9326 @section @code{LOG} --- Natural logarithm function
9333 @cindex exponential function, inverse
9334 @cindex logarithm function
9335 @cindex natural logarithm function
9338 @item @emph{Description}:
9339 @code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the
9340 logarithm to the base @math{e}.
9342 @item @emph{Standard}:
9343 Fortran 77 and later
9348 @item @emph{Syntax}:
9349 @code{RESULT = LOG(X)}
9351 @item @emph{Arguments}:
9352 @multitable @columnfractions .15 .70
9353 @item @var{X} @tab The type shall be @code{REAL} or
9357 @item @emph{Return value}:
9358 The return value is of type @code{REAL} or @code{COMPLEX}.
9359 The kind type parameter is the same as @var{X}.
9360 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
9361 @math{-\pi < \omega \leq \pi}.
9363 @item @emph{Example}:
9366 real(8) :: x = 2.7182818284590451_8
9367 complex :: z = (1.0, 2.0)
9368 x = log(x) ! will yield (approximately) 1
9370 end program test_log
9373 @item @emph{Specific names}:
9374 @multitable @columnfractions .20 .20 .20 .25
9375 @item Name @tab Argument @tab Return type @tab Standard
9376 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
9377 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
9378 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
9379 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9380 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9387 @section @code{LOG10} --- Base 10 logarithm function
9391 @cindex exponential function, inverse
9392 @cindex logarithm function with base 10
9393 @cindex base 10 logarithm function
9396 @item @emph{Description}:
9397 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
9399 @item @emph{Standard}:
9400 Fortran 77 and later
9405 @item @emph{Syntax}:
9406 @code{RESULT = LOG10(X)}
9408 @item @emph{Arguments}:
9409 @multitable @columnfractions .15 .70
9410 @item @var{X} @tab The type shall be @code{REAL}.
9413 @item @emph{Return value}:
9414 The return value is of type @code{REAL} or @code{COMPLEX}.
9415 The kind type parameter is the same as @var{X}.
9417 @item @emph{Example}:
9420 real(8) :: x = 10.0_8
9422 end program test_log10
9425 @item @emph{Specific names}:
9426 @multitable @columnfractions .20 .20 .20 .25
9427 @item Name @tab Argument @tab Return type @tab Standard
9428 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
9429 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
9436 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
9441 @cindex Gamma function, logarithm of
9444 @item @emph{Description}:
9445 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
9446 of the Gamma (@math{\Gamma}) function.
9448 @item @emph{Standard}:
9449 Fortran 2008 and later
9454 @item @emph{Syntax}:
9455 @code{X = LOG_GAMMA(X)}
9457 @item @emph{Arguments}:
9458 @multitable @columnfractions .15 .70
9459 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
9460 nor a negative integer.
9463 @item @emph{Return value}:
9464 The return value is of type @code{REAL} of the same kind as @var{X}.
9466 @item @emph{Example}:
9468 program test_log_gamma
9470 x = lgamma(x) ! returns 0.0
9471 end program test_log_gamma
9474 @item @emph{Specific names}:
9475 @multitable @columnfractions .20 .20 .20 .25
9476 @item Name @tab Argument @tab Return type @tab Standard
9477 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
9478 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
9479 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
9482 @item @emph{See also}:
9483 Gamma function: @ref{GAMMA}
9490 @section @code{LOGICAL} --- Convert to logical type
9492 @cindex conversion, to logical
9495 @item @emph{Description}:
9496 Converts one kind of @code{LOGICAL} variable to another.
9498 @item @emph{Standard}:
9499 Fortran 95 and later
9504 @item @emph{Syntax}:
9505 @code{RESULT = LOGICAL(L [, KIND])}
9507 @item @emph{Arguments}:
9508 @multitable @columnfractions .15 .70
9509 @item @var{L} @tab The type shall be @code{LOGICAL}.
9510 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9511 expression indicating the kind parameter of the result.
9514 @item @emph{Return value}:
9515 The return value is a @code{LOGICAL} value equal to @var{L}, with a
9516 kind corresponding to @var{KIND}, or of the default logical kind if
9517 @var{KIND} is not given.
9519 @item @emph{See also}:
9520 @ref{INT}, @ref{REAL}, @ref{CMPLX}
9526 @section @code{LONG} --- Convert to integer type
9528 @cindex conversion, to integer
9531 @item @emph{Description}:
9532 Convert to a @code{KIND=4} integer type, which is the same size as a C
9533 @code{long} integer. This is equivalent to the standard @code{INT}
9534 intrinsic with an optional argument of @code{KIND=4}, and is only
9535 included for backwards compatibility.
9537 @item @emph{Standard}:
9543 @item @emph{Syntax}:
9544 @code{RESULT = LONG(A)}
9546 @item @emph{Arguments}:
9547 @multitable @columnfractions .15 .70
9548 @item @var{A} @tab Shall be of type @code{INTEGER},
9549 @code{REAL}, or @code{COMPLEX}.
9552 @item @emph{Return value}:
9553 The return value is a @code{INTEGER(4)} variable.
9555 @item @emph{See also}:
9556 @ref{INT}, @ref{INT2}, @ref{INT8}
9562 @section @code{LSHIFT} --- Left shift bits
9564 @cindex bits, shift left
9567 @item @emph{Description}:
9568 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
9569 bits shifted left by @var{SHIFT} places. If the absolute value of
9570 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
9571 Bits shifted out from the left end are lost; zeros are shifted in from
9574 This function has been superseded by the @code{ISHFT} intrinsic, which
9575 is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
9576 which is standard in Fortran 2008 and later.
9578 @item @emph{Standard}:
9584 @item @emph{Syntax}:
9585 @code{RESULT = LSHIFT(I, SHIFT)}
9587 @item @emph{Arguments}:
9588 @multitable @columnfractions .15 .70
9589 @item @var{I} @tab The type shall be @code{INTEGER}.
9590 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
9593 @item @emph{Return value}:
9594 The return value is of type @code{INTEGER} and of the same kind as
9597 @item @emph{See also}:
9598 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}, @ref{SHIFTA}, @ref{SHIFTL},
9606 @section @code{LSTAT} --- Get file status
9608 @cindex file system, file status
9611 @item @emph{Description}:
9612 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
9613 symbolic link, then the link itself is statted, not the file that it
9616 The elements in @code{VALUES} are the same as described by @ref{STAT}.
9618 This intrinsic is provided in both subroutine and function forms;
9619 however, only one form can be used in any given program unit.
9621 @item @emph{Standard}:
9625 Subroutine, function
9627 @item @emph{Syntax}:
9628 @multitable @columnfractions .80
9629 @item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
9630 @item @code{STATUS = LSTAT(NAME, VALUES)}
9633 @item @emph{Arguments}:
9634 @multitable @columnfractions .15 .70
9635 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
9636 kind, a valid path within the file system.
9637 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
9638 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
9639 Returns 0 on success and a system specific error code otherwise.
9642 @item @emph{Example}:
9643 See @ref{STAT} for an example.
9645 @item @emph{See also}:
9646 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
9652 @section @code{LTIME} --- Convert time to local time info
9654 @cindex time, conversion to local time info
9657 @item @emph{Description}:
9658 Given a system time value @var{TIME} (as provided by the @ref{TIME}
9659 intrinsic), fills @var{VALUES} with values extracted from it appropriate
9660 to the local time zone using @code{localtime(3)}.
9662 This intrinsic routine is provided for backwards compatibility with
9663 GNU Fortran 77. In new code, programmers should consider the use of
9664 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
9667 @item @emph{Standard}:
9673 @item @emph{Syntax}:
9674 @code{CALL LTIME(TIME, VALUES)}
9676 @item @emph{Arguments}:
9677 @multitable @columnfractions .15 .70
9678 @item @var{TIME} @tab An @code{INTEGER} scalar expression
9679 corresponding to a system time, with @code{INTENT(IN)}.
9680 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
9681 with @code{INTENT(OUT)}.
9684 @item @emph{Return value}:
9685 The elements of @var{VALUES} are assigned as follows:
9687 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
9689 @item Minutes after the hour, range 0--59
9690 @item Hours past midnight, range 0--23
9691 @item Day of month, range 1--31
9692 @item Number of months since January, range 0--11
9693 @item Years since 1900
9694 @item Number of days since Sunday, range 0--6
9695 @item Days since January 1, range 0--365
9696 @item Daylight savings indicator: positive if daylight savings is in
9697 effect, zero if not, and negative if the information is not available.
9700 @item @emph{See also}:
9701 @ref{DATE_AND_TIME}, @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
9708 @section @code{MALLOC} --- Allocate dynamic memory
9710 @cindex pointer, cray
9713 @item @emph{Description}:
9714 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
9715 returns the address of the allocated memory. The @code{MALLOC} intrinsic
9716 is an extension intended to be used with Cray pointers, and is provided
9717 in GNU Fortran to allow the user to compile legacy code. For new code
9718 using Fortran 95 pointers, the memory allocation intrinsic is
9721 @item @emph{Standard}:
9727 @item @emph{Syntax}:
9728 @code{PTR = MALLOC(SIZE)}
9730 @item @emph{Arguments}:
9731 @multitable @columnfractions .15 .70
9732 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
9735 @item @emph{Return value}:
9736 The return value is of type @code{INTEGER(K)}, with @var{K} such that
9737 variables of type @code{INTEGER(K)} have the same size as
9738 C pointers (@code{sizeof(void *)}).
9740 @item @emph{Example}:
9741 The following example demonstrates the use of @code{MALLOC} and
9742 @code{FREE} with Cray pointers.
9751 ptr_x = malloc(20*8)
9753 x(i) = sqrt(1.0d0 / i)
9761 end program test_malloc
9764 @item @emph{See also}:
9771 @section @code{MASKL} --- Left justified mask
9773 @cindex mask, left justified
9776 @item @emph{Description}:
9777 @code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
9778 remaining bits set to 0.
9780 @item @emph{Standard}:
9781 Fortran 2008 and later
9786 @item @emph{Syntax}:
9787 @code{RESULT = MASKL(I[, KIND])}
9789 @item @emph{Arguments}:
9790 @multitable @columnfractions .15 .70
9791 @item @var{I} @tab Shall be of type @code{INTEGER}.
9792 @item @var{KIND} @tab Shall be a scalar constant expression of type
9796 @item @emph{Return value}:
9797 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
9798 specifies the kind value of the return type; otherwise, it is of the
9799 default integer kind.
9801 @item @emph{See also}:
9808 @section @code{MASKR} --- Right justified mask
9810 @cindex mask, right justified
9813 @item @emph{Description}:
9814 @code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
9815 remaining bits set to 0.
9817 @item @emph{Standard}:
9818 Fortran 2008 and later
9823 @item @emph{Syntax}:
9824 @code{RESULT = MASKR(I[, KIND])}
9826 @item @emph{Arguments}:
9827 @multitable @columnfractions .15 .70
9828 @item @var{I} @tab Shall be of type @code{INTEGER}.
9829 @item @var{KIND} @tab Shall be a scalar constant expression of type
9833 @item @emph{Return value}:
9834 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
9835 specifies the kind value of the return type; otherwise, it is of the
9836 default integer kind.
9838 @item @emph{See also}:
9845 @section @code{MATMUL} --- matrix multiplication
9847 @cindex matrix multiplication
9848 @cindex product, matrix
9851 @item @emph{Description}:
9852 Performs a matrix multiplication on numeric or logical arguments.
9854 @item @emph{Standard}:
9855 Fortran 95 and later
9858 Transformational function
9860 @item @emph{Syntax}:
9861 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
9863 @item @emph{Arguments}:
9864 @multitable @columnfractions .15 .70
9865 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
9866 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
9868 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
9869 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
9870 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
9871 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
9872 equal to the last (or only) dimension of @var{MATRIX_A}.
9873 @var{MATRIX_A} and @var{MATRIX_B} shall not both be rank one arrays.
9876 @item @emph{Return value}:
9877 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
9878 kind of the result follow the usual type and kind promotion rules, as
9879 for the @code{*} or @code{.AND.} operators.
9881 @item @emph{See also}:
9887 @section @code{MAX} --- Maximum value of an argument list
9894 @cindex maximum value
9897 @item @emph{Description}:
9898 Returns the argument with the largest (most positive) value.
9900 @item @emph{Standard}:
9901 Fortran 77 and later
9906 @item @emph{Syntax}:
9907 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
9909 @item @emph{Arguments}:
9910 @multitable @columnfractions .15 .70
9911 @item @var{A1} @tab The type shall be @code{INTEGER} or
9913 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
9914 as @var{A1}. (As a GNU extension, arguments of different kinds are
9918 @item @emph{Return value}:
9919 The return value corresponds to the maximum value among the arguments,
9920 and has the same type and kind as the first argument.
9922 @item @emph{Specific names}:
9923 @multitable @columnfractions .20 .20 .20 .25
9924 @item Name @tab Argument @tab Return type @tab Standard
9925 @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
9926 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
9927 @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
9928 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
9929 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
9932 @item @emph{See also}:
9933 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
9940 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
9941 @fnindex MAXEXPONENT
9942 @cindex model representation, maximum exponent
9945 @item @emph{Description}:
9946 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
9949 @item @emph{Standard}:
9950 Fortran 95 and later
9955 @item @emph{Syntax}:
9956 @code{RESULT = MAXEXPONENT(X)}
9958 @item @emph{Arguments}:
9959 @multitable @columnfractions .15 .70
9960 @item @var{X} @tab Shall be of type @code{REAL}.
9963 @item @emph{Return value}:
9964 The return value is of type @code{INTEGER} and of the default integer
9967 @item @emph{Example}:
9973 print *, minexponent(x), maxexponent(x)
9974 print *, minexponent(y), maxexponent(y)
9975 end program exponents
9982 @section @code{MAXLOC} --- Location of the maximum value within an array
9984 @cindex array, location of maximum element
9987 @item @emph{Description}:
9988 Determines the location of the element in the array with the maximum
9989 value, or, if the @var{DIM} argument is supplied, determines the
9990 locations of the maximum element along each row of the array in the
9991 @var{DIM} direction. If @var{MASK} is present, only the elements for
9992 which @var{MASK} is @code{.TRUE.} are considered. If more than one
9993 element in the array has the maximum value, the location returned is
9994 that of the first such element in array element order. If the array has
9995 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
9996 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
9997 and all of the elements of @var{MASK} along a given row are zero, the
9998 result value for that row is zero.
10000 @item @emph{Standard}:
10001 Fortran 95 and later; @var{ARRAY} of @code{CHARACTER} and the
10002 @var{KIND} argument are available in Fortran 2003 and later.
10004 @item @emph{Class}:
10005 Transformational function
10007 @item @emph{Syntax}:
10008 @multitable @columnfractions .80
10009 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK] [,KIND])}
10010 @item @code{RESULT = MAXLOC(ARRAY [, MASK] [,KIND])}
10013 @item @emph{Arguments}:
10014 @multitable @columnfractions .15 .70
10015 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10017 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10018 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10019 inclusive. It may not be an optional dummy argument.
10020 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
10021 and conformable with @var{ARRAY}.
10022 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10023 expression indicating the kind parameter of the result.
10026 @item @emph{Return value}:
10027 If @var{DIM} is absent, the result is a rank-one array with a length
10028 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
10029 is an array with a rank one less than the rank of @var{ARRAY}, and a
10030 size corresponding to the size of @var{ARRAY} with the @var{DIM}
10031 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
10032 of one, the result is a scalar. If the optional argument @var{KIND}
10033 is present, the result is an integer of kind @var{KIND}, otherwise it
10034 is of default kind.
10036 @item @emph{See also}:
10037 @ref{MAX}, @ref{MAXVAL}
10044 @section @code{MAXVAL} --- Maximum value of an array
10046 @cindex array, maximum value
10047 @cindex maximum value
10050 @item @emph{Description}:
10051 Determines the maximum value of the elements in an array value, or, if
10052 the @var{DIM} argument is supplied, determines the maximum value along
10053 each row of the array in the @var{DIM} direction. If @var{MASK} is
10054 present, only the elements for which @var{MASK} is @code{.TRUE.} are
10055 considered. If the array has zero size, or all of the elements of
10056 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
10057 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
10060 @item @emph{Standard}:
10061 Fortran 95 and later
10063 @item @emph{Class}:
10064 Transformational function
10066 @item @emph{Syntax}:
10067 @multitable @columnfractions .80
10068 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
10069 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
10072 @item @emph{Arguments}:
10073 @multitable @columnfractions .15 .70
10074 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10076 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10077 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10078 inclusive. It may not be an optional dummy argument.
10079 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
10080 and conformable with @var{ARRAY}.
10083 @item @emph{Return value}:
10084 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
10085 is a scalar. If @var{DIM} is present, the result is an array with a
10086 rank one less than the rank of @var{ARRAY}, and a size corresponding to
10087 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
10088 cases, the result is of the same type and kind as @var{ARRAY}.
10090 @item @emph{See also}:
10091 @ref{MAX}, @ref{MAXLOC}
10097 @section @code{MCLOCK} --- Time function
10099 @cindex time, clock ticks
10100 @cindex clock ticks
10103 @item @emph{Description}:
10104 Returns the number of clock ticks since the start of the process, based
10105 on the function @code{clock(3)} in the C standard library.
10107 This intrinsic is not fully portable, such as to systems with 32-bit
10108 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
10109 the values returned by this intrinsic might be, or become, negative, or
10110 numerically less than previous values, during a single run of the
10113 @item @emph{Standard}:
10116 @item @emph{Class}:
10119 @item @emph{Syntax}:
10120 @code{RESULT = MCLOCK()}
10122 @item @emph{Return value}:
10123 The return value is a scalar of type @code{INTEGER(4)}, equal to the
10124 number of clock ticks since the start of the process, or @code{-1} if
10125 the system does not support @code{clock(3)}.
10127 @item @emph{See also}:
10128 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
10135 @section @code{MCLOCK8} --- Time function (64-bit)
10137 @cindex time, clock ticks
10138 @cindex clock ticks
10141 @item @emph{Description}:
10142 Returns the number of clock ticks since the start of the process, based
10143 on the function @code{clock(3)} in the C standard library.
10145 @emph{Warning:} this intrinsic does not increase the range of the timing
10146 values over that returned by @code{clock(3)}. On a system with a 32-bit
10147 @code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though
10148 it is converted to a 64-bit @code{INTEGER(8)} value. That means
10149 overflows of the 32-bit value can still occur. Therefore, the values
10150 returned by this intrinsic might be or become negative or numerically
10151 less than previous values during a single run of the compiled program.
10153 @item @emph{Standard}:
10156 @item @emph{Class}:
10159 @item @emph{Syntax}:
10160 @code{RESULT = MCLOCK8()}
10162 @item @emph{Return value}:
10163 The return value is a scalar of type @code{INTEGER(8)}, equal to the
10164 number of clock ticks since the start of the process, or @code{-1} if
10165 the system does not support @code{clock(3)}.
10167 @item @emph{See also}:
10168 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
10175 @section @code{MERGE} --- Merge variables
10177 @cindex array, merge arrays
10178 @cindex array, combine arrays
10181 @item @emph{Description}:
10182 Select values from two arrays according to a logical mask. The result
10183 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
10184 @var{FSOURCE} if it is @code{.FALSE.}.
10186 @item @emph{Standard}:
10187 Fortran 95 and later
10189 @item @emph{Class}:
10192 @item @emph{Syntax}:
10193 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
10195 @item @emph{Arguments}:
10196 @multitable @columnfractions .15 .70
10197 @item @var{TSOURCE} @tab May be of any type.
10198 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
10200 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
10203 @item @emph{Return value}:
10204 The result is of the same type and type parameters as @var{TSOURCE}.
10211 @section @code{MERGE_BITS} --- Merge of bits under mask
10212 @fnindex MERGE_BITS
10213 @cindex bits, merge
10216 @item @emph{Description}:
10217 @code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
10218 as determined by the mask. The i-th bit of the result is equal to the
10219 i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
10220 the i-th bit of @var{J} otherwise.
10222 @item @emph{Standard}:
10223 Fortran 2008 and later
10225 @item @emph{Class}:
10228 @item @emph{Syntax}:
10229 @code{RESULT = MERGE_BITS(I, J, MASK)}
10231 @item @emph{Arguments}:
10232 @multitable @columnfractions .15 .70
10233 @item @var{I} @tab Shall be of type @code{INTEGER}.
10234 @item @var{J} @tab Shall be of type @code{INTEGER} and of the same
10236 @item @var{MASK} @tab Shall be of type @code{INTEGER} and of the same
10240 @item @emph{Return value}:
10241 The result is of the same type and kind as @var{I}.
10248 @section @code{MIN} --- Minimum value of an argument list
10255 @cindex minimum value
10258 @item @emph{Description}:
10259 Returns the argument with the smallest (most negative) value.
10261 @item @emph{Standard}:
10262 Fortran 77 and later
10264 @item @emph{Class}:
10267 @item @emph{Syntax}:
10268 @code{RESULT = MIN(A1, A2 [, A3, ...])}
10270 @item @emph{Arguments}:
10271 @multitable @columnfractions .15 .70
10272 @item @var{A1} @tab The type shall be @code{INTEGER} or
10274 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
10275 as @var{A1}. (As a GNU extension, arguments of different kinds are
10279 @item @emph{Return value}:
10280 The return value corresponds to the maximum value among the arguments,
10281 and has the same type and kind as the first argument.
10283 @item @emph{Specific names}:
10284 @multitable @columnfractions .20 .20 .20 .25
10285 @item Name @tab Argument @tab Return type @tab Standard
10286 @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
10287 @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
10288 @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
10289 @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
10290 @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
10293 @item @emph{See also}:
10294 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
10300 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
10301 @fnindex MINEXPONENT
10302 @cindex model representation, minimum exponent
10305 @item @emph{Description}:
10306 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
10309 @item @emph{Standard}:
10310 Fortran 95 and later
10312 @item @emph{Class}:
10315 @item @emph{Syntax}:
10316 @code{RESULT = MINEXPONENT(X)}
10318 @item @emph{Arguments}:
10319 @multitable @columnfractions .15 .70
10320 @item @var{X} @tab Shall be of type @code{REAL}.
10323 @item @emph{Return value}:
10324 The return value is of type @code{INTEGER} and of the default integer
10327 @item @emph{Example}:
10328 See @code{MAXEXPONENT} for an example.
10334 @section @code{MINLOC} --- Location of the minimum value within an array
10336 @cindex array, location of minimum element
10339 @item @emph{Description}:
10340 Determines the location of the element in the array with the minimum
10341 value, or, if the @var{DIM} argument is supplied, determines the
10342 locations of the minimum element along each row of the array in the
10343 @var{DIM} direction. If @var{MASK} is present, only the elements for
10344 which @var{MASK} is @code{.TRUE.} are considered. If more than one
10345 element in the array has the minimum value, the location returned is
10346 that of the first such element in array element order. If the array has
10347 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
10348 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
10349 and all of the elements of @var{MASK} along a given row are zero, the
10350 result value for that row is zero.
10352 @item @emph{Standard}:
10353 Fortran 95 and later; @var{ARRAY} of @code{CHARACTER} and the
10354 @var{KIND} argument are available in Fortran 2003 and later.
10356 @item @emph{Class}:
10357 Transformational function
10359 @item @emph{Syntax}:
10360 @multitable @columnfractions .80
10361 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK] [,KIND])}
10362 @item @code{RESULT = MINLOC(ARRAY [, MASK], [,KIND])}
10365 @item @emph{Arguments}:
10366 @multitable @columnfractions .15 .70
10367 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
10368 @code{REAL} or @code{CHARACTER}.
10369 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10370 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10371 inclusive. It may not be an optional dummy argument.
10372 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
10373 and conformable with @var{ARRAY}.
10374 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10375 expression indicating the kind parameter of the result.
10378 @item @emph{Return value}:
10379 If @var{DIM} is absent, the result is a rank-one array with a length
10380 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
10381 is an array with a rank one less than the rank of @var{ARRAY}, and a
10382 size corresponding to the size of @var{ARRAY} with the @var{DIM}
10383 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
10384 of one, the result is a scalar. If the optional argument @var{KIND}
10385 is present, the result is an integer of kind @var{KIND}, otherwise it
10386 is of default kind.
10388 @item @emph{See also}:
10389 @ref{MIN}, @ref{MINVAL}
10396 @section @code{MINVAL} --- Minimum value of an array
10398 @cindex array, minimum value
10399 @cindex minimum value
10402 @item @emph{Description}:
10403 Determines the minimum value of the elements in an array value, or, if
10404 the @var{DIM} argument is supplied, determines the minimum value along
10405 each row of the array in the @var{DIM} direction. If @var{MASK} is
10406 present, only the elements for which @var{MASK} is @code{.TRUE.} are
10407 considered. If the array has zero size, or all of the elements of
10408 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
10409 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
10410 @var{ARRAY} is of character type.
10412 @item @emph{Standard}:
10413 Fortran 95 and later
10415 @item @emph{Class}:
10416 Transformational function
10418 @item @emph{Syntax}:
10419 @multitable @columnfractions .80
10420 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
10421 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
10424 @item @emph{Arguments}:
10425 @multitable @columnfractions .15 .70
10426 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10428 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10429 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10430 inclusive. It may not be an optional dummy argument.
10431 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
10432 and conformable with @var{ARRAY}.
10435 @item @emph{Return value}:
10436 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
10437 is a scalar. If @var{DIM} is present, the result is an array with a
10438 rank one less than the rank of @var{ARRAY}, and a size corresponding to
10439 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
10440 cases, the result is of the same type and kind as @var{ARRAY}.
10442 @item @emph{See also}:
10443 @ref{MIN}, @ref{MINLOC}
10450 @section @code{MOD} --- Remainder function
10459 @cindex division, remainder
10462 @item @emph{Description}:
10463 @code{MOD(A,P)} computes the remainder of the division of A by P@.
10465 @item @emph{Standard}:
10466 Fortran 77 and later, has overloads that are GNU extensions
10468 @item @emph{Class}:
10471 @item @emph{Syntax}:
10472 @code{RESULT = MOD(A, P)}
10474 @item @emph{Arguments}:
10475 @multitable @columnfractions .15 .70
10476 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
10477 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
10478 and not equal to zero.
10481 @item @emph{Return value}:
10482 The return value is the result of @code{A - (INT(A/P) * P)}. The type
10483 and kind of the return value is the same as that of the arguments. The
10484 returned value has the same sign as A and a magnitude less than the
10487 @item @emph{Example}:
10491 print *, mod(17.5,5.5)
10492 print *, mod(17.5d0,5.5)
10493 print *, mod(17.5,5.5d0)
10495 print *, mod(-17,3)
10496 print *, mod(-17.5,5.5)
10497 print *, mod(-17.5d0,5.5)
10498 print *, mod(-17.5,5.5d0)
10500 print *, mod(17,-3)
10501 print *, mod(17.5,-5.5)
10502 print *, mod(17.5d0,-5.5)
10503 print *, mod(17.5,-5.5d0)
10504 end program test_mod
10507 @item @emph{Specific names}:
10508 @multitable @columnfractions .20 .20 .20 .25
10509 @item Name @tab Arguments @tab Return type @tab Standard
10510 @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
10511 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
10512 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
10513 @item @code{BMOD(A,P)} @tab @code{INTEGER(1) A,P} @tab @code{INTEGER(1)} @tab GNU extension
10514 @item @code{IMOD(A,P)} @tab @code{INTEGER(2) A,P} @tab @code{INTEGER(2)} @tab GNU extension
10515 @item @code{JMOD(A,P)} @tab @code{INTEGER(4) A,P} @tab @code{INTEGER(4)} @tab GNU extension
10516 @item @code{KMOD(A,P)} @tab @code{INTEGER(8) A,P} @tab @code{INTEGER(8)} @tab GNU extension
10519 @item @emph{See also}:
10527 @section @code{MODULO} --- Modulo function
10530 @cindex division, modulo
10533 @item @emph{Description}:
10534 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
10536 @item @emph{Standard}:
10537 Fortran 95 and later
10539 @item @emph{Class}:
10542 @item @emph{Syntax}:
10543 @code{RESULT = MODULO(A, P)}
10545 @item @emph{Arguments}:
10546 @multitable @columnfractions .15 .70
10547 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
10548 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}.
10549 It shall not be zero.
10552 @item @emph{Return value}:
10553 The type and kind of the result are those of the arguments.
10555 @item If @var{A} and @var{P} are of type @code{INTEGER}:
10556 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
10557 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
10559 @item If @var{A} and @var{P} are of type @code{REAL}:
10560 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
10562 The returned value has the same sign as P and a magnitude less than
10563 the magnitude of P.
10565 @item @emph{Example}:
10567 program test_modulo
10568 print *, modulo(17,3)
10569 print *, modulo(17.5,5.5)
10571 print *, modulo(-17,3)
10572 print *, modulo(-17.5,5.5)
10574 print *, modulo(17,-3)
10575 print *, modulo(17.5,-5.5)
10579 @item @emph{See also}:
10587 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
10588 @fnindex MOVE_ALLOC
10589 @cindex moving allocation
10590 @cindex allocation, moving
10593 @item @emph{Description}:
10594 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
10595 @var{TO}. @var{FROM} will become deallocated in the process.
10597 @item @emph{Standard}:
10598 Fortran 2003 and later
10600 @item @emph{Class}:
10603 @item @emph{Syntax}:
10604 @code{CALL MOVE_ALLOC(FROM, TO)}
10606 @item @emph{Arguments}:
10607 @multitable @columnfractions .15 .70
10608 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
10609 of any type and kind.
10610 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
10611 of the same type, kind and rank as @var{FROM}.
10614 @item @emph{Return value}:
10617 @item @emph{Example}:
10619 program test_move_alloc
10620 integer, allocatable :: a(:), b(:)
10624 call move_alloc(a, b)
10625 print *, allocated(a), allocated(b)
10627 end program test_move_alloc
10634 @section @code{MVBITS} --- Move bits from one integer to another
10643 @item @emph{Description}:
10644 Moves @var{LEN} bits from positions @var{FROMPOS} through
10645 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
10646 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
10647 affected by the movement of bits is unchanged. The values of
10648 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
10649 @code{BIT_SIZE(FROM)}.
10651 @item @emph{Standard}:
10652 Fortran 95 and later, has overloads that are GNU extensions
10654 @item @emph{Class}:
10655 Elemental subroutine
10657 @item @emph{Syntax}:
10658 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
10660 @item @emph{Arguments}:
10661 @multitable @columnfractions .15 .70
10662 @item @var{FROM} @tab The type shall be @code{INTEGER}.
10663 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
10664 @item @var{LEN} @tab The type shall be @code{INTEGER}.
10665 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
10666 same kind as @var{FROM}.
10667 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
10670 @item @emph{Specific names}:
10671 @multitable @columnfractions .20 .20 .20 .25
10672 @item Name @tab Argument @tab Return type @tab Standard
10673 @item @code{MVBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
10674 @item @code{BMVBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
10675 @item @code{IMVBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
10676 @item @code{JMVBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
10677 @item @code{KMVBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
10680 @item @emph{See also}:
10681 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
10687 @section @code{NEAREST} --- Nearest representable number
10689 @cindex real number, nearest different
10690 @cindex floating point, nearest different
10693 @item @emph{Description}:
10694 @code{NEAREST(X, S)} returns the processor-representable number nearest
10695 to @code{X} in the direction indicated by the sign of @code{S}.
10697 @item @emph{Standard}:
10698 Fortran 95 and later
10700 @item @emph{Class}:
10703 @item @emph{Syntax}:
10704 @code{RESULT = NEAREST(X, S)}
10706 @item @emph{Arguments}:
10707 @multitable @columnfractions .15 .70
10708 @item @var{X} @tab Shall be of type @code{REAL}.
10709 @item @var{S} @tab Shall be of type @code{REAL} and
10713 @item @emph{Return value}:
10714 The return value is of the same type as @code{X}. If @code{S} is
10715 positive, @code{NEAREST} returns the processor-representable number
10716 greater than @code{X} and nearest to it. If @code{S} is negative,
10717 @code{NEAREST} returns the processor-representable number smaller than
10718 @code{X} and nearest to it.
10720 @item @emph{Example}:
10722 program test_nearest
10724 x = nearest(42.0, 1.0)
10725 y = nearest(42.0, -1.0)
10726 write (*,"(3(G20.15))") x, y, x - y
10727 end program test_nearest
10734 @section @code{NEW_LINE} --- New line character
10737 @cindex output, newline
10740 @item @emph{Description}:
10741 @code{NEW_LINE(C)} returns the new-line character.
10743 @item @emph{Standard}:
10744 Fortran 2003 and later
10746 @item @emph{Class}:
10749 @item @emph{Syntax}:
10750 @code{RESULT = NEW_LINE(C)}
10752 @item @emph{Arguments}:
10753 @multitable @columnfractions .15 .70
10754 @item @var{C} @tab The argument shall be a scalar or array of the
10755 type @code{CHARACTER}.
10758 @item @emph{Return value}:
10759 Returns a @var{CHARACTER} scalar of length one with the new-line character of
10760 the same kind as parameter @var{C}.
10762 @item @emph{Example}:
10766 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
10767 end program newline
10774 @section @code{NINT} --- Nearest whole number
10777 @cindex rounding, nearest whole number
10780 @item @emph{Description}:
10781 @code{NINT(A)} rounds its argument to the nearest whole number.
10783 @item @emph{Standard}:
10784 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
10786 @item @emph{Class}:
10789 @item @emph{Syntax}:
10790 @code{RESULT = NINT(A [, KIND])}
10792 @item @emph{Arguments}:
10793 @multitable @columnfractions .15 .70
10794 @item @var{A} @tab The type of the argument shall be @code{REAL}.
10795 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10796 expression indicating the kind parameter of the result.
10799 @item @emph{Return value}:
10800 Returns @var{A} with the fractional portion of its magnitude eliminated by
10801 rounding to the nearest whole number and with its sign preserved,
10802 converted to an @code{INTEGER} of the default kind.
10804 @item @emph{Example}:
10811 print *, nint(x4), idnint(x8)
10812 end program test_nint
10815 @item @emph{Specific names}:
10816 @multitable @columnfractions .20 .20 .20 .25
10817 @item Name @tab Argument @tab Return Type @tab Standard
10818 @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later
10819 @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later
10822 @item @emph{See also}:
10823 @ref{CEILING}, @ref{FLOOR}
10830 @section @code{NORM2} --- Euclidean vector norms
10832 @cindex Euclidean vector norm
10833 @cindex L2 vector norm
10834 @cindex norm, Euclidean
10837 @item @emph{Description}:
10838 Calculates the Euclidean vector norm (@math{L_2} norm) of
10839 of @var{ARRAY} along dimension @var{DIM}.
10841 @item @emph{Standard}:
10842 Fortran 2008 and later
10844 @item @emph{Class}:
10845 Transformational function
10847 @item @emph{Syntax}:
10848 @multitable @columnfractions .80
10849 @item @code{RESULT = NORM2(ARRAY[, DIM])}
10852 @item @emph{Arguments}:
10853 @multitable @columnfractions .15 .70
10854 @item @var{ARRAY} @tab Shall be an array of type @code{REAL}
10855 @item @var{DIM} @tab (Optional) shall be a scalar of type
10856 @code{INTEGER} with a value in the range from 1 to n, where n
10857 equals the rank of @var{ARRAY}.
10860 @item @emph{Return value}:
10861 The result is of the same type as @var{ARRAY}.
10863 If @var{DIM} is absent, a scalar with the square root of the sum of all
10864 elements in @var{ARRAY} squared is returned. Otherwise, an array of
10865 rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
10866 shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
10869 @item @emph{Example}:
10872 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
10873 print *, NORM2(x) ! = sqrt(55.) ~ 7.416
10881 @section @code{NOT} --- Logical negation
10887 @cindex bits, negate
10888 @cindex bitwise logical not
10889 @cindex logical not, bitwise
10892 @item @emph{Description}:
10893 @code{NOT} returns the bitwise Boolean inverse of @var{I}.
10895 @item @emph{Standard}:
10896 Fortran 95 and later, has overloads that are GNU extensions
10898 @item @emph{Class}:
10901 @item @emph{Syntax}:
10902 @code{RESULT = NOT(I)}
10904 @item @emph{Arguments}:
10905 @multitable @columnfractions .15 .70
10906 @item @var{I} @tab The type shall be @code{INTEGER}.
10909 @item @emph{Return value}:
10910 The return type is @code{INTEGER}, of the same kind as the
10913 @item @emph{Specific names}:
10914 @multitable @columnfractions .20 .20 .20 .25
10915 @item Name @tab Argument @tab Return type @tab Standard
10916 @item @code{NOT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
10917 @item @code{BNOT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
10918 @item @code{INOT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
10919 @item @code{JNOT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
10920 @item @code{KNOT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
10923 @item @emph{See also}:
10924 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
10931 @section @code{NULL} --- Function that returns an disassociated pointer
10933 @cindex pointer, status
10934 @cindex pointer, disassociated
10937 @item @emph{Description}:
10938 Returns a disassociated pointer.
10940 If @var{MOLD} is present, a disassociated pointer of the same type is
10941 returned, otherwise the type is determined by context.
10943 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
10944 includes cases where it is required.
10946 @item @emph{Standard}:
10947 Fortran 95 and later
10949 @item @emph{Class}:
10950 Transformational function
10952 @item @emph{Syntax}:
10953 @code{PTR => NULL([MOLD])}
10955 @item @emph{Arguments}:
10956 @multitable @columnfractions .15 .70
10957 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
10958 status and of any type.
10961 @item @emph{Return value}:
10962 A disassociated pointer.
10964 @item @emph{Example}:
10966 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
10969 @item @emph{See also}:
10976 @section @code{NUM_IMAGES} --- Function that returns the number of images
10977 @fnindex NUM_IMAGES
10978 @cindex coarray, @code{NUM_IMAGES}
10979 @cindex images, number of
10982 @item @emph{Description}:
10983 Returns the number of images.
10985 @item @emph{Standard}:
10986 Fortran 2008 and later. With @var{DISTANCE} or @var{FAILED} argument,
10987 Technical Specification (TS) 18508 or later
10990 @item @emph{Class}:
10991 Transformational function
10993 @item @emph{Syntax}:
10994 @code{RESULT = NUM_IMAGES(DISTANCE, FAILED)}
10996 @item @emph{Arguments}:
10997 @multitable @columnfractions .15 .70
10998 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
10999 @item @var{FAILED} @tab (optional, intent(in)) Scalar logical expression
11002 @item @emph{Return value}:
11003 Scalar default-kind integer. If @var{DISTANCE} is not present or has value 0,
11004 the number of images in the current team is returned. For values smaller or
11005 equal distance to the initial team, it returns the number of images index
11006 on the ancestor team which has a distance of @var{DISTANCE} from the invoking
11007 team. If @var{DISTANCE} is larger than the distance to the initial team, the
11008 number of images of the initial team is returned. If @var{FAILED} is not present
11009 the total number of images is returned; if it has the value @code{.TRUE.},
11010 the number of failed images is returned, otherwise, the number of images which
11011 do have not the failed status.
11013 @item @emph{Example}:
11015 INTEGER :: value[*]
11017 value = THIS_IMAGE()
11019 IF (THIS_IMAGE() == 1) THEN
11020 DO i = 1, NUM_IMAGES()
11021 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
11026 @item @emph{See also}:
11027 @ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
11033 @section @code{OR} --- Bitwise logical OR
11035 @cindex bitwise logical or
11036 @cindex logical or, bitwise
11039 @item @emph{Description}:
11040 Bitwise logical @code{OR}.
11042 This intrinsic routine is provided for backwards compatibility with
11043 GNU Fortran 77. For integer arguments, programmers should consider
11044 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
11046 @item @emph{Standard}:
11049 @item @emph{Class}:
11052 @item @emph{Syntax}:
11053 @code{RESULT = OR(I, J)}
11055 @item @emph{Arguments}:
11056 @multitable @columnfractions .15 .70
11057 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
11058 type or a scalar @code{LOGICAL} type.
11059 @item @var{J} @tab The type shall be the same as the type of @var{J}.
11062 @item @emph{Return value}:
11063 The return type is either a scalar @code{INTEGER} or a scalar
11064 @code{LOGICAL}. If the kind type parameters differ, then the
11065 smaller kind type is implicitly converted to larger kind, and the
11066 return has the larger kind.
11068 @item @emph{Example}:
11071 LOGICAL :: T = .TRUE., F = .FALSE.
11073 DATA a / Z'F' /, b / Z'3' /
11075 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
11076 WRITE (*,*) OR(a, b)
11080 @item @emph{See also}:
11081 Fortran 95 elemental function: @ref{IOR}
11087 @section @code{PACK} --- Pack an array into an array of rank one
11089 @cindex array, packing
11090 @cindex array, reduce dimension
11091 @cindex array, gather elements
11094 @item @emph{Description}:
11095 Stores the elements of @var{ARRAY} in an array of rank one.
11097 The beginning of the resulting array is made up of elements whose @var{MASK}
11098 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
11101 @item @emph{Standard}:
11102 Fortran 95 and later
11104 @item @emph{Class}:
11105 Transformational function
11107 @item @emph{Syntax}:
11108 @code{RESULT = PACK(ARRAY, MASK[,VECTOR])}
11110 @item @emph{Arguments}:
11111 @multitable @columnfractions .15 .70
11112 @item @var{ARRAY} @tab Shall be an array of any type.
11113 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
11114 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
11116 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
11117 as @var{ARRAY} and of rank one. If present, the number of elements in
11118 @var{VECTOR} shall be equal to or greater than the number of true elements
11119 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
11120 @var{VECTOR} shall be equal to or greater than the number of elements in
11124 @item @emph{Return value}:
11125 The result is an array of rank one and the same type as that of @var{ARRAY}.
11126 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
11127 number of @code{TRUE} values in @var{MASK} otherwise.
11129 @item @emph{Example}:
11130 Gathering nonzero elements from an array:
11132 PROGRAM test_pack_1
11134 m = (/ 1, 0, 0, 0, 5, 0 /)
11135 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
11139 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
11141 PROGRAM test_pack_2
11143 m = (/ 1, 0, 0, 2 /)
11144 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
11148 @item @emph{See also}:
11155 @section @code{PARITY} --- Reduction with exclusive OR
11158 @cindex Reduction, XOR
11159 @cindex XOR reduction
11162 @item @emph{Description}:
11163 Calculates the parity, i.e. the reduction using @code{.XOR.},
11164 of @var{MASK} along dimension @var{DIM}.
11166 @item @emph{Standard}:
11167 Fortran 2008 and later
11169 @item @emph{Class}:
11170 Transformational function
11172 @item @emph{Syntax}:
11173 @multitable @columnfractions .80
11174 @item @code{RESULT = PARITY(MASK[, DIM])}
11177 @item @emph{Arguments}:
11178 @multitable @columnfractions .15 .70
11179 @item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL}
11180 @item @var{DIM} @tab (Optional) shall be a scalar of type
11181 @code{INTEGER} with a value in the range from 1 to n, where n
11182 equals the rank of @var{MASK}.
11185 @item @emph{Return value}:
11186 The result is of the same type as @var{MASK}.
11188 If @var{DIM} is absent, a scalar with the parity of all elements in
11189 @var{MASK} is returned, i.e. true if an odd number of elements is
11190 @code{.true.} and false otherwise. If @var{DIM} is present, an array
11191 of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
11192 and a shape similar to that of @var{MASK} with dimension @var{DIM}
11193 dropped is returned.
11195 @item @emph{Example}:
11198 LOGICAL :: x(2) = [ .true., .false. ]
11199 print *, PARITY(x) ! prints "T" (true).
11207 @section @code{PERROR} --- Print system error message
11209 @cindex system, error handling
11212 @item @emph{Description}:
11213 Prints (on the C @code{stderr} stream) a newline-terminated error
11214 message corresponding to the last system error. This is prefixed by
11215 @var{STRING}, a colon and a space. See @code{perror(3)}.
11217 @item @emph{Standard}:
11220 @item @emph{Class}:
11223 @item @emph{Syntax}:
11224 @code{CALL PERROR(STRING)}
11226 @item @emph{Arguments}:
11227 @multitable @columnfractions .15 .70
11228 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
11232 @item @emph{See also}:
11239 @section @code{POPCNT} --- Number of bits set
11241 @cindex binary representation
11245 @item @emph{Description}:
11246 @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
11247 representation of @code{I}.
11249 @item @emph{Standard}:
11250 Fortran 2008 and later
11252 @item @emph{Class}:
11255 @item @emph{Syntax}:
11256 @code{RESULT = POPCNT(I)}
11258 @item @emph{Arguments}:
11259 @multitable @columnfractions .15 .70
11260 @item @var{I} @tab Shall be of type @code{INTEGER}.
11263 @item @emph{Return value}:
11264 The return value is of type @code{INTEGER} and of the default integer
11267 @item @emph{See also}:
11268 @ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ}
11270 @item @emph{Example}:
11272 program test_population
11273 print *, popcnt(127), poppar(127)
11274 print *, popcnt(huge(0_4)), poppar(huge(0_4))
11275 print *, popcnt(huge(0_8)), poppar(huge(0_8))
11276 end program test_population
11282 @section @code{POPPAR} --- Parity of the number of bits set
11284 @cindex binary representation
11288 @item @emph{Description}:
11289 @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
11290 of the number of bits set ('1' bits) in the binary representation of
11291 @code{I}. It is equal to 0 if @code{I} has an even number of bits set,
11292 and 1 for an odd number of '1' bits.
11294 @item @emph{Standard}:
11295 Fortran 2008 and later
11297 @item @emph{Class}:
11300 @item @emph{Syntax}:
11301 @code{RESULT = POPPAR(I)}
11303 @item @emph{Arguments}:
11304 @multitable @columnfractions .15 .70
11305 @item @var{I} @tab Shall be of type @code{INTEGER}.
11308 @item @emph{Return value}:
11309 The return value is of type @code{INTEGER} and of the default integer
11312 @item @emph{See also}:
11313 @ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ}
11315 @item @emph{Example}:
11317 program test_population
11318 print *, popcnt(127), poppar(127)
11319 print *, popcnt(huge(0_4)), poppar(huge(0_4))
11320 print *, popcnt(huge(0_8)), poppar(huge(0_8))
11321 end program test_population
11328 @section @code{PRECISION} --- Decimal precision of a real kind
11330 @cindex model representation, precision
11333 @item @emph{Description}:
11334 @code{PRECISION(X)} returns the decimal precision in the model of the
11337 @item @emph{Standard}:
11338 Fortran 95 and later
11340 @item @emph{Class}:
11343 @item @emph{Syntax}:
11344 @code{RESULT = PRECISION(X)}
11346 @item @emph{Arguments}:
11347 @multitable @columnfractions .15 .70
11348 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
11351 @item @emph{Return value}:
11352 The return value is of type @code{INTEGER} and of the default integer
11355 @item @emph{See also}:
11356 @ref{SELECTED_REAL_KIND}, @ref{RANGE}
11358 @item @emph{Example}:
11360 program prec_and_range
11361 real(kind=4) :: x(2)
11362 complex(kind=8) :: y
11364 print *, precision(x), range(x)
11365 print *, precision(y), range(y)
11366 end program prec_and_range
11373 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
11377 @item @emph{Description}:
11378 Determines whether an optional dummy argument is present.
11380 @item @emph{Standard}:
11381 Fortran 95 and later
11383 @item @emph{Class}:
11386 @item @emph{Syntax}:
11387 @code{RESULT = PRESENT(A)}
11389 @item @emph{Arguments}:
11390 @multitable @columnfractions .15 .70
11391 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
11392 value, or a dummy procedure. It shall be the name of an optional dummy argument
11393 accessible within the current subroutine or function.
11396 @item @emph{Return value}:
11397 Returns either @code{TRUE} if the optional argument @var{A} is present, or
11398 @code{FALSE} otherwise.
11400 @item @emph{Example}:
11402 PROGRAM test_present
11403 WRITE(*,*) f(), f(42) ! "F T"
11405 LOGICAL FUNCTION f(x)
11406 INTEGER, INTENT(IN), OPTIONAL :: x
11416 @section @code{PRODUCT} --- Product of array elements
11418 @cindex array, product
11419 @cindex array, multiply elements
11420 @cindex array, conditionally multiply elements
11421 @cindex multiply array elements
11424 @item @emph{Description}:
11425 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
11426 the corresponding element in @var{MASK} is @code{TRUE}.
11428 @item @emph{Standard}:
11429 Fortran 95 and later
11431 @item @emph{Class}:
11432 Transformational function
11434 @item @emph{Syntax}:
11435 @multitable @columnfractions .80
11436 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
11437 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
11440 @item @emph{Arguments}:
11441 @multitable @columnfractions .15 .70
11442 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
11443 @code{REAL} or @code{COMPLEX}.
11444 @item @var{DIM} @tab (Optional) shall be a scalar of type
11445 @code{INTEGER} with a value in the range from 1 to n, where n
11446 equals the rank of @var{ARRAY}.
11447 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
11448 and either be a scalar or an array of the same shape as @var{ARRAY}.
11451 @item @emph{Return value}:
11452 The result is of the same type as @var{ARRAY}.
11454 If @var{DIM} is absent, a scalar with the product of all elements in
11455 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
11456 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
11457 dimension @var{DIM} dropped is returned.
11460 @item @emph{Example}:
11462 PROGRAM test_product
11463 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
11464 print *, PRODUCT(x) ! all elements, product = 120
11465 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
11469 @item @emph{See also}:
11476 @section @code{RADIX} --- Base of a model number
11478 @cindex model representation, base
11479 @cindex model representation, radix
11482 @item @emph{Description}:
11483 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
11485 @item @emph{Standard}:
11486 Fortran 95 and later
11488 @item @emph{Class}:
11491 @item @emph{Syntax}:
11492 @code{RESULT = RADIX(X)}
11494 @item @emph{Arguments}:
11495 @multitable @columnfractions .15 .70
11496 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
11499 @item @emph{Return value}:
11500 The return value is a scalar of type @code{INTEGER} and of the default
11503 @item @emph{See also}:
11504 @ref{SELECTED_REAL_KIND}
11506 @item @emph{Example}:
11509 print *, "The radix for the default integer kind is", radix(0)
11510 print *, "The radix for the default real kind is", radix(0.0)
11511 end program test_radix
11519 @section @code{RAN} --- Real pseudo-random number
11521 @cindex random number generation
11524 @item @emph{Description}:
11525 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
11526 provided as an alias for @code{RAND}. See @ref{RAND} for complete
11529 @item @emph{Standard}:
11532 @item @emph{Class}:
11535 @item @emph{See also}:
11536 @ref{RAND}, @ref{RANDOM_NUMBER}
11542 @section @code{RAND} --- Real pseudo-random number
11544 @cindex random number generation
11547 @item @emph{Description}:
11548 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
11549 distribution between 0 and 1. If @var{FLAG} is 0, the next number
11550 in the current sequence is returned; if @var{FLAG} is 1, the generator
11551 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
11552 it is used as a new seed with @code{SRAND}.
11554 This intrinsic routine is provided for backwards compatibility with
11555 GNU Fortran 77. It implements a simple modulo generator as provided
11556 by @command{g77}. For new code, one should consider the use of
11557 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
11559 @item @emph{Standard}:
11562 @item @emph{Class}:
11565 @item @emph{Syntax}:
11566 @code{RESULT = RAND(I)}
11568 @item @emph{Arguments}:
11569 @multitable @columnfractions .15 .70
11570 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
11573 @item @emph{Return value}:
11574 The return value is of @code{REAL} type and the default kind.
11576 @item @emph{Example}:
11579 integer,parameter :: seed = 86456
11582 print *, rand(), rand(), rand(), rand()
11583 print *, rand(seed), rand(), rand(), rand()
11584 end program test_rand
11587 @item @emph{See also}:
11588 @ref{SRAND}, @ref{RANDOM_NUMBER}
11594 @node RANDOM_NUMBER
11595 @section @code{RANDOM_NUMBER} --- Pseudo-random number
11596 @fnindex RANDOM_NUMBER
11597 @cindex random number generation
11600 @item @emph{Description}:
11601 Returns a single pseudorandom number or an array of pseudorandom numbers
11602 from the uniform distribution over the range @math{ 0 \leq x < 1}.
11604 The runtime-library implements the xorshift1024* random number
11605 generator (RNG). This generator has a period of @math{2^{1024} - 1},
11606 and when using multiple threads up to @math{2^{512}} threads can each
11607 generate @math{2^{512}} random numbers before any aliasing occurs.
11609 Note that in a multi-threaded program (e.g. using OpenMP directives),
11610 each thread will have its own random number state. For details of the
11611 seeding procedure, see the documentation for the @code{RANDOM_SEED}
11615 @item @emph{Standard}:
11616 Fortran 95 and later
11618 @item @emph{Class}:
11621 @item @emph{Syntax}:
11622 @code{RANDOM_NUMBER(HARVEST)}
11624 @item @emph{Arguments}:
11625 @multitable @columnfractions .15 .70
11626 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
11629 @item @emph{Example}:
11631 program test_random_number
11633 CALL RANDOM_NUMBER(r)
11637 @item @emph{See also}:
11644 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
11645 @fnindex RANDOM_SEED
11646 @cindex random number generation, seeding
11647 @cindex seeding a random number generator
11650 @item @emph{Description}:
11651 Restarts or queries the state of the pseudorandom number generator used by
11652 @code{RANDOM_NUMBER}.
11654 If @code{RANDOM_SEED} is called without arguments, it is seeded with
11655 random data retrieved from the operating system.
11657 As an extension to the Fortran standard, the GFortran
11658 @code{RANDOM_NUMBER} supports multiple threads. Each thread in a
11659 multi-threaded program has its own seed. When @code{RANDOM_SEED} is
11660 called either without arguments or with the @var{PUT} argument, the
11661 given seed is copied into a master seed as well as the seed of the
11662 current thread. When a new thread uses @code{RANDOM_NUMBER} for the
11663 first time, the seed is copied from the master seed, and forwarded
11664 @math{N * 2^{512}} steps to guarantee that the random stream does not
11665 alias any other stream in the system, where @var{N} is the number of
11666 threads that have used @code{RANDOM_NUMBER} so far during the program
11669 @item @emph{Standard}:
11670 Fortran 95 and later
11672 @item @emph{Class}:
11675 @item @emph{Syntax}:
11676 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
11678 @item @emph{Arguments}:
11679 @multitable @columnfractions .15 .70
11680 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
11681 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
11682 of the arrays used with the @var{PUT} and @var{GET} arguments.
11683 @item @var{PUT} @tab (Optional) Shall be an array of type default
11684 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
11685 the array must be larger than or equal to the number returned by the
11686 @var{SIZE} argument.
11687 @item @var{GET} @tab (Optional) Shall be an array of type default
11688 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
11689 of the array must be larger than or equal to the number returned by
11690 the @var{SIZE} argument.
11693 @item @emph{Example}:
11695 program test_random_seed
11697 integer, allocatable :: seed(:)
11700 call random_seed(size = n)
11702 call random_seed(get=seed)
11704 end program test_random_seed
11707 @item @emph{See also}:
11708 @ref{RANDOM_NUMBER}
11714 @section @code{RANGE} --- Decimal exponent range
11716 @cindex model representation, range
11719 @item @emph{Description}:
11720 @code{RANGE(X)} returns the decimal exponent range in the model of the
11723 @item @emph{Standard}:
11724 Fortran 95 and later
11726 @item @emph{Class}:
11729 @item @emph{Syntax}:
11730 @code{RESULT = RANGE(X)}
11732 @item @emph{Arguments}:
11733 @multitable @columnfractions .15 .70
11734 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
11738 @item @emph{Return value}:
11739 The return value is of type @code{INTEGER} and of the default integer
11742 @item @emph{See also}:
11743 @ref{SELECTED_REAL_KIND}, @ref{PRECISION}
11745 @item @emph{Example}:
11746 See @code{PRECISION} for an example.
11752 @section @code{RANK} --- Rank of a data object
11757 @item @emph{Description}:
11758 @code{RANK(A)} returns the rank of a scalar or array data object.
11760 @item @emph{Standard}:
11761 Technical Specification (TS) 29113
11763 @item @emph{Class}:
11766 @item @emph{Syntax}:
11767 @code{RESULT = RANK(A)}
11769 @item @emph{Arguments}:
11770 @multitable @columnfractions .15 .70
11771 @item @var{A} @tab can be of any type
11774 @item @emph{Return value}:
11775 The return value is of type @code{INTEGER} and of the default integer
11776 kind. For arrays, their rank is returned; for scalars zero is returned.
11778 @item @emph{Example}:
11782 real, allocatable :: b(:,:)
11784 print *, rank(a), rank(b) ! Prints: 0 2
11785 end program test_rank
11793 @section @code{REAL} --- Convert to real type
11802 @cindex conversion, to real
11803 @cindex complex numbers, real part
11806 @item @emph{Description}:
11807 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
11808 @code{REALPART} function is provided for compatibility with @command{g77},
11809 and its use is strongly discouraged.
11811 @item @emph{Standard}:
11812 Fortran 77 and later
11814 @item @emph{Class}:
11817 @item @emph{Syntax}:
11818 @multitable @columnfractions .80
11819 @item @code{RESULT = REAL(A [, KIND])}
11820 @item @code{RESULT = REALPART(Z)}
11823 @item @emph{Arguments}:
11824 @multitable @columnfractions .15 .70
11825 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
11827 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11828 expression indicating the kind parameter of the result.
11831 @item @emph{Return value}:
11832 These functions return a @code{REAL} variable or array under
11833 the following rules:
11837 @code{REAL(A)} is converted to a default real type if @var{A} is an
11838 integer or real variable.
11840 @code{REAL(A)} is converted to a real type with the kind type parameter
11841 of @var{A} if @var{A} is a complex variable.
11843 @code{REAL(A, KIND)} is converted to a real type with kind type
11844 parameter @var{KIND} if @var{A} is a complex, integer, or real
11848 @item @emph{Example}:
11851 complex :: x = (1.0, 2.0)
11852 print *, real(x), real(x,8), realpart(x)
11853 end program test_real
11856 @item @emph{Specific names}:
11857 @multitable @columnfractions .20 .20 .20 .25
11858 @item Name @tab Argument @tab Return type @tab Standard
11859 @item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later
11860 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension
11861 @item @code{FLOATI(A)} @tab @code{INTEGER(2)} @tab @code{REAL(4)} @tab GNU extension
11862 @item @code{FLOATJ(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab GNU extension
11863 @item @code{FLOATK(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab GNU extension
11864 @item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab Fortran 77 and later
11868 @item @emph{See also}:
11876 @section @code{RENAME} --- Rename a file
11878 @cindex file system, rename file
11881 @item @emph{Description}:
11882 Renames a file from file @var{PATH1} to @var{PATH2}. A null
11883 character (@code{CHAR(0)}) can be used to mark the end of the names in
11884 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
11885 names are ignored. If the @var{STATUS} argument is supplied, it
11886 contains 0 on success or a nonzero error code upon return; see
11889 This intrinsic is provided in both subroutine and function forms;
11890 however, only one form can be used in any given program unit.
11892 @item @emph{Standard}:
11895 @item @emph{Class}:
11896 Subroutine, function
11898 @item @emph{Syntax}:
11899 @multitable @columnfractions .80
11900 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
11901 @item @code{STATUS = RENAME(PATH1, PATH2)}
11904 @item @emph{Arguments}:
11905 @multitable @columnfractions .15 .70
11906 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
11907 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
11908 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11911 @item @emph{See also}:
11919 @section @code{REPEAT} --- Repeated string concatenation
11921 @cindex string, repeat
11922 @cindex string, concatenate
11925 @item @emph{Description}:
11926 Concatenates @var{NCOPIES} copies of a string.
11928 @item @emph{Standard}:
11929 Fortran 95 and later
11931 @item @emph{Class}:
11932 Transformational function
11934 @item @emph{Syntax}:
11935 @code{RESULT = REPEAT(STRING, NCOPIES)}
11937 @item @emph{Arguments}:
11938 @multitable @columnfractions .15 .70
11939 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
11940 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
11943 @item @emph{Return value}:
11944 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
11947 @item @emph{Example}:
11949 program test_repeat
11950 write(*,*) repeat("x", 5) ! "xxxxx"
11958 @section @code{RESHAPE} --- Function to reshape an array
11960 @cindex array, change dimensions
11961 @cindex array, transmogrify
11964 @item @emph{Description}:
11965 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
11966 the new array may be padded with elements from @var{PAD} or permuted
11967 as defined by @var{ORDER}.
11969 @item @emph{Standard}:
11970 Fortran 95 and later
11972 @item @emph{Class}:
11973 Transformational function
11975 @item @emph{Syntax}:
11976 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
11978 @item @emph{Arguments}:
11979 @multitable @columnfractions .15 .70
11980 @item @var{SOURCE} @tab Shall be an array of any type.
11981 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
11982 array of rank one. Its values must be positive or zero.
11983 @item @var{PAD} @tab (Optional) shall be an array of the same
11984 type as @var{SOURCE}.
11985 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
11986 and an array of the same shape as @var{SHAPE}. Its values shall
11987 be a permutation of the numbers from 1 to n, where n is the size of
11988 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
11992 @item @emph{Return value}:
11993 The result is an array of shape @var{SHAPE} with the same type as
11996 @item @emph{Example}:
11998 PROGRAM test_reshape
11999 INTEGER, DIMENSION(4) :: x
12000 WRITE(*,*) SHAPE(x) ! prints "4"
12001 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
12005 @item @emph{See also}:
12012 @section @code{RRSPACING} --- Reciprocal of the relative spacing
12014 @cindex real number, relative spacing
12015 @cindex floating point, relative spacing
12019 @item @emph{Description}:
12020 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
12021 model numbers near @var{X}.
12023 @item @emph{Standard}:
12024 Fortran 95 and later
12026 @item @emph{Class}:
12029 @item @emph{Syntax}:
12030 @code{RESULT = RRSPACING(X)}
12032 @item @emph{Arguments}:
12033 @multitable @columnfractions .15 .70
12034 @item @var{X} @tab Shall be of type @code{REAL}.
12037 @item @emph{Return value}:
12038 The return value is of the same type and kind as @var{X}.
12039 The value returned is equal to
12040 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
12042 @item @emph{See also}:
12049 @section @code{RSHIFT} --- Right shift bits
12051 @cindex bits, shift right
12054 @item @emph{Description}:
12055 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
12056 bits shifted right by @var{SHIFT} places. If the absolute value of
12057 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12058 Bits shifted out from the right end are lost. The fill is arithmetic: the
12059 bits shifted in from the left end are equal to the leftmost bit, which in
12060 two's complement representation is the sign bit.
12062 This function has been superseded by the @code{SHIFTA} intrinsic, which
12063 is standard in Fortran 2008 and later.
12065 @item @emph{Standard}:
12068 @item @emph{Class}:
12071 @item @emph{Syntax}:
12072 @code{RESULT = RSHIFT(I, SHIFT)}
12074 @item @emph{Arguments}:
12075 @multitable @columnfractions .15 .70
12076 @item @var{I} @tab The type shall be @code{INTEGER}.
12077 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12080 @item @emph{Return value}:
12081 The return value is of type @code{INTEGER} and of the same kind as
12084 @item @emph{See also}:
12085 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}, @ref{SHIFTA}, @ref{SHIFTR},
12093 @section @code{SAME_TYPE_AS} --- Query dynamic types for equality
12094 @fnindex SAME_TYPE_AS
12097 @item @emph{Description}:
12098 Query dynamic types for equality.
12100 @item @emph{Standard}:
12101 Fortran 2003 and later
12103 @item @emph{Class}:
12106 @item @emph{Syntax}:
12107 @code{RESULT = SAME_TYPE_AS(A, B)}
12109 @item @emph{Arguments}:
12110 @multitable @columnfractions .15 .70
12111 @item @var{A} @tab Shall be an object of extensible declared type or
12112 unlimited polymorphic.
12113 @item @var{B} @tab Shall be an object of extensible declared type or
12114 unlimited polymorphic.
12117 @item @emph{Return value}:
12118 The return value is a scalar of type default logical. It is true if and
12119 only if the dynamic type of A is the same as the dynamic type of B.
12121 @item @emph{See also}:
12122 @ref{EXTENDS_TYPE_OF}
12129 @section @code{SCALE} --- Scale a real value
12131 @cindex real number, scale
12132 @cindex floating point, scale
12135 @item @emph{Description}:
12136 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
12138 @item @emph{Standard}:
12139 Fortran 95 and later
12141 @item @emph{Class}:
12144 @item @emph{Syntax}:
12145 @code{RESULT = SCALE(X, I)}
12147 @item @emph{Arguments}:
12148 @multitable @columnfractions .15 .70
12149 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
12150 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
12153 @item @emph{Return value}:
12154 The return value is of the same type and kind as @var{X}.
12155 Its value is @code{X * RADIX(X)**I}.
12157 @item @emph{Example}:
12160 real :: x = 178.1387e-4
12162 print *, scale(x,i), x*radix(x)**i
12163 end program test_scale
12171 @section @code{SCAN} --- Scan a string for the presence of a set of characters
12173 @cindex string, find subset
12176 @item @emph{Description}:
12177 Scans a @var{STRING} for any of the characters in a @var{SET}
12180 If @var{BACK} is either absent or equals @code{FALSE}, this function
12181 returns the position of the leftmost character of @var{STRING} that is
12182 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
12183 is returned. If no character of @var{SET} is found in @var{STRING}, the
12186 @item @emph{Standard}:
12187 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12189 @item @emph{Class}:
12192 @item @emph{Syntax}:
12193 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
12195 @item @emph{Arguments}:
12196 @multitable @columnfractions .15 .70
12197 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
12198 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
12199 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
12200 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12201 expression indicating the kind parameter of the result.
12204 @item @emph{Return value}:
12205 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12206 @var{KIND} is absent, the return value is of default integer kind.
12208 @item @emph{Example}:
12211 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
12212 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
12213 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
12217 @item @emph{See also}:
12218 @ref{INDEX intrinsic}, @ref{VERIFY}
12224 @section @code{SECNDS} --- Time function
12226 @cindex time, elapsed
12227 @cindex elapsed time
12230 @item @emph{Description}:
12231 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
12232 @var{X} is a reference time, also in seconds. If this is zero, the time in
12233 seconds from midnight is returned. This function is non-standard and its
12234 use is discouraged.
12236 @item @emph{Standard}:
12239 @item @emph{Class}:
12242 @item @emph{Syntax}:
12243 @code{RESULT = SECNDS (X)}
12245 @item @emph{Arguments}:
12246 @multitable @columnfractions .15 .70
12247 @item @var{T} @tab Shall be of type @code{REAL(4)}.
12248 @item @var{X} @tab Shall be of type @code{REAL(4)}.
12251 @item @emph{Return value}:
12254 @item @emph{Example}:
12256 program test_secnds
12259 print *, secnds (0.0) ! seconds since midnight
12260 t1 = secnds (0.0) ! reference time
12261 do i = 1, 10000000 ! do something
12263 t2 = secnds (t1) ! elapsed time
12264 print *, "Something took ", t2, " seconds."
12265 end program test_secnds
12272 @section @code{SECOND} --- CPU time function
12274 @cindex time, elapsed
12275 @cindex elapsed time
12278 @item @emph{Description}:
12279 Returns a @code{REAL(4)} value representing the elapsed CPU time in
12280 seconds. This provides the same functionality as the standard
12281 @code{CPU_TIME} intrinsic, and is only included for backwards
12284 This intrinsic is provided in both subroutine and function forms;
12285 however, only one form can be used in any given program unit.
12287 @item @emph{Standard}:
12290 @item @emph{Class}:
12291 Subroutine, function
12293 @item @emph{Syntax}:
12294 @multitable @columnfractions .80
12295 @item @code{CALL SECOND(TIME)}
12296 @item @code{TIME = SECOND()}
12299 @item @emph{Arguments}:
12300 @multitable @columnfractions .15 .70
12301 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
12304 @item @emph{Return value}:
12305 In either syntax, @var{TIME} is set to the process's current runtime in
12308 @item @emph{See also}:
12315 @node SELECTED_CHAR_KIND
12316 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
12317 @fnindex SELECTED_CHAR_KIND
12318 @cindex character kind
12319 @cindex kind, character
12322 @item @emph{Description}:
12324 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
12325 set named @var{NAME}, if a character set with such a name is supported,
12326 or @math{-1} otherwise. Currently, supported character sets include
12327 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
12328 (Universal Character Set, UCS-4) which is commonly known as Unicode.
12330 @item @emph{Standard}:
12331 Fortran 2003 and later
12333 @item @emph{Class}:
12334 Transformational function
12336 @item @emph{Syntax}:
12337 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
12339 @item @emph{Arguments}:
12340 @multitable @columnfractions .15 .70
12341 @item @var{NAME} @tab Shall be a scalar and of the default character type.
12344 @item @emph{Example}:
12346 program character_kind
12347 use iso_fortran_env
12349 integer, parameter :: ascii = selected_char_kind ("ascii")
12350 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646')
12352 character(kind=ascii, len=26) :: alphabet
12353 character(kind=ucs4, len=30) :: hello_world
12355 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
12356 hello_world = ucs4_'Hello World and Ni Hao -- ' &
12357 // char (int (z'4F60'), ucs4) &
12358 // char (int (z'597D'), ucs4)
12360 write (*,*) alphabet
12362 open (output_unit, encoding='UTF-8')
12363 write (*,*) trim (hello_world)
12364 end program character_kind
12370 @node SELECTED_INT_KIND
12371 @section @code{SELECTED_INT_KIND} --- Choose integer kind
12372 @fnindex SELECTED_INT_KIND
12373 @cindex integer kind
12374 @cindex kind, integer
12377 @item @emph{Description}:
12378 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
12379 type that can represent all values ranging from @math{-10^R} (exclusive)
12380 to @math{10^R} (exclusive). If there is no integer kind that accommodates
12381 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
12383 @item @emph{Standard}:
12384 Fortran 95 and later
12386 @item @emph{Class}:
12387 Transformational function
12389 @item @emph{Syntax}:
12390 @code{RESULT = SELECTED_INT_KIND(R)}
12392 @item @emph{Arguments}:
12393 @multitable @columnfractions .15 .70
12394 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
12397 @item @emph{Example}:
12399 program large_integers
12400 integer,parameter :: k5 = selected_int_kind(5)
12401 integer,parameter :: k15 = selected_int_kind(15)
12402 integer(kind=k5) :: i5
12403 integer(kind=k15) :: i15
12405 print *, huge(i5), huge(i15)
12407 ! The following inequalities are always true
12408 print *, huge(i5) >= 10_k5**5-1
12409 print *, huge(i15) >= 10_k15**15-1
12410 end program large_integers
12416 @node SELECTED_REAL_KIND
12417 @section @code{SELECTED_REAL_KIND} --- Choose real kind
12418 @fnindex SELECTED_REAL_KIND
12421 @cindex radix, real
12424 @item @emph{Description}:
12425 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
12426 with decimal precision of at least @code{P} digits, exponent range of
12427 at least @code{R}, and with a radix of @code{RADIX}.
12429 @item @emph{Standard}:
12430 Fortran 95 and later, with @code{RADIX} Fortran 2008 or later
12432 @item @emph{Class}:
12433 Transformational function
12435 @item @emph{Syntax}:
12436 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
12438 @item @emph{Arguments}:
12439 @multitable @columnfractions .15 .70
12440 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12441 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12442 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12444 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
12445 be present; since Fortran 2008, they are assumed to be zero if absent.
12447 @item @emph{Return value}:
12449 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
12450 a real data type with decimal precision of at least @code{P} digits, a
12451 decimal exponent range of at least @code{R}, and with the requested
12452 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
12453 any radix can be returned. If more than one real data type meet the
12454 criteria, the kind of the data type with the smallest decimal precision
12455 is returned. If no real data type matches the criteria, the result is
12457 @item -1 if the processor does not support a real data type with a
12458 precision greater than or equal to @code{P}, but the @code{R} and
12459 @code{RADIX} requirements can be fulfilled
12460 @item -2 if the processor does not support a real type with an exponent
12461 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
12463 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
12465 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
12467 @item -5 if there is no real type with the given @code{RADIX}
12470 @item @emph{See also}:
12471 @ref{PRECISION}, @ref{RANGE}, @ref{RADIX}
12473 @item @emph{Example}:
12476 integer,parameter :: p6 = selected_real_kind(6)
12477 integer,parameter :: p10r100 = selected_real_kind(10,100)
12478 integer,parameter :: r400 = selected_real_kind(r=400)
12480 real(kind=p10r100) :: y
12481 real(kind=r400) :: z
12483 print *, precision(x), range(x)
12484 print *, precision(y), range(y)
12485 print *, precision(z), range(z)
12486 end program real_kinds
12493 @section @code{SET_EXPONENT} --- Set the exponent of the model
12494 @fnindex SET_EXPONENT
12495 @cindex real number, set exponent
12496 @cindex floating point, set exponent
12499 @item @emph{Description}:
12500 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
12501 is that that of @var{X} and whose exponent part is @var{I}.
12503 @item @emph{Standard}:
12504 Fortran 95 and later
12506 @item @emph{Class}:
12509 @item @emph{Syntax}:
12510 @code{RESULT = SET_EXPONENT(X, I)}
12512 @item @emph{Arguments}:
12513 @multitable @columnfractions .15 .70
12514 @item @var{X} @tab Shall be of type @code{REAL}.
12515 @item @var{I} @tab Shall be of type @code{INTEGER}.
12518 @item @emph{Return value}:
12519 The return value is of the same type and kind as @var{X}.
12520 The real number whose fractional part
12521 is that that of @var{X} and whose exponent part if @var{I} is returned;
12522 it is @code{FRACTION(X) * RADIX(X)**I}.
12524 @item @emph{Example}:
12526 PROGRAM test_setexp
12527 REAL :: x = 178.1387e-4
12529 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
12538 @section @code{SHAPE} --- Determine the shape of an array
12540 @cindex array, shape
12543 @item @emph{Description}:
12544 Determines the shape of an array.
12546 @item @emph{Standard}:
12547 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12549 @item @emph{Class}:
12552 @item @emph{Syntax}:
12553 @code{RESULT = SHAPE(SOURCE [, KIND])}
12555 @item @emph{Arguments}:
12556 @multitable @columnfractions .15 .70
12557 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
12558 If @var{SOURCE} is a pointer it must be associated and allocatable
12559 arrays must be allocated.
12560 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12561 expression indicating the kind parameter of the result.
12564 @item @emph{Return value}:
12565 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
12566 has dimensions. The elements of the resulting array correspond to the extend
12567 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
12568 the result is the rank one array of size zero. If @var{KIND} is absent, the
12569 return value has the default integer kind otherwise the specified kind.
12571 @item @emph{Example}:
12574 INTEGER, DIMENSION(-1:1, -1:2) :: A
12575 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
12576 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
12580 @item @emph{See also}:
12581 @ref{RESHAPE}, @ref{SIZE}
12587 @section @code{SHIFTA} --- Right shift with fill
12589 @cindex bits, shift right
12590 @cindex shift, right with fill
12593 @item @emph{Description}:
12594 @code{SHIFTA} returns a value corresponding to @var{I} with all of the
12595 bits shifted right by @var{SHIFT} places. If the absolute value of
12596 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12597 Bits shifted out from the right end are lost. The fill is arithmetic: the
12598 bits shifted in from the left end are equal to the leftmost bit, which in
12599 two's complement representation is the sign bit.
12601 @item @emph{Standard}:
12602 Fortran 2008 and later
12604 @item @emph{Class}:
12607 @item @emph{Syntax}:
12608 @code{RESULT = SHIFTA(I, SHIFT)}
12610 @item @emph{Arguments}:
12611 @multitable @columnfractions .15 .70
12612 @item @var{I} @tab The type shall be @code{INTEGER}.
12613 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12616 @item @emph{Return value}:
12617 The return value is of type @code{INTEGER} and of the same kind as
12620 @item @emph{See also}:
12621 @ref{SHIFTL}, @ref{SHIFTR}
12627 @section @code{SHIFTL} --- Left shift
12629 @cindex bits, shift left
12630 @cindex shift, left
12633 @item @emph{Description}:
12634 @code{SHIFTL} returns a value corresponding to @var{I} with all of the
12635 bits shifted left by @var{SHIFT} places. If the absolute value of
12636 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12637 Bits shifted out from the left end are lost, and bits shifted in from
12638 the right end are set to 0.
12640 @item @emph{Standard}:
12641 Fortran 2008 and later
12643 @item @emph{Class}:
12646 @item @emph{Syntax}:
12647 @code{RESULT = SHIFTL(I, SHIFT)}
12649 @item @emph{Arguments}:
12650 @multitable @columnfractions .15 .70
12651 @item @var{I} @tab The type shall be @code{INTEGER}.
12652 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12655 @item @emph{Return value}:
12656 The return value is of type @code{INTEGER} and of the same kind as
12659 @item @emph{See also}:
12660 @ref{SHIFTA}, @ref{SHIFTR}
12666 @section @code{SHIFTR} --- Right shift
12668 @cindex bits, shift right
12669 @cindex shift, right
12672 @item @emph{Description}:
12673 @code{SHIFTR} returns a value corresponding to @var{I} with all of the
12674 bits shifted right by @var{SHIFT} places. If the absolute value of
12675 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12676 Bits shifted out from the right end are lost, and bits shifted in from
12677 the left end are set to 0.
12679 @item @emph{Standard}:
12680 Fortran 2008 and later
12682 @item @emph{Class}:
12685 @item @emph{Syntax}:
12686 @code{RESULT = SHIFTR(I, SHIFT)}
12688 @item @emph{Arguments}:
12689 @multitable @columnfractions .15 .70
12690 @item @var{I} @tab The type shall be @code{INTEGER}.
12691 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12694 @item @emph{Return value}:
12695 The return value is of type @code{INTEGER} and of the same kind as
12698 @item @emph{See also}:
12699 @ref{SHIFTA}, @ref{SHIFTL}
12705 @section @code{SIGN} --- Sign copying function
12709 @cindex sign copying
12712 @item @emph{Description}:
12713 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
12715 @item @emph{Standard}:
12716 Fortran 77 and later
12718 @item @emph{Class}:
12721 @item @emph{Syntax}:
12722 @code{RESULT = SIGN(A, B)}
12724 @item @emph{Arguments}:
12725 @multitable @columnfractions .15 .70
12726 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
12727 @item @var{B} @tab Shall be of the same type and kind as @var{A}
12730 @item @emph{Return value}:
12731 The kind of the return value is that of @var{A} and @var{B}.
12732 If @math{B\ge 0} then the result is @code{ABS(A)}, else
12733 it is @code{-ABS(A)}.
12735 @item @emph{Example}:
12738 print *, sign(-12,1)
12739 print *, sign(-12,0)
12740 print *, sign(-12,-1)
12742 print *, sign(-12.,1.)
12743 print *, sign(-12.,0.)
12744 print *, sign(-12.,-1.)
12745 end program test_sign
12748 @item @emph{Specific names}:
12749 @multitable @columnfractions .20 .20 .20 .25
12750 @item Name @tab Arguments @tab Return type @tab Standard
12751 @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu
12752 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
12753 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu
12760 @section @code{SIGNAL} --- Signal handling subroutine (or function)
12762 @cindex system, signal handling
12765 @item @emph{Description}:
12766 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
12767 @var{HANDLER} to be executed with a single integer argument when signal
12768 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
12769 turn off handling of signal @var{NUMBER} or revert to its default
12770 action. See @code{signal(2)}.
12772 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
12773 is supplied, it is set to the value returned by @code{signal(2)}.
12775 @item @emph{Standard}:
12778 @item @emph{Class}:
12779 Subroutine, function
12781 @item @emph{Syntax}:
12782 @multitable @columnfractions .80
12783 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
12784 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
12787 @item @emph{Arguments}:
12788 @multitable @columnfractions .15 .70
12789 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
12790 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
12791 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
12792 @code{INTEGER}. It is @code{INTENT(IN)}.
12793 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
12794 integer. It has @code{INTENT(OUT)}.
12796 @c TODO: What should the interface of the handler be? Does it take arguments?
12798 @item @emph{Return value}:
12799 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
12801 @item @emph{Example}:
12803 program test_signal
12805 external handler_print
12807 call signal (12, handler_print)
12808 call signal (10, 1)
12811 end program test_signal
12818 @section @code{SIN} --- Sine function
12824 @cindex trigonometric function, sine
12828 @item @emph{Description}:
12829 @code{SIN(X)} computes the sine of @var{X}.
12831 @item @emph{Standard}:
12832 Fortran 77 and later
12834 @item @emph{Class}:
12837 @item @emph{Syntax}:
12838 @code{RESULT = SIN(X)}
12840 @item @emph{Arguments}:
12841 @multitable @columnfractions .15 .70
12842 @item @var{X} @tab The type shall be @code{REAL} or
12846 @item @emph{Return value}:
12847 The return value has same type and kind as @var{X}.
12849 @item @emph{Example}:
12854 end program test_sin
12857 @item @emph{Specific names}:
12858 @multitable @columnfractions .20 .20 .20 .25
12859 @item Name @tab Argument @tab Return type @tab Standard
12860 @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu
12861 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
12862 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
12863 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
12864 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
12867 @item @emph{See also}:
12868 Inverse function: @ref{ASIN}
12869 Degrees function: @ref{SIND}
12875 @section @code{SIND} --- Sine function, degrees
12881 @cindex trigonometric function, sine, degrees
12882 @cindex sine, degrees
12885 @item @emph{Description}:
12886 @code{SIND(X)} computes the sine of @var{X} in degrees.
12888 This function is for compatibility only and should be avoided in favor of
12889 standard constructs wherever possible.
12891 @item @emph{Standard}:
12892 GNU Extension, enabled with @option{-fdec-math}.
12894 @item @emph{Class}:
12897 @item @emph{Syntax}:
12898 @code{RESULT = SIND(X)}
12900 @item @emph{Arguments}:
12901 @multitable @columnfractions .15 .70
12902 @item @var{X} @tab The type shall be @code{REAL} or
12906 @item @emph{Return value}:
12907 The return value has same type and kind as @var{X}, and its value is in degrees.
12909 @item @emph{Example}:
12914 end program test_sind
12917 @item @emph{Specific names}:
12918 @multitable @columnfractions .20 .20 .20 .25
12919 @item Name @tab Argument @tab Return type @tab Standard
12920 @item @code{SIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
12921 @item @code{DSIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
12922 @item @code{CSIND(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU Extension
12923 @item @code{ZSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU Extension
12924 @item @code{CDSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU Extension
12927 @item @emph{See also}:
12928 Inverse function: @ref{ASIND}
12929 Radians function: @ref{SIN}
12936 @section @code{SINH} --- Hyperbolic sine function
12939 @cindex hyperbolic sine
12940 @cindex hyperbolic function, sine
12941 @cindex sine, hyperbolic
12944 @item @emph{Description}:
12945 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
12947 @item @emph{Standard}:
12948 Fortran 95 and later, for a complex argument Fortran 2008 or later
12950 @item @emph{Class}:
12953 @item @emph{Syntax}:
12954 @code{RESULT = SINH(X)}
12956 @item @emph{Arguments}:
12957 @multitable @columnfractions .15 .70
12958 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
12961 @item @emph{Return value}:
12962 The return value has same type and kind as @var{X}.
12964 @item @emph{Example}:
12967 real(8) :: x = - 1.0_8
12969 end program test_sinh
12972 @item @emph{Specific names}:
12973 @multitable @columnfractions .20 .20 .20 .25
12974 @item Name @tab Argument @tab Return type @tab Standard
12975 @item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
12976 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
12979 @item @emph{See also}:
12986 @section @code{SIZE} --- Determine the size of an array
12988 @cindex array, size
12989 @cindex array, number of elements
12990 @cindex array, count elements
12993 @item @emph{Description}:
12994 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
12995 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
12997 @item @emph{Standard}:
12998 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
13000 @item @emph{Class}:
13003 @item @emph{Syntax}:
13004 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
13006 @item @emph{Arguments}:
13007 @multitable @columnfractions .15 .70
13008 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
13009 a pointer it must be associated and allocatable arrays must be allocated.
13010 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
13011 and its value shall be in the range from 1 to n, where n equals the rank
13013 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
13014 expression indicating the kind parameter of the result.
13017 @item @emph{Return value}:
13018 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
13019 @var{KIND} is absent, the return value is of default integer kind.
13021 @item @emph{Example}:
13024 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
13028 @item @emph{See also}:
13029 @ref{SHAPE}, @ref{RESHAPE}
13034 @section @code{SIZEOF} --- Size in bytes of an expression
13036 @cindex expression size
13037 @cindex size of an expression
13040 @item @emph{Description}:
13041 @code{SIZEOF(X)} calculates the number of bytes of storage the
13042 expression @code{X} occupies.
13044 @item @emph{Standard}:
13047 @item @emph{Class}:
13050 @item @emph{Syntax}:
13051 @code{N = SIZEOF(X)}
13053 @item @emph{Arguments}:
13054 @multitable @columnfractions .15 .70
13055 @item @var{X} @tab The argument shall be of any type, rank or shape.
13058 @item @emph{Return value}:
13059 The return value is of type integer and of the system-dependent kind
13060 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
13061 number of bytes occupied by the argument. If the argument has the
13062 @code{POINTER} attribute, the number of bytes of the storage area pointed
13063 to is returned. If the argument is of a derived type with @code{POINTER}
13064 or @code{ALLOCATABLE} components, the return value does not account for
13065 the sizes of the data pointed to by these components. If the argument is
13066 polymorphic, the size according to the dynamic type is returned. The argument
13067 may not be a procedure or procedure pointer. Note that the code assumes for
13068 arrays that those are contiguous; for contiguous arrays, it returns the
13069 storage or an array element multiplied by the size of the array.
13071 @item @emph{Example}:
13075 print *, (sizeof(s)/sizeof(r) == 5)
13078 The example will print @code{.TRUE.} unless you are using a platform
13079 where default @code{REAL} variables are unusually padded.
13081 @item @emph{See also}:
13082 @ref{C_SIZEOF}, @ref{STORAGE_SIZE}
13087 @section @code{SLEEP} --- Sleep for the specified number of seconds
13089 @cindex delayed execution
13092 @item @emph{Description}:
13093 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
13095 @item @emph{Standard}:
13098 @item @emph{Class}:
13101 @item @emph{Syntax}:
13102 @code{CALL SLEEP(SECONDS)}
13104 @item @emph{Arguments}:
13105 @multitable @columnfractions .15 .70
13106 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
13109 @item @emph{Example}:
13120 @section @code{SPACING} --- Smallest distance between two numbers of a given type
13122 @cindex real number, relative spacing
13123 @cindex floating point, relative spacing
13126 @item @emph{Description}:
13127 Determines the distance between the argument @var{X} and the nearest
13128 adjacent number of the same type.
13130 @item @emph{Standard}:
13131 Fortran 95 and later
13133 @item @emph{Class}:
13136 @item @emph{Syntax}:
13137 @code{RESULT = SPACING(X)}
13139 @item @emph{Arguments}:
13140 @multitable @columnfractions .15 .70
13141 @item @var{X} @tab Shall be of type @code{REAL}.
13144 @item @emph{Return value}:
13145 The result is of the same type as the input argument @var{X}.
13147 @item @emph{Example}:
13149 PROGRAM test_spacing
13150 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
13151 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
13153 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
13154 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
13158 @item @emph{See also}:
13165 @section @code{SPREAD} --- Add a dimension to an array
13167 @cindex array, increase dimension
13168 @cindex array, duplicate elements
13169 @cindex array, duplicate dimensions
13172 @item @emph{Description}:
13173 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
13174 dimension @var{DIM}.
13176 @item @emph{Standard}:
13177 Fortran 95 and later
13179 @item @emph{Class}:
13180 Transformational function
13182 @item @emph{Syntax}:
13183 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
13185 @item @emph{Arguments}:
13186 @multitable @columnfractions .15 .70
13187 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
13188 a rank less than seven.
13189 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
13190 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
13191 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
13194 @item @emph{Return value}:
13195 The result is an array of the same type as @var{SOURCE} and has rank n+1
13196 where n equals the rank of @var{SOURCE}.
13198 @item @emph{Example}:
13200 PROGRAM test_spread
13201 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
13202 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
13203 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
13207 @item @emph{See also}:
13214 @section @code{SQRT} --- Square-root function
13221 @cindex square-root
13224 @item @emph{Description}:
13225 @code{SQRT(X)} computes the square root of @var{X}.
13227 @item @emph{Standard}:
13228 Fortran 77 and later
13230 @item @emph{Class}:
13233 @item @emph{Syntax}:
13234 @code{RESULT = SQRT(X)}
13236 @item @emph{Arguments}:
13237 @multitable @columnfractions .15 .70
13238 @item @var{X} @tab The type shall be @code{REAL} or
13242 @item @emph{Return value}:
13243 The return value is of type @code{REAL} or @code{COMPLEX}.
13244 The kind type parameter is the same as @var{X}.
13246 @item @emph{Example}:
13249 real(8) :: x = 2.0_8
13250 complex :: z = (1.0, 2.0)
13253 end program test_sqrt
13256 @item @emph{Specific names}:
13257 @multitable @columnfractions .20 .20 .20 .25
13258 @item Name @tab Argument @tab Return type @tab Standard
13259 @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
13260 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
13261 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
13262 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13263 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13270 @section @code{SRAND} --- Reinitialize the random number generator
13272 @cindex random number generation, seeding
13273 @cindex seeding a random number generator
13276 @item @emph{Description}:
13277 @code{SRAND} reinitializes the pseudo-random number generator
13278 called by @code{RAND} and @code{IRAND}. The new seed used by the
13279 generator is specified by the required argument @var{SEED}.
13281 @item @emph{Standard}:
13284 @item @emph{Class}:
13287 @item @emph{Syntax}:
13288 @code{CALL SRAND(SEED)}
13290 @item @emph{Arguments}:
13291 @multitable @columnfractions .15 .70
13292 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
13295 @item @emph{Return value}:
13296 Does not return anything.
13298 @item @emph{Example}:
13299 See @code{RAND} and @code{IRAND} for examples.
13301 @item @emph{Notes}:
13302 The Fortran standard specifies the intrinsic subroutines
13303 @code{RANDOM_SEED} to initialize the pseudo-random number
13304 generator and @code{RANDOM_NUMBER} to generate pseudo-random numbers.
13305 These subroutines should be used in new codes.
13307 Please note that in GNU Fortran, these two sets of intrinsics (@code{RAND},
13308 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
13309 @code{RANDOM_SEED} on the other hand) access two independent
13310 pseudo-random number generators.
13312 @item @emph{See also}:
13313 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
13320 @section @code{STAT} --- Get file status
13322 @cindex file system, file status
13325 @item @emph{Description}:
13326 This function returns information about a file. No permissions are required on
13327 the file itself, but execute (search) permission is required on all of the
13328 directories in path that lead to the file.
13330 The elements that are obtained and stored in the array @code{VALUES}:
13331 @multitable @columnfractions .15 .70
13332 @item @code{VALUES(1)} @tab Device ID
13333 @item @code{VALUES(2)} @tab Inode number
13334 @item @code{VALUES(3)} @tab File mode
13335 @item @code{VALUES(4)} @tab Number of links
13336 @item @code{VALUES(5)} @tab Owner's uid
13337 @item @code{VALUES(6)} @tab Owner's gid
13338 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
13339 @item @code{VALUES(8)} @tab File size (bytes)
13340 @item @code{VALUES(9)} @tab Last access time
13341 @item @code{VALUES(10)} @tab Last modification time
13342 @item @code{VALUES(11)} @tab Last file status change time
13343 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
13344 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
13347 Not all these elements are relevant on all systems.
13348 If an element is not relevant, it is returned as 0.
13350 This intrinsic is provided in both subroutine and function forms; however,
13351 only one form can be used in any given program unit.
13353 @item @emph{Standard}:
13356 @item @emph{Class}:
13357 Subroutine, function
13359 @item @emph{Syntax}:
13360 @multitable @columnfractions .80
13361 @item @code{CALL STAT(NAME, VALUES [, STATUS])}
13362 @item @code{STATUS = STAT(NAME, VALUES)}
13365 @item @emph{Arguments}:
13366 @multitable @columnfractions .15 .70
13367 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
13368 default kind and a valid path within the file system.
13369 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
13370 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
13371 on success and a system specific error code otherwise.
13374 @item @emph{Example}:
13377 INTEGER, DIMENSION(13) :: buff
13380 CALL STAT("/etc/passwd", buff, status)
13382 IF (status == 0) THEN
13383 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
13384 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
13385 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
13386 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
13387 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
13388 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
13389 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
13390 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
13391 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
13392 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
13393 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
13394 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
13395 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
13400 @item @emph{See also}:
13401 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
13407 @section @code{STORAGE_SIZE} --- Storage size in bits
13408 @fnindex STORAGE_SIZE
13409 @cindex storage size
13412 @item @emph{Description}:
13413 Returns the storage size of argument @var{A} in bits.
13414 @item @emph{Standard}:
13415 Fortran 2008 and later
13416 @item @emph{Class}:
13418 @item @emph{Syntax}:
13419 @code{RESULT = STORAGE_SIZE(A [, KIND])}
13421 @item @emph{Arguments}:
13422 @multitable @columnfractions .15 .70
13423 @item @var{A} @tab Shall be a scalar or array of any type.
13424 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
13427 @item @emph{Return Value}:
13428 The result is a scalar integer with the kind type parameter specified by KIND
13429 (or default integer type if KIND is missing). The result value is the size
13430 expressed in bits for an element of an array that has the dynamic type and type
13433 @item @emph{See also}:
13434 @ref{C_SIZEOF}, @ref{SIZEOF}
13440 @section @code{SUM} --- Sum of array elements
13443 @cindex array, add elements
13444 @cindex array, conditionally add elements
13445 @cindex sum array elements
13448 @item @emph{Description}:
13449 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
13450 the corresponding element in @var{MASK} is @code{TRUE}.
13452 @item @emph{Standard}:
13453 Fortran 95 and later
13455 @item @emph{Class}:
13456 Transformational function
13458 @item @emph{Syntax}:
13459 @multitable @columnfractions .80
13460 @item @code{RESULT = SUM(ARRAY[, MASK])}
13461 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
13464 @item @emph{Arguments}:
13465 @multitable @columnfractions .15 .70
13466 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
13467 @code{REAL} or @code{COMPLEX}.
13468 @item @var{DIM} @tab (Optional) shall be a scalar of type
13469 @code{INTEGER} with a value in the range from 1 to n, where n
13470 equals the rank of @var{ARRAY}.
13471 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
13472 and either be a scalar or an array of the same shape as @var{ARRAY}.
13475 @item @emph{Return value}:
13476 The result is of the same type as @var{ARRAY}.
13478 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
13479 is returned. Otherwise, an array of rank n-1, where n equals the rank of
13480 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
13481 dropped is returned.
13483 @item @emph{Example}:
13486 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
13487 print *, SUM(x) ! all elements, sum = 15
13488 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
13492 @item @emph{See also}:
13499 @section @code{SYMLNK} --- Create a symbolic link
13501 @cindex file system, create link
13502 @cindex file system, soft link
13505 @item @emph{Description}:
13506 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
13507 character (@code{CHAR(0)}) can be used to mark the end of the names in
13508 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
13509 names are ignored. If the @var{STATUS} argument is supplied, it
13510 contains 0 on success or a nonzero error code upon return; see
13511 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
13512 @code{ENOSYS} is returned.
13514 This intrinsic is provided in both subroutine and function forms;
13515 however, only one form can be used in any given program unit.
13517 @item @emph{Standard}:
13520 @item @emph{Class}:
13521 Subroutine, function
13523 @item @emph{Syntax}:
13524 @multitable @columnfractions .80
13525 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
13526 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
13529 @item @emph{Arguments}:
13530 @multitable @columnfractions .15 .70
13531 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
13532 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
13533 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
13536 @item @emph{See also}:
13537 @ref{LINK}, @ref{UNLINK}
13544 @section @code{SYSTEM} --- Execute a shell command
13546 @cindex system, system call
13549 @item @emph{Description}:
13550 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
13551 argument @var{STATUS} is present, it contains the value returned by
13552 @code{system(3)}, which is presumably 0 if the shell command succeeded.
13553 Note that which shell is used to invoke the command is system-dependent
13554 and environment-dependent.
13556 This intrinsic is provided in both subroutine and function forms;
13557 however, only one form can be used in any given program unit.
13559 Note that the @code{system} function need not be thread-safe. It is
13560 the responsibility of the user to ensure that @code{system} is not
13561 called concurrently.
13563 @item @emph{Standard}:
13566 @item @emph{Class}:
13567 Subroutine, function
13569 @item @emph{Syntax}:
13570 @multitable @columnfractions .80
13571 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
13572 @item @code{STATUS = SYSTEM(COMMAND)}
13575 @item @emph{Arguments}:
13576 @multitable @columnfractions .15 .70
13577 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
13578 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
13581 @item @emph{See also}:
13582 @ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
13583 and should considered in new code for future portability.
13589 @section @code{SYSTEM_CLOCK} --- Time function
13590 @fnindex SYSTEM_CLOCK
13591 @cindex time, clock ticks
13592 @cindex clock ticks
13595 @item @emph{Description}:
13596 Determines the @var{COUNT} of a processor clock since an unspecified
13597 time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines
13598 the number of clock ticks per second. If the platform supports a
13599 monotonic clock, that clock is used and can, depending on the platform
13600 clock implementation, provide up to nanosecond resolution. If a
13601 monotonic clock is not available, the implementation falls back to a
13604 @var{COUNT_RATE} is system dependent and can vary depending on the kind of
13605 the arguments. For @var{kind=4} arguments (and smaller integer kinds),
13606 @var{COUNT} represents milliseconds, while for @var{kind=8} arguments (and
13607 larger integer kinds), @var{COUNT} typically represents micro- or
13608 nanoseconds depending on resolution of the underlying platform clock.
13609 @var{COUNT_MAX} usually equals @code{HUGE(COUNT_MAX)}. Note that the
13610 millisecond resolution of the @var{kind=4} version implies that the
13611 @var{COUNT} will wrap around in roughly 25 days. In order to avoid issues
13612 with the wrap around and for more precise timing, please use the
13613 @var{kind=8} version.
13615 If there is no clock, or querying the clock fails, @var{COUNT} is set
13616 to @code{-HUGE(COUNT)}, and @var{COUNT_RATE} and @var{COUNT_MAX} are
13619 When running on a platform using the GNU C library (glibc) version
13620 2.16 or older, or a derivative thereof, the high resolution monotonic
13621 clock is available only when linking with the @var{rt} library. This
13622 can be done explicitly by adding the @code{-lrt} flag when linking the
13623 application, but is also done implicitly when using OpenMP.
13625 On the Windows platform, the version with @var{kind=4} arguments uses
13626 the @code{GetTickCount} function, whereas the @var{kind=8} version
13627 uses @code{QueryPerformanceCounter} and
13628 @code{QueryPerformanceCounterFrequency}. For more information, and
13629 potential caveats, please see the platform documentation.
13631 @item @emph{Standard}:
13632 Fortran 95 and later
13634 @item @emph{Class}:
13637 @item @emph{Syntax}:
13638 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
13640 @item @emph{Arguments}:
13641 @multitable @columnfractions .15 .70
13642 @item @var{COUNT} @tab (Optional) shall be a scalar of type
13643 @code{INTEGER} with @code{INTENT(OUT)}.
13644 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type
13645 @code{INTEGER} or @code{REAL}, with @code{INTENT(OUT)}.
13646 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type
13647 @code{INTEGER} with @code{INTENT(OUT)}.
13650 @item @emph{Example}:
13652 PROGRAM test_system_clock
13653 INTEGER :: count, count_rate, count_max
13654 CALL SYSTEM_CLOCK(count, count_rate, count_max)
13655 WRITE(*,*) count, count_rate, count_max
13659 @item @emph{See also}:
13660 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
13666 @section @code{TAN} --- Tangent function
13669 @cindex trigonometric function, tangent
13673 @item @emph{Description}:
13674 @code{TAN(X)} computes the tangent of @var{X}.
13676 @item @emph{Standard}:
13677 Fortran 77 and later, for a complex argument Fortran 2008 or later
13679 @item @emph{Class}:
13682 @item @emph{Syntax}:
13683 @code{RESULT = TAN(X)}
13685 @item @emph{Arguments}:
13686 @multitable @columnfractions .15 .70
13687 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13690 @item @emph{Return value}:
13691 The return value has same type and kind as @var{X}, and its value is in radians.
13693 @item @emph{Example}:
13696 real(8) :: x = 0.165_8
13698 end program test_tan
13701 @item @emph{Specific names}:
13702 @multitable @columnfractions .20 .20 .20 .25
13703 @item Name @tab Argument @tab Return type @tab Standard
13704 @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
13705 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
13708 @item @emph{See also}:
13709 Inverse function: @ref{ATAN}
13710 Degrees function: @ref{TAND}
13716 @section @code{TAND} --- Tangent function, degrees
13719 @cindex trigonometric function, tangent, degrees
13720 @cindex tangent, degrees
13723 @item @emph{Description}:
13724 @code{TAND(X)} computes the tangent of @var{X} in degrees.
13726 This function is for compatibility only and should be avoided in favor of
13727 standard constructs wherever possible.
13729 @item @emph{Standard}:
13730 GNU Extension, enabled with @option{-fdec-math}.
13732 @item @emph{Class}:
13735 @item @emph{Syntax}:
13736 @code{RESULT = TAND(X)}
13738 @item @emph{Arguments}:
13739 @multitable @columnfractions .15 .70
13740 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13743 @item @emph{Return value}:
13744 The return value has same type and kind as @var{X}, and its value is in degrees.
13746 @item @emph{Example}:
13749 real(8) :: x = 0.165_8
13751 end program test_tand
13754 @item @emph{Specific names}:
13755 @multitable @columnfractions .20 .20 .20 .25
13756 @item Name @tab Argument @tab Return type @tab Standard
13757 @item @code{TAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
13758 @item @code{DTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
13761 @item @emph{See also}:
13762 Inverse function: @ref{ATAND}
13763 Radians function: @ref{TAN}
13769 @section @code{TANH} --- Hyperbolic tangent function
13772 @cindex hyperbolic tangent
13773 @cindex hyperbolic function, tangent
13774 @cindex tangent, hyperbolic
13777 @item @emph{Description}:
13778 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
13780 @item @emph{Standard}:
13781 Fortran 77 and later, for a complex argument Fortran 2008 or later
13783 @item @emph{Class}:
13786 @item @emph{Syntax}:
13789 @item @emph{Arguments}:
13790 @multitable @columnfractions .15 .70
13791 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13794 @item @emph{Return value}:
13795 The return value has same type and kind as @var{X}. If @var{X} is
13796 complex, the imaginary part of the result is in radians. If @var{X}
13797 is @code{REAL}, the return value lies in the range
13798 @math{ - 1 \leq tanh(x) \leq 1 }.
13800 @item @emph{Example}:
13803 real(8) :: x = 2.1_8
13805 end program test_tanh
13808 @item @emph{Specific names}:
13809 @multitable @columnfractions .20 .20 .20 .25
13810 @item Name @tab Argument @tab Return type @tab Standard
13811 @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
13812 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
13815 @item @emph{See also}:
13822 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
13823 @fnindex THIS_IMAGE
13824 @cindex coarray, @code{THIS_IMAGE}
13825 @cindex images, index of this image
13828 @item @emph{Description}:
13829 Returns the cosubscript for this image.
13831 @item @emph{Standard}:
13832 Fortran 2008 and later. With @var{DISTANCE} argument,
13833 Technical Specification (TS) 18508 or later
13835 @item @emph{Class}:
13836 Transformational function
13838 @item @emph{Syntax}:
13839 @multitable @columnfractions .80
13840 @item @code{RESULT = THIS_IMAGE()}
13841 @item @code{RESULT = THIS_IMAGE(DISTANCE)}
13842 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
13845 @item @emph{Arguments}:
13846 @multitable @columnfractions .15 .70
13847 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
13848 (not permitted together with @var{COARRAY}).
13849 @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
13850 present, required).
13851 @item @var{DIM} @tab default integer scalar (optional). If present,
13852 @var{DIM} shall be between one and the corank of @var{COARRAY}.
13856 @item @emph{Return value}:
13857 Default integer. If @var{COARRAY} is not present, it is scalar; if
13858 @var{DISTANCE} is not present or has value 0, its value is the image index on
13859 the invoking image for the current team, for values smaller or equal
13860 distance to the initial team, it returns the image index on the ancestor team
13861 which has a distance of @var{DISTANCE} from the invoking team. If
13862 @var{DISTANCE} is larger than the distance to the initial team, the image
13863 index of the initial team is returned. Otherwise when the @var{COARRAY} is
13864 present, if @var{DIM} is not present, a rank-1 array with corank elements is
13865 returned, containing the cosubscripts for @var{COARRAY} specifying the invoking
13866 image. If @var{DIM} is present, a scalar is returned, with the value of
13867 the @var{DIM} element of @code{THIS_IMAGE(COARRAY)}.
13869 @item @emph{Example}:
13871 INTEGER :: value[*]
13873 value = THIS_IMAGE()
13875 IF (THIS_IMAGE() == 1) THEN
13876 DO i = 1, NUM_IMAGES()
13877 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
13881 ! Check whether the current image is the initial image
13882 IF (THIS_IMAGE(HUGE(1)) /= THIS_IMAGE())
13883 error stop "something is rotten here"
13886 @item @emph{See also}:
13887 @ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
13893 @section @code{TIME} --- Time function
13895 @cindex time, current
13896 @cindex current time
13899 @item @emph{Description}:
13900 Returns the current time encoded as an integer (in the manner of the
13901 function @code{time(3)} in the C standard library). This value is
13902 suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}.
13904 This intrinsic is not fully portable, such as to systems with 32-bit
13905 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
13906 the values returned by this intrinsic might be, or become, negative, or
13907 numerically less than previous values, during a single run of the
13910 See @ref{TIME8}, for information on a similar intrinsic that might be
13911 portable to more GNU Fortran implementations, though to fewer Fortran
13914 @item @emph{Standard}:
13917 @item @emph{Class}:
13920 @item @emph{Syntax}:
13921 @code{RESULT = TIME()}
13923 @item @emph{Return value}:
13924 The return value is a scalar of type @code{INTEGER(4)}.
13926 @item @emph{See also}:
13927 @ref{DATE_AND_TIME}, @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
13934 @section @code{TIME8} --- Time function (64-bit)
13936 @cindex time, current
13937 @cindex current time
13940 @item @emph{Description}:
13941 Returns the current time encoded as an integer (in the manner of the
13942 function @code{time(3)} in the C standard library). This value is
13943 suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}.
13945 @emph{Warning:} this intrinsic does not increase the range of the timing
13946 values over that returned by @code{time(3)}. On a system with a 32-bit
13947 @code{time(3)}, @code{TIME8} will return a 32-bit value, even though
13948 it is converted to a 64-bit @code{INTEGER(8)} value. That means
13949 overflows of the 32-bit value can still occur. Therefore, the values
13950 returned by this intrinsic might be or become negative or numerically
13951 less than previous values during a single run of the compiled program.
13953 @item @emph{Standard}:
13956 @item @emph{Class}:
13959 @item @emph{Syntax}:
13960 @code{RESULT = TIME8()}
13962 @item @emph{Return value}:
13963 The return value is a scalar of type @code{INTEGER(8)}.
13965 @item @emph{See also}:
13966 @ref{DATE_AND_TIME}, @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
13973 @section @code{TINY} --- Smallest positive number of a real kind
13975 @cindex limits, smallest number
13976 @cindex model representation, smallest number
13979 @item @emph{Description}:
13980 @code{TINY(X)} returns the smallest positive (non zero) number
13981 in the model of the type of @code{X}.
13983 @item @emph{Standard}:
13984 Fortran 95 and later
13986 @item @emph{Class}:
13989 @item @emph{Syntax}:
13990 @code{RESULT = TINY(X)}
13992 @item @emph{Arguments}:
13993 @multitable @columnfractions .15 .70
13994 @item @var{X} @tab Shall be of type @code{REAL}.
13997 @item @emph{Return value}:
13998 The return value is of the same type and kind as @var{X}
14000 @item @emph{Example}:
14001 See @code{HUGE} for an example.
14007 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
14012 @item @emph{Description}:
14013 @code{TRAILZ} returns the number of trailing zero bits of an integer.
14015 @item @emph{Standard}:
14016 Fortran 2008 and later
14018 @item @emph{Class}:
14021 @item @emph{Syntax}:
14022 @code{RESULT = TRAILZ(I)}
14024 @item @emph{Arguments}:
14025 @multitable @columnfractions .15 .70
14026 @item @var{I} @tab Shall be of type @code{INTEGER}.
14029 @item @emph{Return value}:
14030 The type of the return value is the default @code{INTEGER}.
14031 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
14033 @item @emph{Example}:
14035 PROGRAM test_trailz
14036 WRITE (*,*) TRAILZ(8) ! prints 3
14040 @item @emph{See also}:
14041 @ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT}
14047 @section @code{TRANSFER} --- Transfer bit patterns
14053 @item @emph{Description}:
14054 Interprets the bitwise representation of @var{SOURCE} in memory as if it
14055 is the representation of a variable or array of the same type and type
14056 parameters as @var{MOLD}.
14058 This is approximately equivalent to the C concept of @emph{casting} one
14061 @item @emph{Standard}:
14062 Fortran 95 and later
14064 @item @emph{Class}:
14065 Transformational function
14067 @item @emph{Syntax}:
14068 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
14070 @item @emph{Arguments}:
14071 @multitable @columnfractions .15 .70
14072 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
14073 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
14074 @item @var{SIZE} @tab (Optional) shall be a scalar of type
14078 @item @emph{Return value}:
14079 The result has the same type as @var{MOLD}, with the bit level
14080 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
14081 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
14082 but @var{MOLD} is an array (of any size or shape), the result is a one-
14083 dimensional array of the minimum length needed to contain the entirety
14084 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
14085 and @var{MOLD} is a scalar, the result is a scalar.
14087 If the bitwise representation of the result is longer than that of
14088 @var{SOURCE}, then the leading bits of the result correspond to those of
14089 @var{SOURCE} and any trailing bits are filled arbitrarily.
14091 When the resulting bit representation does not correspond to a valid
14092 representation of a variable of the same type as @var{MOLD}, the results
14093 are undefined, and subsequent operations on the result cannot be
14094 guaranteed to produce sensible behavior. For example, it is possible to
14095 create @code{LOGICAL} variables for which @code{@var{VAR}} and
14096 @code{.NOT.@var{VAR}} both appear to be true.
14098 @item @emph{Example}:
14100 PROGRAM test_transfer
14101 integer :: x = 2143289344
14102 print *, transfer(x, 1.0) ! prints "NaN" on i686
14110 @section @code{TRANSPOSE} --- Transpose an array of rank two
14112 @cindex array, transpose
14113 @cindex matrix, transpose
14117 @item @emph{Description}:
14118 Transpose an array of rank two. Element (i, j) of the result has the value
14119 @code{MATRIX(j, i)}, for all i, j.
14121 @item @emph{Standard}:
14122 Fortran 95 and later
14124 @item @emph{Class}:
14125 Transformational function
14127 @item @emph{Syntax}:
14128 @code{RESULT = TRANSPOSE(MATRIX)}
14130 @item @emph{Arguments}:
14131 @multitable @columnfractions .15 .70
14132 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
14135 @item @emph{Return value}:
14136 The result has the same type as @var{MATRIX}, and has shape
14137 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
14143 @section @code{TRIM} --- Remove trailing blank characters of a string
14145 @cindex string, remove trailing whitespace
14148 @item @emph{Description}:
14149 Removes trailing blank characters of a string.
14151 @item @emph{Standard}:
14152 Fortran 95 and later
14154 @item @emph{Class}:
14155 Transformational function
14157 @item @emph{Syntax}:
14158 @code{RESULT = TRIM(STRING)}
14160 @item @emph{Arguments}:
14161 @multitable @columnfractions .15 .70
14162 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
14165 @item @emph{Return value}:
14166 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
14167 less the number of trailing blanks.
14169 @item @emph{Example}:
14172 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
14173 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
14177 @item @emph{See also}:
14178 @ref{ADJUSTL}, @ref{ADJUSTR}
14184 @section @code{TTYNAM} --- Get the name of a terminal device.
14186 @cindex system, terminal
14189 @item @emph{Description}:
14190 Get the name of a terminal device. For more information,
14191 see @code{ttyname(3)}.
14193 This intrinsic is provided in both subroutine and function forms;
14194 however, only one form can be used in any given program unit.
14196 @item @emph{Standard}:
14199 @item @emph{Class}:
14200 Subroutine, function
14202 @item @emph{Syntax}:
14203 @multitable @columnfractions .80
14204 @item @code{CALL TTYNAM(UNIT, NAME)}
14205 @item @code{NAME = TTYNAM(UNIT)}
14208 @item @emph{Arguments}:
14209 @multitable @columnfractions .15 .70
14210 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
14211 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
14214 @item @emph{Example}:
14216 PROGRAM test_ttynam
14219 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
14224 @item @emph{See also}:
14231 @section @code{UBOUND} --- Upper dimension bounds of an array
14233 @cindex array, upper bound
14236 @item @emph{Description}:
14237 Returns the upper bounds of an array, or a single upper bound
14238 along the @var{DIM} dimension.
14239 @item @emph{Standard}:
14240 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
14242 @item @emph{Class}:
14245 @item @emph{Syntax}:
14246 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
14248 @item @emph{Arguments}:
14249 @multitable @columnfractions .15 .70
14250 @item @var{ARRAY} @tab Shall be an array, of any type.
14251 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
14252 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
14253 expression indicating the kind parameter of the result.
14256 @item @emph{Return value}:
14257 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14258 @var{KIND} is absent, the return value is of default integer kind.
14259 If @var{DIM} is absent, the result is an array of the upper bounds of
14260 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
14261 corresponding to the upper bound of the array along that dimension. If
14262 @var{ARRAY} is an expression rather than a whole array or array
14263 structure component, or if it has a zero extent along the relevant
14264 dimension, the upper bound is taken to be the number of elements along
14265 the relevant dimension.
14267 @item @emph{See also}:
14268 @ref{LBOUND}, @ref{LCOBOUND}
14274 @section @code{UCOBOUND} --- Upper codimension bounds of an array
14276 @cindex coarray, upper bound
14279 @item @emph{Description}:
14280 Returns the upper cobounds of a coarray, or a single upper cobound
14281 along the @var{DIM} codimension.
14282 @item @emph{Standard}:
14283 Fortran 2008 and later
14285 @item @emph{Class}:
14288 @item @emph{Syntax}:
14289 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
14291 @item @emph{Arguments}:
14292 @multitable @columnfractions .15 .70
14293 @item @var{ARRAY} @tab Shall be an coarray, of any type.
14294 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
14295 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
14296 expression indicating the kind parameter of the result.
14299 @item @emph{Return value}:
14300 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14301 @var{KIND} is absent, the return value is of default integer kind.
14302 If @var{DIM} is absent, the result is an array of the lower cobounds of
14303 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
14304 corresponding to the lower cobound of the array along that codimension.
14306 @item @emph{See also}:
14307 @ref{LCOBOUND}, @ref{LBOUND}
14313 @section @code{UMASK} --- Set the file creation mask
14315 @cindex file system, file creation mask
14318 @item @emph{Description}:
14319 Sets the file creation mask to @var{MASK}. If called as a function, it
14320 returns the old value. If called as a subroutine and argument @var{OLD}
14321 if it is supplied, it is set to the old value. See @code{umask(2)}.
14323 @item @emph{Standard}:
14326 @item @emph{Class}:
14327 Subroutine, function
14329 @item @emph{Syntax}:
14330 @multitable @columnfractions .80
14331 @item @code{CALL UMASK(MASK [, OLD])}
14332 @item @code{OLD = UMASK(MASK)}
14335 @item @emph{Arguments}:
14336 @multitable @columnfractions .15 .70
14337 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
14338 @item @var{OLD} @tab (Optional) Shall be a scalar of type
14347 @section @code{UNLINK} --- Remove a file from the file system
14349 @cindex file system, remove file
14352 @item @emph{Description}:
14353 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
14354 used to mark the end of the name in @var{PATH}; otherwise, trailing
14355 blanks in the file name are ignored. If the @var{STATUS} argument is
14356 supplied, it contains 0 on success or a nonzero error code upon return;
14357 see @code{unlink(2)}.
14359 This intrinsic is provided in both subroutine and function forms;
14360 however, only one form can be used in any given program unit.
14362 @item @emph{Standard}:
14365 @item @emph{Class}:
14366 Subroutine, function
14368 @item @emph{Syntax}:
14369 @multitable @columnfractions .80
14370 @item @code{CALL UNLINK(PATH [, STATUS])}
14371 @item @code{STATUS = UNLINK(PATH)}
14374 @item @emph{Arguments}:
14375 @multitable @columnfractions .15 .70
14376 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
14377 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
14380 @item @emph{See also}:
14381 @ref{LINK}, @ref{SYMLNK}
14387 @section @code{UNPACK} --- Unpack an array of rank one into an array
14389 @cindex array, unpacking
14390 @cindex array, increase dimension
14391 @cindex array, scatter elements
14394 @item @emph{Description}:
14395 Store the elements of @var{VECTOR} in an array of higher rank.
14397 @item @emph{Standard}:
14398 Fortran 95 and later
14400 @item @emph{Class}:
14401 Transformational function
14403 @item @emph{Syntax}:
14404 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
14406 @item @emph{Arguments}:
14407 @multitable @columnfractions .15 .70
14408 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
14409 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
14410 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
14411 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
14412 the same shape as @var{MASK}.
14415 @item @emph{Return value}:
14416 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
14417 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
14419 @item @emph{Example}:
14421 PROGRAM test_unpack
14422 integer :: vector(2) = (/1,1/)
14423 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
14424 integer :: field(2,2) = 0, unity(2,2)
14426 ! result: unity matrix
14427 unity = unpack(vector, reshape(mask, (/2,2/)), field)
14431 @item @emph{See also}:
14432 @ref{PACK}, @ref{SPREAD}
14438 @section @code{VERIFY} --- Scan a string for characters not a given set
14440 @cindex string, find missing set
14443 @item @emph{Description}:
14444 Verifies that all the characters in @var{STRING} belong to the set of
14445 characters in @var{SET}.
14447 If @var{BACK} is either absent or equals @code{FALSE}, this function
14448 returns the position of the leftmost character of @var{STRING} that is
14449 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost
14450 position is returned. If all characters of @var{STRING} are found in
14451 @var{SET}, the result is zero.
14453 @item @emph{Standard}:
14454 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
14456 @item @emph{Class}:
14459 @item @emph{Syntax}:
14460 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
14462 @item @emph{Arguments}:
14463 @multitable @columnfractions .15 .70
14464 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
14465 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
14466 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
14467 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
14468 expression indicating the kind parameter of the result.
14471 @item @emph{Return value}:
14472 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14473 @var{KIND} is absent, the return value is of default integer kind.
14475 @item @emph{Example}:
14477 PROGRAM test_verify
14478 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
14479 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
14480 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
14481 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
14482 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
14486 @item @emph{See also}:
14487 @ref{SCAN}, @ref{INDEX intrinsic}
14493 @section @code{XOR} --- Bitwise logical exclusive OR
14495 @cindex bitwise logical exclusive or
14496 @cindex logical exclusive or, bitwise
14499 @item @emph{Description}:
14500 Bitwise logical exclusive or.
14502 This intrinsic routine is provided for backwards compatibility with
14503 GNU Fortran 77. For integer arguments, programmers should consider
14504 the use of the @ref{IEOR} intrinsic and for logical arguments the
14505 @code{.NEQV.} operator, which are both defined by the Fortran standard.
14507 @item @emph{Standard}:
14510 @item @emph{Class}:
14513 @item @emph{Syntax}:
14514 @code{RESULT = XOR(I, J)}
14516 @item @emph{Arguments}:
14517 @multitable @columnfractions .15 .70
14518 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
14519 type or a scalar @code{LOGICAL} type.
14520 @item @var{J} @tab The type shall be the same as the type of @var{I}.
14523 @item @emph{Return value}:
14524 The return type is either a scalar @code{INTEGER} or a scalar
14525 @code{LOGICAL}. If the kind type parameters differ, then the
14526 smaller kind type is implicitly converted to larger kind, and the
14527 return has the larger kind.
14529 @item @emph{Example}:
14532 LOGICAL :: T = .TRUE., F = .FALSE.
14534 DATA a / Z'F' /, b / Z'3' /
14536 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
14537 WRITE (*,*) XOR(a, b)
14541 @item @emph{See also}:
14542 Fortran 95 elemental function: @ref{IEOR}
14547 @node Intrinsic Modules
14548 @chapter Intrinsic Modules
14549 @cindex intrinsic Modules
14552 * ISO_FORTRAN_ENV::
14555 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
14556 * OpenACC Module OPENACC::
14559 @node ISO_FORTRAN_ENV
14560 @section @code{ISO_FORTRAN_ENV}
14562 @item @emph{Standard}:
14563 Fortran 2003 and later, except when otherwise noted
14566 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
14570 @item @code{ATOMIC_INT_KIND}:
14571 Default-kind integer constant to be used as kind parameter when defining
14572 integer variables used in atomic operations. (Fortran 2008 or later.)
14574 @item @code{ATOMIC_LOGICAL_KIND}:
14575 Default-kind integer constant to be used as kind parameter when defining
14576 logical variables used in atomic operations. (Fortran 2008 or later.)
14578 @item @code{CHARACTER_KINDS}:
14579 Default-kind integer constant array of rank one containing the supported kind
14580 parameters of the @code{CHARACTER} type. (Fortran 2008 or later.)
14582 @item @code{CHARACTER_STORAGE_SIZE}:
14583 Size in bits of the character storage unit.
14585 @item @code{ERROR_UNIT}:
14586 Identifies the preconnected unit used for error reporting.
14588 @item @code{FILE_STORAGE_SIZE}:
14589 Size in bits of the file-storage unit.
14591 @item @code{INPUT_UNIT}:
14592 Identifies the preconnected unit identified by the asterisk
14593 (@code{*}) in @code{READ} statement.
14595 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
14596 Kind type parameters to specify an INTEGER type with a storage
14597 size of 16, 32, and 64 bits. It is negative if a target platform
14598 does not support the particular kind. (Fortran 2008 or later.)
14600 @item @code{INTEGER_KINDS}:
14601 Default-kind integer constant array of rank one containing the supported kind
14602 parameters of the @code{INTEGER} type. (Fortran 2008 or later.)
14604 @item @code{IOSTAT_END}:
14605 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
14606 an input/output statement if an end-of-file condition occurred.
14608 @item @code{IOSTAT_EOR}:
14609 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
14610 an input/output statement if an end-of-record condition occurred.
14612 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
14613 Scalar default-integer constant, used by @code{INQUIRE} for the
14614 @code{IOSTAT=} specifier to denote an that a unit number identifies an
14615 internal unit. (Fortran 2008 or later.)
14617 @item @code{NUMERIC_STORAGE_SIZE}:
14618 The size in bits of the numeric storage unit.
14620 @item @code{LOGICAL_KINDS}:
14621 Default-kind integer constant array of rank one containing the supported kind
14622 parameters of the @code{LOGICAL} type. (Fortran 2008 or later.)
14624 @item @code{OUTPUT_UNIT}:
14625 Identifies the preconnected unit identified by the asterisk
14626 (@code{*}) in @code{WRITE} statement.
14628 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
14629 Kind type parameters to specify a REAL type with a storage
14630 size of 32, 64, and 128 bits. It is negative if a target platform
14631 does not support the particular kind. (Fortran 2008 or later.)
14633 @item @code{REAL_KINDS}:
14634 Default-kind integer constant array of rank one containing the supported kind
14635 parameters of the @code{REAL} type. (Fortran 2008 or later.)
14637 @item @code{STAT_LOCKED}:
14638 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
14639 denote that the lock variable is locked by the executing image. (Fortran 2008
14642 @item @code{STAT_LOCKED_OTHER_IMAGE}:
14643 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
14644 denote that the lock variable is locked by another image. (Fortran 2008 or
14647 @item @code{STAT_STOPPED_IMAGE}:
14648 Positive, scalar default-integer constant used as STAT= return value if the
14649 argument in the statement requires synchronisation with an image, which has
14650 initiated the termination of the execution. (Fortran 2008 or later.)
14652 @item @code{STAT_FAILED_IMAGE}:
14653 Positive, scalar default-integer constant used as STAT= return value if the
14654 argument in the statement requires communication with an image, which has
14655 is in the failed state. (TS 18508 or later.)
14657 @item @code{STAT_UNLOCKED}:
14658 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
14659 denote that the lock variable is unlocked. (Fortran 2008 or later.)
14662 The module provides the following derived type:
14665 @item @code{LOCK_TYPE}:
14666 Derived type with private components to be use with the @code{LOCK} and
14667 @code{UNLOCK} statement. A variable of its type has to be always declared
14668 as coarray and may not appear in a variable-definition context.
14669 (Fortran 2008 or later.)
14672 The module also provides the following intrinsic procedures:
14673 @ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}.
14677 @node ISO_C_BINDING
14678 @section @code{ISO_C_BINDING}
14680 @item @emph{Standard}:
14681 Fortran 2003 and later, GNU extensions
14684 The following intrinsic procedures are provided by the module; their
14685 definition can be found in the section Intrinsic Procedures of this
14689 @item @code{C_ASSOCIATED}
14690 @item @code{C_F_POINTER}
14691 @item @code{C_F_PROCPOINTER}
14692 @item @code{C_FUNLOC}
14694 @item @code{C_SIZEOF}
14696 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
14697 @c don't really know why.
14699 The @code{ISO_C_BINDING} module provides the following named constants of
14700 type default integer, which can be used as KIND type parameters.
14702 In addition to the integer named constants required by the Fortran 2003
14703 standard and @code{C_PTRDIFF_T} of TS 29113, GNU Fortran provides as an
14704 extension named constants for the 128-bit integer types supported by the
14705 C compiler: @code{C_INT128_T, C_INT_LEAST128_T, C_INT_FAST128_T}.
14706 Furthermore, if @code{__float128} is supported in C, the named constants
14707 @code{C_FLOAT128, C_FLOAT128_COMPLEX} are defined.
14709 @multitable @columnfractions .15 .35 .35 .35
14710 @item Fortran Type @tab Named constant @tab C type @tab Extension
14711 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
14712 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
14713 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
14714 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
14715 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
14716 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
14717 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
14718 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
14719 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
14720 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
14721 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
14722 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
14723 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
14724 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
14725 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
14726 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
14727 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
14728 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
14729 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
14730 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
14731 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
14732 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
14733 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
14734 @item @code{INTEGER}@tab @code{C_PTRDIFF_T} @tab @code{ptrdiff_t} @tab TS 29113
14735 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
14736 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
14737 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
14738 @item @code{REAL} @tab @code{C_FLOAT128} @tab @code{__float128} @tab Ext.
14739 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
14740 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
14741 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
14742 @item @code{REAL} @tab @code{C_FLOAT128_COMPLEX} @tab @code{__float128 _Complex} @tab Ext.
14743 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
14744 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
14747 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
14750 @multitable @columnfractions .20 .45 .15
14751 @item Name @tab C definition @tab Value
14752 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
14753 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
14754 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
14755 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
14756 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
14757 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
14758 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
14759 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
14762 Moreover, the following two named constants are defined:
14764 @multitable @columnfractions .20 .80
14765 @item Name @tab Type
14766 @item @code{C_NULL_PTR} @tab @code{C_PTR}
14767 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
14770 Both are equivalent to the value @code{NULL} in C.
14775 @section IEEE modules: @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
14777 @item @emph{Standard}:
14778 Fortran 2003 and later
14781 The @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
14782 intrinsic modules provide support for exceptions and IEEE arithmetic, as
14783 defined in Fortran 2003 and later standards, and the IEC 60559:1989 standard
14784 (@emph{Binary floating-point arithmetic for microprocessor systems}). These
14785 modules are only provided on the following supported platforms:
14788 @item i386 and x86_64 processors
14789 @item platforms which use the GNU C Library (glibc)
14790 @item platforms with support for SysV/386 routines for floating point
14791 interface (including Solaris and BSDs)
14792 @item platforms with the AIX OS
14795 For full compliance with the Fortran standards, code using the
14796 @code{IEEE_EXCEPTIONS} or @code{IEEE_ARITHMETIC} modules should be compiled
14797 with the following options: @code{-fno-unsafe-math-optimizations
14798 -frounding-math -fsignaling-nans}.
14802 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
14803 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
14805 @item @emph{Standard}:
14806 OpenMP Application Program Interface v4.5
14810 The OpenMP Fortran runtime library routines are provided both in
14811 a form of two Fortran 90 modules, named @code{OMP_LIB} and
14812 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
14813 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
14814 in the @ref{Top,,Introduction,libgomp,GNU Offloading and Multi
14815 Processing Runtime Library} manual,
14816 the named constants defined in the modules are listed
14819 For details refer to the actual
14820 @uref{http://www.openmp.org/wp-content/uploads/openmp-4.5.pdf,
14821 OpenMP Application Program Interface v4.5}.
14823 @code{OMP_LIB_KINDS} provides the following scalar default-integer
14827 @item @code{omp_lock_kind}
14828 @item @code{omp_nest_lock_kind}
14829 @item @code{omp_proc_bind_kind}
14830 @item @code{omp_sched_kind}
14833 @code{OMP_LIB} provides the scalar default-integer
14834 named constant @code{openmp_version} with a value of the form
14835 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
14836 of the OpenMP version; for OpenMP v4.5 the value is @code{201511}.
14838 The following scalar integer named constants of the
14839 kind @code{omp_sched_kind}:
14842 @item @code{omp_sched_static}
14843 @item @code{omp_sched_dynamic}
14844 @item @code{omp_sched_guided}
14845 @item @code{omp_sched_auto}
14848 And the following scalar integer named constants of the
14849 kind @code{omp_proc_bind_kind}:
14852 @item @code{omp_proc_bind_false}
14853 @item @code{omp_proc_bind_true}
14854 @item @code{omp_proc_bind_master}
14855 @item @code{omp_proc_bind_close}
14856 @item @code{omp_proc_bind_spread}
14861 @node OpenACC Module OPENACC
14862 @section OpenACC Module @code{OPENACC}
14864 @item @emph{Standard}:
14865 OpenACC Application Programming Interface v2.0
14869 The OpenACC Fortran runtime library routines are provided both in a
14870 form of a Fortran 90 module, named @code{OPENACC}, and in form of a
14871 Fortran @code{include} file named @file{openacc_lib.h}. The
14872 procedures provided by @code{OPENACC} can be found in the
14873 @ref{Top,,Introduction,libgomp,GNU Offloading and Multi Processing
14874 Runtime Library} manual, the named constants defined in the modules
14877 For details refer to the actual
14878 @uref{http://www.openacc.org/,
14879 OpenACC Application Programming Interface v2.0}.
14881 @code{OPENACC} provides the scalar default-integer
14882 named constant @code{openacc_version} with a value of the form
14883 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
14884 of the OpenACC version; for OpenACC v2.0 the value is @code{201306}.