2 Copyright (C) 2005-2019 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}:
406 @ref{EXIT}, @ref{KILL}, @ref{BACKTRACE}
413 @section @code{ABS} --- Absolute value
424 @cindex absolute value
427 @item @emph{Description}:
428 @code{ABS(A)} computes the absolute value of @code{A}.
430 @item @emph{Standard}:
431 Fortran 77 and later, has overloads that are GNU extensions
437 @code{RESULT = ABS(A)}
439 @item @emph{Arguments}:
440 @multitable @columnfractions .15 .70
441 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
442 @code{REAL}, or @code{COMPLEX}.
445 @item @emph{Return value}:
446 The return value is of the same type and
447 kind as the argument except the return value is @code{REAL} for a
448 @code{COMPLEX} argument.
450 @item @emph{Example}:
455 complex :: z = (-1.e0,0.e0)
462 @item @emph{Specific names}:
463 @multitable @columnfractions .20 .20 .20 .25
464 @item Name @tab Argument @tab Return type @tab Standard
465 @item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
466 @item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
467 @item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
468 @item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
469 @item @code{BABS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
470 @item @code{IIABS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
471 @item @code{JIABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
472 @item @code{KIABS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
473 @item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
474 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
481 @section @code{ACCESS} --- Checks file access modes
483 @cindex file system, access mode
486 @item @emph{Description}:
487 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
488 exists, is readable, writable or executable. Except for the
489 executable check, @code{ACCESS} can be replaced by
490 Fortran 95's @code{INQUIRE}.
492 @item @emph{Standard}:
499 @code{RESULT = ACCESS(NAME, MODE)}
501 @item @emph{Arguments}:
502 @multitable @columnfractions .15 .70
503 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
504 file name. Tailing blank are ignored unless the character @code{achar(0)}
505 is present, then all characters up to and excluding @code{achar(0)} are
507 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
508 file access mode, may be any concatenation of @code{"r"} (readable),
509 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
513 @item @emph{Return value}:
514 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
515 accessible in the given mode; otherwise or if an invalid argument
516 has been given for @code{MODE} the value @code{1} is returned.
518 @item @emph{Example}:
522 character(len=*), parameter :: file = 'test.dat'
523 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
524 if(access(file,' ') == 0) print *, trim(file),' is exists'
525 if(access(file,'r') == 0) print *, trim(file),' is readable'
526 if(access(file,'w') == 0) print *, trim(file),' is writable'
527 if(access(file,'x') == 0) print *, trim(file),' is executable'
528 if(access(file2,'rwx') == 0) &
529 print *, trim(file2),' is readable, writable and executable'
530 end program access_test
532 @item @emph{Specific names}:
533 @item @emph{See also}:
540 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
542 @cindex @acronym{ASCII} collating sequence
543 @cindex collating sequence, @acronym{ASCII}
546 @item @emph{Description}:
547 @code{ACHAR(I)} returns the character located at position @code{I}
548 in the @acronym{ASCII} collating sequence.
550 @item @emph{Standard}:
551 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
557 @code{RESULT = ACHAR(I [, KIND])}
559 @item @emph{Arguments}:
560 @multitable @columnfractions .15 .70
561 @item @var{I} @tab The type shall be @code{INTEGER}.
562 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
563 expression indicating the kind parameter of the result.
566 @item @emph{Return value}:
567 The return value is of type @code{CHARACTER} with a length of one.
568 If the @var{KIND} argument is present, the return value is of the
569 specified kind and of the default kind otherwise.
571 @item @emph{Example}:
576 end program test_achar
580 See @ref{ICHAR} for a discussion of converting between numerical values
581 and formatted string representations.
583 @item @emph{See also}:
584 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
591 @section @code{ACOS} --- Arccosine function
594 @cindex trigonometric function, cosine, inverse
595 @cindex cosine, inverse
598 @item @emph{Description}:
599 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
601 @item @emph{Standard}:
602 Fortran 77 and later, for a complex argument Fortran 2008 or later
608 @code{RESULT = ACOS(X)}
610 @item @emph{Arguments}:
611 @multitable @columnfractions .15 .70
612 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
613 less than or equal to one - or the type shall be @code{COMPLEX}.
616 @item @emph{Return value}:
617 The return value is of the same type and kind as @var{X}.
618 The real part of the result is in radians and lies in the range
619 @math{0 \leq \Re \acos(x) \leq \pi}.
621 @item @emph{Example}:
624 real(8) :: x = 0.866_8
626 end program test_acos
629 @item @emph{Specific names}:
630 @multitable @columnfractions .20 .20 .20 .25
631 @item Name @tab Argument @tab Return type @tab Standard
632 @item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
633 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
636 @item @emph{See also}:
637 Inverse function: @ref{COS}
638 Degrees function: @ref{ACOSD}
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: @ref{COSD}
696 Radians function: @ref{ACOS}
703 @section @code{ACOSH} --- Inverse hyperbolic cosine function
706 @cindex area hyperbolic cosine
707 @cindex inverse hyperbolic cosine
708 @cindex hyperbolic function, cosine, inverse
709 @cindex cosine, hyperbolic, inverse
712 @item @emph{Description}:
713 @code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
715 @item @emph{Standard}:
716 Fortran 2008 and later
722 @code{RESULT = ACOSH(X)}
724 @item @emph{Arguments}:
725 @multitable @columnfractions .15 .70
726 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
729 @item @emph{Return value}:
730 The return value has the same type and kind as @var{X}. If @var{X} is
731 complex, the imaginary part of the result is in radians and lies between
732 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
734 @item @emph{Example}:
737 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
742 @item @emph{Specific names}:
743 @multitable @columnfractions .20 .20 .20 .25
744 @item Name @tab Argument @tab Return type @tab Standard
745 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
748 @item @emph{See also}:
749 Inverse function: @ref{COSH}
755 @section @code{ADJUSTL} --- Left adjust a string
757 @cindex string, adjust left
758 @cindex adjust string
761 @item @emph{Description}:
762 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
763 Spaces are inserted at the end of the string as needed.
765 @item @emph{Standard}:
772 @code{RESULT = ADJUSTL(STRING)}
774 @item @emph{Arguments}:
775 @multitable @columnfractions .15 .70
776 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
779 @item @emph{Return value}:
780 The return value is of type @code{CHARACTER} and of the same kind as
781 @var{STRING} where leading spaces are removed and the same number of
782 spaces are inserted on the end of @var{STRING}.
784 @item @emph{Example}:
787 character(len=20) :: str = ' gfortran'
790 end program test_adjustl
793 @item @emph{See also}:
794 @ref{ADJUSTR}, @ref{TRIM}
800 @section @code{ADJUSTR} --- Right adjust a string
802 @cindex string, adjust right
803 @cindex adjust string
806 @item @emph{Description}:
807 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
808 Spaces are inserted at the start of the string as needed.
810 @item @emph{Standard}:
817 @code{RESULT = ADJUSTR(STRING)}
819 @item @emph{Arguments}:
820 @multitable @columnfractions .15 .70
821 @item @var{STR} @tab The type shall be @code{CHARACTER}.
824 @item @emph{Return value}:
825 The return value is of type @code{CHARACTER} and of the same kind as
826 @var{STRING} where trailing spaces are removed and the same number of
827 spaces are inserted at the start of @var{STRING}.
829 @item @emph{Example}:
832 character(len=20) :: str = 'gfortran'
835 end program test_adjustr
838 @item @emph{See also}:
839 @ref{ADJUSTL}, @ref{TRIM}
845 @section @code{AIMAG} --- Imaginary part of complex number
850 @cindex complex numbers, imaginary part
853 @item @emph{Description}:
854 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
855 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
856 for compatibility with @command{g77}, and their use in new code is
857 strongly discouraged.
859 @item @emph{Standard}:
860 Fortran 77 and later, has overloads that are GNU extensions
866 @code{RESULT = AIMAG(Z)}
868 @item @emph{Arguments}:
869 @multitable @columnfractions .15 .70
870 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
873 @item @emph{Return value}:
874 The return value is of type @code{REAL} with the
875 kind type parameter of the argument.
877 @item @emph{Example}:
882 z4 = cmplx(1.e0_4, 0.e0_4)
883 z8 = cmplx(0.e0_8, 1.e0_8)
884 print *, aimag(z4), dimag(z8)
885 end program test_aimag
888 @item @emph{Specific names}:
889 @multitable @columnfractions .20 .20 .20 .25
890 @item Name @tab Argument @tab Return type @tab Standard
891 @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
892 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
893 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
894 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
901 @section @code{AINT} --- Truncate to a whole number
905 @cindex rounding, floor
908 @item @emph{Description}:
909 @code{AINT(A [, KIND])} truncates its argument to a whole number.
911 @item @emph{Standard}:
918 @code{RESULT = AINT(A [, KIND])}
920 @item @emph{Arguments}:
921 @multitable @columnfractions .15 .70
922 @item @var{A} @tab The type of the argument shall be @code{REAL}.
923 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
924 expression indicating the kind parameter of the result.
927 @item @emph{Return value}:
928 The return value is of type @code{REAL} with the kind type parameter of the
929 argument if the optional @var{KIND} is absent; otherwise, the kind
930 type parameter will be given by @var{KIND}. If the magnitude of
931 @var{X} is less than one, @code{AINT(X)} returns zero. If the
932 magnitude is equal to or greater than one then it returns the largest
933 whole number that does not exceed its magnitude. The sign is the same
934 as the sign of @var{X}.
936 @item @emph{Example}:
943 print *, aint(x4), dint(x8)
945 end program test_aint
948 @item @emph{Specific names}:
949 @multitable @columnfractions .20 .20 .20 .25
950 @item Name @tab Argument @tab Return type @tab Standard
951 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
952 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
959 @section @code{ALARM} --- Execute a routine after a given delay
961 @cindex delayed execution
964 @item @emph{Description}:
965 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
966 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
967 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
968 supplied, it will be returned with the number of seconds remaining until
969 any previously scheduled alarm was due to be delivered, or zero if there
970 was no previously scheduled alarm.
972 @item @emph{Standard}:
979 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
981 @item @emph{Arguments}:
982 @multitable @columnfractions .15 .70
983 @item @var{SECONDS} @tab The type of the argument shall be a scalar
984 @code{INTEGER}. It is @code{INTENT(IN)}.
985 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
986 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
987 values may be either @code{SIG_IGN=1} to ignore the alarm generated
988 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
989 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
990 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
993 @item @emph{Example}:
996 external handler_print
998 call alarm (3, handler_print, i)
1001 end program test_alarm
1003 This will cause the external routine @var{handler_print} to be called
1010 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
1012 @cindex array, apply condition
1013 @cindex array, condition testing
1016 @item @emph{Description}:
1017 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
1018 in the array along dimension @var{DIM}.
1020 @item @emph{Standard}:
1021 Fortran 95 and later
1024 Transformational function
1026 @item @emph{Syntax}:
1027 @code{RESULT = ALL(MASK [, DIM])}
1029 @item @emph{Arguments}:
1030 @multitable @columnfractions .15 .70
1031 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1032 it shall not be scalar.
1033 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1034 with a value that lies between one and the rank of @var{MASK}.
1037 @item @emph{Return value}:
1038 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
1039 the kind type parameter is the same as the kind type parameter of
1040 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
1041 an array with the rank of @var{MASK} minus 1. The shape is determined from
1042 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1046 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
1047 It also is true if @var{MASK} has zero size; otherwise, it is false.
1049 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
1050 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
1051 is determined by applying @code{ALL} to the array sections.
1054 @item @emph{Example}:
1058 l = all((/.true., .true., .true./))
1063 integer a(2,3), b(2,3)
1067 print *, all(a .eq. b, 1)
1068 print *, all(a .eq. b, 2)
1069 end subroutine section
1070 end program test_all
1077 @section @code{ALLOCATED} --- Status of an allocatable entity
1079 @cindex allocation, status
1082 @item @emph{Description}:
1083 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
1084 status of @var{ARRAY} and @var{SCALAR}, respectively.
1086 @item @emph{Standard}:
1087 Fortran 95 and later. Note, the @code{SCALAR=} keyword and allocatable
1088 scalar entities are available in Fortran 2003 and later.
1093 @item @emph{Syntax}:
1094 @multitable @columnfractions .80
1095 @item @code{RESULT = ALLOCATED(ARRAY)}
1096 @item @code{RESULT = ALLOCATED(SCALAR)}
1099 @item @emph{Arguments}:
1100 @multitable @columnfractions .15 .70
1101 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
1102 @item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar.
1105 @item @emph{Return value}:
1106 The return value is a scalar @code{LOGICAL} with the default logical
1107 kind type parameter. If the argument is allocated, then the result is
1108 @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
1110 @item @emph{Example}:
1112 program test_allocated
1114 real(4), allocatable :: x(:)
1115 if (.not. allocated(x)) allocate(x(i))
1116 end program test_allocated
1123 @section @code{AND} --- Bitwise logical AND
1125 @cindex bitwise logical and
1126 @cindex logical and, bitwise
1129 @item @emph{Description}:
1130 Bitwise logical @code{AND}.
1132 This intrinsic routine is provided for backwards compatibility with
1133 GNU Fortran 77. For integer arguments, programmers should consider
1134 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1136 @item @emph{Standard}:
1142 @item @emph{Syntax}:
1143 @code{RESULT = AND(I, J)}
1145 @item @emph{Arguments}:
1146 @multitable @columnfractions .15 .70
1147 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1148 type or a scalar @code{LOGICAL} type or a boz-literal-constant.
1149 @item @var{J} @tab The type shall be the same as the type of @var{I} or
1150 a boz-literal-constant. @var{I} and @var{J} shall not both be
1151 boz-literal-constants. If either @var{I} or @var{J} is a
1152 boz-literal-constant, then the other argument must be a scalar @code{INTEGER}.
1155 @item @emph{Return value}:
1156 The return type is either a scalar @code{INTEGER} or a scalar
1157 @code{LOGICAL}. If the kind type parameters differ, then the
1158 smaller kind type is implicitly converted to larger kind, and the
1159 return has the larger kind. A boz-literal-constant is
1160 converted to an @code{INTEGER} with the kind type parameter of
1161 the other argument as-if a call to @ref{INT} occurred.
1163 @item @emph{Example}:
1166 LOGICAL :: T = .TRUE., F = .FALSE.
1168 DATA a / Z'F' /, b / Z'3' /
1170 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1171 WRITE (*,*) AND(a, b)
1175 @item @emph{See also}:
1176 Fortran 95 elemental function: @ref{IAND}
1182 @section @code{ANINT} --- Nearest whole number
1186 @cindex rounding, ceiling
1189 @item @emph{Description}:
1190 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1192 @item @emph{Standard}:
1193 Fortran 77 and later
1198 @item @emph{Syntax}:
1199 @code{RESULT = ANINT(A [, KIND])}
1201 @item @emph{Arguments}:
1202 @multitable @columnfractions .15 .70
1203 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1204 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1205 expression indicating the kind parameter of the result.
1208 @item @emph{Return value}:
1209 The return value is of type real with the kind type parameter of the
1210 argument if the optional @var{KIND} is absent; otherwise, the kind
1211 type parameter will be given by @var{KIND}. If @var{A} is greater than
1212 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1213 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1215 @item @emph{Example}:
1222 print *, anint(x4), dnint(x8)
1224 end program test_anint
1227 @item @emph{Specific names}:
1228 @multitable @columnfractions .20 .20 .20 .25
1229 @item Name @tab Argument @tab Return type @tab Standard
1230 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
1231 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1238 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1240 @cindex array, apply condition
1241 @cindex array, condition testing
1244 @item @emph{Description}:
1245 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1246 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1248 @item @emph{Standard}:
1249 Fortran 95 and later
1252 Transformational function
1254 @item @emph{Syntax}:
1255 @code{RESULT = ANY(MASK [, DIM])}
1257 @item @emph{Arguments}:
1258 @multitable @columnfractions .15 .70
1259 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1260 it shall not be scalar.
1261 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1262 with a value that lies between one and the rank of @var{MASK}.
1265 @item @emph{Return value}:
1266 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1267 the kind type parameter is the same as the kind type parameter of
1268 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1269 an array with the rank of @var{MASK} minus 1. The shape is determined from
1270 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1274 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1275 otherwise, it is false. It also is false if @var{MASK} has zero size.
1277 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1278 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1279 is determined by applying @code{ANY} to the array sections.
1282 @item @emph{Example}:
1286 l = any((/.true., .true., .true./))
1291 integer a(2,3), b(2,3)
1295 print *, any(a .eq. b, 1)
1296 print *, any(a .eq. b, 2)
1297 end subroutine section
1298 end program test_any
1305 @section @code{ASIN} --- Arcsine function
1308 @cindex trigonometric function, sine, inverse
1309 @cindex sine, inverse
1312 @item @emph{Description}:
1313 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1315 @item @emph{Standard}:
1316 Fortran 77 and later, for a complex argument Fortran 2008 or later
1321 @item @emph{Syntax}:
1322 @code{RESULT = ASIN(X)}
1324 @item @emph{Arguments}:
1325 @multitable @columnfractions .15 .70
1326 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1327 less than or equal to one - or be @code{COMPLEX}.
1330 @item @emph{Return value}:
1331 The return value is of the same type and kind as @var{X}.
1332 The real part of the result is in radians and lies in the range
1333 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1335 @item @emph{Example}:
1338 real(8) :: x = 0.866_8
1340 end program test_asin
1343 @item @emph{Specific names}:
1344 @multitable @columnfractions .20 .20 .20 .25
1345 @item Name @tab Argument @tab Return type @tab Standard
1346 @item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1347 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1350 @item @emph{See also}:
1351 Inverse function: @ref{SIN}
1352 Degrees function: @ref{ASIND}
1359 @section @code{ASIND} --- Arcsine function, degrees
1362 @cindex trigonometric function, sine, inverse, degrees
1363 @cindex sine, inverse, degrees
1366 @item @emph{Description}:
1367 @code{ASIND(X)} computes the arcsine of its @var{X} in degrees (inverse of
1370 This function is for compatibility only and should be avoided in favor of
1371 standard constructs wherever possible.
1373 @item @emph{Standard}:
1374 GNU Extension, enabled with @option{-fdec-math}.
1379 @item @emph{Syntax}:
1380 @code{RESULT = ASIND(X)}
1382 @item @emph{Arguments}:
1383 @multitable @columnfractions .15 .70
1384 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1385 less than or equal to one - or be @code{COMPLEX}.
1388 @item @emph{Return value}:
1389 The return value is of the same type and kind as @var{X}.
1390 The real part of the result is in degrees and lies in the range
1391 @math{-90 \leq \Re \asin(x) \leq 90}.
1393 @item @emph{Example}:
1396 real(8) :: x = 0.866_8
1398 end program test_asind
1401 @item @emph{Specific names}:
1402 @multitable @columnfractions .20 .20 .20 .25
1403 @item Name @tab Argument @tab Return type @tab Standard
1404 @item @code{ASIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
1405 @item @code{DASIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
1408 @item @emph{See also}:
1409 Inverse function: @ref{SIND}
1410 Radians function: @ref{ASIN}
1417 @section @code{ASINH} --- Inverse hyperbolic sine function
1420 @cindex area hyperbolic sine
1421 @cindex inverse hyperbolic sine
1422 @cindex hyperbolic function, sine, inverse
1423 @cindex sine, hyperbolic, inverse
1426 @item @emph{Description}:
1427 @code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
1429 @item @emph{Standard}:
1430 Fortran 2008 and later
1435 @item @emph{Syntax}:
1436 @code{RESULT = ASINH(X)}
1438 @item @emph{Arguments}:
1439 @multitable @columnfractions .15 .70
1440 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1443 @item @emph{Return value}:
1444 The return value is of the same type and kind as @var{X}. If @var{X} is
1445 complex, the imaginary part of the result is in radians and lies between
1446 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1448 @item @emph{Example}:
1451 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1452 WRITE (*,*) ASINH(x)
1456 @item @emph{Specific names}:
1457 @multitable @columnfractions .20 .20 .20 .25
1458 @item Name @tab Argument @tab Return type @tab Standard
1459 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1462 @item @emph{See also}:
1463 Inverse function: @ref{SINH}
1469 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1471 @cindex pointer, status
1472 @cindex association status
1475 @item @emph{Description}:
1476 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1477 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1479 @item @emph{Standard}:
1480 Fortran 95 and later
1485 @item @emph{Syntax}:
1486 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1488 @item @emph{Arguments}:
1489 @multitable @columnfractions .15 .70
1490 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1491 and it can be of any type.
1492 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1493 a target. It must have the same type, kind type parameter, and
1494 array rank as @var{POINTER}.
1496 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1499 @item @emph{Return value}:
1500 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1501 There are several cases:
1503 @item (A) When the optional @var{TARGET} is not present then
1504 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1505 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1506 @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
1507 disassociated, the result is false.
1508 @item (C) If @var{TARGET} is present and an array target, the result is true if
1509 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1510 are arrays whose elements are not zero-sized storage sequences, and
1511 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1513 As in case(B), the result is false, if @var{POINTER} is disassociated.
1514 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1515 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1516 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1518 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1519 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1520 target associated with @var{POINTER} and the target associated with @var{TARGET}
1521 have the same shape, are not zero-sized arrays, are arrays whose elements are
1522 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1523 the same storage units in array element order.
1524 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1527 @item @emph{Example}:
1529 program test_associated
1531 real, target :: tgt(2) = (/1., 2./)
1532 real, pointer :: ptr(:)
1534 if (associated(ptr) .eqv. .false.) call abort
1535 if (associated(ptr,tgt) .eqv. .false.) call abort
1536 end program test_associated
1539 @item @emph{See also}:
1546 @section @code{ATAN} --- Arctangent function
1549 @cindex trigonometric function, tangent, inverse
1550 @cindex tangent, inverse
1553 @item @emph{Description}:
1554 @code{ATAN(X)} computes the arctangent of @var{X}.
1556 @item @emph{Standard}:
1557 Fortran 77 and later, for a complex argument and for two arguments
1558 Fortran 2008 or later
1563 @item @emph{Syntax}:
1564 @multitable @columnfractions .80
1565 @item @code{RESULT = ATAN(X)}
1566 @item @code{RESULT = ATAN(Y, X)}
1569 @item @emph{Arguments}:
1570 @multitable @columnfractions .15 .70
1571 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1572 if @var{Y} is present, @var{X} shall be REAL.
1573 @item @var{Y} shall be of the same type and kind as @var{X}.
1576 @item @emph{Return value}:
1577 The return value is of the same type and kind as @var{X}.
1578 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1579 Otherwise, it the arcus tangent of @var{X}, where the real part of
1580 the result is in radians and lies in the range
1581 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1583 @item @emph{Example}:
1586 real(8) :: x = 2.866_8
1588 end program test_atan
1591 @item @emph{Specific names}:
1592 @multitable @columnfractions .20 .20 .20 .25
1593 @item Name @tab Argument @tab Return type @tab Standard
1594 @item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1595 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1598 @item @emph{See also}:
1599 Inverse function: @ref{TAN}
1600 Degrees function: @ref{ATAND}
1607 @section @code{ATAND} --- Arctangent function, degrees
1610 @cindex trigonometric function, tangent, inverse, degrees
1611 @cindex tangent, inverse, degrees
1614 @item @emph{Description}:
1615 @code{ATAND(X)} computes the arctangent of @var{X} in degrees (inverse of
1618 This function is for compatibility only and should be avoided in favor of
1619 standard constructs wherever possible.
1621 @item @emph{Standard}:
1622 GNU Extension, enabled with @option{-fdec-math}.
1627 @item @emph{Syntax}:
1628 @multitable @columnfractions .80
1629 @item @code{RESULT = ATAND(X)}
1630 @item @code{RESULT = ATAND(Y, X)}
1633 @item @emph{Arguments}:
1634 @multitable @columnfractions .15 .70
1635 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1636 if @var{Y} is present, @var{X} shall be REAL.
1637 @item @var{Y} shall be of the same type and kind as @var{X}.
1640 @item @emph{Return value}:
1641 The return value is of the same type and kind as @var{X}.
1642 If @var{Y} is present, the result is identical to @code{ATAND2(Y,X)}.
1643 Otherwise, it is the arcus tangent of @var{X}, where the real part of
1644 the result is in degrees and lies in the range
1645 @math{-90 \leq \Re \atand(x) \leq 90}.
1647 @item @emph{Example}:
1650 real(8) :: x = 2.866_8
1652 end program test_atand
1655 @item @emph{Specific names}:
1656 @multitable @columnfractions .20 .20 .20 .25
1657 @item Name @tab Argument @tab Return type @tab Standard
1658 @item @code{ATAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
1659 @item @code{DATAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
1662 @item @emph{See also}:
1663 Inverse function: @ref{TAND}
1664 Radians function: @ref{ATAN}
1671 @section @code{ATAN2} --- Arctangent function
1674 @cindex trigonometric function, tangent, inverse
1675 @cindex tangent, inverse
1678 @item @emph{Description}:
1679 @code{ATAN2(Y, X)} computes the principal value of the argument
1680 function of the complex number @math{X + i Y}. This function can
1681 be used to transform from Cartesian into polar coordinates and
1682 allows to determine the angle in the correct quadrant.
1684 @item @emph{Standard}:
1685 Fortran 77 and later
1690 @item @emph{Syntax}:
1691 @code{RESULT = ATAN2(Y, X)}
1693 @item @emph{Arguments}:
1694 @multitable @columnfractions .15 .70
1695 @item @var{Y} @tab The type shall be @code{REAL}.
1696 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1697 If @var{Y} is zero, then @var{X} must be nonzero.
1700 @item @emph{Return value}:
1701 The return value has the same type and kind type parameter as @var{Y}. It
1702 is the principal value of the complex number @math{X + i Y}. If @var{X}
1703 is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1704 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1705 the return value is zero if @var{X} is strictly positive, @math{\pi} if
1706 @var{X} is negative and @var{Y} is positive zero (or the processor does
1707 not handle signed zeros), and @math{-\pi} if @var{X} is negative and
1708 @var{Y} is negative zero. Finally, if @var{X} is zero, then the
1709 magnitude of the result is @math{\pi/2}.
1711 @item @emph{Example}:
1714 real(4) :: x = 1.e0_4, y = 0.5e0_4
1716 end program test_atan2
1719 @item @emph{Specific names}:
1720 @multitable @columnfractions .20 .20 .20 .25
1721 @item Name @tab Argument @tab Return type @tab Standard
1722 @item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1723 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1726 @item @emph{See also}:
1728 Degrees function: @ref{ATAN2D}
1735 @section @code{ATAN2D} --- Arctangent function, degrees
1738 @cindex trigonometric function, tangent, inverse, degrees
1739 @cindex tangent, inverse, degrees
1742 @item @emph{Description}:
1743 @code{ATAN2D(Y, X)} computes the principal value of the argument
1744 function of the complex number @math{X + i Y} in degrees. This function can
1745 be used to transform from Cartesian into polar coordinates and
1746 allows to determine the angle in the correct quadrant.
1748 This function is for compatibility only and should be avoided in favor of
1749 standard constructs wherever possible.
1751 @item @emph{Standard}:
1752 GNU Extension, enabled with @option{-fdec-math}.
1757 @item @emph{Syntax}:
1758 @code{RESULT = ATAN2D(Y, X)}
1760 @item @emph{Arguments}:
1761 @multitable @columnfractions .15 .70
1762 @item @var{Y} @tab The type shall be @code{REAL}.
1763 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1764 If @var{Y} is zero, then @var{X} must be nonzero.
1767 @item @emph{Return value}:
1768 The return value has the same type and kind type parameter as @var{Y}. It
1769 is the principal value of the complex number @math{X + i Y}. If @var{X}
1770 is nonzero, then it lies in the range @math{-180 \le \atan (x) \leq 180}.
1771 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1772 the return value is zero if @var{X} is strictly positive, @math{180} if
1773 @var{X} is negative and @var{Y} is positive zero (or the processor does
1774 not handle signed zeros), and @math{-180} if @var{X} is negative and
1775 @var{Y} is negative zero. Finally, if @var{X} is zero, then the
1776 magnitude of the result is @math{90}.
1778 @item @emph{Example}:
1781 real(4) :: x = 1.e0_4, y = 0.5e0_4
1783 end program test_atan2d
1786 @item @emph{Specific names}:
1787 @multitable @columnfractions .20 .20 .20 .25
1788 @item Name @tab Argument @tab Return type @tab Standard
1789 @item @code{ATAN2D(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab GNU Extension
1790 @item @code{DATAN2D(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab GNU Extension
1793 @item @emph{See also}:
1795 Radians function: @ref{ATAN2}
1802 @section @code{ATANH} --- Inverse hyperbolic tangent function
1805 @cindex area hyperbolic tangent
1806 @cindex inverse hyperbolic tangent
1807 @cindex hyperbolic function, tangent, inverse
1808 @cindex tangent, hyperbolic, inverse
1811 @item @emph{Description}:
1812 @code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
1814 @item @emph{Standard}:
1815 Fortran 2008 and later
1820 @item @emph{Syntax}:
1821 @code{RESULT = ATANH(X)}
1823 @item @emph{Arguments}:
1824 @multitable @columnfractions .15 .70
1825 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1828 @item @emph{Return value}:
1829 The return value has same type and kind as @var{X}. If @var{X} is
1830 complex, the imaginary part of the result is in radians and lies between
1831 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1833 @item @emph{Example}:
1836 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1837 WRITE (*,*) ATANH(x)
1841 @item @emph{Specific names}:
1842 @multitable @columnfractions .20 .20 .20 .25
1843 @item Name @tab Argument @tab Return type @tab Standard
1844 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1847 @item @emph{See also}:
1848 Inverse function: @ref{TANH}
1854 @section @code{ATOMIC_ADD} --- Atomic ADD operation
1856 @cindex Atomic subroutine, add
1859 @item @emph{Description}:
1860 @code{ATOMIC_ADD(ATOM, VALUE)} atomically adds the value of @var{VAR} to the
1861 variable @var{ATOM}. When @var{STAT} is present and the invocation was
1862 successful, it is assigned the value 0. If it is present and the invocation
1863 has failed, it is assigned a positive value; in particular, for a coindexed
1864 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1865 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1866 failed, the value @code{STAT_FAILED_IMAGE}.
1868 @item @emph{Standard}:
1874 @item @emph{Syntax}:
1875 @code{CALL ATOMIC_ADD (ATOM, VALUE [, STAT])}
1877 @item @emph{Arguments}:
1878 @multitable @columnfractions .15 .70
1879 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1880 type with @code{ATOMIC_INT_KIND} kind.
1881 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1882 is different, the value is converted to the kind of @var{ATOM}.
1883 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1886 @item @emph{Example}:
1890 integer(atomic_int_kind) :: atom[*]
1891 call atomic_add (atom[1], this_image())
1895 @item @emph{See also}:
1896 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_ADD}, @ref{ISO_FORTRAN_ENV},
1897 @ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
1904 @section @code{ATOMIC_AND} --- Atomic bitwise AND operation
1906 @cindex Atomic subroutine, AND
1909 @item @emph{Description}:
1910 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
1911 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
1912 and the invocation was successful, it is assigned the value 0. If it is present
1913 and the invocation has failed, it is assigned a positive value; in particular,
1914 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
1915 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
1916 image has failed, the value @code{STAT_FAILED_IMAGE}.
1918 @item @emph{Standard}:
1924 @item @emph{Syntax}:
1925 @code{CALL ATOMIC_AND (ATOM, VALUE [, STAT])}
1927 @item @emph{Arguments}:
1928 @multitable @columnfractions .15 .70
1929 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1930 type with @code{ATOMIC_INT_KIND} kind.
1931 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1932 is different, the value is converted to the kind of @var{ATOM}.
1933 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1936 @item @emph{Example}:
1940 integer(atomic_int_kind) :: atom[*]
1941 call atomic_and (atom[1], int(b'10100011101'))
1945 @item @emph{See also}:
1946 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_AND}, @ref{ISO_FORTRAN_ENV},
1947 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
1953 @section @code{ATOMIC_CAS} --- Atomic compare and swap
1954 @fnindex ATOMIC_DEFINE
1955 @cindex Atomic subroutine, compare and swap
1958 @item @emph{Description}:
1959 @code{ATOMIC_CAS} compares the variable @var{ATOM} with the value of
1960 @var{COMPARE}; if the value is the same, @var{ATOM} is set to the value
1961 of @var{NEW}. Additionally, @var{OLD} is set to the value of @var{ATOM}
1962 that was used for the comparison. When @var{STAT} is present and the invocation
1963 was successful, it is assigned the value 0. If it is present and the invocation
1964 has failed, it is assigned a positive value; in particular, for a coindexed
1965 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1966 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1967 failed, the value @code{STAT_FAILED_IMAGE}.
1969 @item @emph{Standard}:
1975 @item @emph{Syntax}:
1976 @code{CALL ATOMIC_CAS (ATOM, OLD, COMPARE, NEW [, STAT])}
1978 @item @emph{Arguments}:
1979 @multitable @columnfractions .15 .70
1980 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
1981 type with @code{ATOMIC_INT_KIND} kind or logical type with
1982 @code{ATOMIC_LOGICAL_KIND} kind.
1983 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1984 @item @var{COMPARE} @tab Scalar variable of the same type and kind as
1986 @item @var{NEW} @tab Scalar variable of the same type as @var{ATOM}. If kind
1987 is different, the value is converted to the kind of @var{ATOM}.
1988 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1991 @item @emph{Example}:
1995 logical(atomic_logical_kind) :: atom[*], prev
1996 call atomic_cas (atom[1], prev, .false., .true.))
2000 @item @emph{See also}:
2001 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_REF}, @ref{ISO_FORTRAN_ENV}
2007 @section @code{ATOMIC_DEFINE} --- Setting a variable atomically
2008 @fnindex ATOMIC_DEFINE
2009 @cindex Atomic subroutine, define
2012 @item @emph{Description}:
2013 @code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value
2014 @var{VALUE} atomically. When @var{STAT} is present and the invocation was
2015 successful, it is assigned the value 0. If it is present and the invocation
2016 has failed, it is assigned a positive value; in particular, for a coindexed
2017 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2018 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2019 failed, the value @code{STAT_FAILED_IMAGE}.
2021 @item @emph{Standard}:
2022 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
2027 @item @emph{Syntax}:
2028 @code{CALL ATOMIC_DEFINE (ATOM, VALUE [, STAT])}
2030 @item @emph{Arguments}:
2031 @multitable @columnfractions .15 .70
2032 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
2033 type with @code{ATOMIC_INT_KIND} kind or logical type with
2034 @code{ATOMIC_LOGICAL_KIND} kind.
2036 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2037 is different, the value is converted to the kind of @var{ATOM}.
2038 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2041 @item @emph{Example}:
2045 integer(atomic_int_kind) :: atom[*]
2046 call atomic_define (atom[1], this_image())
2050 @item @emph{See also}:
2051 @ref{ATOMIC_REF}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV},
2052 @ref{ATOMIC_ADD}, @ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
2057 @node ATOMIC_FETCH_ADD
2058 @section @code{ATOMIC_FETCH_ADD} --- Atomic ADD operation with prior fetch
2059 @fnindex ATOMIC_FETCH_ADD
2060 @cindex Atomic subroutine, ADD with fetch
2063 @item @emph{Description}:
2064 @code{ATOMIC_FETCH_ADD(ATOM, VALUE, OLD)} atomically stores the value of
2065 @var{ATOM} in @var{OLD} and adds the value of @var{VAR} to the
2066 variable @var{ATOM}. When @var{STAT} is present and the invocation was
2067 successful, it is assigned the value 0. If it is present and the invocation
2068 has failed, it is assigned a positive value; in particular, for a coindexed
2069 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2070 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2071 failed, the value @code{STAT_FAILED_IMAGE}.
2073 @item @emph{Standard}:
2079 @item @emph{Syntax}:
2080 @code{CALL ATOMIC_FETCH_ADD (ATOM, VALUE, old [, STAT])}
2082 @item @emph{Arguments}:
2083 @multitable @columnfractions .15 .70
2084 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2085 type with @code{ATOMIC_INT_KIND} kind.
2086 @code{ATOMIC_LOGICAL_KIND} kind.
2088 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2089 is different, the value is converted to the kind of @var{ATOM}.
2090 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2091 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2094 @item @emph{Example}:
2098 integer(atomic_int_kind) :: atom[*], old
2099 call atomic_add (atom[1], this_image(), old)
2103 @item @emph{See also}:
2104 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_ADD}, @ref{ISO_FORTRAN_ENV},
2105 @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR}
2110 @node ATOMIC_FETCH_AND
2111 @section @code{ATOMIC_FETCH_AND} --- Atomic bitwise AND operation with prior fetch
2112 @fnindex ATOMIC_FETCH_AND
2113 @cindex Atomic subroutine, AND with fetch
2116 @item @emph{Description}:
2117 @code{ATOMIC_AND(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2118 @var{OLD} and defines @var{ATOM} with the bitwise AND between the values of
2119 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
2120 successful, it is assigned the value 0. If it is present and the invocation has
2121 failed, it is assigned a positive value; in particular, for a coindexed
2122 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2123 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2124 failed, the value @code{STAT_FAILED_IMAGE}.
2126 @item @emph{Standard}:
2132 @item @emph{Syntax}:
2133 @code{CALL ATOMIC_FETCH_AND (ATOM, VALUE, OLD [, STAT])}
2135 @item @emph{Arguments}:
2136 @multitable @columnfractions .15 .70
2137 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2138 type with @code{ATOMIC_INT_KIND} kind.
2139 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2140 is different, the value is converted to the kind of @var{ATOM}.
2141 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2142 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2145 @item @emph{Example}:
2149 integer(atomic_int_kind) :: atom[*], old
2150 call atomic_fetch_and (atom[1], int(b'10100011101'), old)
2154 @item @emph{See also}:
2155 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_AND}, @ref{ISO_FORTRAN_ENV},
2156 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR}
2161 @node ATOMIC_FETCH_OR
2162 @section @code{ATOMIC_FETCH_OR} --- Atomic bitwise OR operation with prior fetch
2163 @fnindex ATOMIC_FETCH_OR
2164 @cindex Atomic subroutine, OR with fetch
2167 @item @emph{Description}:
2168 @code{ATOMIC_OR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2169 @var{OLD} and defines @var{ATOM} with the bitwise OR between the values of
2170 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
2171 successful, it is assigned the value 0. If it is present and the invocation has
2172 failed, it is assigned a positive value; in particular, for a coindexed
2173 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2174 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2175 failed, the value @code{STAT_FAILED_IMAGE}.
2177 @item @emph{Standard}:
2183 @item @emph{Syntax}:
2184 @code{CALL ATOMIC_FETCH_OR (ATOM, VALUE, OLD [, STAT])}
2186 @item @emph{Arguments}:
2187 @multitable @columnfractions .15 .70
2188 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2189 type with @code{ATOMIC_INT_KIND} kind.
2190 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2191 is different, the value is converted to the kind of @var{ATOM}.
2192 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2193 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2196 @item @emph{Example}:
2200 integer(atomic_int_kind) :: atom[*], old
2201 call atomic_fetch_or (atom[1], int(b'10100011101'), old)
2205 @item @emph{See also}:
2206 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_OR}, @ref{ISO_FORTRAN_ENV},
2207 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_XOR}
2212 @node ATOMIC_FETCH_XOR
2213 @section @code{ATOMIC_FETCH_XOR} --- Atomic bitwise XOR operation with prior fetch
2214 @fnindex ATOMIC_FETCH_XOR
2215 @cindex Atomic subroutine, XOR with fetch
2218 @item @emph{Description}:
2219 @code{ATOMIC_XOR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2220 @var{OLD} and defines @var{ATOM} with the bitwise XOR between the values of
2221 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
2222 successful, it is assigned the value 0. If it is present and the invocation has
2223 failed, it is assigned a positive value; in particular, for a coindexed
2224 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2225 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2226 failed, the value @code{STAT_FAILED_IMAGE}.
2228 @item @emph{Standard}:
2234 @item @emph{Syntax}:
2235 @code{CALL ATOMIC_FETCH_XOR (ATOM, VALUE, OLD [, STAT])}
2237 @item @emph{Arguments}:
2238 @multitable @columnfractions .15 .70
2239 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2240 type with @code{ATOMIC_INT_KIND} kind.
2241 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2242 is different, the value is converted to the kind of @var{ATOM}.
2243 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2244 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2247 @item @emph{Example}:
2251 integer(atomic_int_kind) :: atom[*], old
2252 call atomic_fetch_xor (atom[1], int(b'10100011101'), old)
2256 @item @emph{See also}:
2257 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_XOR}, @ref{ISO_FORTRAN_ENV},
2258 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}
2264 @section @code{ATOMIC_OR} --- Atomic bitwise OR operation
2266 @cindex Atomic subroutine, OR
2269 @item @emph{Description}:
2270 @code{ATOMIC_OR(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
2271 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
2272 and the invocation was successful, it is assigned the value 0. If it is present
2273 and the invocation has failed, it is assigned a positive value; in particular,
2274 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
2275 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
2276 image has failed, the value @code{STAT_FAILED_IMAGE}.
2278 @item @emph{Standard}:
2284 @item @emph{Syntax}:
2285 @code{CALL ATOMIC_OR (ATOM, VALUE [, STAT])}
2287 @item @emph{Arguments}:
2288 @multitable @columnfractions .15 .70
2289 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2290 type with @code{ATOMIC_INT_KIND} kind.
2291 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2292 is different, the value is converted to the kind of @var{ATOM}.
2293 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2296 @item @emph{Example}:
2300 integer(atomic_int_kind) :: atom[*]
2301 call atomic_or (atom[1], int(b'10100011101'))
2305 @item @emph{See also}:
2306 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_OR}, @ref{ISO_FORTRAN_ENV},
2307 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
2313 @section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically
2315 @cindex Atomic subroutine, reference
2318 @item @emph{Description}:
2319 @code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the
2320 variable @var{ATOM} to @var{VALUE}. When @var{STAT} is present and the
2321 invocation was successful, it is assigned the value 0. If it is present and the
2322 invocation has failed, it is assigned a positive value; in particular, for a
2323 coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value
2324 of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image
2325 has failed, the value @code{STAT_FAILED_IMAGE}.
2328 @item @emph{Standard}:
2329 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
2334 @item @emph{Syntax}:
2335 @code{CALL ATOMIC_REF(VALUE, ATOM [, STAT])}
2337 @item @emph{Arguments}:
2338 @multitable @columnfractions .15 .70
2339 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2340 is different, the value is converted to the kind of @var{ATOM}.
2341 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
2342 type with @code{ATOMIC_INT_KIND} kind or logical type with
2343 @code{ATOMIC_LOGICAL_KIND} kind.
2344 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2347 @item @emph{Example}:
2351 logical(atomic_logical_kind) :: atom[*]
2353 call atomic_ref (atom, .false.)
2355 call atomic_ref (atom, val)
2362 @item @emph{See also}:
2363 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV},
2364 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR},
2365 @ref{ATOMIC_FETCH_XOR}
2370 @section @code{ATOMIC_XOR} --- Atomic bitwise OR operation
2372 @cindex Atomic subroutine, XOR
2375 @item @emph{Description}:
2376 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
2377 XOR between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
2378 and the invocation was successful, it is assigned the value 0. If it is present
2379 and the invocation has failed, it is assigned a positive value; in particular,
2380 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
2381 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
2382 image has failed, the value @code{STAT_FAILED_IMAGE}.
2384 @item @emph{Standard}:
2390 @item @emph{Syntax}:
2391 @code{CALL ATOMIC_XOR (ATOM, VALUE [, STAT])}
2393 @item @emph{Arguments}:
2394 @multitable @columnfractions .15 .70
2395 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2396 type with @code{ATOMIC_INT_KIND} kind.
2397 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2398 is different, the value is converted to the kind of @var{ATOM}.
2399 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2402 @item @emph{Example}:
2406 integer(atomic_int_kind) :: atom[*]
2407 call atomic_xor (atom[1], int(b'10100011101'))
2411 @item @emph{See also}:
2412 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_XOR}, @ref{ISO_FORTRAN_ENV},
2413 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
2418 @section @code{BACKTRACE} --- Show a backtrace
2423 @item @emph{Description}:
2424 @code{BACKTRACE} shows a backtrace at an arbitrary place in user code. Program
2425 execution continues normally afterwards. The backtrace information is printed
2426 to the unit corresponding to @code{ERROR_UNIT} in @code{ISO_FORTRAN_ENV}.
2428 @item @emph{Standard}:
2434 @item @emph{Syntax}:
2435 @code{CALL BACKTRACE}
2437 @item @emph{Arguments}:
2440 @item @emph{See also}:
2447 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
2451 @cindex Bessel function, first kind
2454 @item @emph{Description}:
2455 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
2456 order 0 of @var{X}. This function is available under the name
2457 @code{BESJ0} as a GNU extension.
2459 @item @emph{Standard}:
2460 Fortran 2008 and later
2465 @item @emph{Syntax}:
2466 @code{RESULT = BESSEL_J0(X)}
2468 @item @emph{Arguments}:
2469 @multitable @columnfractions .15 .70
2470 @item @var{X} @tab The type shall be @code{REAL}.
2473 @item @emph{Return value}:
2474 The return value is of type @code{REAL} and lies in the
2475 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
2478 @item @emph{Example}:
2481 real(8) :: x = 0.0_8
2483 end program test_besj0
2486 @item @emph{Specific names}:
2487 @multitable @columnfractions .20 .20 .20 .25
2488 @item Name @tab Argument @tab Return type @tab Standard
2489 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2496 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
2500 @cindex Bessel function, first kind
2503 @item @emph{Description}:
2504 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
2505 order 1 of @var{X}. This function is available under the name
2506 @code{BESJ1} as a GNU extension.
2508 @item @emph{Standard}:
2514 @item @emph{Syntax}:
2515 @code{RESULT = BESSEL_J1(X)}
2517 @item @emph{Arguments}:
2518 @multitable @columnfractions .15 .70
2519 @item @var{X} @tab The type shall be @code{REAL}.
2522 @item @emph{Return value}:
2523 The return value is of type @code{REAL} and lies in the
2524 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
2527 @item @emph{Example}:
2530 real(8) :: x = 1.0_8
2532 end program test_besj1
2535 @item @emph{Specific names}:
2536 @multitable @columnfractions .20 .20 .20 .25
2537 @item Name @tab Argument @tab Return type @tab Standard
2538 @item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2545 @section @code{BESSEL_JN} --- Bessel function of the first kind
2549 @cindex Bessel function, first kind
2552 @item @emph{Description}:
2553 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
2554 order @var{N} of @var{X}. This function is available under the name
2555 @code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays,
2556 their ranks and shapes shall conform.
2558 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
2559 of the first kind of the orders @var{N1} to @var{N2}.
2561 @item @emph{Standard}:
2562 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2565 Elemental function, except for the transformational function
2566 @code{BESSEL_JN(N1, N2, X)}
2568 @item @emph{Syntax}:
2569 @multitable @columnfractions .80
2570 @item @code{RESULT = BESSEL_JN(N, X)}
2571 @item @code{RESULT = BESSEL_JN(N1, N2, X)}
2574 @item @emph{Arguments}:
2575 @multitable @columnfractions .15 .70
2576 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
2577 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2578 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2579 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2580 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
2583 @item @emph{Return value}:
2584 The return value is a scalar of type @code{REAL}. It has the same
2588 The transformational function uses a recurrence algorithm which might,
2589 for some values of @var{X}, lead to different results than calls to
2590 the elemental function.
2592 @item @emph{Example}:
2595 real(8) :: x = 1.0_8
2597 end program test_besjn
2600 @item @emph{Specific names}:
2601 @multitable @columnfractions .20 .20 .20 .25
2602 @item Name @tab Argument @tab Return type @tab Standard
2603 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2604 @item @tab @code{REAL(8) X} @tab @tab
2611 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
2615 @cindex Bessel function, second kind
2618 @item @emph{Description}:
2619 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
2620 order 0 of @var{X}. This function is available under the name
2621 @code{BESY0} as a GNU extension.
2623 @item @emph{Standard}:
2624 Fortran 2008 and later
2629 @item @emph{Syntax}:
2630 @code{RESULT = BESSEL_Y0(X)}
2632 @item @emph{Arguments}:
2633 @multitable @columnfractions .15 .70
2634 @item @var{X} @tab The type shall be @code{REAL}.
2637 @item @emph{Return value}:
2638 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2640 @item @emph{Example}:
2643 real(8) :: x = 0.0_8
2645 end program test_besy0
2648 @item @emph{Specific names}:
2649 @multitable @columnfractions .20 .20 .20 .25
2650 @item Name @tab Argument @tab Return type @tab Standard
2651 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2658 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
2662 @cindex Bessel function, second kind
2665 @item @emph{Description}:
2666 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
2667 order 1 of @var{X}. This function is available under the name
2668 @code{BESY1} as a GNU extension.
2670 @item @emph{Standard}:
2671 Fortran 2008 and later
2676 @item @emph{Syntax}:
2677 @code{RESULT = BESSEL_Y1(X)}
2679 @item @emph{Arguments}:
2680 @multitable @columnfractions .15 .70
2681 @item @var{X} @tab The type shall be @code{REAL}.
2684 @item @emph{Return value}:
2685 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2687 @item @emph{Example}:
2690 real(8) :: x = 1.0_8
2692 end program test_besy1
2695 @item @emph{Specific names}:
2696 @multitable @columnfractions .20 .20 .20 .25
2697 @item Name @tab Argument @tab Return type @tab Standard
2698 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2705 @section @code{BESSEL_YN} --- Bessel function of the second kind
2709 @cindex Bessel function, second kind
2712 @item @emph{Description}:
2713 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
2714 order @var{N} of @var{X}. This function is available under the name
2715 @code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays,
2716 their ranks and shapes shall conform.
2718 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
2719 of the first kind of the orders @var{N1} to @var{N2}.
2721 @item @emph{Standard}:
2722 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2725 Elemental function, except for the transformational function
2726 @code{BESSEL_YN(N1, N2, X)}
2728 @item @emph{Syntax}:
2729 @multitable @columnfractions .80
2730 @item @code{RESULT = BESSEL_YN(N, X)}
2731 @item @code{RESULT = BESSEL_YN(N1, N2, X)}
2734 @item @emph{Arguments}:
2735 @multitable @columnfractions .15 .70
2736 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} .
2737 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2738 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2739 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2740 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
2743 @item @emph{Return value}:
2744 The return value is a scalar of type @code{REAL}. It has the same
2748 The transformational function uses a recurrence algorithm which might,
2749 for some values of @var{X}, lead to different results than calls to
2750 the elemental function.
2752 @item @emph{Example}:
2755 real(8) :: x = 1.0_8
2757 end program test_besyn
2760 @item @emph{Specific names}:
2761 @multitable @columnfractions .20 .20 .20 .25
2762 @item Name @tab Argument @tab Return type @tab Standard
2763 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2764 @item @tab @code{REAL(8) X} @tab @tab
2771 @section @code{BGE} --- Bitwise greater than or equal to
2773 @cindex bitwise comparison
2776 @item @emph{Description}:
2777 Determines whether an integral is a bitwise greater than or equal to
2780 @item @emph{Standard}:
2781 Fortran 2008 and later
2786 @item @emph{Syntax}:
2787 @code{RESULT = BGE(I, J)}
2789 @item @emph{Arguments}:
2790 @multitable @columnfractions .15 .70
2791 @item @var{I} @tab Shall be of @code{INTEGER} type.
2792 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2796 @item @emph{Return value}:
2797 The return value is of type @code{LOGICAL} and of the default kind.
2799 @item @emph{See also}:
2800 @ref{BGT}, @ref{BLE}, @ref{BLT}
2806 @section @code{BGT} --- Bitwise greater than
2808 @cindex bitwise comparison
2811 @item @emph{Description}:
2812 Determines whether an integral is a bitwise greater than another.
2814 @item @emph{Standard}:
2815 Fortran 2008 and later
2820 @item @emph{Syntax}:
2821 @code{RESULT = BGT(I, J)}
2823 @item @emph{Arguments}:
2824 @multitable @columnfractions .15 .70
2825 @item @var{I} @tab Shall be of @code{INTEGER} type.
2826 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2830 @item @emph{Return value}:
2831 The return value is of type @code{LOGICAL} and of the default kind.
2833 @item @emph{See also}:
2834 @ref{BGE}, @ref{BLE}, @ref{BLT}
2840 @section @code{BIT_SIZE} --- Bit size inquiry function
2842 @cindex bits, number of
2843 @cindex size of a variable, in bits
2846 @item @emph{Description}:
2847 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
2848 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
2849 independent of the actual value of @var{I}.
2851 @item @emph{Standard}:
2852 Fortran 95 and later
2857 @item @emph{Syntax}:
2858 @code{RESULT = BIT_SIZE(I)}
2860 @item @emph{Arguments}:
2861 @multitable @columnfractions .15 .70
2862 @item @var{I} @tab The type shall be @code{INTEGER}.
2865 @item @emph{Return value}:
2866 The return value is of type @code{INTEGER}
2868 @item @emph{Example}:
2870 program test_bit_size
2875 end program test_bit_size
2882 @section @code{BLE} --- Bitwise less than or equal to
2884 @cindex bitwise comparison
2887 @item @emph{Description}:
2888 Determines whether an integral is a bitwise less than or equal to
2891 @item @emph{Standard}:
2892 Fortran 2008 and later
2897 @item @emph{Syntax}:
2898 @code{RESULT = BLE(I, J)}
2900 @item @emph{Arguments}:
2901 @multitable @columnfractions .15 .70
2902 @item @var{I} @tab Shall be of @code{INTEGER} type.
2903 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2907 @item @emph{Return value}:
2908 The return value is of type @code{LOGICAL} and of the default kind.
2910 @item @emph{See also}:
2911 @ref{BGT}, @ref{BGE}, @ref{BLT}
2917 @section @code{BLT} --- Bitwise less than
2919 @cindex bitwise comparison
2922 @item @emph{Description}:
2923 Determines whether an integral is a bitwise less than another.
2925 @item @emph{Standard}:
2926 Fortran 2008 and later
2931 @item @emph{Syntax}:
2932 @code{RESULT = BLT(I, J)}
2934 @item @emph{Arguments}:
2935 @multitable @columnfractions .15 .70
2936 @item @var{I} @tab Shall be of @code{INTEGER} type.
2937 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2941 @item @emph{Return value}:
2942 The return value is of type @code{LOGICAL} and of the default kind.
2944 @item @emph{See also}:
2945 @ref{BGE}, @ref{BGT}, @ref{BLE}
2951 @section @code{BTEST} --- Bit test function
2957 @cindex bits, testing
2960 @item @emph{Description}:
2961 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
2962 in @var{I} is set. The counting of the bits starts at 0.
2964 @item @emph{Standard}:
2965 Fortran 95 and later, has overloads that are GNU extensions
2970 @item @emph{Syntax}:
2971 @code{RESULT = BTEST(I, POS)}
2973 @item @emph{Arguments}:
2974 @multitable @columnfractions .15 .70
2975 @item @var{I} @tab The type shall be @code{INTEGER}.
2976 @item @var{POS} @tab The type shall be @code{INTEGER}.
2979 @item @emph{Return value}:
2980 The return value is of type @code{LOGICAL}
2982 @item @emph{Example}:
2985 integer :: i = 32768 + 1024 + 64
2989 bool = btest(i, pos)
2992 end program test_btest
2995 @item @emph{Specific names}:
2996 @multitable @columnfractions .20 .20 .20 .25
2997 @item Name @tab Argument @tab Return type @tab Standard
2998 @item @code{BTEST(I,POS)} @tab @code{INTEGER I,POS} @tab @code{LOGICAL} @tab F95 and later
2999 @item @code{BBTEST(I,POS)} @tab @code{INTEGER(1) I,POS} @tab @code{LOGICAL(1)} @tab GNU extension
3000 @item @code{BITEST(I,POS)} @tab @code{INTEGER(2) I,POS} @tab @code{LOGICAL(2)} @tab GNU extension
3001 @item @code{BJTEST(I,POS)} @tab @code{INTEGER(4) I,POS} @tab @code{LOGICAL(4)} @tab GNU extension
3002 @item @code{BKTEST(I,POS)} @tab @code{INTEGER(8) I,POS} @tab @code{LOGICAL(8)} @tab GNU extension
3007 @section @code{C_ASSOCIATED} --- Status of a C pointer
3008 @fnindex C_ASSOCIATED
3009 @cindex association status, C pointer
3010 @cindex pointer, C association status
3013 @item @emph{Description}:
3014 @code{C_ASSOCIATED(c_ptr_1[, c_ptr_2])} determines the status of the C pointer
3015 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
3017 @item @emph{Standard}:
3018 Fortran 2003 and later
3023 @item @emph{Syntax}:
3024 @code{RESULT = C_ASSOCIATED(c_ptr_1[, c_ptr_2])}
3026 @item @emph{Arguments}:
3027 @multitable @columnfractions .15 .70
3028 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
3029 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
3032 @item @emph{Return value}:
3033 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
3034 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
3035 point to different addresses.
3037 @item @emph{Example}:
3039 subroutine association_test(a,b)
3040 use iso_c_binding, only: c_associated, c_loc, c_ptr
3044 if(c_associated(b, c_loc(a))) &
3045 stop 'b and a do not point to same target'
3046 end subroutine association_test
3049 @item @emph{See also}:
3050 @ref{C_LOC}, @ref{C_FUNLOC}
3055 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
3056 @fnindex C_F_POINTER
3057 @cindex pointer, convert C to Fortran
3060 @item @emph{Description}:
3061 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} assigns the target of the C pointer
3062 @var{CPTR} to the Fortran pointer @var{FPTR} and specifies its shape.
3064 @item @emph{Standard}:
3065 Fortran 2003 and later
3070 @item @emph{Syntax}:
3071 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
3073 @item @emph{Arguments}:
3074 @multitable @columnfractions .15 .70
3075 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
3077 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
3079 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
3080 with @code{INTENT(IN)}. It shall be present
3081 if and only if @var{fptr} is an array. The size
3082 must be equal to the rank of @var{fptr}.
3085 @item @emph{Example}:
3091 subroutine my_routine(p) bind(c,name='myC_func')
3093 type(c_ptr), intent(out) :: p
3097 real,pointer :: a(:)
3098 call my_routine(cptr)
3099 call c_f_pointer(cptr, a, [12])
3103 @item @emph{See also}:
3104 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
3108 @node C_F_PROCPOINTER
3109 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
3110 @fnindex C_F_PROCPOINTER
3111 @cindex pointer, C address of pointers
3114 @item @emph{Description}:
3115 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
3116 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
3118 @item @emph{Standard}:
3119 Fortran 2003 and later
3124 @item @emph{Syntax}:
3125 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
3127 @item @emph{Arguments}:
3128 @multitable @columnfractions .15 .70
3129 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
3131 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
3135 @item @emph{Example}:
3143 real(c_float), intent(in) :: a
3144 real(c_float) :: func
3148 function getIterFunc() bind(c,name="getIterFunc")
3150 type(c_funptr) :: getIterFunc
3153 type(c_funptr) :: cfunptr
3154 procedure(func), pointer :: myFunc
3155 cfunptr = getIterFunc()
3156 call c_f_procpointer(cfunptr, myFunc)
3160 @item @emph{See also}:
3161 @ref{C_LOC}, @ref{C_F_POINTER}
3166 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
3168 @cindex pointer, C address of procedures
3171 @item @emph{Description}:
3172 @code{C_FUNLOC(x)} determines the C address of the argument.
3174 @item @emph{Standard}:
3175 Fortran 2003 and later
3180 @item @emph{Syntax}:
3181 @code{RESULT = C_FUNLOC(x)}
3183 @item @emph{Arguments}:
3184 @multitable @columnfractions .15 .70
3185 @item @var{x} @tab Interoperable function or pointer to such function.
3188 @item @emph{Return value}:
3189 The return value is of type @code{C_FUNPTR} and contains the C address
3192 @item @emph{Example}:
3198 subroutine sub(a) bind(c)
3208 subroutine my_routine(p) bind(c,name='myC_func')
3210 type(c_funptr), intent(in) :: p
3213 call my_routine(c_funloc(sub))
3217 @item @emph{See also}:
3218 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
3223 @section @code{C_LOC} --- Obtain the C address of an object
3225 @cindex procedure pointer, convert C to Fortran
3228 @item @emph{Description}:
3229 @code{C_LOC(X)} determines the C address of the argument.
3231 @item @emph{Standard}:
3232 Fortran 2003 and later
3237 @item @emph{Syntax}:
3238 @code{RESULT = C_LOC(X)}
3240 @item @emph{Arguments}:
3241 @multitable @columnfractions .10 .75
3242 @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.
3246 @item @emph{Return value}:
3247 The return value is of type @code{C_PTR} and contains the C address
3250 @item @emph{Example}:
3252 subroutine association_test(a,b)
3253 use iso_c_binding, only: c_associated, c_loc, c_ptr
3257 if(c_associated(b, c_loc(a))) &
3258 stop 'b and a do not point to same target'
3259 end subroutine association_test
3262 @item @emph{See also}:
3263 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
3268 @section @code{C_SIZEOF} --- Size in bytes of an expression
3270 @cindex expression size
3271 @cindex size of an expression
3274 @item @emph{Description}:
3275 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
3276 expression @code{X} occupies.
3278 @item @emph{Standard}:
3282 Inquiry function of the module @code{ISO_C_BINDING}
3284 @item @emph{Syntax}:
3285 @code{N = C_SIZEOF(X)}
3287 @item @emph{Arguments}:
3288 @multitable @columnfractions .15 .70
3289 @item @var{X} @tab The argument shall be an interoperable data entity.
3292 @item @emph{Return value}:
3293 The return value is of type integer and of the system-dependent kind
3294 @code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the
3295 number of bytes occupied by the argument. If the argument has the
3296 @code{POINTER} attribute, the number of bytes of the storage area pointed
3297 to is returned. If the argument is of a derived type with @code{POINTER}
3298 or @code{ALLOCATABLE} components, the return value does not account for
3299 the sizes of the data pointed to by these components.
3301 @item @emph{Example}:
3305 real(c_float) :: r, s(5)
3306 print *, (c_sizeof(s)/c_sizeof(r) == 5)
3309 The example will print @code{.TRUE.} unless you are using a platform
3310 where default @code{REAL} variables are unusually padded.
3312 @item @emph{See also}:
3313 @ref{SIZEOF}, @ref{STORAGE_SIZE}
3318 @section @code{CEILING} --- Integer ceiling function
3321 @cindex rounding, ceiling
3324 @item @emph{Description}:
3325 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
3327 @item @emph{Standard}:
3328 Fortran 95 and later
3333 @item @emph{Syntax}:
3334 @code{RESULT = CEILING(A [, KIND])}
3336 @item @emph{Arguments}:
3337 @multitable @columnfractions .15 .70
3338 @item @var{A} @tab The type shall be @code{REAL}.
3339 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3340 expression indicating the kind parameter of the result.
3343 @item @emph{Return value}:
3344 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
3345 and a default-kind @code{INTEGER} otherwise.
3347 @item @emph{Example}:
3349 program test_ceiling
3352 print *, ceiling(x) ! returns 64
3353 print *, ceiling(y) ! returns -63
3354 end program test_ceiling
3357 @item @emph{See also}:
3358 @ref{FLOOR}, @ref{NINT}
3365 @section @code{CHAR} --- Character conversion function
3367 @cindex conversion, to character
3370 @item @emph{Description}:
3371 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
3373 @item @emph{Standard}:
3374 Fortran 77 and later
3379 @item @emph{Syntax}:
3380 @code{RESULT = CHAR(I [, KIND])}
3382 @item @emph{Arguments}:
3383 @multitable @columnfractions .15 .70
3384 @item @var{I} @tab The type shall be @code{INTEGER}.
3385 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3386 expression indicating the kind parameter of the result.
3389 @item @emph{Return value}:
3390 The return value is of type @code{CHARACTER(1)}
3392 @item @emph{Example}:
3398 print *, i, c ! returns 'J'
3399 end program test_char
3402 @item @emph{Specific names}:
3403 @multitable @columnfractions .20 .20 .20 .25
3404 @item Name @tab Argument @tab Return type @tab Standard
3405 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
3409 See @ref{ICHAR} for a discussion of converting between numerical values
3410 and formatted string representations.
3412 @item @emph{See also}:
3413 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
3420 @section @code{CHDIR} --- Change working directory
3422 @cindex system, working directory
3425 @item @emph{Description}:
3426 Change current working directory to a specified path.
3428 This intrinsic is provided in both subroutine and function forms; however,
3429 only one form can be used in any given program unit.
3431 @item @emph{Standard}:
3435 Subroutine, function
3437 @item @emph{Syntax}:
3438 @multitable @columnfractions .80
3439 @item @code{CALL CHDIR(NAME [, STATUS])}
3440 @item @code{STATUS = CHDIR(NAME)}
3443 @item @emph{Arguments}:
3444 @multitable @columnfractions .15 .70
3445 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
3446 kind and shall specify a valid path within the file system.
3447 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
3448 kind. Returns 0 on success, and a system specific and nonzero error code
3452 @item @emph{Example}:
3455 CHARACTER(len=255) :: path
3457 WRITE(*,*) TRIM(path)
3460 WRITE(*,*) TRIM(path)
3464 @item @emph{See also}:
3471 @section @code{CHMOD} --- Change access permissions of files
3473 @cindex file system, change access mode
3476 @item @emph{Description}:
3477 @code{CHMOD} changes the permissions of a file.
3479 This intrinsic is provided in both subroutine and function forms; however,
3480 only one form can be used in any given program unit.
3482 @item @emph{Standard}:
3486 Subroutine, function
3488 @item @emph{Syntax}:
3489 @multitable @columnfractions .80
3490 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
3491 @item @code{STATUS = CHMOD(NAME, MODE)}
3494 @item @emph{Arguments}:
3495 @multitable @columnfractions .15 .70
3497 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
3498 file name. Trailing blanks are ignored unless the character
3499 @code{achar(0)} is present, then all characters up to and excluding
3500 @code{achar(0)} are used as the file name.
3502 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
3503 file permission. @var{MODE} uses the same syntax as the @code{chmod} utility
3504 as defined by the POSIX standard. The argument shall either be a string of
3505 a nonnegative octal number or a symbolic mode.
3507 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
3508 @code{0} on success and nonzero otherwise.
3511 @item @emph{Return value}:
3512 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
3515 @item @emph{Example}:
3516 @code{CHMOD} as subroutine
3521 call chmod('test.dat','u+x',status)
3522 print *, 'Status: ', status
3523 end program chmod_test
3525 @code{CHMOD} as function:
3530 status = chmod('test.dat','u+x')
3531 print *, 'Status: ', status
3532 end program chmod_test
3540 @section @code{CMPLX} --- Complex conversion function
3542 @cindex complex numbers, conversion to
3543 @cindex conversion, to complex
3546 @item @emph{Description}:
3547 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
3548 the real component. If @var{Y} is present it is converted to the imaginary
3549 component. If @var{Y} is not present then the imaginary component is set to
3550 0.0. If @var{X} is complex then @var{Y} must not be present.
3552 @item @emph{Standard}:
3553 Fortran 77 and later
3558 @item @emph{Syntax}:
3559 @code{RESULT = CMPLX(X [, Y [, KIND]])}
3561 @item @emph{Arguments}:
3562 @multitable @columnfractions .15 .70
3563 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3565 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
3566 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
3567 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3568 expression indicating the kind parameter of the result.
3571 @item @emph{Return value}:
3572 The return value is of @code{COMPLEX} type, with a kind equal to
3573 @var{KIND} if it is specified. If @var{KIND} is not specified, the
3574 result is of the default @code{COMPLEX} kind, regardless of the kinds of
3575 @var{X} and @var{Y}.
3577 @item @emph{Example}:
3584 print *, z, cmplx(x)
3585 end program test_cmplx
3588 @item @emph{See also}:
3595 @section @code{CO_BROADCAST} --- Copy a value to all images the current set of images
3596 @fnindex CO_BROADCAST
3597 @cindex Collectives, value broadcasting
3600 @item @emph{Description}:
3601 @code{CO_BROADCAST} copies the value of argument @var{A} on the image with
3602 image index @code{SOURCE_IMAGE} to all images in the current team. @var{A}
3603 becomes defined as if by intrinsic assignment. If the execution was
3604 successful and @var{STAT} is present, it is assigned the value zero. If the
3605 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3606 @var{ERRMSG} gets assigned a value describing the occurred error.
3608 @item @emph{Standard}:
3609 Technical Specification (TS) 18508 or later
3612 Collective subroutine
3614 @item @emph{Syntax}:
3615 @code{CALL CO_BROADCAST(A, SOURCE_IMAGE [, STAT, ERRMSG])}
3617 @item @emph{Arguments}:
3618 @multitable @columnfractions .15 .70
3619 @item @var{A} @tab INTENT(INOUT) argument; shall have the same
3620 dynamic type and type paramters on all images of the current team. If it
3621 is an array, it shall have the same shape on all images.
3622 @item @var{SOURCE_IMAGE} @tab a scalar integer expression.
3623 It shall have the same the same value on all images and refer to an
3624 image of the current team.
3625 @item @var{STAT} @tab (optional) a scalar integer variable
3626 @item @var{ERRMSG} @tab (optional) a scalar character variable
3629 @item @emph{Example}:
3633 if (this_image() == 1) then
3636 call co_broadcast (val, source_image=1)
3637 print *, this_image, ":", val
3641 @item @emph{See also}:
3642 @ref{CO_MAX}, @ref{CO_MIN}, @ref{CO_SUM}, @ref{CO_REDUCE}
3648 @section @code{CO_MAX} --- Maximal value on the current set of images
3650 @cindex Collectives, maximal value
3653 @item @emph{Description}:
3654 @code{CO_MAX} determines element-wise the maximal value of @var{A} on all
3655 images of the current team. If @var{RESULT_IMAGE} is present, the maximum
3656 values are returned in @var{A} on the specified image only and the value
3657 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3658 not present, the value is returned on all images. If the execution was
3659 successful and @var{STAT} is present, it is assigned the value zero. If the
3660 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3661 @var{ERRMSG} gets assigned a value describing the occurred error.
3663 @item @emph{Standard}:
3664 Technical Specification (TS) 18508 or later
3667 Collective subroutine
3669 @item @emph{Syntax}:
3670 @code{CALL CO_MAX(A [, RESULT_IMAGE, STAT, ERRMSG])}
3672 @item @emph{Arguments}:
3673 @multitable @columnfractions .15 .70
3674 @item @var{A} @tab shall be an integer, real or character variable,
3675 which has the same type and type parameters on all images of the team.
3676 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3677 present, it shall have the same the same value on all images and refer to an
3678 image of the current team.
3679 @item @var{STAT} @tab (optional) a scalar integer variable
3680 @item @var{ERRMSG} @tab (optional) a scalar character variable
3683 @item @emph{Example}:
3688 call co_max (val, result_image=1)
3689 if (this_image() == 1) then
3690 write(*,*) "Maximal value", val ! prints num_images()
3695 @item @emph{See also}:
3696 @ref{CO_MIN}, @ref{CO_SUM}, @ref{CO_REDUCE}, @ref{CO_BROADCAST}
3702 @section @code{CO_MIN} --- Minimal value on the current set of images
3704 @cindex Collectives, minimal value
3707 @item @emph{Description}:
3708 @code{CO_MIN} determines element-wise the minimal value of @var{A} on all
3709 images of the current team. If @var{RESULT_IMAGE} is present, the minimal
3710 values are returned in @var{A} on the specified image only and the value
3711 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3712 not present, the value is returned on all images. If the execution was
3713 successful and @var{STAT} is present, it is assigned the value zero. If the
3714 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3715 @var{ERRMSG} gets assigned a value describing the occurred error.
3717 @item @emph{Standard}:
3718 Technical Specification (TS) 18508 or later
3721 Collective subroutine
3723 @item @emph{Syntax}:
3724 @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3726 @item @emph{Arguments}:
3727 @multitable @columnfractions .15 .70
3728 @item @var{A} @tab shall be an integer, real or character variable,
3729 which has the same type and type parameters on all images of the team.
3730 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3731 present, it shall have the same the same value on all images and refer to an
3732 image of the current team.
3733 @item @var{STAT} @tab (optional) a scalar integer variable
3734 @item @var{ERRMSG} @tab (optional) a scalar character variable
3737 @item @emph{Example}:
3742 call co_min (val, result_image=1)
3743 if (this_image() == 1) then
3744 write(*,*) "Minimal value", val ! prints 1
3749 @item @emph{See also}:
3750 @ref{CO_MAX}, @ref{CO_SUM}, @ref{CO_REDUCE}, @ref{CO_BROADCAST}
3756 @section @code{CO_REDUCE} --- Reduction of values on the current set of images
3758 @cindex Collectives, generic reduction
3761 @item @emph{Description}:
3762 @code{CO_REDUCE} determines element-wise the reduction of the value of @var{A}
3763 on all images of the current team. The pure function passed as @var{OPERATOR}
3764 is used to pairwise reduce the values of @var{A} by passing either the value
3765 of @var{A} of different images or the result values of such a reduction as
3766 argument. If @var{A} is an array, the deduction is done element wise. If
3767 @var{RESULT_IMAGE} is present, the result values are returned in @var{A} on
3768 the specified image only and the value of @var{A} on the other images become
3769 undefined. If @var{RESULT_IMAGE} is not present, the value is returned on all
3770 images. If the execution was successful and @var{STAT} is present, it is
3771 assigned the value zero. If the execution failed, @var{STAT} gets assigned
3772 a nonzero value and, if present, @var{ERRMSG} gets assigned a value describing
3775 @item @emph{Standard}:
3776 Technical Specification (TS) 18508 or later
3779 Collective subroutine
3781 @item @emph{Syntax}:
3782 @code{CALL CO_REDUCE(A, OPERATOR, [, RESULT_IMAGE, STAT, ERRMSG])}
3784 @item @emph{Arguments}:
3785 @multitable @columnfractions .15 .70
3786 @item @var{A} @tab is an @code{INTENT(INOUT)} argument and shall be
3787 nonpolymorphic. If it is allocatable, it shall be allocated; if it is a pointer,
3788 it shall be associated. @var{A} shall have the same type and type parameters on
3789 all images of the team; if it is an array, it shall have the same shape on all
3791 @item @var{OPERATOR} @tab pure function with two scalar nonallocatable
3792 arguments, which shall be nonpolymorphic and have the same type and type
3793 parameters as @var{A}. The function shall return a nonallocatable scalar of
3794 the same type and type parameters as @var{A}. The function shall be the same on
3795 all images and with regards to the arguments mathematically commutative and
3796 associative. Note that @var{OPERATOR} may not be an elemental function, unless
3797 it is an intrisic function.
3798 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3799 present, it shall have the same the same value on all images and refer to an
3800 image of the current team.
3801 @item @var{STAT} @tab (optional) a scalar integer variable
3802 @item @var{ERRMSG} @tab (optional) a scalar character variable
3805 @item @emph{Example}:
3810 call co_reduce (val, result_image=1, operator=myprod)
3811 if (this_image() == 1) then
3812 write(*,*) "Product value", val ! prints num_images() factorial
3815 pure function myprod(a, b)
3816 integer, value :: a, b
3824 While the rules permit in principle an intrinsic function, none of the
3825 intrinsics in the standard fulfill the criteria of having a specific
3826 function, which takes two arguments of the same type and returning that
3829 @item @emph{See also}:
3830 @ref{CO_MIN}, @ref{CO_MAX}, @ref{CO_SUM}, @ref{CO_BROADCAST}
3836 @section @code{CO_SUM} --- Sum of values on the current set of images
3838 @cindex Collectives, sum of values
3841 @item @emph{Description}:
3842 @code{CO_SUM} sums up the values of each element of @var{A} on all
3843 images of the current team. If @var{RESULT_IMAGE} is present, the summed-up
3844 values are returned in @var{A} on the specified image only and the value
3845 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3846 not present, the value is returned on all images. If the execution was
3847 successful and @var{STAT} is present, it is assigned the value zero. If the
3848 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3849 @var{ERRMSG} gets assigned a value describing the occurred error.
3851 @item @emph{Standard}:
3852 Technical Specification (TS) 18508 or later
3855 Collective subroutine
3857 @item @emph{Syntax}:
3858 @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3860 @item @emph{Arguments}:
3861 @multitable @columnfractions .15 .70
3862 @item @var{A} @tab shall be an integer, real or complex variable,
3863 which has the same type and type parameters on all images of the team.
3864 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3865 present, it shall have the same the same value on all images and refer to an
3866 image of the current team.
3867 @item @var{STAT} @tab (optional) a scalar integer variable
3868 @item @var{ERRMSG} @tab (optional) a scalar character variable
3871 @item @emph{Example}:
3876 call co_sum (val, result_image=1)
3877 if (this_image() == 1) then
3878 write(*,*) "The sum is ", val ! prints (n**2 + n)/2, with n = num_images()
3883 @item @emph{See also}:
3884 @ref{CO_MAX}, @ref{CO_MIN}, @ref{CO_REDUCE}, @ref{CO_BROADCAST}
3889 @node COMMAND_ARGUMENT_COUNT
3890 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
3891 @fnindex COMMAND_ARGUMENT_COUNT
3892 @cindex command-line arguments
3893 @cindex command-line arguments, number of
3894 @cindex arguments, to program
3897 @item @emph{Description}:
3898 @code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the
3899 command line when the containing program was invoked.
3901 @item @emph{Standard}:
3902 Fortran 2003 and later
3907 @item @emph{Syntax}:
3908 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
3910 @item @emph{Arguments}:
3911 @multitable @columnfractions .15 .70
3915 @item @emph{Return value}:
3916 The return value is an @code{INTEGER} of default kind.
3918 @item @emph{Example}:
3920 program test_command_argument_count
3922 count = command_argument_count()
3924 end program test_command_argument_count
3927 @item @emph{See also}:
3928 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
3933 @node COMPILER_OPTIONS
3934 @section @code{COMPILER_OPTIONS} --- Options passed to the compiler
3935 @fnindex COMPILER_OPTIONS
3936 @cindex flags inquiry function
3937 @cindex options inquiry function
3938 @cindex compiler flags inquiry function
3941 @item @emph{Description}:
3942 @code{COMPILER_OPTIONS} returns a string with the options used for
3945 @item @emph{Standard}:
3949 Inquiry function of the module @code{ISO_FORTRAN_ENV}
3951 @item @emph{Syntax}:
3952 @code{STR = COMPILER_OPTIONS()}
3954 @item @emph{Arguments}:
3957 @item @emph{Return value}:
3958 The return value is a default-kind string with system-dependent length.
3959 It contains the compiler flags used to compile the file, which called
3960 the @code{COMPILER_OPTIONS} intrinsic.
3962 @item @emph{Example}:
3965 print '(4a)', 'This file was compiled by ', &
3966 compiler_version(), ' using the options ', &
3971 @item @emph{See also}:
3972 @ref{COMPILER_VERSION}, @ref{ISO_FORTRAN_ENV}
3977 @node COMPILER_VERSION
3978 @section @code{COMPILER_VERSION} --- Compiler version string
3979 @fnindex COMPILER_VERSION
3980 @cindex compiler, name and version
3981 @cindex version of the compiler
3984 @item @emph{Description}:
3985 @code{COMPILER_VERSION} returns a string with the name and the
3986 version of the compiler.
3988 @item @emph{Standard}:
3992 Inquiry function of the module @code{ISO_FORTRAN_ENV}
3994 @item @emph{Syntax}:
3995 @code{STR = COMPILER_VERSION()}
3997 @item @emph{Arguments}:
4000 @item @emph{Return value}:
4001 The return value is a default-kind string with system-dependent length.
4002 It contains the name of the compiler and its version number.
4004 @item @emph{Example}:
4007 print '(4a)', 'This file was compiled by ', &
4008 compiler_version(), ' using the options ', &
4013 @item @emph{See also}:
4014 @ref{COMPILER_OPTIONS}, @ref{ISO_FORTRAN_ENV}
4020 @section @code{COMPLEX} --- Complex conversion function
4022 @cindex complex numbers, conversion to
4023 @cindex conversion, to complex
4026 @item @emph{Description}:
4027 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
4028 to the real component and @var{Y} is converted to the imaginary
4031 @item @emph{Standard}:
4037 @item @emph{Syntax}:
4038 @code{RESULT = COMPLEX(X, Y)}
4040 @item @emph{Arguments}:
4041 @multitable @columnfractions .15 .70
4042 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
4043 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
4046 @item @emph{Return value}:
4047 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
4048 value is of default @code{COMPLEX} type.
4050 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
4051 type and one is of @code{INTEGER} type, then the return value is of
4052 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
4053 argument with the highest precision.
4055 @item @emph{Example}:
4057 program test_complex
4060 print *, complex(i, x)
4061 end program test_complex
4064 @item @emph{See also}:
4071 @section @code{CONJG} --- Complex conjugate function
4074 @cindex complex conjugate
4077 @item @emph{Description}:
4078 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
4079 then the result is @code{(x, -y)}
4081 @item @emph{Standard}:
4082 Fortran 77 and later, has overloads that are GNU extensions
4087 @item @emph{Syntax}:
4090 @item @emph{Arguments}:
4091 @multitable @columnfractions .15 .70
4092 @item @var{Z} @tab The type shall be @code{COMPLEX}.
4095 @item @emph{Return value}:
4096 The return value is of type @code{COMPLEX}.
4098 @item @emph{Example}:
4101 complex :: z = (2.0, 3.0)
4102 complex(8) :: dz = (2.71_8, -3.14_8)
4107 end program test_conjg
4110 @item @emph{Specific names}:
4111 @multitable @columnfractions .20 .20 .20 .25
4112 @item Name @tab Argument @tab Return type @tab Standard
4113 @item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension
4114 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
4121 @section @code{COS} --- Cosine function
4127 @cindex trigonometric function, cosine
4131 @item @emph{Description}:
4132 @code{COS(X)} computes the cosine of @var{X}.
4134 @item @emph{Standard}:
4135 Fortran 77 and later, has overloads that are GNU extensions
4140 @item @emph{Syntax}:
4141 @code{RESULT = COS(X)}
4143 @item @emph{Arguments}:
4144 @multitable @columnfractions .15 .70
4145 @item @var{X} @tab The type shall be @code{REAL} or
4149 @item @emph{Return value}:
4150 The return value is of the same type and kind as @var{X}. The real part
4151 of the result is in radians. If @var{X} is of the type @code{REAL},
4152 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
4154 @item @emph{Example}:
4159 end program test_cos
4162 @item @emph{Specific names}:
4163 @multitable @columnfractions .20 .20 .20 .25
4164 @item Name @tab Argument @tab Return type @tab Standard
4165 @item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
4166 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
4167 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
4168 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4169 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4172 @item @emph{See also}:
4173 Inverse function: @ref{ACOS}
4174 Degrees function: @ref{COSD}
4181 @section @code{COSD} --- Cosine function, degrees
4187 @cindex trigonometric function, cosine, degrees
4188 @cindex cosine, degrees
4191 @item @emph{Description}:
4192 @code{COSD(X)} computes the cosine of @var{X} in degrees.
4194 This function is for compatibility only and should be avoided in favor of
4195 standard constructs wherever possible.
4197 @item @emph{Standard}:
4198 GNU Extension, enabled with @option{-fdec-math}.
4203 @item @emph{Syntax}:
4204 @code{RESULT = COSD(X)}
4206 @item @emph{Arguments}:
4207 @multitable @columnfractions .15 .70
4208 @item @var{X} @tab The type shall be @code{REAL} or
4212 @item @emph{Return value}:
4213 The return value is of the same type and kind as @var{X}. The real part
4214 of the result is in degrees. If @var{X} is of the type @code{REAL},
4215 the return value lies in the range @math{ -1 \leq \cosd (x) \leq 1}.
4217 @item @emph{Example}:
4222 end program test_cosd
4225 @item @emph{Specific names}:
4226 @multitable @columnfractions .20 .20 .20 .25
4227 @item Name @tab Argument @tab Return type @tab Standard
4228 @item @code{COSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4229 @item @code{DCOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4230 @item @code{CCOSD(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU Extension
4231 @item @code{ZCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4232 @item @code{CDCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4235 @item @emph{See also}:
4236 Inverse function: @ref{ACOSD}
4237 Radians function: @ref{COS}
4244 @section @code{COSH} --- Hyperbolic cosine function
4247 @cindex hyperbolic cosine
4248 @cindex hyperbolic function, cosine
4249 @cindex cosine, hyperbolic
4252 @item @emph{Description}:
4253 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
4255 @item @emph{Standard}:
4256 Fortran 77 and later, for a complex argument Fortran 2008 or later
4261 @item @emph{Syntax}:
4264 @item @emph{Arguments}:
4265 @multitable @columnfractions .15 .70
4266 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4269 @item @emph{Return value}:
4270 The return value has same type and kind as @var{X}. If @var{X} is
4271 complex, the imaginary part of the result is in radians. If @var{X}
4272 is @code{REAL}, the return value has a lower bound of one,
4273 @math{\cosh (x) \geq 1}.
4275 @item @emph{Example}:
4278 real(8) :: x = 1.0_8
4280 end program test_cosh
4283 @item @emph{Specific names}:
4284 @multitable @columnfractions .20 .20 .20 .25
4285 @item Name @tab Argument @tab Return type @tab Standard
4286 @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
4287 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
4290 @item @emph{See also}:
4291 Inverse function: @ref{ACOSH}
4298 @section @code{COTAN} --- Cotangent function
4301 @cindex trigonometric function, cotangent
4305 @item @emph{Description}:
4306 @code{COTAN(X)} computes the cotangent of @var{X}. Equivalent to @code{COS(x)}
4307 divided by @code{SIN(x)}, or @code{1 / TAN(x)}.
4309 This function is for compatibility only and should be avoided in favor of
4310 standard constructs wherever possible.
4312 @item @emph{Standard}:
4313 GNU Extension, enabled with @option{-fdec-math}.
4318 @item @emph{Syntax}:
4319 @code{RESULT = COTAN(X)}
4321 @item @emph{Arguments}:
4322 @multitable @columnfractions .15 .70
4323 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4326 @item @emph{Return value}:
4327 The return value has same type and kind as @var{X}, and its value is in radians.
4329 @item @emph{Example}:
4332 real(8) :: x = 0.165_8
4334 end program test_cotan
4337 @item @emph{Specific names}:
4338 @multitable @columnfractions .20 .20 .20 .25
4339 @item Name @tab Argument @tab Return type @tab Standard
4340 @item @code{COTAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4341 @item @code{DCOTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4344 @item @emph{See also}:
4345 Converse function: @ref{TAN}
4346 Degrees function: @ref{COTAND}
4352 @section @code{COTAND} --- Cotangent function, degrees
4355 @cindex trigonometric function, cotangent, degrees
4356 @cindex cotangent, degrees
4359 @item @emph{Description}:
4360 @code{COTAND(X)} computes the cotangent of @var{X} in degrees. Equivalent to
4361 @code{COSD(x)} divided by @code{SIND(x)}, or @code{1 / TAND(x)}.
4363 @item @emph{Standard}:
4364 GNU Extension, enabled with @option{-fdec-math}.
4366 This function is for compatibility only and should be avoided in favor of
4367 standard constructs wherever possible.
4372 @item @emph{Syntax}:
4373 @code{RESULT = COTAND(X)}
4375 @item @emph{Arguments}:
4376 @multitable @columnfractions .15 .70
4377 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4380 @item @emph{Return value}:
4381 The return value has same type and kind as @var{X}, and its value is in degrees.
4383 @item @emph{Example}:
4386 real(8) :: x = 0.165_8
4388 end program test_cotand
4391 @item @emph{Specific names}:
4392 @multitable @columnfractions .20 .20 .20 .25
4393 @item Name @tab Argument @tab Return type @tab Standard
4394 @item @code{COTAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4395 @item @code{DCOTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4398 @item @emph{See also}:
4399 Converse function: @ref{TAND}
4400 Radians function: @ref{COTAN}
4407 @section @code{COUNT} --- Count function
4409 @cindex array, conditionally count elements
4410 @cindex array, element counting
4411 @cindex array, number of elements
4414 @item @emph{Description}:
4416 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
4417 or, if the @var{DIM} argument is supplied, counts the number of
4418 elements along each row of the array in the @var{DIM} direction.
4419 If the array has zero size, or all of the elements of @var{MASK} are
4420 @code{.FALSE.}, then the result is @code{0}.
4422 @item @emph{Standard}:
4423 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
4426 Transformational function
4428 @item @emph{Syntax}:
4429 @code{RESULT = COUNT(MASK [, DIM, KIND])}
4431 @item @emph{Arguments}:
4432 @multitable @columnfractions .15 .70
4433 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
4434 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
4435 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4436 expression indicating the kind parameter of the result.
4439 @item @emph{Return value}:
4440 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
4441 @var{KIND} is absent, the return value is of default integer kind.
4442 If @var{DIM} is present, the result is an array with a rank one less
4443 than the rank of @var{ARRAY}, and a size corresponding to the shape
4444 of @var{ARRAY} with the @var{DIM} dimension removed.
4446 @item @emph{Example}:
4449 integer, dimension(2,3) :: a, b
4450 logical, dimension(2,3) :: mask
4451 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
4452 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
4453 print '(3i3)', a(1,:)
4454 print '(3i3)', a(2,:)
4456 print '(3i3)', b(1,:)
4457 print '(3i3)', b(2,:)
4460 print '(3l3)', mask(1,:)
4461 print '(3l3)', mask(2,:)
4463 print '(3i3)', count(mask)
4465 print '(3i3)', count(mask, 1)
4467 print '(3i3)', count(mask, 2)
4468 end program test_count
4475 @section @code{CPU_TIME} --- CPU elapsed time in seconds
4477 @cindex time, elapsed
4480 @item @emph{Description}:
4481 Returns a @code{REAL} value representing the elapsed CPU time in
4482 seconds. This is useful for testing segments of code to determine
4485 If a time source is available, time will be reported with microsecond
4486 resolution. If no time source is available, @var{TIME} is set to
4489 Note that @var{TIME} may contain a, system dependent, arbitrary offset
4490 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
4491 value is meaningless, only differences between subsequent calls to
4492 this subroutine, as shown in the example below, should be used.
4495 @item @emph{Standard}:
4496 Fortran 95 and later
4501 @item @emph{Syntax}:
4502 @code{CALL CPU_TIME(TIME)}
4504 @item @emph{Arguments}:
4505 @multitable @columnfractions .15 .70
4506 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
4509 @item @emph{Return value}:
4512 @item @emph{Example}:
4514 program test_cpu_time
4515 real :: start, finish
4516 call cpu_time(start)
4517 ! put code to test here
4518 call cpu_time(finish)
4519 print '("Time = ",f6.3," seconds.")',finish-start
4520 end program test_cpu_time
4523 @item @emph{See also}:
4524 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
4530 @section @code{CSHIFT} --- Circular shift elements of an array
4532 @cindex array, shift circularly
4533 @cindex array, permutation
4534 @cindex array, rotate
4537 @item @emph{Description}:
4538 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
4539 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
4540 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
4541 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
4542 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
4543 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
4544 sections of @var{ARRAY} along the given dimension are shifted. Elements
4545 shifted out one end of each rank one section are shifted back in the other end.
4547 @item @emph{Standard}:
4548 Fortran 95 and later
4551 Transformational function
4553 @item @emph{Syntax}:
4554 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
4556 @item @emph{Arguments}:
4557 @multitable @columnfractions .15 .70
4558 @item @var{ARRAY} @tab Shall be an array of any type.
4559 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
4560 @item @var{DIM} @tab The type shall be @code{INTEGER}.
4563 @item @emph{Return value}:
4564 Returns an array of same type and rank as the @var{ARRAY} argument.
4566 @item @emph{Example}:
4569 integer, dimension(3,3) :: a
4570 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
4571 print '(3i3)', a(1,:)
4572 print '(3i3)', a(2,:)
4573 print '(3i3)', a(3,:)
4574 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
4576 print '(3i3)', a(1,:)
4577 print '(3i3)', a(2,:)
4578 print '(3i3)', a(3,:)
4579 end program test_cshift
4586 @section @code{CTIME} --- Convert a time into a string
4588 @cindex time, conversion to string
4589 @cindex conversion, to string
4592 @item @emph{Description}:
4593 @code{CTIME} converts a system time value, such as returned by
4594 @ref{TIME8}, to a string. The output will be of the form @samp{Sat
4595 Aug 19 18:13:14 1995}.
4597 This intrinsic is provided in both subroutine and function forms; however,
4598 only one form can be used in any given program unit.
4600 @item @emph{Standard}:
4604 Subroutine, function
4606 @item @emph{Syntax}:
4607 @multitable @columnfractions .80
4608 @item @code{CALL CTIME(TIME, RESULT)}.
4609 @item @code{RESULT = CTIME(TIME)}.
4612 @item @emph{Arguments}:
4613 @multitable @columnfractions .15 .70
4614 @item @var{TIME} @tab The type shall be of type @code{INTEGER}.
4615 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
4616 of default kind. It is an @code{INTENT(OUT)} argument. If the length
4617 of this variable is too short for the time and date string to fit
4618 completely, it will be blank on procedure return.
4621 @item @emph{Return value}:
4622 The converted date and time as a string.
4624 @item @emph{Example}:
4628 character(len=30) :: date
4631 ! Do something, main part of the program
4634 print *, 'Program was started on ', date
4635 end program test_ctime
4638 @item @emph{See Also}:
4639 @ref{DATE_AND_TIME}, @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
4645 @section @code{DATE_AND_TIME} --- Date and time subroutine
4646 @fnindex DATE_AND_TIME
4647 @cindex date, current
4648 @cindex current date
4649 @cindex time, current
4650 @cindex current time
4653 @item @emph{Description}:
4654 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
4655 time information from the real-time system clock. @var{DATE} is
4656 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
4657 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
4658 representing the difference with respect to Coordinated Universal Time (UTC).
4659 Unavailable time and date parameters return blanks.
4661 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
4663 @multitable @columnfractions .15 .30 .40
4664 @item @tab @code{VALUE(1)}: @tab The year
4665 @item @tab @code{VALUE(2)}: @tab The month
4666 @item @tab @code{VALUE(3)}: @tab The day of the month
4667 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
4668 @item @tab @code{VALUE(5)}: @tab The hour of the day
4669 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
4670 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
4671 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
4674 @item @emph{Standard}:
4675 Fortran 95 and later
4680 @item @emph{Syntax}:
4681 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
4683 @item @emph{Arguments}:
4684 @multitable @columnfractions .15 .70
4685 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
4686 or larger, and of default kind.
4687 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
4688 or larger, and of default kind.
4689 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
4690 or larger, and of default kind.
4691 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
4694 @item @emph{Return value}:
4697 @item @emph{Example}:
4699 program test_time_and_date
4700 character(8) :: date
4701 character(10) :: time
4702 character(5) :: zone
4703 integer,dimension(8) :: values
4704 ! using keyword arguments
4705 call date_and_time(date,time,zone,values)
4706 call date_and_time(DATE=date,ZONE=zone)
4707 call date_and_time(TIME=time)
4708 call date_and_time(VALUES=values)
4709 print '(a,2x,a,2x,a)', date, time, zone
4710 print '(8i5)', values
4711 end program test_time_and_date
4714 @item @emph{See also}:
4715 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
4721 @section @code{DBLE} --- Double conversion function
4723 @cindex conversion, to real
4726 @item @emph{Description}:
4727 @code{DBLE(A)} Converts @var{A} to double precision real type.
4729 @item @emph{Standard}:
4730 Fortran 77 and later
4735 @item @emph{Syntax}:
4736 @code{RESULT = DBLE(A)}
4738 @item @emph{Arguments}:
4739 @multitable @columnfractions .15 .70
4740 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
4744 @item @emph{Return value}:
4745 The return value is of type double precision real.
4747 @item @emph{Example}:
4752 complex :: z = (2.3,1.14)
4753 print *, dble(x), dble(i), dble(z)
4754 end program test_dble
4757 @item @emph{See also}:
4764 @section @code{DCMPLX} --- Double complex conversion function
4766 @cindex complex numbers, conversion to
4767 @cindex conversion, to complex
4770 @item @emph{Description}:
4771 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
4772 converted to the real component. If @var{Y} is present it is converted to the
4773 imaginary component. If @var{Y} is not present then the imaginary component is
4774 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
4776 @item @emph{Standard}:
4782 @item @emph{Syntax}:
4783 @code{RESULT = DCMPLX(X [, Y])}
4785 @item @emph{Arguments}:
4786 @multitable @columnfractions .15 .70
4787 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
4789 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
4790 @code{INTEGER} or @code{REAL}.
4793 @item @emph{Return value}:
4794 The return value is of type @code{COMPLEX(8)}
4796 @item @emph{Example}:
4806 print *, dcmplx(x,i)
4807 end program test_dcmplx
4813 @section @code{DIGITS} --- Significant binary digits function
4815 @cindex model representation, significant digits
4818 @item @emph{Description}:
4819 @code{DIGITS(X)} returns the number of significant binary digits of the internal
4820 model representation of @var{X}. For example, on a system using a 32-bit
4821 floating point representation, a default real number would likely return 24.
4823 @item @emph{Standard}:
4824 Fortran 95 and later
4829 @item @emph{Syntax}:
4830 @code{RESULT = DIGITS(X)}
4832 @item @emph{Arguments}:
4833 @multitable @columnfractions .15 .70
4834 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
4837 @item @emph{Return value}:
4838 The return value is of type @code{INTEGER}.
4840 @item @emph{Example}:
4843 integer :: i = 12345
4849 end program test_digits
4856 @section @code{DIM} --- Positive difference
4860 @cindex positive difference
4863 @item @emph{Description}:
4864 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
4865 otherwise returns zero.
4867 @item @emph{Standard}:
4868 Fortran 77 and later
4873 @item @emph{Syntax}:
4874 @code{RESULT = DIM(X, Y)}
4876 @item @emph{Arguments}:
4877 @multitable @columnfractions .15 .70
4878 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
4879 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
4882 @item @emph{Return value}:
4883 The return value is of type @code{INTEGER} or @code{REAL}.
4885 @item @emph{Example}:
4891 x = dim(4.345_8, 2.111_8)
4894 end program test_dim
4897 @item @emph{Specific names}:
4898 @multitable @columnfractions .20 .20 .20 .25
4899 @item Name @tab Argument @tab Return type @tab Standard
4900 @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
4901 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
4902 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
4909 @section @code{DOT_PRODUCT} --- Dot product function
4910 @fnindex DOT_PRODUCT
4912 @cindex vector product
4913 @cindex product, vector
4916 @item @emph{Description}:
4917 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
4918 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
4919 either numeric or logical and must be arrays of rank one and of equal size. If
4920 the vectors are @code{INTEGER} or @code{REAL}, the result is
4921 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
4922 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
4923 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
4925 @item @emph{Standard}:
4926 Fortran 95 and later
4929 Transformational function
4931 @item @emph{Syntax}:
4932 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
4934 @item @emph{Arguments}:
4935 @multitable @columnfractions .15 .70
4936 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
4937 @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.
4940 @item @emph{Return value}:
4941 If the arguments are numeric, the return value is a scalar of numeric type,
4942 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
4943 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
4945 @item @emph{Example}:
4947 program test_dot_prod
4948 integer, dimension(3) :: a, b
4955 print *, dot_product(a,b)
4956 end program test_dot_prod
4963 @section @code{DPROD} --- Double product function
4965 @cindex product, double-precision
4968 @item @emph{Description}:
4969 @code{DPROD(X,Y)} returns the product @code{X*Y}.
4971 @item @emph{Standard}:
4972 Fortran 77 and later
4977 @item @emph{Syntax}:
4978 @code{RESULT = DPROD(X, Y)}
4980 @item @emph{Arguments}:
4981 @multitable @columnfractions .15 .70
4982 @item @var{X} @tab The type shall be @code{REAL}.
4983 @item @var{Y} @tab The type shall be @code{REAL}.
4986 @item @emph{Return value}:
4987 The return value is of type @code{REAL(8)}.
4989 @item @emph{Example}:
4997 end program test_dprod
5000 @item @emph{Specific names}:
5001 @multitable @columnfractions .20 .20 .20 .25
5002 @item Name @tab Argument @tab Return type @tab Standard
5003 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
5010 @section @code{DREAL} --- Double real part function
5012 @cindex complex numbers, real part
5015 @item @emph{Description}:
5016 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
5018 @item @emph{Standard}:
5024 @item @emph{Syntax}:
5025 @code{RESULT = DREAL(A)}
5027 @item @emph{Arguments}:
5028 @multitable @columnfractions .15 .70
5029 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
5032 @item @emph{Return value}:
5033 The return value is of type @code{REAL(8)}.
5035 @item @emph{Example}:
5038 complex(8) :: z = (1.3_8,7.2_8)
5040 end program test_dreal
5043 @item @emph{See also}:
5051 @section @code{DSHIFTL} --- Combined left shift
5053 @cindex left shift, combined
5057 @item @emph{Description}:
5058 @code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
5059 rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
5060 bits of @var{J}, and the remaining bits are the rightmost bits of
5063 @item @emph{Standard}:
5064 Fortran 2008 and later
5069 @item @emph{Syntax}:
5070 @code{RESULT = DSHIFTL(I, J, SHIFT)}
5072 @item @emph{Arguments}:
5073 @multitable @columnfractions .15 .70
5074 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5075 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5076 If both @var{I} and @var{J} have integer type, then they shall have
5077 the same kind type parameter. @var{I} and @var{J} shall not both be
5079 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
5080 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
5081 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
5082 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
5085 @item @emph{Return value}:
5086 If either @var{I} or @var{J} is a BOZ constant, it is first converted
5087 as if by the intrinsic function @code{INT} to an integer type with the
5088 kind type parameter of the other.
5090 @item @emph{See also}:
5096 @section @code{DSHIFTR} --- Combined right shift
5098 @cindex right shift, combined
5099 @cindex shift, right
5102 @item @emph{Description}:
5103 @code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
5104 leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
5105 bits of @var{I}, and the remaining bits are the leftmost bits of
5108 @item @emph{Standard}:
5109 Fortran 2008 and later
5114 @item @emph{Syntax}:
5115 @code{RESULT = DSHIFTR(I, J, SHIFT)}
5117 @item @emph{Arguments}:
5118 @multitable @columnfractions .15 .70
5119 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5120 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5121 If both @var{I} and @var{J} have integer type, then they shall have
5122 the same kind type parameter. @var{I} and @var{J} shall not both be
5124 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
5125 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
5126 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
5127 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
5130 @item @emph{Return value}:
5131 If either @var{I} or @var{J} is a BOZ constant, it is first converted
5132 as if by the intrinsic function @code{INT} to an integer type with the
5133 kind type parameter of the other.
5135 @item @emph{See also}:
5141 @section @code{DTIME} --- Execution time subroutine (or function)
5143 @cindex time, elapsed
5144 @cindex elapsed time
5147 @item @emph{Description}:
5148 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
5149 since the start of the process's execution in @var{TIME}. @var{VALUES}
5150 returns the user and system components of this time in @code{VALUES(1)} and
5151 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
5154 Subsequent invocations of @code{DTIME} return values accumulated since the
5155 previous invocation.
5157 On some systems, the underlying timings are represented using types with
5158 sufficiently small limits that overflows (wrap around) are possible, such as
5159 32-bit types. Therefore, the values returned by this intrinsic might be, or
5160 become, negative, or numerically less than previous values, during a single
5161 run of the compiled program.
5163 Please note, that this implementation is thread safe if used within OpenMP
5164 directives, i.e., its state will be consistent while called from multiple
5165 threads. However, if @code{DTIME} is called from multiple threads, the result
5166 is still the time since the last invocation. This may not give the intended
5167 results. If possible, use @code{CPU_TIME} instead.
5169 This intrinsic is provided in both subroutine and function forms; however,
5170 only one form can be used in any given program unit.
5172 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
5174 @multitable @columnfractions .15 .30 .40
5175 @item @tab @code{VALUES(1)}: @tab User time in seconds.
5176 @item @tab @code{VALUES(2)}: @tab System time in seconds.
5177 @item @tab @code{TIME}: @tab Run time since start in seconds.
5180 @item @emph{Standard}:
5184 Subroutine, function
5186 @item @emph{Syntax}:
5187 @multitable @columnfractions .80
5188 @item @code{CALL DTIME(VALUES, TIME)}.
5189 @item @code{TIME = DTIME(VALUES)}, (not recommended).
5192 @item @emph{Arguments}:
5193 @multitable @columnfractions .15 .70
5194 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
5195 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
5198 @item @emph{Return value}:
5199 Elapsed time in seconds since the last invocation or since the start of program
5200 execution if not called before.
5202 @item @emph{Example}:
5206 real, dimension(2) :: tarray
5208 call dtime(tarray, result)
5212 do i=1,100000000 ! Just a delay
5215 call dtime(tarray, result)
5219 end program test_dtime
5222 @item @emph{See also}:
5230 @section @code{EOSHIFT} --- End-off shift elements of an array
5232 @cindex array, shift
5235 @item @emph{Description}:
5236 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
5237 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
5238 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
5239 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
5240 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
5241 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
5242 then all complete rank one sections of @var{ARRAY} along the given dimension are
5243 shifted. Elements shifted out one end of each rank one section are dropped. If
5244 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
5245 is copied back in the other end. If @var{BOUNDARY} is not present then the
5246 following are copied in depending on the type of @var{ARRAY}.
5248 @multitable @columnfractions .15 .80
5249 @item @emph{Array Type} @tab @emph{Boundary Value}
5250 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
5251 @item Logical @tab @code{.FALSE.}.
5252 @item Character(@var{len}) @tab @var{len} blanks.
5255 @item @emph{Standard}:
5256 Fortran 95 and later
5259 Transformational function
5261 @item @emph{Syntax}:
5262 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
5264 @item @emph{Arguments}:
5265 @multitable @columnfractions .15 .70
5266 @item @var{ARRAY} @tab May be any type, not scalar.
5267 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
5268 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
5269 @item @var{DIM} @tab The type shall be @code{INTEGER}.
5272 @item @emph{Return value}:
5273 Returns an array of same type and rank as the @var{ARRAY} argument.
5275 @item @emph{Example}:
5277 program test_eoshift
5278 integer, dimension(3,3) :: a
5279 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
5280 print '(3i3)', a(1,:)
5281 print '(3i3)', a(2,:)
5282 print '(3i3)', a(3,:)
5283 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
5285 print '(3i3)', a(1,:)
5286 print '(3i3)', a(2,:)
5287 print '(3i3)', a(3,:)
5288 end program test_eoshift
5295 @section @code{EPSILON} --- Epsilon function
5297 @cindex model representation, epsilon
5300 @item @emph{Description}:
5301 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
5302 as @var{X} such that @math{1 + E > 1}.
5304 @item @emph{Standard}:
5305 Fortran 95 and later
5310 @item @emph{Syntax}:
5311 @code{RESULT = EPSILON(X)}
5313 @item @emph{Arguments}:
5314 @multitable @columnfractions .15 .70
5315 @item @var{X} @tab The type shall be @code{REAL}.
5318 @item @emph{Return value}:
5319 The return value is of same type as the argument.
5321 @item @emph{Example}:
5323 program test_epsilon
5328 end program test_epsilon
5335 @section @code{ERF} --- Error function
5337 @cindex error function
5340 @item @emph{Description}:
5341 @code{ERF(X)} computes the error function of @var{X}.
5343 @item @emph{Standard}:
5344 Fortran 2008 and later
5349 @item @emph{Syntax}:
5350 @code{RESULT = ERF(X)}
5352 @item @emph{Arguments}:
5353 @multitable @columnfractions .15 .70
5354 @item @var{X} @tab The type shall be @code{REAL}.
5357 @item @emph{Return value}:
5358 The return value is of type @code{REAL}, of the same kind as
5359 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
5361 @item @emph{Example}:
5364 real(8) :: x = 0.17_8
5366 end program test_erf
5369 @item @emph{Specific names}:
5370 @multitable @columnfractions .20 .20 .20 .25
5371 @item Name @tab Argument @tab Return type @tab Standard
5372 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
5379 @section @code{ERFC} --- Error function
5381 @cindex error function, complementary
5384 @item @emph{Description}:
5385 @code{ERFC(X)} computes the complementary error function of @var{X}.
5387 @item @emph{Standard}:
5388 Fortran 2008 and later
5393 @item @emph{Syntax}:
5394 @code{RESULT = ERFC(X)}
5396 @item @emph{Arguments}:
5397 @multitable @columnfractions .15 .70
5398 @item @var{X} @tab The type shall be @code{REAL}.
5401 @item @emph{Return value}:
5402 The return value is of type @code{REAL} and of the same kind as @var{X}.
5403 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
5405 @item @emph{Example}:
5408 real(8) :: x = 0.17_8
5410 end program test_erfc
5413 @item @emph{Specific names}:
5414 @multitable @columnfractions .20 .20 .20 .25
5415 @item Name @tab Argument @tab Return type @tab Standard
5416 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
5423 @section @code{ERFC_SCALED} --- Error function
5424 @fnindex ERFC_SCALED
5425 @cindex error function, complementary, exponentially-scaled
5428 @item @emph{Description}:
5429 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
5430 error function of @var{X}.
5432 @item @emph{Standard}:
5433 Fortran 2008 and later
5438 @item @emph{Syntax}:
5439 @code{RESULT = ERFC_SCALED(X)}
5441 @item @emph{Arguments}:
5442 @multitable @columnfractions .15 .70
5443 @item @var{X} @tab The type shall be @code{REAL}.
5446 @item @emph{Return value}:
5447 The return value is of type @code{REAL} and of the same kind as @var{X}.
5449 @item @emph{Example}:
5451 program test_erfc_scaled
5452 real(8) :: x = 0.17_8
5454 end program test_erfc_scaled
5461 @section @code{ETIME} --- Execution time subroutine (or function)
5463 @cindex time, elapsed
5466 @item @emph{Description}:
5467 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
5468 since the start of the process's execution in @var{TIME}. @var{VALUES}
5469 returns the user and system components of this time in @code{VALUES(1)} and
5470 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
5472 On some systems, the underlying timings are represented using types with
5473 sufficiently small limits that overflows (wrap around) are possible, such as
5474 32-bit types. Therefore, the values returned by this intrinsic might be, or
5475 become, negative, or numerically less than previous values, during a single
5476 run of the compiled program.
5478 This intrinsic is provided in both subroutine and function forms; however,
5479 only one form can be used in any given program unit.
5481 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
5483 @multitable @columnfractions .15 .30 .60
5484 @item @tab @code{VALUES(1)}: @tab User time in seconds.
5485 @item @tab @code{VALUES(2)}: @tab System time in seconds.
5486 @item @tab @code{TIME}: @tab Run time since start in seconds.
5489 @item @emph{Standard}:
5493 Subroutine, function
5495 @item @emph{Syntax}:
5496 @multitable @columnfractions .80
5497 @item @code{CALL ETIME(VALUES, TIME)}.
5498 @item @code{TIME = ETIME(VALUES)}, (not recommended).
5501 @item @emph{Arguments}:
5502 @multitable @columnfractions .15 .70
5503 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
5504 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
5507 @item @emph{Return value}:
5508 Elapsed time in seconds since the start of program execution.
5510 @item @emph{Example}:
5514 real, dimension(2) :: tarray
5516 call ETIME(tarray, result)
5520 do i=1,100000000 ! Just a delay
5523 call ETIME(tarray, result)
5527 end program test_etime
5530 @item @emph{See also}:
5538 @section @code{EVENT_QUERY} --- Query whether a coarray event has occurred
5539 @fnindex EVENT_QUERY
5540 @cindex Events, EVENT_QUERY
5543 @item @emph{Description}:
5544 @code{EVENT_QUERY} assignes the number of events to @var{COUNT} which have been
5545 posted to the @var{EVENT} variable and not yet been removed by calling
5546 @code{EVENT WAIT}. When @var{STAT} is present and the invocation was successful,
5547 it is assigned the value 0. If it is present and the invocation has failed,
5548 it is assigned a positive value and @var{COUNT} is assigned the value @math{-1}.
5550 @item @emph{Standard}:
5556 @item @emph{Syntax}:
5557 @code{CALL EVENT_QUERY (EVENT, COUNT [, STAT])}
5559 @item @emph{Arguments}:
5560 @multitable @columnfractions .15 .70
5561 @item @var{EVENT} @tab (intent(IN)) Scalar of type @code{EVENT_TYPE},
5562 defined in @code{ISO_FORTRAN_ENV}; shall not be coindexed.
5563 @item @var{COUNT} @tab (intent(out))Scalar integer with at least the
5564 precision of default integer.
5565 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
5568 @item @emph{Example}:
5573 type(event_type) :: event_value_has_been_set[*]
5575 if (this_image() == 1) then
5576 call event_query (event_value_has_been_set, cnt)
5577 if (cnt > 0) write(*,*) "Value has been set"
5578 elseif (this_image() == 2) then
5579 event post (event_value_has_been_set[1])
5588 @node EXECUTE_COMMAND_LINE
5589 @section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
5590 @fnindex EXECUTE_COMMAND_LINE
5591 @cindex system, system call
5592 @cindex command line
5595 @item @emph{Description}:
5596 @code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
5599 The @code{COMMAND} argument is passed to the shell and executed, using
5600 the C library's @code{system} call. (The shell is @code{sh} on Unix
5601 systems, and @code{cmd.exe} on Windows.) If @code{WAIT} is present
5602 and has the value false, the execution of the command is asynchronous
5603 if the system supports it; otherwise, the command is executed
5606 The three last arguments allow the user to get status information. After
5607 synchronous execution, @code{EXITSTAT} contains the integer exit code of
5608 the command, as returned by @code{system}. @code{CMDSTAT} is set to zero
5609 if the command line was executed (whatever its exit status was).
5610 @code{CMDMSG} is assigned an error message if an error has occurred.
5612 Note that the @code{system} function need not be thread-safe. It is
5613 the responsibility of the user to ensure that @code{system} is not
5614 called concurrently.
5616 @item @emph{Standard}:
5617 Fortran 2008 and later
5622 @item @emph{Syntax}:
5623 @code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
5625 @item @emph{Arguments}:
5626 @multitable @columnfractions .15 .70
5627 @item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
5628 @item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
5629 @item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5631 @item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5633 @item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
5637 @item @emph{Example}:
5642 call execute_command_line ("external_prog.exe", exitstat=i)
5643 print *, "Exit status of external_prog.exe was ", i
5645 call execute_command_line ("reindex_files.exe", wait=.false.)
5646 print *, "Now reindexing files in the background"
5648 end program test_exec
5654 Because this intrinsic is implemented in terms of the @code{system}
5655 function call, its behavior with respect to signaling is processor
5656 dependent. In particular, on POSIX-compliant systems, the SIGINT and
5657 SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
5658 such, if the parent process is terminated, the child process might not be
5659 terminated alongside.
5662 @item @emph{See also}:
5669 @section @code{EXIT} --- Exit the program with status.
5671 @cindex program termination
5672 @cindex terminate program
5675 @item @emph{Description}:
5676 @code{EXIT} causes immediate termination of the program with status. If status
5677 is omitted it returns the canonical @emph{success} for the system. All Fortran
5678 I/O units are closed.
5680 @item @emph{Standard}:
5686 @item @emph{Syntax}:
5687 @code{CALL EXIT([STATUS])}
5689 @item @emph{Arguments}:
5690 @multitable @columnfractions .15 .70
5691 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
5694 @item @emph{Return value}:
5695 @code{STATUS} is passed to the parent process on exit.
5697 @item @emph{Example}:
5700 integer :: STATUS = 0
5701 print *, 'This program is going to exit.'
5703 end program test_exit
5706 @item @emph{See also}:
5707 @ref{ABORT}, @ref{KILL}
5713 @section @code{EXP} --- Exponential function
5719 @cindex exponential function
5720 @cindex logarithm function, inverse
5723 @item @emph{Description}:
5724 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
5726 @item @emph{Standard}:
5727 Fortran 77 and later, has overloads that are GNU extensions
5732 @item @emph{Syntax}:
5733 @code{RESULT = EXP(X)}
5735 @item @emph{Arguments}:
5736 @multitable @columnfractions .15 .70
5737 @item @var{X} @tab The type shall be @code{REAL} or
5741 @item @emph{Return value}:
5742 The return value has same type and kind as @var{X}.
5744 @item @emph{Example}:
5749 end program test_exp
5752 @item @emph{Specific names}:
5753 @multitable @columnfractions .20 .20 .20 .25
5754 @item Name @tab Argument @tab Return type @tab Standard
5755 @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
5756 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
5757 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
5758 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5759 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5766 @section @code{EXPONENT} --- Exponent function
5768 @cindex real number, exponent
5769 @cindex floating point, exponent
5772 @item @emph{Description}:
5773 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
5774 is zero the value returned is zero.
5776 @item @emph{Standard}:
5777 Fortran 95 and later
5782 @item @emph{Syntax}:
5783 @code{RESULT = EXPONENT(X)}
5785 @item @emph{Arguments}:
5786 @multitable @columnfractions .15 .70
5787 @item @var{X} @tab The type shall be @code{REAL}.
5790 @item @emph{Return value}:
5791 The return value is of type default @code{INTEGER}.
5793 @item @emph{Example}:
5795 program test_exponent
5800 print *, exponent(0.0)
5801 end program test_exponent
5807 @node EXTENDS_TYPE_OF
5808 @section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension
5809 @fnindex EXTENDS_TYPE_OF
5812 @item @emph{Description}:
5813 Query dynamic type for extension.
5815 @item @emph{Standard}:
5816 Fortran 2003 and later
5821 @item @emph{Syntax}:
5822 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
5824 @item @emph{Arguments}:
5825 @multitable @columnfractions .15 .70
5826 @item @var{A} @tab Shall be an object of extensible declared type or
5827 unlimited polymorphic.
5828 @item @var{MOLD} @tab Shall be an object of extensible declared type or
5829 unlimited polymorphic.
5832 @item @emph{Return value}:
5833 The return value is a scalar of type default logical. It is true if and only if
5834 the dynamic type of A is an extension type of the dynamic type of MOLD.
5837 @item @emph{See also}:
5844 @section @code{FDATE} --- Get the current time as a string
5846 @cindex time, current
5847 @cindex current time
5848 @cindex date, current
5849 @cindex current date
5852 @item @emph{Description}:
5853 @code{FDATE(DATE)} returns the current date (using the same format as
5854 @ref{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
5857 This intrinsic is provided in both subroutine and function forms; however,
5858 only one form can be used in any given program unit.
5860 @item @emph{Standard}:
5864 Subroutine, function
5866 @item @emph{Syntax}:
5867 @multitable @columnfractions .80
5868 @item @code{CALL FDATE(DATE)}.
5869 @item @code{DATE = FDATE()}.
5872 @item @emph{Arguments}:
5873 @multitable @columnfractions .15 .70
5874 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
5875 default kind. It is an @code{INTENT(OUT)} argument. If the length of
5876 this variable is too short for the date and time string to fit
5877 completely, it will be blank on procedure return.
5880 @item @emph{Return value}:
5881 The current date and time as a string.
5883 @item @emph{Example}:
5887 character(len=30) :: date
5889 print *, 'Program started on ', date
5890 do i = 1, 100000000 ! Just a delay
5894 print *, 'Program ended on ', date
5895 end program test_fdate
5898 @item @emph{See also}:
5899 @ref{DATE_AND_TIME}, @ref{CTIME}
5904 @section @code{FGET} --- Read a single character in stream mode from stdin
5906 @cindex read character, stream mode
5907 @cindex stream mode, read character
5908 @cindex file operation, read character
5911 @item @emph{Description}:
5912 Read a single character in stream mode from stdin by bypassing normal
5913 formatted output. Stream I/O should not be mixed with normal record-oriented
5914 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
5916 This intrinsic is provided in both subroutine and function forms; however,
5917 only one form can be used in any given program unit.
5919 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
5920 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5921 Programmers should consider the use of new stream IO feature in new code
5922 for future portability. See also @ref{Fortran 2003 status}.
5924 @item @emph{Standard}:
5928 Subroutine, function
5930 @item @emph{Syntax}:
5931 @multitable @columnfractions .80
5932 @item @code{CALL FGET(C [, STATUS])}
5933 @item @code{STATUS = FGET(C)}
5936 @item @emph{Arguments}:
5937 @multitable @columnfractions .15 .70
5938 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5940 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5941 Returns 0 on success, -1 on end-of-file, and a system specific positive
5942 error code otherwise.
5945 @item @emph{Example}:
5948 INTEGER, PARAMETER :: strlen = 100
5949 INTEGER :: status, i = 1
5950 CHARACTER(len=strlen) :: str = ""
5952 WRITE (*,*) 'Enter text:'
5954 CALL fget(str(i:i), status)
5955 if (status /= 0 .OR. i > strlen) exit
5958 WRITE (*,*) TRIM(str)
5962 @item @emph{See also}:
5963 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
5969 @section @code{FGETC} --- Read a single character in stream mode
5971 @cindex read character, stream mode
5972 @cindex stream mode, read character
5973 @cindex file operation, read character
5976 @item @emph{Description}:
5977 Read a single character in stream mode by bypassing normal formatted output.
5978 Stream I/O should not be mixed with normal record-oriented (formatted or
5979 unformatted) I/O on the same unit; the results are unpredictable.
5981 This intrinsic is provided in both subroutine and function forms; however,
5982 only one form can be used in any given program unit.
5984 Note that the @code{FGET} intrinsic is provided for backwards compatibility
5985 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5986 Programmers should consider the use of new stream IO feature in new code
5987 for future portability. See also @ref{Fortran 2003 status}.
5989 @item @emph{Standard}:
5993 Subroutine, function
5995 @item @emph{Syntax}:
5996 @multitable @columnfractions .80
5997 @item @code{CALL FGETC(UNIT, C [, STATUS])}
5998 @item @code{STATUS = FGETC(UNIT, C)}
6001 @item @emph{Arguments}:
6002 @multitable @columnfractions .15 .70
6003 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
6004 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6006 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6007 Returns 0 on success, -1 on end-of-file and a system specific positive
6008 error code otherwise.
6011 @item @emph{Example}:
6014 INTEGER :: fd = 42, status
6017 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
6019 CALL fgetc(fd, c, status)
6020 IF (status /= 0) EXIT
6027 @item @emph{See also}:
6028 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
6032 @section @code{FINDLOC} --- Search an array for a value
6037 @item @emph{Description}:
6038 Determines the location of the element in the array with the value
6039 given in the @var{VALUE} argument, or, if the @var{DIM} argument is
6040 supplied, determines the locations of the maximum element along each
6041 row of the array in the @var{DIM} direction. If @var{MASK} is
6042 present, only the elements for which @var{MASK} is @code{.TRUE.} are
6043 considered. If more than one element in the array has the value
6044 @var{VALUE}, the location returned is that of the first such element
6045 in array element order if the @var{BACK} is not present or if it is
6046 @code{.FALSE.}. If @var{BACK} is true, the location returned is that
6047 of the last such element. If the array has zero size, or all of the
6048 elements of @var{MASK} are @code{.FALSE.}, then the result is an array
6049 of zeroes. Similarly, if @var{DIM} is supplied and all of the
6050 elements of @var{MASK} along a given row are zero, the result value
6051 for that row is zero.
6053 @item @emph{Standard}:
6054 Fortran 2008 and later.
6057 Transformational function
6059 @item @emph{Syntax}:
6060 @multitable @columnfractions .80
6061 @item @code{RESULT = FINDLOC(ARRAY, VALUE, DIM [, MASK] [,KIND] [,BACK])}
6062 @item @code{RESULT = FINDLOC(ARRAY, VALUE, [, MASK] [,KIND] [,BACK])}
6065 @item @emph{Arguments}:
6066 @multitable @columnfractions .15 .70
6067 @item @var{ARRAY} @tab Shall be an array of intrinsic type.
6068 @item @var{VALUE} @tab A scalar of intrinsic type which is in type
6069 conformance with @var{ARRAY}.
6070 @item @var{DIM} @tab (Optional) Shall be a scalar of type
6071 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
6072 inclusive. It may not be an optional dummy argument.
6073 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6074 expression indicating the kind parameter of the result.
6075 @item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}.
6078 @item @emph{Return value}:
6079 If @var{DIM} is absent, the result is a rank-one array with a length
6080 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
6081 is an array with a rank one less than the rank of @var{ARRAY}, and a
6082 size corresponding to the size of @var{ARRAY} with the @var{DIM}
6083 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
6084 of one, the result is a scalar. If the optional argument @var{KIND}
6085 is present, the result is an integer of kind @var{KIND}, otherwise it
6088 @item @emph{See also}:
6089 @ref{MAXLOC}, @ref{MINLOC}
6094 @section @code{FLOOR} --- Integer floor function
6097 @cindex rounding, floor
6100 @item @emph{Description}:
6101 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
6103 @item @emph{Standard}:
6104 Fortran 95 and later
6109 @item @emph{Syntax}:
6110 @code{RESULT = FLOOR(A [, KIND])}
6112 @item @emph{Arguments}:
6113 @multitable @columnfractions .15 .70
6114 @item @var{A} @tab The type shall be @code{REAL}.
6115 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6116 expression indicating the kind parameter of the result.
6119 @item @emph{Return value}:
6120 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
6121 and of default-kind @code{INTEGER} otherwise.
6123 @item @emph{Example}:
6128 print *, floor(x) ! returns 63
6129 print *, floor(y) ! returns -64
6130 end program test_floor
6133 @item @emph{See also}:
6134 @ref{CEILING}, @ref{NINT}
6141 @section @code{FLUSH} --- Flush I/O unit(s)
6143 @cindex file operation, flush
6146 @item @emph{Description}:
6147 Flushes Fortran unit(s) currently open for output. Without the optional
6148 argument, all units are flushed, otherwise just the unit specified.
6150 @item @emph{Standard}:
6156 @item @emph{Syntax}:
6157 @code{CALL FLUSH(UNIT)}
6159 @item @emph{Arguments}:
6160 @multitable @columnfractions .15 .70
6161 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
6165 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
6166 statement that should be preferred over the @code{FLUSH} intrinsic.
6168 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
6169 have identical effect: they flush the runtime library's I/O buffer so
6170 that the data becomes visible to other processes. This does not guarantee
6171 that the data is committed to disk.
6173 On POSIX systems, you can request that all data is transferred to the
6174 storage device by calling the @code{fsync} function, with the POSIX file
6175 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
6176 @code{FNUM}). The following example shows how:
6179 ! Declare the interface for POSIX fsync function
6181 function fsync (fd) bind(c,name="fsync")
6182 use iso_c_binding, only: c_int
6183 integer(c_int), value :: fd
6184 integer(c_int) :: fsync
6188 ! Variable declaration
6192 open (10,file="foo")
6195 ! Perform I/O on unit 10
6200 ret = fsync(fnum(10))
6202 ! Handle possible error
6203 if (ret /= 0) stop "Error calling FSYNC"
6211 @section @code{FNUM} --- File number function
6213 @cindex file operation, file number
6216 @item @emph{Description}:
6217 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
6218 open Fortran I/O unit @code{UNIT}.
6220 @item @emph{Standard}:
6226 @item @emph{Syntax}:
6227 @code{RESULT = FNUM(UNIT)}
6229 @item @emph{Arguments}:
6230 @multitable @columnfractions .15 .70
6231 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
6234 @item @emph{Return value}:
6235 The return value is of type @code{INTEGER}
6237 @item @emph{Example}:
6241 open (unit=10, status = "scratch")
6245 end program test_fnum
6252 @section @code{FPUT} --- Write a single character in stream mode to stdout
6254 @cindex write character, stream mode
6255 @cindex stream mode, write character
6256 @cindex file operation, write character
6259 @item @emph{Description}:
6260 Write a single character in stream mode to stdout by bypassing normal
6261 formatted output. Stream I/O should not be mixed with normal record-oriented
6262 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
6264 This intrinsic is provided in both subroutine and function forms; however,
6265 only one form can be used in any given program unit.
6267 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
6268 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
6269 Programmers should consider the use of new stream IO feature in new code
6270 for future portability. See also @ref{Fortran 2003 status}.
6272 @item @emph{Standard}:
6276 Subroutine, function
6278 @item @emph{Syntax}:
6279 @multitable @columnfractions .80
6280 @item @code{CALL FPUT(C [, STATUS])}
6281 @item @code{STATUS = FPUT(C)}
6284 @item @emph{Arguments}:
6285 @multitable @columnfractions .15 .70
6286 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6288 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6289 Returns 0 on success, -1 on end-of-file and a system specific positive
6290 error code otherwise.
6293 @item @emph{Example}:
6296 CHARACTER(len=10) :: str = "gfortran"
6298 DO i = 1, len_trim(str)
6304 @item @emph{See also}:
6305 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
6311 @section @code{FPUTC} --- Write a single character in stream mode
6313 @cindex write character, stream mode
6314 @cindex stream mode, write character
6315 @cindex file operation, write character
6318 @item @emph{Description}:
6319 Write a single character in stream mode by bypassing normal formatted
6320 output. Stream I/O should not be mixed with normal record-oriented
6321 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
6323 This intrinsic is provided in both subroutine and function forms; however,
6324 only one form can be used in any given program unit.
6326 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
6327 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
6328 Programmers should consider the use of new stream IO feature in new code
6329 for future portability. See also @ref{Fortran 2003 status}.
6331 @item @emph{Standard}:
6335 Subroutine, function
6337 @item @emph{Syntax}:
6338 @multitable @columnfractions .80
6339 @item @code{CALL FPUTC(UNIT, C [, STATUS])}
6340 @item @code{STATUS = FPUTC(UNIT, C)}
6343 @item @emph{Arguments}:
6344 @multitable @columnfractions .15 .70
6345 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
6346 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6348 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6349 Returns 0 on success, -1 on end-of-file and a system specific positive
6350 error code otherwise.
6353 @item @emph{Example}:
6356 CHARACTER(len=10) :: str = "gfortran"
6357 INTEGER :: fd = 42, i
6359 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
6360 DO i = 1, len_trim(str)
6361 CALL fputc(fd, str(i:i))
6367 @item @emph{See also}:
6368 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
6374 @section @code{FRACTION} --- Fractional part of the model representation
6376 @cindex real number, fraction
6377 @cindex floating point, fraction
6380 @item @emph{Description}:
6381 @code{FRACTION(X)} returns the fractional part of the model
6382 representation of @code{X}.
6384 @item @emph{Standard}:
6385 Fortran 95 and later
6390 @item @emph{Syntax}:
6391 @code{Y = FRACTION(X)}
6393 @item @emph{Arguments}:
6394 @multitable @columnfractions .15 .70
6395 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
6398 @item @emph{Return value}:
6399 The return value is of the same type and kind as the argument.
6400 The fractional part of the model representation of @code{X} is returned;
6401 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
6403 @item @emph{Example}:
6405 program test_fraction
6408 print *, fraction(x), x * radix(x)**(-exponent(x))
6409 end program test_fraction
6417 @section @code{FREE} --- Frees memory
6419 @cindex pointer, cray
6422 @item @emph{Description}:
6423 Frees memory previously allocated by @code{MALLOC}. The @code{FREE}
6424 intrinsic is an extension intended to be used with Cray pointers, and is
6425 provided in GNU Fortran to allow user to compile legacy code. For
6426 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
6429 @item @emph{Standard}:
6435 @item @emph{Syntax}:
6436 @code{CALL FREE(PTR)}
6438 @item @emph{Arguments}:
6439 @multitable @columnfractions .15 .70
6440 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
6441 location of the memory that should be de-allocated.
6444 @item @emph{Return value}:
6447 @item @emph{Example}:
6448 See @code{MALLOC} for an example.
6450 @item @emph{See also}:
6457 @section @code{FSEEK} --- Low level file positioning subroutine
6459 @cindex file operation, seek
6460 @cindex file operation, position
6463 @item @emph{Description}:
6464 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
6465 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
6466 if set to 1, @var{OFFSET} is taken to be relative to the current position
6467 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
6468 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
6471 This intrinsic routine is not fully backwards compatible with @command{g77}.
6472 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
6473 @var{STATUS} variable. If FSEEK is used in old code, change
6475 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
6480 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
6481 IF (status /= 0) GOTO label
6484 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
6485 Programmers should consider the use of new stream IO feature in new code
6486 for future portability. See also @ref{Fortran 2003 status}.
6488 @item @emph{Standard}:
6494 @item @emph{Syntax}:
6495 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
6497 @item @emph{Arguments}:
6498 @multitable @columnfractions .15 .70
6499 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
6500 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
6501 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
6502 Its value shall be either 0, 1 or 2.
6503 @item @var{STATUS} @tab (Optional) shall be a scalar of type
6507 @item @emph{Example}:
6510 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
6511 INTEGER :: fd, offset, ierr
6517 OPEN(UNIT=fd, FILE="fseek.test")
6518 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
6519 print *, FTELL(fd), ierr
6521 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
6522 print *, FTELL(fd), ierr
6524 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
6525 print *, FTELL(fd), ierr
6531 @item @emph{See also}:
6538 @section @code{FSTAT} --- Get file status
6540 @cindex file system, file status
6543 @item @emph{Description}:
6544 @code{FSTAT} is identical to @ref{STAT}, except that information about an
6545 already opened file is obtained.
6547 The elements in @code{VALUES} are the same as described by @ref{STAT}.
6549 This intrinsic is provided in both subroutine and function forms; however,
6550 only one form can be used in any given program unit.
6552 @item @emph{Standard}:
6556 Subroutine, function
6558 @item @emph{Syntax}:
6559 @multitable @columnfractions .80
6560 @item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
6561 @item @code{STATUS = FSTAT(UNIT, VALUES)}
6564 @item @emph{Arguments}:
6565 @multitable @columnfractions .15 .70
6566 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
6567 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
6568 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
6569 on success and a system specific error code otherwise.
6572 @item @emph{Example}:
6573 See @ref{STAT} for an example.
6575 @item @emph{See also}:
6576 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
6582 @section @code{FTELL} --- Current stream position
6584 @cindex file operation, position
6587 @item @emph{Description}:
6588 Retrieves the current position within an open file.
6590 This intrinsic is provided in both subroutine and function forms; however,
6591 only one form can be used in any given program unit.
6593 @item @emph{Standard}:
6597 Subroutine, function
6599 @item @emph{Syntax}:
6600 @multitable @columnfractions .80
6601 @item @code{CALL FTELL(UNIT, OFFSET)}
6602 @item @code{OFFSET = FTELL(UNIT)}
6605 @item @emph{Arguments}:
6606 @multitable @columnfractions .15 .70
6607 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
6608 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
6611 @item @emph{Return value}:
6612 In either syntax, @var{OFFSET} is set to the current offset of unit
6613 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
6615 @item @emph{Example}:
6619 OPEN(10, FILE="temp.dat")
6625 @item @emph{See also}:
6632 @section @code{GAMMA} --- Gamma function
6635 @cindex Gamma function
6636 @cindex Factorial function
6639 @item @emph{Description}:
6640 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
6641 integer values of @var{X} the Gamma function simplifies to the factorial
6642 function @math{\Gamma(x)=(x-1)!}.
6646 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
6650 @item @emph{Standard}:
6651 Fortran 2008 and later
6656 @item @emph{Syntax}:
6659 @item @emph{Arguments}:
6660 @multitable @columnfractions .15 .70
6661 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
6662 nor a negative integer.
6665 @item @emph{Return value}:
6666 The return value is of type @code{REAL} of the same kind as @var{X}.
6668 @item @emph{Example}:
6672 x = gamma(x) ! returns 1.0
6673 end program test_gamma
6676 @item @emph{Specific names}:
6677 @multitable @columnfractions .20 .20 .20 .25
6678 @item Name @tab Argument @tab Return type @tab Standard
6679 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
6680 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
6683 @item @emph{See also}:
6684 Logarithm of the Gamma function: @ref{LOG_GAMMA}
6691 @section @code{GERROR} --- Get last system error message
6693 @cindex system, error handling
6696 @item @emph{Description}:
6697 Returns the system error message corresponding to the last system error.
6698 This resembles the functionality of @code{strerror(3)} in C.
6700 @item @emph{Standard}:
6706 @item @emph{Syntax}:
6707 @code{CALL GERROR(RESULT)}
6709 @item @emph{Arguments}:
6710 @multitable @columnfractions .15 .70
6711 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
6714 @item @emph{Example}:
6717 CHARACTER(len=100) :: msg
6723 @item @emph{See also}:
6724 @ref{IERRNO}, @ref{PERROR}
6730 @section @code{GETARG} --- Get command line arguments
6732 @cindex command-line arguments
6733 @cindex arguments, to program
6736 @item @emph{Description}:
6737 Retrieve the @var{POS}-th argument that was passed on the
6738 command line when the containing program was invoked.
6740 This intrinsic routine is provided for backwards compatibility with
6741 GNU Fortran 77. In new code, programmers should consider the use of
6742 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
6745 @item @emph{Standard}:
6751 @item @emph{Syntax}:
6752 @code{CALL GETARG(POS, VALUE)}
6754 @item @emph{Arguments}:
6755 @multitable @columnfractions .15 .70
6756 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
6757 the default integer kind; @math{@var{POS} \geq 0}
6758 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
6760 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
6763 @item @emph{Return value}:
6764 After @code{GETARG} returns, the @var{VALUE} argument holds the
6765 @var{POS}th command line argument. If @var{VALUE} can not hold the
6766 argument, it is truncated to fit the length of @var{VALUE}. If there are
6767 less than @var{POS} arguments specified at the command line, @var{VALUE}
6768 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
6769 to the name of the program (on systems that support this feature).
6771 @item @emph{Example}:
6775 CHARACTER(len=32) :: arg
6784 @item @emph{See also}:
6785 GNU Fortran 77 compatibility function: @ref{IARGC}
6787 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
6788 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6794 @section @code{GET_COMMAND} --- Get the entire command line
6795 @fnindex GET_COMMAND
6796 @cindex command-line arguments
6797 @cindex arguments, to program
6800 @item @emph{Description}:
6801 Retrieve the entire command line that was used to invoke the program.
6803 @item @emph{Standard}:
6804 Fortran 2003 and later
6809 @item @emph{Syntax}:
6810 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
6812 @item @emph{Arguments}:
6813 @multitable @columnfractions .15 .70
6814 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
6816 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
6818 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
6822 @item @emph{Return value}:
6823 If @var{COMMAND} is present, stores the entire command line that was used
6824 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
6825 assigned the length of the command line. If @var{STATUS} is present, it
6826 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
6827 short to store the command line, or a positive value in case of an error.
6829 @item @emph{Example}:
6831 PROGRAM test_get_command
6832 CHARACTER(len=255) :: cmd
6833 CALL get_command(cmd)
6834 WRITE (*,*) TRIM(cmd)
6838 @item @emph{See also}:
6839 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6844 @node GET_COMMAND_ARGUMENT
6845 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
6846 @fnindex GET_COMMAND_ARGUMENT
6847 @cindex command-line arguments
6848 @cindex arguments, to program
6851 @item @emph{Description}:
6852 Retrieve the @var{NUMBER}-th argument that was passed on the
6853 command line when the containing program was invoked.
6855 @item @emph{Standard}:
6856 Fortran 2003 and later
6861 @item @emph{Syntax}:
6862 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
6864 @item @emph{Arguments}:
6865 @multitable @columnfractions .15 .70
6866 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
6867 default kind, @math{@var{NUMBER} \geq 0}
6868 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
6869 and of default kind.
6870 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6871 and of default kind.
6872 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6873 and of default kind.
6876 @item @emph{Return value}:
6877 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
6878 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
6879 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
6880 arguments specified at the command line, @var{VALUE} will be filled with blanks.
6881 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
6882 systems that support this feature). The @var{LENGTH} argument contains the
6883 length of the @var{NUMBER}-th command line argument. If the argument retrieval
6884 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
6885 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
6888 @item @emph{Example}:
6890 PROGRAM test_get_command_argument
6892 CHARACTER(len=32) :: arg
6896 CALL get_command_argument(i, arg)
6897 IF (LEN_TRIM(arg) == 0) EXIT
6899 WRITE (*,*) TRIM(arg)
6905 @item @emph{See also}:
6906 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
6912 @section @code{GETCWD} --- Get current working directory
6914 @cindex system, working directory
6917 @item @emph{Description}:
6918 Get current working directory.
6920 This intrinsic is provided in both subroutine and function forms; however,
6921 only one form can be used in any given program unit.
6923 @item @emph{Standard}:
6927 Subroutine, function
6929 @item @emph{Syntax}:
6930 @multitable @columnfractions .80
6931 @item @code{CALL GETCWD(C [, STATUS])}
6932 @item @code{STATUS = GETCWD(C)}
6935 @item @emph{Arguments}:
6936 @multitable @columnfractions .15 .70
6937 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
6938 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
6939 a system specific and nonzero error code otherwise.
6942 @item @emph{Example}:
6945 CHARACTER(len=255) :: cwd
6947 WRITE(*,*) TRIM(cwd)
6951 @item @emph{See also}:
6958 @section @code{GETENV} --- Get an environmental variable
6960 @cindex environment variable
6963 @item @emph{Description}:
6964 Get the @var{VALUE} of the environmental variable @var{NAME}.
6966 This intrinsic routine is provided for backwards compatibility with
6967 GNU Fortran 77. In new code, programmers should consider the use of
6968 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
6971 Note that @code{GETENV} need not be thread-safe. It is the
6972 responsibility of the user to ensure that the environment is not being
6973 updated concurrently with a call to the @code{GETENV} intrinsic.
6975 @item @emph{Standard}:
6981 @item @emph{Syntax}:
6982 @code{CALL GETENV(NAME, VALUE)}
6984 @item @emph{Arguments}:
6985 @multitable @columnfractions .15 .70
6986 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
6987 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
6990 @item @emph{Return value}:
6991 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
6992 not large enough to hold the data, it is truncated. If @var{NAME}
6993 is not set, @var{VALUE} will be filled with blanks.
6995 @item @emph{Example}:
6998 CHARACTER(len=255) :: homedir
6999 CALL getenv("HOME", homedir)
7000 WRITE (*,*) TRIM(homedir)
7004 @item @emph{See also}:
7005 @ref{GET_ENVIRONMENT_VARIABLE}
7010 @node GET_ENVIRONMENT_VARIABLE
7011 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
7012 @fnindex GET_ENVIRONMENT_VARIABLE
7013 @cindex environment variable
7016 @item @emph{Description}:
7017 Get the @var{VALUE} of the environmental variable @var{NAME}.
7019 Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It
7020 is the responsibility of the user to ensure that the environment is
7021 not being updated concurrently with a call to the
7022 @code{GET_ENVIRONMENT_VARIABLE} intrinsic.
7024 @item @emph{Standard}:
7025 Fortran 2003 and later
7030 @item @emph{Syntax}:
7031 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
7033 @item @emph{Arguments}:
7034 @multitable @columnfractions .15 .70
7035 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
7036 and of default kind.
7037 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
7038 and of default kind.
7039 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
7040 and of default kind.
7041 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
7042 and of default kind.
7043 @item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL}
7044 and of default kind.
7047 @item @emph{Return value}:
7048 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
7049 not large enough to hold the data, it is truncated. If @var{NAME}
7050 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
7051 contains the length needed for storing the environment variable @var{NAME}
7052 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
7053 but too short for the environment variable; it is 1 if the environment
7054 variable does not exist and 2 if the processor does not support environment
7055 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
7056 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
7057 are significant; otherwise they are not part of the environment variable
7060 @item @emph{Example}:
7063 CHARACTER(len=255) :: homedir
7064 CALL get_environment_variable("HOME", homedir)
7065 WRITE (*,*) TRIM(homedir)
7073 @section @code{GETGID} --- Group ID function
7075 @cindex system, group ID
7078 @item @emph{Description}:
7079 Returns the numerical group ID of the current process.
7081 @item @emph{Standard}:
7087 @item @emph{Syntax}:
7088 @code{RESULT = GETGID()}
7090 @item @emph{Return value}:
7091 The return value of @code{GETGID} is an @code{INTEGER} of the default
7095 @item @emph{Example}:
7096 See @code{GETPID} for an example.
7098 @item @emph{See also}:
7099 @ref{GETPID}, @ref{GETUID}
7105 @section @code{GETLOG} --- Get login name
7107 @cindex system, login name
7111 @item @emph{Description}:
7112 Gets the username under which the program is running.
7114 @item @emph{Standard}:
7120 @item @emph{Syntax}:
7121 @code{CALL GETLOG(C)}
7123 @item @emph{Arguments}:
7124 @multitable @columnfractions .15 .70
7125 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
7128 @item @emph{Return value}:
7129 Stores the current user name in @var{LOGIN}. (On systems where POSIX
7130 functions @code{geteuid} and @code{getpwuid} are not available, and
7131 the @code{getlogin} function is not implemented either, this will
7132 return a blank string.)
7134 @item @emph{Example}:
7137 CHARACTER(32) :: login
7143 @item @emph{See also}:
7150 @section @code{GETPID} --- Process ID function
7152 @cindex system, process ID
7156 @item @emph{Description}:
7157 Returns the numerical process identifier of the current process.
7159 @item @emph{Standard}:
7165 @item @emph{Syntax}:
7166 @code{RESULT = GETPID()}
7168 @item @emph{Return value}:
7169 The return value of @code{GETPID} is an @code{INTEGER} of the default
7173 @item @emph{Example}:
7176 print *, "The current process ID is ", getpid()
7177 print *, "Your numerical user ID is ", getuid()
7178 print *, "Your numerical group ID is ", getgid()
7182 @item @emph{See also}:
7183 @ref{GETGID}, @ref{GETUID}
7189 @section @code{GETUID} --- User ID function
7191 @cindex system, user ID
7195 @item @emph{Description}:
7196 Returns the numerical user ID of the current process.
7198 @item @emph{Standard}:
7204 @item @emph{Syntax}:
7205 @code{RESULT = GETUID()}
7207 @item @emph{Return value}:
7208 The return value of @code{GETUID} is an @code{INTEGER} of the default
7212 @item @emph{Example}:
7213 See @code{GETPID} for an example.
7215 @item @emph{See also}:
7216 @ref{GETPID}, @ref{GETLOG}
7222 @section @code{GMTIME} --- Convert time to GMT info
7224 @cindex time, conversion to GMT info
7227 @item @emph{Description}:
7228 Given a system time value @var{TIME} (as provided by the @ref{TIME}
7229 intrinsic), fills @var{VALUES} with values extracted from it appropriate
7230 to the UTC time zone (Universal Coordinated Time, also known in some
7231 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
7233 This intrinsic routine is provided for backwards compatibility with
7234 GNU Fortran 77. In new code, programmers should consider the use of
7235 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
7238 @item @emph{Standard}:
7244 @item @emph{Syntax}:
7245 @code{CALL GMTIME(TIME, VALUES)}
7247 @item @emph{Arguments}:
7248 @multitable @columnfractions .15 .70
7249 @item @var{TIME} @tab An @code{INTEGER} scalar expression
7250 corresponding to a system time, with @code{INTENT(IN)}.
7251 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
7252 with @code{INTENT(OUT)}.
7255 @item @emph{Return value}:
7256 The elements of @var{VALUES} are assigned as follows:
7258 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
7260 @item Minutes after the hour, range 0--59
7261 @item Hours past midnight, range 0--23
7262 @item Day of month, range 1--31
7263 @item Number of months since January, range 0--11
7264 @item Years since 1900
7265 @item Number of days since Sunday, range 0--6
7266 @item Days since January 1, range 0--365
7267 @item Daylight savings indicator: positive if daylight savings is in
7268 effect, zero if not, and negative if the information is not available.
7271 @item @emph{See also}:
7272 @ref{DATE_AND_TIME}, @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
7279 @section @code{HOSTNM} --- Get system host name
7281 @cindex system, host name
7284 @item @emph{Description}:
7285 Retrieves the host name of the system on which the program is running.
7287 This intrinsic is provided in both subroutine and function forms; however,
7288 only one form can be used in any given program unit.
7290 @item @emph{Standard}:
7294 Subroutine, function
7296 @item @emph{Syntax}:
7297 @multitable @columnfractions .80
7298 @item @code{CALL HOSTNM(C [, STATUS])}
7299 @item @code{STATUS = HOSTNM(NAME)}
7302 @item @emph{Arguments}:
7303 @multitable @columnfractions .15 .70
7304 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
7305 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
7306 Returns 0 on success, or a system specific error code otherwise.
7309 @item @emph{Return value}:
7310 In either syntax, @var{NAME} is set to the current hostname if it can
7311 be obtained, or to a blank string otherwise.
7318 @section @code{HUGE} --- Largest number of a kind
7320 @cindex limits, largest number
7321 @cindex model representation, largest number
7324 @item @emph{Description}:
7325 @code{HUGE(X)} returns the largest number that is not an infinity in
7326 the model of the type of @code{X}.
7328 @item @emph{Standard}:
7329 Fortran 95 and later
7334 @item @emph{Syntax}:
7335 @code{RESULT = HUGE(X)}
7337 @item @emph{Arguments}:
7338 @multitable @columnfractions .15 .70
7339 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
7342 @item @emph{Return value}:
7343 The return value is of the same type and kind as @var{X}
7345 @item @emph{Example}:
7347 program test_huge_tiny
7348 print *, huge(0), huge(0.0), huge(0.0d0)
7349 print *, tiny(0.0), tiny(0.0d0)
7350 end program test_huge_tiny
7357 @section @code{HYPOT} --- Euclidean distance function
7359 @cindex Euclidean distance
7362 @item @emph{Description}:
7363 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
7364 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
7366 @item @emph{Standard}:
7367 Fortran 2008 and later
7372 @item @emph{Syntax}:
7373 @code{RESULT = HYPOT(X, Y)}
7375 @item @emph{Arguments}:
7376 @multitable @columnfractions .15 .70
7377 @item @var{X} @tab The type shall be @code{REAL}.
7378 @item @var{Y} @tab The type and kind type parameter shall be the same as
7382 @item @emph{Return value}:
7383 The return value has the same type and kind type parameter as @var{X}.
7385 @item @emph{Example}:
7388 real(4) :: x = 1.e0_4, y = 0.5e0_4
7390 end program test_hypot
7397 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
7399 @cindex @acronym{ASCII} collating sequence
7400 @cindex collating sequence, @acronym{ASCII}
7401 @cindex conversion, to integer
7404 @item @emph{Description}:
7405 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
7406 in the first character position of @code{C}.
7408 @item @emph{Standard}:
7409 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7414 @item @emph{Syntax}:
7415 @code{RESULT = IACHAR(C [, KIND])}
7417 @item @emph{Arguments}:
7418 @multitable @columnfractions .15 .70
7419 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
7420 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7421 expression indicating the kind parameter of the result.
7424 @item @emph{Return value}:
7425 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7426 @var{KIND} is absent, the return value is of default integer kind.
7428 @item @emph{Example}:
7433 end program test_iachar
7437 See @ref{ICHAR} for a discussion of converting between numerical values
7438 and formatted string representations.
7440 @item @emph{See also}:
7441 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
7448 @section @code{IALL} --- Bitwise AND of array elements
7451 @cindex bits, AND of array elements
7454 @item @emph{Description}:
7455 Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
7456 if the corresponding element in @var{MASK} is @code{TRUE}.
7458 @item @emph{Standard}:
7459 Fortran 2008 and later
7462 Transformational function
7464 @item @emph{Syntax}:
7465 @multitable @columnfractions .80
7466 @item @code{RESULT = IALL(ARRAY[, MASK])}
7467 @item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
7470 @item @emph{Arguments}:
7471 @multitable @columnfractions .15 .70
7472 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7473 @item @var{DIM} @tab (Optional) shall be a scalar of type
7474 @code{INTEGER} with a value in the range from 1 to n, where n
7475 equals the rank of @var{ARRAY}.
7476 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
7477 and either be a scalar or an array of the same shape as @var{ARRAY}.
7480 @item @emph{Return value}:
7481 The result is of the same type as @var{ARRAY}.
7483 If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
7484 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7485 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7486 dimension @var{DIM} dropped is returned.
7488 @item @emph{Example}:
7497 PRINT '(b8.8)', IALL(a)
7501 @item @emph{See also}:
7502 @ref{IANY}, @ref{IPARITY}, @ref{IAND}
7508 @section @code{IAND} --- Bitwise logical and
7514 @cindex bitwise logical and
7515 @cindex logical and, bitwise
7518 @item @emph{Description}:
7519 Bitwise logical @code{AND}.
7521 @item @emph{Standard}:
7522 Fortran 95 and later, has overloads that are GNU extensions
7527 @item @emph{Syntax}:
7528 @code{RESULT = IAND(I, J)}
7530 @item @emph{Arguments}:
7531 @multitable @columnfractions .15 .70
7532 @item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant.
7533 @item @var{J} @tab The type shall be @code{INTEGER} with the same
7534 kind type parameter as @var{I} or a boz-literal-constant.
7535 @var{I} and @var{J} shall not both be boz-literal-constants.
7538 @item @emph{Return value}:
7539 The return type is @code{INTEGER} with the kind type parameter of the
7541 A boz-literal-constant is converted to an @code{INTEGER} with the kind
7542 type parameter of the other argument as-if a call to @ref{INT} occurred.
7544 @item @emph{Example}:
7548 DATA a / Z'F' /, b / Z'3' /
7549 WRITE (*,*) IAND(a, b)
7553 @item @emph{Specific names}:
7554 @multitable @columnfractions .20 .20 .20 .25
7555 @item Name @tab Argument @tab Return type @tab Standard
7556 @item @code{IAND(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7557 @item @code{BIAND(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7558 @item @code{IIAND(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7559 @item @code{JIAND(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7560 @item @code{KIAND(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7563 @item @emph{See also}:
7564 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
7571 @section @code{IANY} --- Bitwise OR of array elements
7574 @cindex bits, OR of array elements
7577 @item @emph{Description}:
7578 Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
7579 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
7581 @item @emph{Standard}:
7582 Fortran 2008 and later
7585 Transformational function
7587 @item @emph{Syntax}:
7588 @multitable @columnfractions .80
7589 @item @code{RESULT = IANY(ARRAY[, MASK])}
7590 @item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
7593 @item @emph{Arguments}:
7594 @multitable @columnfractions .15 .70
7595 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7596 @item @var{DIM} @tab (Optional) shall be a scalar of type
7597 @code{INTEGER} with a value in the range from 1 to n, where n
7598 equals the rank of @var{ARRAY}.
7599 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
7600 and either be a scalar or an array of the same shape as @var{ARRAY}.
7603 @item @emph{Return value}:
7604 The result is of the same type as @var{ARRAY}.
7606 If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
7607 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7608 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7609 dimension @var{DIM} dropped is returned.
7611 @item @emph{Example}:
7620 PRINT '(b8.8)', IANY(a)
7624 @item @emph{See also}:
7625 @ref{IPARITY}, @ref{IALL}, @ref{IOR}
7631 @section @code{IARGC} --- Get the number of command line arguments
7633 @cindex command-line arguments
7634 @cindex command-line arguments, number of
7635 @cindex arguments, to program
7638 @item @emph{Description}:
7639 @code{IARGC} returns the number of arguments passed on the
7640 command line when the containing program was invoked.
7642 This intrinsic routine is provided for backwards compatibility with
7643 GNU Fortran 77. In new code, programmers should consider the use of
7644 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
7647 @item @emph{Standard}:
7653 @item @emph{Syntax}:
7654 @code{RESULT = IARGC()}
7656 @item @emph{Arguments}:
7659 @item @emph{Return value}:
7660 The number of command line arguments, type @code{INTEGER(4)}.
7662 @item @emph{Example}:
7665 @item @emph{See also}:
7666 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
7668 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
7669 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
7675 @section @code{IBCLR} --- Clear bit
7685 @item @emph{Description}:
7686 @code{IBCLR} returns the value of @var{I} with the bit at position
7687 @var{POS} set to zero.
7689 @item @emph{Standard}:
7690 Fortran 95 and later, has overloads that are GNU extensions
7695 @item @emph{Syntax}:
7696 @code{RESULT = IBCLR(I, POS)}
7698 @item @emph{Arguments}:
7699 @multitable @columnfractions .15 .70
7700 @item @var{I} @tab The type shall be @code{INTEGER}.
7701 @item @var{POS} @tab The type shall be @code{INTEGER}.
7704 @item @emph{Return value}:
7705 The return value is of type @code{INTEGER} and of the same kind as
7708 @item @emph{Specific names}:
7709 @multitable @columnfractions .20 .20 .20 .25
7710 @item Name @tab Argument @tab Return type @tab Standard
7711 @item @code{IBCLR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7712 @item @code{BBCLR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7713 @item @code{IIBCLR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7714 @item @code{JIBCLR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7715 @item @code{KIBCLR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7718 @item @emph{See also}:
7719 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
7726 @section @code{IBITS} --- Bit extraction
7733 @cindex bits, extract
7736 @item @emph{Description}:
7737 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
7738 starting from bit position @var{POS} and extending left for @var{LEN}
7739 bits. The result is right-justified and the remaining bits are
7740 zeroed. The value of @code{POS+LEN} must be less than or equal to the
7741 value @code{BIT_SIZE(I)}.
7743 @item @emph{Standard}:
7744 Fortran 95 and later, has overloads that are GNU extensions
7749 @item @emph{Syntax}:
7750 @code{RESULT = IBITS(I, POS, LEN)}
7752 @item @emph{Arguments}:
7753 @multitable @columnfractions .15 .70
7754 @item @var{I} @tab The type shall be @code{INTEGER}.
7755 @item @var{POS} @tab The type shall be @code{INTEGER}.
7756 @item @var{LEN} @tab The type shall be @code{INTEGER}.
7759 @item @emph{Return value}:
7760 The return value is of type @code{INTEGER} and of the same kind as
7763 @item @emph{Specific names}:
7764 @multitable @columnfractions .20 .20 .20 .25
7765 @item Name @tab Argument @tab Return type @tab Standard
7766 @item @code{IBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7767 @item @code{BBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7768 @item @code{IIBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7769 @item @code{JIBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7770 @item @code{KIBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7773 @item @emph{See also}:
7774 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
7780 @section @code{IBSET} --- Set bit
7789 @item @emph{Description}:
7790 @code{IBSET} returns the value of @var{I} with the bit at position
7791 @var{POS} set to one.
7793 @item @emph{Standard}:
7794 Fortran 95 and later, has overloads that are GNU extensions
7799 @item @emph{Syntax}:
7800 @code{RESULT = IBSET(I, POS)}
7802 @item @emph{Arguments}:
7803 @multitable @columnfractions .15 .70
7804 @item @var{I} @tab The type shall be @code{INTEGER}.
7805 @item @var{POS} @tab The type shall be @code{INTEGER}.
7808 @item @emph{Return value}:
7809 The return value is of type @code{INTEGER} and of the same kind as
7812 @item @emph{Specific names}:
7813 @multitable @columnfractions .20 .20 .20 .25
7814 @item Name @tab Argument @tab Return type @tab Standard
7815 @item @code{IBSET(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7816 @item @code{BBSET(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7817 @item @code{IIBSET(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7818 @item @code{JIBSET(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7819 @item @code{KIBSET(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7822 @item @emph{See also}:
7823 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
7830 @section @code{ICHAR} --- Character-to-integer conversion function
7832 @cindex conversion, to integer
7835 @item @emph{Description}:
7836 @code{ICHAR(C)} returns the code for the character in the first character
7837 position of @code{C} in the system's native character set.
7838 The correspondence between characters and their codes is not necessarily
7839 the same across different GNU Fortran implementations.
7841 @item @emph{Standard}:
7842 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7847 @item @emph{Syntax}:
7848 @code{RESULT = ICHAR(C [, KIND])}
7850 @item @emph{Arguments}:
7851 @multitable @columnfractions .15 .70
7852 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
7853 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7854 expression indicating the kind parameter of the result.
7857 @item @emph{Return value}:
7858 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7859 @var{KIND} is absent, the return value is of default integer kind.
7861 @item @emph{Example}:
7866 end program test_ichar
7869 @item @emph{Specific names}:
7870 @multitable @columnfractions .20 .20 .20 .25
7871 @item Name @tab Argument @tab Return type @tab Standard
7872 @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7876 No intrinsic exists to convert between a numeric value and a formatted
7877 character string representation -- for instance, given the
7878 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
7879 @code{REAL} value with the value 154, or vice versa. Instead, this
7880 functionality is provided by internal-file I/O, as in the following
7885 character(len=10) string, string2
7888 ! Convert a string to a numeric value
7889 read (string,'(I10)') value
7892 ! Convert a value to a formatted string
7893 write (string2,'(I10)') value
7895 end program read_val
7898 @item @emph{See also}:
7899 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
7906 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
7908 @cindex date, current
7909 @cindex current date
7912 @item @emph{Description}:
7913 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
7914 current local time. The day (in the range 1-31), month (in the range 1-12),
7915 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
7916 The year has four significant digits.
7918 This intrinsic routine is provided for backwards compatibility with
7919 GNU Fortran 77. In new code, programmers should consider the use of
7920 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
7923 @item @emph{Standard}:
7929 @item @emph{Syntax}:
7930 @code{CALL IDATE(VALUES)}
7932 @item @emph{Arguments}:
7933 @multitable @columnfractions .15 .70
7934 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
7935 the kind shall be the default integer kind.
7938 @item @emph{Return value}:
7939 Does not return anything.
7941 @item @emph{Example}:
7944 integer, dimension(3) :: tarray
7949 end program test_idate
7952 @item @emph{See also}:
7958 @section @code{IEOR} --- Bitwise logical exclusive or
7964 @cindex bitwise logical exclusive or
7965 @cindex logical exclusive or, bitwise
7968 @item @emph{Description}:
7969 @code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
7972 @item @emph{Standard}:
7973 Fortran 95 and later, has overloads that are GNU extensions
7978 @item @emph{Syntax}:
7979 @code{RESULT = IEOR(I, J)}
7981 @item @emph{Arguments}:
7982 @multitable @columnfractions .15 .70
7983 @item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant.
7984 @item @var{J} @tab The type shall be @code{INTEGER} with the same
7985 kind type parameter as @var{I} or a boz-literal-constant.
7986 @var{I} and @var{J} shall not both be boz-literal-constants.
7989 @item @emph{Return value}:
7990 The return type is @code{INTEGER} with the kind type parameter of the
7992 A boz-literal-constant is converted to an @code{INTEGER} with the kind
7993 type parameter of the other argument as-if a call to @ref{INT} occurred.
7995 @item @emph{Specific names}:
7996 @multitable @columnfractions .20 .20 .20 .25
7997 @item Name @tab Argument @tab Return type @tab Standard
7998 @item @code{IEOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7999 @item @code{BIEOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8000 @item @code{IIEOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8001 @item @code{JIEOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8002 @item @code{KIEOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8005 @item @emph{See also}:
8006 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
8012 @section @code{IERRNO} --- Get the last system error number
8014 @cindex system, error handling
8017 @item @emph{Description}:
8018 Returns the last system error number, as given by the C @code{errno}
8021 @item @emph{Standard}:
8027 @item @emph{Syntax}:
8028 @code{RESULT = IERRNO()}
8030 @item @emph{Arguments}:
8033 @item @emph{Return value}:
8034 The return value is of type @code{INTEGER} and of the default integer
8037 @item @emph{See also}:
8044 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
8045 @fnindex IMAGE_INDEX
8046 @cindex coarray, @code{IMAGE_INDEX}
8047 @cindex images, cosubscript to image index conversion
8050 @item @emph{Description}:
8051 Returns the image index belonging to a cosubscript.
8053 @item @emph{Standard}:
8054 Fortran 2008 and later
8059 @item @emph{Syntax}:
8060 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
8062 @item @emph{Arguments}: None.
8063 @multitable @columnfractions .15 .70
8064 @item @var{COARRAY} @tab Coarray of any type.
8065 @item @var{SUB} @tab default integer rank-1 array of a size equal to
8066 the corank of @var{COARRAY}.
8070 @item @emph{Return value}:
8071 Scalar default integer with the value of the image index which corresponds
8072 to the cosubscripts. For invalid cosubscripts the result is zero.
8074 @item @emph{Example}:
8076 INTEGER :: array[2,-1:4,8,*]
8077 ! Writes 28 (or 0 if there are fewer than 28 images)
8078 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
8081 @item @emph{See also}:
8082 @ref{THIS_IMAGE}, @ref{NUM_IMAGES}
8087 @node INDEX intrinsic
8088 @section @code{INDEX} --- Position of a substring within a string
8090 @cindex substring position
8091 @cindex string, find substring
8094 @item @emph{Description}:
8095 Returns the position of the start of the first occurrence of string
8096 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
8097 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
8098 the @var{BACK} argument is present and true, the return value is the
8099 start of the last occurrence rather than the first.
8101 @item @emph{Standard}:
8102 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
8107 @item @emph{Syntax}:
8108 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
8110 @item @emph{Arguments}:
8111 @multitable @columnfractions .15 .70
8112 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
8114 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
8116 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
8118 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8119 expression indicating the kind parameter of the result.
8122 @item @emph{Return value}:
8123 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8124 @var{KIND} is absent, the return value is of default integer kind.
8126 @item @emph{Specific names}:
8127 @multitable @columnfractions .20 .20 .20 .25
8128 @item Name @tab Argument @tab Return type @tab Standard
8129 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8132 @item @emph{See also}:
8133 @ref{SCAN}, @ref{VERIFY}
8139 @section @code{INT} --- Convert to integer type
8143 @cindex conversion, to integer
8146 @item @emph{Description}:
8147 Convert to integer type
8149 @item @emph{Standard}:
8150 Fortran 77 and later
8155 @item @emph{Syntax}:
8156 @code{RESULT = INT(A [, KIND))}
8158 @item @emph{Arguments}:
8159 @multitable @columnfractions .15 .70
8160 @item @var{A} @tab Shall be of type @code{INTEGER},
8161 @code{REAL}, or @code{COMPLEX}.
8162 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8163 expression indicating the kind parameter of the result.
8166 @item @emph{Return value}:
8167 These functions return a @code{INTEGER} variable or array under
8168 the following rules:
8172 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
8174 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)}
8175 equals @code{0}. If @math{|A| \geq 1}, then @code{INT(A)} is the integer
8176 whose magnitude is the largest integer that does not exceed the magnitude
8177 of @var{A} and whose sign is the same as the sign of @var{A}.
8179 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
8182 @item @emph{Example}:
8186 complex :: z = (-3.7, 1.0)
8188 print *, int(z), int(z,8)
8192 @item @emph{Specific names}:
8193 @multitable @columnfractions .20 .20 .20 .25
8194 @item Name @tab Argument @tab Return type @tab Standard
8195 @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
8196 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
8197 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
8204 @section @code{INT2} --- Convert to 16-bit integer type
8207 @cindex conversion, to integer
8210 @item @emph{Description}:
8211 Convert to a @code{KIND=2} integer type. This is equivalent to the
8212 standard @code{INT} intrinsic with an optional argument of
8213 @code{KIND=2}, and is only included for backwards compatibility.
8215 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
8217 @item @emph{Standard}:
8223 @item @emph{Syntax}:
8224 @code{RESULT = INT2(A)}
8226 @item @emph{Arguments}:
8227 @multitable @columnfractions .15 .70
8228 @item @var{A} @tab Shall be of type @code{INTEGER},
8229 @code{REAL}, or @code{COMPLEX}.
8232 @item @emph{Return value}:
8233 The return value is a @code{INTEGER(2)} variable.
8235 @item @emph{See also}:
8236 @ref{INT}, @ref{INT8}, @ref{LONG}
8242 @section @code{INT8} --- Convert to 64-bit integer type
8244 @cindex conversion, to integer
8247 @item @emph{Description}:
8248 Convert to a @code{KIND=8} integer type. This is equivalent to the
8249 standard @code{INT} intrinsic with an optional argument of
8250 @code{KIND=8}, and is only included for backwards compatibility.
8252 @item @emph{Standard}:
8258 @item @emph{Syntax}:
8259 @code{RESULT = INT8(A)}
8261 @item @emph{Arguments}:
8262 @multitable @columnfractions .15 .70
8263 @item @var{A} @tab Shall be of type @code{INTEGER},
8264 @code{REAL}, or @code{COMPLEX}.
8267 @item @emph{Return value}:
8268 The return value is a @code{INTEGER(8)} variable.
8270 @item @emph{See also}:
8271 @ref{INT}, @ref{INT2}, @ref{LONG}
8277 @section @code{IOR} --- Bitwise logical or
8283 @cindex bitwise logical or
8284 @cindex logical or, bitwise
8287 @item @emph{Description}:
8288 @code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
8291 @item @emph{Standard}:
8292 Fortran 95 and later, has overloads that are GNU extensions
8297 @item @emph{Syntax}:
8298 @code{RESULT = IOR(I, J)}
8300 @item @emph{Arguments}:
8301 @multitable @columnfractions .15 .70
8302 @item @var{I} @tab The type shall be @code{INTEGER} or a boz-literal-constant.
8303 @item @var{J} @tab The type shall be @code{INTEGER} with the same
8304 kind type parameter as @var{I} or a boz-literal-constant.
8305 @var{I} and @var{J} shall not both be boz-literal-constants.
8308 @item @emph{Return value}:
8309 The return type is @code{INTEGER} with the kind type parameter of the
8311 A boz-literal-constant is converted to an @code{INTEGER} with the kind
8312 type parameter of the other argument as-if a call to @ref{INT} occurred.
8314 @item @emph{Specific names}:
8315 @multitable @columnfractions .20 .20 .20 .25
8316 @item Name @tab Argument @tab Return type @tab Standard
8317 @item @code{IOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
8318 @item @code{BIOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8319 @item @code{IIOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8320 @item @code{JIOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8321 @item @code{KIOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8324 @item @emph{See also}:
8325 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
8331 @section @code{IPARITY} --- Bitwise XOR of array elements
8333 @cindex array, parity
8335 @cindex bits, XOR of array elements
8338 @item @emph{Description}:
8339 Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
8340 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
8342 @item @emph{Standard}:
8343 Fortran 2008 and later
8346 Transformational function
8348 @item @emph{Syntax}:
8349 @multitable @columnfractions .80
8350 @item @code{RESULT = IPARITY(ARRAY[, MASK])}
8351 @item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
8354 @item @emph{Arguments}:
8355 @multitable @columnfractions .15 .70
8356 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
8357 @item @var{DIM} @tab (Optional) shall be a scalar of type
8358 @code{INTEGER} with a value in the range from 1 to n, where n
8359 equals the rank of @var{ARRAY}.
8360 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
8361 and either be a scalar or an array of the same shape as @var{ARRAY}.
8364 @item @emph{Return value}:
8365 The result is of the same type as @var{ARRAY}.
8367 If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
8368 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
8369 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
8370 dimension @var{DIM} dropped is returned.
8372 @item @emph{Example}:
8374 PROGRAM test_iparity
8381 PRINT '(b8.8)', IPARITY(a)
8385 @item @emph{See also}:
8386 @ref{IANY}, @ref{IALL}, @ref{IEOR}, @ref{PARITY}
8392 @section @code{IRAND} --- Integer pseudo-random number
8394 @cindex random number generation
8397 @item @emph{Description}:
8398 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
8399 distribution between 0 and a system-dependent limit (which is in most
8400 cases 2147483647). If @var{FLAG} is 0, the next number
8401 in the current sequence is returned; if @var{FLAG} is 1, the generator
8402 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
8403 it is used as a new seed with @code{SRAND}.
8405 This intrinsic routine is provided for backwards compatibility with
8406 GNU Fortran 77. It implements a simple modulo generator as provided
8407 by @command{g77}. For new code, one should consider the use of
8408 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
8410 @item @emph{Standard}:
8416 @item @emph{Syntax}:
8417 @code{RESULT = IRAND(I)}
8419 @item @emph{Arguments}:
8420 @multitable @columnfractions .15 .70
8421 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
8424 @item @emph{Return value}:
8425 The return value is of @code{INTEGER(kind=4)} type.
8427 @item @emph{Example}:
8430 integer,parameter :: seed = 86456
8433 print *, irand(), irand(), irand(), irand()
8434 print *, irand(seed), irand(), irand(), irand()
8435 end program test_irand
8443 @section @code{IS_CONTIGUOUS} --- Test whether an array is contiguous
8444 @fnindex IS_IOSTAT_EOR
8445 @cindex array, contiguity
8448 @item @emph{Description}:
8449 @code{IS_CONTIGUOUS} tests whether an array is contiguous.
8451 @item @emph{Standard}:
8452 Fortran 2008 and later
8457 @item @emph{Syntax}:
8458 @code{RESULT = IS_CONTIGUOUS(ARRAY)}
8460 @item @emph{Arguments}:
8461 @multitable @columnfractions .15 .70
8462 @item @var{ARRAY} @tab Shall be an array of any type.
8465 @item @emph{Return value}:
8466 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
8467 @var{ARRAY} is contiguous and false otherwise.
8469 @item @emph{Example}:
8473 a = [1,2,3,4,5,6,7,8,9,10]
8474 call sub (a) ! every element, is contiguous
8475 call sub (a(::2)) ! every other element, is noncontiguous
8479 if (is_contiguous (x)) then
8480 write (*,*) 'X is contiguous'
8482 write (*,*) 'X is not contiguous'
8492 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
8493 @fnindex IS_IOSTAT_END
8494 @cindex @code{IOSTAT}, end of file
8497 @item @emph{Description}:
8498 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
8499 status ``end of file''. The function is equivalent to comparing the variable
8500 with the @code{IOSTAT_END} parameter of the intrinsic module
8501 @code{ISO_FORTRAN_ENV}.
8503 @item @emph{Standard}:
8504 Fortran 2003 and later
8509 @item @emph{Syntax}:
8510 @code{RESULT = IS_IOSTAT_END(I)}
8512 @item @emph{Arguments}:
8513 @multitable @columnfractions .15 .70
8514 @item @var{I} @tab Shall be of the type @code{INTEGER}.
8517 @item @emph{Return value}:
8518 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
8519 @var{I} has the value which indicates an end of file condition for
8520 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
8522 @item @emph{Example}:
8527 OPEN(88, FILE='test.dat')
8528 READ(88, *, IOSTAT=stat) i
8529 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
8537 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
8538 @fnindex IS_IOSTAT_EOR
8539 @cindex @code{IOSTAT}, end of record
8542 @item @emph{Description}:
8543 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
8544 status ``end of record''. The function is equivalent to comparing the
8545 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
8546 @code{ISO_FORTRAN_ENV}.
8548 @item @emph{Standard}:
8549 Fortran 2003 and later
8554 @item @emph{Syntax}:
8555 @code{RESULT = IS_IOSTAT_EOR(I)}
8557 @item @emph{Arguments}:
8558 @multitable @columnfractions .15 .70
8559 @item @var{I} @tab Shall be of the type @code{INTEGER}.
8562 @item @emph{Return value}:
8563 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
8564 @var{I} has the value which indicates an end of file condition for
8565 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
8567 @item @emph{Example}:
8571 INTEGER :: stat, i(50)
8572 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
8573 READ(88, IOSTAT=stat) i
8574 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
8581 @section @code{ISATTY} --- Whether a unit is a terminal device.
8583 @cindex system, terminal
8586 @item @emph{Description}:
8587 Determine whether a unit is connected to a terminal device.
8589 @item @emph{Standard}:
8595 @item @emph{Syntax}:
8596 @code{RESULT = ISATTY(UNIT)}
8598 @item @emph{Arguments}:
8599 @multitable @columnfractions .15 .70
8600 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
8603 @item @emph{Return value}:
8604 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
8605 device, @code{.FALSE.} otherwise.
8607 @item @emph{Example}:
8610 INTEGER(kind=1) :: unit
8612 write(*,*) isatty(unit=unit)
8616 @item @emph{See also}:
8623 @section @code{ISHFT} --- Shift bits
8632 @item @emph{Description}:
8633 @code{ISHFT} returns a value corresponding to @var{I} with all of the
8634 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
8635 zero corresponds to a left shift, a value of zero corresponds to no
8636 shift, and a value less than zero corresponds to a right shift. If the
8637 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
8638 value is undefined. Bits shifted out from the left end or right end are
8639 lost; zeros are shifted in from the opposite end.
8641 @item @emph{Standard}:
8642 Fortran 95 and later, has overloads that are GNU extensions
8647 @item @emph{Syntax}:
8648 @code{RESULT = ISHFT(I, SHIFT)}
8650 @item @emph{Arguments}:
8651 @multitable @columnfractions .15 .70
8652 @item @var{I} @tab The type shall be @code{INTEGER}.
8653 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8656 @item @emph{Return value}:
8657 The return value is of type @code{INTEGER} and of the same kind as
8660 @item @emph{Specific names}:
8661 @multitable @columnfractions .20 .20 .20 .25
8662 @item Name @tab Argument @tab Return type @tab Standard
8663 @item @code{ISHFT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
8664 @item @code{BSHFT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8665 @item @code{IISHFT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8666 @item @code{JISHFT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8667 @item @code{KISHFT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8670 @item @emph{See also}:
8677 @section @code{ISHFTC} --- Shift bits circularly
8683 @cindex bits, shift circular
8686 @item @emph{Description}:
8687 @code{ISHFTC} returns a value corresponding to @var{I} with the
8688 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
8689 is, bits shifted out one end are shifted into the opposite end. A value
8690 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
8691 zero corresponds to no shift, and a value less than zero corresponds to
8692 a right shift. The absolute value of @var{SHIFT} must be less than
8693 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
8694 equivalent to @code{BIT_SIZE(I)}.
8696 @item @emph{Standard}:
8697 Fortran 95 and later, has overloads that are GNU extensions
8702 @item @emph{Syntax}:
8703 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
8705 @item @emph{Arguments}:
8706 @multitable @columnfractions .15 .70
8707 @item @var{I} @tab The type shall be @code{INTEGER}.
8708 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8709 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
8710 the value must be greater than zero and less than or equal to
8714 @item @emph{Return value}:
8715 The return value is of type @code{INTEGER} and of the same kind as
8718 @item @emph{Specific names}:
8719 @multitable @columnfractions .20 .20 .20 .25
8720 @item Name @tab Argument @tab Return type @tab Standard
8721 @item @code{ISHFTC(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
8722 @item @code{BSHFTC(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8723 @item @code{IISHFTC(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8724 @item @code{JISHFTC(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8725 @item @code{KISHFTC(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8728 @item @emph{See also}:
8735 @section @code{ISNAN} --- Test for a NaN
8740 @item @emph{Description}:
8741 @code{ISNAN} tests whether a floating-point value is an IEEE
8743 @item @emph{Standard}:
8749 @item @emph{Syntax}:
8752 @item @emph{Arguments}:
8753 @multitable @columnfractions .15 .70
8754 @item @var{X} @tab Variable of the type @code{REAL}.
8758 @item @emph{Return value}:
8759 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
8760 if @var{X} is a NaN and @code{FALSE} otherwise.
8762 @item @emph{Example}:
8769 if (isnan(x)) stop '"x" is a NaN'
8770 end program test_nan
8777 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
8779 @cindex time, current
8780 @cindex current time
8783 @item @emph{Description}:
8784 @code{ITIME(VALUES)} Fills @var{VALUES} with the numerical values at the
8785 current local time. The hour (in the range 1-24), minute (in the range 1-60),
8786 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
8789 This intrinsic routine is provided for backwards compatibility with
8790 GNU Fortran 77. In new code, programmers should consider the use of
8791 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
8794 @item @emph{Standard}:
8800 @item @emph{Syntax}:
8801 @code{CALL ITIME(VALUES)}
8803 @item @emph{Arguments}:
8804 @multitable @columnfractions .15 .70
8805 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
8806 and the kind shall be the default integer kind.
8809 @item @emph{Return value}:
8810 Does not return anything.
8813 @item @emph{Example}:
8816 integer, dimension(3) :: tarray
8821 end program test_itime
8824 @item @emph{See also}:
8831 @section @code{KILL} --- Send a signal to a process
8835 @item @emph{Description}:
8836 @item @emph{Standard}:
8837 Sends the signal specified by @var{SIG} to the process @var{PID}.
8840 This intrinsic is provided in both subroutine and function forms;
8841 however, only one form can be used in any given program unit.
8844 Subroutine, function
8846 @item @emph{Syntax}:
8847 @multitable @columnfractions .80
8848 @item @code{CALL KILL(PID, SIG [, STATUS])}
8849 @item @code{STATUS = KILL(PID, SIG)}
8852 @item @emph{Arguments}:
8853 @multitable @columnfractions .15 .70
8854 @item @var{PID} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}.
8855 @item @var{SIG} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}.
8856 @item @var{STATUS} @tab [Subroutine](Optional)
8857 Shall be a scalar @code{INTEGER}.
8858 Returns 0 on success; otherwise a system-specific error code is returned.
8859 @item @var{STATUS} @tab [Function] The kind type parameter is that of
8861 Returns 0 on success; otherwise a system-specific error code is returned.
8864 @item @emph{See also}:
8865 @ref{ABORT}, @ref{EXIT}
8870 @section @code{KIND} --- Kind of an entity
8875 @item @emph{Description}:
8876 @code{KIND(X)} returns the kind value of the entity @var{X}.
8878 @item @emph{Standard}:
8879 Fortran 95 and later
8884 @item @emph{Syntax}:
8887 @item @emph{Arguments}:
8888 @multitable @columnfractions .15 .70
8889 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
8890 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
8893 @item @emph{Return value}:
8894 The return value is a scalar of type @code{INTEGER} and of the default
8897 @item @emph{Example}:
8900 integer,parameter :: kc = kind(' ')
8901 integer,parameter :: kl = kind(.true.)
8903 print *, "The default character kind is ", kc
8904 print *, "The default logical kind is ", kl
8905 end program test_kind
8913 @section @code{LBOUND} --- Lower dimension bounds of an array
8915 @cindex array, lower bound
8918 @item @emph{Description}:
8919 Returns the lower bounds of an array, or a single lower bound
8920 along the @var{DIM} dimension.
8921 @item @emph{Standard}:
8922 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
8927 @item @emph{Syntax}:
8928 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
8930 @item @emph{Arguments}:
8931 @multitable @columnfractions .15 .70
8932 @item @var{ARRAY} @tab Shall be an array, of any type.
8933 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
8934 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8935 expression indicating the kind parameter of the result.
8938 @item @emph{Return value}:
8939 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8940 @var{KIND} is absent, the return value is of default integer kind.
8941 If @var{DIM} is absent, the result is an array of the lower bounds of
8942 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
8943 corresponding to the lower bound of the array along that dimension. If
8944 @var{ARRAY} is an expression rather than a whole array or array
8945 structure component, or if it has a zero extent along the relevant
8946 dimension, the lower bound is taken to be 1.
8948 @item @emph{See also}:
8949 @ref{UBOUND}, @ref{LCOBOUND}
8955 @section @code{LCOBOUND} --- Lower codimension bounds of an array
8957 @cindex coarray, lower bound
8960 @item @emph{Description}:
8961 Returns the lower bounds of a coarray, or a single lower cobound
8962 along the @var{DIM} codimension.
8963 @item @emph{Standard}:
8964 Fortran 2008 and later
8969 @item @emph{Syntax}:
8970 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
8972 @item @emph{Arguments}:
8973 @multitable @columnfractions .15 .70
8974 @item @var{ARRAY} @tab Shall be an coarray, of any type.
8975 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
8976 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8977 expression indicating the kind parameter of the result.
8980 @item @emph{Return value}:
8981 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8982 @var{KIND} is absent, the return value is of default integer kind.
8983 If @var{DIM} is absent, the result is an array of the lower cobounds of
8984 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
8985 corresponding to the lower cobound of the array along that codimension.
8987 @item @emph{See also}:
8988 @ref{UCOBOUND}, @ref{LBOUND}
8994 @section @code{LEADZ} --- Number of leading zero bits of an integer
8999 @item @emph{Description}:
9000 @code{LEADZ} returns the number of leading zero bits of an integer.
9002 @item @emph{Standard}:
9003 Fortran 2008 and later
9008 @item @emph{Syntax}:
9009 @code{RESULT = LEADZ(I)}
9011 @item @emph{Arguments}:
9012 @multitable @columnfractions .15 .70
9013 @item @var{I} @tab Shall be of type @code{INTEGER}.
9016 @item @emph{Return value}:
9017 The type of the return value is the default @code{INTEGER}.
9018 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
9020 @item @emph{Example}:
9023 WRITE (*,*) BIT_SIZE(1) ! prints 32
9024 WRITE (*,*) LEADZ(1) ! prints 31
9028 @item @emph{See also}:
9029 @ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR}
9035 @section @code{LEN} --- Length of a character entity
9037 @cindex string, length
9040 @item @emph{Description}:
9041 Returns the length of a character string. If @var{STRING} is an array,
9042 the length of an element of @var{STRING} is returned. Note that
9043 @var{STRING} need not be defined when this intrinsic is invoked, since
9044 only the length, not the content, of @var{STRING} is needed.
9046 @item @emph{Standard}:
9047 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
9052 @item @emph{Syntax}:
9053 @code{L = LEN(STRING [, KIND])}
9055 @item @emph{Arguments}:
9056 @multitable @columnfractions .15 .70
9057 @item @var{STRING} @tab Shall be a scalar or array of type
9058 @code{CHARACTER}, with @code{INTENT(IN)}
9059 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9060 expression indicating the kind parameter of the result.
9063 @item @emph{Return value}:
9064 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9065 @var{KIND} is absent, the return value is of default integer kind.
9068 @item @emph{Specific names}:
9069 @multitable @columnfractions .20 .20 .20 .25
9070 @item Name @tab Argument @tab Return type @tab Standard
9071 @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
9075 @item @emph{See also}:
9076 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
9082 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
9084 @cindex string, length, without trailing whitespace
9087 @item @emph{Description}:
9088 Returns the length of a character string, ignoring any trailing blanks.
9090 @item @emph{Standard}:
9091 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
9096 @item @emph{Syntax}:
9097 @code{RESULT = LEN_TRIM(STRING [, KIND])}
9099 @item @emph{Arguments}:
9100 @multitable @columnfractions .15 .70
9101 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
9102 with @code{INTENT(IN)}
9103 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9104 expression indicating the kind parameter of the result.
9107 @item @emph{Return value}:
9108 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9109 @var{KIND} is absent, the return value is of default integer kind.
9111 @item @emph{See also}:
9112 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
9118 @section @code{LGE} --- Lexical greater than or equal
9120 @cindex lexical comparison of strings
9121 @cindex string, comparison
9124 @item @emph{Description}:
9125 Determines whether one string is lexically greater than or equal to
9126 another string, where the two strings are interpreted as containing
9127 ASCII character codes. If the String A and String B are not the same
9128 length, the shorter is compared as if spaces were appended to it to form
9129 a value that has the same length as the longer.
9131 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9132 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9133 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9134 that the latter use the processor's character ordering (which is not
9135 ASCII on some targets), whereas the former always use the ASCII
9138 @item @emph{Standard}:
9139 Fortran 77 and later
9144 @item @emph{Syntax}:
9145 @code{RESULT = LGE(STRING_A, STRING_B)}
9147 @item @emph{Arguments}:
9148 @multitable @columnfractions .15 .70
9149 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9150 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9153 @item @emph{Return value}:
9154 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
9155 otherwise, based on the ASCII ordering.
9157 @item @emph{Specific names}:
9158 @multitable @columnfractions .20 .20 .20 .25
9159 @item Name @tab Argument @tab Return type @tab Standard
9160 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9163 @item @emph{See also}:
9164 @ref{LGT}, @ref{LLE}, @ref{LLT}
9170 @section @code{LGT} --- Lexical greater than
9172 @cindex lexical comparison of strings
9173 @cindex string, comparison
9176 @item @emph{Description}:
9177 Determines whether one string is lexically greater than another string,
9178 where the two strings are interpreted as containing ASCII character
9179 codes. If the String A and String B are not the same length, the
9180 shorter is compared as if spaces were appended to it to form a value
9181 that has the same length as the longer.
9183 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9184 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9185 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9186 that the latter use the processor's character ordering (which is not
9187 ASCII on some targets), whereas the former always use the ASCII
9190 @item @emph{Standard}:
9191 Fortran 77 and later
9196 @item @emph{Syntax}:
9197 @code{RESULT = LGT(STRING_A, STRING_B)}
9199 @item @emph{Arguments}:
9200 @multitable @columnfractions .15 .70
9201 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9202 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9205 @item @emph{Return value}:
9206 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
9207 otherwise, based on the ASCII ordering.
9209 @item @emph{Specific names}:
9210 @multitable @columnfractions .20 .20 .20 .25
9211 @item Name @tab Argument @tab Return type @tab Standard
9212 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9215 @item @emph{See also}:
9216 @ref{LGE}, @ref{LLE}, @ref{LLT}
9222 @section @code{LINK} --- Create a hard link
9224 @cindex file system, create link
9225 @cindex file system, hard link
9228 @item @emph{Description}:
9229 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
9230 character (@code{CHAR(0)}) can be used to mark the end of the names in
9231 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
9232 names are ignored. If the @var{STATUS} argument is supplied, it
9233 contains 0 on success or a nonzero error code upon return; see
9236 This intrinsic is provided in both subroutine and function forms;
9237 however, only one form can be used in any given program unit.
9239 @item @emph{Standard}:
9243 Subroutine, function
9245 @item @emph{Syntax}:
9246 @multitable @columnfractions .80
9247 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
9248 @item @code{STATUS = LINK(PATH1, PATH2)}
9251 @item @emph{Arguments}:
9252 @multitable @columnfractions .15 .70
9253 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
9254 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
9255 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9258 @item @emph{See also}:
9259 @ref{SYMLNK}, @ref{UNLINK}
9265 @section @code{LLE} --- Lexical less than or equal
9267 @cindex lexical comparison of strings
9268 @cindex string, comparison
9271 @item @emph{Description}:
9272 Determines whether one string is lexically less than or equal to another
9273 string, where the two strings are interpreted as containing ASCII
9274 character codes. If the String A and String B are not the same length,
9275 the shorter is compared as if spaces were appended to it to form a value
9276 that has the same length as the longer.
9278 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9279 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9280 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9281 that the latter use the processor's character ordering (which is not
9282 ASCII on some targets), whereas the former always use the ASCII
9285 @item @emph{Standard}:
9286 Fortran 77 and later
9291 @item @emph{Syntax}:
9292 @code{RESULT = LLE(STRING_A, STRING_B)}
9294 @item @emph{Arguments}:
9295 @multitable @columnfractions .15 .70
9296 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9297 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9300 @item @emph{Return value}:
9301 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
9302 otherwise, based on the ASCII ordering.
9304 @item @emph{Specific names}:
9305 @multitable @columnfractions .20 .20 .20 .25
9306 @item Name @tab Argument @tab Return type @tab Standard
9307 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9310 @item @emph{See also}:
9311 @ref{LGE}, @ref{LGT}, @ref{LLT}
9317 @section @code{LLT} --- Lexical less than
9319 @cindex lexical comparison of strings
9320 @cindex string, comparison
9323 @item @emph{Description}:
9324 Determines whether one string is lexically less than another string,
9325 where the two strings are interpreted as containing ASCII character
9326 codes. If the String A and String B are not the same length, the
9327 shorter is compared as if spaces were appended to it to form a value
9328 that has the same length as the longer.
9330 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9331 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9332 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9333 that the latter use the processor's character ordering (which is not
9334 ASCII on some targets), whereas the former always use the ASCII
9337 @item @emph{Standard}:
9338 Fortran 77 and later
9343 @item @emph{Syntax}:
9344 @code{RESULT = LLT(STRING_A, STRING_B)}
9346 @item @emph{Arguments}:
9347 @multitable @columnfractions .15 .70
9348 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9349 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9352 @item @emph{Return value}:
9353 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
9354 otherwise, based on the ASCII ordering.
9356 @item @emph{Specific names}:
9357 @multitable @columnfractions .20 .20 .20 .25
9358 @item Name @tab Argument @tab Return type @tab Standard
9359 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9362 @item @emph{See also}:
9363 @ref{LGE}, @ref{LGT}, @ref{LLE}
9369 @section @code{LNBLNK} --- Index of the last non-blank character in a string
9371 @cindex string, find non-blank character
9374 @item @emph{Description}:
9375 Returns the length of a character string, ignoring any trailing blanks.
9376 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
9377 included for backwards compatibility.
9379 @item @emph{Standard}:
9385 @item @emph{Syntax}:
9386 @code{RESULT = LNBLNK(STRING)}
9388 @item @emph{Arguments}:
9389 @multitable @columnfractions .15 .70
9390 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
9391 with @code{INTENT(IN)}
9394 @item @emph{Return value}:
9395 The return value is of @code{INTEGER(kind=4)} type.
9397 @item @emph{See also}:
9398 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
9404 @section @code{LOC} --- Returns the address of a variable
9406 @cindex location of a variable in memory
9409 @item @emph{Description}:
9410 @code{LOC(X)} returns the address of @var{X} as an integer.
9412 @item @emph{Standard}:
9418 @item @emph{Syntax}:
9419 @code{RESULT = LOC(X)}
9421 @item @emph{Arguments}:
9422 @multitable @columnfractions .15 .70
9423 @item @var{X} @tab Variable of any type.
9426 @item @emph{Return value}:
9427 The return value is of type @code{INTEGER}, with a @code{KIND}
9428 corresponding to the size (in bytes) of a memory address on the target
9431 @item @emph{Example}:
9438 end program test_loc
9445 @section @code{LOG} --- Natural logarithm function
9452 @cindex exponential function, inverse
9453 @cindex logarithm function
9454 @cindex natural logarithm function
9457 @item @emph{Description}:
9458 @code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the
9459 logarithm to the base @math{e}.
9461 @item @emph{Standard}:
9462 Fortran 77 and later
9467 @item @emph{Syntax}:
9468 @code{RESULT = LOG(X)}
9470 @item @emph{Arguments}:
9471 @multitable @columnfractions .15 .70
9472 @item @var{X} @tab The type shall be @code{REAL} or
9476 @item @emph{Return value}:
9477 The return value is of type @code{REAL} or @code{COMPLEX}.
9478 The kind type parameter is the same as @var{X}.
9479 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
9480 @math{-\pi < \omega \leq \pi}.
9482 @item @emph{Example}:
9485 real(8) :: x = 2.7182818284590451_8
9486 complex :: z = (1.0, 2.0)
9487 x = log(x) ! will yield (approximately) 1
9489 end program test_log
9492 @item @emph{Specific names}:
9493 @multitable @columnfractions .20 .20 .20 .25
9494 @item Name @tab Argument @tab Return type @tab Standard
9495 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
9496 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
9497 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
9498 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9499 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9506 @section @code{LOG10} --- Base 10 logarithm function
9510 @cindex exponential function, inverse
9511 @cindex logarithm function with base 10
9512 @cindex base 10 logarithm function
9515 @item @emph{Description}:
9516 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
9518 @item @emph{Standard}:
9519 Fortran 77 and later
9524 @item @emph{Syntax}:
9525 @code{RESULT = LOG10(X)}
9527 @item @emph{Arguments}:
9528 @multitable @columnfractions .15 .70
9529 @item @var{X} @tab The type shall be @code{REAL}.
9532 @item @emph{Return value}:
9533 The return value is of type @code{REAL} or @code{COMPLEX}.
9534 The kind type parameter is the same as @var{X}.
9536 @item @emph{Example}:
9539 real(8) :: x = 10.0_8
9541 end program test_log10
9544 @item @emph{Specific names}:
9545 @multitable @columnfractions .20 .20 .20 .25
9546 @item Name @tab Argument @tab Return type @tab Standard
9547 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
9548 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
9555 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
9560 @cindex Gamma function, logarithm of
9563 @item @emph{Description}:
9564 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
9565 of the Gamma (@math{\Gamma}) function.
9567 @item @emph{Standard}:
9568 Fortran 2008 and later
9573 @item @emph{Syntax}:
9574 @code{X = LOG_GAMMA(X)}
9576 @item @emph{Arguments}:
9577 @multitable @columnfractions .15 .70
9578 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
9579 nor a negative integer.
9582 @item @emph{Return value}:
9583 The return value is of type @code{REAL} of the same kind as @var{X}.
9585 @item @emph{Example}:
9587 program test_log_gamma
9589 x = lgamma(x) ! returns 0.0
9590 end program test_log_gamma
9593 @item @emph{Specific names}:
9594 @multitable @columnfractions .20 .20 .20 .25
9595 @item Name @tab Argument @tab Return type @tab Standard
9596 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
9597 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
9598 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
9601 @item @emph{See also}:
9602 Gamma function: @ref{GAMMA}
9609 @section @code{LOGICAL} --- Convert to logical type
9611 @cindex conversion, to logical
9614 @item @emph{Description}:
9615 Converts one kind of @code{LOGICAL} variable to another.
9617 @item @emph{Standard}:
9618 Fortran 95 and later
9623 @item @emph{Syntax}:
9624 @code{RESULT = LOGICAL(L [, KIND])}
9626 @item @emph{Arguments}:
9627 @multitable @columnfractions .15 .70
9628 @item @var{L} @tab The type shall be @code{LOGICAL}.
9629 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9630 expression indicating the kind parameter of the result.
9633 @item @emph{Return value}:
9634 The return value is a @code{LOGICAL} value equal to @var{L}, with a
9635 kind corresponding to @var{KIND}, or of the default logical kind if
9636 @var{KIND} is not given.
9638 @item @emph{See also}:
9639 @ref{INT}, @ref{REAL}, @ref{CMPLX}
9645 @section @code{LONG} --- Convert to integer type
9647 @cindex conversion, to integer
9650 @item @emph{Description}:
9651 Convert to a @code{KIND=4} integer type, which is the same size as a C
9652 @code{long} integer. This is equivalent to the standard @code{INT}
9653 intrinsic with an optional argument of @code{KIND=4}, and is only
9654 included for backwards compatibility.
9656 @item @emph{Standard}:
9662 @item @emph{Syntax}:
9663 @code{RESULT = LONG(A)}
9665 @item @emph{Arguments}:
9666 @multitable @columnfractions .15 .70
9667 @item @var{A} @tab Shall be of type @code{INTEGER},
9668 @code{REAL}, or @code{COMPLEX}.
9671 @item @emph{Return value}:
9672 The return value is a @code{INTEGER(4)} variable.
9674 @item @emph{See also}:
9675 @ref{INT}, @ref{INT2}, @ref{INT8}
9681 @section @code{LSHIFT} --- Left shift bits
9683 @cindex bits, shift left
9686 @item @emph{Description}:
9687 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
9688 bits shifted left by @var{SHIFT} places. If the absolute value of
9689 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
9690 Bits shifted out from the left end are lost; zeros are shifted in from
9693 This function has been superseded by the @code{ISHFT} intrinsic, which
9694 is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
9695 which is standard in Fortran 2008 and later.
9697 @item @emph{Standard}:
9703 @item @emph{Syntax}:
9704 @code{RESULT = LSHIFT(I, SHIFT)}
9706 @item @emph{Arguments}:
9707 @multitable @columnfractions .15 .70
9708 @item @var{I} @tab The type shall be @code{INTEGER}.
9709 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
9712 @item @emph{Return value}:
9713 The return value is of type @code{INTEGER} and of the same kind as
9716 @item @emph{See also}:
9717 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}, @ref{SHIFTA}, @ref{SHIFTL},
9725 @section @code{LSTAT} --- Get file status
9727 @cindex file system, file status
9730 @item @emph{Description}:
9731 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
9732 symbolic link, then the link itself is statted, not the file that it
9735 The elements in @code{VALUES} are the same as described by @ref{STAT}.
9737 This intrinsic is provided in both subroutine and function forms;
9738 however, only one form can be used in any given program unit.
9740 @item @emph{Standard}:
9744 Subroutine, function
9746 @item @emph{Syntax}:
9747 @multitable @columnfractions .80
9748 @item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
9749 @item @code{STATUS = LSTAT(NAME, VALUES)}
9752 @item @emph{Arguments}:
9753 @multitable @columnfractions .15 .70
9754 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
9755 kind, a valid path within the file system.
9756 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
9757 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
9758 Returns 0 on success and a system specific error code otherwise.
9761 @item @emph{Example}:
9762 See @ref{STAT} for an example.
9764 @item @emph{See also}:
9765 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
9771 @section @code{LTIME} --- Convert time to local time info
9773 @cindex time, conversion to local time info
9776 @item @emph{Description}:
9777 Given a system time value @var{TIME} (as provided by the @ref{TIME}
9778 intrinsic), fills @var{VALUES} with values extracted from it appropriate
9779 to the local time zone using @code{localtime(3)}.
9781 This intrinsic routine is provided for backwards compatibility with
9782 GNU Fortran 77. In new code, programmers should consider the use of
9783 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
9786 @item @emph{Standard}:
9792 @item @emph{Syntax}:
9793 @code{CALL LTIME(TIME, VALUES)}
9795 @item @emph{Arguments}:
9796 @multitable @columnfractions .15 .70
9797 @item @var{TIME} @tab An @code{INTEGER} scalar expression
9798 corresponding to a system time, with @code{INTENT(IN)}.
9799 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
9800 with @code{INTENT(OUT)}.
9803 @item @emph{Return value}:
9804 The elements of @var{VALUES} are assigned as follows:
9806 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
9808 @item Minutes after the hour, range 0--59
9809 @item Hours past midnight, range 0--23
9810 @item Day of month, range 1--31
9811 @item Number of months since January, range 0--11
9812 @item Years since 1900
9813 @item Number of days since Sunday, range 0--6
9814 @item Days since January 1, range 0--365
9815 @item Daylight savings indicator: positive if daylight savings is in
9816 effect, zero if not, and negative if the information is not available.
9819 @item @emph{See also}:
9820 @ref{DATE_AND_TIME}, @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
9827 @section @code{MALLOC} --- Allocate dynamic memory
9829 @cindex pointer, cray
9832 @item @emph{Description}:
9833 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
9834 returns the address of the allocated memory. The @code{MALLOC} intrinsic
9835 is an extension intended to be used with Cray pointers, and is provided
9836 in GNU Fortran to allow the user to compile legacy code. For new code
9837 using Fortran 95 pointers, the memory allocation intrinsic is
9840 @item @emph{Standard}:
9846 @item @emph{Syntax}:
9847 @code{PTR = MALLOC(SIZE)}
9849 @item @emph{Arguments}:
9850 @multitable @columnfractions .15 .70
9851 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
9854 @item @emph{Return value}:
9855 The return value is of type @code{INTEGER(K)}, with @var{K} such that
9856 variables of type @code{INTEGER(K)} have the same size as
9857 C pointers (@code{sizeof(void *)}).
9859 @item @emph{Example}:
9860 The following example demonstrates the use of @code{MALLOC} and
9861 @code{FREE} with Cray pointers.
9870 ptr_x = malloc(20*8)
9872 x(i) = sqrt(1.0d0 / i)
9880 end program test_malloc
9883 @item @emph{See also}:
9890 @section @code{MASKL} --- Left justified mask
9892 @cindex mask, left justified
9895 @item @emph{Description}:
9896 @code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
9897 remaining bits set to 0.
9899 @item @emph{Standard}:
9900 Fortran 2008 and later
9905 @item @emph{Syntax}:
9906 @code{RESULT = MASKL(I[, KIND])}
9908 @item @emph{Arguments}:
9909 @multitable @columnfractions .15 .70
9910 @item @var{I} @tab Shall be of type @code{INTEGER}.
9911 @item @var{KIND} @tab Shall be a scalar constant expression of type
9915 @item @emph{Return value}:
9916 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
9917 specifies the kind value of the return type; otherwise, it is of the
9918 default integer kind.
9920 @item @emph{See also}:
9927 @section @code{MASKR} --- Right justified mask
9929 @cindex mask, right justified
9932 @item @emph{Description}:
9933 @code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
9934 remaining bits set to 0.
9936 @item @emph{Standard}:
9937 Fortran 2008 and later
9942 @item @emph{Syntax}:
9943 @code{RESULT = MASKR(I[, KIND])}
9945 @item @emph{Arguments}:
9946 @multitable @columnfractions .15 .70
9947 @item @var{I} @tab Shall be of type @code{INTEGER}.
9948 @item @var{KIND} @tab Shall be a scalar constant expression of type
9952 @item @emph{Return value}:
9953 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
9954 specifies the kind value of the return type; otherwise, it is of the
9955 default integer kind.
9957 @item @emph{See also}:
9964 @section @code{MATMUL} --- matrix multiplication
9966 @cindex matrix multiplication
9967 @cindex product, matrix
9970 @item @emph{Description}:
9971 Performs a matrix multiplication on numeric or logical arguments.
9973 @item @emph{Standard}:
9974 Fortran 95 and later
9977 Transformational function
9979 @item @emph{Syntax}:
9980 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
9982 @item @emph{Arguments}:
9983 @multitable @columnfractions .15 .70
9984 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
9985 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
9987 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
9988 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
9989 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
9990 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
9991 equal to the last (or only) dimension of @var{MATRIX_A}.
9992 @var{MATRIX_A} and @var{MATRIX_B} shall not both be rank one arrays.
9995 @item @emph{Return value}:
9996 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
9997 kind of the result follow the usual type and kind promotion rules, as
9998 for the @code{*} or @code{.AND.} operators.
10000 @item @emph{See also}:
10006 @section @code{MAX} --- Maximum value of an argument list
10013 @cindex maximum value
10016 @item @emph{Description}:
10017 Returns the argument with the largest (most positive) value.
10019 @item @emph{Standard}:
10020 Fortran 77 and later
10022 @item @emph{Class}:
10025 @item @emph{Syntax}:
10026 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
10028 @item @emph{Arguments}:
10029 @multitable @columnfractions .15 .70
10030 @item @var{A1} @tab The type shall be @code{INTEGER} or
10032 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
10033 as @var{A1}. (As a GNU extension, arguments of different kinds are
10037 @item @emph{Return value}:
10038 The return value corresponds to the maximum value among the arguments,
10039 and has the same type and kind as the first argument.
10041 @item @emph{Specific names}:
10042 @multitable @columnfractions .20 .20 .20 .25
10043 @item Name @tab Argument @tab Return type @tab Standard
10044 @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
10045 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
10046 @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
10047 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
10048 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
10051 @item @emph{See also}:
10052 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
10059 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
10060 @fnindex MAXEXPONENT
10061 @cindex model representation, maximum exponent
10064 @item @emph{Description}:
10065 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
10068 @item @emph{Standard}:
10069 Fortran 95 and later
10071 @item @emph{Class}:
10074 @item @emph{Syntax}:
10075 @code{RESULT = MAXEXPONENT(X)}
10077 @item @emph{Arguments}:
10078 @multitable @columnfractions .15 .70
10079 @item @var{X} @tab Shall be of type @code{REAL}.
10082 @item @emph{Return value}:
10083 The return value is of type @code{INTEGER} and of the default integer
10086 @item @emph{Example}:
10092 print *, minexponent(x), maxexponent(x)
10093 print *, minexponent(y), maxexponent(y)
10094 end program exponents
10101 @section @code{MAXLOC} --- Location of the maximum value within an array
10103 @cindex array, location of maximum element
10106 @item @emph{Description}:
10107 Determines the location of the element in the array with the maximum
10108 value, or, if the @var{DIM} argument is supplied, determines the
10109 locations of the maximum element along each row of the array in the
10110 @var{DIM} direction. If @var{MASK} is present, only the elements for
10111 which @var{MASK} is @code{.TRUE.} are considered. If more than one
10112 element in the array has the maximum value, the location returned is
10113 that of the first such element in array element order if the
10114 @var{BACK} is not present, or if it false; otherwise, the location
10115 returned is that of the first such element. If the array has zero
10116 size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
10117 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
10118 and all of the elements of @var{MASK} along a given row are zero, the
10119 result value for that row is zero.
10121 @item @emph{Standard}:
10122 Fortran 95 and later; @var{ARRAY} of @code{CHARACTER} and the
10123 @var{KIND} argument are available in Fortran 2003 and later.
10124 The @var{BACK} argument is available in Fortran 2008 and later.
10126 @item @emph{Class}:
10127 Transformational function
10129 @item @emph{Syntax}:
10130 @multitable @columnfractions .80
10131 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK])}
10132 @item @code{RESULT = MAXLOC(ARRAY [, MASK] [,KIND] [,BACK])}
10135 @item @emph{Arguments}:
10136 @multitable @columnfractions .15 .70
10137 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10139 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10140 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10141 inclusive. It may not be an optional dummy argument.
10142 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
10143 and conformable with @var{ARRAY}.
10144 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10145 expression indicating the kind parameter of the result.
10146 @item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}.
10149 @item @emph{Return value}:
10150 If @var{DIM} is absent, the result is a rank-one array with a length
10151 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
10152 is an array with a rank one less than the rank of @var{ARRAY}, and a
10153 size corresponding to the size of @var{ARRAY} with the @var{DIM}
10154 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
10155 of one, the result is a scalar. If the optional argument @var{KIND}
10156 is present, the result is an integer of kind @var{KIND}, otherwise it
10157 is of default kind.
10159 @item @emph{See also}:
10160 @ref{FINDLOC}, @ref{MAX}, @ref{MAXVAL}
10167 @section @code{MAXVAL} --- Maximum value of an array
10169 @cindex array, maximum value
10170 @cindex maximum value
10173 @item @emph{Description}:
10174 Determines the maximum value of the elements in an array value, or, if
10175 the @var{DIM} argument is supplied, determines the maximum value along
10176 each row of the array in the @var{DIM} direction. If @var{MASK} is
10177 present, only the elements for which @var{MASK} is @code{.TRUE.} are
10178 considered. If the array has zero size, or all of the elements of
10179 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
10180 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
10183 @item @emph{Standard}:
10184 Fortran 95 and later
10186 @item @emph{Class}:
10187 Transformational function
10189 @item @emph{Syntax}:
10190 @multitable @columnfractions .80
10191 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
10192 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
10195 @item @emph{Arguments}:
10196 @multitable @columnfractions .15 .70
10197 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10199 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10200 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10201 inclusive. It may not be an optional dummy argument.
10202 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
10203 and conformable with @var{ARRAY}.
10206 @item @emph{Return value}:
10207 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
10208 is a scalar. If @var{DIM} is present, the result is an array with a
10209 rank one less than the rank of @var{ARRAY}, and a size corresponding to
10210 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
10211 cases, the result is of the same type and kind as @var{ARRAY}.
10213 @item @emph{See also}:
10214 @ref{MAX}, @ref{MAXLOC}
10220 @section @code{MCLOCK} --- Time function
10222 @cindex time, clock ticks
10223 @cindex clock ticks
10226 @item @emph{Description}:
10227 Returns the number of clock ticks since the start of the process, based
10228 on the function @code{clock(3)} in the C standard library.
10230 This intrinsic is not fully portable, such as to systems with 32-bit
10231 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
10232 the values returned by this intrinsic might be, or become, negative, or
10233 numerically less than previous values, during a single run of the
10236 @item @emph{Standard}:
10239 @item @emph{Class}:
10242 @item @emph{Syntax}:
10243 @code{RESULT = MCLOCK()}
10245 @item @emph{Return value}:
10246 The return value is a scalar of type @code{INTEGER(4)}, equal to the
10247 number of clock ticks since the start of the process, or @code{-1} if
10248 the system does not support @code{clock(3)}.
10250 @item @emph{See also}:
10251 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
10258 @section @code{MCLOCK8} --- Time function (64-bit)
10260 @cindex time, clock ticks
10261 @cindex clock ticks
10264 @item @emph{Description}:
10265 Returns the number of clock ticks since the start of the process, based
10266 on the function @code{clock(3)} in the C standard library.
10268 @emph{Warning:} this intrinsic does not increase the range of the timing
10269 values over that returned by @code{clock(3)}. On a system with a 32-bit
10270 @code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though
10271 it is converted to a 64-bit @code{INTEGER(8)} value. That means
10272 overflows of the 32-bit value can still occur. Therefore, the values
10273 returned by this intrinsic might be or become negative or numerically
10274 less than previous values during a single run of the compiled program.
10276 @item @emph{Standard}:
10279 @item @emph{Class}:
10282 @item @emph{Syntax}:
10283 @code{RESULT = MCLOCK8()}
10285 @item @emph{Return value}:
10286 The return value is a scalar of type @code{INTEGER(8)}, equal to the
10287 number of clock ticks since the start of the process, or @code{-1} if
10288 the system does not support @code{clock(3)}.
10290 @item @emph{See also}:
10291 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
10298 @section @code{MERGE} --- Merge variables
10300 @cindex array, merge arrays
10301 @cindex array, combine arrays
10304 @item @emph{Description}:
10305 Select values from two arrays according to a logical mask. The result
10306 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
10307 @var{FSOURCE} if it is @code{.FALSE.}.
10309 @item @emph{Standard}:
10310 Fortran 95 and later
10312 @item @emph{Class}:
10315 @item @emph{Syntax}:
10316 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
10318 @item @emph{Arguments}:
10319 @multitable @columnfractions .15 .70
10320 @item @var{TSOURCE} @tab May be of any type.
10321 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
10323 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
10326 @item @emph{Return value}:
10327 The result is of the same type and type parameters as @var{TSOURCE}.
10334 @section @code{MERGE_BITS} --- Merge of bits under mask
10335 @fnindex MERGE_BITS
10336 @cindex bits, merge
10339 @item @emph{Description}:
10340 @code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
10341 as determined by the mask. The i-th bit of the result is equal to the
10342 i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
10343 the i-th bit of @var{J} otherwise.
10345 @item @emph{Standard}:
10346 Fortran 2008 and later
10348 @item @emph{Class}:
10351 @item @emph{Syntax}:
10352 @code{RESULT = MERGE_BITS(I, J, MASK)}
10354 @item @emph{Arguments}:
10355 @multitable @columnfractions .15 .70
10356 @item @var{I} @tab Shall be of type @code{INTEGER} or a boz-literal-constant.
10357 @item @var{J} @tab Shall be of type @code{INTEGER} with the same
10358 kind type parameter as @var{I} or a boz-literal-constant.
10359 @var{I} and @var{J} shall not both be boz-literal-constants.
10360 @item @var{MASK} @tab Shall be of type @code{INTEGER} or a boz-literal-constant
10361 and of the same kind as @var{I}.
10364 @item @emph{Return value}:
10365 The result is of the same type and kind as @var{I}.
10372 @section @code{MIN} --- Minimum value of an argument list
10379 @cindex minimum value
10382 @item @emph{Description}:
10383 Returns the argument with the smallest (most negative) value.
10385 @item @emph{Standard}:
10386 Fortran 77 and later
10388 @item @emph{Class}:
10391 @item @emph{Syntax}:
10392 @code{RESULT = MIN(A1, A2 [, A3, ...])}
10394 @item @emph{Arguments}:
10395 @multitable @columnfractions .15 .70
10396 @item @var{A1} @tab The type shall be @code{INTEGER} or
10398 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
10399 as @var{A1}. (As a GNU extension, arguments of different kinds are
10403 @item @emph{Return value}:
10404 The return value corresponds to the maximum value among the arguments,
10405 and has the same type and kind as the first argument.
10407 @item @emph{Specific names}:
10408 @multitable @columnfractions .20 .20 .20 .25
10409 @item Name @tab Argument @tab Return type @tab Standard
10410 @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
10411 @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
10412 @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
10413 @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
10414 @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
10417 @item @emph{See also}:
10418 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
10424 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
10425 @fnindex MINEXPONENT
10426 @cindex model representation, minimum exponent
10429 @item @emph{Description}:
10430 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
10433 @item @emph{Standard}:
10434 Fortran 95 and later
10436 @item @emph{Class}:
10439 @item @emph{Syntax}:
10440 @code{RESULT = MINEXPONENT(X)}
10442 @item @emph{Arguments}:
10443 @multitable @columnfractions .15 .70
10444 @item @var{X} @tab Shall be of type @code{REAL}.
10447 @item @emph{Return value}:
10448 The return value is of type @code{INTEGER} and of the default integer
10451 @item @emph{Example}:
10452 See @code{MAXEXPONENT} for an example.
10458 @section @code{MINLOC} --- Location of the minimum value within an array
10460 @cindex array, location of minimum element
10463 @item @emph{Description}:
10464 Determines the location of the element in the array with the minimum
10465 value, or, if the @var{DIM} argument is supplied, determines the
10466 locations of the minimum element along each row of the array in the
10467 @var{DIM} direction. If @var{MASK} is present, only the elements for
10468 which @var{MASK} is @code{.TRUE.} are considered. If more than one
10469 element in the array has the minimum value, the location returned is
10470 that of the first such element in array element order if the
10471 @var{BACK} is not present, or if it false; otherwise, the location
10472 returned is that of the first such element. If the array has
10473 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
10474 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
10475 and all of the elements of @var{MASK} along a given row are zero, the
10476 result value for that row is zero.
10478 @item @emph{Standard}:
10479 Fortran 95 and later; @var{ARRAY} of @code{CHARACTER} and the
10480 @var{KIND} argument are available in Fortran 2003 and later.
10481 The @var{BACK} argument is available in Fortran 2008 and later.
10483 @item @emph{Class}:
10484 Transformational function
10486 @item @emph{Syntax}:
10487 @multitable @columnfractions .80
10488 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK])}
10489 @item @code{RESULT = MINLOC(ARRAY [, MASK], [,KIND] [,BACK])}
10492 @item @emph{Arguments}:
10493 @multitable @columnfractions .15 .70
10494 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
10495 @code{REAL} or @code{CHARACTER}.
10496 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10497 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10498 inclusive. It may not be an optional dummy argument.
10499 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
10500 and conformable with @var{ARRAY}.
10501 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10502 expression indicating the kind parameter of the result.
10503 @item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}.
10506 @item @emph{Return value}:
10507 If @var{DIM} is absent, the result is a rank-one array with a length
10508 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
10509 is an array with a rank one less than the rank of @var{ARRAY}, and a
10510 size corresponding to the size of @var{ARRAY} with the @var{DIM}
10511 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
10512 of one, the result is a scalar. If the optional argument @var{KIND}
10513 is present, the result is an integer of kind @var{KIND}, otherwise it
10514 is of default kind.
10516 @item @emph{See also}:
10517 @ref{FINDLOC}, @ref{MIN}, @ref{MINVAL}
10524 @section @code{MINVAL} --- Minimum value of an array
10526 @cindex array, minimum value
10527 @cindex minimum value
10530 @item @emph{Description}:
10531 Determines the minimum value of the elements in an array value, or, if
10532 the @var{DIM} argument is supplied, determines the minimum value along
10533 each row of the array in the @var{DIM} direction. If @var{MASK} is
10534 present, only the elements for which @var{MASK} is @code{.TRUE.} are
10535 considered. If the array has zero size, or all of the elements of
10536 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
10537 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
10538 @var{ARRAY} is of character type.
10540 @item @emph{Standard}:
10541 Fortran 95 and later
10543 @item @emph{Class}:
10544 Transformational function
10546 @item @emph{Syntax}:
10547 @multitable @columnfractions .80
10548 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
10549 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
10552 @item @emph{Arguments}:
10553 @multitable @columnfractions .15 .70
10554 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10556 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10557 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10558 inclusive. It may not be an optional dummy argument.
10559 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
10560 and conformable with @var{ARRAY}.
10563 @item @emph{Return value}:
10564 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
10565 is a scalar. If @var{DIM} is present, the result is an array with a
10566 rank one less than the rank of @var{ARRAY}, and a size corresponding to
10567 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
10568 cases, the result is of the same type and kind as @var{ARRAY}.
10570 @item @emph{See also}:
10571 @ref{MIN}, @ref{MINLOC}
10578 @section @code{MOD} --- Remainder function
10587 @cindex division, remainder
10590 @item @emph{Description}:
10591 @code{MOD(A,P)} computes the remainder of the division of A by P@.
10593 @item @emph{Standard}:
10594 Fortran 77 and later, has overloads that are GNU extensions
10596 @item @emph{Class}:
10599 @item @emph{Syntax}:
10600 @code{RESULT = MOD(A, P)}
10602 @item @emph{Arguments}:
10603 @multitable @columnfractions .15 .70
10604 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
10605 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
10606 and not equal to zero.
10609 @item @emph{Return value}:
10610 The return value is the result of @code{A - (INT(A/P) * P)}. The type
10611 and kind of the return value is the same as that of the arguments. The
10612 returned value has the same sign as A and a magnitude less than the
10615 @item @emph{Example}:
10619 print *, mod(17.5,5.5)
10620 print *, mod(17.5d0,5.5)
10621 print *, mod(17.5,5.5d0)
10623 print *, mod(-17,3)
10624 print *, mod(-17.5,5.5)
10625 print *, mod(-17.5d0,5.5)
10626 print *, mod(-17.5,5.5d0)
10628 print *, mod(17,-3)
10629 print *, mod(17.5,-5.5)
10630 print *, mod(17.5d0,-5.5)
10631 print *, mod(17.5,-5.5d0)
10632 end program test_mod
10635 @item @emph{Specific names}:
10636 @multitable @columnfractions .20 .20 .20 .25
10637 @item Name @tab Arguments @tab Return type @tab Standard
10638 @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
10639 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
10640 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
10641 @item @code{BMOD(A,P)} @tab @code{INTEGER(1) A,P} @tab @code{INTEGER(1)} @tab GNU extension
10642 @item @code{IMOD(A,P)} @tab @code{INTEGER(2) A,P} @tab @code{INTEGER(2)} @tab GNU extension
10643 @item @code{JMOD(A,P)} @tab @code{INTEGER(4) A,P} @tab @code{INTEGER(4)} @tab GNU extension
10644 @item @code{KMOD(A,P)} @tab @code{INTEGER(8) A,P} @tab @code{INTEGER(8)} @tab GNU extension
10647 @item @emph{See also}:
10655 @section @code{MODULO} --- Modulo function
10658 @cindex division, modulo
10661 @item @emph{Description}:
10662 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
10664 @item @emph{Standard}:
10665 Fortran 95 and later
10667 @item @emph{Class}:
10670 @item @emph{Syntax}:
10671 @code{RESULT = MODULO(A, P)}
10673 @item @emph{Arguments}:
10674 @multitable @columnfractions .15 .70
10675 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
10676 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}.
10677 It shall not be zero.
10680 @item @emph{Return value}:
10681 The type and kind of the result are those of the arguments.
10683 @item If @var{A} and @var{P} are of type @code{INTEGER}:
10684 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
10685 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
10687 @item If @var{A} and @var{P} are of type @code{REAL}:
10688 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
10690 The returned value has the same sign as P and a magnitude less than
10691 the magnitude of P.
10693 @item @emph{Example}:
10695 program test_modulo
10696 print *, modulo(17,3)
10697 print *, modulo(17.5,5.5)
10699 print *, modulo(-17,3)
10700 print *, modulo(-17.5,5.5)
10702 print *, modulo(17,-3)
10703 print *, modulo(17.5,-5.5)
10707 @item @emph{See also}:
10715 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
10716 @fnindex MOVE_ALLOC
10717 @cindex moving allocation
10718 @cindex allocation, moving
10721 @item @emph{Description}:
10722 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
10723 @var{TO}. @var{FROM} will become deallocated in the process.
10725 @item @emph{Standard}:
10726 Fortran 2003 and later
10728 @item @emph{Class}:
10731 @item @emph{Syntax}:
10732 @code{CALL MOVE_ALLOC(FROM, TO)}
10734 @item @emph{Arguments}:
10735 @multitable @columnfractions .15 .70
10736 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
10737 of any type and kind.
10738 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
10739 of the same type, kind and rank as @var{FROM}.
10742 @item @emph{Return value}:
10745 @item @emph{Example}:
10747 program test_move_alloc
10748 integer, allocatable :: a(:), b(:)
10752 call move_alloc(a, b)
10753 print *, allocated(a), allocated(b)
10755 end program test_move_alloc
10762 @section @code{MVBITS} --- Move bits from one integer to another
10771 @item @emph{Description}:
10772 Moves @var{LEN} bits from positions @var{FROMPOS} through
10773 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
10774 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
10775 affected by the movement of bits is unchanged. The values of
10776 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
10777 @code{BIT_SIZE(FROM)}.
10779 @item @emph{Standard}:
10780 Fortran 95 and later, has overloads that are GNU extensions
10782 @item @emph{Class}:
10783 Elemental subroutine
10785 @item @emph{Syntax}:
10786 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
10788 @item @emph{Arguments}:
10789 @multitable @columnfractions .15 .70
10790 @item @var{FROM} @tab The type shall be @code{INTEGER}.
10791 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
10792 @item @var{LEN} @tab The type shall be @code{INTEGER}.
10793 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
10794 same kind as @var{FROM}.
10795 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
10798 @item @emph{Specific names}:
10799 @multitable @columnfractions .20 .20 .20 .25
10800 @item Name @tab Argument @tab Return type @tab Standard
10801 @item @code{MVBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
10802 @item @code{BMVBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
10803 @item @code{IMVBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
10804 @item @code{JMVBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
10805 @item @code{KMVBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
10808 @item @emph{See also}:
10809 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
10815 @section @code{NEAREST} --- Nearest representable number
10817 @cindex real number, nearest different
10818 @cindex floating point, nearest different
10821 @item @emph{Description}:
10822 @code{NEAREST(X, S)} returns the processor-representable number nearest
10823 to @code{X} in the direction indicated by the sign of @code{S}.
10825 @item @emph{Standard}:
10826 Fortran 95 and later
10828 @item @emph{Class}:
10831 @item @emph{Syntax}:
10832 @code{RESULT = NEAREST(X, S)}
10834 @item @emph{Arguments}:
10835 @multitable @columnfractions .15 .70
10836 @item @var{X} @tab Shall be of type @code{REAL}.
10837 @item @var{S} @tab Shall be of type @code{REAL} and
10841 @item @emph{Return value}:
10842 The return value is of the same type as @code{X}. If @code{S} is
10843 positive, @code{NEAREST} returns the processor-representable number
10844 greater than @code{X} and nearest to it. If @code{S} is negative,
10845 @code{NEAREST} returns the processor-representable number smaller than
10846 @code{X} and nearest to it.
10848 @item @emph{Example}:
10850 program test_nearest
10852 x = nearest(42.0, 1.0)
10853 y = nearest(42.0, -1.0)
10854 write (*,"(3(G20.15))") x, y, x - y
10855 end program test_nearest
10862 @section @code{NEW_LINE} --- New line character
10865 @cindex output, newline
10868 @item @emph{Description}:
10869 @code{NEW_LINE(C)} returns the new-line character.
10871 @item @emph{Standard}:
10872 Fortran 2003 and later
10874 @item @emph{Class}:
10877 @item @emph{Syntax}:
10878 @code{RESULT = NEW_LINE(C)}
10880 @item @emph{Arguments}:
10881 @multitable @columnfractions .15 .70
10882 @item @var{C} @tab The argument shall be a scalar or array of the
10883 type @code{CHARACTER}.
10886 @item @emph{Return value}:
10887 Returns a @var{CHARACTER} scalar of length one with the new-line character of
10888 the same kind as parameter @var{C}.
10890 @item @emph{Example}:
10894 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
10895 end program newline
10902 @section @code{NINT} --- Nearest whole number
10905 @cindex rounding, nearest whole number
10908 @item @emph{Description}:
10909 @code{NINT(A)} rounds its argument to the nearest whole number.
10911 @item @emph{Standard}:
10912 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
10914 @item @emph{Class}:
10917 @item @emph{Syntax}:
10918 @code{RESULT = NINT(A [, KIND])}
10920 @item @emph{Arguments}:
10921 @multitable @columnfractions .15 .70
10922 @item @var{A} @tab The type of the argument shall be @code{REAL}.
10923 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10924 expression indicating the kind parameter of the result.
10927 @item @emph{Return value}:
10928 Returns @var{A} with the fractional portion of its magnitude eliminated by
10929 rounding to the nearest whole number and with its sign preserved,
10930 converted to an @code{INTEGER} of the default kind.
10932 @item @emph{Example}:
10939 print *, nint(x4), idnint(x8)
10940 end program test_nint
10943 @item @emph{Specific names}:
10944 @multitable @columnfractions .20 .20 .20 .25
10945 @item Name @tab Argument @tab Return Type @tab Standard
10946 @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later
10947 @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later
10950 @item @emph{See also}:
10951 @ref{CEILING}, @ref{FLOOR}
10958 @section @code{NORM2} --- Euclidean vector norms
10960 @cindex Euclidean vector norm
10961 @cindex L2 vector norm
10962 @cindex norm, Euclidean
10965 @item @emph{Description}:
10966 Calculates the Euclidean vector norm (@math{L_2} norm) of
10967 of @var{ARRAY} along dimension @var{DIM}.
10969 @item @emph{Standard}:
10970 Fortran 2008 and later
10972 @item @emph{Class}:
10973 Transformational function
10975 @item @emph{Syntax}:
10976 @multitable @columnfractions .80
10977 @item @code{RESULT = NORM2(ARRAY[, DIM])}
10980 @item @emph{Arguments}:
10981 @multitable @columnfractions .15 .70
10982 @item @var{ARRAY} @tab Shall be an array of type @code{REAL}
10983 @item @var{DIM} @tab (Optional) shall be a scalar of type
10984 @code{INTEGER} with a value in the range from 1 to n, where n
10985 equals the rank of @var{ARRAY}.
10988 @item @emph{Return value}:
10989 The result is of the same type as @var{ARRAY}.
10991 If @var{DIM} is absent, a scalar with the square root of the sum of all
10992 elements in @var{ARRAY} squared is returned. Otherwise, an array of
10993 rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
10994 shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
10997 @item @emph{Example}:
11000 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
11001 print *, NORM2(x) ! = sqrt(55.) ~ 7.416
11009 @section @code{NOT} --- Logical negation
11015 @cindex bits, negate
11016 @cindex bitwise logical not
11017 @cindex logical not, bitwise
11020 @item @emph{Description}:
11021 @code{NOT} returns the bitwise Boolean inverse of @var{I}.
11023 @item @emph{Standard}:
11024 Fortran 95 and later, has overloads that are GNU extensions
11026 @item @emph{Class}:
11029 @item @emph{Syntax}:
11030 @code{RESULT = NOT(I)}
11032 @item @emph{Arguments}:
11033 @multitable @columnfractions .15 .70
11034 @item @var{I} @tab The type shall be @code{INTEGER}.
11037 @item @emph{Return value}:
11038 The return type is @code{INTEGER}, of the same kind as the
11041 @item @emph{Specific names}:
11042 @multitable @columnfractions .20 .20 .20 .25
11043 @item Name @tab Argument @tab Return type @tab Standard
11044 @item @code{NOT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
11045 @item @code{BNOT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
11046 @item @code{INOT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
11047 @item @code{JNOT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
11048 @item @code{KNOT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
11051 @item @emph{See also}:
11052 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
11059 @section @code{NULL} --- Function that returns an disassociated pointer
11061 @cindex pointer, status
11062 @cindex pointer, disassociated
11065 @item @emph{Description}:
11066 Returns a disassociated pointer.
11068 If @var{MOLD} is present, a disassociated pointer of the same type is
11069 returned, otherwise the type is determined by context.
11071 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
11072 includes cases where it is required.
11074 @item @emph{Standard}:
11075 Fortran 95 and later
11077 @item @emph{Class}:
11078 Transformational function
11080 @item @emph{Syntax}:
11081 @code{PTR => NULL([MOLD])}
11083 @item @emph{Arguments}:
11084 @multitable @columnfractions .15 .70
11085 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
11086 status and of any type.
11089 @item @emph{Return value}:
11090 A disassociated pointer.
11092 @item @emph{Example}:
11094 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
11097 @item @emph{See also}:
11104 @section @code{NUM_IMAGES} --- Function that returns the number of images
11105 @fnindex NUM_IMAGES
11106 @cindex coarray, @code{NUM_IMAGES}
11107 @cindex images, number of
11110 @item @emph{Description}:
11111 Returns the number of images.
11113 @item @emph{Standard}:
11114 Fortran 2008 and later. With @var{DISTANCE} or @var{FAILED} argument,
11115 Technical Specification (TS) 18508 or later
11118 @item @emph{Class}:
11119 Transformational function
11121 @item @emph{Syntax}:
11122 @code{RESULT = NUM_IMAGES(DISTANCE, FAILED)}
11124 @item @emph{Arguments}:
11125 @multitable @columnfractions .15 .70
11126 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
11127 @item @var{FAILED} @tab (optional, intent(in)) Scalar logical expression
11130 @item @emph{Return value}:
11131 Scalar default-kind integer. If @var{DISTANCE} is not present or has value 0,
11132 the number of images in the current team is returned. For values smaller or
11133 equal distance to the initial team, it returns the number of images index
11134 on the ancestor team which has a distance of @var{DISTANCE} from the invoking
11135 team. If @var{DISTANCE} is larger than the distance to the initial team, the
11136 number of images of the initial team is returned. If @var{FAILED} is not present
11137 the total number of images is returned; if it has the value @code{.TRUE.},
11138 the number of failed images is returned, otherwise, the number of images which
11139 do have not the failed status.
11141 @item @emph{Example}:
11143 INTEGER :: value[*]
11145 value = THIS_IMAGE()
11147 IF (THIS_IMAGE() == 1) THEN
11148 DO i = 1, NUM_IMAGES()
11149 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
11154 @item @emph{See also}:
11155 @ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
11161 @section @code{OR} --- Bitwise logical OR
11163 @cindex bitwise logical or
11164 @cindex logical or, bitwise
11167 @item @emph{Description}:
11168 Bitwise logical @code{OR}.
11170 This intrinsic routine is provided for backwards compatibility with
11171 GNU Fortran 77. For integer arguments, programmers should consider
11172 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
11174 @item @emph{Standard}:
11177 @item @emph{Class}:
11180 @item @emph{Syntax}:
11181 @code{RESULT = OR(I, J)}
11183 @item @emph{Arguments}:
11184 @multitable @columnfractions .15 .70
11185 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
11186 type or a scalar @code{LOGICAL} type or a boz-literal-constant.
11187 @item @var{J} @tab The type shall be the same as the type of @var{I} or
11188 a boz-literal-constant. @var{I} and @var{J} shall not both be
11189 boz-literal-constants. If either @var{I} and @var{J} is a
11190 boz-literal-constant, then the other argument must be a scalar @code{INTEGER}.
11193 @item @emph{Return value}:
11194 The return type is either a scalar @code{INTEGER} or a scalar
11195 @code{LOGICAL}. If the kind type parameters differ, then the
11196 smaller kind type is implicitly converted to larger kind, and the
11197 return has the larger kind. A boz-literal-constant is
11198 converted to an @code{INTEGER} with the kind type parameter of
11199 the other argument as-if a call to @ref{INT} occurred.
11201 @item @emph{Example}:
11204 LOGICAL :: T = .TRUE., F = .FALSE.
11206 DATA a / Z'F' /, b / Z'3' /
11208 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
11209 WRITE (*,*) OR(a, b)
11213 @item @emph{See also}:
11214 Fortran 95 elemental function: @ref{IOR}
11220 @section @code{PACK} --- Pack an array into an array of rank one
11222 @cindex array, packing
11223 @cindex array, reduce dimension
11224 @cindex array, gather elements
11227 @item @emph{Description}:
11228 Stores the elements of @var{ARRAY} in an array of rank one.
11230 The beginning of the resulting array is made up of elements whose @var{MASK}
11231 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
11234 @item @emph{Standard}:
11235 Fortran 95 and later
11237 @item @emph{Class}:
11238 Transformational function
11240 @item @emph{Syntax}:
11241 @code{RESULT = PACK(ARRAY, MASK[,VECTOR])}
11243 @item @emph{Arguments}:
11244 @multitable @columnfractions .15 .70
11245 @item @var{ARRAY} @tab Shall be an array of any type.
11246 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
11247 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
11249 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
11250 as @var{ARRAY} and of rank one. If present, the number of elements in
11251 @var{VECTOR} shall be equal to or greater than the number of true elements
11252 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
11253 @var{VECTOR} shall be equal to or greater than the number of elements in
11257 @item @emph{Return value}:
11258 The result is an array of rank one and the same type as that of @var{ARRAY}.
11259 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
11260 number of @code{TRUE} values in @var{MASK} otherwise.
11262 @item @emph{Example}:
11263 Gathering nonzero elements from an array:
11265 PROGRAM test_pack_1
11267 m = (/ 1, 0, 0, 0, 5, 0 /)
11268 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
11272 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
11274 PROGRAM test_pack_2
11276 m = (/ 1, 0, 0, 2 /)
11277 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
11281 @item @emph{See also}:
11288 @section @code{PARITY} --- Reduction with exclusive OR
11291 @cindex Reduction, XOR
11292 @cindex XOR reduction
11295 @item @emph{Description}:
11296 Calculates the parity, i.e. the reduction using @code{.XOR.},
11297 of @var{MASK} along dimension @var{DIM}.
11299 @item @emph{Standard}:
11300 Fortran 2008 and later
11302 @item @emph{Class}:
11303 Transformational function
11305 @item @emph{Syntax}:
11306 @multitable @columnfractions .80
11307 @item @code{RESULT = PARITY(MASK[, DIM])}
11310 @item @emph{Arguments}:
11311 @multitable @columnfractions .15 .70
11312 @item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL}
11313 @item @var{DIM} @tab (Optional) shall be a scalar of type
11314 @code{INTEGER} with a value in the range from 1 to n, where n
11315 equals the rank of @var{MASK}.
11318 @item @emph{Return value}:
11319 The result is of the same type as @var{MASK}.
11321 If @var{DIM} is absent, a scalar with the parity of all elements in
11322 @var{MASK} is returned, i.e. true if an odd number of elements is
11323 @code{.true.} and false otherwise. If @var{DIM} is present, an array
11324 of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
11325 and a shape similar to that of @var{MASK} with dimension @var{DIM}
11326 dropped is returned.
11328 @item @emph{Example}:
11331 LOGICAL :: x(2) = [ .true., .false. ]
11332 print *, PARITY(x) ! prints "T" (true).
11340 @section @code{PERROR} --- Print system error message
11342 @cindex system, error handling
11345 @item @emph{Description}:
11346 Prints (on the C @code{stderr} stream) a newline-terminated error
11347 message corresponding to the last system error. This is prefixed by
11348 @var{STRING}, a colon and a space. See @code{perror(3)}.
11350 @item @emph{Standard}:
11353 @item @emph{Class}:
11356 @item @emph{Syntax}:
11357 @code{CALL PERROR(STRING)}
11359 @item @emph{Arguments}:
11360 @multitable @columnfractions .15 .70
11361 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
11365 @item @emph{See also}:
11372 @section @code{POPCNT} --- Number of bits set
11374 @cindex binary representation
11378 @item @emph{Description}:
11379 @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
11380 representation of @code{I}.
11382 @item @emph{Standard}:
11383 Fortran 2008 and later
11385 @item @emph{Class}:
11388 @item @emph{Syntax}:
11389 @code{RESULT = POPCNT(I)}
11391 @item @emph{Arguments}:
11392 @multitable @columnfractions .15 .70
11393 @item @var{I} @tab Shall be of type @code{INTEGER}.
11396 @item @emph{Return value}:
11397 The return value is of type @code{INTEGER} and of the default integer
11400 @item @emph{See also}:
11401 @ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ}
11403 @item @emph{Example}:
11405 program test_population
11406 print *, popcnt(127), poppar(127)
11407 print *, popcnt(huge(0_4)), poppar(huge(0_4))
11408 print *, popcnt(huge(0_8)), poppar(huge(0_8))
11409 end program test_population
11415 @section @code{POPPAR} --- Parity of the number of bits set
11417 @cindex binary representation
11421 @item @emph{Description}:
11422 @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
11423 of the number of bits set ('1' bits) in the binary representation of
11424 @code{I}. It is equal to 0 if @code{I} has an even number of bits set,
11425 and 1 for an odd number of '1' bits.
11427 @item @emph{Standard}:
11428 Fortran 2008 and later
11430 @item @emph{Class}:
11433 @item @emph{Syntax}:
11434 @code{RESULT = POPPAR(I)}
11436 @item @emph{Arguments}:
11437 @multitable @columnfractions .15 .70
11438 @item @var{I} @tab Shall be of type @code{INTEGER}.
11441 @item @emph{Return value}:
11442 The return value is of type @code{INTEGER} and of the default integer
11445 @item @emph{See also}:
11446 @ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ}
11448 @item @emph{Example}:
11450 program test_population
11451 print *, popcnt(127), poppar(127)
11452 print *, popcnt(huge(0_4)), poppar(huge(0_4))
11453 print *, popcnt(huge(0_8)), poppar(huge(0_8))
11454 end program test_population
11461 @section @code{PRECISION} --- Decimal precision of a real kind
11463 @cindex model representation, precision
11466 @item @emph{Description}:
11467 @code{PRECISION(X)} returns the decimal precision in the model of the
11470 @item @emph{Standard}:
11471 Fortran 95 and later
11473 @item @emph{Class}:
11476 @item @emph{Syntax}:
11477 @code{RESULT = PRECISION(X)}
11479 @item @emph{Arguments}:
11480 @multitable @columnfractions .15 .70
11481 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
11484 @item @emph{Return value}:
11485 The return value is of type @code{INTEGER} and of the default integer
11488 @item @emph{See also}:
11489 @ref{SELECTED_REAL_KIND}, @ref{RANGE}
11491 @item @emph{Example}:
11493 program prec_and_range
11494 real(kind=4) :: x(2)
11495 complex(kind=8) :: y
11497 print *, precision(x), range(x)
11498 print *, precision(y), range(y)
11499 end program prec_and_range
11506 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
11510 @item @emph{Description}:
11511 Determines whether an optional dummy argument is present.
11513 @item @emph{Standard}:
11514 Fortran 95 and later
11516 @item @emph{Class}:
11519 @item @emph{Syntax}:
11520 @code{RESULT = PRESENT(A)}
11522 @item @emph{Arguments}:
11523 @multitable @columnfractions .15 .70
11524 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
11525 value, or a dummy procedure. It shall be the name of an optional dummy argument
11526 accessible within the current subroutine or function.
11529 @item @emph{Return value}:
11530 Returns either @code{TRUE} if the optional argument @var{A} is present, or
11531 @code{FALSE} otherwise.
11533 @item @emph{Example}:
11535 PROGRAM test_present
11536 WRITE(*,*) f(), f(42) ! "F T"
11538 LOGICAL FUNCTION f(x)
11539 INTEGER, INTENT(IN), OPTIONAL :: x
11549 @section @code{PRODUCT} --- Product of array elements
11551 @cindex array, product
11552 @cindex array, multiply elements
11553 @cindex array, conditionally multiply elements
11554 @cindex multiply array elements
11557 @item @emph{Description}:
11558 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
11559 the corresponding element in @var{MASK} is @code{TRUE}.
11561 @item @emph{Standard}:
11562 Fortran 95 and later
11564 @item @emph{Class}:
11565 Transformational function
11567 @item @emph{Syntax}:
11568 @multitable @columnfractions .80
11569 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
11570 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
11573 @item @emph{Arguments}:
11574 @multitable @columnfractions .15 .70
11575 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
11576 @code{REAL} or @code{COMPLEX}.
11577 @item @var{DIM} @tab (Optional) shall be a scalar of type
11578 @code{INTEGER} with a value in the range from 1 to n, where n
11579 equals the rank of @var{ARRAY}.
11580 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
11581 and either be a scalar or an array of the same shape as @var{ARRAY}.
11584 @item @emph{Return value}:
11585 The result is of the same type as @var{ARRAY}.
11587 If @var{DIM} is absent, a scalar with the product of all elements in
11588 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
11589 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
11590 dimension @var{DIM} dropped is returned.
11593 @item @emph{Example}:
11595 PROGRAM test_product
11596 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
11597 print *, PRODUCT(x) ! all elements, product = 120
11598 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
11602 @item @emph{See also}:
11609 @section @code{RADIX} --- Base of a model number
11611 @cindex model representation, base
11612 @cindex model representation, radix
11615 @item @emph{Description}:
11616 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
11618 @item @emph{Standard}:
11619 Fortran 95 and later
11621 @item @emph{Class}:
11624 @item @emph{Syntax}:
11625 @code{RESULT = RADIX(X)}
11627 @item @emph{Arguments}:
11628 @multitable @columnfractions .15 .70
11629 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
11632 @item @emph{Return value}:
11633 The return value is a scalar of type @code{INTEGER} and of the default
11636 @item @emph{See also}:
11637 @ref{SELECTED_REAL_KIND}
11639 @item @emph{Example}:
11642 print *, "The radix for the default integer kind is", radix(0)
11643 print *, "The radix for the default real kind is", radix(0.0)
11644 end program test_radix
11652 @section @code{RAN} --- Real pseudo-random number
11654 @cindex random number generation
11657 @item @emph{Description}:
11658 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
11659 provided as an alias for @code{RAND}. See @ref{RAND} for complete
11662 @item @emph{Standard}:
11665 @item @emph{Class}:
11668 @item @emph{See also}:
11669 @ref{RAND}, @ref{RANDOM_NUMBER}
11675 @section @code{RAND} --- Real pseudo-random number
11677 @cindex random number generation
11680 @item @emph{Description}:
11681 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
11682 distribution between 0 and 1. If @var{FLAG} is 0, the next number
11683 in the current sequence is returned; if @var{FLAG} is 1, the generator
11684 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
11685 it is used as a new seed with @code{SRAND}.
11687 This intrinsic routine is provided for backwards compatibility with
11688 GNU Fortran 77. It implements a simple modulo generator as provided
11689 by @command{g77}. For new code, one should consider the use of
11690 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
11692 @item @emph{Standard}:
11695 @item @emph{Class}:
11698 @item @emph{Syntax}:
11699 @code{RESULT = RAND(I)}
11701 @item @emph{Arguments}:
11702 @multitable @columnfractions .15 .70
11703 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
11706 @item @emph{Return value}:
11707 The return value is of @code{REAL} type and the default kind.
11709 @item @emph{Example}:
11712 integer,parameter :: seed = 86456
11715 print *, rand(), rand(), rand(), rand()
11716 print *, rand(seed), rand(), rand(), rand()
11717 end program test_rand
11720 @item @emph{See also}:
11721 @ref{SRAND}, @ref{RANDOM_NUMBER}
11727 @section @code{RANDOM_INIT} --- Initialize a pseudo-random number generator
11728 @fnindex RANDOM_INIT
11729 @cindex random number generation, initialization
11732 @item @emph{Description}:
11733 Initializes the state of the pseudorandom number generator used by
11734 @code{RANDOM_NUMBER}.
11736 @item @emph{Standard}:
11739 @item @emph{Class}:
11742 @item @emph{Syntax}:
11743 @code{CALL RANDOM_INIT(REPEATABLE, IMAGE_DISTINCT)}
11745 @item @emph{Arguments}:
11746 @multitable @columnfractions .20 .75
11747 @item @var{REPEATABLE} @tab Shall be a scalar with a @code{LOGICAL} type,
11748 and it is @code{INTENT(IN)}. If it is @code{.true.}, the seed is set to
11749 a processor-dependent value that is the same each time @code{RANDOM_INIT}
11750 is called from the same image. The term ``same image'' means a single
11751 instance of program execution. The sequence of random numbers is different
11752 for repeated execution of the program. If it is @code{.false.}, the seed
11753 is set to a processor-dependent value.
11754 @item @var{IMAGE_DISTINCT} @tab Shall be a scalar with a
11755 @code{LOGICAL} type, and it is @code{INTENT(IN)}. If it is @code{.true.},
11756 the seed is set to a processor-dependent value that is distinct from th
11757 seed set by a call to @code{RANDOM_INIT} in another image. If it is
11758 @code{.false.}, the seed is set value that does depend which image called
11759 @code{RANDOM_INIT}.
11762 @item @emph{Example}:
11764 program test_random_seed
11767 call random_init(.true., .true.)
11768 call random_number(x)
11769 call random_init(.true., .true.)
11770 call random_number(y)
11771 ! x and y are the same sequence
11772 if (any(x /= y)) call abort
11773 end program test_random_seed
11776 @item @emph{See also}:
11777 @ref{RANDOM_NUMBER}, @ref{RANDOM_SEED}
11781 @node RANDOM_NUMBER
11782 @section @code{RANDOM_NUMBER} --- Pseudo-random number
11783 @fnindex RANDOM_NUMBER
11784 @cindex random number generation
11787 @item @emph{Description}:
11788 Returns a single pseudorandom number or an array of pseudorandom numbers
11789 from the uniform distribution over the range @math{ 0 \leq x < 1}.
11791 The runtime-library implements the xorshift1024* random number
11792 generator (RNG). This generator has a period of @math{2^{1024} - 1},
11793 and when using multiple threads up to @math{2^{512}} threads can each
11794 generate @math{2^{512}} random numbers before any aliasing occurs.
11796 Note that in a multi-threaded program (e.g. using OpenMP directives),
11797 each thread will have its own random number state. For details of the
11798 seeding procedure, see the documentation for the @code{RANDOM_SEED}
11802 @item @emph{Standard}:
11803 Fortran 95 and later
11805 @item @emph{Class}:
11808 @item @emph{Syntax}:
11809 @code{RANDOM_NUMBER(HARVEST)}
11811 @item @emph{Arguments}:
11812 @multitable @columnfractions .15 .70
11813 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
11816 @item @emph{Example}:
11818 program test_random_number
11820 CALL RANDOM_NUMBER(r)
11824 @item @emph{See also}:
11825 @ref{RANDOM_SEED}, @ref{RANDOM_INIT}
11831 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
11832 @fnindex RANDOM_SEED
11833 @cindex random number generation, seeding
11834 @cindex seeding a random number generator
11837 @item @emph{Description}:
11838 Restarts or queries the state of the pseudorandom number generator used by
11839 @code{RANDOM_NUMBER}.
11841 If @code{RANDOM_SEED} is called without arguments, it is seeded with
11842 random data retrieved from the operating system.
11844 As an extension to the Fortran standard, the GFortran
11845 @code{RANDOM_NUMBER} supports multiple threads. Each thread in a
11846 multi-threaded program has its own seed. When @code{RANDOM_SEED} is
11847 called either without arguments or with the @var{PUT} argument, the
11848 given seed is copied into a master seed as well as the seed of the
11849 current thread. When a new thread uses @code{RANDOM_NUMBER} for the
11850 first time, the seed is copied from the master seed, and forwarded
11851 @math{N * 2^{512}} steps to guarantee that the random stream does not
11852 alias any other stream in the system, where @var{N} is the number of
11853 threads that have used @code{RANDOM_NUMBER} so far during the program
11856 @item @emph{Standard}:
11857 Fortran 95 and later
11859 @item @emph{Class}:
11862 @item @emph{Syntax}:
11863 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
11865 @item @emph{Arguments}:
11866 @multitable @columnfractions .15 .70
11867 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
11868 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
11869 of the arrays used with the @var{PUT} and @var{GET} arguments.
11870 @item @var{PUT} @tab (Optional) Shall be an array of type default
11871 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
11872 the array must be larger than or equal to the number returned by the
11873 @var{SIZE} argument.
11874 @item @var{GET} @tab (Optional) Shall be an array of type default
11875 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
11876 of the array must be larger than or equal to the number returned by
11877 the @var{SIZE} argument.
11880 @item @emph{Example}:
11882 program test_random_seed
11884 integer, allocatable :: seed(:)
11887 call random_seed(size = n)
11889 call random_seed(get=seed)
11891 end program test_random_seed
11894 @item @emph{See also}:
11895 @ref{RANDOM_NUMBER}, @ref{RANDOM_INIT}
11901 @section @code{RANGE} --- Decimal exponent range
11903 @cindex model representation, range
11906 @item @emph{Description}:
11907 @code{RANGE(X)} returns the decimal exponent range in the model of the
11910 @item @emph{Standard}:
11911 Fortran 95 and later
11913 @item @emph{Class}:
11916 @item @emph{Syntax}:
11917 @code{RESULT = RANGE(X)}
11919 @item @emph{Arguments}:
11920 @multitable @columnfractions .15 .70
11921 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
11925 @item @emph{Return value}:
11926 The return value is of type @code{INTEGER} and of the default integer
11929 @item @emph{See also}:
11930 @ref{SELECTED_REAL_KIND}, @ref{PRECISION}
11932 @item @emph{Example}:
11933 See @code{PRECISION} for an example.
11939 @section @code{RANK} --- Rank of a data object
11944 @item @emph{Description}:
11945 @code{RANK(A)} returns the rank of a scalar or array data object.
11947 @item @emph{Standard}:
11948 Technical Specification (TS) 29113
11950 @item @emph{Class}:
11953 @item @emph{Syntax}:
11954 @code{RESULT = RANK(A)}
11956 @item @emph{Arguments}:
11957 @multitable @columnfractions .15 .70
11958 @item @var{A} @tab can be of any type
11961 @item @emph{Return value}:
11962 The return value is of type @code{INTEGER} and of the default integer
11963 kind. For arrays, their rank is returned; for scalars zero is returned.
11965 @item @emph{Example}:
11969 real, allocatable :: b(:,:)
11971 print *, rank(a), rank(b) ! Prints: 0 2
11972 end program test_rank
11980 @section @code{REAL} --- Convert to real type
11989 @cindex conversion, to real
11990 @cindex complex numbers, real part
11993 @item @emph{Description}:
11994 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
11995 @code{REALPART} function is provided for compatibility with @command{g77},
11996 and its use is strongly discouraged.
11998 @item @emph{Standard}:
11999 Fortran 77 and later
12001 @item @emph{Class}:
12004 @item @emph{Syntax}:
12005 @multitable @columnfractions .80
12006 @item @code{RESULT = REAL(A [, KIND])}
12007 @item @code{RESULT = REALPART(Z)}
12010 @item @emph{Arguments}:
12011 @multitable @columnfractions .15 .70
12012 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
12014 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12015 expression indicating the kind parameter of the result.
12018 @item @emph{Return value}:
12019 These functions return a @code{REAL} variable or array under
12020 the following rules:
12024 @code{REAL(A)} is converted to a default real type if @var{A} is an
12025 integer or real variable.
12027 @code{REAL(A)} is converted to a real type with the kind type parameter
12028 of @var{A} if @var{A} is a complex variable.
12030 @code{REAL(A, KIND)} is converted to a real type with kind type
12031 parameter @var{KIND} if @var{A} is a complex, integer, or real
12035 @item @emph{Example}:
12038 complex :: x = (1.0, 2.0)
12039 print *, real(x), real(x,8), realpart(x)
12040 end program test_real
12043 @item @emph{Specific names}:
12044 @multitable @columnfractions .20 .20 .20 .25
12045 @item Name @tab Argument @tab Return type @tab Standard
12046 @item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later
12047 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension
12048 @item @code{FLOATI(A)} @tab @code{INTEGER(2)} @tab @code{REAL(4)} @tab GNU extension
12049 @item @code{FLOATJ(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab GNU extension
12050 @item @code{FLOATK(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab GNU extension
12051 @item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab Fortran 77 and later
12055 @item @emph{See also}:
12063 @section @code{RENAME} --- Rename a file
12065 @cindex file system, rename file
12068 @item @emph{Description}:
12069 Renames a file from file @var{PATH1} to @var{PATH2}. A null
12070 character (@code{CHAR(0)}) can be used to mark the end of the names in
12071 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
12072 names are ignored. If the @var{STATUS} argument is supplied, it
12073 contains 0 on success or a nonzero error code upon return; see
12076 This intrinsic is provided in both subroutine and function forms;
12077 however, only one form can be used in any given program unit.
12079 @item @emph{Standard}:
12082 @item @emph{Class}:
12083 Subroutine, function
12085 @item @emph{Syntax}:
12086 @multitable @columnfractions .80
12087 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
12088 @item @code{STATUS = RENAME(PATH1, PATH2)}
12091 @item @emph{Arguments}:
12092 @multitable @columnfractions .15 .70
12093 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
12094 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
12095 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12098 @item @emph{See also}:
12106 @section @code{REPEAT} --- Repeated string concatenation
12108 @cindex string, repeat
12109 @cindex string, concatenate
12112 @item @emph{Description}:
12113 Concatenates @var{NCOPIES} copies of a string.
12115 @item @emph{Standard}:
12116 Fortran 95 and later
12118 @item @emph{Class}:
12119 Transformational function
12121 @item @emph{Syntax}:
12122 @code{RESULT = REPEAT(STRING, NCOPIES)}
12124 @item @emph{Arguments}:
12125 @multitable @columnfractions .15 .70
12126 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
12127 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
12130 @item @emph{Return value}:
12131 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
12134 @item @emph{Example}:
12136 program test_repeat
12137 write(*,*) repeat("x", 5) ! "xxxxx"
12145 @section @code{RESHAPE} --- Function to reshape an array
12147 @cindex array, change dimensions
12148 @cindex array, transmogrify
12151 @item @emph{Description}:
12152 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
12153 the new array may be padded with elements from @var{PAD} or permuted
12154 as defined by @var{ORDER}.
12156 @item @emph{Standard}:
12157 Fortran 95 and later
12159 @item @emph{Class}:
12160 Transformational function
12162 @item @emph{Syntax}:
12163 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
12165 @item @emph{Arguments}:
12166 @multitable @columnfractions .15 .70
12167 @item @var{SOURCE} @tab Shall be an array of any type.
12168 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
12169 array of rank one. Its values must be positive or zero.
12170 @item @var{PAD} @tab (Optional) shall be an array of the same
12171 type as @var{SOURCE}.
12172 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
12173 and an array of the same shape as @var{SHAPE}. Its values shall
12174 be a permutation of the numbers from 1 to n, where n is the size of
12175 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
12179 @item @emph{Return value}:
12180 The result is an array of shape @var{SHAPE} with the same type as
12183 @item @emph{Example}:
12185 PROGRAM test_reshape
12186 INTEGER, DIMENSION(4) :: x
12187 WRITE(*,*) SHAPE(x) ! prints "4"
12188 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
12192 @item @emph{See also}:
12199 @section @code{RRSPACING} --- Reciprocal of the relative spacing
12201 @cindex real number, relative spacing
12202 @cindex floating point, relative spacing
12206 @item @emph{Description}:
12207 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
12208 model numbers near @var{X}.
12210 @item @emph{Standard}:
12211 Fortran 95 and later
12213 @item @emph{Class}:
12216 @item @emph{Syntax}:
12217 @code{RESULT = RRSPACING(X)}
12219 @item @emph{Arguments}:
12220 @multitable @columnfractions .15 .70
12221 @item @var{X} @tab Shall be of type @code{REAL}.
12224 @item @emph{Return value}:
12225 The return value is of the same type and kind as @var{X}.
12226 The value returned is equal to
12227 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
12229 @item @emph{See also}:
12236 @section @code{RSHIFT} --- Right shift bits
12238 @cindex bits, shift right
12241 @item @emph{Description}:
12242 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
12243 bits shifted right by @var{SHIFT} places. If the absolute value of
12244 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12245 Bits shifted out from the right end are lost. The fill is arithmetic: the
12246 bits shifted in from the left end are equal to the leftmost bit, which in
12247 two's complement representation is the sign bit.
12249 This function has been superseded by the @code{SHIFTA} intrinsic, which
12250 is standard in Fortran 2008 and later.
12252 @item @emph{Standard}:
12255 @item @emph{Class}:
12258 @item @emph{Syntax}:
12259 @code{RESULT = RSHIFT(I, SHIFT)}
12261 @item @emph{Arguments}:
12262 @multitable @columnfractions .15 .70
12263 @item @var{I} @tab The type shall be @code{INTEGER}.
12264 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12267 @item @emph{Return value}:
12268 The return value is of type @code{INTEGER} and of the same kind as
12271 @item @emph{See also}:
12272 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}, @ref{SHIFTA}, @ref{SHIFTR},
12280 @section @code{SAME_TYPE_AS} --- Query dynamic types for equality
12281 @fnindex SAME_TYPE_AS
12284 @item @emph{Description}:
12285 Query dynamic types for equality.
12287 @item @emph{Standard}:
12288 Fortran 2003 and later
12290 @item @emph{Class}:
12293 @item @emph{Syntax}:
12294 @code{RESULT = SAME_TYPE_AS(A, B)}
12296 @item @emph{Arguments}:
12297 @multitable @columnfractions .15 .70
12298 @item @var{A} @tab Shall be an object of extensible declared type or
12299 unlimited polymorphic.
12300 @item @var{B} @tab Shall be an object of extensible declared type or
12301 unlimited polymorphic.
12304 @item @emph{Return value}:
12305 The return value is a scalar of type default logical. It is true if and
12306 only if the dynamic type of A is the same as the dynamic type of B.
12308 @item @emph{See also}:
12309 @ref{EXTENDS_TYPE_OF}
12316 @section @code{SCALE} --- Scale a real value
12318 @cindex real number, scale
12319 @cindex floating point, scale
12322 @item @emph{Description}:
12323 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
12325 @item @emph{Standard}:
12326 Fortran 95 and later
12328 @item @emph{Class}:
12331 @item @emph{Syntax}:
12332 @code{RESULT = SCALE(X, I)}
12334 @item @emph{Arguments}:
12335 @multitable @columnfractions .15 .70
12336 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
12337 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
12340 @item @emph{Return value}:
12341 The return value is of the same type and kind as @var{X}.
12342 Its value is @code{X * RADIX(X)**I}.
12344 @item @emph{Example}:
12347 real :: x = 178.1387e-4
12349 print *, scale(x,i), x*radix(x)**i
12350 end program test_scale
12358 @section @code{SCAN} --- Scan a string for the presence of a set of characters
12360 @cindex string, find subset
12363 @item @emph{Description}:
12364 Scans a @var{STRING} for any of the characters in a @var{SET}
12367 If @var{BACK} is either absent or equals @code{FALSE}, this function
12368 returns the position of the leftmost character of @var{STRING} that is
12369 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
12370 is returned. If no character of @var{SET} is found in @var{STRING}, the
12373 @item @emph{Standard}:
12374 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12376 @item @emph{Class}:
12379 @item @emph{Syntax}:
12380 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
12382 @item @emph{Arguments}:
12383 @multitable @columnfractions .15 .70
12384 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
12385 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
12386 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
12387 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12388 expression indicating the kind parameter of the result.
12391 @item @emph{Return value}:
12392 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12393 @var{KIND} is absent, the return value is of default integer kind.
12395 @item @emph{Example}:
12398 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
12399 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
12400 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
12404 @item @emph{See also}:
12405 @ref{INDEX intrinsic}, @ref{VERIFY}
12411 @section @code{SECNDS} --- Time function
12413 @cindex time, elapsed
12414 @cindex elapsed time
12417 @item @emph{Description}:
12418 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
12419 @var{X} is a reference time, also in seconds. If this is zero, the time in
12420 seconds from midnight is returned. This function is non-standard and its
12421 use is discouraged.
12423 @item @emph{Standard}:
12426 @item @emph{Class}:
12429 @item @emph{Syntax}:
12430 @code{RESULT = SECNDS (X)}
12432 @item @emph{Arguments}:
12433 @multitable @columnfractions .15 .70
12434 @item @var{T} @tab Shall be of type @code{REAL(4)}.
12435 @item @var{X} @tab Shall be of type @code{REAL(4)}.
12438 @item @emph{Return value}:
12441 @item @emph{Example}:
12443 program test_secnds
12446 print *, secnds (0.0) ! seconds since midnight
12447 t1 = secnds (0.0) ! reference time
12448 do i = 1, 10000000 ! do something
12450 t2 = secnds (t1) ! elapsed time
12451 print *, "Something took ", t2, " seconds."
12452 end program test_secnds
12459 @section @code{SECOND} --- CPU time function
12461 @cindex time, elapsed
12462 @cindex elapsed time
12465 @item @emph{Description}:
12466 Returns a @code{REAL(4)} value representing the elapsed CPU time in
12467 seconds. This provides the same functionality as the standard
12468 @code{CPU_TIME} intrinsic, and is only included for backwards
12471 This intrinsic is provided in both subroutine and function forms;
12472 however, only one form can be used in any given program unit.
12474 @item @emph{Standard}:
12477 @item @emph{Class}:
12478 Subroutine, function
12480 @item @emph{Syntax}:
12481 @multitable @columnfractions .80
12482 @item @code{CALL SECOND(TIME)}
12483 @item @code{TIME = SECOND()}
12486 @item @emph{Arguments}:
12487 @multitable @columnfractions .15 .70
12488 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
12491 @item @emph{Return value}:
12492 In either syntax, @var{TIME} is set to the process's current runtime in
12495 @item @emph{See also}:
12502 @node SELECTED_CHAR_KIND
12503 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
12504 @fnindex SELECTED_CHAR_KIND
12505 @cindex character kind
12506 @cindex kind, character
12509 @item @emph{Description}:
12511 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
12512 set named @var{NAME}, if a character set with such a name is supported,
12513 or @math{-1} otherwise. Currently, supported character sets include
12514 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
12515 (Universal Character Set, UCS-4) which is commonly known as Unicode.
12517 @item @emph{Standard}:
12518 Fortran 2003 and later
12520 @item @emph{Class}:
12521 Transformational function
12523 @item @emph{Syntax}:
12524 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
12526 @item @emph{Arguments}:
12527 @multitable @columnfractions .15 .70
12528 @item @var{NAME} @tab Shall be a scalar and of the default character type.
12531 @item @emph{Example}:
12533 program character_kind
12534 use iso_fortran_env
12536 integer, parameter :: ascii = selected_char_kind ("ascii")
12537 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646')
12539 character(kind=ascii, len=26) :: alphabet
12540 character(kind=ucs4, len=30) :: hello_world
12542 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
12543 hello_world = ucs4_'Hello World and Ni Hao -- ' &
12544 // char (int (z'4F60'), ucs4) &
12545 // char (int (z'597D'), ucs4)
12547 write (*,*) alphabet
12549 open (output_unit, encoding='UTF-8')
12550 write (*,*) trim (hello_world)
12551 end program character_kind
12557 @node SELECTED_INT_KIND
12558 @section @code{SELECTED_INT_KIND} --- Choose integer kind
12559 @fnindex SELECTED_INT_KIND
12560 @cindex integer kind
12561 @cindex kind, integer
12564 @item @emph{Description}:
12565 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
12566 type that can represent all values ranging from @math{-10^R} (exclusive)
12567 to @math{10^R} (exclusive). If there is no integer kind that accommodates
12568 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
12570 @item @emph{Standard}:
12571 Fortran 95 and later
12573 @item @emph{Class}:
12574 Transformational function
12576 @item @emph{Syntax}:
12577 @code{RESULT = SELECTED_INT_KIND(R)}
12579 @item @emph{Arguments}:
12580 @multitable @columnfractions .15 .70
12581 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
12584 @item @emph{Example}:
12586 program large_integers
12587 integer,parameter :: k5 = selected_int_kind(5)
12588 integer,parameter :: k15 = selected_int_kind(15)
12589 integer(kind=k5) :: i5
12590 integer(kind=k15) :: i15
12592 print *, huge(i5), huge(i15)
12594 ! The following inequalities are always true
12595 print *, huge(i5) >= 10_k5**5-1
12596 print *, huge(i15) >= 10_k15**15-1
12597 end program large_integers
12603 @node SELECTED_REAL_KIND
12604 @section @code{SELECTED_REAL_KIND} --- Choose real kind
12605 @fnindex SELECTED_REAL_KIND
12608 @cindex radix, real
12611 @item @emph{Description}:
12612 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
12613 with decimal precision of at least @code{P} digits, exponent range of
12614 at least @code{R}, and with a radix of @code{RADIX}.
12616 @item @emph{Standard}:
12617 Fortran 95 and later, with @code{RADIX} Fortran 2008 or later
12619 @item @emph{Class}:
12620 Transformational function
12622 @item @emph{Syntax}:
12623 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
12625 @item @emph{Arguments}:
12626 @multitable @columnfractions .15 .70
12627 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12628 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12629 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12631 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
12632 be present; since Fortran 2008, they are assumed to be zero if absent.
12634 @item @emph{Return value}:
12636 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
12637 a real data type with decimal precision of at least @code{P} digits, a
12638 decimal exponent range of at least @code{R}, and with the requested
12639 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
12640 any radix can be returned. If more than one real data type meet the
12641 criteria, the kind of the data type with the smallest decimal precision
12642 is returned. If no real data type matches the criteria, the result is
12644 @item -1 if the processor does not support a real data type with a
12645 precision greater than or equal to @code{P}, but the @code{R} and
12646 @code{RADIX} requirements can be fulfilled
12647 @item -2 if the processor does not support a real type with an exponent
12648 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
12650 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
12652 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
12654 @item -5 if there is no real type with the given @code{RADIX}
12657 @item @emph{See also}:
12658 @ref{PRECISION}, @ref{RANGE}, @ref{RADIX}
12660 @item @emph{Example}:
12663 integer,parameter :: p6 = selected_real_kind(6)
12664 integer,parameter :: p10r100 = selected_real_kind(10,100)
12665 integer,parameter :: r400 = selected_real_kind(r=400)
12667 real(kind=p10r100) :: y
12668 real(kind=r400) :: z
12670 print *, precision(x), range(x)
12671 print *, precision(y), range(y)
12672 print *, precision(z), range(z)
12673 end program real_kinds
12680 @section @code{SET_EXPONENT} --- Set the exponent of the model
12681 @fnindex SET_EXPONENT
12682 @cindex real number, set exponent
12683 @cindex floating point, set exponent
12686 @item @emph{Description}:
12687 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
12688 is that that of @var{X} and whose exponent part is @var{I}.
12690 @item @emph{Standard}:
12691 Fortran 95 and later
12693 @item @emph{Class}:
12696 @item @emph{Syntax}:
12697 @code{RESULT = SET_EXPONENT(X, I)}
12699 @item @emph{Arguments}:
12700 @multitable @columnfractions .15 .70
12701 @item @var{X} @tab Shall be of type @code{REAL}.
12702 @item @var{I} @tab Shall be of type @code{INTEGER}.
12705 @item @emph{Return value}:
12706 The return value is of the same type and kind as @var{X}.
12707 The real number whose fractional part
12708 is that that of @var{X} and whose exponent part if @var{I} is returned;
12709 it is @code{FRACTION(X) * RADIX(X)**I}.
12711 @item @emph{Example}:
12713 PROGRAM test_setexp
12714 REAL :: x = 178.1387e-4
12716 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
12725 @section @code{SHAPE} --- Determine the shape of an array
12727 @cindex array, shape
12730 @item @emph{Description}:
12731 Determines the shape of an array.
12733 @item @emph{Standard}:
12734 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12736 @item @emph{Class}:
12739 @item @emph{Syntax}:
12740 @code{RESULT = SHAPE(SOURCE [, KIND])}
12742 @item @emph{Arguments}:
12743 @multitable @columnfractions .15 .70
12744 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
12745 If @var{SOURCE} is a pointer it must be associated and allocatable
12746 arrays must be allocated.
12747 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12748 expression indicating the kind parameter of the result.
12751 @item @emph{Return value}:
12752 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
12753 has dimensions. The elements of the resulting array correspond to the extend
12754 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
12755 the result is the rank one array of size zero. If @var{KIND} is absent, the
12756 return value has the default integer kind otherwise the specified kind.
12758 @item @emph{Example}:
12761 INTEGER, DIMENSION(-1:1, -1:2) :: A
12762 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
12763 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
12767 @item @emph{See also}:
12768 @ref{RESHAPE}, @ref{SIZE}
12774 @section @code{SHIFTA} --- Right shift with fill
12776 @cindex bits, shift right
12777 @cindex shift, right with fill
12780 @item @emph{Description}:
12781 @code{SHIFTA} returns a value corresponding to @var{I} with all of the
12782 bits shifted right by @var{SHIFT} places. If the absolute value of
12783 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12784 Bits shifted out from the right end are lost. The fill is arithmetic: the
12785 bits shifted in from the left end are equal to the leftmost bit, which in
12786 two's complement representation is the sign bit.
12788 @item @emph{Standard}:
12789 Fortran 2008 and later
12791 @item @emph{Class}:
12794 @item @emph{Syntax}:
12795 @code{RESULT = SHIFTA(I, SHIFT)}
12797 @item @emph{Arguments}:
12798 @multitable @columnfractions .15 .70
12799 @item @var{I} @tab The type shall be @code{INTEGER}.
12800 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12803 @item @emph{Return value}:
12804 The return value is of type @code{INTEGER} and of the same kind as
12807 @item @emph{See also}:
12808 @ref{SHIFTL}, @ref{SHIFTR}
12814 @section @code{SHIFTL} --- Left shift
12816 @cindex bits, shift left
12817 @cindex shift, left
12820 @item @emph{Description}:
12821 @code{SHIFTL} returns a value corresponding to @var{I} with all of the
12822 bits shifted left by @var{SHIFT} places. If the absolute value of
12823 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12824 Bits shifted out from the left end are lost, and bits shifted in from
12825 the right end are set to 0.
12827 @item @emph{Standard}:
12828 Fortran 2008 and later
12830 @item @emph{Class}:
12833 @item @emph{Syntax}:
12834 @code{RESULT = SHIFTL(I, SHIFT)}
12836 @item @emph{Arguments}:
12837 @multitable @columnfractions .15 .70
12838 @item @var{I} @tab The type shall be @code{INTEGER}.
12839 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12842 @item @emph{Return value}:
12843 The return value is of type @code{INTEGER} and of the same kind as
12846 @item @emph{See also}:
12847 @ref{SHIFTA}, @ref{SHIFTR}
12853 @section @code{SHIFTR} --- Right shift
12855 @cindex bits, shift right
12856 @cindex shift, right
12859 @item @emph{Description}:
12860 @code{SHIFTR} returns a value corresponding to @var{I} with all of the
12861 bits shifted right by @var{SHIFT} places. If the absolute value of
12862 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12863 Bits shifted out from the right end are lost, and bits shifted in from
12864 the left end are set to 0.
12866 @item @emph{Standard}:
12867 Fortran 2008 and later
12869 @item @emph{Class}:
12872 @item @emph{Syntax}:
12873 @code{RESULT = SHIFTR(I, SHIFT)}
12875 @item @emph{Arguments}:
12876 @multitable @columnfractions .15 .70
12877 @item @var{I} @tab The type shall be @code{INTEGER}.
12878 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12881 @item @emph{Return value}:
12882 The return value is of type @code{INTEGER} and of the same kind as
12885 @item @emph{See also}:
12886 @ref{SHIFTA}, @ref{SHIFTL}
12892 @section @code{SIGN} --- Sign copying function
12896 @cindex sign copying
12899 @item @emph{Description}:
12900 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
12902 @item @emph{Standard}:
12903 Fortran 77 and later
12905 @item @emph{Class}:
12908 @item @emph{Syntax}:
12909 @code{RESULT = SIGN(A, B)}
12911 @item @emph{Arguments}:
12912 @multitable @columnfractions .15 .70
12913 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
12914 @item @var{B} @tab Shall be of the same type and kind as @var{A}
12917 @item @emph{Return value}:
12918 The kind of the return value is that of @var{A} and @var{B}.
12919 If @math{B\ge 0} then the result is @code{ABS(A)}, else
12920 it is @code{-ABS(A)}.
12922 @item @emph{Example}:
12925 print *, sign(-12,1)
12926 print *, sign(-12,0)
12927 print *, sign(-12,-1)
12929 print *, sign(-12.,1.)
12930 print *, sign(-12.,0.)
12931 print *, sign(-12.,-1.)
12932 end program test_sign
12935 @item @emph{Specific names}:
12936 @multitable @columnfractions .20 .20 .20 .25
12937 @item Name @tab Arguments @tab Return type @tab Standard
12938 @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu
12939 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
12940 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu
12947 @section @code{SIGNAL} --- Signal handling subroutine (or function)
12949 @cindex system, signal handling
12952 @item @emph{Description}:
12953 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
12954 @var{HANDLER} to be executed with a single integer argument when signal
12955 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
12956 turn off handling of signal @var{NUMBER} or revert to its default
12957 action. See @code{signal(2)}.
12959 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
12960 is supplied, it is set to the value returned by @code{signal(2)}.
12962 @item @emph{Standard}:
12965 @item @emph{Class}:
12966 Subroutine, function
12968 @item @emph{Syntax}:
12969 @multitable @columnfractions .80
12970 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
12971 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
12974 @item @emph{Arguments}:
12975 @multitable @columnfractions .15 .70
12976 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
12977 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
12978 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
12979 @code{INTEGER}. It is @code{INTENT(IN)}.
12980 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
12981 integer. It has @code{INTENT(OUT)}.
12983 @c TODO: What should the interface of the handler be? Does it take arguments?
12985 @item @emph{Return value}:
12986 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
12988 @item @emph{Example}:
12990 program test_signal
12992 external handler_print
12994 call signal (12, handler_print)
12995 call signal (10, 1)
12998 end program test_signal
13005 @section @code{SIN} --- Sine function
13011 @cindex trigonometric function, sine
13015 @item @emph{Description}:
13016 @code{SIN(X)} computes the sine of @var{X}.
13018 @item @emph{Standard}:
13019 Fortran 77 and later
13021 @item @emph{Class}:
13024 @item @emph{Syntax}:
13025 @code{RESULT = SIN(X)}
13027 @item @emph{Arguments}:
13028 @multitable @columnfractions .15 .70
13029 @item @var{X} @tab The type shall be @code{REAL} or
13033 @item @emph{Return value}:
13034 The return value has same type and kind as @var{X}.
13036 @item @emph{Example}:
13041 end program test_sin
13044 @item @emph{Specific names}:
13045 @multitable @columnfractions .20 .20 .20 .25
13046 @item Name @tab Argument @tab Return type @tab Standard
13047 @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu
13048 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
13049 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
13050 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
13051 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
13054 @item @emph{See also}:
13055 Inverse function: @ref{ASIN}
13056 Degrees function: @ref{SIND}
13062 @section @code{SIND} --- Sine function, degrees
13068 @cindex trigonometric function, sine, degrees
13069 @cindex sine, degrees
13072 @item @emph{Description}:
13073 @code{SIND(X)} computes the sine of @var{X} in degrees.
13075 This function is for compatibility only and should be avoided in favor of
13076 standard constructs wherever possible.
13078 @item @emph{Standard}:
13079 GNU Extension, enabled with @option{-fdec-math}.
13081 @item @emph{Class}:
13084 @item @emph{Syntax}:
13085 @code{RESULT = SIND(X)}
13087 @item @emph{Arguments}:
13088 @multitable @columnfractions .15 .70
13089 @item @var{X} @tab The type shall be @code{REAL} or
13093 @item @emph{Return value}:
13094 The return value has same type and kind as @var{X}, and its value is in degrees.
13096 @item @emph{Example}:
13101 end program test_sind
13104 @item @emph{Specific names}:
13105 @multitable @columnfractions .20 .20 .20 .25
13106 @item Name @tab Argument @tab Return type @tab Standard
13107 @item @code{SIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
13108 @item @code{DSIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
13109 @item @code{CSIND(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU Extension
13110 @item @code{ZSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU Extension
13111 @item @code{CDSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU Extension
13114 @item @emph{See also}:
13115 Inverse function: @ref{ASIND}
13116 Radians function: @ref{SIN}
13123 @section @code{SINH} --- Hyperbolic sine function
13126 @cindex hyperbolic sine
13127 @cindex hyperbolic function, sine
13128 @cindex sine, hyperbolic
13131 @item @emph{Description}:
13132 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
13134 @item @emph{Standard}:
13135 Fortran 95 and later, for a complex argument Fortran 2008 or later
13137 @item @emph{Class}:
13140 @item @emph{Syntax}:
13141 @code{RESULT = SINH(X)}
13143 @item @emph{Arguments}:
13144 @multitable @columnfractions .15 .70
13145 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13148 @item @emph{Return value}:
13149 The return value has same type and kind as @var{X}.
13151 @item @emph{Example}:
13154 real(8) :: x = - 1.0_8
13156 end program test_sinh
13159 @item @emph{Specific names}:
13160 @multitable @columnfractions .20 .20 .20 .25
13161 @item Name @tab Argument @tab Return type @tab Standard
13162 @item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
13163 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
13166 @item @emph{See also}:
13173 @section @code{SIZE} --- Determine the size of an array
13175 @cindex array, size
13176 @cindex array, number of elements
13177 @cindex array, count elements
13180 @item @emph{Description}:
13181 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
13182 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
13184 @item @emph{Standard}:
13185 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
13187 @item @emph{Class}:
13190 @item @emph{Syntax}:
13191 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
13193 @item @emph{Arguments}:
13194 @multitable @columnfractions .15 .70
13195 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
13196 a pointer it must be associated and allocatable arrays must be allocated.
13197 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
13198 and its value shall be in the range from 1 to n, where n equals the rank
13200 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
13201 expression indicating the kind parameter of the result.
13204 @item @emph{Return value}:
13205 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
13206 @var{KIND} is absent, the return value is of default integer kind.
13208 @item @emph{Example}:
13211 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
13215 @item @emph{See also}:
13216 @ref{SHAPE}, @ref{RESHAPE}
13221 @section @code{SIZEOF} --- Size in bytes of an expression
13223 @cindex expression size
13224 @cindex size of an expression
13227 @item @emph{Description}:
13228 @code{SIZEOF(X)} calculates the number of bytes of storage the
13229 expression @code{X} occupies.
13231 @item @emph{Standard}:
13234 @item @emph{Class}:
13237 @item @emph{Syntax}:
13238 @code{N = SIZEOF(X)}
13240 @item @emph{Arguments}:
13241 @multitable @columnfractions .15 .70
13242 @item @var{X} @tab The argument shall be of any type, rank or shape.
13245 @item @emph{Return value}:
13246 The return value is of type integer and of the system-dependent kind
13247 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
13248 number of bytes occupied by the argument. If the argument has the
13249 @code{POINTER} attribute, the number of bytes of the storage area pointed
13250 to is returned. If the argument is of a derived type with @code{POINTER}
13251 or @code{ALLOCATABLE} components, the return value does not account for
13252 the sizes of the data pointed to by these components. If the argument is
13253 polymorphic, the size according to the dynamic type is returned. The argument
13254 may not be a procedure or procedure pointer. Note that the code assumes for
13255 arrays that those are contiguous; for contiguous arrays, it returns the
13256 storage or an array element multiplied by the size of the array.
13258 @item @emph{Example}:
13262 print *, (sizeof(s)/sizeof(r) == 5)
13265 The example will print @code{.TRUE.} unless you are using a platform
13266 where default @code{REAL} variables are unusually padded.
13268 @item @emph{See also}:
13269 @ref{C_SIZEOF}, @ref{STORAGE_SIZE}
13274 @section @code{SLEEP} --- Sleep for the specified number of seconds
13276 @cindex delayed execution
13279 @item @emph{Description}:
13280 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
13282 @item @emph{Standard}:
13285 @item @emph{Class}:
13288 @item @emph{Syntax}:
13289 @code{CALL SLEEP(SECONDS)}
13291 @item @emph{Arguments}:
13292 @multitable @columnfractions .15 .70
13293 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
13296 @item @emph{Example}:
13307 @section @code{SPACING} --- Smallest distance between two numbers of a given type
13309 @cindex real number, relative spacing
13310 @cindex floating point, relative spacing
13313 @item @emph{Description}:
13314 Determines the distance between the argument @var{X} and the nearest
13315 adjacent number of the same type.
13317 @item @emph{Standard}:
13318 Fortran 95 and later
13320 @item @emph{Class}:
13323 @item @emph{Syntax}:
13324 @code{RESULT = SPACING(X)}
13326 @item @emph{Arguments}:
13327 @multitable @columnfractions .15 .70
13328 @item @var{X} @tab Shall be of type @code{REAL}.
13331 @item @emph{Return value}:
13332 The result is of the same type as the input argument @var{X}.
13334 @item @emph{Example}:
13336 PROGRAM test_spacing
13337 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
13338 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
13340 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
13341 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
13345 @item @emph{See also}:
13352 @section @code{SPREAD} --- Add a dimension to an array
13354 @cindex array, increase dimension
13355 @cindex array, duplicate elements
13356 @cindex array, duplicate dimensions
13359 @item @emph{Description}:
13360 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
13361 dimension @var{DIM}.
13363 @item @emph{Standard}:
13364 Fortran 95 and later
13366 @item @emph{Class}:
13367 Transformational function
13369 @item @emph{Syntax}:
13370 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
13372 @item @emph{Arguments}:
13373 @multitable @columnfractions .15 .70
13374 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
13375 a rank less than seven.
13376 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
13377 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
13378 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
13381 @item @emph{Return value}:
13382 The result is an array of the same type as @var{SOURCE} and has rank n+1
13383 where n equals the rank of @var{SOURCE}.
13385 @item @emph{Example}:
13387 PROGRAM test_spread
13388 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
13389 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
13390 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
13394 @item @emph{See also}:
13401 @section @code{SQRT} --- Square-root function
13408 @cindex square-root
13411 @item @emph{Description}:
13412 @code{SQRT(X)} computes the square root of @var{X}.
13414 @item @emph{Standard}:
13415 Fortran 77 and later
13417 @item @emph{Class}:
13420 @item @emph{Syntax}:
13421 @code{RESULT = SQRT(X)}
13423 @item @emph{Arguments}:
13424 @multitable @columnfractions .15 .70
13425 @item @var{X} @tab The type shall be @code{REAL} or
13429 @item @emph{Return value}:
13430 The return value is of type @code{REAL} or @code{COMPLEX}.
13431 The kind type parameter is the same as @var{X}.
13433 @item @emph{Example}:
13436 real(8) :: x = 2.0_8
13437 complex :: z = (1.0, 2.0)
13440 end program test_sqrt
13443 @item @emph{Specific names}:
13444 @multitable @columnfractions .20 .20 .20 .25
13445 @item Name @tab Argument @tab Return type @tab Standard
13446 @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
13447 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
13448 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
13449 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13450 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13457 @section @code{SRAND} --- Reinitialize the random number generator
13459 @cindex random number generation, seeding
13460 @cindex seeding a random number generator
13463 @item @emph{Description}:
13464 @code{SRAND} reinitializes the pseudo-random number generator
13465 called by @code{RAND} and @code{IRAND}. The new seed used by the
13466 generator is specified by the required argument @var{SEED}.
13468 @item @emph{Standard}:
13471 @item @emph{Class}:
13474 @item @emph{Syntax}:
13475 @code{CALL SRAND(SEED)}
13477 @item @emph{Arguments}:
13478 @multitable @columnfractions .15 .70
13479 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
13482 @item @emph{Return value}:
13483 Does not return anything.
13485 @item @emph{Example}:
13486 See @code{RAND} and @code{IRAND} for examples.
13488 @item @emph{Notes}:
13489 The Fortran standard specifies the intrinsic subroutines
13490 @code{RANDOM_SEED} to initialize the pseudo-random number
13491 generator and @code{RANDOM_NUMBER} to generate pseudo-random numbers.
13492 These subroutines should be used in new codes.
13494 Please note that in GNU Fortran, these two sets of intrinsics (@code{RAND},
13495 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
13496 @code{RANDOM_SEED} on the other hand) access two independent
13497 pseudo-random number generators.
13499 @item @emph{See also}:
13500 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
13507 @section @code{STAT} --- Get file status
13509 @cindex file system, file status
13512 @item @emph{Description}:
13513 This function returns information about a file. No permissions are required on
13514 the file itself, but execute (search) permission is required on all of the
13515 directories in path that lead to the file.
13517 The elements that are obtained and stored in the array @code{VALUES}:
13518 @multitable @columnfractions .15 .70
13519 @item @code{VALUES(1)} @tab Device ID
13520 @item @code{VALUES(2)} @tab Inode number
13521 @item @code{VALUES(3)} @tab File mode
13522 @item @code{VALUES(4)} @tab Number of links
13523 @item @code{VALUES(5)} @tab Owner's uid
13524 @item @code{VALUES(6)} @tab Owner's gid
13525 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
13526 @item @code{VALUES(8)} @tab File size (bytes)
13527 @item @code{VALUES(9)} @tab Last access time
13528 @item @code{VALUES(10)} @tab Last modification time
13529 @item @code{VALUES(11)} @tab Last file status change time
13530 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
13531 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
13534 Not all these elements are relevant on all systems.
13535 If an element is not relevant, it is returned as 0.
13537 This intrinsic is provided in both subroutine and function forms; however,
13538 only one form can be used in any given program unit.
13540 @item @emph{Standard}:
13543 @item @emph{Class}:
13544 Subroutine, function
13546 @item @emph{Syntax}:
13547 @multitable @columnfractions .80
13548 @item @code{CALL STAT(NAME, VALUES [, STATUS])}
13549 @item @code{STATUS = STAT(NAME, VALUES)}
13552 @item @emph{Arguments}:
13553 @multitable @columnfractions .15 .70
13554 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
13555 default kind and a valid path within the file system.
13556 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
13557 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
13558 on success and a system specific error code otherwise.
13561 @item @emph{Example}:
13564 INTEGER, DIMENSION(13) :: buff
13567 CALL STAT("/etc/passwd", buff, status)
13569 IF (status == 0) THEN
13570 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
13571 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
13572 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
13573 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
13574 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
13575 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
13576 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
13577 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
13578 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
13579 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
13580 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
13581 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
13582 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
13587 @item @emph{See also}:
13588 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
13594 @section @code{STORAGE_SIZE} --- Storage size in bits
13595 @fnindex STORAGE_SIZE
13596 @cindex storage size
13599 @item @emph{Description}:
13600 Returns the storage size of argument @var{A} in bits.
13601 @item @emph{Standard}:
13602 Fortran 2008 and later
13603 @item @emph{Class}:
13605 @item @emph{Syntax}:
13606 @code{RESULT = STORAGE_SIZE(A [, KIND])}
13608 @item @emph{Arguments}:
13609 @multitable @columnfractions .15 .70
13610 @item @var{A} @tab Shall be a scalar or array of any type.
13611 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
13614 @item @emph{Return Value}:
13615 The result is a scalar integer with the kind type parameter specified by KIND
13616 (or default integer type if KIND is missing). The result value is the size
13617 expressed in bits for an element of an array that has the dynamic type and type
13620 @item @emph{See also}:
13621 @ref{C_SIZEOF}, @ref{SIZEOF}
13627 @section @code{SUM} --- Sum of array elements
13630 @cindex array, add elements
13631 @cindex array, conditionally add elements
13632 @cindex sum array elements
13635 @item @emph{Description}:
13636 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
13637 the corresponding element in @var{MASK} is @code{TRUE}.
13639 @item @emph{Standard}:
13640 Fortran 95 and later
13642 @item @emph{Class}:
13643 Transformational function
13645 @item @emph{Syntax}:
13646 @multitable @columnfractions .80
13647 @item @code{RESULT = SUM(ARRAY[, MASK])}
13648 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
13651 @item @emph{Arguments}:
13652 @multitable @columnfractions .15 .70
13653 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
13654 @code{REAL} or @code{COMPLEX}.
13655 @item @var{DIM} @tab (Optional) shall be a scalar of type
13656 @code{INTEGER} with a value in the range from 1 to n, where n
13657 equals the rank of @var{ARRAY}.
13658 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
13659 and either be a scalar or an array of the same shape as @var{ARRAY}.
13662 @item @emph{Return value}:
13663 The result is of the same type as @var{ARRAY}.
13665 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
13666 is returned. Otherwise, an array of rank n-1, where n equals the rank of
13667 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
13668 dropped is returned.
13670 @item @emph{Example}:
13673 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
13674 print *, SUM(x) ! all elements, sum = 15
13675 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
13679 @item @emph{See also}:
13686 @section @code{SYMLNK} --- Create a symbolic link
13688 @cindex file system, create link
13689 @cindex file system, soft link
13692 @item @emph{Description}:
13693 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
13694 character (@code{CHAR(0)}) can be used to mark the end of the names in
13695 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
13696 names are ignored. If the @var{STATUS} argument is supplied, it
13697 contains 0 on success or a nonzero error code upon return; see
13698 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
13699 @code{ENOSYS} is returned.
13701 This intrinsic is provided in both subroutine and function forms;
13702 however, only one form can be used in any given program unit.
13704 @item @emph{Standard}:
13707 @item @emph{Class}:
13708 Subroutine, function
13710 @item @emph{Syntax}:
13711 @multitable @columnfractions .80
13712 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
13713 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
13716 @item @emph{Arguments}:
13717 @multitable @columnfractions .15 .70
13718 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
13719 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
13720 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
13723 @item @emph{See also}:
13724 @ref{LINK}, @ref{UNLINK}
13731 @section @code{SYSTEM} --- Execute a shell command
13733 @cindex system, system call
13736 @item @emph{Description}:
13737 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
13738 argument @var{STATUS} is present, it contains the value returned by
13739 @code{system(3)}, which is presumably 0 if the shell command succeeded.
13740 Note that which shell is used to invoke the command is system-dependent
13741 and environment-dependent.
13743 This intrinsic is provided in both subroutine and function forms;
13744 however, only one form can be used in any given program unit.
13746 Note that the @code{system} function need not be thread-safe. It is
13747 the responsibility of the user to ensure that @code{system} is not
13748 called concurrently.
13750 @item @emph{Standard}:
13753 @item @emph{Class}:
13754 Subroutine, function
13756 @item @emph{Syntax}:
13757 @multitable @columnfractions .80
13758 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
13759 @item @code{STATUS = SYSTEM(COMMAND)}
13762 @item @emph{Arguments}:
13763 @multitable @columnfractions .15 .70
13764 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
13765 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
13768 @item @emph{See also}:
13769 @ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
13770 and should considered in new code for future portability.
13776 @section @code{SYSTEM_CLOCK} --- Time function
13777 @fnindex SYSTEM_CLOCK
13778 @cindex time, clock ticks
13779 @cindex clock ticks
13782 @item @emph{Description}:
13783 Determines the @var{COUNT} of a processor clock since an unspecified
13784 time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines
13785 the number of clock ticks per second. If the platform supports a
13786 monotonic clock, that clock is used and can, depending on the platform
13787 clock implementation, provide up to nanosecond resolution. If a
13788 monotonic clock is not available, the implementation falls back to a
13791 @var{COUNT_RATE} is system dependent and can vary depending on the kind of
13792 the arguments. For @var{kind=4} arguments (and smaller integer kinds),
13793 @var{COUNT} represents milliseconds, while for @var{kind=8} arguments (and
13794 larger integer kinds), @var{COUNT} typically represents micro- or
13795 nanoseconds depending on resolution of the underlying platform clock.
13796 @var{COUNT_MAX} usually equals @code{HUGE(COUNT_MAX)}. Note that the
13797 millisecond resolution of the @var{kind=4} version implies that the
13798 @var{COUNT} will wrap around in roughly 25 days. In order to avoid issues
13799 with the wrap around and for more precise timing, please use the
13800 @var{kind=8} version.
13802 If there is no clock, or querying the clock fails, @var{COUNT} is set
13803 to @code{-HUGE(COUNT)}, and @var{COUNT_RATE} and @var{COUNT_MAX} are
13806 When running on a platform using the GNU C library (glibc) version
13807 2.16 or older, or a derivative thereof, the high resolution monotonic
13808 clock is available only when linking with the @var{rt} library. This
13809 can be done explicitly by adding the @code{-lrt} flag when linking the
13810 application, but is also done implicitly when using OpenMP.
13812 On the Windows platform, the version with @var{kind=4} arguments uses
13813 the @code{GetTickCount} function, whereas the @var{kind=8} version
13814 uses @code{QueryPerformanceCounter} and
13815 @code{QueryPerformanceCounterFrequency}. For more information, and
13816 potential caveats, please see the platform documentation.
13818 @item @emph{Standard}:
13819 Fortran 95 and later
13821 @item @emph{Class}:
13824 @item @emph{Syntax}:
13825 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
13827 @item @emph{Arguments}:
13828 @multitable @columnfractions .15 .70
13829 @item @var{COUNT} @tab (Optional) shall be a scalar of type
13830 @code{INTEGER} with @code{INTENT(OUT)}.
13831 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type
13832 @code{INTEGER} or @code{REAL}, with @code{INTENT(OUT)}.
13833 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type
13834 @code{INTEGER} with @code{INTENT(OUT)}.
13837 @item @emph{Example}:
13839 PROGRAM test_system_clock
13840 INTEGER :: count, count_rate, count_max
13841 CALL SYSTEM_CLOCK(count, count_rate, count_max)
13842 WRITE(*,*) count, count_rate, count_max
13846 @item @emph{See also}:
13847 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
13853 @section @code{TAN} --- Tangent function
13856 @cindex trigonometric function, tangent
13860 @item @emph{Description}:
13861 @code{TAN(X)} computes the tangent of @var{X}.
13863 @item @emph{Standard}:
13864 Fortran 77 and later, for a complex argument Fortran 2008 or later
13866 @item @emph{Class}:
13869 @item @emph{Syntax}:
13870 @code{RESULT = TAN(X)}
13872 @item @emph{Arguments}:
13873 @multitable @columnfractions .15 .70
13874 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13877 @item @emph{Return value}:
13878 The return value has same type and kind as @var{X}, and its value is in radians.
13880 @item @emph{Example}:
13883 real(8) :: x = 0.165_8
13885 end program test_tan
13888 @item @emph{Specific names}:
13889 @multitable @columnfractions .20 .20 .20 .25
13890 @item Name @tab Argument @tab Return type @tab Standard
13891 @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
13892 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
13895 @item @emph{See also}:
13896 Inverse function: @ref{ATAN}
13897 Degrees function: @ref{TAND}
13903 @section @code{TAND} --- Tangent function, degrees
13906 @cindex trigonometric function, tangent, degrees
13907 @cindex tangent, degrees
13910 @item @emph{Description}:
13911 @code{TAND(X)} computes the tangent of @var{X} in degrees.
13913 This function is for compatibility only and should be avoided in favor of
13914 standard constructs wherever possible.
13916 @item @emph{Standard}:
13917 GNU Extension, enabled with @option{-fdec-math}.
13919 @item @emph{Class}:
13922 @item @emph{Syntax}:
13923 @code{RESULT = TAND(X)}
13925 @item @emph{Arguments}:
13926 @multitable @columnfractions .15 .70
13927 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13930 @item @emph{Return value}:
13931 The return value has same type and kind as @var{X}, and its value is in degrees.
13933 @item @emph{Example}:
13936 real(8) :: x = 0.165_8
13938 end program test_tand
13941 @item @emph{Specific names}:
13942 @multitable @columnfractions .20 .20 .20 .25
13943 @item Name @tab Argument @tab Return type @tab Standard
13944 @item @code{TAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
13945 @item @code{DTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
13948 @item @emph{See also}:
13949 Inverse function: @ref{ATAND}
13950 Radians function: @ref{TAN}
13956 @section @code{TANH} --- Hyperbolic tangent function
13959 @cindex hyperbolic tangent
13960 @cindex hyperbolic function, tangent
13961 @cindex tangent, hyperbolic
13964 @item @emph{Description}:
13965 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
13967 @item @emph{Standard}:
13968 Fortran 77 and later, for a complex argument Fortran 2008 or later
13970 @item @emph{Class}:
13973 @item @emph{Syntax}:
13976 @item @emph{Arguments}:
13977 @multitable @columnfractions .15 .70
13978 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13981 @item @emph{Return value}:
13982 The return value has same type and kind as @var{X}. If @var{X} is
13983 complex, the imaginary part of the result is in radians. If @var{X}
13984 is @code{REAL}, the return value lies in the range
13985 @math{ - 1 \leq tanh(x) \leq 1 }.
13987 @item @emph{Example}:
13990 real(8) :: x = 2.1_8
13992 end program test_tanh
13995 @item @emph{Specific names}:
13996 @multitable @columnfractions .20 .20 .20 .25
13997 @item Name @tab Argument @tab Return type @tab Standard
13998 @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
13999 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
14002 @item @emph{See also}:
14009 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
14010 @fnindex THIS_IMAGE
14011 @cindex coarray, @code{THIS_IMAGE}
14012 @cindex images, index of this image
14015 @item @emph{Description}:
14016 Returns the cosubscript for this image.
14018 @item @emph{Standard}:
14019 Fortran 2008 and later. With @var{DISTANCE} argument,
14020 Technical Specification (TS) 18508 or later
14022 @item @emph{Class}:
14023 Transformational function
14025 @item @emph{Syntax}:
14026 @multitable @columnfractions .80
14027 @item @code{RESULT = THIS_IMAGE()}
14028 @item @code{RESULT = THIS_IMAGE(DISTANCE)}
14029 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
14032 @item @emph{Arguments}:
14033 @multitable @columnfractions .15 .70
14034 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
14035 (not permitted together with @var{COARRAY}).
14036 @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
14037 present, required).
14038 @item @var{DIM} @tab default integer scalar (optional). If present,
14039 @var{DIM} shall be between one and the corank of @var{COARRAY}.
14043 @item @emph{Return value}:
14044 Default integer. If @var{COARRAY} is not present, it is scalar; if
14045 @var{DISTANCE} is not present or has value 0, its value is the image index on
14046 the invoking image for the current team, for values smaller or equal
14047 distance to the initial team, it returns the image index on the ancestor team
14048 which has a distance of @var{DISTANCE} from the invoking team. If
14049 @var{DISTANCE} is larger than the distance to the initial team, the image
14050 index of the initial team is returned. Otherwise when the @var{COARRAY} is
14051 present, if @var{DIM} is not present, a rank-1 array with corank elements is
14052 returned, containing the cosubscripts for @var{COARRAY} specifying the invoking
14053 image. If @var{DIM} is present, a scalar is returned, with the value of
14054 the @var{DIM} element of @code{THIS_IMAGE(COARRAY)}.
14056 @item @emph{Example}:
14058 INTEGER :: value[*]
14060 value = THIS_IMAGE()
14062 IF (THIS_IMAGE() == 1) THEN
14063 DO i = 1, NUM_IMAGES()
14064 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
14068 ! Check whether the current image is the initial image
14069 IF (THIS_IMAGE(HUGE(1)) /= THIS_IMAGE())
14070 error stop "something is rotten here"
14073 @item @emph{See also}:
14074 @ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
14080 @section @code{TIME} --- Time function
14082 @cindex time, current
14083 @cindex current time
14086 @item @emph{Description}:
14087 Returns the current time encoded as an integer (in the manner of the
14088 function @code{time(3)} in the C standard library). This value is
14089 suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}.
14091 This intrinsic is not fully portable, such as to systems with 32-bit
14092 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
14093 the values returned by this intrinsic might be, or become, negative, or
14094 numerically less than previous values, during a single run of the
14097 See @ref{TIME8}, for information on a similar intrinsic that might be
14098 portable to more GNU Fortran implementations, though to fewer Fortran
14101 @item @emph{Standard}:
14104 @item @emph{Class}:
14107 @item @emph{Syntax}:
14108 @code{RESULT = TIME()}
14110 @item @emph{Return value}:
14111 The return value is a scalar of type @code{INTEGER(4)}.
14113 @item @emph{See also}:
14114 @ref{DATE_AND_TIME}, @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
14121 @section @code{TIME8} --- Time function (64-bit)
14123 @cindex time, current
14124 @cindex current time
14127 @item @emph{Description}:
14128 Returns the current time encoded as an integer (in the manner of the
14129 function @code{time(3)} in the C standard library). This value is
14130 suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}.
14132 @emph{Warning:} this intrinsic does not increase the range of the timing
14133 values over that returned by @code{time(3)}. On a system with a 32-bit
14134 @code{time(3)}, @code{TIME8} will return a 32-bit value, even though
14135 it is converted to a 64-bit @code{INTEGER(8)} value. That means
14136 overflows of the 32-bit value can still occur. Therefore, the values
14137 returned by this intrinsic might be or become negative or numerically
14138 less than previous values during a single run of the compiled program.
14140 @item @emph{Standard}:
14143 @item @emph{Class}:
14146 @item @emph{Syntax}:
14147 @code{RESULT = TIME8()}
14149 @item @emph{Return value}:
14150 The return value is a scalar of type @code{INTEGER(8)}.
14152 @item @emph{See also}:
14153 @ref{DATE_AND_TIME}, @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
14160 @section @code{TINY} --- Smallest positive number of a real kind
14162 @cindex limits, smallest number
14163 @cindex model representation, smallest number
14166 @item @emph{Description}:
14167 @code{TINY(X)} returns the smallest positive (non zero) number
14168 in the model of the type of @code{X}.
14170 @item @emph{Standard}:
14171 Fortran 95 and later
14173 @item @emph{Class}:
14176 @item @emph{Syntax}:
14177 @code{RESULT = TINY(X)}
14179 @item @emph{Arguments}:
14180 @multitable @columnfractions .15 .70
14181 @item @var{X} @tab Shall be of type @code{REAL}.
14184 @item @emph{Return value}:
14185 The return value is of the same type and kind as @var{X}
14187 @item @emph{Example}:
14188 See @code{HUGE} for an example.
14194 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
14199 @item @emph{Description}:
14200 @code{TRAILZ} returns the number of trailing zero bits of an integer.
14202 @item @emph{Standard}:
14203 Fortran 2008 and later
14205 @item @emph{Class}:
14208 @item @emph{Syntax}:
14209 @code{RESULT = TRAILZ(I)}
14211 @item @emph{Arguments}:
14212 @multitable @columnfractions .15 .70
14213 @item @var{I} @tab Shall be of type @code{INTEGER}.
14216 @item @emph{Return value}:
14217 The type of the return value is the default @code{INTEGER}.
14218 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
14220 @item @emph{Example}:
14222 PROGRAM test_trailz
14223 WRITE (*,*) TRAILZ(8) ! prints 3
14227 @item @emph{See also}:
14228 @ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT}
14234 @section @code{TRANSFER} --- Transfer bit patterns
14240 @item @emph{Description}:
14241 Interprets the bitwise representation of @var{SOURCE} in memory as if it
14242 is the representation of a variable or array of the same type and type
14243 parameters as @var{MOLD}.
14245 This is approximately equivalent to the C concept of @emph{casting} one
14248 @item @emph{Standard}:
14249 Fortran 95 and later
14251 @item @emph{Class}:
14252 Transformational function
14254 @item @emph{Syntax}:
14255 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
14257 @item @emph{Arguments}:
14258 @multitable @columnfractions .15 .70
14259 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
14260 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
14261 @item @var{SIZE} @tab (Optional) shall be a scalar of type
14265 @item @emph{Return value}:
14266 The result has the same type as @var{MOLD}, with the bit level
14267 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
14268 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
14269 but @var{MOLD} is an array (of any size or shape), the result is a one-
14270 dimensional array of the minimum length needed to contain the entirety
14271 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
14272 and @var{MOLD} is a scalar, the result is a scalar.
14274 If the bitwise representation of the result is longer than that of
14275 @var{SOURCE}, then the leading bits of the result correspond to those of
14276 @var{SOURCE} and any trailing bits are filled arbitrarily.
14278 When the resulting bit representation does not correspond to a valid
14279 representation of a variable of the same type as @var{MOLD}, the results
14280 are undefined, and subsequent operations on the result cannot be
14281 guaranteed to produce sensible behavior. For example, it is possible to
14282 create @code{LOGICAL} variables for which @code{@var{VAR}} and
14283 @code{.NOT.@var{VAR}} both appear to be true.
14285 @item @emph{Example}:
14287 PROGRAM test_transfer
14288 integer :: x = 2143289344
14289 print *, transfer(x, 1.0) ! prints "NaN" on i686
14297 @section @code{TRANSPOSE} --- Transpose an array of rank two
14299 @cindex array, transpose
14300 @cindex matrix, transpose
14304 @item @emph{Description}:
14305 Transpose an array of rank two. Element (i, j) of the result has the value
14306 @code{MATRIX(j, i)}, for all i, j.
14308 @item @emph{Standard}:
14309 Fortran 95 and later
14311 @item @emph{Class}:
14312 Transformational function
14314 @item @emph{Syntax}:
14315 @code{RESULT = TRANSPOSE(MATRIX)}
14317 @item @emph{Arguments}:
14318 @multitable @columnfractions .15 .70
14319 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
14322 @item @emph{Return value}:
14323 The result has the same type as @var{MATRIX}, and has shape
14324 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
14330 @section @code{TRIM} --- Remove trailing blank characters of a string
14332 @cindex string, remove trailing whitespace
14335 @item @emph{Description}:
14336 Removes trailing blank characters of a string.
14338 @item @emph{Standard}:
14339 Fortran 95 and later
14341 @item @emph{Class}:
14342 Transformational function
14344 @item @emph{Syntax}:
14345 @code{RESULT = TRIM(STRING)}
14347 @item @emph{Arguments}:
14348 @multitable @columnfractions .15 .70
14349 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
14352 @item @emph{Return value}:
14353 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
14354 less the number of trailing blanks.
14356 @item @emph{Example}:
14359 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
14360 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
14364 @item @emph{See also}:
14365 @ref{ADJUSTL}, @ref{ADJUSTR}
14371 @section @code{TTYNAM} --- Get the name of a terminal device.
14373 @cindex system, terminal
14376 @item @emph{Description}:
14377 Get the name of a terminal device. For more information,
14378 see @code{ttyname(3)}.
14380 This intrinsic is provided in both subroutine and function forms;
14381 however, only one form can be used in any given program unit.
14383 @item @emph{Standard}:
14386 @item @emph{Class}:
14387 Subroutine, function
14389 @item @emph{Syntax}:
14390 @multitable @columnfractions .80
14391 @item @code{CALL TTYNAM(UNIT, NAME)}
14392 @item @code{NAME = TTYNAM(UNIT)}
14395 @item @emph{Arguments}:
14396 @multitable @columnfractions .15 .70
14397 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
14398 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
14401 @item @emph{Example}:
14403 PROGRAM test_ttynam
14406 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
14411 @item @emph{See also}:
14418 @section @code{UBOUND} --- Upper dimension bounds of an array
14420 @cindex array, upper bound
14423 @item @emph{Description}:
14424 Returns the upper bounds of an array, or a single upper bound
14425 along the @var{DIM} dimension.
14426 @item @emph{Standard}:
14427 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
14429 @item @emph{Class}:
14432 @item @emph{Syntax}:
14433 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
14435 @item @emph{Arguments}:
14436 @multitable @columnfractions .15 .70
14437 @item @var{ARRAY} @tab Shall be an array, of any type.
14438 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
14439 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
14440 expression indicating the kind parameter of the result.
14443 @item @emph{Return value}:
14444 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14445 @var{KIND} is absent, the return value is of default integer kind.
14446 If @var{DIM} is absent, the result is an array of the upper bounds of
14447 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
14448 corresponding to the upper bound of the array along that dimension. If
14449 @var{ARRAY} is an expression rather than a whole array or array
14450 structure component, or if it has a zero extent along the relevant
14451 dimension, the upper bound is taken to be the number of elements along
14452 the relevant dimension.
14454 @item @emph{See also}:
14455 @ref{LBOUND}, @ref{LCOBOUND}
14461 @section @code{UCOBOUND} --- Upper codimension bounds of an array
14463 @cindex coarray, upper bound
14466 @item @emph{Description}:
14467 Returns the upper cobounds of a coarray, or a single upper cobound
14468 along the @var{DIM} codimension.
14469 @item @emph{Standard}:
14470 Fortran 2008 and later
14472 @item @emph{Class}:
14475 @item @emph{Syntax}:
14476 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
14478 @item @emph{Arguments}:
14479 @multitable @columnfractions .15 .70
14480 @item @var{ARRAY} @tab Shall be an coarray, of any type.
14481 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
14482 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
14483 expression indicating the kind parameter of the result.
14486 @item @emph{Return value}:
14487 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14488 @var{KIND} is absent, the return value is of default integer kind.
14489 If @var{DIM} is absent, the result is an array of the lower cobounds of
14490 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
14491 corresponding to the lower cobound of the array along that codimension.
14493 @item @emph{See also}:
14494 @ref{LCOBOUND}, @ref{LBOUND}
14500 @section @code{UMASK} --- Set the file creation mask
14502 @cindex file system, file creation mask
14505 @item @emph{Description}:
14506 Sets the file creation mask to @var{MASK}. If called as a function, it
14507 returns the old value. If called as a subroutine and argument @var{OLD}
14508 if it is supplied, it is set to the old value. See @code{umask(2)}.
14510 @item @emph{Standard}:
14513 @item @emph{Class}:
14514 Subroutine, function
14516 @item @emph{Syntax}:
14517 @multitable @columnfractions .80
14518 @item @code{CALL UMASK(MASK [, OLD])}
14519 @item @code{OLD = UMASK(MASK)}
14522 @item @emph{Arguments}:
14523 @multitable @columnfractions .15 .70
14524 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
14525 @item @var{OLD} @tab (Optional) Shall be a scalar of type
14534 @section @code{UNLINK} --- Remove a file from the file system
14536 @cindex file system, remove file
14539 @item @emph{Description}:
14540 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
14541 used to mark the end of the name in @var{PATH}; otherwise, trailing
14542 blanks in the file name are ignored. If the @var{STATUS} argument is
14543 supplied, it contains 0 on success or a nonzero error code upon return;
14544 see @code{unlink(2)}.
14546 This intrinsic is provided in both subroutine and function forms;
14547 however, only one form can be used in any given program unit.
14549 @item @emph{Standard}:
14552 @item @emph{Class}:
14553 Subroutine, function
14555 @item @emph{Syntax}:
14556 @multitable @columnfractions .80
14557 @item @code{CALL UNLINK(PATH [, STATUS])}
14558 @item @code{STATUS = UNLINK(PATH)}
14561 @item @emph{Arguments}:
14562 @multitable @columnfractions .15 .70
14563 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
14564 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
14567 @item @emph{See also}:
14568 @ref{LINK}, @ref{SYMLNK}
14574 @section @code{UNPACK} --- Unpack an array of rank one into an array
14576 @cindex array, unpacking
14577 @cindex array, increase dimension
14578 @cindex array, scatter elements
14581 @item @emph{Description}:
14582 Store the elements of @var{VECTOR} in an array of higher rank.
14584 @item @emph{Standard}:
14585 Fortran 95 and later
14587 @item @emph{Class}:
14588 Transformational function
14590 @item @emph{Syntax}:
14591 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
14593 @item @emph{Arguments}:
14594 @multitable @columnfractions .15 .70
14595 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
14596 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
14597 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
14598 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
14599 the same shape as @var{MASK}.
14602 @item @emph{Return value}:
14603 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
14604 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
14606 @item @emph{Example}:
14608 PROGRAM test_unpack
14609 integer :: vector(2) = (/1,1/)
14610 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
14611 integer :: field(2,2) = 0, unity(2,2)
14613 ! result: unity matrix
14614 unity = unpack(vector, reshape(mask, (/2,2/)), field)
14618 @item @emph{See also}:
14619 @ref{PACK}, @ref{SPREAD}
14625 @section @code{VERIFY} --- Scan a string for characters not a given set
14627 @cindex string, find missing set
14630 @item @emph{Description}:
14631 Verifies that all the characters in @var{STRING} belong to the set of
14632 characters in @var{SET}.
14634 If @var{BACK} is either absent or equals @code{FALSE}, this function
14635 returns the position of the leftmost character of @var{STRING} that is
14636 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost
14637 position is returned. If all characters of @var{STRING} are found in
14638 @var{SET}, the result is zero.
14640 @item @emph{Standard}:
14641 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
14643 @item @emph{Class}:
14646 @item @emph{Syntax}:
14647 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
14649 @item @emph{Arguments}:
14650 @multitable @columnfractions .15 .70
14651 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
14652 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
14653 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
14654 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
14655 expression indicating the kind parameter of the result.
14658 @item @emph{Return value}:
14659 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14660 @var{KIND} is absent, the return value is of default integer kind.
14662 @item @emph{Example}:
14664 PROGRAM test_verify
14665 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
14666 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
14667 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
14668 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
14669 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
14673 @item @emph{See also}:
14674 @ref{SCAN}, @ref{INDEX intrinsic}
14680 @section @code{XOR} --- Bitwise logical exclusive OR
14682 @cindex bitwise logical exclusive or
14683 @cindex logical exclusive or, bitwise
14686 @item @emph{Description}:
14687 Bitwise logical exclusive or.
14689 This intrinsic routine is provided for backwards compatibility with
14690 GNU Fortran 77. For integer arguments, programmers should consider
14691 the use of the @ref{IEOR} intrinsic and for logical arguments the
14692 @code{.NEQV.} operator, which are both defined by the Fortran standard.
14694 @item @emph{Standard}:
14697 @item @emph{Class}:
14700 @item @emph{Syntax}:
14701 @code{RESULT = XOR(I, J)}
14703 @item @emph{Arguments}:
14704 @multitable @columnfractions .15 .70
14705 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
14706 type or a scalar @code{LOGICAL} type or a boz-literal-constant.
14707 @item @var{J} @tab The type shall be the same as the type of @var{I} or
14708 a boz-literal-constant. @var{I} and @var{J} shall not both be
14709 boz-literal-constants. If either @var{I} and @var{J} is a
14710 boz-literal-constant, then the other argument must be a scalar @code{INTEGER}.
14713 @item @emph{Return value}:
14714 The return type is either a scalar @code{INTEGER} or a scalar
14715 @code{LOGICAL}. If the kind type parameters differ, then the
14716 smaller kind type is implicitly converted to larger kind, and the
14717 return has the larger kind. A boz-literal-constant is
14718 converted to an @code{INTEGER} with the kind type parameter of
14719 the other argument as-if a call to @ref{INT} occurred.
14721 @item @emph{Example}:
14724 LOGICAL :: T = .TRUE., F = .FALSE.
14726 DATA a / Z'F' /, b / Z'3' /
14728 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
14729 WRITE (*,*) XOR(a, b)
14733 @item @emph{See also}:
14734 Fortran 95 elemental function: @ref{IEOR}
14739 @node Intrinsic Modules
14740 @chapter Intrinsic Modules
14741 @cindex intrinsic Modules
14744 * ISO_FORTRAN_ENV::
14747 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
14748 * OpenACC Module OPENACC::
14751 @node ISO_FORTRAN_ENV
14752 @section @code{ISO_FORTRAN_ENV}
14754 @item @emph{Standard}:
14755 Fortran 2003 and later, except when otherwise noted
14758 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
14762 @item @code{ATOMIC_INT_KIND}:
14763 Default-kind integer constant to be used as kind parameter when defining
14764 integer variables used in atomic operations. (Fortran 2008 or later.)
14766 @item @code{ATOMIC_LOGICAL_KIND}:
14767 Default-kind integer constant to be used as kind parameter when defining
14768 logical variables used in atomic operations. (Fortran 2008 or later.)
14770 @item @code{CHARACTER_KINDS}:
14771 Default-kind integer constant array of rank one containing the supported kind
14772 parameters of the @code{CHARACTER} type. (Fortran 2008 or later.)
14774 @item @code{CHARACTER_STORAGE_SIZE}:
14775 Size in bits of the character storage unit.
14777 @item @code{ERROR_UNIT}:
14778 Identifies the preconnected unit used for error reporting.
14780 @item @code{FILE_STORAGE_SIZE}:
14781 Size in bits of the file-storage unit.
14783 @item @code{INPUT_UNIT}:
14784 Identifies the preconnected unit identified by the asterisk
14785 (@code{*}) in @code{READ} statement.
14787 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
14788 Kind type parameters to specify an INTEGER type with a storage
14789 size of 16, 32, and 64 bits. It is negative if a target platform
14790 does not support the particular kind. (Fortran 2008 or later.)
14792 @item @code{INTEGER_KINDS}:
14793 Default-kind integer constant array of rank one containing the supported kind
14794 parameters of the @code{INTEGER} type. (Fortran 2008 or later.)
14796 @item @code{IOSTAT_END}:
14797 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
14798 an input/output statement if an end-of-file condition occurred.
14800 @item @code{IOSTAT_EOR}:
14801 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
14802 an input/output statement if an end-of-record condition occurred.
14804 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
14805 Scalar default-integer constant, used by @code{INQUIRE} for the
14806 @code{IOSTAT=} specifier to denote an that a unit number identifies an
14807 internal unit. (Fortran 2008 or later.)
14809 @item @code{NUMERIC_STORAGE_SIZE}:
14810 The size in bits of the numeric storage unit.
14812 @item @code{LOGICAL_KINDS}:
14813 Default-kind integer constant array of rank one containing the supported kind
14814 parameters of the @code{LOGICAL} type. (Fortran 2008 or later.)
14816 @item @code{OUTPUT_UNIT}:
14817 Identifies the preconnected unit identified by the asterisk
14818 (@code{*}) in @code{WRITE} statement.
14820 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
14821 Kind type parameters to specify a REAL type with a storage
14822 size of 32, 64, and 128 bits. It is negative if a target platform
14823 does not support the particular kind. (Fortran 2008 or later.)
14825 @item @code{REAL_KINDS}:
14826 Default-kind integer constant array of rank one containing the supported kind
14827 parameters of the @code{REAL} type. (Fortran 2008 or later.)
14829 @item @code{STAT_LOCKED}:
14830 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
14831 denote that the lock variable is locked by the executing image. (Fortran 2008
14834 @item @code{STAT_LOCKED_OTHER_IMAGE}:
14835 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
14836 denote that the lock variable is locked by another image. (Fortran 2008 or
14839 @item @code{STAT_STOPPED_IMAGE}:
14840 Positive, scalar default-integer constant used as STAT= return value if the
14841 argument in the statement requires synchronisation with an image, which has
14842 initiated the termination of the execution. (Fortran 2008 or later.)
14844 @item @code{STAT_FAILED_IMAGE}:
14845 Positive, scalar default-integer constant used as STAT= return value if the
14846 argument in the statement requires communication with an image, which has
14847 is in the failed state. (TS 18508 or later.)
14849 @item @code{STAT_UNLOCKED}:
14850 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
14851 denote that the lock variable is unlocked. (Fortran 2008 or later.)
14854 The module provides the following derived type:
14857 @item @code{LOCK_TYPE}:
14858 Derived type with private components to be use with the @code{LOCK} and
14859 @code{UNLOCK} statement. A variable of its type has to be always declared
14860 as coarray and may not appear in a variable-definition context.
14861 (Fortran 2008 or later.)
14864 The module also provides the following intrinsic procedures:
14865 @ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}.
14869 @node ISO_C_BINDING
14870 @section @code{ISO_C_BINDING}
14872 @item @emph{Standard}:
14873 Fortran 2003 and later, GNU extensions
14876 The following intrinsic procedures are provided by the module; their
14877 definition can be found in the section Intrinsic Procedures of this
14881 @item @code{C_ASSOCIATED}
14882 @item @code{C_F_POINTER}
14883 @item @code{C_F_PROCPOINTER}
14884 @item @code{C_FUNLOC}
14886 @item @code{C_SIZEOF}
14888 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
14889 @c don't really know why.
14891 The @code{ISO_C_BINDING} module provides the following named constants of
14892 type default integer, which can be used as KIND type parameters.
14894 In addition to the integer named constants required by the Fortran 2003
14895 standard and @code{C_PTRDIFF_T} of TS 29113, GNU Fortran provides as an
14896 extension named constants for the 128-bit integer types supported by the
14897 C compiler: @code{C_INT128_T, C_INT_LEAST128_T, C_INT_FAST128_T}.
14898 Furthermore, if @code{__float128} is supported in C, the named constants
14899 @code{C_FLOAT128, C_FLOAT128_COMPLEX} are defined.
14901 @multitable @columnfractions .15 .35 .35 .35
14902 @item Fortran Type @tab Named constant @tab C type @tab Extension
14903 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
14904 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
14905 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
14906 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
14907 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
14908 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
14909 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
14910 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
14911 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
14912 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
14913 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
14914 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
14915 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
14916 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
14917 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
14918 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
14919 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
14920 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
14921 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
14922 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
14923 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
14924 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
14925 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
14926 @item @code{INTEGER}@tab @code{C_PTRDIFF_T} @tab @code{ptrdiff_t} @tab TS 29113
14927 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
14928 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
14929 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
14930 @item @code{REAL} @tab @code{C_FLOAT128} @tab @code{__float128} @tab Ext.
14931 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
14932 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
14933 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
14934 @item @code{REAL} @tab @code{C_FLOAT128_COMPLEX} @tab @code{__float128 _Complex} @tab Ext.
14935 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
14936 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
14939 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
14942 @multitable @columnfractions .20 .45 .15
14943 @item Name @tab C definition @tab Value
14944 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
14945 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
14946 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
14947 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
14948 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
14949 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
14950 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
14951 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
14954 Moreover, the following two named constants are defined:
14956 @multitable @columnfractions .20 .80
14957 @item Name @tab Type
14958 @item @code{C_NULL_PTR} @tab @code{C_PTR}
14959 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
14962 Both are equivalent to the value @code{NULL} in C.
14967 @section IEEE modules: @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
14969 @item @emph{Standard}:
14970 Fortran 2003 and later
14973 The @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
14974 intrinsic modules provide support for exceptions and IEEE arithmetic, as
14975 defined in Fortran 2003 and later standards, and the IEC 60559:1989 standard
14976 (@emph{Binary floating-point arithmetic for microprocessor systems}). These
14977 modules are only provided on the following supported platforms:
14980 @item i386 and x86_64 processors
14981 @item platforms which use the GNU C Library (glibc)
14982 @item platforms with support for SysV/386 routines for floating point
14983 interface (including Solaris and BSDs)
14984 @item platforms with the AIX OS
14987 For full compliance with the Fortran standards, code using the
14988 @code{IEEE_EXCEPTIONS} or @code{IEEE_ARITHMETIC} modules should be compiled
14989 with the following options: @code{-fno-unsafe-math-optimizations
14990 -frounding-math -fsignaling-nans}.
14994 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
14995 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
14997 @item @emph{Standard}:
14998 OpenMP Application Program Interface v4.5
15002 The OpenMP Fortran runtime library routines are provided both in
15003 a form of two Fortran 90 modules, named @code{OMP_LIB} and
15004 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
15005 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
15006 in the @ref{Top,,Introduction,libgomp,GNU Offloading and Multi
15007 Processing Runtime Library} manual,
15008 the named constants defined in the modules are listed
15011 For details refer to the actual
15012 @uref{http://www.openmp.org/wp-content/uploads/openmp-4.5.pdf,
15013 OpenMP Application Program Interface v4.5}.
15015 @code{OMP_LIB_KINDS} provides the following scalar default-integer
15019 @item @code{omp_lock_kind}
15020 @item @code{omp_nest_lock_kind}
15021 @item @code{omp_proc_bind_kind}
15022 @item @code{omp_sched_kind}
15025 @code{OMP_LIB} provides the scalar default-integer
15026 named constant @code{openmp_version} with a value of the form
15027 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
15028 of the OpenMP version; for OpenMP v4.5 the value is @code{201511}.
15030 The following scalar integer named constants of the
15031 kind @code{omp_sched_kind}:
15034 @item @code{omp_sched_static}
15035 @item @code{omp_sched_dynamic}
15036 @item @code{omp_sched_guided}
15037 @item @code{omp_sched_auto}
15040 And the following scalar integer named constants of the
15041 kind @code{omp_proc_bind_kind}:
15044 @item @code{omp_proc_bind_false}
15045 @item @code{omp_proc_bind_true}
15046 @item @code{omp_proc_bind_master}
15047 @item @code{omp_proc_bind_close}
15048 @item @code{omp_proc_bind_spread}
15053 @node OpenACC Module OPENACC
15054 @section OpenACC Module @code{OPENACC}
15056 @item @emph{Standard}:
15057 OpenACC Application Programming Interface v2.0
15061 The OpenACC Fortran runtime library routines are provided both in a
15062 form of a Fortran 90 module, named @code{OPENACC}, and in form of a
15063 Fortran @code{include} file named @file{openacc_lib.h}. The
15064 procedures provided by @code{OPENACC} can be found in the
15065 @ref{Top,,Introduction,libgomp,GNU Offloading and Multi Processing
15066 Runtime Library} manual, the named constants defined in the modules
15069 For details refer to the actual
15070 @uref{http://www.openacc.org/,
15071 OpenACC Application Programming Interface v2.0}.
15073 @code{OPENACC} provides the scalar default-integer
15074 named constant @code{openacc_version} with a value of the form
15075 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
15076 of the OpenACC version; for OpenACC v2.0 the value is @code{201306}.