2 Copyright (C) 2005-2014 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\acos{\mathop{\rm acos}\nolimits}
27 \gdef\asin{\mathop{\rm asin}\nolimits}
28 \gdef\atan{\mathop{\rm atan}\nolimits}
29 \gdef\acosh{\mathop{\rm acosh}\nolimits}
30 \gdef\asinh{\mathop{\rm asinh}\nolimits}
31 \gdef\atanh{\mathop{\rm atanh}\nolimits}
35 @node Intrinsic Procedures
36 @chapter Intrinsic Procedures
37 @cindex intrinsic procedures
40 * Introduction: Introduction to Intrinsics
41 * @code{ABORT}: ABORT, Abort the program
42 * @code{ABS}: ABS, Absolute value
43 * @code{ACCESS}: ACCESS, Checks file access modes
44 * @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence
45 * @code{ACOS}: ACOS, Arccosine function
46 * @code{ACOSH}: ACOSH, Inverse hyperbolic cosine function
47 * @code{ADJUSTL}: ADJUSTL, Left adjust a string
48 * @code{ADJUSTR}: ADJUSTR, Right adjust a string
49 * @code{AIMAG}: AIMAG, Imaginary part of complex number
50 * @code{AINT}: AINT, Truncate to a whole number
51 * @code{ALARM}: ALARM, Set an alarm clock
52 * @code{ALL}: ALL, Determine if all values are true
53 * @code{ALLOCATED}: ALLOCATED, Status of allocatable entity
54 * @code{AND}: AND, Bitwise logical AND
55 * @code{ANINT}: ANINT, Nearest whole number
56 * @code{ANY}: ANY, Determine if any values are true
57 * @code{ASIN}: ASIN, Arcsine function
58 * @code{ASINH}: ASINH, Inverse hyperbolic sine function
59 * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair
60 * @code{ATAN}: ATAN, Arctangent function
61 * @code{ATAN2}: ATAN2, Arctangent function
62 * @code{ATANH}: ATANH, Inverse hyperbolic tangent function
63 * @code{ATOMIC_ADD}: ATOMIC_ADD, Atomic ADD operation
64 * @code{ATOMIC_AND}: ATOMIC_AND, Atomic bitwise AND operation
65 * @code{ATOMIC_CAS}: ATOMIC_CAS, Atomic compare and swap
66 * @code{ATOMIC_DEFINE}: ATOMIC_DEFINE, Setting a variable atomically
67 * @code{ATOMIC_FETCH_ADD}: ATOMIC_FETCH_ADD, Atomic ADD operation with prior fetch
68 * @code{ATOMIC_FETCH_AND}: ATOMIC_FETCH_AND, Atomic bitwise AND operation with prior fetch
69 * @code{ATOMIC_FETCH_OR}: ATOMIC_FETCH_OR, Atomic bitwise OR operation with prior fetch
70 * @code{ATOMIC_FETCH_XOR}: ATOMIC_FETCH_XOR, Atomic bitwise XOR operation with prior fetch
71 * @code{ATOMIC_OR}: ATOMIC_OR, Atomic bitwise OR operation
72 * @code{ATOMIC_REF}: ATOMIC_REF, Obtaining the value of a variable atomically
73 * @code{ATOMIC_XOR}: ATOMIC_XOR, Atomic bitwise OR operation
74 * @code{BACKTRACE}: BACKTRACE, Show a backtrace
75 * @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0
76 * @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1
77 * @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind
78 * @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0
79 * @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1
80 * @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind
81 * @code{BGE}: BGE, Bitwise greater than or equal to
82 * @code{BGT}: BGT, Bitwise greater than
83 * @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function
84 * @code{BLE}: BLE, Bitwise less than or equal to
85 * @code{BLT}: BLT, Bitwise less than
86 * @code{BTEST}: BTEST, Bit test function
87 * @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer
88 * @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer
89 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
90 * @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure
91 * @code{C_LOC}: C_LOC, Obtain the C address of an object
92 * @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression
93 * @code{CEILING}: CEILING, Integer ceiling function
94 * @code{CHAR}: CHAR, Integer-to-character conversion function
95 * @code{CHDIR}: CHDIR, Change working directory
96 * @code{CHMOD}: CHMOD, Change access permissions of files
97 * @code{CMPLX}: CMPLX, Complex conversion function
98 * @code{CO_BROADCAST}: CO_BROADCAST, Copy a value to all images the current set of images
99 * @code{CO_MAX}: CO_MAX, Maximal value on the current set of images
100 * @code{CO_MIN}: CO_MIN, Minimal value on the current set of images
101 * @code{CO_REDUCE}: CO_REDUCE, Reduction of values on the current set of images
102 * @code{CO_SUM}: CO_SUM, Sum of values on the current set of images
103 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
104 * @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler
105 * @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string
106 * @code{COMPLEX}: COMPLEX, Complex conversion function
107 * @code{CONJG}: CONJG, Complex conjugate function
108 * @code{COS}: COS, Cosine function
109 * @code{COSH}: COSH, Hyperbolic cosine function
110 * @code{COUNT}: COUNT, Count occurrences of TRUE in an array
111 * @code{CPU_TIME}: CPU_TIME, CPU time subroutine
112 * @code{CSHIFT}: CSHIFT, Circular shift elements of an array
113 * @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string
114 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
115 * @code{DBLE}: DBLE, Double precision conversion function
116 * @code{DCMPLX}: DCMPLX, Double complex conversion function
117 * @code{DIGITS}: DIGITS, Significant digits function
118 * @code{DIM}: DIM, Positive difference
119 * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
120 * @code{DPROD}: DPROD, Double product function
121 * @code{DREAL}: DREAL, Double real part function
122 * @code{DSHIFTL}: DSHIFTL, Combined left shift
123 * @code{DSHIFTR}: DSHIFTR, Combined right shift
124 * @code{DTIME}: DTIME, Execution time subroutine (or function)
125 * @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array
126 * @code{EPSILON}: EPSILON, Epsilon function
127 * @code{ERF}: ERF, Error function
128 * @code{ERFC}: ERFC, Complementary error function
129 * @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function
130 * @code{ETIME}: ETIME, Execution time subroutine (or function)
131 * @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command
132 * @code{EXIT}: EXIT, Exit the program with status.
133 * @code{EXP}: EXP, Exponential function
134 * @code{EXPONENT}: EXPONENT, Exponent function
135 * @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF, Query dynamic type for extension
136 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
137 * @code{FGET}: FGET, Read a single character in stream mode from stdin
138 * @code{FGETC}: FGETC, Read a single character in stream mode
139 * @code{FLOOR}: FLOOR, Integer floor function
140 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
141 * @code{FNUM}: FNUM, File number function
142 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
143 * @code{FPUTC}: FPUTC, Write a single character in stream mode
144 * @code{FRACTION}: FRACTION, Fractional part of the model representation
145 * @code{FREE}: FREE, Memory de-allocation subroutine
146 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
147 * @code{FSTAT}: FSTAT, Get file status
148 * @code{FTELL}: FTELL, Current stream position
149 * @code{GAMMA}: GAMMA, Gamma function
150 * @code{GERROR}: GERROR, Get last system error message
151 * @code{GETARG}: GETARG, Get command line arguments
152 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
153 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
154 * @code{GETCWD}: GETCWD, Get current working directory
155 * @code{GETENV}: GETENV, Get an environmental variable
156 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
157 * @code{GETGID}: GETGID, Group ID function
158 * @code{GETLOG}: GETLOG, Get login name
159 * @code{GETPID}: GETPID, Process ID function
160 * @code{GETUID}: GETUID, User ID function
161 * @code{GMTIME}: GMTIME, Convert time to GMT info
162 * @code{HOSTNM}: HOSTNM, Get system host name
163 * @code{HUGE}: HUGE, Largest number of a kind
164 * @code{HYPOT}: HYPOT, Euclidean distance function
165 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
166 * @code{IALL}: IALL, Bitwise AND of array elements
167 * @code{IAND}: IAND, Bitwise logical and
168 * @code{IANY}: IANY, Bitwise OR of array elements
169 * @code{IARGC}: IARGC, Get the number of command line arguments
170 * @code{IBCLR}: IBCLR, Clear bit
171 * @code{IBITS}: IBITS, Bit extraction
172 * @code{IBSET}: IBSET, Set bit
173 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
174 * @code{IDATE}: IDATE, Current local time (day/month/year)
175 * @code{IEOR}: IEOR, Bitwise logical exclusive or
176 * @code{IERRNO}: IERRNO, Function to get the last system error number
177 * @code{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index conversion
178 * @code{INDEX}: INDEX intrinsic, Position of a substring within a string
179 * @code{INT}: INT, Convert to integer type
180 * @code{INT2}: INT2, Convert to 16-bit integer type
181 * @code{INT8}: INT8, Convert to 64-bit integer type
182 * @code{IOR}: IOR, Bitwise logical or
183 * @code{IPARITY}: IPARITY, Bitwise XOR of array elements
184 * @code{IRAND}: IRAND, Integer pseudo-random number
185 * @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value
186 * @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value
187 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
188 * @code{ISHFT}: ISHFT, Shift bits
189 * @code{ISHFTC}: ISHFTC, Shift bits circularly
190 * @code{ISNAN}: ISNAN, Tests for a NaN
191 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
192 * @code{KILL}: KILL, Send a signal to a process
193 * @code{KIND}: KIND, Kind of an entity
194 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
195 * @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array
196 * @code{LEADZ}: LEADZ, Number of leading zero bits of an integer
197 * @code{LEN}: LEN, Length of a character entity
198 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
199 * @code{LGE}: LGE, Lexical greater than or equal
200 * @code{LGT}: LGT, Lexical greater than
201 * @code{LINK}: LINK, Create a hard link
202 * @code{LLE}: LLE, Lexical less than or equal
203 * @code{LLT}: LLT, Lexical less than
204 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
205 * @code{LOC}: LOC, Returns the address of a variable
206 * @code{LOG}: LOG, Logarithm function
207 * @code{LOG10}: LOG10, Base 10 logarithm function
208 * @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
209 * @code{LOGICAL}: LOGICAL, Convert to logical type
210 * @code{LONG}: LONG, Convert to integer type
211 * @code{LSHIFT}: LSHIFT, Left shift bits
212 * @code{LSTAT}: LSTAT, Get file status
213 * @code{LTIME}: LTIME, Convert time to local time info
214 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
215 * @code{MASKL}: MASKL, Left justified mask
216 * @code{MASKR}: MASKR, Right justified mask
217 * @code{MATMUL}: MATMUL, matrix multiplication
218 * @code{MAX}: MAX, Maximum value of an argument list
219 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
220 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
221 * @code{MAXVAL}: MAXVAL, Maximum value of an array
222 * @code{MCLOCK}: MCLOCK, Time function
223 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
224 * @code{MERGE}: MERGE, Merge arrays
225 * @code{MERGE_BITS}: MERGE_BITS, Merge of bits under mask
226 * @code{MIN}: MIN, Minimum value of an argument list
227 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
228 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
229 * @code{MINVAL}: MINVAL, Minimum value of an array
230 * @code{MOD}: MOD, Remainder function
231 * @code{MODULO}: MODULO, Modulo function
232 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
233 * @code{MVBITS}: MVBITS, Move bits from one integer to another
234 * @code{NEAREST}: NEAREST, Nearest representable number
235 * @code{NEW_LINE}: NEW_LINE, New line character
236 * @code{NINT}: NINT, Nearest whole number
237 * @code{NORM2}: NORM2, Euclidean vector norm
238 * @code{NOT}: NOT, Logical negation
239 * @code{NULL}: NULL, Function that returns an disassociated pointer
240 * @code{NUM_IMAGES}: NUM_IMAGES, Number of images
241 * @code{OR}: OR, Bitwise logical OR
242 * @code{PACK}: PACK, Pack an array into an array of rank one
243 * @code{PARITY}: PARITY, Reduction with exclusive OR
244 * @code{PERROR}: PERROR, Print system error message
245 * @code{POPCNT}: POPCNT, Number of bits set
246 * @code{POPPAR}: POPPAR, Parity of the number of bits set
247 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
248 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
249 * @code{PRODUCT}: PRODUCT, Product of array elements
250 * @code{RADIX}: RADIX, Base of a data model
251 * @code{RAN}: RAN, Real pseudo-random number
252 * @code{RAND}: RAND, Real pseudo-random number
253 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
254 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
255 * @code{RANGE}: RANGE, Decimal exponent range
256 * @code{RANK} : RANK, Rank of a data object
257 * @code{REAL}: REAL, Convert to real type
258 * @code{RENAME}: RENAME, Rename a file
259 * @code{REPEAT}: REPEAT, Repeated string concatenation
260 * @code{RESHAPE}: RESHAPE, Function to reshape an array
261 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
262 * @code{RSHIFT}: RSHIFT, Right shift bits
263 * @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality
264 * @code{SCALE}: SCALE, Scale a real value
265 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
266 * @code{SECNDS}: SECNDS, Time function
267 * @code{SECOND}: SECOND, CPU time function
268 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind
269 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
270 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
271 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
272 * @code{SHAPE}: SHAPE, Determine the shape of an array
273 * @code{SHIFTA}: SHIFTA, Right shift with fill
274 * @code{SHIFTL}: SHIFTL, Left shift
275 * @code{SHIFTR}: SHIFTR, Right shift
276 * @code{SIGN}: SIGN, Sign copying function
277 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
278 * @code{SIN}: SIN, Sine function
279 * @code{SINH}: SINH, Hyperbolic sine function
280 * @code{SIZE}: SIZE, Function to determine the size of an array
281 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
282 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
283 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
284 * @code{SPREAD}: SPREAD, Add a dimension to an array
285 * @code{SQRT}: SQRT, Square-root function
286 * @code{SRAND}: SRAND, Reinitialize the random number generator
287 * @code{STAT}: STAT, Get file status
288 * @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits
289 * @code{SUM}: SUM, Sum of array elements
290 * @code{SYMLNK}: SYMLNK, Create a symbolic link
291 * @code{SYSTEM}: SYSTEM, Execute a shell command
292 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
293 * @code{TAN}: TAN, Tangent function
294 * @code{TANH}: TANH, Hyperbolic tangent function
295 * @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image
296 * @code{TIME}: TIME, Time function
297 * @code{TIME8}: TIME8, Time function (64-bit)
298 * @code{TINY}: TINY, Smallest positive number of a real kind
299 * @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer
300 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
301 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
302 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
303 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
304 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
305 * @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array
306 * @code{UMASK}: UMASK, Set the file creation mask
307 * @code{UNLINK}: UNLINK, Remove a file from the file system
308 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
309 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
310 * @code{XOR}: XOR, Bitwise logical exclusive or
313 @node Introduction to Intrinsics
314 @section Introduction to intrinsic procedures
316 The intrinsic procedures provided by GNU Fortran include all of the
317 intrinsic procedures required by the Fortran 95 standard, a set of
318 intrinsic procedures for backwards compatibility with G77, and a
319 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
320 standards. Any conflict between a description here and a description in
321 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
322 2008 standard is unintentional, and the standard(s) should be considered
325 The enumeration of the @code{KIND} type parameter is processor defined in
326 the Fortran 95 standard. GNU Fortran defines the default integer type and
327 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
328 respectively. The standard mandates that both data types shall have
329 another kind, which have more precision. On typical target architectures
330 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
331 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
332 In the description of generic intrinsic procedures, the kind type parameter
333 will be specified by @code{KIND=*}, and in the description of specific
334 names for an intrinsic procedure the kind type parameter will be explicitly
335 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
336 brevity the optional @code{KIND=} syntax will be omitted.
338 Many of the intrinsic procedures take one or more optional arguments.
339 This document follows the convention used in the Fortran 95 standard,
340 and denotes such arguments by square brackets.
342 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
343 which can be used to restrict the set of intrinsic procedures to a
344 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
345 option, and so all intrinsic procedures described here are accepted. There
346 is one caveat. For a select group of intrinsic procedures, @command{g77}
347 implemented both a function and a subroutine. Both classes
348 have been implemented in @command{gfortran} for backwards compatibility
349 with @command{g77}. It is noted here that these functions and subroutines
350 cannot be intermixed in a given subprogram. In the descriptions that follow,
351 the applicable standard for each intrinsic procedure is noted.
356 @section @code{ABORT} --- Abort the program
358 @cindex program termination, with core dump
359 @cindex terminate program, with core dump
363 @item @emph{Description}:
364 @code{ABORT} causes immediate termination of the program. On operating
365 systems that support a core dump, @code{ABORT} will produce a core dump.
366 It will also print a backtrace, unless @code{-fno-backtrace} is given.
368 @item @emph{Standard}:
377 @item @emph{Return value}:
380 @item @emph{Example}:
383 integer :: i = 1, j = 2
384 if (i /= j) call abort
385 end program test_abort
388 @item @emph{See also}:
389 @ref{EXIT}, @ref{KILL}, @ref{BACKTRACE}
396 @section @code{ABS} --- Absolute value
403 @cindex absolute value
406 @item @emph{Description}:
407 @code{ABS(A)} computes the absolute value of @code{A}.
409 @item @emph{Standard}:
410 Fortran 77 and later, has overloads that are GNU extensions
416 @code{RESULT = ABS(A)}
418 @item @emph{Arguments}:
419 @multitable @columnfractions .15 .70
420 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
421 @code{REAL}, or @code{COMPLEX}.
424 @item @emph{Return value}:
425 The return value is of the same type and
426 kind as the argument except the return value is @code{REAL} for a
427 @code{COMPLEX} argument.
429 @item @emph{Example}:
434 complex :: z = (-1.e0,0.e0)
441 @item @emph{Specific names}:
442 @multitable @columnfractions .20 .20 .20 .25
443 @item Name @tab Argument @tab Return type @tab Standard
444 @item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
445 @item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
446 @item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
447 @item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
448 @item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
449 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
456 @section @code{ACCESS} --- Checks file access modes
458 @cindex file system, access mode
461 @item @emph{Description}:
462 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
463 exists, is readable, writable or executable. Except for the
464 executable check, @code{ACCESS} can be replaced by
465 Fortran 95's @code{INQUIRE}.
467 @item @emph{Standard}:
474 @code{RESULT = ACCESS(NAME, MODE)}
476 @item @emph{Arguments}:
477 @multitable @columnfractions .15 .70
478 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
479 file name. Tailing blank are ignored unless the character @code{achar(0)}
480 is present, then all characters up to and excluding @code{achar(0)} are
482 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
483 file access mode, may be any concatenation of @code{"r"} (readable),
484 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
488 @item @emph{Return value}:
489 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
490 accessible in the given mode; otherwise or if an invalid argument
491 has been given for @code{MODE} the value @code{1} is returned.
493 @item @emph{Example}:
497 character(len=*), parameter :: file = 'test.dat'
498 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
499 if(access(file,' ') == 0) print *, trim(file),' is exists'
500 if(access(file,'r') == 0) print *, trim(file),' is readable'
501 if(access(file,'w') == 0) print *, trim(file),' is writable'
502 if(access(file,'x') == 0) print *, trim(file),' is executable'
503 if(access(file2,'rwx') == 0) &
504 print *, trim(file2),' is readable, writable and executable'
505 end program access_test
507 @item @emph{Specific names}:
508 @item @emph{See also}:
515 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
517 @cindex @acronym{ASCII} collating sequence
518 @cindex collating sequence, @acronym{ASCII}
521 @item @emph{Description}:
522 @code{ACHAR(I)} returns the character located at position @code{I}
523 in the @acronym{ASCII} collating sequence.
525 @item @emph{Standard}:
526 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
532 @code{RESULT = ACHAR(I [, KIND])}
534 @item @emph{Arguments}:
535 @multitable @columnfractions .15 .70
536 @item @var{I} @tab The type shall be @code{INTEGER}.
537 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
538 expression indicating the kind parameter of the result.
541 @item @emph{Return value}:
542 The return value is of type @code{CHARACTER} with a length of one.
543 If the @var{KIND} argument is present, the return value is of the
544 specified kind and of the default kind otherwise.
546 @item @emph{Example}:
551 end program test_achar
555 See @ref{ICHAR} for a discussion of converting between numerical values
556 and formatted string representations.
558 @item @emph{See also}:
559 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
566 @section @code{ACOS} --- Arccosine function
569 @cindex trigonometric function, cosine, inverse
570 @cindex cosine, inverse
573 @item @emph{Description}:
574 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
576 @item @emph{Standard}:
577 Fortran 77 and later, for a complex argument Fortran 2008 or later
583 @code{RESULT = ACOS(X)}
585 @item @emph{Arguments}:
586 @multitable @columnfractions .15 .70
587 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
588 less than or equal to one - or the type shall be @code{COMPLEX}.
591 @item @emph{Return value}:
592 The return value is of the same type and kind as @var{X}.
593 The real part of the result is in radians and lies in the range
594 @math{0 \leq \Re \acos(x) \leq \pi}.
596 @item @emph{Example}:
599 real(8) :: x = 0.866_8
601 end program test_acos
604 @item @emph{Specific names}:
605 @multitable @columnfractions .20 .20 .20 .25
606 @item Name @tab Argument @tab Return type @tab Standard
607 @item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
608 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
611 @item @emph{See also}:
612 Inverse function: @ref{COS}
619 @section @code{ACOSH} --- Inverse hyperbolic cosine function
622 @cindex area hyperbolic cosine
623 @cindex inverse hyperbolic cosine
624 @cindex hyperbolic function, cosine, inverse
625 @cindex cosine, hyperbolic, inverse
628 @item @emph{Description}:
629 @code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
631 @item @emph{Standard}:
632 Fortran 2008 and later
638 @code{RESULT = ACOSH(X)}
640 @item @emph{Arguments}:
641 @multitable @columnfractions .15 .70
642 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
645 @item @emph{Return value}:
646 The return value has the same type and kind as @var{X}. If @var{X} is
647 complex, the imaginary part of the result is in radians and lies between
648 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
650 @item @emph{Example}:
653 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
658 @item @emph{Specific names}:
659 @multitable @columnfractions .20 .20 .20 .25
660 @item Name @tab Argument @tab Return type @tab Standard
661 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
664 @item @emph{See also}:
665 Inverse function: @ref{COSH}
671 @section @code{ADJUSTL} --- Left adjust a string
673 @cindex string, adjust left
674 @cindex adjust string
677 @item @emph{Description}:
678 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
679 Spaces are inserted at the end of the string as needed.
681 @item @emph{Standard}:
688 @code{RESULT = ADJUSTL(STRING)}
690 @item @emph{Arguments}:
691 @multitable @columnfractions .15 .70
692 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
695 @item @emph{Return value}:
696 The return value is of type @code{CHARACTER} and of the same kind as
697 @var{STRING} where leading spaces are removed and the same number of
698 spaces are inserted on the end of @var{STRING}.
700 @item @emph{Example}:
703 character(len=20) :: str = ' gfortran'
706 end program test_adjustl
709 @item @emph{See also}:
710 @ref{ADJUSTR}, @ref{TRIM}
716 @section @code{ADJUSTR} --- Right adjust a string
718 @cindex string, adjust right
719 @cindex adjust string
722 @item @emph{Description}:
723 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
724 Spaces are inserted at the start of the string as needed.
726 @item @emph{Standard}:
733 @code{RESULT = ADJUSTR(STRING)}
735 @item @emph{Arguments}:
736 @multitable @columnfractions .15 .70
737 @item @var{STR} @tab The type shall be @code{CHARACTER}.
740 @item @emph{Return value}:
741 The return value is of type @code{CHARACTER} and of the same kind as
742 @var{STRING} where trailing spaces are removed and the same number of
743 spaces are inserted at the start of @var{STRING}.
745 @item @emph{Example}:
748 character(len=20) :: str = 'gfortran'
751 end program test_adjustr
754 @item @emph{See also}:
755 @ref{ADJUSTL}, @ref{TRIM}
761 @section @code{AIMAG} --- Imaginary part of complex number
766 @cindex complex numbers, imaginary part
769 @item @emph{Description}:
770 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
771 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
772 for compatibility with @command{g77}, and their use in new code is
773 strongly discouraged.
775 @item @emph{Standard}:
776 Fortran 77 and later, has overloads that are GNU extensions
782 @code{RESULT = AIMAG(Z)}
784 @item @emph{Arguments}:
785 @multitable @columnfractions .15 .70
786 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
789 @item @emph{Return value}:
790 The return value is of type @code{REAL} with the
791 kind type parameter of the argument.
793 @item @emph{Example}:
798 z4 = cmplx(1.e0_4, 0.e0_4)
799 z8 = cmplx(0.e0_8, 1.e0_8)
800 print *, aimag(z4), dimag(z8)
801 end program test_aimag
804 @item @emph{Specific names}:
805 @multitable @columnfractions .20 .20 .20 .25
806 @item Name @tab Argument @tab Return type @tab Standard
807 @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
808 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
809 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
810 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
817 @section @code{AINT} --- Truncate to a whole number
821 @cindex rounding, floor
824 @item @emph{Description}:
825 @code{AINT(A [, KIND])} truncates its argument to a whole number.
827 @item @emph{Standard}:
834 @code{RESULT = AINT(A [, KIND])}
836 @item @emph{Arguments}:
837 @multitable @columnfractions .15 .70
838 @item @var{A} @tab The type of the argument shall be @code{REAL}.
839 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
840 expression indicating the kind parameter of the result.
843 @item @emph{Return value}:
844 The return value is of type @code{REAL} with the kind type parameter of the
845 argument if the optional @var{KIND} is absent; otherwise, the kind
846 type parameter will be given by @var{KIND}. If the magnitude of
847 @var{X} is less than one, @code{AINT(X)} returns zero. If the
848 magnitude is equal to or greater than one then it returns the largest
849 whole number that does not exceed its magnitude. The sign is the same
850 as the sign of @var{X}.
852 @item @emph{Example}:
859 print *, aint(x4), dint(x8)
861 end program test_aint
864 @item @emph{Specific names}:
865 @multitable @columnfractions .20 .20 .20 .25
866 @item Name @tab Argument @tab Return type @tab Standard
867 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
868 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
875 @section @code{ALARM} --- Execute a routine after a given delay
877 @cindex delayed execution
880 @item @emph{Description}:
881 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
882 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
883 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
884 supplied, it will be returned with the number of seconds remaining until
885 any previously scheduled alarm was due to be delivered, or zero if there
886 was no previously scheduled alarm.
888 @item @emph{Standard}:
895 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
897 @item @emph{Arguments}:
898 @multitable @columnfractions .15 .70
899 @item @var{SECONDS} @tab The type of the argument shall be a scalar
900 @code{INTEGER}. It is @code{INTENT(IN)}.
901 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
902 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
903 values may be either @code{SIG_IGN=1} to ignore the alarm generated
904 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
905 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
906 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
909 @item @emph{Example}:
912 external handler_print
914 call alarm (3, handler_print, i)
917 end program test_alarm
919 This will cause the external routine @var{handler_print} to be called
926 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
928 @cindex array, apply condition
929 @cindex array, condition testing
932 @item @emph{Description}:
933 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
934 in the array along dimension @var{DIM}.
936 @item @emph{Standard}:
940 Transformational function
943 @code{RESULT = ALL(MASK [, DIM])}
945 @item @emph{Arguments}:
946 @multitable @columnfractions .15 .70
947 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
948 it shall not be scalar.
949 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
950 with a value that lies between one and the rank of @var{MASK}.
953 @item @emph{Return value}:
954 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
955 the kind type parameter is the same as the kind type parameter of
956 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
957 an array with the rank of @var{MASK} minus 1. The shape is determined from
958 the shape of @var{MASK} where the @var{DIM} dimension is elided.
962 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
963 It also is true if @var{MASK} has zero size; otherwise, it is false.
965 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
966 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
967 is determined by applying @code{ALL} to the array sections.
970 @item @emph{Example}:
974 l = all((/.true., .true., .true./))
979 integer a(2,3), b(2,3)
983 print *, all(a .eq. b, 1)
984 print *, all(a .eq. b, 2)
985 end subroutine section
993 @section @code{ALLOCATED} --- Status of an allocatable entity
995 @cindex allocation, status
998 @item @emph{Description}:
999 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
1000 status of @var{ARRAY} and @var{SCALAR}, respectively.
1002 @item @emph{Standard}:
1003 Fortran 95 and later. Note, the @code{SCALAR=} keyword and allocatable
1004 scalar entities are available in Fortran 2003 and later.
1009 @item @emph{Syntax}:
1010 @multitable @columnfractions .80
1011 @item @code{RESULT = ALLOCATED(ARRAY)}
1012 @item @code{RESULT = ALLOCATED(SCALAR)}
1015 @item @emph{Arguments}:
1016 @multitable @columnfractions .15 .70
1017 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
1018 @item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar.
1021 @item @emph{Return value}:
1022 The return value is a scalar @code{LOGICAL} with the default logical
1023 kind type parameter. If the argument is allocated, then the result is
1024 @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
1026 @item @emph{Example}:
1028 program test_allocated
1030 real(4), allocatable :: x(:)
1031 if (.not. allocated(x)) allocate(x(i))
1032 end program test_allocated
1039 @section @code{AND} --- Bitwise logical AND
1041 @cindex bitwise logical and
1042 @cindex logical and, bitwise
1045 @item @emph{Description}:
1046 Bitwise logical @code{AND}.
1048 This intrinsic routine is provided for backwards compatibility with
1049 GNU Fortran 77. For integer arguments, programmers should consider
1050 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1052 @item @emph{Standard}:
1058 @item @emph{Syntax}:
1059 @code{RESULT = AND(I, J)}
1061 @item @emph{Arguments}:
1062 @multitable @columnfractions .15 .70
1063 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1064 type or a scalar @code{LOGICAL} type.
1065 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1068 @item @emph{Return value}:
1069 The return type is either a scalar @code{INTEGER} or a scalar
1070 @code{LOGICAL}. If the kind type parameters differ, then the
1071 smaller kind type is implicitly converted to larger kind, and the
1072 return has the larger kind.
1074 @item @emph{Example}:
1077 LOGICAL :: T = .TRUE., F = .FALSE.
1079 DATA a / Z'F' /, b / Z'3' /
1081 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1082 WRITE (*,*) AND(a, b)
1086 @item @emph{See also}:
1087 Fortran 95 elemental function: @ref{IAND}
1093 @section @code{ANINT} --- Nearest whole number
1097 @cindex rounding, ceiling
1100 @item @emph{Description}:
1101 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1103 @item @emph{Standard}:
1104 Fortran 77 and later
1109 @item @emph{Syntax}:
1110 @code{RESULT = ANINT(A [, KIND])}
1112 @item @emph{Arguments}:
1113 @multitable @columnfractions .15 .70
1114 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1115 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1116 expression indicating the kind parameter of the result.
1119 @item @emph{Return value}:
1120 The return value is of type real with the kind type parameter of the
1121 argument if the optional @var{KIND} is absent; otherwise, the kind
1122 type parameter will be given by @var{KIND}. If @var{A} is greater than
1123 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1124 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1126 @item @emph{Example}:
1133 print *, anint(x4), dnint(x8)
1135 end program test_anint
1138 @item @emph{Specific names}:
1139 @multitable @columnfractions .20 .20 .20 .25
1140 @item Name @tab Argument @tab Return type @tab Standard
1141 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
1142 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1149 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1151 @cindex array, apply condition
1152 @cindex array, condition testing
1155 @item @emph{Description}:
1156 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1157 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1159 @item @emph{Standard}:
1160 Fortran 95 and later
1163 Transformational function
1165 @item @emph{Syntax}:
1166 @code{RESULT = ANY(MASK [, DIM])}
1168 @item @emph{Arguments}:
1169 @multitable @columnfractions .15 .70
1170 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1171 it shall not be scalar.
1172 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1173 with a value that lies between one and the rank of @var{MASK}.
1176 @item @emph{Return value}:
1177 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1178 the kind type parameter is the same as the kind type parameter of
1179 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1180 an array with the rank of @var{MASK} minus 1. The shape is determined from
1181 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1185 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1186 otherwise, it is false. It also is false if @var{MASK} has zero size.
1188 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1189 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1190 is determined by applying @code{ANY} to the array sections.
1193 @item @emph{Example}:
1197 l = any((/.true., .true., .true./))
1202 integer a(2,3), b(2,3)
1206 print *, any(a .eq. b, 1)
1207 print *, any(a .eq. b, 2)
1208 end subroutine section
1209 end program test_any
1216 @section @code{ASIN} --- Arcsine function
1219 @cindex trigonometric function, sine, inverse
1220 @cindex sine, inverse
1223 @item @emph{Description}:
1224 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1226 @item @emph{Standard}:
1227 Fortran 77 and later, for a complex argument Fortran 2008 or later
1232 @item @emph{Syntax}:
1233 @code{RESULT = ASIN(X)}
1235 @item @emph{Arguments}:
1236 @multitable @columnfractions .15 .70
1237 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1238 less than or equal to one - or be @code{COMPLEX}.
1241 @item @emph{Return value}:
1242 The return value is of the same type and kind as @var{X}.
1243 The real part of the result is in radians and lies in the range
1244 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1246 @item @emph{Example}:
1249 real(8) :: x = 0.866_8
1251 end program test_asin
1254 @item @emph{Specific names}:
1255 @multitable @columnfractions .20 .20 .20 .25
1256 @item Name @tab Argument @tab Return type @tab Standard
1257 @item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1258 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1261 @item @emph{See also}:
1262 Inverse function: @ref{SIN}
1269 @section @code{ASINH} --- Inverse hyperbolic sine function
1272 @cindex area hyperbolic sine
1273 @cindex inverse hyperbolic sine
1274 @cindex hyperbolic function, sine, inverse
1275 @cindex sine, hyperbolic, inverse
1278 @item @emph{Description}:
1279 @code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
1281 @item @emph{Standard}:
1282 Fortran 2008 and later
1287 @item @emph{Syntax}:
1288 @code{RESULT = ASINH(X)}
1290 @item @emph{Arguments}:
1291 @multitable @columnfractions .15 .70
1292 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1295 @item @emph{Return value}:
1296 The return value is of the same type and kind as @var{X}. If @var{X} is
1297 complex, the imaginary part of the result is in radians and lies between
1298 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1300 @item @emph{Example}:
1303 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1304 WRITE (*,*) ASINH(x)
1308 @item @emph{Specific names}:
1309 @multitable @columnfractions .20 .20 .20 .25
1310 @item Name @tab Argument @tab Return type @tab Standard
1311 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1314 @item @emph{See also}:
1315 Inverse function: @ref{SINH}
1321 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1323 @cindex pointer, status
1324 @cindex association status
1327 @item @emph{Description}:
1328 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1329 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1331 @item @emph{Standard}:
1332 Fortran 95 and later
1337 @item @emph{Syntax}:
1338 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1340 @item @emph{Arguments}:
1341 @multitable @columnfractions .15 .70
1342 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1343 and it can be of any type.
1344 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1345 a target. It must have the same type, kind type parameter, and
1346 array rank as @var{POINTER}.
1348 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1351 @item @emph{Return value}:
1352 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1353 There are several cases:
1355 @item (A) When the optional @var{TARGET} is not present then
1356 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1357 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1358 @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
1359 disassociated, the result is false.
1360 @item (C) If @var{TARGET} is present and an array target, the result is true if
1361 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1362 are arrays whose elements are not zero-sized storage sequences, and
1363 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1365 As in case(B), the result is false, if @var{POINTER} is disassociated.
1366 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1367 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1368 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1370 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1371 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1372 target associated with @var{POINTER} and the target associated with @var{TARGET}
1373 have the same shape, are not zero-sized arrays, are arrays whose elements are
1374 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1375 the same storage units in array element order.
1376 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1379 @item @emph{Example}:
1381 program test_associated
1383 real, target :: tgt(2) = (/1., 2./)
1384 real, pointer :: ptr(:)
1386 if (associated(ptr) .eqv. .false.) call abort
1387 if (associated(ptr,tgt) .eqv. .false.) call abort
1388 end program test_associated
1391 @item @emph{See also}:
1398 @section @code{ATAN} --- Arctangent function
1401 @cindex trigonometric function, tangent, inverse
1402 @cindex tangent, inverse
1405 @item @emph{Description}:
1406 @code{ATAN(X)} computes the arctangent of @var{X}.
1408 @item @emph{Standard}:
1409 Fortran 77 and later, for a complex argument and for two arguments
1410 Fortran 2008 or later
1415 @item @emph{Syntax}:
1416 @multitable @columnfractions .80
1417 @item @code{RESULT = ATAN(X)}
1418 @item @code{RESULT = ATAN(Y, X)}
1421 @item @emph{Arguments}:
1422 @multitable @columnfractions .15 .70
1423 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1424 if @var{Y} is present, @var{X} shall be REAL.
1425 @item @var{Y} shall be of the same type and kind as @var{X}.
1428 @item @emph{Return value}:
1429 The return value is of the same type and kind as @var{X}.
1430 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1431 Otherwise, it the arcus tangent of @var{X}, where the real part of
1432 the result is in radians and lies in the range
1433 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1435 @item @emph{Example}:
1438 real(8) :: x = 2.866_8
1440 end program test_atan
1443 @item @emph{Specific names}:
1444 @multitable @columnfractions .20 .20 .20 .25
1445 @item Name @tab Argument @tab Return type @tab Standard
1446 @item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1447 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1450 @item @emph{See also}:
1451 Inverse function: @ref{TAN}
1458 @section @code{ATAN2} --- Arctangent function
1461 @cindex trigonometric function, tangent, inverse
1462 @cindex tangent, inverse
1465 @item @emph{Description}:
1466 @code{ATAN2(Y, X)} computes the principal value of the argument
1467 function of the complex number @math{X + i Y}. This function can
1468 be used to transform from Cartesian into polar coordinates and
1469 allows to determine the angle in the correct quadrant.
1471 @item @emph{Standard}:
1472 Fortran 77 and later
1477 @item @emph{Syntax}:
1478 @code{RESULT = ATAN2(Y, X)}
1480 @item @emph{Arguments}:
1481 @multitable @columnfractions .15 .70
1482 @item @var{Y} @tab The type shall be @code{REAL}.
1483 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1484 If @var{Y} is zero, then @var{X} must be nonzero.
1487 @item @emph{Return value}:
1488 The return value has the same type and kind type parameter as @var{Y}. It
1489 is the principal value of the complex number @math{X + i Y}. If @var{X}
1490 is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1491 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1492 the return value is zero if @var{X} is strictly positive, @math{\pi} if
1493 @var{X} is negative and @var{Y} is positive zero (or the processor does
1494 not handle signed zeros), and @math{-\pi} if @var{X} is negative and
1495 @var{Y} is negative zero. Finally, if @var{X} is zero, then the
1496 magnitude of the result is @math{\pi/2}.
1498 @item @emph{Example}:
1501 real(4) :: x = 1.e0_4, y = 0.5e0_4
1503 end program test_atan2
1506 @item @emph{Specific names}:
1507 @multitable @columnfractions .20 .20 .20 .25
1508 @item Name @tab Argument @tab Return type @tab Standard
1509 @item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1510 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1517 @section @code{ATANH} --- Inverse hyperbolic tangent function
1520 @cindex area hyperbolic tangent
1521 @cindex inverse hyperbolic tangent
1522 @cindex hyperbolic function, tangent, inverse
1523 @cindex tangent, hyperbolic, inverse
1526 @item @emph{Description}:
1527 @code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
1529 @item @emph{Standard}:
1530 Fortran 2008 and later
1535 @item @emph{Syntax}:
1536 @code{RESULT = ATANH(X)}
1538 @item @emph{Arguments}:
1539 @multitable @columnfractions .15 .70
1540 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1543 @item @emph{Return value}:
1544 The return value has same type and kind as @var{X}. If @var{X} is
1545 complex, the imaginary part of the result is in radians and lies between
1546 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1548 @item @emph{Example}:
1551 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1552 WRITE (*,*) ATANH(x)
1556 @item @emph{Specific names}:
1557 @multitable @columnfractions .20 .20 .20 .25
1558 @item Name @tab Argument @tab Return type @tab Standard
1559 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1562 @item @emph{See also}:
1563 Inverse function: @ref{TANH}
1569 @section @code{ATOMIC_ADD} --- Atomic ADD operation
1571 @cindex Atomic subroutine, add
1574 @item @emph{Description}:
1575 @code{ATOMIC_ADD(ATOM, VALUE)} atomically adds the value of @var{VAR} to the
1576 variable @var{ATOM}. When @var{STAT} is present and the invokation was
1577 successful, it is assigned the value 0. If it is present and the invokation
1578 has failed, it is assigned a positive value; in particular, for a coindexed
1579 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1580 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1581 failed, the value @code{STAT_FAILED_IMAGE}.
1583 @item @emph{Standard}:
1589 @item @emph{Syntax}:
1590 @code{CALL ATOMIC_ADD (ATOM, VALUE [, STAT])}
1592 @item @emph{Arguments}:
1593 @multitable @columnfractions .15 .70
1594 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1595 type with @code{ATOMIC_INT_KIND} kind.
1596 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1597 is different, the value is converted to the kind of @var{ATOM}.
1598 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1601 @item @emph{Example}:
1605 integer(atomic_int_kind) :: atom[*]
1606 call atomic_add (atom[1], this_image())
1610 @item @emph{See also}:
1611 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_ADD}, @ref{ISO_FORTRAN_ENV},
1612 @ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
1619 @section @code{ATOMIC_AND} --- Atomic bitwise AND operation
1621 @cindex Atomic subroutine, AND
1624 @item @emph{Description}:
1625 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
1626 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
1627 and the invokation was successful, it is assigned the value 0. If it is present
1628 and the invokation has failed, it is assigned a positive value; in particular,
1629 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
1630 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
1631 image has failed, the value @code{STAT_FAILED_IMAGE}.
1633 @item @emph{Standard}:
1639 @item @emph{Syntax}:
1640 @code{CALL ATOMIC_AND (ATOM, VALUE [, STAT])}
1642 @item @emph{Arguments}:
1643 @multitable @columnfractions .15 .70
1644 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1645 type with @code{ATOMIC_INT_KIND} kind.
1646 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1647 is different, the value is converted to the kind of @var{ATOM}.
1648 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1651 @item @emph{Example}:
1655 integer(atomic_int_kind) :: atom[*]
1656 call atomic_and (atom[1], int(b'10100011101'))
1660 @item @emph{See also}:
1661 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_AND}, @ref{ISO_FORTRAN_ENV},
1662 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
1668 @section @code{ATOMIC_CAS} --- Atomic compare and swap
1669 @fnindex ATOMIC_DEFINE
1670 @cindex Atomic subroutine, compare and swap
1673 @item @emph{Description}:
1674 @code{ATOMIC_CAS} compares the variable @var{ATOM} with the value of
1675 @var{COMPARE}; if the value is the same, @var{ATOM} is set to the value
1676 of @var{NEW}. Additionally, @var{OLD} is set to the value of @var{ATOM}
1677 that was used for the comparison. When @var{STAT} is present and the invokation
1678 was successful, it is assigned the value 0. If it is present and the invokation
1679 has failed, it is assigned a positive value; in particular, for a coindexed
1680 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1681 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1682 failed, the value @code{STAT_FAILED_IMAGE}.
1684 @item @emph{Standard}:
1690 @item @emph{Syntax}:
1691 @code{CALL ATOMIC_CAS (ATOM, OLD, COMPARE, NEW [, STAT])}
1693 @item @emph{Arguments}:
1694 @multitable @columnfractions .15 .70
1695 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
1696 type with @code{ATOMIC_INT_KIND} kind or logical type with
1697 @code{ATOMIC_LOGICAL_KIND} kind.
1698 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1699 @item @var{COMPARE} @tab Scalar variable of the same type and kind as
1701 @item @var{NEW} @tab Scalar variable of the same type as @var{ATOM}. If kind
1702 is different, the value is converted to the kind of @var{ATOM}.
1703 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1706 @item @emph{Example}:
1710 logical(atomic_logical_kind) :: atom[*], prev
1711 call atomic_cas (atom[1], prev, .false., .true.))
1715 @item @emph{See also}:
1716 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_REF}, @ref{ISO_FORTRAN_ENV}
1722 @section @code{ATOMIC_DEFINE} --- Setting a variable atomically
1723 @fnindex ATOMIC_DEFINE
1724 @cindex Atomic subroutine, define
1727 @item @emph{Description}:
1728 @code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value
1729 @var{VALUE} atomically. When @var{STAT} is present and the invokation was
1730 successful, it is assigned the value 0. If it is present and the invokation
1731 has failed, it is assigned a positive value; in particular, for a coindexed
1732 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1733 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1734 failed, the value @code{STAT_FAILED_IMAGE}.
1736 @item @emph{Standard}:
1737 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
1742 @item @emph{Syntax}:
1743 @code{CALL ATOMIC_DEFINE (ATOM, VALUE [, STAT])}
1745 @item @emph{Arguments}:
1746 @multitable @columnfractions .15 .70
1747 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
1748 type with @code{ATOMIC_INT_KIND} kind or logical type with
1749 @code{ATOMIC_LOGICAL_KIND} kind.
1751 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1752 is different, the value is converted to the kind of @var{ATOM}.
1753 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1756 @item @emph{Example}:
1760 integer(atomic_int_kind) :: atom[*]
1761 call atomic_define (atom[1], this_image())
1765 @item @emph{See also}:
1766 @ref{ATOMIC_REF}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV},
1767 @ref{ATOMIC_ADD}, @ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
1772 @node ATOMIC_FETCH_ADD
1773 @section @code{ATOMIC_FETCH_ADD} --- Atomic ADD operation with prior fetch
1774 @fnindex ATOMIC_FETCH_ADD
1775 @cindex Atomic subroutine, ADD with fetch
1778 @item @emph{Description}:
1779 @code{ATOMIC_FETCH_ADD(ATOM, VALUE, OLD)} atomically stores the value of
1780 @var{ATOM} in @var{OLD} and adds the value of @var{VAR} to the
1781 variable @var{ATOM}. When @var{STAT} is present and the invokation was
1782 successful, it is assigned the value 0. If it is present and the invokation
1783 has failed, it is assigned a positive value; in particular, for a coindexed
1784 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1785 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1786 failed, the value @code{STAT_FAILED_IMAGE}.
1788 @item @emph{Standard}:
1794 @item @emph{Syntax}:
1795 @code{CALL ATOMIC_FETCH_ADD (ATOM, VALUE, old [, STAT])}
1797 @item @emph{Arguments}:
1798 @multitable @columnfractions .15 .70
1799 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1800 type with @code{ATOMIC_INT_KIND} kind.
1801 @code{ATOMIC_LOGICAL_KIND} kind.
1803 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1804 is different, the value is converted to the kind of @var{ATOM}.
1805 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1806 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1809 @item @emph{Example}:
1813 integer(atomic_int_kind) :: atom[*], old
1814 call atomic_add (atom[1], this_image(), old)
1818 @item @emph{See also}:
1819 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_ADD}, @ref{ISO_FORTRAN_ENV},
1820 @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR}
1825 @node ATOMIC_FETCH_AND
1826 @section @code{ATOMIC_FETCH_AND} --- Atomic bitwise AND operation with prior fetch
1827 @fnindex ATOMIC_FETCH_AND
1828 @cindex Atomic subroutine, AND with fetch
1831 @item @emph{Description}:
1832 @code{ATOMIC_AND(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
1833 @var{OLD} and defines @var{ATOM} with the bitwise AND between the values of
1834 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was
1835 successful, it is assigned the value 0. If it is present and the invokation has
1836 failed, it is assigned a positive value; in particular, for a coindexed
1837 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1838 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1839 failed, the value @code{STAT_FAILED_IMAGE}.
1841 @item @emph{Standard}:
1847 @item @emph{Syntax}:
1848 @code{CALL ATOMIC_FETCH_AND (ATOM, VALUE, OLD [, STAT])}
1850 @item @emph{Arguments}:
1851 @multitable @columnfractions .15 .70
1852 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1853 type with @code{ATOMIC_INT_KIND} kind.
1854 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1855 is different, the value is converted to the kind of @var{ATOM}.
1856 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1857 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1860 @item @emph{Example}:
1864 integer(atomic_int_kind) :: atom[*], old
1865 call atomic_fetch_and (atom[1], int(b'10100011101'), old)
1869 @item @emph{See also}:
1870 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_AND}, @ref{ISO_FORTRAN_ENV},
1871 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR}
1876 @node ATOMIC_FETCH_OR
1877 @section @code{ATOMIC_FETCH_OR} --- Atomic bitwise OR operation with prior fetch
1878 @fnindex ATOMIC_FETCH_OR
1879 @cindex Atomic subroutine, OR with fetch
1882 @item @emph{Description}:
1883 @code{ATOMIC_OR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
1884 @var{OLD} and defines @var{ATOM} with the bitwise OR between the values of
1885 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was
1886 successful, it is assigned the value 0. If it is present and the invokation has
1887 failed, it is assigned a positive value; in particular, for a coindexed
1888 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1889 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1890 failed, the value @code{STAT_FAILED_IMAGE}.
1892 @item @emph{Standard}:
1898 @item @emph{Syntax}:
1899 @code{CALL ATOMIC_FETCH_OR (ATOM, VALUE, OLD [, STAT])}
1901 @item @emph{Arguments}:
1902 @multitable @columnfractions .15 .70
1903 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1904 type with @code{ATOMIC_INT_KIND} kind.
1905 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1906 is different, the value is converted to the kind of @var{ATOM}.
1907 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1908 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1911 @item @emph{Example}:
1915 integer(atomic_int_kind) :: atom[*], old
1916 call atomic_fetch_or (atom[1], int(b'10100011101'), old)
1920 @item @emph{See also}:
1921 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_OR}, @ref{ISO_FORTRAN_ENV},
1922 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_XOR}
1927 @node ATOMIC_FETCH_XOR
1928 @section @code{ATOMIC_FETCH_XOR} --- Atomic bitwise XOR operation with prior fetch
1929 @fnindex ATOMIC_FETCH_XOR
1930 @cindex Atomic subroutine, XOR with fetch
1933 @item @emph{Description}:
1934 @code{ATOMIC_XOR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
1935 @var{OLD} and defines @var{ATOM} with the bitwise XOR between the values of
1936 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was
1937 successful, it is assigned the value 0. If it is present and the invokation has
1938 failed, it is assigned a positive value; in particular, for a coindexed
1939 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1940 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1941 failed, the value @code{STAT_FAILED_IMAGE}.
1943 @item @emph{Standard}:
1949 @item @emph{Syntax}:
1950 @code{CALL ATOMIC_FETCH_XOR (ATOM, VALUE, OLD [, STAT])}
1952 @item @emph{Arguments}:
1953 @multitable @columnfractions .15 .70
1954 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1955 type with @code{ATOMIC_INT_KIND} kind.
1956 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1957 is different, the value is converted to the kind of @var{ATOM}.
1958 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1959 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1962 @item @emph{Example}:
1966 integer(atomic_int_kind) :: atom[*], old
1967 call atomic_fetch_xor (atom[1], int(b'10100011101'), old)
1971 @item @emph{See also}:
1972 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_XOR}, @ref{ISO_FORTRAN_ENV},
1973 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}
1979 @section @code{ATOMIC_OR} --- Atomic bitwise OR operation
1981 @cindex Atomic subroutine, OR
1984 @item @emph{Description}:
1985 @code{ATOMIC_OR(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
1986 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
1987 and the invokation was successful, it is assigned the value 0. If it is present
1988 and the invokation has failed, it is assigned a positive value; in particular,
1989 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
1990 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
1991 image has failed, the value @code{STAT_FAILED_IMAGE}.
1993 @item @emph{Standard}:
1999 @item @emph{Syntax}:
2000 @code{CALL ATOMIC_OR (ATOM, VALUE [, STAT])}
2002 @item @emph{Arguments}:
2003 @multitable @columnfractions .15 .70
2004 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2005 type with @code{ATOMIC_INT_KIND} kind.
2006 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2007 is different, the value is converted to the kind of @var{ATOM}.
2008 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2011 @item @emph{Example}:
2015 integer(atomic_int_kind) :: atom[*]
2016 call atomic_or (atom[1], int(b'10100011101'))
2020 @item @emph{See also}:
2021 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_OR}, @ref{ISO_FORTRAN_ENV},
2022 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
2028 @section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically
2030 @cindex Atomic subroutine, reference
2033 @item @emph{Description}:
2034 @code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the
2035 variable @var{ATOM} to @var{VALUE}. When @var{STAT} is present and the
2036 invokation was successful, it is assigned the value 0. If it is present and the
2037 invokation has failed, it is assigned a positive value; in particular, for a
2038 coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value
2039 of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image
2040 has failed, the value @code{STAT_FAILED_IMAGE}.
2043 @item @emph{Standard}:
2044 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
2049 @item @emph{Syntax}:
2050 @code{CALL ATOMIC_REF(VALUE, ATOM [, STAT])}
2052 @item @emph{Arguments}:
2053 @multitable @columnfractions .15 .70
2054 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2055 is different, the value is converted to the kind of @var{ATOM}.
2056 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
2057 type with @code{ATOMIC_INT_KIND} kind or logical type with
2058 @code{ATOMIC_LOGICAL_KIND} kind.
2059 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2062 @item @emph{Example}:
2066 logical(atomic_logical_kind) :: atom[*]
2068 call atomic_ref (atom, .false.)
2070 call atomic_ref (atom, val)
2077 @item @emph{See also}:
2078 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV},
2079 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR},
2080 @ref{ATOMIC_FETCH_XOR}
2085 @section @code{ATOMIC_XOR} --- Atomic bitwise OR operation
2087 @cindex Atomic subroutine, XOR
2090 @item @emph{Description}:
2091 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
2092 XOR between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
2093 and the invokation was successful, it is assigned the value 0. If it is present
2094 and the invokation has failed, it is assigned a positive value; in particular,
2095 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
2096 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
2097 image has failed, the value @code{STAT_FAILED_IMAGE}.
2099 @item @emph{Standard}:
2105 @item @emph{Syntax}:
2106 @code{CALL ATOMIC_XOR (ATOM, VALUE [, STAT])}
2108 @item @emph{Arguments}:
2109 @multitable @columnfractions .15 .70
2110 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2111 type with @code{ATOMIC_INT_KIND} kind.
2112 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2113 is different, the value is converted to the kind of @var{ATOM}.
2114 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2117 @item @emph{Example}:
2121 integer(atomic_int_kind) :: atom[*]
2122 call atomic_xor (atom[1], int(b'10100011101'))
2126 @item @emph{See also}:
2127 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_XOR}, @ref{ISO_FORTRAN_ENV},
2128 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
2133 @section @code{BACKTRACE} --- Show a backtrace
2138 @item @emph{Description}:
2139 @code{BACKTRACE} shows a backtrace at an arbitrary place in user code. Program
2140 execution continues normally afterwards. The backtrace information is printed
2141 to the unit corresponding to @code{ERROR_UNIT} in @code{ISO_FORTRAN_ENV}.
2143 @item @emph{Standard}:
2149 @item @emph{Syntax}:
2150 @code{CALL BACKTRACE}
2152 @item @emph{Arguments}:
2155 @item @emph{See also}:
2162 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
2166 @cindex Bessel function, first kind
2169 @item @emph{Description}:
2170 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
2171 order 0 of @var{X}. This function is available under the name
2172 @code{BESJ0} as a GNU extension.
2174 @item @emph{Standard}:
2175 Fortran 2008 and later
2180 @item @emph{Syntax}:
2181 @code{RESULT = BESSEL_J0(X)}
2183 @item @emph{Arguments}:
2184 @multitable @columnfractions .15 .70
2185 @item @var{X} @tab The type shall be @code{REAL}.
2188 @item @emph{Return value}:
2189 The return value is of type @code{REAL} and lies in the
2190 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
2193 @item @emph{Example}:
2196 real(8) :: x = 0.0_8
2198 end program test_besj0
2201 @item @emph{Specific names}:
2202 @multitable @columnfractions .20 .20 .20 .25
2203 @item Name @tab Argument @tab Return type @tab Standard
2204 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2211 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
2215 @cindex Bessel function, first kind
2218 @item @emph{Description}:
2219 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
2220 order 1 of @var{X}. This function is available under the name
2221 @code{BESJ1} as a GNU extension.
2223 @item @emph{Standard}:
2229 @item @emph{Syntax}:
2230 @code{RESULT = BESSEL_J1(X)}
2232 @item @emph{Arguments}:
2233 @multitable @columnfractions .15 .70
2234 @item @var{X} @tab The type shall be @code{REAL}.
2237 @item @emph{Return value}:
2238 The return value is of type @code{REAL} and lies in the
2239 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
2242 @item @emph{Example}:
2245 real(8) :: x = 1.0_8
2247 end program test_besj1
2250 @item @emph{Specific names}:
2251 @multitable @columnfractions .20 .20 .20 .25
2252 @item Name @tab Argument @tab Return type @tab Standard
2253 @item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2260 @section @code{BESSEL_JN} --- Bessel function of the first kind
2264 @cindex Bessel function, first kind
2267 @item @emph{Description}:
2268 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
2269 order @var{N} of @var{X}. This function is available under the name
2270 @code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays,
2271 their ranks and shapes shall conform.
2273 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
2274 of the first kind of the orders @var{N1} to @var{N2}.
2276 @item @emph{Standard}:
2277 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2280 Elemental function, except for the transformational function
2281 @code{BESSEL_JN(N1, N2, X)}
2283 @item @emph{Syntax}:
2284 @multitable @columnfractions .80
2285 @item @code{RESULT = BESSEL_JN(N, X)}
2286 @item @code{RESULT = BESSEL_JN(N1, N2, X)}
2289 @item @emph{Arguments}:
2290 @multitable @columnfractions .15 .70
2291 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
2292 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2293 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2294 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2295 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
2298 @item @emph{Return value}:
2299 The return value is a scalar of type @code{REAL}. It has the same
2303 The transformational function uses a recurrence algorithm which might,
2304 for some values of @var{X}, lead to different results than calls to
2305 the elemental function.
2307 @item @emph{Example}:
2310 real(8) :: x = 1.0_8
2312 end program test_besjn
2315 @item @emph{Specific names}:
2316 @multitable @columnfractions .20 .20 .20 .25
2317 @item Name @tab Argument @tab Return type @tab Standard
2318 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2319 @item @tab @code{REAL(8) X} @tab @tab
2326 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
2330 @cindex Bessel function, second kind
2333 @item @emph{Description}:
2334 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
2335 order 0 of @var{X}. This function is available under the name
2336 @code{BESY0} as a GNU extension.
2338 @item @emph{Standard}:
2339 Fortran 2008 and later
2344 @item @emph{Syntax}:
2345 @code{RESULT = BESSEL_Y0(X)}
2347 @item @emph{Arguments}:
2348 @multitable @columnfractions .15 .70
2349 @item @var{X} @tab The type shall be @code{REAL}.
2352 @item @emph{Return value}:
2353 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2355 @item @emph{Example}:
2358 real(8) :: x = 0.0_8
2360 end program test_besy0
2363 @item @emph{Specific names}:
2364 @multitable @columnfractions .20 .20 .20 .25
2365 @item Name @tab Argument @tab Return type @tab Standard
2366 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2373 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
2377 @cindex Bessel function, second kind
2380 @item @emph{Description}:
2381 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
2382 order 1 of @var{X}. This function is available under the name
2383 @code{BESY1} as a GNU extension.
2385 @item @emph{Standard}:
2386 Fortran 2008 and later
2391 @item @emph{Syntax}:
2392 @code{RESULT = BESSEL_Y1(X)}
2394 @item @emph{Arguments}:
2395 @multitable @columnfractions .15 .70
2396 @item @var{X} @tab The type shall be @code{REAL}.
2399 @item @emph{Return value}:
2400 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2402 @item @emph{Example}:
2405 real(8) :: x = 1.0_8
2407 end program test_besy1
2410 @item @emph{Specific names}:
2411 @multitable @columnfractions .20 .20 .20 .25
2412 @item Name @tab Argument @tab Return type @tab Standard
2413 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2420 @section @code{BESSEL_YN} --- Bessel function of the second kind
2424 @cindex Bessel function, second kind
2427 @item @emph{Description}:
2428 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
2429 order @var{N} of @var{X}. This function is available under the name
2430 @code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays,
2431 their ranks and shapes shall conform.
2433 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
2434 of the first kind of the orders @var{N1} to @var{N2}.
2436 @item @emph{Standard}:
2437 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2440 Elemental function, except for the transformational function
2441 @code{BESSEL_YN(N1, N2, X)}
2443 @item @emph{Syntax}:
2444 @multitable @columnfractions .80
2445 @item @code{RESULT = BESSEL_YN(N, X)}
2446 @item @code{RESULT = BESSEL_YN(N1, N2, X)}
2449 @item @emph{Arguments}:
2450 @multitable @columnfractions .15 .70
2451 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} .
2452 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2453 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2454 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2455 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
2458 @item @emph{Return value}:
2459 The return value is a scalar of type @code{REAL}. It has the same
2463 The transformational function uses a recurrence algorithm which might,
2464 for some values of @var{X}, lead to different results than calls to
2465 the elemental function.
2467 @item @emph{Example}:
2470 real(8) :: x = 1.0_8
2472 end program test_besyn
2475 @item @emph{Specific names}:
2476 @multitable @columnfractions .20 .20 .20 .25
2477 @item Name @tab Argument @tab Return type @tab Standard
2478 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2479 @item @tab @code{REAL(8) X} @tab @tab
2486 @section @code{BGE} --- Bitwise greater than or equal to
2488 @cindex bitwise comparison
2491 @item @emph{Description}:
2492 Determines whether an integral is a bitwise greater than or equal to
2495 @item @emph{Standard}:
2496 Fortran 2008 and later
2501 @item @emph{Syntax}:
2502 @code{RESULT = BGE(I, J)}
2504 @item @emph{Arguments}:
2505 @multitable @columnfractions .15 .70
2506 @item @var{I} @tab Shall be of @code{INTEGER} type.
2507 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2511 @item @emph{Return value}:
2512 The return value is of type @code{LOGICAL} and of the default kind.
2514 @item @emph{See also}:
2515 @ref{BGT}, @ref{BLE}, @ref{BLT}
2521 @section @code{BGT} --- Bitwise greater than
2523 @cindex bitwise comparison
2526 @item @emph{Description}:
2527 Determines whether an integral is a bitwise greater than another.
2529 @item @emph{Standard}:
2530 Fortran 2008 and later
2535 @item @emph{Syntax}:
2536 @code{RESULT = BGT(I, J)}
2538 @item @emph{Arguments}:
2539 @multitable @columnfractions .15 .70
2540 @item @var{I} @tab Shall be of @code{INTEGER} type.
2541 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2545 @item @emph{Return value}:
2546 The return value is of type @code{LOGICAL} and of the default kind.
2548 @item @emph{See also}:
2549 @ref{BGE}, @ref{BLE}, @ref{BLT}
2555 @section @code{BIT_SIZE} --- Bit size inquiry function
2557 @cindex bits, number of
2558 @cindex size of a variable, in bits
2561 @item @emph{Description}:
2562 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
2563 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
2564 independent of the actual value of @var{I}.
2566 @item @emph{Standard}:
2567 Fortran 95 and later
2572 @item @emph{Syntax}:
2573 @code{RESULT = BIT_SIZE(I)}
2575 @item @emph{Arguments}:
2576 @multitable @columnfractions .15 .70
2577 @item @var{I} @tab The type shall be @code{INTEGER}.
2580 @item @emph{Return value}:
2581 The return value is of type @code{INTEGER}
2583 @item @emph{Example}:
2585 program test_bit_size
2590 end program test_bit_size
2597 @section @code{BLE} --- Bitwise less than or equal to
2599 @cindex bitwise comparison
2602 @item @emph{Description}:
2603 Determines whether an integral is a bitwise less than or equal to
2606 @item @emph{Standard}:
2607 Fortran 2008 and later
2612 @item @emph{Syntax}:
2613 @code{RESULT = BLE(I, J)}
2615 @item @emph{Arguments}:
2616 @multitable @columnfractions .15 .70
2617 @item @var{I} @tab Shall be of @code{INTEGER} type.
2618 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2622 @item @emph{Return value}:
2623 The return value is of type @code{LOGICAL} and of the default kind.
2625 @item @emph{See also}:
2626 @ref{BGT}, @ref{BGE}, @ref{BLT}
2632 @section @code{BLT} --- Bitwise less than
2634 @cindex bitwise comparison
2637 @item @emph{Description}:
2638 Determines whether an integral is a bitwise less than another.
2640 @item @emph{Standard}:
2641 Fortran 2008 and later
2646 @item @emph{Syntax}:
2647 @code{RESULT = BLT(I, J)}
2649 @item @emph{Arguments}:
2650 @multitable @columnfractions .15 .70
2651 @item @var{I} @tab Shall be of @code{INTEGER} type.
2652 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2656 @item @emph{Return value}:
2657 The return value is of type @code{LOGICAL} and of the default kind.
2659 @item @emph{See also}:
2660 @ref{BGE}, @ref{BGT}, @ref{BLE}
2666 @section @code{BTEST} --- Bit test function
2668 @cindex bits, testing
2671 @item @emph{Description}:
2672 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
2673 in @var{I} is set. The counting of the bits starts at 0.
2675 @item @emph{Standard}:
2676 Fortran 95 and later
2681 @item @emph{Syntax}:
2682 @code{RESULT = BTEST(I, POS)}
2684 @item @emph{Arguments}:
2685 @multitable @columnfractions .15 .70
2686 @item @var{I} @tab The type shall be @code{INTEGER}.
2687 @item @var{POS} @tab The type shall be @code{INTEGER}.
2690 @item @emph{Return value}:
2691 The return value is of type @code{LOGICAL}
2693 @item @emph{Example}:
2696 integer :: i = 32768 + 1024 + 64
2700 bool = btest(i, pos)
2703 end program test_btest
2709 @section @code{C_ASSOCIATED} --- Status of a C pointer
2710 @fnindex C_ASSOCIATED
2711 @cindex association status, C pointer
2712 @cindex pointer, C association status
2715 @item @emph{Description}:
2716 @code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
2717 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
2719 @item @emph{Standard}:
2720 Fortran 2003 and later
2725 @item @emph{Syntax}:
2726 @code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
2728 @item @emph{Arguments}:
2729 @multitable @columnfractions .15 .70
2730 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
2731 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
2734 @item @emph{Return value}:
2735 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
2736 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
2737 point to different addresses.
2739 @item @emph{Example}:
2741 subroutine association_test(a,b)
2742 use iso_c_binding, only: c_associated, c_loc, c_ptr
2746 if(c_associated(b, c_loc(a))) &
2747 stop 'b and a do not point to same target'
2748 end subroutine association_test
2751 @item @emph{See also}:
2752 @ref{C_LOC}, @ref{C_FUNLOC}
2757 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2758 @fnindex C_F_POINTER
2759 @cindex pointer, convert C to Fortran
2762 @item @emph{Description}:
2763 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} assigns the target of the C pointer
2764 @var{CPTR} to the Fortran pointer @var{FPTR} and specifies its shape.
2766 @item @emph{Standard}:
2767 Fortran 2003 and later
2772 @item @emph{Syntax}:
2773 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2775 @item @emph{Arguments}:
2776 @multitable @columnfractions .15 .70
2777 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
2779 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
2781 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2782 with @code{INTENT(IN)}. It shall be present
2783 if and only if @var{fptr} is an array. The size
2784 must be equal to the rank of @var{fptr}.
2787 @item @emph{Example}:
2793 subroutine my_routine(p) bind(c,name='myC_func')
2795 type(c_ptr), intent(out) :: p
2799 real,pointer :: a(:)
2800 call my_routine(cptr)
2801 call c_f_pointer(cptr, a, [12])
2805 @item @emph{See also}:
2806 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2810 @node C_F_PROCPOINTER
2811 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
2812 @fnindex C_F_PROCPOINTER
2813 @cindex pointer, C address of pointers
2816 @item @emph{Description}:
2817 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
2818 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
2820 @item @emph{Standard}:
2821 Fortran 2003 and later
2826 @item @emph{Syntax}:
2827 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2829 @item @emph{Arguments}:
2830 @multitable @columnfractions .15 .70
2831 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
2833 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
2837 @item @emph{Example}:
2845 real(c_float), intent(in) :: a
2846 real(c_float) :: func
2850 function getIterFunc() bind(c,name="getIterFunc")
2852 type(c_funptr) :: getIterFunc
2855 type(c_funptr) :: cfunptr
2856 procedure(func), pointer :: myFunc
2857 cfunptr = getIterFunc()
2858 call c_f_procpointer(cfunptr, myFunc)
2862 @item @emph{See also}:
2863 @ref{C_LOC}, @ref{C_F_POINTER}
2868 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
2870 @cindex pointer, C address of procedures
2873 @item @emph{Description}:
2874 @code{C_FUNLOC(x)} determines the C address of the argument.
2876 @item @emph{Standard}:
2877 Fortran 2003 and later
2882 @item @emph{Syntax}:
2883 @code{RESULT = C_FUNLOC(x)}
2885 @item @emph{Arguments}:
2886 @multitable @columnfractions .15 .70
2887 @item @var{x} @tab Interoperable function or pointer to such function.
2890 @item @emph{Return value}:
2891 The return value is of type @code{C_FUNPTR} and contains the C address
2894 @item @emph{Example}:
2900 subroutine sub(a) bind(c)
2910 subroutine my_routine(p) bind(c,name='myC_func')
2912 type(c_funptr), intent(in) :: p
2915 call my_routine(c_funloc(sub))
2919 @item @emph{See also}:
2920 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2925 @section @code{C_LOC} --- Obtain the C address of an object
2927 @cindex procedure pointer, convert C to Fortran
2930 @item @emph{Description}:
2931 @code{C_LOC(X)} determines the C address of the argument.
2933 @item @emph{Standard}:
2934 Fortran 2003 and later
2939 @item @emph{Syntax}:
2940 @code{RESULT = C_LOC(X)}
2942 @item @emph{Arguments}:
2943 @multitable @columnfractions .10 .75
2944 @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.
2948 @item @emph{Return value}:
2949 The return value is of type @code{C_PTR} and contains the C address
2952 @item @emph{Example}:
2954 subroutine association_test(a,b)
2955 use iso_c_binding, only: c_associated, c_loc, c_ptr
2959 if(c_associated(b, c_loc(a))) &
2960 stop 'b and a do not point to same target'
2961 end subroutine association_test
2964 @item @emph{See also}:
2965 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2970 @section @code{C_SIZEOF} --- Size in bytes of an expression
2972 @cindex expression size
2973 @cindex size of an expression
2976 @item @emph{Description}:
2977 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
2978 expression @code{X} occupies.
2980 @item @emph{Standard}:
2984 Inquiry function of the module @code{ISO_C_BINDING}
2986 @item @emph{Syntax}:
2987 @code{N = C_SIZEOF(X)}
2989 @item @emph{Arguments}:
2990 @multitable @columnfractions .15 .70
2991 @item @var{X} @tab The argument shall be an interoperable data entity.
2994 @item @emph{Return value}:
2995 The return value is of type integer and of the system-dependent kind
2996 @code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the
2997 number of bytes occupied by the argument. If the argument has the
2998 @code{POINTER} attribute, the number of bytes of the storage area pointed
2999 to is returned. If the argument is of a derived type with @code{POINTER}
3000 or @code{ALLOCATABLE} components, the return value does not account for
3001 the sizes of the data pointed to by these components.
3003 @item @emph{Example}:
3007 real(c_float) :: r, s(5)
3008 print *, (c_sizeof(s)/c_sizeof(r) == 5)
3011 The example will print @code{.TRUE.} unless you are using a platform
3012 where default @code{REAL} variables are unusually padded.
3014 @item @emph{See also}:
3015 @ref{SIZEOF}, @ref{STORAGE_SIZE}
3020 @section @code{CEILING} --- Integer ceiling function
3023 @cindex rounding, ceiling
3026 @item @emph{Description}:
3027 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
3029 @item @emph{Standard}:
3030 Fortran 95 and later
3035 @item @emph{Syntax}:
3036 @code{RESULT = CEILING(A [, KIND])}
3038 @item @emph{Arguments}:
3039 @multitable @columnfractions .15 .70
3040 @item @var{A} @tab The type shall be @code{REAL}.
3041 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3042 expression indicating the kind parameter of the result.
3045 @item @emph{Return value}:
3046 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
3047 and a default-kind @code{INTEGER} otherwise.
3049 @item @emph{Example}:
3051 program test_ceiling
3054 print *, ceiling(x) ! returns 64
3055 print *, ceiling(y) ! returns -63
3056 end program test_ceiling
3059 @item @emph{See also}:
3060 @ref{FLOOR}, @ref{NINT}
3067 @section @code{CHAR} --- Character conversion function
3069 @cindex conversion, to character
3072 @item @emph{Description}:
3073 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
3075 @item @emph{Standard}:
3076 Fortran 77 and later
3081 @item @emph{Syntax}:
3082 @code{RESULT = CHAR(I [, KIND])}
3084 @item @emph{Arguments}:
3085 @multitable @columnfractions .15 .70
3086 @item @var{I} @tab The type shall be @code{INTEGER}.
3087 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3088 expression indicating the kind parameter of the result.
3091 @item @emph{Return value}:
3092 The return value is of type @code{CHARACTER(1)}
3094 @item @emph{Example}:
3100 print *, i, c ! returns 'J'
3101 end program test_char
3104 @item @emph{Specific names}:
3105 @multitable @columnfractions .20 .20 .20 .25
3106 @item Name @tab Argument @tab Return type @tab Standard
3107 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
3111 See @ref{ICHAR} for a discussion of converting between numerical values
3112 and formatted string representations.
3114 @item @emph{See also}:
3115 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
3122 @section @code{CHDIR} --- Change working directory
3124 @cindex system, working directory
3127 @item @emph{Description}:
3128 Change current working directory to a specified path.
3130 This intrinsic is provided in both subroutine and function forms; however,
3131 only one form can be used in any given program unit.
3133 @item @emph{Standard}:
3137 Subroutine, function
3139 @item @emph{Syntax}:
3140 @multitable @columnfractions .80
3141 @item @code{CALL CHDIR(NAME [, STATUS])}
3142 @item @code{STATUS = CHDIR(NAME)}
3145 @item @emph{Arguments}:
3146 @multitable @columnfractions .15 .70
3147 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
3148 kind and shall specify a valid path within the file system.
3149 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
3150 kind. Returns 0 on success, and a system specific and nonzero error code
3154 @item @emph{Example}:
3157 CHARACTER(len=255) :: path
3159 WRITE(*,*) TRIM(path)
3162 WRITE(*,*) TRIM(path)
3166 @item @emph{See also}:
3173 @section @code{CHMOD} --- Change access permissions of files
3175 @cindex file system, change access mode
3178 @item @emph{Description}:
3179 @code{CHMOD} changes the permissions of a file.
3181 This intrinsic is provided in both subroutine and function forms; however,
3182 only one form can be used in any given program unit.
3184 @item @emph{Standard}:
3188 Subroutine, function
3190 @item @emph{Syntax}:
3191 @multitable @columnfractions .80
3192 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
3193 @item @code{STATUS = CHMOD(NAME, MODE)}
3196 @item @emph{Arguments}:
3197 @multitable @columnfractions .15 .70
3199 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
3200 file name. Trailing blanks are ignored unless the character
3201 @code{achar(0)} is present, then all characters up to and excluding
3202 @code{achar(0)} are used as the file name.
3204 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
3205 file permission. @var{MODE} uses the same syntax as the @code{chmod} utility
3206 as defined by the POSIX standard. The argument shall either be a string of
3207 a nonnegative octal number or a symbolic mode.
3209 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
3210 @code{0} on success and nonzero otherwise.
3213 @item @emph{Return value}:
3214 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
3217 @item @emph{Example}:
3218 @code{CHMOD} as subroutine
3223 call chmod('test.dat','u+x',status)
3224 print *, 'Status: ', status
3225 end program chmod_test
3227 @code{CHMOD} as function:
3232 status = chmod('test.dat','u+x')
3233 print *, 'Status: ', status
3234 end program chmod_test
3242 @section @code{CMPLX} --- Complex conversion function
3244 @cindex complex numbers, conversion to
3245 @cindex conversion, to complex
3248 @item @emph{Description}:
3249 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
3250 the real component. If @var{Y} is present it is converted to the imaginary
3251 component. If @var{Y} is not present then the imaginary component is set to
3252 0.0. If @var{X} is complex then @var{Y} must not be present.
3254 @item @emph{Standard}:
3255 Fortran 77 and later
3260 @item @emph{Syntax}:
3261 @code{RESULT = CMPLX(X [, Y [, KIND]])}
3263 @item @emph{Arguments}:
3264 @multitable @columnfractions .15 .70
3265 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3267 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
3268 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
3269 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3270 expression indicating the kind parameter of the result.
3273 @item @emph{Return value}:
3274 The return value is of @code{COMPLEX} type, with a kind equal to
3275 @var{KIND} if it is specified. If @var{KIND} is not specified, the
3276 result is of the default @code{COMPLEX} kind, regardless of the kinds of
3277 @var{X} and @var{Y}.
3279 @item @emph{Example}:
3286 print *, z, cmplx(x)
3287 end program test_cmplx
3290 @item @emph{See also}:
3297 @section @code{CO_BROADCAST} --- Copy a value to all images the current set of images
3298 @fnindex CO_BROADCAST
3299 @cindex Collectives, value broadcasting
3302 @item @emph{Description}:
3303 @code{CO_BROADCAST} copies the value of argument @var{A} on the image with
3304 image index @code{SOURCE_IMAGE} to all images in the current team. @var{A}
3305 becomes defined as if by intrinsic assignment. If the execution was
3306 successful and @var{STAT} is present, it is assigned the value zero. If the
3307 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3308 @var{ERRMSG} gets assigned a value describing the occurred error.
3310 @item @emph{Standard}:
3311 Technical Specification (TS) 18508 or later
3314 Collective subroutine
3316 @item @emph{Syntax}:
3317 @code{CALL CO_BROADCAST(A, SOURCE_IMAGE [, STAT, ERRMSG])}
3319 @item @emph{Arguments}:
3320 @multitable @columnfractions .15 .70
3321 @item @var{A} @tab INTENT(INOUT) argument; shall have the same
3322 dynamic type and type paramters on all images of the current team. If it
3323 is an array, it shall have the same shape on all images.
3324 @item @var{SOURCE_IMAGE} @tab (optional) a scalar integer expression.
3325 It shall have the same the same value on all images and refer to an
3326 image of the current team.
3327 @item @var{STAT} @tab (optional) a scalar integer variable
3328 @item @var{ERRMSG} @tab (optional) a scalar character variable
3331 @item @emph{Example}:
3335 if (this_image() == 1) then
3338 call co_broadcast (val, source_image=1)
3339 print *, this_image, ":", val
3343 @item @emph{See also}:
3344 @ref{CO_MAX}, @ref{CO_MIN}, @ref{CO_SUM}, @ref{CO_REDUCE}
3350 @section @code{CO_MAX} --- Maximal value on the current set of images
3352 @cindex Collectives, maximal value
3355 @item @emph{Description}:
3356 @code{CO_MAX} determines element-wise the maximal value of @var{A} on all
3357 images of the current team. If @var{RESULT_IMAGE} is present, the maximum
3358 values are returned in @var{A} on the specified image only and the value
3359 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3360 not present, the value is returned on all images. If the execution was
3361 successful and @var{STAT} is present, it is assigned the value zero. If the
3362 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3363 @var{ERRMSG} gets assigned a value describing the occurred error.
3365 @item @emph{Standard}:
3366 Technical Specification (TS) 18508 or later
3369 Collective subroutine
3371 @item @emph{Syntax}:
3372 @code{CALL CO_MAX(A [, RESULT_IMAGE, STAT, ERRMSG])}
3374 @item @emph{Arguments}:
3375 @multitable @columnfractions .15 .70
3376 @item @var{A} @tab shall be an integer, real or character variable,
3377 which has the same type and type parameters on all images of the team.
3378 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3379 present, it shall have the same the same value on all images and refer to an
3380 image of the current team.
3381 @item @var{STAT} @tab (optional) a scalar integer variable
3382 @item @var{ERRMSG} @tab (optional) a scalar character variable
3385 @item @emph{Example}:
3390 call co_max (val, result_image=1)
3391 if (this_image() == 1) then
3392 write(*,*) "Maximal value", val ! prints num_images()
3397 @item @emph{See also}:
3398 @ref{CO_MIN}, @ref{CO_SUM}, @ref{CO_REDUCE}, @ref{CO_BROADCAST}
3404 @section @code{CO_MIN} --- Minimal value on the current set of images
3406 @cindex Collectives, minimal value
3409 @item @emph{Description}:
3410 @code{CO_MIN} determines element-wise the minimal value of @var{A} on all
3411 images of the current team. If @var{RESULT_IMAGE} is present, the minimal
3412 values are returned in @var{A} on the specified image only and the value
3413 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3414 not present, the value is returned on all images. If the execution was
3415 successful and @var{STAT} is present, it is assigned the value zero. If the
3416 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3417 @var{ERRMSG} gets assigned a value describing the occurred error.
3419 @item @emph{Standard}:
3420 Technical Specification (TS) 18508 or later
3423 Collective subroutine
3425 @item @emph{Syntax}:
3426 @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3428 @item @emph{Arguments}:
3429 @multitable @columnfractions .15 .70
3430 @item @var{A} @tab shall be an integer, real or character variable,
3431 which has the same type and type parameters on all images of the team.
3432 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3433 present, it shall have the same the same value on all images and refer to an
3434 image of the current team.
3435 @item @var{STAT} @tab (optional) a scalar integer variable
3436 @item @var{ERRMSG} @tab (optional) a scalar character variable
3439 @item @emph{Example}:
3444 call co_min (val, result_image=1)
3445 if (this_image() == 1) then
3446 write(*,*) "Minimal value", val ! prints 1
3451 @item @emph{See also}:
3452 @ref{CO_MAX}, @ref{CO_SUM}, @ref{CO_REDUCE}, @ref{CO_BROADCAST}
3458 @section @code{CO_REDUCE} --- Reduction of values on the current set of images
3460 @cindex Collectives, generic reduction
3463 @item @emph{Description}:
3464 @code{CO_REDUCE} determines element-wise the reduction of the value of @var{A}
3465 on all images of the current team. The pure function passed as @var{OPERATOR}
3466 is used to pairwise reduce the values of @var{A} by passing either the value
3467 of @var{A} of different images or the result values of such a reduction as
3468 argument. If @var{A} is an array, the deduction is done element wise. If
3469 @var{RESULT_IMAGE} is present, the result values are returned in @var{A} on
3470 the specified image only and the value of @var{A} on the other images become
3471 undefined. If @var{RESULT_IMAGE} is not present, the value is returned on all
3472 images. If the execution was successful and @var{STAT} is present, it is
3473 assigned the value zero. If the execution failed, @var{STAT} gets assigned
3474 a nonzero value and, if present, @var{ERRMSG} gets assigned a value describing
3477 @item @emph{Standard}:
3478 Technical Specification (TS) 18508 or later
3481 Collective subroutine
3483 @item @emph{Syntax}:
3484 @code{CALL CO_REDUCE(A, OPERATOR, [, RESULT_IMAGE, STAT, ERRMSG])}
3486 @item @emph{Arguments}:
3487 @multitable @columnfractions .15 .70
3488 @item @var{A} @tab is an @code{INTENT(INOUT)} argument and shall be
3489 nonpolymorphic. If it is allocatable, it shall be allocated; if it is a pointer,
3490 it shall be associated. @var{A} shall have the same type and type parameters on
3491 all images of the team; if it is an array, it shall have the same shape on all
3493 @item @var{OPERATOR} @tab pure function with two scalar nonallocatable
3494 arguments, which shall be nonpolymorphic and have the same type and type
3495 parameters as @var{A}. The function shall return a nonallocatable scalar of
3496 the same type and type parameters as @var{A}. The function shall be the same on
3497 all images and with regards to the arguments mathematically commutative and
3498 associative. Note that @var{OPERATOR} may not be an elemental function, unless
3499 it is an intrisic function.
3500 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3501 present, it shall have the same the same value on all images and refer to an
3502 image of the current team.
3503 @item @var{STAT} @tab (optional) a scalar integer variable
3504 @item @var{ERRMSG} @tab (optional) a scalar character variable
3507 @item @emph{Example}:
3512 call co_reduce (val, result_image=1, operator=myprod)
3513 if (this_image() == 1) then
3514 write(*,*) "Product value", val ! prints num_images() factorial
3517 pure function myprod(a, b)
3518 integer, value :: a, b
3526 While the rules permit in principle an intrinsic function, none of the
3527 intrinsics in the standard fulfill the criteria of having a specific
3528 function, which takes two arguments of the same type and returning that
3531 @item @emph{See also}:
3532 @ref{CO_MIN}, @ref{CO_MAX}, @ref{CO_SUM}, @ref{CO_BROADCAST}
3538 @section @code{CO_SUM} --- Sum of values on the current set of images
3540 @cindex Collectives, sum of values
3543 @item @emph{Description}:
3544 @code{CO_SUM} sums up the values of each element of @var{A} on all
3545 images of the current team. If @var{RESULT_IMAGE} is present, the summed-up
3546 values are returned in @var{A} on the specified image only and the value
3547 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3548 not present, the value is returned on all images. If the execution was
3549 successful and @var{STAT} is present, it is assigned the value zero. If the
3550 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3551 @var{ERRMSG} gets assigned a value describing the occurred error.
3553 @item @emph{Standard}:
3554 Technical Specification (TS) 18508 or later
3557 Collective subroutine
3559 @item @emph{Syntax}:
3560 @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3562 @item @emph{Arguments}:
3563 @multitable @columnfractions .15 .70
3564 @item @var{A} @tab shall be an integer, real or complex variable,
3565 which has the same type and type parameters on all images of the team.
3566 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3567 present, it shall have the same the same value on all images and refer to an
3568 image of the current team.
3569 @item @var{STAT} @tab (optional) a scalar integer variable
3570 @item @var{ERRMSG} @tab (optional) a scalar character variable
3573 @item @emph{Example}:
3578 call co_sum (val, result_image=1)
3579 if (this_image() == 1) then
3580 write(*,*) "The sum is ", val ! prints (n**2 + n)/2, with n = num_images()
3585 @item @emph{See also}:
3586 @ref{CO_MAX}, @ref{CO_MIN}, @ref{CO_REDUCE}, @ref{CO_BROADCAST}
3591 @node COMMAND_ARGUMENT_COUNT
3592 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
3593 @fnindex COMMAND_ARGUMENT_COUNT
3594 @cindex command-line arguments
3595 @cindex command-line arguments, number of
3596 @cindex arguments, to program
3599 @item @emph{Description}:
3600 @code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the
3601 command line when the containing program was invoked.
3603 @item @emph{Standard}:
3604 Fortran 2003 and later
3609 @item @emph{Syntax}:
3610 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
3612 @item @emph{Arguments}:
3613 @multitable @columnfractions .15 .70
3617 @item @emph{Return value}:
3618 The return value is an @code{INTEGER} of default kind.
3620 @item @emph{Example}:
3622 program test_command_argument_count
3624 count = command_argument_count()
3626 end program test_command_argument_count
3629 @item @emph{See also}:
3630 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
3635 @node COMPILER_OPTIONS
3636 @section @code{COMPILER_OPTIONS} --- Options passed to the compiler
3637 @fnindex COMPILER_OPTIONS
3638 @cindex flags inquiry function
3639 @cindex options inquiry function
3640 @cindex compiler flags inquiry function
3643 @item @emph{Description}:
3644 @code{COMPILER_OPTIONS} returns a string with the options used for
3647 @item @emph{Standard}:
3651 Inquiry function of the module @code{ISO_FORTRAN_ENV}
3653 @item @emph{Syntax}:
3654 @code{STR = COMPILER_OPTIONS()}
3656 @item @emph{Arguments}:
3659 @item @emph{Return value}:
3660 The return value is a default-kind string with system-dependent length.
3661 It contains the compiler flags used to compile the file, which called
3662 the @code{COMPILER_OPTIONS} intrinsic.
3664 @item @emph{Example}:
3667 print '(4a)', 'This file was compiled by ', &
3668 compiler_version(), ' using the options ', &
3673 @item @emph{See also}:
3674 @ref{COMPILER_VERSION}, @ref{ISO_FORTRAN_ENV}
3679 @node COMPILER_VERSION
3680 @section @code{COMPILER_VERSION} --- Compiler version string
3681 @fnindex COMPILER_VERSION
3682 @cindex compiler, name and version
3683 @cindex version of the compiler
3686 @item @emph{Description}:
3687 @code{COMPILER_VERSION} returns a string with the name and the
3688 version of the compiler.
3690 @item @emph{Standard}:
3694 Inquiry function of the module @code{ISO_FORTRAN_ENV}
3696 @item @emph{Syntax}:
3697 @code{STR = COMPILER_VERSION()}
3699 @item @emph{Arguments}:
3702 @item @emph{Return value}:
3703 The return value is a default-kind string with system-dependent length.
3704 It contains the name of the compiler and its version number.
3706 @item @emph{Example}:
3709 print '(4a)', 'This file was compiled by ', &
3710 compiler_version(), ' using the options ', &
3715 @item @emph{See also}:
3716 @ref{COMPILER_OPTIONS}, @ref{ISO_FORTRAN_ENV}
3722 @section @code{COMPLEX} --- Complex conversion function
3724 @cindex complex numbers, conversion to
3725 @cindex conversion, to complex
3728 @item @emph{Description}:
3729 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
3730 to the real component and @var{Y} is converted to the imaginary
3733 @item @emph{Standard}:
3739 @item @emph{Syntax}:
3740 @code{RESULT = COMPLEX(X, Y)}
3742 @item @emph{Arguments}:
3743 @multitable @columnfractions .15 .70
3744 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3745 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
3748 @item @emph{Return value}:
3749 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
3750 value is of default @code{COMPLEX} type.
3752 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
3753 type and one is of @code{INTEGER} type, then the return value is of
3754 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
3755 argument with the highest precision.
3757 @item @emph{Example}:
3759 program test_complex
3762 print *, complex(i, x)
3763 end program test_complex
3766 @item @emph{See also}:
3773 @section @code{CONJG} --- Complex conjugate function
3776 @cindex complex conjugate
3779 @item @emph{Description}:
3780 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
3781 then the result is @code{(x, -y)}
3783 @item @emph{Standard}:
3784 Fortran 77 and later, has overloads that are GNU extensions
3789 @item @emph{Syntax}:
3792 @item @emph{Arguments}:
3793 @multitable @columnfractions .15 .70
3794 @item @var{Z} @tab The type shall be @code{COMPLEX}.
3797 @item @emph{Return value}:
3798 The return value is of type @code{COMPLEX}.
3800 @item @emph{Example}:
3803 complex :: z = (2.0, 3.0)
3804 complex(8) :: dz = (2.71_8, -3.14_8)
3809 end program test_conjg
3812 @item @emph{Specific names}:
3813 @multitable @columnfractions .20 .20 .20 .25
3814 @item Name @tab Argument @tab Return type @tab Standard
3815 @item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension
3816 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
3823 @section @code{COS} --- Cosine function
3829 @cindex trigonometric function, cosine
3833 @item @emph{Description}:
3834 @code{COS(X)} computes the cosine of @var{X}.
3836 @item @emph{Standard}:
3837 Fortran 77 and later, has overloads that are GNU extensions
3842 @item @emph{Syntax}:
3843 @code{RESULT = COS(X)}
3845 @item @emph{Arguments}:
3846 @multitable @columnfractions .15 .70
3847 @item @var{X} @tab The type shall be @code{REAL} or
3851 @item @emph{Return value}:
3852 The return value is of the same type and kind as @var{X}. The real part
3853 of the result is in radians. If @var{X} is of the type @code{REAL},
3854 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
3856 @item @emph{Example}:
3861 end program test_cos
3864 @item @emph{Specific names}:
3865 @multitable @columnfractions .20 .20 .20 .25
3866 @item Name @tab Argument @tab Return type @tab Standard
3867 @item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
3868 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3869 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
3870 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3871 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3874 @item @emph{See also}:
3875 Inverse function: @ref{ACOS}
3882 @section @code{COSH} --- Hyperbolic cosine function
3885 @cindex hyperbolic cosine
3886 @cindex hyperbolic function, cosine
3887 @cindex cosine, hyperbolic
3890 @item @emph{Description}:
3891 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
3893 @item @emph{Standard}:
3894 Fortran 77 and later, for a complex argument Fortran 2008 or later
3899 @item @emph{Syntax}:
3902 @item @emph{Arguments}:
3903 @multitable @columnfractions .15 .70
3904 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
3907 @item @emph{Return value}:
3908 The return value has same type and kind as @var{X}. If @var{X} is
3909 complex, the imaginary part of the result is in radians. If @var{X}
3910 is @code{REAL}, the return value has a lower bound of one,
3911 @math{\cosh (x) \geq 1}.
3913 @item @emph{Example}:
3916 real(8) :: x = 1.0_8
3918 end program test_cosh
3921 @item @emph{Specific names}:
3922 @multitable @columnfractions .20 .20 .20 .25
3923 @item Name @tab Argument @tab Return type @tab Standard
3924 @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
3925 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3928 @item @emph{See also}:
3929 Inverse function: @ref{ACOSH}
3936 @section @code{COUNT} --- Count function
3938 @cindex array, conditionally count elements
3939 @cindex array, element counting
3940 @cindex array, number of elements
3943 @item @emph{Description}:
3945 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
3946 or, if the @var{DIM} argument is supplied, counts the number of
3947 elements along each row of the array in the @var{DIM} direction.
3948 If the array has zero size, or all of the elements of @var{MASK} are
3949 @code{.FALSE.}, then the result is @code{0}.
3951 @item @emph{Standard}:
3952 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
3955 Transformational function
3957 @item @emph{Syntax}:
3958 @code{RESULT = COUNT(MASK [, DIM, KIND])}
3960 @item @emph{Arguments}:
3961 @multitable @columnfractions .15 .70
3962 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
3963 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
3964 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3965 expression indicating the kind parameter of the result.
3968 @item @emph{Return value}:
3969 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
3970 @var{KIND} is absent, the return value is of default integer kind.
3971 If @var{DIM} is present, the result is an array with a rank one less
3972 than the rank of @var{ARRAY}, and a size corresponding to the shape
3973 of @var{ARRAY} with the @var{DIM} dimension removed.
3975 @item @emph{Example}:
3978 integer, dimension(2,3) :: a, b
3979 logical, dimension(2,3) :: mask
3980 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
3981 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
3982 print '(3i3)', a(1,:)
3983 print '(3i3)', a(2,:)
3985 print '(3i3)', b(1,:)
3986 print '(3i3)', b(2,:)
3989 print '(3l3)', mask(1,:)
3990 print '(3l3)', mask(2,:)
3992 print '(3i3)', count(mask)
3994 print '(3i3)', count(mask, 1)
3996 print '(3i3)', count(mask, 2)
3997 end program test_count
4004 @section @code{CPU_TIME} --- CPU elapsed time in seconds
4006 @cindex time, elapsed
4009 @item @emph{Description}:
4010 Returns a @code{REAL} value representing the elapsed CPU time in
4011 seconds. This is useful for testing segments of code to determine
4014 If a time source is available, time will be reported with microsecond
4015 resolution. If no time source is available, @var{TIME} is set to
4018 Note that @var{TIME} may contain a, system dependent, arbitrary offset
4019 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
4020 value is meaningless, only differences between subsequent calls to
4021 this subroutine, as shown in the example below, should be used.
4024 @item @emph{Standard}:
4025 Fortran 95 and later
4030 @item @emph{Syntax}:
4031 @code{CALL CPU_TIME(TIME)}
4033 @item @emph{Arguments}:
4034 @multitable @columnfractions .15 .70
4035 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
4038 @item @emph{Return value}:
4041 @item @emph{Example}:
4043 program test_cpu_time
4044 real :: start, finish
4045 call cpu_time(start)
4046 ! put code to test here
4047 call cpu_time(finish)
4048 print '("Time = ",f6.3," seconds.")',finish-start
4049 end program test_cpu_time
4052 @item @emph{See also}:
4053 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
4059 @section @code{CSHIFT} --- Circular shift elements of an array
4061 @cindex array, shift circularly
4062 @cindex array, permutation
4063 @cindex array, rotate
4066 @item @emph{Description}:
4067 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
4068 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
4069 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
4070 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
4071 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
4072 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
4073 sections of @var{ARRAY} along the given dimension are shifted. Elements
4074 shifted out one end of each rank one section are shifted back in the other end.
4076 @item @emph{Standard}:
4077 Fortran 95 and later
4080 Transformational function
4082 @item @emph{Syntax}:
4083 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
4085 @item @emph{Arguments}:
4086 @multitable @columnfractions .15 .70
4087 @item @var{ARRAY} @tab Shall be an array of any type.
4088 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
4089 @item @var{DIM} @tab The type shall be @code{INTEGER}.
4092 @item @emph{Return value}:
4093 Returns an array of same type and rank as the @var{ARRAY} argument.
4095 @item @emph{Example}:
4098 integer, dimension(3,3) :: a
4099 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
4100 print '(3i3)', a(1,:)
4101 print '(3i3)', a(2,:)
4102 print '(3i3)', a(3,:)
4103 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
4105 print '(3i3)', a(1,:)
4106 print '(3i3)', a(2,:)
4107 print '(3i3)', a(3,:)
4108 end program test_cshift
4115 @section @code{CTIME} --- Convert a time into a string
4117 @cindex time, conversion to string
4118 @cindex conversion, to string
4121 @item @emph{Description}:
4122 @code{CTIME} converts a system time value, such as returned by
4123 @code{TIME8}, to a string. The output will be of the form @samp{Sat
4124 Aug 19 18:13:14 1995}.
4126 This intrinsic is provided in both subroutine and function forms; however,
4127 only one form can be used in any given program unit.
4129 @item @emph{Standard}:
4133 Subroutine, function
4135 @item @emph{Syntax}:
4136 @multitable @columnfractions .80
4137 @item @code{CALL CTIME(TIME, RESULT)}.
4138 @item @code{RESULT = CTIME(TIME)}.
4141 @item @emph{Arguments}:
4142 @multitable @columnfractions .15 .70
4143 @item @var{TIME} @tab The type shall be of type @code{INTEGER}.
4144 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
4145 of default kind. It is an @code{INTENT(OUT)} argument. If the length
4146 of this variable is too short for the time and date string to fit
4147 completely, it will be blank on procedure return.
4150 @item @emph{Return value}:
4151 The converted date and time as a string.
4153 @item @emph{Example}:
4157 character(len=30) :: date
4160 ! Do something, main part of the program
4163 print *, 'Program was started on ', date
4164 end program test_ctime
4167 @item @emph{See Also}:
4168 @ref{DATE_AND_TIME}, @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
4174 @section @code{DATE_AND_TIME} --- Date and time subroutine
4175 @fnindex DATE_AND_TIME
4176 @cindex date, current
4177 @cindex current date
4178 @cindex time, current
4179 @cindex current time
4182 @item @emph{Description}:
4183 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
4184 time information from the real-time system clock. @var{DATE} is
4185 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
4186 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
4187 representing the difference with respect to Coordinated Universal Time (UTC).
4188 Unavailable time and date parameters return blanks.
4190 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
4192 @multitable @columnfractions .15 .30 .40
4193 @item @tab @code{VALUE(1)}: @tab The year
4194 @item @tab @code{VALUE(2)}: @tab The month
4195 @item @tab @code{VALUE(3)}: @tab The day of the month
4196 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
4197 @item @tab @code{VALUE(5)}: @tab The hour of the day
4198 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
4199 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
4200 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
4203 @item @emph{Standard}:
4204 Fortran 95 and later
4209 @item @emph{Syntax}:
4210 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
4212 @item @emph{Arguments}:
4213 @multitable @columnfractions .15 .70
4214 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
4215 or larger, and of default kind.
4216 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
4217 or larger, and of default kind.
4218 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
4219 or larger, and of default kind.
4220 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
4223 @item @emph{Return value}:
4226 @item @emph{Example}:
4228 program test_time_and_date
4229 character(8) :: date
4230 character(10) :: time
4231 character(5) :: zone
4232 integer,dimension(8) :: values
4233 ! using keyword arguments
4234 call date_and_time(date,time,zone,values)
4235 call date_and_time(DATE=date,ZONE=zone)
4236 call date_and_time(TIME=time)
4237 call date_and_time(VALUES=values)
4238 print '(a,2x,a,2x,a)', date, time, zone
4239 print '(8i5)', values
4240 end program test_time_and_date
4243 @item @emph{See also}:
4244 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
4250 @section @code{DBLE} --- Double conversion function
4252 @cindex conversion, to real
4255 @item @emph{Description}:
4256 @code{DBLE(A)} Converts @var{A} to double precision real type.
4258 @item @emph{Standard}:
4259 Fortran 77 and later
4264 @item @emph{Syntax}:
4265 @code{RESULT = DBLE(A)}
4267 @item @emph{Arguments}:
4268 @multitable @columnfractions .15 .70
4269 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
4273 @item @emph{Return value}:
4274 The return value is of type double precision real.
4276 @item @emph{Example}:
4281 complex :: z = (2.3,1.14)
4282 print *, dble(x), dble(i), dble(z)
4283 end program test_dble
4286 @item @emph{See also}:
4293 @section @code{DCMPLX} --- Double complex conversion function
4295 @cindex complex numbers, conversion to
4296 @cindex conversion, to complex
4299 @item @emph{Description}:
4300 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
4301 converted to the real component. If @var{Y} is present it is converted to the
4302 imaginary component. If @var{Y} is not present then the imaginary component is
4303 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
4305 @item @emph{Standard}:
4311 @item @emph{Syntax}:
4312 @code{RESULT = DCMPLX(X [, Y])}
4314 @item @emph{Arguments}:
4315 @multitable @columnfractions .15 .70
4316 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
4318 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
4319 @code{INTEGER} or @code{REAL}.
4322 @item @emph{Return value}:
4323 The return value is of type @code{COMPLEX(8)}
4325 @item @emph{Example}:
4335 print *, dcmplx(x,i)
4336 end program test_dcmplx
4342 @section @code{DIGITS} --- Significant binary digits function
4344 @cindex model representation, significant digits
4347 @item @emph{Description}:
4348 @code{DIGITS(X)} returns the number of significant binary digits of the internal
4349 model representation of @var{X}. For example, on a system using a 32-bit
4350 floating point representation, a default real number would likely return 24.
4352 @item @emph{Standard}:
4353 Fortran 95 and later
4358 @item @emph{Syntax}:
4359 @code{RESULT = DIGITS(X)}
4361 @item @emph{Arguments}:
4362 @multitable @columnfractions .15 .70
4363 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
4366 @item @emph{Return value}:
4367 The return value is of type @code{INTEGER}.
4369 @item @emph{Example}:
4372 integer :: i = 12345
4378 end program test_digits
4385 @section @code{DIM} --- Positive difference
4389 @cindex positive difference
4392 @item @emph{Description}:
4393 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
4394 otherwise returns zero.
4396 @item @emph{Standard}:
4397 Fortran 77 and later
4402 @item @emph{Syntax}:
4403 @code{RESULT = DIM(X, Y)}
4405 @item @emph{Arguments}:
4406 @multitable @columnfractions .15 .70
4407 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
4408 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
4411 @item @emph{Return value}:
4412 The return value is of type @code{INTEGER} or @code{REAL}.
4414 @item @emph{Example}:
4420 x = dim(4.345_8, 2.111_8)
4423 end program test_dim
4426 @item @emph{Specific names}:
4427 @multitable @columnfractions .20 .20 .20 .25
4428 @item Name @tab Argument @tab Return type @tab Standard
4429 @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
4430 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
4431 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
4438 @section @code{DOT_PRODUCT} --- Dot product function
4439 @fnindex DOT_PRODUCT
4441 @cindex vector product
4442 @cindex product, vector
4445 @item @emph{Description}:
4446 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
4447 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
4448 either numeric or logical and must be arrays of rank one and of equal size. If
4449 the vectors are @code{INTEGER} or @code{REAL}, the result is
4450 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
4451 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
4452 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
4454 @item @emph{Standard}:
4455 Fortran 95 and later
4458 Transformational function
4460 @item @emph{Syntax}:
4461 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
4463 @item @emph{Arguments}:
4464 @multitable @columnfractions .15 .70
4465 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
4466 @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.
4469 @item @emph{Return value}:
4470 If the arguments are numeric, the return value is a scalar of numeric type,
4471 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
4472 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
4474 @item @emph{Example}:
4476 program test_dot_prod
4477 integer, dimension(3) :: a, b
4484 print *, dot_product(a,b)
4485 end program test_dot_prod
4492 @section @code{DPROD} --- Double product function
4494 @cindex product, double-precision
4497 @item @emph{Description}:
4498 @code{DPROD(X,Y)} returns the product @code{X*Y}.
4500 @item @emph{Standard}:
4501 Fortran 77 and later
4506 @item @emph{Syntax}:
4507 @code{RESULT = DPROD(X, Y)}
4509 @item @emph{Arguments}:
4510 @multitable @columnfractions .15 .70
4511 @item @var{X} @tab The type shall be @code{REAL}.
4512 @item @var{Y} @tab The type shall be @code{REAL}.
4515 @item @emph{Return value}:
4516 The return value is of type @code{REAL(8)}.
4518 @item @emph{Example}:
4526 end program test_dprod
4529 @item @emph{Specific names}:
4530 @multitable @columnfractions .20 .20 .20 .25
4531 @item Name @tab Argument @tab Return type @tab Standard
4532 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
4539 @section @code{DREAL} --- Double real part function
4541 @cindex complex numbers, real part
4544 @item @emph{Description}:
4545 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
4547 @item @emph{Standard}:
4553 @item @emph{Syntax}:
4554 @code{RESULT = DREAL(A)}
4556 @item @emph{Arguments}:
4557 @multitable @columnfractions .15 .70
4558 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
4561 @item @emph{Return value}:
4562 The return value is of type @code{REAL(8)}.
4564 @item @emph{Example}:
4567 complex(8) :: z = (1.3_8,7.2_8)
4569 end program test_dreal
4572 @item @emph{See also}:
4580 @section @code{DSHIFTL} --- Combined left shift
4582 @cindex left shift, combined
4586 @item @emph{Description}:
4587 @code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
4588 rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
4589 bits of @var{J}, and the remaining bits are the rightmost bits of
4592 @item @emph{Standard}:
4593 Fortran 2008 and later
4598 @item @emph{Syntax}:
4599 @code{RESULT = DSHIFTL(I, J, SHIFT)}
4601 @item @emph{Arguments}:
4602 @multitable @columnfractions .15 .70
4603 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
4604 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
4605 If both @var{I} and @var{J} have integer type, then they shall have
4606 the same kind type parameter. @var{I} and @var{J} shall not both be
4608 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
4609 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
4610 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
4611 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
4614 @item @emph{Return value}:
4615 If either @var{I} or @var{J} is a BOZ constant, it is first converted
4616 as if by the intrinsic function @code{INT} to an integer type with the
4617 kind type parameter of the other.
4619 @item @emph{See also}:
4625 @section @code{DSHIFTR} --- Combined right shift
4627 @cindex right shift, combined
4628 @cindex shift, right
4631 @item @emph{Description}:
4632 @code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
4633 leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
4634 bits of @var{I}, and the remaining bits are the leftmost bits of
4637 @item @emph{Standard}:
4638 Fortran 2008 and later
4643 @item @emph{Syntax}:
4644 @code{RESULT = DSHIFTR(I, J, SHIFT)}
4646 @item @emph{Arguments}:
4647 @multitable @columnfractions .15 .70
4648 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
4649 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
4650 If both @var{I} and @var{J} have integer type, then they shall have
4651 the same kind type parameter. @var{I} and @var{J} shall not both be
4653 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
4654 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
4655 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
4656 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
4659 @item @emph{Return value}:
4660 If either @var{I} or @var{J} is a BOZ constant, it is first converted
4661 as if by the intrinsic function @code{INT} to an integer type with the
4662 kind type parameter of the other.
4664 @item @emph{See also}:
4670 @section @code{DTIME} --- Execution time subroutine (or function)
4672 @cindex time, elapsed
4673 @cindex elapsed time
4676 @item @emph{Description}:
4677 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
4678 since the start of the process's execution in @var{TIME}. @var{VALUES}
4679 returns the user and system components of this time in @code{VALUES(1)} and
4680 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
4683 Subsequent invocations of @code{DTIME} return values accumulated since the
4684 previous invocation.
4686 On some systems, the underlying timings are represented using types with
4687 sufficiently small limits that overflows (wrap around) are possible, such as
4688 32-bit types. Therefore, the values returned by this intrinsic might be, or
4689 become, negative, or numerically less than previous values, during a single
4690 run of the compiled program.
4692 Please note, that this implementation is thread safe if used within OpenMP
4693 directives, i.e., its state will be consistent while called from multiple
4694 threads. However, if @code{DTIME} is called from multiple threads, the result
4695 is still the time since the last invocation. This may not give the intended
4696 results. If possible, use @code{CPU_TIME} instead.
4698 This intrinsic is provided in both subroutine and function forms; however,
4699 only one form can be used in any given program unit.
4701 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
4703 @multitable @columnfractions .15 .30 .40
4704 @item @tab @code{VALUES(1)}: @tab User time in seconds.
4705 @item @tab @code{VALUES(2)}: @tab System time in seconds.
4706 @item @tab @code{TIME}: @tab Run time since start in seconds.
4709 @item @emph{Standard}:
4713 Subroutine, function
4715 @item @emph{Syntax}:
4716 @multitable @columnfractions .80
4717 @item @code{CALL DTIME(VALUES, TIME)}.
4718 @item @code{TIME = DTIME(VALUES)}, (not recommended).
4721 @item @emph{Arguments}:
4722 @multitable @columnfractions .15 .70
4723 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
4724 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
4727 @item @emph{Return value}:
4728 Elapsed time in seconds since the last invocation or since the start of program
4729 execution if not called before.
4731 @item @emph{Example}:
4735 real, dimension(2) :: tarray
4737 call dtime(tarray, result)
4741 do i=1,100000000 ! Just a delay
4744 call dtime(tarray, result)
4748 end program test_dtime
4751 @item @emph{See also}:
4759 @section @code{EOSHIFT} --- End-off shift elements of an array
4761 @cindex array, shift
4764 @item @emph{Description}:
4765 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
4766 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
4767 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
4768 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
4769 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
4770 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
4771 then all complete rank one sections of @var{ARRAY} along the given dimension are
4772 shifted. Elements shifted out one end of each rank one section are dropped. If
4773 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
4774 is copied back in the other end. If @var{BOUNDARY} is not present then the
4775 following are copied in depending on the type of @var{ARRAY}.
4777 @multitable @columnfractions .15 .80
4778 @item @emph{Array Type} @tab @emph{Boundary Value}
4779 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
4780 @item Logical @tab @code{.FALSE.}.
4781 @item Character(@var{len}) @tab @var{len} blanks.
4784 @item @emph{Standard}:
4785 Fortran 95 and later
4788 Transformational function
4790 @item @emph{Syntax}:
4791 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
4793 @item @emph{Arguments}:
4794 @multitable @columnfractions .15 .70
4795 @item @var{ARRAY} @tab May be any type, not scalar.
4796 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
4797 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
4798 @item @var{DIM} @tab The type shall be @code{INTEGER}.
4801 @item @emph{Return value}:
4802 Returns an array of same type and rank as the @var{ARRAY} argument.
4804 @item @emph{Example}:
4806 program test_eoshift
4807 integer, dimension(3,3) :: a
4808 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
4809 print '(3i3)', a(1,:)
4810 print '(3i3)', a(2,:)
4811 print '(3i3)', a(3,:)
4812 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
4814 print '(3i3)', a(1,:)
4815 print '(3i3)', a(2,:)
4816 print '(3i3)', a(3,:)
4817 end program test_eoshift
4824 @section @code{EPSILON} --- Epsilon function
4826 @cindex model representation, epsilon
4829 @item @emph{Description}:
4830 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
4831 as @var{X} such that @math{1 + E > 1}.
4833 @item @emph{Standard}:
4834 Fortran 95 and later
4839 @item @emph{Syntax}:
4840 @code{RESULT = EPSILON(X)}
4842 @item @emph{Arguments}:
4843 @multitable @columnfractions .15 .70
4844 @item @var{X} @tab The type shall be @code{REAL}.
4847 @item @emph{Return value}:
4848 The return value is of same type as the argument.
4850 @item @emph{Example}:
4852 program test_epsilon
4857 end program test_epsilon
4864 @section @code{ERF} --- Error function
4866 @cindex error function
4869 @item @emph{Description}:
4870 @code{ERF(X)} computes the error function of @var{X}.
4872 @item @emph{Standard}:
4873 Fortran 2008 and later
4878 @item @emph{Syntax}:
4879 @code{RESULT = ERF(X)}
4881 @item @emph{Arguments}:
4882 @multitable @columnfractions .15 .70
4883 @item @var{X} @tab The type shall be @code{REAL}.
4886 @item @emph{Return value}:
4887 The return value is of type @code{REAL}, of the same kind as
4888 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
4890 @item @emph{Example}:
4893 real(8) :: x = 0.17_8
4895 end program test_erf
4898 @item @emph{Specific names}:
4899 @multitable @columnfractions .20 .20 .20 .25
4900 @item Name @tab Argument @tab Return type @tab Standard
4901 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4908 @section @code{ERFC} --- Error function
4910 @cindex error function, complementary
4913 @item @emph{Description}:
4914 @code{ERFC(X)} computes the complementary error function of @var{X}.
4916 @item @emph{Standard}:
4917 Fortran 2008 and later
4922 @item @emph{Syntax}:
4923 @code{RESULT = ERFC(X)}
4925 @item @emph{Arguments}:
4926 @multitable @columnfractions .15 .70
4927 @item @var{X} @tab The type shall be @code{REAL}.
4930 @item @emph{Return value}:
4931 The return value is of type @code{REAL} and of the same kind as @var{X}.
4932 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
4934 @item @emph{Example}:
4937 real(8) :: x = 0.17_8
4939 end program test_erfc
4942 @item @emph{Specific names}:
4943 @multitable @columnfractions .20 .20 .20 .25
4944 @item Name @tab Argument @tab Return type @tab Standard
4945 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4952 @section @code{ERFC_SCALED} --- Error function
4953 @fnindex ERFC_SCALED
4954 @cindex error function, complementary, exponentially-scaled
4957 @item @emph{Description}:
4958 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
4959 error function of @var{X}.
4961 @item @emph{Standard}:
4962 Fortran 2008 and later
4967 @item @emph{Syntax}:
4968 @code{RESULT = ERFC_SCALED(X)}
4970 @item @emph{Arguments}:
4971 @multitable @columnfractions .15 .70
4972 @item @var{X} @tab The type shall be @code{REAL}.
4975 @item @emph{Return value}:
4976 The return value is of type @code{REAL} and of the same kind as @var{X}.
4978 @item @emph{Example}:
4980 program test_erfc_scaled
4981 real(8) :: x = 0.17_8
4983 end program test_erfc_scaled
4990 @section @code{ETIME} --- Execution time subroutine (or function)
4992 @cindex time, elapsed
4995 @item @emph{Description}:
4996 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
4997 since the start of the process's execution in @var{TIME}. @var{VALUES}
4998 returns the user and system components of this time in @code{VALUES(1)} and
4999 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
5001 On some systems, the underlying timings are represented using types with
5002 sufficiently small limits that overflows (wrap around) are possible, such as
5003 32-bit types. Therefore, the values returned by this intrinsic might be, or
5004 become, negative, or numerically less than previous values, during a single
5005 run of the compiled program.
5007 This intrinsic is provided in both subroutine and function forms; however,
5008 only one form can be used in any given program unit.
5010 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
5012 @multitable @columnfractions .15 .30 .60
5013 @item @tab @code{VALUES(1)}: @tab User time in seconds.
5014 @item @tab @code{VALUES(2)}: @tab System time in seconds.
5015 @item @tab @code{TIME}: @tab Run time since start in seconds.
5018 @item @emph{Standard}:
5022 Subroutine, function
5024 @item @emph{Syntax}:
5025 @multitable @columnfractions .80
5026 @item @code{CALL ETIME(VALUES, TIME)}.
5027 @item @code{TIME = ETIME(VALUES)}, (not recommended).
5030 @item @emph{Arguments}:
5031 @multitable @columnfractions .15 .70
5032 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
5033 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
5036 @item @emph{Return value}:
5037 Elapsed time in seconds since the start of program execution.
5039 @item @emph{Example}:
5043 real, dimension(2) :: tarray
5045 call ETIME(tarray, result)
5049 do i=1,100000000 ! Just a delay
5052 call ETIME(tarray, result)
5056 end program test_etime
5059 @item @emph{See also}:
5066 @node EXECUTE_COMMAND_LINE
5067 @section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
5068 @fnindex EXECUTE_COMMAND_LINE
5069 @cindex system, system call
5070 @cindex command line
5073 @item @emph{Description}:
5074 @code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
5077 The @code{COMMAND} argument is passed to the shell and executed, using
5078 the C library's @code{system} call. (The shell is @code{sh} on Unix
5079 systems, and @code{cmd.exe} on Windows.) If @code{WAIT} is present
5080 and has the value false, the execution of the command is asynchronous
5081 if the system supports it; otherwise, the command is executed
5084 The three last arguments allow the user to get status information. After
5085 synchronous execution, @code{EXITSTAT} contains the integer exit code of
5086 the command, as returned by @code{system}. @code{CMDSTAT} is set to zero
5087 if the command line was executed (whatever its exit status was).
5088 @code{CMDMSG} is assigned an error message if an error has occurred.
5090 Note that the @code{system} function need not be thread-safe. It is
5091 the responsibility of the user to ensure that @code{system} is not
5092 called concurrently.
5094 @item @emph{Standard}:
5095 Fortran 2008 and later
5100 @item @emph{Syntax}:
5101 @code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
5103 @item @emph{Arguments}:
5104 @multitable @columnfractions .15 .70
5105 @item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
5106 @item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
5107 @item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5109 @item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5111 @item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
5115 @item @emph{Example}:
5120 call execute_command_line ("external_prog.exe", exitstat=i)
5121 print *, "Exit status of external_prog.exe was ", i
5123 call execute_command_line ("reindex_files.exe", wait=.false.)
5124 print *, "Now reindexing files in the background"
5126 end program test_exec
5132 Because this intrinsic is implemented in terms of the @code{system}
5133 function call, its behavior with respect to signaling is processor
5134 dependent. In particular, on POSIX-compliant systems, the SIGINT and
5135 SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
5136 such, if the parent process is terminated, the child process might not be
5137 terminated alongside.
5140 @item @emph{See also}:
5147 @section @code{EXIT} --- Exit the program with status.
5149 @cindex program termination
5150 @cindex terminate program
5153 @item @emph{Description}:
5154 @code{EXIT} causes immediate termination of the program with status. If status
5155 is omitted it returns the canonical @emph{success} for the system. All Fortran
5156 I/O units are closed.
5158 @item @emph{Standard}:
5164 @item @emph{Syntax}:
5165 @code{CALL EXIT([STATUS])}
5167 @item @emph{Arguments}:
5168 @multitable @columnfractions .15 .70
5169 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
5172 @item @emph{Return value}:
5173 @code{STATUS} is passed to the parent process on exit.
5175 @item @emph{Example}:
5178 integer :: STATUS = 0
5179 print *, 'This program is going to exit.'
5181 end program test_exit
5184 @item @emph{See also}:
5185 @ref{ABORT}, @ref{KILL}
5191 @section @code{EXP} --- Exponential function
5197 @cindex exponential function
5198 @cindex logarithm function, inverse
5201 @item @emph{Description}:
5202 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
5204 @item @emph{Standard}:
5205 Fortran 77 and later, has overloads that are GNU extensions
5210 @item @emph{Syntax}:
5211 @code{RESULT = EXP(X)}
5213 @item @emph{Arguments}:
5214 @multitable @columnfractions .15 .70
5215 @item @var{X} @tab The type shall be @code{REAL} or
5219 @item @emph{Return value}:
5220 The return value has same type and kind as @var{X}.
5222 @item @emph{Example}:
5227 end program test_exp
5230 @item @emph{Specific names}:
5231 @multitable @columnfractions .20 .20 .20 .25
5232 @item Name @tab Argument @tab Return type @tab Standard
5233 @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
5234 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
5235 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
5236 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5237 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5244 @section @code{EXPONENT} --- Exponent function
5246 @cindex real number, exponent
5247 @cindex floating point, exponent
5250 @item @emph{Description}:
5251 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
5252 is zero the value returned is zero.
5254 @item @emph{Standard}:
5255 Fortran 95 and later
5260 @item @emph{Syntax}:
5261 @code{RESULT = EXPONENT(X)}
5263 @item @emph{Arguments}:
5264 @multitable @columnfractions .15 .70
5265 @item @var{X} @tab The type shall be @code{REAL}.
5268 @item @emph{Return value}:
5269 The return value is of type default @code{INTEGER}.
5271 @item @emph{Example}:
5273 program test_exponent
5278 print *, exponent(0.0)
5279 end program test_exponent
5285 @node EXTENDS_TYPE_OF
5286 @section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension
5287 @fnindex EXTENDS_TYPE_OF
5290 @item @emph{Description}:
5291 Query dynamic type for extension.
5293 @item @emph{Standard}:
5294 Fortran 2003 and later
5299 @item @emph{Syntax}:
5300 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
5302 @item @emph{Arguments}:
5303 @multitable @columnfractions .15 .70
5304 @item @var{A} @tab Shall be an object of extensible declared type or
5305 unlimited polymorphic.
5306 @item @var{MOLD} @tab Shall be an object of extensible declared type or
5307 unlimited polymorphic.
5310 @item @emph{Return value}:
5311 The return value is a scalar of type default logical. It is true if and only if
5312 the dynamic type of A is an extension type of the dynamic type of MOLD.
5315 @item @emph{See also}:
5322 @section @code{FDATE} --- Get the current time as a string
5324 @cindex time, current
5325 @cindex current time
5326 @cindex date, current
5327 @cindex current date
5330 @item @emph{Description}:
5331 @code{FDATE(DATE)} returns the current date (using the same format as
5332 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
5335 This intrinsic is provided in both subroutine and function forms; however,
5336 only one form can be used in any given program unit.
5338 @item @emph{Standard}:
5342 Subroutine, function
5344 @item @emph{Syntax}:
5345 @multitable @columnfractions .80
5346 @item @code{CALL FDATE(DATE)}.
5347 @item @code{DATE = FDATE()}.
5350 @item @emph{Arguments}:
5351 @multitable @columnfractions .15 .70
5352 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
5353 default kind. It is an @code{INTENT(OUT)} argument. If the length of
5354 this variable is too short for the date and time string to fit
5355 completely, it will be blank on procedure return.
5358 @item @emph{Return value}:
5359 The current date and time as a string.
5361 @item @emph{Example}:
5365 character(len=30) :: date
5367 print *, 'Program started on ', date
5368 do i = 1, 100000000 ! Just a delay
5372 print *, 'Program ended on ', date
5373 end program test_fdate
5376 @item @emph{See also}:
5377 @ref{DATE_AND_TIME}, @ref{CTIME}
5382 @section @code{FGET} --- Read a single character in stream mode from stdin
5384 @cindex read character, stream mode
5385 @cindex stream mode, read character
5386 @cindex file operation, read character
5389 @item @emph{Description}:
5390 Read a single character in stream mode from stdin by bypassing normal
5391 formatted output. Stream I/O should not be mixed with normal record-oriented
5392 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
5394 This intrinsic is provided in both subroutine and function forms; however,
5395 only one form can be used in any given program unit.
5397 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
5398 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5399 Programmers should consider the use of new stream IO feature in new code
5400 for future portability. See also @ref{Fortran 2003 status}.
5402 @item @emph{Standard}:
5406 Subroutine, function
5408 @item @emph{Syntax}:
5409 @multitable @columnfractions .80
5410 @item @code{CALL FGET(C [, STATUS])}
5411 @item @code{STATUS = FGET(C)}
5414 @item @emph{Arguments}:
5415 @multitable @columnfractions .15 .70
5416 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5418 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5419 Returns 0 on success, -1 on end-of-file, and a system specific positive
5420 error code otherwise.
5423 @item @emph{Example}:
5426 INTEGER, PARAMETER :: strlen = 100
5427 INTEGER :: status, i = 1
5428 CHARACTER(len=strlen) :: str = ""
5430 WRITE (*,*) 'Enter text:'
5432 CALL fget(str(i:i), status)
5433 if (status /= 0 .OR. i > strlen) exit
5436 WRITE (*,*) TRIM(str)
5440 @item @emph{See also}:
5441 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
5447 @section @code{FGETC} --- Read a single character in stream mode
5449 @cindex read character, stream mode
5450 @cindex stream mode, read character
5451 @cindex file operation, read character
5454 @item @emph{Description}:
5455 Read a single character in stream mode by bypassing normal formatted output.
5456 Stream I/O should not be mixed with normal record-oriented (formatted or
5457 unformatted) I/O on the same unit; the results are unpredictable.
5459 This intrinsic is provided in both subroutine and function forms; however,
5460 only one form can be used in any given program unit.
5462 Note that the @code{FGET} intrinsic is provided for backwards compatibility
5463 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5464 Programmers should consider the use of new stream IO feature in new code
5465 for future portability. See also @ref{Fortran 2003 status}.
5467 @item @emph{Standard}:
5471 Subroutine, function
5473 @item @emph{Syntax}:
5474 @multitable @columnfractions .80
5475 @item @code{CALL FGETC(UNIT, C [, STATUS])}
5476 @item @code{STATUS = FGETC(UNIT, C)}
5479 @item @emph{Arguments}:
5480 @multitable @columnfractions .15 .70
5481 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
5482 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5484 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5485 Returns 0 on success, -1 on end-of-file and a system specific positive
5486 error code otherwise.
5489 @item @emph{Example}:
5492 INTEGER :: fd = 42, status
5495 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
5497 CALL fgetc(fd, c, status)
5498 IF (status /= 0) EXIT
5505 @item @emph{See also}:
5506 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
5512 @section @code{FLOOR} --- Integer floor function
5515 @cindex rounding, floor
5518 @item @emph{Description}:
5519 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
5521 @item @emph{Standard}:
5522 Fortran 95 and later
5527 @item @emph{Syntax}:
5528 @code{RESULT = FLOOR(A [, KIND])}
5530 @item @emph{Arguments}:
5531 @multitable @columnfractions .15 .70
5532 @item @var{A} @tab The type shall be @code{REAL}.
5533 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5534 expression indicating the kind parameter of the result.
5537 @item @emph{Return value}:
5538 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
5539 and of default-kind @code{INTEGER} otherwise.
5541 @item @emph{Example}:
5546 print *, floor(x) ! returns 63
5547 print *, floor(y) ! returns -64
5548 end program test_floor
5551 @item @emph{See also}:
5552 @ref{CEILING}, @ref{NINT}
5559 @section @code{FLUSH} --- Flush I/O unit(s)
5561 @cindex file operation, flush
5564 @item @emph{Description}:
5565 Flushes Fortran unit(s) currently open for output. Without the optional
5566 argument, all units are flushed, otherwise just the unit specified.
5568 @item @emph{Standard}:
5574 @item @emph{Syntax}:
5575 @code{CALL FLUSH(UNIT)}
5577 @item @emph{Arguments}:
5578 @multitable @columnfractions .15 .70
5579 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
5583 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
5584 statement that should be preferred over the @code{FLUSH} intrinsic.
5586 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
5587 have identical effect: they flush the runtime library's I/O buffer so
5588 that the data becomes visible to other processes. This does not guarantee
5589 that the data is committed to disk.
5591 On POSIX systems, you can request that all data is transferred to the
5592 storage device by calling the @code{fsync} function, with the POSIX file
5593 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
5594 @code{FNUM}). The following example shows how:
5597 ! Declare the interface for POSIX fsync function
5599 function fsync (fd) bind(c,name="fsync")
5600 use iso_c_binding, only: c_int
5601 integer(c_int), value :: fd
5602 integer(c_int) :: fsync
5606 ! Variable declaration
5610 open (10,file="foo")
5613 ! Perform I/O on unit 10
5618 ret = fsync(fnum(10))
5620 ! Handle possible error
5621 if (ret /= 0) stop "Error calling FSYNC"
5629 @section @code{FNUM} --- File number function
5631 @cindex file operation, file number
5634 @item @emph{Description}:
5635 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
5636 open Fortran I/O unit @code{UNIT}.
5638 @item @emph{Standard}:
5644 @item @emph{Syntax}:
5645 @code{RESULT = FNUM(UNIT)}
5647 @item @emph{Arguments}:
5648 @multitable @columnfractions .15 .70
5649 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
5652 @item @emph{Return value}:
5653 The return value is of type @code{INTEGER}
5655 @item @emph{Example}:
5659 open (unit=10, status = "scratch")
5663 end program test_fnum
5670 @section @code{FPUT} --- Write a single character in stream mode to stdout
5672 @cindex write character, stream mode
5673 @cindex stream mode, write character
5674 @cindex file operation, write character
5677 @item @emph{Description}:
5678 Write a single character in stream mode to stdout by bypassing normal
5679 formatted output. Stream I/O should not be mixed with normal record-oriented
5680 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
5682 This intrinsic is provided in both subroutine and function forms; however,
5683 only one form can be used in any given program unit.
5685 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
5686 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5687 Programmers should consider the use of new stream IO feature in new code
5688 for future portability. See also @ref{Fortran 2003 status}.
5690 @item @emph{Standard}:
5694 Subroutine, function
5696 @item @emph{Syntax}:
5697 @multitable @columnfractions .80
5698 @item @code{CALL FPUT(C [, STATUS])}
5699 @item @code{STATUS = FPUT(C)}
5702 @item @emph{Arguments}:
5703 @multitable @columnfractions .15 .70
5704 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5706 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5707 Returns 0 on success, -1 on end-of-file and a system specific positive
5708 error code otherwise.
5711 @item @emph{Example}:
5714 CHARACTER(len=10) :: str = "gfortran"
5716 DO i = 1, len_trim(str)
5722 @item @emph{See also}:
5723 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
5729 @section @code{FPUTC} --- Write a single character in stream mode
5731 @cindex write character, stream mode
5732 @cindex stream mode, write character
5733 @cindex file operation, write character
5736 @item @emph{Description}:
5737 Write a single character in stream mode by bypassing normal formatted
5738 output. Stream I/O should not be mixed with normal record-oriented
5739 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
5741 This intrinsic is provided in both subroutine and function forms; however,
5742 only one form can be used in any given program unit.
5744 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
5745 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5746 Programmers should consider the use of new stream IO feature in new code
5747 for future portability. See also @ref{Fortran 2003 status}.
5749 @item @emph{Standard}:
5753 Subroutine, function
5755 @item @emph{Syntax}:
5756 @multitable @columnfractions .80
5757 @item @code{CALL FPUTC(UNIT, C [, STATUS])}
5758 @item @code{STATUS = FPUTC(UNIT, C)}
5761 @item @emph{Arguments}:
5762 @multitable @columnfractions .15 .70
5763 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
5764 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5766 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5767 Returns 0 on success, -1 on end-of-file and a system specific positive
5768 error code otherwise.
5771 @item @emph{Example}:
5774 CHARACTER(len=10) :: str = "gfortran"
5775 INTEGER :: fd = 42, i
5777 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
5778 DO i = 1, len_trim(str)
5779 CALL fputc(fd, str(i:i))
5785 @item @emph{See also}:
5786 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
5792 @section @code{FRACTION} --- Fractional part of the model representation
5794 @cindex real number, fraction
5795 @cindex floating point, fraction
5798 @item @emph{Description}:
5799 @code{FRACTION(X)} returns the fractional part of the model
5800 representation of @code{X}.
5802 @item @emph{Standard}:
5803 Fortran 95 and later
5808 @item @emph{Syntax}:
5809 @code{Y = FRACTION(X)}
5811 @item @emph{Arguments}:
5812 @multitable @columnfractions .15 .70
5813 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
5816 @item @emph{Return value}:
5817 The return value is of the same type and kind as the argument.
5818 The fractional part of the model representation of @code{X} is returned;
5819 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
5821 @item @emph{Example}:
5823 program test_fraction
5826 print *, fraction(x), x * radix(x)**(-exponent(x))
5827 end program test_fraction
5835 @section @code{FREE} --- Frees memory
5837 @cindex pointer, cray
5840 @item @emph{Description}:
5841 Frees memory previously allocated by @code{MALLOC}. The @code{FREE}
5842 intrinsic is an extension intended to be used with Cray pointers, and is
5843 provided in GNU Fortran to allow user to compile legacy code. For
5844 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
5847 @item @emph{Standard}:
5853 @item @emph{Syntax}:
5854 @code{CALL FREE(PTR)}
5856 @item @emph{Arguments}:
5857 @multitable @columnfractions .15 .70
5858 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
5859 location of the memory that should be de-allocated.
5862 @item @emph{Return value}:
5865 @item @emph{Example}:
5866 See @code{MALLOC} for an example.
5868 @item @emph{See also}:
5875 @section @code{FSEEK} --- Low level file positioning subroutine
5877 @cindex file operation, seek
5878 @cindex file operation, position
5881 @item @emph{Description}:
5882 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
5883 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
5884 if set to 1, @var{OFFSET} is taken to be relative to the current position
5885 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
5886 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
5889 This intrinsic routine is not fully backwards compatible with @command{g77}.
5890 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
5891 @var{STATUS} variable. If FSEEK is used in old code, change
5893 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
5898 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
5899 IF (status /= 0) GOTO label
5902 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
5903 Programmers should consider the use of new stream IO feature in new code
5904 for future portability. See also @ref{Fortran 2003 status}.
5906 @item @emph{Standard}:
5912 @item @emph{Syntax}:
5913 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
5915 @item @emph{Arguments}:
5916 @multitable @columnfractions .15 .70
5917 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
5918 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
5919 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
5920 Its value shall be either 0, 1 or 2.
5921 @item @var{STATUS} @tab (Optional) shall be a scalar of type
5925 @item @emph{Example}:
5928 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
5929 INTEGER :: fd, offset, ierr
5935 OPEN(UNIT=fd, FILE="fseek.test")
5936 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
5937 print *, FTELL(fd), ierr
5939 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
5940 print *, FTELL(fd), ierr
5942 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
5943 print *, FTELL(fd), ierr
5949 @item @emph{See also}:
5956 @section @code{FSTAT} --- Get file status
5958 @cindex file system, file status
5961 @item @emph{Description}:
5962 @code{FSTAT} is identical to @ref{STAT}, except that information about an
5963 already opened file is obtained.
5965 The elements in @code{VALUES} are the same as described by @ref{STAT}.
5967 This intrinsic is provided in both subroutine and function forms; however,
5968 only one form can be used in any given program unit.
5970 @item @emph{Standard}:
5974 Subroutine, function
5976 @item @emph{Syntax}:
5977 @multitable @columnfractions .80
5978 @item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
5979 @item @code{STATUS = FSTAT(UNIT, VALUES)}
5982 @item @emph{Arguments}:
5983 @multitable @columnfractions .15 .70
5984 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
5985 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
5986 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
5987 on success and a system specific error code otherwise.
5990 @item @emph{Example}:
5991 See @ref{STAT} for an example.
5993 @item @emph{See also}:
5994 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
6000 @section @code{FTELL} --- Current stream position
6002 @cindex file operation, position
6005 @item @emph{Description}:
6006 Retrieves the current position within an open file.
6008 This intrinsic is provided in both subroutine and function forms; however,
6009 only one form can be used in any given program unit.
6011 @item @emph{Standard}:
6015 Subroutine, function
6017 @item @emph{Syntax}:
6018 @multitable @columnfractions .80
6019 @item @code{CALL FTELL(UNIT, OFFSET)}
6020 @item @code{OFFSET = FTELL(UNIT)}
6023 @item @emph{Arguments}:
6024 @multitable @columnfractions .15 .70
6025 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
6026 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
6029 @item @emph{Return value}:
6030 In either syntax, @var{OFFSET} is set to the current offset of unit
6031 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
6033 @item @emph{Example}:
6037 OPEN(10, FILE="temp.dat")
6043 @item @emph{See also}:
6050 @section @code{GAMMA} --- Gamma function
6053 @cindex Gamma function
6054 @cindex Factorial function
6057 @item @emph{Description}:
6058 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
6059 integer values of @var{X} the Gamma function simplifies to the factorial
6060 function @math{\Gamma(x)=(x-1)!}.
6064 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
6068 @item @emph{Standard}:
6069 Fortran 2008 and later
6074 @item @emph{Syntax}:
6077 @item @emph{Arguments}:
6078 @multitable @columnfractions .15 .70
6079 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
6080 nor a negative integer.
6083 @item @emph{Return value}:
6084 The return value is of type @code{REAL} of the same kind as @var{X}.
6086 @item @emph{Example}:
6090 x = gamma(x) ! returns 1.0
6091 end program test_gamma
6094 @item @emph{Specific names}:
6095 @multitable @columnfractions .20 .20 .20 .25
6096 @item Name @tab Argument @tab Return type @tab Standard
6097 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
6098 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
6101 @item @emph{See also}:
6102 Logarithm of the Gamma function: @ref{LOG_GAMMA}
6109 @section @code{GERROR} --- Get last system error message
6111 @cindex system, error handling
6114 @item @emph{Description}:
6115 Returns the system error message corresponding to the last system error.
6116 This resembles the functionality of @code{strerror(3)} in C.
6118 @item @emph{Standard}:
6124 @item @emph{Syntax}:
6125 @code{CALL GERROR(RESULT)}
6127 @item @emph{Arguments}:
6128 @multitable @columnfractions .15 .70
6129 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
6132 @item @emph{Example}:
6135 CHARACTER(len=100) :: msg
6141 @item @emph{See also}:
6142 @ref{IERRNO}, @ref{PERROR}
6148 @section @code{GETARG} --- Get command line arguments
6150 @cindex command-line arguments
6151 @cindex arguments, to program
6154 @item @emph{Description}:
6155 Retrieve the @var{POS}-th argument that was passed on the
6156 command line when the containing program was invoked.
6158 This intrinsic routine is provided for backwards compatibility with
6159 GNU Fortran 77. In new code, programmers should consider the use of
6160 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
6163 @item @emph{Standard}:
6169 @item @emph{Syntax}:
6170 @code{CALL GETARG(POS, VALUE)}
6172 @item @emph{Arguments}:
6173 @multitable @columnfractions .15 .70
6174 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
6175 the default integer kind; @math{@var{POS} \geq 0}
6176 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
6178 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
6181 @item @emph{Return value}:
6182 After @code{GETARG} returns, the @var{VALUE} argument holds the
6183 @var{POS}th command line argument. If @var{VALUE} can not hold the
6184 argument, it is truncated to fit the length of @var{VALUE}. If there are
6185 less than @var{POS} arguments specified at the command line, @var{VALUE}
6186 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
6187 to the name of the program (on systems that support this feature).
6189 @item @emph{Example}:
6193 CHARACTER(len=32) :: arg
6202 @item @emph{See also}:
6203 GNU Fortran 77 compatibility function: @ref{IARGC}
6205 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
6206 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6212 @section @code{GET_COMMAND} --- Get the entire command line
6213 @fnindex GET_COMMAND
6214 @cindex command-line arguments
6215 @cindex arguments, to program
6218 @item @emph{Description}:
6219 Retrieve the entire command line that was used to invoke the program.
6221 @item @emph{Standard}:
6222 Fortran 2003 and later
6227 @item @emph{Syntax}:
6228 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
6230 @item @emph{Arguments}:
6231 @multitable @columnfractions .15 .70
6232 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
6234 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
6236 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
6240 @item @emph{Return value}:
6241 If @var{COMMAND} is present, stores the entire command line that was used
6242 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
6243 assigned the length of the command line. If @var{STATUS} is present, it
6244 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
6245 short to store the command line, or a positive value in case of an error.
6247 @item @emph{Example}:
6249 PROGRAM test_get_command
6250 CHARACTER(len=255) :: cmd
6251 CALL get_command(cmd)
6252 WRITE (*,*) TRIM(cmd)
6256 @item @emph{See also}:
6257 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6262 @node GET_COMMAND_ARGUMENT
6263 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
6264 @fnindex GET_COMMAND_ARGUMENT
6265 @cindex command-line arguments
6266 @cindex arguments, to program
6269 @item @emph{Description}:
6270 Retrieve the @var{NUMBER}-th argument that was passed on the
6271 command line when the containing program was invoked.
6273 @item @emph{Standard}:
6274 Fortran 2003 and later
6279 @item @emph{Syntax}:
6280 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
6282 @item @emph{Arguments}:
6283 @multitable @columnfractions .15 .70
6284 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
6285 default kind, @math{@var{NUMBER} \geq 0}
6286 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
6287 and of default kind.
6288 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6289 and of default kind.
6290 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6291 and of default kind.
6294 @item @emph{Return value}:
6295 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
6296 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
6297 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
6298 arguments specified at the command line, @var{VALUE} will be filled with blanks.
6299 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
6300 systems that support this feature). The @var{LENGTH} argument contains the
6301 length of the @var{NUMBER}-th command line argument. If the argument retrieval
6302 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
6303 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
6306 @item @emph{Example}:
6308 PROGRAM test_get_command_argument
6310 CHARACTER(len=32) :: arg
6314 CALL get_command_argument(i, arg)
6315 IF (LEN_TRIM(arg) == 0) EXIT
6317 WRITE (*,*) TRIM(arg)
6323 @item @emph{See also}:
6324 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
6330 @section @code{GETCWD} --- Get current working directory
6332 @cindex system, working directory
6335 @item @emph{Description}:
6336 Get current working directory.
6338 This intrinsic is provided in both subroutine and function forms; however,
6339 only one form can be used in any given program unit.
6341 @item @emph{Standard}:
6345 Subroutine, function
6347 @item @emph{Syntax}:
6348 @multitable @columnfractions .80
6349 @item @code{CALL GETCWD(C [, STATUS])}
6350 @item @code{STATUS = GETCWD(C)}
6353 @item @emph{Arguments}:
6354 @multitable @columnfractions .15 .70
6355 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
6356 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
6357 a system specific and nonzero error code otherwise.
6360 @item @emph{Example}:
6363 CHARACTER(len=255) :: cwd
6365 WRITE(*,*) TRIM(cwd)
6369 @item @emph{See also}:
6376 @section @code{GETENV} --- Get an environmental variable
6378 @cindex environment variable
6381 @item @emph{Description}:
6382 Get the @var{VALUE} of the environmental variable @var{NAME}.
6384 This intrinsic routine is provided for backwards compatibility with
6385 GNU Fortran 77. In new code, programmers should consider the use of
6386 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
6389 Note that @code{GETENV} need not be thread-safe. It is the
6390 responsibility of the user to ensure that the environment is not being
6391 updated concurrently with a call to the @code{GETENV} intrinsic.
6393 @item @emph{Standard}:
6399 @item @emph{Syntax}:
6400 @code{CALL GETENV(NAME, VALUE)}
6402 @item @emph{Arguments}:
6403 @multitable @columnfractions .15 .70
6404 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
6405 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
6408 @item @emph{Return value}:
6409 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
6410 not large enough to hold the data, it is truncated. If @var{NAME}
6411 is not set, @var{VALUE} will be filled with blanks.
6413 @item @emph{Example}:
6416 CHARACTER(len=255) :: homedir
6417 CALL getenv("HOME", homedir)
6418 WRITE (*,*) TRIM(homedir)
6422 @item @emph{See also}:
6423 @ref{GET_ENVIRONMENT_VARIABLE}
6428 @node GET_ENVIRONMENT_VARIABLE
6429 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
6430 @fnindex GET_ENVIRONMENT_VARIABLE
6431 @cindex environment variable
6434 @item @emph{Description}:
6435 Get the @var{VALUE} of the environmental variable @var{NAME}.
6437 Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It
6438 is the responsibility of the user to ensure that the environment is
6439 not being updated concurrently with a call to the
6440 @code{GET_ENVIRONMENT_VARIABLE} intrinsic.
6442 @item @emph{Standard}:
6443 Fortran 2003 and later
6448 @item @emph{Syntax}:
6449 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
6451 @item @emph{Arguments}:
6452 @multitable @columnfractions .15 .70
6453 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
6454 and of default kind.
6455 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
6456 and of default kind.
6457 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6458 and of default kind.
6459 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6460 and of default kind.
6461 @item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL}
6462 and of default kind.
6465 @item @emph{Return value}:
6466 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
6467 not large enough to hold the data, it is truncated. If @var{NAME}
6468 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
6469 contains the length needed for storing the environment variable @var{NAME}
6470 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
6471 but too short for the environment variable; it is 1 if the environment
6472 variable does not exist and 2 if the processor does not support environment
6473 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
6474 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
6475 are significant; otherwise they are not part of the environment variable
6478 @item @emph{Example}:
6481 CHARACTER(len=255) :: homedir
6482 CALL get_environment_variable("HOME", homedir)
6483 WRITE (*,*) TRIM(homedir)
6491 @section @code{GETGID} --- Group ID function
6493 @cindex system, group ID
6496 @item @emph{Description}:
6497 Returns the numerical group ID of the current process.
6499 @item @emph{Standard}:
6505 @item @emph{Syntax}:
6506 @code{RESULT = GETGID()}
6508 @item @emph{Return value}:
6509 The return value of @code{GETGID} is an @code{INTEGER} of the default
6513 @item @emph{Example}:
6514 See @code{GETPID} for an example.
6516 @item @emph{See also}:
6517 @ref{GETPID}, @ref{GETUID}
6523 @section @code{GETLOG} --- Get login name
6525 @cindex system, login name
6529 @item @emph{Description}:
6530 Gets the username under which the program is running.
6532 @item @emph{Standard}:
6538 @item @emph{Syntax}:
6539 @code{CALL GETLOG(C)}
6541 @item @emph{Arguments}:
6542 @multitable @columnfractions .15 .70
6543 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
6546 @item @emph{Return value}:
6547 Stores the current user name in @var{LOGIN}. (On systems where POSIX
6548 functions @code{geteuid} and @code{getpwuid} are not available, and
6549 the @code{getlogin} function is not implemented either, this will
6550 return a blank string.)
6552 @item @emph{Example}:
6555 CHARACTER(32) :: login
6561 @item @emph{See also}:
6568 @section @code{GETPID} --- Process ID function
6570 @cindex system, process ID
6574 @item @emph{Description}:
6575 Returns the numerical process identifier of the current process.
6577 @item @emph{Standard}:
6583 @item @emph{Syntax}:
6584 @code{RESULT = GETPID()}
6586 @item @emph{Return value}:
6587 The return value of @code{GETPID} is an @code{INTEGER} of the default
6591 @item @emph{Example}:
6594 print *, "The current process ID is ", getpid()
6595 print *, "Your numerical user ID is ", getuid()
6596 print *, "Your numerical group ID is ", getgid()
6600 @item @emph{See also}:
6601 @ref{GETGID}, @ref{GETUID}
6607 @section @code{GETUID} --- User ID function
6609 @cindex system, user ID
6613 @item @emph{Description}:
6614 Returns the numerical user ID of the current process.
6616 @item @emph{Standard}:
6622 @item @emph{Syntax}:
6623 @code{RESULT = GETUID()}
6625 @item @emph{Return value}:
6626 The return value of @code{GETUID} is an @code{INTEGER} of the default
6630 @item @emph{Example}:
6631 See @code{GETPID} for an example.
6633 @item @emph{See also}:
6634 @ref{GETPID}, @ref{GETLOG}
6640 @section @code{GMTIME} --- Convert time to GMT info
6642 @cindex time, conversion to GMT info
6645 @item @emph{Description}:
6646 Given a system time value @var{TIME} (as provided by the @code{TIME8}
6647 intrinsic), fills @var{VALUES} with values extracted from it appropriate
6648 to the UTC time zone (Universal Coordinated Time, also known in some
6649 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
6651 @item @emph{Standard}:
6657 @item @emph{Syntax}:
6658 @code{CALL GMTIME(TIME, VALUES)}
6660 @item @emph{Arguments}:
6661 @multitable @columnfractions .15 .70
6662 @item @var{TIME} @tab An @code{INTEGER} scalar expression
6663 corresponding to a system time, with @code{INTENT(IN)}.
6664 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
6665 with @code{INTENT(OUT)}.
6668 @item @emph{Return value}:
6669 The elements of @var{VALUES} are assigned as follows:
6671 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
6673 @item Minutes after the hour, range 0--59
6674 @item Hours past midnight, range 0--23
6675 @item Day of month, range 0--31
6676 @item Number of months since January, range 0--12
6677 @item Years since 1900
6678 @item Number of days since Sunday, range 0--6
6679 @item Days since January 1
6680 @item Daylight savings indicator: positive if daylight savings is in
6681 effect, zero if not, and negative if the information is not available.
6684 @item @emph{See also}:
6685 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
6692 @section @code{HOSTNM} --- Get system host name
6694 @cindex system, host name
6697 @item @emph{Description}:
6698 Retrieves the host name of the system on which the program is running.
6700 This intrinsic is provided in both subroutine and function forms; however,
6701 only one form can be used in any given program unit.
6703 @item @emph{Standard}:
6707 Subroutine, function
6709 @item @emph{Syntax}:
6710 @multitable @columnfractions .80
6711 @item @code{CALL HOSTNM(C [, STATUS])}
6712 @item @code{STATUS = HOSTNM(NAME)}
6715 @item @emph{Arguments}:
6716 @multitable @columnfractions .15 .70
6717 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
6718 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6719 Returns 0 on success, or a system specific error code otherwise.
6722 @item @emph{Return value}:
6723 In either syntax, @var{NAME} is set to the current hostname if it can
6724 be obtained, or to a blank string otherwise.
6731 @section @code{HUGE} --- Largest number of a kind
6733 @cindex limits, largest number
6734 @cindex model representation, largest number
6737 @item @emph{Description}:
6738 @code{HUGE(X)} returns the largest number that is not an infinity in
6739 the model of the type of @code{X}.
6741 @item @emph{Standard}:
6742 Fortran 95 and later
6747 @item @emph{Syntax}:
6748 @code{RESULT = HUGE(X)}
6750 @item @emph{Arguments}:
6751 @multitable @columnfractions .15 .70
6752 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
6755 @item @emph{Return value}:
6756 The return value is of the same type and kind as @var{X}
6758 @item @emph{Example}:
6760 program test_huge_tiny
6761 print *, huge(0), huge(0.0), huge(0.0d0)
6762 print *, tiny(0.0), tiny(0.0d0)
6763 end program test_huge_tiny
6770 @section @code{HYPOT} --- Euclidean distance function
6772 @cindex Euclidean distance
6775 @item @emph{Description}:
6776 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
6777 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
6779 @item @emph{Standard}:
6780 Fortran 2008 and later
6785 @item @emph{Syntax}:
6786 @code{RESULT = HYPOT(X, Y)}
6788 @item @emph{Arguments}:
6789 @multitable @columnfractions .15 .70
6790 @item @var{X} @tab The type shall be @code{REAL}.
6791 @item @var{Y} @tab The type and kind type parameter shall be the same as
6795 @item @emph{Return value}:
6796 The return value has the same type and kind type parameter as @var{X}.
6798 @item @emph{Example}:
6801 real(4) :: x = 1.e0_4, y = 0.5e0_4
6803 end program test_hypot
6810 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
6812 @cindex @acronym{ASCII} collating sequence
6813 @cindex collating sequence, @acronym{ASCII}
6814 @cindex conversion, to integer
6817 @item @emph{Description}:
6818 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
6819 in the first character position of @code{C}.
6821 @item @emph{Standard}:
6822 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6827 @item @emph{Syntax}:
6828 @code{RESULT = IACHAR(C [, KIND])}
6830 @item @emph{Arguments}:
6831 @multitable @columnfractions .15 .70
6832 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
6833 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6834 expression indicating the kind parameter of the result.
6837 @item @emph{Return value}:
6838 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6839 @var{KIND} is absent, the return value is of default integer kind.
6841 @item @emph{Example}:
6846 end program test_iachar
6850 See @ref{ICHAR} for a discussion of converting between numerical values
6851 and formatted string representations.
6853 @item @emph{See also}:
6854 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
6861 @section @code{IALL} --- Bitwise AND of array elements
6864 @cindex bits, AND of array elements
6867 @item @emph{Description}:
6868 Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
6869 if the corresponding element in @var{MASK} is @code{TRUE}.
6871 @item @emph{Standard}:
6872 Fortran 2008 and later
6875 Transformational function
6877 @item @emph{Syntax}:
6878 @multitable @columnfractions .80
6879 @item @code{RESULT = IALL(ARRAY[, MASK])}
6880 @item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
6883 @item @emph{Arguments}:
6884 @multitable @columnfractions .15 .70
6885 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6886 @item @var{DIM} @tab (Optional) shall be a scalar of type
6887 @code{INTEGER} with a value in the range from 1 to n, where n
6888 equals the rank of @var{ARRAY}.
6889 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
6890 and either be a scalar or an array of the same shape as @var{ARRAY}.
6893 @item @emph{Return value}:
6894 The result is of the same type as @var{ARRAY}.
6896 If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
6897 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6898 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6899 dimension @var{DIM} dropped is returned.
6901 @item @emph{Example}:
6910 PRINT '(b8.8)', IALL(a)
6914 @item @emph{See also}:
6915 @ref{IANY}, @ref{IPARITY}, @ref{IAND}
6921 @section @code{IAND} --- Bitwise logical and
6923 @cindex bitwise logical and
6924 @cindex logical and, bitwise
6927 @item @emph{Description}:
6928 Bitwise logical @code{AND}.
6930 @item @emph{Standard}:
6931 Fortran 95 and later
6936 @item @emph{Syntax}:
6937 @code{RESULT = IAND(I, J)}
6939 @item @emph{Arguments}:
6940 @multitable @columnfractions .15 .70
6941 @item @var{I} @tab The type shall be @code{INTEGER}.
6942 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6943 kind as @var{I}. (As a GNU extension, different kinds are also
6947 @item @emph{Return value}:
6948 The return type is @code{INTEGER}, of the same kind as the
6949 arguments. (If the argument kinds differ, it is of the same kind as
6950 the larger argument.)
6952 @item @emph{Example}:
6956 DATA a / Z'F' /, b / Z'3' /
6957 WRITE (*,*) IAND(a, b)
6961 @item @emph{See also}:
6962 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6969 @section @code{IANY} --- Bitwise OR of array elements
6972 @cindex bits, OR of array elements
6975 @item @emph{Description}:
6976 Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
6977 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
6979 @item @emph{Standard}:
6980 Fortran 2008 and later
6983 Transformational function
6985 @item @emph{Syntax}:
6986 @multitable @columnfractions .80
6987 @item @code{RESULT = IANY(ARRAY[, MASK])}
6988 @item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
6991 @item @emph{Arguments}:
6992 @multitable @columnfractions .15 .70
6993 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6994 @item @var{DIM} @tab (Optional) shall be a scalar of type
6995 @code{INTEGER} with a value in the range from 1 to n, where n
6996 equals the rank of @var{ARRAY}.
6997 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
6998 and either be a scalar or an array of the same shape as @var{ARRAY}.
7001 @item @emph{Return value}:
7002 The result is of the same type as @var{ARRAY}.
7004 If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
7005 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7006 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7007 dimension @var{DIM} dropped is returned.
7009 @item @emph{Example}:
7018 PRINT '(b8.8)', IANY(a)
7022 @item @emph{See also}:
7023 @ref{IPARITY}, @ref{IALL}, @ref{IOR}
7029 @section @code{IARGC} --- Get the number of command line arguments
7031 @cindex command-line arguments
7032 @cindex command-line arguments, number of
7033 @cindex arguments, to program
7036 @item @emph{Description}:
7037 @code{IARGC} returns the number of arguments passed on the
7038 command line when the containing program was invoked.
7040 This intrinsic routine is provided for backwards compatibility with
7041 GNU Fortran 77. In new code, programmers should consider the use of
7042 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
7045 @item @emph{Standard}:
7051 @item @emph{Syntax}:
7052 @code{RESULT = IARGC()}
7054 @item @emph{Arguments}:
7057 @item @emph{Return value}:
7058 The number of command line arguments, type @code{INTEGER(4)}.
7060 @item @emph{Example}:
7063 @item @emph{See also}:
7064 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
7066 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
7067 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
7073 @section @code{IBCLR} --- Clear bit
7079 @item @emph{Description}:
7080 @code{IBCLR} returns the value of @var{I} with the bit at position
7081 @var{POS} set to zero.
7083 @item @emph{Standard}:
7084 Fortran 95 and later
7089 @item @emph{Syntax}:
7090 @code{RESULT = IBCLR(I, POS)}
7092 @item @emph{Arguments}:
7093 @multitable @columnfractions .15 .70
7094 @item @var{I} @tab The type shall be @code{INTEGER}.
7095 @item @var{POS} @tab The type shall be @code{INTEGER}.
7098 @item @emph{Return value}:
7099 The return value is of type @code{INTEGER} and of the same kind as
7102 @item @emph{See also}:
7103 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
7110 @section @code{IBITS} --- Bit extraction
7113 @cindex bits, extract
7116 @item @emph{Description}:
7117 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
7118 starting from bit position @var{POS} and extending left for @var{LEN}
7119 bits. The result is right-justified and the remaining bits are
7120 zeroed. The value of @code{POS+LEN} must be less than or equal to the
7121 value @code{BIT_SIZE(I)}.
7123 @item @emph{Standard}:
7124 Fortran 95 and later
7129 @item @emph{Syntax}:
7130 @code{RESULT = IBITS(I, POS, LEN)}
7132 @item @emph{Arguments}:
7133 @multitable @columnfractions .15 .70
7134 @item @var{I} @tab The type shall be @code{INTEGER}.
7135 @item @var{POS} @tab The type shall be @code{INTEGER}.
7136 @item @var{LEN} @tab The type shall be @code{INTEGER}.
7139 @item @emph{Return value}:
7140 The return value is of type @code{INTEGER} and of the same kind as
7143 @item @emph{See also}:
7144 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
7150 @section @code{IBSET} --- Set bit
7155 @item @emph{Description}:
7156 @code{IBSET} returns the value of @var{I} with the bit at position
7157 @var{POS} set to one.
7159 @item @emph{Standard}:
7160 Fortran 95 and later
7165 @item @emph{Syntax}:
7166 @code{RESULT = IBSET(I, POS)}
7168 @item @emph{Arguments}:
7169 @multitable @columnfractions .15 .70
7170 @item @var{I} @tab The type shall be @code{INTEGER}.
7171 @item @var{POS} @tab The type shall be @code{INTEGER}.
7174 @item @emph{Return value}:
7175 The return value is of type @code{INTEGER} and of the same kind as
7178 @item @emph{See also}:
7179 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
7186 @section @code{ICHAR} --- Character-to-integer conversion function
7188 @cindex conversion, to integer
7191 @item @emph{Description}:
7192 @code{ICHAR(C)} returns the code for the character in the first character
7193 position of @code{C} in the system's native character set.
7194 The correspondence between characters and their codes is not necessarily
7195 the same across different GNU Fortran implementations.
7197 @item @emph{Standard}:
7198 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7203 @item @emph{Syntax}:
7204 @code{RESULT = ICHAR(C [, KIND])}
7206 @item @emph{Arguments}:
7207 @multitable @columnfractions .15 .70
7208 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
7209 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7210 expression indicating the kind parameter of the result.
7213 @item @emph{Return value}:
7214 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7215 @var{KIND} is absent, the return value is of default integer kind.
7217 @item @emph{Example}:
7222 end program test_ichar
7225 @item @emph{Specific names}:
7226 @multitable @columnfractions .20 .20 .20 .25
7227 @item Name @tab Argument @tab Return type @tab Standard
7228 @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7232 No intrinsic exists to convert between a numeric value and a formatted
7233 character string representation -- for instance, given the
7234 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
7235 @code{REAL} value with the value 154, or vice versa. Instead, this
7236 functionality is provided by internal-file I/O, as in the following
7241 character(len=10) string, string2
7244 ! Convert a string to a numeric value
7245 read (string,'(I10)') value
7248 ! Convert a value to a formatted string
7249 write (string2,'(I10)') value
7251 end program read_val
7254 @item @emph{See also}:
7255 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
7262 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
7264 @cindex date, current
7265 @cindex current date
7268 @item @emph{Description}:
7269 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
7270 current local time. The day (in the range 1-31), month (in the range 1-12),
7271 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
7272 The year has four significant digits.
7274 @item @emph{Standard}:
7280 @item @emph{Syntax}:
7281 @code{CALL IDATE(VALUES)}
7283 @item @emph{Arguments}:
7284 @multitable @columnfractions .15 .70
7285 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
7286 the kind shall be the default integer kind.
7289 @item @emph{Return value}:
7290 Does not return anything.
7292 @item @emph{Example}:
7295 integer, dimension(3) :: tarray
7300 end program test_idate
7307 @section @code{IEOR} --- Bitwise logical exclusive or
7309 @cindex bitwise logical exclusive or
7310 @cindex logical exclusive or, bitwise
7313 @item @emph{Description}:
7314 @code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
7317 @item @emph{Standard}:
7318 Fortran 95 and later
7323 @item @emph{Syntax}:
7324 @code{RESULT = IEOR(I, J)}
7326 @item @emph{Arguments}:
7327 @multitable @columnfractions .15 .70
7328 @item @var{I} @tab The type shall be @code{INTEGER}.
7329 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
7330 kind as @var{I}. (As a GNU extension, different kinds are also
7334 @item @emph{Return value}:
7335 The return type is @code{INTEGER}, of the same kind as the
7336 arguments. (If the argument kinds differ, it is of the same kind as
7337 the larger argument.)
7339 @item @emph{See also}:
7340 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
7346 @section @code{IERRNO} --- Get the last system error number
7348 @cindex system, error handling
7351 @item @emph{Description}:
7352 Returns the last system error number, as given by the C @code{errno}
7355 @item @emph{Standard}:
7361 @item @emph{Syntax}:
7362 @code{RESULT = IERRNO()}
7364 @item @emph{Arguments}:
7367 @item @emph{Return value}:
7368 The return value is of type @code{INTEGER} and of the default integer
7371 @item @emph{See also}:
7378 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
7379 @fnindex IMAGE_INDEX
7380 @cindex coarray, @code{IMAGE_INDEX}
7381 @cindex images, cosubscript to image index conversion
7384 @item @emph{Description}:
7385 Returns the image index belonging to a cosubscript.
7387 @item @emph{Standard}:
7388 Fortran 2008 and later
7393 @item @emph{Syntax}:
7394 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
7396 @item @emph{Arguments}: None.
7397 @multitable @columnfractions .15 .70
7398 @item @var{COARRAY} @tab Coarray of any type.
7399 @item @var{SUB} @tab default integer rank-1 array of a size equal to
7400 the corank of @var{COARRAY}.
7404 @item @emph{Return value}:
7405 Scalar default integer with the value of the image index which corresponds
7406 to the cosubscripts. For invalid cosubscripts the result is zero.
7408 @item @emph{Example}:
7410 INTEGER :: array[2,-1:4,8,*]
7411 ! Writes 28 (or 0 if there are fewer than 28 images)
7412 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
7415 @item @emph{See also}:
7416 @ref{THIS_IMAGE}, @ref{NUM_IMAGES}
7421 @node INDEX intrinsic
7422 @section @code{INDEX} --- Position of a substring within a string
7424 @cindex substring position
7425 @cindex string, find substring
7428 @item @emph{Description}:
7429 Returns the position of the start of the first occurrence of string
7430 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
7431 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
7432 the @var{BACK} argument is present and true, the return value is the
7433 start of the last occurrence rather than the first.
7435 @item @emph{Standard}:
7436 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
7441 @item @emph{Syntax}:
7442 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
7444 @item @emph{Arguments}:
7445 @multitable @columnfractions .15 .70
7446 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
7448 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
7450 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
7452 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7453 expression indicating the kind parameter of the result.
7456 @item @emph{Return value}:
7457 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7458 @var{KIND} is absent, the return value is of default integer kind.
7460 @item @emph{Specific names}:
7461 @multitable @columnfractions .20 .20 .20 .25
7462 @item Name @tab Argument @tab Return type @tab Standard
7463 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7466 @item @emph{See also}:
7467 @ref{SCAN}, @ref{VERIFY}
7473 @section @code{INT} --- Convert to integer type
7477 @cindex conversion, to integer
7480 @item @emph{Description}:
7481 Convert to integer type
7483 @item @emph{Standard}:
7484 Fortran 77 and later
7489 @item @emph{Syntax}:
7490 @code{RESULT = INT(A [, KIND))}
7492 @item @emph{Arguments}:
7493 @multitable @columnfractions .15 .70
7494 @item @var{A} @tab Shall be of type @code{INTEGER},
7495 @code{REAL}, or @code{COMPLEX}.
7496 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7497 expression indicating the kind parameter of the result.
7500 @item @emph{Return value}:
7501 These functions return a @code{INTEGER} variable or array under
7502 the following rules:
7506 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
7508 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)}
7509 equals @code{0}. If @math{|A| \geq 1}, then @code{INT(A)} is the integer
7510 whose magnitude is the largest integer that does not exceed the magnitude
7511 of @var{A} and whose sign is the same as the sign of @var{A}.
7513 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
7516 @item @emph{Example}:
7520 complex :: z = (-3.7, 1.0)
7522 print *, int(z), int(z,8)
7526 @item @emph{Specific names}:
7527 @multitable @columnfractions .20 .20 .20 .25
7528 @item Name @tab Argument @tab Return type @tab Standard
7529 @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
7530 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
7531 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
7538 @section @code{INT2} --- Convert to 16-bit integer type
7541 @cindex conversion, to integer
7544 @item @emph{Description}:
7545 Convert to a @code{KIND=2} integer type. This is equivalent to the
7546 standard @code{INT} intrinsic with an optional argument of
7547 @code{KIND=2}, and is only included for backwards compatibility.
7549 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
7551 @item @emph{Standard}:
7557 @item @emph{Syntax}:
7558 @code{RESULT = INT2(A)}
7560 @item @emph{Arguments}:
7561 @multitable @columnfractions .15 .70
7562 @item @var{A} @tab Shall be of type @code{INTEGER},
7563 @code{REAL}, or @code{COMPLEX}.
7566 @item @emph{Return value}:
7567 The return value is a @code{INTEGER(2)} variable.
7569 @item @emph{See also}:
7570 @ref{INT}, @ref{INT8}, @ref{LONG}
7576 @section @code{INT8} --- Convert to 64-bit integer type
7578 @cindex conversion, to integer
7581 @item @emph{Description}:
7582 Convert to a @code{KIND=8} integer type. This is equivalent to the
7583 standard @code{INT} intrinsic with an optional argument of
7584 @code{KIND=8}, and is only included for backwards compatibility.
7586 @item @emph{Standard}:
7592 @item @emph{Syntax}:
7593 @code{RESULT = INT8(A)}
7595 @item @emph{Arguments}:
7596 @multitable @columnfractions .15 .70
7597 @item @var{A} @tab Shall be of type @code{INTEGER},
7598 @code{REAL}, or @code{COMPLEX}.
7601 @item @emph{Return value}:
7602 The return value is a @code{INTEGER(8)} variable.
7604 @item @emph{See also}:
7605 @ref{INT}, @ref{INT2}, @ref{LONG}
7611 @section @code{IOR} --- Bitwise logical or
7613 @cindex bitwise logical or
7614 @cindex logical or, bitwise
7617 @item @emph{Description}:
7618 @code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
7621 @item @emph{Standard}:
7622 Fortran 95 and later
7627 @item @emph{Syntax}:
7628 @code{RESULT = IOR(I, J)}
7630 @item @emph{Arguments}:
7631 @multitable @columnfractions .15 .70
7632 @item @var{I} @tab The type shall be @code{INTEGER}.
7633 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
7634 kind as @var{I}. (As a GNU extension, different kinds are also
7638 @item @emph{Return value}:
7639 The return type is @code{INTEGER}, of the same kind as the
7640 arguments. (If the argument kinds differ, it is of the same kind as
7641 the larger argument.)
7643 @item @emph{See also}:
7644 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
7650 @section @code{IPARITY} --- Bitwise XOR of array elements
7652 @cindex array, parity
7654 @cindex bits, XOR of array elements
7657 @item @emph{Description}:
7658 Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
7659 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
7661 @item @emph{Standard}:
7662 Fortran 2008 and later
7665 Transformational function
7667 @item @emph{Syntax}:
7668 @multitable @columnfractions .80
7669 @item @code{RESULT = IPARITY(ARRAY[, MASK])}
7670 @item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
7673 @item @emph{Arguments}:
7674 @multitable @columnfractions .15 .70
7675 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7676 @item @var{DIM} @tab (Optional) shall be a scalar of type
7677 @code{INTEGER} with a value in the range from 1 to n, where n
7678 equals the rank of @var{ARRAY}.
7679 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
7680 and either be a scalar or an array of the same shape as @var{ARRAY}.
7683 @item @emph{Return value}:
7684 The result is of the same type as @var{ARRAY}.
7686 If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
7687 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7688 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7689 dimension @var{DIM} dropped is returned.
7691 @item @emph{Example}:
7693 PROGRAM test_iparity
7700 PRINT '(b8.8)', IPARITY(a)
7704 @item @emph{See also}:
7705 @ref{IANY}, @ref{IALL}, @ref{IEOR}, @ref{PARITY}
7711 @section @code{IRAND} --- Integer pseudo-random number
7713 @cindex random number generation
7716 @item @emph{Description}:
7717 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
7718 distribution between 0 and a system-dependent limit (which is in most
7719 cases 2147483647). If @var{FLAG} is 0, the next number
7720 in the current sequence is returned; if @var{FLAG} is 1, the generator
7721 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
7722 it is used as a new seed with @code{SRAND}.
7724 This intrinsic routine is provided for backwards compatibility with
7725 GNU Fortran 77. It implements a simple modulo generator as provided
7726 by @command{g77}. For new code, one should consider the use of
7727 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
7729 @item @emph{Standard}:
7735 @item @emph{Syntax}:
7736 @code{RESULT = IRAND(I)}
7738 @item @emph{Arguments}:
7739 @multitable @columnfractions .15 .70
7740 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
7743 @item @emph{Return value}:
7744 The return value is of @code{INTEGER(kind=4)} type.
7746 @item @emph{Example}:
7749 integer,parameter :: seed = 86456
7752 print *, irand(), irand(), irand(), irand()
7753 print *, irand(seed), irand(), irand(), irand()
7754 end program test_irand
7762 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
7763 @fnindex IS_IOSTAT_END
7764 @cindex @code{IOSTAT}, end of file
7767 @item @emph{Description}:
7768 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
7769 status ``end of file''. The function is equivalent to comparing the variable
7770 with the @code{IOSTAT_END} parameter of the intrinsic module
7771 @code{ISO_FORTRAN_ENV}.
7773 @item @emph{Standard}:
7774 Fortran 2003 and later
7779 @item @emph{Syntax}:
7780 @code{RESULT = IS_IOSTAT_END(I)}
7782 @item @emph{Arguments}:
7783 @multitable @columnfractions .15 .70
7784 @item @var{I} @tab Shall be of the type @code{INTEGER}.
7787 @item @emph{Return value}:
7788 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
7789 @var{I} has the value which indicates an end of file condition for
7790 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
7792 @item @emph{Example}:
7797 OPEN(88, FILE='test.dat')
7798 READ(88, *, IOSTAT=stat) i
7799 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
7807 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
7808 @fnindex IS_IOSTAT_EOR
7809 @cindex @code{IOSTAT}, end of record
7812 @item @emph{Description}:
7813 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
7814 status ``end of record''. The function is equivalent to comparing the
7815 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
7816 @code{ISO_FORTRAN_ENV}.
7818 @item @emph{Standard}:
7819 Fortran 2003 and later
7824 @item @emph{Syntax}:
7825 @code{RESULT = IS_IOSTAT_EOR(I)}
7827 @item @emph{Arguments}:
7828 @multitable @columnfractions .15 .70
7829 @item @var{I} @tab Shall be of the type @code{INTEGER}.
7832 @item @emph{Return value}:
7833 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
7834 @var{I} has the value which indicates an end of file condition for
7835 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
7837 @item @emph{Example}:
7841 INTEGER :: stat, i(50)
7842 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
7843 READ(88, IOSTAT=stat) i
7844 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
7852 @section @code{ISATTY} --- Whether a unit is a terminal device.
7854 @cindex system, terminal
7857 @item @emph{Description}:
7858 Determine whether a unit is connected to a terminal device.
7860 @item @emph{Standard}:
7866 @item @emph{Syntax}:
7867 @code{RESULT = ISATTY(UNIT)}
7869 @item @emph{Arguments}:
7870 @multitable @columnfractions .15 .70
7871 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
7874 @item @emph{Return value}:
7875 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
7876 device, @code{.FALSE.} otherwise.
7878 @item @emph{Example}:
7881 INTEGER(kind=1) :: unit
7883 write(*,*) isatty(unit=unit)
7887 @item @emph{See also}:
7894 @section @code{ISHFT} --- Shift bits
7899 @item @emph{Description}:
7900 @code{ISHFT} returns a value corresponding to @var{I} with all of the
7901 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
7902 zero corresponds to a left shift, a value of zero corresponds to no
7903 shift, and a value less than zero corresponds to a right shift. If the
7904 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
7905 value is undefined. Bits shifted out from the left end or right end are
7906 lost; zeros are shifted in from the opposite end.
7908 @item @emph{Standard}:
7909 Fortran 95 and later
7914 @item @emph{Syntax}:
7915 @code{RESULT = ISHFT(I, SHIFT)}
7917 @item @emph{Arguments}:
7918 @multitable @columnfractions .15 .70
7919 @item @var{I} @tab The type shall be @code{INTEGER}.
7920 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7923 @item @emph{Return value}:
7924 The return value is of type @code{INTEGER} and of the same kind as
7927 @item @emph{See also}:
7934 @section @code{ISHFTC} --- Shift bits circularly
7936 @cindex bits, shift circular
7939 @item @emph{Description}:
7940 @code{ISHFTC} returns a value corresponding to @var{I} with the
7941 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
7942 is, bits shifted out one end are shifted into the opposite end. A value
7943 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
7944 zero corresponds to no shift, and a value less than zero corresponds to
7945 a right shift. The absolute value of @var{SHIFT} must be less than
7946 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
7947 equivalent to @code{BIT_SIZE(I)}.
7949 @item @emph{Standard}:
7950 Fortran 95 and later
7955 @item @emph{Syntax}:
7956 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
7958 @item @emph{Arguments}:
7959 @multitable @columnfractions .15 .70
7960 @item @var{I} @tab The type shall be @code{INTEGER}.
7961 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7962 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
7963 the value must be greater than zero and less than or equal to
7967 @item @emph{Return value}:
7968 The return value is of type @code{INTEGER} and of the same kind as
7971 @item @emph{See also}:
7978 @section @code{ISNAN} --- Test for a NaN
7983 @item @emph{Description}:
7984 @code{ISNAN} tests whether a floating-point value is an IEEE
7986 @item @emph{Standard}:
7992 @item @emph{Syntax}:
7995 @item @emph{Arguments}:
7996 @multitable @columnfractions .15 .70
7997 @item @var{X} @tab Variable of the type @code{REAL}.
8001 @item @emph{Return value}:
8002 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
8003 if @var{X} is a NaN and @code{FALSE} otherwise.
8005 @item @emph{Example}:
8012 if (isnan(x)) stop '"x" is a NaN'
8013 end program test_nan
8020 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
8022 @cindex time, current
8023 @cindex current time
8026 @item @emph{Description}:
8027 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
8028 current local time. The hour (in the range 1-24), minute (in the range 1-60),
8029 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
8032 @item @emph{Standard}:
8038 @item @emph{Syntax}:
8039 @code{CALL ITIME(VALUES)}
8041 @item @emph{Arguments}:
8042 @multitable @columnfractions .15 .70
8043 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
8044 and the kind shall be the default integer kind.
8047 @item @emph{Return value}:
8048 Does not return anything.
8051 @item @emph{Example}:
8054 integer, dimension(3) :: tarray
8059 end program test_itime
8066 @section @code{KILL} --- Send a signal to a process
8070 @item @emph{Description}:
8071 @item @emph{Standard}:
8072 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
8075 This intrinsic is provided in both subroutine and function forms; however,
8076 only one form can be used in any given program unit.
8079 Subroutine, function
8081 @item @emph{Syntax}:
8082 @multitable @columnfractions .80
8083 @item @code{CALL KILL(C, VALUE [, STATUS])}
8084 @item @code{STATUS = KILL(C, VALUE)}
8087 @item @emph{Arguments}:
8088 @multitable @columnfractions .15 .70
8089 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
8091 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
8093 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
8094 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
8098 @item @emph{See also}:
8099 @ref{ABORT}, @ref{EXIT}
8105 @section @code{KIND} --- Kind of an entity
8110 @item @emph{Description}:
8111 @code{KIND(X)} returns the kind value of the entity @var{X}.
8113 @item @emph{Standard}:
8114 Fortran 95 and later
8119 @item @emph{Syntax}:
8122 @item @emph{Arguments}:
8123 @multitable @columnfractions .15 .70
8124 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
8125 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
8128 @item @emph{Return value}:
8129 The return value is a scalar of type @code{INTEGER} and of the default
8132 @item @emph{Example}:
8135 integer,parameter :: kc = kind(' ')
8136 integer,parameter :: kl = kind(.true.)
8138 print *, "The default character kind is ", kc
8139 print *, "The default logical kind is ", kl
8140 end program test_kind
8148 @section @code{LBOUND} --- Lower dimension bounds of an array
8150 @cindex array, lower bound
8153 @item @emph{Description}:
8154 Returns the lower bounds of an array, or a single lower bound
8155 along the @var{DIM} dimension.
8156 @item @emph{Standard}:
8157 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
8162 @item @emph{Syntax}:
8163 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
8165 @item @emph{Arguments}:
8166 @multitable @columnfractions .15 .70
8167 @item @var{ARRAY} @tab Shall be an array, of any type.
8168 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
8169 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8170 expression indicating the kind parameter of the result.
8173 @item @emph{Return value}:
8174 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8175 @var{KIND} is absent, the return value is of default integer kind.
8176 If @var{DIM} is absent, the result is an array of the lower bounds of
8177 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
8178 corresponding to the lower bound of the array along that dimension. If
8179 @var{ARRAY} is an expression rather than a whole array or array
8180 structure component, or if it has a zero extent along the relevant
8181 dimension, the lower bound is taken to be 1.
8183 @item @emph{See also}:
8184 @ref{UBOUND}, @ref{LCOBOUND}
8190 @section @code{LCOBOUND} --- Lower codimension bounds of an array
8192 @cindex coarray, lower bound
8195 @item @emph{Description}:
8196 Returns the lower bounds of a coarray, or a single lower cobound
8197 along the @var{DIM} codimension.
8198 @item @emph{Standard}:
8199 Fortran 2008 and later
8204 @item @emph{Syntax}:
8205 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
8207 @item @emph{Arguments}:
8208 @multitable @columnfractions .15 .70
8209 @item @var{ARRAY} @tab Shall be an coarray, of any type.
8210 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
8211 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8212 expression indicating the kind parameter of the result.
8215 @item @emph{Return value}:
8216 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8217 @var{KIND} is absent, the return value is of default integer kind.
8218 If @var{DIM} is absent, the result is an array of the lower cobounds of
8219 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
8220 corresponding to the lower cobound of the array along that codimension.
8222 @item @emph{See also}:
8223 @ref{UCOBOUND}, @ref{LBOUND}
8229 @section @code{LEADZ} --- Number of leading zero bits of an integer
8234 @item @emph{Description}:
8235 @code{LEADZ} returns the number of leading zero bits of an integer.
8237 @item @emph{Standard}:
8238 Fortran 2008 and later
8243 @item @emph{Syntax}:
8244 @code{RESULT = LEADZ(I)}
8246 @item @emph{Arguments}:
8247 @multitable @columnfractions .15 .70
8248 @item @var{I} @tab Shall be of type @code{INTEGER}.
8251 @item @emph{Return value}:
8252 The type of the return value is the default @code{INTEGER}.
8253 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
8255 @item @emph{Example}:
8258 WRITE (*,*) BIT_SIZE(1) ! prints 32
8259 WRITE (*,*) LEADZ(1) ! prints 31
8263 @item @emph{See also}:
8264 @ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR}
8270 @section @code{LEN} --- Length of a character entity
8272 @cindex string, length
8275 @item @emph{Description}:
8276 Returns the length of a character string. If @var{STRING} is an array,
8277 the length of an element of @var{STRING} is returned. Note that
8278 @var{STRING} need not be defined when this intrinsic is invoked, since
8279 only the length, not the content, of @var{STRING} is needed.
8281 @item @emph{Standard}:
8282 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
8287 @item @emph{Syntax}:
8288 @code{L = LEN(STRING [, KIND])}
8290 @item @emph{Arguments}:
8291 @multitable @columnfractions .15 .70
8292 @item @var{STRING} @tab Shall be a scalar or array of type
8293 @code{CHARACTER}, with @code{INTENT(IN)}
8294 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8295 expression indicating the kind parameter of the result.
8298 @item @emph{Return value}:
8299 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8300 @var{KIND} is absent, the return value is of default integer kind.
8303 @item @emph{Specific names}:
8304 @multitable @columnfractions .20 .20 .20 .25
8305 @item Name @tab Argument @tab Return type @tab Standard
8306 @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
8310 @item @emph{See also}:
8311 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
8317 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
8319 @cindex string, length, without trailing whitespace
8322 @item @emph{Description}:
8323 Returns the length of a character string, ignoring any trailing blanks.
8325 @item @emph{Standard}:
8326 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
8331 @item @emph{Syntax}:
8332 @code{RESULT = LEN_TRIM(STRING [, KIND])}
8334 @item @emph{Arguments}:
8335 @multitable @columnfractions .15 .70
8336 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
8337 with @code{INTENT(IN)}
8338 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8339 expression indicating the kind parameter of the result.
8342 @item @emph{Return value}:
8343 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8344 @var{KIND} is absent, the return value is of default integer kind.
8346 @item @emph{See also}:
8347 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
8353 @section @code{LGE} --- Lexical greater than or equal
8355 @cindex lexical comparison of strings
8356 @cindex string, comparison
8359 @item @emph{Description}:
8360 Determines whether one string is lexically greater than or equal to
8361 another string, where the two strings are interpreted as containing
8362 ASCII character codes. If the String A and String B are not the same
8363 length, the shorter is compared as if spaces were appended to it to form
8364 a value that has the same length as the longer.
8366 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
8367 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
8368 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
8369 that the latter use the processor's character ordering (which is not
8370 ASCII on some targets), whereas the former always use the ASCII
8373 @item @emph{Standard}:
8374 Fortran 77 and later
8379 @item @emph{Syntax}:
8380 @code{RESULT = LGE(STRING_A, STRING_B)}
8382 @item @emph{Arguments}:
8383 @multitable @columnfractions .15 .70
8384 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
8385 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
8388 @item @emph{Return value}:
8389 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
8390 otherwise, based on the ASCII ordering.
8392 @item @emph{Specific names}:
8393 @multitable @columnfractions .20 .20 .20 .25
8394 @item Name @tab Argument @tab Return type @tab Standard
8395 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
8398 @item @emph{See also}:
8399 @ref{LGT}, @ref{LLE}, @ref{LLT}
8405 @section @code{LGT} --- Lexical greater than
8407 @cindex lexical comparison of strings
8408 @cindex string, comparison
8411 @item @emph{Description}:
8412 Determines whether one string is lexically greater than another string,
8413 where the two strings are interpreted as containing ASCII character
8414 codes. If the String A and String B are not the same length, the
8415 shorter is compared as if spaces were appended to it to form a value
8416 that has the same length as the longer.
8418 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
8419 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
8420 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
8421 that the latter use the processor's character ordering (which is not
8422 ASCII on some targets), whereas the former always use the ASCII
8425 @item @emph{Standard}:
8426 Fortran 77 and later
8431 @item @emph{Syntax}:
8432 @code{RESULT = LGT(STRING_A, STRING_B)}
8434 @item @emph{Arguments}:
8435 @multitable @columnfractions .15 .70
8436 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
8437 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
8440 @item @emph{Return value}:
8441 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
8442 otherwise, based on the ASCII ordering.
8444 @item @emph{Specific names}:
8445 @multitable @columnfractions .20 .20 .20 .25
8446 @item Name @tab Argument @tab Return type @tab Standard
8447 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
8450 @item @emph{See also}:
8451 @ref{LGE}, @ref{LLE}, @ref{LLT}
8457 @section @code{LINK} --- Create a hard link
8459 @cindex file system, create link
8460 @cindex file system, hard link
8463 @item @emph{Description}:
8464 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
8465 character (@code{CHAR(0)}) can be used to mark the end of the names in
8466 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
8467 names are ignored. If the @var{STATUS} argument is supplied, it
8468 contains 0 on success or a nonzero error code upon return; see
8471 This intrinsic is provided in both subroutine and function forms;
8472 however, only one form can be used in any given program unit.
8474 @item @emph{Standard}:
8478 Subroutine, function
8480 @item @emph{Syntax}:
8481 @multitable @columnfractions .80
8482 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
8483 @item @code{STATUS = LINK(PATH1, PATH2)}
8486 @item @emph{Arguments}:
8487 @multitable @columnfractions .15 .70
8488 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
8489 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
8490 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
8493 @item @emph{See also}:
8494 @ref{SYMLNK}, @ref{UNLINK}
8500 @section @code{LLE} --- Lexical less than or equal
8502 @cindex lexical comparison of strings
8503 @cindex string, comparison
8506 @item @emph{Description}:
8507 Determines whether one string is lexically less than or equal to another
8508 string, where the two strings are interpreted as containing ASCII
8509 character codes. If the String A and String B are not the same length,
8510 the shorter is compared as if spaces were appended to it to form a value
8511 that has the same length as the longer.
8513 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
8514 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
8515 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
8516 that the latter use the processor's character ordering (which is not
8517 ASCII on some targets), whereas the former always use the ASCII
8520 @item @emph{Standard}:
8521 Fortran 77 and later
8526 @item @emph{Syntax}:
8527 @code{RESULT = LLE(STRING_A, STRING_B)}
8529 @item @emph{Arguments}:
8530 @multitable @columnfractions .15 .70
8531 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
8532 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
8535 @item @emph{Return value}:
8536 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
8537 otherwise, based on the ASCII ordering.
8539 @item @emph{Specific names}:
8540 @multitable @columnfractions .20 .20 .20 .25
8541 @item Name @tab Argument @tab Return type @tab Standard
8542 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
8545 @item @emph{See also}:
8546 @ref{LGE}, @ref{LGT}, @ref{LLT}
8552 @section @code{LLT} --- Lexical less than
8554 @cindex lexical comparison of strings
8555 @cindex string, comparison
8558 @item @emph{Description}:
8559 Determines whether one string is lexically less than another string,
8560 where the two strings are interpreted as containing ASCII character
8561 codes. If the String A and String B are not the same length, the
8562 shorter is compared as if spaces were appended to it to form a value
8563 that has the same length as the longer.
8565 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
8566 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
8567 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
8568 that the latter use the processor's character ordering (which is not
8569 ASCII on some targets), whereas the former always use the ASCII
8572 @item @emph{Standard}:
8573 Fortran 77 and later
8578 @item @emph{Syntax}:
8579 @code{RESULT = LLT(STRING_A, STRING_B)}
8581 @item @emph{Arguments}:
8582 @multitable @columnfractions .15 .70
8583 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
8584 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
8587 @item @emph{Return value}:
8588 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
8589 otherwise, based on the ASCII ordering.
8591 @item @emph{Specific names}:
8592 @multitable @columnfractions .20 .20 .20 .25
8593 @item Name @tab Argument @tab Return type @tab Standard
8594 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
8597 @item @emph{See also}:
8598 @ref{LGE}, @ref{LGT}, @ref{LLE}
8604 @section @code{LNBLNK} --- Index of the last non-blank character in a string
8606 @cindex string, find non-blank character
8609 @item @emph{Description}:
8610 Returns the length of a character string, ignoring any trailing blanks.
8611 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
8612 included for backwards compatibility.
8614 @item @emph{Standard}:
8620 @item @emph{Syntax}:
8621 @code{RESULT = LNBLNK(STRING)}
8623 @item @emph{Arguments}:
8624 @multitable @columnfractions .15 .70
8625 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
8626 with @code{INTENT(IN)}
8629 @item @emph{Return value}:
8630 The return value is of @code{INTEGER(kind=4)} type.
8632 @item @emph{See also}:
8633 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
8639 @section @code{LOC} --- Returns the address of a variable
8641 @cindex location of a variable in memory
8644 @item @emph{Description}:
8645 @code{LOC(X)} returns the address of @var{X} as an integer.
8647 @item @emph{Standard}:
8653 @item @emph{Syntax}:
8654 @code{RESULT = LOC(X)}
8656 @item @emph{Arguments}:
8657 @multitable @columnfractions .15 .70
8658 @item @var{X} @tab Variable of any type.
8661 @item @emph{Return value}:
8662 The return value is of type @code{INTEGER}, with a @code{KIND}
8663 corresponding to the size (in bytes) of a memory address on the target
8666 @item @emph{Example}:
8673 end program test_loc
8680 @section @code{LOG} --- Natural logarithm function
8687 @cindex exponential function, inverse
8688 @cindex logarithm function
8689 @cindex natural logarithm function
8692 @item @emph{Description}:
8693 @code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the
8694 logarithm to the base @math{e}.
8696 @item @emph{Standard}:
8697 Fortran 77 and later
8702 @item @emph{Syntax}:
8703 @code{RESULT = LOG(X)}
8705 @item @emph{Arguments}:
8706 @multitable @columnfractions .15 .70
8707 @item @var{X} @tab The type shall be @code{REAL} or
8711 @item @emph{Return value}:
8712 The return value is of type @code{REAL} or @code{COMPLEX}.
8713 The kind type parameter is the same as @var{X}.
8714 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
8715 @math{-\pi \leq \omega \leq \pi}.
8717 @item @emph{Example}:
8720 real(8) :: x = 2.7182818284590451_8
8721 complex :: z = (1.0, 2.0)
8722 x = log(x) ! will yield (approximately) 1
8724 end program test_log
8727 @item @emph{Specific names}:
8728 @multitable @columnfractions .20 .20 .20 .25
8729 @item Name @tab Argument @tab Return type @tab Standard
8730 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
8731 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
8732 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
8733 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
8734 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
8741 @section @code{LOG10} --- Base 10 logarithm function
8745 @cindex exponential function, inverse
8746 @cindex logarithm function with base 10
8747 @cindex base 10 logarithm function
8750 @item @emph{Description}:
8751 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
8753 @item @emph{Standard}:
8754 Fortran 77 and later
8759 @item @emph{Syntax}:
8760 @code{RESULT = LOG10(X)}
8762 @item @emph{Arguments}:
8763 @multitable @columnfractions .15 .70
8764 @item @var{X} @tab The type shall be @code{REAL}.
8767 @item @emph{Return value}:
8768 The return value is of type @code{REAL} or @code{COMPLEX}.
8769 The kind type parameter is the same as @var{X}.
8771 @item @emph{Example}:
8774 real(8) :: x = 10.0_8
8776 end program test_log10
8779 @item @emph{Specific names}:
8780 @multitable @columnfractions .20 .20 .20 .25
8781 @item Name @tab Argument @tab Return type @tab Standard
8782 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
8783 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
8790 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
8795 @cindex Gamma function, logarithm of
8798 @item @emph{Description}:
8799 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
8800 of the Gamma (@math{\Gamma}) function.
8802 @item @emph{Standard}:
8803 Fortran 2008 and later
8808 @item @emph{Syntax}:
8809 @code{X = LOG_GAMMA(X)}
8811 @item @emph{Arguments}:
8812 @multitable @columnfractions .15 .70
8813 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
8814 nor a negative integer.
8817 @item @emph{Return value}:
8818 The return value is of type @code{REAL} of the same kind as @var{X}.
8820 @item @emph{Example}:
8822 program test_log_gamma
8824 x = lgamma(x) ! returns 0.0
8825 end program test_log_gamma
8828 @item @emph{Specific names}:
8829 @multitable @columnfractions .20 .20 .20 .25
8830 @item Name @tab Argument @tab Return type @tab Standard
8831 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
8832 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
8833 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
8836 @item @emph{See also}:
8837 Gamma function: @ref{GAMMA}
8844 @section @code{LOGICAL} --- Convert to logical type
8846 @cindex conversion, to logical
8849 @item @emph{Description}:
8850 Converts one kind of @code{LOGICAL} variable to another.
8852 @item @emph{Standard}:
8853 Fortran 95 and later
8858 @item @emph{Syntax}:
8859 @code{RESULT = LOGICAL(L [, KIND])}
8861 @item @emph{Arguments}:
8862 @multitable @columnfractions .15 .70
8863 @item @var{L} @tab The type shall be @code{LOGICAL}.
8864 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8865 expression indicating the kind parameter of the result.
8868 @item @emph{Return value}:
8869 The return value is a @code{LOGICAL} value equal to @var{L}, with a
8870 kind corresponding to @var{KIND}, or of the default logical kind if
8871 @var{KIND} is not given.
8873 @item @emph{See also}:
8874 @ref{INT}, @ref{REAL}, @ref{CMPLX}
8880 @section @code{LONG} --- Convert to integer type
8882 @cindex conversion, to integer
8885 @item @emph{Description}:
8886 Convert to a @code{KIND=4} integer type, which is the same size as a C
8887 @code{long} integer. This is equivalent to the standard @code{INT}
8888 intrinsic with an optional argument of @code{KIND=4}, and is only
8889 included for backwards compatibility.
8891 @item @emph{Standard}:
8897 @item @emph{Syntax}:
8898 @code{RESULT = LONG(A)}
8900 @item @emph{Arguments}:
8901 @multitable @columnfractions .15 .70
8902 @item @var{A} @tab Shall be of type @code{INTEGER},
8903 @code{REAL}, or @code{COMPLEX}.
8906 @item @emph{Return value}:
8907 The return value is a @code{INTEGER(4)} variable.
8909 @item @emph{See also}:
8910 @ref{INT}, @ref{INT2}, @ref{INT8}
8916 @section @code{LSHIFT} --- Left shift bits
8918 @cindex bits, shift left
8921 @item @emph{Description}:
8922 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
8923 bits shifted left by @var{SHIFT} places. If the absolute value of
8924 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
8925 Bits shifted out from the left end are lost; zeros are shifted in from
8928 This function has been superseded by the @code{ISHFT} intrinsic, which
8929 is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
8930 which is standard in Fortran 2008 and later.
8932 @item @emph{Standard}:
8938 @item @emph{Syntax}:
8939 @code{RESULT = LSHIFT(I, SHIFT)}
8941 @item @emph{Arguments}:
8942 @multitable @columnfractions .15 .70
8943 @item @var{I} @tab The type shall be @code{INTEGER}.
8944 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8947 @item @emph{Return value}:
8948 The return value is of type @code{INTEGER} and of the same kind as
8951 @item @emph{See also}:
8952 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}, @ref{SHIFTA}, @ref{SHIFTL},
8960 @section @code{LSTAT} --- Get file status
8962 @cindex file system, file status
8965 @item @emph{Description}:
8966 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
8967 symbolic link, then the link itself is statted, not the file that it
8970 The elements in @code{VALUES} are the same as described by @ref{STAT}.
8972 This intrinsic is provided in both subroutine and function forms;
8973 however, only one form can be used in any given program unit.
8975 @item @emph{Standard}:
8979 Subroutine, function
8981 @item @emph{Syntax}:
8982 @multitable @columnfractions .80
8983 @item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
8984 @item @code{STATUS = LSTAT(NAME, VALUES)}
8987 @item @emph{Arguments}:
8988 @multitable @columnfractions .15 .70
8989 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
8990 kind, a valid path within the file system.
8991 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
8992 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
8993 Returns 0 on success and a system specific error code otherwise.
8996 @item @emph{Example}:
8997 See @ref{STAT} for an example.
8999 @item @emph{See also}:
9000 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
9006 @section @code{LTIME} --- Convert time to local time info
9008 @cindex time, conversion to local time info
9011 @item @emph{Description}:
9012 Given a system time value @var{TIME} (as provided by the @code{TIME8}
9013 intrinsic), fills @var{VALUES} with values extracted from it appropriate
9014 to the local time zone using @code{localtime(3)}.
9016 @item @emph{Standard}:
9022 @item @emph{Syntax}:
9023 @code{CALL LTIME(TIME, VALUES)}
9025 @item @emph{Arguments}:
9026 @multitable @columnfractions .15 .70
9027 @item @var{TIME} @tab An @code{INTEGER} scalar expression
9028 corresponding to a system time, with @code{INTENT(IN)}.
9029 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
9030 with @code{INTENT(OUT)}.
9033 @item @emph{Return value}:
9034 The elements of @var{VALUES} are assigned as follows:
9036 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
9038 @item Minutes after the hour, range 0--59
9039 @item Hours past midnight, range 0--23
9040 @item Day of month, range 0--31
9041 @item Number of months since January, range 0--12
9042 @item Years since 1900
9043 @item Number of days since Sunday, range 0--6
9044 @item Days since January 1
9045 @item Daylight savings indicator: positive if daylight savings is in
9046 effect, zero if not, and negative if the information is not available.
9049 @item @emph{See also}:
9050 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
9057 @section @code{MALLOC} --- Allocate dynamic memory
9059 @cindex pointer, cray
9062 @item @emph{Description}:
9063 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
9064 returns the address of the allocated memory. The @code{MALLOC} intrinsic
9065 is an extension intended to be used with Cray pointers, and is provided
9066 in GNU Fortran to allow the user to compile legacy code. For new code
9067 using Fortran 95 pointers, the memory allocation intrinsic is
9070 @item @emph{Standard}:
9076 @item @emph{Syntax}:
9077 @code{PTR = MALLOC(SIZE)}
9079 @item @emph{Arguments}:
9080 @multitable @columnfractions .15 .70
9081 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
9084 @item @emph{Return value}:
9085 The return value is of type @code{INTEGER(K)}, with @var{K} such that
9086 variables of type @code{INTEGER(K)} have the same size as
9087 C pointers (@code{sizeof(void *)}).
9089 @item @emph{Example}:
9090 The following example demonstrates the use of @code{MALLOC} and
9091 @code{FREE} with Cray pointers.
9100 ptr_x = malloc(20*8)
9102 x(i) = sqrt(1.0d0 / i)
9110 end program test_malloc
9113 @item @emph{See also}:
9120 @section @code{MASKL} --- Left justified mask
9122 @cindex mask, left justified
9125 @item @emph{Description}:
9126 @code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
9127 remaining bits set to 0.
9129 @item @emph{Standard}:
9130 Fortran 2008 and later
9135 @item @emph{Syntax}:
9136 @code{RESULT = MASKL(I[, KIND])}
9138 @item @emph{Arguments}:
9139 @multitable @columnfractions .15 .70
9140 @item @var{I} @tab Shall be of type @code{INTEGER}.
9141 @item @var{KIND} @tab Shall be a scalar constant expression of type
9145 @item @emph{Return value}:
9146 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
9147 specifies the kind value of the return type; otherwise, it is of the
9148 default integer kind.
9150 @item @emph{See also}:
9157 @section @code{MASKR} --- Right justified mask
9159 @cindex mask, right justified
9162 @item @emph{Description}:
9163 @code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
9164 remaining bits set to 0.
9166 @item @emph{Standard}:
9167 Fortran 2008 and later
9172 @item @emph{Syntax}:
9173 @code{RESULT = MASKR(I[, KIND])}
9175 @item @emph{Arguments}:
9176 @multitable @columnfractions .15 .70
9177 @item @var{I} @tab Shall be of type @code{INTEGER}.
9178 @item @var{KIND} @tab Shall be a scalar constant expression of type
9182 @item @emph{Return value}:
9183 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
9184 specifies the kind value of the return type; otherwise, it is of the
9185 default integer kind.
9187 @item @emph{See also}:
9194 @section @code{MATMUL} --- matrix multiplication
9196 @cindex matrix multiplication
9197 @cindex product, matrix
9200 @item @emph{Description}:
9201 Performs a matrix multiplication on numeric or logical arguments.
9203 @item @emph{Standard}:
9204 Fortran 95 and later
9207 Transformational function
9209 @item @emph{Syntax}:
9210 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
9212 @item @emph{Arguments}:
9213 @multitable @columnfractions .15 .70
9214 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
9215 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
9217 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
9218 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
9219 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
9220 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
9221 equal to the last (or only) dimension of @var{MATRIX_A}.
9224 @item @emph{Return value}:
9225 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
9226 kind of the result follow the usual type and kind promotion rules, as
9227 for the @code{*} or @code{.AND.} operators.
9229 @item @emph{See also}:
9235 @section @code{MAX} --- Maximum value of an argument list
9242 @cindex maximum value
9245 @item @emph{Description}:
9246 Returns the argument with the largest (most positive) value.
9248 @item @emph{Standard}:
9249 Fortran 77 and later
9254 @item @emph{Syntax}:
9255 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
9257 @item @emph{Arguments}:
9258 @multitable @columnfractions .15 .70
9259 @item @var{A1} @tab The type shall be @code{INTEGER} or
9261 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
9262 as @var{A1}. (As a GNU extension, arguments of different kinds are
9266 @item @emph{Return value}:
9267 The return value corresponds to the maximum value among the arguments,
9268 and has the same type and kind as the first argument.
9270 @item @emph{Specific names}:
9271 @multitable @columnfractions .20 .20 .20 .25
9272 @item Name @tab Argument @tab Return type @tab Standard
9273 @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
9274 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
9275 @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
9276 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
9277 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
9280 @item @emph{See also}:
9281 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
9288 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
9289 @fnindex MAXEXPONENT
9290 @cindex model representation, maximum exponent
9293 @item @emph{Description}:
9294 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
9297 @item @emph{Standard}:
9298 Fortran 95 and later
9303 @item @emph{Syntax}:
9304 @code{RESULT = MAXEXPONENT(X)}
9306 @item @emph{Arguments}:
9307 @multitable @columnfractions .15 .70
9308 @item @var{X} @tab Shall be of type @code{REAL}.
9311 @item @emph{Return value}:
9312 The return value is of type @code{INTEGER} and of the default integer
9315 @item @emph{Example}:
9321 print *, minexponent(x), maxexponent(x)
9322 print *, minexponent(y), maxexponent(y)
9323 end program exponents
9330 @section @code{MAXLOC} --- Location of the maximum value within an array
9332 @cindex array, location of maximum element
9335 @item @emph{Description}:
9336 Determines the location of the element in the array with the maximum
9337 value, or, if the @var{DIM} argument is supplied, determines the
9338 locations of the maximum element along each row of the array in the
9339 @var{DIM} direction. If @var{MASK} is present, only the elements for
9340 which @var{MASK} is @code{.TRUE.} are considered. If more than one
9341 element in the array has the maximum value, the location returned is
9342 that of the first such element in array element order. If the array has
9343 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
9344 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
9345 and all of the elements of @var{MASK} along a given row are zero, the
9346 result value for that row is zero.
9348 @item @emph{Standard}:
9349 Fortran 95 and later
9352 Transformational function
9354 @item @emph{Syntax}:
9355 @multitable @columnfractions .80
9356 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
9357 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
9360 @item @emph{Arguments}:
9361 @multitable @columnfractions .15 .70
9362 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
9364 @item @var{DIM} @tab (Optional) Shall be a scalar of type
9365 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
9366 inclusive. It may not be an optional dummy argument.
9367 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
9368 and conformable with @var{ARRAY}.
9371 @item @emph{Return value}:
9372 If @var{DIM} is absent, the result is a rank-one array with a length
9373 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
9374 is an array with a rank one less than the rank of @var{ARRAY}, and a
9375 size corresponding to the size of @var{ARRAY} with the @var{DIM}
9376 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
9377 of one, the result is a scalar. In all cases, the result is of default
9378 @code{INTEGER} type.
9380 @item @emph{See also}:
9381 @ref{MAX}, @ref{MAXVAL}
9388 @section @code{MAXVAL} --- Maximum value of an array
9390 @cindex array, maximum value
9391 @cindex maximum value
9394 @item @emph{Description}:
9395 Determines the maximum value of the elements in an array value, or, if
9396 the @var{DIM} argument is supplied, determines the maximum value along
9397 each row of the array in the @var{DIM} direction. If @var{MASK} is
9398 present, only the elements for which @var{MASK} is @code{.TRUE.} are
9399 considered. If the array has zero size, or all of the elements of
9400 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
9401 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
9404 @item @emph{Standard}:
9405 Fortran 95 and later
9408 Transformational function
9410 @item @emph{Syntax}:
9411 @multitable @columnfractions .80
9412 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
9413 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
9416 @item @emph{Arguments}:
9417 @multitable @columnfractions .15 .70
9418 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
9420 @item @var{DIM} @tab (Optional) Shall be a scalar of type
9421 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
9422 inclusive. It may not be an optional dummy argument.
9423 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
9424 and conformable with @var{ARRAY}.
9427 @item @emph{Return value}:
9428 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
9429 is a scalar. If @var{DIM} is present, the result is an array with a
9430 rank one less than the rank of @var{ARRAY}, and a size corresponding to
9431 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
9432 cases, the result is of the same type and kind as @var{ARRAY}.
9434 @item @emph{See also}:
9435 @ref{MAX}, @ref{MAXLOC}
9441 @section @code{MCLOCK} --- Time function
9443 @cindex time, clock ticks
9447 @item @emph{Description}:
9448 Returns the number of clock ticks since the start of the process, based
9449 on the function @code{clock(3)} in the C standard library.
9451 This intrinsic is not fully portable, such as to systems with 32-bit
9452 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
9453 the values returned by this intrinsic might be, or become, negative, or
9454 numerically less than previous values, during a single run of the
9457 @item @emph{Standard}:
9463 @item @emph{Syntax}:
9464 @code{RESULT = MCLOCK()}
9466 @item @emph{Return value}:
9467 The return value is a scalar of type @code{INTEGER(4)}, equal to the
9468 number of clock ticks since the start of the process, or @code{-1} if
9469 the system does not support @code{clock(3)}.
9471 @item @emph{See also}:
9472 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
9479 @section @code{MCLOCK8} --- Time function (64-bit)
9481 @cindex time, clock ticks
9485 @item @emph{Description}:
9486 Returns the number of clock ticks since the start of the process, based
9487 on the function @code{clock(3)} in the C standard library.
9489 @emph{Warning:} this intrinsic does not increase the range of the timing
9490 values over that returned by @code{clock(3)}. On a system with a 32-bit
9491 @code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though
9492 it is converted to a 64-bit @code{INTEGER(8)} value. That means
9493 overflows of the 32-bit value can still occur. Therefore, the values
9494 returned by this intrinsic might be or become negative or numerically
9495 less than previous values during a single run of the compiled program.
9497 @item @emph{Standard}:
9503 @item @emph{Syntax}:
9504 @code{RESULT = MCLOCK8()}
9506 @item @emph{Return value}:
9507 The return value is a scalar of type @code{INTEGER(8)}, equal to the
9508 number of clock ticks since the start of the process, or @code{-1} if
9509 the system does not support @code{clock(3)}.
9511 @item @emph{See also}:
9512 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
9519 @section @code{MERGE} --- Merge variables
9521 @cindex array, merge arrays
9522 @cindex array, combine arrays
9525 @item @emph{Description}:
9526 Select values from two arrays according to a logical mask. The result
9527 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
9528 @var{FSOURCE} if it is @code{.FALSE.}.
9530 @item @emph{Standard}:
9531 Fortran 95 and later
9536 @item @emph{Syntax}:
9537 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
9539 @item @emph{Arguments}:
9540 @multitable @columnfractions .15 .70
9541 @item @var{TSOURCE} @tab May be of any type.
9542 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
9544 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
9547 @item @emph{Return value}:
9548 The result is of the same type and type parameters as @var{TSOURCE}.
9555 @section @code{MERGE_BITS} --- Merge of bits under mask
9560 @item @emph{Description}:
9561 @code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
9562 as determined by the mask. The i-th bit of the result is equal to the
9563 i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
9564 the i-th bit of @var{J} otherwise.
9566 @item @emph{Standard}:
9567 Fortran 2008 and later
9572 @item @emph{Syntax}:
9573 @code{RESULT = MERGE_BITS(I, J, MASK)}
9575 @item @emph{Arguments}:
9576 @multitable @columnfractions .15 .70
9577 @item @var{I} @tab Shall be of type @code{INTEGER}.
9578 @item @var{J} @tab Shall be of type @code{INTEGER} and of the same
9580 @item @var{MASK} @tab Shall be of type @code{INTEGER} and of the same
9584 @item @emph{Return value}:
9585 The result is of the same type and kind as @var{I}.
9592 @section @code{MIN} --- Minimum value of an argument list
9599 @cindex minimum value
9602 @item @emph{Description}:
9603 Returns the argument with the smallest (most negative) value.
9605 @item @emph{Standard}:
9606 Fortran 77 and later
9611 @item @emph{Syntax}:
9612 @code{RESULT = MIN(A1, A2 [, A3, ...])}
9614 @item @emph{Arguments}:
9615 @multitable @columnfractions .15 .70
9616 @item @var{A1} @tab The type shall be @code{INTEGER} or
9618 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
9619 as @var{A1}. (As a GNU extension, arguments of different kinds are
9623 @item @emph{Return value}:
9624 The return value corresponds to the maximum value among the arguments,
9625 and has the same type and kind as the first argument.
9627 @item @emph{Specific names}:
9628 @multitable @columnfractions .20 .20 .20 .25
9629 @item Name @tab Argument @tab Return type @tab Standard
9630 @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
9631 @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
9632 @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
9633 @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
9634 @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
9637 @item @emph{See also}:
9638 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
9644 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
9645 @fnindex MINEXPONENT
9646 @cindex model representation, minimum exponent
9649 @item @emph{Description}:
9650 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
9653 @item @emph{Standard}:
9654 Fortran 95 and later
9659 @item @emph{Syntax}:
9660 @code{RESULT = MINEXPONENT(X)}
9662 @item @emph{Arguments}:
9663 @multitable @columnfractions .15 .70
9664 @item @var{X} @tab Shall be of type @code{REAL}.
9667 @item @emph{Return value}:
9668 The return value is of type @code{INTEGER} and of the default integer
9671 @item @emph{Example}:
9672 See @code{MAXEXPONENT} for an example.
9678 @section @code{MINLOC} --- Location of the minimum value within an array
9680 @cindex array, location of minimum element
9683 @item @emph{Description}:
9684 Determines the location of the element in the array with the minimum
9685 value, or, if the @var{DIM} argument is supplied, determines the
9686 locations of the minimum element along each row of the array in the
9687 @var{DIM} direction. If @var{MASK} is present, only the elements for
9688 which @var{MASK} is @code{.TRUE.} are considered. If more than one
9689 element in the array has the minimum value, the location returned is
9690 that of the first such element in array element order. If the array has
9691 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
9692 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
9693 and all of the elements of @var{MASK} along a given row are zero, the
9694 result value for that row is zero.
9696 @item @emph{Standard}:
9697 Fortran 95 and later
9700 Transformational function
9702 @item @emph{Syntax}:
9703 @multitable @columnfractions .80
9704 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
9705 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
9708 @item @emph{Arguments}:
9709 @multitable @columnfractions .15 .70
9710 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
9712 @item @var{DIM} @tab (Optional) Shall be a scalar of type
9713 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
9714 inclusive. It may not be an optional dummy argument.
9715 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
9716 and conformable with @var{ARRAY}.
9719 @item @emph{Return value}:
9720 If @var{DIM} is absent, the result is a rank-one array with a length
9721 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
9722 is an array with a rank one less than the rank of @var{ARRAY}, and a
9723 size corresponding to the size of @var{ARRAY} with the @var{DIM}
9724 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
9725 of one, the result is a scalar. In all cases, the result is of default
9726 @code{INTEGER} type.
9728 @item @emph{See also}:
9729 @ref{MIN}, @ref{MINVAL}
9736 @section @code{MINVAL} --- Minimum value of an array
9738 @cindex array, minimum value
9739 @cindex minimum value
9742 @item @emph{Description}:
9743 Determines the minimum value of the elements in an array value, or, if
9744 the @var{DIM} argument is supplied, determines the minimum value along
9745 each row of the array in the @var{DIM} direction. If @var{MASK} is
9746 present, only the elements for which @var{MASK} is @code{.TRUE.} are
9747 considered. If the array has zero size, or all of the elements of
9748 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
9749 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
9750 @var{ARRAY} is of character type.
9752 @item @emph{Standard}:
9753 Fortran 95 and later
9756 Transformational function
9758 @item @emph{Syntax}:
9759 @multitable @columnfractions .80
9760 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
9761 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
9764 @item @emph{Arguments}:
9765 @multitable @columnfractions .15 .70
9766 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
9768 @item @var{DIM} @tab (Optional) Shall be a scalar of type
9769 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
9770 inclusive. It may not be an optional dummy argument.
9771 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
9772 and conformable with @var{ARRAY}.
9775 @item @emph{Return value}:
9776 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
9777 is a scalar. If @var{DIM} is present, the result is an array with a
9778 rank one less than the rank of @var{ARRAY}, and a size corresponding to
9779 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
9780 cases, the result is of the same type and kind as @var{ARRAY}.
9782 @item @emph{See also}:
9783 @ref{MIN}, @ref{MINLOC}
9790 @section @code{MOD} --- Remainder function
9795 @cindex division, remainder
9798 @item @emph{Description}:
9799 @code{MOD(A,P)} computes the remainder of the division of A by P@.
9801 @item @emph{Standard}:
9802 Fortran 77 and later
9807 @item @emph{Syntax}:
9808 @code{RESULT = MOD(A, P)}
9810 @item @emph{Arguments}:
9811 @multitable @columnfractions .15 .70
9812 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
9813 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
9814 and not equal to zero.
9817 @item @emph{Return value}:
9818 The return value is the result of @code{A - (INT(A/P) * P)}. The type
9819 and kind of the return value is the same as that of the arguments. The
9820 returned value has the same sign as A and a magnitude less than the
9823 @item @emph{Example}:
9827 print *, mod(17.5,5.5)
9828 print *, mod(17.5d0,5.5)
9829 print *, mod(17.5,5.5d0)
9832 print *, mod(-17.5,5.5)
9833 print *, mod(-17.5d0,5.5)
9834 print *, mod(-17.5,5.5d0)
9837 print *, mod(17.5,-5.5)
9838 print *, mod(17.5d0,-5.5)
9839 print *, mod(17.5,-5.5d0)
9840 end program test_mod
9843 @item @emph{Specific names}:
9844 @multitable @columnfractions .20 .20 .20 .25
9845 @item Name @tab Arguments @tab Return type @tab Standard
9846 @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
9847 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
9848 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
9851 @item @emph{See also}:
9859 @section @code{MODULO} --- Modulo function
9862 @cindex division, modulo
9865 @item @emph{Description}:
9866 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
9868 @item @emph{Standard}:
9869 Fortran 95 and later
9874 @item @emph{Syntax}:
9875 @code{RESULT = MODULO(A, P)}
9877 @item @emph{Arguments}:
9878 @multitable @columnfractions .15 .70
9879 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
9880 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}.
9881 It shall not be zero.
9884 @item @emph{Return value}:
9885 The type and kind of the result are those of the arguments.
9887 @item If @var{A} and @var{P} are of type @code{INTEGER}:
9888 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
9889 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
9891 @item If @var{A} and @var{P} are of type @code{REAL}:
9892 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
9894 The returned value has the same sign as P and a magnitude less than
9897 @item @emph{Example}:
9900 print *, modulo(17,3)
9901 print *, modulo(17.5,5.5)
9903 print *, modulo(-17,3)
9904 print *, modulo(-17.5,5.5)
9906 print *, modulo(17,-3)
9907 print *, modulo(17.5,-5.5)
9911 @item @emph{See also}:
9919 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
9921 @cindex moving allocation
9922 @cindex allocation, moving
9925 @item @emph{Description}:
9926 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
9927 @var{TO}. @var{FROM} will become deallocated in the process.
9929 @item @emph{Standard}:
9930 Fortran 2003 and later
9935 @item @emph{Syntax}:
9936 @code{CALL MOVE_ALLOC(FROM, TO)}
9938 @item @emph{Arguments}:
9939 @multitable @columnfractions .15 .70
9940 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
9941 of any type and kind.
9942 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
9943 of the same type, kind and rank as @var{FROM}.
9946 @item @emph{Return value}:
9949 @item @emph{Example}:
9951 program test_move_alloc
9952 integer, allocatable :: a(:), b(:)
9956 call move_alloc(a, b)
9957 print *, allocated(a), allocated(b)
9959 end program test_move_alloc
9966 @section @code{MVBITS} --- Move bits from one integer to another
9971 @item @emph{Description}:
9972 Moves @var{LEN} bits from positions @var{FROMPOS} through
9973 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
9974 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
9975 affected by the movement of bits is unchanged. The values of
9976 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
9977 @code{BIT_SIZE(FROM)}.
9979 @item @emph{Standard}:
9980 Fortran 95 and later
9983 Elemental subroutine
9985 @item @emph{Syntax}:
9986 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
9988 @item @emph{Arguments}:
9989 @multitable @columnfractions .15 .70
9990 @item @var{FROM} @tab The type shall be @code{INTEGER}.
9991 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
9992 @item @var{LEN} @tab The type shall be @code{INTEGER}.
9993 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
9994 same kind as @var{FROM}.
9995 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
9998 @item @emph{See also}:
9999 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
10005 @section @code{NEAREST} --- Nearest representable number
10007 @cindex real number, nearest different
10008 @cindex floating point, nearest different
10011 @item @emph{Description}:
10012 @code{NEAREST(X, S)} returns the processor-representable number nearest
10013 to @code{X} in the direction indicated by the sign of @code{S}.
10015 @item @emph{Standard}:
10016 Fortran 95 and later
10018 @item @emph{Class}:
10021 @item @emph{Syntax}:
10022 @code{RESULT = NEAREST(X, S)}
10024 @item @emph{Arguments}:
10025 @multitable @columnfractions .15 .70
10026 @item @var{X} @tab Shall be of type @code{REAL}.
10027 @item @var{S} @tab Shall be of type @code{REAL} and
10031 @item @emph{Return value}:
10032 The return value is of the same type as @code{X}. If @code{S} is
10033 positive, @code{NEAREST} returns the processor-representable number
10034 greater than @code{X} and nearest to it. If @code{S} is negative,
10035 @code{NEAREST} returns the processor-representable number smaller than
10036 @code{X} and nearest to it.
10038 @item @emph{Example}:
10040 program test_nearest
10042 x = nearest(42.0, 1.0)
10043 y = nearest(42.0, -1.0)
10044 write (*,"(3(G20.15))") x, y, x - y
10045 end program test_nearest
10052 @section @code{NEW_LINE} --- New line character
10055 @cindex output, newline
10058 @item @emph{Description}:
10059 @code{NEW_LINE(C)} returns the new-line character.
10061 @item @emph{Standard}:
10062 Fortran 2003 and later
10064 @item @emph{Class}:
10067 @item @emph{Syntax}:
10068 @code{RESULT = NEW_LINE(C)}
10070 @item @emph{Arguments}:
10071 @multitable @columnfractions .15 .70
10072 @item @var{C} @tab The argument shall be a scalar or array of the
10073 type @code{CHARACTER}.
10076 @item @emph{Return value}:
10077 Returns a @var{CHARACTER} scalar of length one with the new-line character of
10078 the same kind as parameter @var{C}.
10080 @item @emph{Example}:
10084 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
10085 end program newline
10092 @section @code{NINT} --- Nearest whole number
10095 @cindex rounding, nearest whole number
10098 @item @emph{Description}:
10099 @code{NINT(A)} rounds its argument to the nearest whole number.
10101 @item @emph{Standard}:
10102 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
10104 @item @emph{Class}:
10107 @item @emph{Syntax}:
10108 @code{RESULT = NINT(A [, KIND])}
10110 @item @emph{Arguments}:
10111 @multitable @columnfractions .15 .70
10112 @item @var{A} @tab The type of the argument shall be @code{REAL}.
10113 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10114 expression indicating the kind parameter of the result.
10117 @item @emph{Return value}:
10118 Returns @var{A} with the fractional portion of its magnitude eliminated by
10119 rounding to the nearest whole number and with its sign preserved,
10120 converted to an @code{INTEGER} of the default kind.
10122 @item @emph{Example}:
10129 print *, nint(x4), idnint(x8)
10130 end program test_nint
10133 @item @emph{Specific names}:
10134 @multitable @columnfractions .20 .20 .20 .25
10135 @item Name @tab Argument @tab Return Type @tab Standard
10136 @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later
10137 @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later
10140 @item @emph{See also}:
10141 @ref{CEILING}, @ref{FLOOR}
10148 @section @code{NORM2} --- Euclidean vector norms
10150 @cindex Euclidean vector norm
10151 @cindex L2 vector norm
10152 @cindex norm, Euclidean
10155 @item @emph{Description}:
10156 Calculates the Euclidean vector norm (@math{L_2} norm) of
10157 of @var{ARRAY} along dimension @var{DIM}.
10159 @item @emph{Standard}:
10160 Fortran 2008 and later
10162 @item @emph{Class}:
10163 Transformational function
10165 @item @emph{Syntax}:
10166 @multitable @columnfractions .80
10167 @item @code{RESULT = NORM2(ARRAY[, DIM])}
10170 @item @emph{Arguments}:
10171 @multitable @columnfractions .15 .70
10172 @item @var{ARRAY} @tab Shall be an array of type @code{REAL}
10173 @item @var{DIM} @tab (Optional) shall be a scalar of type
10174 @code{INTEGER} with a value in the range from 1 to n, where n
10175 equals the rank of @var{ARRAY}.
10178 @item @emph{Return value}:
10179 The result is of the same type as @var{ARRAY}.
10181 If @var{DIM} is absent, a scalar with the square root of the sum of all
10182 elements in @var{ARRAY} squared is returned. Otherwise, an array of
10183 rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
10184 shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
10187 @item @emph{Example}:
10190 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
10191 print *, NORM2(x) ! = sqrt(55.) ~ 7.416
10199 @section @code{NOT} --- Logical negation
10201 @cindex bits, negate
10202 @cindex bitwise logical not
10203 @cindex logical not, bitwise
10206 @item @emph{Description}:
10207 @code{NOT} returns the bitwise Boolean inverse of @var{I}.
10209 @item @emph{Standard}:
10210 Fortran 95 and later
10212 @item @emph{Class}:
10215 @item @emph{Syntax}:
10216 @code{RESULT = NOT(I)}
10218 @item @emph{Arguments}:
10219 @multitable @columnfractions .15 .70
10220 @item @var{I} @tab The type shall be @code{INTEGER}.
10223 @item @emph{Return value}:
10224 The return type is @code{INTEGER}, of the same kind as the
10227 @item @emph{See also}:
10228 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
10235 @section @code{NULL} --- Function that returns an disassociated pointer
10237 @cindex pointer, status
10238 @cindex pointer, disassociated
10241 @item @emph{Description}:
10242 Returns a disassociated pointer.
10244 If @var{MOLD} is present, a disassociated pointer of the same type is
10245 returned, otherwise the type is determined by context.
10247 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
10248 includes cases where it is required.
10250 @item @emph{Standard}:
10251 Fortran 95 and later
10253 @item @emph{Class}:
10254 Transformational function
10256 @item @emph{Syntax}:
10257 @code{PTR => NULL([MOLD])}
10259 @item @emph{Arguments}:
10260 @multitable @columnfractions .15 .70
10261 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
10262 status and of any type.
10265 @item @emph{Return value}:
10266 A disassociated pointer.
10268 @item @emph{Example}:
10270 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
10273 @item @emph{See also}:
10280 @section @code{NUM_IMAGES} --- Function that returns the number of images
10281 @fnindex NUM_IMAGES
10282 @cindex coarray, @code{NUM_IMAGES}
10283 @cindex images, number of
10286 @item @emph{Description}:
10287 Returns the number of images.
10289 @item @emph{Standard}:
10290 Fortran 2008 and later. With @var{DISTANCE} or @var{FAILED} argument,
10291 Technical Specification (TS) 18508 or later
10294 @item @emph{Class}:
10295 Transformational function
10297 @item @emph{Syntax}:
10298 @code{RESULT = NUM_IMAGES(DISTANCE, FAILED)}
10300 @item @emph{Arguments}:
10301 @multitable @columnfractions .15 .70
10302 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
10303 @item @var{FAILED} @tab (optional, intent(in)) Scalar logical expression
10306 @item @emph{Return value}:
10307 Scalar default-kind integer. If @var{DISTANCE} is not present or has value 0,
10308 the number of images in the current team is returned. For values smaller or
10309 equal distance to the initial team, it returns the number of images index
10310 on the ancestor team which has a distance of @var{DISTANCE} from the invoking
10311 team. If @var{DISTANCE} is larger than the distance to the initial team, the
10312 number of images of the initial team is returned. If @var{FAILED} is not present
10313 the total number of images is returned; if it has the value @code{.TRUE.},
10314 the number of failed images is returned, otherwise, the number of images which
10315 do have not the failed status.
10317 @item @emph{Example}:
10319 INTEGER :: value[*]
10321 value = THIS_IMAGE()
10323 IF (THIS_IMAGE() == 1) THEN
10324 DO i = 1, NUM_IMAGES()
10325 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
10330 @item @emph{See also}:
10331 @ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
10337 @section @code{OR} --- Bitwise logical OR
10339 @cindex bitwise logical or
10340 @cindex logical or, bitwise
10343 @item @emph{Description}:
10344 Bitwise logical @code{OR}.
10346 This intrinsic routine is provided for backwards compatibility with
10347 GNU Fortran 77. For integer arguments, programmers should consider
10348 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
10350 @item @emph{Standard}:
10353 @item @emph{Class}:
10356 @item @emph{Syntax}:
10357 @code{RESULT = OR(I, J)}
10359 @item @emph{Arguments}:
10360 @multitable @columnfractions .15 .70
10361 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
10362 type or a scalar @code{LOGICAL} type.
10363 @item @var{J} @tab The type shall be the same as the type of @var{J}.
10366 @item @emph{Return value}:
10367 The return type is either a scalar @code{INTEGER} or a scalar
10368 @code{LOGICAL}. If the kind type parameters differ, then the
10369 smaller kind type is implicitly converted to larger kind, and the
10370 return has the larger kind.
10372 @item @emph{Example}:
10375 LOGICAL :: T = .TRUE., F = .FALSE.
10377 DATA a / Z'F' /, b / Z'3' /
10379 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
10380 WRITE (*,*) OR(a, b)
10384 @item @emph{See also}:
10385 Fortran 95 elemental function: @ref{IOR}
10391 @section @code{PACK} --- Pack an array into an array of rank one
10393 @cindex array, packing
10394 @cindex array, reduce dimension
10395 @cindex array, gather elements
10398 @item @emph{Description}:
10399 Stores the elements of @var{ARRAY} in an array of rank one.
10401 The beginning of the resulting array is made up of elements whose @var{MASK}
10402 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
10405 @item @emph{Standard}:
10406 Fortran 95 and later
10408 @item @emph{Class}:
10409 Transformational function
10411 @item @emph{Syntax}:
10412 @code{RESULT = PACK(ARRAY, MASK[,VECTOR])}
10414 @item @emph{Arguments}:
10415 @multitable @columnfractions .15 .70
10416 @item @var{ARRAY} @tab Shall be an array of any type.
10417 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
10418 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
10420 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
10421 as @var{ARRAY} and of rank one. If present, the number of elements in
10422 @var{VECTOR} shall be equal to or greater than the number of true elements
10423 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
10424 @var{VECTOR} shall be equal to or greater than the number of elements in
10428 @item @emph{Return value}:
10429 The result is an array of rank one and the same type as that of @var{ARRAY}.
10430 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
10431 number of @code{TRUE} values in @var{MASK} otherwise.
10433 @item @emph{Example}:
10434 Gathering nonzero elements from an array:
10436 PROGRAM test_pack_1
10438 m = (/ 1, 0, 0, 0, 5, 0 /)
10439 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
10443 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
10445 PROGRAM test_pack_2
10447 m = (/ 1, 0, 0, 2 /)
10448 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
10452 @item @emph{See also}:
10459 @section @code{PARITY} --- Reduction with exclusive OR
10462 @cindex Reduction, XOR
10463 @cindex XOR reduction
10466 @item @emph{Description}:
10467 Calculates the parity, i.e. the reduction using @code{.XOR.},
10468 of @var{MASK} along dimension @var{DIM}.
10470 @item @emph{Standard}:
10471 Fortran 2008 and later
10473 @item @emph{Class}:
10474 Transformational function
10476 @item @emph{Syntax}:
10477 @multitable @columnfractions .80
10478 @item @code{RESULT = PARITY(MASK[, DIM])}
10481 @item @emph{Arguments}:
10482 @multitable @columnfractions .15 .70
10483 @item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL}
10484 @item @var{DIM} @tab (Optional) shall be a scalar of type
10485 @code{INTEGER} with a value in the range from 1 to n, where n
10486 equals the rank of @var{MASK}.
10489 @item @emph{Return value}:
10490 The result is of the same type as @var{MASK}.
10492 If @var{DIM} is absent, a scalar with the parity of all elements in
10493 @var{MASK} is returned, i.e. true if an odd number of elements is
10494 @code{.true.} and false otherwise. If @var{DIM} is present, an array
10495 of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
10496 and a shape similar to that of @var{MASK} with dimension @var{DIM}
10497 dropped is returned.
10499 @item @emph{Example}:
10502 LOGICAL :: x(2) = [ .true., .false. ]
10503 print *, PARITY(x) ! prints "T" (true).
10511 @section @code{PERROR} --- Print system error message
10513 @cindex system, error handling
10516 @item @emph{Description}:
10517 Prints (on the C @code{stderr} stream) a newline-terminated error
10518 message corresponding to the last system error. This is prefixed by
10519 @var{STRING}, a colon and a space. See @code{perror(3)}.
10521 @item @emph{Standard}:
10524 @item @emph{Class}:
10527 @item @emph{Syntax}:
10528 @code{CALL PERROR(STRING)}
10530 @item @emph{Arguments}:
10531 @multitable @columnfractions .15 .70
10532 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
10536 @item @emph{See also}:
10543 @section @code{POPCNT} --- Number of bits set
10545 @cindex binary representation
10549 @item @emph{Description}:
10550 @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
10551 representation of @code{I}.
10553 @item @emph{Standard}:
10554 Fortran 2008 and later
10556 @item @emph{Class}:
10559 @item @emph{Syntax}:
10560 @code{RESULT = POPCNT(I)}
10562 @item @emph{Arguments}:
10563 @multitable @columnfractions .15 .70
10564 @item @var{I} @tab Shall be of type @code{INTEGER}.
10567 @item @emph{Return value}:
10568 The return value is of type @code{INTEGER} and of the default integer
10571 @item @emph{See also}:
10572 @ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ}
10574 @item @emph{Example}:
10576 program test_population
10577 print *, popcnt(127), poppar(127)
10578 print *, popcnt(huge(0_4)), poppar(huge(0_4))
10579 print *, popcnt(huge(0_8)), poppar(huge(0_8))
10580 end program test_population
10586 @section @code{POPPAR} --- Parity of the number of bits set
10588 @cindex binary representation
10592 @item @emph{Description}:
10593 @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
10594 of the number of bits set ('1' bits) in the binary representation of
10595 @code{I}. It is equal to 0 if @code{I} has an even number of bits set,
10596 and 1 for an odd number of '1' bits.
10598 @item @emph{Standard}:
10599 Fortran 2008 and later
10601 @item @emph{Class}:
10604 @item @emph{Syntax}:
10605 @code{RESULT = POPPAR(I)}
10607 @item @emph{Arguments}:
10608 @multitable @columnfractions .15 .70
10609 @item @var{I} @tab Shall be of type @code{INTEGER}.
10612 @item @emph{Return value}:
10613 The return value is of type @code{INTEGER} and of the default integer
10616 @item @emph{See also}:
10617 @ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ}
10619 @item @emph{Example}:
10621 program test_population
10622 print *, popcnt(127), poppar(127)
10623 print *, popcnt(huge(0_4)), poppar(huge(0_4))
10624 print *, popcnt(huge(0_8)), poppar(huge(0_8))
10625 end program test_population
10632 @section @code{PRECISION} --- Decimal precision of a real kind
10634 @cindex model representation, precision
10637 @item @emph{Description}:
10638 @code{PRECISION(X)} returns the decimal precision in the model of the
10641 @item @emph{Standard}:
10642 Fortran 95 and later
10644 @item @emph{Class}:
10647 @item @emph{Syntax}:
10648 @code{RESULT = PRECISION(X)}
10650 @item @emph{Arguments}:
10651 @multitable @columnfractions .15 .70
10652 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
10655 @item @emph{Return value}:
10656 The return value is of type @code{INTEGER} and of the default integer
10659 @item @emph{See also}:
10660 @ref{SELECTED_REAL_KIND}, @ref{RANGE}
10662 @item @emph{Example}:
10664 program prec_and_range
10665 real(kind=4) :: x(2)
10666 complex(kind=8) :: y
10668 print *, precision(x), range(x)
10669 print *, precision(y), range(y)
10670 end program prec_and_range
10677 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
10681 @item @emph{Description}:
10682 Determines whether an optional dummy argument is present.
10684 @item @emph{Standard}:
10685 Fortran 95 and later
10687 @item @emph{Class}:
10690 @item @emph{Syntax}:
10691 @code{RESULT = PRESENT(A)}
10693 @item @emph{Arguments}:
10694 @multitable @columnfractions .15 .70
10695 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
10696 value, or a dummy procedure. It shall be the name of an optional dummy argument
10697 accessible within the current subroutine or function.
10700 @item @emph{Return value}:
10701 Returns either @code{TRUE} if the optional argument @var{A} is present, or
10702 @code{FALSE} otherwise.
10704 @item @emph{Example}:
10706 PROGRAM test_present
10707 WRITE(*,*) f(), f(42) ! "F T"
10709 LOGICAL FUNCTION f(x)
10710 INTEGER, INTENT(IN), OPTIONAL :: x
10720 @section @code{PRODUCT} --- Product of array elements
10722 @cindex array, product
10723 @cindex array, multiply elements
10724 @cindex array, conditionally multiply elements
10725 @cindex multiply array elements
10728 @item @emph{Description}:
10729 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
10730 the corresponding element in @var{MASK} is @code{TRUE}.
10732 @item @emph{Standard}:
10733 Fortran 95 and later
10735 @item @emph{Class}:
10736 Transformational function
10738 @item @emph{Syntax}:
10739 @multitable @columnfractions .80
10740 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
10741 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
10744 @item @emph{Arguments}:
10745 @multitable @columnfractions .15 .70
10746 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
10747 @code{REAL} or @code{COMPLEX}.
10748 @item @var{DIM} @tab (Optional) shall be a scalar of type
10749 @code{INTEGER} with a value in the range from 1 to n, where n
10750 equals the rank of @var{ARRAY}.
10751 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
10752 and either be a scalar or an array of the same shape as @var{ARRAY}.
10755 @item @emph{Return value}:
10756 The result is of the same type as @var{ARRAY}.
10758 If @var{DIM} is absent, a scalar with the product of all elements in
10759 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
10760 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
10761 dimension @var{DIM} dropped is returned.
10764 @item @emph{Example}:
10766 PROGRAM test_product
10767 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
10768 print *, PRODUCT(x) ! all elements, product = 120
10769 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
10773 @item @emph{See also}:
10780 @section @code{RADIX} --- Base of a model number
10782 @cindex model representation, base
10783 @cindex model representation, radix
10786 @item @emph{Description}:
10787 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
10789 @item @emph{Standard}:
10790 Fortran 95 and later
10792 @item @emph{Class}:
10795 @item @emph{Syntax}:
10796 @code{RESULT = RADIX(X)}
10798 @item @emph{Arguments}:
10799 @multitable @columnfractions .15 .70
10800 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
10803 @item @emph{Return value}:
10804 The return value is a scalar of type @code{INTEGER} and of the default
10807 @item @emph{See also}:
10808 @ref{SELECTED_REAL_KIND}
10810 @item @emph{Example}:
10813 print *, "The radix for the default integer kind is", radix(0)
10814 print *, "The radix for the default real kind is", radix(0.0)
10815 end program test_radix
10823 @section @code{RAN} --- Real pseudo-random number
10825 @cindex random number generation
10828 @item @emph{Description}:
10829 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
10830 provided as an alias for @code{RAND}. See @ref{RAND} for complete
10833 @item @emph{Standard}:
10836 @item @emph{Class}:
10839 @item @emph{See also}:
10840 @ref{RAND}, @ref{RANDOM_NUMBER}
10846 @section @code{RAND} --- Real pseudo-random number
10848 @cindex random number generation
10851 @item @emph{Description}:
10852 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
10853 distribution between 0 and 1. If @var{FLAG} is 0, the next number
10854 in the current sequence is returned; if @var{FLAG} is 1, the generator
10855 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
10856 it is used as a new seed with @code{SRAND}.
10858 This intrinsic routine is provided for backwards compatibility with
10859 GNU Fortran 77. It implements a simple modulo generator as provided
10860 by @command{g77}. For new code, one should consider the use of
10861 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
10863 @item @emph{Standard}:
10866 @item @emph{Class}:
10869 @item @emph{Syntax}:
10870 @code{RESULT = RAND(I)}
10872 @item @emph{Arguments}:
10873 @multitable @columnfractions .15 .70
10874 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
10877 @item @emph{Return value}:
10878 The return value is of @code{REAL} type and the default kind.
10880 @item @emph{Example}:
10883 integer,parameter :: seed = 86456
10886 print *, rand(), rand(), rand(), rand()
10887 print *, rand(seed), rand(), rand(), rand()
10888 end program test_rand
10891 @item @emph{See also}:
10892 @ref{SRAND}, @ref{RANDOM_NUMBER}
10898 @node RANDOM_NUMBER
10899 @section @code{RANDOM_NUMBER} --- Pseudo-random number
10900 @fnindex RANDOM_NUMBER
10901 @cindex random number generation
10904 @item @emph{Description}:
10905 Returns a single pseudorandom number or an array of pseudorandom numbers
10906 from the uniform distribution over the range @math{ 0 \leq x < 1}.
10908 The runtime-library implements George Marsaglia's KISS (Keep It Simple
10909 Stupid) random number generator (RNG). This RNG combines:
10911 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
10912 with a period of @math{2^{32}},
10913 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
10914 @item Two 16-bit multiply-with-carry generators with a period of
10915 @math{597273182964842497 > 2^{59}}.
10917 The overall period exceeds @math{2^{123}}.
10919 Please note, this RNG is thread safe if used within OpenMP directives,
10920 i.e., its state will be consistent while called from multiple threads.
10921 However, the KISS generator does not create random numbers in parallel
10922 from multiple sources, but in sequence from a single source. If an
10923 OpenMP-enabled application heavily relies on random numbers, one should
10924 consider employing a dedicated parallel random number generator instead.
10926 @item @emph{Standard}:
10927 Fortran 95 and later
10929 @item @emph{Class}:
10932 @item @emph{Syntax}:
10933 @code{RANDOM_NUMBER(HARVEST)}
10935 @item @emph{Arguments}:
10936 @multitable @columnfractions .15 .70
10937 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
10940 @item @emph{Example}:
10942 program test_random_number
10944 CALL init_random_seed() ! see example of RANDOM_SEED
10945 CALL RANDOM_NUMBER(r)
10949 @item @emph{See also}:
10956 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
10957 @fnindex RANDOM_SEED
10958 @cindex random number generation, seeding
10959 @cindex seeding a random number generator
10962 @item @emph{Description}:
10963 Restarts or queries the state of the pseudorandom number generator used by
10964 @code{RANDOM_NUMBER}.
10966 If @code{RANDOM_SEED} is called without arguments, it is initialized
10967 to a default state. The example below shows how to initialize the
10968 random seed with a varying seed in order to ensure a different random
10969 number sequence for each invocation of the program. Note that setting
10970 any of the seed values to zero should be avoided as it can result in
10971 poor quality random numbers being generated.
10973 @item @emph{Standard}:
10974 Fortran 95 and later
10976 @item @emph{Class}:
10979 @item @emph{Syntax}:
10980 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
10982 @item @emph{Arguments}:
10983 @multitable @columnfractions .15 .70
10984 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
10985 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
10986 of the arrays used with the @var{PUT} and @var{GET} arguments.
10987 @item @var{PUT} @tab (Optional) Shall be an array of type default
10988 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
10989 the array must be larger than or equal to the number returned by the
10990 @var{SIZE} argument.
10991 @item @var{GET} @tab (Optional) Shall be an array of type default
10992 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
10993 of the array must be larger than or equal to the number returned by
10994 the @var{SIZE} argument.
10997 @item @emph{Example}:
10999 subroutine init_random_seed()
11000 use iso_fortran_env, only: int64
11002 integer, allocatable :: seed(:)
11003 integer :: i, n, un, istat, dt(8), pid
11004 integer(int64) :: t
11006 call random_seed(size = n)
11008 ! First try if the OS provides a random number generator
11009 open(newunit=un, file="/dev/urandom", access="stream", &
11010 form="unformatted", action="read", status="old", iostat=istat)
11011 if (istat == 0) then
11015 ! Fallback to XOR:ing the current time and pid. The PID is
11016 ! useful in case one launches multiple instances of the same
11017 ! program in parallel.
11018 call system_clock(t)
11020 call date_and_time(values=dt)
11021 t = (dt(1) - 1970) * 365_int64 * 24 * 60 * 60 * 1000 &
11022 + dt(2) * 31_int64 * 24 * 60 * 60 * 1000 &
11023 + dt(3) * 24_int64 * 60 * 60 * 1000 &
11024 + dt(5) * 60 * 60 * 1000 &
11025 + dt(6) * 60 * 1000 + dt(7) * 1000 &
11029 t = ieor(t, int(pid, kind(t)))
11034 call random_seed(put=seed)
11036 ! This simple PRNG might not be good enough for real work, but is
11037 ! sufficient for seeding a better PRNG.
11040 integer(int64) :: s
11044 s = mod(s, 4294967296_int64)
11046 s = mod(s * 279470273_int64, 4294967291_int64)
11047 lcg = int(mod(s, int(huge(0), int64)), kind(0))
11049 end subroutine init_random_seed
11052 @item @emph{See also}:
11053 @ref{RANDOM_NUMBER}
11059 @section @code{RANGE} --- Decimal exponent range
11061 @cindex model representation, range
11064 @item @emph{Description}:
11065 @code{RANGE(X)} returns the decimal exponent range in the model of the
11068 @item @emph{Standard}:
11069 Fortran 95 and later
11071 @item @emph{Class}:
11074 @item @emph{Syntax}:
11075 @code{RESULT = RANGE(X)}
11077 @item @emph{Arguments}:
11078 @multitable @columnfractions .15 .70
11079 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
11083 @item @emph{Return value}:
11084 The return value is of type @code{INTEGER} and of the default integer
11087 @item @emph{See also}:
11088 @ref{SELECTED_REAL_KIND}, @ref{PRECISION}
11090 @item @emph{Example}:
11091 See @code{PRECISION} for an example.
11097 @section @code{RANK} --- Rank of a data object
11102 @item @emph{Description}:
11103 @code{RANK(A)} returns the rank of a scalar or array data object.
11105 @item @emph{Standard}:
11106 Technical Specification (TS) 29113
11108 @item @emph{Class}:
11111 @item @emph{Syntax}:
11112 @code{RESULT = RANK(A)}
11114 @item @emph{Arguments}:
11115 @multitable @columnfractions .15 .70
11116 @item @var{A} @tab can be of any type
11119 @item @emph{Return value}:
11120 The return value is of type @code{INTEGER} and of the default integer
11121 kind. For arrays, their rank is returned; for scalars zero is returned.
11123 @item @emph{Example}:
11127 real, allocatable :: b(:,:)
11129 print *, rank(a), rank(b) ! Prints: 0 2
11130 end program test_rank
11138 @section @code{REAL} --- Convert to real type
11144 @cindex conversion, to real
11145 @cindex complex numbers, real part
11148 @item @emph{Description}:
11149 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
11150 @code{REALPART} function is provided for compatibility with @command{g77},
11151 and its use is strongly discouraged.
11153 @item @emph{Standard}:
11154 Fortran 77 and later
11156 @item @emph{Class}:
11159 @item @emph{Syntax}:
11160 @multitable @columnfractions .80
11161 @item @code{RESULT = REAL(A [, KIND])}
11162 @item @code{RESULT = REALPART(Z)}
11165 @item @emph{Arguments}:
11166 @multitable @columnfractions .15 .70
11167 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
11169 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11170 expression indicating the kind parameter of the result.
11173 @item @emph{Return value}:
11174 These functions return a @code{REAL} variable or array under
11175 the following rules:
11179 @code{REAL(A)} is converted to a default real type if @var{A} is an
11180 integer or real variable.
11182 @code{REAL(A)} is converted to a real type with the kind type parameter
11183 of @var{A} if @var{A} is a complex variable.
11185 @code{REAL(A, KIND)} is converted to a real type with kind type
11186 parameter @var{KIND} if @var{A} is a complex, integer, or real
11190 @item @emph{Example}:
11193 complex :: x = (1.0, 2.0)
11194 print *, real(x), real(x,8), realpart(x)
11195 end program test_real
11198 @item @emph{Specific names}:
11199 @multitable @columnfractions .20 .20 .20 .25
11200 @item Name @tab Argument @tab Return type @tab Standard
11201 @item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later
11202 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension
11203 @item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab Fortran 77 and later
11207 @item @emph{See also}:
11215 @section @code{RENAME} --- Rename a file
11217 @cindex file system, rename file
11220 @item @emph{Description}:
11221 Renames a file from file @var{PATH1} to @var{PATH2}. A null
11222 character (@code{CHAR(0)}) can be used to mark the end of the names in
11223 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
11224 names are ignored. If the @var{STATUS} argument is supplied, it
11225 contains 0 on success or a nonzero error code upon return; see
11228 This intrinsic is provided in both subroutine and function forms;
11229 however, only one form can be used in any given program unit.
11231 @item @emph{Standard}:
11234 @item @emph{Class}:
11235 Subroutine, function
11237 @item @emph{Syntax}:
11238 @multitable @columnfractions .80
11239 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
11240 @item @code{STATUS = RENAME(PATH1, PATH2)}
11243 @item @emph{Arguments}:
11244 @multitable @columnfractions .15 .70
11245 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
11246 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
11247 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11250 @item @emph{See also}:
11258 @section @code{REPEAT} --- Repeated string concatenation
11260 @cindex string, repeat
11261 @cindex string, concatenate
11264 @item @emph{Description}:
11265 Concatenates @var{NCOPIES} copies of a string.
11267 @item @emph{Standard}:
11268 Fortran 95 and later
11270 @item @emph{Class}:
11271 Transformational function
11273 @item @emph{Syntax}:
11274 @code{RESULT = REPEAT(STRING, NCOPIES)}
11276 @item @emph{Arguments}:
11277 @multitable @columnfractions .15 .70
11278 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
11279 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
11282 @item @emph{Return value}:
11283 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
11286 @item @emph{Example}:
11288 program test_repeat
11289 write(*,*) repeat("x", 5) ! "xxxxx"
11297 @section @code{RESHAPE} --- Function to reshape an array
11299 @cindex array, change dimensions
11300 @cindex array, transmogrify
11303 @item @emph{Description}:
11304 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
11305 the new array may be padded with elements from @var{PAD} or permuted
11306 as defined by @var{ORDER}.
11308 @item @emph{Standard}:
11309 Fortran 95 and later
11311 @item @emph{Class}:
11312 Transformational function
11314 @item @emph{Syntax}:
11315 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
11317 @item @emph{Arguments}:
11318 @multitable @columnfractions .15 .70
11319 @item @var{SOURCE} @tab Shall be an array of any type.
11320 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
11321 array of rank one. Its values must be positive or zero.
11322 @item @var{PAD} @tab (Optional) shall be an array of the same
11323 type as @var{SOURCE}.
11324 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
11325 and an array of the same shape as @var{SHAPE}. Its values shall
11326 be a permutation of the numbers from 1 to n, where n is the size of
11327 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
11331 @item @emph{Return value}:
11332 The result is an array of shape @var{SHAPE} with the same type as
11335 @item @emph{Example}:
11337 PROGRAM test_reshape
11338 INTEGER, DIMENSION(4) :: x
11339 WRITE(*,*) SHAPE(x) ! prints "4"
11340 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
11344 @item @emph{See also}:
11351 @section @code{RRSPACING} --- Reciprocal of the relative spacing
11353 @cindex real number, relative spacing
11354 @cindex floating point, relative spacing
11358 @item @emph{Description}:
11359 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
11360 model numbers near @var{X}.
11362 @item @emph{Standard}:
11363 Fortran 95 and later
11365 @item @emph{Class}:
11368 @item @emph{Syntax}:
11369 @code{RESULT = RRSPACING(X)}
11371 @item @emph{Arguments}:
11372 @multitable @columnfractions .15 .70
11373 @item @var{X} @tab Shall be of type @code{REAL}.
11376 @item @emph{Return value}:
11377 The return value is of the same type and kind as @var{X}.
11378 The value returned is equal to
11379 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
11381 @item @emph{See also}:
11388 @section @code{RSHIFT} --- Right shift bits
11390 @cindex bits, shift right
11393 @item @emph{Description}:
11394 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
11395 bits shifted right by @var{SHIFT} places. If the absolute value of
11396 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11397 Bits shifted out from the right end are lost. The fill is arithmetic: the
11398 bits shifted in from the left end are equal to the leftmost bit, which in
11399 two's complement representation is the sign bit.
11401 This function has been superseded by the @code{SHIFTA} intrinsic, which
11402 is standard in Fortran 2008 and later.
11404 @item @emph{Standard}:
11407 @item @emph{Class}:
11410 @item @emph{Syntax}:
11411 @code{RESULT = RSHIFT(I, SHIFT)}
11413 @item @emph{Arguments}:
11414 @multitable @columnfractions .15 .70
11415 @item @var{I} @tab The type shall be @code{INTEGER}.
11416 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11419 @item @emph{Return value}:
11420 The return value is of type @code{INTEGER} and of the same kind as
11423 @item @emph{See also}:
11424 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}, @ref{SHIFTA}, @ref{SHIFTR},
11432 @section @code{SAME_TYPE_AS} --- Query dynamic types for equality
11433 @fnindex SAME_TYPE_AS
11436 @item @emph{Description}:
11437 Query dynamic types for equality.
11439 @item @emph{Standard}:
11440 Fortran 2003 and later
11442 @item @emph{Class}:
11445 @item @emph{Syntax}:
11446 @code{RESULT = SAME_TYPE_AS(A, B)}
11448 @item @emph{Arguments}:
11449 @multitable @columnfractions .15 .70
11450 @item @var{A} @tab Shall be an object of extensible declared type or
11451 unlimited polymorphic.
11452 @item @var{B} @tab Shall be an object of extensible declared type or
11453 unlimited polymorphic.
11456 @item @emph{Return value}:
11457 The return value is a scalar of type default logical. It is true if and
11458 only if the dynamic type of A is the same as the dynamic type of B.
11460 @item @emph{See also}:
11461 @ref{EXTENDS_TYPE_OF}
11468 @section @code{SCALE} --- Scale a real value
11470 @cindex real number, scale
11471 @cindex floating point, scale
11474 @item @emph{Description}:
11475 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
11477 @item @emph{Standard}:
11478 Fortran 95 and later
11480 @item @emph{Class}:
11483 @item @emph{Syntax}:
11484 @code{RESULT = SCALE(X, I)}
11486 @item @emph{Arguments}:
11487 @multitable @columnfractions .15 .70
11488 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
11489 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
11492 @item @emph{Return value}:
11493 The return value is of the same type and kind as @var{X}.
11494 Its value is @code{X * RADIX(X)**I}.
11496 @item @emph{Example}:
11499 real :: x = 178.1387e-4
11501 print *, scale(x,i), x*radix(x)**i
11502 end program test_scale
11510 @section @code{SCAN} --- Scan a string for the presence of a set of characters
11512 @cindex string, find subset
11515 @item @emph{Description}:
11516 Scans a @var{STRING} for any of the characters in a @var{SET}
11519 If @var{BACK} is either absent or equals @code{FALSE}, this function
11520 returns the position of the leftmost character of @var{STRING} that is
11521 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
11522 is returned. If no character of @var{SET} is found in @var{STRING}, the
11525 @item @emph{Standard}:
11526 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11528 @item @emph{Class}:
11531 @item @emph{Syntax}:
11532 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
11534 @item @emph{Arguments}:
11535 @multitable @columnfractions .15 .70
11536 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
11537 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
11538 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
11539 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11540 expression indicating the kind parameter of the result.
11543 @item @emph{Return value}:
11544 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11545 @var{KIND} is absent, the return value is of default integer kind.
11547 @item @emph{Example}:
11550 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
11551 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
11552 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
11556 @item @emph{See also}:
11557 @ref{INDEX intrinsic}, @ref{VERIFY}
11563 @section @code{SECNDS} --- Time function
11565 @cindex time, elapsed
11566 @cindex elapsed time
11569 @item @emph{Description}:
11570 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
11571 @var{X} is a reference time, also in seconds. If this is zero, the time in
11572 seconds from midnight is returned. This function is non-standard and its
11573 use is discouraged.
11575 @item @emph{Standard}:
11578 @item @emph{Class}:
11581 @item @emph{Syntax}:
11582 @code{RESULT = SECNDS (X)}
11584 @item @emph{Arguments}:
11585 @multitable @columnfractions .15 .70
11586 @item @var{T} @tab Shall be of type @code{REAL(4)}.
11587 @item @var{X} @tab Shall be of type @code{REAL(4)}.
11590 @item @emph{Return value}:
11593 @item @emph{Example}:
11595 program test_secnds
11598 print *, secnds (0.0) ! seconds since midnight
11599 t1 = secnds (0.0) ! reference time
11600 do i = 1, 10000000 ! do something
11602 t2 = secnds (t1) ! elapsed time
11603 print *, "Something took ", t2, " seconds."
11604 end program test_secnds
11611 @section @code{SECOND} --- CPU time function
11613 @cindex time, elapsed
11614 @cindex elapsed time
11617 @item @emph{Description}:
11618 Returns a @code{REAL(4)} value representing the elapsed CPU time in
11619 seconds. This provides the same functionality as the standard
11620 @code{CPU_TIME} intrinsic, and is only included for backwards
11623 This intrinsic is provided in both subroutine and function forms;
11624 however, only one form can be used in any given program unit.
11626 @item @emph{Standard}:
11629 @item @emph{Class}:
11630 Subroutine, function
11632 @item @emph{Syntax}:
11633 @multitable @columnfractions .80
11634 @item @code{CALL SECOND(TIME)}
11635 @item @code{TIME = SECOND()}
11638 @item @emph{Arguments}:
11639 @multitable @columnfractions .15 .70
11640 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
11643 @item @emph{Return value}:
11644 In either syntax, @var{TIME} is set to the process's current runtime in
11647 @item @emph{See also}:
11654 @node SELECTED_CHAR_KIND
11655 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
11656 @fnindex SELECTED_CHAR_KIND
11657 @cindex character kind
11658 @cindex kind, character
11661 @item @emph{Description}:
11663 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
11664 set named @var{NAME}, if a character set with such a name is supported,
11665 or @math{-1} otherwise. Currently, supported character sets include
11666 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
11667 (Universal Character Set, UCS-4) which is commonly known as Unicode.
11669 @item @emph{Standard}:
11670 Fortran 2003 and later
11672 @item @emph{Class}:
11673 Transformational function
11675 @item @emph{Syntax}:
11676 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
11678 @item @emph{Arguments}:
11679 @multitable @columnfractions .15 .70
11680 @item @var{NAME} @tab Shall be a scalar and of the default character type.
11683 @item @emph{Example}:
11685 program character_kind
11686 use iso_fortran_env
11688 integer, parameter :: ascii = selected_char_kind ("ascii")
11689 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646')
11691 character(kind=ascii, len=26) :: alphabet
11692 character(kind=ucs4, len=30) :: hello_world
11694 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
11695 hello_world = ucs4_'Hello World and Ni Hao -- ' &
11696 // char (int (z'4F60'), ucs4) &
11697 // char (int (z'597D'), ucs4)
11699 write (*,*) alphabet
11701 open (output_unit, encoding='UTF-8')
11702 write (*,*) trim (hello_world)
11703 end program character_kind
11709 @node SELECTED_INT_KIND
11710 @section @code{SELECTED_INT_KIND} --- Choose integer kind
11711 @fnindex SELECTED_INT_KIND
11712 @cindex integer kind
11713 @cindex kind, integer
11716 @item @emph{Description}:
11717 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
11718 type that can represent all values ranging from @math{-10^R} (exclusive)
11719 to @math{10^R} (exclusive). If there is no integer kind that accommodates
11720 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
11722 @item @emph{Standard}:
11723 Fortran 95 and later
11725 @item @emph{Class}:
11726 Transformational function
11728 @item @emph{Syntax}:
11729 @code{RESULT = SELECTED_INT_KIND(R)}
11731 @item @emph{Arguments}:
11732 @multitable @columnfractions .15 .70
11733 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
11736 @item @emph{Example}:
11738 program large_integers
11739 integer,parameter :: k5 = selected_int_kind(5)
11740 integer,parameter :: k15 = selected_int_kind(15)
11741 integer(kind=k5) :: i5
11742 integer(kind=k15) :: i15
11744 print *, huge(i5), huge(i15)
11746 ! The following inequalities are always true
11747 print *, huge(i5) >= 10_k5**5-1
11748 print *, huge(i15) >= 10_k15**15-1
11749 end program large_integers
11755 @node SELECTED_REAL_KIND
11756 @section @code{SELECTED_REAL_KIND} --- Choose real kind
11757 @fnindex SELECTED_REAL_KIND
11760 @cindex radix, real
11763 @item @emph{Description}:
11764 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
11765 with decimal precision of at least @code{P} digits, exponent range of
11766 at least @code{R}, and with a radix of @code{RADIX}.
11768 @item @emph{Standard}:
11769 Fortran 95 and later, with @code{RADIX} Fortran 2008 or later
11771 @item @emph{Class}:
11772 Transformational function
11774 @item @emph{Syntax}:
11775 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
11777 @item @emph{Arguments}:
11778 @multitable @columnfractions .15 .70
11779 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
11780 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
11781 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
11783 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
11784 be present; since Fortran 2008, they are assumed to be zero if absent.
11786 @item @emph{Return value}:
11788 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
11789 a real data type with decimal precision of at least @code{P} digits, a
11790 decimal exponent range of at least @code{R}, and with the requested
11791 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
11792 any radix can be returned. If more than one real data type meet the
11793 criteria, the kind of the data type with the smallest decimal precision
11794 is returned. If no real data type matches the criteria, the result is
11796 @item -1 if the processor does not support a real data type with a
11797 precision greater than or equal to @code{P}, but the @code{R} and
11798 @code{RADIX} requirements can be fulfilled
11799 @item -2 if the processor does not support a real type with an exponent
11800 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
11802 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
11804 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
11806 @item -5 if there is no real type with the given @code{RADIX}
11809 @item @emph{See also}:
11810 @ref{PRECISION}, @ref{RANGE}, @ref{RADIX}
11812 @item @emph{Example}:
11815 integer,parameter :: p6 = selected_real_kind(6)
11816 integer,parameter :: p10r100 = selected_real_kind(10,100)
11817 integer,parameter :: r400 = selected_real_kind(r=400)
11819 real(kind=p10r100) :: y
11820 real(kind=r400) :: z
11822 print *, precision(x), range(x)
11823 print *, precision(y), range(y)
11824 print *, precision(z), range(z)
11825 end program real_kinds
11832 @section @code{SET_EXPONENT} --- Set the exponent of the model
11833 @fnindex SET_EXPONENT
11834 @cindex real number, set exponent
11835 @cindex floating point, set exponent
11838 @item @emph{Description}:
11839 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
11840 is that that of @var{X} and whose exponent part is @var{I}.
11842 @item @emph{Standard}:
11843 Fortran 95 and later
11845 @item @emph{Class}:
11848 @item @emph{Syntax}:
11849 @code{RESULT = SET_EXPONENT(X, I)}
11851 @item @emph{Arguments}:
11852 @multitable @columnfractions .15 .70
11853 @item @var{X} @tab Shall be of type @code{REAL}.
11854 @item @var{I} @tab Shall be of type @code{INTEGER}.
11857 @item @emph{Return value}:
11858 The return value is of the same type and kind as @var{X}.
11859 The real number whose fractional part
11860 is that that of @var{X} and whose exponent part if @var{I} is returned;
11861 it is @code{FRACTION(X) * RADIX(X)**I}.
11863 @item @emph{Example}:
11865 PROGRAM test_setexp
11866 REAL :: x = 178.1387e-4
11868 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
11877 @section @code{SHAPE} --- Determine the shape of an array
11879 @cindex array, shape
11882 @item @emph{Description}:
11883 Determines the shape of an array.
11885 @item @emph{Standard}:
11886 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11888 @item @emph{Class}:
11891 @item @emph{Syntax}:
11892 @code{RESULT = SHAPE(SOURCE [, KIND])}
11894 @item @emph{Arguments}:
11895 @multitable @columnfractions .15 .70
11896 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
11897 If @var{SOURCE} is a pointer it must be associated and allocatable
11898 arrays must be allocated.
11899 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11900 expression indicating the kind parameter of the result.
11903 @item @emph{Return value}:
11904 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
11905 has dimensions. The elements of the resulting array correspond to the extend
11906 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
11907 the result is the rank one array of size zero. If @var{KIND} is absent, the
11908 return value has the default integer kind otherwise the specified kind.
11910 @item @emph{Example}:
11913 INTEGER, DIMENSION(-1:1, -1:2) :: A
11914 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
11915 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
11919 @item @emph{See also}:
11920 @ref{RESHAPE}, @ref{SIZE}
11926 @section @code{SHIFTA} --- Right shift with fill
11928 @cindex bits, shift right
11929 @cindex shift, right with fill
11932 @item @emph{Description}:
11933 @code{SHIFTA} returns a value corresponding to @var{I} with all of the
11934 bits shifted right by @var{SHIFT} places. If the absolute value of
11935 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11936 Bits shifted out from the right end are lost. The fill is arithmetic: the
11937 bits shifted in from the left end are equal to the leftmost bit, which in
11938 two's complement representation is the sign bit.
11940 @item @emph{Standard}:
11941 Fortran 2008 and later
11943 @item @emph{Class}:
11946 @item @emph{Syntax}:
11947 @code{RESULT = SHIFTA(I, SHIFT)}
11949 @item @emph{Arguments}:
11950 @multitable @columnfractions .15 .70
11951 @item @var{I} @tab The type shall be @code{INTEGER}.
11952 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11955 @item @emph{Return value}:
11956 The return value is of type @code{INTEGER} and of the same kind as
11959 @item @emph{See also}:
11960 @ref{SHIFTL}, @ref{SHIFTR}
11966 @section @code{SHIFTL} --- Left shift
11968 @cindex bits, shift left
11969 @cindex shift, left
11972 @item @emph{Description}:
11973 @code{SHIFTL} returns a value corresponding to @var{I} with all of the
11974 bits shifted left by @var{SHIFT} places. If the absolute value of
11975 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11976 Bits shifted out from the left end are lost, and bits shifted in from
11977 the right end are set to 0.
11979 @item @emph{Standard}:
11980 Fortran 2008 and later
11982 @item @emph{Class}:
11985 @item @emph{Syntax}:
11986 @code{RESULT = SHIFTL(I, SHIFT)}
11988 @item @emph{Arguments}:
11989 @multitable @columnfractions .15 .70
11990 @item @var{I} @tab The type shall be @code{INTEGER}.
11991 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11994 @item @emph{Return value}:
11995 The return value is of type @code{INTEGER} and of the same kind as
11998 @item @emph{See also}:
11999 @ref{SHIFTA}, @ref{SHIFTR}
12005 @section @code{SHIFTR} --- Right shift
12007 @cindex bits, shift right
12008 @cindex shift, right
12011 @item @emph{Description}:
12012 @code{SHIFTR} returns a value corresponding to @var{I} with all of the
12013 bits shifted right by @var{SHIFT} places. If the absolute value of
12014 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12015 Bits shifted out from the right end are lost, and bits shifted in from
12016 the left end are set to 0.
12018 @item @emph{Standard}:
12019 Fortran 2008 and later
12021 @item @emph{Class}:
12024 @item @emph{Syntax}:
12025 @code{RESULT = SHIFTR(I, SHIFT)}
12027 @item @emph{Arguments}:
12028 @multitable @columnfractions .15 .70
12029 @item @var{I} @tab The type shall be @code{INTEGER}.
12030 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12033 @item @emph{Return value}:
12034 The return value is of type @code{INTEGER} and of the same kind as
12037 @item @emph{See also}:
12038 @ref{SHIFTA}, @ref{SHIFTL}
12044 @section @code{SIGN} --- Sign copying function
12048 @cindex sign copying
12051 @item @emph{Description}:
12052 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
12054 @item @emph{Standard}:
12055 Fortran 77 and later
12057 @item @emph{Class}:
12060 @item @emph{Syntax}:
12061 @code{RESULT = SIGN(A, B)}
12063 @item @emph{Arguments}:
12064 @multitable @columnfractions .15 .70
12065 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
12066 @item @var{B} @tab Shall be of the same type and kind as @var{A}
12069 @item @emph{Return value}:
12070 The kind of the return value is that of @var{A} and @var{B}.
12071 If @math{B\ge 0} then the result is @code{ABS(A)}, else
12072 it is @code{-ABS(A)}.
12074 @item @emph{Example}:
12077 print *, sign(-12,1)
12078 print *, sign(-12,0)
12079 print *, sign(-12,-1)
12081 print *, sign(-12.,1.)
12082 print *, sign(-12.,0.)
12083 print *, sign(-12.,-1.)
12084 end program test_sign
12087 @item @emph{Specific names}:
12088 @multitable @columnfractions .20 .20 .20 .25
12089 @item Name @tab Arguments @tab Return type @tab Standard
12090 @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu
12091 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
12092 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu
12099 @section @code{SIGNAL} --- Signal handling subroutine (or function)
12101 @cindex system, signal handling
12104 @item @emph{Description}:
12105 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
12106 @var{HANDLER} to be executed with a single integer argument when signal
12107 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
12108 turn off handling of signal @var{NUMBER} or revert to its default
12109 action. See @code{signal(2)}.
12111 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
12112 is supplied, it is set to the value returned by @code{signal(2)}.
12114 @item @emph{Standard}:
12117 @item @emph{Class}:
12118 Subroutine, function
12120 @item @emph{Syntax}:
12121 @multitable @columnfractions .80
12122 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
12123 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
12126 @item @emph{Arguments}:
12127 @multitable @columnfractions .15 .70
12128 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
12129 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
12130 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
12131 @code{INTEGER}. It is @code{INTENT(IN)}.
12132 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
12133 integer. It has @code{INTENT(OUT)}.
12135 @c TODO: What should the interface of the handler be? Does it take arguments?
12137 @item @emph{Return value}:
12138 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
12140 @item @emph{Example}:
12142 program test_signal
12144 external handler_print
12146 call signal (12, handler_print)
12147 call signal (10, 1)
12150 end program test_signal
12157 @section @code{SIN} --- Sine function
12163 @cindex trigonometric function, sine
12167 @item @emph{Description}:
12168 @code{SIN(X)} computes the sine of @var{X}.
12170 @item @emph{Standard}:
12171 Fortran 77 and later
12173 @item @emph{Class}:
12176 @item @emph{Syntax}:
12177 @code{RESULT = SIN(X)}
12179 @item @emph{Arguments}:
12180 @multitable @columnfractions .15 .70
12181 @item @var{X} @tab The type shall be @code{REAL} or
12185 @item @emph{Return value}:
12186 The return value has same type and kind as @var{X}.
12188 @item @emph{Example}:
12193 end program test_sin
12196 @item @emph{Specific names}:
12197 @multitable @columnfractions .20 .20 .20 .25
12198 @item Name @tab Argument @tab Return type @tab Standard
12199 @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu
12200 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
12201 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
12202 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
12203 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
12206 @item @emph{See also}:
12213 @section @code{SINH} --- Hyperbolic sine function
12216 @cindex hyperbolic sine
12217 @cindex hyperbolic function, sine
12218 @cindex sine, hyperbolic
12221 @item @emph{Description}:
12222 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
12224 @item @emph{Standard}:
12225 Fortran 95 and later, for a complex argument Fortran 2008 or later
12227 @item @emph{Class}:
12230 @item @emph{Syntax}:
12231 @code{RESULT = SINH(X)}
12233 @item @emph{Arguments}:
12234 @multitable @columnfractions .15 .70
12235 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
12238 @item @emph{Return value}:
12239 The return value has same type and kind as @var{X}.
12241 @item @emph{Example}:
12244 real(8) :: x = - 1.0_8
12246 end program test_sinh
12249 @item @emph{Specific names}:
12250 @multitable @columnfractions .20 .20 .20 .25
12251 @item Name @tab Argument @tab Return type @tab Standard
12252 @item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
12253 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
12256 @item @emph{See also}:
12263 @section @code{SIZE} --- Determine the size of an array
12265 @cindex array, size
12266 @cindex array, number of elements
12267 @cindex array, count elements
12270 @item @emph{Description}:
12271 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
12272 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
12274 @item @emph{Standard}:
12275 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12277 @item @emph{Class}:
12280 @item @emph{Syntax}:
12281 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
12283 @item @emph{Arguments}:
12284 @multitable @columnfractions .15 .70
12285 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
12286 a pointer it must be associated and allocatable arrays must be allocated.
12287 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
12288 and its value shall be in the range from 1 to n, where n equals the rank
12290 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12291 expression indicating the kind parameter of the result.
12294 @item @emph{Return value}:
12295 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12296 @var{KIND} is absent, the return value is of default integer kind.
12298 @item @emph{Example}:
12301 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
12305 @item @emph{See also}:
12306 @ref{SHAPE}, @ref{RESHAPE}
12311 @section @code{SIZEOF} --- Size in bytes of an expression
12313 @cindex expression size
12314 @cindex size of an expression
12317 @item @emph{Description}:
12318 @code{SIZEOF(X)} calculates the number of bytes of storage the
12319 expression @code{X} occupies.
12321 @item @emph{Standard}:
12324 @item @emph{Class}:
12327 @item @emph{Syntax}:
12328 @code{N = SIZEOF(X)}
12330 @item @emph{Arguments}:
12331 @multitable @columnfractions .15 .70
12332 @item @var{X} @tab The argument shall be of any type, rank or shape.
12335 @item @emph{Return value}:
12336 The return value is of type integer and of the system-dependent kind
12337 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
12338 number of bytes occupied by the argument. If the argument has the
12339 @code{POINTER} attribute, the number of bytes of the storage area pointed
12340 to is returned. If the argument is of a derived type with @code{POINTER}
12341 or @code{ALLOCATABLE} components, the return value does not account for
12342 the sizes of the data pointed to by these components. If the argument is
12343 polymorphic, the size according to the dynamic type is returned. The argument
12344 may not be a procedure or procedure pointer. Note that the code assumes for
12345 arrays that those are contiguous; for contiguous arrays, it returns the
12346 storage or an array element multiplied by the size of the array.
12348 @item @emph{Example}:
12352 print *, (sizeof(s)/sizeof(r) == 5)
12355 The example will print @code{.TRUE.} unless you are using a platform
12356 where default @code{REAL} variables are unusually padded.
12358 @item @emph{See also}:
12359 @ref{C_SIZEOF}, @ref{STORAGE_SIZE}
12364 @section @code{SLEEP} --- Sleep for the specified number of seconds
12366 @cindex delayed execution
12369 @item @emph{Description}:
12370 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
12372 @item @emph{Standard}:
12375 @item @emph{Class}:
12378 @item @emph{Syntax}:
12379 @code{CALL SLEEP(SECONDS)}
12381 @item @emph{Arguments}:
12382 @multitable @columnfractions .15 .70
12383 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
12386 @item @emph{Example}:
12397 @section @code{SPACING} --- Smallest distance between two numbers of a given type
12399 @cindex real number, relative spacing
12400 @cindex floating point, relative spacing
12403 @item @emph{Description}:
12404 Determines the distance between the argument @var{X} and the nearest
12405 adjacent number of the same type.
12407 @item @emph{Standard}:
12408 Fortran 95 and later
12410 @item @emph{Class}:
12413 @item @emph{Syntax}:
12414 @code{RESULT = SPACING(X)}
12416 @item @emph{Arguments}:
12417 @multitable @columnfractions .15 .70
12418 @item @var{X} @tab Shall be of type @code{REAL}.
12421 @item @emph{Return value}:
12422 The result is of the same type as the input argument @var{X}.
12424 @item @emph{Example}:
12426 PROGRAM test_spacing
12427 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
12428 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
12430 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
12431 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
12435 @item @emph{See also}:
12442 @section @code{SPREAD} --- Add a dimension to an array
12444 @cindex array, increase dimension
12445 @cindex array, duplicate elements
12446 @cindex array, duplicate dimensions
12449 @item @emph{Description}:
12450 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
12451 dimension @var{DIM}.
12453 @item @emph{Standard}:
12454 Fortran 95 and later
12456 @item @emph{Class}:
12457 Transformational function
12459 @item @emph{Syntax}:
12460 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
12462 @item @emph{Arguments}:
12463 @multitable @columnfractions .15 .70
12464 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
12465 a rank less than seven.
12466 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
12467 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
12468 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
12471 @item @emph{Return value}:
12472 The result is an array of the same type as @var{SOURCE} and has rank n+1
12473 where n equals the rank of @var{SOURCE}.
12475 @item @emph{Example}:
12477 PROGRAM test_spread
12478 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
12479 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
12480 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
12484 @item @emph{See also}:
12491 @section @code{SQRT} --- Square-root function
12498 @cindex square-root
12501 @item @emph{Description}:
12502 @code{SQRT(X)} computes the square root of @var{X}.
12504 @item @emph{Standard}:
12505 Fortran 77 and later
12507 @item @emph{Class}:
12510 @item @emph{Syntax}:
12511 @code{RESULT = SQRT(X)}
12513 @item @emph{Arguments}:
12514 @multitable @columnfractions .15 .70
12515 @item @var{X} @tab The type shall be @code{REAL} or
12519 @item @emph{Return value}:
12520 The return value is of type @code{REAL} or @code{COMPLEX}.
12521 The kind type parameter is the same as @var{X}.
12523 @item @emph{Example}:
12526 real(8) :: x = 2.0_8
12527 complex :: z = (1.0, 2.0)
12530 end program test_sqrt
12533 @item @emph{Specific names}:
12534 @multitable @columnfractions .20 .20 .20 .25
12535 @item Name @tab Argument @tab Return type @tab Standard
12536 @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
12537 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
12538 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
12539 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
12540 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
12547 @section @code{SRAND} --- Reinitialize the random number generator
12549 @cindex random number generation, seeding
12550 @cindex seeding a random number generator
12553 @item @emph{Description}:
12554 @code{SRAND} reinitializes the pseudo-random number generator
12555 called by @code{RAND} and @code{IRAND}. The new seed used by the
12556 generator is specified by the required argument @var{SEED}.
12558 @item @emph{Standard}:
12561 @item @emph{Class}:
12564 @item @emph{Syntax}:
12565 @code{CALL SRAND(SEED)}
12567 @item @emph{Arguments}:
12568 @multitable @columnfractions .15 .70
12569 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
12572 @item @emph{Return value}:
12573 Does not return anything.
12575 @item @emph{Example}:
12576 See @code{RAND} and @code{IRAND} for examples.
12578 @item @emph{Notes}:
12579 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
12580 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
12581 to generate pseudo-random numbers. Please note that in
12582 GNU Fortran, these two sets of intrinsics (@code{RAND},
12583 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
12584 @code{RANDOM_SEED} on the other hand) access two independent
12585 pseudo-random number generators.
12587 @item @emph{See also}:
12588 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
12595 @section @code{STAT} --- Get file status
12597 @cindex file system, file status
12600 @item @emph{Description}:
12601 This function returns information about a file. No permissions are required on
12602 the file itself, but execute (search) permission is required on all of the
12603 directories in path that lead to the file.
12605 The elements that are obtained and stored in the array @code{VALUES}:
12606 @multitable @columnfractions .15 .70
12607 @item @code{VALUES(1)} @tab Device ID
12608 @item @code{VALUES(2)} @tab Inode number
12609 @item @code{VALUES(3)} @tab File mode
12610 @item @code{VALUES(4)} @tab Number of links
12611 @item @code{VALUES(5)} @tab Owner's uid
12612 @item @code{VALUES(6)} @tab Owner's gid
12613 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
12614 @item @code{VALUES(8)} @tab File size (bytes)
12615 @item @code{VALUES(9)} @tab Last access time
12616 @item @code{VALUES(10)} @tab Last modification time
12617 @item @code{VALUES(11)} @tab Last file status change time
12618 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
12619 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
12622 Not all these elements are relevant on all systems.
12623 If an element is not relevant, it is returned as 0.
12625 This intrinsic is provided in both subroutine and function forms; however,
12626 only one form can be used in any given program unit.
12628 @item @emph{Standard}:
12631 @item @emph{Class}:
12632 Subroutine, function
12634 @item @emph{Syntax}:
12635 @multitable @columnfractions .80
12636 @item @code{CALL STAT(NAME, VALUES [, STATUS])}
12637 @item @code{STATUS = STAT(NAME, VALUES)}
12640 @item @emph{Arguments}:
12641 @multitable @columnfractions .15 .70
12642 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
12643 default kind and a valid path within the file system.
12644 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
12645 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
12646 on success and a system specific error code otherwise.
12649 @item @emph{Example}:
12652 INTEGER, DIMENSION(13) :: buff
12655 CALL STAT("/etc/passwd", buff, status)
12657 IF (status == 0) THEN
12658 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
12659 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
12660 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
12661 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
12662 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
12663 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
12664 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
12665 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
12666 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
12667 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
12668 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
12669 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
12670 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
12675 @item @emph{See also}:
12676 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
12682 @section @code{STORAGE_SIZE} --- Storage size in bits
12683 @fnindex STORAGE_SIZE
12684 @cindex storage size
12687 @item @emph{Description}:
12688 Returns the storage size of argument @var{A} in bits.
12689 @item @emph{Standard}:
12690 Fortran 2008 and later
12691 @item @emph{Class}:
12693 @item @emph{Syntax}:
12694 @code{RESULT = STORAGE_SIZE(A [, KIND])}
12696 @item @emph{Arguments}:
12697 @multitable @columnfractions .15 .70
12698 @item @var{A} @tab Shall be a scalar or array of any type.
12699 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
12702 @item @emph{Return Value}:
12703 The result is a scalar integer with the kind type parameter specified by KIND
12704 (or default integer type if KIND is missing). The result value is the size
12705 expressed in bits for an element of an array that has the dynamic type and type
12708 @item @emph{See also}:
12709 @ref{C_SIZEOF}, @ref{SIZEOF}
12715 @section @code{SUM} --- Sum of array elements
12718 @cindex array, add elements
12719 @cindex array, conditionally add elements
12720 @cindex sum array elements
12723 @item @emph{Description}:
12724 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
12725 the corresponding element in @var{MASK} is @code{TRUE}.
12727 @item @emph{Standard}:
12728 Fortran 95 and later
12730 @item @emph{Class}:
12731 Transformational function
12733 @item @emph{Syntax}:
12734 @multitable @columnfractions .80
12735 @item @code{RESULT = SUM(ARRAY[, MASK])}
12736 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
12739 @item @emph{Arguments}:
12740 @multitable @columnfractions .15 .70
12741 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
12742 @code{REAL} or @code{COMPLEX}.
12743 @item @var{DIM} @tab (Optional) shall be a scalar of type
12744 @code{INTEGER} with a value in the range from 1 to n, where n
12745 equals the rank of @var{ARRAY}.
12746 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
12747 and either be a scalar or an array of the same shape as @var{ARRAY}.
12750 @item @emph{Return value}:
12751 The result is of the same type as @var{ARRAY}.
12753 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
12754 is returned. Otherwise, an array of rank n-1, where n equals the rank of
12755 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
12756 dropped is returned.
12758 @item @emph{Example}:
12761 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
12762 print *, SUM(x) ! all elements, sum = 15
12763 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
12767 @item @emph{See also}:
12774 @section @code{SYMLNK} --- Create a symbolic link
12776 @cindex file system, create link
12777 @cindex file system, soft link
12780 @item @emph{Description}:
12781 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
12782 character (@code{CHAR(0)}) can be used to mark the end of the names in
12783 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
12784 names are ignored. If the @var{STATUS} argument is supplied, it
12785 contains 0 on success or a nonzero error code upon return; see
12786 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
12787 @code{ENOSYS} is returned.
12789 This intrinsic is provided in both subroutine and function forms;
12790 however, only one form can be used in any given program unit.
12792 @item @emph{Standard}:
12795 @item @emph{Class}:
12796 Subroutine, function
12798 @item @emph{Syntax}:
12799 @multitable @columnfractions .80
12800 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
12801 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
12804 @item @emph{Arguments}:
12805 @multitable @columnfractions .15 .70
12806 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
12807 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
12808 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12811 @item @emph{See also}:
12812 @ref{LINK}, @ref{UNLINK}
12819 @section @code{SYSTEM} --- Execute a shell command
12821 @cindex system, system call
12824 @item @emph{Description}:
12825 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
12826 argument @var{STATUS} is present, it contains the value returned by
12827 @code{system(3)}, which is presumably 0 if the shell command succeeded.
12828 Note that which shell is used to invoke the command is system-dependent
12829 and environment-dependent.
12831 This intrinsic is provided in both subroutine and function forms;
12832 however, only one form can be used in any given program unit.
12834 Note that the @code{system} function need not be thread-safe. It is
12835 the responsibility of the user to ensure that @code{system} is not
12836 called concurrently.
12838 @item @emph{Standard}:
12841 @item @emph{Class}:
12842 Subroutine, function
12844 @item @emph{Syntax}:
12845 @multitable @columnfractions .80
12846 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
12847 @item @code{STATUS = SYSTEM(COMMAND)}
12850 @item @emph{Arguments}:
12851 @multitable @columnfractions .15 .70
12852 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
12853 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12856 @item @emph{See also}:
12857 @ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
12858 and should considered in new code for future portability.
12864 @section @code{SYSTEM_CLOCK} --- Time function
12865 @fnindex SYSTEM_CLOCK
12866 @cindex time, clock ticks
12867 @cindex clock ticks
12870 @item @emph{Description}:
12871 Determines the @var{COUNT} of a processor clock since an unspecified
12872 time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines
12873 the number of clock ticks per second. If the platform supports a
12874 monotonic clock, that clock is used and can, depending on the platform
12875 clock implementation, provide up to nanosecond resolution. If a
12876 monotonic clock is not available, the implementation falls back to a
12879 @var{COUNT_RATE} is system dependent and can vary depending on the kind of
12880 the arguments. For @var{kind=4} arguments (and smaller integer kinds),
12881 @var{COUNT} represents milliseconds, while for @var{kind=8} arguments (and
12882 larger integer kinds), @var{COUNT} typically represents micro- or
12883 nanoseconds depending on resolution of the underlying platform clock.
12884 @var{COUNT_MAX} usually equals @code{HUGE(COUNT_MAX)}. Note that the
12885 millisecond resolution of the @var{kind=4} version implies that the
12886 @var{COUNT} will wrap around in roughly 25 days. In order to avoid issues
12887 with the wrap around and for more precise timing, please use the
12888 @var{kind=8} version.
12890 If there is no clock, or querying the clock fails, @var{COUNT} is set
12891 to @code{-HUGE(COUNT)}, and @var{COUNT_RATE} and @var{COUNT_MAX} are
12894 When running on a platform using the GNU C library (glibc) version
12895 2.16 or older, or a derivative thereof, the high resolution monotonic
12896 clock is available only when linking with the @var{rt} library. This
12897 can be done explicitly by adding the @code{-lrt} flag when linking the
12898 application, but is also done implicitly when using OpenMP.
12900 On the Windows platform, the version with @var{kind=4} arguments uses
12901 the @code{GetTickCount} function, whereas the @var{kind=8} version
12902 uses @code{QueryPerformanceCounter} and
12903 @code{QueryPerformanceCounterFrequency}. For more information, and
12904 potential caveats, please see the platform documentation.
12906 @item @emph{Standard}:
12907 Fortran 95 and later
12909 @item @emph{Class}:
12912 @item @emph{Syntax}:
12913 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
12915 @item @emph{Arguments}:
12916 @multitable @columnfractions .15 .70
12917 @item @var{COUNT} @tab (Optional) shall be a scalar of type
12918 @code{INTEGER} with @code{INTENT(OUT)}.
12919 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type
12920 @code{INTEGER} or @code{REAL}, with @code{INTENT(OUT)}.
12921 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type
12922 @code{INTEGER} with @code{INTENT(OUT)}.
12925 @item @emph{Example}:
12927 PROGRAM test_system_clock
12928 INTEGER :: count, count_rate, count_max
12929 CALL SYSTEM_CLOCK(count, count_rate, count_max)
12930 WRITE(*,*) count, count_rate, count_max
12934 @item @emph{See also}:
12935 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
12941 @section @code{TAN} --- Tangent function
12944 @cindex trigonometric function, tangent
12948 @item @emph{Description}:
12949 @code{TAN(X)} computes the tangent of @var{X}.
12951 @item @emph{Standard}:
12952 Fortran 77 and later, for a complex argument Fortran 2008 or later
12954 @item @emph{Class}:
12957 @item @emph{Syntax}:
12958 @code{RESULT = TAN(X)}
12960 @item @emph{Arguments}:
12961 @multitable @columnfractions .15 .70
12962 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
12965 @item @emph{Return value}:
12966 The return value has same type and kind as @var{X}.
12968 @item @emph{Example}:
12971 real(8) :: x = 0.165_8
12973 end program test_tan
12976 @item @emph{Specific names}:
12977 @multitable @columnfractions .20 .20 .20 .25
12978 @item Name @tab Argument @tab Return type @tab Standard
12979 @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
12980 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
12983 @item @emph{See also}:
12990 @section @code{TANH} --- Hyperbolic tangent function
12993 @cindex hyperbolic tangent
12994 @cindex hyperbolic function, tangent
12995 @cindex tangent, hyperbolic
12998 @item @emph{Description}:
12999 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
13001 @item @emph{Standard}:
13002 Fortran 77 and later, for a complex argument Fortran 2008 or later
13004 @item @emph{Class}:
13007 @item @emph{Syntax}:
13010 @item @emph{Arguments}:
13011 @multitable @columnfractions .15 .70
13012 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13015 @item @emph{Return value}:
13016 The return value has same type and kind as @var{X}. If @var{X} is
13017 complex, the imaginary part of the result is in radians. If @var{X}
13018 is @code{REAL}, the return value lies in the range
13019 @math{ - 1 \leq tanh(x) \leq 1 }.
13021 @item @emph{Example}:
13024 real(8) :: x = 2.1_8
13026 end program test_tanh
13029 @item @emph{Specific names}:
13030 @multitable @columnfractions .20 .20 .20 .25
13031 @item Name @tab Argument @tab Return type @tab Standard
13032 @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
13033 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
13036 @item @emph{See also}:
13043 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
13044 @fnindex THIS_IMAGE
13045 @cindex coarray, @code{THIS_IMAGE}
13046 @cindex images, index of this image
13049 @item @emph{Description}:
13050 Returns the cosubscript for this image.
13052 @item @emph{Standard}:
13053 Fortran 2008 and later. With @var{DISTANCE} argument,
13054 Technical Specification (TS) 18508 or later
13056 @item @emph{Class}:
13057 Transformational function
13059 @item @emph{Syntax}:
13060 @multitable @columnfractions .80
13061 @item @code{RESULT = THIS_IMAGE()}
13062 @item @code{RESULT = THIS_IMAGE(DISTANCE)}
13063 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
13066 @item @emph{Arguments}:
13067 @multitable @columnfractions .15 .70
13068 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
13069 (not permitted together with @var{COARRAY}).
13070 @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
13071 present, required).
13072 @item @var{DIM} @tab default integer scalar (optional). If present,
13073 @var{DIM} shall be between one and the corank of @var{COARRAY}.
13077 @item @emph{Return value}:
13078 Default integer. If @var{COARRAY} is not present, it is scalar; if
13079 @var{DISTANCE} is not present or has value 0, its value is the image index on
13080 the invoking image for the current team, for values smaller or equal
13081 distance to the initial team, it returns the image index on the ancestor team
13082 which has a distance of @var{DISTANCE} from the invoking team. If
13083 @var{DISTANCE} is larger than the distance to the initial team, the image
13084 index of the initial team is returned. Otherwise when the @var{COARRAY} is
13085 present, if @var{DIM} is not present, a rank-1 array with corank elements is
13086 returned, containing the cosubscripts for @var{COARRAY} specifying the invoking
13087 image. If @var{DIM} is present, a scalar is returned, with the value of
13088 the @var{DIM} element of @code{THIS_IMAGE(COARRAY)}.
13090 @item @emph{Example}:
13092 INTEGER :: value[*]
13094 value = THIS_IMAGE()
13096 IF (THIS_IMAGE() == 1) THEN
13097 DO i = 1, NUM_IMAGES()
13098 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
13102 ! Check whether the current image is the initial image
13103 IF (THIS_IMAGE(HUGE(1)) /= THIS_IMAGE())
13104 error stop "something is rotten here"
13107 @item @emph{See also}:
13108 @ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
13114 @section @code{TIME} --- Time function
13116 @cindex time, current
13117 @cindex current time
13120 @item @emph{Description}:
13121 Returns the current time encoded as an integer (in the manner of the
13122 function @code{time(3)} in the C standard library). This value is
13123 suitable for passing to @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
13125 This intrinsic is not fully portable, such as to systems with 32-bit
13126 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
13127 the values returned by this intrinsic might be, or become, negative, or
13128 numerically less than previous values, during a single run of the
13131 See @ref{TIME8}, for information on a similar intrinsic that might be
13132 portable to more GNU Fortran implementations, though to fewer Fortran
13135 @item @emph{Standard}:
13138 @item @emph{Class}:
13141 @item @emph{Syntax}:
13142 @code{RESULT = TIME()}
13144 @item @emph{Return value}:
13145 The return value is a scalar of type @code{INTEGER(4)}.
13147 @item @emph{See also}:
13148 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
13155 @section @code{TIME8} --- Time function (64-bit)
13157 @cindex time, current
13158 @cindex current time
13161 @item @emph{Description}:
13162 Returns the current time encoded as an integer (in the manner of the
13163 function @code{time(3)} in the C standard library). This value is
13164 suitable for passing to @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
13166 @emph{Warning:} this intrinsic does not increase the range of the timing
13167 values over that returned by @code{time(3)}. On a system with a 32-bit
13168 @code{time(3)}, @code{TIME8} will return a 32-bit value, even though
13169 it is converted to a 64-bit @code{INTEGER(8)} value. That means
13170 overflows of the 32-bit value can still occur. Therefore, the values
13171 returned by this intrinsic might be or become negative or numerically
13172 less than previous values during a single run of the compiled program.
13174 @item @emph{Standard}:
13177 @item @emph{Class}:
13180 @item @emph{Syntax}:
13181 @code{RESULT = TIME8()}
13183 @item @emph{Return value}:
13184 The return value is a scalar of type @code{INTEGER(8)}.
13186 @item @emph{See also}:
13187 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
13194 @section @code{TINY} --- Smallest positive number of a real kind
13196 @cindex limits, smallest number
13197 @cindex model representation, smallest number
13200 @item @emph{Description}:
13201 @code{TINY(X)} returns the smallest positive (non zero) number
13202 in the model of the type of @code{X}.
13204 @item @emph{Standard}:
13205 Fortran 95 and later
13207 @item @emph{Class}:
13210 @item @emph{Syntax}:
13211 @code{RESULT = TINY(X)}
13213 @item @emph{Arguments}:
13214 @multitable @columnfractions .15 .70
13215 @item @var{X} @tab Shall be of type @code{REAL}.
13218 @item @emph{Return value}:
13219 The return value is of the same type and kind as @var{X}
13221 @item @emph{Example}:
13222 See @code{HUGE} for an example.
13228 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
13233 @item @emph{Description}:
13234 @code{TRAILZ} returns the number of trailing zero bits of an integer.
13236 @item @emph{Standard}:
13237 Fortran 2008 and later
13239 @item @emph{Class}:
13242 @item @emph{Syntax}:
13243 @code{RESULT = TRAILZ(I)}
13245 @item @emph{Arguments}:
13246 @multitable @columnfractions .15 .70
13247 @item @var{I} @tab Shall be of type @code{INTEGER}.
13250 @item @emph{Return value}:
13251 The type of the return value is the default @code{INTEGER}.
13252 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
13254 @item @emph{Example}:
13256 PROGRAM test_trailz
13257 WRITE (*,*) TRAILZ(8) ! prints 3
13261 @item @emph{See also}:
13262 @ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT}
13268 @section @code{TRANSFER} --- Transfer bit patterns
13274 @item @emph{Description}:
13275 Interprets the bitwise representation of @var{SOURCE} in memory as if it
13276 is the representation of a variable or array of the same type and type
13277 parameters as @var{MOLD}.
13279 This is approximately equivalent to the C concept of @emph{casting} one
13282 @item @emph{Standard}:
13283 Fortran 95 and later
13285 @item @emph{Class}:
13286 Transformational function
13288 @item @emph{Syntax}:
13289 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
13291 @item @emph{Arguments}:
13292 @multitable @columnfractions .15 .70
13293 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
13294 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
13295 @item @var{SIZE} @tab (Optional) shall be a scalar of type
13299 @item @emph{Return value}:
13300 The result has the same type as @var{MOLD}, with the bit level
13301 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
13302 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
13303 but @var{MOLD} is an array (of any size or shape), the result is a one-
13304 dimensional array of the minimum length needed to contain the entirety
13305 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
13306 and @var{MOLD} is a scalar, the result is a scalar.
13308 If the bitwise representation of the result is longer than that of
13309 @var{SOURCE}, then the leading bits of the result correspond to those of
13310 @var{SOURCE} and any trailing bits are filled arbitrarily.
13312 When the resulting bit representation does not correspond to a valid
13313 representation of a variable of the same type as @var{MOLD}, the results
13314 are undefined, and subsequent operations on the result cannot be
13315 guaranteed to produce sensible behavior. For example, it is possible to
13316 create @code{LOGICAL} variables for which @code{@var{VAR}} and
13317 @code{.NOT.@var{VAR}} both appear to be true.
13319 @item @emph{Example}:
13321 PROGRAM test_transfer
13322 integer :: x = 2143289344
13323 print *, transfer(x, 1.0) ! prints "NaN" on i686
13331 @section @code{TRANSPOSE} --- Transpose an array of rank two
13333 @cindex array, transpose
13334 @cindex matrix, transpose
13338 @item @emph{Description}:
13339 Transpose an array of rank two. Element (i, j) of the result has the value
13340 @code{MATRIX(j, i)}, for all i, j.
13342 @item @emph{Standard}:
13343 Fortran 95 and later
13345 @item @emph{Class}:
13346 Transformational function
13348 @item @emph{Syntax}:
13349 @code{RESULT = TRANSPOSE(MATRIX)}
13351 @item @emph{Arguments}:
13352 @multitable @columnfractions .15 .70
13353 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
13356 @item @emph{Return value}:
13357 The result has the same type as @var{MATRIX}, and has shape
13358 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
13364 @section @code{TRIM} --- Remove trailing blank characters of a string
13366 @cindex string, remove trailing whitespace
13369 @item @emph{Description}:
13370 Removes trailing blank characters of a string.
13372 @item @emph{Standard}:
13373 Fortran 95 and later
13375 @item @emph{Class}:
13376 Transformational function
13378 @item @emph{Syntax}:
13379 @code{RESULT = TRIM(STRING)}
13381 @item @emph{Arguments}:
13382 @multitable @columnfractions .15 .70
13383 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
13386 @item @emph{Return value}:
13387 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
13388 less the number of trailing blanks.
13390 @item @emph{Example}:
13393 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
13394 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
13398 @item @emph{See also}:
13399 @ref{ADJUSTL}, @ref{ADJUSTR}
13405 @section @code{TTYNAM} --- Get the name of a terminal device.
13407 @cindex system, terminal
13410 @item @emph{Description}:
13411 Get the name of a terminal device. For more information,
13412 see @code{ttyname(3)}.
13414 This intrinsic is provided in both subroutine and function forms;
13415 however, only one form can be used in any given program unit.
13417 @item @emph{Standard}:
13420 @item @emph{Class}:
13421 Subroutine, function
13423 @item @emph{Syntax}:
13424 @multitable @columnfractions .80
13425 @item @code{CALL TTYNAM(UNIT, NAME)}
13426 @item @code{NAME = TTYNAM(UNIT)}
13429 @item @emph{Arguments}:
13430 @multitable @columnfractions .15 .70
13431 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
13432 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
13435 @item @emph{Example}:
13437 PROGRAM test_ttynam
13440 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
13445 @item @emph{See also}:
13452 @section @code{UBOUND} --- Upper dimension bounds of an array
13454 @cindex array, upper bound
13457 @item @emph{Description}:
13458 Returns the upper bounds of an array, or a single upper bound
13459 along the @var{DIM} dimension.
13460 @item @emph{Standard}:
13461 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
13463 @item @emph{Class}:
13466 @item @emph{Syntax}:
13467 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
13469 @item @emph{Arguments}:
13470 @multitable @columnfractions .15 .70
13471 @item @var{ARRAY} @tab Shall be an array, of any type.
13472 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
13473 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
13474 expression indicating the kind parameter of the result.
13477 @item @emph{Return value}:
13478 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
13479 @var{KIND} is absent, the return value is of default integer kind.
13480 If @var{DIM} is absent, the result is an array of the upper bounds of
13481 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
13482 corresponding to the upper bound of the array along that dimension. If
13483 @var{ARRAY} is an expression rather than a whole array or array
13484 structure component, or if it has a zero extent along the relevant
13485 dimension, the upper bound is taken to be the number of elements along
13486 the relevant dimension.
13488 @item @emph{See also}:
13489 @ref{LBOUND}, @ref{LCOBOUND}
13495 @section @code{UCOBOUND} --- Upper codimension bounds of an array
13497 @cindex coarray, upper bound
13500 @item @emph{Description}:
13501 Returns the upper cobounds of a coarray, or a single upper cobound
13502 along the @var{DIM} codimension.
13503 @item @emph{Standard}:
13504 Fortran 2008 and later
13506 @item @emph{Class}:
13509 @item @emph{Syntax}:
13510 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
13512 @item @emph{Arguments}:
13513 @multitable @columnfractions .15 .70
13514 @item @var{ARRAY} @tab Shall be an coarray, of any type.
13515 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
13516 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
13517 expression indicating the kind parameter of the result.
13520 @item @emph{Return value}:
13521 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
13522 @var{KIND} is absent, the return value is of default integer kind.
13523 If @var{DIM} is absent, the result is an array of the lower cobounds of
13524 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
13525 corresponding to the lower cobound of the array along that codimension.
13527 @item @emph{See also}:
13528 @ref{LCOBOUND}, @ref{LBOUND}
13534 @section @code{UMASK} --- Set the file creation mask
13536 @cindex file system, file creation mask
13539 @item @emph{Description}:
13540 Sets the file creation mask to @var{MASK}. If called as a function, it
13541 returns the old value. If called as a subroutine and argument @var{OLD}
13542 if it is supplied, it is set to the old value. See @code{umask(2)}.
13544 @item @emph{Standard}:
13547 @item @emph{Class}:
13548 Subroutine, function
13550 @item @emph{Syntax}:
13551 @multitable @columnfractions .80
13552 @item @code{CALL UMASK(MASK [, OLD])}
13553 @item @code{OLD = UMASK(MASK)}
13556 @item @emph{Arguments}:
13557 @multitable @columnfractions .15 .70
13558 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
13559 @item @var{OLD} @tab (Optional) Shall be a scalar of type
13568 @section @code{UNLINK} --- Remove a file from the file system
13570 @cindex file system, remove file
13573 @item @emph{Description}:
13574 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
13575 used to mark the end of the name in @var{PATH}; otherwise, trailing
13576 blanks in the file name are ignored. If the @var{STATUS} argument is
13577 supplied, it contains 0 on success or a nonzero error code upon return;
13578 see @code{unlink(2)}.
13580 This intrinsic is provided in both subroutine and function forms;
13581 however, only one form can be used in any given program unit.
13583 @item @emph{Standard}:
13586 @item @emph{Class}:
13587 Subroutine, function
13589 @item @emph{Syntax}:
13590 @multitable @columnfractions .80
13591 @item @code{CALL UNLINK(PATH [, STATUS])}
13592 @item @code{STATUS = UNLINK(PATH)}
13595 @item @emph{Arguments}:
13596 @multitable @columnfractions .15 .70
13597 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
13598 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
13601 @item @emph{See also}:
13602 @ref{LINK}, @ref{SYMLNK}
13608 @section @code{UNPACK} --- Unpack an array of rank one into an array
13610 @cindex array, unpacking
13611 @cindex array, increase dimension
13612 @cindex array, scatter elements
13615 @item @emph{Description}:
13616 Store the elements of @var{VECTOR} in an array of higher rank.
13618 @item @emph{Standard}:
13619 Fortran 95 and later
13621 @item @emph{Class}:
13622 Transformational function
13624 @item @emph{Syntax}:
13625 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
13627 @item @emph{Arguments}:
13628 @multitable @columnfractions .15 .70
13629 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
13630 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
13631 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
13632 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
13633 the same shape as @var{MASK}.
13636 @item @emph{Return value}:
13637 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
13638 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
13640 @item @emph{Example}:
13642 PROGRAM test_unpack
13643 integer :: vector(2) = (/1,1/)
13644 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
13645 integer :: field(2,2) = 0, unity(2,2)
13647 ! result: unity matrix
13648 unity = unpack(vector, reshape(mask, (/2,2/)), field)
13652 @item @emph{See also}:
13653 @ref{PACK}, @ref{SPREAD}
13659 @section @code{VERIFY} --- Scan a string for characters not a given set
13661 @cindex string, find missing set
13664 @item @emph{Description}:
13665 Verifies that all the characters in @var{STRING} belong to the set of
13666 characters in @var{SET}.
13668 If @var{BACK} is either absent or equals @code{FALSE}, this function
13669 returns the position of the leftmost character of @var{STRING} that is
13670 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost
13671 position is returned. If all characters of @var{STRING} are found in
13672 @var{SET}, the result is zero.
13674 @item @emph{Standard}:
13675 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
13677 @item @emph{Class}:
13680 @item @emph{Syntax}:
13681 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
13683 @item @emph{Arguments}:
13684 @multitable @columnfractions .15 .70
13685 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
13686 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
13687 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
13688 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
13689 expression indicating the kind parameter of the result.
13692 @item @emph{Return value}:
13693 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
13694 @var{KIND} is absent, the return value is of default integer kind.
13696 @item @emph{Example}:
13698 PROGRAM test_verify
13699 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
13700 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
13701 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
13702 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
13703 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
13707 @item @emph{See also}:
13708 @ref{SCAN}, @ref{INDEX intrinsic}
13714 @section @code{XOR} --- Bitwise logical exclusive OR
13716 @cindex bitwise logical exclusive or
13717 @cindex logical exclusive or, bitwise
13720 @item @emph{Description}:
13721 Bitwise logical exclusive or.
13723 This intrinsic routine is provided for backwards compatibility with
13724 GNU Fortran 77. For integer arguments, programmers should consider
13725 the use of the @ref{IEOR} intrinsic and for logical arguments the
13726 @code{.NEQV.} operator, which are both defined by the Fortran standard.
13728 @item @emph{Standard}:
13731 @item @emph{Class}:
13734 @item @emph{Syntax}:
13735 @code{RESULT = XOR(I, J)}
13737 @item @emph{Arguments}:
13738 @multitable @columnfractions .15 .70
13739 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
13740 type or a scalar @code{LOGICAL} type.
13741 @item @var{J} @tab The type shall be the same as the type of @var{I}.
13744 @item @emph{Return value}:
13745 The return type is either a scalar @code{INTEGER} or a scalar
13746 @code{LOGICAL}. If the kind type parameters differ, then the
13747 smaller kind type is implicitly converted to larger kind, and the
13748 return has the larger kind.
13750 @item @emph{Example}:
13753 LOGICAL :: T = .TRUE., F = .FALSE.
13755 DATA a / Z'F' /, b / Z'3' /
13757 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
13758 WRITE (*,*) XOR(a, b)
13762 @item @emph{See also}:
13763 Fortran 95 elemental function: @ref{IEOR}
13768 @node Intrinsic Modules
13769 @chapter Intrinsic Modules
13770 @cindex intrinsic Modules
13773 * ISO_FORTRAN_ENV::
13776 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
13779 @node ISO_FORTRAN_ENV
13780 @section @code{ISO_FORTRAN_ENV}
13782 @item @emph{Standard}:
13783 Fortran 2003 and later, except when otherwise noted
13786 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
13790 @item @code{ATOMIC_INT_KIND}:
13791 Default-kind integer constant to be used as kind parameter when defining
13792 integer variables used in atomic operations. (Fortran 2008 or later.)
13794 @item @code{ATOMIC_LOGICAL_KIND}:
13795 Default-kind integer constant to be used as kind parameter when defining
13796 logical variables used in atomic operations. (Fortran 2008 or later.)
13798 @item @code{CHARACTER_KINDS}:
13799 Default-kind integer constant array of rank one containing the supported kind
13800 parameters of the @code{CHARACTER} type. (Fortran 2008 or later.)
13802 @item @code{CHARACTER_STORAGE_SIZE}:
13803 Size in bits of the character storage unit.
13805 @item @code{ERROR_UNIT}:
13806 Identifies the preconnected unit used for error reporting.
13808 @item @code{FILE_STORAGE_SIZE}:
13809 Size in bits of the file-storage unit.
13811 @item @code{INPUT_UNIT}:
13812 Identifies the preconnected unit identified by the asterisk
13813 (@code{*}) in @code{READ} statement.
13815 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
13816 Kind type parameters to specify an INTEGER type with a storage
13817 size of 16, 32, and 64 bits. It is negative if a target platform
13818 does not support the particular kind. (Fortran 2008 or later.)
13820 @item @code{INTEGER_KINDS}:
13821 Default-kind integer constant array of rank one containing the supported kind
13822 parameters of the @code{INTEGER} type. (Fortran 2008 or later.)
13824 @item @code{IOSTAT_END}:
13825 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
13826 an input/output statement if an end-of-file condition occurred.
13828 @item @code{IOSTAT_EOR}:
13829 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
13830 an input/output statement if an end-of-record condition occurred.
13832 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
13833 Scalar default-integer constant, used by @code{INQUIRE} for the
13834 @code{IOSTAT=} specifier to denote an that a unit number identifies an
13835 internal unit. (Fortran 2008 or later.)
13837 @item @code{NUMERIC_STORAGE_SIZE}:
13838 The size in bits of the numeric storage unit.
13840 @item @code{LOGICAL_KINDS}:
13841 Default-kind integer constant array of rank one containing the supported kind
13842 parameters of the @code{LOGICAL} type. (Fortran 2008 or later.)
13844 @item @code{OUTPUT_UNIT}:
13845 Identifies the preconnected unit identified by the asterisk
13846 (@code{*}) in @code{WRITE} statement.
13848 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
13849 Kind type parameters to specify a REAL type with a storage
13850 size of 32, 64, and 128 bits. It is negative if a target platform
13851 does not support the particular kind. (Fortran 2008 or later.)
13853 @item @code{REAL_KINDS}:
13854 Default-kind integer constant array of rank one containing the supported kind
13855 parameters of the @code{REAL} type. (Fortran 2008 or later.)
13857 @item @code{STAT_LOCKED}:
13858 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
13859 denote that the lock variable is locked by the executing image. (Fortran 2008
13862 @item @code{STAT_LOCKED_OTHER_IMAGE}:
13863 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
13864 denote that the lock variable is locked by another image. (Fortran 2008 or
13867 @item @code{STAT_STOPPED_IMAGE}:
13868 Positive, scalar default-integer constant used as STAT= return value if the
13869 argument in the statement requires synchronisation with an image, which has
13870 initiated the termination of the execution. (Fortran 2008 or later.)
13872 @item @code{STAT_FAILED_IMAGE}:
13873 Positive, scalar default-integer constant used as STAT= return value if the
13874 argument in the statement requires communication with an image, which has
13875 is in the failed state. (TS 18508 or later.)
13877 @item @code{STAT_UNLOCKED}:
13878 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
13879 denote that the lock variable is unlocked. (Fortran 2008 or later.)
13882 The module provides the following derived type:
13885 @item @code{LOCK_TYPE}:
13886 Derived type with private components to be use with the @code{LOCK} and
13887 @code{UNLOCK} statement. A variable of its type has to be always declared
13888 as coarray and may not appear in a variable-definition context.
13889 (Fortran 2008 or later.)
13892 The module also provides the following intrinsic procedures:
13893 @ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}.
13897 @node ISO_C_BINDING
13898 @section @code{ISO_C_BINDING}
13900 @item @emph{Standard}:
13901 Fortran 2003 and later, GNU extensions
13904 The following intrinsic procedures are provided by the module; their
13905 definition can be found in the section Intrinsic Procedures of this
13909 @item @code{C_ASSOCIATED}
13910 @item @code{C_F_POINTER}
13911 @item @code{C_F_PROCPOINTER}
13912 @item @code{C_FUNLOC}
13914 @item @code{C_SIZEOF}
13916 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
13917 @c don't really know why.
13919 The @code{ISO_C_BINDING} module provides the following named constants of
13920 type default integer, which can be used as KIND type parameters.
13922 In addition to the integer named constants required by the Fortran 2003
13923 standard and @code{C_PTRDIFF_T} of TS 29113, GNU Fortran provides as an
13924 extension named constants for the 128-bit integer types supported by the
13925 C compiler: @code{C_INT128_T, C_INT_LEAST128_T, C_INT_FAST128_T}.
13926 Furthermore, if @code{__float128} is supported in C, the named constants
13927 @code{C_FLOAT128, C_FLOAT128_COMPLEX} are defined.
13929 @multitable @columnfractions .15 .35 .35 .35
13930 @item Fortran Type @tab Named constant @tab C type @tab Extension
13931 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
13932 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
13933 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
13934 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
13935 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
13936 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
13937 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
13938 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
13939 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
13940 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
13941 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
13942 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
13943 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
13944 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
13945 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
13946 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
13947 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
13948 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
13949 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
13950 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
13951 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
13952 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
13953 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
13954 @item @code{INTEGER}@tab @code{C_PTRDIFF_T} @tab @code{intptr_t} @tab TS 29113
13955 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
13956 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
13957 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
13958 @item @code{REAL} @tab @code{C_FLOAT128} @tab @code{__float128} @tab Ext.
13959 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
13960 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
13961 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
13962 @item @code{REAL} @tab @code{C_FLOAT128_COMPLEX} @tab @code{__float128 _Complex} @tab Ext.
13963 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
13964 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
13967 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
13970 @multitable @columnfractions .20 .45 .15
13971 @item Name @tab C definition @tab Value
13972 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
13973 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
13974 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
13975 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
13976 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
13977 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
13978 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
13979 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
13982 Moreover, the following two named constants are defined:
13984 @multitable @columnfractions .20 .80
13985 @item Name @tab Type
13986 @item @code{C_NULL_PTR} @tab @code{C_PTR}
13987 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
13990 Both are equivalent to the value @code{NULL} in C.
13995 @section IEEE modules: @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
13997 @item @emph{Standard}:
13998 Fortran 2003 and later
14001 The @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
14002 intrinsic modules provide support for exceptions and IEEE arithmetic, as
14003 defined in Fortran 2003 and later standards, and the IEC 60559:1989 standard
14004 (@emph{Binary floating-point arithmetic for microprocessor systems}). These
14005 modules are only provided on the following supported platforms:
14008 @item i386 and x86_64 processors
14009 @item platforms which use the GNU C Library (glibc)
14010 @item platforms with support for SysV/386 routines for floating point
14011 interface (including Solaris and BSDs)
14012 @item platforms with the AIX OS
14015 For full compliance with the Fortran standards, code using the
14016 @code{IEEE_EXCEPTIONS} or @code{IEEE_ARITHMETIC} modules should be compiled
14017 with the following options: @code{-fno-unsafe-math-optimizations
14018 -frounding-math -fsignaling-nans}.
14021 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
14022 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
14024 @item @emph{Standard}:
14025 OpenMP Application Program Interface v4.0
14029 The OpenMP Fortran runtime library routines are provided both in
14030 a form of two Fortran 90 modules, named @code{OMP_LIB} and
14031 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
14032 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
14033 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
14034 the named constants defined in the modules are listed
14037 For details refer to the actual
14038 @uref{http://www.openmp.org/mp-documents/OpenMP4.0.0.pdf,
14039 OpenMP Application Program Interface v4.0}.
14041 @code{OMP_LIB_KINDS} provides the following scalar default-integer
14045 @item @code{omp_lock_kind}
14046 @item @code{omp_nest_lock_kind}
14047 @item @code{omp_proc_bind_kind}
14048 @item @code{omp_sched_kind}
14051 @code{OMP_LIB} provides the scalar default-integer
14052 named constant @code{openmp_version} with a value of the form
14053 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
14054 of the OpenMP version; for OpenMP v4.0 the value is @code{201307}.
14056 The following scalar integer named constants of the
14057 kind @code{omp_sched_kind}:
14060 @item @code{omp_sched_static}
14061 @item @code{omp_sched_dynamic}
14062 @item @code{omp_sched_guided}
14063 @item @code{omp_sched_auto}
14066 And the following scalar integer named constants of the
14067 kind @code{omp_proc_bind_kind}:
14070 @item @code{omp_proc_bind_false}
14071 @item @code{omp_proc_bind_true}
14072 @item @code{omp_proc_bind_master}
14073 @item @code{omp_proc_bind_close}
14074 @item @code{omp_proc_bind_spread}