2 Copyright (C) 2005-2018 Free Software Foundation, Inc.
3 This is part of the GNU Fortran manual.
4 For copying conditions, see the file gfortran.texi.
6 Permission is granted to copy, distribute and/or modify this document
7 under the terms of the GNU Free Documentation License, Version 1.3 or
8 any later version published by the Free Software Foundation; with the
9 Invariant Sections being ``Funding Free Software'', the Front-Cover
10 Texts being (a) (see below), and with the Back-Cover Texts being (b)
11 (see below). A copy of the license is included in the gfdl(7) man page.
14 Some basic guidelines for editing this document:
16 (1) The intrinsic procedures are to be listed in alphabetical order.
17 (2) The generic name is to be used.
18 (3) The specific names are included in the function index and in a
19 table at the end of the node (See ABS entry).
20 (4) Try to maintain the same style for each entry.
26 \gdef\acosd{\mathop{\rm acosd}\nolimits}
27 \gdef\asind{\mathop{\rm asind}\nolimits}
28 \gdef\atand{\mathop{\rm atand}\nolimits}
29 \gdef\acos{\mathop{\rm acos}\nolimits}
30 \gdef\asin{\mathop{\rm asin}\nolimits}
31 \gdef\atan{\mathop{\rm atan}\nolimits}
32 \gdef\acosh{\mathop{\rm acosh}\nolimits}
33 \gdef\asinh{\mathop{\rm asinh}\nolimits}
34 \gdef\atanh{\mathop{\rm atanh}\nolimits}
35 \gdef\cosd{\mathop{\rm cosd}\nolimits}
39 @node Intrinsic Procedures
40 @chapter Intrinsic Procedures
41 @cindex intrinsic procedures
44 * Introduction: Introduction to Intrinsics
45 * @code{ABORT}: ABORT, Abort the program
46 * @code{ABS}: ABS, Absolute value
47 * @code{ACCESS}: ACCESS, Checks file access modes
48 * @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence
49 * @code{ACOS}: ACOS, Arccosine function
50 * @code{ACOSD}: ACOSD, Arccosine function, degrees
51 * @code{ACOSH}: ACOSH, Inverse hyperbolic cosine function
52 * @code{ADJUSTL}: ADJUSTL, Left adjust a string
53 * @code{ADJUSTR}: ADJUSTR, Right adjust a string
54 * @code{AIMAG}: AIMAG, Imaginary part of complex number
55 * @code{AINT}: AINT, Truncate to a whole number
56 * @code{ALARM}: ALARM, Set an alarm clock
57 * @code{ALL}: ALL, Determine if all values are true
58 * @code{ALLOCATED}: ALLOCATED, Status of allocatable entity
59 * @code{AND}: AND, Bitwise logical AND
60 * @code{ANINT}: ANINT, Nearest whole number
61 * @code{ANY}: ANY, Determine if any values are true
62 * @code{ASIN}: ASIN, Arcsine function
63 * @code{ASIND}: ASIND, Arcsine function, degrees
64 * @code{ASINH}: ASINH, Inverse hyperbolic sine function
65 * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair
66 * @code{ATAN}: ATAN, Arctangent function
67 * @code{ATAND}: ATAND, Arctangent function, degrees
68 * @code{ATAN2}: ATAN2, Arctangent function
69 * @code{ATAN2D}: ATAN2D, Arctangent function, degrees
70 * @code{ATANH}: ATANH, Inverse hyperbolic tangent function
71 * @code{ATOMIC_ADD}: ATOMIC_ADD, Atomic ADD operation
72 * @code{ATOMIC_AND}: ATOMIC_AND, Atomic bitwise AND operation
73 * @code{ATOMIC_CAS}: ATOMIC_CAS, Atomic compare and swap
74 * @code{ATOMIC_DEFINE}: ATOMIC_DEFINE, Setting a variable atomically
75 * @code{ATOMIC_FETCH_ADD}: ATOMIC_FETCH_ADD, Atomic ADD operation with prior fetch
76 * @code{ATOMIC_FETCH_AND}: ATOMIC_FETCH_AND, Atomic bitwise AND operation with prior fetch
77 * @code{ATOMIC_FETCH_OR}: ATOMIC_FETCH_OR, Atomic bitwise OR operation with prior fetch
78 * @code{ATOMIC_FETCH_XOR}: ATOMIC_FETCH_XOR, Atomic bitwise XOR operation with prior fetch
79 * @code{ATOMIC_OR}: ATOMIC_OR, Atomic bitwise OR operation
80 * @code{ATOMIC_REF}: ATOMIC_REF, Obtaining the value of a variable atomically
81 * @code{ATOMIC_XOR}: ATOMIC_XOR, Atomic bitwise OR operation
82 * @code{BACKTRACE}: BACKTRACE, Show a backtrace
83 * @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0
84 * @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1
85 * @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind
86 * @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0
87 * @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1
88 * @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind
89 * @code{BGE}: BGE, Bitwise greater than or equal to
90 * @code{BGT}: BGT, Bitwise greater than
91 * @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function
92 * @code{BLE}: BLE, Bitwise less than or equal to
93 * @code{BLT}: BLT, Bitwise less than
94 * @code{BTEST}: BTEST, Bit test function
95 * @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer
96 * @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer
97 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
98 * @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure
99 * @code{C_LOC}: C_LOC, Obtain the C address of an object
100 * @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression
101 * @code{CEILING}: CEILING, Integer ceiling function
102 * @code{CHAR}: CHAR, Integer-to-character conversion function
103 * @code{CHDIR}: CHDIR, Change working directory
104 * @code{CHMOD}: CHMOD, Change access permissions of files
105 * @code{CMPLX}: CMPLX, Complex conversion function
106 * @code{CO_BROADCAST}: CO_BROADCAST, Copy a value to all images the current set of images
107 * @code{CO_MAX}: CO_MAX, Maximal value on the current set of images
108 * @code{CO_MIN}: CO_MIN, Minimal value on the current set of images
109 * @code{CO_REDUCE}: CO_REDUCE, Reduction of values on the current set of images
110 * @code{CO_SUM}: CO_SUM, Sum of values on the current set of images
111 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
112 * @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler
113 * @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string
114 * @code{COMPLEX}: COMPLEX, Complex conversion function
115 * @code{CONJG}: CONJG, Complex conjugate function
116 * @code{COS}: COS, Cosine function
117 * @code{COSD}: COSD, Cosine function, degrees
118 * @code{COSH}: COSH, Hyperbolic cosine function
119 * @code{COTAN}: COTAN, Cotangent function
120 * @code{COTAND}: COTAND, Cotangent function, degrees
121 * @code{COUNT}: COUNT, Count occurrences of TRUE in an array
122 * @code{CPU_TIME}: CPU_TIME, CPU time subroutine
123 * @code{CSHIFT}: CSHIFT, Circular shift elements of an array
124 * @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string
125 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
126 * @code{DBLE}: DBLE, Double precision conversion function
127 * @code{DCMPLX}: DCMPLX, Double complex conversion function
128 * @code{DIGITS}: DIGITS, Significant digits function
129 * @code{DIM}: DIM, Positive difference
130 * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
131 * @code{DPROD}: DPROD, Double product function
132 * @code{DREAL}: DREAL, Double real part function
133 * @code{DSHIFTL}: DSHIFTL, Combined left shift
134 * @code{DSHIFTR}: DSHIFTR, Combined right shift
135 * @code{DTIME}: DTIME, Execution time subroutine (or function)
136 * @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array
137 * @code{EPSILON}: EPSILON, Epsilon function
138 * @code{ERF}: ERF, Error function
139 * @code{ERFC}: ERFC, Complementary error function
140 * @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function
141 * @code{ETIME}: ETIME, Execution time subroutine (or function)
142 * @code{EVENT_QUERY}: EVENT_QUERY, Query whether a coarray event has occurred
143 * @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command
144 * @code{EXIT}: EXIT, Exit the program with status.
145 * @code{EXP}: EXP, Exponential function
146 * @code{EXPONENT}: EXPONENT, Exponent function
147 * @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF, Query dynamic type for extension
148 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
149 * @code{FGET}: FGET, Read a single character in stream mode from stdin
150 * @code{FGETC}: FGETC, Read a single character in stream mode
151 * @code{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_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value
199 * @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value
200 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
201 * @code{ISHFT}: ISHFT, Shift bits
202 * @code{ISHFTC}: ISHFTC, Shift bits circularly
203 * @code{ISNAN}: ISNAN, Tests for a NaN
204 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
205 * @code{KILL}: KILL, Send a signal to a process
206 * @code{KIND}: KIND, Kind of an entity
207 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
208 * @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array
209 * @code{LEADZ}: LEADZ, Number of leading zero bits of an integer
210 * @code{LEN}: LEN, Length of a character entity
211 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
212 * @code{LGE}: LGE, Lexical greater than or equal
213 * @code{LGT}: LGT, Lexical greater than
214 * @code{LINK}: LINK, Create a hard link
215 * @code{LLE}: LLE, Lexical less than or equal
216 * @code{LLT}: LLT, Lexical less than
217 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
218 * @code{LOC}: LOC, Returns the address of a variable
219 * @code{LOG}: LOG, Logarithm function
220 * @code{LOG10}: LOG10, Base 10 logarithm function
221 * @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
222 * @code{LOGICAL}: LOGICAL, Convert to logical type
223 * @code{LONG}: LONG, Convert to integer type
224 * @code{LSHIFT}: LSHIFT, Left shift bits
225 * @code{LSTAT}: LSTAT, Get file status
226 * @code{LTIME}: LTIME, Convert time to local time info
227 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
228 * @code{MASKL}: MASKL, Left justified mask
229 * @code{MASKR}: MASKR, Right justified mask
230 * @code{MATMUL}: MATMUL, matrix multiplication
231 * @code{MAX}: MAX, Maximum value of an argument list
232 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
233 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
234 * @code{MAXVAL}: MAXVAL, Maximum value of an array
235 * @code{MCLOCK}: MCLOCK, Time function
236 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
237 * @code{MERGE}: MERGE, Merge arrays
238 * @code{MERGE_BITS}: MERGE_BITS, Merge of bits under mask
239 * @code{MIN}: MIN, Minimum value of an argument list
240 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
241 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
242 * @code{MINVAL}: MINVAL, Minimum value of an array
243 * @code{MOD}: MOD, Remainder function
244 * @code{MODULO}: MODULO, Modulo function
245 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
246 * @code{MVBITS}: MVBITS, Move bits from one integer to another
247 * @code{NEAREST}: NEAREST, Nearest representable number
248 * @code{NEW_LINE}: NEW_LINE, New line character
249 * @code{NINT}: NINT, Nearest whole number
250 * @code{NORM2}: NORM2, Euclidean vector norm
251 * @code{NOT}: NOT, Logical negation
252 * @code{NULL}: NULL, Function that returns an disassociated pointer
253 * @code{NUM_IMAGES}: NUM_IMAGES, Number of images
254 * @code{OR}: OR, Bitwise logical OR
255 * @code{PACK}: PACK, Pack an array into an array of rank one
256 * @code{PARITY}: PARITY, Reduction with exclusive OR
257 * @code{PERROR}: PERROR, Print system error message
258 * @code{POPCNT}: POPCNT, Number of bits set
259 * @code{POPPAR}: POPPAR, Parity of the number of bits set
260 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
261 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
262 * @code{PRODUCT}: PRODUCT, Product of array elements
263 * @code{RADIX}: RADIX, Base of a data model
264 * @code{RAN}: RAN, Real pseudo-random number
265 * @code{RAND}: RAND, Real pseudo-random number
266 * @code{RANDOM_INIT}: RANDOM_INIT, Initialize pseudo-random number generator
267 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
268 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
269 * @code{RANGE}: RANGE, Decimal exponent range
270 * @code{RANK} : RANK, Rank of a data object
271 * @code{REAL}: REAL, Convert to real type
272 * @code{RENAME}: RENAME, Rename a file
273 * @code{REPEAT}: REPEAT, Repeated string concatenation
274 * @code{RESHAPE}: RESHAPE, Function to reshape an array
275 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
276 * @code{RSHIFT}: RSHIFT, Right shift bits
277 * @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality
278 * @code{SCALE}: SCALE, Scale a real value
279 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
280 * @code{SECNDS}: SECNDS, Time function
281 * @code{SECOND}: SECOND, CPU time function
282 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind
283 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
284 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
285 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
286 * @code{SHAPE}: SHAPE, Determine the shape of an array
287 * @code{SHIFTA}: SHIFTA, Right shift with fill
288 * @code{SHIFTL}: SHIFTL, Left shift
289 * @code{SHIFTR}: SHIFTR, Right shift
290 * @code{SIGN}: SIGN, Sign copying function
291 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
292 * @code{SIN}: SIN, Sine function
293 * @code{SIND}: SIND, Sine function, degrees
294 * @code{SINH}: SINH, Hyperbolic sine function
295 * @code{SIZE}: SIZE, Function to determine the size of an array
296 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
297 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
298 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
299 * @code{SPREAD}: SPREAD, Add a dimension to an array
300 * @code{SQRT}: SQRT, Square-root function
301 * @code{SRAND}: SRAND, Reinitialize the random number generator
302 * @code{STAT}: STAT, Get file status
303 * @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits
304 * @code{SUM}: SUM, Sum of array elements
305 * @code{SYMLNK}: SYMLNK, Create a symbolic link
306 * @code{SYSTEM}: SYSTEM, Execute a shell command
307 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
308 * @code{TAN}: TAN, Tangent function
309 * @code{TAND}: TAND, Tangent function, degrees
310 * @code{TANH}: TANH, Hyperbolic tangent function
311 * @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image
312 * @code{TIME}: TIME, Time function
313 * @code{TIME8}: TIME8, Time function (64-bit)
314 * @code{TINY}: TINY, Smallest positive number of a real kind
315 * @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer
316 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
317 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
318 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
319 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
320 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
321 * @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array
322 * @code{UMASK}: UMASK, Set the file creation mask
323 * @code{UNLINK}: UNLINK, Remove a file from the file system
324 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
325 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
326 * @code{XOR}: XOR, Bitwise logical exclusive or
329 @node Introduction to Intrinsics
330 @section Introduction to intrinsic procedures
332 The intrinsic procedures provided by GNU Fortran include all of the
333 intrinsic procedures required by the Fortran 95 standard, a set of
334 intrinsic procedures for backwards compatibility with G77, and a
335 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
336 standards. Any conflict between a description here and a description in
337 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
338 2008 standard is unintentional, and the standard(s) should be considered
341 The enumeration of the @code{KIND} type parameter is processor defined in
342 the Fortran 95 standard. GNU Fortran defines the default integer type and
343 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
344 respectively. The standard mandates that both data types shall have
345 another kind, which have more precision. On typical target architectures
346 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
347 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
348 In the description of generic intrinsic procedures, the kind type parameter
349 will be specified by @code{KIND=*}, and in the description of specific
350 names for an intrinsic procedure the kind type parameter will be explicitly
351 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
352 brevity the optional @code{KIND=} syntax will be omitted.
354 Many of the intrinsic procedures take one or more optional arguments.
355 This document follows the convention used in the Fortran 95 standard,
356 and denotes such arguments by square brackets.
358 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
359 which can be used to restrict the set of intrinsic procedures to a
360 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
361 option, and so all intrinsic procedures described here are accepted. There
362 is one caveat. For a select group of intrinsic procedures, @command{g77}
363 implemented both a function and a subroutine. Both classes
364 have been implemented in @command{gfortran} for backwards compatibility
365 with @command{g77}. It is noted here that these functions and subroutines
366 cannot be intermixed in a given subprogram. In the descriptions that follow,
367 the applicable standard for each intrinsic procedure is noted.
372 @section @code{ABORT} --- Abort the program
374 @cindex program termination, with core dump
375 @cindex terminate program, with core dump
379 @item @emph{Description}:
380 @code{ABORT} causes immediate termination of the program. On operating
381 systems that support a core dump, @code{ABORT} will produce a core dump.
382 It will also print a backtrace, unless @code{-fno-backtrace} is given.
384 @item @emph{Standard}:
393 @item @emph{Return value}:
396 @item @emph{Example}:
399 integer :: i = 1, j = 2
400 if (i /= j) call abort
401 end program test_abort
404 @item @emph{See also}:
405 @ref{EXIT}, @ref{KILL}, @ref{BACKTRACE}
412 @section @code{ABS} --- Absolute value
423 @cindex absolute value
426 @item @emph{Description}:
427 @code{ABS(A)} computes the absolute value of @code{A}.
429 @item @emph{Standard}:
430 Fortran 77 and later, has overloads that are GNU extensions
436 @code{RESULT = ABS(A)}
438 @item @emph{Arguments}:
439 @multitable @columnfractions .15 .70
440 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
441 @code{REAL}, or @code{COMPLEX}.
444 @item @emph{Return value}:
445 The return value is of the same type and
446 kind as the argument except the return value is @code{REAL} for a
447 @code{COMPLEX} argument.
449 @item @emph{Example}:
454 complex :: z = (-1.e0,0.e0)
461 @item @emph{Specific names}:
462 @multitable @columnfractions .20 .20 .20 .25
463 @item Name @tab Argument @tab Return type @tab Standard
464 @item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
465 @item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
466 @item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
467 @item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
468 @item @code{BABS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
469 @item @code{IIABS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
470 @item @code{JIABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
471 @item @code{KIABS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
472 @item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
473 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
480 @section @code{ACCESS} --- Checks file access modes
482 @cindex file system, access mode
485 @item @emph{Description}:
486 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
487 exists, is readable, writable or executable. Except for the
488 executable check, @code{ACCESS} can be replaced by
489 Fortran 95's @code{INQUIRE}.
491 @item @emph{Standard}:
498 @code{RESULT = ACCESS(NAME, MODE)}
500 @item @emph{Arguments}:
501 @multitable @columnfractions .15 .70
502 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
503 file name. Tailing blank are ignored unless the character @code{achar(0)}
504 is present, then all characters up to and excluding @code{achar(0)} are
506 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
507 file access mode, may be any concatenation of @code{"r"} (readable),
508 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
512 @item @emph{Return value}:
513 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
514 accessible in the given mode; otherwise or if an invalid argument
515 has been given for @code{MODE} the value @code{1} is returned.
517 @item @emph{Example}:
521 character(len=*), parameter :: file = 'test.dat'
522 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
523 if(access(file,' ') == 0) print *, trim(file),' is exists'
524 if(access(file,'r') == 0) print *, trim(file),' is readable'
525 if(access(file,'w') == 0) print *, trim(file),' is writable'
526 if(access(file,'x') == 0) print *, trim(file),' is executable'
527 if(access(file2,'rwx') == 0) &
528 print *, trim(file2),' is readable, writable and executable'
529 end program access_test
531 @item @emph{Specific names}:
532 @item @emph{See also}:
539 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
541 @cindex @acronym{ASCII} collating sequence
542 @cindex collating sequence, @acronym{ASCII}
545 @item @emph{Description}:
546 @code{ACHAR(I)} returns the character located at position @code{I}
547 in the @acronym{ASCII} collating sequence.
549 @item @emph{Standard}:
550 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
556 @code{RESULT = ACHAR(I [, KIND])}
558 @item @emph{Arguments}:
559 @multitable @columnfractions .15 .70
560 @item @var{I} @tab The type shall be @code{INTEGER}.
561 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
562 expression indicating the kind parameter of the result.
565 @item @emph{Return value}:
566 The return value is of type @code{CHARACTER} with a length of one.
567 If the @var{KIND} argument is present, the return value is of the
568 specified kind and of the default kind otherwise.
570 @item @emph{Example}:
575 end program test_achar
579 See @ref{ICHAR} for a discussion of converting between numerical values
580 and formatted string representations.
582 @item @emph{See also}:
583 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
590 @section @code{ACOS} --- Arccosine function
593 @cindex trigonometric function, cosine, inverse
594 @cindex cosine, inverse
597 @item @emph{Description}:
598 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
600 @item @emph{Standard}:
601 Fortran 77 and later, for a complex argument Fortran 2008 or later
607 @code{RESULT = ACOS(X)}
609 @item @emph{Arguments}:
610 @multitable @columnfractions .15 .70
611 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
612 less than or equal to one - or the type shall be @code{COMPLEX}.
615 @item @emph{Return value}:
616 The return value is of the same type and kind as @var{X}.
617 The real part of the result is in radians and lies in the range
618 @math{0 \leq \Re \acos(x) \leq \pi}.
620 @item @emph{Example}:
623 real(8) :: x = 0.866_8
625 end program test_acos
628 @item @emph{Specific names}:
629 @multitable @columnfractions .20 .20 .20 .25
630 @item Name @tab Argument @tab Return type @tab Standard
631 @item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
632 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
635 @item @emph{See also}:
636 Inverse function: @ref{COS}
637 Degrees function: @ref{ACOSD}
644 @section @code{ACOSD} --- Arccosine function, degrees
647 @cindex trigonometric function, cosine, inverse, degrees
648 @cindex cosine, inverse, degrees
651 @item @emph{Description}:
652 @code{ACOSD(X)} computes the arccosine of @var{X} in degrees (inverse of
655 This function is for compatibility only and should be avoided in favor of
656 standard constructs wherever possible.
658 @item @emph{Standard}:
659 GNU Extension, enabled with @option{-fdec-math}
665 @code{RESULT = ACOSD(X)}
667 @item @emph{Arguments}:
668 @multitable @columnfractions .15 .70
669 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
670 less than or equal to one - or the type shall be @code{COMPLEX}.
673 @item @emph{Return value}:
674 The return value is of the same type and kind as @var{X}.
675 The real part of the result is in degrees and lies in the range
676 @math{0 \leq \Re \acos(x) \leq 180}.
678 @item @emph{Example}:
681 real(8) :: x = 0.866_8
683 end program test_acosd
686 @item @emph{Specific names}:
687 @multitable @columnfractions .20 .20 .20 .25
688 @item Name @tab Argument @tab Return type @tab Standard
689 @item @code{ACOSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
690 @item @code{DACOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
693 @item @emph{See also}:
694 Inverse function: @ref{COSD}
695 Radians function: @ref{ACOS}
702 @section @code{ACOSH} --- Inverse hyperbolic cosine function
705 @cindex area hyperbolic cosine
706 @cindex inverse hyperbolic cosine
707 @cindex hyperbolic function, cosine, inverse
708 @cindex cosine, hyperbolic, inverse
711 @item @emph{Description}:
712 @code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
714 @item @emph{Standard}:
715 Fortran 2008 and later
721 @code{RESULT = ACOSH(X)}
723 @item @emph{Arguments}:
724 @multitable @columnfractions .15 .70
725 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
728 @item @emph{Return value}:
729 The return value has the same type and kind as @var{X}. If @var{X} is
730 complex, the imaginary part of the result is in radians and lies between
731 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
733 @item @emph{Example}:
736 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
741 @item @emph{Specific names}:
742 @multitable @columnfractions .20 .20 .20 .25
743 @item Name @tab Argument @tab Return type @tab Standard
744 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
747 @item @emph{See also}:
748 Inverse function: @ref{COSH}
754 @section @code{ADJUSTL} --- Left adjust a string
756 @cindex string, adjust left
757 @cindex adjust string
760 @item @emph{Description}:
761 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
762 Spaces are inserted at the end of the string as needed.
764 @item @emph{Standard}:
771 @code{RESULT = ADJUSTL(STRING)}
773 @item @emph{Arguments}:
774 @multitable @columnfractions .15 .70
775 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
778 @item @emph{Return value}:
779 The return value is of type @code{CHARACTER} and of the same kind as
780 @var{STRING} where leading spaces are removed and the same number of
781 spaces are inserted on the end of @var{STRING}.
783 @item @emph{Example}:
786 character(len=20) :: str = ' gfortran'
789 end program test_adjustl
792 @item @emph{See also}:
793 @ref{ADJUSTR}, @ref{TRIM}
799 @section @code{ADJUSTR} --- Right adjust a string
801 @cindex string, adjust right
802 @cindex adjust string
805 @item @emph{Description}:
806 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
807 Spaces are inserted at the start of the string as needed.
809 @item @emph{Standard}:
816 @code{RESULT = ADJUSTR(STRING)}
818 @item @emph{Arguments}:
819 @multitable @columnfractions .15 .70
820 @item @var{STR} @tab The type shall be @code{CHARACTER}.
823 @item @emph{Return value}:
824 The return value is of type @code{CHARACTER} and of the same kind as
825 @var{STRING} where trailing spaces are removed and the same number of
826 spaces are inserted at the start of @var{STRING}.
828 @item @emph{Example}:
831 character(len=20) :: str = 'gfortran'
834 end program test_adjustr
837 @item @emph{See also}:
838 @ref{ADJUSTL}, @ref{TRIM}
844 @section @code{AIMAG} --- Imaginary part of complex number
849 @cindex complex numbers, imaginary part
852 @item @emph{Description}:
853 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
854 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
855 for compatibility with @command{g77}, and their use in new code is
856 strongly discouraged.
858 @item @emph{Standard}:
859 Fortran 77 and later, has overloads that are GNU extensions
865 @code{RESULT = AIMAG(Z)}
867 @item @emph{Arguments}:
868 @multitable @columnfractions .15 .70
869 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
872 @item @emph{Return value}:
873 The return value is of type @code{REAL} with the
874 kind type parameter of the argument.
876 @item @emph{Example}:
881 z4 = cmplx(1.e0_4, 0.e0_4)
882 z8 = cmplx(0.e0_8, 1.e0_8)
883 print *, aimag(z4), dimag(z8)
884 end program test_aimag
887 @item @emph{Specific names}:
888 @multitable @columnfractions .20 .20 .20 .25
889 @item Name @tab Argument @tab Return type @tab Standard
890 @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
891 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
892 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
893 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
900 @section @code{AINT} --- Truncate to a whole number
904 @cindex rounding, floor
907 @item @emph{Description}:
908 @code{AINT(A [, KIND])} truncates its argument to a whole number.
910 @item @emph{Standard}:
917 @code{RESULT = AINT(A [, KIND])}
919 @item @emph{Arguments}:
920 @multitable @columnfractions .15 .70
921 @item @var{A} @tab The type of the argument shall be @code{REAL}.
922 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
923 expression indicating the kind parameter of the result.
926 @item @emph{Return value}:
927 The return value is of type @code{REAL} with the kind type parameter of the
928 argument if the optional @var{KIND} is absent; otherwise, the kind
929 type parameter will be given by @var{KIND}. If the magnitude of
930 @var{X} is less than one, @code{AINT(X)} returns zero. If the
931 magnitude is equal to or greater than one then it returns the largest
932 whole number that does not exceed its magnitude. The sign is the same
933 as the sign of @var{X}.
935 @item @emph{Example}:
942 print *, aint(x4), dint(x8)
944 end program test_aint
947 @item @emph{Specific names}:
948 @multitable @columnfractions .20 .20 .20 .25
949 @item Name @tab Argument @tab Return type @tab Standard
950 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
951 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
958 @section @code{ALARM} --- Execute a routine after a given delay
960 @cindex delayed execution
963 @item @emph{Description}:
964 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
965 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
966 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
967 supplied, it will be returned with the number of seconds remaining until
968 any previously scheduled alarm was due to be delivered, or zero if there
969 was no previously scheduled alarm.
971 @item @emph{Standard}:
978 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
980 @item @emph{Arguments}:
981 @multitable @columnfractions .15 .70
982 @item @var{SECONDS} @tab The type of the argument shall be a scalar
983 @code{INTEGER}. It is @code{INTENT(IN)}.
984 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
985 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
986 values may be either @code{SIG_IGN=1} to ignore the alarm generated
987 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
988 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
989 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
992 @item @emph{Example}:
995 external handler_print
997 call alarm (3, handler_print, i)
1000 end program test_alarm
1002 This will cause the external routine @var{handler_print} to be called
1009 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
1011 @cindex array, apply condition
1012 @cindex array, condition testing
1015 @item @emph{Description}:
1016 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
1017 in the array along dimension @var{DIM}.
1019 @item @emph{Standard}:
1020 Fortran 95 and later
1023 Transformational function
1025 @item @emph{Syntax}:
1026 @code{RESULT = ALL(MASK [, DIM])}
1028 @item @emph{Arguments}:
1029 @multitable @columnfractions .15 .70
1030 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1031 it shall not be scalar.
1032 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1033 with a value that lies between one and the rank of @var{MASK}.
1036 @item @emph{Return value}:
1037 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
1038 the kind type parameter is the same as the kind type parameter of
1039 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
1040 an array with the rank of @var{MASK} minus 1. The shape is determined from
1041 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1045 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
1046 It also is true if @var{MASK} has zero size; otherwise, it is false.
1048 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
1049 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
1050 is determined by applying @code{ALL} to the array sections.
1053 @item @emph{Example}:
1057 l = all((/.true., .true., .true./))
1062 integer a(2,3), b(2,3)
1066 print *, all(a .eq. b, 1)
1067 print *, all(a .eq. b, 2)
1068 end subroutine section
1069 end program test_all
1076 @section @code{ALLOCATED} --- Status of an allocatable entity
1078 @cindex allocation, status
1081 @item @emph{Description}:
1082 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
1083 status of @var{ARRAY} and @var{SCALAR}, respectively.
1085 @item @emph{Standard}:
1086 Fortran 95 and later. Note, the @code{SCALAR=} keyword and allocatable
1087 scalar entities are available in Fortran 2003 and later.
1092 @item @emph{Syntax}:
1093 @multitable @columnfractions .80
1094 @item @code{RESULT = ALLOCATED(ARRAY)}
1095 @item @code{RESULT = ALLOCATED(SCALAR)}
1098 @item @emph{Arguments}:
1099 @multitable @columnfractions .15 .70
1100 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
1101 @item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar.
1104 @item @emph{Return value}:
1105 The return value is a scalar @code{LOGICAL} with the default logical
1106 kind type parameter. If the argument is allocated, then the result is
1107 @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
1109 @item @emph{Example}:
1111 program test_allocated
1113 real(4), allocatable :: x(:)
1114 if (.not. allocated(x)) allocate(x(i))
1115 end program test_allocated
1122 @section @code{AND} --- Bitwise logical AND
1124 @cindex bitwise logical and
1125 @cindex logical and, bitwise
1128 @item @emph{Description}:
1129 Bitwise logical @code{AND}.
1131 This intrinsic routine is provided for backwards compatibility with
1132 GNU Fortran 77. For integer arguments, programmers should consider
1133 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1135 @item @emph{Standard}:
1141 @item @emph{Syntax}:
1142 @code{RESULT = AND(I, J)}
1144 @item @emph{Arguments}:
1145 @multitable @columnfractions .15 .70
1146 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1147 type or a scalar @code{LOGICAL} type.
1148 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1151 @item @emph{Return value}:
1152 The return type is either a scalar @code{INTEGER} or a scalar
1153 @code{LOGICAL}. If the kind type parameters differ, then the
1154 smaller kind type is implicitly converted to larger kind, and the
1155 return has the larger kind.
1157 @item @emph{Example}:
1160 LOGICAL :: T = .TRUE., F = .FALSE.
1162 DATA a / Z'F' /, b / Z'3' /
1164 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1165 WRITE (*,*) AND(a, b)
1169 @item @emph{See also}:
1170 Fortran 95 elemental function: @ref{IAND}
1176 @section @code{ANINT} --- Nearest whole number
1180 @cindex rounding, ceiling
1183 @item @emph{Description}:
1184 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1186 @item @emph{Standard}:
1187 Fortran 77 and later
1192 @item @emph{Syntax}:
1193 @code{RESULT = ANINT(A [, KIND])}
1195 @item @emph{Arguments}:
1196 @multitable @columnfractions .15 .70
1197 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1198 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1199 expression indicating the kind parameter of the result.
1202 @item @emph{Return value}:
1203 The return value is of type real with the kind type parameter of the
1204 argument if the optional @var{KIND} is absent; otherwise, the kind
1205 type parameter will be given by @var{KIND}. If @var{A} is greater than
1206 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1207 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1209 @item @emph{Example}:
1216 print *, anint(x4), dnint(x8)
1218 end program test_anint
1221 @item @emph{Specific names}:
1222 @multitable @columnfractions .20 .20 .20 .25
1223 @item Name @tab Argument @tab Return type @tab Standard
1224 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
1225 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1232 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1234 @cindex array, apply condition
1235 @cindex array, condition testing
1238 @item @emph{Description}:
1239 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1240 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1242 @item @emph{Standard}:
1243 Fortran 95 and later
1246 Transformational function
1248 @item @emph{Syntax}:
1249 @code{RESULT = ANY(MASK [, DIM])}
1251 @item @emph{Arguments}:
1252 @multitable @columnfractions .15 .70
1253 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1254 it shall not be scalar.
1255 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1256 with a value that lies between one and the rank of @var{MASK}.
1259 @item @emph{Return value}:
1260 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1261 the kind type parameter is the same as the kind type parameter of
1262 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1263 an array with the rank of @var{MASK} minus 1. The shape is determined from
1264 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1268 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1269 otherwise, it is false. It also is false if @var{MASK} has zero size.
1271 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1272 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1273 is determined by applying @code{ANY} to the array sections.
1276 @item @emph{Example}:
1280 l = any((/.true., .true., .true./))
1285 integer a(2,3), b(2,3)
1289 print *, any(a .eq. b, 1)
1290 print *, any(a .eq. b, 2)
1291 end subroutine section
1292 end program test_any
1299 @section @code{ASIN} --- Arcsine function
1302 @cindex trigonometric function, sine, inverse
1303 @cindex sine, inverse
1306 @item @emph{Description}:
1307 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1309 @item @emph{Standard}:
1310 Fortran 77 and later, for a complex argument Fortran 2008 or later
1315 @item @emph{Syntax}:
1316 @code{RESULT = ASIN(X)}
1318 @item @emph{Arguments}:
1319 @multitable @columnfractions .15 .70
1320 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1321 less than or equal to one - or be @code{COMPLEX}.
1324 @item @emph{Return value}:
1325 The return value is of the same type and kind as @var{X}.
1326 The real part of the result is in radians and lies in the range
1327 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1329 @item @emph{Example}:
1332 real(8) :: x = 0.866_8
1334 end program test_asin
1337 @item @emph{Specific names}:
1338 @multitable @columnfractions .20 .20 .20 .25
1339 @item Name @tab Argument @tab Return type @tab Standard
1340 @item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1341 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1344 @item @emph{See also}:
1345 Inverse function: @ref{SIN}
1346 Degrees function: @ref{ASIND}
1353 @section @code{ASIND} --- Arcsine function, degrees
1356 @cindex trigonometric function, sine, inverse, degrees
1357 @cindex sine, inverse, degrees
1360 @item @emph{Description}:
1361 @code{ASIND(X)} computes the arcsine of its @var{X} in degrees (inverse of
1364 This function is for compatibility only and should be avoided in favor of
1365 standard constructs wherever possible.
1367 @item @emph{Standard}:
1368 GNU Extension, enabled with @option{-fdec-math}.
1373 @item @emph{Syntax}:
1374 @code{RESULT = ASIND(X)}
1376 @item @emph{Arguments}:
1377 @multitable @columnfractions .15 .70
1378 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1379 less than or equal to one - or be @code{COMPLEX}.
1382 @item @emph{Return value}:
1383 The return value is of the same type and kind as @var{X}.
1384 The real part of the result is in degrees and lies in the range
1385 @math{-90 \leq \Re \asin(x) \leq 90}.
1387 @item @emph{Example}:
1390 real(8) :: x = 0.866_8
1392 end program test_asind
1395 @item @emph{Specific names}:
1396 @multitable @columnfractions .20 .20 .20 .25
1397 @item Name @tab Argument @tab Return type @tab Standard
1398 @item @code{ASIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
1399 @item @code{DASIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
1402 @item @emph{See also}:
1403 Inverse function: @ref{SIND}
1404 Radians function: @ref{ASIN}
1411 @section @code{ASINH} --- Inverse hyperbolic sine function
1414 @cindex area hyperbolic sine
1415 @cindex inverse hyperbolic sine
1416 @cindex hyperbolic function, sine, inverse
1417 @cindex sine, hyperbolic, inverse
1420 @item @emph{Description}:
1421 @code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
1423 @item @emph{Standard}:
1424 Fortran 2008 and later
1429 @item @emph{Syntax}:
1430 @code{RESULT = ASINH(X)}
1432 @item @emph{Arguments}:
1433 @multitable @columnfractions .15 .70
1434 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1437 @item @emph{Return value}:
1438 The return value is of the same type and kind as @var{X}. If @var{X} is
1439 complex, the imaginary part of the result is in radians and lies between
1440 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1442 @item @emph{Example}:
1445 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1446 WRITE (*,*) ASINH(x)
1450 @item @emph{Specific names}:
1451 @multitable @columnfractions .20 .20 .20 .25
1452 @item Name @tab Argument @tab Return type @tab Standard
1453 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1456 @item @emph{See also}:
1457 Inverse function: @ref{SINH}
1463 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1465 @cindex pointer, status
1466 @cindex association status
1469 @item @emph{Description}:
1470 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1471 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1473 @item @emph{Standard}:
1474 Fortran 95 and later
1479 @item @emph{Syntax}:
1480 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1482 @item @emph{Arguments}:
1483 @multitable @columnfractions .15 .70
1484 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1485 and it can be of any type.
1486 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1487 a target. It must have the same type, kind type parameter, and
1488 array rank as @var{POINTER}.
1490 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1493 @item @emph{Return value}:
1494 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1495 There are several cases:
1497 @item (A) When the optional @var{TARGET} is not present then
1498 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1499 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1500 @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
1501 disassociated, the result is false.
1502 @item (C) If @var{TARGET} is present and an array target, the result is true if
1503 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1504 are arrays whose elements are not zero-sized storage sequences, and
1505 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1507 As in case(B), the result is false, if @var{POINTER} is disassociated.
1508 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1509 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1510 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1512 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1513 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1514 target associated with @var{POINTER} and the target associated with @var{TARGET}
1515 have the same shape, are not zero-sized arrays, are arrays whose elements are
1516 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1517 the same storage units in array element order.
1518 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1521 @item @emph{Example}:
1523 program test_associated
1525 real, target :: tgt(2) = (/1., 2./)
1526 real, pointer :: ptr(:)
1528 if (associated(ptr) .eqv. .false.) call abort
1529 if (associated(ptr,tgt) .eqv. .false.) call abort
1530 end program test_associated
1533 @item @emph{See also}:
1540 @section @code{ATAN} --- Arctangent function
1543 @cindex trigonometric function, tangent, inverse
1544 @cindex tangent, inverse
1547 @item @emph{Description}:
1548 @code{ATAN(X)} computes the arctangent of @var{X}.
1550 @item @emph{Standard}:
1551 Fortran 77 and later, for a complex argument and for two arguments
1552 Fortran 2008 or later
1557 @item @emph{Syntax}:
1558 @multitable @columnfractions .80
1559 @item @code{RESULT = ATAN(X)}
1560 @item @code{RESULT = ATAN(Y, X)}
1563 @item @emph{Arguments}:
1564 @multitable @columnfractions .15 .70
1565 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1566 if @var{Y} is present, @var{X} shall be REAL.
1567 @item @var{Y} shall be of the same type and kind as @var{X}.
1570 @item @emph{Return value}:
1571 The return value is of the same type and kind as @var{X}.
1572 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1573 Otherwise, it the arcus tangent of @var{X}, where the real part of
1574 the result is in radians and lies in the range
1575 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1577 @item @emph{Example}:
1580 real(8) :: x = 2.866_8
1582 end program test_atan
1585 @item @emph{Specific names}:
1586 @multitable @columnfractions .20 .20 .20 .25
1587 @item Name @tab Argument @tab Return type @tab Standard
1588 @item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1589 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1592 @item @emph{See also}:
1593 Inverse function: @ref{TAN}
1594 Degrees function: @ref{ATAND}
1601 @section @code{ATAND} --- Arctangent function, degrees
1604 @cindex trigonometric function, tangent, inverse, degrees
1605 @cindex tangent, inverse, degrees
1608 @item @emph{Description}:
1609 @code{ATAND(X)} computes the arctangent of @var{X} in degrees (inverse of
1612 This function is for compatibility only and should be avoided in favor of
1613 standard constructs wherever possible.
1615 @item @emph{Standard}:
1616 GNU Extension, enabled with @option{-fdec-math}.
1621 @item @emph{Syntax}:
1622 @multitable @columnfractions .80
1623 @item @code{RESULT = ATAND(X)}
1624 @item @code{RESULT = ATAND(Y, X)}
1627 @item @emph{Arguments}:
1628 @multitable @columnfractions .15 .70
1629 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1630 if @var{Y} is present, @var{X} shall be REAL.
1631 @item @var{Y} shall be of the same type and kind as @var{X}.
1634 @item @emph{Return value}:
1635 The return value is of the same type and kind as @var{X}.
1636 If @var{Y} is present, the result is identical to @code{ATAND2(Y,X)}.
1637 Otherwise, it is the arcus tangent of @var{X}, where the real part of
1638 the result is in degrees and lies in the range
1639 @math{-90 \leq \Re \atand(x) \leq 90}.
1641 @item @emph{Example}:
1644 real(8) :: x = 2.866_8
1646 end program test_atand
1649 @item @emph{Specific names}:
1650 @multitable @columnfractions .20 .20 .20 .25
1651 @item Name @tab Argument @tab Return type @tab Standard
1652 @item @code{ATAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
1653 @item @code{DATAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
1656 @item @emph{See also}:
1657 Inverse function: @ref{TAND}
1658 Radians function: @ref{ATAN}
1665 @section @code{ATAN2} --- Arctangent function
1668 @cindex trigonometric function, tangent, inverse
1669 @cindex tangent, inverse
1672 @item @emph{Description}:
1673 @code{ATAN2(Y, X)} computes the principal value of the argument
1674 function of the complex number @math{X + i Y}. This function can
1675 be used to transform from Cartesian into polar coordinates and
1676 allows to determine the angle in the correct quadrant.
1678 @item @emph{Standard}:
1679 Fortran 77 and later
1684 @item @emph{Syntax}:
1685 @code{RESULT = ATAN2(Y, X)}
1687 @item @emph{Arguments}:
1688 @multitable @columnfractions .15 .70
1689 @item @var{Y} @tab The type shall be @code{REAL}.
1690 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1691 If @var{Y} is zero, then @var{X} must be nonzero.
1694 @item @emph{Return value}:
1695 The return value has the same type and kind type parameter as @var{Y}. It
1696 is the principal value of the complex number @math{X + i Y}. If @var{X}
1697 is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1698 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1699 the return value is zero if @var{X} is strictly positive, @math{\pi} if
1700 @var{X} is negative and @var{Y} is positive zero (or the processor does
1701 not handle signed zeros), and @math{-\pi} if @var{X} is negative and
1702 @var{Y} is negative zero. Finally, if @var{X} is zero, then the
1703 magnitude of the result is @math{\pi/2}.
1705 @item @emph{Example}:
1708 real(4) :: x = 1.e0_4, y = 0.5e0_4
1710 end program test_atan2
1713 @item @emph{Specific names}:
1714 @multitable @columnfractions .20 .20 .20 .25
1715 @item Name @tab Argument @tab Return type @tab Standard
1716 @item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1717 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1720 @item @emph{See also}:
1722 Degrees function: @ref{ATAN2D}
1729 @section @code{ATAN2D} --- Arctangent function, degrees
1732 @cindex trigonometric function, tangent, inverse, degrees
1733 @cindex tangent, inverse, degrees
1736 @item @emph{Description}:
1737 @code{ATAN2D(Y, X)} computes the principal value of the argument
1738 function of the complex number @math{X + i Y} in degrees. This function can
1739 be used to transform from Cartesian into polar coordinates and
1740 allows to determine the angle in the correct quadrant.
1742 This function is for compatibility only and should be avoided in favor of
1743 standard constructs wherever possible.
1745 @item @emph{Standard}:
1746 GNU Extension, enabled with @option{-fdec-math}.
1751 @item @emph{Syntax}:
1752 @code{RESULT = ATAN2D(Y, X)}
1754 @item @emph{Arguments}:
1755 @multitable @columnfractions .15 .70
1756 @item @var{Y} @tab The type shall be @code{REAL}.
1757 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1758 If @var{Y} is zero, then @var{X} must be nonzero.
1761 @item @emph{Return value}:
1762 The return value has the same type and kind type parameter as @var{Y}. It
1763 is the principal value of the complex number @math{X + i Y}. If @var{X}
1764 is nonzero, then it lies in the range @math{-180 \le \atan (x) \leq 180}.
1765 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1766 the return value is zero if @var{X} is strictly positive, @math{180} if
1767 @var{X} is negative and @var{Y} is positive zero (or the processor does
1768 not handle signed zeros), and @math{-180} if @var{X} is negative and
1769 @var{Y} is negative zero. Finally, if @var{X} is zero, then the
1770 magnitude of the result is @math{90}.
1772 @item @emph{Example}:
1775 real(4) :: x = 1.e0_4, y = 0.5e0_4
1777 end program test_atan2d
1780 @item @emph{Specific names}:
1781 @multitable @columnfractions .20 .20 .20 .25
1782 @item Name @tab Argument @tab Return type @tab Standard
1783 @item @code{ATAN2D(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab GNU Extension
1784 @item @code{DATAN2D(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab GNU Extension
1787 @item @emph{See also}:
1789 Radians function: @ref{ATAN2}
1796 @section @code{ATANH} --- Inverse hyperbolic tangent function
1799 @cindex area hyperbolic tangent
1800 @cindex inverse hyperbolic tangent
1801 @cindex hyperbolic function, tangent, inverse
1802 @cindex tangent, hyperbolic, inverse
1805 @item @emph{Description}:
1806 @code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
1808 @item @emph{Standard}:
1809 Fortran 2008 and later
1814 @item @emph{Syntax}:
1815 @code{RESULT = ATANH(X)}
1817 @item @emph{Arguments}:
1818 @multitable @columnfractions .15 .70
1819 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1822 @item @emph{Return value}:
1823 The return value has same type and kind as @var{X}. If @var{X} is
1824 complex, the imaginary part of the result is in radians and lies between
1825 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1827 @item @emph{Example}:
1830 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1831 WRITE (*,*) ATANH(x)
1835 @item @emph{Specific names}:
1836 @multitable @columnfractions .20 .20 .20 .25
1837 @item Name @tab Argument @tab Return type @tab Standard
1838 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1841 @item @emph{See also}:
1842 Inverse function: @ref{TANH}
1848 @section @code{ATOMIC_ADD} --- Atomic ADD operation
1850 @cindex Atomic subroutine, add
1853 @item @emph{Description}:
1854 @code{ATOMIC_ADD(ATOM, VALUE)} atomically adds the value of @var{VAR} to the
1855 variable @var{ATOM}. When @var{STAT} is present and the invocation was
1856 successful, it is assigned the value 0. If it is present and the invocation
1857 has failed, it is assigned a positive value; in particular, for a coindexed
1858 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1859 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1860 failed, the value @code{STAT_FAILED_IMAGE}.
1862 @item @emph{Standard}:
1868 @item @emph{Syntax}:
1869 @code{CALL ATOMIC_ADD (ATOM, VALUE [, STAT])}
1871 @item @emph{Arguments}:
1872 @multitable @columnfractions .15 .70
1873 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1874 type with @code{ATOMIC_INT_KIND} kind.
1875 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1876 is different, the value is converted to the kind of @var{ATOM}.
1877 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1880 @item @emph{Example}:
1884 integer(atomic_int_kind) :: atom[*]
1885 call atomic_add (atom[1], this_image())
1889 @item @emph{See also}:
1890 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_ADD}, @ref{ISO_FORTRAN_ENV},
1891 @ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
1898 @section @code{ATOMIC_AND} --- Atomic bitwise AND operation
1900 @cindex Atomic subroutine, AND
1903 @item @emph{Description}:
1904 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
1905 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
1906 and the invocation was successful, it is assigned the value 0. If it is present
1907 and the invocation has failed, it is assigned a positive value; in particular,
1908 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
1909 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
1910 image has failed, the value @code{STAT_FAILED_IMAGE}.
1912 @item @emph{Standard}:
1918 @item @emph{Syntax}:
1919 @code{CALL ATOMIC_AND (ATOM, VALUE [, STAT])}
1921 @item @emph{Arguments}:
1922 @multitable @columnfractions .15 .70
1923 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1924 type with @code{ATOMIC_INT_KIND} kind.
1925 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1926 is different, the value is converted to the kind of @var{ATOM}.
1927 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1930 @item @emph{Example}:
1934 integer(atomic_int_kind) :: atom[*]
1935 call atomic_and (atom[1], int(b'10100011101'))
1939 @item @emph{See also}:
1940 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_AND}, @ref{ISO_FORTRAN_ENV},
1941 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
1947 @section @code{ATOMIC_CAS} --- Atomic compare and swap
1948 @fnindex ATOMIC_DEFINE
1949 @cindex Atomic subroutine, compare and swap
1952 @item @emph{Description}:
1953 @code{ATOMIC_CAS} compares the variable @var{ATOM} with the value of
1954 @var{COMPARE}; if the value is the same, @var{ATOM} is set to the value
1955 of @var{NEW}. Additionally, @var{OLD} is set to the value of @var{ATOM}
1956 that was used for the comparison. When @var{STAT} is present and the invocation
1957 was successful, it is assigned the value 0. If it is present and the invocation
1958 has failed, it is assigned a positive value; in particular, for a coindexed
1959 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1960 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1961 failed, the value @code{STAT_FAILED_IMAGE}.
1963 @item @emph{Standard}:
1969 @item @emph{Syntax}:
1970 @code{CALL ATOMIC_CAS (ATOM, OLD, COMPARE, NEW [, STAT])}
1972 @item @emph{Arguments}:
1973 @multitable @columnfractions .15 .70
1974 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
1975 type with @code{ATOMIC_INT_KIND} kind or logical type with
1976 @code{ATOMIC_LOGICAL_KIND} kind.
1977 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1978 @item @var{COMPARE} @tab Scalar variable of the same type and kind as
1980 @item @var{NEW} @tab Scalar variable of the same type as @var{ATOM}. If kind
1981 is different, the value is converted to the kind of @var{ATOM}.
1982 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1985 @item @emph{Example}:
1989 logical(atomic_logical_kind) :: atom[*], prev
1990 call atomic_cas (atom[1], prev, .false., .true.))
1994 @item @emph{See also}:
1995 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_REF}, @ref{ISO_FORTRAN_ENV}
2001 @section @code{ATOMIC_DEFINE} --- Setting a variable atomically
2002 @fnindex ATOMIC_DEFINE
2003 @cindex Atomic subroutine, define
2006 @item @emph{Description}:
2007 @code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value
2008 @var{VALUE} atomically. When @var{STAT} is present and the invocation was
2009 successful, it is assigned the value 0. If it is present and the invocation
2010 has failed, it is assigned a positive value; in particular, for a coindexed
2011 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2012 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2013 failed, the value @code{STAT_FAILED_IMAGE}.
2015 @item @emph{Standard}:
2016 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
2021 @item @emph{Syntax}:
2022 @code{CALL ATOMIC_DEFINE (ATOM, VALUE [, STAT])}
2024 @item @emph{Arguments}:
2025 @multitable @columnfractions .15 .70
2026 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
2027 type with @code{ATOMIC_INT_KIND} kind or logical type with
2028 @code{ATOMIC_LOGICAL_KIND} kind.
2030 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2031 is different, the value is converted to the kind of @var{ATOM}.
2032 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2035 @item @emph{Example}:
2039 integer(atomic_int_kind) :: atom[*]
2040 call atomic_define (atom[1], this_image())
2044 @item @emph{See also}:
2045 @ref{ATOMIC_REF}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV},
2046 @ref{ATOMIC_ADD}, @ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
2051 @node ATOMIC_FETCH_ADD
2052 @section @code{ATOMIC_FETCH_ADD} --- Atomic ADD operation with prior fetch
2053 @fnindex ATOMIC_FETCH_ADD
2054 @cindex Atomic subroutine, ADD with fetch
2057 @item @emph{Description}:
2058 @code{ATOMIC_FETCH_ADD(ATOM, VALUE, OLD)} atomically stores the value of
2059 @var{ATOM} in @var{OLD} and adds the value of @var{VAR} to the
2060 variable @var{ATOM}. When @var{STAT} is present and the invocation was
2061 successful, it is assigned the value 0. If it is present and the invocation
2062 has failed, it is assigned a positive value; in particular, for a coindexed
2063 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2064 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2065 failed, the value @code{STAT_FAILED_IMAGE}.
2067 @item @emph{Standard}:
2073 @item @emph{Syntax}:
2074 @code{CALL ATOMIC_FETCH_ADD (ATOM, VALUE, old [, STAT])}
2076 @item @emph{Arguments}:
2077 @multitable @columnfractions .15 .70
2078 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2079 type with @code{ATOMIC_INT_KIND} kind.
2080 @code{ATOMIC_LOGICAL_KIND} kind.
2082 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2083 is different, the value is converted to the kind of @var{ATOM}.
2084 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2085 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2088 @item @emph{Example}:
2092 integer(atomic_int_kind) :: atom[*], old
2093 call atomic_add (atom[1], this_image(), old)
2097 @item @emph{See also}:
2098 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_ADD}, @ref{ISO_FORTRAN_ENV},
2099 @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR}
2104 @node ATOMIC_FETCH_AND
2105 @section @code{ATOMIC_FETCH_AND} --- Atomic bitwise AND operation with prior fetch
2106 @fnindex ATOMIC_FETCH_AND
2107 @cindex Atomic subroutine, AND with fetch
2110 @item @emph{Description}:
2111 @code{ATOMIC_AND(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2112 @var{OLD} and defines @var{ATOM} with the bitwise AND between the values of
2113 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
2114 successful, it is assigned the value 0. If it is present and the invocation has
2115 failed, it is assigned a positive value; in particular, for a coindexed
2116 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2117 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2118 failed, the value @code{STAT_FAILED_IMAGE}.
2120 @item @emph{Standard}:
2126 @item @emph{Syntax}:
2127 @code{CALL ATOMIC_FETCH_AND (ATOM, VALUE, OLD [, STAT])}
2129 @item @emph{Arguments}:
2130 @multitable @columnfractions .15 .70
2131 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2132 type with @code{ATOMIC_INT_KIND} kind.
2133 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2134 is different, the value is converted to the kind of @var{ATOM}.
2135 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2136 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2139 @item @emph{Example}:
2143 integer(atomic_int_kind) :: atom[*], old
2144 call atomic_fetch_and (atom[1], int(b'10100011101'), old)
2148 @item @emph{See also}:
2149 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_AND}, @ref{ISO_FORTRAN_ENV},
2150 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR}
2155 @node ATOMIC_FETCH_OR
2156 @section @code{ATOMIC_FETCH_OR} --- Atomic bitwise OR operation with prior fetch
2157 @fnindex ATOMIC_FETCH_OR
2158 @cindex Atomic subroutine, OR with fetch
2161 @item @emph{Description}:
2162 @code{ATOMIC_OR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2163 @var{OLD} and defines @var{ATOM} with the bitwise OR between the values of
2164 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
2165 successful, it is assigned the value 0. If it is present and the invocation has
2166 failed, it is assigned a positive value; in particular, for a coindexed
2167 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2168 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2169 failed, the value @code{STAT_FAILED_IMAGE}.
2171 @item @emph{Standard}:
2177 @item @emph{Syntax}:
2178 @code{CALL ATOMIC_FETCH_OR (ATOM, VALUE, OLD [, STAT])}
2180 @item @emph{Arguments}:
2181 @multitable @columnfractions .15 .70
2182 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2183 type with @code{ATOMIC_INT_KIND} kind.
2184 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2185 is different, the value is converted to the kind of @var{ATOM}.
2186 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2187 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2190 @item @emph{Example}:
2194 integer(atomic_int_kind) :: atom[*], old
2195 call atomic_fetch_or (atom[1], int(b'10100011101'), old)
2199 @item @emph{See also}:
2200 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_OR}, @ref{ISO_FORTRAN_ENV},
2201 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_XOR}
2206 @node ATOMIC_FETCH_XOR
2207 @section @code{ATOMIC_FETCH_XOR} --- Atomic bitwise XOR operation with prior fetch
2208 @fnindex ATOMIC_FETCH_XOR
2209 @cindex Atomic subroutine, XOR with fetch
2212 @item @emph{Description}:
2213 @code{ATOMIC_XOR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
2214 @var{OLD} and defines @var{ATOM} with the bitwise XOR between the values of
2215 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invocation was
2216 successful, it is assigned the value 0. If it is present and the invocation has
2217 failed, it is assigned a positive value; in particular, for a coindexed
2218 @var{ATOM}, if the remote image has stopped, it is assigned the value of
2219 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
2220 failed, the value @code{STAT_FAILED_IMAGE}.
2222 @item @emph{Standard}:
2228 @item @emph{Syntax}:
2229 @code{CALL ATOMIC_FETCH_XOR (ATOM, VALUE, OLD [, STAT])}
2231 @item @emph{Arguments}:
2232 @multitable @columnfractions .15 .70
2233 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2234 type with @code{ATOMIC_INT_KIND} kind.
2235 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2236 is different, the value is converted to the kind of @var{ATOM}.
2237 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
2238 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2241 @item @emph{Example}:
2245 integer(atomic_int_kind) :: atom[*], old
2246 call atomic_fetch_xor (atom[1], int(b'10100011101'), old)
2250 @item @emph{See also}:
2251 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_XOR}, @ref{ISO_FORTRAN_ENV},
2252 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}
2258 @section @code{ATOMIC_OR} --- Atomic bitwise OR operation
2260 @cindex Atomic subroutine, OR
2263 @item @emph{Description}:
2264 @code{ATOMIC_OR(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
2265 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
2266 and the invocation was successful, it is assigned the value 0. If it is present
2267 and the invocation has failed, it is assigned a positive value; in particular,
2268 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
2269 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
2270 image has failed, the value @code{STAT_FAILED_IMAGE}.
2272 @item @emph{Standard}:
2278 @item @emph{Syntax}:
2279 @code{CALL ATOMIC_OR (ATOM, VALUE [, STAT])}
2281 @item @emph{Arguments}:
2282 @multitable @columnfractions .15 .70
2283 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2284 type with @code{ATOMIC_INT_KIND} kind.
2285 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2286 is different, the value is converted to the kind of @var{ATOM}.
2287 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2290 @item @emph{Example}:
2294 integer(atomic_int_kind) :: atom[*]
2295 call atomic_or (atom[1], int(b'10100011101'))
2299 @item @emph{See also}:
2300 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_OR}, @ref{ISO_FORTRAN_ENV},
2301 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
2307 @section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically
2309 @cindex Atomic subroutine, reference
2312 @item @emph{Description}:
2313 @code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the
2314 variable @var{ATOM} to @var{VALUE}. When @var{STAT} is present and the
2315 invocation was successful, it is assigned the value 0. If it is present and the
2316 invocation has failed, it is assigned a positive value; in particular, for a
2317 coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value
2318 of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image
2319 has failed, the value @code{STAT_FAILED_IMAGE}.
2322 @item @emph{Standard}:
2323 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
2328 @item @emph{Syntax}:
2329 @code{CALL ATOMIC_REF(VALUE, ATOM [, STAT])}
2331 @item @emph{Arguments}:
2332 @multitable @columnfractions .15 .70
2333 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2334 is different, the value is converted to the kind of @var{ATOM}.
2335 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
2336 type with @code{ATOMIC_INT_KIND} kind or logical type with
2337 @code{ATOMIC_LOGICAL_KIND} kind.
2338 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2341 @item @emph{Example}:
2345 logical(atomic_logical_kind) :: atom[*]
2347 call atomic_ref (atom, .false.)
2349 call atomic_ref (atom, val)
2356 @item @emph{See also}:
2357 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV},
2358 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR},
2359 @ref{ATOMIC_FETCH_XOR}
2364 @section @code{ATOMIC_XOR} --- Atomic bitwise OR operation
2366 @cindex Atomic subroutine, XOR
2369 @item @emph{Description}:
2370 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
2371 XOR between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
2372 and the invocation was successful, it is assigned the value 0. If it is present
2373 and the invocation has failed, it is assigned a positive value; in particular,
2374 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
2375 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
2376 image has failed, the value @code{STAT_FAILED_IMAGE}.
2378 @item @emph{Standard}:
2384 @item @emph{Syntax}:
2385 @code{CALL ATOMIC_XOR (ATOM, VALUE [, STAT])}
2387 @item @emph{Arguments}:
2388 @multitable @columnfractions .15 .70
2389 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2390 type with @code{ATOMIC_INT_KIND} kind.
2391 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2392 is different, the value is converted to the kind of @var{ATOM}.
2393 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2396 @item @emph{Example}:
2400 integer(atomic_int_kind) :: atom[*]
2401 call atomic_xor (atom[1], int(b'10100011101'))
2405 @item @emph{See also}:
2406 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_XOR}, @ref{ISO_FORTRAN_ENV},
2407 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
2412 @section @code{BACKTRACE} --- Show a backtrace
2417 @item @emph{Description}:
2418 @code{BACKTRACE} shows a backtrace at an arbitrary place in user code. Program
2419 execution continues normally afterwards. The backtrace information is printed
2420 to the unit corresponding to @code{ERROR_UNIT} in @code{ISO_FORTRAN_ENV}.
2422 @item @emph{Standard}:
2428 @item @emph{Syntax}:
2429 @code{CALL BACKTRACE}
2431 @item @emph{Arguments}:
2434 @item @emph{See also}:
2441 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
2445 @cindex Bessel function, first kind
2448 @item @emph{Description}:
2449 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
2450 order 0 of @var{X}. This function is available under the name
2451 @code{BESJ0} as a GNU extension.
2453 @item @emph{Standard}:
2454 Fortran 2008 and later
2459 @item @emph{Syntax}:
2460 @code{RESULT = BESSEL_J0(X)}
2462 @item @emph{Arguments}:
2463 @multitable @columnfractions .15 .70
2464 @item @var{X} @tab The type shall be @code{REAL}.
2467 @item @emph{Return value}:
2468 The return value is of type @code{REAL} and lies in the
2469 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
2472 @item @emph{Example}:
2475 real(8) :: x = 0.0_8
2477 end program test_besj0
2480 @item @emph{Specific names}:
2481 @multitable @columnfractions .20 .20 .20 .25
2482 @item Name @tab Argument @tab Return type @tab Standard
2483 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2490 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
2494 @cindex Bessel function, first kind
2497 @item @emph{Description}:
2498 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
2499 order 1 of @var{X}. This function is available under the name
2500 @code{BESJ1} as a GNU extension.
2502 @item @emph{Standard}:
2508 @item @emph{Syntax}:
2509 @code{RESULT = BESSEL_J1(X)}
2511 @item @emph{Arguments}:
2512 @multitable @columnfractions .15 .70
2513 @item @var{X} @tab The type shall be @code{REAL}.
2516 @item @emph{Return value}:
2517 The return value is of type @code{REAL} and lies in the
2518 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
2521 @item @emph{Example}:
2524 real(8) :: x = 1.0_8
2526 end program test_besj1
2529 @item @emph{Specific names}:
2530 @multitable @columnfractions .20 .20 .20 .25
2531 @item Name @tab Argument @tab Return type @tab Standard
2532 @item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2539 @section @code{BESSEL_JN} --- Bessel function of the first kind
2543 @cindex Bessel function, first kind
2546 @item @emph{Description}:
2547 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
2548 order @var{N} of @var{X}. This function is available under the name
2549 @code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays,
2550 their ranks and shapes shall conform.
2552 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
2553 of the first kind of the orders @var{N1} to @var{N2}.
2555 @item @emph{Standard}:
2556 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2559 Elemental function, except for the transformational function
2560 @code{BESSEL_JN(N1, N2, X)}
2562 @item @emph{Syntax}:
2563 @multitable @columnfractions .80
2564 @item @code{RESULT = BESSEL_JN(N, X)}
2565 @item @code{RESULT = BESSEL_JN(N1, N2, X)}
2568 @item @emph{Arguments}:
2569 @multitable @columnfractions .15 .70
2570 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
2571 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2572 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2573 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2574 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
2577 @item @emph{Return value}:
2578 The return value is a scalar of type @code{REAL}. It has the same
2582 The transformational function uses a recurrence algorithm which might,
2583 for some values of @var{X}, lead to different results than calls to
2584 the elemental function.
2586 @item @emph{Example}:
2589 real(8) :: x = 1.0_8
2591 end program test_besjn
2594 @item @emph{Specific names}:
2595 @multitable @columnfractions .20 .20 .20 .25
2596 @item Name @tab Argument @tab Return type @tab Standard
2597 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2598 @item @tab @code{REAL(8) X} @tab @tab
2605 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
2609 @cindex Bessel function, second kind
2612 @item @emph{Description}:
2613 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
2614 order 0 of @var{X}. This function is available under the name
2615 @code{BESY0} as a GNU extension.
2617 @item @emph{Standard}:
2618 Fortran 2008 and later
2623 @item @emph{Syntax}:
2624 @code{RESULT = BESSEL_Y0(X)}
2626 @item @emph{Arguments}:
2627 @multitable @columnfractions .15 .70
2628 @item @var{X} @tab The type shall be @code{REAL}.
2631 @item @emph{Return value}:
2632 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2634 @item @emph{Example}:
2637 real(8) :: x = 0.0_8
2639 end program test_besy0
2642 @item @emph{Specific names}:
2643 @multitable @columnfractions .20 .20 .20 .25
2644 @item Name @tab Argument @tab Return type @tab Standard
2645 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2652 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
2656 @cindex Bessel function, second kind
2659 @item @emph{Description}:
2660 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
2661 order 1 of @var{X}. This function is available under the name
2662 @code{BESY1} as a GNU extension.
2664 @item @emph{Standard}:
2665 Fortran 2008 and later
2670 @item @emph{Syntax}:
2671 @code{RESULT = BESSEL_Y1(X)}
2673 @item @emph{Arguments}:
2674 @multitable @columnfractions .15 .70
2675 @item @var{X} @tab The type shall be @code{REAL}.
2678 @item @emph{Return value}:
2679 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2681 @item @emph{Example}:
2684 real(8) :: x = 1.0_8
2686 end program test_besy1
2689 @item @emph{Specific names}:
2690 @multitable @columnfractions .20 .20 .20 .25
2691 @item Name @tab Argument @tab Return type @tab Standard
2692 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2699 @section @code{BESSEL_YN} --- Bessel function of the second kind
2703 @cindex Bessel function, second kind
2706 @item @emph{Description}:
2707 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
2708 order @var{N} of @var{X}. This function is available under the name
2709 @code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays,
2710 their ranks and shapes shall conform.
2712 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
2713 of the first kind of the orders @var{N1} to @var{N2}.
2715 @item @emph{Standard}:
2716 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2719 Elemental function, except for the transformational function
2720 @code{BESSEL_YN(N1, N2, X)}
2722 @item @emph{Syntax}:
2723 @multitable @columnfractions .80
2724 @item @code{RESULT = BESSEL_YN(N, X)}
2725 @item @code{RESULT = BESSEL_YN(N1, N2, X)}
2728 @item @emph{Arguments}:
2729 @multitable @columnfractions .15 .70
2730 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} .
2731 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2732 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2733 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2734 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
2737 @item @emph{Return value}:
2738 The return value is a scalar of type @code{REAL}. It has the same
2742 The transformational function uses a recurrence algorithm which might,
2743 for some values of @var{X}, lead to different results than calls to
2744 the elemental function.
2746 @item @emph{Example}:
2749 real(8) :: x = 1.0_8
2751 end program test_besyn
2754 @item @emph{Specific names}:
2755 @multitable @columnfractions .20 .20 .20 .25
2756 @item Name @tab Argument @tab Return type @tab Standard
2757 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2758 @item @tab @code{REAL(8) X} @tab @tab
2765 @section @code{BGE} --- Bitwise greater than or equal to
2767 @cindex bitwise comparison
2770 @item @emph{Description}:
2771 Determines whether an integral is a bitwise greater than or equal to
2774 @item @emph{Standard}:
2775 Fortran 2008 and later
2780 @item @emph{Syntax}:
2781 @code{RESULT = BGE(I, J)}
2783 @item @emph{Arguments}:
2784 @multitable @columnfractions .15 .70
2785 @item @var{I} @tab Shall be of @code{INTEGER} type.
2786 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2790 @item @emph{Return value}:
2791 The return value is of type @code{LOGICAL} and of the default kind.
2793 @item @emph{See also}:
2794 @ref{BGT}, @ref{BLE}, @ref{BLT}
2800 @section @code{BGT} --- Bitwise greater than
2802 @cindex bitwise comparison
2805 @item @emph{Description}:
2806 Determines whether an integral is a bitwise greater than another.
2808 @item @emph{Standard}:
2809 Fortran 2008 and later
2814 @item @emph{Syntax}:
2815 @code{RESULT = BGT(I, J)}
2817 @item @emph{Arguments}:
2818 @multitable @columnfractions .15 .70
2819 @item @var{I} @tab Shall be of @code{INTEGER} type.
2820 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2824 @item @emph{Return value}:
2825 The return value is of type @code{LOGICAL} and of the default kind.
2827 @item @emph{See also}:
2828 @ref{BGE}, @ref{BLE}, @ref{BLT}
2834 @section @code{BIT_SIZE} --- Bit size inquiry function
2836 @cindex bits, number of
2837 @cindex size of a variable, in bits
2840 @item @emph{Description}:
2841 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
2842 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
2843 independent of the actual value of @var{I}.
2845 @item @emph{Standard}:
2846 Fortran 95 and later
2851 @item @emph{Syntax}:
2852 @code{RESULT = BIT_SIZE(I)}
2854 @item @emph{Arguments}:
2855 @multitable @columnfractions .15 .70
2856 @item @var{I} @tab The type shall be @code{INTEGER}.
2859 @item @emph{Return value}:
2860 The return value is of type @code{INTEGER}
2862 @item @emph{Example}:
2864 program test_bit_size
2869 end program test_bit_size
2876 @section @code{BLE} --- Bitwise less than or equal to
2878 @cindex bitwise comparison
2881 @item @emph{Description}:
2882 Determines whether an integral is a bitwise less than or equal to
2885 @item @emph{Standard}:
2886 Fortran 2008 and later
2891 @item @emph{Syntax}:
2892 @code{RESULT = BLE(I, J)}
2894 @item @emph{Arguments}:
2895 @multitable @columnfractions .15 .70
2896 @item @var{I} @tab Shall be of @code{INTEGER} type.
2897 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2901 @item @emph{Return value}:
2902 The return value is of type @code{LOGICAL} and of the default kind.
2904 @item @emph{See also}:
2905 @ref{BGT}, @ref{BGE}, @ref{BLT}
2911 @section @code{BLT} --- Bitwise less than
2913 @cindex bitwise comparison
2916 @item @emph{Description}:
2917 Determines whether an integral is a bitwise less than another.
2919 @item @emph{Standard}:
2920 Fortran 2008 and later
2925 @item @emph{Syntax}:
2926 @code{RESULT = BLT(I, J)}
2928 @item @emph{Arguments}:
2929 @multitable @columnfractions .15 .70
2930 @item @var{I} @tab Shall be of @code{INTEGER} type.
2931 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2935 @item @emph{Return value}:
2936 The return value is of type @code{LOGICAL} and of the default kind.
2938 @item @emph{See also}:
2939 @ref{BGE}, @ref{BGT}, @ref{BLE}
2945 @section @code{BTEST} --- Bit test function
2951 @cindex bits, testing
2954 @item @emph{Description}:
2955 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
2956 in @var{I} is set. The counting of the bits starts at 0.
2958 @item @emph{Standard}:
2959 Fortran 95 and later, has overloads that are GNU extensions
2964 @item @emph{Syntax}:
2965 @code{RESULT = BTEST(I, POS)}
2967 @item @emph{Arguments}:
2968 @multitable @columnfractions .15 .70
2969 @item @var{I} @tab The type shall be @code{INTEGER}.
2970 @item @var{POS} @tab The type shall be @code{INTEGER}.
2973 @item @emph{Return value}:
2974 The return value is of type @code{LOGICAL}
2976 @item @emph{Example}:
2979 integer :: i = 32768 + 1024 + 64
2983 bool = btest(i, pos)
2986 end program test_btest
2989 @item @emph{Specific names}:
2990 @multitable @columnfractions .20 .20 .20 .25
2991 @item Name @tab Argument @tab Return type @tab Standard
2992 @item @code{BTEST(I,POS)} @tab @code{INTEGER I,POS} @tab @code{LOGICAL} @tab F95 and later
2993 @item @code{BBTEST(I,POS)} @tab @code{INTEGER(1) I,POS} @tab @code{LOGICAL(1)} @tab GNU extension
2994 @item @code{BITEST(I,POS)} @tab @code{INTEGER(2) I,POS} @tab @code{LOGICAL(2)} @tab GNU extension
2995 @item @code{BJTEST(I,POS)} @tab @code{INTEGER(4) I,POS} @tab @code{LOGICAL(4)} @tab GNU extension
2996 @item @code{BKTEST(I,POS)} @tab @code{INTEGER(8) I,POS} @tab @code{LOGICAL(8)} @tab GNU extension
3001 @section @code{C_ASSOCIATED} --- Status of a C pointer
3002 @fnindex C_ASSOCIATED
3003 @cindex association status, C pointer
3004 @cindex pointer, C association status
3007 @item @emph{Description}:
3008 @code{C_ASSOCIATED(c_ptr_1[, c_ptr_2])} determines the status of the C pointer
3009 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
3011 @item @emph{Standard}:
3012 Fortran 2003 and later
3017 @item @emph{Syntax}:
3018 @code{RESULT = C_ASSOCIATED(c_ptr_1[, c_ptr_2])}
3020 @item @emph{Arguments}:
3021 @multitable @columnfractions .15 .70
3022 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
3023 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
3026 @item @emph{Return value}:
3027 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
3028 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
3029 point to different addresses.
3031 @item @emph{Example}:
3033 subroutine association_test(a,b)
3034 use iso_c_binding, only: c_associated, c_loc, c_ptr
3038 if(c_associated(b, c_loc(a))) &
3039 stop 'b and a do not point to same target'
3040 end subroutine association_test
3043 @item @emph{See also}:
3044 @ref{C_LOC}, @ref{C_FUNLOC}
3049 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
3050 @fnindex C_F_POINTER
3051 @cindex pointer, convert C to Fortran
3054 @item @emph{Description}:
3055 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} assigns the target of the C pointer
3056 @var{CPTR} to the Fortran pointer @var{FPTR} and specifies its shape.
3058 @item @emph{Standard}:
3059 Fortran 2003 and later
3064 @item @emph{Syntax}:
3065 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
3067 @item @emph{Arguments}:
3068 @multitable @columnfractions .15 .70
3069 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
3071 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
3073 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
3074 with @code{INTENT(IN)}. It shall be present
3075 if and only if @var{fptr} is an array. The size
3076 must be equal to the rank of @var{fptr}.
3079 @item @emph{Example}:
3085 subroutine my_routine(p) bind(c,name='myC_func')
3087 type(c_ptr), intent(out) :: p
3091 real,pointer :: a(:)
3092 call my_routine(cptr)
3093 call c_f_pointer(cptr, a, [12])
3097 @item @emph{See also}:
3098 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
3102 @node C_F_PROCPOINTER
3103 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
3104 @fnindex C_F_PROCPOINTER
3105 @cindex pointer, C address of pointers
3108 @item @emph{Description}:
3109 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
3110 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
3112 @item @emph{Standard}:
3113 Fortran 2003 and later
3118 @item @emph{Syntax}:
3119 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
3121 @item @emph{Arguments}:
3122 @multitable @columnfractions .15 .70
3123 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
3125 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
3129 @item @emph{Example}:
3137 real(c_float), intent(in) :: a
3138 real(c_float) :: func
3142 function getIterFunc() bind(c,name="getIterFunc")
3144 type(c_funptr) :: getIterFunc
3147 type(c_funptr) :: cfunptr
3148 procedure(func), pointer :: myFunc
3149 cfunptr = getIterFunc()
3150 call c_f_procpointer(cfunptr, myFunc)
3154 @item @emph{See also}:
3155 @ref{C_LOC}, @ref{C_F_POINTER}
3160 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
3162 @cindex pointer, C address of procedures
3165 @item @emph{Description}:
3166 @code{C_FUNLOC(x)} determines the C address of the argument.
3168 @item @emph{Standard}:
3169 Fortran 2003 and later
3174 @item @emph{Syntax}:
3175 @code{RESULT = C_FUNLOC(x)}
3177 @item @emph{Arguments}:
3178 @multitable @columnfractions .15 .70
3179 @item @var{x} @tab Interoperable function or pointer to such function.
3182 @item @emph{Return value}:
3183 The return value is of type @code{C_FUNPTR} and contains the C address
3186 @item @emph{Example}:
3192 subroutine sub(a) bind(c)
3202 subroutine my_routine(p) bind(c,name='myC_func')
3204 type(c_funptr), intent(in) :: p
3207 call my_routine(c_funloc(sub))
3211 @item @emph{See also}:
3212 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
3217 @section @code{C_LOC} --- Obtain the C address of an object
3219 @cindex procedure pointer, convert C to Fortran
3222 @item @emph{Description}:
3223 @code{C_LOC(X)} determines the C address of the argument.
3225 @item @emph{Standard}:
3226 Fortran 2003 and later
3231 @item @emph{Syntax}:
3232 @code{RESULT = C_LOC(X)}
3234 @item @emph{Arguments}:
3235 @multitable @columnfractions .10 .75
3236 @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.
3240 @item @emph{Return value}:
3241 The return value is of type @code{C_PTR} and contains the C address
3244 @item @emph{Example}:
3246 subroutine association_test(a,b)
3247 use iso_c_binding, only: c_associated, c_loc, c_ptr
3251 if(c_associated(b, c_loc(a))) &
3252 stop 'b and a do not point to same target'
3253 end subroutine association_test
3256 @item @emph{See also}:
3257 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
3262 @section @code{C_SIZEOF} --- Size in bytes of an expression
3264 @cindex expression size
3265 @cindex size of an expression
3268 @item @emph{Description}:
3269 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
3270 expression @code{X} occupies.
3272 @item @emph{Standard}:
3276 Inquiry function of the module @code{ISO_C_BINDING}
3278 @item @emph{Syntax}:
3279 @code{N = C_SIZEOF(X)}
3281 @item @emph{Arguments}:
3282 @multitable @columnfractions .15 .70
3283 @item @var{X} @tab The argument shall be an interoperable data entity.
3286 @item @emph{Return value}:
3287 The return value is of type integer and of the system-dependent kind
3288 @code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the
3289 number of bytes occupied by the argument. If the argument has the
3290 @code{POINTER} attribute, the number of bytes of the storage area pointed
3291 to is returned. If the argument is of a derived type with @code{POINTER}
3292 or @code{ALLOCATABLE} components, the return value does not account for
3293 the sizes of the data pointed to by these components.
3295 @item @emph{Example}:
3299 real(c_float) :: r, s(5)
3300 print *, (c_sizeof(s)/c_sizeof(r) == 5)
3303 The example will print @code{.TRUE.} unless you are using a platform
3304 where default @code{REAL} variables are unusually padded.
3306 @item @emph{See also}:
3307 @ref{SIZEOF}, @ref{STORAGE_SIZE}
3312 @section @code{CEILING} --- Integer ceiling function
3315 @cindex rounding, ceiling
3318 @item @emph{Description}:
3319 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
3321 @item @emph{Standard}:
3322 Fortran 95 and later
3327 @item @emph{Syntax}:
3328 @code{RESULT = CEILING(A [, KIND])}
3330 @item @emph{Arguments}:
3331 @multitable @columnfractions .15 .70
3332 @item @var{A} @tab The type shall be @code{REAL}.
3333 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3334 expression indicating the kind parameter of the result.
3337 @item @emph{Return value}:
3338 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
3339 and a default-kind @code{INTEGER} otherwise.
3341 @item @emph{Example}:
3343 program test_ceiling
3346 print *, ceiling(x) ! returns 64
3347 print *, ceiling(y) ! returns -63
3348 end program test_ceiling
3351 @item @emph{See also}:
3352 @ref{FLOOR}, @ref{NINT}
3359 @section @code{CHAR} --- Character conversion function
3361 @cindex conversion, to character
3364 @item @emph{Description}:
3365 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
3367 @item @emph{Standard}:
3368 Fortran 77 and later
3373 @item @emph{Syntax}:
3374 @code{RESULT = CHAR(I [, KIND])}
3376 @item @emph{Arguments}:
3377 @multitable @columnfractions .15 .70
3378 @item @var{I} @tab The type shall be @code{INTEGER}.
3379 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3380 expression indicating the kind parameter of the result.
3383 @item @emph{Return value}:
3384 The return value is of type @code{CHARACTER(1)}
3386 @item @emph{Example}:
3392 print *, i, c ! returns 'J'
3393 end program test_char
3396 @item @emph{Specific names}:
3397 @multitable @columnfractions .20 .20 .20 .25
3398 @item Name @tab Argument @tab Return type @tab Standard
3399 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
3403 See @ref{ICHAR} for a discussion of converting between numerical values
3404 and formatted string representations.
3406 @item @emph{See also}:
3407 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
3414 @section @code{CHDIR} --- Change working directory
3416 @cindex system, working directory
3419 @item @emph{Description}:
3420 Change current working directory to a specified path.
3422 This intrinsic is provided in both subroutine and function forms; however,
3423 only one form can be used in any given program unit.
3425 @item @emph{Standard}:
3429 Subroutine, function
3431 @item @emph{Syntax}:
3432 @multitable @columnfractions .80
3433 @item @code{CALL CHDIR(NAME [, STATUS])}
3434 @item @code{STATUS = CHDIR(NAME)}
3437 @item @emph{Arguments}:
3438 @multitable @columnfractions .15 .70
3439 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
3440 kind and shall specify a valid path within the file system.
3441 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
3442 kind. Returns 0 on success, and a system specific and nonzero error code
3446 @item @emph{Example}:
3449 CHARACTER(len=255) :: path
3451 WRITE(*,*) TRIM(path)
3454 WRITE(*,*) TRIM(path)
3458 @item @emph{See also}:
3465 @section @code{CHMOD} --- Change access permissions of files
3467 @cindex file system, change access mode
3470 @item @emph{Description}:
3471 @code{CHMOD} changes the permissions of a file.
3473 This intrinsic is provided in both subroutine and function forms; however,
3474 only one form can be used in any given program unit.
3476 @item @emph{Standard}:
3480 Subroutine, function
3482 @item @emph{Syntax}:
3483 @multitable @columnfractions .80
3484 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
3485 @item @code{STATUS = CHMOD(NAME, MODE)}
3488 @item @emph{Arguments}:
3489 @multitable @columnfractions .15 .70
3491 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
3492 file name. Trailing blanks are ignored unless the character
3493 @code{achar(0)} is present, then all characters up to and excluding
3494 @code{achar(0)} are used as the file name.
3496 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
3497 file permission. @var{MODE} uses the same syntax as the @code{chmod} utility
3498 as defined by the POSIX standard. The argument shall either be a string of
3499 a nonnegative octal number or a symbolic mode.
3501 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
3502 @code{0} on success and nonzero otherwise.
3505 @item @emph{Return value}:
3506 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
3509 @item @emph{Example}:
3510 @code{CHMOD} as subroutine
3515 call chmod('test.dat','u+x',status)
3516 print *, 'Status: ', status
3517 end program chmod_test
3519 @code{CHMOD} as function:
3524 status = chmod('test.dat','u+x')
3525 print *, 'Status: ', status
3526 end program chmod_test
3534 @section @code{CMPLX} --- Complex conversion function
3536 @cindex complex numbers, conversion to
3537 @cindex conversion, to complex
3540 @item @emph{Description}:
3541 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
3542 the real component. If @var{Y} is present it is converted to the imaginary
3543 component. If @var{Y} is not present then the imaginary component is set to
3544 0.0. If @var{X} is complex then @var{Y} must not be present.
3546 @item @emph{Standard}:
3547 Fortran 77 and later
3552 @item @emph{Syntax}:
3553 @code{RESULT = CMPLX(X [, Y [, KIND]])}
3555 @item @emph{Arguments}:
3556 @multitable @columnfractions .15 .70
3557 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3559 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
3560 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
3561 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3562 expression indicating the kind parameter of the result.
3565 @item @emph{Return value}:
3566 The return value is of @code{COMPLEX} type, with a kind equal to
3567 @var{KIND} if it is specified. If @var{KIND} is not specified, the
3568 result is of the default @code{COMPLEX} kind, regardless of the kinds of
3569 @var{X} and @var{Y}.
3571 @item @emph{Example}:
3578 print *, z, cmplx(x)
3579 end program test_cmplx
3582 @item @emph{See also}:
3589 @section @code{CO_BROADCAST} --- Copy a value to all images the current set of images
3590 @fnindex CO_BROADCAST
3591 @cindex Collectives, value broadcasting
3594 @item @emph{Description}:
3595 @code{CO_BROADCAST} copies the value of argument @var{A} on the image with
3596 image index @code{SOURCE_IMAGE} to all images in the current team. @var{A}
3597 becomes defined as if by intrinsic assignment. If the execution was
3598 successful and @var{STAT} is present, it is assigned the value zero. If the
3599 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3600 @var{ERRMSG} gets assigned a value describing the occurred error.
3602 @item @emph{Standard}:
3603 Technical Specification (TS) 18508 or later
3606 Collective subroutine
3608 @item @emph{Syntax}:
3609 @code{CALL CO_BROADCAST(A, SOURCE_IMAGE [, STAT, ERRMSG])}
3611 @item @emph{Arguments}:
3612 @multitable @columnfractions .15 .70
3613 @item @var{A} @tab INTENT(INOUT) argument; shall have the same
3614 dynamic type and type paramters on all images of the current team. If it
3615 is an array, it shall have the same shape on all images.
3616 @item @var{SOURCE_IMAGE} @tab a scalar integer expression.
3617 It shall have the same the same value on all images and refer to an
3618 image of the current team.
3619 @item @var{STAT} @tab (optional) a scalar integer variable
3620 @item @var{ERRMSG} @tab (optional) a scalar character variable
3623 @item @emph{Example}:
3627 if (this_image() == 1) then
3630 call co_broadcast (val, source_image=1)
3631 print *, this_image, ":", val
3635 @item @emph{See also}:
3636 @ref{CO_MAX}, @ref{CO_MIN}, @ref{CO_SUM}, @ref{CO_REDUCE}
3642 @section @code{CO_MAX} --- Maximal value on the current set of images
3644 @cindex Collectives, maximal value
3647 @item @emph{Description}:
3648 @code{CO_MAX} determines element-wise the maximal value of @var{A} on all
3649 images of the current team. If @var{RESULT_IMAGE} is present, the maximum
3650 values are returned in @var{A} on the specified image only and the value
3651 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3652 not present, the value is returned on all images. If the execution was
3653 successful and @var{STAT} is present, it is assigned the value zero. If the
3654 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3655 @var{ERRMSG} gets assigned a value describing the occurred error.
3657 @item @emph{Standard}:
3658 Technical Specification (TS) 18508 or later
3661 Collective subroutine
3663 @item @emph{Syntax}:
3664 @code{CALL CO_MAX(A [, RESULT_IMAGE, STAT, ERRMSG])}
3666 @item @emph{Arguments}:
3667 @multitable @columnfractions .15 .70
3668 @item @var{A} @tab shall be an integer, real or character variable,
3669 which has the same type and type parameters on all images of the team.
3670 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3671 present, it shall have the same the same value on all images and refer to an
3672 image of the current team.
3673 @item @var{STAT} @tab (optional) a scalar integer variable
3674 @item @var{ERRMSG} @tab (optional) a scalar character variable
3677 @item @emph{Example}:
3682 call co_max (val, result_image=1)
3683 if (this_image() == 1) then
3684 write(*,*) "Maximal value", val ! prints num_images()
3689 @item @emph{See also}:
3690 @ref{CO_MIN}, @ref{CO_SUM}, @ref{CO_REDUCE}, @ref{CO_BROADCAST}
3696 @section @code{CO_MIN} --- Minimal value on the current set of images
3698 @cindex Collectives, minimal value
3701 @item @emph{Description}:
3702 @code{CO_MIN} determines element-wise the minimal value of @var{A} on all
3703 images of the current team. If @var{RESULT_IMAGE} is present, the minimal
3704 values are returned in @var{A} on the specified image only and the value
3705 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3706 not present, the value is returned on all images. If the execution was
3707 successful and @var{STAT} is present, it is assigned the value zero. If the
3708 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3709 @var{ERRMSG} gets assigned a value describing the occurred error.
3711 @item @emph{Standard}:
3712 Technical Specification (TS) 18508 or later
3715 Collective subroutine
3717 @item @emph{Syntax}:
3718 @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3720 @item @emph{Arguments}:
3721 @multitable @columnfractions .15 .70
3722 @item @var{A} @tab shall be an integer, real or character variable,
3723 which has the same type and type parameters on all images of the team.
3724 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3725 present, it shall have the same the same value on all images and refer to an
3726 image of the current team.
3727 @item @var{STAT} @tab (optional) a scalar integer variable
3728 @item @var{ERRMSG} @tab (optional) a scalar character variable
3731 @item @emph{Example}:
3736 call co_min (val, result_image=1)
3737 if (this_image() == 1) then
3738 write(*,*) "Minimal value", val ! prints 1
3743 @item @emph{See also}:
3744 @ref{CO_MAX}, @ref{CO_SUM}, @ref{CO_REDUCE}, @ref{CO_BROADCAST}
3750 @section @code{CO_REDUCE} --- Reduction of values on the current set of images
3752 @cindex Collectives, generic reduction
3755 @item @emph{Description}:
3756 @code{CO_REDUCE} determines element-wise the reduction of the value of @var{A}
3757 on all images of the current team. The pure function passed as @var{OPERATOR}
3758 is used to pairwise reduce the values of @var{A} by passing either the value
3759 of @var{A} of different images or the result values of such a reduction as
3760 argument. If @var{A} is an array, the deduction is done element wise. If
3761 @var{RESULT_IMAGE} is present, the result values are returned in @var{A} on
3762 the specified image only and the value of @var{A} on the other images become
3763 undefined. If @var{RESULT_IMAGE} is not present, the value is returned on all
3764 images. If the execution was successful and @var{STAT} is present, it is
3765 assigned the value zero. If the execution failed, @var{STAT} gets assigned
3766 a nonzero value and, if present, @var{ERRMSG} gets assigned a value describing
3769 @item @emph{Standard}:
3770 Technical Specification (TS) 18508 or later
3773 Collective subroutine
3775 @item @emph{Syntax}:
3776 @code{CALL CO_REDUCE(A, OPERATOR, [, RESULT_IMAGE, STAT, ERRMSG])}
3778 @item @emph{Arguments}:
3779 @multitable @columnfractions .15 .70
3780 @item @var{A} @tab is an @code{INTENT(INOUT)} argument and shall be
3781 nonpolymorphic. If it is allocatable, it shall be allocated; if it is a pointer,
3782 it shall be associated. @var{A} shall have the same type and type parameters on
3783 all images of the team; if it is an array, it shall have the same shape on all
3785 @item @var{OPERATOR} @tab pure function with two scalar nonallocatable
3786 arguments, which shall be nonpolymorphic and have the same type and type
3787 parameters as @var{A}. The function shall return a nonallocatable scalar of
3788 the same type and type parameters as @var{A}. The function shall be the same on
3789 all images and with regards to the arguments mathematically commutative and
3790 associative. Note that @var{OPERATOR} may not be an elemental function, unless
3791 it is an intrisic function.
3792 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3793 present, it shall have the same the same value on all images and refer to an
3794 image of the current team.
3795 @item @var{STAT} @tab (optional) a scalar integer variable
3796 @item @var{ERRMSG} @tab (optional) a scalar character variable
3799 @item @emph{Example}:
3804 call co_reduce (val, result_image=1, operator=myprod)
3805 if (this_image() == 1) then
3806 write(*,*) "Product value", val ! prints num_images() factorial
3809 pure function myprod(a, b)
3810 integer, value :: a, b
3818 While the rules permit in principle an intrinsic function, none of the
3819 intrinsics in the standard fulfill the criteria of having a specific
3820 function, which takes two arguments of the same type and returning that
3823 @item @emph{See also}:
3824 @ref{CO_MIN}, @ref{CO_MAX}, @ref{CO_SUM}, @ref{CO_BROADCAST}
3830 @section @code{CO_SUM} --- Sum of values on the current set of images
3832 @cindex Collectives, sum of values
3835 @item @emph{Description}:
3836 @code{CO_SUM} sums up the values of each element of @var{A} on all
3837 images of the current team. If @var{RESULT_IMAGE} is present, the summed-up
3838 values are returned in @var{A} on the specified image only and the value
3839 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3840 not present, the value is returned on all images. If the execution was
3841 successful and @var{STAT} is present, it is assigned the value zero. If the
3842 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3843 @var{ERRMSG} gets assigned a value describing the occurred error.
3845 @item @emph{Standard}:
3846 Technical Specification (TS) 18508 or later
3849 Collective subroutine
3851 @item @emph{Syntax}:
3852 @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3854 @item @emph{Arguments}:
3855 @multitable @columnfractions .15 .70
3856 @item @var{A} @tab shall be an integer, real or complex variable,
3857 which has the same type and type parameters on all images of the team.
3858 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3859 present, it shall have the same the same value on all images and refer to an
3860 image of the current team.
3861 @item @var{STAT} @tab (optional) a scalar integer variable
3862 @item @var{ERRMSG} @tab (optional) a scalar character variable
3865 @item @emph{Example}:
3870 call co_sum (val, result_image=1)
3871 if (this_image() == 1) then
3872 write(*,*) "The sum is ", val ! prints (n**2 + n)/2, with n = num_images()
3877 @item @emph{See also}:
3878 @ref{CO_MAX}, @ref{CO_MIN}, @ref{CO_REDUCE}, @ref{CO_BROADCAST}
3883 @node COMMAND_ARGUMENT_COUNT
3884 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
3885 @fnindex COMMAND_ARGUMENT_COUNT
3886 @cindex command-line arguments
3887 @cindex command-line arguments, number of
3888 @cindex arguments, to program
3891 @item @emph{Description}:
3892 @code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the
3893 command line when the containing program was invoked.
3895 @item @emph{Standard}:
3896 Fortran 2003 and later
3901 @item @emph{Syntax}:
3902 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
3904 @item @emph{Arguments}:
3905 @multitable @columnfractions .15 .70
3909 @item @emph{Return value}:
3910 The return value is an @code{INTEGER} of default kind.
3912 @item @emph{Example}:
3914 program test_command_argument_count
3916 count = command_argument_count()
3918 end program test_command_argument_count
3921 @item @emph{See also}:
3922 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
3927 @node COMPILER_OPTIONS
3928 @section @code{COMPILER_OPTIONS} --- Options passed to the compiler
3929 @fnindex COMPILER_OPTIONS
3930 @cindex flags inquiry function
3931 @cindex options inquiry function
3932 @cindex compiler flags inquiry function
3935 @item @emph{Description}:
3936 @code{COMPILER_OPTIONS} returns a string with the options used for
3939 @item @emph{Standard}:
3943 Inquiry function of the module @code{ISO_FORTRAN_ENV}
3945 @item @emph{Syntax}:
3946 @code{STR = COMPILER_OPTIONS()}
3948 @item @emph{Arguments}:
3951 @item @emph{Return value}:
3952 The return value is a default-kind string with system-dependent length.
3953 It contains the compiler flags used to compile the file, which called
3954 the @code{COMPILER_OPTIONS} intrinsic.
3956 @item @emph{Example}:
3959 print '(4a)', 'This file was compiled by ', &
3960 compiler_version(), ' using the options ', &
3965 @item @emph{See also}:
3966 @ref{COMPILER_VERSION}, @ref{ISO_FORTRAN_ENV}
3971 @node COMPILER_VERSION
3972 @section @code{COMPILER_VERSION} --- Compiler version string
3973 @fnindex COMPILER_VERSION
3974 @cindex compiler, name and version
3975 @cindex version of the compiler
3978 @item @emph{Description}:
3979 @code{COMPILER_VERSION} returns a string with the name and the
3980 version of the compiler.
3982 @item @emph{Standard}:
3986 Inquiry function of the module @code{ISO_FORTRAN_ENV}
3988 @item @emph{Syntax}:
3989 @code{STR = COMPILER_VERSION()}
3991 @item @emph{Arguments}:
3994 @item @emph{Return value}:
3995 The return value is a default-kind string with system-dependent length.
3996 It contains the name of the compiler and its version number.
3998 @item @emph{Example}:
4001 print '(4a)', 'This file was compiled by ', &
4002 compiler_version(), ' using the options ', &
4007 @item @emph{See also}:
4008 @ref{COMPILER_OPTIONS}, @ref{ISO_FORTRAN_ENV}
4014 @section @code{COMPLEX} --- Complex conversion function
4016 @cindex complex numbers, conversion to
4017 @cindex conversion, to complex
4020 @item @emph{Description}:
4021 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
4022 to the real component and @var{Y} is converted to the imaginary
4025 @item @emph{Standard}:
4031 @item @emph{Syntax}:
4032 @code{RESULT = COMPLEX(X, Y)}
4034 @item @emph{Arguments}:
4035 @multitable @columnfractions .15 .70
4036 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
4037 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
4040 @item @emph{Return value}:
4041 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
4042 value is of default @code{COMPLEX} type.
4044 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
4045 type and one is of @code{INTEGER} type, then the return value is of
4046 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
4047 argument with the highest precision.
4049 @item @emph{Example}:
4051 program test_complex
4054 print *, complex(i, x)
4055 end program test_complex
4058 @item @emph{See also}:
4065 @section @code{CONJG} --- Complex conjugate function
4068 @cindex complex conjugate
4071 @item @emph{Description}:
4072 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
4073 then the result is @code{(x, -y)}
4075 @item @emph{Standard}:
4076 Fortran 77 and later, has overloads that are GNU extensions
4081 @item @emph{Syntax}:
4084 @item @emph{Arguments}:
4085 @multitable @columnfractions .15 .70
4086 @item @var{Z} @tab The type shall be @code{COMPLEX}.
4089 @item @emph{Return value}:
4090 The return value is of type @code{COMPLEX}.
4092 @item @emph{Example}:
4095 complex :: z = (2.0, 3.0)
4096 complex(8) :: dz = (2.71_8, -3.14_8)
4101 end program test_conjg
4104 @item @emph{Specific names}:
4105 @multitable @columnfractions .20 .20 .20 .25
4106 @item Name @tab Argument @tab Return type @tab Standard
4107 @item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension
4108 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
4115 @section @code{COS} --- Cosine function
4121 @cindex trigonometric function, cosine
4125 @item @emph{Description}:
4126 @code{COS(X)} computes the cosine of @var{X}.
4128 @item @emph{Standard}:
4129 Fortran 77 and later, has overloads that are GNU extensions
4134 @item @emph{Syntax}:
4135 @code{RESULT = COS(X)}
4137 @item @emph{Arguments}:
4138 @multitable @columnfractions .15 .70
4139 @item @var{X} @tab The type shall be @code{REAL} or
4143 @item @emph{Return value}:
4144 The return value is of the same type and kind as @var{X}. The real part
4145 of the result is in radians. If @var{X} is of the type @code{REAL},
4146 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
4148 @item @emph{Example}:
4153 end program test_cos
4156 @item @emph{Specific names}:
4157 @multitable @columnfractions .20 .20 .20 .25
4158 @item Name @tab Argument @tab Return type @tab Standard
4159 @item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
4160 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
4161 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
4162 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4163 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4166 @item @emph{See also}:
4167 Inverse function: @ref{ACOS}
4168 Degrees function: @ref{COSD}
4175 @section @code{COSD} --- Cosine function, degrees
4181 @cindex trigonometric function, cosine, degrees
4182 @cindex cosine, degrees
4185 @item @emph{Description}:
4186 @code{COSD(X)} computes the cosine of @var{X} in degrees.
4188 This function is for compatibility only and should be avoided in favor of
4189 standard constructs wherever possible.
4191 @item @emph{Standard}:
4192 GNU Extension, enabled with @option{-fdec-math}.
4197 @item @emph{Syntax}:
4198 @code{RESULT = COSD(X)}
4200 @item @emph{Arguments}:
4201 @multitable @columnfractions .15 .70
4202 @item @var{X} @tab The type shall be @code{REAL} or
4206 @item @emph{Return value}:
4207 The return value is of the same type and kind as @var{X}. The real part
4208 of the result is in degrees. If @var{X} is of the type @code{REAL},
4209 the return value lies in the range @math{ -1 \leq \cosd (x) \leq 1}.
4211 @item @emph{Example}:
4216 end program test_cosd
4219 @item @emph{Specific names}:
4220 @multitable @columnfractions .20 .20 .20 .25
4221 @item Name @tab Argument @tab Return type @tab Standard
4222 @item @code{COSD(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4223 @item @code{DCOSD(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4224 @item @code{CCOSD(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU Extension
4225 @item @code{ZCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4226 @item @code{CDCOSD(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4229 @item @emph{See also}:
4230 Inverse function: @ref{ACOSD}
4231 Radians function: @ref{COS}
4238 @section @code{COSH} --- Hyperbolic cosine function
4241 @cindex hyperbolic cosine
4242 @cindex hyperbolic function, cosine
4243 @cindex cosine, hyperbolic
4246 @item @emph{Description}:
4247 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
4249 @item @emph{Standard}:
4250 Fortran 77 and later, for a complex argument Fortran 2008 or later
4255 @item @emph{Syntax}:
4258 @item @emph{Arguments}:
4259 @multitable @columnfractions .15 .70
4260 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4263 @item @emph{Return value}:
4264 The return value has same type and kind as @var{X}. If @var{X} is
4265 complex, the imaginary part of the result is in radians. If @var{X}
4266 is @code{REAL}, the return value has a lower bound of one,
4267 @math{\cosh (x) \geq 1}.
4269 @item @emph{Example}:
4272 real(8) :: x = 1.0_8
4274 end program test_cosh
4277 @item @emph{Specific names}:
4278 @multitable @columnfractions .20 .20 .20 .25
4279 @item Name @tab Argument @tab Return type @tab Standard
4280 @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
4281 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
4284 @item @emph{See also}:
4285 Inverse function: @ref{ACOSH}
4292 @section @code{COTAN} --- Cotangent function
4295 @cindex trigonometric function, cotangent
4299 @item @emph{Description}:
4300 @code{COTAN(X)} computes the cotangent of @var{X}. Equivalent to @code{COS(x)}
4301 divided by @code{SIN(x)}, or @code{1 / TAN(x)}.
4303 This function is for compatibility only and should be avoided in favor of
4304 standard constructs wherever possible.
4306 @item @emph{Standard}:
4307 GNU Extension, enabled with @option{-fdec-math}.
4312 @item @emph{Syntax}:
4313 @code{RESULT = COTAN(X)}
4315 @item @emph{Arguments}:
4316 @multitable @columnfractions .15 .70
4317 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4320 @item @emph{Return value}:
4321 The return value has same type and kind as @var{X}, and its value is in radians.
4323 @item @emph{Example}:
4326 real(8) :: x = 0.165_8
4328 end program test_cotan
4331 @item @emph{Specific names}:
4332 @multitable @columnfractions .20 .20 .20 .25
4333 @item Name @tab Argument @tab Return type @tab Standard
4334 @item @code{COTAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4335 @item @code{DCOTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4338 @item @emph{See also}:
4339 Converse function: @ref{TAN}
4340 Degrees function: @ref{COTAND}
4346 @section @code{COTAND} --- Cotangent function, degrees
4349 @cindex trigonometric function, cotangent, degrees
4350 @cindex cotangent, degrees
4353 @item @emph{Description}:
4354 @code{COTAND(X)} computes the cotangent of @var{X} in degrees. Equivalent to
4355 @code{COSD(x)} divided by @code{SIND(x)}, or @code{1 / TAND(x)}.
4357 @item @emph{Standard}:
4358 GNU Extension, enabled with @option{-fdec-math}.
4360 This function is for compatibility only and should be avoided in favor of
4361 standard constructs wherever possible.
4366 @item @emph{Syntax}:
4367 @code{RESULT = COTAND(X)}
4369 @item @emph{Arguments}:
4370 @multitable @columnfractions .15 .70
4371 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
4374 @item @emph{Return value}:
4375 The return value has same type and kind as @var{X}, and its value is in degrees.
4377 @item @emph{Example}:
4380 real(8) :: x = 0.165_8
4382 end program test_cotand
4385 @item @emph{Specific names}:
4386 @multitable @columnfractions .20 .20 .20 .25
4387 @item Name @tab Argument @tab Return type @tab Standard
4388 @item @code{COTAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4389 @item @code{DCOTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4392 @item @emph{See also}:
4393 Converse function: @ref{TAND}
4394 Radians function: @ref{COTAN}
4401 @section @code{COUNT} --- Count function
4403 @cindex array, conditionally count elements
4404 @cindex array, element counting
4405 @cindex array, number of elements
4408 @item @emph{Description}:
4410 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
4411 or, if the @var{DIM} argument is supplied, counts the number of
4412 elements along each row of the array in the @var{DIM} direction.
4413 If the array has zero size, or all of the elements of @var{MASK} are
4414 @code{.FALSE.}, then the result is @code{0}.
4416 @item @emph{Standard}:
4417 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
4420 Transformational function
4422 @item @emph{Syntax}:
4423 @code{RESULT = COUNT(MASK [, DIM, KIND])}
4425 @item @emph{Arguments}:
4426 @multitable @columnfractions .15 .70
4427 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
4428 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
4429 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4430 expression indicating the kind parameter of the result.
4433 @item @emph{Return value}:
4434 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
4435 @var{KIND} is absent, the return value is of default integer kind.
4436 If @var{DIM} is present, the result is an array with a rank one less
4437 than the rank of @var{ARRAY}, and a size corresponding to the shape
4438 of @var{ARRAY} with the @var{DIM} dimension removed.
4440 @item @emph{Example}:
4443 integer, dimension(2,3) :: a, b
4444 logical, dimension(2,3) :: mask
4445 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
4446 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
4447 print '(3i3)', a(1,:)
4448 print '(3i3)', a(2,:)
4450 print '(3i3)', b(1,:)
4451 print '(3i3)', b(2,:)
4454 print '(3l3)', mask(1,:)
4455 print '(3l3)', mask(2,:)
4457 print '(3i3)', count(mask)
4459 print '(3i3)', count(mask, 1)
4461 print '(3i3)', count(mask, 2)
4462 end program test_count
4469 @section @code{CPU_TIME} --- CPU elapsed time in seconds
4471 @cindex time, elapsed
4474 @item @emph{Description}:
4475 Returns a @code{REAL} value representing the elapsed CPU time in
4476 seconds. This is useful for testing segments of code to determine
4479 If a time source is available, time will be reported with microsecond
4480 resolution. If no time source is available, @var{TIME} is set to
4483 Note that @var{TIME} may contain a, system dependent, arbitrary offset
4484 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
4485 value is meaningless, only differences between subsequent calls to
4486 this subroutine, as shown in the example below, should be used.
4489 @item @emph{Standard}:
4490 Fortran 95 and later
4495 @item @emph{Syntax}:
4496 @code{CALL CPU_TIME(TIME)}
4498 @item @emph{Arguments}:
4499 @multitable @columnfractions .15 .70
4500 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
4503 @item @emph{Return value}:
4506 @item @emph{Example}:
4508 program test_cpu_time
4509 real :: start, finish
4510 call cpu_time(start)
4511 ! put code to test here
4512 call cpu_time(finish)
4513 print '("Time = ",f6.3," seconds.")',finish-start
4514 end program test_cpu_time
4517 @item @emph{See also}:
4518 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
4524 @section @code{CSHIFT} --- Circular shift elements of an array
4526 @cindex array, shift circularly
4527 @cindex array, permutation
4528 @cindex array, rotate
4531 @item @emph{Description}:
4532 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
4533 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
4534 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
4535 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
4536 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
4537 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
4538 sections of @var{ARRAY} along the given dimension are shifted. Elements
4539 shifted out one end of each rank one section are shifted back in the other end.
4541 @item @emph{Standard}:
4542 Fortran 95 and later
4545 Transformational function
4547 @item @emph{Syntax}:
4548 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
4550 @item @emph{Arguments}:
4551 @multitable @columnfractions .15 .70
4552 @item @var{ARRAY} @tab Shall be an array of any type.
4553 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
4554 @item @var{DIM} @tab The type shall be @code{INTEGER}.
4557 @item @emph{Return value}:
4558 Returns an array of same type and rank as the @var{ARRAY} argument.
4560 @item @emph{Example}:
4563 integer, dimension(3,3) :: a
4564 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
4565 print '(3i3)', a(1,:)
4566 print '(3i3)', a(2,:)
4567 print '(3i3)', a(3,:)
4568 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
4570 print '(3i3)', a(1,:)
4571 print '(3i3)', a(2,:)
4572 print '(3i3)', a(3,:)
4573 end program test_cshift
4580 @section @code{CTIME} --- Convert a time into a string
4582 @cindex time, conversion to string
4583 @cindex conversion, to string
4586 @item @emph{Description}:
4587 @code{CTIME} converts a system time value, such as returned by
4588 @ref{TIME8}, to a string. The output will be of the form @samp{Sat
4589 Aug 19 18:13:14 1995}.
4591 This intrinsic is provided in both subroutine and function forms; however,
4592 only one form can be used in any given program unit.
4594 @item @emph{Standard}:
4598 Subroutine, function
4600 @item @emph{Syntax}:
4601 @multitable @columnfractions .80
4602 @item @code{CALL CTIME(TIME, RESULT)}.
4603 @item @code{RESULT = CTIME(TIME)}.
4606 @item @emph{Arguments}:
4607 @multitable @columnfractions .15 .70
4608 @item @var{TIME} @tab The type shall be of type @code{INTEGER}.
4609 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
4610 of default kind. It is an @code{INTENT(OUT)} argument. If the length
4611 of this variable is too short for the time and date string to fit
4612 completely, it will be blank on procedure return.
4615 @item @emph{Return value}:
4616 The converted date and time as a string.
4618 @item @emph{Example}:
4622 character(len=30) :: date
4625 ! Do something, main part of the program
4628 print *, 'Program was started on ', date
4629 end program test_ctime
4632 @item @emph{See Also}:
4633 @ref{DATE_AND_TIME}, @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
4639 @section @code{DATE_AND_TIME} --- Date and time subroutine
4640 @fnindex DATE_AND_TIME
4641 @cindex date, current
4642 @cindex current date
4643 @cindex time, current
4644 @cindex current time
4647 @item @emph{Description}:
4648 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
4649 time information from the real-time system clock. @var{DATE} is
4650 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
4651 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
4652 representing the difference with respect to Coordinated Universal Time (UTC).
4653 Unavailable time and date parameters return blanks.
4655 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
4657 @multitable @columnfractions .15 .30 .40
4658 @item @tab @code{VALUE(1)}: @tab The year
4659 @item @tab @code{VALUE(2)}: @tab The month
4660 @item @tab @code{VALUE(3)}: @tab The day of the month
4661 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
4662 @item @tab @code{VALUE(5)}: @tab The hour of the day
4663 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
4664 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
4665 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
4668 @item @emph{Standard}:
4669 Fortran 95 and later
4674 @item @emph{Syntax}:
4675 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
4677 @item @emph{Arguments}:
4678 @multitable @columnfractions .15 .70
4679 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
4680 or larger, and of default kind.
4681 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
4682 or larger, and of default kind.
4683 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
4684 or larger, and of default kind.
4685 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
4688 @item @emph{Return value}:
4691 @item @emph{Example}:
4693 program test_time_and_date
4694 character(8) :: date
4695 character(10) :: time
4696 character(5) :: zone
4697 integer,dimension(8) :: values
4698 ! using keyword arguments
4699 call date_and_time(date,time,zone,values)
4700 call date_and_time(DATE=date,ZONE=zone)
4701 call date_and_time(TIME=time)
4702 call date_and_time(VALUES=values)
4703 print '(a,2x,a,2x,a)', date, time, zone
4704 print '(8i5)', values
4705 end program test_time_and_date
4708 @item @emph{See also}:
4709 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
4715 @section @code{DBLE} --- Double conversion function
4717 @cindex conversion, to real
4720 @item @emph{Description}:
4721 @code{DBLE(A)} Converts @var{A} to double precision real type.
4723 @item @emph{Standard}:
4724 Fortran 77 and later
4729 @item @emph{Syntax}:
4730 @code{RESULT = DBLE(A)}
4732 @item @emph{Arguments}:
4733 @multitable @columnfractions .15 .70
4734 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
4738 @item @emph{Return value}:
4739 The return value is of type double precision real.
4741 @item @emph{Example}:
4746 complex :: z = (2.3,1.14)
4747 print *, dble(x), dble(i), dble(z)
4748 end program test_dble
4751 @item @emph{See also}:
4758 @section @code{DCMPLX} --- Double complex conversion function
4760 @cindex complex numbers, conversion to
4761 @cindex conversion, to complex
4764 @item @emph{Description}:
4765 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
4766 converted to the real component. If @var{Y} is present it is converted to the
4767 imaginary component. If @var{Y} is not present then the imaginary component is
4768 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
4770 @item @emph{Standard}:
4776 @item @emph{Syntax}:
4777 @code{RESULT = DCMPLX(X [, Y])}
4779 @item @emph{Arguments}:
4780 @multitable @columnfractions .15 .70
4781 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
4783 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
4784 @code{INTEGER} or @code{REAL}.
4787 @item @emph{Return value}:
4788 The return value is of type @code{COMPLEX(8)}
4790 @item @emph{Example}:
4800 print *, dcmplx(x,i)
4801 end program test_dcmplx
4807 @section @code{DIGITS} --- Significant binary digits function
4809 @cindex model representation, significant digits
4812 @item @emph{Description}:
4813 @code{DIGITS(X)} returns the number of significant binary digits of the internal
4814 model representation of @var{X}. For example, on a system using a 32-bit
4815 floating point representation, a default real number would likely return 24.
4817 @item @emph{Standard}:
4818 Fortran 95 and later
4823 @item @emph{Syntax}:
4824 @code{RESULT = DIGITS(X)}
4826 @item @emph{Arguments}:
4827 @multitable @columnfractions .15 .70
4828 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
4831 @item @emph{Return value}:
4832 The return value is of type @code{INTEGER}.
4834 @item @emph{Example}:
4837 integer :: i = 12345
4843 end program test_digits
4850 @section @code{DIM} --- Positive difference
4854 @cindex positive difference
4857 @item @emph{Description}:
4858 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
4859 otherwise returns zero.
4861 @item @emph{Standard}:
4862 Fortran 77 and later
4867 @item @emph{Syntax}:
4868 @code{RESULT = DIM(X, Y)}
4870 @item @emph{Arguments}:
4871 @multitable @columnfractions .15 .70
4872 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
4873 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
4876 @item @emph{Return value}:
4877 The return value is of type @code{INTEGER} or @code{REAL}.
4879 @item @emph{Example}:
4885 x = dim(4.345_8, 2.111_8)
4888 end program test_dim
4891 @item @emph{Specific names}:
4892 @multitable @columnfractions .20 .20 .20 .25
4893 @item Name @tab Argument @tab Return type @tab Standard
4894 @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
4895 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
4896 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
4903 @section @code{DOT_PRODUCT} --- Dot product function
4904 @fnindex DOT_PRODUCT
4906 @cindex vector product
4907 @cindex product, vector
4910 @item @emph{Description}:
4911 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
4912 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
4913 either numeric or logical and must be arrays of rank one and of equal size. If
4914 the vectors are @code{INTEGER} or @code{REAL}, the result is
4915 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
4916 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
4917 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
4919 @item @emph{Standard}:
4920 Fortran 95 and later
4923 Transformational function
4925 @item @emph{Syntax}:
4926 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
4928 @item @emph{Arguments}:
4929 @multitable @columnfractions .15 .70
4930 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
4931 @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.
4934 @item @emph{Return value}:
4935 If the arguments are numeric, the return value is a scalar of numeric type,
4936 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
4937 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
4939 @item @emph{Example}:
4941 program test_dot_prod
4942 integer, dimension(3) :: a, b
4949 print *, dot_product(a,b)
4950 end program test_dot_prod
4957 @section @code{DPROD} --- Double product function
4959 @cindex product, double-precision
4962 @item @emph{Description}:
4963 @code{DPROD(X,Y)} returns the product @code{X*Y}.
4965 @item @emph{Standard}:
4966 Fortran 77 and later
4971 @item @emph{Syntax}:
4972 @code{RESULT = DPROD(X, Y)}
4974 @item @emph{Arguments}:
4975 @multitable @columnfractions .15 .70
4976 @item @var{X} @tab The type shall be @code{REAL}.
4977 @item @var{Y} @tab The type shall be @code{REAL}.
4980 @item @emph{Return value}:
4981 The return value is of type @code{REAL(8)}.
4983 @item @emph{Example}:
4991 end program test_dprod
4994 @item @emph{Specific names}:
4995 @multitable @columnfractions .20 .20 .20 .25
4996 @item Name @tab Argument @tab Return type @tab Standard
4997 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
5004 @section @code{DREAL} --- Double real part function
5006 @cindex complex numbers, real part
5009 @item @emph{Description}:
5010 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
5012 @item @emph{Standard}:
5018 @item @emph{Syntax}:
5019 @code{RESULT = DREAL(A)}
5021 @item @emph{Arguments}:
5022 @multitable @columnfractions .15 .70
5023 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
5026 @item @emph{Return value}:
5027 The return value is of type @code{REAL(8)}.
5029 @item @emph{Example}:
5032 complex(8) :: z = (1.3_8,7.2_8)
5034 end program test_dreal
5037 @item @emph{See also}:
5045 @section @code{DSHIFTL} --- Combined left shift
5047 @cindex left shift, combined
5051 @item @emph{Description}:
5052 @code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
5053 rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
5054 bits of @var{J}, and the remaining bits are the rightmost bits of
5057 @item @emph{Standard}:
5058 Fortran 2008 and later
5063 @item @emph{Syntax}:
5064 @code{RESULT = DSHIFTL(I, J, SHIFT)}
5066 @item @emph{Arguments}:
5067 @multitable @columnfractions .15 .70
5068 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5069 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5070 If both @var{I} and @var{J} have integer type, then they shall have
5071 the same kind type parameter. @var{I} and @var{J} shall not both be
5073 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
5074 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
5075 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
5076 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
5079 @item @emph{Return value}:
5080 If either @var{I} or @var{J} is a BOZ constant, it is first converted
5081 as if by the intrinsic function @code{INT} to an integer type with the
5082 kind type parameter of the other.
5084 @item @emph{See also}:
5090 @section @code{DSHIFTR} --- Combined right shift
5092 @cindex right shift, combined
5093 @cindex shift, right
5096 @item @emph{Description}:
5097 @code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
5098 leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
5099 bits of @var{I}, and the remaining bits are the leftmost bits of
5102 @item @emph{Standard}:
5103 Fortran 2008 and later
5108 @item @emph{Syntax}:
5109 @code{RESULT = DSHIFTR(I, J, SHIFT)}
5111 @item @emph{Arguments}:
5112 @multitable @columnfractions .15 .70
5113 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5114 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
5115 If both @var{I} and @var{J} have integer type, then they shall have
5116 the same kind type parameter. @var{I} and @var{J} shall not both be
5118 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
5119 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
5120 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
5121 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
5124 @item @emph{Return value}:
5125 If either @var{I} or @var{J} is a BOZ constant, it is first converted
5126 as if by the intrinsic function @code{INT} to an integer type with the
5127 kind type parameter of the other.
5129 @item @emph{See also}:
5135 @section @code{DTIME} --- Execution time subroutine (or function)
5137 @cindex time, elapsed
5138 @cindex elapsed time
5141 @item @emph{Description}:
5142 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
5143 since the start of the process's execution in @var{TIME}. @var{VALUES}
5144 returns the user and system components of this time in @code{VALUES(1)} and
5145 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
5148 Subsequent invocations of @code{DTIME} return values accumulated since the
5149 previous invocation.
5151 On some systems, the underlying timings are represented using types with
5152 sufficiently small limits that overflows (wrap around) are possible, such as
5153 32-bit types. Therefore, the values returned by this intrinsic might be, or
5154 become, negative, or numerically less than previous values, during a single
5155 run of the compiled program.
5157 Please note, that this implementation is thread safe if used within OpenMP
5158 directives, i.e., its state will be consistent while called from multiple
5159 threads. However, if @code{DTIME} is called from multiple threads, the result
5160 is still the time since the last invocation. This may not give the intended
5161 results. If possible, use @code{CPU_TIME} instead.
5163 This intrinsic is provided in both subroutine and function forms; however,
5164 only one form can be used in any given program unit.
5166 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
5168 @multitable @columnfractions .15 .30 .40
5169 @item @tab @code{VALUES(1)}: @tab User time in seconds.
5170 @item @tab @code{VALUES(2)}: @tab System time in seconds.
5171 @item @tab @code{TIME}: @tab Run time since start in seconds.
5174 @item @emph{Standard}:
5178 Subroutine, function
5180 @item @emph{Syntax}:
5181 @multitable @columnfractions .80
5182 @item @code{CALL DTIME(VALUES, TIME)}.
5183 @item @code{TIME = DTIME(VALUES)}, (not recommended).
5186 @item @emph{Arguments}:
5187 @multitable @columnfractions .15 .70
5188 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
5189 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
5192 @item @emph{Return value}:
5193 Elapsed time in seconds since the last invocation or since the start of program
5194 execution if not called before.
5196 @item @emph{Example}:
5200 real, dimension(2) :: tarray
5202 call dtime(tarray, result)
5206 do i=1,100000000 ! Just a delay
5209 call dtime(tarray, result)
5213 end program test_dtime
5216 @item @emph{See also}:
5224 @section @code{EOSHIFT} --- End-off shift elements of an array
5226 @cindex array, shift
5229 @item @emph{Description}:
5230 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
5231 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
5232 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
5233 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
5234 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
5235 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
5236 then all complete rank one sections of @var{ARRAY} along the given dimension are
5237 shifted. Elements shifted out one end of each rank one section are dropped. If
5238 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
5239 is copied back in the other end. If @var{BOUNDARY} is not present then the
5240 following are copied in depending on the type of @var{ARRAY}.
5242 @multitable @columnfractions .15 .80
5243 @item @emph{Array Type} @tab @emph{Boundary Value}
5244 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
5245 @item Logical @tab @code{.FALSE.}.
5246 @item Character(@var{len}) @tab @var{len} blanks.
5249 @item @emph{Standard}:
5250 Fortran 95 and later
5253 Transformational function
5255 @item @emph{Syntax}:
5256 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
5258 @item @emph{Arguments}:
5259 @multitable @columnfractions .15 .70
5260 @item @var{ARRAY} @tab May be any type, not scalar.
5261 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
5262 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
5263 @item @var{DIM} @tab The type shall be @code{INTEGER}.
5266 @item @emph{Return value}:
5267 Returns an array of same type and rank as the @var{ARRAY} argument.
5269 @item @emph{Example}:
5271 program test_eoshift
5272 integer, dimension(3,3) :: a
5273 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
5274 print '(3i3)', a(1,:)
5275 print '(3i3)', a(2,:)
5276 print '(3i3)', a(3,:)
5277 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
5279 print '(3i3)', a(1,:)
5280 print '(3i3)', a(2,:)
5281 print '(3i3)', a(3,:)
5282 end program test_eoshift
5289 @section @code{EPSILON} --- Epsilon function
5291 @cindex model representation, epsilon
5294 @item @emph{Description}:
5295 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
5296 as @var{X} such that @math{1 + E > 1}.
5298 @item @emph{Standard}:
5299 Fortran 95 and later
5304 @item @emph{Syntax}:
5305 @code{RESULT = EPSILON(X)}
5307 @item @emph{Arguments}:
5308 @multitable @columnfractions .15 .70
5309 @item @var{X} @tab The type shall be @code{REAL}.
5312 @item @emph{Return value}:
5313 The return value is of same type as the argument.
5315 @item @emph{Example}:
5317 program test_epsilon
5322 end program test_epsilon
5329 @section @code{ERF} --- Error function
5331 @cindex error function
5334 @item @emph{Description}:
5335 @code{ERF(X)} computes the error function of @var{X}.
5337 @item @emph{Standard}:
5338 Fortran 2008 and later
5343 @item @emph{Syntax}:
5344 @code{RESULT = ERF(X)}
5346 @item @emph{Arguments}:
5347 @multitable @columnfractions .15 .70
5348 @item @var{X} @tab The type shall be @code{REAL}.
5351 @item @emph{Return value}:
5352 The return value is of type @code{REAL}, of the same kind as
5353 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
5355 @item @emph{Example}:
5358 real(8) :: x = 0.17_8
5360 end program test_erf
5363 @item @emph{Specific names}:
5364 @multitable @columnfractions .20 .20 .20 .25
5365 @item Name @tab Argument @tab Return type @tab Standard
5366 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
5373 @section @code{ERFC} --- Error function
5375 @cindex error function, complementary
5378 @item @emph{Description}:
5379 @code{ERFC(X)} computes the complementary error function of @var{X}.
5381 @item @emph{Standard}:
5382 Fortran 2008 and later
5387 @item @emph{Syntax}:
5388 @code{RESULT = ERFC(X)}
5390 @item @emph{Arguments}:
5391 @multitable @columnfractions .15 .70
5392 @item @var{X} @tab The type shall be @code{REAL}.
5395 @item @emph{Return value}:
5396 The return value is of type @code{REAL} and of the same kind as @var{X}.
5397 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
5399 @item @emph{Example}:
5402 real(8) :: x = 0.17_8
5404 end program test_erfc
5407 @item @emph{Specific names}:
5408 @multitable @columnfractions .20 .20 .20 .25
5409 @item Name @tab Argument @tab Return type @tab Standard
5410 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
5417 @section @code{ERFC_SCALED} --- Error function
5418 @fnindex ERFC_SCALED
5419 @cindex error function, complementary, exponentially-scaled
5422 @item @emph{Description}:
5423 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
5424 error function of @var{X}.
5426 @item @emph{Standard}:
5427 Fortran 2008 and later
5432 @item @emph{Syntax}:
5433 @code{RESULT = ERFC_SCALED(X)}
5435 @item @emph{Arguments}:
5436 @multitable @columnfractions .15 .70
5437 @item @var{X} @tab The type shall be @code{REAL}.
5440 @item @emph{Return value}:
5441 The return value is of type @code{REAL} and of the same kind as @var{X}.
5443 @item @emph{Example}:
5445 program test_erfc_scaled
5446 real(8) :: x = 0.17_8
5448 end program test_erfc_scaled
5455 @section @code{ETIME} --- Execution time subroutine (or function)
5457 @cindex time, elapsed
5460 @item @emph{Description}:
5461 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
5462 since the start of the process's execution in @var{TIME}. @var{VALUES}
5463 returns the user and system components of this time in @code{VALUES(1)} and
5464 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
5466 On some systems, the underlying timings are represented using types with
5467 sufficiently small limits that overflows (wrap around) are possible, such as
5468 32-bit types. Therefore, the values returned by this intrinsic might be, or
5469 become, negative, or numerically less than previous values, during a single
5470 run of the compiled program.
5472 This intrinsic is provided in both subroutine and function forms; however,
5473 only one form can be used in any given program unit.
5475 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
5477 @multitable @columnfractions .15 .30 .60
5478 @item @tab @code{VALUES(1)}: @tab User time in seconds.
5479 @item @tab @code{VALUES(2)}: @tab System time in seconds.
5480 @item @tab @code{TIME}: @tab Run time since start in seconds.
5483 @item @emph{Standard}:
5487 Subroutine, function
5489 @item @emph{Syntax}:
5490 @multitable @columnfractions .80
5491 @item @code{CALL ETIME(VALUES, TIME)}.
5492 @item @code{TIME = ETIME(VALUES)}, (not recommended).
5495 @item @emph{Arguments}:
5496 @multitable @columnfractions .15 .70
5497 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
5498 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
5501 @item @emph{Return value}:
5502 Elapsed time in seconds since the start of program execution.
5504 @item @emph{Example}:
5508 real, dimension(2) :: tarray
5510 call ETIME(tarray, result)
5514 do i=1,100000000 ! Just a delay
5517 call ETIME(tarray, result)
5521 end program test_etime
5524 @item @emph{See also}:
5532 @section @code{EVENT_QUERY} --- Query whether a coarray event has occurred
5533 @fnindex EVENT_QUERY
5534 @cindex Events, EVENT_QUERY
5537 @item @emph{Description}:
5538 @code{EVENT_QUERY} assignes the number of events to @var{COUNT} which have been
5539 posted to the @var{EVENT} variable and not yet been removed by calling
5540 @code{EVENT WAIT}. When @var{STAT} is present and the invocation was successful,
5541 it is assigned the value 0. If it is present and the invocation has failed,
5542 it is assigned a positive value and @var{COUNT} is assigned the value @math{-1}.
5544 @item @emph{Standard}:
5550 @item @emph{Syntax}:
5551 @code{CALL EVENT_QUERY (EVENT, COUNT [, STAT])}
5553 @item @emph{Arguments}:
5554 @multitable @columnfractions .15 .70
5555 @item @var{EVENT} @tab (intent(IN)) Scalar of type @code{EVENT_TYPE},
5556 defined in @code{ISO_FORTRAN_ENV}; shall not be coindexed.
5557 @item @var{COUNT} @tab (intent(out))Scalar integer with at least the
5558 precision of default integer.
5559 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
5562 @item @emph{Example}:
5567 type(event_type) :: event_value_has_been_set[*]
5569 if (this_image() == 1) then
5570 call event_query (event_value_has_been_set, cnt)
5571 if (cnt > 0) write(*,*) "Value has been set"
5572 elseif (this_image() == 2) then
5573 event post (event_value_has_been_set[1])
5582 @node EXECUTE_COMMAND_LINE
5583 @section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
5584 @fnindex EXECUTE_COMMAND_LINE
5585 @cindex system, system call
5586 @cindex command line
5589 @item @emph{Description}:
5590 @code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
5593 The @code{COMMAND} argument is passed to the shell and executed, using
5594 the C library's @code{system} call. (The shell is @code{sh} on Unix
5595 systems, and @code{cmd.exe} on Windows.) If @code{WAIT} is present
5596 and has the value false, the execution of the command is asynchronous
5597 if the system supports it; otherwise, the command is executed
5600 The three last arguments allow the user to get status information. After
5601 synchronous execution, @code{EXITSTAT} contains the integer exit code of
5602 the command, as returned by @code{system}. @code{CMDSTAT} is set to zero
5603 if the command line was executed (whatever its exit status was).
5604 @code{CMDMSG} is assigned an error message if an error has occurred.
5606 Note that the @code{system} function need not be thread-safe. It is
5607 the responsibility of the user to ensure that @code{system} is not
5608 called concurrently.
5610 @item @emph{Standard}:
5611 Fortran 2008 and later
5616 @item @emph{Syntax}:
5617 @code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
5619 @item @emph{Arguments}:
5620 @multitable @columnfractions .15 .70
5621 @item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
5622 @item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
5623 @item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5625 @item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5627 @item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
5631 @item @emph{Example}:
5636 call execute_command_line ("external_prog.exe", exitstat=i)
5637 print *, "Exit status of external_prog.exe was ", i
5639 call execute_command_line ("reindex_files.exe", wait=.false.)
5640 print *, "Now reindexing files in the background"
5642 end program test_exec
5648 Because this intrinsic is implemented in terms of the @code{system}
5649 function call, its behavior with respect to signaling is processor
5650 dependent. In particular, on POSIX-compliant systems, the SIGINT and
5651 SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
5652 such, if the parent process is terminated, the child process might not be
5653 terminated alongside.
5656 @item @emph{See also}:
5663 @section @code{EXIT} --- Exit the program with status.
5665 @cindex program termination
5666 @cindex terminate program
5669 @item @emph{Description}:
5670 @code{EXIT} causes immediate termination of the program with status. If status
5671 is omitted it returns the canonical @emph{success} for the system. All Fortran
5672 I/O units are closed.
5674 @item @emph{Standard}:
5680 @item @emph{Syntax}:
5681 @code{CALL EXIT([STATUS])}
5683 @item @emph{Arguments}:
5684 @multitable @columnfractions .15 .70
5685 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
5688 @item @emph{Return value}:
5689 @code{STATUS} is passed to the parent process on exit.
5691 @item @emph{Example}:
5694 integer :: STATUS = 0
5695 print *, 'This program is going to exit.'
5697 end program test_exit
5700 @item @emph{See also}:
5701 @ref{ABORT}, @ref{KILL}
5707 @section @code{EXP} --- Exponential function
5713 @cindex exponential function
5714 @cindex logarithm function, inverse
5717 @item @emph{Description}:
5718 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
5720 @item @emph{Standard}:
5721 Fortran 77 and later, has overloads that are GNU extensions
5726 @item @emph{Syntax}:
5727 @code{RESULT = EXP(X)}
5729 @item @emph{Arguments}:
5730 @multitable @columnfractions .15 .70
5731 @item @var{X} @tab The type shall be @code{REAL} or
5735 @item @emph{Return value}:
5736 The return value has same type and kind as @var{X}.
5738 @item @emph{Example}:
5743 end program test_exp
5746 @item @emph{Specific names}:
5747 @multitable @columnfractions .20 .20 .20 .25
5748 @item Name @tab Argument @tab Return type @tab Standard
5749 @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
5750 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
5751 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
5752 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5753 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5760 @section @code{EXPONENT} --- Exponent function
5762 @cindex real number, exponent
5763 @cindex floating point, exponent
5766 @item @emph{Description}:
5767 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
5768 is zero the value returned is zero.
5770 @item @emph{Standard}:
5771 Fortran 95 and later
5776 @item @emph{Syntax}:
5777 @code{RESULT = EXPONENT(X)}
5779 @item @emph{Arguments}:
5780 @multitable @columnfractions .15 .70
5781 @item @var{X} @tab The type shall be @code{REAL}.
5784 @item @emph{Return value}:
5785 The return value is of type default @code{INTEGER}.
5787 @item @emph{Example}:
5789 program test_exponent
5794 print *, exponent(0.0)
5795 end program test_exponent
5801 @node EXTENDS_TYPE_OF
5802 @section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension
5803 @fnindex EXTENDS_TYPE_OF
5806 @item @emph{Description}:
5807 Query dynamic type for extension.
5809 @item @emph{Standard}:
5810 Fortran 2003 and later
5815 @item @emph{Syntax}:
5816 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
5818 @item @emph{Arguments}:
5819 @multitable @columnfractions .15 .70
5820 @item @var{A} @tab Shall be an object of extensible declared type or
5821 unlimited polymorphic.
5822 @item @var{MOLD} @tab Shall be an object of extensible declared type or
5823 unlimited polymorphic.
5826 @item @emph{Return value}:
5827 The return value is a scalar of type default logical. It is true if and only if
5828 the dynamic type of A is an extension type of the dynamic type of MOLD.
5831 @item @emph{See also}:
5838 @section @code{FDATE} --- Get the current time as a string
5840 @cindex time, current
5841 @cindex current time
5842 @cindex date, current
5843 @cindex current date
5846 @item @emph{Description}:
5847 @code{FDATE(DATE)} returns the current date (using the same format as
5848 @ref{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
5851 This intrinsic is provided in both subroutine and function forms; however,
5852 only one form can be used in any given program unit.
5854 @item @emph{Standard}:
5858 Subroutine, function
5860 @item @emph{Syntax}:
5861 @multitable @columnfractions .80
5862 @item @code{CALL FDATE(DATE)}.
5863 @item @code{DATE = FDATE()}.
5866 @item @emph{Arguments}:
5867 @multitable @columnfractions .15 .70
5868 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
5869 default kind. It is an @code{INTENT(OUT)} argument. If the length of
5870 this variable is too short for the date and time string to fit
5871 completely, it will be blank on procedure return.
5874 @item @emph{Return value}:
5875 The current date and time as a string.
5877 @item @emph{Example}:
5881 character(len=30) :: date
5883 print *, 'Program started on ', date
5884 do i = 1, 100000000 ! Just a delay
5888 print *, 'Program ended on ', date
5889 end program test_fdate
5892 @item @emph{See also}:
5893 @ref{DATE_AND_TIME}, @ref{CTIME}
5898 @section @code{FGET} --- Read a single character in stream mode from stdin
5900 @cindex read character, stream mode
5901 @cindex stream mode, read character
5902 @cindex file operation, read character
5905 @item @emph{Description}:
5906 Read a single character in stream mode from stdin by bypassing normal
5907 formatted output. Stream I/O should not be mixed with normal record-oriented
5908 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
5910 This intrinsic is provided in both subroutine and function forms; however,
5911 only one form can be used in any given program unit.
5913 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
5914 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5915 Programmers should consider the use of new stream IO feature in new code
5916 for future portability. See also @ref{Fortran 2003 status}.
5918 @item @emph{Standard}:
5922 Subroutine, function
5924 @item @emph{Syntax}:
5925 @multitable @columnfractions .80
5926 @item @code{CALL FGET(C [, STATUS])}
5927 @item @code{STATUS = FGET(C)}
5930 @item @emph{Arguments}:
5931 @multitable @columnfractions .15 .70
5932 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5934 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5935 Returns 0 on success, -1 on end-of-file, and a system specific positive
5936 error code otherwise.
5939 @item @emph{Example}:
5942 INTEGER, PARAMETER :: strlen = 100
5943 INTEGER :: status, i = 1
5944 CHARACTER(len=strlen) :: str = ""
5946 WRITE (*,*) 'Enter text:'
5948 CALL fget(str(i:i), status)
5949 if (status /= 0 .OR. i > strlen) exit
5952 WRITE (*,*) TRIM(str)
5956 @item @emph{See also}:
5957 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
5963 @section @code{FGETC} --- Read a single character in stream mode
5965 @cindex read character, stream mode
5966 @cindex stream mode, read character
5967 @cindex file operation, read character
5970 @item @emph{Description}:
5971 Read a single character in stream mode by bypassing normal formatted output.
5972 Stream I/O should not be mixed with normal record-oriented (formatted or
5973 unformatted) I/O on the same unit; the results are unpredictable.
5975 This intrinsic is provided in both subroutine and function forms; however,
5976 only one form can be used in any given program unit.
5978 Note that the @code{FGET} intrinsic is provided for backwards compatibility
5979 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5980 Programmers should consider the use of new stream IO feature in new code
5981 for future portability. See also @ref{Fortran 2003 status}.
5983 @item @emph{Standard}:
5987 Subroutine, function
5989 @item @emph{Syntax}:
5990 @multitable @columnfractions .80
5991 @item @code{CALL FGETC(UNIT, C [, STATUS])}
5992 @item @code{STATUS = FGETC(UNIT, C)}
5995 @item @emph{Arguments}:
5996 @multitable @columnfractions .15 .70
5997 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
5998 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6000 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6001 Returns 0 on success, -1 on end-of-file and a system specific positive
6002 error code otherwise.
6005 @item @emph{Example}:
6008 INTEGER :: fd = 42, status
6011 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
6013 CALL fgetc(fd, c, status)
6014 IF (status /= 0) EXIT
6021 @item @emph{See also}:
6022 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
6026 @section @code{FINDLOC} --- Search an array for a value
6031 @item @emph{Description}:
6032 Determines the location of the element in the array with the value
6033 given in the @var{VALUE} argument, or, if the @var{DIM} argument is
6034 supplied, determines the locations of the maximum element along each
6035 row of the array in the @var{DIM} direction. If @var{MASK} is
6036 present, only the elements for which @var{MASK} is @code{.TRUE.} are
6037 considered. If more than one element in the array has the value
6038 @var{VALUE}, the location returned is that of the first such element
6039 in array element order if the @var{BACK} is not present or if it is
6040 @code{.FALSE.}. If @var{BACK} is true, the location returned is that
6041 of the last such element. If the array has zero size, or all of the
6042 elements of @var{MASK} are @code{.FALSE.}, then the result is an array
6043 of zeroes. Similarly, if @var{DIM} is supplied and all of the
6044 elements of @var{MASK} along a given row are zero, the result value
6045 for that row is zero.
6047 @item @emph{Standard}:
6048 Fortran 2008 and later.
6051 Transformational function
6053 @item @emph{Syntax}:
6054 @multitable @columnfractions .80
6055 @item @code{RESULT = FINDLOC(ARRAY, VALUE, DIM [, MASK] [,KIND] [,BACK])}
6056 @item @code{RESULT = FINDLOC(ARRAY, VALUE, [, MASK] [,KIND] [,BACK])}
6059 @item @emph{Arguments}:
6060 @multitable @columnfractions .15 .70
6061 @item @var{ARRAY} @tab Shall be an array of intrinsic type.
6062 @item @var{VALUE} @tab A scalar of intrinsic type which is in type
6063 conformance with @var{ARRAY}.
6064 @item @var{DIM} @tab (Optional) Shall be a scalar of type
6065 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
6066 inclusive. It may not be an optional dummy argument.
6067 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6068 expression indicating the kind parameter of the result.
6069 @item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}.
6072 @item @emph{Return value}:
6073 If @var{DIM} is absent, the result is a rank-one array with a length
6074 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
6075 is an array with a rank one less than the rank of @var{ARRAY}, and a
6076 size corresponding to the size of @var{ARRAY} with the @var{DIM}
6077 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
6078 of one, the result is a scalar. If the optional argument @var{KIND}
6079 is present, the result is an integer of kind @var{KIND}, otherwise it
6082 @item @emph{See also}:
6083 @ref{MAXLOC}, @ref{MINLOC}
6088 @section @code{FLOOR} --- Integer floor function
6091 @cindex rounding, floor
6094 @item @emph{Description}:
6095 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
6097 @item @emph{Standard}:
6098 Fortran 95 and later
6103 @item @emph{Syntax}:
6104 @code{RESULT = FLOOR(A [, KIND])}
6106 @item @emph{Arguments}:
6107 @multitable @columnfractions .15 .70
6108 @item @var{A} @tab The type shall be @code{REAL}.
6109 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6110 expression indicating the kind parameter of the result.
6113 @item @emph{Return value}:
6114 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
6115 and of default-kind @code{INTEGER} otherwise.
6117 @item @emph{Example}:
6122 print *, floor(x) ! returns 63
6123 print *, floor(y) ! returns -64
6124 end program test_floor
6127 @item @emph{See also}:
6128 @ref{CEILING}, @ref{NINT}
6135 @section @code{FLUSH} --- Flush I/O unit(s)
6137 @cindex file operation, flush
6140 @item @emph{Description}:
6141 Flushes Fortran unit(s) currently open for output. Without the optional
6142 argument, all units are flushed, otherwise just the unit specified.
6144 @item @emph{Standard}:
6150 @item @emph{Syntax}:
6151 @code{CALL FLUSH(UNIT)}
6153 @item @emph{Arguments}:
6154 @multitable @columnfractions .15 .70
6155 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
6159 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
6160 statement that should be preferred over the @code{FLUSH} intrinsic.
6162 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
6163 have identical effect: they flush the runtime library's I/O buffer so
6164 that the data becomes visible to other processes. This does not guarantee
6165 that the data is committed to disk.
6167 On POSIX systems, you can request that all data is transferred to the
6168 storage device by calling the @code{fsync} function, with the POSIX file
6169 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
6170 @code{FNUM}). The following example shows how:
6173 ! Declare the interface for POSIX fsync function
6175 function fsync (fd) bind(c,name="fsync")
6176 use iso_c_binding, only: c_int
6177 integer(c_int), value :: fd
6178 integer(c_int) :: fsync
6182 ! Variable declaration
6186 open (10,file="foo")
6189 ! Perform I/O on unit 10
6194 ret = fsync(fnum(10))
6196 ! Handle possible error
6197 if (ret /= 0) stop "Error calling FSYNC"
6205 @section @code{FNUM} --- File number function
6207 @cindex file operation, file number
6210 @item @emph{Description}:
6211 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
6212 open Fortran I/O unit @code{UNIT}.
6214 @item @emph{Standard}:
6220 @item @emph{Syntax}:
6221 @code{RESULT = FNUM(UNIT)}
6223 @item @emph{Arguments}:
6224 @multitable @columnfractions .15 .70
6225 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
6228 @item @emph{Return value}:
6229 The return value is of type @code{INTEGER}
6231 @item @emph{Example}:
6235 open (unit=10, status = "scratch")
6239 end program test_fnum
6246 @section @code{FPUT} --- Write a single character in stream mode to stdout
6248 @cindex write character, stream mode
6249 @cindex stream mode, write character
6250 @cindex file operation, write character
6253 @item @emph{Description}:
6254 Write a single character in stream mode to stdout by bypassing normal
6255 formatted output. Stream I/O should not be mixed with normal record-oriented
6256 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
6258 This intrinsic is provided in both subroutine and function forms; however,
6259 only one form can be used in any given program unit.
6261 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
6262 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
6263 Programmers should consider the use of new stream IO feature in new code
6264 for future portability. See also @ref{Fortran 2003 status}.
6266 @item @emph{Standard}:
6270 Subroutine, function
6272 @item @emph{Syntax}:
6273 @multitable @columnfractions .80
6274 @item @code{CALL FPUT(C [, STATUS])}
6275 @item @code{STATUS = FPUT(C)}
6278 @item @emph{Arguments}:
6279 @multitable @columnfractions .15 .70
6280 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6282 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6283 Returns 0 on success, -1 on end-of-file and a system specific positive
6284 error code otherwise.
6287 @item @emph{Example}:
6290 CHARACTER(len=10) :: str = "gfortran"
6292 DO i = 1, len_trim(str)
6298 @item @emph{See also}:
6299 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
6305 @section @code{FPUTC} --- Write a single character in stream mode
6307 @cindex write character, stream mode
6308 @cindex stream mode, write character
6309 @cindex file operation, write character
6312 @item @emph{Description}:
6313 Write a single character in stream mode by bypassing normal formatted
6314 output. Stream I/O should not be mixed with normal record-oriented
6315 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
6317 This intrinsic is provided in both subroutine and function forms; however,
6318 only one form can be used in any given program unit.
6320 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
6321 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
6322 Programmers should consider the use of new stream IO feature in new code
6323 for future portability. See also @ref{Fortran 2003 status}.
6325 @item @emph{Standard}:
6329 Subroutine, function
6331 @item @emph{Syntax}:
6332 @multitable @columnfractions .80
6333 @item @code{CALL FPUTC(UNIT, C [, STATUS])}
6334 @item @code{STATUS = FPUTC(UNIT, C)}
6337 @item @emph{Arguments}:
6338 @multitable @columnfractions .15 .70
6339 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
6340 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
6342 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6343 Returns 0 on success, -1 on end-of-file and a system specific positive
6344 error code otherwise.
6347 @item @emph{Example}:
6350 CHARACTER(len=10) :: str = "gfortran"
6351 INTEGER :: fd = 42, i
6353 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
6354 DO i = 1, len_trim(str)
6355 CALL fputc(fd, str(i:i))
6361 @item @emph{See also}:
6362 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
6368 @section @code{FRACTION} --- Fractional part of the model representation
6370 @cindex real number, fraction
6371 @cindex floating point, fraction
6374 @item @emph{Description}:
6375 @code{FRACTION(X)} returns the fractional part of the model
6376 representation of @code{X}.
6378 @item @emph{Standard}:
6379 Fortran 95 and later
6384 @item @emph{Syntax}:
6385 @code{Y = FRACTION(X)}
6387 @item @emph{Arguments}:
6388 @multitable @columnfractions .15 .70
6389 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
6392 @item @emph{Return value}:
6393 The return value is of the same type and kind as the argument.
6394 The fractional part of the model representation of @code{X} is returned;
6395 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
6397 @item @emph{Example}:
6399 program test_fraction
6402 print *, fraction(x), x * radix(x)**(-exponent(x))
6403 end program test_fraction
6411 @section @code{FREE} --- Frees memory
6413 @cindex pointer, cray
6416 @item @emph{Description}:
6417 Frees memory previously allocated by @code{MALLOC}. The @code{FREE}
6418 intrinsic is an extension intended to be used with Cray pointers, and is
6419 provided in GNU Fortran to allow user to compile legacy code. For
6420 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
6423 @item @emph{Standard}:
6429 @item @emph{Syntax}:
6430 @code{CALL FREE(PTR)}
6432 @item @emph{Arguments}:
6433 @multitable @columnfractions .15 .70
6434 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
6435 location of the memory that should be de-allocated.
6438 @item @emph{Return value}:
6441 @item @emph{Example}:
6442 See @code{MALLOC} for an example.
6444 @item @emph{See also}:
6451 @section @code{FSEEK} --- Low level file positioning subroutine
6453 @cindex file operation, seek
6454 @cindex file operation, position
6457 @item @emph{Description}:
6458 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
6459 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
6460 if set to 1, @var{OFFSET} is taken to be relative to the current position
6461 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
6462 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
6465 This intrinsic routine is not fully backwards compatible with @command{g77}.
6466 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
6467 @var{STATUS} variable. If FSEEK is used in old code, change
6469 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
6474 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
6475 IF (status /= 0) GOTO label
6478 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
6479 Programmers should consider the use of new stream IO feature in new code
6480 for future portability. See also @ref{Fortran 2003 status}.
6482 @item @emph{Standard}:
6488 @item @emph{Syntax}:
6489 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
6491 @item @emph{Arguments}:
6492 @multitable @columnfractions .15 .70
6493 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
6494 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
6495 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
6496 Its value shall be either 0, 1 or 2.
6497 @item @var{STATUS} @tab (Optional) shall be a scalar of type
6501 @item @emph{Example}:
6504 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
6505 INTEGER :: fd, offset, ierr
6511 OPEN(UNIT=fd, FILE="fseek.test")
6512 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
6513 print *, FTELL(fd), ierr
6515 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
6516 print *, FTELL(fd), ierr
6518 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
6519 print *, FTELL(fd), ierr
6525 @item @emph{See also}:
6532 @section @code{FSTAT} --- Get file status
6534 @cindex file system, file status
6537 @item @emph{Description}:
6538 @code{FSTAT} is identical to @ref{STAT}, except that information about an
6539 already opened file is obtained.
6541 The elements in @code{VALUES} are the same as described by @ref{STAT}.
6543 This intrinsic is provided in both subroutine and function forms; however,
6544 only one form can be used in any given program unit.
6546 @item @emph{Standard}:
6550 Subroutine, function
6552 @item @emph{Syntax}:
6553 @multitable @columnfractions .80
6554 @item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
6555 @item @code{STATUS = FSTAT(UNIT, VALUES)}
6558 @item @emph{Arguments}:
6559 @multitable @columnfractions .15 .70
6560 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
6561 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
6562 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
6563 on success and a system specific error code otherwise.
6566 @item @emph{Example}:
6567 See @ref{STAT} for an example.
6569 @item @emph{See also}:
6570 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
6576 @section @code{FTELL} --- Current stream position
6578 @cindex file operation, position
6581 @item @emph{Description}:
6582 Retrieves the current position within an open file.
6584 This intrinsic is provided in both subroutine and function forms; however,
6585 only one form can be used in any given program unit.
6587 @item @emph{Standard}:
6591 Subroutine, function
6593 @item @emph{Syntax}:
6594 @multitable @columnfractions .80
6595 @item @code{CALL FTELL(UNIT, OFFSET)}
6596 @item @code{OFFSET = FTELL(UNIT)}
6599 @item @emph{Arguments}:
6600 @multitable @columnfractions .15 .70
6601 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
6602 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
6605 @item @emph{Return value}:
6606 In either syntax, @var{OFFSET} is set to the current offset of unit
6607 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
6609 @item @emph{Example}:
6613 OPEN(10, FILE="temp.dat")
6619 @item @emph{See also}:
6626 @section @code{GAMMA} --- Gamma function
6629 @cindex Gamma function
6630 @cindex Factorial function
6633 @item @emph{Description}:
6634 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
6635 integer values of @var{X} the Gamma function simplifies to the factorial
6636 function @math{\Gamma(x)=(x-1)!}.
6640 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
6644 @item @emph{Standard}:
6645 Fortran 2008 and later
6650 @item @emph{Syntax}:
6653 @item @emph{Arguments}:
6654 @multitable @columnfractions .15 .70
6655 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
6656 nor a negative integer.
6659 @item @emph{Return value}:
6660 The return value is of type @code{REAL} of the same kind as @var{X}.
6662 @item @emph{Example}:
6666 x = gamma(x) ! returns 1.0
6667 end program test_gamma
6670 @item @emph{Specific names}:
6671 @multitable @columnfractions .20 .20 .20 .25
6672 @item Name @tab Argument @tab Return type @tab Standard
6673 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
6674 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
6677 @item @emph{See also}:
6678 Logarithm of the Gamma function: @ref{LOG_GAMMA}
6685 @section @code{GERROR} --- Get last system error message
6687 @cindex system, error handling
6690 @item @emph{Description}:
6691 Returns the system error message corresponding to the last system error.
6692 This resembles the functionality of @code{strerror(3)} in C.
6694 @item @emph{Standard}:
6700 @item @emph{Syntax}:
6701 @code{CALL GERROR(RESULT)}
6703 @item @emph{Arguments}:
6704 @multitable @columnfractions .15 .70
6705 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
6708 @item @emph{Example}:
6711 CHARACTER(len=100) :: msg
6717 @item @emph{See also}:
6718 @ref{IERRNO}, @ref{PERROR}
6724 @section @code{GETARG} --- Get command line arguments
6726 @cindex command-line arguments
6727 @cindex arguments, to program
6730 @item @emph{Description}:
6731 Retrieve the @var{POS}-th argument that was passed on the
6732 command line when the containing program was invoked.
6734 This intrinsic routine is provided for backwards compatibility with
6735 GNU Fortran 77. In new code, programmers should consider the use of
6736 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
6739 @item @emph{Standard}:
6745 @item @emph{Syntax}:
6746 @code{CALL GETARG(POS, VALUE)}
6748 @item @emph{Arguments}:
6749 @multitable @columnfractions .15 .70
6750 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
6751 the default integer kind; @math{@var{POS} \geq 0}
6752 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
6754 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
6757 @item @emph{Return value}:
6758 After @code{GETARG} returns, the @var{VALUE} argument holds the
6759 @var{POS}th command line argument. If @var{VALUE} can not hold the
6760 argument, it is truncated to fit the length of @var{VALUE}. If there are
6761 less than @var{POS} arguments specified at the command line, @var{VALUE}
6762 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
6763 to the name of the program (on systems that support this feature).
6765 @item @emph{Example}:
6769 CHARACTER(len=32) :: arg
6778 @item @emph{See also}:
6779 GNU Fortran 77 compatibility function: @ref{IARGC}
6781 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
6782 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6788 @section @code{GET_COMMAND} --- Get the entire command line
6789 @fnindex GET_COMMAND
6790 @cindex command-line arguments
6791 @cindex arguments, to program
6794 @item @emph{Description}:
6795 Retrieve the entire command line that was used to invoke the program.
6797 @item @emph{Standard}:
6798 Fortran 2003 and later
6803 @item @emph{Syntax}:
6804 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
6806 @item @emph{Arguments}:
6807 @multitable @columnfractions .15 .70
6808 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
6810 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
6812 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
6816 @item @emph{Return value}:
6817 If @var{COMMAND} is present, stores the entire command line that was used
6818 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
6819 assigned the length of the command line. If @var{STATUS} is present, it
6820 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
6821 short to store the command line, or a positive value in case of an error.
6823 @item @emph{Example}:
6825 PROGRAM test_get_command
6826 CHARACTER(len=255) :: cmd
6827 CALL get_command(cmd)
6828 WRITE (*,*) TRIM(cmd)
6832 @item @emph{See also}:
6833 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6838 @node GET_COMMAND_ARGUMENT
6839 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
6840 @fnindex GET_COMMAND_ARGUMENT
6841 @cindex command-line arguments
6842 @cindex arguments, to program
6845 @item @emph{Description}:
6846 Retrieve the @var{NUMBER}-th argument that was passed on the
6847 command line when the containing program was invoked.
6849 @item @emph{Standard}:
6850 Fortran 2003 and later
6855 @item @emph{Syntax}:
6856 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
6858 @item @emph{Arguments}:
6859 @multitable @columnfractions .15 .70
6860 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
6861 default kind, @math{@var{NUMBER} \geq 0}
6862 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
6863 and of default kind.
6864 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6865 and of default kind.
6866 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6867 and of default kind.
6870 @item @emph{Return value}:
6871 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
6872 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
6873 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
6874 arguments specified at the command line, @var{VALUE} will be filled with blanks.
6875 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
6876 systems that support this feature). The @var{LENGTH} argument contains the
6877 length of the @var{NUMBER}-th command line argument. If the argument retrieval
6878 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
6879 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
6882 @item @emph{Example}:
6884 PROGRAM test_get_command_argument
6886 CHARACTER(len=32) :: arg
6890 CALL get_command_argument(i, arg)
6891 IF (LEN_TRIM(arg) == 0) EXIT
6893 WRITE (*,*) TRIM(arg)
6899 @item @emph{See also}:
6900 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
6906 @section @code{GETCWD} --- Get current working directory
6908 @cindex system, working directory
6911 @item @emph{Description}:
6912 Get current working directory.
6914 This intrinsic is provided in both subroutine and function forms; however,
6915 only one form can be used in any given program unit.
6917 @item @emph{Standard}:
6921 Subroutine, function
6923 @item @emph{Syntax}:
6924 @multitable @columnfractions .80
6925 @item @code{CALL GETCWD(C [, STATUS])}
6926 @item @code{STATUS = GETCWD(C)}
6929 @item @emph{Arguments}:
6930 @multitable @columnfractions .15 .70
6931 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
6932 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
6933 a system specific and nonzero error code otherwise.
6936 @item @emph{Example}:
6939 CHARACTER(len=255) :: cwd
6941 WRITE(*,*) TRIM(cwd)
6945 @item @emph{See also}:
6952 @section @code{GETENV} --- Get an environmental variable
6954 @cindex environment variable
6957 @item @emph{Description}:
6958 Get the @var{VALUE} of the environmental variable @var{NAME}.
6960 This intrinsic routine is provided for backwards compatibility with
6961 GNU Fortran 77. In new code, programmers should consider the use of
6962 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
6965 Note that @code{GETENV} need not be thread-safe. It is the
6966 responsibility of the user to ensure that the environment is not being
6967 updated concurrently with a call to the @code{GETENV} intrinsic.
6969 @item @emph{Standard}:
6975 @item @emph{Syntax}:
6976 @code{CALL GETENV(NAME, VALUE)}
6978 @item @emph{Arguments}:
6979 @multitable @columnfractions .15 .70
6980 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
6981 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
6984 @item @emph{Return value}:
6985 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
6986 not large enough to hold the data, it is truncated. If @var{NAME}
6987 is not set, @var{VALUE} will be filled with blanks.
6989 @item @emph{Example}:
6992 CHARACTER(len=255) :: homedir
6993 CALL getenv("HOME", homedir)
6994 WRITE (*,*) TRIM(homedir)
6998 @item @emph{See also}:
6999 @ref{GET_ENVIRONMENT_VARIABLE}
7004 @node GET_ENVIRONMENT_VARIABLE
7005 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
7006 @fnindex GET_ENVIRONMENT_VARIABLE
7007 @cindex environment variable
7010 @item @emph{Description}:
7011 Get the @var{VALUE} of the environmental variable @var{NAME}.
7013 Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It
7014 is the responsibility of the user to ensure that the environment is
7015 not being updated concurrently with a call to the
7016 @code{GET_ENVIRONMENT_VARIABLE} intrinsic.
7018 @item @emph{Standard}:
7019 Fortran 2003 and later
7024 @item @emph{Syntax}:
7025 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
7027 @item @emph{Arguments}:
7028 @multitable @columnfractions .15 .70
7029 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
7030 and of default kind.
7031 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
7032 and of default kind.
7033 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
7034 and of default kind.
7035 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
7036 and of default kind.
7037 @item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL}
7038 and of default kind.
7041 @item @emph{Return value}:
7042 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
7043 not large enough to hold the data, it is truncated. If @var{NAME}
7044 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
7045 contains the length needed for storing the environment variable @var{NAME}
7046 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
7047 but too short for the environment variable; it is 1 if the environment
7048 variable does not exist and 2 if the processor does not support environment
7049 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
7050 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
7051 are significant; otherwise they are not part of the environment variable
7054 @item @emph{Example}:
7057 CHARACTER(len=255) :: homedir
7058 CALL get_environment_variable("HOME", homedir)
7059 WRITE (*,*) TRIM(homedir)
7067 @section @code{GETGID} --- Group ID function
7069 @cindex system, group ID
7072 @item @emph{Description}:
7073 Returns the numerical group ID of the current process.
7075 @item @emph{Standard}:
7081 @item @emph{Syntax}:
7082 @code{RESULT = GETGID()}
7084 @item @emph{Return value}:
7085 The return value of @code{GETGID} is an @code{INTEGER} of the default
7089 @item @emph{Example}:
7090 See @code{GETPID} for an example.
7092 @item @emph{See also}:
7093 @ref{GETPID}, @ref{GETUID}
7099 @section @code{GETLOG} --- Get login name
7101 @cindex system, login name
7105 @item @emph{Description}:
7106 Gets the username under which the program is running.
7108 @item @emph{Standard}:
7114 @item @emph{Syntax}:
7115 @code{CALL GETLOG(C)}
7117 @item @emph{Arguments}:
7118 @multitable @columnfractions .15 .70
7119 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
7122 @item @emph{Return value}:
7123 Stores the current user name in @var{LOGIN}. (On systems where POSIX
7124 functions @code{geteuid} and @code{getpwuid} are not available, and
7125 the @code{getlogin} function is not implemented either, this will
7126 return a blank string.)
7128 @item @emph{Example}:
7131 CHARACTER(32) :: login
7137 @item @emph{See also}:
7144 @section @code{GETPID} --- Process ID function
7146 @cindex system, process ID
7150 @item @emph{Description}:
7151 Returns the numerical process identifier of the current process.
7153 @item @emph{Standard}:
7159 @item @emph{Syntax}:
7160 @code{RESULT = GETPID()}
7162 @item @emph{Return value}:
7163 The return value of @code{GETPID} is an @code{INTEGER} of the default
7167 @item @emph{Example}:
7170 print *, "The current process ID is ", getpid()
7171 print *, "Your numerical user ID is ", getuid()
7172 print *, "Your numerical group ID is ", getgid()
7176 @item @emph{See also}:
7177 @ref{GETGID}, @ref{GETUID}
7183 @section @code{GETUID} --- User ID function
7185 @cindex system, user ID
7189 @item @emph{Description}:
7190 Returns the numerical user ID of the current process.
7192 @item @emph{Standard}:
7198 @item @emph{Syntax}:
7199 @code{RESULT = GETUID()}
7201 @item @emph{Return value}:
7202 The return value of @code{GETUID} is an @code{INTEGER} of the default
7206 @item @emph{Example}:
7207 See @code{GETPID} for an example.
7209 @item @emph{See also}:
7210 @ref{GETPID}, @ref{GETLOG}
7216 @section @code{GMTIME} --- Convert time to GMT info
7218 @cindex time, conversion to GMT info
7221 @item @emph{Description}:
7222 Given a system time value @var{TIME} (as provided by the @ref{TIME}
7223 intrinsic), fills @var{VALUES} with values extracted from it appropriate
7224 to the UTC time zone (Universal Coordinated Time, also known in some
7225 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
7227 This intrinsic routine is provided for backwards compatibility with
7228 GNU Fortran 77. In new code, programmers should consider the use of
7229 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
7232 @item @emph{Standard}:
7238 @item @emph{Syntax}:
7239 @code{CALL GMTIME(TIME, VALUES)}
7241 @item @emph{Arguments}:
7242 @multitable @columnfractions .15 .70
7243 @item @var{TIME} @tab An @code{INTEGER} scalar expression
7244 corresponding to a system time, with @code{INTENT(IN)}.
7245 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
7246 with @code{INTENT(OUT)}.
7249 @item @emph{Return value}:
7250 The elements of @var{VALUES} are assigned as follows:
7252 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
7254 @item Minutes after the hour, range 0--59
7255 @item Hours past midnight, range 0--23
7256 @item Day of month, range 1--31
7257 @item Number of months since January, range 0--11
7258 @item Years since 1900
7259 @item Number of days since Sunday, range 0--6
7260 @item Days since January 1, range 0--365
7261 @item Daylight savings indicator: positive if daylight savings is in
7262 effect, zero if not, and negative if the information is not available.
7265 @item @emph{See also}:
7266 @ref{DATE_AND_TIME}, @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
7273 @section @code{HOSTNM} --- Get system host name
7275 @cindex system, host name
7278 @item @emph{Description}:
7279 Retrieves the host name of the system on which the program is running.
7281 This intrinsic is provided in both subroutine and function forms; however,
7282 only one form can be used in any given program unit.
7284 @item @emph{Standard}:
7288 Subroutine, function
7290 @item @emph{Syntax}:
7291 @multitable @columnfractions .80
7292 @item @code{CALL HOSTNM(C [, STATUS])}
7293 @item @code{STATUS = HOSTNM(NAME)}
7296 @item @emph{Arguments}:
7297 @multitable @columnfractions .15 .70
7298 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
7299 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
7300 Returns 0 on success, or a system specific error code otherwise.
7303 @item @emph{Return value}:
7304 In either syntax, @var{NAME} is set to the current hostname if it can
7305 be obtained, or to a blank string otherwise.
7312 @section @code{HUGE} --- Largest number of a kind
7314 @cindex limits, largest number
7315 @cindex model representation, largest number
7318 @item @emph{Description}:
7319 @code{HUGE(X)} returns the largest number that is not an infinity in
7320 the model of the type of @code{X}.
7322 @item @emph{Standard}:
7323 Fortran 95 and later
7328 @item @emph{Syntax}:
7329 @code{RESULT = HUGE(X)}
7331 @item @emph{Arguments}:
7332 @multitable @columnfractions .15 .70
7333 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
7336 @item @emph{Return value}:
7337 The return value is of the same type and kind as @var{X}
7339 @item @emph{Example}:
7341 program test_huge_tiny
7342 print *, huge(0), huge(0.0), huge(0.0d0)
7343 print *, tiny(0.0), tiny(0.0d0)
7344 end program test_huge_tiny
7351 @section @code{HYPOT} --- Euclidean distance function
7353 @cindex Euclidean distance
7356 @item @emph{Description}:
7357 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
7358 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
7360 @item @emph{Standard}:
7361 Fortran 2008 and later
7366 @item @emph{Syntax}:
7367 @code{RESULT = HYPOT(X, Y)}
7369 @item @emph{Arguments}:
7370 @multitable @columnfractions .15 .70
7371 @item @var{X} @tab The type shall be @code{REAL}.
7372 @item @var{Y} @tab The type and kind type parameter shall be the same as
7376 @item @emph{Return value}:
7377 The return value has the same type and kind type parameter as @var{X}.
7379 @item @emph{Example}:
7382 real(4) :: x = 1.e0_4, y = 0.5e0_4
7384 end program test_hypot
7391 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
7393 @cindex @acronym{ASCII} collating sequence
7394 @cindex collating sequence, @acronym{ASCII}
7395 @cindex conversion, to integer
7398 @item @emph{Description}:
7399 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
7400 in the first character position of @code{C}.
7402 @item @emph{Standard}:
7403 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7408 @item @emph{Syntax}:
7409 @code{RESULT = IACHAR(C [, KIND])}
7411 @item @emph{Arguments}:
7412 @multitable @columnfractions .15 .70
7413 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
7414 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7415 expression indicating the kind parameter of the result.
7418 @item @emph{Return value}:
7419 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7420 @var{KIND} is absent, the return value is of default integer kind.
7422 @item @emph{Example}:
7427 end program test_iachar
7431 See @ref{ICHAR} for a discussion of converting between numerical values
7432 and formatted string representations.
7434 @item @emph{See also}:
7435 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
7442 @section @code{IALL} --- Bitwise AND of array elements
7445 @cindex bits, AND of array elements
7448 @item @emph{Description}:
7449 Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
7450 if the corresponding element in @var{MASK} is @code{TRUE}.
7452 @item @emph{Standard}:
7453 Fortran 2008 and later
7456 Transformational function
7458 @item @emph{Syntax}:
7459 @multitable @columnfractions .80
7460 @item @code{RESULT = IALL(ARRAY[, MASK])}
7461 @item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
7464 @item @emph{Arguments}:
7465 @multitable @columnfractions .15 .70
7466 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7467 @item @var{DIM} @tab (Optional) shall be a scalar of type
7468 @code{INTEGER} with a value in the range from 1 to n, where n
7469 equals the rank of @var{ARRAY}.
7470 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
7471 and either be a scalar or an array of the same shape as @var{ARRAY}.
7474 @item @emph{Return value}:
7475 The result is of the same type as @var{ARRAY}.
7477 If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
7478 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7479 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7480 dimension @var{DIM} dropped is returned.
7482 @item @emph{Example}:
7491 PRINT '(b8.8)', IALL(a)
7495 @item @emph{See also}:
7496 @ref{IANY}, @ref{IPARITY}, @ref{IAND}
7502 @section @code{IAND} --- Bitwise logical and
7508 @cindex bitwise logical and
7509 @cindex logical and, bitwise
7512 @item @emph{Description}:
7513 Bitwise logical @code{AND}.
7515 @item @emph{Standard}:
7516 Fortran 95 and later, has overloads that are GNU extensions
7521 @item @emph{Syntax}:
7522 @code{RESULT = IAND(I, J)}
7524 @item @emph{Arguments}:
7525 @multitable @columnfractions .15 .70
7526 @item @var{I} @tab The type shall be @code{INTEGER}.
7527 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
7528 kind as @var{I}. (As a GNU extension, different kinds are also
7532 @item @emph{Return value}:
7533 The return type is @code{INTEGER}, of the same kind as the
7534 arguments. (If the argument kinds differ, it is of the same kind as
7535 the larger argument.)
7537 @item @emph{Example}:
7541 DATA a / Z'F' /, b / Z'3' /
7542 WRITE (*,*) IAND(a, b)
7546 @item @emph{Specific names}:
7547 @multitable @columnfractions .20 .20 .20 .25
7548 @item Name @tab Argument @tab Return type @tab Standard
7549 @item @code{IAND(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7550 @item @code{BIAND(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7551 @item @code{IIAND(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7552 @item @code{JIAND(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7553 @item @code{KIAND(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7556 @item @emph{See also}:
7557 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
7564 @section @code{IANY} --- Bitwise OR of array elements
7567 @cindex bits, OR of array elements
7570 @item @emph{Description}:
7571 Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
7572 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
7574 @item @emph{Standard}:
7575 Fortran 2008 and later
7578 Transformational function
7580 @item @emph{Syntax}:
7581 @multitable @columnfractions .80
7582 @item @code{RESULT = IANY(ARRAY[, MASK])}
7583 @item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
7586 @item @emph{Arguments}:
7587 @multitable @columnfractions .15 .70
7588 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7589 @item @var{DIM} @tab (Optional) shall be a scalar of type
7590 @code{INTEGER} with a value in the range from 1 to n, where n
7591 equals the rank of @var{ARRAY}.
7592 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
7593 and either be a scalar or an array of the same shape as @var{ARRAY}.
7596 @item @emph{Return value}:
7597 The result is of the same type as @var{ARRAY}.
7599 If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
7600 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7601 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7602 dimension @var{DIM} dropped is returned.
7604 @item @emph{Example}:
7613 PRINT '(b8.8)', IANY(a)
7617 @item @emph{See also}:
7618 @ref{IPARITY}, @ref{IALL}, @ref{IOR}
7624 @section @code{IARGC} --- Get the number of command line arguments
7626 @cindex command-line arguments
7627 @cindex command-line arguments, number of
7628 @cindex arguments, to program
7631 @item @emph{Description}:
7632 @code{IARGC} returns the number of arguments passed on the
7633 command line when the containing program was invoked.
7635 This intrinsic routine is provided for backwards compatibility with
7636 GNU Fortran 77. In new code, programmers should consider the use of
7637 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
7640 @item @emph{Standard}:
7646 @item @emph{Syntax}:
7647 @code{RESULT = IARGC()}
7649 @item @emph{Arguments}:
7652 @item @emph{Return value}:
7653 The number of command line arguments, type @code{INTEGER(4)}.
7655 @item @emph{Example}:
7658 @item @emph{See also}:
7659 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
7661 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
7662 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
7668 @section @code{IBCLR} --- Clear bit
7678 @item @emph{Description}:
7679 @code{IBCLR} returns the value of @var{I} with the bit at position
7680 @var{POS} set to zero.
7682 @item @emph{Standard}:
7683 Fortran 95 and later, has overloads that are GNU extensions
7688 @item @emph{Syntax}:
7689 @code{RESULT = IBCLR(I, POS)}
7691 @item @emph{Arguments}:
7692 @multitable @columnfractions .15 .70
7693 @item @var{I} @tab The type shall be @code{INTEGER}.
7694 @item @var{POS} @tab The type shall be @code{INTEGER}.
7697 @item @emph{Return value}:
7698 The return value is of type @code{INTEGER} and of the same kind as
7701 @item @emph{Specific names}:
7702 @multitable @columnfractions .20 .20 .20 .25
7703 @item Name @tab Argument @tab Return type @tab Standard
7704 @item @code{IBCLR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7705 @item @code{BBCLR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7706 @item @code{IIBCLR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7707 @item @code{JIBCLR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7708 @item @code{KIBCLR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7711 @item @emph{See also}:
7712 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
7719 @section @code{IBITS} --- Bit extraction
7726 @cindex bits, extract
7729 @item @emph{Description}:
7730 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
7731 starting from bit position @var{POS} and extending left for @var{LEN}
7732 bits. The result is right-justified and the remaining bits are
7733 zeroed. The value of @code{POS+LEN} must be less than or equal to the
7734 value @code{BIT_SIZE(I)}.
7736 @item @emph{Standard}:
7737 Fortran 95 and later, has overloads that are GNU extensions
7742 @item @emph{Syntax}:
7743 @code{RESULT = IBITS(I, POS, LEN)}
7745 @item @emph{Arguments}:
7746 @multitable @columnfractions .15 .70
7747 @item @var{I} @tab The type shall be @code{INTEGER}.
7748 @item @var{POS} @tab The type shall be @code{INTEGER}.
7749 @item @var{LEN} @tab The type shall be @code{INTEGER}.
7752 @item @emph{Return value}:
7753 The return value is of type @code{INTEGER} and of the same kind as
7756 @item @emph{Specific names}:
7757 @multitable @columnfractions .20 .20 .20 .25
7758 @item Name @tab Argument @tab Return type @tab Standard
7759 @item @code{IBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7760 @item @code{BBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7761 @item @code{IIBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7762 @item @code{JIBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7763 @item @code{KIBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7766 @item @emph{See also}:
7767 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
7773 @section @code{IBSET} --- Set bit
7782 @item @emph{Description}:
7783 @code{IBSET} returns the value of @var{I} with the bit at position
7784 @var{POS} set to one.
7786 @item @emph{Standard}:
7787 Fortran 95 and later, has overloads that are GNU extensions
7792 @item @emph{Syntax}:
7793 @code{RESULT = IBSET(I, POS)}
7795 @item @emph{Arguments}:
7796 @multitable @columnfractions .15 .70
7797 @item @var{I} @tab The type shall be @code{INTEGER}.
7798 @item @var{POS} @tab The type shall be @code{INTEGER}.
7801 @item @emph{Return value}:
7802 The return value is of type @code{INTEGER} and of the same kind as
7805 @item @emph{Specific names}:
7806 @multitable @columnfractions .20 .20 .20 .25
7807 @item Name @tab Argument @tab Return type @tab Standard
7808 @item @code{IBSET(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7809 @item @code{BBSET(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7810 @item @code{IIBSET(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7811 @item @code{JIBSET(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7812 @item @code{KIBSET(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7815 @item @emph{See also}:
7816 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
7823 @section @code{ICHAR} --- Character-to-integer conversion function
7825 @cindex conversion, to integer
7828 @item @emph{Description}:
7829 @code{ICHAR(C)} returns the code for the character in the first character
7830 position of @code{C} in the system's native character set.
7831 The correspondence between characters and their codes is not necessarily
7832 the same across different GNU Fortran implementations.
7834 @item @emph{Standard}:
7835 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7840 @item @emph{Syntax}:
7841 @code{RESULT = ICHAR(C [, KIND])}
7843 @item @emph{Arguments}:
7844 @multitable @columnfractions .15 .70
7845 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
7846 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7847 expression indicating the kind parameter of the result.
7850 @item @emph{Return value}:
7851 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7852 @var{KIND} is absent, the return value is of default integer kind.
7854 @item @emph{Example}:
7859 end program test_ichar
7862 @item @emph{Specific names}:
7863 @multitable @columnfractions .20 .20 .20 .25
7864 @item Name @tab Argument @tab Return type @tab Standard
7865 @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7869 No intrinsic exists to convert between a numeric value and a formatted
7870 character string representation -- for instance, given the
7871 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
7872 @code{REAL} value with the value 154, or vice versa. Instead, this
7873 functionality is provided by internal-file I/O, as in the following
7878 character(len=10) string, string2
7881 ! Convert a string to a numeric value
7882 read (string,'(I10)') value
7885 ! Convert a value to a formatted string
7886 write (string2,'(I10)') value
7888 end program read_val
7891 @item @emph{See also}:
7892 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
7899 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
7901 @cindex date, current
7902 @cindex current date
7905 @item @emph{Description}:
7906 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
7907 current local time. The day (in the range 1-31), month (in the range 1-12),
7908 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
7909 The year has four significant digits.
7911 This intrinsic routine is provided for backwards compatibility with
7912 GNU Fortran 77. In new code, programmers should consider the use of
7913 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
7916 @item @emph{Standard}:
7922 @item @emph{Syntax}:
7923 @code{CALL IDATE(VALUES)}
7925 @item @emph{Arguments}:
7926 @multitable @columnfractions .15 .70
7927 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
7928 the kind shall be the default integer kind.
7931 @item @emph{Return value}:
7932 Does not return anything.
7934 @item @emph{Example}:
7937 integer, dimension(3) :: tarray
7942 end program test_idate
7945 @item @emph{See also}:
7951 @section @code{IEOR} --- Bitwise logical exclusive or
7957 @cindex bitwise logical exclusive or
7958 @cindex logical exclusive or, bitwise
7961 @item @emph{Description}:
7962 @code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
7965 @item @emph{Standard}:
7966 Fortran 95 and later, has overloads that are GNU extensions
7971 @item @emph{Syntax}:
7972 @code{RESULT = IEOR(I, J)}
7974 @item @emph{Arguments}:
7975 @multitable @columnfractions .15 .70
7976 @item @var{I} @tab The type shall be @code{INTEGER}.
7977 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
7978 kind as @var{I}. (As a GNU extension, different kinds are also
7982 @item @emph{Return value}:
7983 The return type is @code{INTEGER}, of the same kind as the
7984 arguments. (If the argument kinds differ, it is of the same kind as
7985 the larger argument.)
7987 @item @emph{Specific names}:
7988 @multitable @columnfractions .20 .20 .20 .25
7989 @item Name @tab Argument @tab Return type @tab Standard
7990 @item @code{IEOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7991 @item @code{BIEOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7992 @item @code{IIEOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7993 @item @code{JIEOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7994 @item @code{KIEOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7997 @item @emph{See also}:
7998 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
8004 @section @code{IERRNO} --- Get the last system error number
8006 @cindex system, error handling
8009 @item @emph{Description}:
8010 Returns the last system error number, as given by the C @code{errno}
8013 @item @emph{Standard}:
8019 @item @emph{Syntax}:
8020 @code{RESULT = IERRNO()}
8022 @item @emph{Arguments}:
8025 @item @emph{Return value}:
8026 The return value is of type @code{INTEGER} and of the default integer
8029 @item @emph{See also}:
8036 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
8037 @fnindex IMAGE_INDEX
8038 @cindex coarray, @code{IMAGE_INDEX}
8039 @cindex images, cosubscript to image index conversion
8042 @item @emph{Description}:
8043 Returns the image index belonging to a cosubscript.
8045 @item @emph{Standard}:
8046 Fortran 2008 and later
8051 @item @emph{Syntax}:
8052 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
8054 @item @emph{Arguments}: None.
8055 @multitable @columnfractions .15 .70
8056 @item @var{COARRAY} @tab Coarray of any type.
8057 @item @var{SUB} @tab default integer rank-1 array of a size equal to
8058 the corank of @var{COARRAY}.
8062 @item @emph{Return value}:
8063 Scalar default integer with the value of the image index which corresponds
8064 to the cosubscripts. For invalid cosubscripts the result is zero.
8066 @item @emph{Example}:
8068 INTEGER :: array[2,-1:4,8,*]
8069 ! Writes 28 (or 0 if there are fewer than 28 images)
8070 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
8073 @item @emph{See also}:
8074 @ref{THIS_IMAGE}, @ref{NUM_IMAGES}
8079 @node INDEX intrinsic
8080 @section @code{INDEX} --- Position of a substring within a string
8082 @cindex substring position
8083 @cindex string, find substring
8086 @item @emph{Description}:
8087 Returns the position of the start of the first occurrence of string
8088 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
8089 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
8090 the @var{BACK} argument is present and true, the return value is the
8091 start of the last occurrence rather than the first.
8093 @item @emph{Standard}:
8094 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
8099 @item @emph{Syntax}:
8100 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
8102 @item @emph{Arguments}:
8103 @multitable @columnfractions .15 .70
8104 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
8106 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
8108 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
8110 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8111 expression indicating the kind parameter of the result.
8114 @item @emph{Return value}:
8115 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8116 @var{KIND} is absent, the return value is of default integer kind.
8118 @item @emph{Specific names}:
8119 @multitable @columnfractions .20 .20 .20 .25
8120 @item Name @tab Argument @tab Return type @tab Standard
8121 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8124 @item @emph{See also}:
8125 @ref{SCAN}, @ref{VERIFY}
8131 @section @code{INT} --- Convert to integer type
8135 @cindex conversion, to integer
8138 @item @emph{Description}:
8139 Convert to integer type
8141 @item @emph{Standard}:
8142 Fortran 77 and later
8147 @item @emph{Syntax}:
8148 @code{RESULT = INT(A [, KIND))}
8150 @item @emph{Arguments}:
8151 @multitable @columnfractions .15 .70
8152 @item @var{A} @tab Shall be of type @code{INTEGER},
8153 @code{REAL}, or @code{COMPLEX}.
8154 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8155 expression indicating the kind parameter of the result.
8158 @item @emph{Return value}:
8159 These functions return a @code{INTEGER} variable or array under
8160 the following rules:
8164 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
8166 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)}
8167 equals @code{0}. If @math{|A| \geq 1}, then @code{INT(A)} is the integer
8168 whose magnitude is the largest integer that does not exceed the magnitude
8169 of @var{A} and whose sign is the same as the sign of @var{A}.
8171 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
8174 @item @emph{Example}:
8178 complex :: z = (-3.7, 1.0)
8180 print *, int(z), int(z,8)
8184 @item @emph{Specific names}:
8185 @multitable @columnfractions .20 .20 .20 .25
8186 @item Name @tab Argument @tab Return type @tab Standard
8187 @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
8188 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
8189 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
8196 @section @code{INT2} --- Convert to 16-bit integer type
8199 @cindex conversion, to integer
8202 @item @emph{Description}:
8203 Convert to a @code{KIND=2} integer type. This is equivalent to the
8204 standard @code{INT} intrinsic with an optional argument of
8205 @code{KIND=2}, and is only included for backwards compatibility.
8207 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
8209 @item @emph{Standard}:
8215 @item @emph{Syntax}:
8216 @code{RESULT = INT2(A)}
8218 @item @emph{Arguments}:
8219 @multitable @columnfractions .15 .70
8220 @item @var{A} @tab Shall be of type @code{INTEGER},
8221 @code{REAL}, or @code{COMPLEX}.
8224 @item @emph{Return value}:
8225 The return value is a @code{INTEGER(2)} variable.
8227 @item @emph{See also}:
8228 @ref{INT}, @ref{INT8}, @ref{LONG}
8234 @section @code{INT8} --- Convert to 64-bit integer type
8236 @cindex conversion, to integer
8239 @item @emph{Description}:
8240 Convert to a @code{KIND=8} integer type. This is equivalent to the
8241 standard @code{INT} intrinsic with an optional argument of
8242 @code{KIND=8}, and is only included for backwards compatibility.
8244 @item @emph{Standard}:
8250 @item @emph{Syntax}:
8251 @code{RESULT = INT8(A)}
8253 @item @emph{Arguments}:
8254 @multitable @columnfractions .15 .70
8255 @item @var{A} @tab Shall be of type @code{INTEGER},
8256 @code{REAL}, or @code{COMPLEX}.
8259 @item @emph{Return value}:
8260 The return value is a @code{INTEGER(8)} variable.
8262 @item @emph{See also}:
8263 @ref{INT}, @ref{INT2}, @ref{LONG}
8269 @section @code{IOR} --- Bitwise logical or
8275 @cindex bitwise logical or
8276 @cindex logical or, bitwise
8279 @item @emph{Description}:
8280 @code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
8283 @item @emph{Standard}:
8284 Fortran 95 and later, has overloads that are GNU extensions
8289 @item @emph{Syntax}:
8290 @code{RESULT = IOR(I, J)}
8292 @item @emph{Arguments}:
8293 @multitable @columnfractions .15 .70
8294 @item @var{I} @tab The type shall be @code{INTEGER}.
8295 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
8296 kind as @var{I}. (As a GNU extension, different kinds are also
8300 @item @emph{Return value}:
8301 The return type is @code{INTEGER}, of the same kind as the
8302 arguments. (If the argument kinds differ, it is of the same kind as
8303 the larger argument.)
8305 @item @emph{Specific names}:
8306 @multitable @columnfractions .20 .20 .20 .25
8307 @item Name @tab Argument @tab Return type @tab Standard
8308 @item @code{IOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
8309 @item @code{BIOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8310 @item @code{IIOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8311 @item @code{JIOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8312 @item @code{KIOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8315 @item @emph{See also}:
8316 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
8322 @section @code{IPARITY} --- Bitwise XOR of array elements
8324 @cindex array, parity
8326 @cindex bits, XOR of array elements
8329 @item @emph{Description}:
8330 Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
8331 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
8333 @item @emph{Standard}:
8334 Fortran 2008 and later
8337 Transformational function
8339 @item @emph{Syntax}:
8340 @multitable @columnfractions .80
8341 @item @code{RESULT = IPARITY(ARRAY[, MASK])}
8342 @item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
8345 @item @emph{Arguments}:
8346 @multitable @columnfractions .15 .70
8347 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
8348 @item @var{DIM} @tab (Optional) shall be a scalar of type
8349 @code{INTEGER} with a value in the range from 1 to n, where n
8350 equals the rank of @var{ARRAY}.
8351 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
8352 and either be a scalar or an array of the same shape as @var{ARRAY}.
8355 @item @emph{Return value}:
8356 The result is of the same type as @var{ARRAY}.
8358 If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
8359 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
8360 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
8361 dimension @var{DIM} dropped is returned.
8363 @item @emph{Example}:
8365 PROGRAM test_iparity
8372 PRINT '(b8.8)', IPARITY(a)
8376 @item @emph{See also}:
8377 @ref{IANY}, @ref{IALL}, @ref{IEOR}, @ref{PARITY}
8383 @section @code{IRAND} --- Integer pseudo-random number
8385 @cindex random number generation
8388 @item @emph{Description}:
8389 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
8390 distribution between 0 and a system-dependent limit (which is in most
8391 cases 2147483647). If @var{FLAG} is 0, the next number
8392 in the current sequence is returned; if @var{FLAG} is 1, the generator
8393 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
8394 it is used as a new seed with @code{SRAND}.
8396 This intrinsic routine is provided for backwards compatibility with
8397 GNU Fortran 77. It implements a simple modulo generator as provided
8398 by @command{g77}. For new code, one should consider the use of
8399 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
8401 @item @emph{Standard}:
8407 @item @emph{Syntax}:
8408 @code{RESULT = IRAND(I)}
8410 @item @emph{Arguments}:
8411 @multitable @columnfractions .15 .70
8412 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
8415 @item @emph{Return value}:
8416 The return value is of @code{INTEGER(kind=4)} type.
8418 @item @emph{Example}:
8421 integer,parameter :: seed = 86456
8424 print *, irand(), irand(), irand(), irand()
8425 print *, irand(seed), irand(), irand(), irand()
8426 end program test_irand
8434 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
8435 @fnindex IS_IOSTAT_END
8436 @cindex @code{IOSTAT}, end of file
8439 @item @emph{Description}:
8440 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
8441 status ``end of file''. The function is equivalent to comparing the variable
8442 with the @code{IOSTAT_END} parameter of the intrinsic module
8443 @code{ISO_FORTRAN_ENV}.
8445 @item @emph{Standard}:
8446 Fortran 2003 and later
8451 @item @emph{Syntax}:
8452 @code{RESULT = IS_IOSTAT_END(I)}
8454 @item @emph{Arguments}:
8455 @multitable @columnfractions .15 .70
8456 @item @var{I} @tab Shall be of the type @code{INTEGER}.
8459 @item @emph{Return value}:
8460 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
8461 @var{I} has the value which indicates an end of file condition for
8462 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
8464 @item @emph{Example}:
8469 OPEN(88, FILE='test.dat')
8470 READ(88, *, IOSTAT=stat) i
8471 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
8479 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
8480 @fnindex IS_IOSTAT_EOR
8481 @cindex @code{IOSTAT}, end of record
8484 @item @emph{Description}:
8485 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
8486 status ``end of record''. The function is equivalent to comparing the
8487 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
8488 @code{ISO_FORTRAN_ENV}.
8490 @item @emph{Standard}:
8491 Fortran 2003 and later
8496 @item @emph{Syntax}:
8497 @code{RESULT = IS_IOSTAT_EOR(I)}
8499 @item @emph{Arguments}:
8500 @multitable @columnfractions .15 .70
8501 @item @var{I} @tab Shall be of the type @code{INTEGER}.
8504 @item @emph{Return value}:
8505 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
8506 @var{I} has the value which indicates an end of file condition for
8507 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
8509 @item @emph{Example}:
8513 INTEGER :: stat, i(50)
8514 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
8515 READ(88, IOSTAT=stat) i
8516 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
8524 @section @code{ISATTY} --- Whether a unit is a terminal device.
8526 @cindex system, terminal
8529 @item @emph{Description}:
8530 Determine whether a unit is connected to a terminal device.
8532 @item @emph{Standard}:
8538 @item @emph{Syntax}:
8539 @code{RESULT = ISATTY(UNIT)}
8541 @item @emph{Arguments}:
8542 @multitable @columnfractions .15 .70
8543 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
8546 @item @emph{Return value}:
8547 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
8548 device, @code{.FALSE.} otherwise.
8550 @item @emph{Example}:
8553 INTEGER(kind=1) :: unit
8555 write(*,*) isatty(unit=unit)
8559 @item @emph{See also}:
8566 @section @code{ISHFT} --- Shift bits
8575 @item @emph{Description}:
8576 @code{ISHFT} returns a value corresponding to @var{I} with all of the
8577 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
8578 zero corresponds to a left shift, a value of zero corresponds to no
8579 shift, and a value less than zero corresponds to a right shift. If the
8580 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
8581 value is undefined. Bits shifted out from the left end or right end are
8582 lost; zeros are shifted in from the opposite end.
8584 @item @emph{Standard}:
8585 Fortran 95 and later, has overloads that are GNU extensions
8590 @item @emph{Syntax}:
8591 @code{RESULT = ISHFT(I, SHIFT)}
8593 @item @emph{Arguments}:
8594 @multitable @columnfractions .15 .70
8595 @item @var{I} @tab The type shall be @code{INTEGER}.
8596 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8599 @item @emph{Return value}:
8600 The return value is of type @code{INTEGER} and of the same kind as
8603 @item @emph{Specific names}:
8604 @multitable @columnfractions .20 .20 .20 .25
8605 @item Name @tab Argument @tab Return type @tab Standard
8606 @item @code{ISHFT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
8607 @item @code{BSHFT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8608 @item @code{IISHFT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8609 @item @code{JISHFT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8610 @item @code{KISHFT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8613 @item @emph{See also}:
8620 @section @code{ISHFTC} --- Shift bits circularly
8626 @cindex bits, shift circular
8629 @item @emph{Description}:
8630 @code{ISHFTC} returns a value corresponding to @var{I} with the
8631 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
8632 is, bits shifted out one end are shifted into the opposite end. A value
8633 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
8634 zero corresponds to no shift, and a value less than zero corresponds to
8635 a right shift. The absolute value of @var{SHIFT} must be less than
8636 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
8637 equivalent to @code{BIT_SIZE(I)}.
8639 @item @emph{Standard}:
8640 Fortran 95 and later, has overloads that are GNU extensions
8645 @item @emph{Syntax}:
8646 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
8648 @item @emph{Arguments}:
8649 @multitable @columnfractions .15 .70
8650 @item @var{I} @tab The type shall be @code{INTEGER}.
8651 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8652 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
8653 the value must be greater than zero and less than or equal to
8657 @item @emph{Return value}:
8658 The return value is of type @code{INTEGER} and of the same kind as
8661 @item @emph{Specific names}:
8662 @multitable @columnfractions .20 .20 .20 .25
8663 @item Name @tab Argument @tab Return type @tab Standard
8664 @item @code{ISHFTC(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
8665 @item @code{BSHFTC(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8666 @item @code{IISHFTC(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8667 @item @code{JISHFTC(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8668 @item @code{KISHFTC(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8671 @item @emph{See also}:
8678 @section @code{ISNAN} --- Test for a NaN
8683 @item @emph{Description}:
8684 @code{ISNAN} tests whether a floating-point value is an IEEE
8686 @item @emph{Standard}:
8692 @item @emph{Syntax}:
8695 @item @emph{Arguments}:
8696 @multitable @columnfractions .15 .70
8697 @item @var{X} @tab Variable of the type @code{REAL}.
8701 @item @emph{Return value}:
8702 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
8703 if @var{X} is a NaN and @code{FALSE} otherwise.
8705 @item @emph{Example}:
8712 if (isnan(x)) stop '"x" is a NaN'
8713 end program test_nan
8720 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
8722 @cindex time, current
8723 @cindex current time
8726 @item @emph{Description}:
8727 @code{ITIME(VALUES)} Fills @var{VALUES} with the numerical values at the
8728 current local time. The hour (in the range 1-24), minute (in the range 1-60),
8729 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
8732 This intrinsic routine is provided for backwards compatibility with
8733 GNU Fortran 77. In new code, programmers should consider the use of
8734 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
8737 @item @emph{Standard}:
8743 @item @emph{Syntax}:
8744 @code{CALL ITIME(VALUES)}
8746 @item @emph{Arguments}:
8747 @multitable @columnfractions .15 .70
8748 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
8749 and the kind shall be the default integer kind.
8752 @item @emph{Return value}:
8753 Does not return anything.
8756 @item @emph{Example}:
8759 integer, dimension(3) :: tarray
8764 end program test_itime
8767 @item @emph{See also}:
8774 @section @code{KILL} --- Send a signal to a process
8778 @item @emph{Description}:
8779 @item @emph{Standard}:
8780 Sends the signal specified by @var{SIG} to the process @var{PID}.
8783 This intrinsic is provided in both subroutine and function forms;
8784 however, only one form can be used in any given program unit.
8787 Subroutine, function
8789 @item @emph{Syntax}:
8790 @multitable @columnfractions .80
8791 @item @code{CALL KILL(PID, SIG [, STATUS])}
8792 @item @code{STATUS = KILL(PID, SIG)}
8795 @item @emph{Arguments}:
8796 @multitable @columnfractions .15 .70
8797 @item @var{PID} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}.
8798 @item @var{SIG} @tab Shall be a scalar @code{INTEGER} with @code{INTENT(IN)}.
8799 @item @var{STATUS} @tab [Subroutine](Optional)
8800 Shall be a scalar @code{INTEGER}.
8801 Returns 0 on success; otherwise a system-specific error code is returned.
8802 @item @var{STATUS} @tab [Function] The kind type parameter is that of
8804 Returns 0 on success; otherwise a system-specific error code is returned.
8807 @item @emph{See also}:
8808 @ref{ABORT}, @ref{EXIT}
8813 @section @code{KIND} --- Kind of an entity
8818 @item @emph{Description}:
8819 @code{KIND(X)} returns the kind value of the entity @var{X}.
8821 @item @emph{Standard}:
8822 Fortran 95 and later
8827 @item @emph{Syntax}:
8830 @item @emph{Arguments}:
8831 @multitable @columnfractions .15 .70
8832 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
8833 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
8836 @item @emph{Return value}:
8837 The return value is a scalar of type @code{INTEGER} and of the default
8840 @item @emph{Example}:
8843 integer,parameter :: kc = kind(' ')
8844 integer,parameter :: kl = kind(.true.)
8846 print *, "The default character kind is ", kc
8847 print *, "The default logical kind is ", kl
8848 end program test_kind
8856 @section @code{LBOUND} --- Lower dimension bounds of an array
8858 @cindex array, lower bound
8861 @item @emph{Description}:
8862 Returns the lower bounds of an array, or a single lower bound
8863 along the @var{DIM} dimension.
8864 @item @emph{Standard}:
8865 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
8870 @item @emph{Syntax}:
8871 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
8873 @item @emph{Arguments}:
8874 @multitable @columnfractions .15 .70
8875 @item @var{ARRAY} @tab Shall be an array, of any type.
8876 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
8877 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8878 expression indicating the kind parameter of the result.
8881 @item @emph{Return value}:
8882 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8883 @var{KIND} is absent, the return value is of default integer kind.
8884 If @var{DIM} is absent, the result is an array of the lower bounds of
8885 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
8886 corresponding to the lower bound of the array along that dimension. If
8887 @var{ARRAY} is an expression rather than a whole array or array
8888 structure component, or if it has a zero extent along the relevant
8889 dimension, the lower bound is taken to be 1.
8891 @item @emph{See also}:
8892 @ref{UBOUND}, @ref{LCOBOUND}
8898 @section @code{LCOBOUND} --- Lower codimension bounds of an array
8900 @cindex coarray, lower bound
8903 @item @emph{Description}:
8904 Returns the lower bounds of a coarray, or a single lower cobound
8905 along the @var{DIM} codimension.
8906 @item @emph{Standard}:
8907 Fortran 2008 and later
8912 @item @emph{Syntax}:
8913 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
8915 @item @emph{Arguments}:
8916 @multitable @columnfractions .15 .70
8917 @item @var{ARRAY} @tab Shall be an coarray, of any type.
8918 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
8919 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8920 expression indicating the kind parameter of the result.
8923 @item @emph{Return value}:
8924 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8925 @var{KIND} is absent, the return value is of default integer kind.
8926 If @var{DIM} is absent, the result is an array of the lower cobounds of
8927 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
8928 corresponding to the lower cobound of the array along that codimension.
8930 @item @emph{See also}:
8931 @ref{UCOBOUND}, @ref{LBOUND}
8937 @section @code{LEADZ} --- Number of leading zero bits of an integer
8942 @item @emph{Description}:
8943 @code{LEADZ} returns the number of leading zero bits of an integer.
8945 @item @emph{Standard}:
8946 Fortran 2008 and later
8951 @item @emph{Syntax}:
8952 @code{RESULT = LEADZ(I)}
8954 @item @emph{Arguments}:
8955 @multitable @columnfractions .15 .70
8956 @item @var{I} @tab Shall be of type @code{INTEGER}.
8959 @item @emph{Return value}:
8960 The type of the return value is the default @code{INTEGER}.
8961 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
8963 @item @emph{Example}:
8966 WRITE (*,*) BIT_SIZE(1) ! prints 32
8967 WRITE (*,*) LEADZ(1) ! prints 31
8971 @item @emph{See also}:
8972 @ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR}
8978 @section @code{LEN} --- Length of a character entity
8980 @cindex string, length
8983 @item @emph{Description}:
8984 Returns the length of a character string. If @var{STRING} is an array,
8985 the length of an element of @var{STRING} is returned. Note that
8986 @var{STRING} need not be defined when this intrinsic is invoked, since
8987 only the length, not the content, of @var{STRING} is needed.
8989 @item @emph{Standard}:
8990 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
8995 @item @emph{Syntax}:
8996 @code{L = LEN(STRING [, KIND])}
8998 @item @emph{Arguments}:
8999 @multitable @columnfractions .15 .70
9000 @item @var{STRING} @tab Shall be a scalar or array of type
9001 @code{CHARACTER}, with @code{INTENT(IN)}
9002 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9003 expression indicating the kind parameter of the result.
9006 @item @emph{Return value}:
9007 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9008 @var{KIND} is absent, the return value is of default integer kind.
9011 @item @emph{Specific names}:
9012 @multitable @columnfractions .20 .20 .20 .25
9013 @item Name @tab Argument @tab Return type @tab Standard
9014 @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
9018 @item @emph{See also}:
9019 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
9025 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
9027 @cindex string, length, without trailing whitespace
9030 @item @emph{Description}:
9031 Returns the length of a character string, ignoring any trailing blanks.
9033 @item @emph{Standard}:
9034 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
9039 @item @emph{Syntax}:
9040 @code{RESULT = LEN_TRIM(STRING [, KIND])}
9042 @item @emph{Arguments}:
9043 @multitable @columnfractions .15 .70
9044 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
9045 with @code{INTENT(IN)}
9046 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9047 expression indicating the kind parameter of the result.
9050 @item @emph{Return value}:
9051 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9052 @var{KIND} is absent, the return value is of default integer kind.
9054 @item @emph{See also}:
9055 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
9061 @section @code{LGE} --- Lexical greater than or equal
9063 @cindex lexical comparison of strings
9064 @cindex string, comparison
9067 @item @emph{Description}:
9068 Determines whether one string is lexically greater than or equal to
9069 another string, where the two strings are interpreted as containing
9070 ASCII character codes. If the String A and String B are not the same
9071 length, the shorter is compared as if spaces were appended to it to form
9072 a value that has the same length as the longer.
9074 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9075 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9076 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9077 that the latter use the processor's character ordering (which is not
9078 ASCII on some targets), whereas the former always use the ASCII
9081 @item @emph{Standard}:
9082 Fortran 77 and later
9087 @item @emph{Syntax}:
9088 @code{RESULT = LGE(STRING_A, STRING_B)}
9090 @item @emph{Arguments}:
9091 @multitable @columnfractions .15 .70
9092 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9093 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9096 @item @emph{Return value}:
9097 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
9098 otherwise, based on the ASCII ordering.
9100 @item @emph{Specific names}:
9101 @multitable @columnfractions .20 .20 .20 .25
9102 @item Name @tab Argument @tab Return type @tab Standard
9103 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9106 @item @emph{See also}:
9107 @ref{LGT}, @ref{LLE}, @ref{LLT}
9113 @section @code{LGT} --- Lexical greater than
9115 @cindex lexical comparison of strings
9116 @cindex string, comparison
9119 @item @emph{Description}:
9120 Determines whether one string is lexically greater than another string,
9121 where the two strings are interpreted as containing ASCII character
9122 codes. If the String A and String B are not the same length, the
9123 shorter is compared as if spaces were appended to it to form a value
9124 that has the same length as the longer.
9126 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9127 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9128 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9129 that the latter use the processor's character ordering (which is not
9130 ASCII on some targets), whereas the former always use the ASCII
9133 @item @emph{Standard}:
9134 Fortran 77 and later
9139 @item @emph{Syntax}:
9140 @code{RESULT = LGT(STRING_A, STRING_B)}
9142 @item @emph{Arguments}:
9143 @multitable @columnfractions .15 .70
9144 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9145 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9148 @item @emph{Return value}:
9149 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
9150 otherwise, based on the ASCII ordering.
9152 @item @emph{Specific names}:
9153 @multitable @columnfractions .20 .20 .20 .25
9154 @item Name @tab Argument @tab Return type @tab Standard
9155 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9158 @item @emph{See also}:
9159 @ref{LGE}, @ref{LLE}, @ref{LLT}
9165 @section @code{LINK} --- Create a hard link
9167 @cindex file system, create link
9168 @cindex file system, hard link
9171 @item @emph{Description}:
9172 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
9173 character (@code{CHAR(0)}) can be used to mark the end of the names in
9174 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
9175 names are ignored. If the @var{STATUS} argument is supplied, it
9176 contains 0 on success or a nonzero error code upon return; see
9179 This intrinsic is provided in both subroutine and function forms;
9180 however, only one form can be used in any given program unit.
9182 @item @emph{Standard}:
9186 Subroutine, function
9188 @item @emph{Syntax}:
9189 @multitable @columnfractions .80
9190 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
9191 @item @code{STATUS = LINK(PATH1, PATH2)}
9194 @item @emph{Arguments}:
9195 @multitable @columnfractions .15 .70
9196 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
9197 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
9198 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9201 @item @emph{See also}:
9202 @ref{SYMLNK}, @ref{UNLINK}
9208 @section @code{LLE} --- Lexical less than or equal
9210 @cindex lexical comparison of strings
9211 @cindex string, comparison
9214 @item @emph{Description}:
9215 Determines whether one string is lexically less than or equal to another
9216 string, where the two strings are interpreted as containing ASCII
9217 character codes. If the String A and String B are not the same length,
9218 the shorter is compared as if spaces were appended to it to form a value
9219 that has the same length as the longer.
9221 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9222 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9223 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9224 that the latter use the processor's character ordering (which is not
9225 ASCII on some targets), whereas the former always use the ASCII
9228 @item @emph{Standard}:
9229 Fortran 77 and later
9234 @item @emph{Syntax}:
9235 @code{RESULT = LLE(STRING_A, STRING_B)}
9237 @item @emph{Arguments}:
9238 @multitable @columnfractions .15 .70
9239 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9240 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9243 @item @emph{Return value}:
9244 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
9245 otherwise, based on the ASCII ordering.
9247 @item @emph{Specific names}:
9248 @multitable @columnfractions .20 .20 .20 .25
9249 @item Name @tab Argument @tab Return type @tab Standard
9250 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9253 @item @emph{See also}:
9254 @ref{LGE}, @ref{LGT}, @ref{LLT}
9260 @section @code{LLT} --- Lexical less than
9262 @cindex lexical comparison of strings
9263 @cindex string, comparison
9266 @item @emph{Description}:
9267 Determines whether one string is lexically less than another string,
9268 where the two strings are interpreted as containing ASCII character
9269 codes. If the String A and String B are not the same length, the
9270 shorter is compared as if spaces were appended to it to form a value
9271 that has the same length as the longer.
9273 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
9274 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
9275 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
9276 that the latter use the processor's character ordering (which is not
9277 ASCII on some targets), whereas the former always use the ASCII
9280 @item @emph{Standard}:
9281 Fortran 77 and later
9286 @item @emph{Syntax}:
9287 @code{RESULT = LLT(STRING_A, STRING_B)}
9289 @item @emph{Arguments}:
9290 @multitable @columnfractions .15 .70
9291 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
9292 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
9295 @item @emph{Return value}:
9296 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
9297 otherwise, based on the ASCII ordering.
9299 @item @emph{Specific names}:
9300 @multitable @columnfractions .20 .20 .20 .25
9301 @item Name @tab Argument @tab Return type @tab Standard
9302 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
9305 @item @emph{See also}:
9306 @ref{LGE}, @ref{LGT}, @ref{LLE}
9312 @section @code{LNBLNK} --- Index of the last non-blank character in a string
9314 @cindex string, find non-blank character
9317 @item @emph{Description}:
9318 Returns the length of a character string, ignoring any trailing blanks.
9319 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
9320 included for backwards compatibility.
9322 @item @emph{Standard}:
9328 @item @emph{Syntax}:
9329 @code{RESULT = LNBLNK(STRING)}
9331 @item @emph{Arguments}:
9332 @multitable @columnfractions .15 .70
9333 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
9334 with @code{INTENT(IN)}
9337 @item @emph{Return value}:
9338 The return value is of @code{INTEGER(kind=4)} type.
9340 @item @emph{See also}:
9341 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
9347 @section @code{LOC} --- Returns the address of a variable
9349 @cindex location of a variable in memory
9352 @item @emph{Description}:
9353 @code{LOC(X)} returns the address of @var{X} as an integer.
9355 @item @emph{Standard}:
9361 @item @emph{Syntax}:
9362 @code{RESULT = LOC(X)}
9364 @item @emph{Arguments}:
9365 @multitable @columnfractions .15 .70
9366 @item @var{X} @tab Variable of any type.
9369 @item @emph{Return value}:
9370 The return value is of type @code{INTEGER}, with a @code{KIND}
9371 corresponding to the size (in bytes) of a memory address on the target
9374 @item @emph{Example}:
9381 end program test_loc
9388 @section @code{LOG} --- Natural logarithm function
9395 @cindex exponential function, inverse
9396 @cindex logarithm function
9397 @cindex natural logarithm function
9400 @item @emph{Description}:
9401 @code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the
9402 logarithm to the base @math{e}.
9404 @item @emph{Standard}:
9405 Fortran 77 and later
9410 @item @emph{Syntax}:
9411 @code{RESULT = LOG(X)}
9413 @item @emph{Arguments}:
9414 @multitable @columnfractions .15 .70
9415 @item @var{X} @tab The type shall be @code{REAL} or
9419 @item @emph{Return value}:
9420 The return value is of type @code{REAL} or @code{COMPLEX}.
9421 The kind type parameter is the same as @var{X}.
9422 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
9423 @math{-\pi < \omega \leq \pi}.
9425 @item @emph{Example}:
9428 real(8) :: x = 2.7182818284590451_8
9429 complex :: z = (1.0, 2.0)
9430 x = log(x) ! will yield (approximately) 1
9432 end program test_log
9435 @item @emph{Specific names}:
9436 @multitable @columnfractions .20 .20 .20 .25
9437 @item Name @tab Argument @tab Return type @tab Standard
9438 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
9439 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
9440 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
9441 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9442 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9449 @section @code{LOG10} --- Base 10 logarithm function
9453 @cindex exponential function, inverse
9454 @cindex logarithm function with base 10
9455 @cindex base 10 logarithm function
9458 @item @emph{Description}:
9459 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
9461 @item @emph{Standard}:
9462 Fortran 77 and later
9467 @item @emph{Syntax}:
9468 @code{RESULT = LOG10(X)}
9470 @item @emph{Arguments}:
9471 @multitable @columnfractions .15 .70
9472 @item @var{X} @tab The type shall be @code{REAL}.
9475 @item @emph{Return value}:
9476 The return value is of type @code{REAL} or @code{COMPLEX}.
9477 The kind type parameter is the same as @var{X}.
9479 @item @emph{Example}:
9482 real(8) :: x = 10.0_8
9484 end program test_log10
9487 @item @emph{Specific names}:
9488 @multitable @columnfractions .20 .20 .20 .25
9489 @item Name @tab Argument @tab Return type @tab Standard
9490 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
9491 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
9498 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
9503 @cindex Gamma function, logarithm of
9506 @item @emph{Description}:
9507 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
9508 of the Gamma (@math{\Gamma}) function.
9510 @item @emph{Standard}:
9511 Fortran 2008 and later
9516 @item @emph{Syntax}:
9517 @code{X = LOG_GAMMA(X)}
9519 @item @emph{Arguments}:
9520 @multitable @columnfractions .15 .70
9521 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
9522 nor a negative integer.
9525 @item @emph{Return value}:
9526 The return value is of type @code{REAL} of the same kind as @var{X}.
9528 @item @emph{Example}:
9530 program test_log_gamma
9532 x = lgamma(x) ! returns 0.0
9533 end program test_log_gamma
9536 @item @emph{Specific names}:
9537 @multitable @columnfractions .20 .20 .20 .25
9538 @item Name @tab Argument @tab Return type @tab Standard
9539 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
9540 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
9541 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
9544 @item @emph{See also}:
9545 Gamma function: @ref{GAMMA}
9552 @section @code{LOGICAL} --- Convert to logical type
9554 @cindex conversion, to logical
9557 @item @emph{Description}:
9558 Converts one kind of @code{LOGICAL} variable to another.
9560 @item @emph{Standard}:
9561 Fortran 95 and later
9566 @item @emph{Syntax}:
9567 @code{RESULT = LOGICAL(L [, KIND])}
9569 @item @emph{Arguments}:
9570 @multitable @columnfractions .15 .70
9571 @item @var{L} @tab The type shall be @code{LOGICAL}.
9572 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9573 expression indicating the kind parameter of the result.
9576 @item @emph{Return value}:
9577 The return value is a @code{LOGICAL} value equal to @var{L}, with a
9578 kind corresponding to @var{KIND}, or of the default logical kind if
9579 @var{KIND} is not given.
9581 @item @emph{See also}:
9582 @ref{INT}, @ref{REAL}, @ref{CMPLX}
9588 @section @code{LONG} --- Convert to integer type
9590 @cindex conversion, to integer
9593 @item @emph{Description}:
9594 Convert to a @code{KIND=4} integer type, which is the same size as a C
9595 @code{long} integer. This is equivalent to the standard @code{INT}
9596 intrinsic with an optional argument of @code{KIND=4}, and is only
9597 included for backwards compatibility.
9599 @item @emph{Standard}:
9605 @item @emph{Syntax}:
9606 @code{RESULT = LONG(A)}
9608 @item @emph{Arguments}:
9609 @multitable @columnfractions .15 .70
9610 @item @var{A} @tab Shall be of type @code{INTEGER},
9611 @code{REAL}, or @code{COMPLEX}.
9614 @item @emph{Return value}:
9615 The return value is a @code{INTEGER(4)} variable.
9617 @item @emph{See also}:
9618 @ref{INT}, @ref{INT2}, @ref{INT8}
9624 @section @code{LSHIFT} --- Left shift bits
9626 @cindex bits, shift left
9629 @item @emph{Description}:
9630 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
9631 bits shifted left by @var{SHIFT} places. If the absolute value of
9632 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
9633 Bits shifted out from the left end are lost; zeros are shifted in from
9636 This function has been superseded by the @code{ISHFT} intrinsic, which
9637 is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
9638 which is standard in Fortran 2008 and later.
9640 @item @emph{Standard}:
9646 @item @emph{Syntax}:
9647 @code{RESULT = LSHIFT(I, SHIFT)}
9649 @item @emph{Arguments}:
9650 @multitable @columnfractions .15 .70
9651 @item @var{I} @tab The type shall be @code{INTEGER}.
9652 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
9655 @item @emph{Return value}:
9656 The return value is of type @code{INTEGER} and of the same kind as
9659 @item @emph{See also}:
9660 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}, @ref{SHIFTA}, @ref{SHIFTL},
9668 @section @code{LSTAT} --- Get file status
9670 @cindex file system, file status
9673 @item @emph{Description}:
9674 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
9675 symbolic link, then the link itself is statted, not the file that it
9678 The elements in @code{VALUES} are the same as described by @ref{STAT}.
9680 This intrinsic is provided in both subroutine and function forms;
9681 however, only one form can be used in any given program unit.
9683 @item @emph{Standard}:
9687 Subroutine, function
9689 @item @emph{Syntax}:
9690 @multitable @columnfractions .80
9691 @item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
9692 @item @code{STATUS = LSTAT(NAME, VALUES)}
9695 @item @emph{Arguments}:
9696 @multitable @columnfractions .15 .70
9697 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
9698 kind, a valid path within the file system.
9699 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
9700 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
9701 Returns 0 on success and a system specific error code otherwise.
9704 @item @emph{Example}:
9705 See @ref{STAT} for an example.
9707 @item @emph{See also}:
9708 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
9714 @section @code{LTIME} --- Convert time to local time info
9716 @cindex time, conversion to local time info
9719 @item @emph{Description}:
9720 Given a system time value @var{TIME} (as provided by the @ref{TIME}
9721 intrinsic), fills @var{VALUES} with values extracted from it appropriate
9722 to the local time zone using @code{localtime(3)}.
9724 This intrinsic routine is provided for backwards compatibility with
9725 GNU Fortran 77. In new code, programmers should consider the use of
9726 the @ref{DATE_AND_TIME} intrinsic defined by the Fortran 95
9729 @item @emph{Standard}:
9735 @item @emph{Syntax}:
9736 @code{CALL LTIME(TIME, VALUES)}
9738 @item @emph{Arguments}:
9739 @multitable @columnfractions .15 .70
9740 @item @var{TIME} @tab An @code{INTEGER} scalar expression
9741 corresponding to a system time, with @code{INTENT(IN)}.
9742 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
9743 with @code{INTENT(OUT)}.
9746 @item @emph{Return value}:
9747 The elements of @var{VALUES} are assigned as follows:
9749 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
9751 @item Minutes after the hour, range 0--59
9752 @item Hours past midnight, range 0--23
9753 @item Day of month, range 1--31
9754 @item Number of months since January, range 0--11
9755 @item Years since 1900
9756 @item Number of days since Sunday, range 0--6
9757 @item Days since January 1, range 0--365
9758 @item Daylight savings indicator: positive if daylight savings is in
9759 effect, zero if not, and negative if the information is not available.
9762 @item @emph{See also}:
9763 @ref{DATE_AND_TIME}, @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
9770 @section @code{MALLOC} --- Allocate dynamic memory
9772 @cindex pointer, cray
9775 @item @emph{Description}:
9776 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
9777 returns the address of the allocated memory. The @code{MALLOC} intrinsic
9778 is an extension intended to be used with Cray pointers, and is provided
9779 in GNU Fortran to allow the user to compile legacy code. For new code
9780 using Fortran 95 pointers, the memory allocation intrinsic is
9783 @item @emph{Standard}:
9789 @item @emph{Syntax}:
9790 @code{PTR = MALLOC(SIZE)}
9792 @item @emph{Arguments}:
9793 @multitable @columnfractions .15 .70
9794 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
9797 @item @emph{Return value}:
9798 The return value is of type @code{INTEGER(K)}, with @var{K} such that
9799 variables of type @code{INTEGER(K)} have the same size as
9800 C pointers (@code{sizeof(void *)}).
9802 @item @emph{Example}:
9803 The following example demonstrates the use of @code{MALLOC} and
9804 @code{FREE} with Cray pointers.
9813 ptr_x = malloc(20*8)
9815 x(i) = sqrt(1.0d0 / i)
9823 end program test_malloc
9826 @item @emph{See also}:
9833 @section @code{MASKL} --- Left justified mask
9835 @cindex mask, left justified
9838 @item @emph{Description}:
9839 @code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
9840 remaining bits set to 0.
9842 @item @emph{Standard}:
9843 Fortran 2008 and later
9848 @item @emph{Syntax}:
9849 @code{RESULT = MASKL(I[, KIND])}
9851 @item @emph{Arguments}:
9852 @multitable @columnfractions .15 .70
9853 @item @var{I} @tab Shall be of type @code{INTEGER}.
9854 @item @var{KIND} @tab Shall be a scalar constant expression of type
9858 @item @emph{Return value}:
9859 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
9860 specifies the kind value of the return type; otherwise, it is of the
9861 default integer kind.
9863 @item @emph{See also}:
9870 @section @code{MASKR} --- Right justified mask
9872 @cindex mask, right justified
9875 @item @emph{Description}:
9876 @code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
9877 remaining bits set to 0.
9879 @item @emph{Standard}:
9880 Fortran 2008 and later
9885 @item @emph{Syntax}:
9886 @code{RESULT = MASKR(I[, KIND])}
9888 @item @emph{Arguments}:
9889 @multitable @columnfractions .15 .70
9890 @item @var{I} @tab Shall be of type @code{INTEGER}.
9891 @item @var{KIND} @tab Shall be a scalar constant expression of type
9895 @item @emph{Return value}:
9896 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
9897 specifies the kind value of the return type; otherwise, it is of the
9898 default integer kind.
9900 @item @emph{See also}:
9907 @section @code{MATMUL} --- matrix multiplication
9909 @cindex matrix multiplication
9910 @cindex product, matrix
9913 @item @emph{Description}:
9914 Performs a matrix multiplication on numeric or logical arguments.
9916 @item @emph{Standard}:
9917 Fortran 95 and later
9920 Transformational function
9922 @item @emph{Syntax}:
9923 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
9925 @item @emph{Arguments}:
9926 @multitable @columnfractions .15 .70
9927 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
9928 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
9930 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
9931 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
9932 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
9933 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
9934 equal to the last (or only) dimension of @var{MATRIX_A}.
9935 @var{MATRIX_A} and @var{MATRIX_B} shall not both be rank one arrays.
9938 @item @emph{Return value}:
9939 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
9940 kind of the result follow the usual type and kind promotion rules, as
9941 for the @code{*} or @code{.AND.} operators.
9943 @item @emph{See also}:
9949 @section @code{MAX} --- Maximum value of an argument list
9956 @cindex maximum value
9959 @item @emph{Description}:
9960 Returns the argument with the largest (most positive) value.
9962 @item @emph{Standard}:
9963 Fortran 77 and later
9968 @item @emph{Syntax}:
9969 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
9971 @item @emph{Arguments}:
9972 @multitable @columnfractions .15 .70
9973 @item @var{A1} @tab The type shall be @code{INTEGER} or
9975 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
9976 as @var{A1}. (As a GNU extension, arguments of different kinds are
9980 @item @emph{Return value}:
9981 The return value corresponds to the maximum value among the arguments,
9982 and has the same type and kind as the first argument.
9984 @item @emph{Specific names}:
9985 @multitable @columnfractions .20 .20 .20 .25
9986 @item Name @tab Argument @tab Return type @tab Standard
9987 @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
9988 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
9989 @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
9990 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
9991 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
9994 @item @emph{See also}:
9995 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
10002 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
10003 @fnindex MAXEXPONENT
10004 @cindex model representation, maximum exponent
10007 @item @emph{Description}:
10008 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
10011 @item @emph{Standard}:
10012 Fortran 95 and later
10014 @item @emph{Class}:
10017 @item @emph{Syntax}:
10018 @code{RESULT = MAXEXPONENT(X)}
10020 @item @emph{Arguments}:
10021 @multitable @columnfractions .15 .70
10022 @item @var{X} @tab Shall be of type @code{REAL}.
10025 @item @emph{Return value}:
10026 The return value is of type @code{INTEGER} and of the default integer
10029 @item @emph{Example}:
10035 print *, minexponent(x), maxexponent(x)
10036 print *, minexponent(y), maxexponent(y)
10037 end program exponents
10044 @section @code{MAXLOC} --- Location of the maximum value within an array
10046 @cindex array, location of maximum element
10049 @item @emph{Description}:
10050 Determines the location of the element in the array with the maximum
10051 value, or, if the @var{DIM} argument is supplied, determines the
10052 locations of the maximum element along each row of the array in the
10053 @var{DIM} direction. If @var{MASK} is present, only the elements for
10054 which @var{MASK} is @code{.TRUE.} are considered. If more than one
10055 element in the array has the maximum value, the location returned is
10056 that of the first such element in array element order if the
10057 @var{BACK} is not present, or if it false; otherwise, the location
10058 returned is that of the first such element. If the array has zero
10059 size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
10060 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
10061 and all of the elements of @var{MASK} along a given row are zero, the
10062 result value for that row is zero.
10064 @item @emph{Standard}:
10065 Fortran 95 and later; @var{ARRAY} of @code{CHARACTER} and the
10066 @var{KIND} argument are available in Fortran 2003 and later.
10067 The @var{BACK} argument is available in Fortran 2008 and later.
10069 @item @emph{Class}:
10070 Transformational function
10072 @item @emph{Syntax}:
10073 @multitable @columnfractions .80
10074 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK])}
10075 @item @code{RESULT = MAXLOC(ARRAY [, MASK] [,KIND] [,BACK])}
10078 @item @emph{Arguments}:
10079 @multitable @columnfractions .15 .70
10080 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10082 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10083 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10084 inclusive. It may not be an optional dummy argument.
10085 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
10086 and conformable with @var{ARRAY}.
10087 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10088 expression indicating the kind parameter of the result.
10089 @item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}.
10092 @item @emph{Return value}:
10093 If @var{DIM} is absent, the result is a rank-one array with a length
10094 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
10095 is an array with a rank one less than the rank of @var{ARRAY}, and a
10096 size corresponding to the size of @var{ARRAY} with the @var{DIM}
10097 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
10098 of one, the result is a scalar. If the optional argument @var{KIND}
10099 is present, the result is an integer of kind @var{KIND}, otherwise it
10100 is of default kind.
10102 @item @emph{See also}:
10103 @ref{FINDLOC}, @ref{MAX}, @ref{MAXVAL}
10110 @section @code{MAXVAL} --- Maximum value of an array
10112 @cindex array, maximum value
10113 @cindex maximum value
10116 @item @emph{Description}:
10117 Determines the maximum value of the elements in an array value, or, if
10118 the @var{DIM} argument is supplied, determines the maximum value along
10119 each row of the array in the @var{DIM} direction. If @var{MASK} is
10120 present, only the elements for which @var{MASK} is @code{.TRUE.} are
10121 considered. If the array has zero size, or all of the elements of
10122 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
10123 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
10126 @item @emph{Standard}:
10127 Fortran 95 and later
10129 @item @emph{Class}:
10130 Transformational function
10132 @item @emph{Syntax}:
10133 @multitable @columnfractions .80
10134 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
10135 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
10138 @item @emph{Arguments}:
10139 @multitable @columnfractions .15 .70
10140 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10142 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10143 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10144 inclusive. It may not be an optional dummy argument.
10145 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
10146 and conformable with @var{ARRAY}.
10149 @item @emph{Return value}:
10150 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
10151 is a scalar. If @var{DIM} is present, the result is an array with a
10152 rank one less than the rank of @var{ARRAY}, and a size corresponding to
10153 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
10154 cases, the result is of the same type and kind as @var{ARRAY}.
10156 @item @emph{See also}:
10157 @ref{MAX}, @ref{MAXLOC}
10163 @section @code{MCLOCK} --- Time function
10165 @cindex time, clock ticks
10166 @cindex clock ticks
10169 @item @emph{Description}:
10170 Returns the number of clock ticks since the start of the process, based
10171 on the function @code{clock(3)} in the C standard library.
10173 This intrinsic is not fully portable, such as to systems with 32-bit
10174 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
10175 the values returned by this intrinsic might be, or become, negative, or
10176 numerically less than previous values, during a single run of the
10179 @item @emph{Standard}:
10182 @item @emph{Class}:
10185 @item @emph{Syntax}:
10186 @code{RESULT = MCLOCK()}
10188 @item @emph{Return value}:
10189 The return value is a scalar of type @code{INTEGER(4)}, equal to the
10190 number of clock ticks since the start of the process, or @code{-1} if
10191 the system does not support @code{clock(3)}.
10193 @item @emph{See also}:
10194 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
10201 @section @code{MCLOCK8} --- Time function (64-bit)
10203 @cindex time, clock ticks
10204 @cindex clock ticks
10207 @item @emph{Description}:
10208 Returns the number of clock ticks since the start of the process, based
10209 on the function @code{clock(3)} in the C standard library.
10211 @emph{Warning:} this intrinsic does not increase the range of the timing
10212 values over that returned by @code{clock(3)}. On a system with a 32-bit
10213 @code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though
10214 it is converted to a 64-bit @code{INTEGER(8)} value. That means
10215 overflows of the 32-bit value can still occur. Therefore, the values
10216 returned by this intrinsic might be or become negative or numerically
10217 less than previous values during a single run of the compiled program.
10219 @item @emph{Standard}:
10222 @item @emph{Class}:
10225 @item @emph{Syntax}:
10226 @code{RESULT = MCLOCK8()}
10228 @item @emph{Return value}:
10229 The return value is a scalar of type @code{INTEGER(8)}, equal to the
10230 number of clock ticks since the start of the process, or @code{-1} if
10231 the system does not support @code{clock(3)}.
10233 @item @emph{See also}:
10234 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
10241 @section @code{MERGE} --- Merge variables
10243 @cindex array, merge arrays
10244 @cindex array, combine arrays
10247 @item @emph{Description}:
10248 Select values from two arrays according to a logical mask. The result
10249 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
10250 @var{FSOURCE} if it is @code{.FALSE.}.
10252 @item @emph{Standard}:
10253 Fortran 95 and later
10255 @item @emph{Class}:
10258 @item @emph{Syntax}:
10259 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
10261 @item @emph{Arguments}:
10262 @multitable @columnfractions .15 .70
10263 @item @var{TSOURCE} @tab May be of any type.
10264 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
10266 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
10269 @item @emph{Return value}:
10270 The result is of the same type and type parameters as @var{TSOURCE}.
10277 @section @code{MERGE_BITS} --- Merge of bits under mask
10278 @fnindex MERGE_BITS
10279 @cindex bits, merge
10282 @item @emph{Description}:
10283 @code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
10284 as determined by the mask. The i-th bit of the result is equal to the
10285 i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
10286 the i-th bit of @var{J} otherwise.
10288 @item @emph{Standard}:
10289 Fortran 2008 and later
10291 @item @emph{Class}:
10294 @item @emph{Syntax}:
10295 @code{RESULT = MERGE_BITS(I, J, MASK)}
10297 @item @emph{Arguments}:
10298 @multitable @columnfractions .15 .70
10299 @item @var{I} @tab Shall be of type @code{INTEGER}.
10300 @item @var{J} @tab Shall be of type @code{INTEGER} and of the same
10302 @item @var{MASK} @tab Shall be of type @code{INTEGER} and of the same
10306 @item @emph{Return value}:
10307 The result is of the same type and kind as @var{I}.
10314 @section @code{MIN} --- Minimum value of an argument list
10321 @cindex minimum value
10324 @item @emph{Description}:
10325 Returns the argument with the smallest (most negative) value.
10327 @item @emph{Standard}:
10328 Fortran 77 and later
10330 @item @emph{Class}:
10333 @item @emph{Syntax}:
10334 @code{RESULT = MIN(A1, A2 [, A3, ...])}
10336 @item @emph{Arguments}:
10337 @multitable @columnfractions .15 .70
10338 @item @var{A1} @tab The type shall be @code{INTEGER} or
10340 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
10341 as @var{A1}. (As a GNU extension, arguments of different kinds are
10345 @item @emph{Return value}:
10346 The return value corresponds to the maximum value among the arguments,
10347 and has the same type and kind as the first argument.
10349 @item @emph{Specific names}:
10350 @multitable @columnfractions .20 .20 .20 .25
10351 @item Name @tab Argument @tab Return type @tab Standard
10352 @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
10353 @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
10354 @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
10355 @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
10356 @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
10359 @item @emph{See also}:
10360 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
10366 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
10367 @fnindex MINEXPONENT
10368 @cindex model representation, minimum exponent
10371 @item @emph{Description}:
10372 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
10375 @item @emph{Standard}:
10376 Fortran 95 and later
10378 @item @emph{Class}:
10381 @item @emph{Syntax}:
10382 @code{RESULT = MINEXPONENT(X)}
10384 @item @emph{Arguments}:
10385 @multitable @columnfractions .15 .70
10386 @item @var{X} @tab Shall be of type @code{REAL}.
10389 @item @emph{Return value}:
10390 The return value is of type @code{INTEGER} and of the default integer
10393 @item @emph{Example}:
10394 See @code{MAXEXPONENT} for an example.
10400 @section @code{MINLOC} --- Location of the minimum value within an array
10402 @cindex array, location of minimum element
10405 @item @emph{Description}:
10406 Determines the location of the element in the array with the minimum
10407 value, or, if the @var{DIM} argument is supplied, determines the
10408 locations of the minimum element along each row of the array in the
10409 @var{DIM} direction. If @var{MASK} is present, only the elements for
10410 which @var{MASK} is @code{.TRUE.} are considered. If more than one
10411 element in the array has the minimum value, the location returned is
10412 that of the first such element in array element order if the
10413 @var{BACK} is not present, or if it false; otherwise, the location
10414 returned is that of the first such element. If the array has
10415 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
10416 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
10417 and all of the elements of @var{MASK} along a given row are zero, the
10418 result value for that row is zero.
10420 @item @emph{Standard}:
10421 Fortran 95 and later; @var{ARRAY} of @code{CHARACTER} and the
10422 @var{KIND} argument are available in Fortran 2003 and later.
10423 The @var{BACK} argument is available in Fortran 2008 and later.
10425 @item @emph{Class}:
10426 Transformational function
10428 @item @emph{Syntax}:
10429 @multitable @columnfractions .80
10430 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK] [,KIND] [,BACK])}
10431 @item @code{RESULT = MINLOC(ARRAY [, MASK], [,KIND] [,BACK])}
10434 @item @emph{Arguments}:
10435 @multitable @columnfractions .15 .70
10436 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
10437 @code{REAL} or @code{CHARACTER}.
10438 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10439 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10440 inclusive. It may not be an optional dummy argument.
10441 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
10442 and conformable with @var{ARRAY}.
10443 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10444 expression indicating the kind parameter of the result.
10445 @item @var{BACK} @tab (Optional) A scalar of type @code{LOGICAL}.
10448 @item @emph{Return value}:
10449 If @var{DIM} is absent, the result is a rank-one array with a length
10450 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
10451 is an array with a rank one less than the rank of @var{ARRAY}, and a
10452 size corresponding to the size of @var{ARRAY} with the @var{DIM}
10453 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
10454 of one, the result is a scalar. If the optional argument @var{KIND}
10455 is present, the result is an integer of kind @var{KIND}, otherwise it
10456 is of default kind.
10458 @item @emph{See also}:
10459 @ref{FINDLOC}, @ref{MIN}, @ref{MINVAL}
10466 @section @code{MINVAL} --- Minimum value of an array
10468 @cindex array, minimum value
10469 @cindex minimum value
10472 @item @emph{Description}:
10473 Determines the minimum value of the elements in an array value, or, if
10474 the @var{DIM} argument is supplied, determines the minimum value along
10475 each row of the array in the @var{DIM} direction. If @var{MASK} is
10476 present, only the elements for which @var{MASK} is @code{.TRUE.} are
10477 considered. If the array has zero size, or all of the elements of
10478 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
10479 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
10480 @var{ARRAY} is of character type.
10482 @item @emph{Standard}:
10483 Fortran 95 and later
10485 @item @emph{Class}:
10486 Transformational function
10488 @item @emph{Syntax}:
10489 @multitable @columnfractions .80
10490 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
10491 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
10494 @item @emph{Arguments}:
10495 @multitable @columnfractions .15 .70
10496 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
10498 @item @var{DIM} @tab (Optional) Shall be a scalar of type
10499 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
10500 inclusive. It may not be an optional dummy argument.
10501 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
10502 and conformable with @var{ARRAY}.
10505 @item @emph{Return value}:
10506 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
10507 is a scalar. If @var{DIM} is present, the result is an array with a
10508 rank one less than the rank of @var{ARRAY}, and a size corresponding to
10509 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
10510 cases, the result is of the same type and kind as @var{ARRAY}.
10512 @item @emph{See also}:
10513 @ref{MIN}, @ref{MINLOC}
10520 @section @code{MOD} --- Remainder function
10529 @cindex division, remainder
10532 @item @emph{Description}:
10533 @code{MOD(A,P)} computes the remainder of the division of A by P@.
10535 @item @emph{Standard}:
10536 Fortran 77 and later, has overloads that are GNU extensions
10538 @item @emph{Class}:
10541 @item @emph{Syntax}:
10542 @code{RESULT = MOD(A, P)}
10544 @item @emph{Arguments}:
10545 @multitable @columnfractions .15 .70
10546 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
10547 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
10548 and not equal to zero.
10551 @item @emph{Return value}:
10552 The return value is the result of @code{A - (INT(A/P) * P)}. The type
10553 and kind of the return value is the same as that of the arguments. The
10554 returned value has the same sign as A and a magnitude less than the
10557 @item @emph{Example}:
10561 print *, mod(17.5,5.5)
10562 print *, mod(17.5d0,5.5)
10563 print *, mod(17.5,5.5d0)
10565 print *, mod(-17,3)
10566 print *, mod(-17.5,5.5)
10567 print *, mod(-17.5d0,5.5)
10568 print *, mod(-17.5,5.5d0)
10570 print *, mod(17,-3)
10571 print *, mod(17.5,-5.5)
10572 print *, mod(17.5d0,-5.5)
10573 print *, mod(17.5,-5.5d0)
10574 end program test_mod
10577 @item @emph{Specific names}:
10578 @multitable @columnfractions .20 .20 .20 .25
10579 @item Name @tab Arguments @tab Return type @tab Standard
10580 @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
10581 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
10582 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
10583 @item @code{BMOD(A,P)} @tab @code{INTEGER(1) A,P} @tab @code{INTEGER(1)} @tab GNU extension
10584 @item @code{IMOD(A,P)} @tab @code{INTEGER(2) A,P} @tab @code{INTEGER(2)} @tab GNU extension
10585 @item @code{JMOD(A,P)} @tab @code{INTEGER(4) A,P} @tab @code{INTEGER(4)} @tab GNU extension
10586 @item @code{KMOD(A,P)} @tab @code{INTEGER(8) A,P} @tab @code{INTEGER(8)} @tab GNU extension
10589 @item @emph{See also}:
10597 @section @code{MODULO} --- Modulo function
10600 @cindex division, modulo
10603 @item @emph{Description}:
10604 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
10606 @item @emph{Standard}:
10607 Fortran 95 and later
10609 @item @emph{Class}:
10612 @item @emph{Syntax}:
10613 @code{RESULT = MODULO(A, P)}
10615 @item @emph{Arguments}:
10616 @multitable @columnfractions .15 .70
10617 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
10618 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}.
10619 It shall not be zero.
10622 @item @emph{Return value}:
10623 The type and kind of the result are those of the arguments.
10625 @item If @var{A} and @var{P} are of type @code{INTEGER}:
10626 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
10627 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
10629 @item If @var{A} and @var{P} are of type @code{REAL}:
10630 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
10632 The returned value has the same sign as P and a magnitude less than
10633 the magnitude of P.
10635 @item @emph{Example}:
10637 program test_modulo
10638 print *, modulo(17,3)
10639 print *, modulo(17.5,5.5)
10641 print *, modulo(-17,3)
10642 print *, modulo(-17.5,5.5)
10644 print *, modulo(17,-3)
10645 print *, modulo(17.5,-5.5)
10649 @item @emph{See also}:
10657 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
10658 @fnindex MOVE_ALLOC
10659 @cindex moving allocation
10660 @cindex allocation, moving
10663 @item @emph{Description}:
10664 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
10665 @var{TO}. @var{FROM} will become deallocated in the process.
10667 @item @emph{Standard}:
10668 Fortran 2003 and later
10670 @item @emph{Class}:
10673 @item @emph{Syntax}:
10674 @code{CALL MOVE_ALLOC(FROM, TO)}
10676 @item @emph{Arguments}:
10677 @multitable @columnfractions .15 .70
10678 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
10679 of any type and kind.
10680 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
10681 of the same type, kind and rank as @var{FROM}.
10684 @item @emph{Return value}:
10687 @item @emph{Example}:
10689 program test_move_alloc
10690 integer, allocatable :: a(:), b(:)
10694 call move_alloc(a, b)
10695 print *, allocated(a), allocated(b)
10697 end program test_move_alloc
10704 @section @code{MVBITS} --- Move bits from one integer to another
10713 @item @emph{Description}:
10714 Moves @var{LEN} bits from positions @var{FROMPOS} through
10715 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
10716 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
10717 affected by the movement of bits is unchanged. The values of
10718 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
10719 @code{BIT_SIZE(FROM)}.
10721 @item @emph{Standard}:
10722 Fortran 95 and later, has overloads that are GNU extensions
10724 @item @emph{Class}:
10725 Elemental subroutine
10727 @item @emph{Syntax}:
10728 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
10730 @item @emph{Arguments}:
10731 @multitable @columnfractions .15 .70
10732 @item @var{FROM} @tab The type shall be @code{INTEGER}.
10733 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
10734 @item @var{LEN} @tab The type shall be @code{INTEGER}.
10735 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
10736 same kind as @var{FROM}.
10737 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
10740 @item @emph{Specific names}:
10741 @multitable @columnfractions .20 .20 .20 .25
10742 @item Name @tab Argument @tab Return type @tab Standard
10743 @item @code{MVBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
10744 @item @code{BMVBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
10745 @item @code{IMVBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
10746 @item @code{JMVBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
10747 @item @code{KMVBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
10750 @item @emph{See also}:
10751 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
10757 @section @code{NEAREST} --- Nearest representable number
10759 @cindex real number, nearest different
10760 @cindex floating point, nearest different
10763 @item @emph{Description}:
10764 @code{NEAREST(X, S)} returns the processor-representable number nearest
10765 to @code{X} in the direction indicated by the sign of @code{S}.
10767 @item @emph{Standard}:
10768 Fortran 95 and later
10770 @item @emph{Class}:
10773 @item @emph{Syntax}:
10774 @code{RESULT = NEAREST(X, S)}
10776 @item @emph{Arguments}:
10777 @multitable @columnfractions .15 .70
10778 @item @var{X} @tab Shall be of type @code{REAL}.
10779 @item @var{S} @tab Shall be of type @code{REAL} and
10783 @item @emph{Return value}:
10784 The return value is of the same type as @code{X}. If @code{S} is
10785 positive, @code{NEAREST} returns the processor-representable number
10786 greater than @code{X} and nearest to it. If @code{S} is negative,
10787 @code{NEAREST} returns the processor-representable number smaller than
10788 @code{X} and nearest to it.
10790 @item @emph{Example}:
10792 program test_nearest
10794 x = nearest(42.0, 1.0)
10795 y = nearest(42.0, -1.0)
10796 write (*,"(3(G20.15))") x, y, x - y
10797 end program test_nearest
10804 @section @code{NEW_LINE} --- New line character
10807 @cindex output, newline
10810 @item @emph{Description}:
10811 @code{NEW_LINE(C)} returns the new-line character.
10813 @item @emph{Standard}:
10814 Fortran 2003 and later
10816 @item @emph{Class}:
10819 @item @emph{Syntax}:
10820 @code{RESULT = NEW_LINE(C)}
10822 @item @emph{Arguments}:
10823 @multitable @columnfractions .15 .70
10824 @item @var{C} @tab The argument shall be a scalar or array of the
10825 type @code{CHARACTER}.
10828 @item @emph{Return value}:
10829 Returns a @var{CHARACTER} scalar of length one with the new-line character of
10830 the same kind as parameter @var{C}.
10832 @item @emph{Example}:
10836 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
10837 end program newline
10844 @section @code{NINT} --- Nearest whole number
10847 @cindex rounding, nearest whole number
10850 @item @emph{Description}:
10851 @code{NINT(A)} rounds its argument to the nearest whole number.
10853 @item @emph{Standard}:
10854 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
10856 @item @emph{Class}:
10859 @item @emph{Syntax}:
10860 @code{RESULT = NINT(A [, KIND])}
10862 @item @emph{Arguments}:
10863 @multitable @columnfractions .15 .70
10864 @item @var{A} @tab The type of the argument shall be @code{REAL}.
10865 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10866 expression indicating the kind parameter of the result.
10869 @item @emph{Return value}:
10870 Returns @var{A} with the fractional portion of its magnitude eliminated by
10871 rounding to the nearest whole number and with its sign preserved,
10872 converted to an @code{INTEGER} of the default kind.
10874 @item @emph{Example}:
10881 print *, nint(x4), idnint(x8)
10882 end program test_nint
10885 @item @emph{Specific names}:
10886 @multitable @columnfractions .20 .20 .20 .25
10887 @item Name @tab Argument @tab Return Type @tab Standard
10888 @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later
10889 @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later
10892 @item @emph{See also}:
10893 @ref{CEILING}, @ref{FLOOR}
10900 @section @code{NORM2} --- Euclidean vector norms
10902 @cindex Euclidean vector norm
10903 @cindex L2 vector norm
10904 @cindex norm, Euclidean
10907 @item @emph{Description}:
10908 Calculates the Euclidean vector norm (@math{L_2} norm) of
10909 of @var{ARRAY} along dimension @var{DIM}.
10911 @item @emph{Standard}:
10912 Fortran 2008 and later
10914 @item @emph{Class}:
10915 Transformational function
10917 @item @emph{Syntax}:
10918 @multitable @columnfractions .80
10919 @item @code{RESULT = NORM2(ARRAY[, DIM])}
10922 @item @emph{Arguments}:
10923 @multitable @columnfractions .15 .70
10924 @item @var{ARRAY} @tab Shall be an array of type @code{REAL}
10925 @item @var{DIM} @tab (Optional) shall be a scalar of type
10926 @code{INTEGER} with a value in the range from 1 to n, where n
10927 equals the rank of @var{ARRAY}.
10930 @item @emph{Return value}:
10931 The result is of the same type as @var{ARRAY}.
10933 If @var{DIM} is absent, a scalar with the square root of the sum of all
10934 elements in @var{ARRAY} squared is returned. Otherwise, an array of
10935 rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
10936 shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
10939 @item @emph{Example}:
10942 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
10943 print *, NORM2(x) ! = sqrt(55.) ~ 7.416
10951 @section @code{NOT} --- Logical negation
10957 @cindex bits, negate
10958 @cindex bitwise logical not
10959 @cindex logical not, bitwise
10962 @item @emph{Description}:
10963 @code{NOT} returns the bitwise Boolean inverse of @var{I}.
10965 @item @emph{Standard}:
10966 Fortran 95 and later, has overloads that are GNU extensions
10968 @item @emph{Class}:
10971 @item @emph{Syntax}:
10972 @code{RESULT = NOT(I)}
10974 @item @emph{Arguments}:
10975 @multitable @columnfractions .15 .70
10976 @item @var{I} @tab The type shall be @code{INTEGER}.
10979 @item @emph{Return value}:
10980 The return type is @code{INTEGER}, of the same kind as the
10983 @item @emph{Specific names}:
10984 @multitable @columnfractions .20 .20 .20 .25
10985 @item Name @tab Argument @tab Return type @tab Standard
10986 @item @code{NOT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
10987 @item @code{BNOT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
10988 @item @code{INOT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
10989 @item @code{JNOT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
10990 @item @code{KNOT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
10993 @item @emph{See also}:
10994 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
11001 @section @code{NULL} --- Function that returns an disassociated pointer
11003 @cindex pointer, status
11004 @cindex pointer, disassociated
11007 @item @emph{Description}:
11008 Returns a disassociated pointer.
11010 If @var{MOLD} is present, a disassociated pointer of the same type is
11011 returned, otherwise the type is determined by context.
11013 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
11014 includes cases where it is required.
11016 @item @emph{Standard}:
11017 Fortran 95 and later
11019 @item @emph{Class}:
11020 Transformational function
11022 @item @emph{Syntax}:
11023 @code{PTR => NULL([MOLD])}
11025 @item @emph{Arguments}:
11026 @multitable @columnfractions .15 .70
11027 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
11028 status and of any type.
11031 @item @emph{Return value}:
11032 A disassociated pointer.
11034 @item @emph{Example}:
11036 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
11039 @item @emph{See also}:
11046 @section @code{NUM_IMAGES} --- Function that returns the number of images
11047 @fnindex NUM_IMAGES
11048 @cindex coarray, @code{NUM_IMAGES}
11049 @cindex images, number of
11052 @item @emph{Description}:
11053 Returns the number of images.
11055 @item @emph{Standard}:
11056 Fortran 2008 and later. With @var{DISTANCE} or @var{FAILED} argument,
11057 Technical Specification (TS) 18508 or later
11060 @item @emph{Class}:
11061 Transformational function
11063 @item @emph{Syntax}:
11064 @code{RESULT = NUM_IMAGES(DISTANCE, FAILED)}
11066 @item @emph{Arguments}:
11067 @multitable @columnfractions .15 .70
11068 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
11069 @item @var{FAILED} @tab (optional, intent(in)) Scalar logical expression
11072 @item @emph{Return value}:
11073 Scalar default-kind integer. If @var{DISTANCE} is not present or has value 0,
11074 the number of images in the current team is returned. For values smaller or
11075 equal distance to the initial team, it returns the number of images index
11076 on the ancestor team which has a distance of @var{DISTANCE} from the invoking
11077 team. If @var{DISTANCE} is larger than the distance to the initial team, the
11078 number of images of the initial team is returned. If @var{FAILED} is not present
11079 the total number of images is returned; if it has the value @code{.TRUE.},
11080 the number of failed images is returned, otherwise, the number of images which
11081 do have not the failed status.
11083 @item @emph{Example}:
11085 INTEGER :: value[*]
11087 value = THIS_IMAGE()
11089 IF (THIS_IMAGE() == 1) THEN
11090 DO i = 1, NUM_IMAGES()
11091 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
11096 @item @emph{See also}:
11097 @ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
11103 @section @code{OR} --- Bitwise logical OR
11105 @cindex bitwise logical or
11106 @cindex logical or, bitwise
11109 @item @emph{Description}:
11110 Bitwise logical @code{OR}.
11112 This intrinsic routine is provided for backwards compatibility with
11113 GNU Fortran 77. For integer arguments, programmers should consider
11114 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
11116 @item @emph{Standard}:
11119 @item @emph{Class}:
11122 @item @emph{Syntax}:
11123 @code{RESULT = OR(I, J)}
11125 @item @emph{Arguments}:
11126 @multitable @columnfractions .15 .70
11127 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
11128 type or a scalar @code{LOGICAL} type.
11129 @item @var{J} @tab The type shall be the same as the type of @var{J}.
11132 @item @emph{Return value}:
11133 The return type is either a scalar @code{INTEGER} or a scalar
11134 @code{LOGICAL}. If the kind type parameters differ, then the
11135 smaller kind type is implicitly converted to larger kind, and the
11136 return has the larger kind.
11138 @item @emph{Example}:
11141 LOGICAL :: T = .TRUE., F = .FALSE.
11143 DATA a / Z'F' /, b / Z'3' /
11145 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
11146 WRITE (*,*) OR(a, b)
11150 @item @emph{See also}:
11151 Fortran 95 elemental function: @ref{IOR}
11157 @section @code{PACK} --- Pack an array into an array of rank one
11159 @cindex array, packing
11160 @cindex array, reduce dimension
11161 @cindex array, gather elements
11164 @item @emph{Description}:
11165 Stores the elements of @var{ARRAY} in an array of rank one.
11167 The beginning of the resulting array is made up of elements whose @var{MASK}
11168 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
11171 @item @emph{Standard}:
11172 Fortran 95 and later
11174 @item @emph{Class}:
11175 Transformational function
11177 @item @emph{Syntax}:
11178 @code{RESULT = PACK(ARRAY, MASK[,VECTOR])}
11180 @item @emph{Arguments}:
11181 @multitable @columnfractions .15 .70
11182 @item @var{ARRAY} @tab Shall be an array of any type.
11183 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
11184 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
11186 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
11187 as @var{ARRAY} and of rank one. If present, the number of elements in
11188 @var{VECTOR} shall be equal to or greater than the number of true elements
11189 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
11190 @var{VECTOR} shall be equal to or greater than the number of elements in
11194 @item @emph{Return value}:
11195 The result is an array of rank one and the same type as that of @var{ARRAY}.
11196 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
11197 number of @code{TRUE} values in @var{MASK} otherwise.
11199 @item @emph{Example}:
11200 Gathering nonzero elements from an array:
11202 PROGRAM test_pack_1
11204 m = (/ 1, 0, 0, 0, 5, 0 /)
11205 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
11209 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
11211 PROGRAM test_pack_2
11213 m = (/ 1, 0, 0, 2 /)
11214 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
11218 @item @emph{See also}:
11225 @section @code{PARITY} --- Reduction with exclusive OR
11228 @cindex Reduction, XOR
11229 @cindex XOR reduction
11232 @item @emph{Description}:
11233 Calculates the parity, i.e. the reduction using @code{.XOR.},
11234 of @var{MASK} along dimension @var{DIM}.
11236 @item @emph{Standard}:
11237 Fortran 2008 and later
11239 @item @emph{Class}:
11240 Transformational function
11242 @item @emph{Syntax}:
11243 @multitable @columnfractions .80
11244 @item @code{RESULT = PARITY(MASK[, DIM])}
11247 @item @emph{Arguments}:
11248 @multitable @columnfractions .15 .70
11249 @item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL}
11250 @item @var{DIM} @tab (Optional) shall be a scalar of type
11251 @code{INTEGER} with a value in the range from 1 to n, where n
11252 equals the rank of @var{MASK}.
11255 @item @emph{Return value}:
11256 The result is of the same type as @var{MASK}.
11258 If @var{DIM} is absent, a scalar with the parity of all elements in
11259 @var{MASK} is returned, i.e. true if an odd number of elements is
11260 @code{.true.} and false otherwise. If @var{DIM} is present, an array
11261 of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
11262 and a shape similar to that of @var{MASK} with dimension @var{DIM}
11263 dropped is returned.
11265 @item @emph{Example}:
11268 LOGICAL :: x(2) = [ .true., .false. ]
11269 print *, PARITY(x) ! prints "T" (true).
11277 @section @code{PERROR} --- Print system error message
11279 @cindex system, error handling
11282 @item @emph{Description}:
11283 Prints (on the C @code{stderr} stream) a newline-terminated error
11284 message corresponding to the last system error. This is prefixed by
11285 @var{STRING}, a colon and a space. See @code{perror(3)}.
11287 @item @emph{Standard}:
11290 @item @emph{Class}:
11293 @item @emph{Syntax}:
11294 @code{CALL PERROR(STRING)}
11296 @item @emph{Arguments}:
11297 @multitable @columnfractions .15 .70
11298 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
11302 @item @emph{See also}:
11309 @section @code{POPCNT} --- Number of bits set
11311 @cindex binary representation
11315 @item @emph{Description}:
11316 @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
11317 representation of @code{I}.
11319 @item @emph{Standard}:
11320 Fortran 2008 and later
11322 @item @emph{Class}:
11325 @item @emph{Syntax}:
11326 @code{RESULT = POPCNT(I)}
11328 @item @emph{Arguments}:
11329 @multitable @columnfractions .15 .70
11330 @item @var{I} @tab Shall be of type @code{INTEGER}.
11333 @item @emph{Return value}:
11334 The return value is of type @code{INTEGER} and of the default integer
11337 @item @emph{See also}:
11338 @ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ}
11340 @item @emph{Example}:
11342 program test_population
11343 print *, popcnt(127), poppar(127)
11344 print *, popcnt(huge(0_4)), poppar(huge(0_4))
11345 print *, popcnt(huge(0_8)), poppar(huge(0_8))
11346 end program test_population
11352 @section @code{POPPAR} --- Parity of the number of bits set
11354 @cindex binary representation
11358 @item @emph{Description}:
11359 @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
11360 of the number of bits set ('1' bits) in the binary representation of
11361 @code{I}. It is equal to 0 if @code{I} has an even number of bits set,
11362 and 1 for an odd number of '1' bits.
11364 @item @emph{Standard}:
11365 Fortran 2008 and later
11367 @item @emph{Class}:
11370 @item @emph{Syntax}:
11371 @code{RESULT = POPPAR(I)}
11373 @item @emph{Arguments}:
11374 @multitable @columnfractions .15 .70
11375 @item @var{I} @tab Shall be of type @code{INTEGER}.
11378 @item @emph{Return value}:
11379 The return value is of type @code{INTEGER} and of the default integer
11382 @item @emph{See also}:
11383 @ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ}
11385 @item @emph{Example}:
11387 program test_population
11388 print *, popcnt(127), poppar(127)
11389 print *, popcnt(huge(0_4)), poppar(huge(0_4))
11390 print *, popcnt(huge(0_8)), poppar(huge(0_8))
11391 end program test_population
11398 @section @code{PRECISION} --- Decimal precision of a real kind
11400 @cindex model representation, precision
11403 @item @emph{Description}:
11404 @code{PRECISION(X)} returns the decimal precision in the model of the
11407 @item @emph{Standard}:
11408 Fortran 95 and later
11410 @item @emph{Class}:
11413 @item @emph{Syntax}:
11414 @code{RESULT = PRECISION(X)}
11416 @item @emph{Arguments}:
11417 @multitable @columnfractions .15 .70
11418 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
11421 @item @emph{Return value}:
11422 The return value is of type @code{INTEGER} and of the default integer
11425 @item @emph{See also}:
11426 @ref{SELECTED_REAL_KIND}, @ref{RANGE}
11428 @item @emph{Example}:
11430 program prec_and_range
11431 real(kind=4) :: x(2)
11432 complex(kind=8) :: y
11434 print *, precision(x), range(x)
11435 print *, precision(y), range(y)
11436 end program prec_and_range
11443 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
11447 @item @emph{Description}:
11448 Determines whether an optional dummy argument is present.
11450 @item @emph{Standard}:
11451 Fortran 95 and later
11453 @item @emph{Class}:
11456 @item @emph{Syntax}:
11457 @code{RESULT = PRESENT(A)}
11459 @item @emph{Arguments}:
11460 @multitable @columnfractions .15 .70
11461 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
11462 value, or a dummy procedure. It shall be the name of an optional dummy argument
11463 accessible within the current subroutine or function.
11466 @item @emph{Return value}:
11467 Returns either @code{TRUE} if the optional argument @var{A} is present, or
11468 @code{FALSE} otherwise.
11470 @item @emph{Example}:
11472 PROGRAM test_present
11473 WRITE(*,*) f(), f(42) ! "F T"
11475 LOGICAL FUNCTION f(x)
11476 INTEGER, INTENT(IN), OPTIONAL :: x
11486 @section @code{PRODUCT} --- Product of array elements
11488 @cindex array, product
11489 @cindex array, multiply elements
11490 @cindex array, conditionally multiply elements
11491 @cindex multiply array elements
11494 @item @emph{Description}:
11495 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
11496 the corresponding element in @var{MASK} is @code{TRUE}.
11498 @item @emph{Standard}:
11499 Fortran 95 and later
11501 @item @emph{Class}:
11502 Transformational function
11504 @item @emph{Syntax}:
11505 @multitable @columnfractions .80
11506 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
11507 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
11510 @item @emph{Arguments}:
11511 @multitable @columnfractions .15 .70
11512 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
11513 @code{REAL} or @code{COMPLEX}.
11514 @item @var{DIM} @tab (Optional) shall be a scalar of type
11515 @code{INTEGER} with a value in the range from 1 to n, where n
11516 equals the rank of @var{ARRAY}.
11517 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
11518 and either be a scalar or an array of the same shape as @var{ARRAY}.
11521 @item @emph{Return value}:
11522 The result is of the same type as @var{ARRAY}.
11524 If @var{DIM} is absent, a scalar with the product of all elements in
11525 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
11526 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
11527 dimension @var{DIM} dropped is returned.
11530 @item @emph{Example}:
11532 PROGRAM test_product
11533 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
11534 print *, PRODUCT(x) ! all elements, product = 120
11535 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
11539 @item @emph{See also}:
11546 @section @code{RADIX} --- Base of a model number
11548 @cindex model representation, base
11549 @cindex model representation, radix
11552 @item @emph{Description}:
11553 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
11555 @item @emph{Standard}:
11556 Fortran 95 and later
11558 @item @emph{Class}:
11561 @item @emph{Syntax}:
11562 @code{RESULT = RADIX(X)}
11564 @item @emph{Arguments}:
11565 @multitable @columnfractions .15 .70
11566 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
11569 @item @emph{Return value}:
11570 The return value is a scalar of type @code{INTEGER} and of the default
11573 @item @emph{See also}:
11574 @ref{SELECTED_REAL_KIND}
11576 @item @emph{Example}:
11579 print *, "The radix for the default integer kind is", radix(0)
11580 print *, "The radix for the default real kind is", radix(0.0)
11581 end program test_radix
11589 @section @code{RAN} --- Real pseudo-random number
11591 @cindex random number generation
11594 @item @emph{Description}:
11595 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
11596 provided as an alias for @code{RAND}. See @ref{RAND} for complete
11599 @item @emph{Standard}:
11602 @item @emph{Class}:
11605 @item @emph{See also}:
11606 @ref{RAND}, @ref{RANDOM_NUMBER}
11612 @section @code{RAND} --- Real pseudo-random number
11614 @cindex random number generation
11617 @item @emph{Description}:
11618 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
11619 distribution between 0 and 1. If @var{FLAG} is 0, the next number
11620 in the current sequence is returned; if @var{FLAG} is 1, the generator
11621 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
11622 it is used as a new seed with @code{SRAND}.
11624 This intrinsic routine is provided for backwards compatibility with
11625 GNU Fortran 77. It implements a simple modulo generator as provided
11626 by @command{g77}. For new code, one should consider the use of
11627 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
11629 @item @emph{Standard}:
11632 @item @emph{Class}:
11635 @item @emph{Syntax}:
11636 @code{RESULT = RAND(I)}
11638 @item @emph{Arguments}:
11639 @multitable @columnfractions .15 .70
11640 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
11643 @item @emph{Return value}:
11644 The return value is of @code{REAL} type and the default kind.
11646 @item @emph{Example}:
11649 integer,parameter :: seed = 86456
11652 print *, rand(), rand(), rand(), rand()
11653 print *, rand(seed), rand(), rand(), rand()
11654 end program test_rand
11657 @item @emph{See also}:
11658 @ref{SRAND}, @ref{RANDOM_NUMBER}
11664 @section @code{RANDOM_INIT} --- Initialize a pseudo-random number generator
11665 @fnindex RANDOM_INIT
11666 @cindex random number generation, initialization
11669 @item @emph{Description}:
11670 Initializes the state of the pseudorandom number generator used by
11671 @code{RANDOM_NUMBER}.
11673 @item @emph{Standard}:
11676 @item @emph{Class}:
11679 @item @emph{Syntax}:
11680 @code{CALL RANDOM_INIT(REPEATABLE, IMAGE_DISTINCT)}
11682 @item @emph{Arguments}:
11683 @multitable @columnfractions .20 .75
11684 @item @var{REPEATABLE} @tab Shall be a scalar with a @code{LOGICAL} type,
11685 and it is @code{INTENT(IN)}. If it is @code{.true.}, the seed is set to
11686 a processor-dependent value that is the same each time @code{RANDOM_INIT}
11687 is called from the same image. The term ``same image'' means a single
11688 instance of program execution. The sequence of random numbers is different
11689 for repeated execution of the program. If it is @code{.false.}, the seed
11690 is set to a processor-dependent value.
11691 @item @var{IMAGE_DISTINCT} @tab Shall be a scalar with a
11692 @code{LOGICAL} type, and it is @code{INTENT(IN)}. If it is @code{.true.},
11693 the seed is set to a processor-dependent value that is distinct from th
11694 seed set by a call to @code{RANDOM_INIT} in another image. If it is
11695 @code{.false.}, the seed is set value that does depend which image called
11696 @code{RANDOM_INIT}.
11699 @item @emph{Example}:
11701 program test_random_seed
11704 call random_init(.true., .true.)
11705 call random_number(x)
11706 call random_init(.true., .true.)
11707 call random_number(y)
11708 ! x and y are the same sequence
11709 if (any(x /= y)) call abort
11710 end program test_random_seed
11713 @item @emph{See also}:
11714 @ref{RANDOM_NUMBER}, @ref{RANDOM_SEED}
11718 @node RANDOM_NUMBER
11719 @section @code{RANDOM_NUMBER} --- Pseudo-random number
11720 @fnindex RANDOM_NUMBER
11721 @cindex random number generation
11724 @item @emph{Description}:
11725 Returns a single pseudorandom number or an array of pseudorandom numbers
11726 from the uniform distribution over the range @math{ 0 \leq x < 1}.
11728 The runtime-library implements the xorshift1024* random number
11729 generator (RNG). This generator has a period of @math{2^{1024} - 1},
11730 and when using multiple threads up to @math{2^{512}} threads can each
11731 generate @math{2^{512}} random numbers before any aliasing occurs.
11733 Note that in a multi-threaded program (e.g. using OpenMP directives),
11734 each thread will have its own random number state. For details of the
11735 seeding procedure, see the documentation for the @code{RANDOM_SEED}
11739 @item @emph{Standard}:
11740 Fortran 95 and later
11742 @item @emph{Class}:
11745 @item @emph{Syntax}:
11746 @code{RANDOM_NUMBER(HARVEST)}
11748 @item @emph{Arguments}:
11749 @multitable @columnfractions .15 .70
11750 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
11753 @item @emph{Example}:
11755 program test_random_number
11757 CALL RANDOM_NUMBER(r)
11761 @item @emph{See also}:
11762 @ref{RANDOM_SEED}, @ref{RANDOM_INIT}
11768 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
11769 @fnindex RANDOM_SEED
11770 @cindex random number generation, seeding
11771 @cindex seeding a random number generator
11774 @item @emph{Description}:
11775 Restarts or queries the state of the pseudorandom number generator used by
11776 @code{RANDOM_NUMBER}.
11778 If @code{RANDOM_SEED} is called without arguments, it is seeded with
11779 random data retrieved from the operating system.
11781 As an extension to the Fortran standard, the GFortran
11782 @code{RANDOM_NUMBER} supports multiple threads. Each thread in a
11783 multi-threaded program has its own seed. When @code{RANDOM_SEED} is
11784 called either without arguments or with the @var{PUT} argument, the
11785 given seed is copied into a master seed as well as the seed of the
11786 current thread. When a new thread uses @code{RANDOM_NUMBER} for the
11787 first time, the seed is copied from the master seed, and forwarded
11788 @math{N * 2^{512}} steps to guarantee that the random stream does not
11789 alias any other stream in the system, where @var{N} is the number of
11790 threads that have used @code{RANDOM_NUMBER} so far during the program
11793 @item @emph{Standard}:
11794 Fortran 95 and later
11796 @item @emph{Class}:
11799 @item @emph{Syntax}:
11800 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
11802 @item @emph{Arguments}:
11803 @multitable @columnfractions .15 .70
11804 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
11805 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
11806 of the arrays used with the @var{PUT} and @var{GET} arguments.
11807 @item @var{PUT} @tab (Optional) Shall be an array of type default
11808 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
11809 the array must be larger than or equal to the number returned by the
11810 @var{SIZE} argument.
11811 @item @var{GET} @tab (Optional) Shall be an array of type default
11812 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
11813 of the array must be larger than or equal to the number returned by
11814 the @var{SIZE} argument.
11817 @item @emph{Example}:
11819 program test_random_seed
11821 integer, allocatable :: seed(:)
11824 call random_seed(size = n)
11826 call random_seed(get=seed)
11828 end program test_random_seed
11831 @item @emph{See also}:
11832 @ref{RANDOM_NUMBER}, @ref{RANDOM_INIT}
11838 @section @code{RANGE} --- Decimal exponent range
11840 @cindex model representation, range
11843 @item @emph{Description}:
11844 @code{RANGE(X)} returns the decimal exponent range in the model of the
11847 @item @emph{Standard}:
11848 Fortran 95 and later
11850 @item @emph{Class}:
11853 @item @emph{Syntax}:
11854 @code{RESULT = RANGE(X)}
11856 @item @emph{Arguments}:
11857 @multitable @columnfractions .15 .70
11858 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
11862 @item @emph{Return value}:
11863 The return value is of type @code{INTEGER} and of the default integer
11866 @item @emph{See also}:
11867 @ref{SELECTED_REAL_KIND}, @ref{PRECISION}
11869 @item @emph{Example}:
11870 See @code{PRECISION} for an example.
11876 @section @code{RANK} --- Rank of a data object
11881 @item @emph{Description}:
11882 @code{RANK(A)} returns the rank of a scalar or array data object.
11884 @item @emph{Standard}:
11885 Technical Specification (TS) 29113
11887 @item @emph{Class}:
11890 @item @emph{Syntax}:
11891 @code{RESULT = RANK(A)}
11893 @item @emph{Arguments}:
11894 @multitable @columnfractions .15 .70
11895 @item @var{A} @tab can be of any type
11898 @item @emph{Return value}:
11899 The return value is of type @code{INTEGER} and of the default integer
11900 kind. For arrays, their rank is returned; for scalars zero is returned.
11902 @item @emph{Example}:
11906 real, allocatable :: b(:,:)
11908 print *, rank(a), rank(b) ! Prints: 0 2
11909 end program test_rank
11917 @section @code{REAL} --- Convert to real type
11926 @cindex conversion, to real
11927 @cindex complex numbers, real part
11930 @item @emph{Description}:
11931 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
11932 @code{REALPART} function is provided for compatibility with @command{g77},
11933 and its use is strongly discouraged.
11935 @item @emph{Standard}:
11936 Fortran 77 and later
11938 @item @emph{Class}:
11941 @item @emph{Syntax}:
11942 @multitable @columnfractions .80
11943 @item @code{RESULT = REAL(A [, KIND])}
11944 @item @code{RESULT = REALPART(Z)}
11947 @item @emph{Arguments}:
11948 @multitable @columnfractions .15 .70
11949 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
11951 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11952 expression indicating the kind parameter of the result.
11955 @item @emph{Return value}:
11956 These functions return a @code{REAL} variable or array under
11957 the following rules:
11961 @code{REAL(A)} is converted to a default real type if @var{A} is an
11962 integer or real variable.
11964 @code{REAL(A)} is converted to a real type with the kind type parameter
11965 of @var{A} if @var{A} is a complex variable.
11967 @code{REAL(A, KIND)} is converted to a real type with kind type
11968 parameter @var{KIND} if @var{A} is a complex, integer, or real
11972 @item @emph{Example}:
11975 complex :: x = (1.0, 2.0)
11976 print *, real(x), real(x,8), realpart(x)
11977 end program test_real
11980 @item @emph{Specific names}:
11981 @multitable @columnfractions .20 .20 .20 .25
11982 @item Name @tab Argument @tab Return type @tab Standard
11983 @item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later
11984 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension
11985 @item @code{FLOATI(A)} @tab @code{INTEGER(2)} @tab @code{REAL(4)} @tab GNU extension
11986 @item @code{FLOATJ(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab GNU extension
11987 @item @code{FLOATK(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab GNU extension
11988 @item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab Fortran 77 and later
11992 @item @emph{See also}:
12000 @section @code{RENAME} --- Rename a file
12002 @cindex file system, rename file
12005 @item @emph{Description}:
12006 Renames a file from file @var{PATH1} to @var{PATH2}. A null
12007 character (@code{CHAR(0)}) can be used to mark the end of the names in
12008 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
12009 names are ignored. If the @var{STATUS} argument is supplied, it
12010 contains 0 on success or a nonzero error code upon return; see
12013 This intrinsic is provided in both subroutine and function forms;
12014 however, only one form can be used in any given program unit.
12016 @item @emph{Standard}:
12019 @item @emph{Class}:
12020 Subroutine, function
12022 @item @emph{Syntax}:
12023 @multitable @columnfractions .80
12024 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
12025 @item @code{STATUS = RENAME(PATH1, PATH2)}
12028 @item @emph{Arguments}:
12029 @multitable @columnfractions .15 .70
12030 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
12031 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
12032 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12035 @item @emph{See also}:
12043 @section @code{REPEAT} --- Repeated string concatenation
12045 @cindex string, repeat
12046 @cindex string, concatenate
12049 @item @emph{Description}:
12050 Concatenates @var{NCOPIES} copies of a string.
12052 @item @emph{Standard}:
12053 Fortran 95 and later
12055 @item @emph{Class}:
12056 Transformational function
12058 @item @emph{Syntax}:
12059 @code{RESULT = REPEAT(STRING, NCOPIES)}
12061 @item @emph{Arguments}:
12062 @multitable @columnfractions .15 .70
12063 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
12064 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
12067 @item @emph{Return value}:
12068 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
12071 @item @emph{Example}:
12073 program test_repeat
12074 write(*,*) repeat("x", 5) ! "xxxxx"
12082 @section @code{RESHAPE} --- Function to reshape an array
12084 @cindex array, change dimensions
12085 @cindex array, transmogrify
12088 @item @emph{Description}:
12089 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
12090 the new array may be padded with elements from @var{PAD} or permuted
12091 as defined by @var{ORDER}.
12093 @item @emph{Standard}:
12094 Fortran 95 and later
12096 @item @emph{Class}:
12097 Transformational function
12099 @item @emph{Syntax}:
12100 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
12102 @item @emph{Arguments}:
12103 @multitable @columnfractions .15 .70
12104 @item @var{SOURCE} @tab Shall be an array of any type.
12105 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
12106 array of rank one. Its values must be positive or zero.
12107 @item @var{PAD} @tab (Optional) shall be an array of the same
12108 type as @var{SOURCE}.
12109 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
12110 and an array of the same shape as @var{SHAPE}. Its values shall
12111 be a permutation of the numbers from 1 to n, where n is the size of
12112 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
12116 @item @emph{Return value}:
12117 The result is an array of shape @var{SHAPE} with the same type as
12120 @item @emph{Example}:
12122 PROGRAM test_reshape
12123 INTEGER, DIMENSION(4) :: x
12124 WRITE(*,*) SHAPE(x) ! prints "4"
12125 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
12129 @item @emph{See also}:
12136 @section @code{RRSPACING} --- Reciprocal of the relative spacing
12138 @cindex real number, relative spacing
12139 @cindex floating point, relative spacing
12143 @item @emph{Description}:
12144 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
12145 model numbers near @var{X}.
12147 @item @emph{Standard}:
12148 Fortran 95 and later
12150 @item @emph{Class}:
12153 @item @emph{Syntax}:
12154 @code{RESULT = RRSPACING(X)}
12156 @item @emph{Arguments}:
12157 @multitable @columnfractions .15 .70
12158 @item @var{X} @tab Shall be of type @code{REAL}.
12161 @item @emph{Return value}:
12162 The return value is of the same type and kind as @var{X}.
12163 The value returned is equal to
12164 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
12166 @item @emph{See also}:
12173 @section @code{RSHIFT} --- Right shift bits
12175 @cindex bits, shift right
12178 @item @emph{Description}:
12179 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
12180 bits shifted right by @var{SHIFT} places. If the absolute value of
12181 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12182 Bits shifted out from the right end are lost. The fill is arithmetic: the
12183 bits shifted in from the left end are equal to the leftmost bit, which in
12184 two's complement representation is the sign bit.
12186 This function has been superseded by the @code{SHIFTA} intrinsic, which
12187 is standard in Fortran 2008 and later.
12189 @item @emph{Standard}:
12192 @item @emph{Class}:
12195 @item @emph{Syntax}:
12196 @code{RESULT = RSHIFT(I, SHIFT)}
12198 @item @emph{Arguments}:
12199 @multitable @columnfractions .15 .70
12200 @item @var{I} @tab The type shall be @code{INTEGER}.
12201 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12204 @item @emph{Return value}:
12205 The return value is of type @code{INTEGER} and of the same kind as
12208 @item @emph{See also}:
12209 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}, @ref{SHIFTA}, @ref{SHIFTR},
12217 @section @code{SAME_TYPE_AS} --- Query dynamic types for equality
12218 @fnindex SAME_TYPE_AS
12221 @item @emph{Description}:
12222 Query dynamic types for equality.
12224 @item @emph{Standard}:
12225 Fortran 2003 and later
12227 @item @emph{Class}:
12230 @item @emph{Syntax}:
12231 @code{RESULT = SAME_TYPE_AS(A, B)}
12233 @item @emph{Arguments}:
12234 @multitable @columnfractions .15 .70
12235 @item @var{A} @tab Shall be an object of extensible declared type or
12236 unlimited polymorphic.
12237 @item @var{B} @tab Shall be an object of extensible declared type or
12238 unlimited polymorphic.
12241 @item @emph{Return value}:
12242 The return value is a scalar of type default logical. It is true if and
12243 only if the dynamic type of A is the same as the dynamic type of B.
12245 @item @emph{See also}:
12246 @ref{EXTENDS_TYPE_OF}
12253 @section @code{SCALE} --- Scale a real value
12255 @cindex real number, scale
12256 @cindex floating point, scale
12259 @item @emph{Description}:
12260 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
12262 @item @emph{Standard}:
12263 Fortran 95 and later
12265 @item @emph{Class}:
12268 @item @emph{Syntax}:
12269 @code{RESULT = SCALE(X, I)}
12271 @item @emph{Arguments}:
12272 @multitable @columnfractions .15 .70
12273 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
12274 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
12277 @item @emph{Return value}:
12278 The return value is of the same type and kind as @var{X}.
12279 Its value is @code{X * RADIX(X)**I}.
12281 @item @emph{Example}:
12284 real :: x = 178.1387e-4
12286 print *, scale(x,i), x*radix(x)**i
12287 end program test_scale
12295 @section @code{SCAN} --- Scan a string for the presence of a set of characters
12297 @cindex string, find subset
12300 @item @emph{Description}:
12301 Scans a @var{STRING} for any of the characters in a @var{SET}
12304 If @var{BACK} is either absent or equals @code{FALSE}, this function
12305 returns the position of the leftmost character of @var{STRING} that is
12306 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
12307 is returned. If no character of @var{SET} is found in @var{STRING}, the
12310 @item @emph{Standard}:
12311 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12313 @item @emph{Class}:
12316 @item @emph{Syntax}:
12317 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
12319 @item @emph{Arguments}:
12320 @multitable @columnfractions .15 .70
12321 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
12322 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
12323 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
12324 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12325 expression indicating the kind parameter of the result.
12328 @item @emph{Return value}:
12329 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12330 @var{KIND} is absent, the return value is of default integer kind.
12332 @item @emph{Example}:
12335 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
12336 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
12337 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
12341 @item @emph{See also}:
12342 @ref{INDEX intrinsic}, @ref{VERIFY}
12348 @section @code{SECNDS} --- Time function
12350 @cindex time, elapsed
12351 @cindex elapsed time
12354 @item @emph{Description}:
12355 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
12356 @var{X} is a reference time, also in seconds. If this is zero, the time in
12357 seconds from midnight is returned. This function is non-standard and its
12358 use is discouraged.
12360 @item @emph{Standard}:
12363 @item @emph{Class}:
12366 @item @emph{Syntax}:
12367 @code{RESULT = SECNDS (X)}
12369 @item @emph{Arguments}:
12370 @multitable @columnfractions .15 .70
12371 @item @var{T} @tab Shall be of type @code{REAL(4)}.
12372 @item @var{X} @tab Shall be of type @code{REAL(4)}.
12375 @item @emph{Return value}:
12378 @item @emph{Example}:
12380 program test_secnds
12383 print *, secnds (0.0) ! seconds since midnight
12384 t1 = secnds (0.0) ! reference time
12385 do i = 1, 10000000 ! do something
12387 t2 = secnds (t1) ! elapsed time
12388 print *, "Something took ", t2, " seconds."
12389 end program test_secnds
12396 @section @code{SECOND} --- CPU time function
12398 @cindex time, elapsed
12399 @cindex elapsed time
12402 @item @emph{Description}:
12403 Returns a @code{REAL(4)} value representing the elapsed CPU time in
12404 seconds. This provides the same functionality as the standard
12405 @code{CPU_TIME} intrinsic, and is only included for backwards
12408 This intrinsic is provided in both subroutine and function forms;
12409 however, only one form can be used in any given program unit.
12411 @item @emph{Standard}:
12414 @item @emph{Class}:
12415 Subroutine, function
12417 @item @emph{Syntax}:
12418 @multitable @columnfractions .80
12419 @item @code{CALL SECOND(TIME)}
12420 @item @code{TIME = SECOND()}
12423 @item @emph{Arguments}:
12424 @multitable @columnfractions .15 .70
12425 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
12428 @item @emph{Return value}:
12429 In either syntax, @var{TIME} is set to the process's current runtime in
12432 @item @emph{See also}:
12439 @node SELECTED_CHAR_KIND
12440 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
12441 @fnindex SELECTED_CHAR_KIND
12442 @cindex character kind
12443 @cindex kind, character
12446 @item @emph{Description}:
12448 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
12449 set named @var{NAME}, if a character set with such a name is supported,
12450 or @math{-1} otherwise. Currently, supported character sets include
12451 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
12452 (Universal Character Set, UCS-4) which is commonly known as Unicode.
12454 @item @emph{Standard}:
12455 Fortran 2003 and later
12457 @item @emph{Class}:
12458 Transformational function
12460 @item @emph{Syntax}:
12461 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
12463 @item @emph{Arguments}:
12464 @multitable @columnfractions .15 .70
12465 @item @var{NAME} @tab Shall be a scalar and of the default character type.
12468 @item @emph{Example}:
12470 program character_kind
12471 use iso_fortran_env
12473 integer, parameter :: ascii = selected_char_kind ("ascii")
12474 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646')
12476 character(kind=ascii, len=26) :: alphabet
12477 character(kind=ucs4, len=30) :: hello_world
12479 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
12480 hello_world = ucs4_'Hello World and Ni Hao -- ' &
12481 // char (int (z'4F60'), ucs4) &
12482 // char (int (z'597D'), ucs4)
12484 write (*,*) alphabet
12486 open (output_unit, encoding='UTF-8')
12487 write (*,*) trim (hello_world)
12488 end program character_kind
12494 @node SELECTED_INT_KIND
12495 @section @code{SELECTED_INT_KIND} --- Choose integer kind
12496 @fnindex SELECTED_INT_KIND
12497 @cindex integer kind
12498 @cindex kind, integer
12501 @item @emph{Description}:
12502 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
12503 type that can represent all values ranging from @math{-10^R} (exclusive)
12504 to @math{10^R} (exclusive). If there is no integer kind that accommodates
12505 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
12507 @item @emph{Standard}:
12508 Fortran 95 and later
12510 @item @emph{Class}:
12511 Transformational function
12513 @item @emph{Syntax}:
12514 @code{RESULT = SELECTED_INT_KIND(R)}
12516 @item @emph{Arguments}:
12517 @multitable @columnfractions .15 .70
12518 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
12521 @item @emph{Example}:
12523 program large_integers
12524 integer,parameter :: k5 = selected_int_kind(5)
12525 integer,parameter :: k15 = selected_int_kind(15)
12526 integer(kind=k5) :: i5
12527 integer(kind=k15) :: i15
12529 print *, huge(i5), huge(i15)
12531 ! The following inequalities are always true
12532 print *, huge(i5) >= 10_k5**5-1
12533 print *, huge(i15) >= 10_k15**15-1
12534 end program large_integers
12540 @node SELECTED_REAL_KIND
12541 @section @code{SELECTED_REAL_KIND} --- Choose real kind
12542 @fnindex SELECTED_REAL_KIND
12545 @cindex radix, real
12548 @item @emph{Description}:
12549 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
12550 with decimal precision of at least @code{P} digits, exponent range of
12551 at least @code{R}, and with a radix of @code{RADIX}.
12553 @item @emph{Standard}:
12554 Fortran 95 and later, with @code{RADIX} Fortran 2008 or later
12556 @item @emph{Class}:
12557 Transformational function
12559 @item @emph{Syntax}:
12560 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
12562 @item @emph{Arguments}:
12563 @multitable @columnfractions .15 .70
12564 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12565 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12566 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
12568 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
12569 be present; since Fortran 2008, they are assumed to be zero if absent.
12571 @item @emph{Return value}:
12573 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
12574 a real data type with decimal precision of at least @code{P} digits, a
12575 decimal exponent range of at least @code{R}, and with the requested
12576 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
12577 any radix can be returned. If more than one real data type meet the
12578 criteria, the kind of the data type with the smallest decimal precision
12579 is returned. If no real data type matches the criteria, the result is
12581 @item -1 if the processor does not support a real data type with a
12582 precision greater than or equal to @code{P}, but the @code{R} and
12583 @code{RADIX} requirements can be fulfilled
12584 @item -2 if the processor does not support a real type with an exponent
12585 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
12587 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
12589 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
12591 @item -5 if there is no real type with the given @code{RADIX}
12594 @item @emph{See also}:
12595 @ref{PRECISION}, @ref{RANGE}, @ref{RADIX}
12597 @item @emph{Example}:
12600 integer,parameter :: p6 = selected_real_kind(6)
12601 integer,parameter :: p10r100 = selected_real_kind(10,100)
12602 integer,parameter :: r400 = selected_real_kind(r=400)
12604 real(kind=p10r100) :: y
12605 real(kind=r400) :: z
12607 print *, precision(x), range(x)
12608 print *, precision(y), range(y)
12609 print *, precision(z), range(z)
12610 end program real_kinds
12617 @section @code{SET_EXPONENT} --- Set the exponent of the model
12618 @fnindex SET_EXPONENT
12619 @cindex real number, set exponent
12620 @cindex floating point, set exponent
12623 @item @emph{Description}:
12624 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
12625 is that that of @var{X} and whose exponent part is @var{I}.
12627 @item @emph{Standard}:
12628 Fortran 95 and later
12630 @item @emph{Class}:
12633 @item @emph{Syntax}:
12634 @code{RESULT = SET_EXPONENT(X, I)}
12636 @item @emph{Arguments}:
12637 @multitable @columnfractions .15 .70
12638 @item @var{X} @tab Shall be of type @code{REAL}.
12639 @item @var{I} @tab Shall be of type @code{INTEGER}.
12642 @item @emph{Return value}:
12643 The return value is of the same type and kind as @var{X}.
12644 The real number whose fractional part
12645 is that that of @var{X} and whose exponent part if @var{I} is returned;
12646 it is @code{FRACTION(X) * RADIX(X)**I}.
12648 @item @emph{Example}:
12650 PROGRAM test_setexp
12651 REAL :: x = 178.1387e-4
12653 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
12662 @section @code{SHAPE} --- Determine the shape of an array
12664 @cindex array, shape
12667 @item @emph{Description}:
12668 Determines the shape of an array.
12670 @item @emph{Standard}:
12671 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12673 @item @emph{Class}:
12676 @item @emph{Syntax}:
12677 @code{RESULT = SHAPE(SOURCE [, KIND])}
12679 @item @emph{Arguments}:
12680 @multitable @columnfractions .15 .70
12681 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
12682 If @var{SOURCE} is a pointer it must be associated and allocatable
12683 arrays must be allocated.
12684 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12685 expression indicating the kind parameter of the result.
12688 @item @emph{Return value}:
12689 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
12690 has dimensions. The elements of the resulting array correspond to the extend
12691 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
12692 the result is the rank one array of size zero. If @var{KIND} is absent, the
12693 return value has the default integer kind otherwise the specified kind.
12695 @item @emph{Example}:
12698 INTEGER, DIMENSION(-1:1, -1:2) :: A
12699 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
12700 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
12704 @item @emph{See also}:
12705 @ref{RESHAPE}, @ref{SIZE}
12711 @section @code{SHIFTA} --- Right shift with fill
12713 @cindex bits, shift right
12714 @cindex shift, right with fill
12717 @item @emph{Description}:
12718 @code{SHIFTA} returns a value corresponding to @var{I} with all of the
12719 bits shifted right by @var{SHIFT} places. If the absolute value of
12720 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12721 Bits shifted out from the right end are lost. The fill is arithmetic: the
12722 bits shifted in from the left end are equal to the leftmost bit, which in
12723 two's complement representation is the sign bit.
12725 @item @emph{Standard}:
12726 Fortran 2008 and later
12728 @item @emph{Class}:
12731 @item @emph{Syntax}:
12732 @code{RESULT = SHIFTA(I, SHIFT)}
12734 @item @emph{Arguments}:
12735 @multitable @columnfractions .15 .70
12736 @item @var{I} @tab The type shall be @code{INTEGER}.
12737 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12740 @item @emph{Return value}:
12741 The return value is of type @code{INTEGER} and of the same kind as
12744 @item @emph{See also}:
12745 @ref{SHIFTL}, @ref{SHIFTR}
12751 @section @code{SHIFTL} --- Left shift
12753 @cindex bits, shift left
12754 @cindex shift, left
12757 @item @emph{Description}:
12758 @code{SHIFTL} returns a value corresponding to @var{I} with all of the
12759 bits shifted left by @var{SHIFT} places. If the absolute value of
12760 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12761 Bits shifted out from the left end are lost, and bits shifted in from
12762 the right end are set to 0.
12764 @item @emph{Standard}:
12765 Fortran 2008 and later
12767 @item @emph{Class}:
12770 @item @emph{Syntax}:
12771 @code{RESULT = SHIFTL(I, SHIFT)}
12773 @item @emph{Arguments}:
12774 @multitable @columnfractions .15 .70
12775 @item @var{I} @tab The type shall be @code{INTEGER}.
12776 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12779 @item @emph{Return value}:
12780 The return value is of type @code{INTEGER} and of the same kind as
12783 @item @emph{See also}:
12784 @ref{SHIFTA}, @ref{SHIFTR}
12790 @section @code{SHIFTR} --- Right shift
12792 @cindex bits, shift right
12793 @cindex shift, right
12796 @item @emph{Description}:
12797 @code{SHIFTR} returns a value corresponding to @var{I} with all of the
12798 bits shifted right by @var{SHIFT} places. If the absolute value of
12799 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12800 Bits shifted out from the right end are lost, and bits shifted in from
12801 the left end are set to 0.
12803 @item @emph{Standard}:
12804 Fortran 2008 and later
12806 @item @emph{Class}:
12809 @item @emph{Syntax}:
12810 @code{RESULT = SHIFTR(I, SHIFT)}
12812 @item @emph{Arguments}:
12813 @multitable @columnfractions .15 .70
12814 @item @var{I} @tab The type shall be @code{INTEGER}.
12815 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12818 @item @emph{Return value}:
12819 The return value is of type @code{INTEGER} and of the same kind as
12822 @item @emph{See also}:
12823 @ref{SHIFTA}, @ref{SHIFTL}
12829 @section @code{SIGN} --- Sign copying function
12833 @cindex sign copying
12836 @item @emph{Description}:
12837 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
12839 @item @emph{Standard}:
12840 Fortran 77 and later
12842 @item @emph{Class}:
12845 @item @emph{Syntax}:
12846 @code{RESULT = SIGN(A, B)}
12848 @item @emph{Arguments}:
12849 @multitable @columnfractions .15 .70
12850 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
12851 @item @var{B} @tab Shall be of the same type and kind as @var{A}
12854 @item @emph{Return value}:
12855 The kind of the return value is that of @var{A} and @var{B}.
12856 If @math{B\ge 0} then the result is @code{ABS(A)}, else
12857 it is @code{-ABS(A)}.
12859 @item @emph{Example}:
12862 print *, sign(-12,1)
12863 print *, sign(-12,0)
12864 print *, sign(-12,-1)
12866 print *, sign(-12.,1.)
12867 print *, sign(-12.,0.)
12868 print *, sign(-12.,-1.)
12869 end program test_sign
12872 @item @emph{Specific names}:
12873 @multitable @columnfractions .20 .20 .20 .25
12874 @item Name @tab Arguments @tab Return type @tab Standard
12875 @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu
12876 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
12877 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu
12884 @section @code{SIGNAL} --- Signal handling subroutine (or function)
12886 @cindex system, signal handling
12889 @item @emph{Description}:
12890 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
12891 @var{HANDLER} to be executed with a single integer argument when signal
12892 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
12893 turn off handling of signal @var{NUMBER} or revert to its default
12894 action. See @code{signal(2)}.
12896 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
12897 is supplied, it is set to the value returned by @code{signal(2)}.
12899 @item @emph{Standard}:
12902 @item @emph{Class}:
12903 Subroutine, function
12905 @item @emph{Syntax}:
12906 @multitable @columnfractions .80
12907 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
12908 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
12911 @item @emph{Arguments}:
12912 @multitable @columnfractions .15 .70
12913 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
12914 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
12915 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
12916 @code{INTEGER}. It is @code{INTENT(IN)}.
12917 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
12918 integer. It has @code{INTENT(OUT)}.
12920 @c TODO: What should the interface of the handler be? Does it take arguments?
12922 @item @emph{Return value}:
12923 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
12925 @item @emph{Example}:
12927 program test_signal
12929 external handler_print
12931 call signal (12, handler_print)
12932 call signal (10, 1)
12935 end program test_signal
12942 @section @code{SIN} --- Sine function
12948 @cindex trigonometric function, sine
12952 @item @emph{Description}:
12953 @code{SIN(X)} computes the sine of @var{X}.
12955 @item @emph{Standard}:
12956 Fortran 77 and later
12958 @item @emph{Class}:
12961 @item @emph{Syntax}:
12962 @code{RESULT = SIN(X)}
12964 @item @emph{Arguments}:
12965 @multitable @columnfractions .15 .70
12966 @item @var{X} @tab The type shall be @code{REAL} or
12970 @item @emph{Return value}:
12971 The return value has same type and kind as @var{X}.
12973 @item @emph{Example}:
12978 end program test_sin
12981 @item @emph{Specific names}:
12982 @multitable @columnfractions .20 .20 .20 .25
12983 @item Name @tab Argument @tab Return type @tab Standard
12984 @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu
12985 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
12986 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
12987 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
12988 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
12991 @item @emph{See also}:
12992 Inverse function: @ref{ASIN}
12993 Degrees function: @ref{SIND}
12999 @section @code{SIND} --- Sine function, degrees
13005 @cindex trigonometric function, sine, degrees
13006 @cindex sine, degrees
13009 @item @emph{Description}:
13010 @code{SIND(X)} computes the sine of @var{X} in degrees.
13012 This function is for compatibility only and should be avoided in favor of
13013 standard constructs wherever possible.
13015 @item @emph{Standard}:
13016 GNU Extension, enabled with @option{-fdec-math}.
13018 @item @emph{Class}:
13021 @item @emph{Syntax}:
13022 @code{RESULT = SIND(X)}
13024 @item @emph{Arguments}:
13025 @multitable @columnfractions .15 .70
13026 @item @var{X} @tab The type shall be @code{REAL} or
13030 @item @emph{Return value}:
13031 The return value has same type and kind as @var{X}, and its value is in degrees.
13033 @item @emph{Example}:
13038 end program test_sind
13041 @item @emph{Specific names}:
13042 @multitable @columnfractions .20 .20 .20 .25
13043 @item Name @tab Argument @tab Return type @tab Standard
13044 @item @code{SIND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
13045 @item @code{DSIND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
13046 @item @code{CSIND(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab GNU Extension
13047 @item @code{ZSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU Extension
13048 @item @code{CDSIND(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU Extension
13051 @item @emph{See also}:
13052 Inverse function: @ref{ASIND}
13053 Radians function: @ref{SIN}
13060 @section @code{SINH} --- Hyperbolic sine function
13063 @cindex hyperbolic sine
13064 @cindex hyperbolic function, sine
13065 @cindex sine, hyperbolic
13068 @item @emph{Description}:
13069 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
13071 @item @emph{Standard}:
13072 Fortran 95 and later, for a complex argument Fortran 2008 or later
13074 @item @emph{Class}:
13077 @item @emph{Syntax}:
13078 @code{RESULT = SINH(X)}
13080 @item @emph{Arguments}:
13081 @multitable @columnfractions .15 .70
13082 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13085 @item @emph{Return value}:
13086 The return value has same type and kind as @var{X}.
13088 @item @emph{Example}:
13091 real(8) :: x = - 1.0_8
13093 end program test_sinh
13096 @item @emph{Specific names}:
13097 @multitable @columnfractions .20 .20 .20 .25
13098 @item Name @tab Argument @tab Return type @tab Standard
13099 @item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
13100 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
13103 @item @emph{See also}:
13110 @section @code{SIZE} --- Determine the size of an array
13112 @cindex array, size
13113 @cindex array, number of elements
13114 @cindex array, count elements
13117 @item @emph{Description}:
13118 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
13119 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
13121 @item @emph{Standard}:
13122 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
13124 @item @emph{Class}:
13127 @item @emph{Syntax}:
13128 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
13130 @item @emph{Arguments}:
13131 @multitable @columnfractions .15 .70
13132 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
13133 a pointer it must be associated and allocatable arrays must be allocated.
13134 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
13135 and its value shall be in the range from 1 to n, where n equals the rank
13137 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
13138 expression indicating the kind parameter of the result.
13141 @item @emph{Return value}:
13142 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
13143 @var{KIND} is absent, the return value is of default integer kind.
13145 @item @emph{Example}:
13148 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
13152 @item @emph{See also}:
13153 @ref{SHAPE}, @ref{RESHAPE}
13158 @section @code{SIZEOF} --- Size in bytes of an expression
13160 @cindex expression size
13161 @cindex size of an expression
13164 @item @emph{Description}:
13165 @code{SIZEOF(X)} calculates the number of bytes of storage the
13166 expression @code{X} occupies.
13168 @item @emph{Standard}:
13171 @item @emph{Class}:
13174 @item @emph{Syntax}:
13175 @code{N = SIZEOF(X)}
13177 @item @emph{Arguments}:
13178 @multitable @columnfractions .15 .70
13179 @item @var{X} @tab The argument shall be of any type, rank or shape.
13182 @item @emph{Return value}:
13183 The return value is of type integer and of the system-dependent kind
13184 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
13185 number of bytes occupied by the argument. If the argument has the
13186 @code{POINTER} attribute, the number of bytes of the storage area pointed
13187 to is returned. If the argument is of a derived type with @code{POINTER}
13188 or @code{ALLOCATABLE} components, the return value does not account for
13189 the sizes of the data pointed to by these components. If the argument is
13190 polymorphic, the size according to the dynamic type is returned. The argument
13191 may not be a procedure or procedure pointer. Note that the code assumes for
13192 arrays that those are contiguous; for contiguous arrays, it returns the
13193 storage or an array element multiplied by the size of the array.
13195 @item @emph{Example}:
13199 print *, (sizeof(s)/sizeof(r) == 5)
13202 The example will print @code{.TRUE.} unless you are using a platform
13203 where default @code{REAL} variables are unusually padded.
13205 @item @emph{See also}:
13206 @ref{C_SIZEOF}, @ref{STORAGE_SIZE}
13211 @section @code{SLEEP} --- Sleep for the specified number of seconds
13213 @cindex delayed execution
13216 @item @emph{Description}:
13217 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
13219 @item @emph{Standard}:
13222 @item @emph{Class}:
13225 @item @emph{Syntax}:
13226 @code{CALL SLEEP(SECONDS)}
13228 @item @emph{Arguments}:
13229 @multitable @columnfractions .15 .70
13230 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
13233 @item @emph{Example}:
13244 @section @code{SPACING} --- Smallest distance between two numbers of a given type
13246 @cindex real number, relative spacing
13247 @cindex floating point, relative spacing
13250 @item @emph{Description}:
13251 Determines the distance between the argument @var{X} and the nearest
13252 adjacent number of the same type.
13254 @item @emph{Standard}:
13255 Fortran 95 and later
13257 @item @emph{Class}:
13260 @item @emph{Syntax}:
13261 @code{RESULT = SPACING(X)}
13263 @item @emph{Arguments}:
13264 @multitable @columnfractions .15 .70
13265 @item @var{X} @tab Shall be of type @code{REAL}.
13268 @item @emph{Return value}:
13269 The result is of the same type as the input argument @var{X}.
13271 @item @emph{Example}:
13273 PROGRAM test_spacing
13274 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
13275 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
13277 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
13278 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
13282 @item @emph{See also}:
13289 @section @code{SPREAD} --- Add a dimension to an array
13291 @cindex array, increase dimension
13292 @cindex array, duplicate elements
13293 @cindex array, duplicate dimensions
13296 @item @emph{Description}:
13297 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
13298 dimension @var{DIM}.
13300 @item @emph{Standard}:
13301 Fortran 95 and later
13303 @item @emph{Class}:
13304 Transformational function
13306 @item @emph{Syntax}:
13307 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
13309 @item @emph{Arguments}:
13310 @multitable @columnfractions .15 .70
13311 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
13312 a rank less than seven.
13313 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
13314 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
13315 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
13318 @item @emph{Return value}:
13319 The result is an array of the same type as @var{SOURCE} and has rank n+1
13320 where n equals the rank of @var{SOURCE}.
13322 @item @emph{Example}:
13324 PROGRAM test_spread
13325 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
13326 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
13327 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
13331 @item @emph{See also}:
13338 @section @code{SQRT} --- Square-root function
13345 @cindex square-root
13348 @item @emph{Description}:
13349 @code{SQRT(X)} computes the square root of @var{X}.
13351 @item @emph{Standard}:
13352 Fortran 77 and later
13354 @item @emph{Class}:
13357 @item @emph{Syntax}:
13358 @code{RESULT = SQRT(X)}
13360 @item @emph{Arguments}:
13361 @multitable @columnfractions .15 .70
13362 @item @var{X} @tab The type shall be @code{REAL} or
13366 @item @emph{Return value}:
13367 The return value is of type @code{REAL} or @code{COMPLEX}.
13368 The kind type parameter is the same as @var{X}.
13370 @item @emph{Example}:
13373 real(8) :: x = 2.0_8
13374 complex :: z = (1.0, 2.0)
13377 end program test_sqrt
13380 @item @emph{Specific names}:
13381 @multitable @columnfractions .20 .20 .20 .25
13382 @item Name @tab Argument @tab Return type @tab Standard
13383 @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
13384 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
13385 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
13386 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13387 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
13394 @section @code{SRAND} --- Reinitialize the random number generator
13396 @cindex random number generation, seeding
13397 @cindex seeding a random number generator
13400 @item @emph{Description}:
13401 @code{SRAND} reinitializes the pseudo-random number generator
13402 called by @code{RAND} and @code{IRAND}. The new seed used by the
13403 generator is specified by the required argument @var{SEED}.
13405 @item @emph{Standard}:
13408 @item @emph{Class}:
13411 @item @emph{Syntax}:
13412 @code{CALL SRAND(SEED)}
13414 @item @emph{Arguments}:
13415 @multitable @columnfractions .15 .70
13416 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
13419 @item @emph{Return value}:
13420 Does not return anything.
13422 @item @emph{Example}:
13423 See @code{RAND} and @code{IRAND} for examples.
13425 @item @emph{Notes}:
13426 The Fortran standard specifies the intrinsic subroutines
13427 @code{RANDOM_SEED} to initialize the pseudo-random number
13428 generator and @code{RANDOM_NUMBER} to generate pseudo-random numbers.
13429 These subroutines should be used in new codes.
13431 Please note that in GNU Fortran, these two sets of intrinsics (@code{RAND},
13432 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
13433 @code{RANDOM_SEED} on the other hand) access two independent
13434 pseudo-random number generators.
13436 @item @emph{See also}:
13437 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
13444 @section @code{STAT} --- Get file status
13446 @cindex file system, file status
13449 @item @emph{Description}:
13450 This function returns information about a file. No permissions are required on
13451 the file itself, but execute (search) permission is required on all of the
13452 directories in path that lead to the file.
13454 The elements that are obtained and stored in the array @code{VALUES}:
13455 @multitable @columnfractions .15 .70
13456 @item @code{VALUES(1)} @tab Device ID
13457 @item @code{VALUES(2)} @tab Inode number
13458 @item @code{VALUES(3)} @tab File mode
13459 @item @code{VALUES(4)} @tab Number of links
13460 @item @code{VALUES(5)} @tab Owner's uid
13461 @item @code{VALUES(6)} @tab Owner's gid
13462 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
13463 @item @code{VALUES(8)} @tab File size (bytes)
13464 @item @code{VALUES(9)} @tab Last access time
13465 @item @code{VALUES(10)} @tab Last modification time
13466 @item @code{VALUES(11)} @tab Last file status change time
13467 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
13468 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
13471 Not all these elements are relevant on all systems.
13472 If an element is not relevant, it is returned as 0.
13474 This intrinsic is provided in both subroutine and function forms; however,
13475 only one form can be used in any given program unit.
13477 @item @emph{Standard}:
13480 @item @emph{Class}:
13481 Subroutine, function
13483 @item @emph{Syntax}:
13484 @multitable @columnfractions .80
13485 @item @code{CALL STAT(NAME, VALUES [, STATUS])}
13486 @item @code{STATUS = STAT(NAME, VALUES)}
13489 @item @emph{Arguments}:
13490 @multitable @columnfractions .15 .70
13491 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
13492 default kind and a valid path within the file system.
13493 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
13494 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
13495 on success and a system specific error code otherwise.
13498 @item @emph{Example}:
13501 INTEGER, DIMENSION(13) :: buff
13504 CALL STAT("/etc/passwd", buff, status)
13506 IF (status == 0) THEN
13507 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
13508 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
13509 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
13510 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
13511 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
13512 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
13513 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
13514 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
13515 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
13516 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
13517 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
13518 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
13519 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
13524 @item @emph{See also}:
13525 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
13531 @section @code{STORAGE_SIZE} --- Storage size in bits
13532 @fnindex STORAGE_SIZE
13533 @cindex storage size
13536 @item @emph{Description}:
13537 Returns the storage size of argument @var{A} in bits.
13538 @item @emph{Standard}:
13539 Fortran 2008 and later
13540 @item @emph{Class}:
13542 @item @emph{Syntax}:
13543 @code{RESULT = STORAGE_SIZE(A [, KIND])}
13545 @item @emph{Arguments}:
13546 @multitable @columnfractions .15 .70
13547 @item @var{A} @tab Shall be a scalar or array of any type.
13548 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
13551 @item @emph{Return Value}:
13552 The result is a scalar integer with the kind type parameter specified by KIND
13553 (or default integer type if KIND is missing). The result value is the size
13554 expressed in bits for an element of an array that has the dynamic type and type
13557 @item @emph{See also}:
13558 @ref{C_SIZEOF}, @ref{SIZEOF}
13564 @section @code{SUM} --- Sum of array elements
13567 @cindex array, add elements
13568 @cindex array, conditionally add elements
13569 @cindex sum array elements
13572 @item @emph{Description}:
13573 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
13574 the corresponding element in @var{MASK} is @code{TRUE}.
13576 @item @emph{Standard}:
13577 Fortran 95 and later
13579 @item @emph{Class}:
13580 Transformational function
13582 @item @emph{Syntax}:
13583 @multitable @columnfractions .80
13584 @item @code{RESULT = SUM(ARRAY[, MASK])}
13585 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
13588 @item @emph{Arguments}:
13589 @multitable @columnfractions .15 .70
13590 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
13591 @code{REAL} or @code{COMPLEX}.
13592 @item @var{DIM} @tab (Optional) shall be a scalar of type
13593 @code{INTEGER} with a value in the range from 1 to n, where n
13594 equals the rank of @var{ARRAY}.
13595 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
13596 and either be a scalar or an array of the same shape as @var{ARRAY}.
13599 @item @emph{Return value}:
13600 The result is of the same type as @var{ARRAY}.
13602 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
13603 is returned. Otherwise, an array of rank n-1, where n equals the rank of
13604 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
13605 dropped is returned.
13607 @item @emph{Example}:
13610 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
13611 print *, SUM(x) ! all elements, sum = 15
13612 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
13616 @item @emph{See also}:
13623 @section @code{SYMLNK} --- Create a symbolic link
13625 @cindex file system, create link
13626 @cindex file system, soft link
13629 @item @emph{Description}:
13630 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
13631 character (@code{CHAR(0)}) can be used to mark the end of the names in
13632 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
13633 names are ignored. If the @var{STATUS} argument is supplied, it
13634 contains 0 on success or a nonzero error code upon return; see
13635 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
13636 @code{ENOSYS} is returned.
13638 This intrinsic is provided in both subroutine and function forms;
13639 however, only one form can be used in any given program unit.
13641 @item @emph{Standard}:
13644 @item @emph{Class}:
13645 Subroutine, function
13647 @item @emph{Syntax}:
13648 @multitable @columnfractions .80
13649 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
13650 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
13653 @item @emph{Arguments}:
13654 @multitable @columnfractions .15 .70
13655 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
13656 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
13657 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
13660 @item @emph{See also}:
13661 @ref{LINK}, @ref{UNLINK}
13668 @section @code{SYSTEM} --- Execute a shell command
13670 @cindex system, system call
13673 @item @emph{Description}:
13674 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
13675 argument @var{STATUS} is present, it contains the value returned by
13676 @code{system(3)}, which is presumably 0 if the shell command succeeded.
13677 Note that which shell is used to invoke the command is system-dependent
13678 and environment-dependent.
13680 This intrinsic is provided in both subroutine and function forms;
13681 however, only one form can be used in any given program unit.
13683 Note that the @code{system} function need not be thread-safe. It is
13684 the responsibility of the user to ensure that @code{system} is not
13685 called concurrently.
13687 @item @emph{Standard}:
13690 @item @emph{Class}:
13691 Subroutine, function
13693 @item @emph{Syntax}:
13694 @multitable @columnfractions .80
13695 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
13696 @item @code{STATUS = SYSTEM(COMMAND)}
13699 @item @emph{Arguments}:
13700 @multitable @columnfractions .15 .70
13701 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
13702 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
13705 @item @emph{See also}:
13706 @ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
13707 and should considered in new code for future portability.
13713 @section @code{SYSTEM_CLOCK} --- Time function
13714 @fnindex SYSTEM_CLOCK
13715 @cindex time, clock ticks
13716 @cindex clock ticks
13719 @item @emph{Description}:
13720 Determines the @var{COUNT} of a processor clock since an unspecified
13721 time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines
13722 the number of clock ticks per second. If the platform supports a
13723 monotonic clock, that clock is used and can, depending on the platform
13724 clock implementation, provide up to nanosecond resolution. If a
13725 monotonic clock is not available, the implementation falls back to a
13728 @var{COUNT_RATE} is system dependent and can vary depending on the kind of
13729 the arguments. For @var{kind=4} arguments (and smaller integer kinds),
13730 @var{COUNT} represents milliseconds, while for @var{kind=8} arguments (and
13731 larger integer kinds), @var{COUNT} typically represents micro- or
13732 nanoseconds depending on resolution of the underlying platform clock.
13733 @var{COUNT_MAX} usually equals @code{HUGE(COUNT_MAX)}. Note that the
13734 millisecond resolution of the @var{kind=4} version implies that the
13735 @var{COUNT} will wrap around in roughly 25 days. In order to avoid issues
13736 with the wrap around and for more precise timing, please use the
13737 @var{kind=8} version.
13739 If there is no clock, or querying the clock fails, @var{COUNT} is set
13740 to @code{-HUGE(COUNT)}, and @var{COUNT_RATE} and @var{COUNT_MAX} are
13743 When running on a platform using the GNU C library (glibc) version
13744 2.16 or older, or a derivative thereof, the high resolution monotonic
13745 clock is available only when linking with the @var{rt} library. This
13746 can be done explicitly by adding the @code{-lrt} flag when linking the
13747 application, but is also done implicitly when using OpenMP.
13749 On the Windows platform, the version with @var{kind=4} arguments uses
13750 the @code{GetTickCount} function, whereas the @var{kind=8} version
13751 uses @code{QueryPerformanceCounter} and
13752 @code{QueryPerformanceCounterFrequency}. For more information, and
13753 potential caveats, please see the platform documentation.
13755 @item @emph{Standard}:
13756 Fortran 95 and later
13758 @item @emph{Class}:
13761 @item @emph{Syntax}:
13762 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
13764 @item @emph{Arguments}:
13765 @multitable @columnfractions .15 .70
13766 @item @var{COUNT} @tab (Optional) shall be a scalar of type
13767 @code{INTEGER} with @code{INTENT(OUT)}.
13768 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type
13769 @code{INTEGER} or @code{REAL}, with @code{INTENT(OUT)}.
13770 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type
13771 @code{INTEGER} with @code{INTENT(OUT)}.
13774 @item @emph{Example}:
13776 PROGRAM test_system_clock
13777 INTEGER :: count, count_rate, count_max
13778 CALL SYSTEM_CLOCK(count, count_rate, count_max)
13779 WRITE(*,*) count, count_rate, count_max
13783 @item @emph{See also}:
13784 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
13790 @section @code{TAN} --- Tangent function
13793 @cindex trigonometric function, tangent
13797 @item @emph{Description}:
13798 @code{TAN(X)} computes the tangent of @var{X}.
13800 @item @emph{Standard}:
13801 Fortran 77 and later, for a complex argument Fortran 2008 or later
13803 @item @emph{Class}:
13806 @item @emph{Syntax}:
13807 @code{RESULT = TAN(X)}
13809 @item @emph{Arguments}:
13810 @multitable @columnfractions .15 .70
13811 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13814 @item @emph{Return value}:
13815 The return value has same type and kind as @var{X}, and its value is in radians.
13817 @item @emph{Example}:
13820 real(8) :: x = 0.165_8
13822 end program test_tan
13825 @item @emph{Specific names}:
13826 @multitable @columnfractions .20 .20 .20 .25
13827 @item Name @tab Argument @tab Return type @tab Standard
13828 @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
13829 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
13832 @item @emph{See also}:
13833 Inverse function: @ref{ATAN}
13834 Degrees function: @ref{TAND}
13840 @section @code{TAND} --- Tangent function, degrees
13843 @cindex trigonometric function, tangent, degrees
13844 @cindex tangent, degrees
13847 @item @emph{Description}:
13848 @code{TAND(X)} computes the tangent of @var{X} in degrees.
13850 This function is for compatibility only and should be avoided in favor of
13851 standard constructs wherever possible.
13853 @item @emph{Standard}:
13854 GNU Extension, enabled with @option{-fdec-math}.
13856 @item @emph{Class}:
13859 @item @emph{Syntax}:
13860 @code{RESULT = TAND(X)}
13862 @item @emph{Arguments}:
13863 @multitable @columnfractions .15 .70
13864 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13867 @item @emph{Return value}:
13868 The return value has same type and kind as @var{X}, and its value is in degrees.
13870 @item @emph{Example}:
13873 real(8) :: x = 0.165_8
13875 end program test_tand
13878 @item @emph{Specific names}:
13879 @multitable @columnfractions .20 .20 .20 .25
13880 @item Name @tab Argument @tab Return type @tab Standard
13881 @item @code{TAND(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
13882 @item @code{DTAND(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
13885 @item @emph{See also}:
13886 Inverse function: @ref{ATAND}
13887 Radians function: @ref{TAN}
13893 @section @code{TANH} --- Hyperbolic tangent function
13896 @cindex hyperbolic tangent
13897 @cindex hyperbolic function, tangent
13898 @cindex tangent, hyperbolic
13901 @item @emph{Description}:
13902 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
13904 @item @emph{Standard}:
13905 Fortran 77 and later, for a complex argument Fortran 2008 or later
13907 @item @emph{Class}:
13910 @item @emph{Syntax}:
13913 @item @emph{Arguments}:
13914 @multitable @columnfractions .15 .70
13915 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13918 @item @emph{Return value}:
13919 The return value has same type and kind as @var{X}. If @var{X} is
13920 complex, the imaginary part of the result is in radians. If @var{X}
13921 is @code{REAL}, the return value lies in the range
13922 @math{ - 1 \leq tanh(x) \leq 1 }.
13924 @item @emph{Example}:
13927 real(8) :: x = 2.1_8
13929 end program test_tanh
13932 @item @emph{Specific names}:
13933 @multitable @columnfractions .20 .20 .20 .25
13934 @item Name @tab Argument @tab Return type @tab Standard
13935 @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
13936 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
13939 @item @emph{See also}:
13946 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
13947 @fnindex THIS_IMAGE
13948 @cindex coarray, @code{THIS_IMAGE}
13949 @cindex images, index of this image
13952 @item @emph{Description}:
13953 Returns the cosubscript for this image.
13955 @item @emph{Standard}:
13956 Fortran 2008 and later. With @var{DISTANCE} argument,
13957 Technical Specification (TS) 18508 or later
13959 @item @emph{Class}:
13960 Transformational function
13962 @item @emph{Syntax}:
13963 @multitable @columnfractions .80
13964 @item @code{RESULT = THIS_IMAGE()}
13965 @item @code{RESULT = THIS_IMAGE(DISTANCE)}
13966 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
13969 @item @emph{Arguments}:
13970 @multitable @columnfractions .15 .70
13971 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
13972 (not permitted together with @var{COARRAY}).
13973 @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
13974 present, required).
13975 @item @var{DIM} @tab default integer scalar (optional). If present,
13976 @var{DIM} shall be between one and the corank of @var{COARRAY}.
13980 @item @emph{Return value}:
13981 Default integer. If @var{COARRAY} is not present, it is scalar; if
13982 @var{DISTANCE} is not present or has value 0, its value is the image index on
13983 the invoking image for the current team, for values smaller or equal
13984 distance to the initial team, it returns the image index on the ancestor team
13985 which has a distance of @var{DISTANCE} from the invoking team. If
13986 @var{DISTANCE} is larger than the distance to the initial team, the image
13987 index of the initial team is returned. Otherwise when the @var{COARRAY} is
13988 present, if @var{DIM} is not present, a rank-1 array with corank elements is
13989 returned, containing the cosubscripts for @var{COARRAY} specifying the invoking
13990 image. If @var{DIM} is present, a scalar is returned, with the value of
13991 the @var{DIM} element of @code{THIS_IMAGE(COARRAY)}.
13993 @item @emph{Example}:
13995 INTEGER :: value[*]
13997 value = THIS_IMAGE()
13999 IF (THIS_IMAGE() == 1) THEN
14000 DO i = 1, NUM_IMAGES()
14001 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
14005 ! Check whether the current image is the initial image
14006 IF (THIS_IMAGE(HUGE(1)) /= THIS_IMAGE())
14007 error stop "something is rotten here"
14010 @item @emph{See also}:
14011 @ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
14017 @section @code{TIME} --- Time function
14019 @cindex time, current
14020 @cindex current time
14023 @item @emph{Description}:
14024 Returns the current time encoded as an integer (in the manner of the
14025 function @code{time(3)} in the C standard library). This value is
14026 suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}.
14028 This intrinsic is not fully portable, such as to systems with 32-bit
14029 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
14030 the values returned by this intrinsic might be, or become, negative, or
14031 numerically less than previous values, during a single run of the
14034 See @ref{TIME8}, for information on a similar intrinsic that might be
14035 portable to more GNU Fortran implementations, though to fewer Fortran
14038 @item @emph{Standard}:
14041 @item @emph{Class}:
14044 @item @emph{Syntax}:
14045 @code{RESULT = TIME()}
14047 @item @emph{Return value}:
14048 The return value is a scalar of type @code{INTEGER(4)}.
14050 @item @emph{See also}:
14051 @ref{DATE_AND_TIME}, @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
14058 @section @code{TIME8} --- Time function (64-bit)
14060 @cindex time, current
14061 @cindex current time
14064 @item @emph{Description}:
14065 Returns the current time encoded as an integer (in the manner of the
14066 function @code{time(3)} in the C standard library). This value is
14067 suitable for passing to @ref{CTIME}, @ref{GMTIME}, and @ref{LTIME}.
14069 @emph{Warning:} this intrinsic does not increase the range of the timing
14070 values over that returned by @code{time(3)}. On a system with a 32-bit
14071 @code{time(3)}, @code{TIME8} will return a 32-bit value, even though
14072 it is converted to a 64-bit @code{INTEGER(8)} value. That means
14073 overflows of the 32-bit value can still occur. Therefore, the values
14074 returned by this intrinsic might be or become negative or numerically
14075 less than previous values during a single run of the compiled program.
14077 @item @emph{Standard}:
14080 @item @emph{Class}:
14083 @item @emph{Syntax}:
14084 @code{RESULT = TIME8()}
14086 @item @emph{Return value}:
14087 The return value is a scalar of type @code{INTEGER(8)}.
14089 @item @emph{See also}:
14090 @ref{DATE_AND_TIME}, @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
14097 @section @code{TINY} --- Smallest positive number of a real kind
14099 @cindex limits, smallest number
14100 @cindex model representation, smallest number
14103 @item @emph{Description}:
14104 @code{TINY(X)} returns the smallest positive (non zero) number
14105 in the model of the type of @code{X}.
14107 @item @emph{Standard}:
14108 Fortran 95 and later
14110 @item @emph{Class}:
14113 @item @emph{Syntax}:
14114 @code{RESULT = TINY(X)}
14116 @item @emph{Arguments}:
14117 @multitable @columnfractions .15 .70
14118 @item @var{X} @tab Shall be of type @code{REAL}.
14121 @item @emph{Return value}:
14122 The return value is of the same type and kind as @var{X}
14124 @item @emph{Example}:
14125 See @code{HUGE} for an example.
14131 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
14136 @item @emph{Description}:
14137 @code{TRAILZ} returns the number of trailing zero bits of an integer.
14139 @item @emph{Standard}:
14140 Fortran 2008 and later
14142 @item @emph{Class}:
14145 @item @emph{Syntax}:
14146 @code{RESULT = TRAILZ(I)}
14148 @item @emph{Arguments}:
14149 @multitable @columnfractions .15 .70
14150 @item @var{I} @tab Shall be of type @code{INTEGER}.
14153 @item @emph{Return value}:
14154 The type of the return value is the default @code{INTEGER}.
14155 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
14157 @item @emph{Example}:
14159 PROGRAM test_trailz
14160 WRITE (*,*) TRAILZ(8) ! prints 3
14164 @item @emph{See also}:
14165 @ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT}
14171 @section @code{TRANSFER} --- Transfer bit patterns
14177 @item @emph{Description}:
14178 Interprets the bitwise representation of @var{SOURCE} in memory as if it
14179 is the representation of a variable or array of the same type and type
14180 parameters as @var{MOLD}.
14182 This is approximately equivalent to the C concept of @emph{casting} one
14185 @item @emph{Standard}:
14186 Fortran 95 and later
14188 @item @emph{Class}:
14189 Transformational function
14191 @item @emph{Syntax}:
14192 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
14194 @item @emph{Arguments}:
14195 @multitable @columnfractions .15 .70
14196 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
14197 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
14198 @item @var{SIZE} @tab (Optional) shall be a scalar of type
14202 @item @emph{Return value}:
14203 The result has the same type as @var{MOLD}, with the bit level
14204 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
14205 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
14206 but @var{MOLD} is an array (of any size or shape), the result is a one-
14207 dimensional array of the minimum length needed to contain the entirety
14208 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
14209 and @var{MOLD} is a scalar, the result is a scalar.
14211 If the bitwise representation of the result is longer than that of
14212 @var{SOURCE}, then the leading bits of the result correspond to those of
14213 @var{SOURCE} and any trailing bits are filled arbitrarily.
14215 When the resulting bit representation does not correspond to a valid
14216 representation of a variable of the same type as @var{MOLD}, the results
14217 are undefined, and subsequent operations on the result cannot be
14218 guaranteed to produce sensible behavior. For example, it is possible to
14219 create @code{LOGICAL} variables for which @code{@var{VAR}} and
14220 @code{.NOT.@var{VAR}} both appear to be true.
14222 @item @emph{Example}:
14224 PROGRAM test_transfer
14225 integer :: x = 2143289344
14226 print *, transfer(x, 1.0) ! prints "NaN" on i686
14234 @section @code{TRANSPOSE} --- Transpose an array of rank two
14236 @cindex array, transpose
14237 @cindex matrix, transpose
14241 @item @emph{Description}:
14242 Transpose an array of rank two. Element (i, j) of the result has the value
14243 @code{MATRIX(j, i)}, for all i, j.
14245 @item @emph{Standard}:
14246 Fortran 95 and later
14248 @item @emph{Class}:
14249 Transformational function
14251 @item @emph{Syntax}:
14252 @code{RESULT = TRANSPOSE(MATRIX)}
14254 @item @emph{Arguments}:
14255 @multitable @columnfractions .15 .70
14256 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
14259 @item @emph{Return value}:
14260 The result has the same type as @var{MATRIX}, and has shape
14261 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
14267 @section @code{TRIM} --- Remove trailing blank characters of a string
14269 @cindex string, remove trailing whitespace
14272 @item @emph{Description}:
14273 Removes trailing blank characters of a string.
14275 @item @emph{Standard}:
14276 Fortran 95 and later
14278 @item @emph{Class}:
14279 Transformational function
14281 @item @emph{Syntax}:
14282 @code{RESULT = TRIM(STRING)}
14284 @item @emph{Arguments}:
14285 @multitable @columnfractions .15 .70
14286 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
14289 @item @emph{Return value}:
14290 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
14291 less the number of trailing blanks.
14293 @item @emph{Example}:
14296 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
14297 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
14301 @item @emph{See also}:
14302 @ref{ADJUSTL}, @ref{ADJUSTR}
14308 @section @code{TTYNAM} --- Get the name of a terminal device.
14310 @cindex system, terminal
14313 @item @emph{Description}:
14314 Get the name of a terminal device. For more information,
14315 see @code{ttyname(3)}.
14317 This intrinsic is provided in both subroutine and function forms;
14318 however, only one form can be used in any given program unit.
14320 @item @emph{Standard}:
14323 @item @emph{Class}:
14324 Subroutine, function
14326 @item @emph{Syntax}:
14327 @multitable @columnfractions .80
14328 @item @code{CALL TTYNAM(UNIT, NAME)}
14329 @item @code{NAME = TTYNAM(UNIT)}
14332 @item @emph{Arguments}:
14333 @multitable @columnfractions .15 .70
14334 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
14335 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
14338 @item @emph{Example}:
14340 PROGRAM test_ttynam
14343 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
14348 @item @emph{See also}:
14355 @section @code{UBOUND} --- Upper dimension bounds of an array
14357 @cindex array, upper bound
14360 @item @emph{Description}:
14361 Returns the upper bounds of an array, or a single upper bound
14362 along the @var{DIM} dimension.
14363 @item @emph{Standard}:
14364 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
14366 @item @emph{Class}:
14369 @item @emph{Syntax}:
14370 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
14372 @item @emph{Arguments}:
14373 @multitable @columnfractions .15 .70
14374 @item @var{ARRAY} @tab Shall be an array, of any type.
14375 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
14376 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
14377 expression indicating the kind parameter of the result.
14380 @item @emph{Return value}:
14381 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14382 @var{KIND} is absent, the return value is of default integer kind.
14383 If @var{DIM} is absent, the result is an array of the upper bounds of
14384 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
14385 corresponding to the upper bound of the array along that dimension. If
14386 @var{ARRAY} is an expression rather than a whole array or array
14387 structure component, or if it has a zero extent along the relevant
14388 dimension, the upper bound is taken to be the number of elements along
14389 the relevant dimension.
14391 @item @emph{See also}:
14392 @ref{LBOUND}, @ref{LCOBOUND}
14398 @section @code{UCOBOUND} --- Upper codimension bounds of an array
14400 @cindex coarray, upper bound
14403 @item @emph{Description}:
14404 Returns the upper cobounds of a coarray, or a single upper cobound
14405 along the @var{DIM} codimension.
14406 @item @emph{Standard}:
14407 Fortran 2008 and later
14409 @item @emph{Class}:
14412 @item @emph{Syntax}:
14413 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
14415 @item @emph{Arguments}:
14416 @multitable @columnfractions .15 .70
14417 @item @var{ARRAY} @tab Shall be an coarray, of any type.
14418 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
14419 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
14420 expression indicating the kind parameter of the result.
14423 @item @emph{Return value}:
14424 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14425 @var{KIND} is absent, the return value is of default integer kind.
14426 If @var{DIM} is absent, the result is an array of the lower cobounds of
14427 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
14428 corresponding to the lower cobound of the array along that codimension.
14430 @item @emph{See also}:
14431 @ref{LCOBOUND}, @ref{LBOUND}
14437 @section @code{UMASK} --- Set the file creation mask
14439 @cindex file system, file creation mask
14442 @item @emph{Description}:
14443 Sets the file creation mask to @var{MASK}. If called as a function, it
14444 returns the old value. If called as a subroutine and argument @var{OLD}
14445 if it is supplied, it is set to the old value. See @code{umask(2)}.
14447 @item @emph{Standard}:
14450 @item @emph{Class}:
14451 Subroutine, function
14453 @item @emph{Syntax}:
14454 @multitable @columnfractions .80
14455 @item @code{CALL UMASK(MASK [, OLD])}
14456 @item @code{OLD = UMASK(MASK)}
14459 @item @emph{Arguments}:
14460 @multitable @columnfractions .15 .70
14461 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
14462 @item @var{OLD} @tab (Optional) Shall be a scalar of type
14471 @section @code{UNLINK} --- Remove a file from the file system
14473 @cindex file system, remove file
14476 @item @emph{Description}:
14477 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
14478 used to mark the end of the name in @var{PATH}; otherwise, trailing
14479 blanks in the file name are ignored. If the @var{STATUS} argument is
14480 supplied, it contains 0 on success or a nonzero error code upon return;
14481 see @code{unlink(2)}.
14483 This intrinsic is provided in both subroutine and function forms;
14484 however, only one form can be used in any given program unit.
14486 @item @emph{Standard}:
14489 @item @emph{Class}:
14490 Subroutine, function
14492 @item @emph{Syntax}:
14493 @multitable @columnfractions .80
14494 @item @code{CALL UNLINK(PATH [, STATUS])}
14495 @item @code{STATUS = UNLINK(PATH)}
14498 @item @emph{Arguments}:
14499 @multitable @columnfractions .15 .70
14500 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
14501 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
14504 @item @emph{See also}:
14505 @ref{LINK}, @ref{SYMLNK}
14511 @section @code{UNPACK} --- Unpack an array of rank one into an array
14513 @cindex array, unpacking
14514 @cindex array, increase dimension
14515 @cindex array, scatter elements
14518 @item @emph{Description}:
14519 Store the elements of @var{VECTOR} in an array of higher rank.
14521 @item @emph{Standard}:
14522 Fortran 95 and later
14524 @item @emph{Class}:
14525 Transformational function
14527 @item @emph{Syntax}:
14528 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
14530 @item @emph{Arguments}:
14531 @multitable @columnfractions .15 .70
14532 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
14533 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
14534 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
14535 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
14536 the same shape as @var{MASK}.
14539 @item @emph{Return value}:
14540 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
14541 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
14543 @item @emph{Example}:
14545 PROGRAM test_unpack
14546 integer :: vector(2) = (/1,1/)
14547 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
14548 integer :: field(2,2) = 0, unity(2,2)
14550 ! result: unity matrix
14551 unity = unpack(vector, reshape(mask, (/2,2/)), field)
14555 @item @emph{See also}:
14556 @ref{PACK}, @ref{SPREAD}
14562 @section @code{VERIFY} --- Scan a string for characters not a given set
14564 @cindex string, find missing set
14567 @item @emph{Description}:
14568 Verifies that all the characters in @var{STRING} belong to the set of
14569 characters in @var{SET}.
14571 If @var{BACK} is either absent or equals @code{FALSE}, this function
14572 returns the position of the leftmost character of @var{STRING} that is
14573 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost
14574 position is returned. If all characters of @var{STRING} are found in
14575 @var{SET}, the result is zero.
14577 @item @emph{Standard}:
14578 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
14580 @item @emph{Class}:
14583 @item @emph{Syntax}:
14584 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
14586 @item @emph{Arguments}:
14587 @multitable @columnfractions .15 .70
14588 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
14589 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
14590 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
14591 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
14592 expression indicating the kind parameter of the result.
14595 @item @emph{Return value}:
14596 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
14597 @var{KIND} is absent, the return value is of default integer kind.
14599 @item @emph{Example}:
14601 PROGRAM test_verify
14602 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
14603 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
14604 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
14605 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
14606 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
14610 @item @emph{See also}:
14611 @ref{SCAN}, @ref{INDEX intrinsic}
14617 @section @code{XOR} --- Bitwise logical exclusive OR
14619 @cindex bitwise logical exclusive or
14620 @cindex logical exclusive or, bitwise
14623 @item @emph{Description}:
14624 Bitwise logical exclusive or.
14626 This intrinsic routine is provided for backwards compatibility with
14627 GNU Fortran 77. For integer arguments, programmers should consider
14628 the use of the @ref{IEOR} intrinsic and for logical arguments the
14629 @code{.NEQV.} operator, which are both defined by the Fortran standard.
14631 @item @emph{Standard}:
14634 @item @emph{Class}:
14637 @item @emph{Syntax}:
14638 @code{RESULT = XOR(I, J)}
14640 @item @emph{Arguments}:
14641 @multitable @columnfractions .15 .70
14642 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
14643 type or a scalar @code{LOGICAL} type.
14644 @item @var{J} @tab The type shall be the same as the type of @var{I}.
14647 @item @emph{Return value}:
14648 The return type is either a scalar @code{INTEGER} or a scalar
14649 @code{LOGICAL}. If the kind type parameters differ, then the
14650 smaller kind type is implicitly converted to larger kind, and the
14651 return has the larger kind.
14653 @item @emph{Example}:
14656 LOGICAL :: T = .TRUE., F = .FALSE.
14658 DATA a / Z'F' /, b / Z'3' /
14660 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
14661 WRITE (*,*) XOR(a, b)
14665 @item @emph{See also}:
14666 Fortran 95 elemental function: @ref{IEOR}
14671 @node Intrinsic Modules
14672 @chapter Intrinsic Modules
14673 @cindex intrinsic Modules
14676 * ISO_FORTRAN_ENV::
14679 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
14680 * OpenACC Module OPENACC::
14683 @node ISO_FORTRAN_ENV
14684 @section @code{ISO_FORTRAN_ENV}
14686 @item @emph{Standard}:
14687 Fortran 2003 and later, except when otherwise noted
14690 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
14694 @item @code{ATOMIC_INT_KIND}:
14695 Default-kind integer constant to be used as kind parameter when defining
14696 integer variables used in atomic operations. (Fortran 2008 or later.)
14698 @item @code{ATOMIC_LOGICAL_KIND}:
14699 Default-kind integer constant to be used as kind parameter when defining
14700 logical variables used in atomic operations. (Fortran 2008 or later.)
14702 @item @code{CHARACTER_KINDS}:
14703 Default-kind integer constant array of rank one containing the supported kind
14704 parameters of the @code{CHARACTER} type. (Fortran 2008 or later.)
14706 @item @code{CHARACTER_STORAGE_SIZE}:
14707 Size in bits of the character storage unit.
14709 @item @code{ERROR_UNIT}:
14710 Identifies the preconnected unit used for error reporting.
14712 @item @code{FILE_STORAGE_SIZE}:
14713 Size in bits of the file-storage unit.
14715 @item @code{INPUT_UNIT}:
14716 Identifies the preconnected unit identified by the asterisk
14717 (@code{*}) in @code{READ} statement.
14719 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
14720 Kind type parameters to specify an INTEGER type with a storage
14721 size of 16, 32, and 64 bits. It is negative if a target platform
14722 does not support the particular kind. (Fortran 2008 or later.)
14724 @item @code{INTEGER_KINDS}:
14725 Default-kind integer constant array of rank one containing the supported kind
14726 parameters of the @code{INTEGER} type. (Fortran 2008 or later.)
14728 @item @code{IOSTAT_END}:
14729 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
14730 an input/output statement if an end-of-file condition occurred.
14732 @item @code{IOSTAT_EOR}:
14733 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
14734 an input/output statement if an end-of-record condition occurred.
14736 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
14737 Scalar default-integer constant, used by @code{INQUIRE} for the
14738 @code{IOSTAT=} specifier to denote an that a unit number identifies an
14739 internal unit. (Fortran 2008 or later.)
14741 @item @code{NUMERIC_STORAGE_SIZE}:
14742 The size in bits of the numeric storage unit.
14744 @item @code{LOGICAL_KINDS}:
14745 Default-kind integer constant array of rank one containing the supported kind
14746 parameters of the @code{LOGICAL} type. (Fortran 2008 or later.)
14748 @item @code{OUTPUT_UNIT}:
14749 Identifies the preconnected unit identified by the asterisk
14750 (@code{*}) in @code{WRITE} statement.
14752 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
14753 Kind type parameters to specify a REAL type with a storage
14754 size of 32, 64, and 128 bits. It is negative if a target platform
14755 does not support the particular kind. (Fortran 2008 or later.)
14757 @item @code{REAL_KINDS}:
14758 Default-kind integer constant array of rank one containing the supported kind
14759 parameters of the @code{REAL} type. (Fortran 2008 or later.)
14761 @item @code{STAT_LOCKED}:
14762 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
14763 denote that the lock variable is locked by the executing image. (Fortran 2008
14766 @item @code{STAT_LOCKED_OTHER_IMAGE}:
14767 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
14768 denote that the lock variable is locked by another image. (Fortran 2008 or
14771 @item @code{STAT_STOPPED_IMAGE}:
14772 Positive, scalar default-integer constant used as STAT= return value if the
14773 argument in the statement requires synchronisation with an image, which has
14774 initiated the termination of the execution. (Fortran 2008 or later.)
14776 @item @code{STAT_FAILED_IMAGE}:
14777 Positive, scalar default-integer constant used as STAT= return value if the
14778 argument in the statement requires communication with an image, which has
14779 is in the failed state. (TS 18508 or later.)
14781 @item @code{STAT_UNLOCKED}:
14782 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
14783 denote that the lock variable is unlocked. (Fortran 2008 or later.)
14786 The module provides the following derived type:
14789 @item @code{LOCK_TYPE}:
14790 Derived type with private components to be use with the @code{LOCK} and
14791 @code{UNLOCK} statement. A variable of its type has to be always declared
14792 as coarray and may not appear in a variable-definition context.
14793 (Fortran 2008 or later.)
14796 The module also provides the following intrinsic procedures:
14797 @ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}.
14801 @node ISO_C_BINDING
14802 @section @code{ISO_C_BINDING}
14804 @item @emph{Standard}:
14805 Fortran 2003 and later, GNU extensions
14808 The following intrinsic procedures are provided by the module; their
14809 definition can be found in the section Intrinsic Procedures of this
14813 @item @code{C_ASSOCIATED}
14814 @item @code{C_F_POINTER}
14815 @item @code{C_F_PROCPOINTER}
14816 @item @code{C_FUNLOC}
14818 @item @code{C_SIZEOF}
14820 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
14821 @c don't really know why.
14823 The @code{ISO_C_BINDING} module provides the following named constants of
14824 type default integer, which can be used as KIND type parameters.
14826 In addition to the integer named constants required by the Fortran 2003
14827 standard and @code{C_PTRDIFF_T} of TS 29113, GNU Fortran provides as an
14828 extension named constants for the 128-bit integer types supported by the
14829 C compiler: @code{C_INT128_T, C_INT_LEAST128_T, C_INT_FAST128_T}.
14830 Furthermore, if @code{__float128} is supported in C, the named constants
14831 @code{C_FLOAT128, C_FLOAT128_COMPLEX} are defined.
14833 @multitable @columnfractions .15 .35 .35 .35
14834 @item Fortran Type @tab Named constant @tab C type @tab Extension
14835 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
14836 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
14837 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
14838 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
14839 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
14840 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
14841 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
14842 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
14843 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
14844 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
14845 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
14846 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
14847 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
14848 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
14849 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
14850 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
14851 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
14852 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
14853 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
14854 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
14855 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
14856 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
14857 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
14858 @item @code{INTEGER}@tab @code{C_PTRDIFF_T} @tab @code{ptrdiff_t} @tab TS 29113
14859 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
14860 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
14861 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
14862 @item @code{REAL} @tab @code{C_FLOAT128} @tab @code{__float128} @tab Ext.
14863 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
14864 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
14865 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
14866 @item @code{REAL} @tab @code{C_FLOAT128_COMPLEX} @tab @code{__float128 _Complex} @tab Ext.
14867 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
14868 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
14871 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
14874 @multitable @columnfractions .20 .45 .15
14875 @item Name @tab C definition @tab Value
14876 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
14877 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
14878 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
14879 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
14880 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
14881 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
14882 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
14883 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
14886 Moreover, the following two named constants are defined:
14888 @multitable @columnfractions .20 .80
14889 @item Name @tab Type
14890 @item @code{C_NULL_PTR} @tab @code{C_PTR}
14891 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
14894 Both are equivalent to the value @code{NULL} in C.
14899 @section IEEE modules: @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
14901 @item @emph{Standard}:
14902 Fortran 2003 and later
14905 The @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
14906 intrinsic modules provide support for exceptions and IEEE arithmetic, as
14907 defined in Fortran 2003 and later standards, and the IEC 60559:1989 standard
14908 (@emph{Binary floating-point arithmetic for microprocessor systems}). These
14909 modules are only provided on the following supported platforms:
14912 @item i386 and x86_64 processors
14913 @item platforms which use the GNU C Library (glibc)
14914 @item platforms with support for SysV/386 routines for floating point
14915 interface (including Solaris and BSDs)
14916 @item platforms with the AIX OS
14919 For full compliance with the Fortran standards, code using the
14920 @code{IEEE_EXCEPTIONS} or @code{IEEE_ARITHMETIC} modules should be compiled
14921 with the following options: @code{-fno-unsafe-math-optimizations
14922 -frounding-math -fsignaling-nans}.
14926 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
14927 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
14929 @item @emph{Standard}:
14930 OpenMP Application Program Interface v4.5
14934 The OpenMP Fortran runtime library routines are provided both in
14935 a form of two Fortran 90 modules, named @code{OMP_LIB} and
14936 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
14937 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
14938 in the @ref{Top,,Introduction,libgomp,GNU Offloading and Multi
14939 Processing Runtime Library} manual,
14940 the named constants defined in the modules are listed
14943 For details refer to the actual
14944 @uref{http://www.openmp.org/wp-content/uploads/openmp-4.5.pdf,
14945 OpenMP Application Program Interface v4.5}.
14947 @code{OMP_LIB_KINDS} provides the following scalar default-integer
14951 @item @code{omp_lock_kind}
14952 @item @code{omp_nest_lock_kind}
14953 @item @code{omp_proc_bind_kind}
14954 @item @code{omp_sched_kind}
14957 @code{OMP_LIB} provides the scalar default-integer
14958 named constant @code{openmp_version} with a value of the form
14959 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
14960 of the OpenMP version; for OpenMP v4.5 the value is @code{201511}.
14962 The following scalar integer named constants of the
14963 kind @code{omp_sched_kind}:
14966 @item @code{omp_sched_static}
14967 @item @code{omp_sched_dynamic}
14968 @item @code{omp_sched_guided}
14969 @item @code{omp_sched_auto}
14972 And the following scalar integer named constants of the
14973 kind @code{omp_proc_bind_kind}:
14976 @item @code{omp_proc_bind_false}
14977 @item @code{omp_proc_bind_true}
14978 @item @code{omp_proc_bind_master}
14979 @item @code{omp_proc_bind_close}
14980 @item @code{omp_proc_bind_spread}
14985 @node OpenACC Module OPENACC
14986 @section OpenACC Module @code{OPENACC}
14988 @item @emph{Standard}:
14989 OpenACC Application Programming Interface v2.0
14993 The OpenACC Fortran runtime library routines are provided both in a
14994 form of a Fortran 90 module, named @code{OPENACC}, and in form of a
14995 Fortran @code{include} file named @file{openacc_lib.h}. The
14996 procedures provided by @code{OPENACC} can be found in the
14997 @ref{Top,,Introduction,libgomp,GNU Offloading and Multi Processing
14998 Runtime Library} manual, the named constants defined in the modules
15001 For details refer to the actual
15002 @uref{http://www.openacc.org/,
15003 OpenACC Application Programming Interface v2.0}.
15005 @code{OPENACC} provides the scalar default-integer
15006 named constant @code{openacc_version} with a value of the form
15007 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
15008 of the OpenACC version; for OpenACC v2.0 the value is @code{201306}.