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_SUM}: CO_SUM, Sum of values on the current set of images
102 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
103 * @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler
104 * @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string
105 * @code{COMPLEX}: COMPLEX, Complex conversion function
106 * @code{CONJG}: CONJG, Complex conjugate function
107 * @code{COS}: COS, Cosine function
108 * @code{COSH}: COSH, Hyperbolic cosine function
109 * @code{COUNT}: COUNT, Count occurrences of TRUE in an array
110 * @code{CPU_TIME}: CPU_TIME, CPU time subroutine
111 * @code{CSHIFT}: CSHIFT, Circular shift elements of an array
112 * @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string
113 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
114 * @code{DBLE}: DBLE, Double precision conversion function
115 * @code{DCMPLX}: DCMPLX, Double complex conversion function
116 * @code{DIGITS}: DIGITS, Significant digits function
117 * @code{DIM}: DIM, Positive difference
118 * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
119 * @code{DPROD}: DPROD, Double product function
120 * @code{DREAL}: DREAL, Double real part function
121 * @code{DSHIFTL}: DSHIFTL, Combined left shift
122 * @code{DSHIFTR}: DSHIFTR, Combined right shift
123 * @code{DTIME}: DTIME, Execution time subroutine (or function)
124 * @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array
125 * @code{EPSILON}: EPSILON, Epsilon function
126 * @code{ERF}: ERF, Error function
127 * @code{ERFC}: ERFC, Complementary error function
128 * @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function
129 * @code{ETIME}: ETIME, Execution time subroutine (or function)
130 * @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command
131 * @code{EXIT}: EXIT, Exit the program with status.
132 * @code{EXP}: EXP, Exponential function
133 * @code{EXPONENT}: EXPONENT, Exponent function
134 * @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF, Query dynamic type for extension
135 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
136 * @code{FGET}: FGET, Read a single character in stream mode from stdin
137 * @code{FGETC}: FGETC, Read a single character in stream mode
138 * @code{FLOOR}: FLOOR, Integer floor function
139 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
140 * @code{FNUM}: FNUM, File number function
141 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
142 * @code{FPUTC}: FPUTC, Write a single character in stream mode
143 * @code{FRACTION}: FRACTION, Fractional part of the model representation
144 * @code{FREE}: FREE, Memory de-allocation subroutine
145 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
146 * @code{FSTAT}: FSTAT, Get file status
147 * @code{FTELL}: FTELL, Current stream position
148 * @code{GAMMA}: GAMMA, Gamma function
149 * @code{GERROR}: GERROR, Get last system error message
150 * @code{GETARG}: GETARG, Get command line arguments
151 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
152 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
153 * @code{GETCWD}: GETCWD, Get current working directory
154 * @code{GETENV}: GETENV, Get an environmental variable
155 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
156 * @code{GETGID}: GETGID, Group ID function
157 * @code{GETLOG}: GETLOG, Get login name
158 * @code{GETPID}: GETPID, Process ID function
159 * @code{GETUID}: GETUID, User ID function
160 * @code{GMTIME}: GMTIME, Convert time to GMT info
161 * @code{HOSTNM}: HOSTNM, Get system host name
162 * @code{HUGE}: HUGE, Largest number of a kind
163 * @code{HYPOT}: HYPOT, Euclidean distance function
164 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
165 * @code{IALL}: IALL, Bitwise AND of array elements
166 * @code{IAND}: IAND, Bitwise logical and
167 * @code{IANY}: IANY, Bitwise OR of array elements
168 * @code{IARGC}: IARGC, Get the number of command line arguments
169 * @code{IBCLR}: IBCLR, Clear bit
170 * @code{IBITS}: IBITS, Bit extraction
171 * @code{IBSET}: IBSET, Set bit
172 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
173 * @code{IDATE}: IDATE, Current local time (day/month/year)
174 * @code{IEOR}: IEOR, Bitwise logical exclusive or
175 * @code{IERRNO}: IERRNO, Function to get the last system error number
176 * @code{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index conversion
177 * @code{INDEX}: INDEX intrinsic, Position of a substring within a string
178 * @code{INT}: INT, Convert to integer type
179 * @code{INT2}: INT2, Convert to 16-bit integer type
180 * @code{INT8}: INT8, Convert to 64-bit integer type
181 * @code{IOR}: IOR, Bitwise logical or
182 * @code{IPARITY}: IPARITY, Bitwise XOR of array elements
183 * @code{IRAND}: IRAND, Integer pseudo-random number
184 * @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value
185 * @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value
186 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
187 * @code{ISHFT}: ISHFT, Shift bits
188 * @code{ISHFTC}: ISHFTC, Shift bits circularly
189 * @code{ISNAN}: ISNAN, Tests for a NaN
190 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
191 * @code{KILL}: KILL, Send a signal to a process
192 * @code{KIND}: KIND, Kind of an entity
193 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
194 * @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array
195 * @code{LEADZ}: LEADZ, Number of leading zero bits of an integer
196 * @code{LEN}: LEN, Length of a character entity
197 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
198 * @code{LGE}: LGE, Lexical greater than or equal
199 * @code{LGT}: LGT, Lexical greater than
200 * @code{LINK}: LINK, Create a hard link
201 * @code{LLE}: LLE, Lexical less than or equal
202 * @code{LLT}: LLT, Lexical less than
203 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
204 * @code{LOC}: LOC, Returns the address of a variable
205 * @code{LOG}: LOG, Logarithm function
206 * @code{LOG10}: LOG10, Base 10 logarithm function
207 * @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
208 * @code{LOGICAL}: LOGICAL, Convert to logical type
209 * @code{LONG}: LONG, Convert to integer type
210 * @code{LSHIFT}: LSHIFT, Left shift bits
211 * @code{LSTAT}: LSTAT, Get file status
212 * @code{LTIME}: LTIME, Convert time to local time info
213 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
214 * @code{MASKL}: MASKL, Left justified mask
215 * @code{MASKR}: MASKR, Right justified mask
216 * @code{MATMUL}: MATMUL, matrix multiplication
217 * @code{MAX}: MAX, Maximum value of an argument list
218 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
219 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
220 * @code{MAXVAL}: MAXVAL, Maximum value of an array
221 * @code{MCLOCK}: MCLOCK, Time function
222 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
223 * @code{MERGE}: MERGE, Merge arrays
224 * @code{MERGE_BITS}: MERGE_BITS, Merge of bits under mask
225 * @code{MIN}: MIN, Minimum value of an argument list
226 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
227 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
228 * @code{MINVAL}: MINVAL, Minimum value of an array
229 * @code{MOD}: MOD, Remainder function
230 * @code{MODULO}: MODULO, Modulo function
231 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
232 * @code{MVBITS}: MVBITS, Move bits from one integer to another
233 * @code{NEAREST}: NEAREST, Nearest representable number
234 * @code{NEW_LINE}: NEW_LINE, New line character
235 * @code{NINT}: NINT, Nearest whole number
236 * @code{NORM2}: NORM2, Euclidean vector norm
237 * @code{NOT}: NOT, Logical negation
238 * @code{NULL}: NULL, Function that returns an disassociated pointer
239 * @code{NUM_IMAGES}: NUM_IMAGES, Number of images
240 * @code{OR}: OR, Bitwise logical OR
241 * @code{PACK}: PACK, Pack an array into an array of rank one
242 * @code{PARITY}: PARITY, Reduction with exclusive OR
243 * @code{PERROR}: PERROR, Print system error message
244 * @code{POPCNT}: POPCNT, Number of bits set
245 * @code{POPPAR}: POPPAR, Parity of the number of bits set
246 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
247 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
248 * @code{PRODUCT}: PRODUCT, Product of array elements
249 * @code{RADIX}: RADIX, Base of a data model
250 * @code{RAN}: RAN, Real pseudo-random number
251 * @code{RAND}: RAND, Real pseudo-random number
252 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
253 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
254 * @code{RANGE}: RANGE, Decimal exponent range
255 * @code{RANK} : RANK, Rank of a data object
256 * @code{REAL}: REAL, Convert to real type
257 * @code{RENAME}: RENAME, Rename a file
258 * @code{REPEAT}: REPEAT, Repeated string concatenation
259 * @code{RESHAPE}: RESHAPE, Function to reshape an array
260 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
261 * @code{RSHIFT}: RSHIFT, Right shift bits
262 * @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality
263 * @code{SCALE}: SCALE, Scale a real value
264 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
265 * @code{SECNDS}: SECNDS, Time function
266 * @code{SECOND}: SECOND, CPU time function
267 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind
268 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
269 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
270 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
271 * @code{SHAPE}: SHAPE, Determine the shape of an array
272 * @code{SHIFTA}: SHIFTA, Right shift with fill
273 * @code{SHIFTL}: SHIFTL, Left shift
274 * @code{SHIFTR}: SHIFTR, Right shift
275 * @code{SIGN}: SIGN, Sign copying function
276 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
277 * @code{SIN}: SIN, Sine function
278 * @code{SINH}: SINH, Hyperbolic sine function
279 * @code{SIZE}: SIZE, Function to determine the size of an array
280 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
281 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
282 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
283 * @code{SPREAD}: SPREAD, Add a dimension to an array
284 * @code{SQRT}: SQRT, Square-root function
285 * @code{SRAND}: SRAND, Reinitialize the random number generator
286 * @code{STAT}: STAT, Get file status
287 * @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits
288 * @code{SUM}: SUM, Sum of array elements
289 * @code{SYMLNK}: SYMLNK, Create a symbolic link
290 * @code{SYSTEM}: SYSTEM, Execute a shell command
291 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
292 * @code{TAN}: TAN, Tangent function
293 * @code{TANH}: TANH, Hyperbolic tangent function
294 * @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image
295 * @code{TIME}: TIME, Time function
296 * @code{TIME8}: TIME8, Time function (64-bit)
297 * @code{TINY}: TINY, Smallest positive number of a real kind
298 * @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer
299 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
300 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
301 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
302 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
303 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
304 * @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array
305 * @code{UMASK}: UMASK, Set the file creation mask
306 * @code{UNLINK}: UNLINK, Remove a file from the file system
307 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
308 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
309 * @code{XOR}: XOR, Bitwise logical exclusive or
312 @node Introduction to Intrinsics
313 @section Introduction to intrinsic procedures
315 The intrinsic procedures provided by GNU Fortran include all of the
316 intrinsic procedures required by the Fortran 95 standard, a set of
317 intrinsic procedures for backwards compatibility with G77, and a
318 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
319 standards. Any conflict between a description here and a description in
320 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
321 2008 standard is unintentional, and the standard(s) should be considered
324 The enumeration of the @code{KIND} type parameter is processor defined in
325 the Fortran 95 standard. GNU Fortran defines the default integer type and
326 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
327 respectively. The standard mandates that both data types shall have
328 another kind, which have more precision. On typical target architectures
329 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
330 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
331 In the description of generic intrinsic procedures, the kind type parameter
332 will be specified by @code{KIND=*}, and in the description of specific
333 names for an intrinsic procedure the kind type parameter will be explicitly
334 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
335 brevity the optional @code{KIND=} syntax will be omitted.
337 Many of the intrinsic procedures take one or more optional arguments.
338 This document follows the convention used in the Fortran 95 standard,
339 and denotes such arguments by square brackets.
341 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
342 which can be used to restrict the set of intrinsic procedures to a
343 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
344 option, and so all intrinsic procedures described here are accepted. There
345 is one caveat. For a select group of intrinsic procedures, @command{g77}
346 implemented both a function and a subroutine. Both classes
347 have been implemented in @command{gfortran} for backwards compatibility
348 with @command{g77}. It is noted here that these functions and subroutines
349 cannot be intermixed in a given subprogram. In the descriptions that follow,
350 the applicable standard for each intrinsic procedure is noted.
355 @section @code{ABORT} --- Abort the program
357 @cindex program termination, with core dump
358 @cindex terminate program, with core dump
362 @item @emph{Description}:
363 @code{ABORT} causes immediate termination of the program. On operating
364 systems that support a core dump, @code{ABORT} will produce a core dump.
365 It will also print a backtrace, unless @code{-fno-backtrace} is given.
367 @item @emph{Standard}:
376 @item @emph{Return value}:
379 @item @emph{Example}:
382 integer :: i = 1, j = 2
383 if (i /= j) call abort
384 end program test_abort
387 @item @emph{See also}:
388 @ref{EXIT}, @ref{KILL}, @ref{BACKTRACE}
395 @section @code{ABS} --- Absolute value
402 @cindex absolute value
405 @item @emph{Description}:
406 @code{ABS(A)} computes the absolute value of @code{A}.
408 @item @emph{Standard}:
409 Fortran 77 and later, has overloads that are GNU extensions
415 @code{RESULT = ABS(A)}
417 @item @emph{Arguments}:
418 @multitable @columnfractions .15 .70
419 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
420 @code{REAL}, or @code{COMPLEX}.
423 @item @emph{Return value}:
424 The return value is of the same type and
425 kind as the argument except the return value is @code{REAL} for a
426 @code{COMPLEX} argument.
428 @item @emph{Example}:
433 complex :: z = (-1.e0,0.e0)
440 @item @emph{Specific names}:
441 @multitable @columnfractions .20 .20 .20 .25
442 @item Name @tab Argument @tab Return type @tab Standard
443 @item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
444 @item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
445 @item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
446 @item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
447 @item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
448 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
455 @section @code{ACCESS} --- Checks file access modes
457 @cindex file system, access mode
460 @item @emph{Description}:
461 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
462 exists, is readable, writable or executable. Except for the
463 executable check, @code{ACCESS} can be replaced by
464 Fortran 95's @code{INQUIRE}.
466 @item @emph{Standard}:
473 @code{RESULT = ACCESS(NAME, MODE)}
475 @item @emph{Arguments}:
476 @multitable @columnfractions .15 .70
477 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
478 file name. Tailing blank are ignored unless the character @code{achar(0)}
479 is present, then all characters up to and excluding @code{achar(0)} are
481 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
482 file access mode, may be any concatenation of @code{"r"} (readable),
483 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
487 @item @emph{Return value}:
488 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
489 accessible in the given mode; otherwise or if an invalid argument
490 has been given for @code{MODE} the value @code{1} is returned.
492 @item @emph{Example}:
496 character(len=*), parameter :: file = 'test.dat'
497 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
498 if(access(file,' ') == 0) print *, trim(file),' is exists'
499 if(access(file,'r') == 0) print *, trim(file),' is readable'
500 if(access(file,'w') == 0) print *, trim(file),' is writable'
501 if(access(file,'x') == 0) print *, trim(file),' is executable'
502 if(access(file2,'rwx') == 0) &
503 print *, trim(file2),' is readable, writable and executable'
504 end program access_test
506 @item @emph{Specific names}:
507 @item @emph{See also}:
514 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
516 @cindex @acronym{ASCII} collating sequence
517 @cindex collating sequence, @acronym{ASCII}
520 @item @emph{Description}:
521 @code{ACHAR(I)} returns the character located at position @code{I}
522 in the @acronym{ASCII} collating sequence.
524 @item @emph{Standard}:
525 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
531 @code{RESULT = ACHAR(I [, KIND])}
533 @item @emph{Arguments}:
534 @multitable @columnfractions .15 .70
535 @item @var{I} @tab The type shall be @code{INTEGER}.
536 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
537 expression indicating the kind parameter of the result.
540 @item @emph{Return value}:
541 The return value is of type @code{CHARACTER} with a length of one.
542 If the @var{KIND} argument is present, the return value is of the
543 specified kind and of the default kind otherwise.
545 @item @emph{Example}:
550 end program test_achar
554 See @ref{ICHAR} for a discussion of converting between numerical values
555 and formatted string representations.
557 @item @emph{See also}:
558 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
565 @section @code{ACOS} --- Arccosine function
568 @cindex trigonometric function, cosine, inverse
569 @cindex cosine, inverse
572 @item @emph{Description}:
573 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
575 @item @emph{Standard}:
576 Fortran 77 and later, for a complex argument Fortran 2008 or later
582 @code{RESULT = ACOS(X)}
584 @item @emph{Arguments}:
585 @multitable @columnfractions .15 .70
586 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
587 less than or equal to one - or the type shall be @code{COMPLEX}.
590 @item @emph{Return value}:
591 The return value is of the same type and kind as @var{X}.
592 The real part of the result is in radians and lies in the range
593 @math{0 \leq \Re \acos(x) \leq \pi}.
595 @item @emph{Example}:
598 real(8) :: x = 0.866_8
600 end program test_acos
603 @item @emph{Specific names}:
604 @multitable @columnfractions .20 .20 .20 .25
605 @item Name @tab Argument @tab Return type @tab Standard
606 @item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
607 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
610 @item @emph{See also}:
611 Inverse function: @ref{COS}
618 @section @code{ACOSH} --- Inverse hyperbolic cosine function
621 @cindex area hyperbolic cosine
622 @cindex inverse hyperbolic cosine
623 @cindex hyperbolic function, cosine, inverse
624 @cindex cosine, hyperbolic, inverse
627 @item @emph{Description}:
628 @code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
630 @item @emph{Standard}:
631 Fortran 2008 and later
637 @code{RESULT = ACOSH(X)}
639 @item @emph{Arguments}:
640 @multitable @columnfractions .15 .70
641 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
644 @item @emph{Return value}:
645 The return value has the same type and kind as @var{X}. If @var{X} is
646 complex, the imaginary part of the result is in radians and lies between
647 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
649 @item @emph{Example}:
652 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
657 @item @emph{Specific names}:
658 @multitable @columnfractions .20 .20 .20 .25
659 @item Name @tab Argument @tab Return type @tab Standard
660 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
663 @item @emph{See also}:
664 Inverse function: @ref{COSH}
670 @section @code{ADJUSTL} --- Left adjust a string
672 @cindex string, adjust left
673 @cindex adjust string
676 @item @emph{Description}:
677 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
678 Spaces are inserted at the end of the string as needed.
680 @item @emph{Standard}:
687 @code{RESULT = ADJUSTL(STRING)}
689 @item @emph{Arguments}:
690 @multitable @columnfractions .15 .70
691 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
694 @item @emph{Return value}:
695 The return value is of type @code{CHARACTER} and of the same kind as
696 @var{STRING} where leading spaces are removed and the same number of
697 spaces are inserted on the end of @var{STRING}.
699 @item @emph{Example}:
702 character(len=20) :: str = ' gfortran'
705 end program test_adjustl
708 @item @emph{See also}:
709 @ref{ADJUSTR}, @ref{TRIM}
715 @section @code{ADJUSTR} --- Right adjust a string
717 @cindex string, adjust right
718 @cindex adjust string
721 @item @emph{Description}:
722 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
723 Spaces are inserted at the start of the string as needed.
725 @item @emph{Standard}:
732 @code{RESULT = ADJUSTR(STRING)}
734 @item @emph{Arguments}:
735 @multitable @columnfractions .15 .70
736 @item @var{STR} @tab The type shall be @code{CHARACTER}.
739 @item @emph{Return value}:
740 The return value is of type @code{CHARACTER} and of the same kind as
741 @var{STRING} where trailing spaces are removed and the same number of
742 spaces are inserted at the start of @var{STRING}.
744 @item @emph{Example}:
747 character(len=20) :: str = 'gfortran'
750 end program test_adjustr
753 @item @emph{See also}:
754 @ref{ADJUSTL}, @ref{TRIM}
760 @section @code{AIMAG} --- Imaginary part of complex number
765 @cindex complex numbers, imaginary part
768 @item @emph{Description}:
769 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
770 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
771 for compatibility with @command{g77}, and their use in new code is
772 strongly discouraged.
774 @item @emph{Standard}:
775 Fortran 77 and later, has overloads that are GNU extensions
781 @code{RESULT = AIMAG(Z)}
783 @item @emph{Arguments}:
784 @multitable @columnfractions .15 .70
785 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
788 @item @emph{Return value}:
789 The return value is of type @code{REAL} with the
790 kind type parameter of the argument.
792 @item @emph{Example}:
797 z4 = cmplx(1.e0_4, 0.e0_4)
798 z8 = cmplx(0.e0_8, 1.e0_8)
799 print *, aimag(z4), dimag(z8)
800 end program test_aimag
803 @item @emph{Specific names}:
804 @multitable @columnfractions .20 .20 .20 .25
805 @item Name @tab Argument @tab Return type @tab Standard
806 @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
807 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
808 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
809 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
816 @section @code{AINT} --- Truncate to a whole number
820 @cindex rounding, floor
823 @item @emph{Description}:
824 @code{AINT(A [, KIND])} truncates its argument to a whole number.
826 @item @emph{Standard}:
833 @code{RESULT = AINT(A [, KIND])}
835 @item @emph{Arguments}:
836 @multitable @columnfractions .15 .70
837 @item @var{A} @tab The type of the argument shall be @code{REAL}.
838 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
839 expression indicating the kind parameter of the result.
842 @item @emph{Return value}:
843 The return value is of type @code{REAL} with the kind type parameter of the
844 argument if the optional @var{KIND} is absent; otherwise, the kind
845 type parameter will be given by @var{KIND}. If the magnitude of
846 @var{X} is less than one, @code{AINT(X)} returns zero. If the
847 magnitude is equal to or greater than one then it returns the largest
848 whole number that does not exceed its magnitude. The sign is the same
849 as the sign of @var{X}.
851 @item @emph{Example}:
858 print *, aint(x4), dint(x8)
860 end program test_aint
863 @item @emph{Specific names}:
864 @multitable @columnfractions .20 .20 .20 .25
865 @item Name @tab Argument @tab Return type @tab Standard
866 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
867 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
874 @section @code{ALARM} --- Execute a routine after a given delay
876 @cindex delayed execution
879 @item @emph{Description}:
880 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
881 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
882 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
883 supplied, it will be returned with the number of seconds remaining until
884 any previously scheduled alarm was due to be delivered, or zero if there
885 was no previously scheduled alarm.
887 @item @emph{Standard}:
894 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
896 @item @emph{Arguments}:
897 @multitable @columnfractions .15 .70
898 @item @var{SECONDS} @tab The type of the argument shall be a scalar
899 @code{INTEGER}. It is @code{INTENT(IN)}.
900 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
901 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
902 values may be either @code{SIG_IGN=1} to ignore the alarm generated
903 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
904 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
905 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
908 @item @emph{Example}:
911 external handler_print
913 call alarm (3, handler_print, i)
916 end program test_alarm
918 This will cause the external routine @var{handler_print} to be called
925 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
927 @cindex array, apply condition
928 @cindex array, condition testing
931 @item @emph{Description}:
932 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
933 in the array along dimension @var{DIM}.
935 @item @emph{Standard}:
939 Transformational function
942 @code{RESULT = ALL(MASK [, DIM])}
944 @item @emph{Arguments}:
945 @multitable @columnfractions .15 .70
946 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
947 it shall not be scalar.
948 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
949 with a value that lies between one and the rank of @var{MASK}.
952 @item @emph{Return value}:
953 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
954 the kind type parameter is the same as the kind type parameter of
955 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
956 an array with the rank of @var{MASK} minus 1. The shape is determined from
957 the shape of @var{MASK} where the @var{DIM} dimension is elided.
961 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
962 It also is true if @var{MASK} has zero size; otherwise, it is false.
964 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
965 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
966 is determined by applying @code{ALL} to the array sections.
969 @item @emph{Example}:
973 l = all((/.true., .true., .true./))
978 integer a(2,3), b(2,3)
982 print *, all(a .eq. b, 1)
983 print *, all(a .eq. b, 2)
984 end subroutine section
992 @section @code{ALLOCATED} --- Status of an allocatable entity
994 @cindex allocation, status
997 @item @emph{Description}:
998 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
999 status of @var{ARRAY} and @var{SCALAR}, respectively.
1001 @item @emph{Standard}:
1002 Fortran 95 and later. Note, the @code{SCALAR=} keyword and allocatable
1003 scalar entities are available in Fortran 2003 and later.
1008 @item @emph{Syntax}:
1009 @multitable @columnfractions .80
1010 @item @code{RESULT = ALLOCATED(ARRAY)}
1011 @item @code{RESULT = ALLOCATED(SCALAR)}
1014 @item @emph{Arguments}:
1015 @multitable @columnfractions .15 .70
1016 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
1017 @item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar.
1020 @item @emph{Return value}:
1021 The return value is a scalar @code{LOGICAL} with the default logical
1022 kind type parameter. If the argument is allocated, then the result is
1023 @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
1025 @item @emph{Example}:
1027 program test_allocated
1029 real(4), allocatable :: x(:)
1030 if (.not. allocated(x)) allocate(x(i))
1031 end program test_allocated
1038 @section @code{AND} --- Bitwise logical AND
1040 @cindex bitwise logical and
1041 @cindex logical and, bitwise
1044 @item @emph{Description}:
1045 Bitwise logical @code{AND}.
1047 This intrinsic routine is provided for backwards compatibility with
1048 GNU Fortran 77. For integer arguments, programmers should consider
1049 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1051 @item @emph{Standard}:
1057 @item @emph{Syntax}:
1058 @code{RESULT = AND(I, J)}
1060 @item @emph{Arguments}:
1061 @multitable @columnfractions .15 .70
1062 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1063 type or a scalar @code{LOGICAL} type.
1064 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1067 @item @emph{Return value}:
1068 The return type is either a scalar @code{INTEGER} or a scalar
1069 @code{LOGICAL}. If the kind type parameters differ, then the
1070 smaller kind type is implicitly converted to larger kind, and the
1071 return has the larger kind.
1073 @item @emph{Example}:
1076 LOGICAL :: T = .TRUE., F = .FALSE.
1078 DATA a / Z'F' /, b / Z'3' /
1080 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1081 WRITE (*,*) AND(a, b)
1085 @item @emph{See also}:
1086 Fortran 95 elemental function: @ref{IAND}
1092 @section @code{ANINT} --- Nearest whole number
1096 @cindex rounding, ceiling
1099 @item @emph{Description}:
1100 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1102 @item @emph{Standard}:
1103 Fortran 77 and later
1108 @item @emph{Syntax}:
1109 @code{RESULT = ANINT(A [, KIND])}
1111 @item @emph{Arguments}:
1112 @multitable @columnfractions .15 .70
1113 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1114 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1115 expression indicating the kind parameter of the result.
1118 @item @emph{Return value}:
1119 The return value is of type real with the kind type parameter of the
1120 argument if the optional @var{KIND} is absent; otherwise, the kind
1121 type parameter will be given by @var{KIND}. If @var{A} is greater than
1122 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1123 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1125 @item @emph{Example}:
1132 print *, anint(x4), dnint(x8)
1134 end program test_anint
1137 @item @emph{Specific names}:
1138 @multitable @columnfractions .20 .20 .20 .25
1139 @item Name @tab Argument @tab Return type @tab Standard
1140 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
1141 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1148 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1150 @cindex array, apply condition
1151 @cindex array, condition testing
1154 @item @emph{Description}:
1155 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1156 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1158 @item @emph{Standard}:
1159 Fortran 95 and later
1162 Transformational function
1164 @item @emph{Syntax}:
1165 @code{RESULT = ANY(MASK [, DIM])}
1167 @item @emph{Arguments}:
1168 @multitable @columnfractions .15 .70
1169 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1170 it shall not be scalar.
1171 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1172 with a value that lies between one and the rank of @var{MASK}.
1175 @item @emph{Return value}:
1176 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1177 the kind type parameter is the same as the kind type parameter of
1178 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1179 an array with the rank of @var{MASK} minus 1. The shape is determined from
1180 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1184 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1185 otherwise, it is false. It also is false if @var{MASK} has zero size.
1187 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1188 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1189 is determined by applying @code{ANY} to the array sections.
1192 @item @emph{Example}:
1196 l = any((/.true., .true., .true./))
1201 integer a(2,3), b(2,3)
1205 print *, any(a .eq. b, 1)
1206 print *, any(a .eq. b, 2)
1207 end subroutine section
1208 end program test_any
1215 @section @code{ASIN} --- Arcsine function
1218 @cindex trigonometric function, sine, inverse
1219 @cindex sine, inverse
1222 @item @emph{Description}:
1223 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1225 @item @emph{Standard}:
1226 Fortran 77 and later, for a complex argument Fortran 2008 or later
1231 @item @emph{Syntax}:
1232 @code{RESULT = ASIN(X)}
1234 @item @emph{Arguments}:
1235 @multitable @columnfractions .15 .70
1236 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1237 less than or equal to one - or be @code{COMPLEX}.
1240 @item @emph{Return value}:
1241 The return value is of the same type and kind as @var{X}.
1242 The real part of the result is in radians and lies in the range
1243 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1245 @item @emph{Example}:
1248 real(8) :: x = 0.866_8
1250 end program test_asin
1253 @item @emph{Specific names}:
1254 @multitable @columnfractions .20 .20 .20 .25
1255 @item Name @tab Argument @tab Return type @tab Standard
1256 @item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1257 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1260 @item @emph{See also}:
1261 Inverse function: @ref{SIN}
1268 @section @code{ASINH} --- Inverse hyperbolic sine function
1271 @cindex area hyperbolic sine
1272 @cindex inverse hyperbolic sine
1273 @cindex hyperbolic function, sine, inverse
1274 @cindex sine, hyperbolic, inverse
1277 @item @emph{Description}:
1278 @code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
1280 @item @emph{Standard}:
1281 Fortran 2008 and later
1286 @item @emph{Syntax}:
1287 @code{RESULT = ASINH(X)}
1289 @item @emph{Arguments}:
1290 @multitable @columnfractions .15 .70
1291 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1294 @item @emph{Return value}:
1295 The return value is of the same type and kind as @var{X}. If @var{X} is
1296 complex, the imaginary part of the result is in radians and lies between
1297 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1299 @item @emph{Example}:
1302 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1303 WRITE (*,*) ASINH(x)
1307 @item @emph{Specific names}:
1308 @multitable @columnfractions .20 .20 .20 .25
1309 @item Name @tab Argument @tab Return type @tab Standard
1310 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1313 @item @emph{See also}:
1314 Inverse function: @ref{SINH}
1320 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1322 @cindex pointer, status
1323 @cindex association status
1326 @item @emph{Description}:
1327 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1328 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1330 @item @emph{Standard}:
1331 Fortran 95 and later
1336 @item @emph{Syntax}:
1337 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1339 @item @emph{Arguments}:
1340 @multitable @columnfractions .15 .70
1341 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1342 and it can be of any type.
1343 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1344 a target. It must have the same type, kind type parameter, and
1345 array rank as @var{POINTER}.
1347 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1350 @item @emph{Return value}:
1351 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1352 There are several cases:
1354 @item (A) When the optional @var{TARGET} is not present then
1355 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1356 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1357 @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
1358 disassociated, the result is false.
1359 @item (C) If @var{TARGET} is present and an array target, the result is true if
1360 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1361 are arrays whose elements are not zero-sized storage sequences, and
1362 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1364 As in case(B), the result is false, if @var{POINTER} is disassociated.
1365 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1366 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1367 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1369 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1370 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1371 target associated with @var{POINTER} and the target associated with @var{TARGET}
1372 have the same shape, are not zero-sized arrays, are arrays whose elements are
1373 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1374 the same storage units in array element order.
1375 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1378 @item @emph{Example}:
1380 program test_associated
1382 real, target :: tgt(2) = (/1., 2./)
1383 real, pointer :: ptr(:)
1385 if (associated(ptr) .eqv. .false.) call abort
1386 if (associated(ptr,tgt) .eqv. .false.) call abort
1387 end program test_associated
1390 @item @emph{See also}:
1397 @section @code{ATAN} --- Arctangent function
1400 @cindex trigonometric function, tangent, inverse
1401 @cindex tangent, inverse
1404 @item @emph{Description}:
1405 @code{ATAN(X)} computes the arctangent of @var{X}.
1407 @item @emph{Standard}:
1408 Fortran 77 and later, for a complex argument and for two arguments
1409 Fortran 2008 or later
1414 @item @emph{Syntax}:
1415 @multitable @columnfractions .80
1416 @item @code{RESULT = ATAN(X)}
1417 @item @code{RESULT = ATAN(Y, X)}
1420 @item @emph{Arguments}:
1421 @multitable @columnfractions .15 .70
1422 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1423 if @var{Y} is present, @var{X} shall be REAL.
1424 @item @var{Y} shall be of the same type and kind as @var{X}.
1427 @item @emph{Return value}:
1428 The return value is of the same type and kind as @var{X}.
1429 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1430 Otherwise, it the arcus tangent of @var{X}, where the real part of
1431 the result is in radians and lies in the range
1432 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1434 @item @emph{Example}:
1437 real(8) :: x = 2.866_8
1439 end program test_atan
1442 @item @emph{Specific names}:
1443 @multitable @columnfractions .20 .20 .20 .25
1444 @item Name @tab Argument @tab Return type @tab Standard
1445 @item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1446 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1449 @item @emph{See also}:
1450 Inverse function: @ref{TAN}
1457 @section @code{ATAN2} --- Arctangent function
1460 @cindex trigonometric function, tangent, inverse
1461 @cindex tangent, inverse
1464 @item @emph{Description}:
1465 @code{ATAN2(Y, X)} computes the principal value of the argument
1466 function of the complex number @math{X + i Y}. This function can
1467 be used to transform from Cartesian into polar coordinates and
1468 allows to determine the angle in the correct quadrant.
1470 @item @emph{Standard}:
1471 Fortran 77 and later
1476 @item @emph{Syntax}:
1477 @code{RESULT = ATAN2(Y, X)}
1479 @item @emph{Arguments}:
1480 @multitable @columnfractions .15 .70
1481 @item @var{Y} @tab The type shall be @code{REAL}.
1482 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1483 If @var{Y} is zero, then @var{X} must be nonzero.
1486 @item @emph{Return value}:
1487 The return value has the same type and kind type parameter as @var{Y}. It
1488 is the principal value of the complex number @math{X + i Y}. If @var{X}
1489 is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1490 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1491 the return value is zero if @var{X} is strictly positive, @math{\pi} if
1492 @var{X} is negative and @var{Y} is positive zero (or the processor does
1493 not handle signed zeros), and @math{-\pi} if @var{X} is negative and
1494 @var{Y} is negative zero. Finally, if @var{X} is zero, then the
1495 magnitude of the result is @math{\pi/2}.
1497 @item @emph{Example}:
1500 real(4) :: x = 1.e0_4, y = 0.5e0_4
1502 end program test_atan2
1505 @item @emph{Specific names}:
1506 @multitable @columnfractions .20 .20 .20 .25
1507 @item Name @tab Argument @tab Return type @tab Standard
1508 @item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1509 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1516 @section @code{ATANH} --- Inverse hyperbolic tangent function
1519 @cindex area hyperbolic tangent
1520 @cindex inverse hyperbolic tangent
1521 @cindex hyperbolic function, tangent, inverse
1522 @cindex tangent, hyperbolic, inverse
1525 @item @emph{Description}:
1526 @code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
1528 @item @emph{Standard}:
1529 Fortran 2008 and later
1534 @item @emph{Syntax}:
1535 @code{RESULT = ATANH(X)}
1537 @item @emph{Arguments}:
1538 @multitable @columnfractions .15 .70
1539 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1542 @item @emph{Return value}:
1543 The return value has same type and kind as @var{X}. If @var{X} is
1544 complex, the imaginary part of the result is in radians and lies between
1545 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1547 @item @emph{Example}:
1550 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1551 WRITE (*,*) ATANH(x)
1555 @item @emph{Specific names}:
1556 @multitable @columnfractions .20 .20 .20 .25
1557 @item Name @tab Argument @tab Return type @tab Standard
1558 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1561 @item @emph{See also}:
1562 Inverse function: @ref{TANH}
1568 @section @code{ATOMIC_ADD} --- Atomic ADD operation
1570 @cindex Atomic subroutine, add
1573 @item @emph{Description}:
1574 @code{ATOMIC_ADD(ATOM, VALUE)} atomically adds the value of @var{VAR} to the
1575 variable @var{ATOM}. When @var{STAT} is present and the invokation was
1576 successful, it is assigned the value 0. If it is present and the invokation
1577 has failed, it is assigned a positive value; in particular, for a coindexed
1578 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1579 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1580 failed, the value @code{STAT_FAILED_IMAGE}.
1582 @item @emph{Standard}:
1588 @item @emph{Syntax}:
1589 @code{CALL ATOMIC_ADD (ATOM, VALUE [, STAT])}
1591 @item @emph{Arguments}:
1592 @multitable @columnfractions .15 .70
1593 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1594 type with @code{ATOMIC_INT_KIND} kind.
1595 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1596 is different, the value is converted to the kind of @var{ATOM}.
1597 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1600 @item @emph{Example}:
1604 integer(atomic_int_kind) :: atom[*]
1605 call atomic_add (atom[1], this_image())
1609 @item @emph{See also}:
1610 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_ADD}, @ref{ISO_FORTRAN_ENV},
1611 @ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
1618 @section @code{ATOMIC_AND} --- Atomic bitwise AND operation
1620 @cindex Atomic subroutine, AND
1623 @item @emph{Description}:
1624 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
1625 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
1626 and the invokation was successful, it is assigned the value 0. If it is present
1627 and the invokation has failed, it is assigned a positive value; in particular,
1628 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
1629 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
1630 image has failed, the value @code{STAT_FAILED_IMAGE}.
1632 @item @emph{Standard}:
1638 @item @emph{Syntax}:
1639 @code{CALL ATOMIC_AND (ATOM, VALUE [, STAT])}
1641 @item @emph{Arguments}:
1642 @multitable @columnfractions .15 .70
1643 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1644 type with @code{ATOMIC_INT_KIND} kind.
1645 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1646 is different, the value is converted to the kind of @var{ATOM}.
1647 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1650 @item @emph{Example}:
1654 integer(atomic_int_kind) :: atom[*]
1655 call atomic_and (atom[1], int(b'10100011101'))
1659 @item @emph{See also}:
1660 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_AND}, @ref{ISO_FORTRAN_ENV},
1661 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
1667 @section @code{ATOMIC_CAS} --- Atomic compare and swap
1668 @fnindex ATOMIC_DEFINE
1669 @cindex Atomic subroutine, compare and swap
1672 @item @emph{Description}:
1673 @code{ATOMIC_CAS} compares the variable @var{ATOM} with the value of
1674 @var{COMPARE}; if the value is the same, @var{ATOM} is set to the value
1675 of @var{NEW}. Additionally, @var{OLD} is set to the value of @var{ATOM}
1676 that was used for the comparison. When @var{STAT} is present and the invokation
1677 was successful, it is assigned the value 0. If it is present and the invokation
1678 has failed, it is assigned a positive value; in particular, for a coindexed
1679 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1680 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1681 failed, the value @code{STAT_FAILED_IMAGE}.
1683 @item @emph{Standard}:
1689 @item @emph{Syntax}:
1690 @code{CALL ATOMIC_CAS (ATOM, OLD, COMPARE, NEW [, STAT])}
1692 @item @emph{Arguments}:
1693 @multitable @columnfractions .15 .70
1694 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
1695 type with @code{ATOMIC_INT_KIND} kind or logical type with
1696 @code{ATOMIC_LOGICAL_KIND} kind.
1697 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1698 @item @var{COMPARE} @tab Scalar variable of the same type and kind as
1700 @item @var{NEW} @tab Scalar variable of the same type as @var{ATOM}. If kind
1701 is different, the value is converted to the kind of @var{ATOM}.
1702 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1705 @item @emph{Example}:
1709 logical(atomic_logical_kind) :: atom[*], prev
1710 call atomic_cas (atom[1], prev, .false., .true.))
1714 @item @emph{See also}:
1715 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_REF}, @ref{ISO_FORTRAN_ENV}
1721 @section @code{ATOMIC_DEFINE} --- Setting a variable atomically
1722 @fnindex ATOMIC_DEFINE
1723 @cindex Atomic subroutine, define
1726 @item @emph{Description}:
1727 @code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value
1728 @var{VALUE} atomically. When @var{STAT} is present and the invokation was
1729 successful, it is assigned the value 0. If it is present and the invokation
1730 has failed, it is assigned a positive value; in particular, for a coindexed
1731 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1732 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1733 failed, the value @code{STAT_FAILED_IMAGE}.
1735 @item @emph{Standard}:
1736 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
1741 @item @emph{Syntax}:
1742 @code{CALL ATOMIC_DEFINE (ATOM, VALUE [, STAT])}
1744 @item @emph{Arguments}:
1745 @multitable @columnfractions .15 .70
1746 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
1747 type with @code{ATOMIC_INT_KIND} kind or logical type with
1748 @code{ATOMIC_LOGICAL_KIND} kind.
1750 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1751 is different, the value is converted to the kind of @var{ATOM}.
1752 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1755 @item @emph{Example}:
1759 integer(atomic_int_kind) :: atom[*]
1760 call atomic_define (atom[1], this_image())
1764 @item @emph{See also}:
1765 @ref{ATOMIC_REF}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV},
1766 @ref{ATOMIC_ADD}, @ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
1771 @node ATOMIC_FETCH_ADD
1772 @section @code{ATOMIC_FETCH_ADD} --- Atomic ADD operation with prior fetch
1773 @fnindex ATOMIC_FETCH_ADD
1774 @cindex Atomic subroutine, ADD with fetch
1777 @item @emph{Description}:
1778 @code{ATOMIC_FETCH_ADD(ATOM, VALUE, OLD)} atomically stores the value of
1779 @var{ATOM} in @var{OLD} and adds the value of @var{VAR} to the
1780 variable @var{ATOM}. When @var{STAT} is present and the invokation was
1781 successful, it is assigned the value 0. If it is present and the invokation
1782 has failed, it is assigned a positive value; in particular, for a coindexed
1783 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1784 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1785 failed, the value @code{STAT_FAILED_IMAGE}.
1787 @item @emph{Standard}:
1793 @item @emph{Syntax}:
1794 @code{CALL ATOMIC_FETCH_ADD (ATOM, VALUE, old [, STAT])}
1796 @item @emph{Arguments}:
1797 @multitable @columnfractions .15 .70
1798 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1799 type with @code{ATOMIC_INT_KIND} kind.
1800 @code{ATOMIC_LOGICAL_KIND} kind.
1802 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1803 is different, the value is converted to the kind of @var{ATOM}.
1804 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1805 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1808 @item @emph{Example}:
1812 integer(atomic_int_kind) :: atom[*], old
1813 call atomic_add (atom[1], this_image(), old)
1817 @item @emph{See also}:
1818 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_ADD}, @ref{ISO_FORTRAN_ENV},
1819 @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR}
1824 @node ATOMIC_FETCH_AND
1825 @section @code{ATOMIC_FETCH_AND} --- Atomic bitwise AND operation with prior fetch
1826 @fnindex ATOMIC_FETCH_AND
1827 @cindex Atomic subroutine, AND with fetch
1830 @item @emph{Description}:
1831 @code{ATOMIC_AND(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
1832 @var{OLD} and defines @var{ATOM} with the bitwise AND between the values of
1833 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was
1834 successful, it is assigned the value 0. If it is present and the invokation has
1835 failed, it is assigned a positive value; in particular, for a coindexed
1836 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1837 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1838 failed, the value @code{STAT_FAILED_IMAGE}.
1840 @item @emph{Standard}:
1846 @item @emph{Syntax}:
1847 @code{CALL ATOMIC_FETCH_AND (ATOM, VALUE, OLD [, STAT])}
1849 @item @emph{Arguments}:
1850 @multitable @columnfractions .15 .70
1851 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1852 type with @code{ATOMIC_INT_KIND} kind.
1853 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1854 is different, the value is converted to the kind of @var{ATOM}.
1855 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1856 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1859 @item @emph{Example}:
1863 integer(atomic_int_kind) :: atom[*], old
1864 call atomic_fetch_and (atom[1], int(b'10100011101'), old)
1868 @item @emph{See also}:
1869 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_AND}, @ref{ISO_FORTRAN_ENV},
1870 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR}
1875 @node ATOMIC_FETCH_OR
1876 @section @code{ATOMIC_FETCH_OR} --- Atomic bitwise OR operation with prior fetch
1877 @fnindex ATOMIC_FETCH_OR
1878 @cindex Atomic subroutine, OR with fetch
1881 @item @emph{Description}:
1882 @code{ATOMIC_OR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
1883 @var{OLD} and defines @var{ATOM} with the bitwise OR between the values of
1884 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was
1885 successful, it is assigned the value 0. If it is present and the invokation has
1886 failed, it is assigned a positive value; in particular, for a coindexed
1887 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1888 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1889 failed, the value @code{STAT_FAILED_IMAGE}.
1891 @item @emph{Standard}:
1897 @item @emph{Syntax}:
1898 @code{CALL ATOMIC_FETCH_OR (ATOM, VALUE, OLD [, STAT])}
1900 @item @emph{Arguments}:
1901 @multitable @columnfractions .15 .70
1902 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1903 type with @code{ATOMIC_INT_KIND} kind.
1904 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1905 is different, the value is converted to the kind of @var{ATOM}.
1906 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1907 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1910 @item @emph{Example}:
1914 integer(atomic_int_kind) :: atom[*], old
1915 call atomic_fetch_or (atom[1], int(b'10100011101'), old)
1919 @item @emph{See also}:
1920 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_OR}, @ref{ISO_FORTRAN_ENV},
1921 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_XOR}
1926 @node ATOMIC_FETCH_XOR
1927 @section @code{ATOMIC_FETCH_XOR} --- Atomic bitwise XOR operation with prior fetch
1928 @fnindex ATOMIC_FETCH_XOR
1929 @cindex Atomic subroutine, XOR with fetch
1932 @item @emph{Description}:
1933 @code{ATOMIC_XOR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
1934 @var{OLD} and defines @var{ATOM} with the bitwise XOR between the values of
1935 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was
1936 successful, it is assigned the value 0. If it is present and the invokation has
1937 failed, it is assigned a positive value; in particular, for a coindexed
1938 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1939 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1940 failed, the value @code{STAT_FAILED_IMAGE}.
1942 @item @emph{Standard}:
1948 @item @emph{Syntax}:
1949 @code{CALL ATOMIC_FETCH_XOR (ATOM, VALUE, OLD [, STAT])}
1951 @item @emph{Arguments}:
1952 @multitable @columnfractions .15 .70
1953 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1954 type with @code{ATOMIC_INT_KIND} kind.
1955 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1956 is different, the value is converted to the kind of @var{ATOM}.
1957 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1958 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1961 @item @emph{Example}:
1965 integer(atomic_int_kind) :: atom[*], old
1966 call atomic_fetch_xor (atom[1], int(b'10100011101'), old)
1970 @item @emph{See also}:
1971 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_XOR}, @ref{ISO_FORTRAN_ENV},
1972 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}
1978 @section @code{ATOMIC_OR} --- Atomic bitwise OR operation
1980 @cindex Atomic subroutine, OR
1983 @item @emph{Description}:
1984 @code{ATOMIC_OR(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
1985 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
1986 and the invokation was successful, it is assigned the value 0. If it is present
1987 and the invokation has failed, it is assigned a positive value; in particular,
1988 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
1989 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
1990 image has failed, the value @code{STAT_FAILED_IMAGE}.
1992 @item @emph{Standard}:
1998 @item @emph{Syntax}:
1999 @code{CALL ATOMIC_OR (ATOM, VALUE [, STAT])}
2001 @item @emph{Arguments}:
2002 @multitable @columnfractions .15 .70
2003 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2004 type with @code{ATOMIC_INT_KIND} kind.
2005 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2006 is different, the value is converted to the kind of @var{ATOM}.
2007 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2010 @item @emph{Example}:
2014 integer(atomic_int_kind) :: atom[*]
2015 call atomic_or (atom[1], int(b'10100011101'))
2019 @item @emph{See also}:
2020 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_OR}, @ref{ISO_FORTRAN_ENV},
2021 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
2027 @section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically
2029 @cindex Atomic subroutine, reference
2032 @item @emph{Description}:
2033 @code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the
2034 variable @var{ATOM} to @var{VALUE}. When @var{STAT} is present and the
2035 invokation was successful, it is assigned the value 0. If it is present and the
2036 invokation has failed, it is assigned a positive value; in particular, for a
2037 coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value
2038 of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image
2039 has failed, the value @code{STAT_FAILED_IMAGE}.
2042 @item @emph{Standard}:
2043 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
2048 @item @emph{Syntax}:
2049 @code{CALL ATOMIC_REF(VALUE, ATOM [, STAT])}
2051 @item @emph{Arguments}:
2052 @multitable @columnfractions .15 .70
2053 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2054 is different, the value is converted to the kind of @var{ATOM}.
2055 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
2056 type with @code{ATOMIC_INT_KIND} kind or logical type with
2057 @code{ATOMIC_LOGICAL_KIND} kind.
2058 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2061 @item @emph{Example}:
2065 logical(atomic_logical_kind) :: atom[*]
2067 call atomic_ref (atom, .false.)
2069 call atomic_ref (atom, val)
2076 @item @emph{See also}:
2077 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV},
2078 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR},
2079 @ref{ATOMIC_FETCH_XOR}
2084 @section @code{ATOMIC_XOR} --- Atomic bitwise OR operation
2086 @cindex Atomic subroutine, XOR
2089 @item @emph{Description}:
2090 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
2091 XOR between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
2092 and the invokation was successful, it is assigned the value 0. If it is present
2093 and the invokation has failed, it is assigned a positive value; in particular,
2094 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
2095 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
2096 image has failed, the value @code{STAT_FAILED_IMAGE}.
2098 @item @emph{Standard}:
2104 @item @emph{Syntax}:
2105 @code{CALL ATOMIC_XOR (ATOM, VALUE [, STAT])}
2107 @item @emph{Arguments}:
2108 @multitable @columnfractions .15 .70
2109 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2110 type with @code{ATOMIC_INT_KIND} kind.
2111 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2112 is different, the value is converted to the kind of @var{ATOM}.
2113 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2116 @item @emph{Example}:
2120 integer(atomic_int_kind) :: atom[*]
2121 call atomic_xor (atom[1], int(b'10100011101'))
2125 @item @emph{See also}:
2126 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_XOR}, @ref{ISO_FORTRAN_ENV},
2127 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
2132 @section @code{BACKTRACE} --- Show a backtrace
2137 @item @emph{Description}:
2138 @code{BACKTRACE} shows a backtrace at an arbitrary place in user code. Program
2139 execution continues normally afterwards. The backtrace information is printed
2140 to the unit corresponding to @code{ERROR_UNIT} in @code{ISO_FORTRAN_ENV}.
2142 @item @emph{Standard}:
2148 @item @emph{Syntax}:
2149 @code{CALL BACKTRACE}
2151 @item @emph{Arguments}:
2154 @item @emph{See also}:
2161 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
2165 @cindex Bessel function, first kind
2168 @item @emph{Description}:
2169 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
2170 order 0 of @var{X}. This function is available under the name
2171 @code{BESJ0} as a GNU extension.
2173 @item @emph{Standard}:
2174 Fortran 2008 and later
2179 @item @emph{Syntax}:
2180 @code{RESULT = BESSEL_J0(X)}
2182 @item @emph{Arguments}:
2183 @multitable @columnfractions .15 .70
2184 @item @var{X} @tab The type shall be @code{REAL}.
2187 @item @emph{Return value}:
2188 The return value is of type @code{REAL} and lies in the
2189 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
2192 @item @emph{Example}:
2195 real(8) :: x = 0.0_8
2197 end program test_besj0
2200 @item @emph{Specific names}:
2201 @multitable @columnfractions .20 .20 .20 .25
2202 @item Name @tab Argument @tab Return type @tab Standard
2203 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2210 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
2214 @cindex Bessel function, first kind
2217 @item @emph{Description}:
2218 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
2219 order 1 of @var{X}. This function is available under the name
2220 @code{BESJ1} as a GNU extension.
2222 @item @emph{Standard}:
2228 @item @emph{Syntax}:
2229 @code{RESULT = BESSEL_J1(X)}
2231 @item @emph{Arguments}:
2232 @multitable @columnfractions .15 .70
2233 @item @var{X} @tab The type shall be @code{REAL}.
2236 @item @emph{Return value}:
2237 The return value is of type @code{REAL} and lies in the
2238 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
2241 @item @emph{Example}:
2244 real(8) :: x = 1.0_8
2246 end program test_besj1
2249 @item @emph{Specific names}:
2250 @multitable @columnfractions .20 .20 .20 .25
2251 @item Name @tab Argument @tab Return type @tab Standard
2252 @item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2259 @section @code{BESSEL_JN} --- Bessel function of the first kind
2263 @cindex Bessel function, first kind
2266 @item @emph{Description}:
2267 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
2268 order @var{N} of @var{X}. This function is available under the name
2269 @code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays,
2270 their ranks and shapes shall conform.
2272 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
2273 of the first kind of the orders @var{N1} to @var{N2}.
2275 @item @emph{Standard}:
2276 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2279 Elemental function, except for the transformational function
2280 @code{BESSEL_JN(N1, N2, X)}
2282 @item @emph{Syntax}:
2283 @multitable @columnfractions .80
2284 @item @code{RESULT = BESSEL_JN(N, X)}
2285 @item @code{RESULT = BESSEL_JN(N1, N2, X)}
2288 @item @emph{Arguments}:
2289 @multitable @columnfractions .15 .70
2290 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
2291 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2292 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2293 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2294 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
2297 @item @emph{Return value}:
2298 The return value is a scalar of type @code{REAL}. It has the same
2302 The transformational function uses a recurrence algorithm which might,
2303 for some values of @var{X}, lead to different results than calls to
2304 the elemental function.
2306 @item @emph{Example}:
2309 real(8) :: x = 1.0_8
2311 end program test_besjn
2314 @item @emph{Specific names}:
2315 @multitable @columnfractions .20 .20 .20 .25
2316 @item Name @tab Argument @tab Return type @tab Standard
2317 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2318 @item @tab @code{REAL(8) X} @tab @tab
2325 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
2329 @cindex Bessel function, second kind
2332 @item @emph{Description}:
2333 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
2334 order 0 of @var{X}. This function is available under the name
2335 @code{BESY0} as a GNU extension.
2337 @item @emph{Standard}:
2338 Fortran 2008 and later
2343 @item @emph{Syntax}:
2344 @code{RESULT = BESSEL_Y0(X)}
2346 @item @emph{Arguments}:
2347 @multitable @columnfractions .15 .70
2348 @item @var{X} @tab The type shall be @code{REAL}.
2351 @item @emph{Return value}:
2352 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2354 @item @emph{Example}:
2357 real(8) :: x = 0.0_8
2359 end program test_besy0
2362 @item @emph{Specific names}:
2363 @multitable @columnfractions .20 .20 .20 .25
2364 @item Name @tab Argument @tab Return type @tab Standard
2365 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2372 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
2376 @cindex Bessel function, second kind
2379 @item @emph{Description}:
2380 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
2381 order 1 of @var{X}. This function is available under the name
2382 @code{BESY1} as a GNU extension.
2384 @item @emph{Standard}:
2385 Fortran 2008 and later
2390 @item @emph{Syntax}:
2391 @code{RESULT = BESSEL_Y1(X)}
2393 @item @emph{Arguments}:
2394 @multitable @columnfractions .15 .70
2395 @item @var{X} @tab The type shall be @code{REAL}.
2398 @item @emph{Return value}:
2399 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2401 @item @emph{Example}:
2404 real(8) :: x = 1.0_8
2406 end program test_besy1
2409 @item @emph{Specific names}:
2410 @multitable @columnfractions .20 .20 .20 .25
2411 @item Name @tab Argument @tab Return type @tab Standard
2412 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2419 @section @code{BESSEL_YN} --- Bessel function of the second kind
2423 @cindex Bessel function, second kind
2426 @item @emph{Description}:
2427 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
2428 order @var{N} of @var{X}. This function is available under the name
2429 @code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays,
2430 their ranks and shapes shall conform.
2432 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
2433 of the first kind of the orders @var{N1} to @var{N2}.
2435 @item @emph{Standard}:
2436 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2439 Elemental function, except for the transformational function
2440 @code{BESSEL_YN(N1, N2, X)}
2442 @item @emph{Syntax}:
2443 @multitable @columnfractions .80
2444 @item @code{RESULT = BESSEL_YN(N, X)}
2445 @item @code{RESULT = BESSEL_YN(N1, N2, X)}
2448 @item @emph{Arguments}:
2449 @multitable @columnfractions .15 .70
2450 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} .
2451 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2452 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2453 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2454 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
2457 @item @emph{Return value}:
2458 The return value is a scalar of type @code{REAL}. It has the same
2462 The transformational function uses a recurrence algorithm which might,
2463 for some values of @var{X}, lead to different results than calls to
2464 the elemental function.
2466 @item @emph{Example}:
2469 real(8) :: x = 1.0_8
2471 end program test_besyn
2474 @item @emph{Specific names}:
2475 @multitable @columnfractions .20 .20 .20 .25
2476 @item Name @tab Argument @tab Return type @tab Standard
2477 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2478 @item @tab @code{REAL(8) X} @tab @tab
2485 @section @code{BGE} --- Bitwise greater than or equal to
2487 @cindex bitwise comparison
2490 @item @emph{Description}:
2491 Determines whether an integral is a bitwise greater than or equal to
2494 @item @emph{Standard}:
2495 Fortran 2008 and later
2500 @item @emph{Syntax}:
2501 @code{RESULT = BGE(I, J)}
2503 @item @emph{Arguments}:
2504 @multitable @columnfractions .15 .70
2505 @item @var{I} @tab Shall be of @code{INTEGER} type.
2506 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2510 @item @emph{Return value}:
2511 The return value is of type @code{LOGICAL} and of the default kind.
2513 @item @emph{See also}:
2514 @ref{BGT}, @ref{BLE}, @ref{BLT}
2520 @section @code{BGT} --- Bitwise greater than
2522 @cindex bitwise comparison
2525 @item @emph{Description}:
2526 Determines whether an integral is a bitwise greater than another.
2528 @item @emph{Standard}:
2529 Fortran 2008 and later
2534 @item @emph{Syntax}:
2535 @code{RESULT = BGT(I, J)}
2537 @item @emph{Arguments}:
2538 @multitable @columnfractions .15 .70
2539 @item @var{I} @tab Shall be of @code{INTEGER} type.
2540 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2544 @item @emph{Return value}:
2545 The return value is of type @code{LOGICAL} and of the default kind.
2547 @item @emph{See also}:
2548 @ref{BGE}, @ref{BLE}, @ref{BLT}
2554 @section @code{BIT_SIZE} --- Bit size inquiry function
2556 @cindex bits, number of
2557 @cindex size of a variable, in bits
2560 @item @emph{Description}:
2561 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
2562 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
2563 independent of the actual value of @var{I}.
2565 @item @emph{Standard}:
2566 Fortran 95 and later
2571 @item @emph{Syntax}:
2572 @code{RESULT = BIT_SIZE(I)}
2574 @item @emph{Arguments}:
2575 @multitable @columnfractions .15 .70
2576 @item @var{I} @tab The type shall be @code{INTEGER}.
2579 @item @emph{Return value}:
2580 The return value is of type @code{INTEGER}
2582 @item @emph{Example}:
2584 program test_bit_size
2589 end program test_bit_size
2596 @section @code{BLE} --- Bitwise less than or equal to
2598 @cindex bitwise comparison
2601 @item @emph{Description}:
2602 Determines whether an integral is a bitwise less than or equal to
2605 @item @emph{Standard}:
2606 Fortran 2008 and later
2611 @item @emph{Syntax}:
2612 @code{RESULT = BLE(I, J)}
2614 @item @emph{Arguments}:
2615 @multitable @columnfractions .15 .70
2616 @item @var{I} @tab Shall be of @code{INTEGER} type.
2617 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2621 @item @emph{Return value}:
2622 The return value is of type @code{LOGICAL} and of the default kind.
2624 @item @emph{See also}:
2625 @ref{BGT}, @ref{BGE}, @ref{BLT}
2631 @section @code{BLT} --- Bitwise less than
2633 @cindex bitwise comparison
2636 @item @emph{Description}:
2637 Determines whether an integral is a bitwise less than another.
2639 @item @emph{Standard}:
2640 Fortran 2008 and later
2645 @item @emph{Syntax}:
2646 @code{RESULT = BLT(I, J)}
2648 @item @emph{Arguments}:
2649 @multitable @columnfractions .15 .70
2650 @item @var{I} @tab Shall be of @code{INTEGER} type.
2651 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2655 @item @emph{Return value}:
2656 The return value is of type @code{LOGICAL} and of the default kind.
2658 @item @emph{See also}:
2659 @ref{BGE}, @ref{BGT}, @ref{BLE}
2665 @section @code{BTEST} --- Bit test function
2667 @cindex bits, testing
2670 @item @emph{Description}:
2671 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
2672 in @var{I} is set. The counting of the bits starts at 0.
2674 @item @emph{Standard}:
2675 Fortran 95 and later
2680 @item @emph{Syntax}:
2681 @code{RESULT = BTEST(I, POS)}
2683 @item @emph{Arguments}:
2684 @multitable @columnfractions .15 .70
2685 @item @var{I} @tab The type shall be @code{INTEGER}.
2686 @item @var{POS} @tab The type shall be @code{INTEGER}.
2689 @item @emph{Return value}:
2690 The return value is of type @code{LOGICAL}
2692 @item @emph{Example}:
2695 integer :: i = 32768 + 1024 + 64
2699 bool = btest(i, pos)
2702 end program test_btest
2708 @section @code{C_ASSOCIATED} --- Status of a C pointer
2709 @fnindex C_ASSOCIATED
2710 @cindex association status, C pointer
2711 @cindex pointer, C association status
2714 @item @emph{Description}:
2715 @code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
2716 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
2718 @item @emph{Standard}:
2719 Fortran 2003 and later
2724 @item @emph{Syntax}:
2725 @code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
2727 @item @emph{Arguments}:
2728 @multitable @columnfractions .15 .70
2729 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
2730 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
2733 @item @emph{Return value}:
2734 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
2735 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
2736 point to different addresses.
2738 @item @emph{Example}:
2740 subroutine association_test(a,b)
2741 use iso_c_binding, only: c_associated, c_loc, c_ptr
2745 if(c_associated(b, c_loc(a))) &
2746 stop 'b and a do not point to same target'
2747 end subroutine association_test
2750 @item @emph{See also}:
2751 @ref{C_LOC}, @ref{C_FUNLOC}
2756 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2757 @fnindex C_F_POINTER
2758 @cindex pointer, convert C to Fortran
2761 @item @emph{Description}:
2762 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} assigns the target of the C pointer
2763 @var{CPTR} to the Fortran pointer @var{FPTR} and specifies its shape.
2765 @item @emph{Standard}:
2766 Fortran 2003 and later
2771 @item @emph{Syntax}:
2772 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2774 @item @emph{Arguments}:
2775 @multitable @columnfractions .15 .70
2776 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
2778 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
2780 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2781 with @code{INTENT(IN)}. It shall be present
2782 if and only if @var{fptr} is an array. The size
2783 must be equal to the rank of @var{fptr}.
2786 @item @emph{Example}:
2792 subroutine my_routine(p) bind(c,name='myC_func')
2794 type(c_ptr), intent(out) :: p
2798 real,pointer :: a(:)
2799 call my_routine(cptr)
2800 call c_f_pointer(cptr, a, [12])
2804 @item @emph{See also}:
2805 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2809 @node C_F_PROCPOINTER
2810 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
2811 @fnindex C_F_PROCPOINTER
2812 @cindex pointer, C address of pointers
2815 @item @emph{Description}:
2816 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
2817 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
2819 @item @emph{Standard}:
2820 Fortran 2003 and later
2825 @item @emph{Syntax}:
2826 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2828 @item @emph{Arguments}:
2829 @multitable @columnfractions .15 .70
2830 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
2832 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
2836 @item @emph{Example}:
2844 real(c_float), intent(in) :: a
2845 real(c_float) :: func
2849 function getIterFunc() bind(c,name="getIterFunc")
2851 type(c_funptr) :: getIterFunc
2854 type(c_funptr) :: cfunptr
2855 procedure(func), pointer :: myFunc
2856 cfunptr = getIterFunc()
2857 call c_f_procpointer(cfunptr, myFunc)
2861 @item @emph{See also}:
2862 @ref{C_LOC}, @ref{C_F_POINTER}
2867 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
2869 @cindex pointer, C address of procedures
2872 @item @emph{Description}:
2873 @code{C_FUNLOC(x)} determines the C address of the argument.
2875 @item @emph{Standard}:
2876 Fortran 2003 and later
2881 @item @emph{Syntax}:
2882 @code{RESULT = C_FUNLOC(x)}
2884 @item @emph{Arguments}:
2885 @multitable @columnfractions .15 .70
2886 @item @var{x} @tab Interoperable function or pointer to such function.
2889 @item @emph{Return value}:
2890 The return value is of type @code{C_FUNPTR} and contains the C address
2893 @item @emph{Example}:
2899 subroutine sub(a) bind(c)
2909 subroutine my_routine(p) bind(c,name='myC_func')
2911 type(c_funptr), intent(in) :: p
2914 call my_routine(c_funloc(sub))
2918 @item @emph{See also}:
2919 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2924 @section @code{C_LOC} --- Obtain the C address of an object
2926 @cindex procedure pointer, convert C to Fortran
2929 @item @emph{Description}:
2930 @code{C_LOC(X)} determines the C address of the argument.
2932 @item @emph{Standard}:
2933 Fortran 2003 and later
2938 @item @emph{Syntax}:
2939 @code{RESULT = C_LOC(X)}
2941 @item @emph{Arguments}:
2942 @multitable @columnfractions .10 .75
2943 @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.
2947 @item @emph{Return value}:
2948 The return value is of type @code{C_PTR} and contains the C address
2951 @item @emph{Example}:
2953 subroutine association_test(a,b)
2954 use iso_c_binding, only: c_associated, c_loc, c_ptr
2958 if(c_associated(b, c_loc(a))) &
2959 stop 'b and a do not point to same target'
2960 end subroutine association_test
2963 @item @emph{See also}:
2964 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2969 @section @code{C_SIZEOF} --- Size in bytes of an expression
2971 @cindex expression size
2972 @cindex size of an expression
2975 @item @emph{Description}:
2976 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
2977 expression @code{X} occupies.
2979 @item @emph{Standard}:
2983 Inquiry function of the module @code{ISO_C_BINDING}
2985 @item @emph{Syntax}:
2986 @code{N = C_SIZEOF(X)}
2988 @item @emph{Arguments}:
2989 @multitable @columnfractions .15 .70
2990 @item @var{X} @tab The argument shall be an interoperable data entity.
2993 @item @emph{Return value}:
2994 The return value is of type integer and of the system-dependent kind
2995 @code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the
2996 number of bytes occupied by the argument. If the argument has the
2997 @code{POINTER} attribute, the number of bytes of the storage area pointed
2998 to is returned. If the argument is of a derived type with @code{POINTER}
2999 or @code{ALLOCATABLE} components, the return value does not account for
3000 the sizes of the data pointed to by these components.
3002 @item @emph{Example}:
3006 real(c_float) :: r, s(5)
3007 print *, (c_sizeof(s)/c_sizeof(r) == 5)
3010 The example will print @code{.TRUE.} unless you are using a platform
3011 where default @code{REAL} variables are unusually padded.
3013 @item @emph{See also}:
3014 @ref{SIZEOF}, @ref{STORAGE_SIZE}
3019 @section @code{CEILING} --- Integer ceiling function
3022 @cindex rounding, ceiling
3025 @item @emph{Description}:
3026 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
3028 @item @emph{Standard}:
3029 Fortran 95 and later
3034 @item @emph{Syntax}:
3035 @code{RESULT = CEILING(A [, KIND])}
3037 @item @emph{Arguments}:
3038 @multitable @columnfractions .15 .70
3039 @item @var{A} @tab The type shall be @code{REAL}.
3040 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3041 expression indicating the kind parameter of the result.
3044 @item @emph{Return value}:
3045 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
3046 and a default-kind @code{INTEGER} otherwise.
3048 @item @emph{Example}:
3050 program test_ceiling
3053 print *, ceiling(x) ! returns 64
3054 print *, ceiling(y) ! returns -63
3055 end program test_ceiling
3058 @item @emph{See also}:
3059 @ref{FLOOR}, @ref{NINT}
3066 @section @code{CHAR} --- Character conversion function
3068 @cindex conversion, to character
3071 @item @emph{Description}:
3072 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
3074 @item @emph{Standard}:
3075 Fortran 77 and later
3080 @item @emph{Syntax}:
3081 @code{RESULT = CHAR(I [, KIND])}
3083 @item @emph{Arguments}:
3084 @multitable @columnfractions .15 .70
3085 @item @var{I} @tab The type shall be @code{INTEGER}.
3086 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3087 expression indicating the kind parameter of the result.
3090 @item @emph{Return value}:
3091 The return value is of type @code{CHARACTER(1)}
3093 @item @emph{Example}:
3099 print *, i, c ! returns 'J'
3100 end program test_char
3103 @item @emph{Specific names}:
3104 @multitable @columnfractions .20 .20 .20 .25
3105 @item Name @tab Argument @tab Return type @tab Standard
3106 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
3110 See @ref{ICHAR} for a discussion of converting between numerical values
3111 and formatted string representations.
3113 @item @emph{See also}:
3114 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
3121 @section @code{CHDIR} --- Change working directory
3123 @cindex system, working directory
3126 @item @emph{Description}:
3127 Change current working directory to a specified path.
3129 This intrinsic is provided in both subroutine and function forms; however,
3130 only one form can be used in any given program unit.
3132 @item @emph{Standard}:
3136 Subroutine, function
3138 @item @emph{Syntax}:
3139 @multitable @columnfractions .80
3140 @item @code{CALL CHDIR(NAME [, STATUS])}
3141 @item @code{STATUS = CHDIR(NAME)}
3144 @item @emph{Arguments}:
3145 @multitable @columnfractions .15 .70
3146 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
3147 kind and shall specify a valid path within the file system.
3148 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
3149 kind. Returns 0 on success, and a system specific and nonzero error code
3153 @item @emph{Example}:
3156 CHARACTER(len=255) :: path
3158 WRITE(*,*) TRIM(path)
3161 WRITE(*,*) TRIM(path)
3165 @item @emph{See also}:
3172 @section @code{CHMOD} --- Change access permissions of files
3174 @cindex file system, change access mode
3177 @item @emph{Description}:
3178 @code{CHMOD} changes the permissions of a file.
3180 This intrinsic is provided in both subroutine and function forms; however,
3181 only one form can be used in any given program unit.
3183 @item @emph{Standard}:
3187 Subroutine, function
3189 @item @emph{Syntax}:
3190 @multitable @columnfractions .80
3191 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
3192 @item @code{STATUS = CHMOD(NAME, MODE)}
3195 @item @emph{Arguments}:
3196 @multitable @columnfractions .15 .70
3198 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
3199 file name. Trailing blanks are ignored unless the character
3200 @code{achar(0)} is present, then all characters up to and excluding
3201 @code{achar(0)} are used as the file name.
3203 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
3204 file permission. @var{MODE} uses the same syntax as the @code{chmod} utility
3205 as defined by the POSIX standard. The argument shall either be a string of
3206 a nonnegative octal number or a symbolic mode.
3208 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
3209 @code{0} on success and nonzero otherwise.
3212 @item @emph{Return value}:
3213 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
3216 @item @emph{Example}:
3217 @code{CHMOD} as subroutine
3222 call chmod('test.dat','u+x',status)
3223 print *, 'Status: ', status
3224 end program chmod_test
3226 @code{CHMOD} as function:
3231 status = chmod('test.dat','u+x')
3232 print *, 'Status: ', status
3233 end program chmod_test
3241 @section @code{CMPLX} --- Complex conversion function
3243 @cindex complex numbers, conversion to
3244 @cindex conversion, to complex
3247 @item @emph{Description}:
3248 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
3249 the real component. If @var{Y} is present it is converted to the imaginary
3250 component. If @var{Y} is not present then the imaginary component is set to
3251 0.0. If @var{X} is complex then @var{Y} must not be present.
3253 @item @emph{Standard}:
3254 Fortran 77 and later
3259 @item @emph{Syntax}:
3260 @code{RESULT = CMPLX(X [, Y [, KIND]])}
3262 @item @emph{Arguments}:
3263 @multitable @columnfractions .15 .70
3264 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3266 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
3267 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
3268 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3269 expression indicating the kind parameter of the result.
3272 @item @emph{Return value}:
3273 The return value is of @code{COMPLEX} type, with a kind equal to
3274 @var{KIND} if it is specified. If @var{KIND} is not specified, the
3275 result is of the default @code{COMPLEX} kind, regardless of the kinds of
3276 @var{X} and @var{Y}.
3278 @item @emph{Example}:
3285 print *, z, cmplx(x)
3286 end program test_cmplx
3289 @item @emph{See also}:
3296 @section @code{CO_BROADCAST} --- Copy a value to all images the current set of images
3297 @fnindex CO_BROADCAST
3298 @cindex Collectives, value broadcasting
3301 @item @emph{Description}:
3302 @code{CO_BROADCAST} copies the value of argument @var{A} on the image with
3303 image index @code{SOURCE_IMAGE} to all images in the current team. @var{A}
3304 becomes defined as if by intrinsic assignment. If the execution was
3305 successful and @var{STAT} is present, it is assigned the value zero. If the
3306 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3307 @var{ERRMSG} gets assigned a value describing the occurred error.
3309 @item @emph{Standard}:
3310 Technical Specification (TS) 18508 or later
3313 Collective subroutine
3315 @item @emph{Syntax}:
3316 @code{CALL CO_BROADCAST(A, SOURCE_IMAGE [, STAT, ERRMSG])}
3318 @item @emph{Arguments}:
3319 @multitable @columnfractions .15 .70
3320 @item @var{A} @tab INTENT(INOUT) argument; shall have the same
3321 dynamic type and type paramters on all images of the current team. If it
3322 is an array, it shall have the same shape on all images.
3323 @item @var{SOURCE_IMAGE} @tab (optional) a scalar integer expression.
3324 It shall have the same the same value on all images and refer to an
3325 image of the current team.
3326 @item @var{STAT} @tab (optional) a scalar integer variable
3327 @item @var{ERRMSG} @tab (optional) a scalar character variable
3330 @item @emph{Example}:
3334 if (this_image() == 1) then
3337 call co_broadcast (val, source_image=1)
3338 print *, this_image, ":", val
3342 @item @emph{See also}:
3343 @ref{CO_MAX}, @ref{CO_MIN}, @ref{CO_SUM}
3349 @section @code{CO_MAX} --- Maximal value on the current set of images
3351 @cindex Collectives, maximal value
3354 @item @emph{Description}:
3355 @code{CO_MAX} determines element-wise the maximal value of @var{A} on all
3356 images of the current team. If @var{RESULT_IMAGE} is present, the maximum
3357 values are returned on in @var{A} on the specified image only and the value
3358 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3359 not present, the value is returned on all images. If the execution was
3360 successful and @var{STAT} is present, it is assigned the value zero. If the
3361 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3362 @var{ERRMSG} gets assigned a value describing the occurred error.
3364 @item @emph{Standard}:
3365 Technical Specification (TS) 18508 or later
3368 Collective subroutine
3370 @item @emph{Syntax}:
3371 @code{CALL CO_MAX(A [, RESULT_IMAGE, STAT, ERRMSG])}
3373 @item @emph{Arguments}:
3374 @multitable @columnfractions .15 .70
3375 @item @var{A} @tab shall be an integer, real or character variable,
3376 which has the same type and type parameters on all images of the team.
3377 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3378 present, it shall have the same the same value on all images and refer to an
3379 image of the current team.
3380 @item @var{STAT} @tab (optional) a scalar integer variable
3381 @item @var{ERRMSG} @tab (optional) a scalar character variable
3384 @item @emph{Example}:
3389 call co_max (val, result_image=1)
3390 if (this_image() == 1) then
3391 write(*,*) "Maximal value", val ! prints num_images()
3396 @item @emph{See also}:
3397 @ref{CO_MIN}, @ref{CO_SUM}, @ref{CO_BROADCAST}
3403 @section @code{CO_MIN} --- Minimal value on the current set of images
3405 @cindex Collectives, minimal value
3408 @item @emph{Description}:
3409 @code{CO_MIN} determines element-wise the minimal value of @var{A} on all
3410 images of the current team. If @var{RESULT_IMAGE} is present, the minimal
3411 values are returned on in @var{A} on the specified image only and the value
3412 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3413 not present, the value is returned on all images. If the execution was
3414 successful and @var{STAT} is present, it is assigned the value zero. If the
3415 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3416 @var{ERRMSG} gets assigned a value describing the occurred error.
3418 @item @emph{Standard}:
3419 Technical Specification (TS) 18508 or later
3422 Collective subroutine
3424 @item @emph{Syntax}:
3425 @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3427 @item @emph{Arguments}:
3428 @multitable @columnfractions .15 .70
3429 @item @var{A} @tab shall be an integer, real or character variable,
3430 which has the same type and type parameters on all images of the team.
3431 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3432 present, it shall have the same the same value on all images and refer to an
3433 image of the current team.
3434 @item @var{STAT} @tab (optional) a scalar integer variable
3435 @item @var{ERRMSG} @tab (optional) a scalar character variable
3438 @item @emph{Example}:
3443 call co_min (val, result_image=1)
3444 if (this_image() == 1) then
3445 write(*,*) "Minimal value", val ! prints 1
3450 @item @emph{See also}:
3451 @ref{CO_MAX}, @ref{CO_SUM}, @ref{CO_BROADCAST}
3457 @section @code{CO_SUM} --- Sum of values on the current set of images
3459 @cindex Collectives, sum of values
3462 @item @emph{Description}:
3463 @code{CO_SUM} sums up the values of each element of @var{A} on all
3464 images of the current team. If @var{RESULT_IMAGE} is present, the summed-up
3465 values are returned on in @var{A} on the specified image only and the value
3466 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3467 not present, the value is returned on all images. If the execution was
3468 successful and @var{STAT} is present, it is assigned the value zero. If the
3469 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3470 @var{ERRMSG} gets assigned a value describing the occurred error.
3472 @item @emph{Standard}:
3473 Technical Specification (TS) 18508 or later
3476 Collective subroutine
3478 @item @emph{Syntax}:
3479 @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3481 @item @emph{Arguments}:
3482 @multitable @columnfractions .15 .70
3483 @item @var{A} @tab shall be an integer, real or complex variable,
3484 which has the same type and type parameters on all images of the team.
3485 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3486 present, it shall have the same the same value on all images and refer to an
3487 image of the current team.
3488 @item @var{STAT} @tab (optional) a scalar integer variable
3489 @item @var{ERRMSG} @tab (optional) a scalar character variable
3492 @item @emph{Example}:
3497 call co_sum (val, result_image=1)
3498 if (this_image() == 1) then
3499 write(*,*) "The sum is ", val ! prints (n**2 + n)/2, with n = num_images()
3504 @item @emph{See also}:
3505 @ref{CO_MAX}, @ref{CO_MIN}, @ref{CO_BROADCAST}
3510 @node COMMAND_ARGUMENT_COUNT
3511 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
3512 @fnindex COMMAND_ARGUMENT_COUNT
3513 @cindex command-line arguments
3514 @cindex command-line arguments, number of
3515 @cindex arguments, to program
3518 @item @emph{Description}:
3519 @code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the
3520 command line when the containing program was invoked.
3522 @item @emph{Standard}:
3523 Fortran 2003 and later
3528 @item @emph{Syntax}:
3529 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
3531 @item @emph{Arguments}:
3532 @multitable @columnfractions .15 .70
3536 @item @emph{Return value}:
3537 The return value is an @code{INTEGER} of default kind.
3539 @item @emph{Example}:
3541 program test_command_argument_count
3543 count = command_argument_count()
3545 end program test_command_argument_count
3548 @item @emph{See also}:
3549 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
3554 @node COMPILER_OPTIONS
3555 @section @code{COMPILER_OPTIONS} --- Options passed to the compiler
3556 @fnindex COMPILER_OPTIONS
3557 @cindex flags inquiry function
3558 @cindex options inquiry function
3559 @cindex compiler flags inquiry function
3562 @item @emph{Description}:
3563 @code{COMPILER_OPTIONS} returns a string with the options used for
3566 @item @emph{Standard}:
3570 Inquiry function of the module @code{ISO_FORTRAN_ENV}
3572 @item @emph{Syntax}:
3573 @code{STR = COMPILER_OPTIONS()}
3575 @item @emph{Arguments}:
3578 @item @emph{Return value}:
3579 The return value is a default-kind string with system-dependent length.
3580 It contains the compiler flags used to compile the file, which called
3581 the @code{COMPILER_OPTIONS} intrinsic.
3583 @item @emph{Example}:
3586 print '(4a)', 'This file was compiled by ', &
3587 compiler_version(), ' using the options ', &
3592 @item @emph{See also}:
3593 @ref{COMPILER_VERSION}, @ref{ISO_FORTRAN_ENV}
3598 @node COMPILER_VERSION
3599 @section @code{COMPILER_VERSION} --- Compiler version string
3600 @fnindex COMPILER_VERSION
3601 @cindex compiler, name and version
3602 @cindex version of the compiler
3605 @item @emph{Description}:
3606 @code{COMPILER_VERSION} returns a string with the name and the
3607 version of the compiler.
3609 @item @emph{Standard}:
3613 Inquiry function of the module @code{ISO_FORTRAN_ENV}
3615 @item @emph{Syntax}:
3616 @code{STR = COMPILER_VERSION()}
3618 @item @emph{Arguments}:
3621 @item @emph{Return value}:
3622 The return value is a default-kind string with system-dependent length.
3623 It contains the name of the compiler and its version number.
3625 @item @emph{Example}:
3628 print '(4a)', 'This file was compiled by ', &
3629 compiler_version(), ' using the options ', &
3634 @item @emph{See also}:
3635 @ref{COMPILER_OPTIONS}, @ref{ISO_FORTRAN_ENV}
3641 @section @code{COMPLEX} --- Complex conversion function
3643 @cindex complex numbers, conversion to
3644 @cindex conversion, to complex
3647 @item @emph{Description}:
3648 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
3649 to the real component and @var{Y} is converted to the imaginary
3652 @item @emph{Standard}:
3658 @item @emph{Syntax}:
3659 @code{RESULT = COMPLEX(X, Y)}
3661 @item @emph{Arguments}:
3662 @multitable @columnfractions .15 .70
3663 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3664 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
3667 @item @emph{Return value}:
3668 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
3669 value is of default @code{COMPLEX} type.
3671 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
3672 type and one is of @code{INTEGER} type, then the return value is of
3673 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
3674 argument with the highest precision.
3676 @item @emph{Example}:
3678 program test_complex
3681 print *, complex(i, x)
3682 end program test_complex
3685 @item @emph{See also}:
3692 @section @code{CONJG} --- Complex conjugate function
3695 @cindex complex conjugate
3698 @item @emph{Description}:
3699 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
3700 then the result is @code{(x, -y)}
3702 @item @emph{Standard}:
3703 Fortran 77 and later, has overloads that are GNU extensions
3708 @item @emph{Syntax}:
3711 @item @emph{Arguments}:
3712 @multitable @columnfractions .15 .70
3713 @item @var{Z} @tab The type shall be @code{COMPLEX}.
3716 @item @emph{Return value}:
3717 The return value is of type @code{COMPLEX}.
3719 @item @emph{Example}:
3722 complex :: z = (2.0, 3.0)
3723 complex(8) :: dz = (2.71_8, -3.14_8)
3728 end program test_conjg
3731 @item @emph{Specific names}:
3732 @multitable @columnfractions .20 .20 .20 .25
3733 @item Name @tab Argument @tab Return type @tab Standard
3734 @item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension
3735 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
3742 @section @code{COS} --- Cosine function
3748 @cindex trigonometric function, cosine
3752 @item @emph{Description}:
3753 @code{COS(X)} computes the cosine of @var{X}.
3755 @item @emph{Standard}:
3756 Fortran 77 and later, has overloads that are GNU extensions
3761 @item @emph{Syntax}:
3762 @code{RESULT = COS(X)}
3764 @item @emph{Arguments}:
3765 @multitable @columnfractions .15 .70
3766 @item @var{X} @tab The type shall be @code{REAL} or
3770 @item @emph{Return value}:
3771 The return value is of the same type and kind as @var{X}. The real part
3772 of the result is in radians. If @var{X} is of the type @code{REAL},
3773 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
3775 @item @emph{Example}:
3780 end program test_cos
3783 @item @emph{Specific names}:
3784 @multitable @columnfractions .20 .20 .20 .25
3785 @item Name @tab Argument @tab Return type @tab Standard
3786 @item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
3787 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3788 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
3789 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3790 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3793 @item @emph{See also}:
3794 Inverse function: @ref{ACOS}
3801 @section @code{COSH} --- Hyperbolic cosine function
3804 @cindex hyperbolic cosine
3805 @cindex hyperbolic function, cosine
3806 @cindex cosine, hyperbolic
3809 @item @emph{Description}:
3810 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
3812 @item @emph{Standard}:
3813 Fortran 77 and later, for a complex argument Fortran 2008 or later
3818 @item @emph{Syntax}:
3821 @item @emph{Arguments}:
3822 @multitable @columnfractions .15 .70
3823 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
3826 @item @emph{Return value}:
3827 The return value has same type and kind as @var{X}. If @var{X} is
3828 complex, the imaginary part of the result is in radians. If @var{X}
3829 is @code{REAL}, the return value has a lower bound of one,
3830 @math{\cosh (x) \geq 1}.
3832 @item @emph{Example}:
3835 real(8) :: x = 1.0_8
3837 end program test_cosh
3840 @item @emph{Specific names}:
3841 @multitable @columnfractions .20 .20 .20 .25
3842 @item Name @tab Argument @tab Return type @tab Standard
3843 @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
3844 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3847 @item @emph{See also}:
3848 Inverse function: @ref{ACOSH}
3855 @section @code{COUNT} --- Count function
3857 @cindex array, conditionally count elements
3858 @cindex array, element counting
3859 @cindex array, number of elements
3862 @item @emph{Description}:
3864 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
3865 or, if the @var{DIM} argument is supplied, counts the number of
3866 elements along each row of the array in the @var{DIM} direction.
3867 If the array has zero size, or all of the elements of @var{MASK} are
3868 @code{.FALSE.}, then the result is @code{0}.
3870 @item @emph{Standard}:
3871 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
3874 Transformational function
3876 @item @emph{Syntax}:
3877 @code{RESULT = COUNT(MASK [, DIM, KIND])}
3879 @item @emph{Arguments}:
3880 @multitable @columnfractions .15 .70
3881 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
3882 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
3883 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3884 expression indicating the kind parameter of the result.
3887 @item @emph{Return value}:
3888 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
3889 @var{KIND} is absent, the return value is of default integer kind.
3890 If @var{DIM} is present, the result is an array with a rank one less
3891 than the rank of @var{ARRAY}, and a size corresponding to the shape
3892 of @var{ARRAY} with the @var{DIM} dimension removed.
3894 @item @emph{Example}:
3897 integer, dimension(2,3) :: a, b
3898 logical, dimension(2,3) :: mask
3899 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
3900 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
3901 print '(3i3)', a(1,:)
3902 print '(3i3)', a(2,:)
3904 print '(3i3)', b(1,:)
3905 print '(3i3)', b(2,:)
3908 print '(3l3)', mask(1,:)
3909 print '(3l3)', mask(2,:)
3911 print '(3i3)', count(mask)
3913 print '(3i3)', count(mask, 1)
3915 print '(3i3)', count(mask, 2)
3916 end program test_count
3923 @section @code{CPU_TIME} --- CPU elapsed time in seconds
3925 @cindex time, elapsed
3928 @item @emph{Description}:
3929 Returns a @code{REAL} value representing the elapsed CPU time in
3930 seconds. This is useful for testing segments of code to determine
3933 If a time source is available, time will be reported with microsecond
3934 resolution. If no time source is available, @var{TIME} is set to
3937 Note that @var{TIME} may contain a, system dependent, arbitrary offset
3938 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
3939 value is meaningless, only differences between subsequent calls to
3940 this subroutine, as shown in the example below, should be used.
3943 @item @emph{Standard}:
3944 Fortran 95 and later
3949 @item @emph{Syntax}:
3950 @code{CALL CPU_TIME(TIME)}
3952 @item @emph{Arguments}:
3953 @multitable @columnfractions .15 .70
3954 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
3957 @item @emph{Return value}:
3960 @item @emph{Example}:
3962 program test_cpu_time
3963 real :: start, finish
3964 call cpu_time(start)
3965 ! put code to test here
3966 call cpu_time(finish)
3967 print '("Time = ",f6.3," seconds.")',finish-start
3968 end program test_cpu_time
3971 @item @emph{See also}:
3972 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
3978 @section @code{CSHIFT} --- Circular shift elements of an array
3980 @cindex array, shift circularly
3981 @cindex array, permutation
3982 @cindex array, rotate
3985 @item @emph{Description}:
3986 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
3987 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
3988 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
3989 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
3990 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
3991 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
3992 sections of @var{ARRAY} along the given dimension are shifted. Elements
3993 shifted out one end of each rank one section are shifted back in the other end.
3995 @item @emph{Standard}:
3996 Fortran 95 and later
3999 Transformational function
4001 @item @emph{Syntax}:
4002 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
4004 @item @emph{Arguments}:
4005 @multitable @columnfractions .15 .70
4006 @item @var{ARRAY} @tab Shall be an array of any type.
4007 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
4008 @item @var{DIM} @tab The type shall be @code{INTEGER}.
4011 @item @emph{Return value}:
4012 Returns an array of same type and rank as the @var{ARRAY} argument.
4014 @item @emph{Example}:
4017 integer, dimension(3,3) :: a
4018 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
4019 print '(3i3)', a(1,:)
4020 print '(3i3)', a(2,:)
4021 print '(3i3)', a(3,:)
4022 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
4024 print '(3i3)', a(1,:)
4025 print '(3i3)', a(2,:)
4026 print '(3i3)', a(3,:)
4027 end program test_cshift
4034 @section @code{CTIME} --- Convert a time into a string
4036 @cindex time, conversion to string
4037 @cindex conversion, to string
4040 @item @emph{Description}:
4041 @code{CTIME} converts a system time value, such as returned by
4042 @code{TIME8}, to a string. The output will be of the form @samp{Sat
4043 Aug 19 18:13:14 1995}.
4045 This intrinsic is provided in both subroutine and function forms; however,
4046 only one form can be used in any given program unit.
4048 @item @emph{Standard}:
4052 Subroutine, function
4054 @item @emph{Syntax}:
4055 @multitable @columnfractions .80
4056 @item @code{CALL CTIME(TIME, RESULT)}.
4057 @item @code{RESULT = CTIME(TIME)}.
4060 @item @emph{Arguments}:
4061 @multitable @columnfractions .15 .70
4062 @item @var{TIME} @tab The type shall be of type @code{INTEGER}.
4063 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
4064 of default kind. It is an @code{INTENT(OUT)} argument. If the length
4065 of this variable is too short for the time and date string to fit
4066 completely, it will be blank on procedure return.
4069 @item @emph{Return value}:
4070 The converted date and time as a string.
4072 @item @emph{Example}:
4076 character(len=30) :: date
4079 ! Do something, main part of the program
4082 print *, 'Program was started on ', date
4083 end program test_ctime
4086 @item @emph{See Also}:
4087 @ref{DATE_AND_TIME}, @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
4093 @section @code{DATE_AND_TIME} --- Date and time subroutine
4094 @fnindex DATE_AND_TIME
4095 @cindex date, current
4096 @cindex current date
4097 @cindex time, current
4098 @cindex current time
4101 @item @emph{Description}:
4102 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
4103 time information from the real-time system clock. @var{DATE} is
4104 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
4105 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
4106 representing the difference with respect to Coordinated Universal Time (UTC).
4107 Unavailable time and date parameters return blanks.
4109 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
4111 @multitable @columnfractions .15 .30 .40
4112 @item @tab @code{VALUE(1)}: @tab The year
4113 @item @tab @code{VALUE(2)}: @tab The month
4114 @item @tab @code{VALUE(3)}: @tab The day of the month
4115 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
4116 @item @tab @code{VALUE(5)}: @tab The hour of the day
4117 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
4118 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
4119 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
4122 @item @emph{Standard}:
4123 Fortran 95 and later
4128 @item @emph{Syntax}:
4129 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
4131 @item @emph{Arguments}:
4132 @multitable @columnfractions .15 .70
4133 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
4134 or larger, and of default kind.
4135 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
4136 or larger, and of default kind.
4137 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
4138 or larger, and of default kind.
4139 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
4142 @item @emph{Return value}:
4145 @item @emph{Example}:
4147 program test_time_and_date
4148 character(8) :: date
4149 character(10) :: time
4150 character(5) :: zone
4151 integer,dimension(8) :: values
4152 ! using keyword arguments
4153 call date_and_time(date,time,zone,values)
4154 call date_and_time(DATE=date,ZONE=zone)
4155 call date_and_time(TIME=time)
4156 call date_and_time(VALUES=values)
4157 print '(a,2x,a,2x,a)', date, time, zone
4158 print '(8i5)', values
4159 end program test_time_and_date
4162 @item @emph{See also}:
4163 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
4169 @section @code{DBLE} --- Double conversion function
4171 @cindex conversion, to real
4174 @item @emph{Description}:
4175 @code{DBLE(A)} Converts @var{A} to double precision real type.
4177 @item @emph{Standard}:
4178 Fortran 77 and later
4183 @item @emph{Syntax}:
4184 @code{RESULT = DBLE(A)}
4186 @item @emph{Arguments}:
4187 @multitable @columnfractions .15 .70
4188 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
4192 @item @emph{Return value}:
4193 The return value is of type double precision real.
4195 @item @emph{Example}:
4200 complex :: z = (2.3,1.14)
4201 print *, dble(x), dble(i), dble(z)
4202 end program test_dble
4205 @item @emph{See also}:
4212 @section @code{DCMPLX} --- Double complex conversion function
4214 @cindex complex numbers, conversion to
4215 @cindex conversion, to complex
4218 @item @emph{Description}:
4219 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
4220 converted to the real component. If @var{Y} is present it is converted to the
4221 imaginary component. If @var{Y} is not present then the imaginary component is
4222 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
4224 @item @emph{Standard}:
4230 @item @emph{Syntax}:
4231 @code{RESULT = DCMPLX(X [, Y])}
4233 @item @emph{Arguments}:
4234 @multitable @columnfractions .15 .70
4235 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
4237 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
4238 @code{INTEGER} or @code{REAL}.
4241 @item @emph{Return value}:
4242 The return value is of type @code{COMPLEX(8)}
4244 @item @emph{Example}:
4254 print *, dcmplx(x,i)
4255 end program test_dcmplx
4261 @section @code{DIGITS} --- Significant binary digits function
4263 @cindex model representation, significant digits
4266 @item @emph{Description}:
4267 @code{DIGITS(X)} returns the number of significant binary digits of the internal
4268 model representation of @var{X}. For example, on a system using a 32-bit
4269 floating point representation, a default real number would likely return 24.
4271 @item @emph{Standard}:
4272 Fortran 95 and later
4277 @item @emph{Syntax}:
4278 @code{RESULT = DIGITS(X)}
4280 @item @emph{Arguments}:
4281 @multitable @columnfractions .15 .70
4282 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
4285 @item @emph{Return value}:
4286 The return value is of type @code{INTEGER}.
4288 @item @emph{Example}:
4291 integer :: i = 12345
4297 end program test_digits
4304 @section @code{DIM} --- Positive difference
4308 @cindex positive difference
4311 @item @emph{Description}:
4312 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
4313 otherwise returns zero.
4315 @item @emph{Standard}:
4316 Fortran 77 and later
4321 @item @emph{Syntax}:
4322 @code{RESULT = DIM(X, Y)}
4324 @item @emph{Arguments}:
4325 @multitable @columnfractions .15 .70
4326 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
4327 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
4330 @item @emph{Return value}:
4331 The return value is of type @code{INTEGER} or @code{REAL}.
4333 @item @emph{Example}:
4339 x = dim(4.345_8, 2.111_8)
4342 end program test_dim
4345 @item @emph{Specific names}:
4346 @multitable @columnfractions .20 .20 .20 .25
4347 @item Name @tab Argument @tab Return type @tab Standard
4348 @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
4349 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
4350 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
4357 @section @code{DOT_PRODUCT} --- Dot product function
4358 @fnindex DOT_PRODUCT
4360 @cindex vector product
4361 @cindex product, vector
4364 @item @emph{Description}:
4365 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
4366 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
4367 either numeric or logical and must be arrays of rank one and of equal size. If
4368 the vectors are @code{INTEGER} or @code{REAL}, the result is
4369 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
4370 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
4371 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
4373 @item @emph{Standard}:
4374 Fortran 95 and later
4377 Transformational function
4379 @item @emph{Syntax}:
4380 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
4382 @item @emph{Arguments}:
4383 @multitable @columnfractions .15 .70
4384 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
4385 @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.
4388 @item @emph{Return value}:
4389 If the arguments are numeric, the return value is a scalar of numeric type,
4390 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
4391 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
4393 @item @emph{Example}:
4395 program test_dot_prod
4396 integer, dimension(3) :: a, b
4403 print *, dot_product(a,b)
4404 end program test_dot_prod
4411 @section @code{DPROD} --- Double product function
4413 @cindex product, double-precision
4416 @item @emph{Description}:
4417 @code{DPROD(X,Y)} returns the product @code{X*Y}.
4419 @item @emph{Standard}:
4420 Fortran 77 and later
4425 @item @emph{Syntax}:
4426 @code{RESULT = DPROD(X, Y)}
4428 @item @emph{Arguments}:
4429 @multitable @columnfractions .15 .70
4430 @item @var{X} @tab The type shall be @code{REAL}.
4431 @item @var{Y} @tab The type shall be @code{REAL}.
4434 @item @emph{Return value}:
4435 The return value is of type @code{REAL(8)}.
4437 @item @emph{Example}:
4445 end program test_dprod
4448 @item @emph{Specific names}:
4449 @multitable @columnfractions .20 .20 .20 .25
4450 @item Name @tab Argument @tab Return type @tab Standard
4451 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
4458 @section @code{DREAL} --- Double real part function
4460 @cindex complex numbers, real part
4463 @item @emph{Description}:
4464 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
4466 @item @emph{Standard}:
4472 @item @emph{Syntax}:
4473 @code{RESULT = DREAL(A)}
4475 @item @emph{Arguments}:
4476 @multitable @columnfractions .15 .70
4477 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
4480 @item @emph{Return value}:
4481 The return value is of type @code{REAL(8)}.
4483 @item @emph{Example}:
4486 complex(8) :: z = (1.3_8,7.2_8)
4488 end program test_dreal
4491 @item @emph{See also}:
4499 @section @code{DSHIFTL} --- Combined left shift
4501 @cindex left shift, combined
4505 @item @emph{Description}:
4506 @code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
4507 rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
4508 bits of @var{J}, and the remaining bits are the rightmost bits of
4511 @item @emph{Standard}:
4512 Fortran 2008 and later
4517 @item @emph{Syntax}:
4518 @code{RESULT = DSHIFTL(I, J, SHIFT)}
4520 @item @emph{Arguments}:
4521 @multitable @columnfractions .15 .70
4522 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
4523 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
4524 If both @var{I} and @var{J} have integer type, then they shall have
4525 the same kind type parameter. @var{I} and @var{J} shall not both be
4527 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
4528 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
4529 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
4530 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
4533 @item @emph{Return value}:
4534 If either @var{I} or @var{J} is a BOZ constant, it is first converted
4535 as if by the intrinsic function @code{INT} to an integer type with the
4536 kind type parameter of the other.
4538 @item @emph{See also}:
4544 @section @code{DSHIFTR} --- Combined right shift
4546 @cindex right shift, combined
4547 @cindex shift, right
4550 @item @emph{Description}:
4551 @code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
4552 leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
4553 bits of @var{I}, and the remaining bits are the leftmost bits of
4556 @item @emph{Standard}:
4557 Fortran 2008 and later
4562 @item @emph{Syntax}:
4563 @code{RESULT = DSHIFTR(I, J, SHIFT)}
4565 @item @emph{Arguments}:
4566 @multitable @columnfractions .15 .70
4567 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
4568 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
4569 If both @var{I} and @var{J} have integer type, then they shall have
4570 the same kind type parameter. @var{I} and @var{J} shall not both be
4572 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
4573 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
4574 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
4575 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
4578 @item @emph{Return value}:
4579 If either @var{I} or @var{J} is a BOZ constant, it is first converted
4580 as if by the intrinsic function @code{INT} to an integer type with the
4581 kind type parameter of the other.
4583 @item @emph{See also}:
4589 @section @code{DTIME} --- Execution time subroutine (or function)
4591 @cindex time, elapsed
4592 @cindex elapsed time
4595 @item @emph{Description}:
4596 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
4597 since the start of the process's execution in @var{TIME}. @var{VALUES}
4598 returns the user and system components of this time in @code{VALUES(1)} and
4599 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
4602 Subsequent invocations of @code{DTIME} return values accumulated since the
4603 previous invocation.
4605 On some systems, the underlying timings are represented using types with
4606 sufficiently small limits that overflows (wrap around) are possible, such as
4607 32-bit types. Therefore, the values returned by this intrinsic might be, or
4608 become, negative, or numerically less than previous values, during a single
4609 run of the compiled program.
4611 Please note, that this implementation is thread safe if used within OpenMP
4612 directives, i.e., its state will be consistent while called from multiple
4613 threads. However, if @code{DTIME} is called from multiple threads, the result
4614 is still the time since the last invocation. This may not give the intended
4615 results. If possible, use @code{CPU_TIME} instead.
4617 This intrinsic is provided in both subroutine and function forms; however,
4618 only one form can be used in any given program unit.
4620 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
4622 @multitable @columnfractions .15 .30 .40
4623 @item @tab @code{VALUES(1)}: @tab User time in seconds.
4624 @item @tab @code{VALUES(2)}: @tab System time in seconds.
4625 @item @tab @code{TIME}: @tab Run time since start in seconds.
4628 @item @emph{Standard}:
4632 Subroutine, function
4634 @item @emph{Syntax}:
4635 @multitable @columnfractions .80
4636 @item @code{CALL DTIME(VALUES, TIME)}.
4637 @item @code{TIME = DTIME(VALUES)}, (not recommended).
4640 @item @emph{Arguments}:
4641 @multitable @columnfractions .15 .70
4642 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
4643 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
4646 @item @emph{Return value}:
4647 Elapsed time in seconds since the last invocation or since the start of program
4648 execution if not called before.
4650 @item @emph{Example}:
4654 real, dimension(2) :: tarray
4656 call dtime(tarray, result)
4660 do i=1,100000000 ! Just a delay
4663 call dtime(tarray, result)
4667 end program test_dtime
4670 @item @emph{See also}:
4678 @section @code{EOSHIFT} --- End-off shift elements of an array
4680 @cindex array, shift
4683 @item @emph{Description}:
4684 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
4685 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
4686 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
4687 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
4688 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
4689 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
4690 then all complete rank one sections of @var{ARRAY} along the given dimension are
4691 shifted. Elements shifted out one end of each rank one section are dropped. If
4692 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
4693 is copied back in the other end. If @var{BOUNDARY} is not present then the
4694 following are copied in depending on the type of @var{ARRAY}.
4696 @multitable @columnfractions .15 .80
4697 @item @emph{Array Type} @tab @emph{Boundary Value}
4698 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
4699 @item Logical @tab @code{.FALSE.}.
4700 @item Character(@var{len}) @tab @var{len} blanks.
4703 @item @emph{Standard}:
4704 Fortran 95 and later
4707 Transformational function
4709 @item @emph{Syntax}:
4710 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
4712 @item @emph{Arguments}:
4713 @multitable @columnfractions .15 .70
4714 @item @var{ARRAY} @tab May be any type, not scalar.
4715 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
4716 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
4717 @item @var{DIM} @tab The type shall be @code{INTEGER}.
4720 @item @emph{Return value}:
4721 Returns an array of same type and rank as the @var{ARRAY} argument.
4723 @item @emph{Example}:
4725 program test_eoshift
4726 integer, dimension(3,3) :: a
4727 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
4728 print '(3i3)', a(1,:)
4729 print '(3i3)', a(2,:)
4730 print '(3i3)', a(3,:)
4731 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
4733 print '(3i3)', a(1,:)
4734 print '(3i3)', a(2,:)
4735 print '(3i3)', a(3,:)
4736 end program test_eoshift
4743 @section @code{EPSILON} --- Epsilon function
4745 @cindex model representation, epsilon
4748 @item @emph{Description}:
4749 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
4750 as @var{X} such that @math{1 + E > 1}.
4752 @item @emph{Standard}:
4753 Fortran 95 and later
4758 @item @emph{Syntax}:
4759 @code{RESULT = EPSILON(X)}
4761 @item @emph{Arguments}:
4762 @multitable @columnfractions .15 .70
4763 @item @var{X} @tab The type shall be @code{REAL}.
4766 @item @emph{Return value}:
4767 The return value is of same type as the argument.
4769 @item @emph{Example}:
4771 program test_epsilon
4776 end program test_epsilon
4783 @section @code{ERF} --- Error function
4785 @cindex error function
4788 @item @emph{Description}:
4789 @code{ERF(X)} computes the error function of @var{X}.
4791 @item @emph{Standard}:
4792 Fortran 2008 and later
4797 @item @emph{Syntax}:
4798 @code{RESULT = ERF(X)}
4800 @item @emph{Arguments}:
4801 @multitable @columnfractions .15 .70
4802 @item @var{X} @tab The type shall be @code{REAL}.
4805 @item @emph{Return value}:
4806 The return value is of type @code{REAL}, of the same kind as
4807 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
4809 @item @emph{Example}:
4812 real(8) :: x = 0.17_8
4814 end program test_erf
4817 @item @emph{Specific names}:
4818 @multitable @columnfractions .20 .20 .20 .25
4819 @item Name @tab Argument @tab Return type @tab Standard
4820 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4827 @section @code{ERFC} --- Error function
4829 @cindex error function, complementary
4832 @item @emph{Description}:
4833 @code{ERFC(X)} computes the complementary error function of @var{X}.
4835 @item @emph{Standard}:
4836 Fortran 2008 and later
4841 @item @emph{Syntax}:
4842 @code{RESULT = ERFC(X)}
4844 @item @emph{Arguments}:
4845 @multitable @columnfractions .15 .70
4846 @item @var{X} @tab The type shall be @code{REAL}.
4849 @item @emph{Return value}:
4850 The return value is of type @code{REAL} and of the same kind as @var{X}.
4851 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
4853 @item @emph{Example}:
4856 real(8) :: x = 0.17_8
4858 end program test_erfc
4861 @item @emph{Specific names}:
4862 @multitable @columnfractions .20 .20 .20 .25
4863 @item Name @tab Argument @tab Return type @tab Standard
4864 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4871 @section @code{ERFC_SCALED} --- Error function
4872 @fnindex ERFC_SCALED
4873 @cindex error function, complementary, exponentially-scaled
4876 @item @emph{Description}:
4877 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
4878 error function of @var{X}.
4880 @item @emph{Standard}:
4881 Fortran 2008 and later
4886 @item @emph{Syntax}:
4887 @code{RESULT = ERFC_SCALED(X)}
4889 @item @emph{Arguments}:
4890 @multitable @columnfractions .15 .70
4891 @item @var{X} @tab The type shall be @code{REAL}.
4894 @item @emph{Return value}:
4895 The return value is of type @code{REAL} and of the same kind as @var{X}.
4897 @item @emph{Example}:
4899 program test_erfc_scaled
4900 real(8) :: x = 0.17_8
4902 end program test_erfc_scaled
4909 @section @code{ETIME} --- Execution time subroutine (or function)
4911 @cindex time, elapsed
4914 @item @emph{Description}:
4915 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
4916 since the start of the process's execution in @var{TIME}. @var{VALUES}
4917 returns the user and system components of this time in @code{VALUES(1)} and
4918 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
4920 On some systems, the underlying timings are represented using types with
4921 sufficiently small limits that overflows (wrap around) are possible, such as
4922 32-bit types. Therefore, the values returned by this intrinsic might be, or
4923 become, negative, or numerically less than previous values, during a single
4924 run of the compiled program.
4926 This intrinsic is provided in both subroutine and function forms; however,
4927 only one form can be used in any given program unit.
4929 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
4931 @multitable @columnfractions .15 .30 .60
4932 @item @tab @code{VALUES(1)}: @tab User time in seconds.
4933 @item @tab @code{VALUES(2)}: @tab System time in seconds.
4934 @item @tab @code{TIME}: @tab Run time since start in seconds.
4937 @item @emph{Standard}:
4941 Subroutine, function
4943 @item @emph{Syntax}:
4944 @multitable @columnfractions .80
4945 @item @code{CALL ETIME(VALUES, TIME)}.
4946 @item @code{TIME = ETIME(VALUES)}, (not recommended).
4949 @item @emph{Arguments}:
4950 @multitable @columnfractions .15 .70
4951 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
4952 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
4955 @item @emph{Return value}:
4956 Elapsed time in seconds since the start of program execution.
4958 @item @emph{Example}:
4962 real, dimension(2) :: tarray
4964 call ETIME(tarray, result)
4968 do i=1,100000000 ! Just a delay
4971 call ETIME(tarray, result)
4975 end program test_etime
4978 @item @emph{See also}:
4985 @node EXECUTE_COMMAND_LINE
4986 @section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
4987 @fnindex EXECUTE_COMMAND_LINE
4988 @cindex system, system call
4989 @cindex command line
4992 @item @emph{Description}:
4993 @code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
4996 The @code{COMMAND} argument is passed to the shell and executed, using
4997 the C library's @code{system} call. (The shell is @code{sh} on Unix
4998 systems, and @code{cmd.exe} on Windows.) If @code{WAIT} is present
4999 and has the value false, the execution of the command is asynchronous
5000 if the system supports it; otherwise, the command is executed
5003 The three last arguments allow the user to get status information. After
5004 synchronous execution, @code{EXITSTAT} contains the integer exit code of
5005 the command, as returned by @code{system}. @code{CMDSTAT} is set to zero
5006 if the command line was executed (whatever its exit status was).
5007 @code{CMDMSG} is assigned an error message if an error has occurred.
5009 Note that the @code{system} function need not be thread-safe. It is
5010 the responsibility of the user to ensure that @code{system} is not
5011 called concurrently.
5013 @item @emph{Standard}:
5014 Fortran 2008 and later
5019 @item @emph{Syntax}:
5020 @code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
5022 @item @emph{Arguments}:
5023 @multitable @columnfractions .15 .70
5024 @item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
5025 @item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
5026 @item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5028 @item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5030 @item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
5034 @item @emph{Example}:
5039 call execute_command_line ("external_prog.exe", exitstat=i)
5040 print *, "Exit status of external_prog.exe was ", i
5042 call execute_command_line ("reindex_files.exe", wait=.false.)
5043 print *, "Now reindexing files in the background"
5045 end program test_exec
5051 Because this intrinsic is implemented in terms of the @code{system}
5052 function call, its behavior with respect to signaling is processor
5053 dependent. In particular, on POSIX-compliant systems, the SIGINT and
5054 SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
5055 such, if the parent process is terminated, the child process might not be
5056 terminated alongside.
5059 @item @emph{See also}:
5066 @section @code{EXIT} --- Exit the program with status.
5068 @cindex program termination
5069 @cindex terminate program
5072 @item @emph{Description}:
5073 @code{EXIT} causes immediate termination of the program with status. If status
5074 is omitted it returns the canonical @emph{success} for the system. All Fortran
5075 I/O units are closed.
5077 @item @emph{Standard}:
5083 @item @emph{Syntax}:
5084 @code{CALL EXIT([STATUS])}
5086 @item @emph{Arguments}:
5087 @multitable @columnfractions .15 .70
5088 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
5091 @item @emph{Return value}:
5092 @code{STATUS} is passed to the parent process on exit.
5094 @item @emph{Example}:
5097 integer :: STATUS = 0
5098 print *, 'This program is going to exit.'
5100 end program test_exit
5103 @item @emph{See also}:
5104 @ref{ABORT}, @ref{KILL}
5110 @section @code{EXP} --- Exponential function
5116 @cindex exponential function
5117 @cindex logarithm function, inverse
5120 @item @emph{Description}:
5121 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
5123 @item @emph{Standard}:
5124 Fortran 77 and later, has overloads that are GNU extensions
5129 @item @emph{Syntax}:
5130 @code{RESULT = EXP(X)}
5132 @item @emph{Arguments}:
5133 @multitable @columnfractions .15 .70
5134 @item @var{X} @tab The type shall be @code{REAL} or
5138 @item @emph{Return value}:
5139 The return value has same type and kind as @var{X}.
5141 @item @emph{Example}:
5146 end program test_exp
5149 @item @emph{Specific names}:
5150 @multitable @columnfractions .20 .20 .20 .25
5151 @item Name @tab Argument @tab Return type @tab Standard
5152 @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
5153 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
5154 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
5155 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5156 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5163 @section @code{EXPONENT} --- Exponent function
5165 @cindex real number, exponent
5166 @cindex floating point, exponent
5169 @item @emph{Description}:
5170 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
5171 is zero the value returned is zero.
5173 @item @emph{Standard}:
5174 Fortran 95 and later
5179 @item @emph{Syntax}:
5180 @code{RESULT = EXPONENT(X)}
5182 @item @emph{Arguments}:
5183 @multitable @columnfractions .15 .70
5184 @item @var{X} @tab The type shall be @code{REAL}.
5187 @item @emph{Return value}:
5188 The return value is of type default @code{INTEGER}.
5190 @item @emph{Example}:
5192 program test_exponent
5197 print *, exponent(0.0)
5198 end program test_exponent
5204 @node EXTENDS_TYPE_OF
5205 @section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension
5206 @fnindex EXTENDS_TYPE_OF
5209 @item @emph{Description}:
5210 Query dynamic type for extension.
5212 @item @emph{Standard}:
5213 Fortran 2003 and later
5218 @item @emph{Syntax}:
5219 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
5221 @item @emph{Arguments}:
5222 @multitable @columnfractions .15 .70
5223 @item @var{A} @tab Shall be an object of extensible declared type or
5224 unlimited polymorphic.
5225 @item @var{MOLD} @tab Shall be an object of extensible declared type or
5226 unlimited polymorphic.
5229 @item @emph{Return value}:
5230 The return value is a scalar of type default logical. It is true if and only if
5231 the dynamic type of A is an extension type of the dynamic type of MOLD.
5234 @item @emph{See also}:
5241 @section @code{FDATE} --- Get the current time as a string
5243 @cindex time, current
5244 @cindex current time
5245 @cindex date, current
5246 @cindex current date
5249 @item @emph{Description}:
5250 @code{FDATE(DATE)} returns the current date (using the same format as
5251 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
5254 This intrinsic is provided in both subroutine and function forms; however,
5255 only one form can be used in any given program unit.
5257 @item @emph{Standard}:
5261 Subroutine, function
5263 @item @emph{Syntax}:
5264 @multitable @columnfractions .80
5265 @item @code{CALL FDATE(DATE)}.
5266 @item @code{DATE = FDATE()}.
5269 @item @emph{Arguments}:
5270 @multitable @columnfractions .15 .70
5271 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
5272 default kind. It is an @code{INTENT(OUT)} argument. If the length of
5273 this variable is too short for the date and time string to fit
5274 completely, it will be blank on procedure return.
5277 @item @emph{Return value}:
5278 The current date and time as a string.
5280 @item @emph{Example}:
5284 character(len=30) :: date
5286 print *, 'Program started on ', date
5287 do i = 1, 100000000 ! Just a delay
5291 print *, 'Program ended on ', date
5292 end program test_fdate
5295 @item @emph{See also}:
5296 @ref{DATE_AND_TIME}, @ref{CTIME}
5301 @section @code{FGET} --- Read a single character in stream mode from stdin
5303 @cindex read character, stream mode
5304 @cindex stream mode, read character
5305 @cindex file operation, read character
5308 @item @emph{Description}:
5309 Read a single character in stream mode from stdin by bypassing normal
5310 formatted output. Stream I/O should not be mixed with normal record-oriented
5311 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
5313 This intrinsic is provided in both subroutine and function forms; however,
5314 only one form can be used in any given program unit.
5316 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
5317 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5318 Programmers should consider the use of new stream IO feature in new code
5319 for future portability. See also @ref{Fortran 2003 status}.
5321 @item @emph{Standard}:
5325 Subroutine, function
5327 @item @emph{Syntax}:
5328 @multitable @columnfractions .80
5329 @item @code{CALL FGET(C [, STATUS])}
5330 @item @code{STATUS = FGET(C)}
5333 @item @emph{Arguments}:
5334 @multitable @columnfractions .15 .70
5335 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5337 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5338 Returns 0 on success, -1 on end-of-file, and a system specific positive
5339 error code otherwise.
5342 @item @emph{Example}:
5345 INTEGER, PARAMETER :: strlen = 100
5346 INTEGER :: status, i = 1
5347 CHARACTER(len=strlen) :: str = ""
5349 WRITE (*,*) 'Enter text:'
5351 CALL fget(str(i:i), status)
5352 if (status /= 0 .OR. i > strlen) exit
5355 WRITE (*,*) TRIM(str)
5359 @item @emph{See also}:
5360 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
5366 @section @code{FGETC} --- Read a single character in stream mode
5368 @cindex read character, stream mode
5369 @cindex stream mode, read character
5370 @cindex file operation, read character
5373 @item @emph{Description}:
5374 Read a single character in stream mode by bypassing normal formatted output.
5375 Stream I/O should not be mixed with normal record-oriented (formatted or
5376 unformatted) I/O on the same unit; the results are unpredictable.
5378 This intrinsic is provided in both subroutine and function forms; however,
5379 only one form can be used in any given program unit.
5381 Note that the @code{FGET} intrinsic is provided for backwards compatibility
5382 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5383 Programmers should consider the use of new stream IO feature in new code
5384 for future portability. See also @ref{Fortran 2003 status}.
5386 @item @emph{Standard}:
5390 Subroutine, function
5392 @item @emph{Syntax}:
5393 @multitable @columnfractions .80
5394 @item @code{CALL FGETC(UNIT, C [, STATUS])}
5395 @item @code{STATUS = FGETC(UNIT, C)}
5398 @item @emph{Arguments}:
5399 @multitable @columnfractions .15 .70
5400 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
5401 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5403 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5404 Returns 0 on success, -1 on end-of-file and a system specific positive
5405 error code otherwise.
5408 @item @emph{Example}:
5411 INTEGER :: fd = 42, status
5414 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
5416 CALL fgetc(fd, c, status)
5417 IF (status /= 0) EXIT
5424 @item @emph{See also}:
5425 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
5431 @section @code{FLOOR} --- Integer floor function
5434 @cindex rounding, floor
5437 @item @emph{Description}:
5438 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
5440 @item @emph{Standard}:
5441 Fortran 95 and later
5446 @item @emph{Syntax}:
5447 @code{RESULT = FLOOR(A [, KIND])}
5449 @item @emph{Arguments}:
5450 @multitable @columnfractions .15 .70
5451 @item @var{A} @tab The type shall be @code{REAL}.
5452 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5453 expression indicating the kind parameter of the result.
5456 @item @emph{Return value}:
5457 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
5458 and of default-kind @code{INTEGER} otherwise.
5460 @item @emph{Example}:
5465 print *, floor(x) ! returns 63
5466 print *, floor(y) ! returns -64
5467 end program test_floor
5470 @item @emph{See also}:
5471 @ref{CEILING}, @ref{NINT}
5478 @section @code{FLUSH} --- Flush I/O unit(s)
5480 @cindex file operation, flush
5483 @item @emph{Description}:
5484 Flushes Fortran unit(s) currently open for output. Without the optional
5485 argument, all units are flushed, otherwise just the unit specified.
5487 @item @emph{Standard}:
5493 @item @emph{Syntax}:
5494 @code{CALL FLUSH(UNIT)}
5496 @item @emph{Arguments}:
5497 @multitable @columnfractions .15 .70
5498 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
5502 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
5503 statement that should be preferred over the @code{FLUSH} intrinsic.
5505 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
5506 have identical effect: they flush the runtime library's I/O buffer so
5507 that the data becomes visible to other processes. This does not guarantee
5508 that the data is committed to disk.
5510 On POSIX systems, you can request that all data is transferred to the
5511 storage device by calling the @code{fsync} function, with the POSIX file
5512 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
5513 @code{FNUM}). The following example shows how:
5516 ! Declare the interface for POSIX fsync function
5518 function fsync (fd) bind(c,name="fsync")
5519 use iso_c_binding, only: c_int
5520 integer(c_int), value :: fd
5521 integer(c_int) :: fsync
5525 ! Variable declaration
5529 open (10,file="foo")
5532 ! Perform I/O on unit 10
5537 ret = fsync(fnum(10))
5539 ! Handle possible error
5540 if (ret /= 0) stop "Error calling FSYNC"
5548 @section @code{FNUM} --- File number function
5550 @cindex file operation, file number
5553 @item @emph{Description}:
5554 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
5555 open Fortran I/O unit @code{UNIT}.
5557 @item @emph{Standard}:
5563 @item @emph{Syntax}:
5564 @code{RESULT = FNUM(UNIT)}
5566 @item @emph{Arguments}:
5567 @multitable @columnfractions .15 .70
5568 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
5571 @item @emph{Return value}:
5572 The return value is of type @code{INTEGER}
5574 @item @emph{Example}:
5578 open (unit=10, status = "scratch")
5582 end program test_fnum
5589 @section @code{FPUT} --- Write a single character in stream mode to stdout
5591 @cindex write character, stream mode
5592 @cindex stream mode, write character
5593 @cindex file operation, write character
5596 @item @emph{Description}:
5597 Write a single character in stream mode to stdout by bypassing normal
5598 formatted output. Stream I/O should not be mixed with normal record-oriented
5599 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
5601 This intrinsic is provided in both subroutine and function forms; however,
5602 only one form can be used in any given program unit.
5604 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
5605 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5606 Programmers should consider the use of new stream IO feature in new code
5607 for future portability. See also @ref{Fortran 2003 status}.
5609 @item @emph{Standard}:
5613 Subroutine, function
5615 @item @emph{Syntax}:
5616 @multitable @columnfractions .80
5617 @item @code{CALL FPUT(C [, STATUS])}
5618 @item @code{STATUS = FPUT(C)}
5621 @item @emph{Arguments}:
5622 @multitable @columnfractions .15 .70
5623 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5625 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5626 Returns 0 on success, -1 on end-of-file and a system specific positive
5627 error code otherwise.
5630 @item @emph{Example}:
5633 CHARACTER(len=10) :: str = "gfortran"
5635 DO i = 1, len_trim(str)
5641 @item @emph{See also}:
5642 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
5648 @section @code{FPUTC} --- Write a single character in stream mode
5650 @cindex write character, stream mode
5651 @cindex stream mode, write character
5652 @cindex file operation, write character
5655 @item @emph{Description}:
5656 Write a single character in stream mode by bypassing normal formatted
5657 output. Stream I/O should not be mixed with normal record-oriented
5658 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
5660 This intrinsic is provided in both subroutine and function forms; however,
5661 only one form can be used in any given program unit.
5663 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
5664 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5665 Programmers should consider the use of new stream IO feature in new code
5666 for future portability. See also @ref{Fortran 2003 status}.
5668 @item @emph{Standard}:
5672 Subroutine, function
5674 @item @emph{Syntax}:
5675 @multitable @columnfractions .80
5676 @item @code{CALL FPUTC(UNIT, C [, STATUS])}
5677 @item @code{STATUS = FPUTC(UNIT, C)}
5680 @item @emph{Arguments}:
5681 @multitable @columnfractions .15 .70
5682 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
5683 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5685 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5686 Returns 0 on success, -1 on end-of-file and a system specific positive
5687 error code otherwise.
5690 @item @emph{Example}:
5693 CHARACTER(len=10) :: str = "gfortran"
5694 INTEGER :: fd = 42, i
5696 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
5697 DO i = 1, len_trim(str)
5698 CALL fputc(fd, str(i:i))
5704 @item @emph{See also}:
5705 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
5711 @section @code{FRACTION} --- Fractional part of the model representation
5713 @cindex real number, fraction
5714 @cindex floating point, fraction
5717 @item @emph{Description}:
5718 @code{FRACTION(X)} returns the fractional part of the model
5719 representation of @code{X}.
5721 @item @emph{Standard}:
5722 Fortran 95 and later
5727 @item @emph{Syntax}:
5728 @code{Y = FRACTION(X)}
5730 @item @emph{Arguments}:
5731 @multitable @columnfractions .15 .70
5732 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
5735 @item @emph{Return value}:
5736 The return value is of the same type and kind as the argument.
5737 The fractional part of the model representation of @code{X} is returned;
5738 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
5740 @item @emph{Example}:
5742 program test_fraction
5745 print *, fraction(x), x * radix(x)**(-exponent(x))
5746 end program test_fraction
5754 @section @code{FREE} --- Frees memory
5756 @cindex pointer, cray
5759 @item @emph{Description}:
5760 Frees memory previously allocated by @code{MALLOC}. The @code{FREE}
5761 intrinsic is an extension intended to be used with Cray pointers, and is
5762 provided in GNU Fortran to allow user to compile legacy code. For
5763 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
5766 @item @emph{Standard}:
5772 @item @emph{Syntax}:
5773 @code{CALL FREE(PTR)}
5775 @item @emph{Arguments}:
5776 @multitable @columnfractions .15 .70
5777 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
5778 location of the memory that should be de-allocated.
5781 @item @emph{Return value}:
5784 @item @emph{Example}:
5785 See @code{MALLOC} for an example.
5787 @item @emph{See also}:
5794 @section @code{FSEEK} --- Low level file positioning subroutine
5796 @cindex file operation, seek
5797 @cindex file operation, position
5800 @item @emph{Description}:
5801 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
5802 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
5803 if set to 1, @var{OFFSET} is taken to be relative to the current position
5804 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
5805 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
5808 This intrinsic routine is not fully backwards compatible with @command{g77}.
5809 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
5810 @var{STATUS} variable. If FSEEK is used in old code, change
5812 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
5817 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
5818 IF (status /= 0) GOTO label
5821 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
5822 Programmers should consider the use of new stream IO feature in new code
5823 for future portability. See also @ref{Fortran 2003 status}.
5825 @item @emph{Standard}:
5831 @item @emph{Syntax}:
5832 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
5834 @item @emph{Arguments}:
5835 @multitable @columnfractions .15 .70
5836 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
5837 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
5838 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
5839 Its value shall be either 0, 1 or 2.
5840 @item @var{STATUS} @tab (Optional) shall be a scalar of type
5844 @item @emph{Example}:
5847 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
5848 INTEGER :: fd, offset, ierr
5854 OPEN(UNIT=fd, FILE="fseek.test")
5855 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
5856 print *, FTELL(fd), ierr
5858 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
5859 print *, FTELL(fd), ierr
5861 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
5862 print *, FTELL(fd), ierr
5868 @item @emph{See also}:
5875 @section @code{FSTAT} --- Get file status
5877 @cindex file system, file status
5880 @item @emph{Description}:
5881 @code{FSTAT} is identical to @ref{STAT}, except that information about an
5882 already opened file is obtained.
5884 The elements in @code{VALUES} are the same as described by @ref{STAT}.
5886 This intrinsic is provided in both subroutine and function forms; however,
5887 only one form can be used in any given program unit.
5889 @item @emph{Standard}:
5893 Subroutine, function
5895 @item @emph{Syntax}:
5896 @multitable @columnfractions .80
5897 @item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
5898 @item @code{STATUS = FSTAT(UNIT, VALUES)}
5901 @item @emph{Arguments}:
5902 @multitable @columnfractions .15 .70
5903 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
5904 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
5905 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
5906 on success and a system specific error code otherwise.
5909 @item @emph{Example}:
5910 See @ref{STAT} for an example.
5912 @item @emph{See also}:
5913 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
5919 @section @code{FTELL} --- Current stream position
5921 @cindex file operation, position
5924 @item @emph{Description}:
5925 Retrieves the current position within an open file.
5927 This intrinsic is provided in both subroutine and function forms; however,
5928 only one form can be used in any given program unit.
5930 @item @emph{Standard}:
5934 Subroutine, function
5936 @item @emph{Syntax}:
5937 @multitable @columnfractions .80
5938 @item @code{CALL FTELL(UNIT, OFFSET)}
5939 @item @code{OFFSET = FTELL(UNIT)}
5942 @item @emph{Arguments}:
5943 @multitable @columnfractions .15 .70
5944 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
5945 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
5948 @item @emph{Return value}:
5949 In either syntax, @var{OFFSET} is set to the current offset of unit
5950 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
5952 @item @emph{Example}:
5956 OPEN(10, FILE="temp.dat")
5962 @item @emph{See also}:
5969 @section @code{GAMMA} --- Gamma function
5972 @cindex Gamma function
5973 @cindex Factorial function
5976 @item @emph{Description}:
5977 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
5978 integer values of @var{X} the Gamma function simplifies to the factorial
5979 function @math{\Gamma(x)=(x-1)!}.
5983 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
5987 @item @emph{Standard}:
5988 Fortran 2008 and later
5993 @item @emph{Syntax}:
5996 @item @emph{Arguments}:
5997 @multitable @columnfractions .15 .70
5998 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
5999 nor a negative integer.
6002 @item @emph{Return value}:
6003 The return value is of type @code{REAL} of the same kind as @var{X}.
6005 @item @emph{Example}:
6009 x = gamma(x) ! returns 1.0
6010 end program test_gamma
6013 @item @emph{Specific names}:
6014 @multitable @columnfractions .20 .20 .20 .25
6015 @item Name @tab Argument @tab Return type @tab Standard
6016 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
6017 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
6020 @item @emph{See also}:
6021 Logarithm of the Gamma function: @ref{LOG_GAMMA}
6028 @section @code{GERROR} --- Get last system error message
6030 @cindex system, error handling
6033 @item @emph{Description}:
6034 Returns the system error message corresponding to the last system error.
6035 This resembles the functionality of @code{strerror(3)} in C.
6037 @item @emph{Standard}:
6043 @item @emph{Syntax}:
6044 @code{CALL GERROR(RESULT)}
6046 @item @emph{Arguments}:
6047 @multitable @columnfractions .15 .70
6048 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
6051 @item @emph{Example}:
6054 CHARACTER(len=100) :: msg
6060 @item @emph{See also}:
6061 @ref{IERRNO}, @ref{PERROR}
6067 @section @code{GETARG} --- Get command line arguments
6069 @cindex command-line arguments
6070 @cindex arguments, to program
6073 @item @emph{Description}:
6074 Retrieve the @var{POS}-th argument that was passed on the
6075 command line when the containing program was invoked.
6077 This intrinsic routine is provided for backwards compatibility with
6078 GNU Fortran 77. In new code, programmers should consider the use of
6079 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
6082 @item @emph{Standard}:
6088 @item @emph{Syntax}:
6089 @code{CALL GETARG(POS, VALUE)}
6091 @item @emph{Arguments}:
6092 @multitable @columnfractions .15 .70
6093 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
6094 the default integer kind; @math{@var{POS} \geq 0}
6095 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
6097 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
6100 @item @emph{Return value}:
6101 After @code{GETARG} returns, the @var{VALUE} argument holds the
6102 @var{POS}th command line argument. If @var{VALUE} can not hold the
6103 argument, it is truncated to fit the length of @var{VALUE}. If there are
6104 less than @var{POS} arguments specified at the command line, @var{VALUE}
6105 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
6106 to the name of the program (on systems that support this feature).
6108 @item @emph{Example}:
6112 CHARACTER(len=32) :: arg
6121 @item @emph{See also}:
6122 GNU Fortran 77 compatibility function: @ref{IARGC}
6124 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
6125 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6131 @section @code{GET_COMMAND} --- Get the entire command line
6132 @fnindex GET_COMMAND
6133 @cindex command-line arguments
6134 @cindex arguments, to program
6137 @item @emph{Description}:
6138 Retrieve the entire command line that was used to invoke the program.
6140 @item @emph{Standard}:
6141 Fortran 2003 and later
6146 @item @emph{Syntax}:
6147 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
6149 @item @emph{Arguments}:
6150 @multitable @columnfractions .15 .70
6151 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
6153 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
6155 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
6159 @item @emph{Return value}:
6160 If @var{COMMAND} is present, stores the entire command line that was used
6161 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
6162 assigned the length of the command line. If @var{STATUS} is present, it
6163 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
6164 short to store the command line, or a positive value in case of an error.
6166 @item @emph{Example}:
6168 PROGRAM test_get_command
6169 CHARACTER(len=255) :: cmd
6170 CALL get_command(cmd)
6171 WRITE (*,*) TRIM(cmd)
6175 @item @emph{See also}:
6176 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6181 @node GET_COMMAND_ARGUMENT
6182 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
6183 @fnindex GET_COMMAND_ARGUMENT
6184 @cindex command-line arguments
6185 @cindex arguments, to program
6188 @item @emph{Description}:
6189 Retrieve the @var{NUMBER}-th argument that was passed on the
6190 command line when the containing program was invoked.
6192 @item @emph{Standard}:
6193 Fortran 2003 and later
6198 @item @emph{Syntax}:
6199 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
6201 @item @emph{Arguments}:
6202 @multitable @columnfractions .15 .70
6203 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
6204 default kind, @math{@var{NUMBER} \geq 0}
6205 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
6206 and of default kind.
6207 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6208 and of default kind.
6209 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6210 and of default kind.
6213 @item @emph{Return value}:
6214 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
6215 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
6216 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
6217 arguments specified at the command line, @var{VALUE} will be filled with blanks.
6218 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
6219 systems that support this feature). The @var{LENGTH} argument contains the
6220 length of the @var{NUMBER}-th command line argument. If the argument retrieval
6221 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
6222 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
6225 @item @emph{Example}:
6227 PROGRAM test_get_command_argument
6229 CHARACTER(len=32) :: arg
6233 CALL get_command_argument(i, arg)
6234 IF (LEN_TRIM(arg) == 0) EXIT
6236 WRITE (*,*) TRIM(arg)
6242 @item @emph{See also}:
6243 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
6249 @section @code{GETCWD} --- Get current working directory
6251 @cindex system, working directory
6254 @item @emph{Description}:
6255 Get current working directory.
6257 This intrinsic is provided in both subroutine and function forms; however,
6258 only one form can be used in any given program unit.
6260 @item @emph{Standard}:
6264 Subroutine, function
6266 @item @emph{Syntax}:
6267 @multitable @columnfractions .80
6268 @item @code{CALL GETCWD(C [, STATUS])}
6269 @item @code{STATUS = GETCWD(C)}
6272 @item @emph{Arguments}:
6273 @multitable @columnfractions .15 .70
6274 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
6275 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
6276 a system specific and nonzero error code otherwise.
6279 @item @emph{Example}:
6282 CHARACTER(len=255) :: cwd
6284 WRITE(*,*) TRIM(cwd)
6288 @item @emph{See also}:
6295 @section @code{GETENV} --- Get an environmental variable
6297 @cindex environment variable
6300 @item @emph{Description}:
6301 Get the @var{VALUE} of the environmental variable @var{NAME}.
6303 This intrinsic routine is provided for backwards compatibility with
6304 GNU Fortran 77. In new code, programmers should consider the use of
6305 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
6308 Note that @code{GETENV} need not be thread-safe. It is the
6309 responsibility of the user to ensure that the environment is not being
6310 updated concurrently with a call to the @code{GETENV} intrinsic.
6312 @item @emph{Standard}:
6318 @item @emph{Syntax}:
6319 @code{CALL GETENV(NAME, VALUE)}
6321 @item @emph{Arguments}:
6322 @multitable @columnfractions .15 .70
6323 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
6324 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
6327 @item @emph{Return value}:
6328 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
6329 not large enough to hold the data, it is truncated. If @var{NAME}
6330 is not set, @var{VALUE} will be filled with blanks.
6332 @item @emph{Example}:
6335 CHARACTER(len=255) :: homedir
6336 CALL getenv("HOME", homedir)
6337 WRITE (*,*) TRIM(homedir)
6341 @item @emph{See also}:
6342 @ref{GET_ENVIRONMENT_VARIABLE}
6347 @node GET_ENVIRONMENT_VARIABLE
6348 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
6349 @fnindex GET_ENVIRONMENT_VARIABLE
6350 @cindex environment variable
6353 @item @emph{Description}:
6354 Get the @var{VALUE} of the environmental variable @var{NAME}.
6356 Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It
6357 is the responsibility of the user to ensure that the environment is
6358 not being updated concurrently with a call to the
6359 @code{GET_ENVIRONMENT_VARIABLE} intrinsic.
6361 @item @emph{Standard}:
6362 Fortran 2003 and later
6367 @item @emph{Syntax}:
6368 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
6370 @item @emph{Arguments}:
6371 @multitable @columnfractions .15 .70
6372 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
6373 and of default kind.
6374 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
6375 and of default kind.
6376 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6377 and of default kind.
6378 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6379 and of default kind.
6380 @item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL}
6381 and of default kind.
6384 @item @emph{Return value}:
6385 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
6386 not large enough to hold the data, it is truncated. If @var{NAME}
6387 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
6388 contains the length needed for storing the environment variable @var{NAME}
6389 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
6390 but too short for the environment variable; it is 1 if the environment
6391 variable does not exist and 2 if the processor does not support environment
6392 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
6393 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
6394 are significant; otherwise they are not part of the environment variable
6397 @item @emph{Example}:
6400 CHARACTER(len=255) :: homedir
6401 CALL get_environment_variable("HOME", homedir)
6402 WRITE (*,*) TRIM(homedir)
6410 @section @code{GETGID} --- Group ID function
6412 @cindex system, group ID
6415 @item @emph{Description}:
6416 Returns the numerical group ID of the current process.
6418 @item @emph{Standard}:
6424 @item @emph{Syntax}:
6425 @code{RESULT = GETGID()}
6427 @item @emph{Return value}:
6428 The return value of @code{GETGID} is an @code{INTEGER} of the default
6432 @item @emph{Example}:
6433 See @code{GETPID} for an example.
6435 @item @emph{See also}:
6436 @ref{GETPID}, @ref{GETUID}
6442 @section @code{GETLOG} --- Get login name
6444 @cindex system, login name
6448 @item @emph{Description}:
6449 Gets the username under which the program is running.
6451 @item @emph{Standard}:
6457 @item @emph{Syntax}:
6458 @code{CALL GETLOG(C)}
6460 @item @emph{Arguments}:
6461 @multitable @columnfractions .15 .70
6462 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
6465 @item @emph{Return value}:
6466 Stores the current user name in @var{LOGIN}. (On systems where POSIX
6467 functions @code{geteuid} and @code{getpwuid} are not available, and
6468 the @code{getlogin} function is not implemented either, this will
6469 return a blank string.)
6471 @item @emph{Example}:
6474 CHARACTER(32) :: login
6480 @item @emph{See also}:
6487 @section @code{GETPID} --- Process ID function
6489 @cindex system, process ID
6493 @item @emph{Description}:
6494 Returns the numerical process identifier of the current process.
6496 @item @emph{Standard}:
6502 @item @emph{Syntax}:
6503 @code{RESULT = GETPID()}
6505 @item @emph{Return value}:
6506 The return value of @code{GETPID} is an @code{INTEGER} of the default
6510 @item @emph{Example}:
6513 print *, "The current process ID is ", getpid()
6514 print *, "Your numerical user ID is ", getuid()
6515 print *, "Your numerical group ID is ", getgid()
6519 @item @emph{See also}:
6520 @ref{GETGID}, @ref{GETUID}
6526 @section @code{GETUID} --- User ID function
6528 @cindex system, user ID
6532 @item @emph{Description}:
6533 Returns the numerical user ID of the current process.
6535 @item @emph{Standard}:
6541 @item @emph{Syntax}:
6542 @code{RESULT = GETUID()}
6544 @item @emph{Return value}:
6545 The return value of @code{GETUID} is an @code{INTEGER} of the default
6549 @item @emph{Example}:
6550 See @code{GETPID} for an example.
6552 @item @emph{See also}:
6553 @ref{GETPID}, @ref{GETLOG}
6559 @section @code{GMTIME} --- Convert time to GMT info
6561 @cindex time, conversion to GMT info
6564 @item @emph{Description}:
6565 Given a system time value @var{TIME} (as provided by the @code{TIME8}
6566 intrinsic), fills @var{VALUES} with values extracted from it appropriate
6567 to the UTC time zone (Universal Coordinated Time, also known in some
6568 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
6570 @item @emph{Standard}:
6576 @item @emph{Syntax}:
6577 @code{CALL GMTIME(TIME, VALUES)}
6579 @item @emph{Arguments}:
6580 @multitable @columnfractions .15 .70
6581 @item @var{TIME} @tab An @code{INTEGER} scalar expression
6582 corresponding to a system time, with @code{INTENT(IN)}.
6583 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
6584 with @code{INTENT(OUT)}.
6587 @item @emph{Return value}:
6588 The elements of @var{VALUES} are assigned as follows:
6590 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
6592 @item Minutes after the hour, range 0--59
6593 @item Hours past midnight, range 0--23
6594 @item Day of month, range 0--31
6595 @item Number of months since January, range 0--12
6596 @item Years since 1900
6597 @item Number of days since Sunday, range 0--6
6598 @item Days since January 1
6599 @item Daylight savings indicator: positive if daylight savings is in
6600 effect, zero if not, and negative if the information is not available.
6603 @item @emph{See also}:
6604 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
6611 @section @code{HOSTNM} --- Get system host name
6613 @cindex system, host name
6616 @item @emph{Description}:
6617 Retrieves the host name of the system on which the program is running.
6619 This intrinsic is provided in both subroutine and function forms; however,
6620 only one form can be used in any given program unit.
6622 @item @emph{Standard}:
6626 Subroutine, function
6628 @item @emph{Syntax}:
6629 @multitable @columnfractions .80
6630 @item @code{CALL HOSTNM(C [, STATUS])}
6631 @item @code{STATUS = HOSTNM(NAME)}
6634 @item @emph{Arguments}:
6635 @multitable @columnfractions .15 .70
6636 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
6637 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6638 Returns 0 on success, or a system specific error code otherwise.
6641 @item @emph{Return value}:
6642 In either syntax, @var{NAME} is set to the current hostname if it can
6643 be obtained, or to a blank string otherwise.
6650 @section @code{HUGE} --- Largest number of a kind
6652 @cindex limits, largest number
6653 @cindex model representation, largest number
6656 @item @emph{Description}:
6657 @code{HUGE(X)} returns the largest number that is not an infinity in
6658 the model of the type of @code{X}.
6660 @item @emph{Standard}:
6661 Fortran 95 and later
6666 @item @emph{Syntax}:
6667 @code{RESULT = HUGE(X)}
6669 @item @emph{Arguments}:
6670 @multitable @columnfractions .15 .70
6671 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
6674 @item @emph{Return value}:
6675 The return value is of the same type and kind as @var{X}
6677 @item @emph{Example}:
6679 program test_huge_tiny
6680 print *, huge(0), huge(0.0), huge(0.0d0)
6681 print *, tiny(0.0), tiny(0.0d0)
6682 end program test_huge_tiny
6689 @section @code{HYPOT} --- Euclidean distance function
6691 @cindex Euclidean distance
6694 @item @emph{Description}:
6695 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
6696 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
6698 @item @emph{Standard}:
6699 Fortran 2008 and later
6704 @item @emph{Syntax}:
6705 @code{RESULT = HYPOT(X, Y)}
6707 @item @emph{Arguments}:
6708 @multitable @columnfractions .15 .70
6709 @item @var{X} @tab The type shall be @code{REAL}.
6710 @item @var{Y} @tab The type and kind type parameter shall be the same as
6714 @item @emph{Return value}:
6715 The return value has the same type and kind type parameter as @var{X}.
6717 @item @emph{Example}:
6720 real(4) :: x = 1.e0_4, y = 0.5e0_4
6722 end program test_hypot
6729 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
6731 @cindex @acronym{ASCII} collating sequence
6732 @cindex collating sequence, @acronym{ASCII}
6733 @cindex conversion, to integer
6736 @item @emph{Description}:
6737 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
6738 in the first character position of @code{C}.
6740 @item @emph{Standard}:
6741 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6746 @item @emph{Syntax}:
6747 @code{RESULT = IACHAR(C [, KIND])}
6749 @item @emph{Arguments}:
6750 @multitable @columnfractions .15 .70
6751 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
6752 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6753 expression indicating the kind parameter of the result.
6756 @item @emph{Return value}:
6757 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6758 @var{KIND} is absent, the return value is of default integer kind.
6760 @item @emph{Example}:
6765 end program test_iachar
6769 See @ref{ICHAR} for a discussion of converting between numerical values
6770 and formatted string representations.
6772 @item @emph{See also}:
6773 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
6780 @section @code{IALL} --- Bitwise AND of array elements
6783 @cindex bits, AND of array elements
6786 @item @emph{Description}:
6787 Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
6788 if the corresponding element in @var{MASK} is @code{TRUE}.
6790 @item @emph{Standard}:
6791 Fortran 2008 and later
6794 Transformational function
6796 @item @emph{Syntax}:
6797 @multitable @columnfractions .80
6798 @item @code{RESULT = IALL(ARRAY[, MASK])}
6799 @item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
6802 @item @emph{Arguments}:
6803 @multitable @columnfractions .15 .70
6804 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6805 @item @var{DIM} @tab (Optional) shall be a scalar of type
6806 @code{INTEGER} with a value in the range from 1 to n, where n
6807 equals the rank of @var{ARRAY}.
6808 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
6809 and either be a scalar or an array of the same shape as @var{ARRAY}.
6812 @item @emph{Return value}:
6813 The result is of the same type as @var{ARRAY}.
6815 If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
6816 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6817 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6818 dimension @var{DIM} dropped is returned.
6820 @item @emph{Example}:
6829 PRINT '(b8.8)', IALL(a)
6833 @item @emph{See also}:
6834 @ref{IANY}, @ref{IPARITY}, @ref{IAND}
6840 @section @code{IAND} --- Bitwise logical and
6842 @cindex bitwise logical and
6843 @cindex logical and, bitwise
6846 @item @emph{Description}:
6847 Bitwise logical @code{AND}.
6849 @item @emph{Standard}:
6850 Fortran 95 and later
6855 @item @emph{Syntax}:
6856 @code{RESULT = IAND(I, J)}
6858 @item @emph{Arguments}:
6859 @multitable @columnfractions .15 .70
6860 @item @var{I} @tab The type shall be @code{INTEGER}.
6861 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6862 kind as @var{I}. (As a GNU extension, different kinds are also
6866 @item @emph{Return value}:
6867 The return type is @code{INTEGER}, of the same kind as the
6868 arguments. (If the argument kinds differ, it is of the same kind as
6869 the larger argument.)
6871 @item @emph{Example}:
6875 DATA a / Z'F' /, b / Z'3' /
6876 WRITE (*,*) IAND(a, b)
6880 @item @emph{See also}:
6881 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6888 @section @code{IANY} --- Bitwise OR of array elements
6891 @cindex bits, OR of array elements
6894 @item @emph{Description}:
6895 Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
6896 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
6898 @item @emph{Standard}:
6899 Fortran 2008 and later
6902 Transformational function
6904 @item @emph{Syntax}:
6905 @multitable @columnfractions .80
6906 @item @code{RESULT = IANY(ARRAY[, MASK])}
6907 @item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
6910 @item @emph{Arguments}:
6911 @multitable @columnfractions .15 .70
6912 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6913 @item @var{DIM} @tab (Optional) shall be a scalar of type
6914 @code{INTEGER} with a value in the range from 1 to n, where n
6915 equals the rank of @var{ARRAY}.
6916 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
6917 and either be a scalar or an array of the same shape as @var{ARRAY}.
6920 @item @emph{Return value}:
6921 The result is of the same type as @var{ARRAY}.
6923 If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
6924 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6925 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6926 dimension @var{DIM} dropped is returned.
6928 @item @emph{Example}:
6937 PRINT '(b8.8)', IANY(a)
6941 @item @emph{See also}:
6942 @ref{IPARITY}, @ref{IALL}, @ref{IOR}
6948 @section @code{IARGC} --- Get the number of command line arguments
6950 @cindex command-line arguments
6951 @cindex command-line arguments, number of
6952 @cindex arguments, to program
6955 @item @emph{Description}:
6956 @code{IARGC} returns the number of arguments passed on the
6957 command line when the containing program was invoked.
6959 This intrinsic routine is provided for backwards compatibility with
6960 GNU Fortran 77. In new code, programmers should consider the use of
6961 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
6964 @item @emph{Standard}:
6970 @item @emph{Syntax}:
6971 @code{RESULT = IARGC()}
6973 @item @emph{Arguments}:
6976 @item @emph{Return value}:
6977 The number of command line arguments, type @code{INTEGER(4)}.
6979 @item @emph{Example}:
6982 @item @emph{See also}:
6983 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
6985 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
6986 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6992 @section @code{IBCLR} --- Clear bit
6998 @item @emph{Description}:
6999 @code{IBCLR} returns the value of @var{I} with the bit at position
7000 @var{POS} set to zero.
7002 @item @emph{Standard}:
7003 Fortran 95 and later
7008 @item @emph{Syntax}:
7009 @code{RESULT = IBCLR(I, POS)}
7011 @item @emph{Arguments}:
7012 @multitable @columnfractions .15 .70
7013 @item @var{I} @tab The type shall be @code{INTEGER}.
7014 @item @var{POS} @tab The type shall be @code{INTEGER}.
7017 @item @emph{Return value}:
7018 The return value is of type @code{INTEGER} and of the same kind as
7021 @item @emph{See also}:
7022 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
7029 @section @code{IBITS} --- Bit extraction
7032 @cindex bits, extract
7035 @item @emph{Description}:
7036 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
7037 starting from bit position @var{POS} and extending left for @var{LEN}
7038 bits. The result is right-justified and the remaining bits are
7039 zeroed. The value of @code{POS+LEN} must be less than or equal to the
7040 value @code{BIT_SIZE(I)}.
7042 @item @emph{Standard}:
7043 Fortran 95 and later
7048 @item @emph{Syntax}:
7049 @code{RESULT = IBITS(I, POS, LEN)}
7051 @item @emph{Arguments}:
7052 @multitable @columnfractions .15 .70
7053 @item @var{I} @tab The type shall be @code{INTEGER}.
7054 @item @var{POS} @tab The type shall be @code{INTEGER}.
7055 @item @var{LEN} @tab The type shall be @code{INTEGER}.
7058 @item @emph{Return value}:
7059 The return value is of type @code{INTEGER} and of the same kind as
7062 @item @emph{See also}:
7063 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
7069 @section @code{IBSET} --- Set bit
7074 @item @emph{Description}:
7075 @code{IBSET} returns the value of @var{I} with the bit at position
7076 @var{POS} set to one.
7078 @item @emph{Standard}:
7079 Fortran 95 and later
7084 @item @emph{Syntax}:
7085 @code{RESULT = IBSET(I, POS)}
7087 @item @emph{Arguments}:
7088 @multitable @columnfractions .15 .70
7089 @item @var{I} @tab The type shall be @code{INTEGER}.
7090 @item @var{POS} @tab The type shall be @code{INTEGER}.
7093 @item @emph{Return value}:
7094 The return value is of type @code{INTEGER} and of the same kind as
7097 @item @emph{See also}:
7098 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
7105 @section @code{ICHAR} --- Character-to-integer conversion function
7107 @cindex conversion, to integer
7110 @item @emph{Description}:
7111 @code{ICHAR(C)} returns the code for the character in the first character
7112 position of @code{C} in the system's native character set.
7113 The correspondence between characters and their codes is not necessarily
7114 the same across different GNU Fortran implementations.
7116 @item @emph{Standard}:
7117 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7122 @item @emph{Syntax}:
7123 @code{RESULT = ICHAR(C [, KIND])}
7125 @item @emph{Arguments}:
7126 @multitable @columnfractions .15 .70
7127 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
7128 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7129 expression indicating the kind parameter of the result.
7132 @item @emph{Return value}:
7133 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7134 @var{KIND} is absent, the return value is of default integer kind.
7136 @item @emph{Example}:
7141 end program test_ichar
7144 @item @emph{Specific names}:
7145 @multitable @columnfractions .20 .20 .20 .25
7146 @item Name @tab Argument @tab Return type @tab Standard
7147 @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7151 No intrinsic exists to convert between a numeric value and a formatted
7152 character string representation -- for instance, given the
7153 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
7154 @code{REAL} value with the value 154, or vice versa. Instead, this
7155 functionality is provided by internal-file I/O, as in the following
7160 character(len=10) string, string2
7163 ! Convert a string to a numeric value
7164 read (string,'(I10)') value
7167 ! Convert a value to a formatted string
7168 write (string2,'(I10)') value
7170 end program read_val
7173 @item @emph{See also}:
7174 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
7181 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
7183 @cindex date, current
7184 @cindex current date
7187 @item @emph{Description}:
7188 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
7189 current local time. The day (in the range 1-31), month (in the range 1-12),
7190 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
7191 The year has four significant digits.
7193 @item @emph{Standard}:
7199 @item @emph{Syntax}:
7200 @code{CALL IDATE(VALUES)}
7202 @item @emph{Arguments}:
7203 @multitable @columnfractions .15 .70
7204 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
7205 the kind shall be the default integer kind.
7208 @item @emph{Return value}:
7209 Does not return anything.
7211 @item @emph{Example}:
7214 integer, dimension(3) :: tarray
7219 end program test_idate
7226 @section @code{IEOR} --- Bitwise logical exclusive or
7228 @cindex bitwise logical exclusive or
7229 @cindex logical exclusive or, bitwise
7232 @item @emph{Description}:
7233 @code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
7236 @item @emph{Standard}:
7237 Fortran 95 and later
7242 @item @emph{Syntax}:
7243 @code{RESULT = IEOR(I, J)}
7245 @item @emph{Arguments}:
7246 @multitable @columnfractions .15 .70
7247 @item @var{I} @tab The type shall be @code{INTEGER}.
7248 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
7249 kind as @var{I}. (As a GNU extension, different kinds are also
7253 @item @emph{Return value}:
7254 The return type is @code{INTEGER}, of the same kind as the
7255 arguments. (If the argument kinds differ, it is of the same kind as
7256 the larger argument.)
7258 @item @emph{See also}:
7259 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
7265 @section @code{IERRNO} --- Get the last system error number
7267 @cindex system, error handling
7270 @item @emph{Description}:
7271 Returns the last system error number, as given by the C @code{errno}
7274 @item @emph{Standard}:
7280 @item @emph{Syntax}:
7281 @code{RESULT = IERRNO()}
7283 @item @emph{Arguments}:
7286 @item @emph{Return value}:
7287 The return value is of type @code{INTEGER} and of the default integer
7290 @item @emph{See also}:
7297 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
7298 @fnindex IMAGE_INDEX
7299 @cindex coarray, @code{IMAGE_INDEX}
7300 @cindex images, cosubscript to image index conversion
7303 @item @emph{Description}:
7304 Returns the image index belonging to a cosubscript.
7306 @item @emph{Standard}:
7307 Fortran 2008 and later
7312 @item @emph{Syntax}:
7313 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
7315 @item @emph{Arguments}: None.
7316 @multitable @columnfractions .15 .70
7317 @item @var{COARRAY} @tab Coarray of any type.
7318 @item @var{SUB} @tab default integer rank-1 array of a size equal to
7319 the corank of @var{COARRAY}.
7323 @item @emph{Return value}:
7324 Scalar default integer with the value of the image index which corresponds
7325 to the cosubscripts. For invalid cosubscripts the result is zero.
7327 @item @emph{Example}:
7329 INTEGER :: array[2,-1:4,8,*]
7330 ! Writes 28 (or 0 if there are fewer than 28 images)
7331 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
7334 @item @emph{See also}:
7335 @ref{THIS_IMAGE}, @ref{NUM_IMAGES}
7340 @node INDEX intrinsic
7341 @section @code{INDEX} --- Position of a substring within a string
7343 @cindex substring position
7344 @cindex string, find substring
7347 @item @emph{Description}:
7348 Returns the position of the start of the first occurrence of string
7349 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
7350 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
7351 the @var{BACK} argument is present and true, the return value is the
7352 start of the last occurrence rather than the first.
7354 @item @emph{Standard}:
7355 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
7360 @item @emph{Syntax}:
7361 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
7363 @item @emph{Arguments}:
7364 @multitable @columnfractions .15 .70
7365 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
7367 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
7369 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
7371 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7372 expression indicating the kind parameter of the result.
7375 @item @emph{Return value}:
7376 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7377 @var{KIND} is absent, the return value is of default integer kind.
7379 @item @emph{Specific names}:
7380 @multitable @columnfractions .20 .20 .20 .25
7381 @item Name @tab Argument @tab Return type @tab Standard
7382 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7385 @item @emph{See also}:
7386 @ref{SCAN}, @ref{VERIFY}
7392 @section @code{INT} --- Convert to integer type
7396 @cindex conversion, to integer
7399 @item @emph{Description}:
7400 Convert to integer type
7402 @item @emph{Standard}:
7403 Fortran 77 and later
7408 @item @emph{Syntax}:
7409 @code{RESULT = INT(A [, KIND))}
7411 @item @emph{Arguments}:
7412 @multitable @columnfractions .15 .70
7413 @item @var{A} @tab Shall be of type @code{INTEGER},
7414 @code{REAL}, or @code{COMPLEX}.
7415 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7416 expression indicating the kind parameter of the result.
7419 @item @emph{Return value}:
7420 These functions return a @code{INTEGER} variable or array under
7421 the following rules:
7425 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
7427 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)}
7428 equals @code{0}. If @math{|A| \geq 1}, then @code{INT(A)} is the integer
7429 whose magnitude is the largest integer that does not exceed the magnitude
7430 of @var{A} and whose sign is the same as the sign of @var{A}.
7432 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
7435 @item @emph{Example}:
7439 complex :: z = (-3.7, 1.0)
7441 print *, int(z), int(z,8)
7445 @item @emph{Specific names}:
7446 @multitable @columnfractions .20 .20 .20 .25
7447 @item Name @tab Argument @tab Return type @tab Standard
7448 @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
7449 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
7450 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
7457 @section @code{INT2} --- Convert to 16-bit integer type
7460 @cindex conversion, to integer
7463 @item @emph{Description}:
7464 Convert to a @code{KIND=2} integer type. This is equivalent to the
7465 standard @code{INT} intrinsic with an optional argument of
7466 @code{KIND=2}, and is only included for backwards compatibility.
7468 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
7470 @item @emph{Standard}:
7476 @item @emph{Syntax}:
7477 @code{RESULT = INT2(A)}
7479 @item @emph{Arguments}:
7480 @multitable @columnfractions .15 .70
7481 @item @var{A} @tab Shall be of type @code{INTEGER},
7482 @code{REAL}, or @code{COMPLEX}.
7485 @item @emph{Return value}:
7486 The return value is a @code{INTEGER(2)} variable.
7488 @item @emph{See also}:
7489 @ref{INT}, @ref{INT8}, @ref{LONG}
7495 @section @code{INT8} --- Convert to 64-bit integer type
7497 @cindex conversion, to integer
7500 @item @emph{Description}:
7501 Convert to a @code{KIND=8} integer type. This is equivalent to the
7502 standard @code{INT} intrinsic with an optional argument of
7503 @code{KIND=8}, and is only included for backwards compatibility.
7505 @item @emph{Standard}:
7511 @item @emph{Syntax}:
7512 @code{RESULT = INT8(A)}
7514 @item @emph{Arguments}:
7515 @multitable @columnfractions .15 .70
7516 @item @var{A} @tab Shall be of type @code{INTEGER},
7517 @code{REAL}, or @code{COMPLEX}.
7520 @item @emph{Return value}:
7521 The return value is a @code{INTEGER(8)} variable.
7523 @item @emph{See also}:
7524 @ref{INT}, @ref{INT2}, @ref{LONG}
7530 @section @code{IOR} --- Bitwise logical or
7532 @cindex bitwise logical or
7533 @cindex logical or, bitwise
7536 @item @emph{Description}:
7537 @code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
7540 @item @emph{Standard}:
7541 Fortran 95 and later
7546 @item @emph{Syntax}:
7547 @code{RESULT = IOR(I, J)}
7549 @item @emph{Arguments}:
7550 @multitable @columnfractions .15 .70
7551 @item @var{I} @tab The type shall be @code{INTEGER}.
7552 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
7553 kind as @var{I}. (As a GNU extension, different kinds are also
7557 @item @emph{Return value}:
7558 The return type is @code{INTEGER}, of the same kind as the
7559 arguments. (If the argument kinds differ, it is of the same kind as
7560 the larger argument.)
7562 @item @emph{See also}:
7563 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
7569 @section @code{IPARITY} --- Bitwise XOR of array elements
7571 @cindex array, parity
7573 @cindex bits, XOR of array elements
7576 @item @emph{Description}:
7577 Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
7578 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
7580 @item @emph{Standard}:
7581 Fortran 2008 and later
7584 Transformational function
7586 @item @emph{Syntax}:
7587 @multitable @columnfractions .80
7588 @item @code{RESULT = IPARITY(ARRAY[, MASK])}
7589 @item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
7592 @item @emph{Arguments}:
7593 @multitable @columnfractions .15 .70
7594 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7595 @item @var{DIM} @tab (Optional) shall be a scalar of type
7596 @code{INTEGER} with a value in the range from 1 to n, where n
7597 equals the rank of @var{ARRAY}.
7598 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
7599 and either be a scalar or an array of the same shape as @var{ARRAY}.
7602 @item @emph{Return value}:
7603 The result is of the same type as @var{ARRAY}.
7605 If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
7606 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7607 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7608 dimension @var{DIM} dropped is returned.
7610 @item @emph{Example}:
7612 PROGRAM test_iparity
7619 PRINT '(b8.8)', IPARITY(a)
7623 @item @emph{See also}:
7624 @ref{IANY}, @ref{IALL}, @ref{IEOR}, @ref{PARITY}
7630 @section @code{IRAND} --- Integer pseudo-random number
7632 @cindex random number generation
7635 @item @emph{Description}:
7636 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
7637 distribution between 0 and a system-dependent limit (which is in most
7638 cases 2147483647). If @var{FLAG} is 0, the next number
7639 in the current sequence is returned; if @var{FLAG} is 1, the generator
7640 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
7641 it is used as a new seed with @code{SRAND}.
7643 This intrinsic routine is provided for backwards compatibility with
7644 GNU Fortran 77. It implements a simple modulo generator as provided
7645 by @command{g77}. For new code, one should consider the use of
7646 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
7648 @item @emph{Standard}:
7654 @item @emph{Syntax}:
7655 @code{RESULT = IRAND(I)}
7657 @item @emph{Arguments}:
7658 @multitable @columnfractions .15 .70
7659 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
7662 @item @emph{Return value}:
7663 The return value is of @code{INTEGER(kind=4)} type.
7665 @item @emph{Example}:
7668 integer,parameter :: seed = 86456
7671 print *, irand(), irand(), irand(), irand()
7672 print *, irand(seed), irand(), irand(), irand()
7673 end program test_irand
7681 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
7682 @fnindex IS_IOSTAT_END
7683 @cindex @code{IOSTAT}, end of file
7686 @item @emph{Description}:
7687 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
7688 status ``end of file''. The function is equivalent to comparing the variable
7689 with the @code{IOSTAT_END} parameter of the intrinsic module
7690 @code{ISO_FORTRAN_ENV}.
7692 @item @emph{Standard}:
7693 Fortran 2003 and later
7698 @item @emph{Syntax}:
7699 @code{RESULT = IS_IOSTAT_END(I)}
7701 @item @emph{Arguments}:
7702 @multitable @columnfractions .15 .70
7703 @item @var{I} @tab Shall be of the type @code{INTEGER}.
7706 @item @emph{Return value}:
7707 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
7708 @var{I} has the value which indicates an end of file condition for
7709 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
7711 @item @emph{Example}:
7716 OPEN(88, FILE='test.dat')
7717 READ(88, *, IOSTAT=stat) i
7718 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
7726 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
7727 @fnindex IS_IOSTAT_EOR
7728 @cindex @code{IOSTAT}, end of record
7731 @item @emph{Description}:
7732 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
7733 status ``end of record''. The function is equivalent to comparing the
7734 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
7735 @code{ISO_FORTRAN_ENV}.
7737 @item @emph{Standard}:
7738 Fortran 2003 and later
7743 @item @emph{Syntax}:
7744 @code{RESULT = IS_IOSTAT_EOR(I)}
7746 @item @emph{Arguments}:
7747 @multitable @columnfractions .15 .70
7748 @item @var{I} @tab Shall be of the type @code{INTEGER}.
7751 @item @emph{Return value}:
7752 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
7753 @var{I} has the value which indicates an end of file condition for
7754 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
7756 @item @emph{Example}:
7760 INTEGER :: stat, i(50)
7761 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
7762 READ(88, IOSTAT=stat) i
7763 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
7771 @section @code{ISATTY} --- Whether a unit is a terminal device.
7773 @cindex system, terminal
7776 @item @emph{Description}:
7777 Determine whether a unit is connected to a terminal device.
7779 @item @emph{Standard}:
7785 @item @emph{Syntax}:
7786 @code{RESULT = ISATTY(UNIT)}
7788 @item @emph{Arguments}:
7789 @multitable @columnfractions .15 .70
7790 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
7793 @item @emph{Return value}:
7794 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
7795 device, @code{.FALSE.} otherwise.
7797 @item @emph{Example}:
7800 INTEGER(kind=1) :: unit
7802 write(*,*) isatty(unit=unit)
7806 @item @emph{See also}:
7813 @section @code{ISHFT} --- Shift bits
7818 @item @emph{Description}:
7819 @code{ISHFT} returns a value corresponding to @var{I} with all of the
7820 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
7821 zero corresponds to a left shift, a value of zero corresponds to no
7822 shift, and a value less than zero corresponds to a right shift. If the
7823 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
7824 value is undefined. Bits shifted out from the left end or right end are
7825 lost; zeros are shifted in from the opposite end.
7827 @item @emph{Standard}:
7828 Fortran 95 and later
7833 @item @emph{Syntax}:
7834 @code{RESULT = ISHFT(I, SHIFT)}
7836 @item @emph{Arguments}:
7837 @multitable @columnfractions .15 .70
7838 @item @var{I} @tab The type shall be @code{INTEGER}.
7839 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7842 @item @emph{Return value}:
7843 The return value is of type @code{INTEGER} and of the same kind as
7846 @item @emph{See also}:
7853 @section @code{ISHFTC} --- Shift bits circularly
7855 @cindex bits, shift circular
7858 @item @emph{Description}:
7859 @code{ISHFTC} returns a value corresponding to @var{I} with the
7860 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
7861 is, bits shifted out one end are shifted into the opposite end. A value
7862 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
7863 zero corresponds to no shift, and a value less than zero corresponds to
7864 a right shift. The absolute value of @var{SHIFT} must be less than
7865 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
7866 equivalent to @code{BIT_SIZE(I)}.
7868 @item @emph{Standard}:
7869 Fortran 95 and later
7874 @item @emph{Syntax}:
7875 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
7877 @item @emph{Arguments}:
7878 @multitable @columnfractions .15 .70
7879 @item @var{I} @tab The type shall be @code{INTEGER}.
7880 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7881 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
7882 the value must be greater than zero and less than or equal to
7886 @item @emph{Return value}:
7887 The return value is of type @code{INTEGER} and of the same kind as
7890 @item @emph{See also}:
7897 @section @code{ISNAN} --- Test for a NaN
7902 @item @emph{Description}:
7903 @code{ISNAN} tests whether a floating-point value is an IEEE
7905 @item @emph{Standard}:
7911 @item @emph{Syntax}:
7914 @item @emph{Arguments}:
7915 @multitable @columnfractions .15 .70
7916 @item @var{X} @tab Variable of the type @code{REAL}.
7920 @item @emph{Return value}:
7921 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
7922 if @var{X} is a NaN and @code{FALSE} otherwise.
7924 @item @emph{Example}:
7931 if (isnan(x)) stop '"x" is a NaN'
7932 end program test_nan
7939 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
7941 @cindex time, current
7942 @cindex current time
7945 @item @emph{Description}:
7946 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
7947 current local time. The hour (in the range 1-24), minute (in the range 1-60),
7948 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
7951 @item @emph{Standard}:
7957 @item @emph{Syntax}:
7958 @code{CALL ITIME(VALUES)}
7960 @item @emph{Arguments}:
7961 @multitable @columnfractions .15 .70
7962 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
7963 and the kind shall be the default integer kind.
7966 @item @emph{Return value}:
7967 Does not return anything.
7970 @item @emph{Example}:
7973 integer, dimension(3) :: tarray
7978 end program test_itime
7985 @section @code{KILL} --- Send a signal to a process
7989 @item @emph{Description}:
7990 @item @emph{Standard}:
7991 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
7994 This intrinsic is provided in both subroutine and function forms; however,
7995 only one form can be used in any given program unit.
7998 Subroutine, function
8000 @item @emph{Syntax}:
8001 @multitable @columnfractions .80
8002 @item @code{CALL KILL(C, VALUE [, STATUS])}
8003 @item @code{STATUS = KILL(C, VALUE)}
8006 @item @emph{Arguments}:
8007 @multitable @columnfractions .15 .70
8008 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
8010 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
8012 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
8013 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
8017 @item @emph{See also}:
8018 @ref{ABORT}, @ref{EXIT}
8024 @section @code{KIND} --- Kind of an entity
8029 @item @emph{Description}:
8030 @code{KIND(X)} returns the kind value of the entity @var{X}.
8032 @item @emph{Standard}:
8033 Fortran 95 and later
8038 @item @emph{Syntax}:
8041 @item @emph{Arguments}:
8042 @multitable @columnfractions .15 .70
8043 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
8044 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
8047 @item @emph{Return value}:
8048 The return value is a scalar of type @code{INTEGER} and of the default
8051 @item @emph{Example}:
8054 integer,parameter :: kc = kind(' ')
8055 integer,parameter :: kl = kind(.true.)
8057 print *, "The default character kind is ", kc
8058 print *, "The default logical kind is ", kl
8059 end program test_kind
8067 @section @code{LBOUND} --- Lower dimension bounds of an array
8069 @cindex array, lower bound
8072 @item @emph{Description}:
8073 Returns the lower bounds of an array, or a single lower bound
8074 along the @var{DIM} dimension.
8075 @item @emph{Standard}:
8076 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
8081 @item @emph{Syntax}:
8082 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
8084 @item @emph{Arguments}:
8085 @multitable @columnfractions .15 .70
8086 @item @var{ARRAY} @tab Shall be an array, of any type.
8087 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
8088 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8089 expression indicating the kind parameter of the result.
8092 @item @emph{Return value}:
8093 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8094 @var{KIND} is absent, the return value is of default integer kind.
8095 If @var{DIM} is absent, the result is an array of the lower bounds of
8096 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
8097 corresponding to the lower bound of the array along that dimension. If
8098 @var{ARRAY} is an expression rather than a whole array or array
8099 structure component, or if it has a zero extent along the relevant
8100 dimension, the lower bound is taken to be 1.
8102 @item @emph{See also}:
8103 @ref{UBOUND}, @ref{LCOBOUND}
8109 @section @code{LCOBOUND} --- Lower codimension bounds of an array
8111 @cindex coarray, lower bound
8114 @item @emph{Description}:
8115 Returns the lower bounds of a coarray, or a single lower cobound
8116 along the @var{DIM} codimension.
8117 @item @emph{Standard}:
8118 Fortran 2008 and later
8123 @item @emph{Syntax}:
8124 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
8126 @item @emph{Arguments}:
8127 @multitable @columnfractions .15 .70
8128 @item @var{ARRAY} @tab Shall be an coarray, of any type.
8129 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
8130 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8131 expression indicating the kind parameter of the result.
8134 @item @emph{Return value}:
8135 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8136 @var{KIND} is absent, the return value is of default integer kind.
8137 If @var{DIM} is absent, the result is an array of the lower cobounds of
8138 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
8139 corresponding to the lower cobound of the array along that codimension.
8141 @item @emph{See also}:
8142 @ref{UCOBOUND}, @ref{LBOUND}
8148 @section @code{LEADZ} --- Number of leading zero bits of an integer
8153 @item @emph{Description}:
8154 @code{LEADZ} returns the number of leading zero bits of an integer.
8156 @item @emph{Standard}:
8157 Fortran 2008 and later
8162 @item @emph{Syntax}:
8163 @code{RESULT = LEADZ(I)}
8165 @item @emph{Arguments}:
8166 @multitable @columnfractions .15 .70
8167 @item @var{I} @tab Shall be of type @code{INTEGER}.
8170 @item @emph{Return value}:
8171 The type of the return value is the default @code{INTEGER}.
8172 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
8174 @item @emph{Example}:
8177 WRITE (*,*) BIT_SIZE(1) ! prints 32
8178 WRITE (*,*) LEADZ(1) ! prints 31
8182 @item @emph{See also}:
8183 @ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR}
8189 @section @code{LEN} --- Length of a character entity
8191 @cindex string, length
8194 @item @emph{Description}:
8195 Returns the length of a character string. If @var{STRING} is an array,
8196 the length of an element of @var{STRING} is returned. Note that
8197 @var{STRING} need not be defined when this intrinsic is invoked, since
8198 only the length, not the content, of @var{STRING} is needed.
8200 @item @emph{Standard}:
8201 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
8206 @item @emph{Syntax}:
8207 @code{L = LEN(STRING [, KIND])}
8209 @item @emph{Arguments}:
8210 @multitable @columnfractions .15 .70
8211 @item @var{STRING} @tab Shall be a scalar or array of type
8212 @code{CHARACTER}, with @code{INTENT(IN)}
8213 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8214 expression indicating the kind parameter of the result.
8217 @item @emph{Return value}:
8218 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8219 @var{KIND} is absent, the return value is of default integer kind.
8222 @item @emph{Specific names}:
8223 @multitable @columnfractions .20 .20 .20 .25
8224 @item Name @tab Argument @tab Return type @tab Standard
8225 @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
8229 @item @emph{See also}:
8230 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
8236 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
8238 @cindex string, length, without trailing whitespace
8241 @item @emph{Description}:
8242 Returns the length of a character string, ignoring any trailing blanks.
8244 @item @emph{Standard}:
8245 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
8250 @item @emph{Syntax}:
8251 @code{RESULT = LEN_TRIM(STRING [, KIND])}
8253 @item @emph{Arguments}:
8254 @multitable @columnfractions .15 .70
8255 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
8256 with @code{INTENT(IN)}
8257 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8258 expression indicating the kind parameter of the result.
8261 @item @emph{Return value}:
8262 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8263 @var{KIND} is absent, the return value is of default integer kind.
8265 @item @emph{See also}:
8266 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
8272 @section @code{LGE} --- Lexical greater than or equal
8274 @cindex lexical comparison of strings
8275 @cindex string, comparison
8278 @item @emph{Description}:
8279 Determines whether one string is lexically greater than or equal to
8280 another string, where the two strings are interpreted as containing
8281 ASCII character codes. If the String A and String B are not the same
8282 length, the shorter is compared as if spaces were appended to it to form
8283 a value that has the same length as the longer.
8285 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
8286 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
8287 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
8288 that the latter use the processor's character ordering (which is not
8289 ASCII on some targets), whereas the former always use the ASCII
8292 @item @emph{Standard}:
8293 Fortran 77 and later
8298 @item @emph{Syntax}:
8299 @code{RESULT = LGE(STRING_A, STRING_B)}
8301 @item @emph{Arguments}:
8302 @multitable @columnfractions .15 .70
8303 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
8304 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
8307 @item @emph{Return value}:
8308 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
8309 otherwise, based on the ASCII ordering.
8311 @item @emph{Specific names}:
8312 @multitable @columnfractions .20 .20 .20 .25
8313 @item Name @tab Argument @tab Return type @tab Standard
8314 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
8317 @item @emph{See also}:
8318 @ref{LGT}, @ref{LLE}, @ref{LLT}
8324 @section @code{LGT} --- Lexical greater than
8326 @cindex lexical comparison of strings
8327 @cindex string, comparison
8330 @item @emph{Description}:
8331 Determines whether one string is lexically greater than another string,
8332 where the two strings are interpreted as containing ASCII character
8333 codes. If the String A and String B are not the same length, the
8334 shorter is compared as if spaces were appended to it to form a value
8335 that has the same length as the longer.
8337 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
8338 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
8339 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
8340 that the latter use the processor's character ordering (which is not
8341 ASCII on some targets), whereas the former always use the ASCII
8344 @item @emph{Standard}:
8345 Fortran 77 and later
8350 @item @emph{Syntax}:
8351 @code{RESULT = LGT(STRING_A, STRING_B)}
8353 @item @emph{Arguments}:
8354 @multitable @columnfractions .15 .70
8355 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
8356 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
8359 @item @emph{Return value}:
8360 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
8361 otherwise, based on the ASCII ordering.
8363 @item @emph{Specific names}:
8364 @multitable @columnfractions .20 .20 .20 .25
8365 @item Name @tab Argument @tab Return type @tab Standard
8366 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
8369 @item @emph{See also}:
8370 @ref{LGE}, @ref{LLE}, @ref{LLT}
8376 @section @code{LINK} --- Create a hard link
8378 @cindex file system, create link
8379 @cindex file system, hard link
8382 @item @emph{Description}:
8383 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
8384 character (@code{CHAR(0)}) can be used to mark the end of the names in
8385 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
8386 names are ignored. If the @var{STATUS} argument is supplied, it
8387 contains 0 on success or a nonzero error code upon return; see
8390 This intrinsic is provided in both subroutine and function forms;
8391 however, only one form can be used in any given program unit.
8393 @item @emph{Standard}:
8397 Subroutine, function
8399 @item @emph{Syntax}:
8400 @multitable @columnfractions .80
8401 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
8402 @item @code{STATUS = LINK(PATH1, PATH2)}
8405 @item @emph{Arguments}:
8406 @multitable @columnfractions .15 .70
8407 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
8408 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
8409 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
8412 @item @emph{See also}:
8413 @ref{SYMLNK}, @ref{UNLINK}
8419 @section @code{LLE} --- Lexical less than or equal
8421 @cindex lexical comparison of strings
8422 @cindex string, comparison
8425 @item @emph{Description}:
8426 Determines whether one string is lexically less than or equal to another
8427 string, where the two strings are interpreted as containing ASCII
8428 character codes. If the String A and String B are not the same length,
8429 the shorter is compared as if spaces were appended to it to form a value
8430 that has the same length as the longer.
8432 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
8433 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
8434 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
8435 that the latter use the processor's character ordering (which is not
8436 ASCII on some targets), whereas the former always use the ASCII
8439 @item @emph{Standard}:
8440 Fortran 77 and later
8445 @item @emph{Syntax}:
8446 @code{RESULT = LLE(STRING_A, STRING_B)}
8448 @item @emph{Arguments}:
8449 @multitable @columnfractions .15 .70
8450 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
8451 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
8454 @item @emph{Return value}:
8455 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
8456 otherwise, based on the ASCII ordering.
8458 @item @emph{Specific names}:
8459 @multitable @columnfractions .20 .20 .20 .25
8460 @item Name @tab Argument @tab Return type @tab Standard
8461 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
8464 @item @emph{See also}:
8465 @ref{LGE}, @ref{LGT}, @ref{LLT}
8471 @section @code{LLT} --- Lexical less than
8473 @cindex lexical comparison of strings
8474 @cindex string, comparison
8477 @item @emph{Description}:
8478 Determines whether one string is lexically less than another string,
8479 where the two strings are interpreted as containing ASCII character
8480 codes. If the String A and String B are not the same length, the
8481 shorter is compared as if spaces were appended to it to form a value
8482 that has the same length as the longer.
8484 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
8485 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
8486 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
8487 that the latter use the processor's character ordering (which is not
8488 ASCII on some targets), whereas the former always use the ASCII
8491 @item @emph{Standard}:
8492 Fortran 77 and later
8497 @item @emph{Syntax}:
8498 @code{RESULT = LLT(STRING_A, STRING_B)}
8500 @item @emph{Arguments}:
8501 @multitable @columnfractions .15 .70
8502 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
8503 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
8506 @item @emph{Return value}:
8507 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
8508 otherwise, based on the ASCII ordering.
8510 @item @emph{Specific names}:
8511 @multitable @columnfractions .20 .20 .20 .25
8512 @item Name @tab Argument @tab Return type @tab Standard
8513 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
8516 @item @emph{See also}:
8517 @ref{LGE}, @ref{LGT}, @ref{LLE}
8523 @section @code{LNBLNK} --- Index of the last non-blank character in a string
8525 @cindex string, find non-blank character
8528 @item @emph{Description}:
8529 Returns the length of a character string, ignoring any trailing blanks.
8530 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
8531 included for backwards compatibility.
8533 @item @emph{Standard}:
8539 @item @emph{Syntax}:
8540 @code{RESULT = LNBLNK(STRING)}
8542 @item @emph{Arguments}:
8543 @multitable @columnfractions .15 .70
8544 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
8545 with @code{INTENT(IN)}
8548 @item @emph{Return value}:
8549 The return value is of @code{INTEGER(kind=4)} type.
8551 @item @emph{See also}:
8552 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
8558 @section @code{LOC} --- Returns the address of a variable
8560 @cindex location of a variable in memory
8563 @item @emph{Description}:
8564 @code{LOC(X)} returns the address of @var{X} as an integer.
8566 @item @emph{Standard}:
8572 @item @emph{Syntax}:
8573 @code{RESULT = LOC(X)}
8575 @item @emph{Arguments}:
8576 @multitable @columnfractions .15 .70
8577 @item @var{X} @tab Variable of any type.
8580 @item @emph{Return value}:
8581 The return value is of type @code{INTEGER}, with a @code{KIND}
8582 corresponding to the size (in bytes) of a memory address on the target
8585 @item @emph{Example}:
8592 end program test_loc
8599 @section @code{LOG} --- Natural logarithm function
8606 @cindex exponential function, inverse
8607 @cindex logarithm function
8608 @cindex natural logarithm function
8611 @item @emph{Description}:
8612 @code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the
8613 logarithm to the base @math{e}.
8615 @item @emph{Standard}:
8616 Fortran 77 and later
8621 @item @emph{Syntax}:
8622 @code{RESULT = LOG(X)}
8624 @item @emph{Arguments}:
8625 @multitable @columnfractions .15 .70
8626 @item @var{X} @tab The type shall be @code{REAL} or
8630 @item @emph{Return value}:
8631 The return value is of type @code{REAL} or @code{COMPLEX}.
8632 The kind type parameter is the same as @var{X}.
8633 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
8634 @math{-\pi \leq \omega \leq \pi}.
8636 @item @emph{Example}:
8639 real(8) :: x = 2.7182818284590451_8
8640 complex :: z = (1.0, 2.0)
8641 x = log(x) ! will yield (approximately) 1
8643 end program test_log
8646 @item @emph{Specific names}:
8647 @multitable @columnfractions .20 .20 .20 .25
8648 @item Name @tab Argument @tab Return type @tab Standard
8649 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
8650 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
8651 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
8652 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
8653 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
8660 @section @code{LOG10} --- Base 10 logarithm function
8664 @cindex exponential function, inverse
8665 @cindex logarithm function with base 10
8666 @cindex base 10 logarithm function
8669 @item @emph{Description}:
8670 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
8672 @item @emph{Standard}:
8673 Fortran 77 and later
8678 @item @emph{Syntax}:
8679 @code{RESULT = LOG10(X)}
8681 @item @emph{Arguments}:
8682 @multitable @columnfractions .15 .70
8683 @item @var{X} @tab The type shall be @code{REAL}.
8686 @item @emph{Return value}:
8687 The return value is of type @code{REAL} or @code{COMPLEX}.
8688 The kind type parameter is the same as @var{X}.
8690 @item @emph{Example}:
8693 real(8) :: x = 10.0_8
8695 end program test_log10
8698 @item @emph{Specific names}:
8699 @multitable @columnfractions .20 .20 .20 .25
8700 @item Name @tab Argument @tab Return type @tab Standard
8701 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
8702 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
8709 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
8714 @cindex Gamma function, logarithm of
8717 @item @emph{Description}:
8718 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
8719 of the Gamma (@math{\Gamma}) function.
8721 @item @emph{Standard}:
8722 Fortran 2008 and later
8727 @item @emph{Syntax}:
8728 @code{X = LOG_GAMMA(X)}
8730 @item @emph{Arguments}:
8731 @multitable @columnfractions .15 .70
8732 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
8733 nor a negative integer.
8736 @item @emph{Return value}:
8737 The return value is of type @code{REAL} of the same kind as @var{X}.
8739 @item @emph{Example}:
8741 program test_log_gamma
8743 x = lgamma(x) ! returns 0.0
8744 end program test_log_gamma
8747 @item @emph{Specific names}:
8748 @multitable @columnfractions .20 .20 .20 .25
8749 @item Name @tab Argument @tab Return type @tab Standard
8750 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
8751 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
8752 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
8755 @item @emph{See also}:
8756 Gamma function: @ref{GAMMA}
8763 @section @code{LOGICAL} --- Convert to logical type
8765 @cindex conversion, to logical
8768 @item @emph{Description}:
8769 Converts one kind of @code{LOGICAL} variable to another.
8771 @item @emph{Standard}:
8772 Fortran 95 and later
8777 @item @emph{Syntax}:
8778 @code{RESULT = LOGICAL(L [, KIND])}
8780 @item @emph{Arguments}:
8781 @multitable @columnfractions .15 .70
8782 @item @var{L} @tab The type shall be @code{LOGICAL}.
8783 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8784 expression indicating the kind parameter of the result.
8787 @item @emph{Return value}:
8788 The return value is a @code{LOGICAL} value equal to @var{L}, with a
8789 kind corresponding to @var{KIND}, or of the default logical kind if
8790 @var{KIND} is not given.
8792 @item @emph{See also}:
8793 @ref{INT}, @ref{REAL}, @ref{CMPLX}
8799 @section @code{LONG} --- Convert to integer type
8801 @cindex conversion, to integer
8804 @item @emph{Description}:
8805 Convert to a @code{KIND=4} integer type, which is the same size as a C
8806 @code{long} integer. This is equivalent to the standard @code{INT}
8807 intrinsic with an optional argument of @code{KIND=4}, and is only
8808 included for backwards compatibility.
8810 @item @emph{Standard}:
8816 @item @emph{Syntax}:
8817 @code{RESULT = LONG(A)}
8819 @item @emph{Arguments}:
8820 @multitable @columnfractions .15 .70
8821 @item @var{A} @tab Shall be of type @code{INTEGER},
8822 @code{REAL}, or @code{COMPLEX}.
8825 @item @emph{Return value}:
8826 The return value is a @code{INTEGER(4)} variable.
8828 @item @emph{See also}:
8829 @ref{INT}, @ref{INT2}, @ref{INT8}
8835 @section @code{LSHIFT} --- Left shift bits
8837 @cindex bits, shift left
8840 @item @emph{Description}:
8841 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
8842 bits shifted left by @var{SHIFT} places. If the absolute value of
8843 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
8844 Bits shifted out from the left end are lost; zeros are shifted in from
8847 This function has been superseded by the @code{ISHFT} intrinsic, which
8848 is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
8849 which is standard in Fortran 2008 and later.
8851 @item @emph{Standard}:
8857 @item @emph{Syntax}:
8858 @code{RESULT = LSHIFT(I, SHIFT)}
8860 @item @emph{Arguments}:
8861 @multitable @columnfractions .15 .70
8862 @item @var{I} @tab The type shall be @code{INTEGER}.
8863 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8866 @item @emph{Return value}:
8867 The return value is of type @code{INTEGER} and of the same kind as
8870 @item @emph{See also}:
8871 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}, @ref{SHIFTA}, @ref{SHIFTL},
8879 @section @code{LSTAT} --- Get file status
8881 @cindex file system, file status
8884 @item @emph{Description}:
8885 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
8886 symbolic link, then the link itself is statted, not the file that it
8889 The elements in @code{VALUES} are the same as described by @ref{STAT}.
8891 This intrinsic is provided in both subroutine and function forms;
8892 however, only one form can be used in any given program unit.
8894 @item @emph{Standard}:
8898 Subroutine, function
8900 @item @emph{Syntax}:
8901 @multitable @columnfractions .80
8902 @item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
8903 @item @code{STATUS = LSTAT(NAME, VALUES)}
8906 @item @emph{Arguments}:
8907 @multitable @columnfractions .15 .70
8908 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
8909 kind, a valid path within the file system.
8910 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
8911 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
8912 Returns 0 on success and a system specific error code otherwise.
8915 @item @emph{Example}:
8916 See @ref{STAT} for an example.
8918 @item @emph{See also}:
8919 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
8925 @section @code{LTIME} --- Convert time to local time info
8927 @cindex time, conversion to local time info
8930 @item @emph{Description}:
8931 Given a system time value @var{TIME} (as provided by the @code{TIME8}
8932 intrinsic), fills @var{VALUES} with values extracted from it appropriate
8933 to the local time zone using @code{localtime(3)}.
8935 @item @emph{Standard}:
8941 @item @emph{Syntax}:
8942 @code{CALL LTIME(TIME, VALUES)}
8944 @item @emph{Arguments}:
8945 @multitable @columnfractions .15 .70
8946 @item @var{TIME} @tab An @code{INTEGER} scalar expression
8947 corresponding to a system time, with @code{INTENT(IN)}.
8948 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
8949 with @code{INTENT(OUT)}.
8952 @item @emph{Return value}:
8953 The elements of @var{VALUES} are assigned as follows:
8955 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
8957 @item Minutes after the hour, range 0--59
8958 @item Hours past midnight, range 0--23
8959 @item Day of month, range 0--31
8960 @item Number of months since January, range 0--12
8961 @item Years since 1900
8962 @item Number of days since Sunday, range 0--6
8963 @item Days since January 1
8964 @item Daylight savings indicator: positive if daylight savings is in
8965 effect, zero if not, and negative if the information is not available.
8968 @item @emph{See also}:
8969 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
8976 @section @code{MALLOC} --- Allocate dynamic memory
8978 @cindex pointer, cray
8981 @item @emph{Description}:
8982 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
8983 returns the address of the allocated memory. The @code{MALLOC} intrinsic
8984 is an extension intended to be used with Cray pointers, and is provided
8985 in GNU Fortran to allow the user to compile legacy code. For new code
8986 using Fortran 95 pointers, the memory allocation intrinsic is
8989 @item @emph{Standard}:
8995 @item @emph{Syntax}:
8996 @code{PTR = MALLOC(SIZE)}
8998 @item @emph{Arguments}:
8999 @multitable @columnfractions .15 .70
9000 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
9003 @item @emph{Return value}:
9004 The return value is of type @code{INTEGER(K)}, with @var{K} such that
9005 variables of type @code{INTEGER(K)} have the same size as
9006 C pointers (@code{sizeof(void *)}).
9008 @item @emph{Example}:
9009 The following example demonstrates the use of @code{MALLOC} and
9010 @code{FREE} with Cray pointers.
9019 ptr_x = malloc(20*8)
9021 x(i) = sqrt(1.0d0 / i)
9029 end program test_malloc
9032 @item @emph{See also}:
9039 @section @code{MASKL} --- Left justified mask
9041 @cindex mask, left justified
9044 @item @emph{Description}:
9045 @code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
9046 remaining bits set to 0.
9048 @item @emph{Standard}:
9049 Fortran 2008 and later
9054 @item @emph{Syntax}:
9055 @code{RESULT = MASKL(I[, KIND])}
9057 @item @emph{Arguments}:
9058 @multitable @columnfractions .15 .70
9059 @item @var{I} @tab Shall be of type @code{INTEGER}.
9060 @item @var{KIND} @tab Shall be a scalar constant expression of type
9064 @item @emph{Return value}:
9065 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
9066 specifies the kind value of the return type; otherwise, it is of the
9067 default integer kind.
9069 @item @emph{See also}:
9076 @section @code{MASKR} --- Right justified mask
9078 @cindex mask, right justified
9081 @item @emph{Description}:
9082 @code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
9083 remaining bits set to 0.
9085 @item @emph{Standard}:
9086 Fortran 2008 and later
9091 @item @emph{Syntax}:
9092 @code{RESULT = MASKR(I[, KIND])}
9094 @item @emph{Arguments}:
9095 @multitable @columnfractions .15 .70
9096 @item @var{I} @tab Shall be of type @code{INTEGER}.
9097 @item @var{KIND} @tab Shall be a scalar constant expression of type
9101 @item @emph{Return value}:
9102 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
9103 specifies the kind value of the return type; otherwise, it is of the
9104 default integer kind.
9106 @item @emph{See also}:
9113 @section @code{MATMUL} --- matrix multiplication
9115 @cindex matrix multiplication
9116 @cindex product, matrix
9119 @item @emph{Description}:
9120 Performs a matrix multiplication on numeric or logical arguments.
9122 @item @emph{Standard}:
9123 Fortran 95 and later
9126 Transformational function
9128 @item @emph{Syntax}:
9129 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
9131 @item @emph{Arguments}:
9132 @multitable @columnfractions .15 .70
9133 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
9134 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
9136 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
9137 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
9138 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
9139 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
9140 equal to the last (or only) dimension of @var{MATRIX_A}.
9143 @item @emph{Return value}:
9144 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
9145 kind of the result follow the usual type and kind promotion rules, as
9146 for the @code{*} or @code{.AND.} operators.
9148 @item @emph{See also}:
9154 @section @code{MAX} --- Maximum value of an argument list
9161 @cindex maximum value
9164 @item @emph{Description}:
9165 Returns the argument with the largest (most positive) value.
9167 @item @emph{Standard}:
9168 Fortran 77 and later
9173 @item @emph{Syntax}:
9174 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
9176 @item @emph{Arguments}:
9177 @multitable @columnfractions .15 .70
9178 @item @var{A1} @tab The type shall be @code{INTEGER} or
9180 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
9181 as @var{A1}. (As a GNU extension, arguments of different kinds are
9185 @item @emph{Return value}:
9186 The return value corresponds to the maximum value among the arguments,
9187 and has the same type and kind as the first argument.
9189 @item @emph{Specific names}:
9190 @multitable @columnfractions .20 .20 .20 .25
9191 @item Name @tab Argument @tab Return type @tab Standard
9192 @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
9193 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
9194 @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
9195 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
9196 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
9199 @item @emph{See also}:
9200 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
9207 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
9208 @fnindex MAXEXPONENT
9209 @cindex model representation, maximum exponent
9212 @item @emph{Description}:
9213 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
9216 @item @emph{Standard}:
9217 Fortran 95 and later
9222 @item @emph{Syntax}:
9223 @code{RESULT = MAXEXPONENT(X)}
9225 @item @emph{Arguments}:
9226 @multitable @columnfractions .15 .70
9227 @item @var{X} @tab Shall be of type @code{REAL}.
9230 @item @emph{Return value}:
9231 The return value is of type @code{INTEGER} and of the default integer
9234 @item @emph{Example}:
9240 print *, minexponent(x), maxexponent(x)
9241 print *, minexponent(y), maxexponent(y)
9242 end program exponents
9249 @section @code{MAXLOC} --- Location of the maximum value within an array
9251 @cindex array, location of maximum element
9254 @item @emph{Description}:
9255 Determines the location of the element in the array with the maximum
9256 value, or, if the @var{DIM} argument is supplied, determines the
9257 locations of the maximum element along each row of the array in the
9258 @var{DIM} direction. If @var{MASK} is present, only the elements for
9259 which @var{MASK} is @code{.TRUE.} are considered. If more than one
9260 element in the array has the maximum value, the location returned is
9261 that of the first such element in array element order. If the array has
9262 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
9263 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
9264 and all of the elements of @var{MASK} along a given row are zero, the
9265 result value for that row is zero.
9267 @item @emph{Standard}:
9268 Fortran 95 and later
9271 Transformational function
9273 @item @emph{Syntax}:
9274 @multitable @columnfractions .80
9275 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
9276 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
9279 @item @emph{Arguments}:
9280 @multitable @columnfractions .15 .70
9281 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
9283 @item @var{DIM} @tab (Optional) Shall be a scalar of type
9284 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
9285 inclusive. It may not be an optional dummy argument.
9286 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
9287 and conformable with @var{ARRAY}.
9290 @item @emph{Return value}:
9291 If @var{DIM} is absent, the result is a rank-one array with a length
9292 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
9293 is an array with a rank one less than the rank of @var{ARRAY}, and a
9294 size corresponding to the size of @var{ARRAY} with the @var{DIM}
9295 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
9296 of one, the result is a scalar. In all cases, the result is of default
9297 @code{INTEGER} type.
9299 @item @emph{See also}:
9300 @ref{MAX}, @ref{MAXVAL}
9307 @section @code{MAXVAL} --- Maximum value of an array
9309 @cindex array, maximum value
9310 @cindex maximum value
9313 @item @emph{Description}:
9314 Determines the maximum value of the elements in an array value, or, if
9315 the @var{DIM} argument is supplied, determines the maximum value along
9316 each row of the array in the @var{DIM} direction. If @var{MASK} is
9317 present, only the elements for which @var{MASK} is @code{.TRUE.} are
9318 considered. If the array has zero size, or all of the elements of
9319 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
9320 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
9323 @item @emph{Standard}:
9324 Fortran 95 and later
9327 Transformational function
9329 @item @emph{Syntax}:
9330 @multitable @columnfractions .80
9331 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
9332 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
9335 @item @emph{Arguments}:
9336 @multitable @columnfractions .15 .70
9337 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
9339 @item @var{DIM} @tab (Optional) Shall be a scalar of type
9340 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
9341 inclusive. It may not be an optional dummy argument.
9342 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
9343 and conformable with @var{ARRAY}.
9346 @item @emph{Return value}:
9347 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
9348 is a scalar. If @var{DIM} is present, the result is an array with a
9349 rank one less than the rank of @var{ARRAY}, and a size corresponding to
9350 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
9351 cases, the result is of the same type and kind as @var{ARRAY}.
9353 @item @emph{See also}:
9354 @ref{MAX}, @ref{MAXLOC}
9360 @section @code{MCLOCK} --- Time function
9362 @cindex time, clock ticks
9366 @item @emph{Description}:
9367 Returns the number of clock ticks since the start of the process, based
9368 on the function @code{clock(3)} in the C standard library.
9370 This intrinsic is not fully portable, such as to systems with 32-bit
9371 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
9372 the values returned by this intrinsic might be, or become, negative, or
9373 numerically less than previous values, during a single run of the
9376 @item @emph{Standard}:
9382 @item @emph{Syntax}:
9383 @code{RESULT = MCLOCK()}
9385 @item @emph{Return value}:
9386 The return value is a scalar of type @code{INTEGER(4)}, equal to the
9387 number of clock ticks since the start of the process, or @code{-1} if
9388 the system does not support @code{clock(3)}.
9390 @item @emph{See also}:
9391 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
9398 @section @code{MCLOCK8} --- Time function (64-bit)
9400 @cindex time, clock ticks
9404 @item @emph{Description}:
9405 Returns the number of clock ticks since the start of the process, based
9406 on the function @code{clock(3)} in the C standard library.
9408 @emph{Warning:} this intrinsic does not increase the range of the timing
9409 values over that returned by @code{clock(3)}. On a system with a 32-bit
9410 @code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though
9411 it is converted to a 64-bit @code{INTEGER(8)} value. That means
9412 overflows of the 32-bit value can still occur. Therefore, the values
9413 returned by this intrinsic might be or become negative or numerically
9414 less than previous values during a single run of the compiled program.
9416 @item @emph{Standard}:
9422 @item @emph{Syntax}:
9423 @code{RESULT = MCLOCK8()}
9425 @item @emph{Return value}:
9426 The return value is a scalar of type @code{INTEGER(8)}, equal to the
9427 number of clock ticks since the start of the process, or @code{-1} if
9428 the system does not support @code{clock(3)}.
9430 @item @emph{See also}:
9431 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
9438 @section @code{MERGE} --- Merge variables
9440 @cindex array, merge arrays
9441 @cindex array, combine arrays
9444 @item @emph{Description}:
9445 Select values from two arrays according to a logical mask. The result
9446 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
9447 @var{FSOURCE} if it is @code{.FALSE.}.
9449 @item @emph{Standard}:
9450 Fortran 95 and later
9455 @item @emph{Syntax}:
9456 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
9458 @item @emph{Arguments}:
9459 @multitable @columnfractions .15 .70
9460 @item @var{TSOURCE} @tab May be of any type.
9461 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
9463 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
9466 @item @emph{Return value}:
9467 The result is of the same type and type parameters as @var{TSOURCE}.
9474 @section @code{MERGE_BITS} --- Merge of bits under mask
9479 @item @emph{Description}:
9480 @code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
9481 as determined by the mask. The i-th bit of the result is equal to the
9482 i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
9483 the i-th bit of @var{J} otherwise.
9485 @item @emph{Standard}:
9486 Fortran 2008 and later
9491 @item @emph{Syntax}:
9492 @code{RESULT = MERGE_BITS(I, J, MASK)}
9494 @item @emph{Arguments}:
9495 @multitable @columnfractions .15 .70
9496 @item @var{I} @tab Shall be of type @code{INTEGER}.
9497 @item @var{J} @tab Shall be of type @code{INTEGER} and of the same
9499 @item @var{MASK} @tab Shall be of type @code{INTEGER} and of the same
9503 @item @emph{Return value}:
9504 The result is of the same type and kind as @var{I}.
9511 @section @code{MIN} --- Minimum value of an argument list
9518 @cindex minimum value
9521 @item @emph{Description}:
9522 Returns the argument with the smallest (most negative) value.
9524 @item @emph{Standard}:
9525 Fortran 77 and later
9530 @item @emph{Syntax}:
9531 @code{RESULT = MIN(A1, A2 [, A3, ...])}
9533 @item @emph{Arguments}:
9534 @multitable @columnfractions .15 .70
9535 @item @var{A1} @tab The type shall be @code{INTEGER} or
9537 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
9538 as @var{A1}. (As a GNU extension, arguments of different kinds are
9542 @item @emph{Return value}:
9543 The return value corresponds to the maximum value among the arguments,
9544 and has the same type and kind as the first argument.
9546 @item @emph{Specific names}:
9547 @multitable @columnfractions .20 .20 .20 .25
9548 @item Name @tab Argument @tab Return type @tab Standard
9549 @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
9550 @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
9551 @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
9552 @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
9553 @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
9556 @item @emph{See also}:
9557 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
9563 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
9564 @fnindex MINEXPONENT
9565 @cindex model representation, minimum exponent
9568 @item @emph{Description}:
9569 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
9572 @item @emph{Standard}:
9573 Fortran 95 and later
9578 @item @emph{Syntax}:
9579 @code{RESULT = MINEXPONENT(X)}
9581 @item @emph{Arguments}:
9582 @multitable @columnfractions .15 .70
9583 @item @var{X} @tab Shall be of type @code{REAL}.
9586 @item @emph{Return value}:
9587 The return value is of type @code{INTEGER} and of the default integer
9590 @item @emph{Example}:
9591 See @code{MAXEXPONENT} for an example.
9597 @section @code{MINLOC} --- Location of the minimum value within an array
9599 @cindex array, location of minimum element
9602 @item @emph{Description}:
9603 Determines the location of the element in the array with the minimum
9604 value, or, if the @var{DIM} argument is supplied, determines the
9605 locations of the minimum element along each row of the array in the
9606 @var{DIM} direction. If @var{MASK} is present, only the elements for
9607 which @var{MASK} is @code{.TRUE.} are considered. If more than one
9608 element in the array has the minimum value, the location returned is
9609 that of the first such element in array element order. If the array has
9610 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
9611 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
9612 and all of the elements of @var{MASK} along a given row are zero, the
9613 result value for that row is zero.
9615 @item @emph{Standard}:
9616 Fortran 95 and later
9619 Transformational function
9621 @item @emph{Syntax}:
9622 @multitable @columnfractions .80
9623 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
9624 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
9627 @item @emph{Arguments}:
9628 @multitable @columnfractions .15 .70
9629 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
9631 @item @var{DIM} @tab (Optional) Shall be a scalar of type
9632 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
9633 inclusive. It may not be an optional dummy argument.
9634 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
9635 and conformable with @var{ARRAY}.
9638 @item @emph{Return value}:
9639 If @var{DIM} is absent, the result is a rank-one array with a length
9640 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
9641 is an array with a rank one less than the rank of @var{ARRAY}, and a
9642 size corresponding to the size of @var{ARRAY} with the @var{DIM}
9643 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
9644 of one, the result is a scalar. In all cases, the result is of default
9645 @code{INTEGER} type.
9647 @item @emph{See also}:
9648 @ref{MIN}, @ref{MINVAL}
9655 @section @code{MINVAL} --- Minimum value of an array
9657 @cindex array, minimum value
9658 @cindex minimum value
9661 @item @emph{Description}:
9662 Determines the minimum value of the elements in an array value, or, if
9663 the @var{DIM} argument is supplied, determines the minimum value along
9664 each row of the array in the @var{DIM} direction. If @var{MASK} is
9665 present, only the elements for which @var{MASK} is @code{.TRUE.} are
9666 considered. If the array has zero size, or all of the elements of
9667 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
9668 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
9669 @var{ARRAY} is of character type.
9671 @item @emph{Standard}:
9672 Fortran 95 and later
9675 Transformational function
9677 @item @emph{Syntax}:
9678 @multitable @columnfractions .80
9679 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
9680 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
9683 @item @emph{Arguments}:
9684 @multitable @columnfractions .15 .70
9685 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
9687 @item @var{DIM} @tab (Optional) Shall be a scalar of type
9688 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
9689 inclusive. It may not be an optional dummy argument.
9690 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
9691 and conformable with @var{ARRAY}.
9694 @item @emph{Return value}:
9695 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
9696 is a scalar. If @var{DIM} is present, the result is an array with a
9697 rank one less than the rank of @var{ARRAY}, and a size corresponding to
9698 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
9699 cases, the result is of the same type and kind as @var{ARRAY}.
9701 @item @emph{See also}:
9702 @ref{MIN}, @ref{MINLOC}
9709 @section @code{MOD} --- Remainder function
9714 @cindex division, remainder
9717 @item @emph{Description}:
9718 @code{MOD(A,P)} computes the remainder of the division of A by P@.
9720 @item @emph{Standard}:
9721 Fortran 77 and later
9726 @item @emph{Syntax}:
9727 @code{RESULT = MOD(A, P)}
9729 @item @emph{Arguments}:
9730 @multitable @columnfractions .15 .70
9731 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
9732 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
9733 and not equal to zero.
9736 @item @emph{Return value}:
9737 The return value is the result of @code{A - (INT(A/P) * P)}. The type
9738 and kind of the return value is the same as that of the arguments. The
9739 returned value has the same sign as A and a magnitude less than the
9742 @item @emph{Example}:
9746 print *, mod(17.5,5.5)
9747 print *, mod(17.5d0,5.5)
9748 print *, mod(17.5,5.5d0)
9751 print *, mod(-17.5,5.5)
9752 print *, mod(-17.5d0,5.5)
9753 print *, mod(-17.5,5.5d0)
9756 print *, mod(17.5,-5.5)
9757 print *, mod(17.5d0,-5.5)
9758 print *, mod(17.5,-5.5d0)
9759 end program test_mod
9762 @item @emph{Specific names}:
9763 @multitable @columnfractions .20 .20 .20 .25
9764 @item Name @tab Arguments @tab Return type @tab Standard
9765 @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
9766 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
9767 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
9770 @item @emph{See also}:
9778 @section @code{MODULO} --- Modulo function
9781 @cindex division, modulo
9784 @item @emph{Description}:
9785 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
9787 @item @emph{Standard}:
9788 Fortran 95 and later
9793 @item @emph{Syntax}:
9794 @code{RESULT = MODULO(A, P)}
9796 @item @emph{Arguments}:
9797 @multitable @columnfractions .15 .70
9798 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
9799 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}.
9800 It shall not be zero.
9803 @item @emph{Return value}:
9804 The type and kind of the result are those of the arguments.
9806 @item If @var{A} and @var{P} are of type @code{INTEGER}:
9807 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
9808 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
9810 @item If @var{A} and @var{P} are of type @code{REAL}:
9811 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
9813 The returned value has the same sign as P and a magnitude less than
9816 @item @emph{Example}:
9819 print *, modulo(17,3)
9820 print *, modulo(17.5,5.5)
9822 print *, modulo(-17,3)
9823 print *, modulo(-17.5,5.5)
9825 print *, modulo(17,-3)
9826 print *, modulo(17.5,-5.5)
9830 @item @emph{See also}:
9838 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
9840 @cindex moving allocation
9841 @cindex allocation, moving
9844 @item @emph{Description}:
9845 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
9846 @var{TO}. @var{FROM} will become deallocated in the process.
9848 @item @emph{Standard}:
9849 Fortran 2003 and later
9854 @item @emph{Syntax}:
9855 @code{CALL MOVE_ALLOC(FROM, TO)}
9857 @item @emph{Arguments}:
9858 @multitable @columnfractions .15 .70
9859 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
9860 of any type and kind.
9861 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
9862 of the same type, kind and rank as @var{FROM}.
9865 @item @emph{Return value}:
9868 @item @emph{Example}:
9870 program test_move_alloc
9871 integer, allocatable :: a(:), b(:)
9875 call move_alloc(a, b)
9876 print *, allocated(a), allocated(b)
9878 end program test_move_alloc
9885 @section @code{MVBITS} --- Move bits from one integer to another
9890 @item @emph{Description}:
9891 Moves @var{LEN} bits from positions @var{FROMPOS} through
9892 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
9893 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
9894 affected by the movement of bits is unchanged. The values of
9895 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
9896 @code{BIT_SIZE(FROM)}.
9898 @item @emph{Standard}:
9899 Fortran 95 and later
9902 Elemental subroutine
9904 @item @emph{Syntax}:
9905 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
9907 @item @emph{Arguments}:
9908 @multitable @columnfractions .15 .70
9909 @item @var{FROM} @tab The type shall be @code{INTEGER}.
9910 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
9911 @item @var{LEN} @tab The type shall be @code{INTEGER}.
9912 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
9913 same kind as @var{FROM}.
9914 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
9917 @item @emph{See also}:
9918 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
9924 @section @code{NEAREST} --- Nearest representable number
9926 @cindex real number, nearest different
9927 @cindex floating point, nearest different
9930 @item @emph{Description}:
9931 @code{NEAREST(X, S)} returns the processor-representable number nearest
9932 to @code{X} in the direction indicated by the sign of @code{S}.
9934 @item @emph{Standard}:
9935 Fortran 95 and later
9940 @item @emph{Syntax}:
9941 @code{RESULT = NEAREST(X, S)}
9943 @item @emph{Arguments}:
9944 @multitable @columnfractions .15 .70
9945 @item @var{X} @tab Shall be of type @code{REAL}.
9946 @item @var{S} @tab Shall be of type @code{REAL} and
9950 @item @emph{Return value}:
9951 The return value is of the same type as @code{X}. If @code{S} is
9952 positive, @code{NEAREST} returns the processor-representable number
9953 greater than @code{X} and nearest to it. If @code{S} is negative,
9954 @code{NEAREST} returns the processor-representable number smaller than
9955 @code{X} and nearest to it.
9957 @item @emph{Example}:
9959 program test_nearest
9961 x = nearest(42.0, 1.0)
9962 y = nearest(42.0, -1.0)
9963 write (*,"(3(G20.15))") x, y, x - y
9964 end program test_nearest
9971 @section @code{NEW_LINE} --- New line character
9974 @cindex output, newline
9977 @item @emph{Description}:
9978 @code{NEW_LINE(C)} returns the new-line character.
9980 @item @emph{Standard}:
9981 Fortran 2003 and later
9986 @item @emph{Syntax}:
9987 @code{RESULT = NEW_LINE(C)}
9989 @item @emph{Arguments}:
9990 @multitable @columnfractions .15 .70
9991 @item @var{C} @tab The argument shall be a scalar or array of the
9992 type @code{CHARACTER}.
9995 @item @emph{Return value}:
9996 Returns a @var{CHARACTER} scalar of length one with the new-line character of
9997 the same kind as parameter @var{C}.
9999 @item @emph{Example}:
10003 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
10004 end program newline
10011 @section @code{NINT} --- Nearest whole number
10014 @cindex rounding, nearest whole number
10017 @item @emph{Description}:
10018 @code{NINT(A)} rounds its argument to the nearest whole number.
10020 @item @emph{Standard}:
10021 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
10023 @item @emph{Class}:
10026 @item @emph{Syntax}:
10027 @code{RESULT = NINT(A [, KIND])}
10029 @item @emph{Arguments}:
10030 @multitable @columnfractions .15 .70
10031 @item @var{A} @tab The type of the argument shall be @code{REAL}.
10032 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10033 expression indicating the kind parameter of the result.
10036 @item @emph{Return value}:
10037 Returns @var{A} with the fractional portion of its magnitude eliminated by
10038 rounding to the nearest whole number and with its sign preserved,
10039 converted to an @code{INTEGER} of the default kind.
10041 @item @emph{Example}:
10048 print *, nint(x4), idnint(x8)
10049 end program test_nint
10052 @item @emph{Specific names}:
10053 @multitable @columnfractions .20 .20 .20 .25
10054 @item Name @tab Argument @tab Return Type @tab Standard
10055 @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later
10056 @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later
10059 @item @emph{See also}:
10060 @ref{CEILING}, @ref{FLOOR}
10067 @section @code{NORM2} --- Euclidean vector norms
10069 @cindex Euclidean vector norm
10070 @cindex L2 vector norm
10071 @cindex norm, Euclidean
10074 @item @emph{Description}:
10075 Calculates the Euclidean vector norm (@math{L_2} norm) of
10076 of @var{ARRAY} along dimension @var{DIM}.
10078 @item @emph{Standard}:
10079 Fortran 2008 and later
10081 @item @emph{Class}:
10082 Transformational function
10084 @item @emph{Syntax}:
10085 @multitable @columnfractions .80
10086 @item @code{RESULT = NORM2(ARRAY[, DIM])}
10089 @item @emph{Arguments}:
10090 @multitable @columnfractions .15 .70
10091 @item @var{ARRAY} @tab Shall be an array of type @code{REAL}
10092 @item @var{DIM} @tab (Optional) shall be a scalar of type
10093 @code{INTEGER} with a value in the range from 1 to n, where n
10094 equals the rank of @var{ARRAY}.
10097 @item @emph{Return value}:
10098 The result is of the same type as @var{ARRAY}.
10100 If @var{DIM} is absent, a scalar with the square root of the sum of all
10101 elements in @var{ARRAY} squared is returned. Otherwise, an array of
10102 rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
10103 shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
10106 @item @emph{Example}:
10109 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
10110 print *, NORM2(x) ! = sqrt(55.) ~ 7.416
10118 @section @code{NOT} --- Logical negation
10120 @cindex bits, negate
10121 @cindex bitwise logical not
10122 @cindex logical not, bitwise
10125 @item @emph{Description}:
10126 @code{NOT} returns the bitwise Boolean inverse of @var{I}.
10128 @item @emph{Standard}:
10129 Fortran 95 and later
10131 @item @emph{Class}:
10134 @item @emph{Syntax}:
10135 @code{RESULT = NOT(I)}
10137 @item @emph{Arguments}:
10138 @multitable @columnfractions .15 .70
10139 @item @var{I} @tab The type shall be @code{INTEGER}.
10142 @item @emph{Return value}:
10143 The return type is @code{INTEGER}, of the same kind as the
10146 @item @emph{See also}:
10147 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
10154 @section @code{NULL} --- Function that returns an disassociated pointer
10156 @cindex pointer, status
10157 @cindex pointer, disassociated
10160 @item @emph{Description}:
10161 Returns a disassociated pointer.
10163 If @var{MOLD} is present, a disassociated pointer of the same type is
10164 returned, otherwise the type is determined by context.
10166 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
10167 includes cases where it is required.
10169 @item @emph{Standard}:
10170 Fortran 95 and later
10172 @item @emph{Class}:
10173 Transformational function
10175 @item @emph{Syntax}:
10176 @code{PTR => NULL([MOLD])}
10178 @item @emph{Arguments}:
10179 @multitable @columnfractions .15 .70
10180 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
10181 status and of any type.
10184 @item @emph{Return value}:
10185 A disassociated pointer.
10187 @item @emph{Example}:
10189 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
10192 @item @emph{See also}:
10199 @section @code{NUM_IMAGES} --- Function that returns the number of images
10200 @fnindex NUM_IMAGES
10201 @cindex coarray, @code{NUM_IMAGES}
10202 @cindex images, number of
10205 @item @emph{Description}:
10206 Returns the number of images.
10208 @item @emph{Standard}:
10209 Fortran 2008 and later. With @var{DISTANCE} or @var{FAILED} argument,
10210 Technical Specification (TS) 18508 or later
10213 @item @emph{Class}:
10214 Transformational function
10216 @item @emph{Syntax}:
10217 @code{RESULT = NUM_IMAGES(DISTANCE, FAILED)}
10219 @item @emph{Arguments}:
10220 @multitable @columnfractions .15 .70
10221 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
10222 @item @var{FAILED} @tab (optional, intent(in)) Scalar logical expression
10225 @item @emph{Return value}:
10226 Scalar default-kind integer. If @var{DISTANCE} is not present or has value 0,
10227 the number of images in the current team is returned. For values smaller or
10228 equal distance to the initial team, it returns the number of images index
10229 on the ancestor team which has a distance of @var{DISTANCE} from the invoking
10230 team. If @var{DISTANCE} is larger than the distance to the initial team, the
10231 number of images of the initial team is returned. If @var{FAILED} is not present
10232 the total number of images is returned; if it has the value @code{.TRUE.},
10233 the number of failed images is returned, otherwise, the number of images which
10234 do have not the failed status.
10236 @item @emph{Example}:
10238 INTEGER :: value[*]
10240 value = THIS_IMAGE()
10242 IF (THIS_IMAGE() == 1) THEN
10243 DO i = 1, NUM_IMAGES()
10244 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
10249 @item @emph{See also}:
10250 @ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
10256 @section @code{OR} --- Bitwise logical OR
10258 @cindex bitwise logical or
10259 @cindex logical or, bitwise
10262 @item @emph{Description}:
10263 Bitwise logical @code{OR}.
10265 This intrinsic routine is provided for backwards compatibility with
10266 GNU Fortran 77. For integer arguments, programmers should consider
10267 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
10269 @item @emph{Standard}:
10272 @item @emph{Class}:
10275 @item @emph{Syntax}:
10276 @code{RESULT = OR(I, J)}
10278 @item @emph{Arguments}:
10279 @multitable @columnfractions .15 .70
10280 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
10281 type or a scalar @code{LOGICAL} type.
10282 @item @var{J} @tab The type shall be the same as the type of @var{J}.
10285 @item @emph{Return value}:
10286 The return type is either a scalar @code{INTEGER} or a scalar
10287 @code{LOGICAL}. If the kind type parameters differ, then the
10288 smaller kind type is implicitly converted to larger kind, and the
10289 return has the larger kind.
10291 @item @emph{Example}:
10294 LOGICAL :: T = .TRUE., F = .FALSE.
10296 DATA a / Z'F' /, b / Z'3' /
10298 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
10299 WRITE (*,*) OR(a, b)
10303 @item @emph{See also}:
10304 Fortran 95 elemental function: @ref{IOR}
10310 @section @code{PACK} --- Pack an array into an array of rank one
10312 @cindex array, packing
10313 @cindex array, reduce dimension
10314 @cindex array, gather elements
10317 @item @emph{Description}:
10318 Stores the elements of @var{ARRAY} in an array of rank one.
10320 The beginning of the resulting array is made up of elements whose @var{MASK}
10321 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
10324 @item @emph{Standard}:
10325 Fortran 95 and later
10327 @item @emph{Class}:
10328 Transformational function
10330 @item @emph{Syntax}:
10331 @code{RESULT = PACK(ARRAY, MASK[,VECTOR])}
10333 @item @emph{Arguments}:
10334 @multitable @columnfractions .15 .70
10335 @item @var{ARRAY} @tab Shall be an array of any type.
10336 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
10337 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
10339 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
10340 as @var{ARRAY} and of rank one. If present, the number of elements in
10341 @var{VECTOR} shall be equal to or greater than the number of true elements
10342 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
10343 @var{VECTOR} shall be equal to or greater than the number of elements in
10347 @item @emph{Return value}:
10348 The result is an array of rank one and the same type as that of @var{ARRAY}.
10349 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
10350 number of @code{TRUE} values in @var{MASK} otherwise.
10352 @item @emph{Example}:
10353 Gathering nonzero elements from an array:
10355 PROGRAM test_pack_1
10357 m = (/ 1, 0, 0, 0, 5, 0 /)
10358 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
10362 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
10364 PROGRAM test_pack_2
10366 m = (/ 1, 0, 0, 2 /)
10367 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
10371 @item @emph{See also}:
10378 @section @code{PARITY} --- Reduction with exclusive OR
10381 @cindex Reduction, XOR
10382 @cindex XOR reduction
10385 @item @emph{Description}:
10386 Calculates the parity, i.e. the reduction using @code{.XOR.},
10387 of @var{MASK} along dimension @var{DIM}.
10389 @item @emph{Standard}:
10390 Fortran 2008 and later
10392 @item @emph{Class}:
10393 Transformational function
10395 @item @emph{Syntax}:
10396 @multitable @columnfractions .80
10397 @item @code{RESULT = PARITY(MASK[, DIM])}
10400 @item @emph{Arguments}:
10401 @multitable @columnfractions .15 .70
10402 @item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL}
10403 @item @var{DIM} @tab (Optional) shall be a scalar of type
10404 @code{INTEGER} with a value in the range from 1 to n, where n
10405 equals the rank of @var{MASK}.
10408 @item @emph{Return value}:
10409 The result is of the same type as @var{MASK}.
10411 If @var{DIM} is absent, a scalar with the parity of all elements in
10412 @var{MASK} is returned, i.e. true if an odd number of elements is
10413 @code{.true.} and false otherwise. If @var{DIM} is present, an array
10414 of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
10415 and a shape similar to that of @var{MASK} with dimension @var{DIM}
10416 dropped is returned.
10418 @item @emph{Example}:
10421 LOGICAL :: x(2) = [ .true., .false. ]
10422 print *, PARITY(x) ! prints "T" (true).
10430 @section @code{PERROR} --- Print system error message
10432 @cindex system, error handling
10435 @item @emph{Description}:
10436 Prints (on the C @code{stderr} stream) a newline-terminated error
10437 message corresponding to the last system error. This is prefixed by
10438 @var{STRING}, a colon and a space. See @code{perror(3)}.
10440 @item @emph{Standard}:
10443 @item @emph{Class}:
10446 @item @emph{Syntax}:
10447 @code{CALL PERROR(STRING)}
10449 @item @emph{Arguments}:
10450 @multitable @columnfractions .15 .70
10451 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
10455 @item @emph{See also}:
10462 @section @code{POPCNT} --- Number of bits set
10464 @cindex binary representation
10468 @item @emph{Description}:
10469 @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
10470 representation of @code{I}.
10472 @item @emph{Standard}:
10473 Fortran 2008 and later
10475 @item @emph{Class}:
10478 @item @emph{Syntax}:
10479 @code{RESULT = POPCNT(I)}
10481 @item @emph{Arguments}:
10482 @multitable @columnfractions .15 .70
10483 @item @var{I} @tab Shall be of type @code{INTEGER}.
10486 @item @emph{Return value}:
10487 The return value is of type @code{INTEGER} and of the default integer
10490 @item @emph{See also}:
10491 @ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ}
10493 @item @emph{Example}:
10495 program test_population
10496 print *, popcnt(127), poppar(127)
10497 print *, popcnt(huge(0_4)), poppar(huge(0_4))
10498 print *, popcnt(huge(0_8)), poppar(huge(0_8))
10499 end program test_population
10505 @section @code{POPPAR} --- Parity of the number of bits set
10507 @cindex binary representation
10511 @item @emph{Description}:
10512 @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
10513 of the number of bits set ('1' bits) in the binary representation of
10514 @code{I}. It is equal to 0 if @code{I} has an even number of bits set,
10515 and 1 for an odd number of '1' bits.
10517 @item @emph{Standard}:
10518 Fortran 2008 and later
10520 @item @emph{Class}:
10523 @item @emph{Syntax}:
10524 @code{RESULT = POPPAR(I)}
10526 @item @emph{Arguments}:
10527 @multitable @columnfractions .15 .70
10528 @item @var{I} @tab Shall be of type @code{INTEGER}.
10531 @item @emph{Return value}:
10532 The return value is of type @code{INTEGER} and of the default integer
10535 @item @emph{See also}:
10536 @ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ}
10538 @item @emph{Example}:
10540 program test_population
10541 print *, popcnt(127), poppar(127)
10542 print *, popcnt(huge(0_4)), poppar(huge(0_4))
10543 print *, popcnt(huge(0_8)), poppar(huge(0_8))
10544 end program test_population
10551 @section @code{PRECISION} --- Decimal precision of a real kind
10553 @cindex model representation, precision
10556 @item @emph{Description}:
10557 @code{PRECISION(X)} returns the decimal precision in the model of the
10560 @item @emph{Standard}:
10561 Fortran 95 and later
10563 @item @emph{Class}:
10566 @item @emph{Syntax}:
10567 @code{RESULT = PRECISION(X)}
10569 @item @emph{Arguments}:
10570 @multitable @columnfractions .15 .70
10571 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
10574 @item @emph{Return value}:
10575 The return value is of type @code{INTEGER} and of the default integer
10578 @item @emph{See also}:
10579 @ref{SELECTED_REAL_KIND}, @ref{RANGE}
10581 @item @emph{Example}:
10583 program prec_and_range
10584 real(kind=4) :: x(2)
10585 complex(kind=8) :: y
10587 print *, precision(x), range(x)
10588 print *, precision(y), range(y)
10589 end program prec_and_range
10596 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
10600 @item @emph{Description}:
10601 Determines whether an optional dummy argument is present.
10603 @item @emph{Standard}:
10604 Fortran 95 and later
10606 @item @emph{Class}:
10609 @item @emph{Syntax}:
10610 @code{RESULT = PRESENT(A)}
10612 @item @emph{Arguments}:
10613 @multitable @columnfractions .15 .70
10614 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
10615 value, or a dummy procedure. It shall be the name of an optional dummy argument
10616 accessible within the current subroutine or function.
10619 @item @emph{Return value}:
10620 Returns either @code{TRUE} if the optional argument @var{A} is present, or
10621 @code{FALSE} otherwise.
10623 @item @emph{Example}:
10625 PROGRAM test_present
10626 WRITE(*,*) f(), f(42) ! "F T"
10628 LOGICAL FUNCTION f(x)
10629 INTEGER, INTENT(IN), OPTIONAL :: x
10639 @section @code{PRODUCT} --- Product of array elements
10641 @cindex array, product
10642 @cindex array, multiply elements
10643 @cindex array, conditionally multiply elements
10644 @cindex multiply array elements
10647 @item @emph{Description}:
10648 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
10649 the corresponding element in @var{MASK} is @code{TRUE}.
10651 @item @emph{Standard}:
10652 Fortran 95 and later
10654 @item @emph{Class}:
10655 Transformational function
10657 @item @emph{Syntax}:
10658 @multitable @columnfractions .80
10659 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
10660 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
10663 @item @emph{Arguments}:
10664 @multitable @columnfractions .15 .70
10665 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
10666 @code{REAL} or @code{COMPLEX}.
10667 @item @var{DIM} @tab (Optional) shall be a scalar of type
10668 @code{INTEGER} with a value in the range from 1 to n, where n
10669 equals the rank of @var{ARRAY}.
10670 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
10671 and either be a scalar or an array of the same shape as @var{ARRAY}.
10674 @item @emph{Return value}:
10675 The result is of the same type as @var{ARRAY}.
10677 If @var{DIM} is absent, a scalar with the product of all elements in
10678 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
10679 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
10680 dimension @var{DIM} dropped is returned.
10683 @item @emph{Example}:
10685 PROGRAM test_product
10686 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
10687 print *, PRODUCT(x) ! all elements, product = 120
10688 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
10692 @item @emph{See also}:
10699 @section @code{RADIX} --- Base of a model number
10701 @cindex model representation, base
10702 @cindex model representation, radix
10705 @item @emph{Description}:
10706 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
10708 @item @emph{Standard}:
10709 Fortran 95 and later
10711 @item @emph{Class}:
10714 @item @emph{Syntax}:
10715 @code{RESULT = RADIX(X)}
10717 @item @emph{Arguments}:
10718 @multitable @columnfractions .15 .70
10719 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
10722 @item @emph{Return value}:
10723 The return value is a scalar of type @code{INTEGER} and of the default
10726 @item @emph{See also}:
10727 @ref{SELECTED_REAL_KIND}
10729 @item @emph{Example}:
10732 print *, "The radix for the default integer kind is", radix(0)
10733 print *, "The radix for the default real kind is", radix(0.0)
10734 end program test_radix
10742 @section @code{RAN} --- Real pseudo-random number
10744 @cindex random number generation
10747 @item @emph{Description}:
10748 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
10749 provided as an alias for @code{RAND}. See @ref{RAND} for complete
10752 @item @emph{Standard}:
10755 @item @emph{Class}:
10758 @item @emph{See also}:
10759 @ref{RAND}, @ref{RANDOM_NUMBER}
10765 @section @code{RAND} --- Real pseudo-random number
10767 @cindex random number generation
10770 @item @emph{Description}:
10771 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
10772 distribution between 0 and 1. If @var{FLAG} is 0, the next number
10773 in the current sequence is returned; if @var{FLAG} is 1, the generator
10774 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
10775 it is used as a new seed with @code{SRAND}.
10777 This intrinsic routine is provided for backwards compatibility with
10778 GNU Fortran 77. It implements a simple modulo generator as provided
10779 by @command{g77}. For new code, one should consider the use of
10780 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
10782 @item @emph{Standard}:
10785 @item @emph{Class}:
10788 @item @emph{Syntax}:
10789 @code{RESULT = RAND(I)}
10791 @item @emph{Arguments}:
10792 @multitable @columnfractions .15 .70
10793 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
10796 @item @emph{Return value}:
10797 The return value is of @code{REAL} type and the default kind.
10799 @item @emph{Example}:
10802 integer,parameter :: seed = 86456
10805 print *, rand(), rand(), rand(), rand()
10806 print *, rand(seed), rand(), rand(), rand()
10807 end program test_rand
10810 @item @emph{See also}:
10811 @ref{SRAND}, @ref{RANDOM_NUMBER}
10817 @node RANDOM_NUMBER
10818 @section @code{RANDOM_NUMBER} --- Pseudo-random number
10819 @fnindex RANDOM_NUMBER
10820 @cindex random number generation
10823 @item @emph{Description}:
10824 Returns a single pseudorandom number or an array of pseudorandom numbers
10825 from the uniform distribution over the range @math{ 0 \leq x < 1}.
10827 The runtime-library implements George Marsaglia's KISS (Keep It Simple
10828 Stupid) random number generator (RNG). This RNG combines:
10830 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
10831 with a period of @math{2^{32}},
10832 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
10833 @item Two 16-bit multiply-with-carry generators with a period of
10834 @math{597273182964842497 > 2^{59}}.
10836 The overall period exceeds @math{2^{123}}.
10838 Please note, this RNG is thread safe if used within OpenMP directives,
10839 i.e., its state will be consistent while called from multiple threads.
10840 However, the KISS generator does not create random numbers in parallel
10841 from multiple sources, but in sequence from a single source. If an
10842 OpenMP-enabled application heavily relies on random numbers, one should
10843 consider employing a dedicated parallel random number generator instead.
10845 @item @emph{Standard}:
10846 Fortran 95 and later
10848 @item @emph{Class}:
10851 @item @emph{Syntax}:
10852 @code{RANDOM_NUMBER(HARVEST)}
10854 @item @emph{Arguments}:
10855 @multitable @columnfractions .15 .70
10856 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
10859 @item @emph{Example}:
10861 program test_random_number
10863 CALL init_random_seed() ! see example of RANDOM_SEED
10864 CALL RANDOM_NUMBER(r)
10868 @item @emph{See also}:
10875 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
10876 @fnindex RANDOM_SEED
10877 @cindex random number generation, seeding
10878 @cindex seeding a random number generator
10881 @item @emph{Description}:
10882 Restarts or queries the state of the pseudorandom number generator used by
10883 @code{RANDOM_NUMBER}.
10885 If @code{RANDOM_SEED} is called without arguments, it is initialized
10886 to a default state. The example below shows how to initialize the
10887 random seed with a varying seed in order to ensure a different random
10888 number sequence for each invocation of the program. Note that setting
10889 any of the seed values to zero should be avoided as it can result in
10890 poor quality random numbers being generated.
10892 @item @emph{Standard}:
10893 Fortran 95 and later
10895 @item @emph{Class}:
10898 @item @emph{Syntax}:
10899 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
10901 @item @emph{Arguments}:
10902 @multitable @columnfractions .15 .70
10903 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
10904 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
10905 of the arrays used with the @var{PUT} and @var{GET} arguments.
10906 @item @var{PUT} @tab (Optional) Shall be an array of type default
10907 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
10908 the array must be larger than or equal to the number returned by the
10909 @var{SIZE} argument.
10910 @item @var{GET} @tab (Optional) Shall be an array of type default
10911 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
10912 of the array must be larger than or equal to the number returned by
10913 the @var{SIZE} argument.
10916 @item @emph{Example}:
10918 subroutine init_random_seed()
10919 use iso_fortran_env, only: int64
10921 integer, allocatable :: seed(:)
10922 integer :: i, n, un, istat, dt(8), pid
10923 integer(int64) :: t
10925 call random_seed(size = n)
10927 ! First try if the OS provides a random number generator
10928 open(newunit=un, file="/dev/urandom", access="stream", &
10929 form="unformatted", action="read", status="old", iostat=istat)
10930 if (istat == 0) then
10934 ! Fallback to XOR:ing the current time and pid. The PID is
10935 ! useful in case one launches multiple instances of the same
10936 ! program in parallel.
10937 call system_clock(t)
10939 call date_and_time(values=dt)
10940 t = (dt(1) - 1970) * 365_int64 * 24 * 60 * 60 * 1000 &
10941 + dt(2) * 31_int64 * 24 * 60 * 60 * 1000 &
10942 + dt(3) * 24_int64 * 60 * 60 * 1000 &
10943 + dt(5) * 60 * 60 * 1000 &
10944 + dt(6) * 60 * 1000 + dt(7) * 1000 &
10948 t = ieor(t, int(pid, kind(t)))
10953 call random_seed(put=seed)
10955 ! This simple PRNG might not be good enough for real work, but is
10956 ! sufficient for seeding a better PRNG.
10959 integer(int64) :: s
10963 s = mod(s, 4294967296_int64)
10965 s = mod(s * 279470273_int64, 4294967291_int64)
10966 lcg = int(mod(s, int(huge(0), int64)), kind(0))
10968 end subroutine init_random_seed
10971 @item @emph{See also}:
10972 @ref{RANDOM_NUMBER}
10978 @section @code{RANGE} --- Decimal exponent range
10980 @cindex model representation, range
10983 @item @emph{Description}:
10984 @code{RANGE(X)} returns the decimal exponent range in the model of the
10987 @item @emph{Standard}:
10988 Fortran 95 and later
10990 @item @emph{Class}:
10993 @item @emph{Syntax}:
10994 @code{RESULT = RANGE(X)}
10996 @item @emph{Arguments}:
10997 @multitable @columnfractions .15 .70
10998 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
11002 @item @emph{Return value}:
11003 The return value is of type @code{INTEGER} and of the default integer
11006 @item @emph{See also}:
11007 @ref{SELECTED_REAL_KIND}, @ref{PRECISION}
11009 @item @emph{Example}:
11010 See @code{PRECISION} for an example.
11016 @section @code{RANK} --- Rank of a data object
11021 @item @emph{Description}:
11022 @code{RANK(A)} returns the rank of a scalar or array data object.
11024 @item @emph{Standard}:
11025 Technical Specification (TS) 29113
11027 @item @emph{Class}:
11030 @item @emph{Syntax}:
11031 @code{RESULT = RANK(A)}
11033 @item @emph{Arguments}:
11034 @multitable @columnfractions .15 .70
11035 @item @var{A} @tab can be of any type
11038 @item @emph{Return value}:
11039 The return value is of type @code{INTEGER} and of the default integer
11040 kind. For arrays, their rank is returned; for scalars zero is returned.
11042 @item @emph{Example}:
11046 real, allocatable :: b(:,:)
11048 print *, rank(a), rank(b) ! Prints: 0 2
11049 end program test_rank
11057 @section @code{REAL} --- Convert to real type
11063 @cindex conversion, to real
11064 @cindex complex numbers, real part
11067 @item @emph{Description}:
11068 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
11069 @code{REALPART} function is provided for compatibility with @command{g77},
11070 and its use is strongly discouraged.
11072 @item @emph{Standard}:
11073 Fortran 77 and later
11075 @item @emph{Class}:
11078 @item @emph{Syntax}:
11079 @multitable @columnfractions .80
11080 @item @code{RESULT = REAL(A [, KIND])}
11081 @item @code{RESULT = REALPART(Z)}
11084 @item @emph{Arguments}:
11085 @multitable @columnfractions .15 .70
11086 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
11088 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11089 expression indicating the kind parameter of the result.
11092 @item @emph{Return value}:
11093 These functions return a @code{REAL} variable or array under
11094 the following rules:
11098 @code{REAL(A)} is converted to a default real type if @var{A} is an
11099 integer or real variable.
11101 @code{REAL(A)} is converted to a real type with the kind type parameter
11102 of @var{A} if @var{A} is a complex variable.
11104 @code{REAL(A, KIND)} is converted to a real type with kind type
11105 parameter @var{KIND} if @var{A} is a complex, integer, or real
11109 @item @emph{Example}:
11112 complex :: x = (1.0, 2.0)
11113 print *, real(x), real(x,8), realpart(x)
11114 end program test_real
11117 @item @emph{Specific names}:
11118 @multitable @columnfractions .20 .20 .20 .25
11119 @item Name @tab Argument @tab Return type @tab Standard
11120 @item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later
11121 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension
11122 @item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab Fortran 77 and later
11126 @item @emph{See also}:
11134 @section @code{RENAME} --- Rename a file
11136 @cindex file system, rename file
11139 @item @emph{Description}:
11140 Renames a file from file @var{PATH1} to @var{PATH2}. A null
11141 character (@code{CHAR(0)}) can be used to mark the end of the names in
11142 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
11143 names are ignored. If the @var{STATUS} argument is supplied, it
11144 contains 0 on success or a nonzero error code upon return; see
11147 This intrinsic is provided in both subroutine and function forms;
11148 however, only one form can be used in any given program unit.
11150 @item @emph{Standard}:
11153 @item @emph{Class}:
11154 Subroutine, function
11156 @item @emph{Syntax}:
11157 @multitable @columnfractions .80
11158 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
11159 @item @code{STATUS = RENAME(PATH1, PATH2)}
11162 @item @emph{Arguments}:
11163 @multitable @columnfractions .15 .70
11164 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
11165 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
11166 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11169 @item @emph{See also}:
11177 @section @code{REPEAT} --- Repeated string concatenation
11179 @cindex string, repeat
11180 @cindex string, concatenate
11183 @item @emph{Description}:
11184 Concatenates @var{NCOPIES} copies of a string.
11186 @item @emph{Standard}:
11187 Fortran 95 and later
11189 @item @emph{Class}:
11190 Transformational function
11192 @item @emph{Syntax}:
11193 @code{RESULT = REPEAT(STRING, NCOPIES)}
11195 @item @emph{Arguments}:
11196 @multitable @columnfractions .15 .70
11197 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
11198 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
11201 @item @emph{Return value}:
11202 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
11205 @item @emph{Example}:
11207 program test_repeat
11208 write(*,*) repeat("x", 5) ! "xxxxx"
11216 @section @code{RESHAPE} --- Function to reshape an array
11218 @cindex array, change dimensions
11219 @cindex array, transmogrify
11222 @item @emph{Description}:
11223 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
11224 the new array may be padded with elements from @var{PAD} or permuted
11225 as defined by @var{ORDER}.
11227 @item @emph{Standard}:
11228 Fortran 95 and later
11230 @item @emph{Class}:
11231 Transformational function
11233 @item @emph{Syntax}:
11234 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
11236 @item @emph{Arguments}:
11237 @multitable @columnfractions .15 .70
11238 @item @var{SOURCE} @tab Shall be an array of any type.
11239 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
11240 array of rank one. Its values must be positive or zero.
11241 @item @var{PAD} @tab (Optional) shall be an array of the same
11242 type as @var{SOURCE}.
11243 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
11244 and an array of the same shape as @var{SHAPE}. Its values shall
11245 be a permutation of the numbers from 1 to n, where n is the size of
11246 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
11250 @item @emph{Return value}:
11251 The result is an array of shape @var{SHAPE} with the same type as
11254 @item @emph{Example}:
11256 PROGRAM test_reshape
11257 INTEGER, DIMENSION(4) :: x
11258 WRITE(*,*) SHAPE(x) ! prints "4"
11259 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
11263 @item @emph{See also}:
11270 @section @code{RRSPACING} --- Reciprocal of the relative spacing
11272 @cindex real number, relative spacing
11273 @cindex floating point, relative spacing
11277 @item @emph{Description}:
11278 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
11279 model numbers near @var{X}.
11281 @item @emph{Standard}:
11282 Fortran 95 and later
11284 @item @emph{Class}:
11287 @item @emph{Syntax}:
11288 @code{RESULT = RRSPACING(X)}
11290 @item @emph{Arguments}:
11291 @multitable @columnfractions .15 .70
11292 @item @var{X} @tab Shall be of type @code{REAL}.
11295 @item @emph{Return value}:
11296 The return value is of the same type and kind as @var{X}.
11297 The value returned is equal to
11298 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
11300 @item @emph{See also}:
11307 @section @code{RSHIFT} --- Right shift bits
11309 @cindex bits, shift right
11312 @item @emph{Description}:
11313 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
11314 bits shifted right by @var{SHIFT} places. If the absolute value of
11315 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11316 Bits shifted out from the right end are lost. The fill is arithmetic: the
11317 bits shifted in from the left end are equal to the leftmost bit, which in
11318 two's complement representation is the sign bit.
11320 This function has been superseded by the @code{SHIFTA} intrinsic, which
11321 is standard in Fortran 2008 and later.
11323 @item @emph{Standard}:
11326 @item @emph{Class}:
11329 @item @emph{Syntax}:
11330 @code{RESULT = RSHIFT(I, SHIFT)}
11332 @item @emph{Arguments}:
11333 @multitable @columnfractions .15 .70
11334 @item @var{I} @tab The type shall be @code{INTEGER}.
11335 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11338 @item @emph{Return value}:
11339 The return value is of type @code{INTEGER} and of the same kind as
11342 @item @emph{See also}:
11343 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}, @ref{SHIFTA}, @ref{SHIFTR},
11351 @section @code{SAME_TYPE_AS} --- Query dynamic types for equality
11352 @fnindex SAME_TYPE_AS
11355 @item @emph{Description}:
11356 Query dynamic types for equality.
11358 @item @emph{Standard}:
11359 Fortran 2003 and later
11361 @item @emph{Class}:
11364 @item @emph{Syntax}:
11365 @code{RESULT = SAME_TYPE_AS(A, B)}
11367 @item @emph{Arguments}:
11368 @multitable @columnfractions .15 .70
11369 @item @var{A} @tab Shall be an object of extensible declared type or
11370 unlimited polymorphic.
11371 @item @var{B} @tab Shall be an object of extensible declared type or
11372 unlimited polymorphic.
11375 @item @emph{Return value}:
11376 The return value is a scalar of type default logical. It is true if and
11377 only if the dynamic type of A is the same as the dynamic type of B.
11379 @item @emph{See also}:
11380 @ref{EXTENDS_TYPE_OF}
11387 @section @code{SCALE} --- Scale a real value
11389 @cindex real number, scale
11390 @cindex floating point, scale
11393 @item @emph{Description}:
11394 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
11396 @item @emph{Standard}:
11397 Fortran 95 and later
11399 @item @emph{Class}:
11402 @item @emph{Syntax}:
11403 @code{RESULT = SCALE(X, I)}
11405 @item @emph{Arguments}:
11406 @multitable @columnfractions .15 .70
11407 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
11408 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
11411 @item @emph{Return value}:
11412 The return value is of the same type and kind as @var{X}.
11413 Its value is @code{X * RADIX(X)**I}.
11415 @item @emph{Example}:
11418 real :: x = 178.1387e-4
11420 print *, scale(x,i), x*radix(x)**i
11421 end program test_scale
11429 @section @code{SCAN} --- Scan a string for the presence of a set of characters
11431 @cindex string, find subset
11434 @item @emph{Description}:
11435 Scans a @var{STRING} for any of the characters in a @var{SET}
11438 If @var{BACK} is either absent or equals @code{FALSE}, this function
11439 returns the position of the leftmost character of @var{STRING} that is
11440 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
11441 is returned. If no character of @var{SET} is found in @var{STRING}, the
11444 @item @emph{Standard}:
11445 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11447 @item @emph{Class}:
11450 @item @emph{Syntax}:
11451 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
11453 @item @emph{Arguments}:
11454 @multitable @columnfractions .15 .70
11455 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
11456 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
11457 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
11458 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11459 expression indicating the kind parameter of the result.
11462 @item @emph{Return value}:
11463 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11464 @var{KIND} is absent, the return value is of default integer kind.
11466 @item @emph{Example}:
11469 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
11470 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
11471 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
11475 @item @emph{See also}:
11476 @ref{INDEX intrinsic}, @ref{VERIFY}
11482 @section @code{SECNDS} --- Time function
11484 @cindex time, elapsed
11485 @cindex elapsed time
11488 @item @emph{Description}:
11489 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
11490 @var{X} is a reference time, also in seconds. If this is zero, the time in
11491 seconds from midnight is returned. This function is non-standard and its
11492 use is discouraged.
11494 @item @emph{Standard}:
11497 @item @emph{Class}:
11500 @item @emph{Syntax}:
11501 @code{RESULT = SECNDS (X)}
11503 @item @emph{Arguments}:
11504 @multitable @columnfractions .15 .70
11505 @item @var{T} @tab Shall be of type @code{REAL(4)}.
11506 @item @var{X} @tab Shall be of type @code{REAL(4)}.
11509 @item @emph{Return value}:
11512 @item @emph{Example}:
11514 program test_secnds
11517 print *, secnds (0.0) ! seconds since midnight
11518 t1 = secnds (0.0) ! reference time
11519 do i = 1, 10000000 ! do something
11521 t2 = secnds (t1) ! elapsed time
11522 print *, "Something took ", t2, " seconds."
11523 end program test_secnds
11530 @section @code{SECOND} --- CPU time function
11532 @cindex time, elapsed
11533 @cindex elapsed time
11536 @item @emph{Description}:
11537 Returns a @code{REAL(4)} value representing the elapsed CPU time in
11538 seconds. This provides the same functionality as the standard
11539 @code{CPU_TIME} intrinsic, and is only included for backwards
11542 This intrinsic is provided in both subroutine and function forms;
11543 however, only one form can be used in any given program unit.
11545 @item @emph{Standard}:
11548 @item @emph{Class}:
11549 Subroutine, function
11551 @item @emph{Syntax}:
11552 @multitable @columnfractions .80
11553 @item @code{CALL SECOND(TIME)}
11554 @item @code{TIME = SECOND()}
11557 @item @emph{Arguments}:
11558 @multitable @columnfractions .15 .70
11559 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
11562 @item @emph{Return value}:
11563 In either syntax, @var{TIME} is set to the process's current runtime in
11566 @item @emph{See also}:
11573 @node SELECTED_CHAR_KIND
11574 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
11575 @fnindex SELECTED_CHAR_KIND
11576 @cindex character kind
11577 @cindex kind, character
11580 @item @emph{Description}:
11582 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
11583 set named @var{NAME}, if a character set with such a name is supported,
11584 or @math{-1} otherwise. Currently, supported character sets include
11585 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
11586 (Universal Character Set, UCS-4) which is commonly known as Unicode.
11588 @item @emph{Standard}:
11589 Fortran 2003 and later
11591 @item @emph{Class}:
11592 Transformational function
11594 @item @emph{Syntax}:
11595 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
11597 @item @emph{Arguments}:
11598 @multitable @columnfractions .15 .70
11599 @item @var{NAME} @tab Shall be a scalar and of the default character type.
11602 @item @emph{Example}:
11604 program character_kind
11605 use iso_fortran_env
11607 integer, parameter :: ascii = selected_char_kind ("ascii")
11608 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646')
11610 character(kind=ascii, len=26) :: alphabet
11611 character(kind=ucs4, len=30) :: hello_world
11613 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
11614 hello_world = ucs4_'Hello World and Ni Hao -- ' &
11615 // char (int (z'4F60'), ucs4) &
11616 // char (int (z'597D'), ucs4)
11618 write (*,*) alphabet
11620 open (output_unit, encoding='UTF-8')
11621 write (*,*) trim (hello_world)
11622 end program character_kind
11628 @node SELECTED_INT_KIND
11629 @section @code{SELECTED_INT_KIND} --- Choose integer kind
11630 @fnindex SELECTED_INT_KIND
11631 @cindex integer kind
11632 @cindex kind, integer
11635 @item @emph{Description}:
11636 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
11637 type that can represent all values ranging from @math{-10^R} (exclusive)
11638 to @math{10^R} (exclusive). If there is no integer kind that accommodates
11639 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
11641 @item @emph{Standard}:
11642 Fortran 95 and later
11644 @item @emph{Class}:
11645 Transformational function
11647 @item @emph{Syntax}:
11648 @code{RESULT = SELECTED_INT_KIND(R)}
11650 @item @emph{Arguments}:
11651 @multitable @columnfractions .15 .70
11652 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
11655 @item @emph{Example}:
11657 program large_integers
11658 integer,parameter :: k5 = selected_int_kind(5)
11659 integer,parameter :: k15 = selected_int_kind(15)
11660 integer(kind=k5) :: i5
11661 integer(kind=k15) :: i15
11663 print *, huge(i5), huge(i15)
11665 ! The following inequalities are always true
11666 print *, huge(i5) >= 10_k5**5-1
11667 print *, huge(i15) >= 10_k15**15-1
11668 end program large_integers
11674 @node SELECTED_REAL_KIND
11675 @section @code{SELECTED_REAL_KIND} --- Choose real kind
11676 @fnindex SELECTED_REAL_KIND
11679 @cindex radix, real
11682 @item @emph{Description}:
11683 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
11684 with decimal precision of at least @code{P} digits, exponent range of
11685 at least @code{R}, and with a radix of @code{RADIX}.
11687 @item @emph{Standard}:
11688 Fortran 95 and later, with @code{RADIX} Fortran 2008 or later
11690 @item @emph{Class}:
11691 Transformational function
11693 @item @emph{Syntax}:
11694 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
11696 @item @emph{Arguments}:
11697 @multitable @columnfractions .15 .70
11698 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
11699 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
11700 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
11702 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
11703 be present; since Fortran 2008, they are assumed to be zero if absent.
11705 @item @emph{Return value}:
11707 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
11708 a real data type with decimal precision of at least @code{P} digits, a
11709 decimal exponent range of at least @code{R}, and with the requested
11710 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
11711 any radix can be returned. If more than one real data type meet the
11712 criteria, the kind of the data type with the smallest decimal precision
11713 is returned. If no real data type matches the criteria, the result is
11715 @item -1 if the processor does not support a real data type with a
11716 precision greater than or equal to @code{P}, but the @code{R} and
11717 @code{RADIX} requirements can be fulfilled
11718 @item -2 if the processor does not support a real type with an exponent
11719 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
11721 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
11723 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
11725 @item -5 if there is no real type with the given @code{RADIX}
11728 @item @emph{See also}:
11729 @ref{PRECISION}, @ref{RANGE}, @ref{RADIX}
11731 @item @emph{Example}:
11734 integer,parameter :: p6 = selected_real_kind(6)
11735 integer,parameter :: p10r100 = selected_real_kind(10,100)
11736 integer,parameter :: r400 = selected_real_kind(r=400)
11738 real(kind=p10r100) :: y
11739 real(kind=r400) :: z
11741 print *, precision(x), range(x)
11742 print *, precision(y), range(y)
11743 print *, precision(z), range(z)
11744 end program real_kinds
11751 @section @code{SET_EXPONENT} --- Set the exponent of the model
11752 @fnindex SET_EXPONENT
11753 @cindex real number, set exponent
11754 @cindex floating point, set exponent
11757 @item @emph{Description}:
11758 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
11759 is that that of @var{X} and whose exponent part is @var{I}.
11761 @item @emph{Standard}:
11762 Fortran 95 and later
11764 @item @emph{Class}:
11767 @item @emph{Syntax}:
11768 @code{RESULT = SET_EXPONENT(X, I)}
11770 @item @emph{Arguments}:
11771 @multitable @columnfractions .15 .70
11772 @item @var{X} @tab Shall be of type @code{REAL}.
11773 @item @var{I} @tab Shall be of type @code{INTEGER}.
11776 @item @emph{Return value}:
11777 The return value is of the same type and kind as @var{X}.
11778 The real number whose fractional part
11779 is that that of @var{X} and whose exponent part if @var{I} is returned;
11780 it is @code{FRACTION(X) * RADIX(X)**I}.
11782 @item @emph{Example}:
11784 PROGRAM test_setexp
11785 REAL :: x = 178.1387e-4
11787 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
11796 @section @code{SHAPE} --- Determine the shape of an array
11798 @cindex array, shape
11801 @item @emph{Description}:
11802 Determines the shape of an array.
11804 @item @emph{Standard}:
11805 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11807 @item @emph{Class}:
11810 @item @emph{Syntax}:
11811 @code{RESULT = SHAPE(SOURCE [, KIND])}
11813 @item @emph{Arguments}:
11814 @multitable @columnfractions .15 .70
11815 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
11816 If @var{SOURCE} is a pointer it must be associated and allocatable
11817 arrays must be allocated.
11818 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11819 expression indicating the kind parameter of the result.
11822 @item @emph{Return value}:
11823 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
11824 has dimensions. The elements of the resulting array correspond to the extend
11825 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
11826 the result is the rank one array of size zero. If @var{KIND} is absent, the
11827 return value has the default integer kind otherwise the specified kind.
11829 @item @emph{Example}:
11832 INTEGER, DIMENSION(-1:1, -1:2) :: A
11833 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
11834 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
11838 @item @emph{See also}:
11839 @ref{RESHAPE}, @ref{SIZE}
11845 @section @code{SHIFTA} --- Right shift with fill
11847 @cindex bits, shift right
11848 @cindex shift, right with fill
11851 @item @emph{Description}:
11852 @code{SHIFTA} returns a value corresponding to @var{I} with all of the
11853 bits shifted right by @var{SHIFT} places. If the absolute value of
11854 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11855 Bits shifted out from the right end are lost. The fill is arithmetic: the
11856 bits shifted in from the left end are equal to the leftmost bit, which in
11857 two's complement representation is the sign bit.
11859 @item @emph{Standard}:
11860 Fortran 2008 and later
11862 @item @emph{Class}:
11865 @item @emph{Syntax}:
11866 @code{RESULT = SHIFTA(I, SHIFT)}
11868 @item @emph{Arguments}:
11869 @multitable @columnfractions .15 .70
11870 @item @var{I} @tab The type shall be @code{INTEGER}.
11871 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11874 @item @emph{Return value}:
11875 The return value is of type @code{INTEGER} and of the same kind as
11878 @item @emph{See also}:
11879 @ref{SHIFTL}, @ref{SHIFTR}
11885 @section @code{SHIFTL} --- Left shift
11887 @cindex bits, shift left
11888 @cindex shift, left
11891 @item @emph{Description}:
11892 @code{SHIFTL} returns a value corresponding to @var{I} with all of the
11893 bits shifted left by @var{SHIFT} places. If the absolute value of
11894 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11895 Bits shifted out from the left end are lost, and bits shifted in from
11896 the right end are set to 0.
11898 @item @emph{Standard}:
11899 Fortran 2008 and later
11901 @item @emph{Class}:
11904 @item @emph{Syntax}:
11905 @code{RESULT = SHIFTL(I, SHIFT)}
11907 @item @emph{Arguments}:
11908 @multitable @columnfractions .15 .70
11909 @item @var{I} @tab The type shall be @code{INTEGER}.
11910 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11913 @item @emph{Return value}:
11914 The return value is of type @code{INTEGER} and of the same kind as
11917 @item @emph{See also}:
11918 @ref{SHIFTA}, @ref{SHIFTR}
11924 @section @code{SHIFTR} --- Right shift
11926 @cindex bits, shift right
11927 @cindex shift, right
11930 @item @emph{Description}:
11931 @code{SHIFTR} returns a value corresponding to @var{I} with all of the
11932 bits shifted right by @var{SHIFT} places. If the absolute value of
11933 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11934 Bits shifted out from the right end are lost, and bits shifted in from
11935 the left end are set to 0.
11937 @item @emph{Standard}:
11938 Fortran 2008 and later
11940 @item @emph{Class}:
11943 @item @emph{Syntax}:
11944 @code{RESULT = SHIFTR(I, SHIFT)}
11946 @item @emph{Arguments}:
11947 @multitable @columnfractions .15 .70
11948 @item @var{I} @tab The type shall be @code{INTEGER}.
11949 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11952 @item @emph{Return value}:
11953 The return value is of type @code{INTEGER} and of the same kind as
11956 @item @emph{See also}:
11957 @ref{SHIFTA}, @ref{SHIFTL}
11963 @section @code{SIGN} --- Sign copying function
11967 @cindex sign copying
11970 @item @emph{Description}:
11971 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
11973 @item @emph{Standard}:
11974 Fortran 77 and later
11976 @item @emph{Class}:
11979 @item @emph{Syntax}:
11980 @code{RESULT = SIGN(A, B)}
11982 @item @emph{Arguments}:
11983 @multitable @columnfractions .15 .70
11984 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
11985 @item @var{B} @tab Shall be of the same type and kind as @var{A}
11988 @item @emph{Return value}:
11989 The kind of the return value is that of @var{A} and @var{B}.
11990 If @math{B\ge 0} then the result is @code{ABS(A)}, else
11991 it is @code{-ABS(A)}.
11993 @item @emph{Example}:
11996 print *, sign(-12,1)
11997 print *, sign(-12,0)
11998 print *, sign(-12,-1)
12000 print *, sign(-12.,1.)
12001 print *, sign(-12.,0.)
12002 print *, sign(-12.,-1.)
12003 end program test_sign
12006 @item @emph{Specific names}:
12007 @multitable @columnfractions .20 .20 .20 .25
12008 @item Name @tab Arguments @tab Return type @tab Standard
12009 @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu
12010 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
12011 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu
12018 @section @code{SIGNAL} --- Signal handling subroutine (or function)
12020 @cindex system, signal handling
12023 @item @emph{Description}:
12024 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
12025 @var{HANDLER} to be executed with a single integer argument when signal
12026 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
12027 turn off handling of signal @var{NUMBER} or revert to its default
12028 action. See @code{signal(2)}.
12030 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
12031 is supplied, it is set to the value returned by @code{signal(2)}.
12033 @item @emph{Standard}:
12036 @item @emph{Class}:
12037 Subroutine, function
12039 @item @emph{Syntax}:
12040 @multitable @columnfractions .80
12041 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
12042 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
12045 @item @emph{Arguments}:
12046 @multitable @columnfractions .15 .70
12047 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
12048 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
12049 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
12050 @code{INTEGER}. It is @code{INTENT(IN)}.
12051 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
12052 integer. It has @code{INTENT(OUT)}.
12054 @c TODO: What should the interface of the handler be? Does it take arguments?
12056 @item @emph{Return value}:
12057 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
12059 @item @emph{Example}:
12061 program test_signal
12063 external handler_print
12065 call signal (12, handler_print)
12066 call signal (10, 1)
12069 end program test_signal
12076 @section @code{SIN} --- Sine function
12082 @cindex trigonometric function, sine
12086 @item @emph{Description}:
12087 @code{SIN(X)} computes the sine of @var{X}.
12089 @item @emph{Standard}:
12090 Fortran 77 and later
12092 @item @emph{Class}:
12095 @item @emph{Syntax}:
12096 @code{RESULT = SIN(X)}
12098 @item @emph{Arguments}:
12099 @multitable @columnfractions .15 .70
12100 @item @var{X} @tab The type shall be @code{REAL} or
12104 @item @emph{Return value}:
12105 The return value has same type and kind as @var{X}.
12107 @item @emph{Example}:
12112 end program test_sin
12115 @item @emph{Specific names}:
12116 @multitable @columnfractions .20 .20 .20 .25
12117 @item Name @tab Argument @tab Return type @tab Standard
12118 @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu
12119 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
12120 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
12121 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
12122 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
12125 @item @emph{See also}:
12132 @section @code{SINH} --- Hyperbolic sine function
12135 @cindex hyperbolic sine
12136 @cindex hyperbolic function, sine
12137 @cindex sine, hyperbolic
12140 @item @emph{Description}:
12141 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
12143 @item @emph{Standard}:
12144 Fortran 95 and later, for a complex argument Fortran 2008 or later
12146 @item @emph{Class}:
12149 @item @emph{Syntax}:
12150 @code{RESULT = SINH(X)}
12152 @item @emph{Arguments}:
12153 @multitable @columnfractions .15 .70
12154 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
12157 @item @emph{Return value}:
12158 The return value has same type and kind as @var{X}.
12160 @item @emph{Example}:
12163 real(8) :: x = - 1.0_8
12165 end program test_sinh
12168 @item @emph{Specific names}:
12169 @multitable @columnfractions .20 .20 .20 .25
12170 @item Name @tab Argument @tab Return type @tab Standard
12171 @item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
12172 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
12175 @item @emph{See also}:
12182 @section @code{SIZE} --- Determine the size of an array
12184 @cindex array, size
12185 @cindex array, number of elements
12186 @cindex array, count elements
12189 @item @emph{Description}:
12190 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
12191 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
12193 @item @emph{Standard}:
12194 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12196 @item @emph{Class}:
12199 @item @emph{Syntax}:
12200 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
12202 @item @emph{Arguments}:
12203 @multitable @columnfractions .15 .70
12204 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
12205 a pointer it must be associated and allocatable arrays must be allocated.
12206 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
12207 and its value shall be in the range from 1 to n, where n equals the rank
12209 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12210 expression indicating the kind parameter of the result.
12213 @item @emph{Return value}:
12214 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12215 @var{KIND} is absent, the return value is of default integer kind.
12217 @item @emph{Example}:
12220 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
12224 @item @emph{See also}:
12225 @ref{SHAPE}, @ref{RESHAPE}
12230 @section @code{SIZEOF} --- Size in bytes of an expression
12232 @cindex expression size
12233 @cindex size of an expression
12236 @item @emph{Description}:
12237 @code{SIZEOF(X)} calculates the number of bytes of storage the
12238 expression @code{X} occupies.
12240 @item @emph{Standard}:
12243 @item @emph{Class}:
12246 @item @emph{Syntax}:
12247 @code{N = SIZEOF(X)}
12249 @item @emph{Arguments}:
12250 @multitable @columnfractions .15 .70
12251 @item @var{X} @tab The argument shall be of any type, rank or shape.
12254 @item @emph{Return value}:
12255 The return value is of type integer and of the system-dependent kind
12256 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
12257 number of bytes occupied by the argument. If the argument has the
12258 @code{POINTER} attribute, the number of bytes of the storage area pointed
12259 to is returned. If the argument is of a derived type with @code{POINTER}
12260 or @code{ALLOCATABLE} components, the return value does not account for
12261 the sizes of the data pointed to by these components. If the argument is
12262 polymorphic, the size according to the dynamic type is returned. The argument
12263 may not be a procedure or procedure pointer. Note that the code assumes for
12264 arrays that those are contiguous; for contiguous arrays, it returns the
12265 storage or an array element multiplied by the size of the array.
12267 @item @emph{Example}:
12271 print *, (sizeof(s)/sizeof(r) == 5)
12274 The example will print @code{.TRUE.} unless you are using a platform
12275 where default @code{REAL} variables are unusually padded.
12277 @item @emph{See also}:
12278 @ref{C_SIZEOF}, @ref{STORAGE_SIZE}
12283 @section @code{SLEEP} --- Sleep for the specified number of seconds
12285 @cindex delayed execution
12288 @item @emph{Description}:
12289 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
12291 @item @emph{Standard}:
12294 @item @emph{Class}:
12297 @item @emph{Syntax}:
12298 @code{CALL SLEEP(SECONDS)}
12300 @item @emph{Arguments}:
12301 @multitable @columnfractions .15 .70
12302 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
12305 @item @emph{Example}:
12316 @section @code{SPACING} --- Smallest distance between two numbers of a given type
12318 @cindex real number, relative spacing
12319 @cindex floating point, relative spacing
12322 @item @emph{Description}:
12323 Determines the distance between the argument @var{X} and the nearest
12324 adjacent number of the same type.
12326 @item @emph{Standard}:
12327 Fortran 95 and later
12329 @item @emph{Class}:
12332 @item @emph{Syntax}:
12333 @code{RESULT = SPACING(X)}
12335 @item @emph{Arguments}:
12336 @multitable @columnfractions .15 .70
12337 @item @var{X} @tab Shall be of type @code{REAL}.
12340 @item @emph{Return value}:
12341 The result is of the same type as the input argument @var{X}.
12343 @item @emph{Example}:
12345 PROGRAM test_spacing
12346 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
12347 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
12349 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
12350 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
12354 @item @emph{See also}:
12361 @section @code{SPREAD} --- Add a dimension to an array
12363 @cindex array, increase dimension
12364 @cindex array, duplicate elements
12365 @cindex array, duplicate dimensions
12368 @item @emph{Description}:
12369 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
12370 dimension @var{DIM}.
12372 @item @emph{Standard}:
12373 Fortran 95 and later
12375 @item @emph{Class}:
12376 Transformational function
12378 @item @emph{Syntax}:
12379 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
12381 @item @emph{Arguments}:
12382 @multitable @columnfractions .15 .70
12383 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
12384 a rank less than seven.
12385 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
12386 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
12387 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
12390 @item @emph{Return value}:
12391 The result is an array of the same type as @var{SOURCE} and has rank n+1
12392 where n equals the rank of @var{SOURCE}.
12394 @item @emph{Example}:
12396 PROGRAM test_spread
12397 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
12398 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
12399 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
12403 @item @emph{See also}:
12410 @section @code{SQRT} --- Square-root function
12417 @cindex square-root
12420 @item @emph{Description}:
12421 @code{SQRT(X)} computes the square root of @var{X}.
12423 @item @emph{Standard}:
12424 Fortran 77 and later
12426 @item @emph{Class}:
12429 @item @emph{Syntax}:
12430 @code{RESULT = SQRT(X)}
12432 @item @emph{Arguments}:
12433 @multitable @columnfractions .15 .70
12434 @item @var{X} @tab The type shall be @code{REAL} or
12438 @item @emph{Return value}:
12439 The return value is of type @code{REAL} or @code{COMPLEX}.
12440 The kind type parameter is the same as @var{X}.
12442 @item @emph{Example}:
12445 real(8) :: x = 2.0_8
12446 complex :: z = (1.0, 2.0)
12449 end program test_sqrt
12452 @item @emph{Specific names}:
12453 @multitable @columnfractions .20 .20 .20 .25
12454 @item Name @tab Argument @tab Return type @tab Standard
12455 @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
12456 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
12457 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
12458 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
12459 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
12466 @section @code{SRAND} --- Reinitialize the random number generator
12468 @cindex random number generation, seeding
12469 @cindex seeding a random number generator
12472 @item @emph{Description}:
12473 @code{SRAND} reinitializes the pseudo-random number generator
12474 called by @code{RAND} and @code{IRAND}. The new seed used by the
12475 generator is specified by the required argument @var{SEED}.
12477 @item @emph{Standard}:
12480 @item @emph{Class}:
12483 @item @emph{Syntax}:
12484 @code{CALL SRAND(SEED)}
12486 @item @emph{Arguments}:
12487 @multitable @columnfractions .15 .70
12488 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
12491 @item @emph{Return value}:
12492 Does not return anything.
12494 @item @emph{Example}:
12495 See @code{RAND} and @code{IRAND} for examples.
12497 @item @emph{Notes}:
12498 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
12499 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
12500 to generate pseudo-random numbers. Please note that in
12501 GNU Fortran, these two sets of intrinsics (@code{RAND},
12502 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
12503 @code{RANDOM_SEED} on the other hand) access two independent
12504 pseudo-random number generators.
12506 @item @emph{See also}:
12507 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
12514 @section @code{STAT} --- Get file status
12516 @cindex file system, file status
12519 @item @emph{Description}:
12520 This function returns information about a file. No permissions are required on
12521 the file itself, but execute (search) permission is required on all of the
12522 directories in path that lead to the file.
12524 The elements that are obtained and stored in the array @code{VALUES}:
12525 @multitable @columnfractions .15 .70
12526 @item @code{VALUES(1)} @tab Device ID
12527 @item @code{VALUES(2)} @tab Inode number
12528 @item @code{VALUES(3)} @tab File mode
12529 @item @code{VALUES(4)} @tab Number of links
12530 @item @code{VALUES(5)} @tab Owner's uid
12531 @item @code{VALUES(6)} @tab Owner's gid
12532 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
12533 @item @code{VALUES(8)} @tab File size (bytes)
12534 @item @code{VALUES(9)} @tab Last access time
12535 @item @code{VALUES(10)} @tab Last modification time
12536 @item @code{VALUES(11)} @tab Last file status change time
12537 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
12538 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
12541 Not all these elements are relevant on all systems.
12542 If an element is not relevant, it is returned as 0.
12544 This intrinsic is provided in both subroutine and function forms; however,
12545 only one form can be used in any given program unit.
12547 @item @emph{Standard}:
12550 @item @emph{Class}:
12551 Subroutine, function
12553 @item @emph{Syntax}:
12554 @multitable @columnfractions .80
12555 @item @code{CALL STAT(NAME, VALUES [, STATUS])}
12556 @item @code{STATUS = STAT(NAME, VALUES)}
12559 @item @emph{Arguments}:
12560 @multitable @columnfractions .15 .70
12561 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
12562 default kind and a valid path within the file system.
12563 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
12564 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
12565 on success and a system specific error code otherwise.
12568 @item @emph{Example}:
12571 INTEGER, DIMENSION(13) :: buff
12574 CALL STAT("/etc/passwd", buff, status)
12576 IF (status == 0) THEN
12577 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
12578 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
12579 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
12580 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
12581 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
12582 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
12583 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
12584 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
12585 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
12586 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
12587 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
12588 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
12589 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
12594 @item @emph{See also}:
12595 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
12601 @section @code{STORAGE_SIZE} --- Storage size in bits
12602 @fnindex STORAGE_SIZE
12603 @cindex storage size
12606 @item @emph{Description}:
12607 Returns the storage size of argument @var{A} in bits.
12608 @item @emph{Standard}:
12609 Fortran 2008 and later
12610 @item @emph{Class}:
12612 @item @emph{Syntax}:
12613 @code{RESULT = STORAGE_SIZE(A [, KIND])}
12615 @item @emph{Arguments}:
12616 @multitable @columnfractions .15 .70
12617 @item @var{A} @tab Shall be a scalar or array of any type.
12618 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
12621 @item @emph{Return Value}:
12622 The result is a scalar integer with the kind type parameter specified by KIND
12623 (or default integer type if KIND is missing). The result value is the size
12624 expressed in bits for an element of an array that has the dynamic type and type
12627 @item @emph{See also}:
12628 @ref{C_SIZEOF}, @ref{SIZEOF}
12634 @section @code{SUM} --- Sum of array elements
12637 @cindex array, add elements
12638 @cindex array, conditionally add elements
12639 @cindex sum array elements
12642 @item @emph{Description}:
12643 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
12644 the corresponding element in @var{MASK} is @code{TRUE}.
12646 @item @emph{Standard}:
12647 Fortran 95 and later
12649 @item @emph{Class}:
12650 Transformational function
12652 @item @emph{Syntax}:
12653 @multitable @columnfractions .80
12654 @item @code{RESULT = SUM(ARRAY[, MASK])}
12655 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
12658 @item @emph{Arguments}:
12659 @multitable @columnfractions .15 .70
12660 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
12661 @code{REAL} or @code{COMPLEX}.
12662 @item @var{DIM} @tab (Optional) shall be a scalar of type
12663 @code{INTEGER} with a value in the range from 1 to n, where n
12664 equals the rank of @var{ARRAY}.
12665 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
12666 and either be a scalar or an array of the same shape as @var{ARRAY}.
12669 @item @emph{Return value}:
12670 The result is of the same type as @var{ARRAY}.
12672 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
12673 is returned. Otherwise, an array of rank n-1, where n equals the rank of
12674 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
12675 dropped is returned.
12677 @item @emph{Example}:
12680 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
12681 print *, SUM(x) ! all elements, sum = 15
12682 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
12686 @item @emph{See also}:
12693 @section @code{SYMLNK} --- Create a symbolic link
12695 @cindex file system, create link
12696 @cindex file system, soft link
12699 @item @emph{Description}:
12700 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
12701 character (@code{CHAR(0)}) can be used to mark the end of the names in
12702 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
12703 names are ignored. If the @var{STATUS} argument is supplied, it
12704 contains 0 on success or a nonzero error code upon return; see
12705 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
12706 @code{ENOSYS} is returned.
12708 This intrinsic is provided in both subroutine and function forms;
12709 however, only one form can be used in any given program unit.
12711 @item @emph{Standard}:
12714 @item @emph{Class}:
12715 Subroutine, function
12717 @item @emph{Syntax}:
12718 @multitable @columnfractions .80
12719 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
12720 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
12723 @item @emph{Arguments}:
12724 @multitable @columnfractions .15 .70
12725 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
12726 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
12727 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12730 @item @emph{See also}:
12731 @ref{LINK}, @ref{UNLINK}
12738 @section @code{SYSTEM} --- Execute a shell command
12740 @cindex system, system call
12743 @item @emph{Description}:
12744 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
12745 argument @var{STATUS} is present, it contains the value returned by
12746 @code{system(3)}, which is presumably 0 if the shell command succeeded.
12747 Note that which shell is used to invoke the command is system-dependent
12748 and environment-dependent.
12750 This intrinsic is provided in both subroutine and function forms;
12751 however, only one form can be used in any given program unit.
12753 Note that the @code{system} function need not be thread-safe. It is
12754 the responsibility of the user to ensure that @code{system} is not
12755 called concurrently.
12757 @item @emph{Standard}:
12760 @item @emph{Class}:
12761 Subroutine, function
12763 @item @emph{Syntax}:
12764 @multitable @columnfractions .80
12765 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
12766 @item @code{STATUS = SYSTEM(COMMAND)}
12769 @item @emph{Arguments}:
12770 @multitable @columnfractions .15 .70
12771 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
12772 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12775 @item @emph{See also}:
12776 @ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
12777 and should considered in new code for future portability.
12783 @section @code{SYSTEM_CLOCK} --- Time function
12784 @fnindex SYSTEM_CLOCK
12785 @cindex time, clock ticks
12786 @cindex clock ticks
12789 @item @emph{Description}:
12790 Determines the @var{COUNT} of a processor clock since an unspecified
12791 time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines
12792 the number of clock ticks per second. If the platform supports a
12793 monotonic clock, that clock is used and can, depending on the platform
12794 clock implementation, provide up to nanosecond resolution. If a
12795 monotonic clock is not available, the implementation falls back to a
12798 @var{COUNT_RATE} is system dependent and can vary depending on the kind of
12799 the arguments. For @var{kind=4} arguments (and smaller integer kinds),
12800 @var{COUNT} represents milliseconds, while for @var{kind=8} arguments (and
12801 larger integer kinds), @var{COUNT} typically represents micro- or
12802 nanoseconds depending on resolution of the underlying platform clock.
12803 @var{COUNT_MAX} usually equals @code{HUGE(COUNT_MAX)}. Note that the
12804 millisecond resolution of the @var{kind=4} version implies that the
12805 @var{COUNT} will wrap around in roughly 25 days. In order to avoid issues
12806 with the wrap around and for more precise timing, please use the
12807 @var{kind=8} version.
12809 If there is no clock, or querying the clock fails, @var{COUNT} is set
12810 to @code{-HUGE(COUNT)}, and @var{COUNT_RATE} and @var{COUNT_MAX} are
12813 When running on a platform using the GNU C library (glibc) version
12814 2.16 or older, or a derivative thereof, the high resolution monotonic
12815 clock is available only when linking with the @var{rt} library. This
12816 can be done explicitly by adding the @code{-lrt} flag when linking the
12817 application, but is also done implicitly when using OpenMP.
12819 On the Windows platform, the version with @var{kind=4} arguments uses
12820 the @code{GetTickCount} function, whereas the @var{kind=8} version
12821 uses @code{QueryPerformanceCounter} and
12822 @code{QueryPerformanceCounterFrequency}. For more information, and
12823 potential caveats, please see the platform documentation.
12825 @item @emph{Standard}:
12826 Fortran 95 and later
12828 @item @emph{Class}:
12831 @item @emph{Syntax}:
12832 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
12834 @item @emph{Arguments}:
12835 @multitable @columnfractions .15 .70
12836 @item @var{COUNT} @tab (Optional) shall be a scalar of type
12837 @code{INTEGER} with @code{INTENT(OUT)}.
12838 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type
12839 @code{INTEGER} or @code{REAL}, with @code{INTENT(OUT)}.
12840 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type
12841 @code{INTEGER} with @code{INTENT(OUT)}.
12844 @item @emph{Example}:
12846 PROGRAM test_system_clock
12847 INTEGER :: count, count_rate, count_max
12848 CALL SYSTEM_CLOCK(count, count_rate, count_max)
12849 WRITE(*,*) count, count_rate, count_max
12853 @item @emph{See also}:
12854 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
12860 @section @code{TAN} --- Tangent function
12863 @cindex trigonometric function, tangent
12867 @item @emph{Description}:
12868 @code{TAN(X)} computes the tangent of @var{X}.
12870 @item @emph{Standard}:
12871 Fortran 77 and later, for a complex argument Fortran 2008 or later
12873 @item @emph{Class}:
12876 @item @emph{Syntax}:
12877 @code{RESULT = TAN(X)}
12879 @item @emph{Arguments}:
12880 @multitable @columnfractions .15 .70
12881 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
12884 @item @emph{Return value}:
12885 The return value has same type and kind as @var{X}.
12887 @item @emph{Example}:
12890 real(8) :: x = 0.165_8
12892 end program test_tan
12895 @item @emph{Specific names}:
12896 @multitable @columnfractions .20 .20 .20 .25
12897 @item Name @tab Argument @tab Return type @tab Standard
12898 @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
12899 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
12902 @item @emph{See also}:
12909 @section @code{TANH} --- Hyperbolic tangent function
12912 @cindex hyperbolic tangent
12913 @cindex hyperbolic function, tangent
12914 @cindex tangent, hyperbolic
12917 @item @emph{Description}:
12918 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
12920 @item @emph{Standard}:
12921 Fortran 77 and later, for a complex argument Fortran 2008 or later
12923 @item @emph{Class}:
12926 @item @emph{Syntax}:
12929 @item @emph{Arguments}:
12930 @multitable @columnfractions .15 .70
12931 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
12934 @item @emph{Return value}:
12935 The return value has same type and kind as @var{X}. If @var{X} is
12936 complex, the imaginary part of the result is in radians. If @var{X}
12937 is @code{REAL}, the return value lies in the range
12938 @math{ - 1 \leq tanh(x) \leq 1 }.
12940 @item @emph{Example}:
12943 real(8) :: x = 2.1_8
12945 end program test_tanh
12948 @item @emph{Specific names}:
12949 @multitable @columnfractions .20 .20 .20 .25
12950 @item Name @tab Argument @tab Return type @tab Standard
12951 @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
12952 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
12955 @item @emph{See also}:
12962 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
12963 @fnindex THIS_IMAGE
12964 @cindex coarray, @code{THIS_IMAGE}
12965 @cindex images, index of this image
12968 @item @emph{Description}:
12969 Returns the cosubscript for this image.
12971 @item @emph{Standard}:
12972 Fortran 2008 and later. With @var{DISTANCE} argument,
12973 Technical Specification (TS) 18508 or later
12975 @item @emph{Class}:
12976 Transformational function
12978 @item @emph{Syntax}:
12979 @multitable @columnfractions .80
12980 @item @code{RESULT = THIS_IMAGE()}
12981 @item @code{RESULT = THIS_IMAGE(DISTANCE)}
12982 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
12985 @item @emph{Arguments}:
12986 @multitable @columnfractions .15 .70
12987 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
12988 (not permitted together with @var{COARRAY}).
12989 @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
12990 present, required).
12991 @item @var{DIM} @tab default integer scalar (optional). If present,
12992 @var{DIM} shall be between one and the corank of @var{COARRAY}.
12996 @item @emph{Return value}:
12997 Default integer. If @var{COARRAY} is not present, it is scalar; if
12998 @var{DISTANCE} is not present or has value 0, its value is the image index on
12999 the invoking image for the current team, for values smaller or equal
13000 distance to the initial team, it returns the image index on the ancestor team
13001 which has a distance of @var{DISTANCE} from the invoking team. If
13002 @var{DISTANCE} is larger than the distance to the initial team, the image
13003 index of the initial team is returned. Otherwise when the @var{COARRAY} is
13004 present, if @var{DIM} is not present, a rank-1 array with corank elements is
13005 returned, containing the cosubscripts for @var{COARRAY} specifying the invoking
13006 image. If @var{DIM} is present, a scalar is returned, with the value of
13007 the @var{DIM} element of @code{THIS_IMAGE(COARRAY)}.
13009 @item @emph{Example}:
13011 INTEGER :: value[*]
13013 value = THIS_IMAGE()
13015 IF (THIS_IMAGE() == 1) THEN
13016 DO i = 1, NUM_IMAGES()
13017 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
13021 ! Check whether the current image is the initial image
13022 IF (THIS_IMAGE(HUGE(1)) /= THIS_IMAGE())
13023 error stop "something is rotten here"
13026 @item @emph{See also}:
13027 @ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
13033 @section @code{TIME} --- Time function
13035 @cindex time, current
13036 @cindex current time
13039 @item @emph{Description}:
13040 Returns the current time encoded as an integer (in the manner of the
13041 function @code{time(3)} in the C standard library). This value is
13042 suitable for passing to @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
13044 This intrinsic is not fully portable, such as to systems with 32-bit
13045 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
13046 the values returned by this intrinsic might be, or become, negative, or
13047 numerically less than previous values, during a single run of the
13050 See @ref{TIME8}, for information on a similar intrinsic that might be
13051 portable to more GNU Fortran implementations, though to fewer Fortran
13054 @item @emph{Standard}:
13057 @item @emph{Class}:
13060 @item @emph{Syntax}:
13061 @code{RESULT = TIME()}
13063 @item @emph{Return value}:
13064 The return value is a scalar of type @code{INTEGER(4)}.
13066 @item @emph{See also}:
13067 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
13074 @section @code{TIME8} --- Time function (64-bit)
13076 @cindex time, current
13077 @cindex current time
13080 @item @emph{Description}:
13081 Returns the current time encoded as an integer (in the manner of the
13082 function @code{time(3)} in the C standard library). This value is
13083 suitable for passing to @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
13085 @emph{Warning:} this intrinsic does not increase the range of the timing
13086 values over that returned by @code{time(3)}. On a system with a 32-bit
13087 @code{time(3)}, @code{TIME8} will return a 32-bit value, even though
13088 it is converted to a 64-bit @code{INTEGER(8)} value. That means
13089 overflows of the 32-bit value can still occur. Therefore, the values
13090 returned by this intrinsic might be or become negative or numerically
13091 less than previous values during a single run of the compiled program.
13093 @item @emph{Standard}:
13096 @item @emph{Class}:
13099 @item @emph{Syntax}:
13100 @code{RESULT = TIME8()}
13102 @item @emph{Return value}:
13103 The return value is a scalar of type @code{INTEGER(8)}.
13105 @item @emph{See also}:
13106 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
13113 @section @code{TINY} --- Smallest positive number of a real kind
13115 @cindex limits, smallest number
13116 @cindex model representation, smallest number
13119 @item @emph{Description}:
13120 @code{TINY(X)} returns the smallest positive (non zero) number
13121 in the model of the type of @code{X}.
13123 @item @emph{Standard}:
13124 Fortran 95 and later
13126 @item @emph{Class}:
13129 @item @emph{Syntax}:
13130 @code{RESULT = TINY(X)}
13132 @item @emph{Arguments}:
13133 @multitable @columnfractions .15 .70
13134 @item @var{X} @tab Shall be of type @code{REAL}.
13137 @item @emph{Return value}:
13138 The return value is of the same type and kind as @var{X}
13140 @item @emph{Example}:
13141 See @code{HUGE} for an example.
13147 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
13152 @item @emph{Description}:
13153 @code{TRAILZ} returns the number of trailing zero bits of an integer.
13155 @item @emph{Standard}:
13156 Fortran 2008 and later
13158 @item @emph{Class}:
13161 @item @emph{Syntax}:
13162 @code{RESULT = TRAILZ(I)}
13164 @item @emph{Arguments}:
13165 @multitable @columnfractions .15 .70
13166 @item @var{I} @tab Shall be of type @code{INTEGER}.
13169 @item @emph{Return value}:
13170 The type of the return value is the default @code{INTEGER}.
13171 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
13173 @item @emph{Example}:
13175 PROGRAM test_trailz
13176 WRITE (*,*) TRAILZ(8) ! prints 3
13180 @item @emph{See also}:
13181 @ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT}
13187 @section @code{TRANSFER} --- Transfer bit patterns
13193 @item @emph{Description}:
13194 Interprets the bitwise representation of @var{SOURCE} in memory as if it
13195 is the representation of a variable or array of the same type and type
13196 parameters as @var{MOLD}.
13198 This is approximately equivalent to the C concept of @emph{casting} one
13201 @item @emph{Standard}:
13202 Fortran 95 and later
13204 @item @emph{Class}:
13205 Transformational function
13207 @item @emph{Syntax}:
13208 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
13210 @item @emph{Arguments}:
13211 @multitable @columnfractions .15 .70
13212 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
13213 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
13214 @item @var{SIZE} @tab (Optional) shall be a scalar of type
13218 @item @emph{Return value}:
13219 The result has the same type as @var{MOLD}, with the bit level
13220 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
13221 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
13222 but @var{MOLD} is an array (of any size or shape), the result is a one-
13223 dimensional array of the minimum length needed to contain the entirety
13224 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
13225 and @var{MOLD} is a scalar, the result is a scalar.
13227 If the bitwise representation of the result is longer than that of
13228 @var{SOURCE}, then the leading bits of the result correspond to those of
13229 @var{SOURCE} and any trailing bits are filled arbitrarily.
13231 When the resulting bit representation does not correspond to a valid
13232 representation of a variable of the same type as @var{MOLD}, the results
13233 are undefined, and subsequent operations on the result cannot be
13234 guaranteed to produce sensible behavior. For example, it is possible to
13235 create @code{LOGICAL} variables for which @code{@var{VAR}} and
13236 @code{.NOT.@var{VAR}} both appear to be true.
13238 @item @emph{Example}:
13240 PROGRAM test_transfer
13241 integer :: x = 2143289344
13242 print *, transfer(x, 1.0) ! prints "NaN" on i686
13250 @section @code{TRANSPOSE} --- Transpose an array of rank two
13252 @cindex array, transpose
13253 @cindex matrix, transpose
13257 @item @emph{Description}:
13258 Transpose an array of rank two. Element (i, j) of the result has the value
13259 @code{MATRIX(j, i)}, for all i, j.
13261 @item @emph{Standard}:
13262 Fortran 95 and later
13264 @item @emph{Class}:
13265 Transformational function
13267 @item @emph{Syntax}:
13268 @code{RESULT = TRANSPOSE(MATRIX)}
13270 @item @emph{Arguments}:
13271 @multitable @columnfractions .15 .70
13272 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
13275 @item @emph{Return value}:
13276 The result has the same type as @var{MATRIX}, and has shape
13277 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
13283 @section @code{TRIM} --- Remove trailing blank characters of a string
13285 @cindex string, remove trailing whitespace
13288 @item @emph{Description}:
13289 Removes trailing blank characters of a string.
13291 @item @emph{Standard}:
13292 Fortran 95 and later
13294 @item @emph{Class}:
13295 Transformational function
13297 @item @emph{Syntax}:
13298 @code{RESULT = TRIM(STRING)}
13300 @item @emph{Arguments}:
13301 @multitable @columnfractions .15 .70
13302 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
13305 @item @emph{Return value}:
13306 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
13307 less the number of trailing blanks.
13309 @item @emph{Example}:
13312 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
13313 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
13317 @item @emph{See also}:
13318 @ref{ADJUSTL}, @ref{ADJUSTR}
13324 @section @code{TTYNAM} --- Get the name of a terminal device.
13326 @cindex system, terminal
13329 @item @emph{Description}:
13330 Get the name of a terminal device. For more information,
13331 see @code{ttyname(3)}.
13333 This intrinsic is provided in both subroutine and function forms;
13334 however, only one form can be used in any given program unit.
13336 @item @emph{Standard}:
13339 @item @emph{Class}:
13340 Subroutine, function
13342 @item @emph{Syntax}:
13343 @multitable @columnfractions .80
13344 @item @code{CALL TTYNAM(UNIT, NAME)}
13345 @item @code{NAME = TTYNAM(UNIT)}
13348 @item @emph{Arguments}:
13349 @multitable @columnfractions .15 .70
13350 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
13351 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
13354 @item @emph{Example}:
13356 PROGRAM test_ttynam
13359 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
13364 @item @emph{See also}:
13371 @section @code{UBOUND} --- Upper dimension bounds of an array
13373 @cindex array, upper bound
13376 @item @emph{Description}:
13377 Returns the upper bounds of an array, or a single upper bound
13378 along the @var{DIM} dimension.
13379 @item @emph{Standard}:
13380 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
13382 @item @emph{Class}:
13385 @item @emph{Syntax}:
13386 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
13388 @item @emph{Arguments}:
13389 @multitable @columnfractions .15 .70
13390 @item @var{ARRAY} @tab Shall be an array, of any type.
13391 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
13392 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
13393 expression indicating the kind parameter of the result.
13396 @item @emph{Return value}:
13397 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
13398 @var{KIND} is absent, the return value is of default integer kind.
13399 If @var{DIM} is absent, the result is an array of the upper bounds of
13400 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
13401 corresponding to the upper bound of the array along that dimension. If
13402 @var{ARRAY} is an expression rather than a whole array or array
13403 structure component, or if it has a zero extent along the relevant
13404 dimension, the upper bound is taken to be the number of elements along
13405 the relevant dimension.
13407 @item @emph{See also}:
13408 @ref{LBOUND}, @ref{LCOBOUND}
13414 @section @code{UCOBOUND} --- Upper codimension bounds of an array
13416 @cindex coarray, upper bound
13419 @item @emph{Description}:
13420 Returns the upper cobounds of a coarray, or a single upper cobound
13421 along the @var{DIM} codimension.
13422 @item @emph{Standard}:
13423 Fortran 2008 and later
13425 @item @emph{Class}:
13428 @item @emph{Syntax}:
13429 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
13431 @item @emph{Arguments}:
13432 @multitable @columnfractions .15 .70
13433 @item @var{ARRAY} @tab Shall be an coarray, of any type.
13434 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
13435 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
13436 expression indicating the kind parameter of the result.
13439 @item @emph{Return value}:
13440 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
13441 @var{KIND} is absent, the return value is of default integer kind.
13442 If @var{DIM} is absent, the result is an array of the lower cobounds of
13443 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
13444 corresponding to the lower cobound of the array along that codimension.
13446 @item @emph{See also}:
13447 @ref{LCOBOUND}, @ref{LBOUND}
13453 @section @code{UMASK} --- Set the file creation mask
13455 @cindex file system, file creation mask
13458 @item @emph{Description}:
13459 Sets the file creation mask to @var{MASK}. If called as a function, it
13460 returns the old value. If called as a subroutine and argument @var{OLD}
13461 if it is supplied, it is set to the old value. See @code{umask(2)}.
13463 @item @emph{Standard}:
13466 @item @emph{Class}:
13467 Subroutine, function
13469 @item @emph{Syntax}:
13470 @multitable @columnfractions .80
13471 @item @code{CALL UMASK(MASK [, OLD])}
13472 @item @code{OLD = UMASK(MASK)}
13475 @item @emph{Arguments}:
13476 @multitable @columnfractions .15 .70
13477 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
13478 @item @var{OLD} @tab (Optional) Shall be a scalar of type
13487 @section @code{UNLINK} --- Remove a file from the file system
13489 @cindex file system, remove file
13492 @item @emph{Description}:
13493 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
13494 used to mark the end of the name in @var{PATH}; otherwise, trailing
13495 blanks in the file name are ignored. If the @var{STATUS} argument is
13496 supplied, it contains 0 on success or a nonzero error code upon return;
13497 see @code{unlink(2)}.
13499 This intrinsic is provided in both subroutine and function forms;
13500 however, only one form can be used in any given program unit.
13502 @item @emph{Standard}:
13505 @item @emph{Class}:
13506 Subroutine, function
13508 @item @emph{Syntax}:
13509 @multitable @columnfractions .80
13510 @item @code{CALL UNLINK(PATH [, STATUS])}
13511 @item @code{STATUS = UNLINK(PATH)}
13514 @item @emph{Arguments}:
13515 @multitable @columnfractions .15 .70
13516 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
13517 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
13520 @item @emph{See also}:
13521 @ref{LINK}, @ref{SYMLNK}
13527 @section @code{UNPACK} --- Unpack an array of rank one into an array
13529 @cindex array, unpacking
13530 @cindex array, increase dimension
13531 @cindex array, scatter elements
13534 @item @emph{Description}:
13535 Store the elements of @var{VECTOR} in an array of higher rank.
13537 @item @emph{Standard}:
13538 Fortran 95 and later
13540 @item @emph{Class}:
13541 Transformational function
13543 @item @emph{Syntax}:
13544 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
13546 @item @emph{Arguments}:
13547 @multitable @columnfractions .15 .70
13548 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
13549 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
13550 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
13551 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
13552 the same shape as @var{MASK}.
13555 @item @emph{Return value}:
13556 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
13557 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
13559 @item @emph{Example}:
13561 PROGRAM test_unpack
13562 integer :: vector(2) = (/1,1/)
13563 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
13564 integer :: field(2,2) = 0, unity(2,2)
13566 ! result: unity matrix
13567 unity = unpack(vector, reshape(mask, (/2,2/)), field)
13571 @item @emph{See also}:
13572 @ref{PACK}, @ref{SPREAD}
13578 @section @code{VERIFY} --- Scan a string for characters not a given set
13580 @cindex string, find missing set
13583 @item @emph{Description}:
13584 Verifies that all the characters in @var{STRING} belong to the set of
13585 characters in @var{SET}.
13587 If @var{BACK} is either absent or equals @code{FALSE}, this function
13588 returns the position of the leftmost character of @var{STRING} that is
13589 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost
13590 position is returned. If all characters of @var{STRING} are found in
13591 @var{SET}, the result is zero.
13593 @item @emph{Standard}:
13594 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
13596 @item @emph{Class}:
13599 @item @emph{Syntax}:
13600 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
13602 @item @emph{Arguments}:
13603 @multitable @columnfractions .15 .70
13604 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
13605 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
13606 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
13607 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
13608 expression indicating the kind parameter of the result.
13611 @item @emph{Return value}:
13612 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
13613 @var{KIND} is absent, the return value is of default integer kind.
13615 @item @emph{Example}:
13617 PROGRAM test_verify
13618 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
13619 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
13620 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
13621 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
13622 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
13626 @item @emph{See also}:
13627 @ref{SCAN}, @ref{INDEX intrinsic}
13633 @section @code{XOR} --- Bitwise logical exclusive OR
13635 @cindex bitwise logical exclusive or
13636 @cindex logical exclusive or, bitwise
13639 @item @emph{Description}:
13640 Bitwise logical exclusive or.
13642 This intrinsic routine is provided for backwards compatibility with
13643 GNU Fortran 77. For integer arguments, programmers should consider
13644 the use of the @ref{IEOR} intrinsic and for logical arguments the
13645 @code{.NEQV.} operator, which are both defined by the Fortran standard.
13647 @item @emph{Standard}:
13650 @item @emph{Class}:
13653 @item @emph{Syntax}:
13654 @code{RESULT = XOR(I, J)}
13656 @item @emph{Arguments}:
13657 @multitable @columnfractions .15 .70
13658 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
13659 type or a scalar @code{LOGICAL} type.
13660 @item @var{J} @tab The type shall be the same as the type of @var{I}.
13663 @item @emph{Return value}:
13664 The return type is either a scalar @code{INTEGER} or a scalar
13665 @code{LOGICAL}. If the kind type parameters differ, then the
13666 smaller kind type is implicitly converted to larger kind, and the
13667 return has the larger kind.
13669 @item @emph{Example}:
13672 LOGICAL :: T = .TRUE., F = .FALSE.
13674 DATA a / Z'F' /, b / Z'3' /
13676 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
13677 WRITE (*,*) XOR(a, b)
13681 @item @emph{See also}:
13682 Fortran 95 elemental function: @ref{IEOR}
13687 @node Intrinsic Modules
13688 @chapter Intrinsic Modules
13689 @cindex intrinsic Modules
13692 * ISO_FORTRAN_ENV::
13695 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
13698 @node ISO_FORTRAN_ENV
13699 @section @code{ISO_FORTRAN_ENV}
13701 @item @emph{Standard}:
13702 Fortran 2003 and later, except when otherwise noted
13705 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
13709 @item @code{ATOMIC_INT_KIND}:
13710 Default-kind integer constant to be used as kind parameter when defining
13711 integer variables used in atomic operations. (Fortran 2008 or later.)
13713 @item @code{ATOMIC_LOGICAL_KIND}:
13714 Default-kind integer constant to be used as kind parameter when defining
13715 logical variables used in atomic operations. (Fortran 2008 or later.)
13717 @item @code{CHARACTER_KINDS}:
13718 Default-kind integer constant array of rank one containing the supported kind
13719 parameters of the @code{CHARACTER} type. (Fortran 2008 or later.)
13721 @item @code{CHARACTER_STORAGE_SIZE}:
13722 Size in bits of the character storage unit.
13724 @item @code{ERROR_UNIT}:
13725 Identifies the preconnected unit used for error reporting.
13727 @item @code{FILE_STORAGE_SIZE}:
13728 Size in bits of the file-storage unit.
13730 @item @code{INPUT_UNIT}:
13731 Identifies the preconnected unit identified by the asterisk
13732 (@code{*}) in @code{READ} statement.
13734 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
13735 Kind type parameters to specify an INTEGER type with a storage
13736 size of 16, 32, and 64 bits. It is negative if a target platform
13737 does not support the particular kind. (Fortran 2008 or later.)
13739 @item @code{INTEGER_KINDS}:
13740 Default-kind integer constant array of rank one containing the supported kind
13741 parameters of the @code{INTEGER} type. (Fortran 2008 or later.)
13743 @item @code{IOSTAT_END}:
13744 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
13745 an input/output statement if an end-of-file condition occurred.
13747 @item @code{IOSTAT_EOR}:
13748 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
13749 an input/output statement if an end-of-record condition occurred.
13751 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
13752 Scalar default-integer constant, used by @code{INQUIRE} for the
13753 @code{IOSTAT=} specifier to denote an that a unit number identifies an
13754 internal unit. (Fortran 2008 or later.)
13756 @item @code{NUMERIC_STORAGE_SIZE}:
13757 The size in bits of the numeric storage unit.
13759 @item @code{LOGICAL_KINDS}:
13760 Default-kind integer constant array of rank one containing the supported kind
13761 parameters of the @code{LOGICAL} type. (Fortran 2008 or later.)
13763 @item @code{OUTPUT_UNIT}:
13764 Identifies the preconnected unit identified by the asterisk
13765 (@code{*}) in @code{WRITE} statement.
13767 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
13768 Kind type parameters to specify a REAL type with a storage
13769 size of 32, 64, and 128 bits. It is negative if a target platform
13770 does not support the particular kind. (Fortran 2008 or later.)
13772 @item @code{REAL_KINDS}:
13773 Default-kind integer constant array of rank one containing the supported kind
13774 parameters of the @code{REAL} type. (Fortran 2008 or later.)
13776 @item @code{STAT_LOCKED}:
13777 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
13778 denote that the lock variable is locked by the executing image. (Fortran 2008
13781 @item @code{STAT_LOCKED_OTHER_IMAGE}:
13782 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
13783 denote that the lock variable is locked by another image. (Fortran 2008 or
13786 @item @code{STAT_STOPPED_IMAGE}:
13787 Positive, scalar default-integer constant used as STAT= return value if the
13788 argument in the statement requires synchronisation with an image, which has
13789 initiated the termination of the execution. (Fortran 2008 or later.)
13791 @item @code{STAT_FAILED_IMAGE}:
13792 Positive, scalar default-integer constant used as STAT= return value if the
13793 argument in the statement requires communication with an image, which has
13794 is in the failed state. (TS 18508 or later.)
13796 @item @code{STAT_UNLOCKED}:
13797 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
13798 denote that the lock variable is unlocked. (Fortran 2008 or later.)
13801 The module provides the following derived type:
13804 @item @code{LOCK_TYPE}:
13805 Derived type with private components to be use with the @code{LOCK} and
13806 @code{UNLOCK} statement. A variable of its type has to be always declared
13807 as coarray and may not appear in a variable-definition context.
13808 (Fortran 2008 or later.)
13811 The module also provides the following intrinsic procedures:
13812 @ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}.
13816 @node ISO_C_BINDING
13817 @section @code{ISO_C_BINDING}
13819 @item @emph{Standard}:
13820 Fortran 2003 and later, GNU extensions
13823 The following intrinsic procedures are provided by the module; their
13824 definition can be found in the section Intrinsic Procedures of this
13828 @item @code{C_ASSOCIATED}
13829 @item @code{C_F_POINTER}
13830 @item @code{C_F_PROCPOINTER}
13831 @item @code{C_FUNLOC}
13833 @item @code{C_SIZEOF}
13835 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
13836 @c don't really know why.
13838 The @code{ISO_C_BINDING} module provides the following named constants of
13839 type default integer, which can be used as KIND type parameters.
13841 In addition to the integer named constants required by the Fortran 2003
13842 standard and @code{C_PTRDIFF_T} of TS 29113, GNU Fortran provides as an
13843 extension named constants for the 128-bit integer types supported by the
13844 C compiler: @code{C_INT128_T, C_INT_LEAST128_T, C_INT_FAST128_T}.
13845 Furthermore, if @code{__float128} is supported in C, the named constants
13846 @code{C_FLOAT128, C_FLOAT128_COMPLEX} are defined.
13848 @multitable @columnfractions .15 .35 .35 .35
13849 @item Fortran Type @tab Named constant @tab C type @tab Extension
13850 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
13851 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
13852 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
13853 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
13854 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
13855 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
13856 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
13857 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
13858 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
13859 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
13860 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
13861 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
13862 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
13863 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
13864 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
13865 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
13866 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
13867 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
13868 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
13869 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
13870 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
13871 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
13872 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
13873 @item @code{INTEGER}@tab @code{C_PTRDIFF_T} @tab @code{intptr_t} @tab TS 29113
13874 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
13875 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
13876 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
13877 @item @code{REAL} @tab @code{C_FLOAT128} @tab @code{__float128} @tab Ext.
13878 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
13879 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
13880 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
13881 @item @code{REAL} @tab @code{C_FLOAT128_COMPLEX} @tab @code{__float128 _Complex} @tab Ext.
13882 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
13883 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
13886 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
13889 @multitable @columnfractions .20 .45 .15
13890 @item Name @tab C definition @tab Value
13891 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
13892 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
13893 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
13894 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
13895 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
13896 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
13897 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
13898 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
13901 Moreover, the following two named constants are defined:
13903 @multitable @columnfractions .20 .80
13904 @item Name @tab Type
13905 @item @code{C_NULL_PTR} @tab @code{C_PTR}
13906 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
13909 Both are equivalent to the value @code{NULL} in C.
13914 @section IEEE modules: @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
13916 @item @emph{Standard}:
13917 Fortran 2003 and later
13920 The @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
13921 intrinsic modules provide support for exceptions and IEEE arithmetic, as
13922 defined in Fortran 2003 and later standards, and the IEC 60559:1989 standard
13923 (@emph{Binary floating-point arithmetic for microprocessor systems}). These
13924 modules are only provided on the following supported platforms:
13927 @item i386 and x86_64 processors
13928 @item platforms which use the GNU C Library (glibc)
13929 @item platforms with support for SysV/386 routines for floating point
13930 interface (including Solaris and BSDs)
13931 @item platforms with the AIX OS
13934 For full compliance with the Fortran standards, code using the
13935 @code{IEEE_EXCEPTIONS} or @code{IEEE_ARITHMETIC} modules should be compiled
13936 with the following options: @code{-fno-unsafe-math-optimizations
13937 -frounding-math -fsignaling-nans}.
13940 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
13941 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
13943 @item @emph{Standard}:
13944 OpenMP Application Program Interface v4.0
13948 The OpenMP Fortran runtime library routines are provided both in
13949 a form of two Fortran 90 modules, named @code{OMP_LIB} and
13950 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
13951 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
13952 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
13953 the named constants defined in the modules are listed
13956 For details refer to the actual
13957 @uref{http://www.openmp.org/mp-documents/OpenMP4.0.0.pdf,
13958 OpenMP Application Program Interface v4.0}.
13960 @code{OMP_LIB_KINDS} provides the following scalar default-integer
13964 @item @code{omp_lock_kind}
13965 @item @code{omp_nest_lock_kind}
13966 @item @code{omp_proc_bind_kind}
13967 @item @code{omp_sched_kind}
13970 @code{OMP_LIB} provides the scalar default-integer
13971 named constant @code{openmp_version} with a value of the form
13972 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
13973 of the OpenMP version; for OpenMP v4.0 the value is @code{201307}.
13975 The following scalar integer named constants of the
13976 kind @code{omp_sched_kind}:
13979 @item @code{omp_sched_static}
13980 @item @code{omp_sched_dynamic}
13981 @item @code{omp_sched_guided}
13982 @item @code{omp_sched_auto}
13985 And the following scalar integer named constants of the
13986 kind @code{omp_proc_bind_kind}:
13989 @item @code{omp_proc_bind_false}
13990 @item @code{omp_proc_bind_true}
13991 @item @code{omp_proc_bind_master}
13992 @item @code{omp_proc_bind_close}
13993 @item @code{omp_proc_bind_spread}