2 Copyright (C) 2005-2020 Free Software Foundation, Inc.
3 This is part of the GNU Fortran manual.
4 For copying conditions, see the file gfortran.texi.
6 Permission is granted to copy, distribute and/or modify this document
7 under the terms of the GNU Free Documentation License, Version 1.3 or
8 any later version published by the Free Software Foundation; with the
9 Invariant Sections being ``Funding Free Software'', the Front-Cover
10 Texts being (a) (see below), and with the Back-Cover Texts being (b)
11 (see below). A copy of the license is included in the gfdl(7) man page.
14 Some basic guidelines for editing this document:
16 (1) The intrinsic procedures are to be listed in alphabetical order.
17 (2) The generic name is to be used.
18 (3) The specific names are included in the function index and in a
19 table at the end of the node (See ABS entry).
20 (4) Try to maintain the same style for each entry.
26 \gdef\acosd{\mathop{\rm acosd}\nolimits}
27 \gdef\asind{\mathop{\rm asind}\nolimits}
28 \gdef\atand{\mathop{\rm atand}\nolimits}
29 \gdef\acos{\mathop{\rm acos}\nolimits}
30 \gdef\asin{\mathop{\rm asin}\nolimits}
31 \gdef\atan{\mathop{\rm atan}\nolimits}
32 \gdef\acosh{\mathop{\rm acosh}\nolimits}
33 \gdef\asinh{\mathop{\rm asinh}\nolimits}
34 \gdef\atanh{\mathop{\rm atanh}\nolimits}
35 \gdef\cosd{\mathop{\rm cosd}\nolimits}
39 @node Intrinsic Procedures
40 @chapter Intrinsic Procedures
41 @cindex intrinsic procedures
44 * Introduction: Introduction to Intrinsics
45 * @code{ABORT}: ABORT, Abort the program
46 * @code{ABS}: ABS, Absolute value
47 * @code{ACCESS}: ACCESS, Checks file access modes
48 * @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence
49 * @code{ACOS}: ACOS, Arccosine function
50 * @code{ACOSD}: ACOSD, Arccosine function, degrees
51 * @code{ACOSH}: ACOSH, Inverse hyperbolic cosine function
52 * @code{ADJUSTL}: ADJUSTL, Left adjust a string
53 * @code{ADJUSTR}: ADJUSTR, Right adjust a string
54 * @code{AIMAG}: AIMAG, Imaginary part of complex number
55 * @code{AINT}: AINT, Truncate to a whole number
56 * @code{ALARM}: ALARM, Set an alarm clock
57 * @code{ALL}: ALL, Determine if all values are true
58 * @code{ALLOCATED}: ALLOCATED, Status of allocatable entity
59 * @code{AND}: AND, Bitwise logical AND
60 * @code{ANINT}: ANINT, Nearest whole number
61 * @code{ANY}: ANY, Determine if any values are true
62 * @code{ASIN}: ASIN, Arcsine function
63 * @code{ASIND}: ASIND, Arcsine function, degrees
64 * @code{ASINH}: ASINH, Inverse hyperbolic sine function
65 * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair
66 * @code{ATAN}: ATAN, Arctangent function
67 * @code{ATAND}: ATAND, Arctangent function, degrees
68 * @code{ATAN2}: ATAN2, Arctangent function
69 * @code{ATAN2D}: ATAN2D, Arctangent function, degrees
70 * @code{ATANH}: ATANH, Inverse hyperbolic tangent function
71 * @code{ATOMIC_ADD}: ATOMIC_ADD, Atomic ADD operation
72 * @code{ATOMIC_AND}: ATOMIC_AND, Atomic bitwise AND operation
73 * @code{ATOMIC_CAS}: ATOMIC_CAS, Atomic compare and swap
74 * @code{ATOMIC_DEFINE}: ATOMIC_DEFINE, Setting a variable atomically
75 * @code{ATOMIC_FETCH_ADD}: ATOMIC_FETCH_ADD, Atomic ADD operation with prior fetch
76 * @code{ATOMIC_FETCH_AND}: ATOMIC_FETCH_AND, Atomic bitwise AND operation with prior fetch
77 * @code{ATOMIC_FETCH_OR}: ATOMIC_FETCH_OR, Atomic bitwise OR operation with prior fetch
78 * @code{ATOMIC_FETCH_XOR}: ATOMIC_FETCH_XOR, Atomic bitwise XOR operation with prior fetch
79 * @code{ATOMIC_OR}: ATOMIC_OR, Atomic bitwise OR operation
80 * @code{ATOMIC_REF}: ATOMIC_REF, Obtaining the value of a variable atomically
81 * @code{ATOMIC_XOR}: ATOMIC_XOR, Atomic bitwise OR operation
82 * @code{BACKTRACE}: BACKTRACE, Show a backtrace
83 * @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0
84 * @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1
85 * @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind
86 * @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0
87 * @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1
88 * @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind
89 * @code{BGE}: BGE, Bitwise greater than or equal to
90 * @code{BGT}: BGT, Bitwise greater than
91 * @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function
92 * @code{BLE}: BLE, Bitwise less than or equal to
93 * @code{BLT}: BLT, Bitwise less than
94 * @code{BTEST}: BTEST, Bit test function
95 * @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer
96 * @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer
97 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
98 * @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure
99 * @code{C_LOC}: C_LOC, Obtain the C address of an object
100 * @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression
101 * @code{CEILING}: CEILING, Integer ceiling function
102 * @code{CHAR}: CHAR, Integer-to-character conversion function
103 * @code{CHDIR}: CHDIR, Change working directory
104 * @code{CHMOD}: CHMOD, Change access permissions of files
105 * @code{CMPLX}: CMPLX, Complex conversion function
106 * @code{CO_BROADCAST}: CO_BROADCAST, Copy a value to all images the current set of images
107 * @code{CO_MAX}: CO_MAX, Maximal value on the current set of images
108 * @code{CO_MIN}: CO_MIN, Minimal value on the current set of images
109 * @code{CO_REDUCE}: CO_REDUCE, Reduction of values on the current set of images
110 * @code{CO_SUM}: CO_SUM, Sum of values on the current set of images
111 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
112 * @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler
113 * @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string
114 * @code{COMPLEX}: COMPLEX, Complex conversion function
115 * @code{CONJG}: CONJG, Complex conjugate function
116 * @code{COS}: COS, Cosine function
117 * @code{COSD}: COSD, Cosine function, degrees
118 * @code{COSH}: COSH, Hyperbolic cosine function
119 * @code{COTAN}: COTAN, Cotangent function
120 * @code{COTAND}: COTAND, Cotangent function, degrees
121 * @code{COUNT}: COUNT, Count occurrences of TRUE in an array
122 * @code{CPU_TIME}: CPU_TIME, CPU time subroutine
123 * @code{CSHIFT}: CSHIFT, Circular shift elements of an array
124 * @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string
125 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
126 * @code{DBLE}: DBLE, Double precision conversion function
127 * @code{DCMPLX}: DCMPLX, Double complex conversion function
128 * @code{DIGITS}: DIGITS, Significant digits function
129 * @code{DIM}: DIM, Positive difference
130 * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
131 * @code{DPROD}: DPROD, Double product function
132 * @code{DREAL}: DREAL, Double real part function
133 * @code{DSHIFTL}: DSHIFTL, Combined left shift
134 * @code{DSHIFTR}: DSHIFTR, Combined right shift
135 * @code{DTIME}: DTIME, Execution time subroutine (or function)
136 * @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array
137 * @code{EPSILON}: EPSILON, Epsilon function
138 * @code{ERF}: ERF, Error function
139 * @code{ERFC}: ERFC, Complementary error function
140 * @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function
141 * @code{ETIME}: ETIME, Execution time subroutine (or function)
142 * @code{EVENT_QUERY}: EVENT_QUERY, Query whether a coarray event has occurred
143 * @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command
144 * @code{EXIT}: EXIT, Exit the program with status.
145 * @code{EXP}: EXP, Exponential function
146 * @code{EXPONENT}: EXPONENT, Exponent function
147 * @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF, Query dynamic type for extension
148 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
149 * @code{FGET}: FGET, Read a single character in stream mode from stdin
150 * @code{FGETC}: FGETC, Read a single character in stream mode
151 * @code{FINDLOC}: FINDLOC, Search an array for a value
152 * @code{FLOOR}: FLOOR, Integer floor function
153 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
154 * @code{FNUM}: FNUM, File number function
155 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
156 * @code{FPUTC}: FPUTC, Write a single character in stream mode
157 * @code{FRACTION}: FRACTION, Fractional part of the model representation
158 * @code{FREE}: FREE, Memory de-allocation subroutine
159 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
160 * @code{FSTAT}: FSTAT, Get file status
161 * @code{FTELL}: FTELL, Current stream position
162 * @code{GAMMA}: GAMMA, Gamma function
163 * @code{GERROR}: GERROR, Get last system error message
164 * @code{GETARG}: GETARG, Get command line arguments
165 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
166 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
167 * @code{GETCWD}: GETCWD, Get current working directory
168 * @code{GETENV}: GETENV, Get an environmental variable
169 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
170 * @code{GETGID}: GETGID, Group ID function
171 * @code{GETLOG}: GETLOG, Get login name
172 * @code{GETPID}: GETPID, Process ID function
173 * @code{GETUID}: GETUID, User ID function
174 * @code{GMTIME}: GMTIME, Convert time to GMT info
175 * @code{HOSTNM}: HOSTNM, Get system host name
176 * @code{HUGE}: HUGE, Largest number of a kind
177 * @code{HYPOT}: HYPOT, Euclidean distance function
178 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
179 * @code{IALL}: IALL, Bitwise AND of array elements
180 * @code{IAND}: IAND, Bitwise logical and
181 * @code{IANY}: IANY, Bitwise OR of array elements
182 * @code{IARGC}: IARGC, Get the number of command line arguments
183 * @code{IBCLR}: IBCLR, Clear bit
184 * @code{IBITS}: IBITS, Bit extraction
185 * @code{IBSET}: IBSET, Set bit
186 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
187 * @code{IDATE}: IDATE, Current local time (day/month/year)
188 * @code{IEOR}: IEOR, Bitwise logical exclusive or
189 * @code{IERRNO}: IERRNO, Function to get the last system error number
190 * @code{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index conversion
191 * @code{INDEX}: INDEX intrinsic, Position of a substring within a string
192 * @code{INT}: INT, Convert to integer type
193 * @code{INT2}: INT2, Convert to 16-bit integer type
194 * @code{INT8}: INT8, Convert to 64-bit integer type
195 * @code{IOR}: IOR, Bitwise logical or
196 * @code{IPARITY}: IPARITY, Bitwise XOR of array elements
197 * @code{IRAND}: IRAND, Integer pseudo-random number
198 * @code{IS_CONTIGUOUS}: IS_CONTIGUOUS, Test whether an array is contiguous
199 * @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value
200 * @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value
201 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
202 * @code{ISHFT}: ISHFT, Shift bits
203 * @code{ISHFTC}: ISHFTC, Shift bits circularly
204 * @code{ISNAN}: ISNAN, Tests for a NaN
205 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
206 * @code{KILL}: KILL, Send a signal to a process
207 * @code{KIND}: KIND, Kind of an entity
208 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
209 * @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array
210 * @code{LEADZ}: LEADZ, Number of leading zero bits of an integer
211 * @code{LEN}: LEN, Length of a character entity
212 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
213 * @code{LGE}: LGE, Lexical greater than or equal
214 * @code{LGT}: LGT, Lexical greater than
215 * @code{LINK}: LINK, Create a hard link
216 * @code{LLE}: LLE, Lexical less than or equal
217 * @code{LLT}: LLT, Lexical less than
218 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
219 * @code{LOC}: LOC, Returns the address of a variable
220 * @code{LOG}: LOG, Logarithm function
221 * @code{LOG10}: LOG10, Base 10 logarithm function
222 * @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
223 * @code{LOGICAL}: LOGICAL, Convert to logical type
224 * @code{LONG}: LONG, Convert to integer type
225 * @code{LSHIFT}: LSHIFT, Left shift bits
226 * @code{LSTAT}: LSTAT, Get file status
227 * @code{LTIME}: LTIME, Convert time to local time info
228 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
229 * @code{MASKL}: MASKL, Left justified mask
230 * @code{MASKR}: MASKR, Right justified mask
231 * @code{MATMUL}: MATMUL, matrix multiplication
232 * @code{MAX}: MAX, Maximum value of an argument list
233 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
234 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
235 * @code{MAXVAL}: MAXVAL, Maximum value of an array
236 * @code{MCLOCK}: MCLOCK, Time function
237 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
238 * @code{MERGE}: MERGE, Merge arrays
239 * @code{MERGE_BITS}: MERGE_BITS, Merge of bits under mask
240 * @code{MIN}: MIN, Minimum value of an argument list
241 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
242 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
243 * @code{MINVAL}: MINVAL, Minimum value of an array
244 * @code{MOD}: MOD, Remainder function
245 * @code{MODULO}: MODULO, Modulo function
246 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
247 * @code{MVBITS}: MVBITS, Move bits from one integer to another
248 * @code{NEAREST}: NEAREST, Nearest representable number
249 * @code{NEW_LINE}: NEW_LINE, New line character
250 * @code{NINT}: NINT, Nearest whole number
251 * @code{NORM2}: NORM2, Euclidean vector norm
252 * @code{NOT}: NOT, Logical negation
253 * @code{NULL}: NULL, Function that returns an disassociated pointer
254 * @code{NUM_IMAGES}: NUM_IMAGES, Number of images
255 * @code{OR}: OR, Bitwise logical OR
256 * @code{PACK}: PACK, Pack an array into an array of rank one
257 * @code{PARITY}: PARITY, Reduction with exclusive OR
258 * @code{PERROR}: PERROR, Print system error message
259 * @code{POPCNT}: POPCNT, Number of bits set
260 * @code{POPPAR}: POPPAR, Parity of the number of bits set
261 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
262 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
263 * @code{PRODUCT}: PRODUCT, Product of array elements
264 * @code{RADIX}: RADIX, Base of a data model
265 * @code{RAN}: RAN, Real pseudo-random number
266 * @code{RAND}: RAND, Real pseudo-random number
267 * @code{RANDOM_INIT}: RANDOM_INIT, Initialize pseudo-random number generator
268 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
269 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
270 * @code{RANGE}: RANGE, Decimal exponent range
271 * @code{RANK} : RANK, Rank of a data object
272 * @code{REAL}: REAL, Convert to real type
273 * @code{RENAME}: RENAME, Rename a file
274 * @code{REPEAT}: REPEAT, Repeated string concatenation
275 * @code{RESHAPE}: RESHAPE, Function to reshape an array
276 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
277 * @code{RSHIFT}: RSHIFT, Right shift bits
278 * @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality
279 * @code{SCALE}: SCALE, Scale a real value
280 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
281 * @code{SECNDS}: SECNDS, Time function
282 * @code{SECOND}: SECOND, CPU time function
283 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind
284 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
285 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
286 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
287 * @code{SHAPE}: SHAPE, Determine the shape of an array
288 * @code{SHIFTA}: SHIFTA, Right shift with fill
289 * @code{SHIFTL}: SHIFTL, Left shift
290 * @code{SHIFTR}: SHIFTR, Right shift
291 * @code{SIGN}: SIGN, Sign copying function
292 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
293 * @code{SIN}: SIN, Sine function
294 * @code{SIND}: SIND, Sine function, degrees
295 * @code{SINH}: SINH, Hyperbolic sine function
296 * @code{SIZE}: SIZE, Function to determine the size of an array
297 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
298 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
299 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
300 * @code{SPREAD}: SPREAD, Add a dimension to an array
301 * @code{SQRT}: SQRT, Square-root function
302 * @code{SRAND}: SRAND, Reinitialize the random number generator
303 * @code{STAT}: STAT, Get file status
304 * @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits
305 * @code{SUM}: SUM, Sum of array elements
306 * @code{SYMLNK}: SYMLNK, Create a symbolic link
307 * @code{SYSTEM}: SYSTEM, Execute a shell command
308 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
309 * @code{TAN}: TAN, Tangent function
310 * @code{TAND}: TAND, Tangent function, degrees
311 * @code{TANH}: TANH, Hyperbolic tangent function
312 * @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image
313 * @code{TIME}: TIME, Time function
314 * @code{TIME8}: TIME8, Time function (64-bit)
315 * @code{TINY}: TINY, Smallest positive number of a real kind
316 * @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer
317 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
318 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
319 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
320 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
321 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
322 * @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array
323 * @code{UMASK}: UMASK, Set the file creation mask
324 * @code{UNLINK}: UNLINK, Remove a file from the file system
325 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
326 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
327 * @code{XOR}: XOR, Bitwise logical exclusive or
330 @node Introduction to Intrinsics
331 @section Introduction to intrinsic procedures
333 The intrinsic procedures provided by GNU Fortran include all of the
334 intrinsic procedures required by the Fortran 95 standard, a set of
335 intrinsic procedures for backwards compatibility with G77, and a
336 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
337 standards. Any conflict between a description here and a description in
338 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
339 2008 standard is unintentional, and the standard(s) should be considered
342 The enumeration of the @code{KIND} type parameter is processor defined in
343 the Fortran 95 standard. GNU Fortran defines the default integer type and
344 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
345 respectively. The standard mandates that both data types shall have
346 another kind, which have more precision. On typical target architectures
347 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
348 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
349 In the description of generic intrinsic procedures, the kind type parameter
350 will be specified by @code{KIND=*}, and in the description of specific
351 names for an intrinsic procedure the kind type parameter will be explicitly
352 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
353 brevity the optional @code{KIND=} syntax will be omitted.
355 Many of the intrinsic procedures take one or more optional arguments.
356 This document follows the convention used in the Fortran 95 standard,
357 and denotes such arguments by square brackets.
359 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
360 which can be used to restrict the set of intrinsic procedures to a
361 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
362 option, and so all intrinsic procedures described here are accepted. There
363 is one caveat. For a select group of intrinsic procedures, @command{g77}
364 implemented both a function and a subroutine. Both classes
365 have been implemented in @command{gfortran} for backwards compatibility
366 with @command{g77}. It is noted here that these functions and subroutines
367 cannot be intermixed in a given subprogram. In the descriptions that follow,
368 the applicable standard for each intrinsic procedure is noted.
373 @section @code{ABORT} --- Abort the program
375 @cindex program termination, with core dump
376 @cindex terminate program, with core dump
380 @item @emph{Description}:
381 @code{ABORT} causes immediate termination of the program. On operating
382 systems that support a core dump, @code{ABORT} will produce a core dump.
383 It will also print a backtrace, unless @code{-fno-backtrace} is given.
385 @item @emph{Standard}:
394 @item @emph{Return value}:
397 @item @emph{Example}:
400 integer :: i = 1, j = 2
401 if (i /= j) call abort
402 end program test_abort
405 @item @emph{See also}:
414 @section @code{ABS} --- Absolute value
425 @cindex absolute value
428 @item @emph{Description}:
429 @code{ABS(A)} computes the absolute value of @code{A}.
431 @item @emph{Standard}:
432 Fortran 77 and later, has overloads that are GNU extensions
438 @code{RESULT = ABS(A)}
440 @item @emph{Arguments}:
441 @multitable @columnfractions .15 .70
442 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
443 @code{REAL}, or @code{COMPLEX}.
446 @item @emph{Return value}:
447 The return value is of the same type and
448 kind as the argument except the return value is @code{REAL} for a
449 @code{COMPLEX} argument.
451 @item @emph{Example}:
456 complex :: z = (-1.e0,0.e0)
463 @item @emph{Specific names}:
464 @multitable @columnfractions .20 .20 .20 .25
465 @item Name @tab Argument @tab Return type @tab Standard
466 @item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
467 @item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
468 @item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
469 @item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
470 @item @code{BABS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
471 @item @code{IIABS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
472 @item @code{JIABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
473 @item @code{KIABS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
474 @item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{REAL(8)} @tab GNU extension
475 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{REAL(8)} @tab GNU extension
482 @section @code{ACCESS} --- Checks file access modes
484 @cindex file system, access mode
487 @item @emph{Description}:
488 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
489 exists, is readable, writable or executable. Except for the
490 executable check, @code{ACCESS} can be replaced by
491 Fortran 95's @code{INQUIRE}.
493 @item @emph{Standard}:
500 @code{RESULT = ACCESS(NAME, MODE)}
502 @item @emph{Arguments}:
503 @multitable @columnfractions .15 .70
504 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
505 file name. Tailing blank are ignored unless the character @code{achar(0)}
506 is present, then all characters up to and excluding @code{achar(0)} are
508 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
509 file access mode, may be any concatenation of @code{"r"} (readable),
510 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
514 @item @emph{Return value}:
515 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
516 accessible in the given mode; otherwise or if an invalid argument
517 has been given for @code{MODE} the value @code{1} is returned.
519 @item @emph{Example}:
523 character(len=*), parameter :: file = 'test.dat'
524 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
525 if(access(file,' ') == 0) print *, trim(file),' is exists'
526 if(access(file,'r') == 0) print *, trim(file),' is readable'
527 if(access(file,'w') == 0) print *, trim(file),' is writable'
528 if(access(file,'x') == 0) print *, trim(file),' is executable'
529 if(access(file2,'rwx') == 0) &
530 print *, trim(file2),' is readable, writable and executable'
531 end program access_test
538 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
540 @cindex @acronym{ASCII} collating sequence
541 @cindex collating sequence, @acronym{ASCII}
544 @item @emph{Description}:
545 @code{ACHAR(I)} returns the character located at position @code{I}
546 in the @acronym{ASCII} collating sequence.
548 @item @emph{Standard}:
549 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
555 @code{RESULT = ACHAR(I [, KIND])}
557 @item @emph{Arguments}:
558 @multitable @columnfractions .15 .70
559 @item @var{I} @tab The type shall be @code{INTEGER}.
560 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
561 expression indicating the kind parameter of the result.
564 @item @emph{Return value}:
565 The return value is of type @code{CHARACTER} with a length of one.
566 If the @var{KIND} argument is present, the return value is of the
567 specified kind and of the default kind otherwise.
569 @item @emph{Example}:
574 end program test_achar
578 See @ref{ICHAR} for a discussion of converting between numerical values
579 and formatted string representations.
581 @item @emph{See also}:
590 @section @code{ACOS} --- Arccosine function
593 @cindex trigonometric function, cosine, inverse
594 @cindex cosine, inverse
597 @item @emph{Description}:
598 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
600 @item @emph{Standard}:
601 Fortran 77 and later, for a complex argument Fortran 2008 or later
607 @code{RESULT = ACOS(X)}
609 @item @emph{Arguments}:
610 @multitable @columnfractions .15 .70
611 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
612 less than or equal to one - or the type shall be @code{COMPLEX}.
615 @item @emph{Return value}:
616 The return value is of the same type and kind as @var{X}.
617 The real part of the result is in radians and lies in the range
618 @math{0 \leq \Re \acos(x) \leq \pi}.
620 @item @emph{Example}:
623 real(8) :: x = 0.866_8
625 end program test_acos
628 @item @emph{Specific names}:
629 @multitable @columnfractions .20 .20 .20 .25
630 @item Name @tab Argument @tab Return type @tab Standard
631 @item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
632 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
635 @item @emph{See also}:
636 Inverse function: @gol
638 Degrees function: @gol
645 @section @code{ACOSD} --- Arccosine function, degrees
648 @cindex trigonometric function, cosine, inverse, degrees
649 @cindex cosine, inverse, degrees
652 @item @emph{Description}:
653 @code{ACOSD(X)} computes the arccosine of @var{X} in degrees (inverse of
656 This function is for compatibility only and should be avoided in favor of
657 standard constructs wherever possible.
659 @item @emph{Standard}:
660 GNU extension, enabled with @option{-fdec-math}
666 @code{RESULT = ACOSD(X)}
668 @item @emph{Arguments}:
669 @multitable @columnfractions .15 .70
670 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
671 less than or equal to one - or the type shall be @code{COMPLEX}.
674 @item @emph{Return value}:
675 The return value is of the same type and kind as @var{X}.
676 The real part of the result is in degrees and lies in the range
677 @math{0 \leq \Re \acos(x) \leq 180}.
679 @item @emph{Example}:
682 real(8) :: x = 0.866_8
684 end program test_acosd
687 @item @emph{Specific names}:
688 @multitable @columnfractions .20 .20 .20 .25
689 @item Name @tab Argument @tab Return type @tab Standard
690 @item @code{ACOSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
691 @item @code{DACOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
694 @item @emph{See also}:
695 Inverse function: @gol
697 Radians function: @gol
704 @section @code{ACOSH} --- Inverse hyperbolic cosine function
707 @cindex area hyperbolic cosine
708 @cindex inverse hyperbolic cosine
709 @cindex hyperbolic function, cosine, inverse
710 @cindex cosine, hyperbolic, inverse
713 @item @emph{Description}:
714 @code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
716 @item @emph{Standard}:
717 Fortran 2008 and later
723 @code{RESULT = ACOSH(X)}
725 @item @emph{Arguments}:
726 @multitable @columnfractions .15 .70
727 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
730 @item @emph{Return value}:
731 The return value has the same type and kind as @var{X}. If @var{X} is
732 complex, the imaginary part of the result is in radians and lies between
733 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
735 @item @emph{Example}:
738 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
743 @item @emph{Specific names}:
744 @multitable @columnfractions .20 .20 .20 .25
745 @item Name @tab Argument @tab Return type @tab Standard
746 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
749 @item @emph{See also}:
750 Inverse function: @gol
757 @section @code{ADJUSTL} --- Left adjust a string
759 @cindex string, adjust left
760 @cindex adjust string
763 @item @emph{Description}:
764 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
765 Spaces are inserted at the end of the string as needed.
767 @item @emph{Standard}:
774 @code{RESULT = ADJUSTL(STRING)}
776 @item @emph{Arguments}:
777 @multitable @columnfractions .15 .70
778 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
781 @item @emph{Return value}:
782 The return value is of type @code{CHARACTER} and of the same kind as
783 @var{STRING} where leading spaces are removed and the same number of
784 spaces are inserted on the end of @var{STRING}.
786 @item @emph{Example}:
789 character(len=20) :: str = ' gfortran'
792 end program test_adjustl
795 @item @emph{See also}:
803 @section @code{ADJUSTR} --- Right adjust a string
805 @cindex string, adjust right
806 @cindex adjust string
809 @item @emph{Description}:
810 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
811 Spaces are inserted at the start of the string as needed.
813 @item @emph{Standard}:
820 @code{RESULT = ADJUSTR(STRING)}
822 @item @emph{Arguments}:
823 @multitable @columnfractions .15 .70
824 @item @var{STR} @tab The type shall be @code{CHARACTER}.
827 @item @emph{Return value}:
828 The return value is of type @code{CHARACTER} and of the same kind as
829 @var{STRING} where trailing spaces are removed and the same number of
830 spaces are inserted at the start of @var{STRING}.
832 @item @emph{Example}:
835 character(len=20) :: str = 'gfortran'
838 end program test_adjustr
841 @item @emph{See also}:
849 @section @code{AIMAG} --- Imaginary part of complex number
854 @cindex complex numbers, imaginary part
857 @item @emph{Description}:
858 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
859 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
860 for compatibility with @command{g77}, and their use in new code is
861 strongly discouraged.
863 @item @emph{Standard}:
864 Fortran 77 and later, has overloads that are GNU extensions
870 @code{RESULT = AIMAG(Z)}
872 @item @emph{Arguments}:
873 @multitable @columnfractions .15 .70
874 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
877 @item @emph{Return value}:
878 The return value is of type @code{REAL} with the
879 kind type parameter of the argument.
881 @item @emph{Example}:
886 z4 = cmplx(1.e0_4, 0.e0_4)
887 z8 = cmplx(0.e0_8, 1.e0_8)
888 print *, aimag(z4), dimag(z8)
889 end program test_aimag
892 @item @emph{Specific names}:
893 @multitable @columnfractions .20 .20 .20 .25
894 @item Name @tab Argument @tab Return type @tab Standard
895 @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab Fortran 77 and later
896 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
897 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
898 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
905 @section @code{AINT} --- Truncate to a whole number
909 @cindex rounding, floor
912 @item @emph{Description}:
913 @code{AINT(A [, KIND])} truncates its argument to a whole number.
915 @item @emph{Standard}:
922 @code{RESULT = AINT(A [, KIND])}
924 @item @emph{Arguments}:
925 @multitable @columnfractions .15 .70
926 @item @var{A} @tab The type of the argument shall be @code{REAL}.
927 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
928 expression indicating the kind parameter of the result.
931 @item @emph{Return value}:
932 The return value is of type @code{REAL} with the kind type parameter of the
933 argument if the optional @var{KIND} is absent; otherwise, the kind
934 type parameter will be given by @var{KIND}. If the magnitude of
935 @var{X} is less than one, @code{AINT(X)} returns zero. If the
936 magnitude is equal to or greater than one then it returns the largest
937 whole number that does not exceed its magnitude. The sign is the same
938 as the sign of @var{X}.
940 @item @emph{Example}:
947 print *, aint(x4), dint(x8)
949 end program test_aint
952 @item @emph{Specific names}:
953 @multitable @columnfractions .20 .20 .20 .25
954 @item Name @tab Argument @tab Return type @tab Standard
955 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
956 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
963 @section @code{ALARM} --- Execute a routine after a given delay
965 @cindex delayed execution
968 @item @emph{Description}:
969 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
970 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
971 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
972 supplied, it will be returned with the number of seconds remaining until
973 any previously scheduled alarm was due to be delivered, or zero if there
974 was no previously scheduled alarm.
976 @item @emph{Standard}:
983 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
985 @item @emph{Arguments}:
986 @multitable @columnfractions .15 .70
987 @item @var{SECONDS} @tab The type of the argument shall be a scalar
988 @code{INTEGER}. It is @code{INTENT(IN)}.
989 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
990 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
991 values may be either @code{SIG_IGN=1} to ignore the alarm generated
992 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
993 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
994 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
997 @item @emph{Example}:
1000 external handler_print
1002 call alarm (3, handler_print, i)
1005 end program test_alarm
1007 This will cause the external routine @var{handler_print} to be called
1014 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
1016 @cindex array, apply condition
1017 @cindex array, condition testing
1020 @item @emph{Description}:
1021 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
1022 in the array along dimension @var{DIM}.
1024 @item @emph{Standard}:
1025 Fortran 90 and later
1028 Transformational function
1030 @item @emph{Syntax}:
1031 @code{RESULT = ALL(MASK [, DIM])}
1033 @item @emph{Arguments}:
1034 @multitable @columnfractions .15 .70
1035 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1036 it shall not be scalar.
1037 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1038 with a value that lies between one and the rank of @var{MASK}.
1041 @item @emph{Return value}:
1042 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
1043 the kind type parameter is the same as the kind type parameter of
1044 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
1045 an array with the rank of @var{MASK} minus 1. The shape is determined from
1046 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1050 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
1051 It also is true if @var{MASK} has zero size; otherwise, it is false.
1053 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
1054 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
1055 is determined by applying @code{ALL} to the array sections.
1058 @item @emph{Example}:
1062 l = all((/.true., .true., .true./))
1067 integer a(2,3), b(2,3)
1071 print *, all(a .eq. b, 1)
1072 print *, all(a .eq. b, 2)
1073 end subroutine section
1074 end program test_all
1081 @section @code{ALLOCATED} --- Status of an allocatable entity
1083 @cindex allocation, status
1086 @item @emph{Description}:
1087 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
1088 status of @var{ARRAY} and @var{SCALAR}, respectively.
1090 @item @emph{Standard}:
1091 Fortran 90 and later. Note, the @code{SCALAR=} keyword and allocatable
1092 scalar entities are available in Fortran 2003 and later.
1097 @item @emph{Syntax}:
1098 @multitable @columnfractions .80
1099 @item @code{RESULT = ALLOCATED(ARRAY)}
1100 @item @code{RESULT = ALLOCATED(SCALAR)}
1103 @item @emph{Arguments}:
1104 @multitable @columnfractions .15 .70
1105 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
1106 @item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar.
1109 @item @emph{Return value}:
1110 The return value is a scalar @code{LOGICAL} with the default logical
1111 kind type parameter. If the argument is allocated, then the result is
1112 @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
1114 @item @emph{Example}:
1116 program test_allocated
1118 real(4), allocatable :: x(:)
1119 if (.not. allocated(x)) allocate(x(i))
1120 end program test_allocated
1127 @section @code{AND} --- Bitwise logical AND
1129 @cindex bitwise logical and
1130 @cindex logical and, bitwise
1133 @item @emph{Description}:
1134 Bitwise logical @code{AND}.
1136 This intrinsic routine is provided for backwards compatibility with
1137 GNU Fortran 77. For integer arguments, programmers should consider
1138 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1140 @item @emph{Standard}:
1146 @item @emph{Syntax}:
1147 @code{RESULT = AND(I, J)}
1149 @item @emph{Arguments}:
1150 @multitable @columnfractions .15 .70
1151 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1152 type or a scalar @code{LOGICAL} type or a boz-literal-constant.
1153 @item @var{J} @tab The type shall be the same as the type of @var{I} or
1154 a boz-literal-constant. @var{I} and @var{J} shall not both be
1155 boz-literal-constants. If either @var{I} or @var{J} is a
1156 boz-literal-constant, then the other argument must be a scalar @code{INTEGER}.
1159 @item @emph{Return value}:
1160 The return type is either a scalar @code{INTEGER} or a scalar
1161 @code{LOGICAL}. If the kind type parameters differ, then the
1162 smaller kind type is implicitly converted to larger kind, and the
1163 return has the larger kind. A boz-literal-constant is
1164 converted to an @code{INTEGER} with the kind type parameter of
1165 the other argument as-if a call to @ref{INT} occurred.
1167 @item @emph{Example}:
1170 LOGICAL :: T = .TRUE., F = .FALSE.
1172 DATA a / Z'F' /, b / Z'3' /
1174 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1175 WRITE (*,*) AND(a, b)
1179 @item @emph{See also}:
1180 Fortran 95 elemental function: @gol
1187 @section @code{ANINT} --- Nearest whole number
1191 @cindex rounding, ceiling
1194 @item @emph{Description}:
1195 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1197 @item @emph{Standard}:
1198 Fortran 77 and later
1203 @item @emph{Syntax}:
1204 @code{RESULT = ANINT(A [, KIND])}
1206 @item @emph{Arguments}:
1207 @multitable @columnfractions .15 .70
1208 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1209 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1210 expression indicating the kind parameter of the result.
1213 @item @emph{Return value}:
1214 The return value is of type real with the kind type parameter of the
1215 argument if the optional @var{KIND} is absent; otherwise, the kind
1216 type parameter will be given by @var{KIND}. If @var{A} is greater than
1217 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1218 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1220 @item @emph{Example}:
1227 print *, anint(x4), dnint(x8)
1229 end program test_anint
1232 @item @emph{Specific names}:
1233 @multitable @columnfractions .20 .20 .20 .25
1234 @item Name @tab Argument @tab Return type @tab Standard
1235 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
1236 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1243 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1245 @cindex array, apply condition
1246 @cindex array, condition testing
1249 @item @emph{Description}:
1250 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1251 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1253 @item @emph{Standard}:
1254 Fortran 90 and later
1257 Transformational function
1259 @item @emph{Syntax}:
1260 @code{RESULT = ANY(MASK [, DIM])}
1262 @item @emph{Arguments}:
1263 @multitable @columnfractions .15 .70
1264 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1265 it shall not be scalar.
1266 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1267 with a value that lies between one and the rank of @var{MASK}.
1270 @item @emph{Return value}:
1271 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1272 the kind type parameter is the same as the kind type parameter of
1273 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1274 an array with the rank of @var{MASK} minus 1. The shape is determined from
1275 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1279 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1280 otherwise, it is false. It also is false if @var{MASK} has zero size.
1282 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1283 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1284 is determined by applying @code{ANY} to the array sections.
1287 @item @emph{Example}:
1291 l = any((/.true., .true., .true./))
1296 integer a(2,3), b(2,3)
1300 print *, any(a .eq. b, 1)
1301 print *, any(a .eq. b, 2)
1302 end subroutine section
1303 end program test_any
1310 @section @code{ASIN} --- Arcsine function
1313 @cindex trigonometric function, sine, inverse
1314 @cindex sine, inverse
1317 @item @emph{Description}:
1318 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1320 @item @emph{Standard}:
1321 Fortran 77 and later, for a complex argument Fortran 2008 or later
1326 @item @emph{Syntax}:
1327 @code{RESULT = ASIN(X)}
1329 @item @emph{Arguments}:
1330 @multitable @columnfractions .15 .70
1331 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1332 less than or equal to one - or be @code{COMPLEX}.
1335 @item @emph{Return value}:
1336 The return value is of the same type and kind as @var{X}.
1337 The real part of the result is in radians and lies in the range
1338 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1340 @item @emph{Example}:
1343 real(8) :: x = 0.866_8
1345 end program test_asin
1348 @item @emph{Specific names}:
1349 @multitable @columnfractions .20 .20 .20 .25
1350 @item Name @tab Argument @tab Return type @tab Standard
1351 @item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1352 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1355 @item @emph{See also}:
1356 Inverse function: @gol
1358 Degrees function: @gol
1365 @section @code{ASIND} --- Arcsine function, degrees
1368 @cindex trigonometric function, sine, inverse, degrees
1369 @cindex sine, inverse, degrees
1372 @item @emph{Description}:
1373 @code{ASIND(X)} computes the arcsine of its @var{X} in degrees (inverse of
1376 This function is for compatibility only and should be avoided in favor of
1377 standard constructs wherever possible.
1379 @item @emph{Standard}:
1380 GNU extension, enabled with @option{-fdec-math}.
1385 @item @emph{Syntax}:
1386 @code{RESULT = ASIND(X)}
1388 @item @emph{Arguments}:
1389 @multitable @columnfractions .15 .70
1390 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1391 less than or equal to one - or be @code{COMPLEX}.
1394 @item @emph{Return value}:
1395 The return value is of the same type and kind as @var{X}.
1396 The real part of the result is in degrees and lies in the range
1397 @math{-90 \leq \Re \asin(x) \leq 90}.
1399 @item @emph{Example}:
1402 real(8) :: x = 0.866_8
1404 end program test_asind
1407 @item @emph{Specific names}:
1408 @multitable @columnfractions .20 .20 .20 .25
1409 @item Name @tab Argument @tab Return type @tab Standard
1410 @item @code{ASIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
1411 @item @code{DASIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1414 @item @emph{See also}:
1415 Inverse function: @gol
1417 Radians function: @gol
1424 @section @code{ASINH} --- Inverse hyperbolic sine function
1427 @cindex area hyperbolic sine
1428 @cindex inverse hyperbolic sine
1429 @cindex hyperbolic function, sine, inverse
1430 @cindex sine, hyperbolic, inverse
1433 @item @emph{Description}:
1434 @code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
1436 @item @emph{Standard}:
1437 Fortran 2008 and later
1442 @item @emph{Syntax}:
1443 @code{RESULT = ASINH(X)}
1445 @item @emph{Arguments}:
1446 @multitable @columnfractions .15 .70
1447 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1450 @item @emph{Return value}:
1451 The return value is of the same type and kind as @var{X}. If @var{X} is
1452 complex, the imaginary part of the result is in radians and lies between
1453 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1455 @item @emph{Example}:
1458 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1459 WRITE (*,*) ASINH(x)
1463 @item @emph{Specific names}:
1464 @multitable @columnfractions .20 .20 .20 .25
1465 @item Name @tab Argument @tab Return type @tab Standard
1466 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1469 @item @emph{See also}:
1470 Inverse function: @gol
1477 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1479 @cindex pointer, status
1480 @cindex association status
1483 @item @emph{Description}:
1484 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1485 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1487 @item @emph{Standard}:
1488 Fortran 90 and later
1493 @item @emph{Syntax}:
1494 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1496 @item @emph{Arguments}:
1497 @multitable @columnfractions .15 .70
1498 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1499 and it can be of any type.
1500 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1501 a target. It must have the same type, kind type parameter, and
1502 array rank as @var{POINTER}.
1504 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1507 @item @emph{Return value}:
1508 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1509 There are several cases:
1511 @item (A) When the optional @var{TARGET} is not present then
1512 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1513 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1514 @var{TARGET} is not a zero-sized storage sequence and the target associated with @var{POINTER} occupies the same storage units. If @var{POINTER} is
1515 disassociated, the result is false.
1516 @item (C) If @var{TARGET} is present and an array target, the result is true if
1517 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1518 are arrays whose elements are not zero-sized storage sequences, and
1519 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1521 As in case(B), the result is false, if @var{POINTER} is disassociated.
1522 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1523 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1524 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1526 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1527 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1528 target associated with @var{POINTER} and the target associated with @var{TARGET}
1529 have the same shape, are not zero-sized arrays, are arrays whose elements are
1530 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1531 the same storage units in array element order.
1532 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1535 @item @emph{Example}:
1537 program test_associated
1539 real, target :: tgt(2) = (/1., 2./)
1540 real, pointer :: ptr(:)
1542 if (associated(ptr) .eqv. .false.) call abort
1543 if (associated(ptr,tgt) .eqv. .false.) call abort
1544 end program test_associated
1547 @item @emph{See also}:
1554 @section @code{ATAN} --- Arctangent function
1557 @cindex trigonometric function, tangent, inverse
1558 @cindex tangent, inverse
1561 @item @emph{Description}:
1562 @code{ATAN(X)} computes the arctangent of @var{X}.
1564 @item @emph{Standard}:
1565 Fortran 77 and later, for a complex argument and for two arguments
1566 Fortran 2008 or later
1571 @item @emph{Syntax}:
1572 @multitable @columnfractions .80
1573 @item @code{RESULT = ATAN(X)}
1574 @item @code{RESULT = ATAN(Y, X)}
1577 @item @emph{Arguments}:
1578 @multitable @columnfractions .15 .70
1579 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1580 if @var{Y} is present, @var{X} shall be REAL.
1581 @item @var{Y} @tab The type and kind type parameter shall be the same as @var{X}.
1584 @item @emph{Return value}:
1585 The return value is of the same type and kind as @var{X}.
1586 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1587 Otherwise, it the arcus tangent of @var{X}, where the real part of
1588 the result is in radians and lies in the range
1589 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1591 @item @emph{Example}:
1594 real(8) :: x = 2.866_8
1596 end program test_atan
1599 @item @emph{Specific names}:
1600 @multitable @columnfractions .20 .20 .20 .25
1601 @item Name @tab Argument @tab Return type @tab Standard
1602 @item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1603 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1606 @item @emph{See also}:
1607 Inverse function: @gol
1609 Degrees function: @gol
1616 @section @code{ATAND} --- Arctangent function, degrees
1619 @cindex trigonometric function, tangent, inverse, degrees
1620 @cindex tangent, inverse, degrees
1623 @item @emph{Description}:
1624 @code{ATAND(X)} computes the arctangent of @var{X} in degrees (inverse of
1627 This function is for compatibility only and should be avoided in favor of
1628 standard constructs wherever possible.
1630 @item @emph{Standard}:
1631 GNU extension, enabled with @option{-fdec-math}.
1636 @item @emph{Syntax}:
1637 @multitable @columnfractions .80
1638 @item @code{RESULT = ATAND(X)}
1639 @item @code{RESULT = ATAND(Y, X)}
1642 @item @emph{Arguments}:
1643 @multitable @columnfractions .15 .70
1644 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1645 if @var{Y} is present, @var{X} shall be REAL.
1646 @item @var{Y} @tab The type and kind type parameter shall be the same as @var{X}.
1649 @item @emph{Return value}:
1650 The return value is of the same type and kind as @var{X}.
1651 If @var{Y} is present, the result is identical to @code{ATAND2(Y,X)}.
1652 Otherwise, it is the arcus tangent of @var{X}, where the real part of
1653 the result is in degrees and lies in the range
1654 @math{-90 \leq \Re \atand(x) \leq 90}.
1656 @item @emph{Example}:
1659 real(8) :: x = 2.866_8
1661 end program test_atand
1664 @item @emph{Specific names}:
1665 @multitable @columnfractions .20 .20 .20 .25
1666 @item Name @tab Argument @tab Return type @tab Standard
1667 @item @code{ATAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
1668 @item @code{DATAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1671 @item @emph{See also}:
1672 Inverse function: @gol
1674 Radians function: @gol
1681 @section @code{ATAN2} --- Arctangent function
1684 @cindex trigonometric function, tangent, inverse
1685 @cindex tangent, inverse
1688 @item @emph{Description}:
1689 @code{ATAN2(Y, X)} computes the principal value of the argument
1690 function of the complex number @math{X + i Y}. This function can
1691 be used to transform from Cartesian into polar coordinates and
1692 allows to determine the angle in the correct quadrant.
1694 @item @emph{Standard}:
1695 Fortran 77 and later
1700 @item @emph{Syntax}:
1701 @code{RESULT = ATAN2(Y, X)}
1703 @item @emph{Arguments}:
1704 @multitable @columnfractions .15 .70
1705 @item @var{Y} @tab The type shall be @code{REAL}.
1706 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1707 If @var{Y} is zero, then @var{X} must be nonzero.
1710 @item @emph{Return value}:
1711 The return value has the same type and kind type parameter as @var{Y}. It
1712 is the principal value of the complex number @math{X + i Y}. If @var{X}
1713 is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1714 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1715 the return value is zero if @var{X} is strictly positive, @math{\pi} if
1716 @var{X} is negative and @var{Y} is positive zero (or the processor does
1717 not handle signed zeros), and @math{-\pi} if @var{X} is negative and
1718 @var{Y} is negative zero. Finally, if @var{X} is zero, then the
1719 magnitude of the result is @math{\pi/2}.
1721 @item @emph{Example}:
1724 real(4) :: x = 1.e0_4, y = 0.5e0_4
1726 end program test_atan2
1729 @item @emph{Specific names}:
1730 @multitable @columnfractions .20 .20 .20 .25
1731 @item Name @tab Argument @tab Return type @tab Standard
1732 @item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1733 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1736 @item @emph{See also}:
1739 Degrees function: @gol
1746 @section @code{ATAN2D} --- Arctangent function, degrees
1749 @cindex trigonometric function, tangent, inverse, degrees
1750 @cindex tangent, inverse, degrees
1753 @item @emph{Description}:
1754 @code{ATAN2D(Y, X)} computes the principal value of the argument
1755 function of the complex number @math{X + i Y} in degrees. This function can
1756 be used to transform from Cartesian into polar coordinates and
1757 allows to determine the angle in the correct quadrant.
1759 This function is for compatibility only and should be avoided in favor of
1760 standard constructs wherever possible.
1762 @item @emph{Standard}:
1763 GNU extension, enabled with @option{-fdec-math}.
1768 @item @emph{Syntax}:
1769 @code{RESULT = ATAN2D(Y, X)}
1771 @item @emph{Arguments}:
1772 @multitable @columnfractions .15 .70
1773 @item @var{Y} @tab The type shall be @code{REAL}.
1774 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1775 If @var{Y} is zero, then @var{X} must be nonzero.
1778 @item @emph{Return value}:
1779 The return value has the same type and kind type parameter as @var{Y}. It
1780 is the principal value of the complex number @math{X + i Y}. If @var{X}
1781 is nonzero, then it lies in the range @math{-180 \le \atan (x) \leq 180}.
1782 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1783 the return value is zero if @var{X} is strictly positive, @math{180} if
1784 @var{X} is negative and @var{Y} is positive zero (or the processor does
1785 not handle signed zeros), and @math{-180} if @var{X} is negative and
1786 @var{Y} is negative zero. Finally, if @var{X} is zero, then the
1787 magnitude of the result is @math{90}.
1789 @item @emph{Example}:
1792 real(4) :: x = 1.e0_4, y = 0.5e0_4
1794 end program test_atan2d
1797 @item @emph{Specific names}:
1798 @multitable @columnfractions .20 .20 .20 .25
1799 @item Name @tab Argument @tab Return type @tab Standard
1800 @item @code{ATAN2D(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab GNU extension
1801 @item @code{DATAN2D(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab GNU extension
1804 @item @emph{See also}:
1807 Radians function: @gol
1814 @section @code{ATANH} --- Inverse hyperbolic tangent function
1817 @cindex area hyperbolic tangent
1818 @cindex inverse hyperbolic tangent
1819 @cindex hyperbolic function, tangent, inverse
1820 @cindex tangent, hyperbolic, inverse
1823 @item @emph{Description}:
1824 @code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
1826 @item @emph{Standard}:
1827 Fortran 2008 and later
1832 @item @emph{Syntax}:
1833 @code{RESULT = ATANH(X)}
1835 @item @emph{Arguments}:
1836 @multitable @columnfractions .15 .70
1837 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1840 @item @emph{Return value}:
1841 The return value has same type and kind as @var{X}. If @var{X} is
1842 complex, the imaginary part of the result is in radians and lies between
1843 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1845 @item @emph{Example}:
1848 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1849 WRITE (*,*) ATANH(x)
1853 @item @emph{Specific names}:
1854 @multitable @columnfractions .20 .20 .20 .25
1855 @item Name @tab Argument @tab Return type @tab Standard
1856 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1859 @item @emph{See also}:
1860 Inverse function: @gol
1867 @section @code{ATOMIC_ADD} --- Atomic ADD operation
1869 @cindex Atomic subroutine, add
1872 @item @emph{Description}:
1873 @code{ATOMIC_ADD(ATOM, VALUE)} atomically adds the value of @var{VAR} to the
1874 variable @var{ATOM}. When @var{STAT} is present and the invocation was
1875 successful, it is assigned the value 0. If it is present and the invocation
1876 has failed, it is assigned a positive value; in particular, for a coindexed
1877 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1878 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1879 failed, the value @code{STAT_FAILED_IMAGE}.
1881 @item @emph{Standard}:
1887 @item @emph{Syntax}:
1888 @code{CALL ATOMIC_ADD (ATOM, VALUE [, STAT])}
1890 @item @emph{Arguments}:
1891 @multitable @columnfractions .15 .70
1892 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1893 type with @code{ATOMIC_INT_KIND} kind.
1894 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1895 is different, the value is converted to the kind of @var{ATOM}.
1896 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1899 @item @emph{Example}:
1903 integer(atomic_int_kind) :: atom[*]
1904 call atomic_add (atom[1], this_image())
1908 @item @emph{See also}:
1909 @ref{ATOMIC_DEFINE}, @gol
1910 @ref{ATOMIC_FETCH_ADD}, @gol
1911 @ref{ISO_FORTRAN_ENV}, @gol
1912 @ref{ATOMIC_AND}, @gol
1913 @ref{ATOMIC_OR}, @gol
1921 @section @code{ATOMIC_AND} --- Atomic bitwise AND operation
1923 @cindex Atomic subroutine, AND
1926 @item @emph{Description}:
1927 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
1928 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
1929 and the invocation was successful, it is assigned the value 0. If it is present
1930 and the invocation has failed, it is assigned a positive value; in particular,
1931 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
1932 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
1933 image has failed, the value @code{STAT_FAILED_IMAGE}.
1935 @item @emph{Standard}:
1941 @item @emph{Syntax}:
1942 @code{CALL ATOMIC_AND (ATOM, VALUE [, STAT])}
1944 @item @emph{Arguments}:
1945 @multitable @columnfractions .15 .70
1946 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1947 type with @code{ATOMIC_INT_KIND} kind.
1948 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1949 is different, the value is converted to the kind of @var{ATOM}.
1950 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1953 @item @emph{Example}:
1957 integer(atomic_int_kind) :: atom[*]
1958 call atomic_and (atom[1], int(b'10100011101'))
1962 @item @emph{See also}:
1963 @ref{ATOMIC_DEFINE}, @gol
1964 @ref{ATOMIC_FETCH_AND}, @gol
1965 @ref{ISO_FORTRAN_ENV}, @gol
1966 @ref{ATOMIC_ADD}, @gol
1967 @ref{ATOMIC_OR}, @gol
1974 @section @code{ATOMIC_CAS} --- Atomic compare and swap
1975 @fnindex ATOMIC_DEFINE
1976 @cindex Atomic subroutine, compare and swap
1979 @item @emph{Description}:
1980 @code{ATOMIC_CAS} compares the variable @var{ATOM} with the value of
1981 @var{COMPARE}; if the value is the same, @var{ATOM} is set to the value
1982 of @var{NEW}. Additionally, @var{OLD} is set to the value of @var{ATOM}
1983 that was used for the comparison. When @var{STAT} is present and the invocation
1984 was successful, it is assigned the value 0. If it is present and the invocation
1985 has failed, it is assigned a positive value; in particular, for a coindexed
1986 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1987 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1988 failed, the value @code{STAT_FAILED_IMAGE}.
1990 @item @emph{Standard}:
1996 @item @emph{Syntax}:
1997 @code{CALL ATOMIC_CAS (ATOM, OLD, COMPARE, NEW [, STAT])}
1999 @item @emph{Arguments}:
2000 @multitable @columnfractions .15 .70
2001 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
2002 type with @code{ATOMIC_INT_KIND} kind or logical type with
2003 @code{ATOMIC_LOGICAL_KIND} kind.
2004 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2005 @item @var{COMPARE} @tab Scalar variable of the same type and kind as
2007 @item @var{NEW} @tab Scalar variable of the same type as @var{ATOM}. If kind
2008 is different, the value is converted to the kind of @var{ATOM}.
2009 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2012 @item @emph{Example}:
2016 logical(atomic_logical_kind) :: atom[*], prev
2017 call atomic_cas (atom[1], prev, .false., .true.))
2021 @item @emph{See also}:
2022 @ref{ATOMIC_DEFINE}, @gol
2023 @ref{ATOMIC_REF}, @gol
2024 @ref{ISO_FORTRAN_ENV}
2030 @section @code{ATOMIC_DEFINE} --- Setting a variable atomically
2031 @fnindex ATOMIC_DEFINE
2032 @cindex Atomic subroutine, define
2035 @item @emph{Description}:
2036 @code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value
2037 @var{VALUE} atomically. When @var{STAT} is present and the invocation was
2038 successful, it is assigned the value 0. If it is present and the invocation
2039 has failed, it is assigned a positive value; in particular, for a coindexed
2040 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2041 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2042 failed, the value @code{STAT_FAILED_IMAGE}.
2044 @item @emph{Standard}:
2045 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
2050 @item @emph{Syntax}:
2051 @code{CALL ATOMIC_DEFINE (ATOM, VALUE [, STAT])}
2053 @item @emph{Arguments}:
2054 @multitable @columnfractions .15 .70
2055 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
2056 type with @code{ATOMIC_INT_KIND} kind or logical type with
2057 @code{ATOMIC_LOGICAL_KIND} kind.
2059 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2060 is different, the value is converted to the kind of @var{ATOM}.
2061 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2064 @item @emph{Example}:
2068 integer(atomic_int_kind) :: atom[*]
2069 call atomic_define (atom[1], this_image())
2073 @item @emph{See also}:
2074 @ref{ATOMIC_REF}, @gol
2075 @ref{ATOMIC_CAS}, @gol
2076 @ref{ISO_FORTRAN_ENV}, @gol
2077 @ref{ATOMIC_ADD}, @gol
2078 @ref{ATOMIC_AND}, @gol
2079 @ref{ATOMIC_OR}, @gol
2085 @node ATOMIC_FETCH_ADD
2086 @section @code{ATOMIC_FETCH_ADD} --- Atomic ADD operation with prior fetch
2087 @fnindex ATOMIC_FETCH_ADD
2088 @cindex Atomic subroutine, ADD with fetch
2091 @item @emph{Description}:
2092 @code{ATOMIC_FETCH_ADD(ATOM, VALUE, OLD)} atomically stores the value of
2093 @var{ATOM} in @var{OLD} and adds the value of @var{VAR} to the
2094 variable @var{ATOM}. When @var{STAT} is present and the invocation was
2095 successful, it is assigned the value 0. If it is present and the invocation
2096 has failed, it is assigned a positive value; in particular, for a coindexed
2097 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2098 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2099 failed, the value @code{STAT_FAILED_IMAGE}.
2101 @item @emph{Standard}:
2107 @item @emph{Syntax}:
2108 @code{CALL ATOMIC_FETCH_ADD (ATOM, VALUE, old [, STAT])}
2110 @item @emph{Arguments}:
2111 @multitable @columnfractions .15 .70
2112 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2113 type with @code{ATOMIC_INT_KIND} kind.
2114 @code{ATOMIC_LOGICAL_KIND} kind.
2116 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2117 is different, the value is converted to the kind of @var{ATOM}.
2118 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2119 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2122 @item @emph{Example}:
2126 integer(atomic_int_kind) :: atom[*], old
2127 call atomic_add (atom[1], this_image(), old)
2131 @item @emph{See also}:
2132 @ref{ATOMIC_DEFINE}, @gol
2133 @ref{ATOMIC_ADD}, @gol
2134 @ref{ISO_FORTRAN_ENV}, @gol
2135 @ref{ATOMIC_FETCH_AND}, @gol
2136 @ref{ATOMIC_FETCH_OR}, @gol
2137 @ref{ATOMIC_FETCH_XOR}
2142 @node ATOMIC_FETCH_AND
2143 @section @code{ATOMIC_FETCH_AND} --- Atomic bitwise AND operation with prior fetch
2144 @fnindex ATOMIC_FETCH_AND
2145 @cindex Atomic subroutine, AND with fetch
2148 @item @emph{Description}:
2149 @code{ATOMIC_AND(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2150 @var{OLD} and defines @var{ATOM} with the bitwise AND between the values of
2151 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
2152 successful, it is assigned the value 0. If it is present and the invocation has
2153 failed, it is assigned a positive value; in particular, for a coindexed
2154 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2155 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2156 failed, the value @code{STAT_FAILED_IMAGE}.
2158 @item @emph{Standard}:
2164 @item @emph{Syntax}:
2165 @code{CALL ATOMIC_FETCH_AND (ATOM, VALUE, OLD [, STAT])}
2167 @item @emph{Arguments}:
2168 @multitable @columnfractions .15 .70
2169 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2170 type with @code{ATOMIC_INT_KIND} kind.
2171 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2172 is different, the value is converted to the kind of @var{ATOM}.
2173 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2174 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2177 @item @emph{Example}:
2181 integer(atomic_int_kind) :: atom[*], old
2182 call atomic_fetch_and (atom[1], int(b'10100011101'), old)
2186 @item @emph{See also}:
2187 @ref{ATOMIC_DEFINE}, @gol
2188 @ref{ATOMIC_AND}, @gol
2189 @ref{ISO_FORTRAN_ENV}, @gol
2190 @ref{ATOMIC_FETCH_ADD}, @gol
2191 @ref{ATOMIC_FETCH_OR}, @gol
2192 @ref{ATOMIC_FETCH_XOR}
2197 @node ATOMIC_FETCH_OR
2198 @section @code{ATOMIC_FETCH_OR} --- Atomic bitwise OR operation with prior fetch
2199 @fnindex ATOMIC_FETCH_OR
2200 @cindex Atomic subroutine, OR with fetch
2203 @item @emph{Description}:
2204 @code{ATOMIC_OR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2205 @var{OLD} and defines @var{ATOM} with the bitwise OR between the values of
2206 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
2207 successful, it is assigned the value 0. If it is present and the invocation has
2208 failed, it is assigned a positive value; in particular, for a coindexed
2209 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2210 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2211 failed, the value @code{STAT_FAILED_IMAGE}.
2213 @item @emph{Standard}:
2219 @item @emph{Syntax}:
2220 @code{CALL ATOMIC_FETCH_OR (ATOM, VALUE, OLD [, STAT])}
2222 @item @emph{Arguments}:
2223 @multitable @columnfractions .15 .70
2224 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2225 type with @code{ATOMIC_INT_KIND} kind.
2226 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2227 is different, the value is converted to the kind of @var{ATOM}.
2228 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2229 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2232 @item @emph{Example}:
2236 integer(atomic_int_kind) :: atom[*], old
2237 call atomic_fetch_or (atom[1], int(b'10100011101'), old)
2241 @item @emph{See also}:
2242 @ref{ATOMIC_DEFINE}, @gol
2243 @ref{ATOMIC_OR}, @gol
2244 @ref{ISO_FORTRAN_ENV}, @gol
2245 @ref{ATOMIC_FETCH_ADD}, @gol
2246 @ref{ATOMIC_FETCH_AND}, @gol
2247 @ref{ATOMIC_FETCH_XOR}
2252 @node ATOMIC_FETCH_XOR
2253 @section @code{ATOMIC_FETCH_XOR} --- Atomic bitwise XOR operation with prior fetch
2254 @fnindex ATOMIC_FETCH_XOR
2255 @cindex Atomic subroutine, XOR with fetch
2258 @item @emph{Description}:
2259 @code{ATOMIC_XOR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2260 @var{OLD} and defines @var{ATOM} with the bitwise XOR between the values of
2261 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
2262 successful, it is assigned the value 0. If it is present and the invocation has
2263 failed, it is assigned a positive value; in particular, for a coindexed
2264 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2265 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2266 failed, the value @code{STAT_FAILED_IMAGE}.
2268 @item @emph{Standard}:
2274 @item @emph{Syntax}:
2275 @code{CALL ATOMIC_FETCH_XOR (ATOM, VALUE, OLD [, STAT])}
2277 @item @emph{Arguments}:
2278 @multitable @columnfractions .15 .70
2279 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2280 type with @code{ATOMIC_INT_KIND} kind.
2281 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2282 is different, the value is converted to the kind of @var{ATOM}.
2283 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2284 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2287 @item @emph{Example}:
2291 integer(atomic_int_kind) :: atom[*], old
2292 call atomic_fetch_xor (atom[1], int(b'10100011101'), old)
2296 @item @emph{See also}:
2297 @ref{ATOMIC_DEFINE}, @gol
2298 @ref{ATOMIC_XOR}, @gol
2299 @ref{ISO_FORTRAN_ENV}, @gol
2300 @ref{ATOMIC_FETCH_ADD}, @gol
2301 @ref{ATOMIC_FETCH_AND}, @gol
2302 @ref{ATOMIC_FETCH_OR}
2308 @section @code{ATOMIC_OR} --- Atomic bitwise OR operation
2310 @cindex Atomic subroutine, OR
2313 @item @emph{Description}:
2314 @code{ATOMIC_OR(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
2315 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
2316 and the invocation was successful, it is assigned the value 0. If it is present
2317 and the invocation has failed, it is assigned a positive value; in particular,
2318 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
2319 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
2320 image has failed, the value @code{STAT_FAILED_IMAGE}.
2322 @item @emph{Standard}:
2328 @item @emph{Syntax}:
2329 @code{CALL ATOMIC_OR (ATOM, VALUE [, STAT])}
2331 @item @emph{Arguments}:
2332 @multitable @columnfractions .15 .70
2333 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2334 type with @code{ATOMIC_INT_KIND} kind.
2335 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2336 is different, the value is converted to the kind of @var{ATOM}.
2337 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2340 @item @emph{Example}:
2344 integer(atomic_int_kind) :: atom[*]
2345 call atomic_or (atom[1], int(b'10100011101'))
2349 @item @emph{See also}:
2350 @ref{ATOMIC_DEFINE}, @gol
2351 @ref{ATOMIC_FETCH_OR}, @gol
2352 @ref{ISO_FORTRAN_ENV}, @gol
2353 @ref{ATOMIC_ADD}, @gol
2354 @ref{ATOMIC_OR}, @gol
2361 @section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically
2363 @cindex Atomic subroutine, reference
2366 @item @emph{Description}:
2367 @code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the
2368 variable @var{ATOM} to @var{VALUE}. When @var{STAT} is present and the
2369 invocation was successful, it is assigned the value 0. If it is present and the
2370 invocation has failed, it is assigned a positive value; in particular, for a
2371 coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value
2372 of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image
2373 has failed, the value @code{STAT_FAILED_IMAGE}.
2376 @item @emph{Standard}:
2377 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
2382 @item @emph{Syntax}:
2383 @code{CALL ATOMIC_REF(VALUE, ATOM [, STAT])}
2385 @item @emph{Arguments}:
2386 @multitable @columnfractions .15 .70
2387 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2388 is different, the value is converted to the kind of @var{ATOM}.
2389 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
2390 type with @code{ATOMIC_INT_KIND} kind or logical type with
2391 @code{ATOMIC_LOGICAL_KIND} kind.
2392 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2395 @item @emph{Example}:
2399 logical(atomic_logical_kind) :: atom[*]
2401 call atomic_ref (atom, .false.)
2403 call atomic_ref (atom, val)
2410 @item @emph{See also}:
2411 @ref{ATOMIC_DEFINE}, @gol
2412 @ref{ATOMIC_CAS}, @gol
2413 @ref{ISO_FORTRAN_ENV}, @gol
2414 @ref{ATOMIC_FETCH_ADD}, @gol
2415 @ref{ATOMIC_FETCH_AND}, @gol
2416 @ref{ATOMIC_FETCH_OR}, @gol
2417 @ref{ATOMIC_FETCH_XOR}
2422 @section @code{ATOMIC_XOR} --- Atomic bitwise OR operation
2424 @cindex Atomic subroutine, XOR
2427 @item @emph{Description}:
2428 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
2429 XOR between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
2430 and the invocation was successful, it is assigned the value 0. If it is present
2431 and the invocation has failed, it is assigned a positive value; in particular,
2432 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
2433 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
2434 image has failed, the value @code{STAT_FAILED_IMAGE}.
2436 @item @emph{Standard}:
2442 @item @emph{Syntax}:
2443 @code{CALL ATOMIC_XOR (ATOM, VALUE [, STAT])}
2445 @item @emph{Arguments}:
2446 @multitable @columnfractions .15 .70
2447 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2448 type with @code{ATOMIC_INT_KIND} kind.
2449 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2450 is different, the value is converted to the kind of @var{ATOM}.
2451 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2454 @item @emph{Example}:
2458 integer(atomic_int_kind) :: atom[*]
2459 call atomic_xor (atom[1], int(b'10100011101'))
2463 @item @emph{See also}:
2464 @ref{ATOMIC_DEFINE}, @gol
2465 @ref{ATOMIC_FETCH_XOR}, @gol
2466 @ref{ISO_FORTRAN_ENV}, @gol
2467 @ref{ATOMIC_ADD}, @gol
2468 @ref{ATOMIC_OR}, @gol
2474 @section @code{BACKTRACE} --- Show a backtrace
2479 @item @emph{Description}:
2480 @code{BACKTRACE} shows a backtrace at an arbitrary place in user code. Program
2481 execution continues normally afterwards. The backtrace information is printed
2482 to the unit corresponding to @code{ERROR_UNIT} in @code{ISO_FORTRAN_ENV}.
2484 @item @emph{Standard}:
2490 @item @emph{Syntax}:
2491 @code{CALL BACKTRACE}
2493 @item @emph{Arguments}:
2496 @item @emph{See also}:
2503 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
2507 @cindex Bessel function, first kind
2510 @item @emph{Description}:
2511 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
2512 order 0 of @var{X}. This function is available under the name
2513 @code{BESJ0} as a GNU extension.
2515 @item @emph{Standard}:
2516 Fortran 2008 and later
2521 @item @emph{Syntax}:
2522 @code{RESULT = BESSEL_J0(X)}
2524 @item @emph{Arguments}:
2525 @multitable @columnfractions .15 .70
2526 @item @var{X} @tab The type shall be @code{REAL}.
2529 @item @emph{Return value}:
2530 The return value is of type @code{REAL} and lies in the
2531 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
2534 @item @emph{Example}:
2537 real(8) :: x = 0.0_8
2539 end program test_besj0
2542 @item @emph{Specific names}:
2543 @multitable @columnfractions .20 .20 .20 .25
2544 @item Name @tab Argument @tab Return type @tab Standard
2545 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2552 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
2556 @cindex Bessel function, first kind
2559 @item @emph{Description}:
2560 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
2561 order 1 of @var{X}. This function is available under the name
2562 @code{BESJ1} as a GNU extension.
2564 @item @emph{Standard}:
2570 @item @emph{Syntax}:
2571 @code{RESULT = BESSEL_J1(X)}
2573 @item @emph{Arguments}:
2574 @multitable @columnfractions .15 .70
2575 @item @var{X} @tab The type shall be @code{REAL}.
2578 @item @emph{Return value}:
2579 The return value is of type @code{REAL} and lies in the
2580 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
2583 @item @emph{Example}:
2586 real(8) :: x = 1.0_8
2588 end program test_besj1
2591 @item @emph{Specific names}:
2592 @multitable @columnfractions .20 .20 .20 .25
2593 @item Name @tab Argument @tab Return type @tab Standard
2594 @item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2601 @section @code{BESSEL_JN} --- Bessel function of the first kind
2605 @cindex Bessel function, first kind
2608 @item @emph{Description}:
2609 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
2610 order @var{N} of @var{X}. This function is available under the name
2611 @code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays,
2612 their ranks and shapes shall conform.
2614 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
2615 of the first kind of the orders @var{N1} to @var{N2}.
2617 @item @emph{Standard}:
2618 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2621 Elemental function, except for the transformational function
2622 @code{BESSEL_JN(N1, N2, X)}
2624 @item @emph{Syntax}:
2625 @multitable @columnfractions .80
2626 @item @code{RESULT = BESSEL_JN(N, X)}
2627 @item @code{RESULT = BESSEL_JN(N1, N2, X)}
2630 @item @emph{Arguments}:
2631 @multitable @columnfractions .15 .70
2632 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
2633 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2634 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2635 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2636 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
2639 @item @emph{Return value}:
2640 The return value is a scalar of type @code{REAL}. It has the same
2644 The transformational function uses a recurrence algorithm which might,
2645 for some values of @var{X}, lead to different results than calls to
2646 the elemental function.
2648 @item @emph{Example}:
2651 real(8) :: x = 1.0_8
2653 end program test_besjn
2656 @item @emph{Specific names}:
2657 @multitable @columnfractions .20 .20 .20 .25
2658 @item Name @tab Argument @tab Return type @tab Standard
2659 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2660 @item @tab @code{REAL(8) X} @tab @tab
2667 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
2671 @cindex Bessel function, second kind
2674 @item @emph{Description}:
2675 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
2676 order 0 of @var{X}. This function is available under the name
2677 @code{BESY0} as a GNU extension.
2679 @item @emph{Standard}:
2680 Fortran 2008 and later
2685 @item @emph{Syntax}:
2686 @code{RESULT = BESSEL_Y0(X)}
2688 @item @emph{Arguments}:
2689 @multitable @columnfractions .15 .70
2690 @item @var{X} @tab The type shall be @code{REAL}.
2693 @item @emph{Return value}:
2694 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2696 @item @emph{Example}:
2699 real(8) :: x = 0.0_8
2701 end program test_besy0
2704 @item @emph{Specific names}:
2705 @multitable @columnfractions .20 .20 .20 .25
2706 @item Name @tab Argument @tab Return type @tab Standard
2707 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2714 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
2718 @cindex Bessel function, second kind
2721 @item @emph{Description}:
2722 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
2723 order 1 of @var{X}. This function is available under the name
2724 @code{BESY1} as a GNU extension.
2726 @item @emph{Standard}:
2727 Fortran 2008 and later
2732 @item @emph{Syntax}:
2733 @code{RESULT = BESSEL_Y1(X)}
2735 @item @emph{Arguments}:
2736 @multitable @columnfractions .15 .70
2737 @item @var{X} @tab The type shall be @code{REAL}.
2740 @item @emph{Return value}:
2741 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2743 @item @emph{Example}:
2746 real(8) :: x = 1.0_8
2748 end program test_besy1
2751 @item @emph{Specific names}:
2752 @multitable @columnfractions .20 .20 .20 .25
2753 @item Name @tab Argument @tab Return type @tab Standard
2754 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2761 @section @code{BESSEL_YN} --- Bessel function of the second kind
2765 @cindex Bessel function, second kind
2768 @item @emph{Description}:
2769 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
2770 order @var{N} of @var{X}. This function is available under the name
2771 @code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays,
2772 their ranks and shapes shall conform.
2774 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
2775 of the first kind of the orders @var{N1} to @var{N2}.
2777 @item @emph{Standard}:
2778 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2781 Elemental function, except for the transformational function
2782 @code{BESSEL_YN(N1, N2, X)}
2784 @item @emph{Syntax}:
2785 @multitable @columnfractions .80
2786 @item @code{RESULT = BESSEL_YN(N, X)}
2787 @item @code{RESULT = BESSEL_YN(N1, N2, X)}
2790 @item @emph{Arguments}:
2791 @multitable @columnfractions .15 .70
2792 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} .
2793 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2794 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2795 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2796 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
2799 @item @emph{Return value}:
2800 The return value is a scalar of type @code{REAL}. It has the same
2804 The transformational function uses a recurrence algorithm which might,
2805 for some values of @var{X}, lead to different results than calls to
2806 the elemental function.
2808 @item @emph{Example}:
2811 real(8) :: x = 1.0_8
2813 end program test_besyn
2816 @item @emph{Specific names}:
2817 @multitable @columnfractions .20 .20 .20 .25
2818 @item Name @tab Argument @tab Return type @tab Standard
2819 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2820 @item @tab @code{REAL(8) X} @tab @tab
2827 @section @code{BGE} --- Bitwise greater than or equal to
2829 @cindex bitwise comparison
2832 @item @emph{Description}:
2833 Determines whether an integral is a bitwise greater than or equal to
2836 @item @emph{Standard}:
2837 Fortran 2008 and later
2842 @item @emph{Syntax}:
2843 @code{RESULT = BGE(I, J)}
2845 @item @emph{Arguments}:
2846 @multitable @columnfractions .15 .70
2847 @item @var{I} @tab Shall be of @code{INTEGER} type.
2848 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2852 @item @emph{Return value}:
2853 The return value is of type @code{LOGICAL} and of the default kind.
2855 @item @emph{See also}:
2864 @section @code{BGT} --- Bitwise greater than
2866 @cindex bitwise comparison
2869 @item @emph{Description}:
2870 Determines whether an integral is a bitwise greater than another.
2872 @item @emph{Standard}:
2873 Fortran 2008 and later
2878 @item @emph{Syntax}:
2879 @code{RESULT = BGT(I, J)}
2881 @item @emph{Arguments}:
2882 @multitable @columnfractions .15 .70
2883 @item @var{I} @tab Shall be of @code{INTEGER} type.
2884 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2888 @item @emph{Return value}:
2889 The return value is of type @code{LOGICAL} and of the default kind.
2891 @item @emph{See also}:
2900 @section @code{BIT_SIZE} --- Bit size inquiry function
2902 @cindex bits, number of
2903 @cindex size of a variable, in bits
2906 @item @emph{Description}:
2907 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
2908 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
2909 independent of the actual value of @var{I}.
2911 @item @emph{Standard}:
2912 Fortran 90 and later
2917 @item @emph{Syntax}:
2918 @code{RESULT = BIT_SIZE(I)}
2920 @item @emph{Arguments}:
2921 @multitable @columnfractions .15 .70
2922 @item @var{I} @tab The type shall be @code{INTEGER}.
2925 @item @emph{Return value}:
2926 The return value is of type @code{INTEGER}
2928 @item @emph{Example}:
2930 program test_bit_size
2935 end program test_bit_size
2942 @section @code{BLE} --- Bitwise less than or equal to
2944 @cindex bitwise comparison
2947 @item @emph{Description}:
2948 Determines whether an integral is a bitwise less than or equal to
2951 @item @emph{Standard}:
2952 Fortran 2008 and later
2957 @item @emph{Syntax}:
2958 @code{RESULT = BLE(I, J)}
2960 @item @emph{Arguments}:
2961 @multitable @columnfractions .15 .70
2962 @item @var{I} @tab Shall be of @code{INTEGER} type.
2963 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2967 @item @emph{Return value}:
2968 The return value is of type @code{LOGICAL} and of the default kind.
2970 @item @emph{See also}:
2979 @section @code{BLT} --- Bitwise less than
2981 @cindex bitwise comparison
2984 @item @emph{Description}:
2985 Determines whether an integral is a bitwise less than another.
2987 @item @emph{Standard}:
2988 Fortran 2008 and later
2993 @item @emph{Syntax}:
2994 @code{RESULT = BLT(I, J)}
2996 @item @emph{Arguments}:
2997 @multitable @columnfractions .15 .70
2998 @item @var{I} @tab Shall be of @code{INTEGER} type.
2999 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
3003 @item @emph{Return value}:
3004 The return value is of type @code{LOGICAL} and of the default kind.
3006 @item @emph{See also}:
3015 @section @code{BTEST} --- Bit test function
3021 @cindex bits, testing
3024 @item @emph{Description}:
3025 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
3026 in @var{I} is set. The counting of the bits starts at 0.
3028 @item @emph{Standard}:
3029 Fortran 90 and later, has overloads that are GNU extensions
3034 @item @emph{Syntax}:
3035 @code{RESULT = BTEST(I, POS)}
3037 @item @emph{Arguments}:
3038 @multitable @columnfractions .15 .70
3039 @item @var{I} @tab The type shall be @code{INTEGER}.
3040 @item @var{POS} @tab The type shall be @code{INTEGER}.
3043 @item @emph{Return value}:
3044 The return value is of type @code{LOGICAL}
3046 @item @emph{Example}:
3049 integer :: i = 32768 + 1024 + 64
3053 bool = btest(i, pos)
3056 end program test_btest
3059 @item @emph{Specific names}:
3060 @multitable @columnfractions .20 .20 .20 .25
3061 @item Name @tab Argument @tab Return type @tab Standard
3062 @item @code{BTEST(I,POS)} @tab @code{INTEGER I,POS} @tab @code{LOGICAL} @tab Fortran 95 and later
3063 @item @code{BBTEST(I,POS)} @tab @code{INTEGER(1) I,POS} @tab @code{LOGICAL(1)} @tab GNU extension
3064 @item @code{BITEST(I,POS)} @tab @code{INTEGER(2) I,POS} @tab @code{LOGICAL(2)} @tab GNU extension
3065 @item @code{BJTEST(I,POS)} @tab @code{INTEGER(4) I,POS} @tab @code{LOGICAL(4)} @tab GNU extension
3066 @item @code{BKTEST(I,POS)} @tab @code{INTEGER(8) I,POS} @tab @code{LOGICAL(8)} @tab GNU extension
3071 @section @code{C_ASSOCIATED} --- Status of a C pointer
3072 @fnindex C_ASSOCIATED
3073 @cindex association status, C pointer
3074 @cindex pointer, C association status
3077 @item @emph{Description}:
3078 @code{C_ASSOCIATED(c_ptr_1[, c_ptr_2])} determines the status of the C pointer
3079 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
3081 @item @emph{Standard}:
3082 Fortran 2003 and later
3087 @item @emph{Syntax}:
3088 @code{RESULT = C_ASSOCIATED(c_ptr_1[, c_ptr_2])}
3090 @item @emph{Arguments}:
3091 @multitable @columnfractions .15 .70
3092 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
3093 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
3096 @item @emph{Return value}:
3097 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
3098 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
3099 point to different addresses.
3101 @item @emph{Example}:
3103 subroutine association_test(a,b)
3104 use iso_c_binding, only: c_associated, c_loc, c_ptr
3108 if(c_associated(b, c_loc(a))) &
3109 stop 'b and a do not point to same target'
3110 end subroutine association_test
3113 @item @emph{See also}:
3120 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
3121 @fnindex C_F_POINTER
3122 @cindex pointer, convert C to Fortran
3125 @item @emph{Description}:
3126 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} assigns the target of the C pointer
3127 @var{CPTR} to the Fortran pointer @var{FPTR} and specifies its shape.
3129 @item @emph{Standard}:
3130 Fortran 2003 and later
3135 @item @emph{Syntax}:
3136 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
3138 @item @emph{Arguments}:
3139 @multitable @columnfractions .15 .70
3140 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
3142 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
3144 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
3145 with @code{INTENT(IN)}. It shall be present
3146 if and only if @var{fptr} is an array. The size
3147 must be equal to the rank of @var{fptr}.
3150 @item @emph{Example}:
3156 subroutine my_routine(p) bind(c,name='myC_func')
3158 type(c_ptr), intent(out) :: p
3162 real,pointer :: a(:)
3163 call my_routine(cptr)
3164 call c_f_pointer(cptr, a, [12])
3168 @item @emph{See also}:
3170 @ref{C_F_PROCPOINTER}
3174 @node C_F_PROCPOINTER
3175 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
3176 @fnindex C_F_PROCPOINTER
3177 @cindex pointer, C address of pointers
3180 @item @emph{Description}:
3181 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
3182 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
3184 @item @emph{Standard}:
3185 Fortran 2003 and later
3190 @item @emph{Syntax}:
3191 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
3193 @item @emph{Arguments}:
3194 @multitable @columnfractions .15 .70
3195 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
3197 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
3201 @item @emph{Example}:
3209 real(c_float), intent(in) :: a
3210 real(c_float) :: func
3214 function getIterFunc() bind(c,name="getIterFunc")
3216 type(c_funptr) :: getIterFunc
3219 type(c_funptr) :: cfunptr
3220 procedure(func), pointer :: myFunc
3221 cfunptr = getIterFunc()
3222 call c_f_procpointer(cfunptr, myFunc)
3226 @item @emph{See also}:
3233 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
3235 @cindex pointer, C address of procedures
3238 @item @emph{Description}:
3239 @code{C_FUNLOC(x)} determines the C address of the argument.
3241 @item @emph{Standard}:
3242 Fortran 2003 and later
3247 @item @emph{Syntax}:
3248 @code{RESULT = C_FUNLOC(x)}
3250 @item @emph{Arguments}:
3251 @multitable @columnfractions .15 .70
3252 @item @var{x} @tab Interoperable function or pointer to such function.
3255 @item @emph{Return value}:
3256 The return value is of type @code{C_FUNPTR} and contains the C address
3259 @item @emph{Example}:
3265 subroutine sub(a) bind(c)
3275 subroutine my_routine(p) bind(c,name='myC_func')
3277 type(c_funptr), intent(in) :: p
3280 call my_routine(c_funloc(sub))
3284 @item @emph{See also}:
3285 @ref{C_ASSOCIATED}, @gol
3287 @ref{C_F_POINTER}, @gol
3288 @ref{C_F_PROCPOINTER}
3293 @section @code{C_LOC} --- Obtain the C address of an object
3295 @cindex procedure pointer, convert C to Fortran
3298 @item @emph{Description}:
3299 @code{C_LOC(X)} determines the C address of the argument.
3301 @item @emph{Standard}:
3302 Fortran 2003 and later
3307 @item @emph{Syntax}:
3308 @code{RESULT = C_LOC(X)}
3310 @item @emph{Arguments}:
3311 @multitable @columnfractions .10 .75
3312 @item @var{X} @tab Shall have either the POINTER or TARGET attribute. It shall not be a coindexed object. It shall either be a variable with interoperable type and kind type parameters, or be a scalar, nonpolymorphic variable with no length type parameters.
3316 @item @emph{Return value}:
3317 The return value is of type @code{C_PTR} and contains the C address
3320 @item @emph{Example}:
3322 subroutine association_test(a,b)
3323 use iso_c_binding, only: c_associated, c_loc, c_ptr
3327 if(c_associated(b, c_loc(a))) &
3328 stop 'b and a do not point to same target'
3329 end subroutine association_test
3332 @item @emph{See also}:
3333 @ref{C_ASSOCIATED}, @gol
3334 @ref{C_FUNLOC}, @gol
3335 @ref{C_F_POINTER}, @gol
3336 @ref{C_F_PROCPOINTER}
3341 @section @code{C_SIZEOF} --- Size in bytes of an expression
3343 @cindex expression size
3344 @cindex size of an expression
3347 @item @emph{Description}:
3348 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
3349 expression @code{X} occupies.
3351 @item @emph{Standard}:
3355 Inquiry function of the module @code{ISO_C_BINDING}
3357 @item @emph{Syntax}:
3358 @code{N = C_SIZEOF(X)}
3360 @item @emph{Arguments}:
3361 @multitable @columnfractions .15 .70
3362 @item @var{X} @tab The argument shall be an interoperable data entity.
3365 @item @emph{Return value}:
3366 The return value is of type integer and of the system-dependent kind
3367 @code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the
3368 number of bytes occupied by the argument. If the argument has the
3369 @code{POINTER} attribute, the number of bytes of the storage area pointed
3370 to is returned. If the argument is of a derived type with @code{POINTER}
3371 or @code{ALLOCATABLE} components, the return value does not account for
3372 the sizes of the data pointed to by these components.
3374 @item @emph{Example}:
3378 real(c_float) :: r, s(5)
3379 print *, (c_sizeof(s)/c_sizeof(r) == 5)
3382 The example will print @code{T} unless you are using a platform
3383 where default @code{REAL} variables are unusually padded.
3385 @item @emph{See also}:
3392 @section @code{CEILING} --- Integer ceiling function
3395 @cindex rounding, ceiling
3398 @item @emph{Description}:
3399 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
3401 @item @emph{Standard}:
3402 Fortran 95 and later
3407 @item @emph{Syntax}:
3408 @code{RESULT = CEILING(A [, KIND])}
3410 @item @emph{Arguments}:
3411 @multitable @columnfractions .15 .70
3412 @item @var{A} @tab The type shall be @code{REAL}.
3413 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3414 expression indicating the kind parameter of the result.
3417 @item @emph{Return value}:
3418 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
3419 and a default-kind @code{INTEGER} otherwise.
3421 @item @emph{Example}:
3423 program test_ceiling
3426 print *, ceiling(x) ! returns 64
3427 print *, ceiling(y) ! returns -63
3428 end program test_ceiling
3431 @item @emph{See also}:
3439 @section @code{CHAR} --- Character conversion function
3441 @cindex conversion, to character
3444 @item @emph{Description}:
3445 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
3447 @item @emph{Standard}:
3448 Fortran 77 and later
3453 @item @emph{Syntax}:
3454 @code{RESULT = CHAR(I [, KIND])}
3456 @item @emph{Arguments}:
3457 @multitable @columnfractions .15 .70
3458 @item @var{I} @tab The type shall be @code{INTEGER}.
3459 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3460 expression indicating the kind parameter of the result.
3463 @item @emph{Return value}:
3464 The return value is of type @code{CHARACTER(1)}
3466 @item @emph{Example}:
3472 print *, i, c ! returns 'J'
3473 end program test_char
3476 @item @emph{Specific names}:
3477 @multitable @columnfractions .18 .18 .24 .25
3478 @item Name @tab Argument @tab Return type @tab Standard
3479 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab Fortran 77 and later
3483 See @ref{ICHAR} for a discussion of converting between numerical values
3484 and formatted string representations.
3486 @item @emph{See also}:
3496 @section @code{CHDIR} --- Change working directory
3498 @cindex system, working directory
3501 @item @emph{Description}:
3502 Change current working directory to a specified path.
3504 This intrinsic is provided in both subroutine and function forms; however,
3505 only one form can be used in any given program unit.
3507 @item @emph{Standard}:
3511 Subroutine, function
3513 @item @emph{Syntax}:
3514 @multitable @columnfractions .80
3515 @item @code{CALL CHDIR(NAME [, STATUS])}
3516 @item @code{STATUS = CHDIR(NAME)}
3519 @item @emph{Arguments}:
3520 @multitable @columnfractions .15 .70
3521 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
3522 kind and shall specify a valid path within the file system.
3523 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
3524 kind. Returns 0 on success, and a system specific and nonzero error code
3528 @item @emph{Example}:
3531 CHARACTER(len=255) :: path
3533 WRITE(*,*) TRIM(path)
3536 WRITE(*,*) TRIM(path)
3540 @item @emph{See also}:
3547 @section @code{CHMOD} --- Change access permissions of files
3549 @cindex file system, change access mode
3552 @item @emph{Description}:
3553 @code{CHMOD} changes the permissions of a file.
3555 This intrinsic is provided in both subroutine and function forms; however,
3556 only one form can be used in any given program unit.
3558 @item @emph{Standard}:
3562 Subroutine, function
3564 @item @emph{Syntax}:
3565 @multitable @columnfractions .80
3566 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
3567 @item @code{STATUS = CHMOD(NAME, MODE)}
3570 @item @emph{Arguments}:
3571 @multitable @columnfractions .15 .70
3573 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
3574 file name. Trailing blanks are ignored unless the character
3575 @code{achar(0)} is present, then all characters up to and excluding
3576 @code{achar(0)} are used as the file name.
3578 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
3579 file permission. @var{MODE} uses the same syntax as the @code{chmod} utility
3580 as defined by the POSIX standard. The argument shall either be a string of
3581 a nonnegative octal number or a symbolic mode.
3583 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
3584 @code{0} on success and nonzero otherwise.
3587 @item @emph{Return value}:
3588 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
3591 @item @emph{Example}:
3592 @code{CHMOD} as subroutine
3597 call chmod('test.dat','u+x',status)
3598 print *, 'Status: ', status
3599 end program chmod_test
3601 @code{CHMOD} as function:
3606 status = chmod('test.dat','u+x')
3607 print *, 'Status: ', status
3608 end program chmod_test
3616 @section @code{CMPLX} --- Complex conversion function
3618 @cindex complex numbers, conversion to
3619 @cindex conversion, to complex
3622 @item @emph{Description}:
3623 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
3624 the real component. If @var{Y} is present it is converted to the imaginary
3625 component. If @var{Y} is not present then the imaginary component is set to
3626 0.0. If @var{X} is complex then @var{Y} must not be present.
3628 @item @emph{Standard}:
3629 Fortran 77 and later
3634 @item @emph{Syntax}:
3635 @code{RESULT = CMPLX(X [, Y [, KIND]])}
3637 @item @emph{Arguments}:
3638 @multitable @columnfractions .15 .70
3639 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3641 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
3642 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
3643 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3644 expression indicating the kind parameter of the result.
3647 @item @emph{Return value}:
3648 The return value is of @code{COMPLEX} type, with a kind equal to
3649 @var{KIND} if it is specified. If @var{KIND} is not specified, the
3650 result is of the default @code{COMPLEX} kind, regardless of the kinds of
3651 @var{X} and @var{Y}.
3653 @item @emph{Example}:
3660 print *, z, cmplx(x)
3661 end program test_cmplx
3664 @item @emph{See also}:
3671 @section @code{CO_BROADCAST} --- Copy a value to all images the current set of images
3672 @fnindex CO_BROADCAST
3673 @cindex Collectives, value broadcasting
3676 @item @emph{Description}:
3677 @code{CO_BROADCAST} copies the value of argument @var{A} on the image with
3678 image index @code{SOURCE_IMAGE} to all images in the current team. @var{A}
3679 becomes defined as if by intrinsic assignment. If the execution was
3680 successful and @var{STAT} is present, it is assigned the value zero. If the
3681 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3682 @var{ERRMSG} gets assigned a value describing the occurred error.
3684 @item @emph{Standard}:
3685 Technical Specification (TS) 18508 or later
3688 Collective subroutine
3690 @item @emph{Syntax}:
3691 @code{CALL CO_BROADCAST(A, SOURCE_IMAGE [, STAT, ERRMSG])}
3693 @item @emph{Arguments}:
3694 @multitable @columnfractions .20 .65
3695 @item @var{A} @tab INTENT(INOUT) argument; shall have the same
3696 dynamic type and type paramters on all images of the current team. If it
3697 is an array, it shall have the same shape on all images.
3698 @item @var{SOURCE_IMAGE} @tab a scalar integer expression.
3699 It shall have the same the same value on all images and refer to an
3700 image of the current team.
3701 @item @var{STAT} @tab (optional) a scalar integer variable
3702 @item @var{ERRMSG} @tab (optional) a scalar character variable
3705 @item @emph{Example}:
3709 if (this_image() == 1) then
3712 call co_broadcast (val, source_image=1)
3713 print *, this_image, ":", val
3717 @item @emph{See also}:
3727 @section @code{CO_MAX} --- Maximal value on the current set of images
3729 @cindex Collectives, maximal value
3732 @item @emph{Description}:
3733 @code{CO_MAX} determines element-wise the maximal value of @var{A} on all
3734 images of the current team. If @var{RESULT_IMAGE} is present, the maximum
3735 values are returned in @var{A} on the specified image only and the value
3736 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3737 not present, the value is returned on all images. If the execution was
3738 successful and @var{STAT} is present, it is assigned the value zero. If the
3739 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3740 @var{ERRMSG} gets assigned a value describing the occurred error.
3742 @item @emph{Standard}:
3743 Technical Specification (TS) 18508 or later
3746 Collective subroutine
3748 @item @emph{Syntax}:
3749 @code{CALL CO_MAX(A [, RESULT_IMAGE, STAT, ERRMSG])}
3751 @item @emph{Arguments}:
3752 @multitable @columnfractions .20 .65
3753 @item @var{A} @tab shall be an integer, real or character variable,
3754 which has the same type and type parameters on all images of the team.
3755 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3756 present, it shall have the same the same value on all images and refer to an
3757 image of the current team.
3758 @item @var{STAT} @tab (optional) a scalar integer variable
3759 @item @var{ERRMSG} @tab (optional) a scalar character variable
3762 @item @emph{Example}:
3767 call co_max (val, result_image=1)
3768 if (this_image() == 1) then
3769 write(*,*) "Maximal value", val ! prints num_images()
3774 @item @emph{See also}:
3777 @ref{CO_REDUCE}, @gol
3784 @section @code{CO_MIN} --- Minimal value on the current set of images
3786 @cindex Collectives, minimal value
3789 @item @emph{Description}:
3790 @code{CO_MIN} determines element-wise the minimal value of @var{A} on all
3791 images of the current team. If @var{RESULT_IMAGE} is present, the minimal
3792 values are returned in @var{A} on the specified image only and the value
3793 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3794 not present, the value is returned on all images. If the execution was
3795 successful and @var{STAT} is present, it is assigned the value zero. If the
3796 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3797 @var{ERRMSG} gets assigned a value describing the occurred error.
3799 @item @emph{Standard}:
3800 Technical Specification (TS) 18508 or later
3803 Collective subroutine
3805 @item @emph{Syntax}:
3806 @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3808 @item @emph{Arguments}:
3809 @multitable @columnfractions .20 .65
3810 @item @var{A} @tab shall be an integer, real or character variable,
3811 which has the same type and type parameters on all images of the team.
3812 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3813 present, it shall have the same the same value on all images and refer to an
3814 image of the current team.
3815 @item @var{STAT} @tab (optional) a scalar integer variable
3816 @item @var{ERRMSG} @tab (optional) a scalar character variable
3819 @item @emph{Example}:
3824 call co_min (val, result_image=1)
3825 if (this_image() == 1) then
3826 write(*,*) "Minimal value", val ! prints 1
3831 @item @emph{See also}:
3834 @ref{CO_REDUCE}, @gol
3841 @section @code{CO_REDUCE} --- Reduction of values on the current set of images
3843 @cindex Collectives, generic reduction
3846 @item @emph{Description}:
3847 @code{CO_REDUCE} determines element-wise the reduction of the value of @var{A}
3848 on all images of the current team. The pure function passed as @var{OPERATOR}
3849 is used to pairwise reduce the values of @var{A} by passing either the value
3850 of @var{A} of different images or the result values of such a reduction as
3851 argument. If @var{A} is an array, the deduction is done element wise. If
3852 @var{RESULT_IMAGE} is present, the result values are returned in @var{A} on
3853 the specified image only and the value of @var{A} on the other images become
3854 undefined. If @var{RESULT_IMAGE} is not present, the value is returned on all
3855 images. If the execution was successful and @var{STAT} is present, it is
3856 assigned the value zero. If the execution failed, @var{STAT} gets assigned
3857 a nonzero value and, if present, @var{ERRMSG} gets assigned a value describing
3860 @item @emph{Standard}:
3861 Technical Specification (TS) 18508 or later
3864 Collective subroutine
3866 @item @emph{Syntax}:
3867 @code{CALL CO_REDUCE(A, OPERATOR, [, RESULT_IMAGE, STAT, ERRMSG])}
3869 @item @emph{Arguments}:
3870 @multitable @columnfractions .20 .65
3871 @item @var{A} @tab is an @code{INTENT(INOUT)} argument and shall be
3872 nonpolymorphic. If it is allocatable, it shall be allocated; if it is a pointer,
3873 it shall be associated. @var{A} shall have the same type and type parameters on
3874 all images of the team; if it is an array, it shall have the same shape on all
3876 @item @var{OPERATOR} @tab pure function with two scalar nonallocatable
3877 arguments, which shall be nonpolymorphic and have the same type and type
3878 parameters as @var{A}. The function shall return a nonallocatable scalar of
3879 the same type and type parameters as @var{A}. The function shall be the same on
3880 all images and with regards to the arguments mathematically commutative and
3881 associative. Note that @var{OPERATOR} may not be an elemental function, unless
3882 it is an intrisic function.
3883 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3884 present, it shall have the same the same value on all images and refer to an
3885 image of the current team.
3886 @item @var{STAT} @tab (optional) a scalar integer variable
3887 @item @var{ERRMSG} @tab (optional) a scalar character variable
3890 @item @emph{Example}:
3895 call co_reduce (val, result_image=1, operator=myprod)
3896 if (this_image() == 1) then
3897 write(*,*) "Product value", val ! prints num_images() factorial
3900 pure function myprod(a, b)
3901 integer, value :: a, b
3909 While the rules permit in principle an intrinsic function, none of the
3910 intrinsics in the standard fulfill the criteria of having a specific
3911 function, which takes two arguments of the same type and returning that
3914 @item @emph{See also}:
3924 @section @code{CO_SUM} --- Sum of values on the current set of images
3926 @cindex Collectives, sum of values
3929 @item @emph{Description}:
3930 @code{CO_SUM} sums up the values of each element of @var{A} on all
3931 images of the current team. If @var{RESULT_IMAGE} is present, the summed-up
3932 values are returned in @var{A} on the specified image only and the value
3933 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3934 not present, the value is returned on all images. If the execution was
3935 successful and @var{STAT} is present, it is assigned the value zero. If the
3936 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3937 @var{ERRMSG} gets assigned a value describing the occurred error.
3939 @item @emph{Standard}:
3940 Technical Specification (TS) 18508 or later
3943 Collective subroutine
3945 @item @emph{Syntax}:
3946 @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3948 @item @emph{Arguments}:
3949 @multitable @columnfractions .20 .65
3950 @item @var{A} @tab shall be an integer, real or complex variable,
3951 which has the same type and type parameters on all images of the team.
3952 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3953 present, it shall have the same the same value on all images and refer to an
3954 image of the current team.
3955 @item @var{STAT} @tab (optional) a scalar integer variable
3956 @item @var{ERRMSG} @tab (optional) a scalar character variable
3959 @item @emph{Example}:
3964 call co_sum (val, result_image=1)
3965 if (this_image() == 1) then
3966 write(*,*) "The sum is ", val ! prints (n**2 + n)/2,
3967 ! with n = num_images()
3972 @item @emph{See also}:
3975 @ref{CO_REDUCE}, @gol
3981 @node COMMAND_ARGUMENT_COUNT
3982 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
3983 @fnindex COMMAND_ARGUMENT_COUNT
3984 @cindex command-line arguments
3985 @cindex command-line arguments, number of
3986 @cindex arguments, to program
3989 @item @emph{Description}:
3990 @code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the
3991 command line when the containing program was invoked.
3993 @item @emph{Standard}:
3994 Fortran 2003 and later
3999 @item @emph{Syntax}:
4000 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
4002 @item @emph{Arguments}:
4003 @multitable @columnfractions .15 .70
4007 @item @emph{Return value}:
4008 The return value is an @code{INTEGER} of default kind.
4010 @item @emph{Example}:
4012 program test_command_argument_count
4014 count = command_argument_count()
4016 end program test_command_argument_count
4019 @item @emph{See also}:
4020 @ref{GET_COMMAND}, @gol
4021 @ref{GET_COMMAND_ARGUMENT}
4026 @node COMPILER_OPTIONS
4027 @section @code{COMPILER_OPTIONS} --- Options passed to the compiler
4028 @fnindex COMPILER_OPTIONS
4029 @cindex flags inquiry function
4030 @cindex options inquiry function
4031 @cindex compiler flags inquiry function
4034 @item @emph{Description}:
4035 @code{COMPILER_OPTIONS} returns a string with the options used for
4038 @item @emph{Standard}:
4042 Inquiry function of the module @code{ISO_FORTRAN_ENV}
4044 @item @emph{Syntax}:
4045 @code{STR = COMPILER_OPTIONS()}
4047 @item @emph{Arguments}:
4050 @item @emph{Return value}:
4051 The return value is a default-kind string with system-dependent length.
4052 It contains the compiler flags used to compile the file, which called
4053 the @code{COMPILER_OPTIONS} intrinsic.
4055 @item @emph{Example}:
4058 print '(4a)', 'This file was compiled by ', &
4059 compiler_version(), ' using the options ', &
4064 @item @emph{See also}:
4065 @ref{COMPILER_VERSION}, @gol
4066 @ref{ISO_FORTRAN_ENV}
4071 @node COMPILER_VERSION
4072 @section @code{COMPILER_VERSION} --- Compiler version string
4073 @fnindex COMPILER_VERSION
4074 @cindex compiler, name and version
4075 @cindex version of the compiler
4078 @item @emph{Description}:
4079 @code{COMPILER_VERSION} returns a string with the name and the
4080 version of the compiler.
4082 @item @emph{Standard}:
4086 Inquiry function of the module @code{ISO_FORTRAN_ENV}
4088 @item @emph{Syntax}:
4089 @code{STR = COMPILER_VERSION()}
4091 @item @emph{Arguments}:
4094 @item @emph{Return value}:
4095 The return value is a default-kind string with system-dependent length.
4096 It contains the name of the compiler and its version number.
4098 @item @emph{Example}:
4101 print '(4a)', 'This file was compiled by ', &
4102 compiler_version(), ' using the options ', &
4107 @item @emph{See also}:
4108 @ref{COMPILER_OPTIONS}, @gol
4109 @ref{ISO_FORTRAN_ENV}
4115 @section @code{COMPLEX} --- Complex conversion function
4117 @cindex complex numbers, conversion to
4118 @cindex conversion, to complex
4121 @item @emph{Description}:
4122 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
4123 to the real component and @var{Y} is converted to the imaginary
4126 @item @emph{Standard}:
4132 @item @emph{Syntax}:
4133 @code{RESULT = COMPLEX(X, Y)}
4135 @item @emph{Arguments}:
4136 @multitable @columnfractions .15 .70
4137 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
4138 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
4141 @item @emph{Return value}:
4142 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
4143 value is of default @code{COMPLEX} type.
4145 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
4146 type and one is of @code{INTEGER} type, then the return value is of
4147 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
4148 argument with the highest precision.
4150 @item @emph{Example}:
4152 program test_complex
4155 print *, complex(i, x)
4156 end program test_complex
4159 @item @emph{See also}:
4166 @section @code{CONJG} --- Complex conjugate function
4169 @cindex complex conjugate
4172 @item @emph{Description}:
4173 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
4174 then the result is @code{(x, -y)}
4176 @item @emph{Standard}:
4177 Fortran 77 and later, has an overload that is a GNU extension
4182 @item @emph{Syntax}:
4185 @item @emph{Arguments}:
4186 @multitable @columnfractions .15 .70
4187 @item @var{Z} @tab The type shall be @code{COMPLEX}.
4190 @item @emph{Return value}:
4191 The return value is of type @code{COMPLEX}.
4193 @item @emph{Example}:
4196 complex :: z = (2.0, 3.0)
4197 complex(8) :: dz = (2.71_8, -3.14_8)
4202 end program test_conjg
4205 @item @emph{Specific names}:
4206 @multitable @columnfractions .20 .20 .20 .25
4207 @item Name @tab Argument @tab Return type @tab Standard
4208 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
4215 @section @code{COS} --- Cosine function
4221 @cindex trigonometric function, cosine
4225 @item @emph{Description}:
4226 @code{COS(X)} computes the cosine of @var{X}.
4228 @item @emph{Standard}:
4229 Fortran 77 and later, has overloads that are GNU extensions
4234 @item @emph{Syntax}:
4235 @code{RESULT = COS(X)}
4237 @item @emph{Arguments}:
4238 @multitable @columnfractions .15 .70
4239 @item @var{X} @tab The type shall be @code{REAL} or
4243 @item @emph{Return value}:
4244 The return value is of the same type and kind as @var{X}. The real part
4245 of the result is in radians. If @var{X} is of the type @code{REAL},
4246 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
4248 @item @emph{Example}:
4253 end program test_cos
4256 @item @emph{Specific names}:
4257 @multitable @columnfractions .20 .20 .20 .25
4258 @item Name @tab Argument @tab Return type @tab Standard
4259 @item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
4260 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
4261 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
4262 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4263 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4266 @item @emph{See also}:
4267 Inverse function: @gol
4269 Degrees function: @gol
4276 @section @code{COSD} --- Cosine function, degrees
4282 @cindex trigonometric function, cosine, degrees
4283 @cindex cosine, degrees
4286 @item @emph{Description}:
4287 @code{COSD(X)} computes the cosine of @var{X} in degrees.
4289 This function is for compatibility only and should be avoided in favor of
4290 standard constructs wherever possible.
4292 @item @emph{Standard}:
4293 GNU extension, enabled with @option{-fdec-math}.
4298 @item @emph{Syntax}:
4299 @code{RESULT = COSD(X)}
4301 @item @emph{Arguments}:
4302 @multitable @columnfractions .15 .70
4303 @item @var{X} @tab The type shall be @code{REAL} or
4307 @item @emph{Return value}:
4308 The return value is of the same type and kind as @var{X}. The real part
4309 of the result is in degrees. If @var{X} is of the type @code{REAL},
4310 the return value lies in the range @math{ -1 \leq \cosd (x) \leq 1}.
4312 @item @emph{Example}:
4317 end program test_cosd
4320 @item @emph{Specific names}:
4321 @multitable @columnfractions .20 .20 .20 .25
4322 @item Name @tab Argument @tab Return type @tab Standard
4323 @item @code{COSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
4324 @item @code{DCOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4325 @item @code{CCOSD(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU extension
4326 @item @code{ZCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4327 @item @code{CDCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4330 @item @emph{See also}:
4331 Inverse function: @gol
4333 Radians function: @gol
4340 @section @code{COSH} --- Hyperbolic cosine function
4343 @cindex hyperbolic cosine
4344 @cindex hyperbolic function, cosine
4345 @cindex cosine, hyperbolic
4348 @item @emph{Description}:
4349 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
4351 @item @emph{Standard}:
4352 Fortran 77 and later, for a complex argument Fortran 2008 or later
4357 @item @emph{Syntax}:
4360 @item @emph{Arguments}:
4361 @multitable @columnfractions .15 .70
4362 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4365 @item @emph{Return value}:
4366 The return value has same type and kind as @var{X}. If @var{X} is
4367 complex, the imaginary part of the result is in radians. If @var{X}
4368 is @code{REAL}, the return value has a lower bound of one,
4369 @math{\cosh (x) \geq 1}.
4371 @item @emph{Example}:
4374 real(8) :: x = 1.0_8
4376 end program test_cosh
4379 @item @emph{Specific names}:
4380 @multitable @columnfractions .20 .20 .20 .25
4381 @item Name @tab Argument @tab Return type @tab Standard
4382 @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
4383 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
4386 @item @emph{See also}:
4387 Inverse function: @gol
4394 @section @code{COTAN} --- Cotangent function
4397 @cindex trigonometric function, cotangent
4401 @item @emph{Description}:
4402 @code{COTAN(X)} computes the cotangent of @var{X}. Equivalent to @code{COS(x)}
4403 divided by @code{SIN(x)}, or @code{1 / TAN(x)}.
4405 This function is for compatibility only and should be avoided in favor of
4406 standard constructs wherever possible.
4408 @item @emph{Standard}:
4409 GNU extension, enabled with @option{-fdec-math}.
4414 @item @emph{Syntax}:
4415 @code{RESULT = COTAN(X)}
4417 @item @emph{Arguments}:
4418 @multitable @columnfractions .15 .70
4419 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4422 @item @emph{Return value}:
4423 The return value has same type and kind as @var{X}, and its value is in radians.
4425 @item @emph{Example}:
4428 real(8) :: x = 0.165_8
4430 end program test_cotan
4433 @item @emph{Specific names}:
4434 @multitable @columnfractions .20 .20 .20 .25
4435 @item Name @tab Argument @tab Return type @tab Standard
4436 @item @code{COTAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
4437 @item @code{DCOTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4440 @item @emph{See also}:
4441 Converse function: @gol
4443 Degrees function: @gol
4450 @section @code{COTAND} --- Cotangent function, degrees
4453 @cindex trigonometric function, cotangent, degrees
4454 @cindex cotangent, degrees
4457 @item @emph{Description}:
4458 @code{COTAND(X)} computes the cotangent of @var{X} in degrees. Equivalent to
4459 @code{COSD(x)} divided by @code{SIND(x)}, or @code{1 / TAND(x)}.
4461 @item @emph{Standard}:
4462 GNU extension, enabled with @option{-fdec-math}.
4464 This function is for compatibility only and should be avoided in favor of
4465 standard constructs wherever possible.
4470 @item @emph{Syntax}:
4471 @code{RESULT = COTAND(X)}
4473 @item @emph{Arguments}:
4474 @multitable @columnfractions .15 .70
4475 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4478 @item @emph{Return value}:
4479 The return value has same type and kind as @var{X}, and its value is in degrees.
4481 @item @emph{Example}:
4484 real(8) :: x = 0.165_8
4486 end program test_cotand
4489 @item @emph{Specific names}:
4490 @multitable @columnfractions .20 .20 .20 .25
4491 @item Name @tab Argument @tab Return type @tab Standard
4492 @item @code{COTAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
4493 @item @code{DCOTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4496 @item @emph{See also}:
4497 Converse function: @gol
4499 Radians function: @gol
4506 @section @code{COUNT} --- Count function
4508 @cindex array, conditionally count elements
4509 @cindex array, element counting
4510 @cindex array, number of elements
4513 @item @emph{Description}:
4515 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
4516 or, if the @var{DIM} argument is supplied, counts the number of
4517 elements along each row of the array in the @var{DIM} direction.
4518 If the array has zero size, or all of the elements of @var{MASK} are
4519 @code{.FALSE.}, then the result is @code{0}.
4521 @item @emph{Standard}:
4522 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
4525 Transformational function
4527 @item @emph{Syntax}:
4528 @code{RESULT = COUNT(MASK [, DIM, KIND])}
4530 @item @emph{Arguments}:
4531 @multitable @columnfractions .15 .70
4532 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
4533 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
4534 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4535 expression indicating the kind parameter of the result.
4538 @item @emph{Return value}:
4539 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
4540 @var{KIND} is absent, the return value is of default integer kind.
4541 If @var{DIM} is present, the result is an array with a rank one less
4542 than the rank of @var{ARRAY}, and a size corresponding to the shape
4543 of @var{ARRAY} with the @var{DIM} dimension removed.
4545 @item @emph{Example}:
4548 integer, dimension(2,3) :: a, b
4549 logical, dimension(2,3) :: mask
4550 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
4551 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
4552 print '(3i3)', a(1,:)
4553 print '(3i3)', a(2,:)
4555 print '(3i3)', b(1,:)
4556 print '(3i3)', b(2,:)
4559 print '(3l3)', mask(1,:)
4560 print '(3l3)', mask(2,:)
4562 print '(3i3)', count(mask)
4564 print '(3i3)', count(mask, 1)
4566 print '(3i3)', count(mask, 2)
4567 end program test_count
4574 @section @code{CPU_TIME} --- CPU elapsed time in seconds
4576 @cindex time, elapsed
4579 @item @emph{Description}:
4580 Returns a @code{REAL} value representing the elapsed CPU time in
4581 seconds. This is useful for testing segments of code to determine
4584 If a time source is available, time will be reported with microsecond
4585 resolution. If no time source is available, @var{TIME} is set to
4588 Note that @var{TIME} may contain a, system dependent, arbitrary offset
4589 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
4590 value is meaningless, only differences between subsequent calls to
4591 this subroutine, as shown in the example below, should be used.
4594 @item @emph{Standard}:
4595 Fortran 95 and later
4600 @item @emph{Syntax}:
4601 @code{CALL CPU_TIME(TIME)}
4603 @item @emph{Arguments}:
4604 @multitable @columnfractions .15 .70
4605 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
4608 @item @emph{Return value}:
4611 @item @emph{Example}:
4613 program test_cpu_time
4614 real :: start, finish
4615 call cpu_time(start)
4616 ! put code to test here
4617 call cpu_time(finish)
4618 print '("Time = ",f6.3," seconds.")',finish-start
4619 end program test_cpu_time
4622 @item @emph{See also}:
4623 @ref{SYSTEM_CLOCK}, @gol
4630 @section @code{CSHIFT} --- Circular shift elements of an array
4632 @cindex array, shift circularly
4633 @cindex array, permutation
4634 @cindex array, rotate
4637 @item @emph{Description}:
4638 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
4639 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
4640 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
4641 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
4642 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
4643 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
4644 sections of @var{ARRAY} along the given dimension are shifted. Elements
4645 shifted out one end of each rank one section are shifted back in the other end.
4647 @item @emph{Standard}:
4648 Fortran 90 and later
4651 Transformational function
4653 @item @emph{Syntax}:
4654 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
4656 @item @emph{Arguments}:
4657 @multitable @columnfractions .15 .70
4658 @item @var{ARRAY} @tab Shall be an array of any type.
4659 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
4660 @item @var{DIM} @tab The type shall be @code{INTEGER}.
4663 @item @emph{Return value}:
4664 Returns an array of same type and rank as the @var{ARRAY} argument.
4666 @item @emph{Example}:
4669 integer, dimension(3,3) :: a
4670 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
4671 print '(3i3)', a(1,:)
4672 print '(3i3)', a(2,:)
4673 print '(3i3)', a(3,:)
4674 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
4676 print '(3i3)', a(1,:)
4677 print '(3i3)', a(2,:)
4678 print '(3i3)', a(3,:)
4679 end program test_cshift
4686 @section @code{CTIME} --- Convert a time into a string
4688 @cindex time, conversion to string
4689 @cindex conversion, to string
4692 @item @emph{Description}:
4693 @code{CTIME} converts a system time value, such as returned by
4694 @ref{TIME8}, to a string. The output will be of the form @samp{Sat
4695 Aug 19 18:13:14 1995}.
4697 This intrinsic is provided in both subroutine and function forms; however,
4698 only one form can be used in any given program unit.
4700 @item @emph{Standard}:
4704 Subroutine, function
4706 @item @emph{Syntax}:
4707 @multitable @columnfractions .80
4708 @item @code{CALL CTIME(TIME, RESULT)}.
4709 @item @code{RESULT = CTIME(TIME)}.
4712 @item @emph{Arguments}:
4713 @multitable @columnfractions .15 .70
4714 @item @var{TIME} @tab The type shall be of type @code{INTEGER}.
4715 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
4716 of default kind. It is an @code{INTENT(OUT)} argument. If the length
4717 of this variable is too short for the time and date string to fit
4718 completely, it will be blank on procedure return.
4721 @item @emph{Return value}:
4722 The converted date and time as a string.
4724 @item @emph{Example}:
4728 character(len=30) :: date
4731 ! Do something, main part of the program
4734 print *, 'Program was started on ', date
4735 end program test_ctime
4738 @item @emph{See Also}:
4739 @ref{DATE_AND_TIME}, @gol
4749 @section @code{DATE_AND_TIME} --- Date and time subroutine
4750 @fnindex DATE_AND_TIME
4751 @cindex date, current
4752 @cindex current date
4753 @cindex time, current
4754 @cindex current time
4757 @item @emph{Description}:
4758 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
4759 time information from the real-time system clock. @var{DATE} is
4760 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
4761 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
4762 representing the difference with respect to Coordinated Universal Time (UTC).
4763 Unavailable time and date parameters return blanks.
4765 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
4767 @multitable @columnfractions .15 .30 .40
4768 @item @tab @code{VALUE(1)}: @tab The year
4769 @item @tab @code{VALUE(2)}: @tab The month
4770 @item @tab @code{VALUE(3)}: @tab The day of the month
4771 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
4772 @item @tab @code{VALUE(5)}: @tab The hour of the day
4773 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
4774 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
4775 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
4778 @item @emph{Standard}:
4779 Fortran 90 and later
4784 @item @emph{Syntax}:
4785 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
4787 @item @emph{Arguments}:
4788 @multitable @columnfractions .15 .70
4789 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
4790 or larger, and of default kind.
4791 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
4792 or larger, and of default kind.
4793 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
4794 or larger, and of default kind.
4795 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
4798 @item @emph{Return value}:
4801 @item @emph{Example}:
4803 program test_time_and_date
4804 character(8) :: date
4805 character(10) :: time
4806 character(5) :: zone
4807 integer,dimension(8) :: values
4808 ! using keyword arguments
4809 call date_and_time(date,time,zone,values)
4810 call date_and_time(DATE=date,ZONE=zone)
4811 call date_and_time(TIME=time)
4812 call date_and_time(VALUES=values)
4813 print '(a,2x,a,2x,a)', date, time, zone
4814 print '(8i5)', values
4815 end program test_time_and_date
4818 @item @emph{See also}:
4819 @ref{CPU_TIME}, @gol
4826 @section @code{DBLE} --- Double conversion function
4828 @cindex conversion, to real
4831 @item @emph{Description}:
4832 @code{DBLE(A)} Converts @var{A} to double precision real type.
4834 @item @emph{Standard}:
4835 Fortran 77 and later
4840 @item @emph{Syntax}:
4841 @code{RESULT = DBLE(A)}
4843 @item @emph{Arguments}:
4844 @multitable @columnfractions .15 .70
4845 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
4849 @item @emph{Return value}:
4850 The return value is of type double precision real.
4852 @item @emph{Example}:
4857 complex :: z = (2.3,1.14)
4858 print *, dble(x), dble(i), dble(z)
4859 end program test_dble
4862 @item @emph{See also}:
4869 @section @code{DCMPLX} --- Double complex conversion function
4871 @cindex complex numbers, conversion to
4872 @cindex conversion, to complex
4875 @item @emph{Description}:
4876 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
4877 converted to the real component. If @var{Y} is present it is converted to the
4878 imaginary component. If @var{Y} is not present then the imaginary component is
4879 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
4881 @item @emph{Standard}:
4887 @item @emph{Syntax}:
4888 @code{RESULT = DCMPLX(X [, Y])}
4890 @item @emph{Arguments}:
4891 @multitable @columnfractions .15 .70
4892 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
4894 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
4895 @code{INTEGER} or @code{REAL}.
4898 @item @emph{Return value}:
4899 The return value is of type @code{COMPLEX(8)}
4901 @item @emph{Example}:
4911 print *, dcmplx(x,i)
4912 end program test_dcmplx
4918 @section @code{DIGITS} --- Significant binary digits function
4920 @cindex model representation, significant digits
4923 @item @emph{Description}:
4924 @code{DIGITS(X)} returns the number of significant binary digits of the internal
4925 model representation of @var{X}. For example, on a system using a 32-bit
4926 floating point representation, a default real number would likely return 24.
4928 @item @emph{Standard}:
4929 Fortran 90 and later
4934 @item @emph{Syntax}:
4935 @code{RESULT = DIGITS(X)}
4937 @item @emph{Arguments}:
4938 @multitable @columnfractions .15 .70
4939 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
4942 @item @emph{Return value}:
4943 The return value is of type @code{INTEGER}.
4945 @item @emph{Example}:
4948 integer :: i = 12345
4954 end program test_digits
4961 @section @code{DIM} --- Positive difference
4965 @cindex positive difference
4968 @item @emph{Description}:
4969 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
4970 otherwise returns zero.
4972 @item @emph{Standard}:
4973 Fortran 77 and later
4978 @item @emph{Syntax}:
4979 @code{RESULT = DIM(X, Y)}
4981 @item @emph{Arguments}:
4982 @multitable @columnfractions .15 .70
4983 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
4984 @item @var{Y} @tab The type shall be the same type and kind as @var{X}. (As
4985 a GNU extension, arguments of different kinds are permitted.)
4988 @item @emph{Return value}:
4989 The return value is of type @code{INTEGER} or @code{REAL}. (As a GNU
4990 extension, kind is the largest kind of the actual arguments.)
4992 @item @emph{Example}:
4998 x = dim(4.345_8, 2.111_8)
5001 end program test_dim
5004 @item @emph{Specific names}:
5005 @multitable @columnfractions .20 .20 .20 .25
5006 @item Name @tab Argument @tab Return type @tab Standard
5007 @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
5008 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
5009 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
5016 @section @code{DOT_PRODUCT} --- Dot product function
5017 @fnindex DOT_PRODUCT
5019 @cindex vector product
5020 @cindex product, vector
5023 @item @emph{Description}:
5024 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
5025 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
5026 either numeric or logical and must be arrays of rank one and of equal size. If
5027 the vectors are @code{INTEGER} or @code{REAL}, the result is
5028 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
5029 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
5030 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
5032 @item @emph{Standard}:
5033 Fortran 90 and later
5036 Transformational function
5038 @item @emph{Syntax}:
5039 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
5041 @item @emph{Arguments}:
5042 @multitable @columnfractions .15 .70
5043 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
5044 @item @var{VECTOR_B} @tab The type shall be numeric if @var{VECTOR_A} is of numeric type or @code{LOGICAL} if @var{VECTOR_A} is of type @code{LOGICAL}. @var{VECTOR_B} shall be a rank-one array.
5047 @item @emph{Return value}:
5048 If the arguments are numeric, the return value is a scalar of numeric type,
5049 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
5050 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
5052 @item @emph{Example}:
5054 program test_dot_prod
5055 integer, dimension(3) :: a, b
5062 print *, dot_product(a,b)
5063 end program test_dot_prod
5070 @section @code{DPROD} --- Double product function
5072 @cindex product, double-precision
5075 @item @emph{Description}:
5076 @code{DPROD(X,Y)} returns the product @code{X*Y}.
5078 @item @emph{Standard}:
5079 Fortran 77 and later
5084 @item @emph{Syntax}:
5085 @code{RESULT = DPROD(X, Y)}
5087 @item @emph{Arguments}:
5088 @multitable @columnfractions .15 .70
5089 @item @var{X} @tab The type shall be @code{REAL}.
5090 @item @var{Y} @tab The type shall be @code{REAL}.
5093 @item @emph{Return value}:
5094 The return value is of type @code{REAL(8)}.
5096 @item @emph{Example}:
5104 end program test_dprod
5107 @item @emph{Specific names}:
5108 @multitable @columnfractions .20 .20 .20 .25
5109 @item Name @tab Argument @tab Return type @tab Standard
5110 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
5117 @section @code{DREAL} --- Double real part function
5119 @cindex complex numbers, real part
5122 @item @emph{Description}:
5123 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
5125 @item @emph{Standard}:
5131 @item @emph{Syntax}:
5132 @code{RESULT = DREAL(A)}
5134 @item @emph{Arguments}:
5135 @multitable @columnfractions .15 .70
5136 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
5139 @item @emph{Return value}:
5140 The return value is of type @code{REAL(8)}.
5142 @item @emph{Example}:
5145 complex(8) :: z = (1.3_8,7.2_8)
5147 end program test_dreal
5150 @item @emph{See also}:
5158 @section @code{DSHIFTL} --- Combined left shift
5160 @cindex left shift, combined
5164 @item @emph{Description}:
5165 @code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
5166 rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
5167 bits of @var{J}, and the remaining bits are the rightmost bits of
5170 @item @emph{Standard}:
5171 Fortran 2008 and later
5176 @item @emph{Syntax}:
5177 @code{RESULT = DSHIFTL(I, J, SHIFT)}
5179 @item @emph{Arguments}:
5180 @multitable @columnfractions .15 .70
5181 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5182 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5183 If both @var{I} and @var{J} have integer type, then they shall have
5184 the same kind type parameter. @var{I} and @var{J} shall not both be
5186 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
5187 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
5188 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
5189 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
5192 @item @emph{Return value}:
5193 If either @var{I} or @var{J} is a BOZ constant, it is first converted
5194 as if by the intrinsic function @code{INT} to an integer type with the
5195 kind type parameter of the other.
5197 @item @emph{See also}:
5203 @section @code{DSHIFTR} --- Combined right shift
5205 @cindex right shift, combined
5206 @cindex shift, right
5209 @item @emph{Description}:
5210 @code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
5211 leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
5212 bits of @var{I}, and the remaining bits are the leftmost bits of
5215 @item @emph{Standard}:
5216 Fortran 2008 and later
5221 @item @emph{Syntax}:
5222 @code{RESULT = DSHIFTR(I, J, SHIFT)}
5224 @item @emph{Arguments}:
5225 @multitable @columnfractions .15 .70
5226 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5227 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5228 If both @var{I} and @var{J} have integer type, then they shall have
5229 the same kind type parameter. @var{I} and @var{J} shall not both be
5231 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
5232 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
5233 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
5234 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
5237 @item @emph{Return value}:
5238 If either @var{I} or @var{J} is a BOZ constant, it is first converted
5239 as if by the intrinsic function @code{INT} to an integer type with the
5240 kind type parameter of the other.
5242 @item @emph{See also}:
5248 @section @code{DTIME} --- Execution time subroutine (or function)
5250 @cindex time, elapsed
5251 @cindex elapsed time
5254 @item @emph{Description}:
5255 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
5256 since the start of the process's execution in @var{TIME}. @var{VALUES}
5257 returns the user and system components of this time in @code{VALUES(1)} and
5258 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
5261 Subsequent invocations of @code{DTIME} return values accumulated since the
5262 previous invocation.
5264 On some systems, the underlying timings are represented using types with
5265 sufficiently small limits that overflows (wrap around) are possible, such as
5266 32-bit types. Therefore, the values returned by this intrinsic might be, or
5267 become, negative, or numerically less than previous values, during a single
5268 run of the compiled program.
5270 Please note, that this implementation is thread safe if used within OpenMP
5271 directives, i.e., its state will be consistent while called from multiple
5272 threads. However, if @code{DTIME} is called from multiple threads, the result
5273 is still the time since the last invocation. This may not give the intended
5274 results. If possible, use @code{CPU_TIME} instead.
5276 This intrinsic is provided in both subroutine and function forms; however,
5277 only one form can be used in any given program unit.
5279 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
5281 @multitable @columnfractions .15 .30 .40
5282 @item @tab @code{VALUES(1)}: @tab User time in seconds.
5283 @item @tab @code{VALUES(2)}: @tab System time in seconds.
5284 @item @tab @code{TIME}: @tab Run time since start in seconds.
5287 @item @emph{Standard}:
5291 Subroutine, function
5293 @item @emph{Syntax}:
5294 @multitable @columnfractions .80
5295 @item @code{CALL DTIME(VALUES, TIME)}.
5296 @item @code{TIME = DTIME(VALUES)}, (not recommended).
5299 @item @emph{Arguments}:
5300 @multitable @columnfractions .15 .70
5301 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
5302 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
5305 @item @emph{Return value}:
5306 Elapsed time in seconds since the last invocation or since the start of program
5307 execution if not called before.
5309 @item @emph{Example}:
5313 real, dimension(2) :: tarray
5315 call dtime(tarray, result)
5319 do i=1,100000000 ! Just a delay
5322 call dtime(tarray, result)
5326 end program test_dtime
5329 @item @emph{See also}:
5337 @section @code{EOSHIFT} --- End-off shift elements of an array
5339 @cindex array, shift
5342 @item @emph{Description}:
5343 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
5344 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
5345 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
5346 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
5347 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
5348 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
5349 then all complete rank one sections of @var{ARRAY} along the given dimension are
5350 shifted. Elements shifted out one end of each rank one section are dropped. If
5351 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
5352 is copied back in the other end. If @var{BOUNDARY} is not present then the
5353 following are copied in depending on the type of @var{ARRAY}.
5355 @multitable @columnfractions .15 .80
5356 @item @emph{Array Type} @tab @emph{Boundary Value}
5357 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
5358 @item Logical @tab @code{.FALSE.}.
5359 @item Character(@var{len}) @tab @var{len} blanks.
5362 @item @emph{Standard}:
5363 Fortran 90 and later
5366 Transformational function
5368 @item @emph{Syntax}:
5369 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
5371 @item @emph{Arguments}:
5372 @multitable @columnfractions .15 .70
5373 @item @var{ARRAY} @tab May be any type, not scalar.
5374 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
5375 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
5376 @item @var{DIM} @tab The type shall be @code{INTEGER}.
5379 @item @emph{Return value}:
5380 Returns an array of same type and rank as the @var{ARRAY} argument.
5382 @item @emph{Example}:
5384 program test_eoshift
5385 integer, dimension(3,3) :: a
5386 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
5387 print '(3i3)', a(1,:)
5388 print '(3i3)', a(2,:)
5389 print '(3i3)', a(3,:)
5390 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
5392 print '(3i3)', a(1,:)
5393 print '(3i3)', a(2,:)
5394 print '(3i3)', a(3,:)
5395 end program test_eoshift
5402 @section @code{EPSILON} --- Epsilon function
5404 @cindex model representation, epsilon
5407 @item @emph{Description}:
5408 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
5409 as @var{X} such that @math{1 + E > 1}.
5411 @item @emph{Standard}:
5412 Fortran 90 and later
5417 @item @emph{Syntax}:
5418 @code{RESULT = EPSILON(X)}
5420 @item @emph{Arguments}:
5421 @multitable @columnfractions .15 .70
5422 @item @var{X} @tab The type shall be @code{REAL}.
5425 @item @emph{Return value}:
5426 The return value is of same type as the argument.
5428 @item @emph{Example}:
5430 program test_epsilon
5435 end program test_epsilon
5442 @section @code{ERF} --- Error function
5444 @cindex error function
5447 @item @emph{Description}:
5448 @code{ERF(X)} computes the error function of @var{X}.
5450 @item @emph{Standard}:
5451 Fortran 2008 and later
5456 @item @emph{Syntax}:
5457 @code{RESULT = ERF(X)}
5459 @item @emph{Arguments}:
5460 @multitable @columnfractions .15 .70
5461 @item @var{X} @tab The type shall be @code{REAL}.
5464 @item @emph{Return value}:
5465 The return value is of type @code{REAL}, of the same kind as
5466 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
5468 @item @emph{Example}:
5471 real(8) :: x = 0.17_8
5473 end program test_erf
5476 @item @emph{Specific names}:
5477 @multitable @columnfractions .20 .20 .20 .25
5478 @item Name @tab Argument @tab Return type @tab Standard
5479 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
5486 @section @code{ERFC} --- Error function
5488 @cindex error function, complementary
5491 @item @emph{Description}:
5492 @code{ERFC(X)} computes the complementary error function of @var{X}.
5494 @item @emph{Standard}:
5495 Fortran 2008 and later
5500 @item @emph{Syntax}:
5501 @code{RESULT = ERFC(X)}
5503 @item @emph{Arguments}:
5504 @multitable @columnfractions .15 .70
5505 @item @var{X} @tab The type shall be @code{REAL}.
5508 @item @emph{Return value}:
5509 The return value is of type @code{REAL} and of the same kind as @var{X}.
5510 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
5512 @item @emph{Example}:
5515 real(8) :: x = 0.17_8
5517 end program test_erfc
5520 @item @emph{Specific names}:
5521 @multitable @columnfractions .20 .20 .20 .25
5522 @item Name @tab Argument @tab Return type @tab Standard
5523 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
5530 @section @code{ERFC_SCALED} --- Error function
5531 @fnindex ERFC_SCALED
5532 @cindex error function, complementary, exponentially-scaled
5535 @item @emph{Description}:
5536 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
5537 error function of @var{X}.
5539 @item @emph{Standard}:
5540 Fortran 2008 and later
5545 @item @emph{Syntax}:
5546 @code{RESULT = ERFC_SCALED(X)}
5548 @item @emph{Arguments}:
5549 @multitable @columnfractions .15 .70
5550 @item @var{X} @tab The type shall be @code{REAL}.
5553 @item @emph{Return value}:
5554 The return value is of type @code{REAL} and of the same kind as @var{X}.
5556 @item @emph{Example}:
5558 program test_erfc_scaled
5559 real(8) :: x = 0.17_8
5561 end program test_erfc_scaled
5568 @section @code{ETIME} --- Execution time subroutine (or function)
5570 @cindex time, elapsed
5573 @item @emph{Description}:
5574 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
5575 since the start of the process's execution in @var{TIME}. @var{VALUES}
5576 returns the user and system components of this time in @code{VALUES(1)} and
5577 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
5579 On some systems, the underlying timings are represented using types with
5580 sufficiently small limits that overflows (wrap around) are possible, such as
5581 32-bit types. Therefore, the values returned by this intrinsic might be, or
5582 become, negative, or numerically less than previous values, during a single
5583 run of the compiled program.
5585 This intrinsic is provided in both subroutine and function forms; however,
5586 only one form can be used in any given program unit.
5588 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
5590 @multitable @columnfractions .15 .30 .60
5591 @item @tab @code{VALUES(1)}: @tab User time in seconds.
5592 @item @tab @code{VALUES(2)}: @tab System time in seconds.
5593 @item @tab @code{TIME}: @tab Run time since start in seconds.
5596 @item @emph{Standard}:
5600 Subroutine, function
5602 @item @emph{Syntax}:
5603 @multitable @columnfractions .80
5604 @item @code{CALL ETIME(VALUES, TIME)}.
5605 @item @code{TIME = ETIME(VALUES)}, (not recommended).
5608 @item @emph{Arguments}:
5609 @multitable @columnfractions .15 .70
5610 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
5611 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
5614 @item @emph{Return value}:
5615 Elapsed time in seconds since the start of program execution.
5617 @item @emph{Example}:
5621 real, dimension(2) :: tarray
5623 call ETIME(tarray, result)
5627 do i=1,100000000 ! Just a delay
5630 call ETIME(tarray, result)
5634 end program test_etime
5637 @item @emph{See also}:
5645 @section @code{EVENT_QUERY} --- Query whether a coarray event has occurred
5646 @fnindex EVENT_QUERY
5647 @cindex Events, EVENT_QUERY
5650 @item @emph{Description}:
5651 @code{EVENT_QUERY} assignes the number of events to @var{COUNT} which have been
5652 posted to the @var{EVENT} variable and not yet been removed by calling
5653 @code{EVENT WAIT}. When @var{STAT} is present and the invocation was successful,
5654 it is assigned the value 0. If it is present and the invocation has failed,
5655 it is assigned a positive value and @var{COUNT} is assigned the value @math{-1}.
5657 @item @emph{Standard}:
5663 @item @emph{Syntax}:
5664 @code{CALL EVENT_QUERY (EVENT, COUNT [, STAT])}
5666 @item @emph{Arguments}:
5667 @multitable @columnfractions .15 .70
5668 @item @var{EVENT} @tab (intent(IN)) Scalar of type @code{EVENT_TYPE},
5669 defined in @code{ISO_FORTRAN_ENV}; shall not be coindexed.
5670 @item @var{COUNT} @tab (intent(out))Scalar integer with at least the
5671 precision of default integer.
5672 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
5675 @item @emph{Example}:
5680 type(event_type) :: event_value_has_been_set[*]
5682 if (this_image() == 1) then
5683 call event_query (event_value_has_been_set, cnt)
5684 if (cnt > 0) write(*,*) "Value has been set"
5685 elseif (this_image() == 2) then
5686 event post (event_value_has_been_set[1])
5695 @node EXECUTE_COMMAND_LINE
5696 @section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
5697 @fnindex EXECUTE_COMMAND_LINE
5698 @cindex system, system call
5699 @cindex command line
5702 @item @emph{Description}:
5703 @code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
5706 The @code{COMMAND} argument is passed to the shell and executed (The
5707 shell is @code{sh} on Unix systems, and @code{cmd.exe} on Windows.).
5708 If @code{WAIT} is present and has the value false, the execution of
5709 the command is asynchronous if the system supports it; otherwise, the
5710 command is executed synchronously using the C library's @code{system}
5713 The three last arguments allow the user to get status information. After
5714 synchronous execution, @code{EXITSTAT} contains the integer exit code of
5715 the command, as returned by @code{system}. @code{CMDSTAT} is set to zero
5716 if the command line was executed (whatever its exit status was).
5717 @code{CMDMSG} is assigned an error message if an error has occurred.
5719 Note that the @code{system} function need not be thread-safe. It is
5720 the responsibility of the user to ensure that @code{system} is not
5721 called concurrently.
5723 For asynchronous execution on supported targets, the POSIX
5724 @code{posix_spawn} or @code{fork} functions are used. Also, a signal
5725 handler for the @code{SIGCHLD} signal is installed.
5727 @item @emph{Standard}:
5728 Fortran 2008 and later
5733 @item @emph{Syntax}:
5734 @code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
5736 @item @emph{Arguments}:
5737 @multitable @columnfractions .15 .70
5738 @item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
5739 @item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
5740 @item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5742 @item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5744 @item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
5748 @item @emph{Example}:
5753 call execute_command_line ("external_prog.exe", exitstat=i)
5754 print *, "Exit status of external_prog.exe was ", i
5756 call execute_command_line ("reindex_files.exe", wait=.false.)
5757 print *, "Now reindexing files in the background"
5759 end program test_exec
5765 Because this intrinsic is implemented in terms of the @code{system}
5766 function call, its behavior with respect to signaling is processor
5767 dependent. In particular, on POSIX-compliant systems, the SIGINT and
5768 SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
5769 such, if the parent process is terminated, the child process might not be
5770 terminated alongside.
5773 @item @emph{See also}:
5780 @section @code{EXIT} --- Exit the program with status.
5782 @cindex program termination
5783 @cindex terminate program
5786 @item @emph{Description}:
5787 @code{EXIT} causes immediate termination of the program with status. If status
5788 is omitted it returns the canonical @emph{success} for the system. All Fortran
5789 I/O units are closed.
5791 @item @emph{Standard}:
5797 @item @emph{Syntax}:
5798 @code{CALL EXIT([STATUS])}
5800 @item @emph{Arguments}:
5801 @multitable @columnfractions .15 .70
5802 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
5805 @item @emph{Return value}:
5806 @code{STATUS} is passed to the parent process on exit.
5808 @item @emph{Example}:
5811 integer :: STATUS = 0
5812 print *, 'This program is going to exit.'
5814 end program test_exit
5817 @item @emph{See also}:
5825 @section @code{EXP} --- Exponential function
5831 @cindex exponential function
5832 @cindex logarithm function, inverse
5835 @item @emph{Description}:
5836 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
5838 @item @emph{Standard}:
5839 Fortran 77 and later, has overloads that are GNU extensions
5844 @item @emph{Syntax}:
5845 @code{RESULT = EXP(X)}
5847 @item @emph{Arguments}:
5848 @multitable @columnfractions .15 .70
5849 @item @var{X} @tab The type shall be @code{REAL} or
5853 @item @emph{Return value}:
5854 The return value has same type and kind as @var{X}.
5856 @item @emph{Example}:
5861 end program test_exp
5864 @item @emph{Specific names}:
5865 @multitable @columnfractions .20 .20 .20 .25
5866 @item Name @tab Argument @tab Return type @tab Standard
5867 @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
5868 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
5869 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
5870 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5871 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5878 @section @code{EXPONENT} --- Exponent function
5880 @cindex real number, exponent
5881 @cindex floating point, exponent
5884 @item @emph{Description}:
5885 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
5886 is zero the value returned is zero.
5888 @item @emph{Standard}:
5889 Fortran 90 and later
5894 @item @emph{Syntax}:
5895 @code{RESULT = EXPONENT(X)}
5897 @item @emph{Arguments}:
5898 @multitable @columnfractions .15 .70
5899 @item @var{X} @tab The type shall be @code{REAL}.
5902 @item @emph{Return value}:
5903 The return value is of type default @code{INTEGER}.
5905 @item @emph{Example}:
5907 program test_exponent
5912 print *, exponent(0.0)
5913 end program test_exponent
5919 @node EXTENDS_TYPE_OF
5920 @section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension
5921 @fnindex EXTENDS_TYPE_OF
5924 @item @emph{Description}:
5925 Query dynamic type for extension.
5927 @item @emph{Standard}:
5928 Fortran 2003 and later
5933 @item @emph{Syntax}:
5934 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
5936 @item @emph{Arguments}:
5937 @multitable @columnfractions .15 .70
5938 @item @var{A} @tab Shall be an object of extensible declared type or
5939 unlimited polymorphic.
5940 @item @var{MOLD} @tab Shall be an object of extensible declared type or
5941 unlimited polymorphic.
5944 @item @emph{Return value}:
5945 The return value is a scalar of type default logical. It is true if and only if
5946 the dynamic type of A is an extension type of the dynamic type of MOLD.
5949 @item @emph{See also}:
5956 @section @code{FDATE} --- Get the current time as a string
5958 @cindex time, current
5959 @cindex current time
5960 @cindex date, current
5961 @cindex current date
5964 @item @emph{Description}:
5965 @code{FDATE(DATE)} returns the current date (using the same format as
5966 @ref{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
5969 This intrinsic is provided in both subroutine and function forms; however,
5970 only one form can be used in any given program unit.
5972 @item @emph{Standard}:
5976 Subroutine, function
5978 @item @emph{Syntax}:
5979 @multitable @columnfractions .80
5980 @item @code{CALL FDATE(DATE)}.
5981 @item @code{DATE = FDATE()}.
5984 @item @emph{Arguments}:
5985 @multitable @columnfractions .15 .70
5986 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
5987 default kind. It is an @code{INTENT(OUT)} argument. If the length of
5988 this variable is too short for the date and time string to fit
5989 completely, it will be blank on procedure return.
5992 @item @emph{Return value}:
5993 The current date and time as a string.
5995 @item @emph{Example}:
5999 character(len=30) :: date
6001 print *, 'Program started on ', date
6002 do i = 1, 100000000 ! Just a delay
6006 print *, 'Program ended on ', date
6007 end program test_fdate
6010 @item @emph{See also}:
6011 @ref{DATE_AND_TIME}, @gol
6017 @section @code{FGET} --- Read a single character in stream mode from stdin
6019 @cindex read character, stream mode
6020 @cindex stream mode, read character
6021 @cindex file operation, read character
6024 @item @emph{Description}:
6025 Read a single character in stream mode from stdin by bypassing normal
6026 formatted output. Stream I/O should not be mixed with normal record-oriented
6027 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
6029 This intrinsic is provided in both subroutine and function forms; however,
6030 only one form can be used in any given program unit.
6032 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
6033 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
6034 Programmers should consider the use of new stream IO feature in new code
6035 for future portability. See also @ref{Fortran 2003 status}.
6037 @item @emph{Standard}:
6041 Subroutine, function
6043 @item @emph{Syntax}:
6044 @multitable @columnfractions .80
6045 @item @code{CALL FGET(C [, STATUS])}
6046 @item @code{STATUS = FGET(C)}
6049 @item @emph{Arguments}:
6050 @multitable @columnfractions .15 .70
6051 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6053 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6054 Returns 0 on success, -1 on end-of-file, and a system specific positive
6055 error code otherwise.
6058 @item @emph{Example}:
6061 INTEGER, PARAMETER :: strlen = 100
6062 INTEGER :: status, i = 1
6063 CHARACTER(len=strlen) :: str = ""
6065 WRITE (*,*) 'Enter text:'
6067 CALL fget(str(i:i), status)
6068 if (status /= 0 .OR. i > strlen) exit
6071 WRITE (*,*) TRIM(str)
6075 @item @emph{See also}:
6084 @section @code{FGETC} --- Read a single character in stream mode
6086 @cindex read character, stream mode
6087 @cindex stream mode, read character
6088 @cindex file operation, read character
6091 @item @emph{Description}:
6092 Read a single character in stream mode by bypassing normal formatted output.
6093 Stream I/O should not be mixed with normal record-oriented (formatted or
6094 unformatted) I/O on the same unit; the results are unpredictable.
6096 This intrinsic is provided in both subroutine and function forms; however,
6097 only one form can be used in any given program unit.
6099 Note that the @code{FGET} intrinsic is provided for backwards compatibility
6100 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
6101 Programmers should consider the use of new stream IO feature in new code
6102 for future portability. See also @ref{Fortran 2003 status}.
6104 @item @emph{Standard}:
6108 Subroutine, function
6110 @item @emph{Syntax}:
6111 @multitable @columnfractions .80
6112 @item @code{CALL FGETC(UNIT, C [, STATUS])}
6113 @item @code{STATUS = FGETC(UNIT, C)}
6116 @item @emph{Arguments}:
6117 @multitable @columnfractions .15 .70
6118 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
6119 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6121 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6122 Returns 0 on success, -1 on end-of-file and a system specific positive
6123 error code otherwise.
6126 @item @emph{Example}:
6129 INTEGER :: fd = 42, status
6132 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
6134 CALL fgetc(fd, c, status)
6135 IF (status /= 0) EXIT
6142 @item @emph{See also}:
6149 @section @code{FINDLOC} --- Search an array for a value
6154 @item @emph{Description}:
6155 Determines the location of the element in the array with the value
6156 given in the @var{VALUE} argument, or, if the @var{DIM} argument is
6157 supplied, determines the locations of the maximum element along each
6158 row of the array in the @var{DIM} direction. If @var{MASK} is
6159 present, only the elements for which @var{MASK} is @code{.TRUE.} are
6160 considered. If more than one element in the array has the value
6161 @var{VALUE}, the location returned is that of the first such element
6162 in array element order if the @var{BACK} is not present or if it is
6163 @code{.FALSE.}. If @var{BACK} is true, the location returned is that
6164 of the last such element. If the array has zero size, or all of the
6165 elements of @var{MASK} are @code{.FALSE.}, then the result is an array
6166 of zeroes. Similarly, if @var{DIM} is supplied and all of the
6167 elements of @var{MASK} along a given row are zero, the result value
6168 for that row is zero.
6170 @item @emph{Standard}:
6171 Fortran 2008 and later.
6174 Transformational function
6176 @item @emph{Syntax}:
6177 @multitable @columnfractions .80
6178 @item @code{RESULT = FINDLOC(ARRAY, VALUE, DIM [, MASK] [,KIND] [,BACK])}
6179 @item @code{RESULT = FINDLOC(ARRAY, VALUE, [, MASK] [,KIND] [,BACK])}
6182 @item @emph{Arguments}:
6183 @multitable @columnfractions .15 .70
6184 @item @var{ARRAY} @tab Shall be an array of intrinsic type.
6185 @item @var{VALUE} @tab A scalar of intrinsic type which is in type
6186 conformance with @var{ARRAY}.
6187 @item @var{DIM} @tab (Optional) Shall be a scalar of type
6188 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
6189 inclusive. It may not be an optional dummy argument.
6190 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6191 expression indicating the kind parameter of the result.
6192 @item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}.
6195 @item @emph{Return value}:
6196 If @var{DIM} is absent, the result is a rank-one array with a length
6197 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
6198 is an array with a rank one less than the rank of @var{ARRAY}, and a
6199 size corresponding to the size of @var{ARRAY} with the @var{DIM}
6200 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
6201 of one, the result is a scalar. If the optional argument @var{KIND}
6202 is present, the result is an integer of kind @var{KIND}, otherwise it
6205 @item @emph{See also}:
6212 @section @code{FLOOR} --- Integer floor function
6215 @cindex rounding, floor
6218 @item @emph{Description}:
6219 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
6221 @item @emph{Standard}:
6222 Fortran 95 and later
6227 @item @emph{Syntax}:
6228 @code{RESULT = FLOOR(A [, KIND])}
6230 @item @emph{Arguments}:
6231 @multitable @columnfractions .15 .70
6232 @item @var{A} @tab The type shall be @code{REAL}.
6233 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6234 expression indicating the kind parameter of the result.
6237 @item @emph{Return value}:
6238 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
6239 and of default-kind @code{INTEGER} otherwise.
6241 @item @emph{Example}:
6246 print *, floor(x) ! returns 63
6247 print *, floor(y) ! returns -64
6248 end program test_floor
6251 @item @emph{See also}:
6259 @section @code{FLUSH} --- Flush I/O unit(s)
6261 @cindex file operation, flush
6264 @item @emph{Description}:
6265 Flushes Fortran unit(s) currently open for output. Without the optional
6266 argument, all units are flushed, otherwise just the unit specified.
6268 @item @emph{Standard}:
6274 @item @emph{Syntax}:
6275 @code{CALL FLUSH(UNIT)}
6277 @item @emph{Arguments}:
6278 @multitable @columnfractions .15 .70
6279 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
6283 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
6284 statement that should be preferred over the @code{FLUSH} intrinsic.
6286 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
6287 have identical effect: they flush the runtime library's I/O buffer so
6288 that the data becomes visible to other processes. This does not guarantee
6289 that the data is committed to disk.
6291 On POSIX systems, you can request that all data is transferred to the
6292 storage device by calling the @code{fsync} function, with the POSIX file
6293 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
6294 @code{FNUM}). The following example shows how:
6297 ! Declare the interface for POSIX fsync function
6299 function fsync (fd) bind(c,name="fsync")
6300 use iso_c_binding, only: c_int
6301 integer(c_int), value :: fd
6302 integer(c_int) :: fsync
6306 ! Variable declaration
6310 open (10,file="foo")
6313 ! Perform I/O on unit 10
6318 ret = fsync(fnum(10))
6320 ! Handle possible error
6321 if (ret /= 0) stop "Error calling FSYNC"
6329 @section @code{FNUM} --- File number function
6331 @cindex file operation, file number
6334 @item @emph{Description}:
6335 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
6336 open Fortran I/O unit @code{UNIT}.
6338 @item @emph{Standard}:
6344 @item @emph{Syntax}:
6345 @code{RESULT = FNUM(UNIT)}
6347 @item @emph{Arguments}:
6348 @multitable @columnfractions .15 .70
6349 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
6352 @item @emph{Return value}:
6353 The return value is of type @code{INTEGER}
6355 @item @emph{Example}:
6359 open (unit=10, status = "scratch")
6363 end program test_fnum
6370 @section @code{FPUT} --- Write a single character in stream mode to stdout
6372 @cindex write character, stream mode
6373 @cindex stream mode, write character
6374 @cindex file operation, write character
6377 @item @emph{Description}:
6378 Write a single character in stream mode to stdout by bypassing normal
6379 formatted output. Stream I/O should not be mixed with normal record-oriented
6380 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
6382 This intrinsic is provided in both subroutine and function forms; however,
6383 only one form can be used in any given program unit.
6385 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
6386 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
6387 Programmers should consider the use of new stream IO feature in new code
6388 for future portability. See also @ref{Fortran 2003 status}.
6390 @item @emph{Standard}:
6394 Subroutine, function
6396 @item @emph{Syntax}:
6397 @multitable @columnfractions .80
6398 @item @code{CALL FPUT(C [, STATUS])}
6399 @item @code{STATUS = FPUT(C)}
6402 @item @emph{Arguments}:
6403 @multitable @columnfractions .15 .70
6404 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6406 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6407 Returns 0 on success, -1 on end-of-file and a system specific positive
6408 error code otherwise.
6411 @item @emph{Example}:
6414 CHARACTER(len=10) :: str = "gfortran"
6416 DO i = 1, len_trim(str)
6422 @item @emph{See also}:
6431 @section @code{FPUTC} --- Write a single character in stream mode
6433 @cindex write character, stream mode
6434 @cindex stream mode, write character
6435 @cindex file operation, write character
6438 @item @emph{Description}:
6439 Write a single character in stream mode by bypassing normal formatted
6440 output. Stream I/O should not be mixed with normal record-oriented
6441 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
6443 This intrinsic is provided in both subroutine and function forms; however,
6444 only one form can be used in any given program unit.
6446 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
6447 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
6448 Programmers should consider the use of new stream IO feature in new code
6449 for future portability. See also @ref{Fortran 2003 status}.
6451 @item @emph{Standard}:
6455 Subroutine, function
6457 @item @emph{Syntax}:
6458 @multitable @columnfractions .80
6459 @item @code{CALL FPUTC(UNIT, C [, STATUS])}
6460 @item @code{STATUS = FPUTC(UNIT, C)}
6463 @item @emph{Arguments}:
6464 @multitable @columnfractions .15 .70
6465 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
6466 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6468 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6469 Returns 0 on success, -1 on end-of-file and a system specific positive
6470 error code otherwise.
6473 @item @emph{Example}:
6476 CHARACTER(len=10) :: str = "gfortran"
6477 INTEGER :: fd = 42, i
6479 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
6480 DO i = 1, len_trim(str)
6481 CALL fputc(fd, str(i:i))
6487 @item @emph{See also}:
6496 @section @code{FRACTION} --- Fractional part of the model representation
6498 @cindex real number, fraction
6499 @cindex floating point, fraction
6502 @item @emph{Description}:
6503 @code{FRACTION(X)} returns the fractional part of the model
6504 representation of @code{X}.
6506 @item @emph{Standard}:
6507 Fortran 90 and later
6512 @item @emph{Syntax}:
6513 @code{Y = FRACTION(X)}
6515 @item @emph{Arguments}:
6516 @multitable @columnfractions .15 .70
6517 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
6520 @item @emph{Return value}:
6521 The return value is of the same type and kind as the argument.
6522 The fractional part of the model representation of @code{X} is returned;
6523 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
6525 @item @emph{Example}:
6527 program test_fraction
6530 print *, fraction(x), x * radix(x)**(-exponent(x))
6531 end program test_fraction
6539 @section @code{FREE} --- Frees memory
6541 @cindex pointer, cray
6544 @item @emph{Description}:
6545 Frees memory previously allocated by @code{MALLOC}. The @code{FREE}
6546 intrinsic is an extension intended to be used with Cray pointers, and is
6547 provided in GNU Fortran to allow user to compile legacy code. For
6548 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
6551 @item @emph{Standard}:
6557 @item @emph{Syntax}:
6558 @code{CALL FREE(PTR)}
6560 @item @emph{Arguments}:
6561 @multitable @columnfractions .15 .70
6562 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
6563 location of the memory that should be de-allocated.
6566 @item @emph{Return value}:
6569 @item @emph{Example}:
6570 See @code{MALLOC} for an example.
6572 @item @emph{See also}:
6579 @section @code{FSEEK} --- Low level file positioning subroutine
6581 @cindex file operation, seek
6582 @cindex file operation, position
6585 @item @emph{Description}:
6586 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
6587 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
6588 if set to 1, @var{OFFSET} is taken to be relative to the current position
6589 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
6590 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
6593 This intrinsic routine is not fully backwards compatible with @command{g77}.
6594 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
6595 @var{STATUS} variable. If FSEEK is used in old code, change
6597 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
6602 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
6603 IF (status /= 0) GOTO label
6606 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
6607 Programmers should consider the use of new stream IO feature in new code
6608 for future portability. See also @ref{Fortran 2003 status}.
6610 @item @emph{Standard}:
6616 @item @emph{Syntax}:
6617 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
6619 @item @emph{Arguments}:
6620 @multitable @columnfractions .15 .70
6621 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
6622 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
6623 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
6624 Its value shall be either 0, 1 or 2.
6625 @item @var{STATUS} @tab (Optional) shall be a scalar of type
6629 @item @emph{Example}:
6632 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
6633 INTEGER :: fd, offset, ierr
6639 OPEN(UNIT=fd, FILE="fseek.test")
6640 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
6641 print *, FTELL(fd), ierr
6643 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
6644 print *, FTELL(fd), ierr
6646 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
6647 print *, FTELL(fd), ierr
6653 @item @emph{See also}:
6660 @section @code{FSTAT} --- Get file status
6662 @cindex file system, file status
6665 @item @emph{Description}:
6666 @code{FSTAT} is identical to @ref{STAT}, except that information about an
6667 already opened file is obtained.
6669 The elements in @code{VALUES} are the same as described by @ref{STAT}.
6671 This intrinsic is provided in both subroutine and function forms; however,
6672 only one form can be used in any given program unit.
6674 @item @emph{Standard}:
6678 Subroutine, function
6680 @item @emph{Syntax}:
6681 @multitable @columnfractions .80
6682 @item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
6683 @item @code{STATUS = FSTAT(UNIT, VALUES)}
6686 @item @emph{Arguments}:
6687 @multitable @columnfractions .15 .70
6688 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
6689 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
6690 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
6691 on success and a system specific error code otherwise.
6694 @item @emph{Example}:
6695 See @ref{STAT} for an example.
6697 @item @emph{See also}:
6698 To stat a link: @gol
6700 To stat a file: @gol
6707 @section @code{FTELL} --- Current stream position
6709 @cindex file operation, position
6712 @item @emph{Description}:
6713 Retrieves the current position within an open file.
6715 This intrinsic is provided in both subroutine and function forms; however,
6716 only one form can be used in any given program unit.
6718 @item @emph{Standard}:
6722 Subroutine, function
6724 @item @emph{Syntax}:
6725 @multitable @columnfractions .80
6726 @item @code{CALL FTELL(UNIT, OFFSET)}
6727 @item @code{OFFSET = FTELL(UNIT)}
6730 @item @emph{Arguments}:
6731 @multitable @columnfractions .15 .70
6732 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
6733 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
6736 @item @emph{Return value}:
6737 In either syntax, @var{OFFSET} is set to the current offset of unit
6738 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
6740 @item @emph{Example}:
6744 OPEN(10, FILE="temp.dat")
6750 @item @emph{See also}:
6757 @section @code{GAMMA} --- Gamma function
6760 @cindex Gamma function
6761 @cindex Factorial function
6764 @item @emph{Description}:
6765 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
6766 integer values of @var{X} the Gamma function simplifies to the factorial
6767 function @math{\Gamma(x)=(x-1)!}.
6771 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
6775 @item @emph{Standard}:
6776 Fortran 2008 and later
6781 @item @emph{Syntax}:
6784 @item @emph{Arguments}:
6785 @multitable @columnfractions .15 .70
6786 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
6787 nor a negative integer.
6790 @item @emph{Return value}:
6791 The return value is of type @code{REAL} of the same kind as @var{X}.
6793 @item @emph{Example}:
6797 x = gamma(x) ! returns 1.0
6798 end program test_gamma
6801 @item @emph{Specific names}:
6802 @multitable @columnfractions .20 .20 .20 .25
6803 @item Name @tab Argument @tab Return type @tab Standard
6804 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
6807 @item @emph{See also}:
6808 Logarithm of the Gamma function: @gol
6815 @section @code{GERROR} --- Get last system error message
6817 @cindex system, error handling
6820 @item @emph{Description}:
6821 Returns the system error message corresponding to the last system error.
6822 This resembles the functionality of @code{strerror(3)} in C.
6824 @item @emph{Standard}:
6830 @item @emph{Syntax}:
6831 @code{CALL GERROR(RESULT)}
6833 @item @emph{Arguments}:
6834 @multitable @columnfractions .15 .70
6835 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
6838 @item @emph{Example}:
6841 CHARACTER(len=100) :: msg
6847 @item @emph{See also}:
6855 @section @code{GETARG} --- Get command line arguments
6857 @cindex command-line arguments
6858 @cindex arguments, to program
6861 @item @emph{Description}:
6862 Retrieve the @var{POS}-th argument that was passed on the
6863 command line when the containing program was invoked.
6865 This intrinsic routine is provided for backwards compatibility with
6866 GNU Fortran 77. In new code, programmers should consider the use of
6867 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
6870 @item @emph{Standard}:
6876 @item @emph{Syntax}:
6877 @code{CALL GETARG(POS, VALUE)}
6879 @item @emph{Arguments}:
6880 @multitable @columnfractions .15 .70
6881 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
6882 the default integer kind; @math{@var{POS} \geq 0}
6883 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
6885 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
6888 @item @emph{Return value}:
6889 After @code{GETARG} returns, the @var{VALUE} argument holds the
6890 @var{POS}th command line argument. If @var{VALUE} cannot hold the
6891 argument, it is truncated to fit the length of @var{VALUE}. If there are
6892 less than @var{POS} arguments specified at the command line, @var{VALUE}
6893 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
6894 to the name of the program (on systems that support this feature).
6896 @item @emph{Example}:
6900 CHARACTER(len=32) :: arg
6909 @item @emph{See also}:
6910 GNU Fortran 77 compatibility function: @gol
6912 Fortran 2003 functions and subroutines: @gol
6913 @ref{GET_COMMAND}, @gol
6914 @ref{GET_COMMAND_ARGUMENT}, @gol
6915 @ref{COMMAND_ARGUMENT_COUNT}
6921 @section @code{GET_COMMAND} --- Get the entire command line
6922 @fnindex GET_COMMAND
6923 @cindex command-line arguments
6924 @cindex arguments, to program
6927 @item @emph{Description}:
6928 Retrieve the entire command line that was used to invoke the program.
6930 @item @emph{Standard}:
6931 Fortran 2003 and later
6936 @item @emph{Syntax}:
6937 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
6939 @item @emph{Arguments}:
6940 @multitable @columnfractions .15 .70
6941 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
6943 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
6945 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
6949 @item @emph{Return value}:
6950 If @var{COMMAND} is present, stores the entire command line that was used
6951 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
6952 assigned the length of the command line. If @var{STATUS} is present, it
6953 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
6954 short to store the command line, or a positive value in case of an error.
6956 @item @emph{Example}:
6958 PROGRAM test_get_command
6959 CHARACTER(len=255) :: cmd
6960 CALL get_command(cmd)
6961 WRITE (*,*) TRIM(cmd)
6965 @item @emph{See also}:
6966 @ref{GET_COMMAND_ARGUMENT}, @gol
6967 @ref{COMMAND_ARGUMENT_COUNT}
6972 @node GET_COMMAND_ARGUMENT
6973 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
6974 @fnindex GET_COMMAND_ARGUMENT
6975 @cindex command-line arguments
6976 @cindex arguments, to program
6979 @item @emph{Description}:
6980 Retrieve the @var{NUMBER}-th argument that was passed on the
6981 command line when the containing program was invoked.
6983 @item @emph{Standard}:
6984 Fortran 2003 and later
6989 @item @emph{Syntax}:
6990 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
6992 @item @emph{Arguments}:
6993 @multitable @columnfractions .15 .70
6994 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
6995 default kind, @math{@var{NUMBER} \geq 0}
6996 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
6997 and of default kind.
6998 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6999 and of default kind.
7000 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
7001 and of default kind.
7004 @item @emph{Return value}:
7005 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
7006 @var{NUMBER}-th command line argument. If @var{VALUE} cannot hold the argument, it is
7007 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
7008 arguments specified at the command line, @var{VALUE} will be filled with blanks.
7009 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
7010 systems that support this feature). The @var{LENGTH} argument contains the
7011 length of the @var{NUMBER}-th command line argument. If the argument retrieval
7012 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
7013 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
7016 @item @emph{Example}:
7018 PROGRAM test_get_command_argument
7020 CHARACTER(len=32) :: arg
7024 CALL get_command_argument(i, arg)
7025 IF (LEN_TRIM(arg) == 0) EXIT
7027 WRITE (*,*) TRIM(arg)
7033 @item @emph{See also}:
7034 @ref{GET_COMMAND}, @gol
7035 @ref{COMMAND_ARGUMENT_COUNT}
7041 @section @code{GETCWD} --- Get current working directory
7043 @cindex system, working directory
7046 @item @emph{Description}:
7047 Get current working directory.
7049 This intrinsic is provided in both subroutine and function forms; however,
7050 only one form can be used in any given program unit.
7052 @item @emph{Standard}:
7056 Subroutine, function
7058 @item @emph{Syntax}:
7059 @multitable @columnfractions .80
7060 @item @code{CALL GETCWD(C [, STATUS])}
7061 @item @code{STATUS = GETCWD(C)}
7064 @item @emph{Arguments}:
7065 @multitable @columnfractions .15 .70
7066 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
7067 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
7068 a system specific and nonzero error code otherwise.
7071 @item @emph{Example}:
7074 CHARACTER(len=255) :: cwd
7076 WRITE(*,*) TRIM(cwd)
7080 @item @emph{See also}:
7087 @section @code{GETENV} --- Get an environmental variable
7089 @cindex environment variable
7092 @item @emph{Description}:
7093 Get the @var{VALUE} of the environmental variable @var{NAME}.
7095 This intrinsic routine is provided for backwards compatibility with
7096 GNU Fortran 77. In new code, programmers should consider the use of
7097 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
7100 Note that @code{GETENV} need not be thread-safe. It is the
7101 responsibility of the user to ensure that the environment is not being
7102 updated concurrently with a call to the @code{GETENV} intrinsic.
7104 @item @emph{Standard}:
7110 @item @emph{Syntax}:
7111 @code{CALL GETENV(NAME, VALUE)}
7113 @item @emph{Arguments}:
7114 @multitable @columnfractions .15 .70
7115 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
7116 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
7119 @item @emph{Return value}:
7120 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
7121 not large enough to hold the data, it is truncated. If @var{NAME}
7122 is not set, @var{VALUE} will be filled with blanks.
7124 @item @emph{Example}:
7127 CHARACTER(len=255) :: homedir
7128 CALL getenv("HOME", homedir)
7129 WRITE (*,*) TRIM(homedir)
7133 @item @emph{See also}:
7134 @ref{GET_ENVIRONMENT_VARIABLE}
7139 @node GET_ENVIRONMENT_VARIABLE
7140 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
7141 @fnindex GET_ENVIRONMENT_VARIABLE
7142 @cindex environment variable
7145 @item @emph{Description}:
7146 Get the @var{VALUE} of the environmental variable @var{NAME}.
7148 Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It
7149 is the responsibility of the user to ensure that the environment is
7150 not being updated concurrently with a call to the
7151 @code{GET_ENVIRONMENT_VARIABLE} intrinsic.
7153 @item @emph{Standard}:
7154 Fortran 2003 and later
7159 @item @emph{Syntax}:
7160 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
7162 @item @emph{Arguments}:
7163 @multitable @columnfractions .15 .70
7164 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
7165 and of default kind.
7166 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
7167 and of default kind.
7168 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
7169 and of default kind.
7170 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
7171 and of default kind.
7172 @item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL}
7173 and of default kind.
7176 @item @emph{Return value}:
7177 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
7178 not large enough to hold the data, it is truncated. If @var{NAME}
7179 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
7180 contains the length needed for storing the environment variable @var{NAME}
7181 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
7182 but too short for the environment variable; it is 1 if the environment
7183 variable does not exist and 2 if the processor does not support environment
7184 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
7185 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
7186 are significant; otherwise they are not part of the environment variable
7189 @item @emph{Example}:
7192 CHARACTER(len=255) :: homedir
7193 CALL get_environment_variable("HOME", homedir)
7194 WRITE (*,*) TRIM(homedir)
7202 @section @code{GETGID} --- Group ID function
7204 @cindex system, group ID
7207 @item @emph{Description}:
7208 Returns the numerical group ID of the current process.
7210 @item @emph{Standard}:
7216 @item @emph{Syntax}:
7217 @code{RESULT = GETGID()}
7219 @item @emph{Return value}:
7220 The return value of @code{GETGID} is an @code{INTEGER} of the default
7224 @item @emph{Example}:
7225 See @code{GETPID} for an example.
7227 @item @emph{See also}:
7235 @section @code{GETLOG} --- Get login name
7237 @cindex system, login name
7241 @item @emph{Description}:
7242 Gets the username under which the program is running.
7244 @item @emph{Standard}:
7250 @item @emph{Syntax}:
7251 @code{CALL GETLOG(C)}
7253 @item @emph{Arguments}:
7254 @multitable @columnfractions .15 .70
7255 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
7258 @item @emph{Return value}:
7259 Stores the current user name in @var{LOGIN}. (On systems where POSIX
7260 functions @code{geteuid} and @code{getpwuid} are not available, and
7261 the @code{getlogin} function is not implemented either, this will
7262 return a blank string.)
7264 @item @emph{Example}:
7267 CHARACTER(32) :: login
7273 @item @emph{See also}:
7280 @section @code{GETPID} --- Process ID function
7282 @cindex system, process ID
7286 @item @emph{Description}:
7287 Returns the numerical process identifier of the current process.
7289 @item @emph{Standard}:
7295 @item @emph{Syntax}:
7296 @code{RESULT = GETPID()}
7298 @item @emph{Return value}:
7299 The return value of @code{GETPID} is an @code{INTEGER} of the default
7303 @item @emph{Example}:
7306 print *, "The current process ID is ", getpid()
7307 print *, "Your numerical user ID is ", getuid()
7308 print *, "Your numerical group ID is ", getgid()
7312 @item @emph{See also}:
7320 @section @code{GETUID} --- User ID function
7322 @cindex system, user ID
7326 @item @emph{Description}:
7327 Returns the numerical user ID of the current process.
7329 @item @emph{Standard}:
7335 @item @emph{Syntax}:
7336 @code{RESULT = GETUID()}
7338 @item @emph{Return value}:
7339 The return value of @code{GETUID} is an @code{INTEGER} of the default
7343 @item @emph{Example}:
7344 See @code{GETPID} for an example.
7346 @item @emph{See also}:
7354 @section @code{GMTIME} --- Convert time to GMT info
7356 @cindex time, conversion to GMT info
7359 @item @emph{Description}:
7360 Given a system time value @var{TIME} (as provided by the @ref{TIME}
7361 intrinsic), fills @var{VALUES} with values extracted from it appropriate
7362 to the UTC time zone (Universal Coordinated Time, also known in some
7363 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
7365 This intrinsic routine is provided for backwards compatibility with
7366 GNU Fortran 77. In new code, programmers should consider the use of
7367 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
7370 @item @emph{Standard}:
7376 @item @emph{Syntax}:
7377 @code{CALL GMTIME(TIME, VALUES)}
7379 @item @emph{Arguments}:
7380 @multitable @columnfractions .15 .70
7381 @item @var{TIME} @tab An @code{INTEGER} scalar expression
7382 corresponding to a system time, with @code{INTENT(IN)}.
7383 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
7384 with @code{INTENT(OUT)}.
7387 @item @emph{Return value}:
7388 The elements of @var{VALUES} are assigned as follows:
7390 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
7392 @item Minutes after the hour, range 0--59
7393 @item Hours past midnight, range 0--23
7394 @item Day of month, range 1--31
7395 @item Number of months since January, range 0--11
7396 @item Years since 1900
7397 @item Number of days since Sunday, range 0--6
7398 @item Days since January 1, range 0--365
7399 @item Daylight savings indicator: positive if daylight savings is in
7400 effect, zero if not, and negative if the information is not available.
7403 @item @emph{See also}:
7404 @ref{DATE_AND_TIME}, @gol
7414 @section @code{HOSTNM} --- Get system host name
7416 @cindex system, host name
7419 @item @emph{Description}:
7420 Retrieves the host name of the system on which the program is running.
7422 This intrinsic is provided in both subroutine and function forms; however,
7423 only one form can be used in any given program unit.
7425 @item @emph{Standard}:
7429 Subroutine, function
7431 @item @emph{Syntax}:
7432 @multitable @columnfractions .80
7433 @item @code{CALL HOSTNM(C [, STATUS])}
7434 @item @code{STATUS = HOSTNM(NAME)}
7437 @item @emph{Arguments}:
7438 @multitable @columnfractions .15 .70
7439 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
7440 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
7441 Returns 0 on success, or a system specific error code otherwise.
7444 @item @emph{Return value}:
7445 In either syntax, @var{NAME} is set to the current hostname if it can
7446 be obtained, or to a blank string otherwise.
7453 @section @code{HUGE} --- Largest number of a kind
7455 @cindex limits, largest number
7456 @cindex model representation, largest number
7459 @item @emph{Description}:
7460 @code{HUGE(X)} returns the largest number that is not an infinity in
7461 the model of the type of @code{X}.
7463 @item @emph{Standard}:
7464 Fortran 90 and later
7469 @item @emph{Syntax}:
7470 @code{RESULT = HUGE(X)}
7472 @item @emph{Arguments}:
7473 @multitable @columnfractions .15 .70
7474 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
7477 @item @emph{Return value}:
7478 The return value is of the same type and kind as @var{X}
7480 @item @emph{Example}:
7482 program test_huge_tiny
7483 print *, huge(0), huge(0.0), huge(0.0d0)
7484 print *, tiny(0.0), tiny(0.0d0)
7485 end program test_huge_tiny
7492 @section @code{HYPOT} --- Euclidean distance function
7494 @cindex Euclidean distance
7497 @item @emph{Description}:
7498 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
7499 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
7501 @item @emph{Standard}:
7502 Fortran 2008 and later
7507 @item @emph{Syntax}:
7508 @code{RESULT = HYPOT(X, Y)}
7510 @item @emph{Arguments}:
7511 @multitable @columnfractions .15 .70
7512 @item @var{X} @tab The type shall be @code{REAL}.
7513 @item @var{Y} @tab The type and kind type parameter shall be the same as
7517 @item @emph{Return value}:
7518 The return value has the same type and kind type parameter as @var{X}.
7520 @item @emph{Example}:
7523 real(4) :: x = 1.e0_4, y = 0.5e0_4
7525 end program test_hypot
7532 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
7534 @cindex @acronym{ASCII} collating sequence
7535 @cindex collating sequence, @acronym{ASCII}
7536 @cindex conversion, to integer
7539 @item @emph{Description}:
7540 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
7541 in the first character position of @code{C}.
7543 @item @emph{Standard}:
7544 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7549 @item @emph{Syntax}:
7550 @code{RESULT = IACHAR(C [, KIND])}
7552 @item @emph{Arguments}:
7553 @multitable @columnfractions .15 .70
7554 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
7555 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7556 expression indicating the kind parameter of the result.
7559 @item @emph{Return value}:
7560 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7561 @var{KIND} is absent, the return value is of default integer kind.
7563 @item @emph{Example}:
7568 end program test_iachar
7572 See @ref{ICHAR} for a discussion of converting between numerical values
7573 and formatted string representations.
7575 @item @emph{See also}:
7584 @section @code{IALL} --- Bitwise AND of array elements
7587 @cindex bits, AND of array elements
7590 @item @emph{Description}:
7591 Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
7592 if the corresponding element in @var{MASK} is @code{TRUE}.
7594 @item @emph{Standard}:
7595 Fortran 2008 and later
7598 Transformational function
7600 @item @emph{Syntax}:
7601 @multitable @columnfractions .80
7602 @item @code{RESULT = IALL(ARRAY[, MASK])}
7603 @item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
7606 @item @emph{Arguments}:
7607 @multitable @columnfractions .15 .70
7608 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7609 @item @var{DIM} @tab (Optional) shall be a scalar of type
7610 @code{INTEGER} with a value in the range from 1 to n, where n
7611 equals the rank of @var{ARRAY}.
7612 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
7613 and either be a scalar or an array of the same shape as @var{ARRAY}.
7616 @item @emph{Return value}:
7617 The result is of the same type as @var{ARRAY}.
7619 If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
7620 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7621 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7622 dimension @var{DIM} dropped is returned.
7624 @item @emph{Example}:
7633 PRINT '(b8.8)', IALL(a)
7637 @item @emph{See also}:
7646 @section @code{IAND} --- Bitwise logical and
7652 @cindex bitwise logical and
7653 @cindex logical and, bitwise
7656 @item @emph{Description}:
7657 Bitwise logical @code{AND}.
7659 @item @emph{Standard}:
7660 Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions
7665 @item @emph{Syntax}:
7666 @code{RESULT = IAND(I, J)}
7668 @item @emph{Arguments}:
7669 @multitable @columnfractions .15 .70
7670 @item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant.
7671 @item @var{J} @tab The type shall be @code{INTEGER} with the same
7672 kind type parameter as @var{I} or a boz-literal-constant.
7673 @var{I} and @var{J} shall not both be boz-literal-constants.
7676 @item @emph{Return value}:
7677 The return type is @code{INTEGER} with the kind type parameter of the
7679 A boz-literal-constant is converted to an @code{INTEGER} with the kind
7680 type parameter of the other argument as-if a call to @ref{INT} occurred.
7682 @item @emph{Example}:
7686 DATA a / Z'F' /, b / Z'3' /
7687 WRITE (*,*) IAND(a, b)
7691 @item @emph{Specific names}:
7692 @multitable @columnfractions .20 .20 .20 .25
7693 @item Name @tab Argument @tab Return type @tab Standard
7694 @item @code{IAND(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
7695 @item @code{BIAND(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7696 @item @code{IIAND(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7697 @item @code{JIAND(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7698 @item @code{KIAND(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7701 @item @emph{See also}:
7713 @section @code{IANY} --- Bitwise OR of array elements
7716 @cindex bits, OR of array elements
7719 @item @emph{Description}:
7720 Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
7721 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
7723 @item @emph{Standard}:
7724 Fortran 2008 and later
7727 Transformational function
7729 @item @emph{Syntax}:
7730 @multitable @columnfractions .80
7731 @item @code{RESULT = IANY(ARRAY[, MASK])}
7732 @item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
7735 @item @emph{Arguments}:
7736 @multitable @columnfractions .15 .70
7737 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7738 @item @var{DIM} @tab (Optional) shall be a scalar of type
7739 @code{INTEGER} with a value in the range from 1 to n, where n
7740 equals the rank of @var{ARRAY}.
7741 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
7742 and either be a scalar or an array of the same shape as @var{ARRAY}.
7745 @item @emph{Return value}:
7746 The result is of the same type as @var{ARRAY}.
7748 If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
7749 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7750 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7751 dimension @var{DIM} dropped is returned.
7753 @item @emph{Example}:
7762 PRINT '(b8.8)', IANY(a)
7766 @item @emph{See also}:
7775 @section @code{IARGC} --- Get the number of command line arguments
7777 @cindex command-line arguments
7778 @cindex command-line arguments, number of
7779 @cindex arguments, to program
7782 @item @emph{Description}:
7783 @code{IARGC} returns the number of arguments passed on the
7784 command line when the containing program was invoked.
7786 This intrinsic routine is provided for backwards compatibility with
7787 GNU Fortran 77. In new code, programmers should consider the use of
7788 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
7791 @item @emph{Standard}:
7797 @item @emph{Syntax}:
7798 @code{RESULT = IARGC()}
7800 @item @emph{Arguments}:
7803 @item @emph{Return value}:
7804 The number of command line arguments, type @code{INTEGER(4)}.
7806 @item @emph{Example}:
7809 @item @emph{See also}:
7810 GNU Fortran 77 compatibility subroutine: @gol
7812 Fortran 2003 functions and subroutines: @gol
7813 @ref{GET_COMMAND}, @gol
7814 @ref{GET_COMMAND_ARGUMENT}, @gol
7815 @ref{COMMAND_ARGUMENT_COUNT}
7821 @section @code{IBCLR} --- Clear bit
7831 @item @emph{Description}:
7832 @code{IBCLR} returns the value of @var{I} with the bit at position
7833 @var{POS} set to zero.
7835 @item @emph{Standard}:
7836 Fortran 90 and later, has overloads that are GNU extensions
7841 @item @emph{Syntax}:
7842 @code{RESULT = IBCLR(I, POS)}
7844 @item @emph{Arguments}:
7845 @multitable @columnfractions .15 .70
7846 @item @var{I} @tab The type shall be @code{INTEGER}.
7847 @item @var{POS} @tab The type shall be @code{INTEGER}.
7850 @item @emph{Return value}:
7851 The return value is of type @code{INTEGER} and of the same kind as
7854 @item @emph{Specific names}:
7855 @multitable @columnfractions .20 .20 .20 .25
7856 @item Name @tab Argument @tab Return type @tab Standard
7857 @item @code{IBCLR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
7858 @item @code{BBCLR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7859 @item @code{IIBCLR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7860 @item @code{JIBCLR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7861 @item @code{KIBCLR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7864 @item @emph{See also}:
7876 @section @code{IBITS} --- Bit extraction
7883 @cindex bits, extract
7886 @item @emph{Description}:
7887 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
7888 starting from bit position @var{POS} and extending left for @var{LEN}
7889 bits. The result is right-justified and the remaining bits are
7890 zeroed. The value of @code{POS+LEN} must be less than or equal to the
7891 value @code{BIT_SIZE(I)}.
7893 @item @emph{Standard}:
7894 Fortran 90 and later, has overloads that are GNU extensions
7899 @item @emph{Syntax}:
7900 @code{RESULT = IBITS(I, POS, LEN)}
7902 @item @emph{Arguments}:
7903 @multitable @columnfractions .15 .70
7904 @item @var{I} @tab The type shall be @code{INTEGER}.
7905 @item @var{POS} @tab The type shall be @code{INTEGER}.
7906 @item @var{LEN} @tab The type shall be @code{INTEGER}.
7909 @item @emph{Return value}:
7910 The return value is of type @code{INTEGER} and of the same kind as
7913 @item @emph{Specific names}:
7914 @multitable @columnfractions .20 .20 .20 .25
7915 @item Name @tab Argument @tab Return type @tab Standard
7916 @item @code{IBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
7917 @item @code{BBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7918 @item @code{IIBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7919 @item @code{JIBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7920 @item @code{KIBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7923 @item @emph{See also}:
7924 @ref{BIT_SIZE}, @gol
7935 @section @code{IBSET} --- Set bit
7944 @item @emph{Description}:
7945 @code{IBSET} returns the value of @var{I} with the bit at position
7946 @var{POS} set to one.
7948 @item @emph{Standard}:
7949 Fortran 90 and later, has overloads that are GNU extensions
7954 @item @emph{Syntax}:
7955 @code{RESULT = IBSET(I, POS)}
7957 @item @emph{Arguments}:
7958 @multitable @columnfractions .15 .70
7959 @item @var{I} @tab The type shall be @code{INTEGER}.
7960 @item @var{POS} @tab The type shall be @code{INTEGER}.
7963 @item @emph{Return value}:
7964 The return value is of type @code{INTEGER} and of the same kind as
7967 @item @emph{Specific names}:
7968 @multitable @columnfractions .20 .20 .20 .25
7969 @item Name @tab Argument @tab Return type @tab Standard
7970 @item @code{IBSET(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
7971 @item @code{BBSET(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7972 @item @code{IIBSET(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7973 @item @code{JIBSET(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7974 @item @code{KIBSET(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7977 @item @emph{See also}:
7989 @section @code{ICHAR} --- Character-to-integer conversion function
7991 @cindex conversion, to integer
7994 @item @emph{Description}:
7995 @code{ICHAR(C)} returns the code for the character in the first character
7996 position of @code{C} in the system's native character set.
7997 The correspondence between characters and their codes is not necessarily
7998 the same across different GNU Fortran implementations.
8000 @item @emph{Standard}:
8001 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
8006 @item @emph{Syntax}:
8007 @code{RESULT = ICHAR(C [, KIND])}
8009 @item @emph{Arguments}:
8010 @multitable @columnfractions .15 .70
8011 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
8012 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8013 expression indicating the kind parameter of the result.
8016 @item @emph{Return value}:
8017 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8018 @var{KIND} is absent, the return value is of default integer kind.
8020 @item @emph{Example}:
8025 end program test_ichar
8028 @item @emph{Specific names}:
8029 @multitable @columnfractions .20 .20 .20 .25
8030 @item Name @tab Argument @tab Return type @tab Standard
8031 @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8035 No intrinsic exists to convert between a numeric value and a formatted
8036 character string representation -- for instance, given the
8037 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
8038 @code{REAL} value with the value 154, or vice versa. Instead, this
8039 functionality is provided by internal-file I/O, as in the following
8044 character(len=10) string, string2
8047 ! Convert a string to a numeric value
8048 read (string,'(I10)') value
8051 ! Convert a value to a formatted string
8052 write (string2,'(I10)') value
8054 end program read_val
8057 @item @emph{See also}:
8066 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
8068 @cindex date, current
8069 @cindex current date
8072 @item @emph{Description}:
8073 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
8074 current local time. The day (in the range 1-31), month (in the range 1-12),
8075 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
8076 The year has four significant digits.
8078 This intrinsic routine is provided for backwards compatibility with
8079 GNU Fortran 77. In new code, programmers should consider the use of
8080 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
8083 @item @emph{Standard}:
8089 @item @emph{Syntax}:
8090 @code{CALL IDATE(VALUES)}
8092 @item @emph{Arguments}:
8093 @multitable @columnfractions .15 .70
8094 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
8095 the kind shall be the default integer kind.
8098 @item @emph{Return value}:
8099 Does not return anything.
8101 @item @emph{Example}:
8104 integer, dimension(3) :: tarray
8109 end program test_idate
8112 @item @emph{See also}:
8118 @section @code{IEOR} --- Bitwise logical exclusive or
8124 @cindex bitwise logical exclusive or
8125 @cindex logical exclusive or, bitwise
8128 @item @emph{Description}:
8129 @code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
8132 @item @emph{Standard}:
8133 Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions
8138 @item @emph{Syntax}:
8139 @code{RESULT = IEOR(I, J)}
8141 @item @emph{Arguments}:
8142 @multitable @columnfractions .15 .70
8143 @item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant.
8144 @item @var{J} @tab The type shall be @code{INTEGER} with the same
8145 kind type parameter as @var{I} or a boz-literal-constant.
8146 @var{I} and @var{J} shall not both be boz-literal-constants.
8149 @item @emph{Return value}:
8150 The return type is @code{INTEGER} with the kind type parameter of the
8152 A boz-literal-constant is converted to an @code{INTEGER} with the kind
8153 type parameter of the other argument as-if a call to @ref{INT} occurred.
8155 @item @emph{Specific names}:
8156 @multitable @columnfractions .20 .20 .20 .25
8157 @item Name @tab Argument @tab Return type @tab Standard
8158 @item @code{IEOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
8159 @item @code{BIEOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8160 @item @code{IIEOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8161 @item @code{JIEOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8162 @item @code{KIEOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8165 @item @emph{See also}:
8177 @section @code{IERRNO} --- Get the last system error number
8179 @cindex system, error handling
8182 @item @emph{Description}:
8183 Returns the last system error number, as given by the C @code{errno}
8186 @item @emph{Standard}:
8192 @item @emph{Syntax}:
8193 @code{RESULT = IERRNO()}
8195 @item @emph{Arguments}:
8198 @item @emph{Return value}:
8199 The return value is of type @code{INTEGER} and of the default integer
8202 @item @emph{See also}:
8209 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
8210 @fnindex IMAGE_INDEX
8211 @cindex coarray, @code{IMAGE_INDEX}
8212 @cindex images, cosubscript to image index conversion
8215 @item @emph{Description}:
8216 Returns the image index belonging to a cosubscript.
8218 @item @emph{Standard}:
8219 Fortran 2008 and later
8224 @item @emph{Syntax}:
8225 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
8227 @item @emph{Arguments}:
8228 @multitable @columnfractions .15 .70
8229 @item @var{COARRAY} @tab Coarray of any type.
8230 @item @var{SUB} @tab default integer rank-1 array of a size equal to
8231 the corank of @var{COARRAY}.
8235 @item @emph{Return value}:
8236 Scalar default integer with the value of the image index which corresponds
8237 to the cosubscripts. For invalid cosubscripts the result is zero.
8239 @item @emph{Example}:
8241 INTEGER :: array[2,-1:4,8,*]
8242 ! Writes 28 (or 0 if there are fewer than 28 images)
8243 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
8246 @item @emph{See also}:
8247 @ref{THIS_IMAGE}, @gol
8253 @node INDEX intrinsic
8254 @section @code{INDEX} --- Position of a substring within a string
8256 @cindex substring position
8257 @cindex string, find substring
8260 @item @emph{Description}:
8261 Returns the position of the start of the first occurrence of string
8262 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
8263 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
8264 the @var{BACK} argument is present and true, the return value is the
8265 start of the last occurrence rather than the first.
8267 @item @emph{Standard}:
8268 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
8273 @item @emph{Syntax}:
8274 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
8276 @item @emph{Arguments}:
8277 @multitable @columnfractions .15 .70
8278 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
8280 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
8282 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
8284 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8285 expression indicating the kind parameter of the result.
8288 @item @emph{Return value}:
8289 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8290 @var{KIND} is absent, the return value is of default integer kind.
8292 @item @emph{Specific names}:
8293 @multitable @columnfractions .20 .20 .20 .25
8294 @item Name @tab Argument @tab Return type @tab Standard
8295 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8298 @item @emph{See also}:
8306 @section @code{INT} --- Convert to integer type
8310 @cindex conversion, to integer
8313 @item @emph{Description}:
8314 Convert to integer type
8316 @item @emph{Standard}:
8317 Fortran 77 and later, with boz-literal-constant Fortran 2008 and later.
8322 @item @emph{Syntax}:
8323 @code{RESULT = INT(A [, KIND))}
8325 @item @emph{Arguments}:
8326 @multitable @columnfractions .15 .70
8327 @item @var{A} @tab Shall be of type @code{INTEGER},
8328 @code{REAL}, or @code{COMPLEX} or or a boz-literal-constant.
8329 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8330 expression indicating the kind parameter of the result.
8333 @item @emph{Return value}:
8334 These functions return a @code{INTEGER} variable or array under
8335 the following rules:
8339 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
8341 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)}
8342 equals @code{0}. If @math{|A| \geq 1}, then @code{INT(A)} is the integer
8343 whose magnitude is the largest integer that does not exceed the magnitude
8344 of @var{A} and whose sign is the same as the sign of @var{A}.
8346 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
8349 @item @emph{Example}:
8353 complex :: z = (-3.7, 1.0)
8355 print *, int(z), int(z,8)
8359 @item @emph{Specific names}:
8360 @multitable @columnfractions .20 .20 .20 .25
8361 @item Name @tab Argument @tab Return type @tab Standard
8362 @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
8363 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
8364 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
8371 @section @code{INT2} --- Convert to 16-bit integer type
8374 @cindex conversion, to integer
8377 @item @emph{Description}:
8378 Convert to a @code{KIND=2} integer type. This is equivalent to the
8379 standard @code{INT} intrinsic with an optional argument of
8380 @code{KIND=2}, and is only included for backwards compatibility.
8382 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
8384 @item @emph{Standard}:
8390 @item @emph{Syntax}:
8391 @code{RESULT = INT2(A)}
8393 @item @emph{Arguments}:
8394 @multitable @columnfractions .15 .70
8395 @item @var{A} @tab Shall be of type @code{INTEGER},
8396 @code{REAL}, or @code{COMPLEX}.
8399 @item @emph{Return value}:
8400 The return value is a @code{INTEGER(2)} variable.
8402 @item @emph{See also}:
8411 @section @code{INT8} --- Convert to 64-bit integer type
8413 @cindex conversion, to integer
8416 @item @emph{Description}:
8417 Convert to a @code{KIND=8} integer type. This is equivalent to the
8418 standard @code{INT} intrinsic with an optional argument of
8419 @code{KIND=8}, and is only included for backwards compatibility.
8421 @item @emph{Standard}:
8427 @item @emph{Syntax}:
8428 @code{RESULT = INT8(A)}
8430 @item @emph{Arguments}:
8431 @multitable @columnfractions .15 .70
8432 @item @var{A} @tab Shall be of type @code{INTEGER},
8433 @code{REAL}, or @code{COMPLEX}.
8436 @item @emph{Return value}:
8437 The return value is a @code{INTEGER(8)} variable.
8439 @item @emph{See also}:
8448 @section @code{IOR} --- Bitwise logical or
8454 @cindex bitwise logical or
8455 @cindex logical or, bitwise
8458 @item @emph{Description}:
8459 @code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
8462 @item @emph{Standard}:
8463 Fortran 90 and later, with boz-literal-constant Fortran 2008 and later, has overloads that are GNU extensions
8468 @item @emph{Syntax}:
8469 @code{RESULT = IOR(I, J)}
8471 @item @emph{Arguments}:
8472 @multitable @columnfractions .15 .70
8473 @item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant.
8474 @item @var{J} @tab The type shall be @code{INTEGER} with the same
8475 kind type parameter as @var{I} or a boz-literal-constant.
8476 @var{I} and @var{J} shall not both be boz-literal-constants.
8479 @item @emph{Return value}:
8480 The return type is @code{INTEGER} with the kind type parameter of the
8482 A boz-literal-constant is converted to an @code{INTEGER} with the kind
8483 type parameter of the other argument as-if a call to @ref{INT} occurred.
8485 @item @emph{Specific names}:
8486 @multitable @columnfractions .20 .20 .20 .25
8487 @item Name @tab Argument @tab Return type @tab Standard
8488 @item @code{IOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
8489 @item @code{BIOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8490 @item @code{IIOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8491 @item @code{JIOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8492 @item @code{KIOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8495 @item @emph{See also}:
8507 @section @code{IPARITY} --- Bitwise XOR of array elements
8509 @cindex array, parity
8511 @cindex bits, XOR of array elements
8514 @item @emph{Description}:
8515 Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
8516 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
8518 @item @emph{Standard}:
8519 Fortran 2008 and later
8522 Transformational function
8524 @item @emph{Syntax}:
8525 @multitable @columnfractions .80
8526 @item @code{RESULT = IPARITY(ARRAY[, MASK])}
8527 @item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
8530 @item @emph{Arguments}:
8531 @multitable @columnfractions .15 .70
8532 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
8533 @item @var{DIM} @tab (Optional) shall be a scalar of type
8534 @code{INTEGER} with a value in the range from 1 to n, where n
8535 equals the rank of @var{ARRAY}.
8536 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
8537 and either be a scalar or an array of the same shape as @var{ARRAY}.
8540 @item @emph{Return value}:
8541 The result is of the same type as @var{ARRAY}.
8543 If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
8544 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
8545 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
8546 dimension @var{DIM} dropped is returned.
8548 @item @emph{Example}:
8550 PROGRAM test_iparity
8553 a(1) = int(b'00100100', 1)
8554 a(2) = int(b'01101010', 1)
8557 PRINT '(b8.8)', IPARITY(a)
8561 @item @emph{See also}:
8571 @section @code{IRAND} --- Integer pseudo-random number
8573 @cindex random number generation
8576 @item @emph{Description}:
8577 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
8578 distribution between 0 and a system-dependent limit (which is in most
8579 cases 2147483647). If @var{FLAG} is 0, the next number
8580 in the current sequence is returned; if @var{FLAG} is 1, the generator
8581 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
8582 it is used as a new seed with @code{SRAND}.
8584 This intrinsic routine is provided for backwards compatibility with
8585 GNU Fortran 77. It implements a simple modulo generator as provided
8586 by @command{g77}. For new code, one should consider the use of
8587 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
8589 @item @emph{Standard}:
8595 @item @emph{Syntax}:
8596 @code{RESULT = IRAND(I)}
8598 @item @emph{Arguments}:
8599 @multitable @columnfractions .15 .70
8600 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
8603 @item @emph{Return value}:
8604 The return value is of @code{INTEGER(kind=4)} type.
8606 @item @emph{Example}:
8609 integer,parameter :: seed = 86456
8612 print *, irand(), irand(), irand(), irand()
8613 print *, irand(seed), irand(), irand(), irand()
8614 end program test_irand
8622 @section @code{IS_CONTIGUOUS} --- Test whether an array is contiguous
8623 @fnindex IS_IOSTAT_EOR
8624 @cindex array, contiguity
8627 @item @emph{Description}:
8628 @code{IS_CONTIGUOUS} tests whether an array is contiguous.
8630 @item @emph{Standard}:
8631 Fortran 2008 and later
8636 @item @emph{Syntax}:
8637 @code{RESULT = IS_CONTIGUOUS(ARRAY)}
8639 @item @emph{Arguments}:
8640 @multitable @columnfractions .15 .70
8641 @item @var{ARRAY} @tab Shall be an array of any type.
8644 @item @emph{Return value}:
8645 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
8646 @var{ARRAY} is contiguous and false otherwise.
8648 @item @emph{Example}:
8652 a = [1,2,3,4,5,6,7,8,9,10]
8653 call sub (a) ! every element, is contiguous
8654 call sub (a(::2)) ! every other element, is noncontiguous
8658 if (is_contiguous (x)) then
8659 write (*,*) 'X is contiguous'
8661 write (*,*) 'X is not contiguous'
8671 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
8672 @fnindex IS_IOSTAT_END
8673 @cindex @code{IOSTAT}, end of file
8676 @item @emph{Description}:
8677 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
8678 status ``end of file''. The function is equivalent to comparing the variable
8679 with the @code{IOSTAT_END} parameter of the intrinsic module
8680 @code{ISO_FORTRAN_ENV}.
8682 @item @emph{Standard}:
8683 Fortran 2003 and later
8688 @item @emph{Syntax}:
8689 @code{RESULT = IS_IOSTAT_END(I)}
8691 @item @emph{Arguments}:
8692 @multitable @columnfractions .15 .70
8693 @item @var{I} @tab Shall be of the type @code{INTEGER}.
8696 @item @emph{Return value}:
8697 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
8698 @var{I} has the value which indicates an end of file condition for
8699 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
8701 @item @emph{Example}:
8706 OPEN(88, FILE='test.dat')
8707 READ(88, *, IOSTAT=stat) i
8708 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
8716 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
8717 @fnindex IS_IOSTAT_EOR
8718 @cindex @code{IOSTAT}, end of record
8721 @item @emph{Description}:
8722 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
8723 status ``end of record''. The function is equivalent to comparing the
8724 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
8725 @code{ISO_FORTRAN_ENV}.
8727 @item @emph{Standard}:
8728 Fortran 2003 and later
8733 @item @emph{Syntax}:
8734 @code{RESULT = IS_IOSTAT_EOR(I)}
8736 @item @emph{Arguments}:
8737 @multitable @columnfractions .15 .70
8738 @item @var{I} @tab Shall be of the type @code{INTEGER}.
8741 @item @emph{Return value}:
8742 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
8743 @var{I} has the value which indicates an end of file condition for
8744 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
8746 @item @emph{Example}:
8750 INTEGER :: stat, i(50)
8751 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
8752 READ(88, IOSTAT=stat) i
8753 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
8760 @section @code{ISATTY} --- Whether a unit is a terminal device.
8762 @cindex system, terminal
8765 @item @emph{Description}:
8766 Determine whether a unit is connected to a terminal device.
8768 @item @emph{Standard}:
8774 @item @emph{Syntax}:
8775 @code{RESULT = ISATTY(UNIT)}
8777 @item @emph{Arguments}:
8778 @multitable @columnfractions .15 .70
8779 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
8782 @item @emph{Return value}:
8783 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
8784 device, @code{.FALSE.} otherwise.
8786 @item @emph{Example}:
8789 INTEGER(kind=1) :: unit
8791 write(*,*) isatty(unit=unit)
8795 @item @emph{See also}:
8802 @section @code{ISHFT} --- Shift bits
8811 @item @emph{Description}:
8812 @code{ISHFT} returns a value corresponding to @var{I} with all of the
8813 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
8814 zero corresponds to a left shift, a value of zero corresponds to no
8815 shift, and a value less than zero corresponds to a right shift. If the
8816 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
8817 value is undefined. Bits shifted out from the left end or right end are
8818 lost; zeros are shifted in from the opposite end.
8820 @item @emph{Standard}:
8821 Fortran 90 and later, has overloads that are GNU extensions
8826 @item @emph{Syntax}:
8827 @code{RESULT = ISHFT(I, SHIFT)}
8829 @item @emph{Arguments}:
8830 @multitable @columnfractions .15 .70
8831 @item @var{I} @tab The type shall be @code{INTEGER}.
8832 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8835 @item @emph{Return value}:
8836 The return value is of type @code{INTEGER} and of the same kind as
8839 @item @emph{Specific names}:
8840 @multitable @columnfractions .20 .20 .20 .25
8841 @item Name @tab Argument @tab Return type @tab Standard
8842 @item @code{ISHFT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
8843 @item @code{BSHFT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8844 @item @code{IISHFT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8845 @item @code{JISHFT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8846 @item @code{KISHFT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8849 @item @emph{See also}:
8856 @section @code{ISHFTC} --- Shift bits circularly
8862 @cindex bits, shift circular
8865 @item @emph{Description}:
8866 @code{ISHFTC} returns a value corresponding to @var{I} with the
8867 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
8868 is, bits shifted out one end are shifted into the opposite end. A value
8869 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
8870 zero corresponds to no shift, and a value less than zero corresponds to
8871 a right shift. The absolute value of @var{SHIFT} must be less than
8872 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
8873 equivalent to @code{BIT_SIZE(I)}.
8875 @item @emph{Standard}:
8876 Fortran 90 and later, has overloads that are GNU extensions
8881 @item @emph{Syntax}:
8882 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
8884 @item @emph{Arguments}:
8885 @multitable @columnfractions .15 .70
8886 @item @var{I} @tab The type shall be @code{INTEGER}.
8887 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8888 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
8889 the value must be greater than zero and less than or equal to
8893 @item @emph{Return value}:
8894 The return value is of type @code{INTEGER} and of the same kind as
8897 @item @emph{Specific names}:
8898 @multitable @columnfractions .20 .20 .20 .25
8899 @item Name @tab Argument @tab Return type @tab Standard
8900 @item @code{ISHFTC(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
8901 @item @code{BSHFTC(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8902 @item @code{IISHFTC(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8903 @item @code{JISHFTC(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8904 @item @code{KISHFTC(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8907 @item @emph{See also}:
8914 @section @code{ISNAN} --- Test for a NaN
8919 @item @emph{Description}:
8920 @code{ISNAN} tests whether a floating-point value is an IEEE
8922 @item @emph{Standard}:
8928 @item @emph{Syntax}:
8931 @item @emph{Arguments}:
8932 @multitable @columnfractions .15 .70
8933 @item @var{X} @tab Variable of the type @code{REAL}.
8937 @item @emph{Return value}:
8938 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
8939 if @var{X} is a NaN and @code{FALSE} otherwise.
8941 @item @emph{Example}:
8948 if (isnan(x)) stop '"x" is a NaN'
8949 end program test_nan
8956 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
8958 @cindex time, current
8959 @cindex current time
8962 @item @emph{Description}:
8963 @code{ITIME(VALUES)} Fills @var{VALUES} with the numerical values at the
8964 current local time. The hour (in the range 1-24), minute (in the range 1-60),
8965 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
8968 This intrinsic routine is provided for backwards compatibility with
8969 GNU Fortran 77. In new code, programmers should consider the use of
8970 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
8973 @item @emph{Standard}:
8979 @item @emph{Syntax}:
8980 @code{CALL ITIME(VALUES)}
8982 @item @emph{Arguments}:
8983 @multitable @columnfractions .15 .70
8984 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
8985 and the kind shall be the default integer kind.
8988 @item @emph{Return value}:
8989 Does not return anything.
8992 @item @emph{Example}:
8995 integer, dimension(3) :: tarray
9000 end program test_itime
9003 @item @emph{See also}:
9010 @section @code{KILL} --- Send a signal to a process
9014 @item @emph{Description}:
9015 Sends the signal specified by @var{SIG} to the process @var{PID}.
9018 This intrinsic is provided in both subroutine and function forms;
9019 however, only one form can be used in any given program unit.
9020 @item @emph{Standard}:
9023 @item @emph{Standard}:
9027 Subroutine, function
9029 @item @emph{Syntax}:
9030 @multitable @columnfractions .80
9031 @item @code{CALL KILL(PID, SIG [, STATUS])}
9032 @item @code{STATUS = KILL(PID, SIG)}
9035 @item @emph{Arguments}:
9036 @multitable @columnfractions .15 .70
9037 @item @var{PID} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}.
9038 @item @var{SIG} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}.
9039 @item @var{STATUS} @tab [Subroutine](Optional)
9040 Shall be a scalar @code{INTEGER}.
9041 Returns 0 on success; otherwise a system-specific error code is returned.
9042 @item @var{STATUS} @tab [Function] The kind type parameter is that of
9044 Returns 0 on success; otherwise a system-specific error code is returned.
9047 @item @emph{See also}:
9054 @section @code{KIND} --- Kind of an entity
9059 @item @emph{Description}:
9060 @code{KIND(X)} returns the kind value of the entity @var{X}.
9062 @item @emph{Standard}:
9063 Fortran 95 and later
9068 @item @emph{Syntax}:
9071 @item @emph{Arguments}:
9072 @multitable @columnfractions .15 .70
9073 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
9074 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}. It may be scalar or
9078 @item @emph{Return value}:
9079 The return value is a scalar of type @code{INTEGER} and of the default
9082 @item @emph{Example}:
9085 integer,parameter :: kc = kind(' ')
9086 integer,parameter :: kl = kind(.true.)
9088 print *, "The default character kind is ", kc
9089 print *, "The default logical kind is ", kl
9090 end program test_kind
9098 @section @code{LBOUND} --- Lower dimension bounds of an array
9100 @cindex array, lower bound
9103 @item @emph{Description}:
9104 Returns the lower bounds of an array, or a single lower bound
9105 along the @var{DIM} dimension.
9106 @item @emph{Standard}:
9107 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
9112 @item @emph{Syntax}:
9113 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
9115 @item @emph{Arguments}:
9116 @multitable @columnfractions .15 .70
9117 @item @var{ARRAY} @tab Shall be an array, of any type.
9118 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
9119 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9120 expression indicating the kind parameter of the result.
9123 @item @emph{Return value}:
9124 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9125 @var{KIND} is absent, the return value is of default integer kind.
9126 If @var{DIM} is absent, the result is an array of the lower bounds of
9127 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
9128 corresponding to the lower bound of the array along that dimension. If
9129 @var{ARRAY} is an expression rather than a whole array or array
9130 structure component, or if it has a zero extent along the relevant
9131 dimension, the lower bound is taken to be 1.
9133 @item @emph{See also}:
9141 @section @code{LCOBOUND} --- Lower codimension bounds of an array
9143 @cindex coarray, lower bound
9146 @item @emph{Description}:
9147 Returns the lower bounds of a coarray, or a single lower cobound
9148 along the @var{DIM} codimension.
9149 @item @emph{Standard}:
9150 Fortran 2008 and later
9155 @item @emph{Syntax}:
9156 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
9158 @item @emph{Arguments}:
9159 @multitable @columnfractions .15 .70
9160 @item @var{ARRAY} @tab Shall be an coarray, of any type.
9161 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
9162 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9163 expression indicating the kind parameter of the result.
9166 @item @emph{Return value}:
9167 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9168 @var{KIND} is absent, the return value is of default integer kind.
9169 If @var{DIM} is absent, the result is an array of the lower cobounds of
9170 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
9171 corresponding to the lower cobound of the array along that codimension.
9173 @item @emph{See also}:
9174 @ref{UCOBOUND}, @gol
9181 @section @code{LEADZ} --- Number of leading zero bits of an integer
9186 @item @emph{Description}:
9187 @code{LEADZ} returns the number of leading zero bits of an integer.
9189 @item @emph{Standard}:
9190 Fortran 2008 and later
9195 @item @emph{Syntax}:
9196 @code{RESULT = LEADZ(I)}
9198 @item @emph{Arguments}:
9199 @multitable @columnfractions .15 .70
9200 @item @var{I} @tab Shall be of type @code{INTEGER}.
9203 @item @emph{Return value}:
9204 The type of the return value is the default @code{INTEGER}.
9205 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
9207 @item @emph{Example}:
9210 WRITE (*,*) BIT_SIZE(1) ! prints 32
9211 WRITE (*,*) LEADZ(1) ! prints 31
9215 @item @emph{See also}:
9216 @ref{BIT_SIZE}, @gol
9225 @section @code{LEN} --- Length of a character entity
9227 @cindex string, length
9230 @item @emph{Description}:
9231 Returns the length of a character string. If @var{STRING} is an array,
9232 the length of an element of @var{STRING} is returned. Note that
9233 @var{STRING} need not be defined when this intrinsic is invoked, since
9234 only the length, not the content, of @var{STRING} is needed.
9236 @item @emph{Standard}:
9237 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
9242 @item @emph{Syntax}:
9243 @code{L = LEN(STRING [, KIND])}
9245 @item @emph{Arguments}:
9246 @multitable @columnfractions .15 .70
9247 @item @var{STRING} @tab Shall be a scalar or array of type
9248 @code{CHARACTER}, with @code{INTENT(IN)}
9249 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9250 expression indicating the kind parameter of the result.
9253 @item @emph{Return value}:
9254 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9255 @var{KIND} is absent, the return value is of default integer kind.
9258 @item @emph{Specific names}:
9259 @multitable @columnfractions .20 .20 .20 .25
9260 @item Name @tab Argument @tab Return type @tab Standard
9261 @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
9265 @item @emph{See also}:
9266 @ref{LEN_TRIM}, @gol
9274 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
9276 @cindex string, length, without trailing whitespace
9279 @item @emph{Description}:
9280 Returns the length of a character string, ignoring any trailing blanks.
9282 @item @emph{Standard}:
9283 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
9288 @item @emph{Syntax}:
9289 @code{RESULT = LEN_TRIM(STRING [, KIND])}
9291 @item @emph{Arguments}:
9292 @multitable @columnfractions .15 .70
9293 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
9294 with @code{INTENT(IN)}
9295 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9296 expression indicating the kind parameter of the result.
9299 @item @emph{Return value}:
9300 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9301 @var{KIND} is absent, the return value is of default integer kind.
9303 @item @emph{See also}:
9312 @section @code{LGE} --- Lexical greater than or equal
9314 @cindex lexical comparison of strings
9315 @cindex string, comparison
9318 @item @emph{Description}:
9319 Determines whether one string is lexically greater than or equal to
9320 another string, where the two strings are interpreted as containing
9321 ASCII character codes. If the String A and String B are not the same
9322 length, the shorter is compared as if spaces were appended to it to form
9323 a value that has the same length as the longer.
9325 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9326 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9327 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9328 that the latter use the processor's character ordering (which is not
9329 ASCII on some targets), whereas the former always use the ASCII
9332 @item @emph{Standard}:
9333 Fortran 77 and later
9338 @item @emph{Syntax}:
9339 @code{RESULT = LGE(STRING_A, STRING_B)}
9341 @item @emph{Arguments}:
9342 @multitable @columnfractions .15 .70
9343 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9344 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9347 @item @emph{Return value}:
9348 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
9349 otherwise, based on the ASCII ordering.
9351 @item @emph{Specific names}:
9352 @multitable @columnfractions .20 .20 .20 .25
9353 @item Name @tab Argument @tab Return type @tab Standard
9354 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9357 @item @emph{See also}:
9366 @section @code{LGT} --- Lexical greater than
9368 @cindex lexical comparison of strings
9369 @cindex string, comparison
9372 @item @emph{Description}:
9373 Determines whether one string is lexically greater than another string,
9374 where the two strings are interpreted as containing ASCII character
9375 codes. If the String A and String B are not the same length, the
9376 shorter is compared as if spaces were appended to it to form a value
9377 that has the same length as the longer.
9379 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9380 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9381 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9382 that the latter use the processor's character ordering (which is not
9383 ASCII on some targets), whereas the former always use the ASCII
9386 @item @emph{Standard}:
9387 Fortran 77 and later
9392 @item @emph{Syntax}:
9393 @code{RESULT = LGT(STRING_A, STRING_B)}
9395 @item @emph{Arguments}:
9396 @multitable @columnfractions .15 .70
9397 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9398 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9401 @item @emph{Return value}:
9402 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
9403 otherwise, based on the ASCII ordering.
9405 @item @emph{Specific names}:
9406 @multitable @columnfractions .20 .20 .20 .25
9407 @item Name @tab Argument @tab Return type @tab Standard
9408 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9411 @item @emph{See also}:
9420 @section @code{LINK} --- Create a hard link
9422 @cindex file system, create link
9423 @cindex file system, hard link
9426 @item @emph{Description}:
9427 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
9428 character (@code{CHAR(0)}) can be used to mark the end of the names in
9429 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
9430 names are ignored. If the @var{STATUS} argument is supplied, it
9431 contains 0 on success or a nonzero error code upon return; see
9434 This intrinsic is provided in both subroutine and function forms;
9435 however, only one form can be used in any given program unit.
9437 @item @emph{Standard}:
9441 Subroutine, function
9443 @item @emph{Syntax}:
9444 @multitable @columnfractions .80
9445 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
9446 @item @code{STATUS = LINK(PATH1, PATH2)}
9449 @item @emph{Arguments}:
9450 @multitable @columnfractions .15 .70
9451 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
9452 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
9453 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9456 @item @emph{See also}:
9464 @section @code{LLE} --- Lexical less than or equal
9466 @cindex lexical comparison of strings
9467 @cindex string, comparison
9470 @item @emph{Description}:
9471 Determines whether one string is lexically less than or equal to another
9472 string, where the two strings are interpreted as containing ASCII
9473 character codes. If the String A and String B are not the same length,
9474 the shorter is compared as if spaces were appended to it to form a value
9475 that has the same length as the longer.
9477 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9478 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9479 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9480 that the latter use the processor's character ordering (which is not
9481 ASCII on some targets), whereas the former always use the ASCII
9484 @item @emph{Standard}:
9485 Fortran 77 and later
9490 @item @emph{Syntax}:
9491 @code{RESULT = LLE(STRING_A, STRING_B)}
9493 @item @emph{Arguments}:
9494 @multitable @columnfractions .15 .70
9495 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9496 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9499 @item @emph{Return value}:
9500 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
9501 otherwise, based on the ASCII ordering.
9503 @item @emph{Specific names}:
9504 @multitable @columnfractions .20 .20 .20 .25
9505 @item Name @tab Argument @tab Return type @tab Standard
9506 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9509 @item @emph{See also}:
9518 @section @code{LLT} --- Lexical less than
9520 @cindex lexical comparison of strings
9521 @cindex string, comparison
9524 @item @emph{Description}:
9525 Determines whether one string is lexically less than another string,
9526 where the two strings are interpreted as containing ASCII character
9527 codes. If the String A and String B are not the same length, the
9528 shorter is compared as if spaces were appended to it to form a value
9529 that has the same length as the longer.
9531 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9532 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9533 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9534 that the latter use the processor's character ordering (which is not
9535 ASCII on some targets), whereas the former always use the ASCII
9538 @item @emph{Standard}:
9539 Fortran 77 and later
9544 @item @emph{Syntax}:
9545 @code{RESULT = LLT(STRING_A, STRING_B)}
9547 @item @emph{Arguments}:
9548 @multitable @columnfractions .15 .70
9549 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9550 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9553 @item @emph{Return value}:
9554 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
9555 otherwise, based on the ASCII ordering.
9557 @item @emph{Specific names}:
9558 @multitable @columnfractions .20 .20 .20 .25
9559 @item Name @tab Argument @tab Return type @tab Standard
9560 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9563 @item @emph{See also}:
9572 @section @code{LNBLNK} --- Index of the last non-blank character in a string
9574 @cindex string, find non-blank character
9577 @item @emph{Description}:
9578 Returns the length of a character string, ignoring any trailing blanks.
9579 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
9580 included for backwards compatibility.
9582 @item @emph{Standard}:
9588 @item @emph{Syntax}:
9589 @code{RESULT = LNBLNK(STRING)}
9591 @item @emph{Arguments}:
9592 @multitable @columnfractions .15 .70
9593 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
9594 with @code{INTENT(IN)}
9597 @item @emph{Return value}:
9598 The return value is of @code{INTEGER(kind=4)} type.
9600 @item @emph{See also}:
9601 @ref{INDEX intrinsic}, @gol
9608 @section @code{LOC} --- Returns the address of a variable
9610 @cindex location of a variable in memory
9613 @item @emph{Description}:
9614 @code{LOC(X)} returns the address of @var{X} as an integer.
9616 @item @emph{Standard}:
9622 @item @emph{Syntax}:
9623 @code{RESULT = LOC(X)}
9625 @item @emph{Arguments}:
9626 @multitable @columnfractions .15 .70
9627 @item @var{X} @tab Variable of any type.
9630 @item @emph{Return value}:
9631 The return value is of type @code{INTEGER}, with a @code{KIND}
9632 corresponding to the size (in bytes) of a memory address on the target
9635 @item @emph{Example}:
9642 end program test_loc
9649 @section @code{LOG} --- Natural logarithm function
9656 @cindex exponential function, inverse
9657 @cindex logarithm function
9658 @cindex natural logarithm function
9661 @item @emph{Description}:
9662 @code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the
9663 logarithm to the base @math{e}.
9665 @item @emph{Standard}:
9666 Fortran 77 and later, has GNU extensions
9671 @item @emph{Syntax}:
9672 @code{RESULT = LOG(X)}
9674 @item @emph{Arguments}:
9675 @multitable @columnfractions .15 .70
9676 @item @var{X} @tab The type shall be @code{REAL} or
9680 @item @emph{Return value}:
9681 The return value is of type @code{REAL} or @code{COMPLEX}.
9682 The kind type parameter is the same as @var{X}.
9683 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
9684 @math{-\pi < \omega \leq \pi}.
9686 @item @emph{Example}:
9689 real(8) :: x = 2.7182818284590451_8
9690 complex :: z = (1.0, 2.0)
9691 x = log(x) ! will yield (approximately) 1
9693 end program test_log
9696 @item @emph{Specific names}:
9697 @multitable @columnfractions .20 .20 .20 .25
9698 @item Name @tab Argument @tab Return type @tab Standard
9699 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 or later
9700 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 or later
9701 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 or later
9702 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
9703 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
9710 @section @code{LOG10} --- Base 10 logarithm function
9714 @cindex exponential function, inverse
9715 @cindex logarithm function with base 10
9716 @cindex base 10 logarithm function
9719 @item @emph{Description}:
9720 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
9722 @item @emph{Standard}:
9723 Fortran 77 and later
9728 @item @emph{Syntax}:
9729 @code{RESULT = LOG10(X)}
9731 @item @emph{Arguments}:
9732 @multitable @columnfractions .15 .70
9733 @item @var{X} @tab The type shall be @code{REAL}.
9736 @item @emph{Return value}:
9737 The return value is of type @code{REAL} or @code{COMPLEX}.
9738 The kind type parameter is the same as @var{X}.
9740 @item @emph{Example}:
9743 real(8) :: x = 10.0_8
9745 end program test_log10
9748 @item @emph{Specific names}:
9749 @multitable @columnfractions .20 .20 .20 .25
9750 @item Name @tab Argument @tab Return type @tab Standard
9751 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
9752 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
9759 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
9764 @cindex Gamma function, logarithm of
9767 @item @emph{Description}:
9768 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
9769 of the Gamma (@math{\Gamma}) function.
9771 @item @emph{Standard}:
9772 Fortran 2008 and later
9777 @item @emph{Syntax}:
9778 @code{X = LOG_GAMMA(X)}
9780 @item @emph{Arguments}:
9781 @multitable @columnfractions .15 .70
9782 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
9783 nor a negative integer.
9786 @item @emph{Return value}:
9787 The return value is of type @code{REAL} of the same kind as @var{X}.
9789 @item @emph{Example}:
9791 program test_log_gamma
9793 x = lgamma(x) ! returns 0.0
9794 end program test_log_gamma
9797 @item @emph{Specific names}:
9798 @multitable @columnfractions .20 .20 .20 .25
9799 @item Name @tab Argument @tab Return type @tab Standard
9800 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
9801 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
9802 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
9805 @item @emph{See also}:
9806 Gamma function: @gol
9813 @section @code{LOGICAL} --- Convert to logical type
9815 @cindex conversion, to logical
9818 @item @emph{Description}:
9819 Converts one kind of @code{LOGICAL} variable to another.
9821 @item @emph{Standard}:
9822 Fortran 90 and later
9827 @item @emph{Syntax}:
9828 @code{RESULT = LOGICAL(L [, KIND])}
9830 @item @emph{Arguments}:
9831 @multitable @columnfractions .15 .70
9832 @item @var{L} @tab The type shall be @code{LOGICAL}.
9833 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9834 expression indicating the kind parameter of the result.
9837 @item @emph{Return value}:
9838 The return value is a @code{LOGICAL} value equal to @var{L}, with a
9839 kind corresponding to @var{KIND}, or of the default logical kind if
9840 @var{KIND} is not given.
9842 @item @emph{See also}:
9851 @section @code{LONG} --- Convert to integer type
9853 @cindex conversion, to integer
9856 @item @emph{Description}:
9857 Convert to a @code{KIND=4} integer type, which is the same size as a C
9858 @code{long} integer. This is equivalent to the standard @code{INT}
9859 intrinsic with an optional argument of @code{KIND=4}, and is only
9860 included for backwards compatibility.
9862 @item @emph{Standard}:
9868 @item @emph{Syntax}:
9869 @code{RESULT = LONG(A)}
9871 @item @emph{Arguments}:
9872 @multitable @columnfractions .15 .70
9873 @item @var{A} @tab Shall be of type @code{INTEGER},
9874 @code{REAL}, or @code{COMPLEX}.
9877 @item @emph{Return value}:
9878 The return value is a @code{INTEGER(4)} variable.
9880 @item @emph{See also}:
9889 @section @code{LSHIFT} --- Left shift bits
9891 @cindex bits, shift left
9894 @item @emph{Description}:
9895 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
9896 bits shifted left by @var{SHIFT} places. @var{SHIFT} shall be
9897 nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
9898 the result value is undefined. Bits shifted out from the left end are
9899 lost; zeros are shifted in from the opposite end.
9901 This function has been superseded by the @code{ISHFT} intrinsic, which
9902 is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
9903 which is standard in Fortran 2008 and later.
9905 @item @emph{Standard}:
9911 @item @emph{Syntax}:
9912 @code{RESULT = LSHIFT(I, SHIFT)}
9914 @item @emph{Arguments}:
9915 @multitable @columnfractions .15 .70
9916 @item @var{I} @tab The type shall be @code{INTEGER}.
9917 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
9920 @item @emph{Return value}:
9921 The return value is of type @code{INTEGER} and of the same kind as
9924 @item @emph{See also}:
9936 @section @code{LSTAT} --- Get file status
9938 @cindex file system, file status
9941 @item @emph{Description}:
9942 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
9943 symbolic link, then the link itself is statted, not the file that it
9946 The elements in @code{VALUES} are the same as described by @ref{STAT}.
9948 This intrinsic is provided in both subroutine and function forms;
9949 however, only one form can be used in any given program unit.
9951 @item @emph{Standard}:
9955 Subroutine, function
9957 @item @emph{Syntax}:
9958 @multitable @columnfractions .80
9959 @item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
9960 @item @code{STATUS = LSTAT(NAME, VALUES)}
9963 @item @emph{Arguments}:
9964 @multitable @columnfractions .15 .70
9965 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
9966 kind, a valid path within the file system.
9967 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
9968 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
9969 Returns 0 on success and a system specific error code otherwise.
9972 @item @emph{Example}:
9973 See @ref{STAT} for an example.
9975 @item @emph{See also}:
9976 To stat an open file: @gol
9978 To stat a file: @gol
9985 @section @code{LTIME} --- Convert time to local time info
9987 @cindex time, conversion to local time info
9990 @item @emph{Description}:
9991 Given a system time value @var{TIME} (as provided by the @ref{TIME}
9992 intrinsic), fills @var{VALUES} with values extracted from it appropriate
9993 to the local time zone using @code{localtime(3)}.
9995 This intrinsic routine is provided for backwards compatibility with
9996 GNU Fortran 77. In new code, programmers should consider the use of
9997 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
10000 @item @emph{Standard}:
10003 @item @emph{Class}:
10006 @item @emph{Syntax}:
10007 @code{CALL LTIME(TIME, VALUES)}
10009 @item @emph{Arguments}:
10010 @multitable @columnfractions .15 .70
10011 @item @var{TIME} @tab An @code{INTEGER} scalar expression
10012 corresponding to a system time, with @code{INTENT(IN)}.
10013 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
10014 with @code{INTENT(OUT)}.
10017 @item @emph{Return value}:
10018 The elements of @var{VALUES} are assigned as follows:
10020 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
10022 @item Minutes after the hour, range 0--59
10023 @item Hours past midnight, range 0--23
10024 @item Day of month, range 1--31
10025 @item Number of months since January, range 0--11
10026 @item Years since 1900
10027 @item Number of days since Sunday, range 0--6
10028 @item Days since January 1, range 0--365
10029 @item Daylight savings indicator: positive if daylight savings is in
10030 effect, zero if not, and negative if the information is not available.
10033 @item @emph{See also}:
10034 @ref{DATE_AND_TIME}, @gol
10044 @section @code{MALLOC} --- Allocate dynamic memory
10046 @cindex pointer, cray
10049 @item @emph{Description}:
10050 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
10051 returns the address of the allocated memory. The @code{MALLOC} intrinsic
10052 is an extension intended to be used with Cray pointers, and is provided
10053 in GNU Fortran to allow the user to compile legacy code. For new code
10054 using Fortran 95 pointers, the memory allocation intrinsic is
10057 @item @emph{Standard}:
10060 @item @emph{Class}:
10063 @item @emph{Syntax}:
10064 @code{PTR = MALLOC(SIZE)}
10066 @item @emph{Arguments}:
10067 @multitable @columnfractions .15 .70
10068 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
10071 @item @emph{Return value}:
10072 The return value is of type @code{INTEGER(K)}, with @var{K} such that
10073 variables of type @code{INTEGER(K)} have the same size as
10074 C pointers (@code{sizeof(void *)}).
10076 @item @emph{Example}:
10077 The following example demonstrates the use of @code{MALLOC} and
10078 @code{FREE} with Cray pointers.
10081 program test_malloc
10087 ptr_x = malloc(20*8)
10089 x(i) = sqrt(1.0d0 / i)
10097 end program test_malloc
10100 @item @emph{See also}:
10107 @section @code{MASKL} --- Left justified mask
10109 @cindex mask, left justified
10112 @item @emph{Description}:
10113 @code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
10114 remaining bits set to 0.
10116 @item @emph{Standard}:
10117 Fortran 2008 and later
10119 @item @emph{Class}:
10122 @item @emph{Syntax}:
10123 @code{RESULT = MASKL(I[, KIND])}
10125 @item @emph{Arguments}:
10126 @multitable @columnfractions .15 .70
10127 @item @var{I} @tab Shall be of type @code{INTEGER}.
10128 @item @var{KIND} @tab Shall be a scalar constant expression of type
10132 @item @emph{Return value}:
10133 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
10134 specifies the kind value of the return type; otherwise, it is of the
10135 default integer kind.
10137 @item @emph{See also}:
10144 @section @code{MASKR} --- Right justified mask
10146 @cindex mask, right justified
10149 @item @emph{Description}:
10150 @code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
10151 remaining bits set to 0.
10153 @item @emph{Standard}:
10154 Fortran 2008 and later
10156 @item @emph{Class}:
10159 @item @emph{Syntax}:
10160 @code{RESULT = MASKR(I[, KIND])}
10162 @item @emph{Arguments}:
10163 @multitable @columnfractions .15 .70
10164 @item @var{I} @tab Shall be of type @code{INTEGER}.
10165 @item @var{KIND} @tab Shall be a scalar constant expression of type
10169 @item @emph{Return value}:
10170 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
10171 specifies the kind value of the return type; otherwise, it is of the
10172 default integer kind.
10174 @item @emph{See also}:
10181 @section @code{MATMUL} --- matrix multiplication
10183 @cindex matrix multiplication
10184 @cindex product, matrix
10187 @item @emph{Description}:
10188 Performs a matrix multiplication on numeric or logical arguments.
10190 @item @emph{Standard}:
10191 Fortran 90 and later
10193 @item @emph{Class}:
10194 Transformational function
10196 @item @emph{Syntax}:
10197 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
10199 @item @emph{Arguments}:
10200 @multitable @columnfractions .15 .70
10201 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
10202 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
10204 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
10205 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
10206 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
10207 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
10208 equal to the last (or only) dimension of @var{MATRIX_A}.
10209 @var{MATRIX_A} and @var{MATRIX_B} shall not both be rank one arrays.
10212 @item @emph{Return value}:
10213 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
10214 kind of the result follow the usual type and kind promotion rules, as
10215 for the @code{*} or @code{.AND.} operators.
10221 @section @code{MAX} --- Maximum value of an argument list
10228 @cindex maximum value
10231 @item @emph{Description}:
10232 Returns the argument with the largest (most positive) value.
10234 @item @emph{Standard}:
10235 Fortran 77 and later
10237 @item @emph{Class}:
10240 @item @emph{Syntax}:
10241 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
10243 @item @emph{Arguments}:
10244 @multitable @columnfractions .15 .70
10245 @item @var{A1} @tab The type shall be @code{INTEGER} or
10247 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
10248 as @var{A1}. (As a GNU extension, arguments of different kinds are
10252 @item @emph{Return value}:
10253 The return value corresponds to the maximum value among the arguments,
10254 and has the same type and kind as the first argument.
10256 @item @emph{Specific names}:
10257 @multitable @columnfractions .20 .20 .20 .25
10258 @item Name @tab Argument @tab Return type @tab Standard
10259 @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
10260 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
10261 @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
10262 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
10263 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
10266 @item @emph{See also}:
10275 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
10276 @fnindex MAXEXPONENT
10277 @cindex model representation, maximum exponent
10280 @item @emph{Description}:
10281 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
10284 @item @emph{Standard}:
10285 Fortran 90 and later
10287 @item @emph{Class}:
10290 @item @emph{Syntax}:
10291 @code{RESULT = MAXEXPONENT(X)}
10293 @item @emph{Arguments}:
10294 @multitable @columnfractions .15 .70
10295 @item @var{X} @tab Shall be of type @code{REAL}.
10298 @item @emph{Return value}:
10299 The return value is of type @code{INTEGER} and of the default integer
10302 @item @emph{Example}:
10308 print *, minexponent(x), maxexponent(x)
10309 print *, minexponent(y), maxexponent(y)
10310 end program exponents
10317 @section @code{MAXLOC} --- Location of the maximum value within an array
10319 @cindex array, location of maximum element
10322 @item @emph{Description}:
10323 Determines the location of the element in the array with the maximum
10324 value, or, if the @var{DIM} argument is supplied, determines the
10325 locations of the maximum element along each row of the array in the
10326 @var{DIM} direction. If @var{MASK} is present, only the elements for
10327 which @var{MASK} is @code{.TRUE.} are considered. If more than one
10328 element in the array has the maximum value, the location returned is
10329 that of the first such element in array element order if the
10330 @var{BACK} is not present, or is false; if @var{BACK} is true, the location
10331 returned is that of the last such element. If the array has zero
10332 size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
10333 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
10334 and all of the elements of @var{MASK} along a given row are zero, the
10335 result value for that row is zero.
10337 @item @emph{Standard}:
10338 Fortran 95 and later; @var{ARRAY} of @code{CHARACTER} and the
10339 @var{KIND} argument are available in Fortran 2003 and later.
10340 The @var{BACK} argument is available in Fortran 2008 and later.
10342 @item @emph{Class}:
10343 Transformational function
10345 @item @emph{Syntax}:
10346 @multitable @columnfractions .80
10347 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK])}
10348 @item @code{RESULT = MAXLOC(ARRAY [, MASK] [,KIND] [,BACK])}
10351 @item @emph{Arguments}:
10352 @multitable @columnfractions .15 .70
10353 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10355 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10356 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10357 inclusive. It may not be an optional dummy argument.
10358 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
10359 and conformable with @var{ARRAY}.
10360 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10361 expression indicating the kind parameter of the result.
10362 @item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}.
10365 @item @emph{Return value}:
10366 If @var{DIM} is absent, the result is a rank-one array with a length
10367 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
10368 is an array with a rank one less than the rank of @var{ARRAY}, and a
10369 size corresponding to the size of @var{ARRAY} with the @var{DIM}
10370 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
10371 of one, the result is a scalar. If the optional argument @var{KIND}
10372 is present, the result is an integer of kind @var{KIND}, otherwise it
10373 is of default kind.
10375 @item @emph{See also}:
10376 @ref{FINDLOC}, @gol
10384 @section @code{MAXVAL} --- Maximum value of an array
10386 @cindex array, maximum value
10387 @cindex maximum value
10390 @item @emph{Description}:
10391 Determines the maximum value of the elements in an array value, or, if
10392 the @var{DIM} argument is supplied, determines the maximum value along
10393 each row of the array in the @var{DIM} direction. If @var{MASK} is
10394 present, only the elements for which @var{MASK} is @code{.TRUE.} are
10395 considered. If the array has zero size, or all of the elements of
10396 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
10397 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
10400 @item @emph{Standard}:
10401 Fortran 90 and later
10403 @item @emph{Class}:
10404 Transformational function
10406 @item @emph{Syntax}:
10407 @multitable @columnfractions .80
10408 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
10409 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
10412 @item @emph{Arguments}:
10413 @multitable @columnfractions .15 .70
10414 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10416 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10417 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10418 inclusive. It may not be an optional dummy argument.
10419 @item @var{MASK} @tab (Opional) Shall be an array of type @code{LOGICAL},
10420 and conformable with @var{ARRAY}.
10423 @item @emph{Return value}:
10424 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
10425 is a scalar. If @var{DIM} is present, the result is an array with a
10426 rank one less than the rank of @var{ARRAY}, and a size corresponding to
10427 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
10428 cases, the result is of the same type and kind as @var{ARRAY}.
10430 @item @emph{See also}:
10438 @section @code{MCLOCK} --- Time function
10440 @cindex time, clock ticks
10441 @cindex clock ticks
10444 @item @emph{Description}:
10445 Returns the number of clock ticks since the start of the process, based
10446 on the function @code{clock(3)} in the C standard library.
10448 This intrinsic is not fully portable, such as to systems with 32-bit
10449 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
10450 the values returned by this intrinsic might be, or become, negative, or
10451 numerically less than previous values, during a single run of the
10454 @item @emph{Standard}:
10457 @item @emph{Class}:
10460 @item @emph{Syntax}:
10461 @code{RESULT = MCLOCK()}
10463 @item @emph{Return value}:
10464 The return value is a scalar of type @code{INTEGER(4)}, equal to the
10465 number of clock ticks since the start of the process, or @code{-1} if
10466 the system does not support @code{clock(3)}.
10468 @item @emph{See also}:
10479 @section @code{MCLOCK8} --- Time function (64-bit)
10481 @cindex time, clock ticks
10482 @cindex clock ticks
10485 @item @emph{Description}:
10486 Returns the number of clock ticks since the start of the process, based
10487 on the function @code{clock(3)} in the C standard library.
10489 @emph{Warning:} this intrinsic does not increase the range of the timing
10490 values over that returned by @code{clock(3)}. On a system with a 32-bit
10491 @code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though
10492 it is converted to a 64-bit @code{INTEGER(8)} value. That means
10493 overflows of the 32-bit value can still occur. Therefore, the values
10494 returned by this intrinsic might be or become negative or numerically
10495 less than previous values during a single run of the compiled program.
10497 @item @emph{Standard}:
10500 @item @emph{Class}:
10503 @item @emph{Syntax}:
10504 @code{RESULT = MCLOCK8()}
10506 @item @emph{Return value}:
10507 The return value is a scalar of type @code{INTEGER(8)}, equal to the
10508 number of clock ticks since the start of the process, or @code{-1} if
10509 the system does not support @code{clock(3)}.
10511 @item @emph{See also}:
10522 @section @code{MERGE} --- Merge variables
10524 @cindex array, merge arrays
10525 @cindex array, combine arrays
10528 @item @emph{Description}:
10529 Select values from two arrays according to a logical mask. The result
10530 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
10531 @var{FSOURCE} if it is @code{.FALSE.}.
10533 @item @emph{Standard}:
10534 Fortran 90 and later
10536 @item @emph{Class}:
10539 @item @emph{Syntax}:
10540 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
10542 @item @emph{Arguments}:
10543 @multitable @columnfractions .15 .70
10544 @item @var{TSOURCE} @tab May be of any type.
10545 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
10547 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
10550 @item @emph{Return value}:
10551 The result is of the same type and type parameters as @var{TSOURCE}.
10558 @section @code{MERGE_BITS} --- Merge of bits under mask
10559 @fnindex MERGE_BITS
10560 @cindex bits, merge
10563 @item @emph{Description}:
10564 @code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
10565 as determined by the mask. The i-th bit of the result is equal to the
10566 i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
10567 the i-th bit of @var{J} otherwise.
10569 @item @emph{Standard}:
10570 Fortran 2008 and later
10572 @item @emph{Class}:
10575 @item @emph{Syntax}:
10576 @code{RESULT = MERGE_BITS(I, J, MASK)}
10578 @item @emph{Arguments}:
10579 @multitable @columnfractions .15 .70
10580 @item @var{I} @tab Shall be of type @code{INTEGER} or a boz-literal-constant.
10581 @item @var{J} @tab Shall be of type @code{INTEGER} with the same
10582 kind type parameter as @var{I} or a boz-literal-constant.
10583 @var{I} and @var{J} shall not both be boz-literal-constants.
10584 @item @var{MASK} @tab Shall be of type @code{INTEGER} or a boz-literal-constant
10585 and of the same kind as @var{I}.
10588 @item @emph{Return value}:
10589 The result is of the same type and kind as @var{I}.
10596 @section @code{MIN} --- Minimum value of an argument list
10603 @cindex minimum value
10606 @item @emph{Description}:
10607 Returns the argument with the smallest (most negative) value.
10609 @item @emph{Standard}:
10610 Fortran 77 and later
10612 @item @emph{Class}:
10615 @item @emph{Syntax}:
10616 @code{RESULT = MIN(A1, A2 [, A3, ...])}
10618 @item @emph{Arguments}:
10619 @multitable @columnfractions .15 .70
10620 @item @var{A1} @tab The type shall be @code{INTEGER} or
10622 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
10623 as @var{A1}. (As a GNU extension, arguments of different kinds are
10627 @item @emph{Return value}:
10628 The return value corresponds to the maximum value among the arguments,
10629 and has the same type and kind as the first argument.
10631 @item @emph{Specific names}:
10632 @multitable @columnfractions .20 .20 .20 .25
10633 @item Name @tab Argument @tab Return type @tab Standard
10634 @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
10635 @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
10636 @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
10637 @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
10638 @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
10641 @item @emph{See also}:
10650 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
10651 @fnindex MINEXPONENT
10652 @cindex model representation, minimum exponent
10655 @item @emph{Description}:
10656 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
10659 @item @emph{Standard}:
10660 Fortran 90 and later
10662 @item @emph{Class}:
10665 @item @emph{Syntax}:
10666 @code{RESULT = MINEXPONENT(X)}
10668 @item @emph{Arguments}:
10669 @multitable @columnfractions .15 .70
10670 @item @var{X} @tab Shall be of type @code{REAL}.
10673 @item @emph{Return value}:
10674 The return value is of type @code{INTEGER} and of the default integer
10677 @item @emph{Example}:
10678 See @code{MAXEXPONENT} for an example.
10684 @section @code{MINLOC} --- Location of the minimum value within an array
10686 @cindex array, location of minimum element
10689 @item @emph{Description}:
10690 Determines the location of the element in the array with the minimum
10691 value, or, if the @var{DIM} argument is supplied, determines the
10692 locations of the minimum element along each row of the array in the
10693 @var{DIM} direction. If @var{MASK} is present, only the elements for
10694 which @var{MASK} is @code{.TRUE.} are considered. If more than one
10695 element in the array has the minimum value, the location returned is
10696 that of the first such element in array element order if the
10697 @var{BACK} is not present, or is false; if @var{BACK} is true, the location
10698 returned is that of the last such element. If the array has
10699 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
10700 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
10701 and all of the elements of @var{MASK} along a given row are zero, the
10702 result value for that row is zero.
10704 @item @emph{Standard}:
10705 Fortran 90 and later; @var{ARRAY} of @code{CHARACTER} and the
10706 @var{KIND} argument are available in Fortran 2003 and later.
10707 The @var{BACK} argument is available in Fortran 2008 and later.
10709 @item @emph{Class}:
10710 Transformational function
10712 @item @emph{Syntax}:
10713 @multitable @columnfractions .80
10714 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK])}
10715 @item @code{RESULT = MINLOC(ARRAY [, MASK], [,KIND] [,BACK])}
10718 @item @emph{Arguments}:
10719 @multitable @columnfractions .15 .70
10720 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
10721 @code{REAL} or @code{CHARACTER}.
10722 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10723 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10724 inclusive. It may not be an optional dummy argument.
10725 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
10726 and conformable with @var{ARRAY}.
10727 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10728 expression indicating the kind parameter of the result.
10729 @item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}.
10732 @item @emph{Return value}:
10733 If @var{DIM} is absent, the result is a rank-one array with a length
10734 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
10735 is an array with a rank one less than the rank of @var{ARRAY}, and a
10736 size corresponding to the size of @var{ARRAY} with the @var{DIM}
10737 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
10738 of one, the result is a scalar. If the optional argument @var{KIND}
10739 is present, the result is an integer of kind @var{KIND}, otherwise it
10740 is of default kind.
10742 @item @emph{See also}:
10743 @ref{FINDLOC}, @gol
10751 @section @code{MINVAL} --- Minimum value of an array
10753 @cindex array, minimum value
10754 @cindex minimum value
10757 @item @emph{Description}:
10758 Determines the minimum value of the elements in an array value, or, if
10759 the @var{DIM} argument is supplied, determines the minimum value along
10760 each row of the array in the @var{DIM} direction. If @var{MASK} is
10761 present, only the elements for which @var{MASK} is @code{.TRUE.} are
10762 considered. If the array has zero size, or all of the elements of
10763 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
10764 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
10765 @var{ARRAY} is of character type.
10767 @item @emph{Standard}:
10768 Fortran 90 and later
10770 @item @emph{Class}:
10771 Transformational function
10773 @item @emph{Syntax}:
10774 @multitable @columnfractions .80
10775 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
10776 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
10779 @item @emph{Arguments}:
10780 @multitable @columnfractions .15 .70
10781 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10783 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10784 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10785 inclusive. It may not be an optional dummy argument.
10786 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
10787 and conformable with @var{ARRAY}.
10790 @item @emph{Return value}:
10791 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
10792 is a scalar. If @var{DIM} is present, the result is an array with a
10793 rank one less than the rank of @var{ARRAY}, and a size corresponding to
10794 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
10795 cases, the result is of the same type and kind as @var{ARRAY}.
10797 @item @emph{See also}:
10805 @section @code{MOD} --- Remainder function
10814 @cindex division, remainder
10817 @item @emph{Description}:
10818 @code{MOD(A,P)} computes the remainder of the division of A by P@.
10820 @item @emph{Standard}:
10821 Fortran 77 and later, has overloads that are GNU extensions
10823 @item @emph{Class}:
10826 @item @emph{Syntax}:
10827 @code{RESULT = MOD(A, P)}
10829 @item @emph{Arguments}:
10830 @multitable @columnfractions .15 .70
10831 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
10832 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
10833 and not equal to zero. (As a GNU extension, arguments of different kinds are
10837 @item @emph{Return value}:
10838 The return value is the result of @code{A - (INT(A/P) * P)}. The type
10839 and kind of the return value is the same as that of the arguments. The
10840 returned value has the same sign as A and a magnitude less than the
10841 magnitude of P. (As a GNU extension, kind is the largest kind of the actual
10844 @item @emph{Example}:
10848 print *, mod(17.5,5.5)
10849 print *, mod(17.5d0,5.5)
10850 print *, mod(17.5,5.5d0)
10852 print *, mod(-17,3)
10853 print *, mod(-17.5,5.5)
10854 print *, mod(-17.5d0,5.5)
10855 print *, mod(-17.5,5.5d0)
10857 print *, mod(17,-3)
10858 print *, mod(17.5,-5.5)
10859 print *, mod(17.5d0,-5.5)
10860 print *, mod(17.5,-5.5d0)
10861 end program test_mod
10864 @item @emph{Specific names}:
10865 @multitable @columnfractions .20 .20 .20 .25
10866 @item Name @tab Arguments @tab Return type @tab Standard
10867 @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 77 and later
10868 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 77 and later
10869 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 77 and later
10870 @item @code{BMOD(A,P)} @tab @code{INTEGER(1) A,P} @tab @code{INTEGER(1)} @tab GNU extension
10871 @item @code{IMOD(A,P)} @tab @code{INTEGER(2) A,P} @tab @code{INTEGER(2)} @tab GNU extension
10872 @item @code{JMOD(A,P)} @tab @code{INTEGER(4) A,P} @tab @code{INTEGER(4)} @tab GNU extension
10873 @item @code{KMOD(A,P)} @tab @code{INTEGER(8) A,P} @tab @code{INTEGER(8)} @tab GNU extension
10876 @item @emph{See also}:
10884 @section @code{MODULO} --- Modulo function
10887 @cindex division, modulo
10890 @item @emph{Description}:
10891 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
10893 @item @emph{Standard}:
10894 Fortran 95 and later
10896 @item @emph{Class}:
10899 @item @emph{Syntax}:
10900 @code{RESULT = MODULO(A, P)}
10902 @item @emph{Arguments}:
10903 @multitable @columnfractions .15 .70
10904 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
10905 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}.
10906 It shall not be zero. (As a GNU extension, arguments of different kinds are
10910 @item @emph{Return value}:
10911 The type and kind of the result are those of the arguments. (As a GNU
10912 extension, kind is the largest kind of the actual arguments.)
10914 @item If @var{A} and @var{P} are of type @code{INTEGER}:
10915 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
10916 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
10918 @item If @var{A} and @var{P} are of type @code{REAL}:
10919 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
10921 The returned value has the same sign as P and a magnitude less than
10922 the magnitude of P.
10924 @item @emph{Example}:
10926 program test_modulo
10927 print *, modulo(17,3)
10928 print *, modulo(17.5,5.5)
10930 print *, modulo(-17,3)
10931 print *, modulo(-17.5,5.5)
10933 print *, modulo(17,-3)
10934 print *, modulo(17.5,-5.5)
10938 @item @emph{See also}:
10946 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
10947 @fnindex MOVE_ALLOC
10948 @cindex moving allocation
10949 @cindex allocation, moving
10952 @item @emph{Description}:
10953 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
10954 @var{TO}. @var{FROM} will become deallocated in the process.
10956 @item @emph{Standard}:
10957 Fortran 2003 and later
10959 @item @emph{Class}:
10962 @item @emph{Syntax}:
10963 @code{CALL MOVE_ALLOC(FROM, TO)}
10965 @item @emph{Arguments}:
10966 @multitable @columnfractions .15 .70
10967 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
10968 of any type and kind.
10969 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
10970 of the same type, kind and rank as @var{FROM}.
10973 @item @emph{Return value}:
10976 @item @emph{Example}:
10978 program test_move_alloc
10979 integer, allocatable :: a(:), b(:)
10983 call move_alloc(a, b)
10984 print *, allocated(a), allocated(b)
10986 end program test_move_alloc
10993 @section @code{MVBITS} --- Move bits from one integer to another
11002 @item @emph{Description}:
11003 Moves @var{LEN} bits from positions @var{FROMPOS} through
11004 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
11005 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
11006 affected by the movement of bits is unchanged. The values of
11007 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
11008 @code{BIT_SIZE(FROM)}.
11010 @item @emph{Standard}:
11011 Fortran 90 and later, has overloads that are GNU extensions
11013 @item @emph{Class}:
11014 Elemental subroutine
11016 @item @emph{Syntax}:
11017 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
11019 @item @emph{Arguments}:
11020 @multitable @columnfractions .15 .70
11021 @item @var{FROM} @tab The type shall be @code{INTEGER}.
11022 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
11023 @item @var{LEN} @tab The type shall be @code{INTEGER}.
11024 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
11025 same kind as @var{FROM}.
11026 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
11029 @item @emph{Specific names}:
11030 @multitable @columnfractions .20 .20 .20 .25
11031 @item Name @tab Argument @tab Return type @tab Standard
11032 @item @code{MVBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 90 and later
11033 @item @code{BMVBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
11034 @item @code{IMVBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
11035 @item @code{JMVBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
11036 @item @code{KMVBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
11039 @item @emph{See also}:
11051 @section @code{NEAREST} --- Nearest representable number
11053 @cindex real number, nearest different
11054 @cindex floating point, nearest different
11057 @item @emph{Description}:
11058 @code{NEAREST(X, S)} returns the processor-representable number nearest
11059 to @code{X} in the direction indicated by the sign of @code{S}.
11061 @item @emph{Standard}:
11062 Fortran 90 and later
11064 @item @emph{Class}:
11067 @item @emph{Syntax}:
11068 @code{RESULT = NEAREST(X, S)}
11070 @item @emph{Arguments}:
11071 @multitable @columnfractions .15 .70
11072 @item @var{X} @tab Shall be of type @code{REAL}.
11073 @item @var{S} @tab Shall be of type @code{REAL} and
11077 @item @emph{Return value}:
11078 The return value is of the same type as @code{X}. If @code{S} is
11079 positive, @code{NEAREST} returns the processor-representable number
11080 greater than @code{X} and nearest to it. If @code{S} is negative,
11081 @code{NEAREST} returns the processor-representable number smaller than
11082 @code{X} and nearest to it.
11084 @item @emph{Example}:
11086 program test_nearest
11088 x = nearest(42.0, 1.0)
11089 y = nearest(42.0, -1.0)
11090 write (*,"(3(G20.15))") x, y, x - y
11091 end program test_nearest
11098 @section @code{NEW_LINE} --- New line character
11101 @cindex output, newline
11104 @item @emph{Description}:
11105 @code{NEW_LINE(C)} returns the new-line character.
11107 @item @emph{Standard}:
11108 Fortran 2003 and later
11110 @item @emph{Class}:
11113 @item @emph{Syntax}:
11114 @code{RESULT = NEW_LINE(C)}
11116 @item @emph{Arguments}:
11117 @multitable @columnfractions .15 .70
11118 @item @var{C} @tab The argument shall be a scalar or array of the
11119 type @code{CHARACTER}.
11122 @item @emph{Return value}:
11123 Returns a @var{CHARACTER} scalar of length one with the new-line character of
11124 the same kind as parameter @var{C}.
11126 @item @emph{Example}:
11130 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
11131 end program newline
11138 @section @code{NINT} --- Nearest whole number
11141 @cindex rounding, nearest whole number
11144 @item @emph{Description}:
11145 @code{NINT(A)} rounds its argument to the nearest whole number.
11147 @item @emph{Standard}:
11148 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
11150 @item @emph{Class}:
11153 @item @emph{Syntax}:
11154 @code{RESULT = NINT(A [, KIND])}
11156 @item @emph{Arguments}:
11157 @multitable @columnfractions .15 .70
11158 @item @var{A} @tab The type of the argument shall be @code{REAL}.
11159 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11160 expression indicating the kind parameter of the result.
11163 @item @emph{Return value}:
11164 Returns @var{A} with the fractional portion of its magnitude eliminated by
11165 rounding to the nearest whole number and with its sign preserved,
11166 converted to an @code{INTEGER} of the default kind.
11168 @item @emph{Example}:
11175 print *, nint(x4), idnint(x8)
11176 end program test_nint
11179 @item @emph{Specific names}:
11180 @multitable @columnfractions .20 .20 .20 .25
11181 @item Name @tab Argument @tab Return Type @tab Standard
11182 @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
11183 @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
11186 @item @emph{See also}:
11187 @ref{CEILING}, @gol
11194 @section @code{NORM2} --- Euclidean vector norms
11196 @cindex Euclidean vector norm
11197 @cindex L2 vector norm
11198 @cindex norm, Euclidean
11201 @item @emph{Description}:
11202 Calculates the Euclidean vector norm (@math{L_2} norm) of
11203 of @var{ARRAY} along dimension @var{DIM}.
11205 @item @emph{Standard}:
11206 Fortran 2008 and later
11208 @item @emph{Class}:
11209 Transformational function
11211 @item @emph{Syntax}:
11212 @multitable @columnfractions .80
11213 @item @code{RESULT = NORM2(ARRAY[, DIM])}
11216 @item @emph{Arguments}:
11217 @multitable @columnfractions .15 .70
11218 @item @var{ARRAY} @tab Shall be an array of type @code{REAL}
11219 @item @var{DIM} @tab (Optional) shall be a scalar of type
11220 @code{INTEGER} with a value in the range from 1 to n, where n
11221 equals the rank of @var{ARRAY}.
11224 @item @emph{Return value}:
11225 The result is of the same type as @var{ARRAY}.
11227 If @var{DIM} is absent, a scalar with the square root of the sum of all
11228 elements in @var{ARRAY} squared is returned. Otherwise, an array of
11229 rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
11230 shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
11233 @item @emph{Example}:
11236 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
11237 print *, NORM2(x) ! = sqrt(55.) ~ 7.416
11245 @section @code{NOT} --- Logical negation
11251 @cindex bits, negate
11252 @cindex bitwise logical not
11253 @cindex logical not, bitwise
11256 @item @emph{Description}:
11257 @code{NOT} returns the bitwise Boolean inverse of @var{I}.
11259 @item @emph{Standard}:
11260 Fortran 90 and later, has overloads that are GNU extensions
11262 @item @emph{Class}:
11265 @item @emph{Syntax}:
11266 @code{RESULT = NOT(I)}
11268 @item @emph{Arguments}:
11269 @multitable @columnfractions .15 .70
11270 @item @var{I} @tab The type shall be @code{INTEGER}.
11273 @item @emph{Return value}:
11274 The return type is @code{INTEGER}, of the same kind as the
11277 @item @emph{Specific names}:
11278 @multitable @columnfractions .20 .20 .20 .25
11279 @item Name @tab Argument @tab Return type @tab Standard
11280 @item @code{NOT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
11281 @item @code{BNOT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
11282 @item @code{INOT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
11283 @item @code{JNOT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
11284 @item @code{KNOT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
11287 @item @emph{See also}:
11299 @section @code{NULL} --- Function that returns an disassociated pointer
11301 @cindex pointer, status
11302 @cindex pointer, disassociated
11305 @item @emph{Description}:
11306 Returns a disassociated pointer.
11308 If @var{MOLD} is present, a disassociated pointer of the same type is
11309 returned, otherwise the type is determined by context.
11311 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
11312 includes cases where it is required.
11314 @item @emph{Standard}:
11315 Fortran 95 and later
11317 @item @emph{Class}:
11318 Transformational function
11320 @item @emph{Syntax}:
11321 @code{PTR => NULL([MOLD])}
11323 @item @emph{Arguments}:
11324 @multitable @columnfractions .15 .70
11325 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
11326 status and of any type.
11329 @item @emph{Return value}:
11330 A disassociated pointer.
11332 @item @emph{Example}:
11334 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
11337 @item @emph{See also}:
11344 @section @code{NUM_IMAGES} --- Function that returns the number of images
11345 @fnindex NUM_IMAGES
11346 @cindex coarray, @code{NUM_IMAGES}
11347 @cindex images, number of
11350 @item @emph{Description}:
11351 Returns the number of images.
11353 @item @emph{Standard}:
11354 Fortran 2008 and later. With @var{DISTANCE} or @var{FAILED} argument,
11355 Technical Specification (TS) 18508 or later
11358 @item @emph{Class}:
11359 Transformational function
11361 @item @emph{Syntax}:
11362 @code{RESULT = NUM_IMAGES(DISTANCE, FAILED)}
11364 @item @emph{Arguments}:
11365 @multitable @columnfractions .15 .70
11366 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
11367 @item @var{FAILED} @tab (optional, intent(in)) Scalar logical expression
11370 @item @emph{Return value}:
11371 Scalar default-kind integer. If @var{DISTANCE} is not present or has value 0,
11372 the number of images in the current team is returned. For values smaller or
11373 equal distance to the initial team, it returns the number of images index
11374 on the ancestor team which has a distance of @var{DISTANCE} from the invoking
11375 team. If @var{DISTANCE} is larger than the distance to the initial team, the
11376 number of images of the initial team is returned. If @var{FAILED} is not present
11377 the total number of images is returned; if it has the value @code{.TRUE.},
11378 the number of failed images is returned, otherwise, the number of images which
11379 do have not the failed status.
11381 @item @emph{Example}:
11383 INTEGER :: value[*]
11385 value = THIS_IMAGE()
11387 IF (THIS_IMAGE() == 1) THEN
11388 DO i = 1, NUM_IMAGES()
11389 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
11394 @item @emph{See also}:
11395 @ref{THIS_IMAGE}, @gol
11402 @section @code{OR} --- Bitwise logical OR
11404 @cindex bitwise logical or
11405 @cindex logical or, bitwise
11408 @item @emph{Description}:
11409 Bitwise logical @code{OR}.
11411 This intrinsic routine is provided for backwards compatibility with
11412 GNU Fortran 77. For integer arguments, programmers should consider
11413 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
11415 @item @emph{Standard}:
11418 @item @emph{Class}:
11421 @item @emph{Syntax}:
11422 @code{RESULT = OR(I, J)}
11424 @item @emph{Arguments}:
11425 @multitable @columnfractions .15 .70
11426 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
11427 type or a scalar @code{LOGICAL} type or a boz-literal-constant.
11428 @item @var{J} @tab The type shall be the same as the type of @var{I} or
11429 a boz-literal-constant. @var{I} and @var{J} shall not both be
11430 boz-literal-constants. If either @var{I} and @var{J} is a
11431 boz-literal-constant, then the other argument must be a scalar @code{INTEGER}.
11434 @item @emph{Return value}:
11435 The return type is either a scalar @code{INTEGER} or a scalar
11436 @code{LOGICAL}. If the kind type parameters differ, then the
11437 smaller kind type is implicitly converted to larger kind, and the
11438 return has the larger kind. A boz-literal-constant is
11439 converted to an @code{INTEGER} with the kind type parameter of
11440 the other argument as-if a call to @ref{INT} occurred.
11442 @item @emph{Example}:
11445 LOGICAL :: T = .TRUE., F = .FALSE.
11447 DATA a / Z'F' /, b / Z'3' /
11449 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
11450 WRITE (*,*) OR(a, b)
11454 @item @emph{See also}:
11455 Fortran 95 elemental function: @gol
11462 @section @code{PACK} --- Pack an array into an array of rank one
11464 @cindex array, packing
11465 @cindex array, reduce dimension
11466 @cindex array, gather elements
11469 @item @emph{Description}:
11470 Stores the elements of @var{ARRAY} in an array of rank one.
11472 The beginning of the resulting array is made up of elements whose @var{MASK}
11473 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
11476 @item @emph{Standard}:
11477 Fortran 90 and later
11479 @item @emph{Class}:
11480 Transformational function
11482 @item @emph{Syntax}:
11483 @code{RESULT = PACK(ARRAY, MASK[,VECTOR])}
11485 @item @emph{Arguments}:
11486 @multitable @columnfractions .15 .70
11487 @item @var{ARRAY} @tab Shall be an array of any type.
11488 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
11489 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
11491 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
11492 as @var{ARRAY} and of rank one. If present, the number of elements in
11493 @var{VECTOR} shall be equal to or greater than the number of true elements
11494 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
11495 @var{VECTOR} shall be equal to or greater than the number of elements in
11499 @item @emph{Return value}:
11500 The result is an array of rank one and the same type as that of @var{ARRAY}.
11501 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
11502 number of @code{TRUE} values in @var{MASK} otherwise.
11504 @item @emph{Example}:
11505 Gathering nonzero elements from an array:
11507 PROGRAM test_pack_1
11509 m = (/ 1, 0, 0, 0, 5, 0 /)
11510 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
11514 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
11516 PROGRAM test_pack_2
11518 m = (/ 1, 0, 0, 2 /)
11519 ! The following results in "1 2 3 4"
11520 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /))
11524 @item @emph{See also}:
11531 @section @code{PARITY} --- Reduction with exclusive OR
11534 @cindex Reduction, XOR
11535 @cindex XOR reduction
11538 @item @emph{Description}:
11539 Calculates the parity, i.e. the reduction using @code{.XOR.},
11540 of @var{MASK} along dimension @var{DIM}.
11542 @item @emph{Standard}:
11543 Fortran 2008 and later
11545 @item @emph{Class}:
11546 Transformational function
11548 @item @emph{Syntax}:
11549 @multitable @columnfractions .80
11550 @item @code{RESULT = PARITY(MASK[, DIM])}
11553 @item @emph{Arguments}:
11554 @multitable @columnfractions .15 .70
11555 @item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL}
11556 @item @var{DIM} @tab (Optional) shall be a scalar of type
11557 @code{INTEGER} with a value in the range from 1 to n, where n
11558 equals the rank of @var{MASK}.
11561 @item @emph{Return value}:
11562 The result is of the same type as @var{MASK}.
11564 If @var{DIM} is absent, a scalar with the parity of all elements in
11565 @var{MASK} is returned, i.e. true if an odd number of elements is
11566 @code{.true.} and false otherwise. If @var{DIM} is present, an array
11567 of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
11568 and a shape similar to that of @var{MASK} with dimension @var{DIM}
11569 dropped is returned.
11571 @item @emph{Example}:
11574 LOGICAL :: x(2) = [ .true., .false. ]
11575 print *, PARITY(x) ! prints "T" (true).
11583 @section @code{PERROR} --- Print system error message
11585 @cindex system, error handling
11588 @item @emph{Description}:
11589 Prints (on the C @code{stderr} stream) a newline-terminated error
11590 message corresponding to the last system error. This is prefixed by
11591 @var{STRING}, a colon and a space. See @code{perror(3)}.
11593 @item @emph{Standard}:
11596 @item @emph{Class}:
11599 @item @emph{Syntax}:
11600 @code{CALL PERROR(STRING)}
11602 @item @emph{Arguments}:
11603 @multitable @columnfractions .15 .70
11604 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
11608 @item @emph{See also}:
11615 @section @code{POPCNT} --- Number of bits set
11617 @cindex binary representation
11621 @item @emph{Description}:
11622 @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
11623 representation of @code{I}.
11625 @item @emph{Standard}:
11626 Fortran 2008 and later
11628 @item @emph{Class}:
11631 @item @emph{Syntax}:
11632 @code{RESULT = POPCNT(I)}
11634 @item @emph{Arguments}:
11635 @multitable @columnfractions .15 .70
11636 @item @var{I} @tab Shall be of type @code{INTEGER}.
11639 @item @emph{Return value}:
11640 The return value is of type @code{INTEGER} and of the default integer
11643 @item @emph{Example}:
11645 program test_population
11646 print *, popcnt(127), poppar(127)
11647 print *, popcnt(huge(0_4)), poppar(huge(0_4))
11648 print *, popcnt(huge(0_8)), poppar(huge(0_8))
11649 end program test_population
11651 @item @emph{See also}:
11660 @section @code{POPPAR} --- Parity of the number of bits set
11662 @cindex binary representation
11666 @item @emph{Description}:
11667 @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
11668 of the number of bits set ('1' bits) in the binary representation of
11669 @code{I}. It is equal to 0 if @code{I} has an even number of bits set,
11670 and 1 for an odd number of '1' bits.
11672 @item @emph{Standard}:
11673 Fortran 2008 and later
11675 @item @emph{Class}:
11678 @item @emph{Syntax}:
11679 @code{RESULT = POPPAR(I)}
11681 @item @emph{Arguments}:
11682 @multitable @columnfractions .15 .70
11683 @item @var{I} @tab Shall be of type @code{INTEGER}.
11686 @item @emph{Return value}:
11687 The return value is of type @code{INTEGER} and of the default integer
11690 @item @emph{Example}:
11692 program test_population
11693 print *, popcnt(127), poppar(127)
11694 print *, popcnt(huge(0_4)), poppar(huge(0_4))
11695 print *, popcnt(huge(0_8)), poppar(huge(0_8))
11696 end program test_population
11698 @item @emph{See also}:
11707 @section @code{PRECISION} --- Decimal precision of a real kind
11709 @cindex model representation, precision
11712 @item @emph{Description}:
11713 @code{PRECISION(X)} returns the decimal precision in the model of the
11716 @item @emph{Standard}:
11717 Fortran 90 and later
11719 @item @emph{Class}:
11722 @item @emph{Syntax}:
11723 @code{RESULT = PRECISION(X)}
11725 @item @emph{Arguments}:
11726 @multitable @columnfractions .15 .70
11727 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}. It may
11728 be scalar or valued.
11731 @item @emph{Return value}:
11732 The return value is of type @code{INTEGER} and of the default integer
11735 @item @emph{Example}:
11737 program prec_and_range
11738 real(kind=4) :: x(2)
11739 complex(kind=8) :: y
11741 print *, precision(x), range(x)
11742 print *, precision(y), range(y)
11743 end program prec_and_range
11745 @item @emph{See also}:
11746 @ref{SELECTED_REAL_KIND}, @gol
11753 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
11757 @item @emph{Description}:
11758 Determines whether an optional dummy argument is present.
11760 @item @emph{Standard}:
11761 Fortran 90 and later
11763 @item @emph{Class}:
11766 @item @emph{Syntax}:
11767 @code{RESULT = PRESENT(A)}
11769 @item @emph{Arguments}:
11770 @multitable @columnfractions .15 .70
11771 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
11772 value, or a dummy procedure. It shall be the name of an optional dummy argument
11773 accessible within the current subroutine or function.
11776 @item @emph{Return value}:
11777 Returns either @code{TRUE} if the optional argument @var{A} is present, or
11778 @code{FALSE} otherwise.
11780 @item @emph{Example}:
11782 PROGRAM test_present
11783 WRITE(*,*) f(), f(42) ! "F T"
11785 LOGICAL FUNCTION f(x)
11786 INTEGER, INTENT(IN), OPTIONAL :: x
11796 @section @code{PRODUCT} --- Product of array elements
11798 @cindex array, product
11799 @cindex array, multiply elements
11800 @cindex array, conditionally multiply elements
11801 @cindex multiply array elements
11804 @item @emph{Description}:
11805 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
11806 the corresponding element in @var{MASK} is @code{TRUE}.
11808 @item @emph{Standard}:
11809 Fortran 90 and later
11811 @item @emph{Class}:
11812 Transformational function
11814 @item @emph{Syntax}:
11815 @multitable @columnfractions .80
11816 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
11817 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
11820 @item @emph{Arguments}:
11821 @multitable @columnfractions .15 .70
11822 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
11823 @code{REAL} or @code{COMPLEX}.
11824 @item @var{DIM} @tab (Optional) shall be a scalar of type
11825 @code{INTEGER} with a value in the range from 1 to n, where n
11826 equals the rank of @var{ARRAY}.
11827 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
11828 and either be a scalar or an array of the same shape as @var{ARRAY}.
11831 @item @emph{Return value}:
11832 The result is of the same type as @var{ARRAY}.
11834 If @var{DIM} is absent, a scalar with the product of all elements in
11835 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
11836 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
11837 dimension @var{DIM} dropped is returned.
11840 @item @emph{Example}:
11842 PROGRAM test_product
11843 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
11844 print *, PRODUCT(x) ! all elements, product = 120
11845 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
11849 @item @emph{See also}:
11856 @section @code{RADIX} --- Base of a model number
11858 @cindex model representation, base
11859 @cindex model representation, radix
11862 @item @emph{Description}:
11863 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
11865 @item @emph{Standard}:
11866 Fortran 90 and later
11868 @item @emph{Class}:
11871 @item @emph{Syntax}:
11872 @code{RESULT = RADIX(X)}
11874 @item @emph{Arguments}:
11875 @multitable @columnfractions .15 .70
11876 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
11879 @item @emph{Return value}:
11880 The return value is a scalar of type @code{INTEGER} and of the default
11883 @item @emph{Example}:
11886 print *, "The radix for the default integer kind is", radix(0)
11887 print *, "The radix for the default real kind is", radix(0.0)
11888 end program test_radix
11890 @item @emph{See also}:
11891 @ref{SELECTED_REAL_KIND}
11897 @section @code{RAN} --- Real pseudo-random number
11899 @cindex random number generation
11902 @item @emph{Description}:
11903 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
11904 provided as an alias for @code{RAND}. See @ref{RAND} for complete
11907 @item @emph{Standard}:
11910 @item @emph{Class}:
11913 @item @emph{See also}:
11915 @ref{RANDOM_NUMBER}
11921 @section @code{RAND} --- Real pseudo-random number
11923 @cindex random number generation
11926 @item @emph{Description}:
11927 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
11928 distribution between 0 and 1. If @var{FLAG} is 0, the next number
11929 in the current sequence is returned; if @var{FLAG} is 1, the generator
11930 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
11931 it is used as a new seed with @code{SRAND}.
11933 This intrinsic routine is provided for backwards compatibility with
11934 GNU Fortran 77. It implements a simple modulo generator as provided
11935 by @command{g77}. For new code, one should consider the use of
11936 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
11938 @item @emph{Standard}:
11941 @item @emph{Class}:
11944 @item @emph{Syntax}:
11945 @code{RESULT = RAND(I)}
11947 @item @emph{Arguments}:
11948 @multitable @columnfractions .15 .70
11949 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
11952 @item @emph{Return value}:
11953 The return value is of @code{REAL} type and the default kind.
11955 @item @emph{Example}:
11958 integer,parameter :: seed = 86456
11961 print *, rand(), rand(), rand(), rand()
11962 print *, rand(seed), rand(), rand(), rand()
11963 end program test_rand
11966 @item @emph{See also}:
11968 @ref{RANDOM_NUMBER}
11974 @section @code{RANDOM_INIT} --- Initialize a pseudo-random number generator
11975 @fnindex RANDOM_INIT
11976 @cindex random number generation, initialization
11979 @item @emph{Description}:
11980 Initializes the state of the pseudorandom number generator used by
11981 @code{RANDOM_NUMBER}.
11983 @item @emph{Standard}:
11986 @item @emph{Class}:
11989 @item @emph{Syntax}:
11990 @code{CALL RANDOM_INIT(REPEATABLE, IMAGE_DISTINCT)}
11992 @item @emph{Arguments}:
11993 @multitable @columnfractions .25 .70
11994 @item @var{REPEATABLE} @tab Shall be a scalar with a @code{LOGICAL} type,
11995 and it is @code{INTENT(IN)}. If it is @code{.true.}, the seed is set to
11996 a processor-dependent value that is the same each time @code{RANDOM_INIT}
11997 is called from the same image. The term ``same image'' means a single
11998 instance of program execution. The sequence of random numbers is different
11999 for repeated execution of the program. If it is @code{.false.}, the seed
12000 is set to a processor-dependent value.
12001 @item @var{IMAGE_DISTINCT} @tab Shall be a scalar with a
12002 @code{LOGICAL} type, and it is @code{INTENT(IN)}. If it is @code{.true.},
12003 the seed is set to a processor-dependent value that is distinct from th
12004 seed set by a call to @code{RANDOM_INIT} in another image. If it is
12005 @code{.false.}, the seed is set value that does depend which image called
12006 @code{RANDOM_INIT}.
12009 @item @emph{Example}:
12011 program test_random_seed
12014 call random_init(.true., .true.)
12015 call random_number(x)
12016 call random_init(.true., .true.)
12017 call random_number(y)
12018 ! x and y are the same sequence
12019 if (any(x /= y)) call abort
12020 end program test_random_seed
12023 @item @emph{See also}:
12024 @ref{RANDOM_NUMBER}, @gol
12029 @node RANDOM_NUMBER
12030 @section @code{RANDOM_NUMBER} --- Pseudo-random number
12031 @fnindex RANDOM_NUMBER
12032 @cindex random number generation
12035 @item @emph{Description}:
12036 Returns a single pseudorandom number or an array of pseudorandom numbers
12037 from the uniform distribution over the range @math{ 0 \leq x < 1}.
12039 The runtime-library implements the xoshiro256** pseudorandom number
12040 generator (PRNG). This generator has a period of @math{2^{256} - 1},
12041 and when using multiple threads up to @math{2^{128}} threads can each
12042 generate @math{2^{128}} random numbers before any aliasing occurs.
12044 Note that in a multi-threaded program (e.g. using OpenMP directives),
12045 each thread will have its own random number state. For details of the
12046 seeding procedure, see the documentation for the @code{RANDOM_SEED}
12050 @item @emph{Standard}:
12051 Fortran 90 and later
12053 @item @emph{Class}:
12056 @item @emph{Syntax}:
12057 @code{RANDOM_NUMBER(HARVEST)}
12059 @item @emph{Arguments}:
12060 @multitable @columnfractions .15 .70
12061 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
12064 @item @emph{Example}:
12066 program test_random_number
12068 CALL RANDOM_NUMBER(r)
12072 @item @emph{See also}:
12073 @ref{RANDOM_SEED}, @gol
12080 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
12081 @fnindex RANDOM_SEED
12082 @cindex random number generation, seeding
12083 @cindex seeding a random number generator
12086 @item @emph{Description}:
12087 Restarts or queries the state of the pseudorandom number generator used by
12088 @code{RANDOM_NUMBER}.
12090 If @code{RANDOM_SEED} is called without arguments, it is seeded with
12091 random data retrieved from the operating system.
12093 As an extension to the Fortran standard, the GFortran
12094 @code{RANDOM_NUMBER} supports multiple threads. Each thread in a
12095 multi-threaded program has its own seed. When @code{RANDOM_SEED} is
12096 called either without arguments or with the @var{PUT} argument, the
12097 given seed is copied into a master seed as well as the seed of the
12098 current thread. When a new thread uses @code{RANDOM_NUMBER} for the
12099 first time, the seed is copied from the master seed, and forwarded
12100 @math{N * 2^{128}} steps to guarantee that the random stream does not
12101 alias any other stream in the system, where @var{N} is the number of
12102 threads that have used @code{RANDOM_NUMBER} so far during the program
12105 @item @emph{Standard}:
12106 Fortran 90 and later
12108 @item @emph{Class}:
12111 @item @emph{Syntax}:
12112 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
12114 @item @emph{Arguments}:
12115 @multitable @columnfractions .15 .70
12116 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
12117 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
12118 of the arrays used with the @var{PUT} and @var{GET} arguments.
12119 @item @var{PUT} @tab (Optional) Shall be an array of type default
12120 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
12121 the array must be larger than or equal to the number returned by the
12122 @var{SIZE} argument.
12123 @item @var{GET} @tab (Optional) Shall be an array of type default
12124 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
12125 of the array must be larger than or equal to the number returned by
12126 the @var{SIZE} argument.
12129 @item @emph{Example}:
12131 program test_random_seed
12133 integer, allocatable :: seed(:)
12136 call random_seed(size = n)
12138 call random_seed(get=seed)
12140 end program test_random_seed
12143 @item @emph{See also}:
12144 @ref{RANDOM_NUMBER}, @gol
12151 @section @code{RANGE} --- Decimal exponent range
12153 @cindex model representation, range
12156 @item @emph{Description}:
12157 @code{RANGE(X)} returns the decimal exponent range in the model of the
12160 @item @emph{Standard}:
12161 Fortran 90 and later
12163 @item @emph{Class}:
12166 @item @emph{Syntax}:
12167 @code{RESULT = RANGE(X)}
12169 @item @emph{Arguments}:
12170 @multitable @columnfractions .15 .70
12171 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
12175 @item @emph{Return value}:
12176 The return value is of type @code{INTEGER} and of the default integer
12179 @item @emph{Example}:
12180 See @code{PRECISION} for an example.
12181 @item @emph{See also}:
12182 @ref{SELECTED_REAL_KIND}, @gol
12189 @section @code{RANK} --- Rank of a data object
12194 @item @emph{Description}:
12195 @code{RANK(A)} returns the rank of a scalar or array data object.
12197 @item @emph{Standard}:
12198 Technical Specification (TS) 29113
12200 @item @emph{Class}:
12203 @item @emph{Syntax}:
12204 @code{RESULT = RANK(A)}
12206 @item @emph{Arguments}:
12207 @multitable @columnfractions .15 .70
12208 @item @var{A} @tab can be of any type
12211 @item @emph{Return value}:
12212 The return value is of type @code{INTEGER} and of the default integer
12213 kind. For arrays, their rank is returned; for scalars zero is returned.
12215 @item @emph{Example}:
12219 real, allocatable :: b(:,:)
12221 print *, rank(a), rank(b) ! Prints: 0 2
12222 end program test_rank
12230 @section @code{REAL} --- Convert to real type
12239 @cindex conversion, to real
12240 @cindex complex numbers, real part
12243 @item @emph{Description}:
12244 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
12245 @code{REALPART} function is provided for compatibility with @command{g77},
12246 and its use is strongly discouraged.
12248 @item @emph{Standard}:
12249 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later, has GNU extensions
12251 @item @emph{Class}:
12254 @item @emph{Syntax}:
12255 @multitable @columnfractions .80
12256 @item @code{RESULT = REAL(A [, KIND])}
12257 @item @code{RESULT = REALPART(Z)}
12260 @item @emph{Arguments}:
12261 @multitable @columnfractions .15 .70
12262 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
12264 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12265 expression indicating the kind parameter of the result.
12268 @item @emph{Return value}:
12269 These functions return a @code{REAL} variable or array under
12270 the following rules:
12274 @code{REAL(A)} is converted to a default real type if @var{A} is an
12275 integer or real variable.
12277 @code{REAL(A)} is converted to a real type with the kind type parameter
12278 of @var{A} if @var{A} is a complex variable.
12280 @code{REAL(A, KIND)} is converted to a real type with kind type
12281 parameter @var{KIND} if @var{A} is a complex, integer, or real
12285 @item @emph{Example}:
12288 complex :: x = (1.0, 2.0)
12289 print *, real(x), real(x,8), realpart(x)
12290 end program test_real
12293 @item @emph{Specific names}:
12294 @multitable @columnfractions .20 .20 .20 .25
12295 @item Name @tab Argument @tab Return type @tab Standard
12296 @item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab GNU extension
12297 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension
12298 @item @code{FLOATI(A)} @tab @code{INTEGER(2)} @tab @code{REAL(4)} @tab GNU extension
12299 @item @code{FLOATJ(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab GNU extension
12300 @item @code{FLOATK(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab GNU extension
12301 @item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab GNU extension
12305 @item @emph{See also}:
12313 @section @code{RENAME} --- Rename a file
12315 @cindex file system, rename file
12318 @item @emph{Description}:
12319 Renames a file from file @var{PATH1} to @var{PATH2}. A null
12320 character (@code{CHAR(0)}) can be used to mark the end of the names in
12321 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
12322 names are ignored. If the @var{STATUS} argument is supplied, it
12323 contains 0 on success or a nonzero error code upon return; see
12326 This intrinsic is provided in both subroutine and function forms;
12327 however, only one form can be used in any given program unit.
12329 @item @emph{Standard}:
12332 @item @emph{Class}:
12333 Subroutine, function
12335 @item @emph{Syntax}:
12336 @multitable @columnfractions .80
12337 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
12338 @item @code{STATUS = RENAME(PATH1, PATH2)}
12341 @item @emph{Arguments}:
12342 @multitable @columnfractions .15 .70
12343 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
12344 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
12345 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12348 @item @emph{See also}:
12356 @section @code{REPEAT} --- Repeated string concatenation
12358 @cindex string, repeat
12359 @cindex string, concatenate
12362 @item @emph{Description}:
12363 Concatenates @var{NCOPIES} copies of a string.
12365 @item @emph{Standard}:
12366 Fortran 90 and later
12368 @item @emph{Class}:
12369 Transformational function
12371 @item @emph{Syntax}:
12372 @code{RESULT = REPEAT(STRING, NCOPIES)}
12374 @item @emph{Arguments}:
12375 @multitable @columnfractions .15 .70
12376 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
12377 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
12380 @item @emph{Return value}:
12381 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
12384 @item @emph{Example}:
12386 program test_repeat
12387 write(*,*) repeat("x", 5) ! "xxxxx"
12395 @section @code{RESHAPE} --- Function to reshape an array
12397 @cindex array, change dimensions
12398 @cindex array, transmogrify
12401 @item @emph{Description}:
12402 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
12403 the new array may be padded with elements from @var{PAD} or permuted
12404 as defined by @var{ORDER}.
12406 @item @emph{Standard}:
12407 Fortran 90 and later
12409 @item @emph{Class}:
12410 Transformational function
12412 @item @emph{Syntax}:
12413 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
12415 @item @emph{Arguments}:
12416 @multitable @columnfractions .15 .70
12417 @item @var{SOURCE} @tab Shall be an array of any type.
12418 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
12419 array of rank one. Its values must be positive or zero.
12420 @item @var{PAD} @tab (Optional) shall be an array of the same
12421 type as @var{SOURCE}.
12422 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
12423 and an array of the same shape as @var{SHAPE}. Its values shall
12424 be a permutation of the numbers from 1 to n, where n is the size of
12425 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
12429 @item @emph{Return value}:
12430 The result is an array of shape @var{SHAPE} with the same type as
12433 @item @emph{Example}:
12435 PROGRAM test_reshape
12436 INTEGER, DIMENSION(4) :: x
12437 WRITE(*,*) SHAPE(x) ! prints "4"
12438 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
12442 @item @emph{See also}:
12449 @section @code{RRSPACING} --- Reciprocal of the relative spacing
12451 @cindex real number, relative spacing
12452 @cindex floating point, relative spacing
12456 @item @emph{Description}:
12457 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
12458 model numbers near @var{X}.
12460 @item @emph{Standard}:
12461 Fortran 90 and later
12463 @item @emph{Class}:
12466 @item @emph{Syntax}:
12467 @code{RESULT = RRSPACING(X)}
12469 @item @emph{Arguments}:
12470 @multitable @columnfractions .15 .70
12471 @item @var{X} @tab Shall be of type @code{REAL}.
12474 @item @emph{Return value}:
12475 The return value is of the same type and kind as @var{X}.
12476 The value returned is equal to
12477 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
12479 @item @emph{See also}:
12486 @section @code{RSHIFT} --- Right shift bits
12488 @cindex bits, shift right
12491 @item @emph{Description}:
12492 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
12493 bits shifted right by @var{SHIFT} places. @var{SHIFT} shall be
12494 nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
12495 the result value is undefined. Bits shifted out from the right end
12496 are lost. The fill is arithmetic: the bits shifted in from the left
12497 end are equal to the leftmost bit, which in two's complement
12498 representation is the sign bit.
12500 This function has been superseded by the @code{SHIFTA} intrinsic, which
12501 is standard in Fortran 2008 and later.
12503 @item @emph{Standard}:
12506 @item @emph{Class}:
12509 @item @emph{Syntax}:
12510 @code{RESULT = RSHIFT(I, SHIFT)}
12512 @item @emph{Arguments}:
12513 @multitable @columnfractions .15 .70
12514 @item @var{I} @tab The type shall be @code{INTEGER}.
12515 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12518 @item @emph{Return value}:
12519 The return value is of type @code{INTEGER} and of the same kind as
12522 @item @emph{See also}:
12535 @section @code{SAME_TYPE_AS} --- Query dynamic types for equality
12536 @fnindex SAME_TYPE_AS
12539 @item @emph{Description}:
12540 Query dynamic types for equality.
12542 @item @emph{Standard}:
12543 Fortran 2003 and later
12545 @item @emph{Class}:
12548 @item @emph{Syntax}:
12549 @code{RESULT = SAME_TYPE_AS(A, B)}
12551 @item @emph{Arguments}:
12552 @multitable @columnfractions .15 .70
12553 @item @var{A} @tab Shall be an object of extensible declared type or
12554 unlimited polymorphic.
12555 @item @var{B} @tab Shall be an object of extensible declared type or
12556 unlimited polymorphic.
12559 @item @emph{Return value}:
12560 The return value is a scalar of type default logical. It is true if and
12561 only if the dynamic type of A is the same as the dynamic type of B.
12563 @item @emph{See also}:
12564 @ref{EXTENDS_TYPE_OF}
12571 @section @code{SCALE} --- Scale a real value
12573 @cindex real number, scale
12574 @cindex floating point, scale
12577 @item @emph{Description}:
12578 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
12580 @item @emph{Standard}:
12581 Fortran 90 and later
12583 @item @emph{Class}:
12586 @item @emph{Syntax}:
12587 @code{RESULT = SCALE(X, I)}
12589 @item @emph{Arguments}:
12590 @multitable @columnfractions .15 .70
12591 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
12592 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
12595 @item @emph{Return value}:
12596 The return value is of the same type and kind as @var{X}.
12597 Its value is @code{X * RADIX(X)**I}.
12599 @item @emph{Example}:
12602 real :: x = 178.1387e-4
12604 print *, scale(x,i), x*radix(x)**i
12605 end program test_scale
12613 @section @code{SCAN} --- Scan a string for the presence of a set of characters
12615 @cindex string, find subset
12618 @item @emph{Description}:
12619 Scans a @var{STRING} for any of the characters in a @var{SET}
12622 If @var{BACK} is either absent or equals @code{FALSE}, this function
12623 returns the position of the leftmost character of @var{STRING} that is
12624 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
12625 is returned. If no character of @var{SET} is found in @var{STRING}, the
12628 @item @emph{Standard}:
12629 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
12631 @item @emph{Class}:
12634 @item @emph{Syntax}:
12635 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
12637 @item @emph{Arguments}:
12638 @multitable @columnfractions .15 .70
12639 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
12640 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
12641 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
12642 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12643 expression indicating the kind parameter of the result.
12646 @item @emph{Return value}:
12647 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12648 @var{KIND} is absent, the return value is of default integer kind.
12650 @item @emph{Example}:
12653 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
12654 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
12655 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
12659 @item @emph{See also}:
12660 @ref{INDEX intrinsic}, @gol
12667 @section @code{SECNDS} --- Time function
12669 @cindex time, elapsed
12670 @cindex elapsed time
12673 @item @emph{Description}:
12674 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
12675 @var{X} is a reference time, also in seconds. If this is zero, the time in
12676 seconds from midnight is returned. This function is non-standard and its
12677 use is discouraged.
12679 @item @emph{Standard}:
12682 @item @emph{Class}:
12685 @item @emph{Syntax}:
12686 @code{RESULT = SECNDS (X)}
12688 @item @emph{Arguments}:
12689 @multitable @columnfractions .15 .70
12690 @item @var{T} @tab Shall be of type @code{REAL(4)}.
12691 @item @var{X} @tab Shall be of type @code{REAL(4)}.
12694 @item @emph{Return value}:
12697 @item @emph{Example}:
12699 program test_secnds
12702 print *, secnds (0.0) ! seconds since midnight
12703 t1 = secnds (0.0) ! reference time
12704 do i = 1, 10000000 ! do something
12706 t2 = secnds (t1) ! elapsed time
12707 print *, "Something took ", t2, " seconds."
12708 end program test_secnds
12715 @section @code{SECOND} --- CPU time function
12717 @cindex time, elapsed
12718 @cindex elapsed time
12721 @item @emph{Description}:
12722 Returns a @code{REAL(4)} value representing the elapsed CPU time in
12723 seconds. This provides the same functionality as the standard
12724 @code{CPU_TIME} intrinsic, and is only included for backwards
12727 This intrinsic is provided in both subroutine and function forms;
12728 however, only one form can be used in any given program unit.
12730 @item @emph{Standard}:
12733 @item @emph{Class}:
12734 Subroutine, function
12736 @item @emph{Syntax}:
12737 @multitable @columnfractions .80
12738 @item @code{CALL SECOND(TIME)}
12739 @item @code{TIME = SECOND()}
12742 @item @emph{Arguments}:
12743 @multitable @columnfractions .15 .70
12744 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
12747 @item @emph{Return value}:
12748 In either syntax, @var{TIME} is set to the process's current runtime in
12751 @item @emph{See also}:
12758 @node SELECTED_CHAR_KIND
12759 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
12760 @fnindex SELECTED_CHAR_KIND
12761 @cindex character kind
12762 @cindex kind, character
12765 @item @emph{Description}:
12767 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
12768 set named @var{NAME}, if a character set with such a name is supported,
12769 or @math{-1} otherwise. Currently, supported character sets include
12770 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
12771 (Universal Character Set, UCS-4) which is commonly known as Unicode.
12773 @item @emph{Standard}:
12774 Fortran 2003 and later
12776 @item @emph{Class}:
12777 Transformational function
12779 @item @emph{Syntax}:
12780 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
12782 @item @emph{Arguments}:
12783 @multitable @columnfractions .15 .70
12784 @item @var{NAME} @tab Shall be a scalar and of the default character type.
12787 @item @emph{Example}:
12789 program character_kind
12790 use iso_fortran_env
12792 integer, parameter :: ascii = selected_char_kind ("ascii")
12793 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646')
12795 character(kind=ascii, len=26) :: alphabet
12796 character(kind=ucs4, len=30) :: hello_world
12798 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
12799 hello_world = ucs4_'Hello World and Ni Hao -- ' &
12800 // char (int (z'4F60'), ucs4) &
12801 // char (int (z'597D'), ucs4)
12803 write (*,*) alphabet
12805 open (output_unit, encoding='UTF-8')
12806 write (*,*) trim (hello_world)
12807 end program character_kind
12813 @node SELECTED_INT_KIND
12814 @section @code{SELECTED_INT_KIND} --- Choose integer kind
12815 @fnindex SELECTED_INT_KIND
12816 @cindex integer kind
12817 @cindex kind, integer
12820 @item @emph{Description}:
12821 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
12822 type that can represent all values ranging from @math{-10^R} (exclusive)
12823 to @math{10^R} (exclusive). If there is no integer kind that accommodates
12824 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
12826 @item @emph{Standard}:
12827 Fortran 90 and later
12829 @item @emph{Class}:
12830 Transformational function
12832 @item @emph{Syntax}:
12833 @code{RESULT = SELECTED_INT_KIND(R)}
12835 @item @emph{Arguments}:
12836 @multitable @columnfractions .15 .70
12837 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
12840 @item @emph{Example}:
12842 program large_integers
12843 integer,parameter :: k5 = selected_int_kind(5)
12844 integer,parameter :: k15 = selected_int_kind(15)
12845 integer(kind=k5) :: i5
12846 integer(kind=k15) :: i15
12848 print *, huge(i5), huge(i15)
12850 ! The following inequalities are always true
12851 print *, huge(i5) >= 10_k5**5-1
12852 print *, huge(i15) >= 10_k15**15-1
12853 end program large_integers
12859 @node SELECTED_REAL_KIND
12860 @section @code{SELECTED_REAL_KIND} --- Choose real kind
12861 @fnindex SELECTED_REAL_KIND
12864 @cindex radix, real
12867 @item @emph{Description}:
12868 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
12869 with decimal precision of at least @code{P} digits, exponent range of
12870 at least @code{R}, and with a radix of @code{RADIX}.
12872 @item @emph{Standard}:
12873 Fortran 90 and later, with @code{RADIX} Fortran 2008 or later
12875 @item @emph{Class}:
12876 Transformational function
12878 @item @emph{Syntax}:
12879 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
12881 @item @emph{Arguments}:
12882 @multitable @columnfractions .15 .70
12883 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12884 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12885 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12887 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
12888 be present; since Fortran 2008, they are assumed to be zero if absent.
12890 @item @emph{Return value}:
12892 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
12893 a real data type with decimal precision of at least @code{P} digits, a
12894 decimal exponent range of at least @code{R}, and with the requested
12895 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
12896 any radix can be returned. If more than one real data type meet the
12897 criteria, the kind of the data type with the smallest decimal precision
12898 is returned. If no real data type matches the criteria, the result is
12900 @item -1 if the processor does not support a real data type with a
12901 precision greater than or equal to @code{P}, but the @code{R} and
12902 @code{RADIX} requirements can be fulfilled
12903 @item -2 if the processor does not support a real type with an exponent
12904 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
12906 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
12908 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
12910 @item -5 if there is no real type with the given @code{RADIX}
12913 @item @emph{Example}:
12916 integer,parameter :: p6 = selected_real_kind(6)
12917 integer,parameter :: p10r100 = selected_real_kind(10,100)
12918 integer,parameter :: r400 = selected_real_kind(r=400)
12920 real(kind=p10r100) :: y
12921 real(kind=r400) :: z
12923 print *, precision(x), range(x)
12924 print *, precision(y), range(y)
12925 print *, precision(z), range(z)
12926 end program real_kinds
12928 @item @emph{See also}:
12929 @ref{PRECISION}, @gol
12937 @section @code{SET_EXPONENT} --- Set the exponent of the model
12938 @fnindex SET_EXPONENT
12939 @cindex real number, set exponent
12940 @cindex floating point, set exponent
12943 @item @emph{Description}:
12944 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
12945 is that that of @var{X} and whose exponent part is @var{I}.
12947 @item @emph{Standard}:
12948 Fortran 90 and later
12950 @item @emph{Class}:
12953 @item @emph{Syntax}:
12954 @code{RESULT = SET_EXPONENT(X, I)}
12956 @item @emph{Arguments}:
12957 @multitable @columnfractions .15 .70
12958 @item @var{X} @tab Shall be of type @code{REAL}.
12959 @item @var{I} @tab Shall be of type @code{INTEGER}.
12962 @item @emph{Return value}:
12963 The return value is of the same type and kind as @var{X}.
12964 The real number whose fractional part
12965 is that that of @var{X} and whose exponent part if @var{I} is returned;
12966 it is @code{FRACTION(X) * RADIX(X)**I}.
12968 @item @emph{Example}:
12970 PROGRAM test_setexp
12971 REAL :: x = 178.1387e-4
12973 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
12982 @section @code{SHAPE} --- Determine the shape of an array
12984 @cindex array, shape
12987 @item @emph{Description}:
12988 Determines the shape of an array.
12990 @item @emph{Standard}:
12991 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
12993 @item @emph{Class}:
12996 @item @emph{Syntax}:
12997 @code{RESULT = SHAPE(SOURCE [, KIND])}
12999 @item @emph{Arguments}:
13000 @multitable @columnfractions .15 .70
13001 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
13002 If @var{SOURCE} is a pointer it must be associated and allocatable
13003 arrays must be allocated.
13004 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
13005 expression indicating the kind parameter of the result.
13008 @item @emph{Return value}:
13009 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
13010 has dimensions. The elements of the resulting array correspond to the extend
13011 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
13012 the result is the rank one array of size zero. If @var{KIND} is absent, the
13013 return value has the default integer kind otherwise the specified kind.
13015 @item @emph{Example}:
13018 INTEGER, DIMENSION(-1:1, -1:2) :: A
13019 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
13020 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
13024 @item @emph{See also}:
13025 @ref{RESHAPE}, @gol
13032 @section @code{SHIFTA} --- Right shift with fill
13034 @cindex bits, shift right
13035 @cindex shift, right with fill
13038 @item @emph{Description}:
13039 @code{SHIFTA} returns a value corresponding to @var{I} with all of the
13040 bits shifted right by @var{SHIFT} places. @var{SHIFT} that be
13041 nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
13042 the result value is undefined. Bits shifted out from the right end
13043 are lost. The fill is arithmetic: the bits shifted in from the left
13044 end are equal to the leftmost bit, which in two's complement
13045 representation is the sign bit.
13047 @item @emph{Standard}:
13048 Fortran 2008 and later
13050 @item @emph{Class}:
13053 @item @emph{Syntax}:
13054 @code{RESULT = SHIFTA(I, SHIFT)}
13056 @item @emph{Arguments}:
13057 @multitable @columnfractions .15 .70
13058 @item @var{I} @tab The type shall be @code{INTEGER}.
13059 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
13062 @item @emph{Return value}:
13063 The return value is of type @code{INTEGER} and of the same kind as
13066 @item @emph{See also}:
13074 @section @code{SHIFTL} --- Left shift
13076 @cindex bits, shift left
13077 @cindex shift, left
13080 @item @emph{Description}:
13081 @code{SHIFTL} returns a value corresponding to @var{I} with all of the
13082 bits shifted left by @var{SHIFT} places. @var{SHIFT} shall be
13083 nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
13084 the result value is undefined. Bits shifted out from the left end are
13085 lost, and bits shifted in from the right end are set to 0.
13087 @item @emph{Standard}:
13088 Fortran 2008 and later
13090 @item @emph{Class}:
13093 @item @emph{Syntax}:
13094 @code{RESULT = SHIFTL(I, SHIFT)}
13096 @item @emph{Arguments}:
13097 @multitable @columnfractions .15 .70
13098 @item @var{I} @tab The type shall be @code{INTEGER}.
13099 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
13102 @item @emph{Return value}:
13103 The return value is of type @code{INTEGER} and of the same kind as
13106 @item @emph{See also}:
13114 @section @code{SHIFTR} --- Right shift
13116 @cindex bits, shift right
13117 @cindex shift, right
13120 @item @emph{Description}:
13121 @code{SHIFTR} returns a value corresponding to @var{I} with all of the
13122 bits shifted right by @var{SHIFT} places. @var{SHIFT} shall be
13123 nonnegative and less than or equal to @code{BIT_SIZE(I)}, otherwise
13124 the result value is undefined. Bits shifted out from the right end
13125 are lost, and bits shifted in from the left end are set to 0.
13127 @item @emph{Standard}:
13128 Fortran 2008 and later
13130 @item @emph{Class}:
13133 @item @emph{Syntax}:
13134 @code{RESULT = SHIFTR(I, SHIFT)}
13136 @item @emph{Arguments}:
13137 @multitable @columnfractions .15 .70
13138 @item @var{I} @tab The type shall be @code{INTEGER}.
13139 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
13142 @item @emph{Return value}:
13143 The return value is of type @code{INTEGER} and of the same kind as
13146 @item @emph{See also}:
13154 @section @code{SIGN} --- Sign copying function
13158 @cindex sign copying
13161 @item @emph{Description}:
13162 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
13164 @item @emph{Standard}:
13165 Fortran 77 and later
13167 @item @emph{Class}:
13170 @item @emph{Syntax}:
13171 @code{RESULT = SIGN(A, B)}
13173 @item @emph{Arguments}:
13174 @multitable @columnfractions .15 .70
13175 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
13176 @item @var{B} @tab Shall be of the same type and kind as @var{A}.
13179 @item @emph{Return value}:
13180 The kind of the return value is that of @var{A} and @var{B}.
13181 If @math{B\ge 0} then the result is @code{ABS(A)}, else
13182 it is @code{-ABS(A)}.
13184 @item @emph{Example}:
13187 print *, sign(-12,1)
13188 print *, sign(-12,0)
13189 print *, sign(-12,-1)
13191 print *, sign(-12.,1.)
13192 print *, sign(-12.,0.)
13193 print *, sign(-12.,-1.)
13194 end program test_sign
13197 @item @emph{Specific names}:
13198 @multitable @columnfractions .20 .20 .20 .25
13199 @item Name @tab Arguments @tab Return type @tab Standard
13200 @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab Fortran 77 and later
13201 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab Fortran 77 and later
13202 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab Fortran 77 and later
13209 @section @code{SIGNAL} --- Signal handling subroutine (or function)
13211 @cindex system, signal handling
13214 @item @emph{Description}:
13215 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
13216 @var{HANDLER} to be executed with a single integer argument when signal
13217 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
13218 turn off handling of signal @var{NUMBER} or revert to its default
13219 action. See @code{signal(2)}.
13221 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
13222 is supplied, it is set to the value returned by @code{signal(2)}.
13224 @item @emph{Standard}:
13227 @item @emph{Class}:
13228 Subroutine, function
13230 @item @emph{Syntax}:
13231 @multitable @columnfractions .80
13232 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
13233 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
13236 @item @emph{Arguments}:
13237 @multitable @columnfractions .15 .70
13238 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
13239 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
13240 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
13241 @code{INTEGER}. It is @code{INTENT(IN)}.
13242 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
13243 integer. It has @code{INTENT(OUT)}.
13245 @c TODO: What should the interface of the handler be? Does it take arguments?
13247 @item @emph{Return value}:
13248 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
13250 @item @emph{Example}:
13252 program test_signal
13254 external handler_print
13256 call signal (12, handler_print)
13257 call signal (10, 1)
13260 end program test_signal
13267 @section @code{SIN} --- Sine function
13273 @cindex trigonometric function, sine
13277 @item @emph{Description}:
13278 @code{SIN(X)} computes the sine of @var{X}.
13280 @item @emph{Standard}:
13281 Fortran 77 and later
13283 @item @emph{Class}:
13286 @item @emph{Syntax}:
13287 @code{RESULT = SIN(X)}
13289 @item @emph{Arguments}:
13290 @multitable @columnfractions .15 .70
13291 @item @var{X} @tab The type shall be @code{REAL} or
13295 @item @emph{Return value}:
13296 The return value has same type and kind as @var{X}.
13298 @item @emph{Example}:
13303 end program test_sin
13306 @item @emph{Specific names}:
13307 @multitable @columnfractions .20 .20 .20 .25
13308 @item Name @tab Argument @tab Return type @tab Standard
13309 @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
13310 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
13311 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
13312 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13313 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13316 @item @emph{See also}:
13317 Inverse function: @gol
13319 Degrees function: @gol
13326 @section @code{SIND} --- Sine function, degrees
13332 @cindex trigonometric function, sine, degrees
13333 @cindex sine, degrees
13336 @item @emph{Description}:
13337 @code{SIND(X)} computes the sine of @var{X} in degrees.
13339 This function is for compatibility only and should be avoided in favor of
13340 standard constructs wherever possible.
13342 @item @emph{Standard}:
13343 GNU extension, enabled with @option{-fdec-math}.
13345 @item @emph{Class}:
13348 @item @emph{Syntax}:
13349 @code{RESULT = SIND(X)}
13351 @item @emph{Arguments}:
13352 @multitable @columnfractions .15 .70
13353 @item @var{X} @tab The type shall be @code{REAL} or
13357 @item @emph{Return value}:
13358 The return value has same type and kind as @var{X}, and its value is in degrees.
13360 @item @emph{Example}:
13365 end program test_sind
13368 @item @emph{Specific names}:
13369 @multitable @columnfractions .20 .20 .20 .25
13370 @item Name @tab Argument @tab Return type @tab Standard
13371 @item @code{SIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
13372 @item @code{DSIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
13373 @item @code{CSIND(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU extension
13374 @item @code{ZSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13375 @item @code{CDSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13378 @item @emph{See also}:
13379 Inverse function: @gol
13381 Radians function: @gol
13388 @section @code{SINH} --- Hyperbolic sine function
13391 @cindex hyperbolic sine
13392 @cindex hyperbolic function, sine
13393 @cindex sine, hyperbolic
13396 @item @emph{Description}:
13397 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
13399 @item @emph{Standard}:
13400 Fortran 90 and later, for a complex argument Fortran 2008 or later, has
13403 @item @emph{Class}:
13406 @item @emph{Syntax}:
13407 @code{RESULT = SINH(X)}
13409 @item @emph{Arguments}:
13410 @multitable @columnfractions .15 .70
13411 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13414 @item @emph{Return value}:
13415 The return value has same type and kind as @var{X}.
13417 @item @emph{Example}:
13420 real(8) :: x = - 1.0_8
13422 end program test_sinh
13425 @item @emph{Specific names}:
13426 @multitable @columnfractions .20 .20 .20 .25
13427 @item Name @tab Argument @tab Return type @tab Standard
13428 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 90 and later
13431 @item @emph{See also}:
13438 @section @code{SIZE} --- Determine the size of an array
13440 @cindex array, size
13441 @cindex array, number of elements
13442 @cindex array, count elements
13445 @item @emph{Description}:
13446 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
13447 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
13449 @item @emph{Standard}:
13450 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
13452 @item @emph{Class}:
13455 @item @emph{Syntax}:
13456 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
13458 @item @emph{Arguments}:
13459 @multitable @columnfractions .15 .70
13460 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
13461 a pointer it must be associated and allocatable arrays must be allocated.
13462 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
13463 and its value shall be in the range from 1 to n, where n equals the rank
13465 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
13466 expression indicating the kind parameter of the result.
13469 @item @emph{Return value}:
13470 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
13471 @var{KIND} is absent, the return value is of default integer kind.
13473 @item @emph{Example}:
13476 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
13480 @item @emph{See also}:
13487 @section @code{SIZEOF} --- Size in bytes of an expression
13489 @cindex expression size
13490 @cindex size of an expression
13493 @item @emph{Description}:
13494 @code{SIZEOF(X)} calculates the number of bytes of storage the
13495 expression @code{X} occupies.
13497 @item @emph{Standard}:
13500 @item @emph{Class}:
13503 @item @emph{Syntax}:
13504 @code{N = SIZEOF(X)}
13506 @item @emph{Arguments}:
13507 @multitable @columnfractions .15 .70
13508 @item @var{X} @tab The argument shall be of any type, rank or shape.
13511 @item @emph{Return value}:
13512 The return value is of type integer and of the system-dependent kind
13513 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
13514 number of bytes occupied by the argument. If the argument has the
13515 @code{POINTER} attribute, the number of bytes of the storage area pointed
13516 to is returned. If the argument is of a derived type with @code{POINTER}
13517 or @code{ALLOCATABLE} components, the return value does not account for
13518 the sizes of the data pointed to by these components. If the argument is
13519 polymorphic, the size according to the dynamic type is returned. The argument
13520 may not be a procedure or procedure pointer. Note that the code assumes for
13521 arrays that those are contiguous; for contiguous arrays, it returns the
13522 storage or an array element multiplied by the size of the array.
13524 @item @emph{Example}:
13528 print *, (sizeof(s)/sizeof(r) == 5)
13531 The example will print @code{.TRUE.} unless you are using a platform
13532 where default @code{REAL} variables are unusually padded.
13534 @item @emph{See also}:
13535 @ref{C_SIZEOF}, @gol
13541 @section @code{SLEEP} --- Sleep for the specified number of seconds
13543 @cindex delayed execution
13546 @item @emph{Description}:
13547 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
13549 @item @emph{Standard}:
13552 @item @emph{Class}:
13555 @item @emph{Syntax}:
13556 @code{CALL SLEEP(SECONDS)}
13558 @item @emph{Arguments}:
13559 @multitable @columnfractions .15 .70
13560 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
13563 @item @emph{Example}:
13574 @section @code{SPACING} --- Smallest distance between two numbers of a given type
13576 @cindex real number, relative spacing
13577 @cindex floating point, relative spacing
13580 @item @emph{Description}:
13581 Determines the distance between the argument @var{X} and the nearest
13582 adjacent number of the same type.
13584 @item @emph{Standard}:
13585 Fortran 90 and later
13587 @item @emph{Class}:
13590 @item @emph{Syntax}:
13591 @code{RESULT = SPACING(X)}
13593 @item @emph{Arguments}:
13594 @multitable @columnfractions .15 .70
13595 @item @var{X} @tab Shall be of type @code{REAL}.
13598 @item @emph{Return value}:
13599 The result is of the same type as the input argument @var{X}.
13601 @item @emph{Example}:
13603 PROGRAM test_spacing
13604 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
13605 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
13607 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
13608 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
13612 @item @emph{See also}:
13619 @section @code{SPREAD} --- Add a dimension to an array
13621 @cindex array, increase dimension
13622 @cindex array, duplicate elements
13623 @cindex array, duplicate dimensions
13626 @item @emph{Description}:
13627 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
13628 dimension @var{DIM}.
13630 @item @emph{Standard}:
13631 Fortran 90 and later
13633 @item @emph{Class}:
13634 Transformational function
13636 @item @emph{Syntax}:
13637 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
13639 @item @emph{Arguments}:
13640 @multitable @columnfractions .15 .70
13641 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
13642 a rank less than seven.
13643 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
13644 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
13645 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
13648 @item @emph{Return value}:
13649 The result is an array of the same type as @var{SOURCE} and has rank n+1
13650 where n equals the rank of @var{SOURCE}.
13652 @item @emph{Example}:
13654 PROGRAM test_spread
13655 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
13656 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
13657 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
13661 @item @emph{See also}:
13668 @section @code{SQRT} --- Square-root function
13675 @cindex square-root
13678 @item @emph{Description}:
13679 @code{SQRT(X)} computes the square root of @var{X}.
13681 @item @emph{Standard}:
13682 Fortran 77 and later
13684 @item @emph{Class}:
13687 @item @emph{Syntax}:
13688 @code{RESULT = SQRT(X)}
13690 @item @emph{Arguments}:
13691 @multitable @columnfractions .15 .70
13692 @item @var{X} @tab The type shall be @code{REAL} or
13696 @item @emph{Return value}:
13697 The return value is of type @code{REAL} or @code{COMPLEX}.
13698 The kind type parameter is the same as @var{X}.
13700 @item @emph{Example}:
13703 real(8) :: x = 2.0_8
13704 complex :: z = (1.0, 2.0)
13707 end program test_sqrt
13710 @item @emph{Specific names}:
13711 @multitable @columnfractions .20 .20 .20 .25
13712 @item Name @tab Argument @tab Return type @tab Standard
13713 @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
13714 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
13715 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
13716 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13717 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13724 @section @code{SRAND} --- Reinitialize the random number generator
13726 @cindex random number generation, seeding
13727 @cindex seeding a random number generator
13730 @item @emph{Description}:
13731 @code{SRAND} reinitializes the pseudo-random number generator
13732 called by @code{RAND} and @code{IRAND}. The new seed used by the
13733 generator is specified by the required argument @var{SEED}.
13735 @item @emph{Standard}:
13738 @item @emph{Class}:
13741 @item @emph{Syntax}:
13742 @code{CALL SRAND(SEED)}
13744 @item @emph{Arguments}:
13745 @multitable @columnfractions .15 .70
13746 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
13749 @item @emph{Return value}:
13750 Does not return anything.
13752 @item @emph{Example}:
13753 See @code{RAND} and @code{IRAND} for examples.
13755 @item @emph{Notes}:
13756 The Fortran standard specifies the intrinsic subroutines
13757 @code{RANDOM_SEED} to initialize the pseudo-random number
13758 generator and @code{RANDOM_NUMBER} to generate pseudo-random numbers.
13759 These subroutines should be used in new codes.
13761 Please note that in GNU Fortran, these two sets of intrinsics (@code{RAND},
13762 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
13763 @code{RANDOM_SEED} on the other hand) access two independent
13764 pseudo-random number generators.
13766 @item @emph{See also}:
13768 @ref{RANDOM_SEED}, @gol
13769 @ref{RANDOM_NUMBER}
13775 @section @code{STAT} --- Get file status
13777 @cindex file system, file status
13780 @item @emph{Description}:
13781 This function returns information about a file. No permissions are required on
13782 the file itself, but execute (search) permission is required on all of the
13783 directories in path that lead to the file.
13785 The elements that are obtained and stored in the array @code{VALUES}:
13786 @multitable @columnfractions .15 .70
13787 @item @code{VALUES(1)} @tab Device ID
13788 @item @code{VALUES(2)} @tab Inode number
13789 @item @code{VALUES(3)} @tab File mode
13790 @item @code{VALUES(4)} @tab Number of links
13791 @item @code{VALUES(5)} @tab Owner's uid
13792 @item @code{VALUES(6)} @tab Owner's gid
13793 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
13794 @item @code{VALUES(8)} @tab File size (bytes)
13795 @item @code{VALUES(9)} @tab Last access time
13796 @item @code{VALUES(10)} @tab Last modification time
13797 @item @code{VALUES(11)} @tab Last file status change time
13798 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
13799 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
13802 Not all these elements are relevant on all systems.
13803 If an element is not relevant, it is returned as 0.
13805 This intrinsic is provided in both subroutine and function forms; however,
13806 only one form can be used in any given program unit.
13808 @item @emph{Standard}:
13811 @item @emph{Class}:
13812 Subroutine, function
13814 @item @emph{Syntax}:
13815 @multitable @columnfractions .80
13816 @item @code{CALL STAT(NAME, VALUES [, STATUS])}
13817 @item @code{STATUS = STAT(NAME, VALUES)}
13820 @item @emph{Arguments}:
13821 @multitable @columnfractions .15 .70
13822 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
13823 default kind and a valid path within the file system.
13824 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
13825 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
13826 on success and a system specific error code otherwise.
13829 @item @emph{Example}:
13832 INTEGER, DIMENSION(13) :: buff
13835 CALL STAT("/etc/passwd", buff, status)
13837 IF (status == 0) THEN
13838 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
13839 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
13840 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
13841 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
13842 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
13843 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
13844 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
13845 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
13846 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
13847 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
13848 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
13849 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
13850 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
13855 @item @emph{See also}:
13856 To stat an open file: @gol
13858 To stat a link: @gol
13865 @section @code{STORAGE_SIZE} --- Storage size in bits
13866 @fnindex STORAGE_SIZE
13867 @cindex storage size
13870 @item @emph{Description}:
13871 Returns the storage size of argument @var{A} in bits.
13872 @item @emph{Standard}:
13873 Fortran 2008 and later
13874 @item @emph{Class}:
13876 @item @emph{Syntax}:
13877 @code{RESULT = STORAGE_SIZE(A [, KIND])}
13879 @item @emph{Arguments}:
13880 @multitable @columnfractions .15 .70
13881 @item @var{A} @tab Shall be a scalar or array of any type.
13882 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
13885 @item @emph{Return Value}:
13886 The result is a scalar integer with the kind type parameter specified by KIND
13887 (or default integer type if KIND is missing). The result value is the size
13888 expressed in bits for an element of an array that has the dynamic type and type
13891 @item @emph{See also}:
13892 @ref{C_SIZEOF}, @gol
13899 @section @code{SUM} --- Sum of array elements
13902 @cindex array, add elements
13903 @cindex array, conditionally add elements
13904 @cindex sum array elements
13907 @item @emph{Description}:
13908 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
13909 the corresponding element in @var{MASK} is @code{TRUE}.
13911 @item @emph{Standard}:
13912 Fortran 90 and later
13914 @item @emph{Class}:
13915 Transformational function
13917 @item @emph{Syntax}:
13918 @multitable @columnfractions .80
13919 @item @code{RESULT = SUM(ARRAY[, MASK])}
13920 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
13923 @item @emph{Arguments}:
13924 @multitable @columnfractions .15 .70
13925 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
13926 @code{REAL} or @code{COMPLEX}.
13927 @item @var{DIM} @tab (Optional) shall be a scalar of type
13928 @code{INTEGER} with a value in the range from 1 to n, where n
13929 equals the rank of @var{ARRAY}.
13930 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
13931 and either be a scalar or an array of the same shape as @var{ARRAY}.
13934 @item @emph{Return value}:
13935 The result is of the same type as @var{ARRAY}.
13937 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
13938 is returned. Otherwise, an array of rank n-1, where n equals the rank of
13939 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
13940 dropped is returned.
13942 @item @emph{Example}:
13945 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
13946 print *, SUM(x) ! all elements, sum = 15
13947 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
13951 @item @emph{See also}:
13958 @section @code{SYMLNK} --- Create a symbolic link
13960 @cindex file system, create link
13961 @cindex file system, soft link
13964 @item @emph{Description}:
13965 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
13966 character (@code{CHAR(0)}) can be used to mark the end of the names in
13967 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
13968 names are ignored. If the @var{STATUS} argument is supplied, it
13969 contains 0 on success or a nonzero error code upon return; see
13970 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
13971 @code{ENOSYS} is returned.
13973 This intrinsic is provided in both subroutine and function forms;
13974 however, only one form can be used in any given program unit.
13976 @item @emph{Standard}:
13979 @item @emph{Class}:
13980 Subroutine, function
13982 @item @emph{Syntax}:
13983 @multitable @columnfractions .80
13984 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
13985 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
13988 @item @emph{Arguments}:
13989 @multitable @columnfractions .15 .70
13990 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
13991 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
13992 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
13995 @item @emph{See also}:
14003 @section @code{SYSTEM} --- Execute a shell command
14005 @cindex system, system call
14008 @item @emph{Description}:
14009 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
14010 argument @var{STATUS} is present, it contains the value returned by
14011 @code{system(3)}, which is presumably 0 if the shell command succeeded.
14012 Note that which shell is used to invoke the command is system-dependent
14013 and environment-dependent.
14015 This intrinsic is provided in both subroutine and function forms;
14016 however, only one form can be used in any given program unit.
14018 Note that the @code{system} function need not be thread-safe. It is
14019 the responsibility of the user to ensure that @code{system} is not
14020 called concurrently.
14022 @item @emph{Standard}:
14025 @item @emph{Class}:
14026 Subroutine, function
14028 @item @emph{Syntax}:
14029 @multitable @columnfractions .80
14030 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
14031 @item @code{STATUS = SYSTEM(COMMAND)}
14034 @item @emph{Arguments}:
14035 @multitable @columnfractions .15 .70
14036 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
14037 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
14040 @item @emph{See also}:
14041 @ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
14042 and should considered in new code for future portability.
14048 @section @code{SYSTEM_CLOCK} --- Time function
14049 @fnindex SYSTEM_CLOCK
14050 @cindex time, clock ticks
14051 @cindex clock ticks
14054 @item @emph{Description}:
14055 Determines the @var{COUNT} of a processor clock since an unspecified
14056 time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines
14057 the number of clock ticks per second. If the platform supports a
14058 monotonic clock, that clock is used and can, depending on the platform
14059 clock implementation, provide up to nanosecond resolution. If a
14060 monotonic clock is not available, the implementation falls back to a
14063 @var{COUNT_RATE} is system dependent and can vary depending on the kind of
14064 the arguments. For @var{kind=4} arguments (and smaller integer kinds),
14065 @var{COUNT} represents milliseconds, while for @var{kind=8} arguments (and
14066 larger integer kinds), @var{COUNT} typically represents micro- or
14067 nanoseconds depending on resolution of the underlying platform clock.
14068 @var{COUNT_MAX} usually equals @code{HUGE(COUNT_MAX)}. Note that the
14069 millisecond resolution of the @var{kind=4} version implies that the
14070 @var{COUNT} will wrap around in roughly 25 days. In order to avoid issues
14071 with the wrap around and for more precise timing, please use the
14072 @var{kind=8} version.
14074 If there is no clock, or querying the clock fails, @var{COUNT} is set
14075 to @code{-HUGE(COUNT)}, and @var{COUNT_RATE} and @var{COUNT_MAX} are
14078 When running on a platform using the GNU C library (glibc) version
14079 2.16 or older, or a derivative thereof, the high resolution monotonic
14080 clock is available only when linking with the @var{rt} library. This
14081 can be done explicitly by adding the @code{-lrt} flag when linking the
14082 application, but is also done implicitly when using OpenMP.
14084 On the Windows platform, the version with @var{kind=4} arguments uses
14085 the @code{GetTickCount} function, whereas the @var{kind=8} version
14086 uses @code{QueryPerformanceCounter} and
14087 @code{QueryPerformanceCounterFrequency}. For more information, and
14088 potential caveats, please see the platform documentation.
14090 @item @emph{Standard}:
14091 Fortran 90 and later
14093 @item @emph{Class}:
14096 @item @emph{Syntax}:
14097 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
14099 @item @emph{Arguments}:
14100 @multitable @columnfractions .20 .65
14101 @item @var{COUNT} @tab (Optional) shall be a scalar of type
14102 @code{INTEGER} with @code{INTENT(OUT)}.
14103 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type
14104 @code{INTEGER} or @code{REAL}, with @code{INTENT(OUT)}.
14105 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type
14106 @code{INTEGER} with @code{INTENT(OUT)}.
14109 @item @emph{Example}:
14111 PROGRAM test_system_clock
14112 INTEGER :: count, count_rate, count_max
14113 CALL SYSTEM_CLOCK(count, count_rate, count_max)
14114 WRITE(*,*) count, count_rate, count_max
14118 @item @emph{See also}:
14119 @ref{DATE_AND_TIME}, @gol
14126 @section @code{TAN} --- Tangent function
14129 @cindex trigonometric function, tangent
14133 @item @emph{Description}:
14134 @code{TAN(X)} computes the tangent of @var{X}.
14136 @item @emph{Standard}:
14137 Fortran 77 and later, for a complex argument Fortran 2008 or later
14139 @item @emph{Class}:
14142 @item @emph{Syntax}:
14143 @code{RESULT = TAN(X)}
14145 @item @emph{Arguments}:
14146 @multitable @columnfractions .15 .70
14147 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
14150 @item @emph{Return value}:
14151 The return value has same type and kind as @var{X}, and its value is in radians.
14153 @item @emph{Example}:
14156 real(8) :: x = 0.165_8
14158 end program test_tan
14161 @item @emph{Specific names}:
14162 @multitable @columnfractions .20 .20 .20 .25
14163 @item Name @tab Argument @tab Return type @tab Standard
14164 @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
14165 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
14168 @item @emph{See also}:
14169 Inverse function: @gol
14171 Degrees function: @gol
14178 @section @code{TAND} --- Tangent function, degrees
14181 @cindex trigonometric function, tangent, degrees
14182 @cindex tangent, degrees
14185 @item @emph{Description}:
14186 @code{TAND(X)} computes the tangent of @var{X} in degrees.
14188 This function is for compatibility only and should be avoided in favor of
14189 standard constructs wherever possible.
14191 @item @emph{Standard}:
14192 GNU extension, enabled with @option{-fdec-math}.
14194 @item @emph{Class}:
14197 @item @emph{Syntax}:
14198 @code{RESULT = TAND(X)}
14200 @item @emph{Arguments}:
14201 @multitable @columnfractions .15 .70
14202 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
14205 @item @emph{Return value}:
14206 The return value has same type and kind as @var{X}, and its value is in degrees.
14208 @item @emph{Example}:
14211 real(8) :: x = 0.165_8
14213 end program test_tand
14216 @item @emph{Specific names}:
14217 @multitable @columnfractions .20 .20 .20 .25
14218 @item Name @tab Argument @tab Return type @tab Standard
14219 @item @code{TAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU extension
14220 @item @code{DTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
14223 @item @emph{See also}:
14224 Inverse function: @gol
14226 Radians function: @gol
14233 @section @code{TANH} --- Hyperbolic tangent function
14236 @cindex hyperbolic tangent
14237 @cindex hyperbolic function, tangent
14238 @cindex tangent, hyperbolic
14241 @item @emph{Description}:
14242 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
14244 @item @emph{Standard}:
14245 Fortran 77 and later, for a complex argument Fortran 2008 or later
14247 @item @emph{Class}:
14250 @item @emph{Syntax}:
14253 @item @emph{Arguments}:
14254 @multitable @columnfractions .15 .70
14255 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
14258 @item @emph{Return value}:
14259 The return value has same type and kind as @var{X}. If @var{X} is
14260 complex, the imaginary part of the result is in radians. If @var{X}
14261 is @code{REAL}, the return value lies in the range
14262 @math{ - 1 \leq tanh(x) \leq 1 }.
14264 @item @emph{Example}:
14267 real(8) :: x = 2.1_8
14269 end program test_tanh
14272 @item @emph{Specific names}:
14273 @multitable @columnfractions .20 .20 .20 .25
14274 @item Name @tab Argument @tab Return type @tab Standard
14275 @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
14276 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
14279 @item @emph{See also}:
14286 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
14287 @fnindex THIS_IMAGE
14288 @cindex coarray, @code{THIS_IMAGE}
14289 @cindex images, index of this image
14292 @item @emph{Description}:
14293 Returns the cosubscript for this image.
14295 @item @emph{Standard}:
14296 Fortran 2008 and later. With @var{DISTANCE} argument,
14297 Technical Specification (TS) 18508 or later
14299 @item @emph{Class}:
14300 Transformational function
14302 @item @emph{Syntax}:
14303 @multitable @columnfractions .80
14304 @item @code{RESULT = THIS_IMAGE()}
14305 @item @code{RESULT = THIS_IMAGE(DISTANCE)}
14306 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
14309 @item @emph{Arguments}:
14310 @multitable @columnfractions .15 .70
14311 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
14312 (not permitted together with @var{COARRAY}).
14313 @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
14314 present, required).
14315 @item @var{DIM} @tab default integer scalar (optional). If present,
14316 @var{DIM} shall be between one and the corank of @var{COARRAY}.
14320 @item @emph{Return value}:
14321 Default integer. If @var{COARRAY} is not present, it is scalar; if
14322 @var{DISTANCE} is not present or has value 0, its value is the image index on
14323 the invoking image for the current team, for values smaller or equal
14324 distance to the initial team, it returns the image index on the ancestor team
14325 which has a distance of @var{DISTANCE} from the invoking team. If
14326 @var{DISTANCE} is larger than the distance to the initial team, the image
14327 index of the initial team is returned. Otherwise when the @var{COARRAY} is
14328 present, if @var{DIM} is not present, a rank-1 array with corank elements is
14329 returned, containing the cosubscripts for @var{COARRAY} specifying the invoking
14330 image. If @var{DIM} is present, a scalar is returned, with the value of
14331 the @var{DIM} element of @code{THIS_IMAGE(COARRAY)}.
14333 @item @emph{Example}:
14335 INTEGER :: value[*]
14337 value = THIS_IMAGE()
14339 IF (THIS_IMAGE() == 1) THEN
14340 DO i = 1, NUM_IMAGES()
14341 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
14345 ! Check whether the current image is the initial image
14346 IF (THIS_IMAGE(HUGE(1)) /= THIS_IMAGE())
14347 error stop "something is rotten here"
14350 @item @emph{See also}:
14351 @ref{NUM_IMAGES}, @gol
14358 @section @code{TIME} --- Time function
14360 @cindex time, current
14361 @cindex current time
14364 @item @emph{Description}:
14365 Returns the current time encoded as an integer (in the manner of the
14366 function @code{time(3)} in the C standard library). This value is
14367 suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}.
14369 This intrinsic is not fully portable, such as to systems with 32-bit
14370 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
14371 the values returned by this intrinsic might be, or become, negative, or
14372 numerically less than previous values, during a single run of the
14375 See @ref{TIME8}, for information on a similar intrinsic that might be
14376 portable to more GNU Fortran implementations, though to fewer Fortran
14379 @item @emph{Standard}:
14382 @item @emph{Class}:
14385 @item @emph{Syntax}:
14386 @code{RESULT = TIME()}
14388 @item @emph{Return value}:
14389 The return value is a scalar of type @code{INTEGER(4)}.
14391 @item @emph{See also}:
14392 @ref{DATE_AND_TIME}, @gol
14403 @section @code{TIME8} --- Time function (64-bit)
14405 @cindex time, current
14406 @cindex current time
14409 @item @emph{Description}:
14410 Returns the current time encoded as an integer (in the manner of the
14411 function @code{time(3)} in the C standard library). This value is
14412 suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}.
14414 @emph{Warning:} this intrinsic does not increase the range of the timing
14415 values over that returned by @code{time(3)}. On a system with a 32-bit
14416 @code{time(3)}, @code{TIME8} will return a 32-bit value, even though
14417 it is converted to a 64-bit @code{INTEGER(8)} value. That means
14418 overflows of the 32-bit value can still occur. Therefore, the values
14419 returned by this intrinsic might be or become negative or numerically
14420 less than previous values during a single run of the compiled program.
14422 @item @emph{Standard}:
14425 @item @emph{Class}:
14428 @item @emph{Syntax}:
14429 @code{RESULT = TIME8()}
14431 @item @emph{Return value}:
14432 The return value is a scalar of type @code{INTEGER(8)}.
14434 @item @emph{See also}:
14435 @ref{DATE_AND_TIME}, @gol
14439 @ref{MCLOCK8}, @gol
14446 @section @code{TINY} --- Smallest positive number of a real kind
14448 @cindex limits, smallest number
14449 @cindex model representation, smallest number
14452 @item @emph{Description}:
14453 @code{TINY(X)} returns the smallest positive (non zero) number
14454 in the model of the type of @code{X}.
14456 @item @emph{Standard}:
14457 Fortran 90 and later
14459 @item @emph{Class}:
14462 @item @emph{Syntax}:
14463 @code{RESULT = TINY(X)}
14465 @item @emph{Arguments}:
14466 @multitable @columnfractions .15 .70
14467 @item @var{X} @tab Shall be of type @code{REAL}.
14470 @item @emph{Return value}:
14471 The return value is of the same type and kind as @var{X}
14473 @item @emph{Example}:
14474 See @code{HUGE} for an example.
14480 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
14485 @item @emph{Description}:
14486 @code{TRAILZ} returns the number of trailing zero bits of an integer.
14488 @item @emph{Standard}:
14489 Fortran 2008 and later
14491 @item @emph{Class}:
14494 @item @emph{Syntax}:
14495 @code{RESULT = TRAILZ(I)}
14497 @item @emph{Arguments}:
14498 @multitable @columnfractions .15 .70
14499 @item @var{I} @tab Shall be of type @code{INTEGER}.
14502 @item @emph{Return value}:
14503 The type of the return value is the default @code{INTEGER}.
14504 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
14506 @item @emph{Example}:
14508 PROGRAM test_trailz
14509 WRITE (*,*) TRAILZ(8) ! prints 3
14513 @item @emph{See also}:
14514 @ref{BIT_SIZE}, @gol
14523 @section @code{TRANSFER} --- Transfer bit patterns
14529 @item @emph{Description}:
14530 Interprets the bitwise representation of @var{SOURCE} in memory as if it
14531 is the representation of a variable or array of the same type and type
14532 parameters as @var{MOLD}.
14534 This is approximately equivalent to the C concept of @emph{casting} one
14537 @item @emph{Standard}:
14538 Fortran 90 and later
14540 @item @emph{Class}:
14541 Transformational function
14543 @item @emph{Syntax}:
14544 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
14546 @item @emph{Arguments}:
14547 @multitable @columnfractions .15 .70
14548 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
14549 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
14550 @item @var{SIZE} @tab (Optional) shall be a scalar of type
14554 @item @emph{Return value}:
14555 The result has the same type as @var{MOLD}, with the bit level
14556 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
14557 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
14558 but @var{MOLD} is an array (of any size or shape), the result is a one-
14559 dimensional array of the minimum length needed to contain the entirety
14560 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
14561 and @var{MOLD} is a scalar, the result is a scalar.
14563 If the bitwise representation of the result is longer than that of
14564 @var{SOURCE}, then the leading bits of the result correspond to those of
14565 @var{SOURCE} and any trailing bits are filled arbitrarily.
14567 When the resulting bit representation does not correspond to a valid
14568 representation of a variable of the same type as @var{MOLD}, the results
14569 are undefined, and subsequent operations on the result cannot be
14570 guaranteed to produce sensible behavior. For example, it is possible to
14571 create @code{LOGICAL} variables for which @code{@var{VAR}} and
14572 @code{.NOT.@var{VAR}} both appear to be true.
14574 @item @emph{Example}:
14576 PROGRAM test_transfer
14577 integer :: x = 2143289344
14578 print *, transfer(x, 1.0) ! prints "NaN" on i686
14586 @section @code{TRANSPOSE} --- Transpose an array of rank two
14588 @cindex array, transpose
14589 @cindex matrix, transpose
14593 @item @emph{Description}:
14594 Transpose an array of rank two. Element (i, j) of the result has the value
14595 @code{MATRIX(j, i)}, for all i, j.
14597 @item @emph{Standard}:
14598 Fortran 90 and later
14600 @item @emph{Class}:
14601 Transformational function
14603 @item @emph{Syntax}:
14604 @code{RESULT = TRANSPOSE(MATRIX)}
14606 @item @emph{Arguments}:
14607 @multitable @columnfractions .15 .70
14608 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
14611 @item @emph{Return value}:
14612 The result has the same type as @var{MATRIX}, and has shape
14613 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
14619 @section @code{TRIM} --- Remove trailing blank characters of a string
14621 @cindex string, remove trailing whitespace
14624 @item @emph{Description}:
14625 Removes trailing blank characters of a string.
14627 @item @emph{Standard}:
14628 Fortran 90 and later
14630 @item @emph{Class}:
14631 Transformational function
14633 @item @emph{Syntax}:
14634 @code{RESULT = TRIM(STRING)}
14636 @item @emph{Arguments}:
14637 @multitable @columnfractions .15 .70
14638 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
14641 @item @emph{Return value}:
14642 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
14643 less the number of trailing blanks.
14645 @item @emph{Example}:
14648 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
14649 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
14653 @item @emph{See also}:
14654 @ref{ADJUSTL}, @gol
14661 @section @code{TTYNAM} --- Get the name of a terminal device.
14663 @cindex system, terminal
14666 @item @emph{Description}:
14667 Get the name of a terminal device. For more information,
14668 see @code{ttyname(3)}.
14670 This intrinsic is provided in both subroutine and function forms;
14671 however, only one form can be used in any given program unit.
14673 @item @emph{Standard}:
14676 @item @emph{Class}:
14677 Subroutine, function
14679 @item @emph{Syntax}:
14680 @multitable @columnfractions .80
14681 @item @code{CALL TTYNAM(UNIT, NAME)}
14682 @item @code{NAME = TTYNAM(UNIT)}
14685 @item @emph{Arguments}:
14686 @multitable @columnfractions .15 .70
14687 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
14688 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
14691 @item @emph{Example}:
14693 PROGRAM test_ttynam
14696 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
14701 @item @emph{See also}:
14708 @section @code{UBOUND} --- Upper dimension bounds of an array
14710 @cindex array, upper bound
14713 @item @emph{Description}:
14714 Returns the upper bounds of an array, or a single upper bound
14715 along the @var{DIM} dimension.
14716 @item @emph{Standard}:
14717 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
14719 @item @emph{Class}:
14722 @item @emph{Syntax}:
14723 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
14725 @item @emph{Arguments}:
14726 @multitable @columnfractions .15 .70
14727 @item @var{ARRAY} @tab Shall be an array, of any type.
14728 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
14729 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
14730 expression indicating the kind parameter of the result.
14733 @item @emph{Return value}:
14734 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14735 @var{KIND} is absent, the return value is of default integer kind.
14736 If @var{DIM} is absent, the result is an array of the upper bounds of
14737 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
14738 corresponding to the upper bound of the array along that dimension. If
14739 @var{ARRAY} is an expression rather than a whole array or array
14740 structure component, or if it has a zero extent along the relevant
14741 dimension, the upper bound is taken to be the number of elements along
14742 the relevant dimension.
14744 @item @emph{See also}:
14752 @section @code{UCOBOUND} --- Upper codimension bounds of an array
14754 @cindex coarray, upper bound
14757 @item @emph{Description}:
14758 Returns the upper cobounds of a coarray, or a single upper cobound
14759 along the @var{DIM} codimension.
14760 @item @emph{Standard}:
14761 Fortran 2008 and later
14763 @item @emph{Class}:
14766 @item @emph{Syntax}:
14767 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
14769 @item @emph{Arguments}:
14770 @multitable @columnfractions .15 .70
14771 @item @var{ARRAY} @tab Shall be an coarray, of any type.
14772 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
14773 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
14774 expression indicating the kind parameter of the result.
14777 @item @emph{Return value}:
14778 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14779 @var{KIND} is absent, the return value is of default integer kind.
14780 If @var{DIM} is absent, the result is an array of the lower cobounds of
14781 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
14782 corresponding to the lower cobound of the array along that codimension.
14784 @item @emph{See also}:
14785 @ref{LCOBOUND}, @gol
14792 @section @code{UMASK} --- Set the file creation mask
14794 @cindex file system, file creation mask
14797 @item @emph{Description}:
14798 Sets the file creation mask to @var{MASK}. If called as a function, it
14799 returns the old value. If called as a subroutine and argument @var{OLD}
14800 if it is supplied, it is set to the old value. See @code{umask(2)}.
14802 @item @emph{Standard}:
14805 @item @emph{Class}:
14806 Subroutine, function
14808 @item @emph{Syntax}:
14809 @multitable @columnfractions .80
14810 @item @code{CALL UMASK(MASK [, OLD])}
14811 @item @code{OLD = UMASK(MASK)}
14814 @item @emph{Arguments}:
14815 @multitable @columnfractions .15 .70
14816 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
14817 @item @var{OLD} @tab (Optional) Shall be a scalar of type
14826 @section @code{UNLINK} --- Remove a file from the file system
14828 @cindex file system, remove file
14831 @item @emph{Description}:
14832 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
14833 used to mark the end of the name in @var{PATH}; otherwise, trailing
14834 blanks in the file name are ignored. If the @var{STATUS} argument is
14835 supplied, it contains 0 on success or a nonzero error code upon return;
14836 see @code{unlink(2)}.
14838 This intrinsic is provided in both subroutine and function forms;
14839 however, only one form can be used in any given program unit.
14841 @item @emph{Standard}:
14844 @item @emph{Class}:
14845 Subroutine, function
14847 @item @emph{Syntax}:
14848 @multitable @columnfractions .80
14849 @item @code{CALL UNLINK(PATH [, STATUS])}
14850 @item @code{STATUS = UNLINK(PATH)}
14853 @item @emph{Arguments}:
14854 @multitable @columnfractions .15 .70
14855 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
14856 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
14859 @item @emph{See also}:
14867 @section @code{UNPACK} --- Unpack an array of rank one into an array
14869 @cindex array, unpacking
14870 @cindex array, increase dimension
14871 @cindex array, scatter elements
14874 @item @emph{Description}:
14875 Store the elements of @var{VECTOR} in an array of higher rank.
14877 @item @emph{Standard}:
14878 Fortran 90 and later
14880 @item @emph{Class}:
14881 Transformational function
14883 @item @emph{Syntax}:
14884 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
14886 @item @emph{Arguments}:
14887 @multitable @columnfractions .15 .70
14888 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
14889 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
14890 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
14891 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
14892 the same shape as @var{MASK}.
14895 @item @emph{Return value}:
14896 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
14897 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
14899 @item @emph{Example}:
14901 PROGRAM test_unpack
14902 integer :: vector(2) = (/1,1/)
14903 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
14904 integer :: field(2,2) = 0, unity(2,2)
14906 ! result: unity matrix
14907 unity = unpack(vector, reshape(mask, (/2,2/)), field)
14911 @item @emph{See also}:
14919 @section @code{VERIFY} --- Scan a string for characters not a given set
14921 @cindex string, find missing set
14924 @item @emph{Description}:
14925 Verifies that all the characters in @var{STRING} belong to the set of
14926 characters in @var{SET}.
14928 If @var{BACK} is either absent or equals @code{FALSE}, this function
14929 returns the position of the leftmost character of @var{STRING} that is
14930 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost
14931 position is returned. If all characters of @var{STRING} are found in
14932 @var{SET}, the result is zero.
14934 @item @emph{Standard}:
14935 Fortran 90 and later, with @var{KIND} argument Fortran 2003 and later
14937 @item @emph{Class}:
14940 @item @emph{Syntax}:
14941 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
14943 @item @emph{Arguments}:
14944 @multitable @columnfractions .15 .70
14945 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
14946 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
14947 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
14948 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
14949 expression indicating the kind parameter of the result.
14952 @item @emph{Return value}:
14953 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14954 @var{KIND} is absent, the return value is of default integer kind.
14956 @item @emph{Example}:
14958 PROGRAM test_verify
14959 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
14960 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
14961 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
14962 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
14963 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
14967 @item @emph{See also}:
14969 @ref{INDEX intrinsic}
14975 @section @code{XOR} --- Bitwise logical exclusive OR
14977 @cindex bitwise logical exclusive or
14978 @cindex logical exclusive or, bitwise
14981 @item @emph{Description}:
14982 Bitwise logical exclusive or.
14984 This intrinsic routine is provided for backwards compatibility with
14985 GNU Fortran 77. For integer arguments, programmers should consider
14986 the use of the @ref{IEOR} intrinsic and for logical arguments the
14987 @code{.NEQV.} operator, which are both defined by the Fortran standard.
14989 @item @emph{Standard}:
14992 @item @emph{Class}:
14995 @item @emph{Syntax}:
14996 @code{RESULT = XOR(I, J)}
14998 @item @emph{Arguments}:
14999 @multitable @columnfractions .15 .70
15000 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
15001 type or a scalar @code{LOGICAL} type or a boz-literal-constant.
15002 @item @var{J} @tab The type shall be the same as the type of @var{I} or
15003 a boz-literal-constant. @var{I} and @var{J} shall not both be
15004 boz-literal-constants. If either @var{I} and @var{J} is a
15005 boz-literal-constant, then the other argument must be a scalar @code{INTEGER}.
15008 @item @emph{Return value}:
15009 The return type is either a scalar @code{INTEGER} or a scalar
15010 @code{LOGICAL}. If the kind type parameters differ, then the
15011 smaller kind type is implicitly converted to larger kind, and the
15012 return has the larger kind. A boz-literal-constant is
15013 converted to an @code{INTEGER} with the kind type parameter of
15014 the other argument as-if a call to @ref{INT} occurred.
15016 @item @emph{Example}:
15019 LOGICAL :: T = .TRUE., F = .FALSE.
15021 DATA a / Z'F' /, b / Z'3' /
15023 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
15024 WRITE (*,*) XOR(a, b)
15028 @item @emph{See also}:
15029 Fortran 95 elemental function: @gol
15035 @node Intrinsic Modules
15036 @chapter Intrinsic Modules
15037 @cindex intrinsic Modules
15040 * ISO_FORTRAN_ENV::
15043 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
15044 * OpenACC Module OPENACC::
15047 @node ISO_FORTRAN_ENV
15048 @section @code{ISO_FORTRAN_ENV}
15050 @item @emph{Standard}:
15051 Fortran 2003 and later, except when otherwise noted
15054 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
15058 @item @code{ATOMIC_INT_KIND}:
15059 Default-kind integer constant to be used as kind parameter when defining
15060 integer variables used in atomic operations. (Fortran 2008 or later.)
15062 @item @code{ATOMIC_LOGICAL_KIND}:
15063 Default-kind integer constant to be used as kind parameter when defining
15064 logical variables used in atomic operations. (Fortran 2008 or later.)
15066 @item @code{CHARACTER_KINDS}:
15067 Default-kind integer constant array of rank one containing the supported kind
15068 parameters of the @code{CHARACTER} type. (Fortran 2008 or later.)
15070 @item @code{CHARACTER_STORAGE_SIZE}:
15071 Size in bits of the character storage unit.
15073 @item @code{ERROR_UNIT}:
15074 Identifies the preconnected unit used for error reporting.
15076 @item @code{FILE_STORAGE_SIZE}:
15077 Size in bits of the file-storage unit.
15079 @item @code{INPUT_UNIT}:
15080 Identifies the preconnected unit identified by the asterisk
15081 (@code{*}) in @code{READ} statement.
15083 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
15084 Kind type parameters to specify an INTEGER type with a storage
15085 size of 16, 32, and 64 bits. It is negative if a target platform
15086 does not support the particular kind. (Fortran 2008 or later.)
15088 @item @code{INTEGER_KINDS}:
15089 Default-kind integer constant array of rank one containing the supported kind
15090 parameters of the @code{INTEGER} type. (Fortran 2008 or later.)
15092 @item @code{IOSTAT_END}:
15093 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
15094 an input/output statement if an end-of-file condition occurred.
15096 @item @code{IOSTAT_EOR}:
15097 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
15098 an input/output statement if an end-of-record condition occurred.
15100 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
15101 Scalar default-integer constant, used by @code{INQUIRE} for the
15102 @code{IOSTAT=} specifier to denote an that a unit number identifies an
15103 internal unit. (Fortran 2008 or later.)
15105 @item @code{NUMERIC_STORAGE_SIZE}:
15106 The size in bits of the numeric storage unit.
15108 @item @code{LOGICAL_KINDS}:
15109 Default-kind integer constant array of rank one containing the supported kind
15110 parameters of the @code{LOGICAL} type. (Fortran 2008 or later.)
15112 @item @code{OUTPUT_UNIT}:
15113 Identifies the preconnected unit identified by the asterisk
15114 (@code{*}) in @code{WRITE} statement.
15116 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
15117 Kind type parameters to specify a REAL type with a storage
15118 size of 32, 64, and 128 bits. It is negative if a target platform
15119 does not support the particular kind. (Fortran 2008 or later.)
15121 @item @code{REAL_KINDS}:
15122 Default-kind integer constant array of rank one containing the supported kind
15123 parameters of the @code{REAL} type. (Fortran 2008 or later.)
15125 @item @code{STAT_LOCKED}:
15126 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
15127 denote that the lock variable is locked by the executing image. (Fortran 2008
15130 @item @code{STAT_LOCKED_OTHER_IMAGE}:
15131 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
15132 denote that the lock variable is locked by another image. (Fortran 2008 or
15135 @item @code{STAT_STOPPED_IMAGE}:
15136 Positive, scalar default-integer constant used as STAT= return value if the
15137 argument in the statement requires synchronisation with an image, which has
15138 initiated the termination of the execution. (Fortran 2008 or later.)
15140 @item @code{STAT_FAILED_IMAGE}:
15141 Positive, scalar default-integer constant used as STAT= return value if the
15142 argument in the statement requires communication with an image, which has
15143 is in the failed state. (TS 18508 or later.)
15145 @item @code{STAT_UNLOCKED}:
15146 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
15147 denote that the lock variable is unlocked. (Fortran 2008 or later.)
15150 The module provides the following derived type:
15153 @item @code{LOCK_TYPE}:
15154 Derived type with private components to be use with the @code{LOCK} and
15155 @code{UNLOCK} statement. A variable of its type has to be always declared
15156 as coarray and may not appear in a variable-definition context.
15157 (Fortran 2008 or later.)
15160 The module also provides the following intrinsic procedures:
15161 @ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}.
15165 @node ISO_C_BINDING
15166 @section @code{ISO_C_BINDING}
15168 @item @emph{Standard}:
15169 Fortran 2003 and later, GNU extensions
15172 The following intrinsic procedures are provided by the module; their
15173 definition can be found in the section Intrinsic Procedures of this
15177 @item @code{C_ASSOCIATED}
15178 @item @code{C_F_POINTER}
15179 @item @code{C_F_PROCPOINTER}
15180 @item @code{C_FUNLOC}
15182 @item @code{C_SIZEOF}
15184 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
15185 @c don't really know why.
15187 The @code{ISO_C_BINDING} module provides the following named constants of
15188 type default integer, which can be used as KIND type parameters.
15190 In addition to the integer named constants required by the Fortran 2003
15191 standard and @code{C_PTRDIFF_T} of TS 29113, GNU Fortran provides as an
15192 extension named constants for the 128-bit integer types supported by the
15193 C compiler: @code{C_INT128_T, C_INT_LEAST128_T, C_INT_FAST128_T}.
15194 Furthermore, if @code{__float128} is supported in C, the named constants
15195 @code{C_FLOAT128, C_FLOAT128_COMPLEX} are defined.
15197 @multitable @columnfractions .15 .35 .35 .35
15198 @item Fortran Type @tab Named constant @tab C type @tab Extension
15199 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
15200 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
15201 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
15202 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
15203 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
15204 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
15205 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
15206 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
15207 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
15208 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
15209 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
15210 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
15211 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
15212 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
15213 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
15214 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
15215 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
15216 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
15217 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
15218 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
15219 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
15220 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
15221 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
15222 @item @code{INTEGER}@tab @code{C_PTRDIFF_T} @tab @code{ptrdiff_t} @tab TS 29113
15223 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
15224 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
15225 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
15226 @item @code{REAL} @tab @code{C_FLOAT128} @tab @code{__float128} @tab Ext.
15227 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
15228 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
15229 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
15230 @item @code{REAL} @tab @code{C_FLOAT128_COMPLEX} @tab @code{__float128 _Complex} @tab Ext.
15231 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
15232 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
15235 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
15238 @multitable @columnfractions .20 .45 .15
15239 @item Name @tab C definition @tab Value
15240 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
15241 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
15242 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
15243 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
15244 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
15245 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
15246 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
15247 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
15250 Moreover, the following two named constants are defined:
15252 @multitable @columnfractions .20 .80
15253 @item Name @tab Type
15254 @item @code{C_NULL_PTR} @tab @code{C_PTR}
15255 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
15258 Both are equivalent to the value @code{NULL} in C.
15263 @section IEEE modules: @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
15265 @item @emph{Standard}:
15266 Fortran 2003 and later
15269 The @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
15270 intrinsic modules provide support for exceptions and IEEE arithmetic, as
15271 defined in Fortran 2003 and later standards, and the IEC 60559:1989 standard
15272 (@emph{Binary floating-point arithmetic for microprocessor systems}). These
15273 modules are only provided on the following supported platforms:
15276 @item i386 and x86_64 processors
15277 @item platforms which use the GNU C Library (glibc)
15278 @item platforms with support for SysV/386 routines for floating point
15279 interface (including Solaris and BSDs)
15280 @item platforms with the AIX OS
15283 For full compliance with the Fortran standards, code using the
15284 @code{IEEE_EXCEPTIONS} or @code{IEEE_ARITHMETIC} modules should be compiled
15285 with the following options: @code{-fno-unsafe-math-optimizations
15286 -frounding-math -fsignaling-nans}.
15290 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
15291 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
15293 @item @emph{Standard}:
15294 OpenMP Application Program Interface v4.5
15298 The OpenMP Fortran runtime library routines are provided both in
15299 a form of two Fortran 90 modules, named @code{OMP_LIB} and
15300 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
15301 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
15302 in the @ref{Top,,Introduction,libgomp,GNU Offloading and Multi
15303 Processing Runtime Library} manual,
15304 the named constants defined in the modules are listed
15307 For details refer to the actual
15308 @uref{http://www.openmp.org/wp-content/uploads/openmp-4.5.pdf,
15309 OpenMP Application Program Interface v4.5}.
15311 @code{OMP_LIB_KINDS} provides the following scalar default-integer
15315 @item @code{omp_lock_kind}
15316 @item @code{omp_nest_lock_kind}
15317 @item @code{omp_proc_bind_kind}
15318 @item @code{omp_sched_kind}
15321 @code{OMP_LIB} provides the scalar default-integer
15322 named constant @code{openmp_version} with a value of the form
15323 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
15324 of the OpenMP version; for OpenMP v4.5 the value is @code{201511}.
15326 The following scalar integer named constants of the
15327 kind @code{omp_sched_kind}:
15330 @item @code{omp_sched_static}
15331 @item @code{omp_sched_dynamic}
15332 @item @code{omp_sched_guided}
15333 @item @code{omp_sched_auto}
15336 And the following scalar integer named constants of the
15337 kind @code{omp_proc_bind_kind}:
15340 @item @code{omp_proc_bind_false}
15341 @item @code{omp_proc_bind_true}
15342 @item @code{omp_proc_bind_master}
15343 @item @code{omp_proc_bind_close}
15344 @item @code{omp_proc_bind_spread}
15349 @node OpenACC Module OPENACC
15350 @section OpenACC Module @code{OPENACC}
15352 @item @emph{Standard}:
15353 OpenACC Application Programming Interface v2.0
15357 The OpenACC Fortran runtime library routines are provided both in a
15358 form of a Fortran 90 module, named @code{OPENACC}, and in form of a
15359 Fortran @code{include} file named @file{openacc_lib.h}. The
15360 procedures provided by @code{OPENACC} can be found in the
15361 @ref{Top,,Introduction,libgomp,GNU Offloading and Multi Processing
15362 Runtime Library} manual, the named constants defined in the modules
15365 For details refer to the actual
15366 @uref{http://www.openacc.org/,
15367 OpenACC Application Programming Interface v2.0}.
15369 @code{OPENACC} provides the scalar default-integer
15370 named constant @code{openacc_version} with a value of the form
15371 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
15372 of the OpenACC version; for OpenACC v2.0 the value is @code{201306}.